elly_core/

parse.rs

//! Parsing: Muon tree → Elly AST.
//!
//! A program is a single chain (`<expr>`). A chain's items are split on the
//! first `&`-prefixed item into an application spine and a trailing
//! abstraction, per `docs/elly-spec.md` and `docs/done/2026-07-06_elly-crate.md`.
//! Comments are dropped.
//!
//! **Patterns** (see `docs/done/2026-07-26_elly-patterns-native.md`) are
//! *faithful AST*: a `&`-header or a `let` binding's left-hand side parses into
//! a [`Pattern`] node that the evaluator matches directly. Parsing does not compile patterns
//! into eliminators — it only rephrases the Muon syntax into Elly's own
//! structures. Every abstraction is an `Expr::Abs(Rc<Lambda>)`, a run of
//! `&p0 &p1 …` collected into one multi-parameter [`Lambda`]; applying it matches
//! the arguments against the head (refuting via `NoMatch` on a miss). Source
//! application spines and spread calls flatten into one `Expr::App(Box<[Expr]>)`.

use alloc::boxed::Box;
use alloc::rc::Rc;
use alloc::string::String;
use alloc::vec::Vec;

use muon::{Chain, Item, Seq};
use num_bigint::BigInt;

use crate::ast::{Captures, Expr, HomeLeaf, Lambda, MapKey, Pattern, ProtoRef, Rest, Text};
use crate::eval::{Builtin, ModuleData};

/// Copy a source string slice into an owned text leaf. The AST no longer borrows
/// the Muon source (see `docs/todo/elly-impl-expr-repr-v1.md`), so every name /
/// symbol / bound name captured at parse time is copied here (inline for short
/// spellings, else a shared `Rc`). Takes `&str` so a `&&str` binding from a
/// slice pattern deref-coerces at the call site.
fn text(s: &str) -> Text {
    Text::from(s)
}

// TODO: use thiserror?
/// A parse failure: the input is a valid Muon tree but not a well-formed Elly
/// program in this subset.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ParseError {
    /// The top-level sequence held no chain (nothing to evaluate).
    EmptyProgram,
    /// The top-level sequence held more than one chain; top-level sequencing
    /// is deferred (a program is a single expression).
    MultipleExpressions,
    /// A chain reduced to nothing (e.g. only comments).
    EmptyChain,
    /// A `&` binder with no body — `&x` alone is ill-formed (yet).
    AbsWithoutBody,
    /// A `&` prefix on something that is not a well-formed binder header (see
    /// `BadPattern` for the pattern content itself).
    BadBinder,
    /// A binder appeared where an atomic expression was expected. Not reachable
    /// via the split logic, kept so parsing never panics.
    UnexpectedBinder,
    /// A `.` sigil on something that is not a single name/number segment (e.g.
    /// `.(…)`, `.&x`). `.foo` / `.0` are symbols; the record sugar `.(…)` and
    /// other prefixed items are deferred / ill-formed.
    BadSymbol,
    /// A bare `.` used as an atom (`f . g`, a lone `.`). At the Muon layer this
    /// is a `<punct>`; Elly reserves it for a future `.` / `|>` application
    /// combinator, which is deferred.
    CombinatorDeferred,
    /// `_` used as a reference. `_` is the discard pattern (a binder that binds
    /// nothing), never a name that can be read back.
    DiscardReference,
    /// A `&`-binder tried to introduce a name starting with `__`. Such names are
    /// reserved for builtins / special forms and may be referenced but not bound.
    ReservedName,
    /// A `<sym>` that begins like a number but is not a valid integer literal
    /// (`1a`, `0xZZ`, `1__2`, `0x`). Since a `<name>` may not start with a digit,
    /// a digit-leading sym must be a well-formed `<int>` or it is an error.
    MalformedNumber,
    /// A stray `:` / `=` (or other) `<punct>` item at atom position. Muon parses
    /// this punctuation, but outside a `let` binding (`=`) or a map entry (`:`)
    /// it has no atomic reading. (A `<block>` `{…}` is a map literal and a
    /// `<list>` `[…]` a runtime list value — neither is deferred.)
    PunctAtAtom,
    /// A map entry (`<block>` chain) whose key is missing or malformed: no `:`
    /// after the key, or a key item that is not a bare atom, a `.`-symbol, a `(…)`
    /// computed key, or a `[…]` list/unit key (`{ : 1 }`, `{ foo }`).
    MalformedMapKey,
    /// A `let` not followed by a binder group — `let 1 e`. An *empty* group is not
    /// an error: `let () e` binds nothing and is `e` (see `parse_let`).
    LetMissingBinders,
    /// A `let (…)` with nothing after the binder group; the body is required.
    LetMissingBody,
    /// A `recur` not followed by a binder group — `recur 1 e`. As with `let`, an
    /// empty group is not an error: `recur () e` is `e`.
    RecurMissingBinders,
    /// A `recur (…)` with nothing after the binder group; the body is required.
    RecurMissingBody,
    /// A `recur` binding whose name is already in scope. The group's bindings are
    /// simultaneous, so inside it the name would mean the group's own binding and
    /// never the outer one — the opposite of what the identical `let` line means.
    /// Detected by the resolution pass (`resolve.rs`); carries the offending name.
    RecurShadowsOuter(Text),
    /// A binding inside a `let (…)` group is not `<pattern> "=" <expr>`: missing
    /// or repeated top-level `=`, an empty pattern, or an empty value.
    MalformedBinding,
    /// A keyword (`let`, `with`) used as a reference or a binder. Keywords are
    /// syntax, not names: they may be neither read nor bound.
    ReservedKeyword,
    /// A malformed pattern: an empty pattern, a comma-grouped `(a, b)` used as a
    /// single pattern, a misplaced `...rest`, or any item with no pattern reading.
    BadPattern,
    /// A comparand after `=` / `<` / `>` that is not a single **atom** (a name or
    /// a literal). A pattern is a closed grammar — `= f x`, `< (f x)`, `= [a]`
    /// have no reading; write `= x`, `= 5`, or `.foo`.
    ComparandNotAtom,
    /// A bare **matching literal** used as an entire `&`-header or `let` binding
    /// LHS: a number (`&42`), a symbol (`&.foo`), or a string (`&"foo"`).
    /// Parenthesize it — `&(42)`, `&(.foo)`, `&("foo")`, `let ((42) = v)` — so the
    /// "match this literal" intent is explicit (a bare literal reads as a value, or
    /// as an intended binder). A literal *nested* in `[…]` / `{…}` / `(…)` / an
    /// or-pattern needs no parens.
    BareLiteralHeader,
    /// A `<str>` literal with an **unpaired UTF-16 surrogate** escape (`"\uD83D"`,
    /// a high or low `\uXXXX` not completing a pair). Muon accepts it lexically,
    /// but UTF-8 cannot represent it, so Elly's decode rejects it at parse.
    LoneSurrogate,
    /// A bare top-level `|` in a `let` binding's LHS: `let ((x=.a) | (x=.b) = v)`.
    /// Wrap the or-pattern — `let (((x=.a) | (x=.b)) = v) e` — so it does not
    /// visually compete with the binding's own `=`.
    LetOrUnparenthesized,
    /// An `as <Type>` whose `<Type>` is not one of the closed kinds
    /// `Int Sym List Map Fun`.
    UnknownType,
    /// An or-pattern `(p | q)` whose arms bind different sets of names.
    OrBindersMismatch,
    /// A `|>` pipe combinator with a missing operand — `|> f`, `x |>`, or
    /// `x |> |> f`. Both sides of `|>` must be non-empty.
    MalformedPipe,
    /// A name reference that resolves to no enclosing `&`-binding — a free
    /// variable. Detected by the resolution pass (`resolve.rs`) after parsing,
    /// so it is a *static* error: the program is rejected before it runs, rather
    /// than raising `.unbound_name` at eval. Carries the offending name (spans
    /// are still a TODO). `__`-names never reach here — they are resolved to
    /// [`Expr::Builtin`](crate::Expr) at parse.
    UnboundName(Text),
    /// A module (`parse_module`) binding whose left-hand side is not a single bare
    /// name: a destructuring pattern, a literal, a discard, or a digit-leading
    /// token. Module top-level keys are plain names in v0. A `__…` or keyword LHS
    /// reports [`ParseError::ReservedName`] / [`ParseError::ReservedKeyword`] instead.
    BadModuleItemName,
    /// A module defines the same item name twice, or an `import`'s local name is
    /// also an item name. A name means one thing inside a module, so both are
    /// rejected here. The `Foo = import "spec"` form is the one place a name is
    /// both an import and an item: it is a single declaration, and it makes them
    /// the same thing.
    DuplicateModuleItem,
    /// An `import` that is neither `import "<spec>" as <Name>` nor
    /// `<Name> = import "<spec>"`: a missing `as`, a spec that is not a string
    /// literal, or trailing items. The spec is a literal in a fixed position —
    /// which is what makes a module's imports a static, auditable list — so there
    /// is nothing to compute here.
    MalformedImport,
    /// An `import` somewhere other than a module's top level — today, inside a
    /// [`recur`](crate::Expr::Recur) group. An import is a frame slot the const
    /// stage fills before the module exists, so it can only be written in a
    /// module's own source. Written anywhere else, `import` is an ordinary keyword
    /// and reports [`ParseError::ReservedKeyword`].
    MisplacedImport,
    /// A `const` declaration that is neither `const <name>`, `const (<name> …)`
    /// nor `<name> = const`: a declaration that is not a bare name, a group whose
    /// chains are not bare names, or a **payload** — `const x = 1`, `x = const 1`.
    /// The payload forms are reserved for const-time expressions and rejected
    /// until those exist (see `docs/done/2026-08-13_elly-modules-iotas.md`).
    MalformedConst,
    /// A `const` somewhere other than a module's top level — today, inside a
    /// [`recur`](crate::Expr::Recur) group. A group is built while a program runs
    /// and has no instance of its own to mint against, so an iota can only be
    /// declared in a module's source. Written anywhere else, `const` is an
    /// ordinary keyword and reports [`ParseError::ReservedKeyword`].
    MisplacedConst,
    /// A binder — a pattern binder, a `let` binding, a `recur` binding — taking a
    /// name the enclosing module declares as an **import**. A declaration's name
    /// means one thing over the whole module, so it may not be shadowed from
    /// inside (see `docs/done/2026-08-13_elly-modules-iotas.md`). Carries the name.
    ShadowsImport(Text),
    /// A binder taking a name the enclosing module declares as a `const`
    /// [iota](ParseError::ShadowsImport). Carries the name.
    ShadowsIota(Text),
    /// A `local` declaration that is neither `local <name> = <expr>` nor the
    /// group `local (<name> = <expr> …)`: a left-hand side that is not a bare
    /// name, a group chain that is not a binding, or a missing body. The
    /// head-with-arguments form `local f x = <expr>` lands here too — it is a
    /// template moditem, left open (see `docs/done/2026-08-13_elly-modules-local.md`).
    MalformedLocal,
    /// A `local` somewhere other than a module's top level — today, inside a
    /// [`recur`](crate::Expr::Recur) group, where every binding is private
    /// already, so the keyword would say nothing. Written anywhere else, `local`
    /// is an ordinary keyword and reports [`ParseError::ReservedKeyword`].
    MisplacedLocal,
    /// A binder taking a name the enclosing module declares as a
    /// [`local`](ParseError::ShadowsImport). Carries the name.
    ShadowsLocal(Text),
    /// A binder taking a name the enclosing module — or an enclosing
    /// [`recur`](crate::Expr::Recur) group — declares as an **item**. Carries the
    /// name. This is the direction opposite to
    /// [`RecurShadowsOuter`](ParseError::RecurShadowsOuter), which stops a group
    /// binding from shadowing a name already in scope; together they make a
    /// declared name unshadowable from either side.
    ShadowsItem(Text),
    /// A `__` name the language does not define, in either position it can be
    /// written: a module top-level left-hand side (`__mian = …`) or a reference
    /// in an expression (`__mian`). The `__` namespace belongs to the language —
    /// a source may write the builtins and the **reserved moditems** it defines
    /// and nothing else — so a misspelling fails here, naming the namespace,
    /// rather than becoming an item nobody reads or a name nothing binds.
    /// Carries the name as written.
    UnknownReserved(Text),
    /// A module declaring the same reserved moditem twice (two `__main`s). A
    /// reserved moditem is a single slot, not a table, so there is no second one
    /// to hold. Carries the name.
    DuplicateReserved(Text),
    /// A reserved moditem somewhere other than a module's top level — today,
    /// inside a [`recur`](crate::Expr::Recur) group. A group is an item table,
    /// not a module source, and nothing would ever read the slot. Written
    /// anywhere else, `__main` is an ordinary `__` name and reports
    /// [`UnknownReserved`](ParseError::UnknownReserved).
    MisplacedReserved,
    /// A [home-module leaf](crate::HomeLeaf) — `__module`, `__new`, `__value`, or
    /// the `__value <pat>` pattern — outside a module body. Each reads the module
    /// its body is written in, and there is none: the term is not a module's, or
    /// it is a [`recur`](crate::Expr::Recur) group in a program that is not a
    /// module. One test covers both, since a group is not a module either.
    /// Carries the name.
    OutsideModule(Text),
    /// An `as <Proto>` pattern whose reference is a `__` name that is not a
    /// **prototype**: a builtin that is no module at all (`as __eq`), or `__Err`,
    /// which is a namespace of operations that no value answers `__proto` with —
    /// so the check could never hold. Rejected here rather than compiled into a
    /// pattern that always refutes. Carries the name.
    NotAPrototype(Text),
}

