Module segment 

Lexer-driven file segmentation for per-knot incremental lowering (issue #3084, docs/per-knot-incremental-lowering-spec.md §3 step 1).

segment_file splits an ink source file into a leading header segment plus one segment per top-level knot (and per top-level stitch before the first knot — the ones lowering promotes to knots). Segments tile the file: every byte belongs to exactly one segment, in source order, so downstream assembly can rebase per-segment output by each segment’s current offset.

The boundary decision mirrors the parser’s dispatch rule exactly — it must, because per-segment parse output has to match the corresponding subtree of the whole-file parse byte-for-byte:

• A header starts at a dispatch point: the file start, or after a NEWLINE at interpolation-brace depth zero, with trivia (whitespace, //, /* … */) skipped. This is source_file’s / knot_body’s loop shape: a == inside a prose line, a string, or a /* … */ block comment (including a multi-line or unterminated one — the lexer scans those to */ or EOF as one token) never splits.
• Brace depth tracks {/} tokens because a multiline block’s inner lines are consumed inside one statement — the parser reaches no dispatch point there, and its inner loops do not break on knot headers, so an unterminated { swallowing the rest of the file is mirrored here by depth never returning to zero.
• EQ_EQ at a dispatch point opens a knot (at_knot); a single EQ whose next non-trivia token is neither EQ nor GT opens a top-level stitch (at_stitch) — only until the first knot, after which stitch headers are internal to their knot’s segment.
• A segment’s range extends backward over the contiguous /// doc-comment block preceding its header, mirroring collect_doc_lines in brink-ir’s lowering (walk back over whitespace and newlines, attach /// line comments, break on a blank-line gap of two newlines, a plain // comment, or any other token): a doc block is structurally part of the declaration it precedes, so it must travel with the knot’s segment.

Structs

Segment

One contiguous slice of the file. Produced by segment_file; segments tile the file in source order.

Enums

SegmentKind

What a Segment covers.

Functions

segment_file

Split source into a header segment plus one segment per top-level knot / top-level stitch. See the module doc for the boundary rules.