Overview Modules syntax syntax::Assign Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Assign name : string value : syntax::Expr RECORD Expr kind : syntax::ExprKind span : syntax::Span syntax::BinOp A binary operator (§7.5): arithmetic, comparison, equality, and boolean.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION BinOp Add Sub Mul Div Rem Eq Ne Lt Gt Le Ge And Or syntax::Binary Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Binary left : syntax::Expr op : syntax::BinOp opSpan : syntax::Span right : syntax::Expr RECORD Expr kind : syntax::ExprKind span : syntax::Span UNION BinOp Add Sub Mul Div Rem Eq Ne Lt Gt Le Ge And Or RECORD Span start : number end : number syntax::BlankLines Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD BlankLines count : number syntax::Block A `{ ... }` statement block (§7): statements in order, plus the brace span.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Block stmts : syntax::Stmt[] span : syntax::Span RECORD Stmt kind : syntax::StmtKind leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span RECORD Span start : number end : number syntax::BodyMember A member of a disclosed node body: a callable, or — under error recovery —
a nested structural declaration the parser flags as illegal (ADR-011).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION BodyMember CallableMember DeclMember RECORD CallableMember callable : syntax::CallableDecl RECORD DeclMember decl : syntax::Declaration syntax::BoolLit Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD BoolLit value : bool span : syntax::Span RECORD Span start : number end : number data CallableDecl # public syntax::CallableDecl A callable (implicit operation) declared inside a disclosed node (§5.1).
`returnTy` is required (ADR-040) — a missing return type is a syntax error,
recovered as `void`; `body` absent means a black box (`;`).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD CallableDecl doc : syntax::DocBlock macros : syntax::Macro[] isPublic : bool name : string params : syntax::Param[] returnTy : syntax::Type body : syntax::Block leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span RECORD DocBlock summary : string[] extended : string[] tags : syntax::Tag[] RECORD Macro name : syntax::Path args : syntax::MacroArgs span : syntax::Span RECORD Param name : string ty : syntax::Type span : syntax::Span RECORD Type name : syntax::Path generics : syntax::Type[] isArray : bool span : syntax::Span RECORD Block stmts : syntax::Stmt[] span : syntax::Span RECORD SpannedTrivia trivia : syntax::Trivia span : syntax::Span RECORD Span start : number end : number data CallableMember # public syntax::CallableMember Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD CallableMember callable : syntax::CallableDecl RECORD CallableDecl doc : syntax::DocBlock macros : syntax::Macro[] isPublic : bool name : string params : syntax::Param[] returnTy : syntax::Type body : syntax::Block leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span syntax::Compose Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Compose sources : syntax::Expr[] RECORD Expr kind : syntax::ExprKind span : syntax::Span syntax::Constant Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Constant decl : syntax::ConstantDecl RECORD ConstantDecl name : string value : syntax::Literal span : syntax::Span data ConstantDecl # public syntax::ConstantDecl A `constant NAME = Literal` declaration (§3.6, ADR-039): a top-level primitive
value. `public` lives on the enclosing `Declaration`, mirroring `data`.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD ConstantDecl name : string value : syntax::Literal span : syntax::Span UNION Literal StringLit NumberLit BoolLit RECORD Span start : number end : number syntax::Convert Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Convert value : syntax::Expr RECORD Expr kind : syntax::ExprKind span : syntax::Span syntax::Data Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Data decl : syntax::DataDecl RECORD DataDecl name : string body : syntax::DataBody span : syntax::Span syntax::DataBody The three `data` forms. A bare `| Name` variant is an enum case; a
`| Name { .. }` variant carries an inline record (§3.5, ADR-006).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION DataBody Record Union BlackBox RECORD Record fields : syntax::Field[] RECORD Union variants : syntax::Variant[] syntax::DataDecl A `data` declaration: a record, a union, or a black box (§3.4, §3.5).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD DataDecl name : string body : syntax::DataBody span : syntax::Span UNION DataBody Record Union BlackBox RECORD Span start : number end : number syntax::DeclItem Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD DeclItem decl : syntax::Declaration RECORD Declaration doc : syntax::DocBlock macros : syntax::Macro[] isPublic : bool kind : syntax::DeclKind leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span syntax::DeclKind The structural payload of a declaration: a node (person/system/container/
component), a `data` type, or a top-level `constant` (§3.6, ADR-039).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION DeclKind Node Data Constant RECORD Node node : syntax::NodeDecl RECORD Data decl : syntax::DataDecl RECORD Constant decl : syntax::ConstantDecl syntax::DeclMember Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD DeclMember decl : syntax::Declaration RECORD Declaration doc : syntax::DocBlock macros : syntax::Macro[] isPublic : bool kind : syntax::DeclKind leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span data Declaration # public syntax::Declaration A documented, annotated structural declaration (§4): the shared
`doc → macros → public` prefix plus the structural payload.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Declaration doc : syntax::DocBlock macros : syntax::Macro[] isPublic : bool kind : syntax::DeclKind leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span RECORD DocBlock summary : string[] extended : string[] tags : syntax::Tag[] RECORD Macro name : syntax::Path args : syntax::MacroArgs span : syntax::Span UNION DeclKind Node Data Constant RECORD SpannedTrivia trivia : syntax::Trivia span : syntax::Span RECORD Span start : number end : number syntax::Diagnostic One message about a span of source. The single diagnostic type every crate
emits, so a driver collects lexer, parser, and checker output into one
ordered list. `code` is an optional stable identifier (e.g. `E0001`) for
tooling; the human-facing text is `message`. `codeDescription` is an optional
URL the code resolves to — an article explaining the rule — which the LSP
surfaces as the diagnostic's clickable link. Empty when the code carries no
article.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Diagnostic severity : syntax::Severity span : syntax::Span code : string codeDescription : string message : string UNION Severity Error Warning Info RECORD Span start : number end : number syntax::DocBlock A `///` doc block split into summary and extended on the first blank `///`
line (ADR-009): summary feeds compact diagrams, extended feeds tooltips,
tags carry the `
` markers.
#name
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD DocBlock summary : string[] extended : string[] tags : syntax::Tag[] RECORD Tag text : string span : syntax::Span syntax::Expr An expression (§7, §10): its form and source span.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Expr kind : syntax::ExprKind span : syntax::Span UNION ExprKind Marker From Postfix Ref Lit Unary Binary Paren RECORD Span start : number end : number syntax::ExprKind The expression forms (§10). `Marker` is a built-in generic constructor —
`Ok`/`Err` (`Result`) or `Some`/`None` (`Option`); `From` names a target
type and its `source`, whose `FromSource` form is the §7.2 vs §7.4 split;
`Postfix` is a `.name`/`.name(..)` access chain (ADR-007); `Unary`/`Binary`
are the §7.5 operator forms. A `Marker` or `From` head is never a binary
operand (§7.5).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION ExprKind Marker From Postfix Ref Lit Unary Binary Paren RECORD Marker kind : syntax::MarkerKind payload : syntax::Expr RECORD From ty : syntax::Type source : syntax::FromSource RECORD Postfix base : syntax::Expr segments : syntax::PostfixSeg[] RECORD Ref target : syntax::Reference RECORD Lit value : syntax::Literal RECORD Unary op : syntax::UnaryOp opSpan : syntax::Span expr : syntax::Expr RECORD Binary left : syntax::Expr op : syntax::BinOp opSpan : syntax::Span right : syntax::Expr RECORD Paren inner : syntax::Expr syntax::ExprStmt Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD ExprStmt expr : syntax::Expr RECORD Expr kind : syntax::ExprKind span : syntax::Span data FeatureDecl # public syntax::FeatureDecl A `feature Name for Path { given* when+ then+ }` BDD scenario (§5.2). Steps
are prose, not resolved against the model; the strict given→when→then order
is enforced by the parser. A feature takes no macros and no `public`.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD FeatureDecl doc : syntax::DocBlock name : string target : syntax::Path steps : syntax::FeatureStep[] leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span RECORD DocBlock summary : string[] extended : string[] tags : syntax::Tag[] RECORD Path segments : string[] span : syntax::Span RECORD FeatureStep kind : syntax::StepKind text : string span : syntax::Span RECORD SpannedTrivia trivia : syntax::Trivia span : syntax::Span RECORD Span start : number end : number data FeatureItem # public syntax::FeatureItem Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD FeatureItem decl : syntax::FeatureDecl RECORD FeatureDecl doc : syntax::DocBlock name : string target : syntax::Path steps : syntax::FeatureStep[] leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span data FeatureStep # public syntax::FeatureStep One step line in a feature flow: a step keyword and its prose string (§5.2).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD FeatureStep kind : syntax::StepKind text : string span : syntax::Span UNION StepKind Given When Then And But RECORD Span start : number end : number syntax::Field A record field `name: Type`.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Field name : string ty : syntax::Type span : syntax::Span RECORD Type name : syntax::Path generics : syntax::Type[] isArray : bool span : syntax::Span RECORD Span start : number end : number syntax::For Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD For binding : string iter : syntax::Expr body : syntax::Block RECORD Expr kind : syntax::ExprKind span : syntax::Span RECORD Block stmts : syntax::Stmt[] span : syntax::Span syntax::From Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD From ty : syntax::Type source : syntax::FromSource RECORD Type name : syntax::Path generics : syntax::Type[] isArray : bool span : syntax::Span UNION FromSource Compose Convert syntax::FromSource The source of a `from` expression (§7.2, §7.4, ADR-035) — the parser
branches on the leading token, so the two forms are distinct: a `{`
opens `Compose`, a set the target `data` record/variant is built from;
anything else is `Convert`, carrying the target type onto one value.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION FromSource Compose Convert RECORD Compose sources : syntax::Expr[] RECORD Convert value : syntax::Expr syntax::If Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD If cond : syntax::Expr thenBlock : syntax::Block elseBlock : syntax::Block RECORD Expr kind : syntax::ExprKind span : syntax::Span RECORD Block stmts : syntax::Stmt[] span : syntax::Span syntax::InnerDoc One `//!` inner-doc line documenting the module (§2.1).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD InnerDoc text : string span : syntax::Span RECORD Span start : number end : number syntax::Item A top-level item: a documented structural declaration, or a `feature` BDD
scenario.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION Item DeclItem FeatureItem RECORD DeclItem decl : syntax::Declaration RECORD FeatureItem decl : syntax::FeatureDecl syntax::Lexed The full result of lexing: the conformance token stream plus interleaved
trivia for the formatter.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Lexed tokens : syntax::Token[] trivia : syntax::SpannedTrivia[] RECORD Token kind : syntax::TokenKind span : syntax::Span text : string RECORD SpannedTrivia trivia : syntax::Trivia span : syntax::Span component Lexer # private syntax::Lexer Hand-written lexer for LANG.md §2. One pass yields the conformance token
stream (comments discarded, `///`→`Doc`+`Tag`, `//!`→`InnerDoc`) and
full-fidelity trivia for the formatter. Infallible: lexical anomalies surface
as parser diagnostics, never a failed lex.
#critical
Scenarios LexerNeverStalls
The lexer is greedy and never stalls on bad input.
given source containing an unknown byte or an unterminated string when the lexer scans it then the offending bytes are skipped or the string is closed at end of line and lexing reaches the end of input Flow Flow — LexerNeverStalls scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE LexerNeverStalls for Lexer GIVEN source containing an unknown byte or an unterminated string WHEN the lexer scans it THEN the offending bytes are skipped or the string is closed at end of line AND lexing reaches the end of input GreedyKeywordMatch
The longest identifier wins, then a keyword lookup classifies it.
given an identifier-start byte when the lexer consumes the run of identifier bytes then a reserved spelling lexes as its keyword kind but a primitive name or `Result` stays an identifier, classified later Flow Flow — GreedyKeywordMatch scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE GreedyKeywordMatch for Lexer GIVEN an identifier-start byte WHEN the lexer consumes the run of identifier bytes THEN a reserved spelling lexes as its keyword kind BUT a primitive name or `Result` stays an identifier, classified later DocCommentDisambiguation
A leading `/` resolves to a comment, doc, or inner doc by its run length.
given a line beginning with two or more slashes when the lexer reads the marker then `//!` becomes an inner-doc token and `///` becomes a doc line of prose and tag tokens but plain `//` is discarded as line-comment trivia Flow Flow — DocCommentDisambiguation scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE DocCommentDisambiguation for Lexer GIVEN a line beginning with two or more slashes WHEN the lexer reads the marker THEN `//!` becomes an inner-doc token AND `///` becomes a doc line of prose and tag tokens BUT plain `//` is discarded as line-comment trivia HashDisambiguation
On a `///` line, `
` is a tag while `#[` is a macro.
#name
given a `#` in the source when the lexer classifies it then `#name` on a doc line becomes a tag token including the `#` and `#[` becomes a macro-open token but a bare `#` in ordinary prose is skipped, with no grammar role Flow Flow — HashDisambiguation scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE HashDisambiguation for Lexer GIVEN a `#` in the source WHEN the lexer classifies it THEN `#name` on a doc line becomes a tag token including the `#` AND `#[` becomes a macro-open token BUT a bare `#` in ordinary prose is skipped, with no grammar role TriviaPreservedForFormatter
Comments and blank-line runs are preserved for the formatter.
given source interleaving tokens with comments and blank lines when the lexer runs then the token stream carries no comment trivia and comments and blank-line runs are returned alongside as spanned trivia Flow Flow — TriviaPreservedForFormatter scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE TriviaPreservedForFormatter for Lexer GIVEN source interleaving tokens with comments and blank lines WHEN the lexer runs THEN the token stream carries no comment trivia AND comments and blank-line runs are returned alongside as spanned trivia ConformanceTokenRendering
Token rendering matches the conformance golden form.
given a source string when its tokens are rendered then each token prints as `KIND@line:col \"lexeme\"` on its own line and interior backslashes and quotes in the lexeme are escaped Flow Flow — ConformanceTokenRendering scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE ConformanceTokenRendering for Lexer GIVEN a source string WHEN its tokens are rendered THEN each token prints as `KIND@line:col \"lexeme\"` on its own line AND interior backslashes and quotes in the lexeme are escaped component LineIndex # public syntax::LineIndex Precomputed newline offsets turning a byte offset into a 1-based (line, col)
pair in O(log n). Built once per source and reused for every lookup; column
counts bytes from the line start.
Scenarios OffsetToLineColumn
A byte offset maps to a 1-based line and column.
given a line index built over a source string when a byte offset is looked up then the 1-based line and byte column are returned but an offset past the end clamps to the end of the source Flow Flow — OffsetToLineColumn scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE OffsetToLineColumn for LineIndex GIVEN a line index built over a source string WHEN a byte offset is looked up THEN the 1-based line and byte column are returned BUT an offset past the end clamps to the end of the source syntax::List Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD List args : syntax::MacroArg[] UNION MacroArg LiteralArg PathArg NestedArg syntax::Lit Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Lit value : syntax::Literal UNION Literal StringLit NumberLit BoolLit syntax::Literal A literal value (ADR-013). `raw` carries the source text (string literals
keep their quotes).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION Literal StringLit NumberLit BoolLit RECORD StringLit raw : string span : syntax::Span RECORD NumberLit raw : string span : syntax::Span RECORD BoolLit value : bool span : syntax::Span syntax::LiteralArg Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD LiteralArg value : syntax::Literal UNION Literal StringLit NumberLit BoolLit syntax::Macro A `#[..]` macro (outer attribute) on a callable (§2.4): its name path and
argument form.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Macro name : syntax::Path args : syntax::MacroArgs span : syntax::Span RECORD Path segments : string[] span : syntax::Span UNION MacroArgs Word List NameValue RECORD Span start : number end : number syntax::MacroArg One argument inside a macro's `( .. )` list (§10 `MetaArg`).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION MacroArg LiteralArg PathArg NestedArg RECORD LiteralArg value : syntax::Literal RECORD PathArg path : syntax::Path RECORD NestedArg macro : syntax::Macro syntax::MacroArgs The three macro argument forms (§2.4): `#[manual]` word, `#[onevent(Path)]`/
`#[http("..")]` list, `#[schedule = "..]` name=value.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION MacroArgs Word List NameValue RECORD List args : syntax::MacroArg[] RECORD NameValue value : syntax::Literal syntax::Marker Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Marker kind : syntax::MarkerKind payload : syntax::Expr UNION MarkerKind KwOk KwErr KwSome KwNone RECORD Expr kind : syntax::ExprKind span : syntax::Span syntax::MarkerKind The built-in generic constructor a `Marker` names (§6, ADR-019). The
variants mirror the four marker keywords (their names carry the `Kw` prefix
because `Ok`/`Err`/`Some`/`None` are reserved words): `KwOk`/`KwErr` build a
`Result`, `KwSome`/`KwNone` build an `Option`.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION MarkerKind KwOk KwErr KwSome KwNone syntax::Module The typed syntax tree of one module (LANG.md §10): module-level inner docs,
then declarations and features in source order. Every node carries a `Span`;
declarations and statements also carry leading trivia so the formatter can
reproduce layout.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Module innerDocs : syntax::InnerDoc[] items : syntax::Item[] span : syntax::Span RECORD InnerDoc text : string span : syntax::Span UNION Item DeclItem FeatureItem RECORD Span start : number end : number syntax::NameValue Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD NameValue value : syntax::Literal UNION Literal StringLit NumberLit BoolLit syntax::NestedArg Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD NestedArg macro : syntax::Macro RECORD Macro name : syntax::Path args : syntax::MacroArgs span : syntax::Span syntax::Node Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Node node : syntax::NodeDecl RECORD NodeDecl kind : syntax::NodeKind name : string parent : syntax::Path body : syntax::BodyMember[] span : syntax::Span syntax::NodeDecl A `person` / `system` / `container` / `component` declaration. `parent` is
the `for <Parent>` path, present for container/component. `body` is the
disclosed member list, or absent for a black box (`;`).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD NodeDecl kind : syntax::NodeKind name : string parent : syntax::Path body : syntax::BodyMember[] span : syntax::Span UNION NodeKind Person System Container Component RECORD Path segments : string[] span : syntax::Span UNION BodyMember CallableMember DeclMember RECORD Span start : number end : number syntax::NodeKind The structural keyword class of a node.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION NodeKind Person System Container Component RECORD Container of : string RECORD Component of : string syntax::NumberLit Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD NumberLit raw : string span : syntax::Span RECORD Span start : number end : number syntax::Param A callable parameter `name: Type`.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Param name : string ty : syntax::Type span : syntax::Span RECORD Type name : syntax::Path generics : syntax::Type[] isArray : bool span : syntax::Span RECORD Span start : number end : number syntax::Paren Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Paren inner : syntax::Expr RECORD Expr kind : syntax::ExprKind span : syntax::Span syntax::Parsed Parser output: the tree (always present, recovered on error) plus the
diagnostics collected while parsing. Parsing never fails outright.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Parsed ast : syntax::Module diagnostics : syntax::Diagnostic[] RECORD Module innerDocs : syntax::InnerDoc[] items : syntax::Item[] span : syntax::Span RECORD Diagnostic severity : syntax::Severity span : syntax::Span code : string codeDescription : string message : string component Parser # private syntax::Parser Recursive-descent parser for the §10 grammar with error recovery: on
unexpected input it records a `Diagnostic`, resynchronises to the next
statement/declaration boundary, and continues. Always yields a (possibly
partial) `Module`; never panics.
#critical
Scenarios ParsingIsInfallible
Parsing always yields a tree, even on malformed input.
#critical
given source text that may contain syntax errors when the parser runs then a syntax tree is returned, recovered around the errors and each error rides alongside as a diagnostic but parsing never throws or aborts Flow Flow — ParsingIsInfallible scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE ParsingIsInfallible for Parser GIVEN source text that may contain syntax errors WHEN the parser runs THEN a syntax tree is returned, recovered around the errors AND each error rides alongside as a diagnostic BUT parsing never throws or aborts StrayTokenTerminates
A stray `;` in statement position never spins the block loop (regression).
given a callable body with a stray `;` in statement position when the block is parsed then the stray token is reported as a diagnostic and the forward-progress guard advances past it but the surrounding callable still parses Flow Flow — StrayTokenTerminates scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE StrayTokenTerminates for Parser GIVEN a callable body with a stray `;` in statement position WHEN the block is parsed THEN the stray token is reported as a diagnostic AND the forward-progress guard advances past it BUT the surrounding callable still parses MarkerAndFromAreNotOperands
A marker or `from` expression never combines with a binary operator (§7.5).
given an expression whose head is a marker or a `Type from ..` when a binary operator follows the head then the operator is reported as a diagnostic and the head expression still parses, with its postfix chain but the operator is left unconsumed for the enclosing context to resync on Flow Flow — MarkerAndFromAreNotOperands scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE MarkerAndFromAreNotOperands for Parser GIVEN an expression whose head is a marker or a `Type from ..` WHEN a binary operator follows the head THEN the operator is reported as a diagnostic AND the head expression still parses, with its postfix chain BUT the operator is left unconsumed for the enclosing context to resync on DocSummaryBodySplit
A blank `///` line splits the doc block into summary and extended.
given a doc block whose lines are separated by one blank `///` line when the doc block is parsed then lines before the blank become the summary and lines after it become the extended description and tags are gathered regardless of which side they sit on Flow Flow — DocSummaryBodySplit scroll to zoom · drag to pan + − ⟲ ⤢ FEATURE DocSummaryBodySplit for Parser GIVEN a doc block whose lines are separated by one blank `///` line WHEN the doc block is parsed THEN lines before the blank become the summary AND lines after it become the extended description AND tags are gathered regardless of which side they sit on syntax::Path A `::`-separated path of identifiers (§2.2, §10 `Path`); never empty.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Path segments : string[] span : syntax::Span RECORD Span start : number end : number syntax::PathArg Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD PathArg path : syntax::Path RECORD Path segments : string[] span : syntax::Span syntax::PathRef Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD PathRef path : syntax::Path RECORD Path segments : string[] span : syntax::Span syntax::Postfix Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Postfix base : syntax::Expr segments : syntax::PostfixSeg[] RECORD Expr kind : syntax::ExprKind span : syntax::Span RECORD PostfixSeg name : string callArgs : syntax::Expr[] span : syntax::Span syntax::PostfixSeg One `.name` or `.name(args)` step in a postfix chain (ADR-007). `callArgs`
present marks a call; absent marks field access.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD PostfixSeg name : string callArgs : syntax::Expr[] span : syntax::Span RECORD Expr kind : syntax::ExprKind span : syntax::Span RECORD Span start : number end : number syntax::Record Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Record fields : syntax::Field[] RECORD Field name : string ty : syntax::Type span : syntax::Span syntax::Ref Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Ref target : syntax::Reference UNION Reference SelfNode PathRef syntax::Reference A reference primary (§10 `Ref`): `self` or an FQN.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION Reference SelfNode PathRef RECORD SelfNode span : syntax::Span RECORD PathRef path : syntax::Path syntax::Return Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Return value : syntax::Expr RECORD Expr kind : syntax::ExprKind span : syntax::Span syntax::SelfNode Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD SelfNode span : syntax::Span RECORD Span start : number end : number syntax::Severity Diagnostic severity. `Error` invalidates the input; `Warning`/`Info` advise
and never block compilation.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION Severity Error Warning Info syntax::Span A half-open byte range `[start, end)` into one module's source. Offsets are
bytes, not characters; columns derived via `LineIndex` count bytes too,
matching the conformance token goldens.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Span start : number end : number data SpannedTrivia # public syntax::SpannedTrivia A trivia element paired with the source span it occupies.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD SpannedTrivia trivia : syntax::Trivia span : syntax::Span UNION Trivia LineComment BlockComment BlankLines RECORD Span start : number end : number syntax::StepKind The step keyword class of a feature step (§5.2). `And`/`But` continue the
preceding step's flow phase.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION StepKind Given When Then And But syntax::Stmt A statement valid inside a callable body (§7), with the leading trivia that
preceded it.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Stmt kind : syntax::StmtKind leadingTrivia : syntax::SpannedTrivia[] span : syntax::Span UNION StmtKind Assign Return If For While ExprStmt RECORD SpannedTrivia trivia : syntax::Trivia span : syntax::Span RECORD Span start : number end : number syntax::StmtKind The statement forms (§7).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION StmtKind Assign Return If For While ExprStmt RECORD Assign name : string value : syntax::Expr RECORD Return value : syntax::Expr RECORD If cond : syntax::Expr thenBlock : syntax::Block elseBlock : syntax::Block RECORD For binding : string iter : syntax::Expr body : syntax::Block RECORD While cond : syntax::Expr body : syntax::Block RECORD ExprStmt expr : syntax::Expr syntax::StringLit Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD StringLit raw : string span : syntax::Span RECORD Span start : number end : number container Syntax # public syntax::Syntax `crates/pseudoscript-syntax`. The foundation crate: source text to tokens
and a typed AST, emitting the shared `Diagnostic`. WASM-safe and I/O-free.
#critical
Components Component diagram scroll to zoom · drag to pan + − ⟲ ⤢ Pseudoscript Syntax COMPONENT Lexer Hand-written lexer for LANG.md §2. One pass yields the conformance token stream… COMPONENT LineIndex Precomputed newline offsets turning a byte offset into a 1-based (line, col) pair in… COMPONENT Parser Recursive-descent parser for the §10 grammar with error recovery: on unexpected input it… CONTAINER Cli `crates/pseudoscript` — the binary crate (`pds`). The composition root and only I/O… CONTAINER Format `crates/pseudoscript-format`. The canonical formatter: parse, then pretty-print the tre… CONTAINER Model `crates/pseudoscript-model`. AST to one resolved graph; static checks (resolution,… format check checkWorkspace checkWorkspaceModules graph build lex syntax::Tag A `
` tag from a doc block, including the leading `#` (§2.4).
#name
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Tag text : string span : syntax::Span RECORD Span start : number end : number syntax::Token A lexical token: its kind, source span, and rendered lexeme (LANG.md §2).
For most tokens `text` is the raw source slice. For `Doc`/`InnerDoc` it is
the doc text with the marker and surrounding whitespace stripped; for `Tag`
it includes the leading `#`.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Token kind : syntax::TokenKind span : syntax::Span text : string UNION TokenKind Keyword Ident Punctuation StringLiteral NumberLiteral Doc InnerDoc Tag HashLBracket RECORD Span start : number end : number syntax::TokenKind Every lexical token class (LANG.md §2). The `name` rendering (e.g.
`KW_SYSTEM`) is the conformance golden's `KIND`. Primitive type names and
`Result` are NOT keywords — they lex as `Ident` and are classified in type
position by the model crate.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION TokenKind Keyword Ident Punctuation StringLiteral NumberLiteral Doc InnerDoc Tag HashLBracket RECORD InnerDoc text : string span : syntax::Span RECORD Tag text : string span : syntax::Span syntax::Trivia Non-token source between tokens, preserved for the formatter. Doc comments,
tags, macros, and modifiers are first-class tokens/AST data, not trivia —
only discarded comments and blank-line gaps live here.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ UNION Trivia LineComment BlockComment BlankLines RECORD LineComment text : string RECORD BlockComment text : string RECORD BlankLines count : number syntax::Type A type expression: a named base with optional generic arguments and an
optional trailing `[]` array suffix (§3.3, ADR-008 — no optionality marker).
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Type name : syntax::Path generics : syntax::Type[] isArray : bool span : syntax::Span RECORD Path segments : string[] span : syntax::Span RECORD Span start : number end : number syntax::Unary Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Unary op : syntax::UnaryOp opSpan : syntax::Span expr : syntax::Expr UNION UnaryOp Not Neg RECORD Span start : number end : number RECORD Expr kind : syntax::ExprKind span : syntax::Span syntax::UnaryOp A unary operator (§7.5): boolean `!` or numeric `-`.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ syntax::Union Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Union variants : syntax::Variant[] RECORD Variant name : string record : syntax::Field[] span : syntax::Span syntax::Variant One union variant: its name and an optional inline record body.
Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD Variant name : string record : syntax::Field[] span : syntax::Span RECORD Field name : string ty : syntax::Type span : syntax::Span RECORD Span start : number end : number syntax::While Entities Entity diagram scroll to zoom · drag to pan + − ⟲ ⤢ RECORD While cond : syntax::Expr body : syntax::Block RECORD Expr kind : syntax::ExprKind span : syntax::Span RECORD Block stmts : syntax::Stmt[] span : syntax::Span 