/// What a module's source writes to name an import — a path, a package-qualified
/// name. Its grammar belongs to the host resolver, not to Elly.
pub type ImportSpec = Text;

/// What a resolver answers a spec with: one name per module, however many specs
/// reach it. Module instances are deduplicated by this name, so a resolver that
/// returns the spec unchanged would hand back two instances of one module for
/// `"./foo"` and `"foo"` (see [`crate::load_module`]).
pub type ModuleName = Text;

/// One `import` declaration: the name the importing module reaches the instance
/// by, and the spec its host resolver is handed.
///
/// The two written forms differ in whether the module also **re-exports** the
/// instance. `import "spec" as Foo` is a private frame slot; `Foo = import "spec"`
/// is the same slot plus an ordinary item `Foo` that forwards it. Both arrive here
/// as one `ImportDecl` — the re-exporting form has additionally pushed its
/// forwarding item into [`ModuleSyntax::items`] (see
/// `docs/done/2026-08-11_elly-modules-import.md`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImportDecl {
    /// The name the importing module's bodies read the instance by.
    pub name: Text,
    /// What the host resolver is handed.
    pub spec: ImportSpec,
}

/// A module source's top-level declarations: its imports and its `const`
/// declarations, in source order, and its items. The imports are the module's
/// first frame slots — the const stage resolves, compiles and instantiates each
/// one, then instantiates this module against the results (see
/// [`crate::load_module`]). The iotas take no slot at all: an iota's identity is
/// its instance plus its position, derived on reference (see
/// `docs/done/2026-08-13_elly-modules-iotas.md`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModuleSyntax {
    /// The `import` declarations, in source order, which is frame-slot order.
    pub imports: Vec<ImportDecl>,
    /// The names declared by `const`, in source order — the module's **iotas**.
    /// Sorted before they reach [`ModuleData`](crate::ModuleData), where the
    /// order is the address space a member reference counts against.
    pub iotas: Vec<Text>,
    /// The `name = body` items, in source order, bodies unresolved.
    pub items: Vec<(Text, Expr)>,
    /// The `local name = body` declarations, in source order, bodies unresolved
    /// — the module's **private** bindings. They are members like the items, and
    /// differ only in not being searched by name from outside (see
    /// `docs/done/2026-08-13_elly-modules-local.md`).
    pub locals: Vec<(Text, Expr)>,
    /// What the module declared as `__main`, if anything — the **reserved
    /// moditem** a runner evaluates and applies to the root capability.
    ///
    /// It is a slot rather than an entry in [`items`](Self::items), and that is
    /// what makes it unnameable: the member index space it stays out of is the
    /// only thing a body's reference or an outside `M.name` access can address.
    /// See `docs/done/2026-08-14_elly-run.md`.
    pub main: Option<Expr>,
}

/// Parse a whole parsed program (one top-level chain) to an expression.
pub fn parse_program<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    match seq.0.as_slice() {
        [] => Err(ParseError::EmptyProgram),
        [chain] => parse_chain(chain),
        _ => Err(ParseError::MultipleExpressions),
    }
}

