lang::parser::lower_parse

lang/src/parser/lower_parse.mo

ParseTerm -> Term: de Bruijn resolution, as its own pass.

Fully wired: lang/parser.mo builds ParseDecl/ParseTerm throughout and lowers here at its three entry points (decls_parser, decls_parser_strict, decls_parser_located). Nothing outside lang/parser* ever sees a Parse* type.

This is the stage the compiler did not have. The parser used to resolve variables inline -- var_term/find_index against a ctx : List Identifier threaded through ~235 of its defs -- which is why there was nowhere to hang a source position and why Literal.struct_update's own doc comment records that "this checker has no separate parse-then-lower stage the way the reference's Literal (pre-lowering) vs CoreLit (post-lowering) split does".

The grammar now produces named, located ParseTerms and this module turns them into canonical de Bruijn Terms. The binder structure the parser used to track by hand is recovered here from the tree itself: lam/forall/pi and match arms say what they bind, so ctx is threaded through this pass instead -- one place rather than the whole grammar.

Name resolution lives HERE: find_index, show_name_path_dotted and name_ref_to_string are DEFINED in this module, and lang/parser.mo imports name_ref_to_string back rather than keeping the byte-identical copy it used to carry beside that import -- two definitions of one bare LLVM symbol, the shape validate_no_colliding_def_symbols (codegen/validate.mo) now rejects and AGENTS.md item 18 describes.

sentinel is the exception: it belongs to Term's representation rather than to this pass, so lang/types.mo owns it and both modules import it from there.

show_name_path_dotted delegates to lang/types.mo's show_name_path rather than duplicating its body here -- the old dotted-path copy predates the qualified-names split, when name paths and module paths shared one rendering and one type.

structParseLowerCtx#
pub struct ParseLowerCtx {
    binders : List Identifier,
    /// `with Dotted.Name { ... }` is open inside its own body: a bare
    /// reference that names no local binder but does name a sibling
    /// declaration lowers to that sibling's prefixed name. Innermost
    /// block first, so an inner block shadows an outer one. Consulted
    /// only AFTER `binders` -- a local always shadows an opened name.
    opened : List (Pair Identifier Identifier),
    /// Absolute start offset (as a decimal string, since there is no
    /// `Hashable I64`) -> resolved position. Built once per file by
    /// `resolve_offsets_in_file` (`lang/parser/position.mo`).
    locs : Option (HashMap String Location),
}

What lowering carries down the tree.

ParseLowerCtx, not LowerCtx: lang/lower_core_ir.mo already owns that name, and duplicate top-level names across lang/*.mo silently collide (AGENTS.md item 18) -- here loudly, since both are types.

Was a bare List Identifier of binders. It gained a second field because source positions have to reach the wrap site, and the wrap site is every value-position term -- there is nowhere else to put the table that does not amount to threading it anyway.

locs absent means no wrappers are constructed at all, and that is the whole --debug gate: check, test and a non-debug compile go through entry points that leave it none, so their ASTs are byte-identical to what they were before locations existed. The phase this would otherwise slow down is 67% of elaboration (AGENTS.md item 27), so the gate is structural rather than a matter of discipline.

deflower_ctx_locating#
pub def lower_ctx_locating (table : HashMap String Location) : ParseLowerCtx

A context that records positions from a prepared table.

The table is keyed by ParseSpan.start_rem -- the REMAINING-input length at a construct's start, which is what a span actually stores -- rather than by absolute offset. The conversion needs the file's total length and so can only happen where the whole file is in hand; doing it once when the table is built beats doing it at each of the ~10^4 lookups.

deflower_ctx_bare#
pub def lower_ctx_bare : ParseLowerCtx

A context that records no positions -- what every non-debug caller uses.

defcollect_decl_rems#
pub def collect_decl_rems (ds : List ParseDecl) (acc : List I64) : List I64
defcollect_decl_spans#
pub def collect_decl_spans (ds : List ParseDecl) (acc : List (Pair I64 I64)) : List (Pair I64 I64)

Every TOP-LEVEL declaration's own span, as (start_rem, end_rem), in the order lower_parse_decls consumes them.

collect_decl_rems above does not carry this and is not meant to: it walks into each declaration hunting for the terms that need locating, so a declaration's own extent -- the thing an outline or a declaration-granular diagnostic wants -- is dropped on the floor. This collects exactly that dropped piece and nothing else.

THE ORDER IS THE CONTRACT. lower_parse_decls maps each ParseDecl to exactly one Decl -- no filtering, no desugaring, no length change -- EXCEPT the one documented with_d splice below. So the nth span here belongs to the nth lowered Decl, and a caller may zip the two lists. That is load-bearing and it is not enforced by any type -- a later change that filters or expands a declaration inside that map would shift every range from that point on, silently and only in the presence of a diagnostic. lang/src/tests/decl_range_tests.mo therefore pins the COUNT equality rather than trusting this paragraph.

Unlike collect_decl_kind_rems, this does NOT recurse into a scoped_open_d/decl_gen_d's inner declarations. Those are still one element of the list lower_parse_decls maps over, so descending would break the alignment this exists to provide.

with_d is the ONE exception, on both sides of that contract: a with block is the one declaration form lower_parse_decls EXPANDS rather than maps 1:1 (its lowered form is its inner decls, name-prefixed), so this splices the inner decls' own spans the same way, keeping the two lists element-for-element.

A reversed accumulator, like collect_decl_rems: callers reverse once.

defcfg_filter_parse_decls#
pub def cfg_filter_parse_decls (env : CfgEnv) (ds : List ParseDecl) : List ParseDecl

Drop the declarations whose #[cfg] is false under env, and unwrap the parser-internal attrs_d (attributes on a use/open) to its wrappee, keeping the wrapper's span. Recurses into with blocks.

deflower_parse_decls#
pub def lower_parse_decls (ctx : ParseLowerCtx) (ds : List ParseDecl) : List Decl

The single entry point. The grammar's three top-level parsers call this with an empty context; everything downstream keeps seeing Decl.

Not a strict 1:1 map: with Dotted.Name { ... } is the one form that expands -- its lowered form is its inner decls, name-prefixed by prefix_parse_decl and spliced out flat. collect_decl_spans splices the same way, keeping the two lists element-for-element (see its own doc comment).