nocter-syntax#

Responsibility#

Transform one immutable source file into lexical tokens, diagnostics, and a lossless immutable syntax tree for an explicit parse goal.

Contract#

The crate consumes nocter-source and the closed language vocabulary. It publishes token and node identities, source-preserving trees, documentation trivia, structural queries, literal decoding, syntax-owned subtree completeness, and a reusable parse product that binds only to equal normalized source text. Source-backed semantic helpers accept BoundSyntax, which proves the source file and tree share one exact source identity. It also publishes a canonical declaration-syntax surface that excludes body contents, trivia, and source identities without interpreting a declaration. Each pruned semantic body root—callable block or constant/static initializer expression—is published separately as exact normalized body bytes keyed by its stable declaration-surface locator. Its source-syntax provider contract lets callers choose direct or revisioned parsing without exposing either mechanism to package or discovery code. It does not resolve names or apply semantic rules.

Internal Responsibilities#

• lexing and token subdivision
• the closed contextual-spelling catalog shared by parser comparisons and lexical validation
• canonical source-name and portable directory-module-segment validation
• event-based parsing and flat tree construction
• one callable-prefix recognizer shared by declaration classification, declaration parsing, and structural callable types; it consumes the language-owned modifier order and grammar categories and retains authored modifier nodes without effect or execution interpretation
• one structural ProvenanceClause in callable-result, input, receiver, structural-callable, and annotated-local positions without resolving its names
• syntax diagnostics and missing/error elements
• structural navigation and documentation extraction
• value-free floating-literal decimal/suffix decomposition shared by semantic consumers
• exact node-completeness queries for recovery consumers
• validated rebinding of source-independent parse work into one current SourceMap identity domain
• source-neutral declaration-syntax canonicalization with explicit body pruning
• exact per-body source surfaces under stable declaration locators
• bidirectional body-local node/token locators for source-neutral semantic recipes
• the shared direct/reusable source-syntax provider boundary

Invariants#

• Every syntax token retains its lexical-token identity and exact normalized range.
• Every independently built tree has an opaque identity carried by its NodeId values. Tree clones retain that identity; a separate parse of the same source cannot lend nodes to the first tree.
• SourceId and NodeId integrity tokens stay out of deterministic debug and presentation text.
• Floating-literal suffix spelling is decomposed once by syntax. Semantic consumers map that lexical suffix to a type and send only the decimal component to target evaluation.
• Contextual spellings remain identifier tokens; parser responsibilities select them through the typed catalog rather than duplicating source-text literals.
• Package, discovery, lowering, and tooling consume the syntax-owned module-segment validator; none maintains a second keyword or identifier exclusion list.
• Parser recovery preserves authored structure without inventing semantic success.
• Callable modifiers have dedicated nodes. One ordered vocabulary recognizes them in every supported syntax context; downstream stages never recover guarantees from token text or declaration spelling.
• A consumer never infers subtree completeness from file-wide diagnostic presence.
• Bounded ambiguity is parsed once transactionally rather than reparsed after lookahead.
• Reusing parse work rewrites every embedded source identity and rejects unequal normalized text.
• Block and initializer edits and their body-local diagnostics do not change the declaration-syntax surface; declaration shape, body presence, and declaration-local diagnostics do.
• Editing one body changes only that body's exact surface; unchanged sibling bodies retain equal locators and bytes.
• A BodySyntaxProjection is a complete immutable locator table. The checking body-source catalog constructs it once for a current body and lends that same table to every semantic recipe capture and materialization operation.