/// Parse a **module** source's top-level sequence into its declarations: one
/// `name = body` item or one `import` per non-comment chain, in source order.
/// Unlike [`parse_program`] a module is a *multi-chain* sequence, and a body is
/// not resolved here — [`crate::compile_module`] runs
/// [`crate::resolve::resolve_module_bodies`] afterwards so a body may refer to any
/// sibling regardless of order. An item's left-hand side is a single bare name in
/// v0 (no destructuring at module top level); duplicate names and non-name LHSs
/// are rejected. See `docs/done/2026-08-07_elly-modules-v0.md`.
///
/// An `import` chain has no top-level `=` in its private form, so it is recognized
/// before the `=` split rather than reported as a `MalformedBinding`. Its two
/// forms are described on [`ImportDecl`]; `Foo = import "spec"` also pushes the
/// item `Foo` that forwards the slot, since it is written as an item and should
/// read as one from outside.
///
/// A `const` declaration is read the same way and follows the same privacy
/// convention: `const false` and `const (false, true)` are private, `false =
/// const` declares the iota *and* the item that exports it.
///
/// A `local` declaration is the ordinary binding under the same convention:
/// `local x = <expr>` and the group `local (x = <expr> …)` bind a member the
/// module's own bodies reach and nothing outside can, where the bare
/// `x = <expr>` beside them is the export form.
pub fn parse_module<'a>(seq: &Seq<'a>) -> Result<ModuleSyntax, ParseError> {
    let mut items: Vec<(Text, Expr)> = Vec::new();
    let mut imports: Vec<ImportDecl> = Vec::new();
    let mut iotas: Vec<Text> = Vec::new();
    let mut locals: Vec<(Text, Expr)> = Vec::new();
    let mut main: Option<Expr> = None;
    // The declarations that are also items, kept apart by kind, so the collision
    // check below knows which shared names were written as one declaration and
    // are therefore fine. A name shared by two *declarations* never is.
    let mut reexported_imports: Vec<Text> = Vec::new();
    let mut reexported_iotas: Vec<Text> = Vec::new();
    for chain in &seq.0 {
        let ci: Vec<&Item<'a>> = chain
            .0
            .iter()
            .filter(|it| !matches!(it, Item::Comm(_)))
            .collect();
        if ci.is_empty() {
            continue; // a blank / comment-only line separates items
        }
        // Split on the first top-level `=`, exactly as `parse_binding` does; a
        // second top-level `=` is malformed (a nested `=` lives inside `(…)`/…).
        let split = ci.iter().position(|it| matches!(it, Item::Punct("=")));
        // `import "spec" as Foo` — a private slot, and the one module top-level
        // chain with no `=` of its own. A chain that *has* one is a binding
        // whatever it starts with, so `import = 3` still reports the keyword.
        if split.is_none() && is_import_keyword(ci[0]) {
            let (name, spec) = parse_private_import(&ci)?;
            push_import(&mut imports, name, spec)?;
            continue;
        }
        // `const false` / `const (false, true)` — a private declaration, and like
        // a private import the whole chain is the declaration.
        if split.is_none() && is_const_keyword(ci[0]) {
            for name in parse_const_decl(&ci)? {
                push_iota(&mut iotas, name)?;
            }
            continue;
        }
        // `local (x = 1, y = 2)` — the group form, whose bindings' `=`s all sit
        // inside the tuple, so the chain has none of its own. The single form
        // `local x = 1` does, and is read below with the other bindings.
        if split.is_none() && is_local_keyword(ci[0]) {
            for (name, body) in parse_local_group(&ci)? {
                push_local(&mut locals, name, body)?;
            }
            continue;
        }
        let eq = split.ok_or(ParseError::MalformedBinding)?;
        if ci[eq + 1..].iter().any(|it| matches!(it, Item::Punct("="))) {
            return Err(ParseError::MalformedBinding);
        }
        let (head, tail) = (&ci[..eq], &ci[eq + 1..]);
        if head.is_empty() || tail.is_empty() {
            return Err(ParseError::MalformedBinding);
        }
        // `const x = <expr>`, the private const-time expression form the grammar
        // reserves and nothing implements. A bare `const = 3` is not this — it
        // falls through to `plain_name`, which reports the keyword.
        if head.len() > 1 && is_const_keyword(head[0]) {
            return Err(ParseError::MalformedConst);
        }
        // `local x = <expr>` — the single private binding. A bare `local = 3` is
        // not this: it falls through to `plain_name`, which reports the keyword.
        if head.len() > 1 && is_local_keyword(head[0]) {
            let name = plain_name(&head[1..], ParseError::MalformedLocal)?;
            push_local(&mut locals, name, parse_items(tail)?)?;
            continue;
        }
        // `__main = <expr>` — a **reserved moditem**, recognized here because
        // `plain_name` would otherwise stop at the `__` and report the name as
        // reserved. It is not an item: it goes to its own slot, outside the
        // member index space, so nothing can name it (see `ModuleSyntax::main`).
        if let [Item::Sym(s)] = head {
            if let Some(reserved) = reserved_moditem(s) {
                if main.is_some() {
                    return Err(ParseError::DuplicateReserved(text(reserved)));
                }
                main = Some(parse_items(tail)?);
                continue;
            }
            if s.starts_with("__") {
                return Err(ParseError::UnknownReserved(text(s)));
            }
        }
        let name = plain_name(head, ParseError::BadModuleItemName)?;
        if items.iter().any(|(n, _)| n.as_str() == name.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
        // `Foo = import "spec"` — the same slot, re-exported. The item's body is
        // the name itself: resolution looks imports up before items, so it reads
        // the slot rather than looping back through this forwarding item.
        if is_import_keyword(tail[0]) {
            let spec = parse_import_spec(tail)?;
            push_import(&mut imports, name.clone(), spec)?;
            reexported_imports.push(name.clone());
            items.push((name.clone(), Expr::Name(name)));
            continue;
        }
        // `false = const` — the iota plus the item exporting it. There is nothing
        // to the right of the keyword until const-time expressions exist, and the
        // item's body is the name itself: a sibling reference finds the iota,
        // since members are searched iotas-first (see `resolve_module_bodies`).
        if is_const_keyword(tail[0]) {
            if tail.len() != 1 {
                return Err(ParseError::MalformedConst);
            }
            push_iota(&mut iotas, name.clone())?;
            reexported_iotas.push(name.clone());
            items.push((name.clone(), Expr::Name(name)));
            continue;
        }
        let body = parse_items(tail)?;
        items.push((name, body));
    }
    // A private declaration may not share a name with an item — inside the module
    // the name would have to mean both. A re-exported one shares by construction.
    // Two *declarations* may never share one, re-exported or not: neither form
    // writes an import and an iota at once.
    for imp in &imports {
        if iotas.iter().any(|n| n.as_str() == imp.name.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
        if reexported_imports
            .iter()
            .any(|n| n.as_str() == imp.name.as_str())
        {
            continue;
        }
        if items.iter().any(|(n, _)| n.as_str() == imp.name.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
    }
    for iota in &iotas {
        if reexported_iotas.iter().any(|n| n.as_str() == iota.as_str()) {
            continue;
        }
        if items.iter().any(|(n, _)| n.as_str() == iota.as_str()) {
            return Err(ParseError::DuplicateModuleItem);
        }
    }
    // A local shares with nothing: it is a declaration, and there is no form
    // writing a local and something else at once.
    for (name, _) in &locals {
        let taken = items.iter().any(|(n, _)| n.as_str() == name.as_str())
            || iotas.iter().any(|n| n.as_str() == name.as_str())
            || imports.iter().any(|i| i.name.as_str() == name.as_str());
        if taken {
            return Err(ParseError::DuplicateModuleItem);
        }
    }
    Ok(ModuleSyntax {
        imports,
        iotas,
        items,
        locals,
        main,
    })
}

/// The reserved moditems the language defines, as the names a module top-level
/// left-hand side may spell in the `__` namespace. One so far; `__test` and
/// `__doc` are anticipated, and each will be another slot on [`ModuleSyntax`]
/// with a clause here (see `docs/done/2026-08-14_elly-run.md`).
///
/// Answers with the `'static` spelling so the caller reports the *defined* name
/// rather than echoing the source, and `None` for a name that is not one — which
/// the caller turns into [`ParseError::UnknownReserved`] rather than an item.
fn reserved_moditem(name: &str) -> Option<&'static str> {
    match name {
        "__main" => Some("__main"),
        _ => None,
    }
}

/// Record one import, rejecting a name a previous import already took.
fn push_import(
    imports: &mut Vec<ImportDecl>,
    name: Text,
    spec: ImportSpec,
) -> Result<(), ParseError> {
    if imports.iter().any(|i| i.name.as_str() == name.as_str()) {
        return Err(ParseError::DuplicateModuleItem);
    }
    imports.push(ImportDecl { name, spec });
    Ok(())
}

/// Parse `import "<spec>" as <Name>` — the private form, whose whole chain is the
/// declaration — to its name and spec.
fn parse_private_import<'a>(ci: &[&Item<'a>]) -> Result<(Text, ImportSpec), ParseError> {
    match ci {
        [_import, Item::Str(spec), Item::Sym("as"), rest @ ..] if !rest.is_empty() => {
            let name = plain_name(rest, ParseError::BadModuleItemName)?;
            Ok((name, decode_str(spec)?))
        }
        _ => Err(ParseError::MalformedImport),
    }
}

/// Record one iota, rejecting a name a previous `const` already declared.
fn push_iota(iotas: &mut Vec<Text>, name: Text) -> Result<(), ParseError> {
    if iotas.iter().any(|n| n.as_str() == name.as_str()) {
        return Err(ParseError::DuplicateModuleItem);
    }
    iotas.push(name);
    Ok(())
}

/// Parse a private `const` declaration — `const <name>`, or the group form
/// `const (<name> …)` — to the names it declares.
///
/// The group is an ordinary `<tuple>` wrapping a `<seq>`, so its names may be
/// newline- or comma-separated and it may carry comments, exactly as a `let`
/// group may. An **empty group declares nothing**, the same degenerate reading
/// `let ()` and `recur ()` take.
fn parse_const_decl<'a>(ci: &[&Item<'a>]) -> Result<Vec<Text>, ParseError> {
    match ci {
        [_const, Item::Tuple(seq)] => {
            let mut names = Vec::new();
            for chain in &seq.0 {
                let c: Vec<&Item<'a>> = chain
                    .0
                    .iter()
                    .filter(|it| !matches!(it, Item::Comm(_)))
                    .collect();
                if c.is_empty() {
                    continue; // a blank / comment-only line inside the group
                }
                names.push(plain_name(&c, ParseError::MalformedConst)?);
            }
            Ok(names)
        }
        [_const, rest @ ..] if !rest.is_empty() => {
            Ok(alloc::vec![plain_name(rest, ParseError::MalformedConst)?])
        }
        _ => Err(ParseError::MalformedConst),
    }
}

/// Record one local, rejecting a name a previous `local` already took.
fn push_local(locals: &mut Vec<(Text, Expr)>, name: Text, body: Expr) -> Result<(), ParseError> {
    if locals.iter().any(|(n, _)| n.as_str() == name.as_str()) {
        return Err(ParseError::DuplicateModuleItem);
    }
    locals.push((name, body));
    Ok(())
}

/// Parse the group form `local (<name> = <expr> …)` to its bindings.
///
/// The group is an ordinary `<tuple>` wrapping a `<seq>`, so its bindings may be
/// newline- or comma-separated and it may carry comments, exactly as a `let`
/// group may — and an **empty group declares nothing**, the degenerate reading
/// `const ()` and `let ()` take. Anything else after the keyword is a malformed
/// declaration: the single form `local x = <expr>` has a top-level `=` and never
/// reaches here.
fn parse_local_group<'a>(ci: &[&Item<'a>]) -> Result<Vec<(Text, Expr)>, ParseError> {
    let [_local, Item::Tuple(seq)] = ci else {
        return Err(ParseError::MalformedLocal);
    };
    let mut bindings = Vec::new();
    for chain in &seq.0 {
        let c: Vec<&Item<'a>> = chain
            .0
            .iter()
            .filter(|it| !matches!(it, Item::Comm(_)))
            .collect();
        if c.is_empty() {
            continue; // a blank / comment-only line inside the group
        }
        let eq = c
            .iter()
            .position(|it| matches!(it, Item::Punct("=")))
            .ok_or(ParseError::MalformedLocal)?;
        let (head, tail) = (&c[..eq], &c[eq + 1..]);
        if head.is_empty() || tail.is_empty() {
            return Err(ParseError::MalformedLocal);
        }
        if tail.iter().any(|it| matches!(it, Item::Punct("="))) {
            return Err(ParseError::MalformedLocal);
        }
        bindings.push((
            plain_name(head, ParseError::MalformedLocal)?,
            parse_items(tail)?,
        ));
    }
    Ok(bindings)
}

