Source Map
This page is a source map for people changing the implementation. It is not a formal language specification.
Sources Of Truth
Section titled “Sources Of Truth”@nlk/language owns the canonical vocabulary and reusable Monaco and TextMate grammars.
@nlk/interpreter owns the implemented semantics: parsing, checking, lowering, execution, and
runtime diagnostics. User-facing docs should be updated when either authority changes.
| Area | Source |
| -------------------------------------------- | ----------------------------------- |
| Language identity and canonical vocabulary | packages/language/src/metadata.ts |
| Monaco configuration and Monarch tokenizer | packages/language/src/monaco.ts |
| TextMate grammar | packages/language/src/textmate.ts |
| Catppuccin Monaco and TextMate syntax themes | packages/ui/src/syntax-theme.ts |
Lexical and semantic highlighting
Section titled “Lexical and semantic highlighting”@nlk/language identifies syntactic forms and declaration sites. Parameter declarations are
lexical, as are declarations inside init and primed identifiers. Parameter references and unprimed
state references require symbol resolution, so the lexical adapters intentionally render them as
ordinary variables.
The Monaco and TextMate adapters do not infer symbol identity, scopes, shadowing, or reference
targets. @nlk/language must remain stateless: it must not gain a scanner or document model to
imitate semantic highlighting. Semantic-token resolution belongs in a stateful analysis layer that
can apply parameter and state roles after resolving their symbols.
Monaco and TextMate should differ only where their host capabilities inherently differ. Their lexical role mappings and final presentation colors are shared integration contracts and must not drift.
Parser And Lexer
Section titled “Parser And Lexer”| Area | Source |
| ------------------------------------------- | ----------------------------------------------------- |
| Tokens, comments, indentation, continuation | packages/interpreter/src/lexer.ts |
| Chevrotain grammar rules | packages/interpreter/src/grammar.ts |
| Parse orchestration and recovery | packages/interpreter/src/parser.ts |
| CST-to-AST construction | packages/interpreter/src/astBuilder.ts |
| Generated typed CST surface | packages/interpreter/src/cst.generated.ts |
| CST type generator | packages/interpreter/scripts/generate-cst-types.mjs |
| AST shape | packages/interpreter/src/ast.ts |
Static Checks And Lowering
Section titled “Static Checks And Lowering”| Area | Source |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| init plus while lowering | packages/interpreter/src/lower.ts |
| Static restrictions and diagnostics | packages/interpreter/src/staticCheck.ts, packages/interpreter/src/staticDiagnostics.ts |
| Static constant folding | packages/interpreter/src/staticConstants.ts |
| Commit-loop dependency planning | packages/interpreter/src/commitPlan.ts |
| Type contracts | packages/interpreter/src/typeSystem.ts |
| Error-effect analysis and function flow | packages/interpreter/src/errorSemantics.ts, packages/interpreter/src/functionSummaries.ts |
| Error-effect values and type compatibility | packages/interpreter/src/effectValues.ts, packages/interpreter/src/effectFlow.ts, packages/interpreter/src/effectTypeSystem.ts |
| Effectful-procedure inference | packages/interpreter/src/functionEffects.ts |
| Operation error/result contracts | packages/interpreter/src/operationContracts.ts |
Runtime
Section titled “Runtime”| Area | Source |
| --------------------------- | ------------------------------------------------------------------------------- |
| Program execution | packages/interpreter/src/interpreter.ts |
| Expression evaluation | packages/interpreter/src/evalExpr.ts |
| Built-ins and methods | packages/interpreter/src/builtins.ts |
| Runtime value helpers | packages/interpreter/src/values.ts |
| Diagnostics and errors | packages/interpreter/src/diagnostics.ts, packages/interpreter/src/errors.ts |
| Stable diagnostic codes | packages/interpreter/src/diagnosticCodes.ts |
| Runtime allocation limits | packages/interpreter/src/runtimeValueLimits.ts |
| Unicode case/numeric tables | packages/interpreter/src/unicodeData.generated.ts |
cst.generated.ts and unicodeData.generated.ts are generated artifacts. Change the grammar or
generator inputs, run the corresponding repository generator, and commit the regenerated output; do
not hand-edit either file.
| Area | Source |
| ------------------------------------- | ---------------------------- |
| Argument parsing and process behavior | packages/cli/src/cli.ts |
| CLI entrypoint | packages/cli/src/index.ts |
| CLI fixtures | packages/cli/test/fixtures |
Interpreter tests protect intended language behavior and regressions. Production code and observed runtime behavior remain canonical for implemented semantics. CLI tests protect input selection, flags, exit status, streamed output, and terminal rendering; they use only representative programs instead of duplicating every semantic combination. Editor tests cover the worker and browser integration on top of those contracts. Every test should encode intended behavior or a regression, rather than preserve whatever behavior the current implementation happens to exhibit. When a test disagrees with production behavior, establish the intended behavior before updating either one.
| Intended contract | Interpreter test protection | CLI protection | Boundary rationale |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| lexing, parsing, and recovered analysis | parser.test.ts, parserDiagnostics.test.ts, parserRecovery.test.ts, analysis.test.ts | selected multiple-error and source-location cases in cli.test.ts | Tokenization and recovery are interpreter semantics; the CLI verifies that collected diagnostics render. |
| static checks, lowering, and dependency order | staticCheck.test.ts, lower.test.ts, commitPlan.test.ts | representative diagnostics in diagnostics.test.ts and checked-in fixtures | The interpreter owns rejection and scheduling; the CLI samples their user-facing presentation. |
| functions, expressions, and control flow | interpreter.test.ts, conditionalRuntime.test.ts, nestedLoops.test.ts | successful end-to-end fixtures exercised by cli.test.ts | Semantic combinations stay in the interpreter; fixtures prove the built command executes real programs. |
| type contracts and collection behavior | typeRuntime.test.ts, the *Syntax.test.ts, *Runtime.test.ts, *Methods.test.ts, and *CommitLoops.test.ts suites for lists, tuples, sets, and dictionaries | representative type and collection fixtures | Container edge cases remain close to runtime code rather than being repeated through the process boundary. |
| errors as values, try, and catch | effectValues.test.ts, errValue.test.ts, errorMatching.test.ts, explicitErrorSemantics.test.ts, functionSummaries.test.ts | rendered failures in diagnostics.test.ts and process status in cli.test.ts | Structured error semantics belong to the interpreter; the CLI protects formatting and failure status. |
| commit loops, nesting, and resource limits | interpreter.test.ts, loopDepth.test.ts, nestedCommitLoops.test.ts, nestedLoops.test.ts, and the collection commit-loop suites | --max-rounds, --max-call-depth, --max-loop-depth, and --max-prime-depth in cli.test.ts | The interpreter enforces limits; the CLI verifies option plumbing, exit status, and rendered failures. |
| diagnostic structure and terminal rendering | structured assertions throughout interpreter tests | diagnostics.test.ts for layout, Unicode, sanitization, labels, notes, and suggestions | Producers protect diagnostic data; the formatter protects terminal cells and untrusted text. |
| files, stdin, arguments, and process status | not applicable | cli.test.ts and test/fixtures | These behaviors exist only at the CLI boundary and should not leak into interpreter tests. |
Tests under apps/editor/test separately protect worker request ordering, cancellation and
recovery, playground state, Monaco diagnostics, persistence, and browser workflows in Chromium and
Firefox. They do not redefine interpreter semantics.
When adding a language behavior, put its complete semantic regression in the interpreter suite. Add a CLI case only when file or stdin handling, an option, exit status, streamed output, or the rendered diagnostic is part of the intended CLI contract. When documenting edge behavior, cite the matching test path in the commit or pull-request description so future implementation changes can find it quickly.