/// Parse the `import "<spec>"` right-hand side of a re-exporting import to its
/// spec. There is no `as` here: the item's own left-hand side named it.
fn parse_import_spec<'a>(tail: &[&Item<'a>]) -> Result<ImportSpec, ParseError> {
    match tail {
        [_import, Item::Str(spec)] => decode_str(spec),
        _ => Err(ParseError::MalformedImport),
    }
}

/// The single plain name a binding position may hold: exactly one `<sym>` that is
/// not a keyword, a `__` name, a discard, or a number. A reserved token gets its
/// own error; every other shape (a destructuring pattern, a literal, several
/// items) gets the caller's `bad`, which names the position —
/// [`ParseError::BadPattern`] for an at-pattern's LHS,
/// [`ParseError::BadModuleItemName`] for a module item's.
fn plain_name<'a>(items: &[&Item<'a>], bad: ParseError) -> Result<Text, ParseError> {
    match items {
        [Item::Sym(s)] if is_keyword(s) => Err(ParseError::ReservedKeyword),
        [Item::Sym(s)] if s.starts_with("__") => Err(ParseError::ReservedName),
        [Item::Sym(s)] if reads_as_number(s) || *s == "_" => Err(bad),
        [Item::Sym(s)] => Ok(text(s)),
        _ => Err(bad),
    }
}

/// Would this non-empty `<sym>` read as a number rather than a reference? Either
/// it is a valid integer literal — including a signed one, since `-`/`+` are
/// symchars, so `-1` is one `<sym>` — or it is digit-leading and therefore a
/// *malformed* number. A reference is neither (see the atom path above), so a
/// binding may not take such a name: it could never be read back.
fn reads_as_number(s: &str) -> bool {
    parse_int(s).is_some() || s.as_bytes()[0].is_ascii_digit()
}

/// Parse one chain: drop comments, then split on the first binder.
fn parse_chain<'a>(chain: &Chain<'a>) -> Result<Expr, ParseError> {
    let items: Vec<&Item<'a>> = chain
        .0
        .iter()
        .filter(|it| !matches!(it, Item::Comm(_)))
        .collect();
    parse_items(&items)
}

/// Parse a comment-free slice of items (a chain, or a suffix of one).
fn parse_items<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    if items.is_empty() {
        return Err(ParseError::EmptyChain);
    }
    // `|>` is the **loosest** operator: split on the last one so the chain is
    // a left-associative pipe chain over **segments**, each parsed by
    // `parse_segment`. A `&`/`let`/`recur` binder form can therefore never
    // capture a pipe — `&x x |> f` is `f (&x x)`, and a pipe-bodied lambda is
    // written `&x (x |> f)` — and a pipe's right operand is a whole segment,
    // which may itself end in a trailing binder form (`x |> &y body`).
    match items.iter().rposition(|it| matches!(it, Item::Punct("|>"))) {
        None => parse_segment(items),
        Some(k) => {
            let (left, right) = (&items[..k], &items[k + 1..]);
            if left.is_empty() || right.is_empty() {
                return Err(ParseError::MalformedPipe);
            }
            let l = parse_items(left)?;
            let r = parse_segment(right)?;
            // Thread the left operand in as `r`'s final argument, extending its
            // spine so `x |> f a b` stays one flattened call `f a b x`.
            Ok(append_arg(r, l))
        }
    }
}

/// Parse one pipe segment — a `|>`-free item slice: an application spine whose
/// trailing argument may be a `&`/`let`/`recur` binder form. A split point is a
/// `&`-binder or the `let`/`recur` keyword: it has the lowest precedence within
/// the segment and captures the rest of the segment as its body, so the spine
/// before the first one is a left-folded application whose trailing argument is
/// the abstraction / let / recur that follows. With no split point this is
/// exactly `parse_app_spine`.
fn parse_segment<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    match items.iter().position(|it| is_split_point(it)) {
        // No split point: a plain application spine (with `()` spread).
        None => parse_app_spine(items),
        // Leading split point: a `let (…) body`, or `&<header> <rest>`
        // abstracting a pattern over the rest.
        Some(0) => {
            if is_let_keyword(items[0]) {
                parse_let(items)
            } else if is_recur_keyword(items[0]) {
                parse_recur(items)
            } else {
                if items.len() == 1 {
                    return Err(ParseError::AbsWithoutBody);
                }
                let inner = match items[0] {
                    Item::Prefixed { sigil: '&', item } => item.as_ref(),
                    _ => return Err(ParseError::UnexpectedBinder),
                };
                let body = parse_segment(&items[1..])?;
                build_binder(inner, body)
            }
        }
        // Split point in the middle: the abstraction / let is the trailing
        // argument of the application spine that precedes it.
        Some(k) => {
            let f = parse_segment(&items[..k])?;
            let arg = parse_segment(&items[k..])?;
            Ok(append_arg(f, arg))
        }
    }
}

/// Parse a `let (b0, b1, …) body`. `items[0]` is the `let` keyword; `items[1]`
/// must be the binder-group tuple and `items[2..]` the (non-empty) body. The
/// group's bindings are **sequential** — `let (a = va, b = vb) e` desugars to the
/// nested `(&a ((&b e) vb)) va` — so we parse the body once and fold the bindings
/// right-to-left, leaving the leftmost binding outermost.
///
/// An **empty group binds nothing**, so `let () e` is `e` — the fold over zero
/// bindings, and the unit of the form. It is not an error: a group is a list, and
/// a generated or commented-out one may legitimately come out empty.
fn parse_let<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    let group = match items.get(1).map(|it| &**it) {
        Some(Item::Tuple(seq)) => seq,
        _ => return Err(ParseError::LetMissingBinders),
    };
    let body_items = &items[2..];
    if body_items.is_empty() {
        return Err(ParseError::LetMissingBody);
    }
    // Each binding is a chain of the group's `<seq>`; drop comment-only chains so
    // a group can be laid out as a block with blank lines and comments.
    let mut bindings: Vec<Vec<&Item<'a>>> = Vec::new();
    for chain in &group.0 {
        let ci: Vec<&Item<'a>> = chain
            .0
            .iter()
            .filter(|it| !matches!(it, Item::Comm(_)))
            .collect();
        if !ci.is_empty() {
            bindings.push(ci);
        }
    }
    let mut acc = parse_segment(body_items)?;
    for ci in bindings.iter().rev() {
        let (pat, value) = parse_binding(ci)?;
        acc = Expr::App(Box::new([abs(pat, acc), value]));
    }
    Ok(acc)
}

/// Parse a `recur (b0, b1, …) body`. Shaped like [`parse_let`] — `items[0]` is the
/// keyword, `items[1]` the binder-group tuple, `items[2..]` the body — and unlike
/// it in what the group means: the bindings are **simultaneous**, so they cannot
/// desugar to nested abstractions and instead become a module item table that the
/// bodies reach through a terminal.
///
/// The left-hand sides are plain names, not patterns. The group *is* an item table,
/// so it follows [`parse_module`]'s rule (which is also what rejects a duplicate)
/// rather than `let`'s, which does allow a destructuring pattern. That divergence
/// falls out of the mechanism rather than being a choice.
///
/// The table is sorted here, at parse: the sort order *is* the index space a
/// sibling [`Expr::ModItem`] counts against, and the resolver assigns those indices
/// against the frozen [`ModuleData`].
///
/// As with `let`, an empty group is `body` — with the terminal dropped too, since a
/// group with no items has nothing to reach through it.
fn parse_recur<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    let group = match items.get(1).map(|it| &**it) {
        Some(Item::Tuple(seq)) => seq,
        _ => return Err(ParseError::RecurMissingBinders),
    };
    let body_items = &items[2..];
    if body_items.is_empty() {
        return Err(ParseError::RecurMissingBody);
    }
    let syntax = parse_module(group)?;
    if !syntax.imports.is_empty() {
        // A group is an item table, not a module source: it has no frame of its
        // own for the const stage to fill, and it is built while a program runs.
        return Err(ParseError::MisplacedImport);
    }
    if !syntax.iotas.is_empty() {
        // Nor an instance of its own to mint iotas against.
        return Err(ParseError::MisplacedConst);
    }
    if !syntax.locals.is_empty() {
        // And every binding of a group is private already — it is reachable from
        // the group's own bodies and its body, and from nowhere else — so the
        // keyword would mark nothing.
        return Err(ParseError::MisplacedLocal);
    }
    if syntax.main.is_some() {
        // A reserved moditem is read by a tool that was pointed at a *source* —
        // a runner, a test runner — and a group is not one, so the slot would
        // never be looked at.
        return Err(ParseError::MisplacedReserved);
    }
    let mut bindings = syntax.items;
    let body = parse_segment(body_items)?;
    if bindings.is_empty() {
        return Ok(body);
    }
    bindings.sort_by(|(a, _), (b, _)| a.as_str().cmp(b.as_str()));
    // No frame, no imports, and no name: a group's bindings are written where
    // they are used, so there is no source of its own for a host to name. The
    // body goes in the module's own body slot — the same one a source fills with
    // `__main`, differing only in who evaluates it and when.
    Ok(Expr::Recur(Rc::new(ModuleData::from_bindings(
        bindings,
        Vec::new(),
        Box::new([]),
        Box::new([]),
        Box::new([]),
        Some(body),
        None,
    ))))
}

/// Parse one binding chain `<pattern> "=" <expr>` to its pattern and value. The
/// separator is the **first** top-level `=` (`<punct>`); a pattern may carry its
/// own `=` only inside `(…)`/`[…]`/`{…}` (a nested item, never top-level), so a
/// second top-level `=` is malformed. Both the head (pattern) and tail (value)
/// must be non-empty.
fn parse_binding<'a>(items: &[&Item<'a>]) -> Result<(Pattern, Expr), ParseError> {
    let mut eq = None;
    for (i, it) in items.iter().enumerate() {
        if matches!(it, Item::Punct("=")) {
            if eq.is_some() {
                return Err(ParseError::MalformedBinding); // a second top-level `=`
            }
            eq = Some(i);
        }
    }
    let eq = eq.ok_or(ParseError::MalformedBinding)?;
    let (head, tail) = (&items[..eq], &items[eq + 1..]);
    if head.is_empty() || tail.is_empty() {
        return Err(ParseError::MalformedBinding);
    }
    // A top-level `|` in the LHS must be parenthesized (an `&`-header can't reach
    // this, since `&` prefixes one item), so the or-`|` and the binding `=` do
    // not compete: `let (((x=.a) | (x=.b)) = v) e`.
    if head.iter().any(|it| matches!(it, Item::Punct("|"))) {
        return Err(ParseError::LetOrUnparenthesized);
    }
    // A bare matching literal as the whole LHS needs parens: `let ((42) = v)`,
    // `let ((.foo) = v)`, `let (("s") = v)` (see `BareLiteralHeader`).
    if let [it] = head {
        if is_bare_literal_header(it) {
            return Err(ParseError::BareLiteralHeader);
        }
    }
    let pat = parse_pattern(head)?;
    let value = parse_items(tail)?;
    Ok((pat, value))
}

/// Parse a single item as an atomic expression (`<aexpr>`).
fn parse_aexpr<'a>(item: &Item<'a>) -> Result<Expr, ParseError> {
    match item {
        Item::Sym(s) => Ok(parse_sym(s)?),
        // A `.`-prefixed item is a symbol (`.foo`, `.0`); see parse_dot_symbol.
        Item::Prefixed { sigil: '.', item } => parse_dot_symbol(item),
        // A `[…]` list is a runtime list value (any arity, no 1-element
        // collapse); a `(…)` group is grouping / spread folded into one expr.
        Item::List(seq) => parse_list(seq),
        Item::Tuple(seq) => parse_group(seq),
        // A `<str>` literal, decoded at parse into an owned `Expr::Str`.
        Item::Str(s) => Ok(Expr::Str(decode_str(s)?)),
        // A `{…}` block is a map literal (see parse_map).
        Item::Block(seq) => parse_map(seq),
        // A bare `.` (composition combinator) is deferred; any other stray punct
        // (`:`, `=`) has no atomic reading outside a map entry / `let` binding.
        Item::Punct(".") => Err(ParseError::CombinatorDeferred),
        Item::Punct(_) => Err(ParseError::PunctAtAtom),
        // Filtered before we get here.
        Item::Comm(_) => Err(ParseError::EmptyChain),
        // A `&`-binder is never fed to parse_aexpr by the split logic above.
        Item::Prefixed { .. } => Err(ParseError::UnexpectedBinder),
    }
}

/// Decode a Muon `<str>`'s raw inner text (the bytes between the quotes, escapes
/// unresolved) into an owned UTF-8 [`Text`]. Muon has already validated the escape
/// *grammar* (only `\" \n \t \r \\ \/ \b \f` and four-hex-digit `\uXXXX`, no raw
/// newline), so this resolves the escapes and — the higher-layer job Muon defers —
/// **combines `\uXXXX` surrogate pairs** into one scalar. The one failure is an
/// **unpaired surrogate** (a high not followed by a low, or a lone low), which
/// UTF-8 cannot represent: [`ParseError::LoneSurrogate`].
fn decode_str(raw: &str) -> Result<Text, ParseError> {
    let b = raw.as_bytes();
    let mut out = String::with_capacity(raw.len());
    let mut i = 0;
    let mut chunk = 0; // start of the current verbatim (unescaped) run
    while i < b.len() {
        if b[i] != b'\\' {
            i += 1; // a non-escape byte (incl. any UTF-8 continuation) copies as-is
            continue;
        }
        out.push_str(&raw[chunk..i]); // flush the verbatim run before this escape
        match b[i + 1] {
            b'"' => out.push('"'),
            b'\\' => out.push('\\'),
            b'/' => out.push('/'),
            b'n' => out.push('\n'),
            b't' => out.push('\t'),
            b'r' => out.push('\r'),
            b'b' => out.push('\u{8}'),
            b'f' => out.push('\u{c}'),
            b'u' => {
                let hi = hex4(&b[i + 2..i + 6]);
                i += 6;
                if (0xD800..=0xDBFF).contains(&hi) {
                    // A high surrogate must be completed by a `\uXXXX` low surrogate.
                    let lo = match (b.get(i), b.get(i + 1)) {
                        (Some(b'\\'), Some(b'u')) => hex4(&b[i + 2..i + 6]),
                        _ => return Err(ParseError::LoneSurrogate),
                    };
                    if !(0xDC00..=0xDFFF).contains(&lo) {
                        return Err(ParseError::LoneSurrogate);
                    }
                    let c = 0x1_0000 + ((hi - 0xD800) << 10) + (lo - 0xDC00);
                    out.push(char::from_u32(c).expect("combined surrogate pair"));
                    i += 6;
                } else if (0xDC00..=0xDFFF).contains(&hi) {
                    return Err(ParseError::LoneSurrogate); // a lone low surrogate
                } else {
                    out.push(char::from_u32(hi).expect("non-surrogate BMP scalar"));
                }
                chunk = i;
                continue;
            }
            _ => unreachable!("Muon validated the <str> escape grammar"),
        }
        i += 2;
        chunk = i;
    }
    out.push_str(&raw[chunk..]);
    Ok(Text::from(out.as_str()))
}

/// Read exactly four ASCII hex-digit bytes (Muon-validated) as a `u32`.
fn hex4(b: &[u8]) -> u32 {
    b.iter()
        .fold(0, |v, &c| v * 16 + (c as char).to_digit(16).unwrap())
}

/// Parse a `.`-prefixed item into a symbol. The inner item must be a single
/// name or number segment (`.foo`, `.0`); a `.` glued to anything else — the
/// record sugar `.(…)`, a nested sigil, a string — is deferred / ill-formed.
fn parse_dot_symbol<'a>(item: &Item<'a>) -> Result<Expr, ParseError> {
    match item {
        // Stored *without* the leading dot; the dot is implied by Expr::Symbol
        // and re-added when displayed / dumped.
        Item::Sym(s) => Ok(Expr::Symbol(text(s))),
        _ => Err(ParseError::BadSymbol),
    }
}

/// Classify a `<sym>`: an integer literal, a name, or an error. Symbols are no
/// longer `<sym>`s (a `.` is a Muon sigil now) — they arrive as `<prefixed>`
/// items and are handled by parse_dot_symbol.
fn parse_sym(s: &str) -> Result<Expr, ParseError> {
    if is_keyword(s) {
        // A keyword is syntax, never a reference. `let` at a chain head is
        // handled before we get here; anywhere else it (and `with`) is an error.
        return Err(ParseError::ReservedKeyword);
    }
    if s == "_" {
        // `_` is the discard pattern (valid only as a binder), never a reference.
        Err(ParseError::DiscardReference)
    } else if let Some(n) = parse_int(s) {
        Ok(Expr::Int(n))
    } else if s.as_bytes()[0].is_ascii_digit() {
        // Digit-leading but not a valid int, and a name can't start with a digit.
        Err(ParseError::MalformedNumber)
    } else if s.starts_with("__") {
        // A `__` name is un-bindable, so resolve a known builtin here (a direct
        // dispatch node) rather than leaving it to a failing env walk plus a name
        // match on every call. The namespace is the language's, and closed, so an
        // unknown one is rejected here too — a misspelled `__mian` is a compile
        // error naming the namespace, not a name that happens to bind to nothing.
        // A reserved moditem (`__main`) is not a name at all and lands here as
        // well: it is a slot, and nothing reads it by reference.
        //
        // The three **home-module leaves** are the other clause: they read the
        // module the body is written in rather than naming a builtin, so they
        // become an `Expr::Home` whose depth the resolver measures (a leaf outside
        // any module body is [`ParseError::OutsideModule`] there).
        if let Some(leaf) = home_leaf(s) {
            return Ok(Expr::Home { leaf, depth: 0 });
        }
        match Builtin::from_name(s) {
            Some(op) => Ok(Expr::Builtin(op)),
            None => Err(ParseError::UnknownReserved(text(s))),
        }
    } else {
        Ok(Expr::Name(text(s)))
    }
}

/// The [home-module leaf](HomeLeaf) a `__` name spells, if it is one. Kept beside
/// [`reserved_moditem`] and read the same way: the `__` namespace is the
/// language's and closed, so every name in it is defined in exactly one of these
/// small tables.
fn home_leaf(name: &str) -> Option<HomeLeaf> {
    match name {
        "__module" => Some(HomeLeaf::Module),
        "__new" => Some(HomeLeaf::New),
        "__value" => Some(HomeLeaf::Value),
        _ => None,
    }
}

/// Parse an integer literal per the *integers* grammar: optional `-`/`+` sign,
/// then decimal / `0x` hex / `0b` binary digits, with `_` separating digit
/// groups (never leading, trailing, or doubled). `None` if `s` is not a literal.
fn parse_int(s: &str) -> Option<BigInt> {
    let (neg, body) = match s.as_bytes().first()? {
        b'-' => (true, &s[1..]),
        b'+' => (false, &s[1..]),
        _ => (false, s),
    };
    let (radix, digits) =
        if let Some(h) = body.strip_prefix("0x").or_else(|| body.strip_prefix("0X")) {
            (16u32, h)
        } else if let Some(b) = body.strip_prefix("0b").or_else(|| body.strip_prefix("0B")) {
            (2, b)
        } else {
            (10, body)
        };
    // Strip `_` separators while rejecting leading/trailing/doubled ones.
    let mut cleaned = String::new();
    let mut after_sep = true; // start "after a separator" → forbids a leading `_`
    for &c in digits.as_bytes() {
        if c == b'_' {
            if after_sep {
                return None;
            }
            after_sep = true;
        } else {
            cleaned.push(c as char);
            after_sep = false;
        }
    }
    if after_sep || cleaned.is_empty() {
        return None; // trailing `_`, or no digits at all (e.g. `0x`, `+`)
    }
    let mag = BigInt::parse_bytes(cleaned.as_bytes(), radix)?;
    Some(if neg { -mag } else { mag })
}

/// Parse an application spine (a chain slice with no `&`/`let` split point and no
/// top-level `|>`), folding left. A `(…)` item does not contribute one argument —
/// it **spreads** (see `expand_arg`): `f (a, b)` folds to `((f a) b)`.
fn parse_app_spine<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    let mut args: Vec<Expr> = Vec::new();
    for it in items {
        expand_arg(it, &mut args)?;
    }
    // `items` is non-empty and every item yields at least one arg (a `()` group
    // yields the unit), so `args` is non-empty. A single arg is not an
    // application; two or more flatten into one spine (callee then arguments).
    Ok(fold_spine(args))
}

/// Fold a non-empty argument list into an expression: the lone element itself if
/// there is one, else a flattened `App` spine (element 0 the callee).
fn fold_spine(args: Vec<Expr>) -> Expr {
    if args.len() == 1 {
        args.into_iter().next().unwrap()
    } else {
        app(args)
    }
}

/// Expand one chain item into argument expressions. A `(…)` group spreads its
/// chains (see `expand_group_args`); any other item is a single atom.
fn expand_arg<'a>(item: &Item<'a>, out: &mut Vec<Expr>) -> Result<(), ParseError> {
    match item {
        Item::Tuple(seq) => expand_group_args(seq, out),
        _ => {
            out.push(parse_aexpr(item)?);
            Ok(())
        }
    }
}

/// Expand a `(…)` group's chains as arguments, on the rule **one chain → one
/// argument** (grouping is the one-chain case). An *empty* group is the nullary
/// marker: it feeds one unit value `[]` (an empty call still calls). Comment-only
/// chains are skipped and do not count toward emptiness.
fn expand_group_args<'a>(seq: &Seq<'a>, out: &mut Vec<Expr>) -> Result<(), ParseError> {
    let mut any = false;
    for chain in &seq.0 {
        if is_comment_only(chain) {
            continue;
        }
        out.push(parse_chain(chain)?);
        any = true;
    }
    if !any {
        out.push(Expr::List(Vec::new())); // nullary marker → unit []
    }
    Ok(())
}

/// Parse a `(…)` group appearing as a standalone atom: expand it (grouping /
/// spread / nullary) and fold the pieces into one expression.
fn parse_group<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    let mut args: Vec<Expr> = Vec::new();
    expand_group_args(seq, &mut args)?;
    // `expand_group_args` always yields ≥1 arg (an empty group feeds unit `[]`).
    Ok(fold_spine(args))
}

/// Parse a `[…]` list into a runtime list literal of *any* arity: `[]` (unit),
/// `[e]` (a genuine 1-list, not collapsed), `[e0, e1, …]`. Each non-comment
/// chain is one element expression.
fn parse_list<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    let mut elems: Vec<Expr> = Vec::new();
    for chain in &seq.0 {
        if is_comment_only(chain) {
            continue;
        }
        elems.push(parse_chain(chain)?);
    }
    Ok(Expr::List(elems))
}

/// Parse a `{…}` block into a map literal: each non-comment chain of the `<seq>`
/// is one entry (see `parse_entry`); comment-only chains are skipped (so a map may
/// be laid out multi-line with blank lines and comments). Entry order is source
/// order — evaluation re-sorts by the value order.
fn parse_map<'a>(seq: &Seq<'a>) -> Result<Expr, ParseError> {
    let mut entries: Vec<(Expr, Expr)> = Vec::new();
    for chain in &seq.0 {
        let items: Vec<&Item<'a>> = chain
            .0
            .iter()
            .filter(|it| !matches!(it, Item::Comm(_)))
            .collect();
        if items.is_empty() {
            continue;
        }
        entries.push(parse_entry(&items)?);
    }
    Ok(Expr::Map(entries))
}

/// Parse one map entry `<key> ":" <value>`. The `:` is a single `<punct>` item at
/// position 1; the key is the single head item (`parse_key`) and the value is the
/// rest of the chain parsed as an `<expr>`. An *empty* value tail is sugar for the
/// unit value `[]` (so `{ .foo: }` == `{ .foo: [] }`).
fn parse_entry<'a>(items: &[&Item<'a>]) -> Result<(Expr, Expr), ParseError> {
    if items.len() < 2 || !matches!(items[1], Item::Punct(":")) {
        return Err(ParseError::MalformedMapKey);
    }
    let key = parse_key(items[0])?;
    let value_items = &items[2..];
    let value = if value_items.is_empty() {
        Expr::List(Vec::new()) // empty rest → the unit value []
    } else {
        parse_items(value_items)?
    };
    Ok((key, value))
}

/// Parse a map-entry key item. A bare *non-digit* atom key is the **symbol** of
/// the same spelling — `one` == `.one` — mirroring `.foo` exactly; a key is just
/// a token. A **digit-leading** bare key (`0`, `5`) is rejected to avoid the
/// number/symbol confusion: write `.0` for the symbol or `(0)` for the integer.
/// Wrap a key as a `(…)` **computed** key to evaluate it: `(one)` is the *value*
/// of variable `one`, `(0)` the integer `0`. The remaining forms are a
/// `.`-prefixed symbol (`.one`) and a `[…]` list/unit key (`[]` is the unit key).
/// Anything else is a `MalformedMapKey`.
fn parse_key<'a>(item: &Item<'a>) -> Result<Expr, ParseError> {
    match item {
        // A bare non-digit `<sym>` key is the symbol of that spelling, read
        // exactly as `.<sym>` would be. A digit-leading key is rejected — write
        // `.5` (the symbol) or `(5)` (the computed integer key) to disambiguate.
        Item::Sym(s) if s.as_bytes()[0].is_ascii_digit() => Err(ParseError::MalformedMapKey),
        Item::Sym(s) => Ok(Expr::Symbol(text(s))),
        // `.sym` symbol key, `[…]` list/unit key, `(…)` computed key, `"…"` string
        // key — each reads exactly as the same item would at atom position.
        Item::Prefixed { sigil: '.', .. } | Item::List(_) | Item::Tuple(_) | Item::Str(_) => {
            parse_aexpr(item)
        }
        _ => Err(ParseError::MalformedMapKey),
    }
}

// ===========================================================================
// patterns
// ===========================================================================

/// `&<pattern> body` — the one binding form every abstraction (and `let`, and a
/// `__match` clause) is built from. Greedily **collects** into one multi-parameter
/// [`Lambda`]: when `body` is *directly* another abstraction (a run of `&p0 &p1 …`,
/// or a curried binder group), `pat` is prepended to its head so the whole run
/// shares one code node with a known arity. Collection stops at the first
/// non-abstraction body (a `&` nested inside an application does not extend the
/// arity) and at 255 parameters — a head that would exceed the `applied: u8`
/// counter starts a fresh nested `Lambda` instead of overflowing.
fn abs(pat: Pattern, body: Expr) -> Expr {
    match body {
        Expr::Abs(lam) if lam.head.len() < 255 => {
            // Prepend `pat` to the (freshly built, so uniquely owned) inner head.
            let lam = Rc::try_unwrap(lam).unwrap_or_else(|rc| (*rc).clone());
            let mut head = Vec::with_capacity(lam.head.len() + 1);
            head.push(pat);
            head.extend(Vec::from(lam.head));
            Expr::Abs(Rc::new(Lambda {
                head: head.into_boxed_slice(),
                body: lam.body,
                // Free variables are a resolution artifact: the parser leaves the
                // capture plan unresolved and `resolve.rs` fills it in.
                captures: Captures::Unresolved,
            }))
        }
        _ => Expr::Abs(Rc::new(Lambda {
            head: Box::new([pat]),
            body,
            captures: Captures::Unresolved,
        })),
    }
}

/// Build an application node from a flat call spine `[callee, arg0, …]` (≥ 2
/// elements). A single-element `items` is *not* an application — the caller
/// returns that element directly.
fn app(items: Vec<Expr>) -> Expr {
    debug_assert!(
        items.len() >= 2,
        "an application has a callee and ≥1 argument"
    );
    Expr::App(items.into_boxed_slice())
}

/// Apply `f` to one more `arg`, extending `f`'s call spine when it already is one
/// so `g x &y …` and `x |> f a` stay single flattened `App` nodes (a partial
/// applied to a trailing abstraction / pipe operand). Currying makes this
/// equivalent to a fresh binary application, and it re-renders identically.
fn append_arg(f: Expr, arg: Expr) -> Expr {
    match f {
        Expr::App(items) => {
            let mut v = Vec::from(items);
            v.push(arg);
            Expr::App(v.into_boxed_slice())
        }
        _ => Expr::App(Box::new([f, arg])),
    }
}

/// Whether `item` is a bare **matching literal** — a number, a `.`-symbol, or a
/// string — used where a whole `&`-header or `let` LHS is expected. These are
/// equality patterns, not binders, so a bare one reads as a stray value or an
/// intended binding; Elly requires the wrap (`&(42)`, `&(.foo)`, `&("s")`; see
/// `BareLiteralHeader`). Nested in `[…]`/`{…}`/`(…)`/an or-pattern they are fine.
fn is_bare_literal_header(item: &Item<'_>) -> bool {
    match item {
        Item::Sym(s) => parse_int(s).is_some(),
        Item::Prefixed { sigil: '.', .. } => true,
        Item::Str(_) => true,
        _ => false,
    }
}

/// Build the abstraction(s) an `&`-header `&<inner>` introduces over `body`. A
/// `(…)` inner is a **binder group** whose commas curry (`&(a, b)` → two params);
/// any other inner is a single-parameter pattern.
fn build_binder<'a>(inner: &Item<'a>, body: Expr) -> Result<Expr, ParseError> {
    match inner {
        Item::Tuple(seq) => build_group(seq, body),
        // A bare matching literal (number `&42`, symbol `&.foo`, string `&"s"`) as
        // the whole header must be parenthesized: `&(42)`, `&(.foo)`, `&("s")` (see
        // `BareLiteralHeader`). Nested literals reach `parse_atom_item` unaffected.
        it if is_bare_literal_header(it) => Err(ParseError::BareLiteralHeader),
        other => {
            let pat = parse_pattern(&[other])?;
            Ok(abs(pat, body))
        }
    }
}

/// Build a curried binder group `&(p0, p1, …)`: each non-comment chain is one
/// parameter pattern, curried left-to-right (leftmost outermost). An empty group
/// `&()` is the nullary marker, desugaring to `&[]` — one param, the unit pattern.
fn build_group<'a>(seq: &Seq<'a>, body: Expr) -> Result<Expr, ParseError> {
    let params = chain_slices(seq);
    if params.is_empty() {
        // `&()` → `&[]`: assert the argument is unit.
        return Ok(abs(Pattern::List(Vec::new(), Rest::None), body));
    }
    let mut acc = body;
    for chain in params.iter().rev() {
        let pat = parse_pattern(chain)?;
        acc = abs(pat, acc);
    }
    Ok(acc)
}

/// The non-comment chains of a `<seq>`, each as its non-comment items.
fn chain_slices<'a, 'b>(seq: &'b Seq<'a>) -> Vec<Vec<&'b Item<'a>>> {
    seq.0
        .iter()
        .filter(|c| !is_comment_only(c))
        .map(|c| {
            c.0.iter()
                .filter(|it| !matches!(it, Item::Comm(_)))
                .collect()
        })
        .collect()
}

/// The single non-comment chain of a `<seq>` (its non-comment items), or `None`
/// if the seq holds zero or more than one chain (e.g. a comma-separated group).
fn single_chain<'a, 'b>(seq: &'b Seq<'a>) -> Option<Vec<&'b Item<'a>>> {
    let mut chains = chain_slices(seq).into_iter();
    let first = chains.next()?;
    if chains.next().is_some() {
        return None;
    }
    Some(first)
}

/// Parse a pattern from a chain of items. Splits on the first top-level `|`
/// (or-pattern), then `=` (equality / at-pattern), else defers to the `as`/atom
/// levels.
fn parse_pattern<'a>(items: &[&Item<'a>]) -> Result<Pattern, ParseError> {
    if items.is_empty() {
        return Err(ParseError::BadPattern);
    }
    // `|` has the lowest precedence — split first so `=` and `as` bind tighter
    // inside each arm. Left-associative on multiple `|`.
    if let Some(idx) = items.iter().position(|it| matches!(it, Item::Punct("|"))) {
        let left = parse_pattern(&items[..idx])?;
        let right = parse_pattern(&items[idx + 1..])?;
        // Both arms must bind the same names in the same order (see
        // `ParseError::OrBindersMismatch`); that agreement is checked by the
        // resolver, which has the binders' de Bruijn order naturally.
        return Ok(Pattern::Or(Box::new(left), Box::new(right)));
    }
    // Prefix ordering comparators `< <ref>` / `> <ref>` (the rest is an atom
    // comparand, like `= <ref>`); they only appear at the head of a pattern.
    match items[0] {
        Item::Punct("<") => return Ok(Pattern::Less(parse_comparand(&items[1..])?)),
        Item::Punct(">") => return Ok(Pattern::Greater(parse_comparand(&items[1..])?)),
        _ => {}
    }
    if let Some(idx) = items.iter().position(|it| matches!(it, Item::Punct("="))) {
        if idx == 0 {
            // `= <ref>` — equality against an atom (name or literal).
            return Ok(Pattern::Equal(parse_comparand(&items[1..])?));
        }
        // `name = pat` — at-pattern (the rest is a *pattern*).
        let name = at_name(&items[..idx])?;
        let inner = parse_pattern(&items[idx + 1..])?;
        return Ok(Pattern::At(name, Box::new(inner)));
    }
    parse_as(items)
}

/// Parse the right-hand side of an `=` / `<` / `>` comparand: exactly one
/// **atom** — a name (`= x`), an integer (`= 5`), or a symbol (`= .foo`). A
/// pattern is a *closed grammar*, so a comparand never recurses into the general
/// expression parser (`parse_items`); a compound `= f x` / `< (f x)` is rejected
/// (`ComparandNotAtom`). The atom keeps the ordinary expression default at match
/// time — a name is a lookup — which is the only non-literal a match evaluates.
fn parse_comparand<'a>(items: &[&Item<'a>]) -> Result<Expr, ParseError> {
    match items {
        [it] => match it {
            Item::Sym(s) => parse_sym(s),
            Item::Prefixed { sigil: '.', item } => parse_dot_symbol(item),
            Item::Str(s) => Ok(Expr::Str(decode_str(s)?)),
            _ => Err(ParseError::ComparandNotAtom),
        },
        _ => Err(ParseError::ComparandNotAtom),
    }
}

/// The bound name of an at-pattern's left-hand side: exactly one plain name (not
/// a keyword, a `__` name, a discard, or a number).
fn at_name<'a>(items: &[&Item<'a>]) -> Result<Text, ParseError> {
    plain_name(items, ParseError::BadPattern)
}

/// The narrowing level: the `__value <pat>` unwrapping qualifier, the prefix
/// `(as <Proto>) <pat>`, the postfix `<pat> as <Proto>`, or a bare atom.
fn parse_as<'a>(items: &[&Item<'a>]) -> Result<Pattern, ParseError> {
    // `__value <pat>` — narrow to an object of the home module and match its
    // payload. It qualifies whatever follows, so the rest is a whole pattern and
    // `__value x as Int` reads as `__value (x as Int)`.
    if let Item::Sym("__value") = items[0] {
        if items.len() < 2 {
            // Nothing to unwrap *into*. `__value _` is how to say "an object of
            // mine, payload ignored" — spelled out, since a bare `__value` in a
            // binder is much more likely a slip.
            return Err(ParseError::BadPattern);
        }
        let inner = parse_pattern(&items[1..])?;
        return Ok(Pattern::Unwrap {
            depth: 0,
            inner: Box::new(inner),
        });
    }
    // Prefix: `(as <Proto>) <pat>` — items[0] is a `(as …)` group.
    if let Item::Tuple(seq) = items[0] {
        if let Some(chain) = single_chain(seq) {
            if !chain.is_empty() && matches!(chain[0], Item::Sym("as")) {
                let proto = parse_proto_ref(&chain[1..])?;
                let inner = parse_pattern(&items[1..])?;
                return Ok(Pattern::Type(proto, Box::new(inner)));
            }
        }
    }
    // Postfix: `<atom> as <Proto>`.
    if let Some(idx) = items.iter().position(|it| matches!(it, Item::Sym("as"))) {
        let proto = parse_proto_ref(&items[idx + 1..])?;
        let inner = parse_atom(&items[..idx])?;
        return Ok(Pattern::Type(proto, Box::new(inner)));
    }
    parse_atom(items)
}

/// Parse the prototype of an `as <Proto>` pattern: exactly one **name**. A
/// prototype is a value like any other now — `Int` is the module `__Int` under its
/// shadowable alias, not a keyword — so this is the same closed-grammar atom an
/// `=` comparand is, minus the literals: a module is named, never written out.
///
/// It stays a [`ProtoRef::Ref`] here even when the name is the `__`-spelling of a
/// builtin module. The alias spelling only becomes one at *resolve* (it is the
/// resolver's bottom tier), so folding both to the compiled [`ProtoRef::Kind`]
/// form belongs there, in one place.
fn parse_proto_ref(items: &[&Item<'_>]) -> Result<ProtoRef, ParseError> {
    let [Item::Sym(s)] = items else {
        return Err(ParseError::UnknownType);
    };
    match parse_sym(s)? {
        // A name (`Bool`, `Int`), a `__` builtin (`__Int`), or `__module`.
        e @ (Expr::Name(_) | Expr::Builtin(_) | Expr::Home { .. }) => Ok(ProtoRef::Ref(e)),
        // A literal: `as 5` names no module.
        _ => Err(ParseError::UnknownType),
    }
}

/// Parse an atomic pattern: a single item (or a `(…)` grouping of one pattern).
fn parse_atom<'a>(items: &[&Item<'a>]) -> Result<Pattern, ParseError> {
    match items {
        [it] => parse_atom_item(it),
        _ => Err(ParseError::BadPattern),
    }
}

/// Parse a single atomic-pattern item.
fn parse_atom_item<'a>(item: &Item<'a>) -> Result<Pattern, ParseError> {
    match item {
        Item::Sym("_") => Ok(Pattern::Discard),
        Item::Sym(s) if is_keyword(s) => Err(ParseError::ReservedKeyword),
        Item::Sym(s) if s.starts_with("__") => Err(ParseError::ReservedName),
        // A numeric literal is an equality pattern (`= n` sugar, mirroring the
        // `.sym → Equal(Symbol)` sugar below); a digit-leading non-integer is a
        // malformed number, and everything else is a binder name.
        Item::Sym(s) => match parse_int(s) {
            Some(n) => Ok(Pattern::Equal(Expr::Int(n))),
            None if s.as_bytes()[0].is_ascii_digit() => Err(ParseError::MalformedNumber),
            None => Ok(Pattern::Bind(text(s))),
        },
        // `.sym` literal → `= .sym`.
        Item::Prefixed { sigil: '.', item } => Ok(Pattern::Equal(parse_dot_symbol(item)?)),
        // A `<str>` literal is an equality pattern — the textual twin of `.sym`.
        Item::Str(s) => Ok(Pattern::Equal(Expr::Str(decode_str(s)?))),
        Item::List(seq) => parse_list_pattern(seq),
        // `(…)` grouping — a single subpattern; commas (multiple chains) are an
        // error (they only curry after `&`).
        Item::Tuple(seq) => match single_chain(seq) {
            Some(chain) if !chain.is_empty() => parse_pattern(&chain),
            _ => Err(ParseError::BadPattern),
        },
        Item::Block(seq) => parse_map_pattern(seq),
        _ => Err(ParseError::BadPattern),
    }
}

/// Parse a `{ k0: p0, … }` map pattern: each entry is `<key> ":" <value-pattern>`,
/// with an optional trailing `...`/`...rest`; `Rest::None` (no rest) is a
/// **closed** key set. The **key is itself a pattern**, but must denote a concrete
/// value to probe. A **lookup** key names a concrete value: `.sym` (the literal),
/// bare `sym` (the literal), or the equality pattern `(= <expr>)` / `= <expr>` for
/// a computed key. A grouped **binder** pattern in key position is instead a
/// **capture** — `(k)` / `(_)` peels the smallest remaining entry, binding its key
/// (see `match_pattern` in `eval.rs`); this is why the computed key is `(= k)`,
/// not `(k)`. The entry splits on its first top-level `:`.
fn parse_map_pattern<'a>(seq: &Seq<'a>) -> Result<Pattern, ParseError> {
    let chains = chain_slices(seq);
    let n = chains.len();
    let mut entries: Vec<(MapKey, Pattern)> = Vec::new();
    let mut rest = Rest::None;
    for (i, chain) in chains.iter().enumerate() {
        if let Some(r) = as_rest(chain) {
            if i != n - 1 {
                return Err(ParseError::BadPattern); // rest must be trailing
            }
            rest = r;
        } else {
            let colon = chain
                .iter()
                .position(|it| matches!(it, Item::Punct(":")))
                .ok_or(ParseError::MalformedMapKey)?;
            let val_items = &chain[colon + 1..];
            if colon == 0 || val_items.is_empty() {
                return Err(ParseError::MalformedMapKey); // empty key or value
            }
            // A bare single `<sym>` key is the literal symbol (like a map literal);
            // otherwise the key is a pattern — an equality form is a concrete-key
            // lookup, any other (binder) pattern is a key capture.
            let key_items = &chain[..colon];
            let bare_sym = match key_items {
                [Item::Sym(s)] => Some(*s),
                _ => None,
            };
            let key = if let Some(s) = bare_sym {
                // A bare non-digit sym key is the literal symbol (`five` → `.five`);
                // a digit-leading key is rejected — write `.5` (the symbol) or
                // `(5)` / `(= 5)` (the integer key) to disambiguate.
                if s.as_bytes()[0].is_ascii_digit() {
                    return Err(ParseError::MalformedMapKey);
                }
                MapKey::Lookup(Expr::Symbol(text(s)))
            } else {
                match parse_pattern(key_items)? {
                    Pattern::Equal(expr) => MapKey::Lookup(expr),
                    kpat => MapKey::Capture(Box::new(kpat)),
                }
            };
            let valpat = parse_pattern(val_items)?;
            entries.push((key, valpat));
        }
    }
    Ok(Pattern::Map(entries, rest))
}

/// Parse a `[…]` list pattern: fixed-arity element patterns with an optional
/// trailing `...`/`...rest`.
fn parse_list_pattern<'a>(seq: &Seq<'a>) -> Result<Pattern, ParseError> {
    let chains = chain_slices(seq);
    let n = chains.len();
    let mut elems: Vec<Pattern> = Vec::new();
    let mut rest = Rest::None;
    for (i, chain) in chains.iter().enumerate() {
        if let Some(r) = as_rest(chain) {
            if i != n - 1 {
                return Err(ParseError::BadPattern); // rest must be trailing
            }
            rest = r;
        } else {
            elems.push(parse_pattern(chain)?);
        }
    }
    Ok(Pattern::List(elems, rest))
}

/// Recognize a trailing-rest element chain: `...rest` (a name) or `...` (anon).
/// Both lex as nested `.` sigils (three deep), so no new Muon token is needed.
fn as_rest<'a>(chain: &[&Item<'a>]) -> Option<Rest> {
    if chain.len() != 1 {
        return None;
    }
    // `it = .( .( … ) )`: two `.` sigils, then either `.name` (→ named) or a bare
    // `.` punct (→ anon).
    if let Item::Prefixed {
        sigil: '.',
        item: a,
    } = chain[0]
    {
        if let Item::Prefixed {
            sigil: '.',
            item: b,
        } = a.as_ref()
        {
            match b.as_ref() {
                Item::Prefixed {
                    sigil: '.',
                    item: c,
                } => {
                    if let Item::Sym(name) = c.as_ref() {
                        return Some(Rest::Named(text(name)));
                    }
                }
                Item::Punct(".") => return Some(Rest::Anon),
                _ => {}
            }
        }
    }
    None
}

/// Does this chain hold only comments (so it contributes no expression)?
fn is_comment_only(chain: &Chain) -> bool {
    chain.0.iter().all(|it| matches!(it, Item::Comm(_)))
}

/// Is `s` an Elly keyword (reserved syntax, neither a reference nor bindable)?
/// `as` leads the type-narrowing pattern qualifier (recognized structurally
/// before this check); `with`/`when`/`match`/`case`/`of` are parked for future
/// forms (a parallel binding, a guard, and the surface `case`/`match` sugar over
/// the `__match` builtin).
fn is_keyword(s: &str) -> bool {
    matches!(
        s,
        "let"
            | "recur"
            | "import"
            | "const"
            | "local"
            | "with"
            | "as"
            | "when"
            | "match"
            | "case"
            | "of"
    )
}

/// Is this item the `import` keyword (the sym `import`)? Reserving the word is
/// what stops `import = 3` and a local named `import`, so the only place it can
/// appear is where [`parse_module`] looks for it.
fn is_import_keyword(item: &Item) -> bool {
    matches!(item, Item::Sym("import"))
}

/// Is this item the `const` keyword (the sym `const`)? Reserved for the same
/// reason `import` is: the word is syntax, so `const = 3` and a local named
/// `const` are rejected, and the only place it can appear is where
/// [`parse_module`] looks for it.
fn is_const_keyword(item: &Item) -> bool {
    matches!(item, Item::Sym("const"))
}

/// Is this item the `local` keyword (the sym `local`)? Reserved for the same
/// reason `import` and `const` are: the word is syntax, so `local = 3` and a
/// binder named `local` are rejected, and the only place it can appear is where
/// [`parse_module`] looks for it.
fn is_local_keyword(item: &Item) -> bool {
    matches!(item, Item::Sym("local"))
}

/// Can `name` be bound and then referenced from Elly source as a plain name? It
/// must be a Muon `<sym>` and pass the same tests `plain_name` applies to a
/// binding's left-hand side: not a keyword, not a `__` reserved name, not the
/// discard `_`, and not something that `reads_as_number` accepts.
///
/// This is the rule for names a *host* binds from outside a program — the PyO3
/// `elly.Env` prelude — where there is no left-hand side to parse but source must
/// still be able to read the binding back. Keep it in step with `plain_name`;
/// `crates/elly-core/tests/module.rs` pins the two together.
pub fn is_bindable_name(name: &str) -> bool {
    muon::is_sym(name)
        && !is_keyword(name)
        && !name.starts_with("__")
        && name != "_"
        && !reads_as_number(name)
}

/// Is this item a chain split point — a `&`-binder, or a `let` / `recur` keyword?
fn is_split_point(item: &Item) -> bool {
    is_binder(item) || is_let_keyword(item) || is_recur_keyword(item)
}

/// Is this item the `let` keyword (the sym `let`)?
fn is_let_keyword(item: &Item) -> bool {
    matches!(item, Item::Sym("let"))
}

/// Is this item the `recur` keyword (the sym `recur`)?
fn is_recur_keyword(item: &Item) -> bool {
    matches!(item, Item::Sym("recur"))
}

/// Is this item a `&`-prefixed binder?
fn is_binder(item: &Item) -> bool {
    matches!(item, Item::Prefixed { sigil: '&', .. })
}