parser-lr 0.5.0 → 0.6.1

package/docs/parser-lr-enhancement-proposals.md

@@ -1,325 +1,135 @@
-# parser-lr enhancement proposals (EduBASIC consumer)
+# parser-lr open requests (EduBASIC)
 
-This document is for agents working on [parser-lr](https://github.com/adamrmoss/parser-lr). It lists concrete improvements suggested by the EduBASIC migration (`parser-lr` **0.4.1**, grammar at [`src/lang/parsing/grammars/edu-basic.grammar`](../src/lang/parsing/grammars/edu-basic.grammar)).
+Audience: agents working on [parser-lr](https://github.com/adamrmoss/parser-lr).
 
-**Goal:** let grammar authors write stable `ast` + `transform` rules for statements the same way expressions already work, so downstream bridges do not need `keyword-fallbacks.ts`-style workarounds.
+Consumer: **edu-basic** (`parser-lr` **0.5.0** in [`package.json`](../package.json)). Reference grammar: [`src/lang/parsing/grammars/edu-basic.grammar`](../src/lang/parsing/grammars/edu-basic.grammar).
+
+This document lists **only what parser-lr still needs to change**. Items resolved in 0.5.0 are noted so they are not re-opened.
 
 ---
 
-## Reference consumer
+## Resolved in 0.5.0 (no further work)
 
-| Artifact | Path |
-|----------|------|
-| Grammar | [`src/lang/parsing/grammars/edu-basic.grammar`](../src/lang/parsing/grammars/edu-basic.grammar) |
-| Generated table | [`src/lang/parsing/edu-basic.table.json`](../src/lang/parsing/edu-basic.table.json) |
-| AST bridge | [`src/lang/parsing/ast-bridge/`](../src/lang/parsing/ast-bridge/) |
-| Keyword fallbacks (debt) | [`src/lang/parsing/ast-bridge/statements/keyword-fallbacks.ts`](../src/lang/parsing/ast-bridge/statements/keyword-fallbacks.ts) |
-| Dispatch table | [`src/lang/parsing/ast-bridge/statements/dispatch.ts`](../src/lang/parsing/ast-bridge/statements/dispatch.ts) |
+| Item | Notes |
+|------|--------|
+| **`pass()` preserves production symbol** | Bare `CLS` → `cls_stmt`, not `kw_cls`. Same for `PRINT`, `END`, `ELSE`, `WEND`, `DO`, `LOOP`, etc. |
+| **`table validate` command** | Documented in README; implementation exists but is blocked by packaging bug below. |
+| **CJS `require` export** | `package.json` `exports.require` → `dist/lib-cjs/index.js`. |
 
-Regenerate table after grammar changes:
+After upgrading to a build that includes the pass fix, EduBASIC can delete [`keyword-fallbacks.ts`](../src/lang/parsing/ast-bridge/statements/keyword-fallbacks.ts) (kept temporarily for older tables / edge cases).
 
-```bash
-npm run parser:table
-```
+---
+
+## 1. CLI cannot find `grammar.json` (blocker)
 
-Parse smoke test:
+### Symptom
 
 ```bash
-node -e "
-import { ParseContext } from 'parser-lr';
-import table from './src/lang/parsing/edu-basic.table.json' with { type: 'json' };
-const ctx = ParseContext.fromTableJson(JSON.stringify(table));
-console.log(JSON.stringify(ctx.parseSource('CLS'), null, 2));
-"
+npm run parser:table
+# ENOENT: .../node_modules/parser-lr/bin/grammar.json
 ```
 
----
-
-## Current asymmetry
-
-**Expressions** in EduBASIC have full `ast` + `transform` coverage (`comparison_expr.#binary`, `flatten(expr_list)`, etc.). Bridge code walks predictable node shapes.
-
-**Statements** use `transform` only at the `statement` dispatcher:
+Same failure for:
 
-```ebnf
-statement ->
-    #cls pass(stmt)
-  | #print pass(stmt)
-  | … ;
+```bash
+npx parser-lr table validate -g src/lang/parsing/grammars/edu-basic.grammar
 ```
 
-Individual `*_stmt` productions have **no** `ast` entries and **no** `transform` rules. When `pass(stmt)` runs and the matched production has a single terminal child, the output often **collapses** to that terminal instead of preserving the production symbol.
+### Actual layout in published 0.5.0
 
-That forces ~70 lines of `keyword-fallbacks.ts` plus duplicate handling in domain builders.
+| Path | Present? |
+|------|----------|
+| `dist/lib/grammar/grammar.json` | Yes |
+| `dist/lib-cjs/grammar/grammar.json` | Yes |
+| `bin/grammar.json` | **No** |
 
----
+CLI bundle resolves meta-grammar relative to `bin/`, not `dist/lib/grammar/`.
 
-## Priority 1: `pass()` must preserve production symbol
+### Required fix
 
-### Problem
+Bundle CLI against the same `grammarJsonDirectory()` helper the library uses, or copy `grammar.json` beside `bin/parser-lr.js` in `prepack`.
 
-Grammar author binds `[stmt]:cls_stmt` and expects consumers to key off `cls_stmt`. Today bare `CLS` yields `kw_cls`.
+### Acceptance test (parser-lr repo)
 
-**Grammar fragment (reproducer):**
+```bash
+npm pack
+tmpdir=$(mktemp -d)
+tar -xzf parser-lr-*.tgz -C "$tmpdir"
+cd "$tmpdir/package"
+node bin/parser-lr.js table validate -g grammars/calc.grammar
+node bin/parser-lr.js table generate -g grammars/calc.grammar -o /tmp/calc.json -a lalr
+```
 
-```ebnf
-name "pass-collapse-repro" ;
+Both commands must exit 0 on a clean install from the tarball.
 
-tokens
-    kw_cls = /CLS/i ;
-    kw_with = /WITH/i ;
-    ident = /[a-z]+/ ;
+---
 
-start program_line ;
+## 2. Table-only import must not load meta-grammar (blocker for Jest)
 
-grammar
-    program_line =
-        #statement [stmt]:cls_stmt
-      ;
+### Symptom
 
-    cls_stmt =
-        kw_cls [ kw_with ident ]
-      ;
+EduBASIC tests import `ParseContext` / `AstNode` from `parser-lr` only to parse a pre-built table. Jest fails:
 
-transform
-    program_line ->
-        #statement pass(stmt) ;
 ```
-
-**Input:** `CLS`
-
-**Actual output today:**
-
-```json
-{
-  "symbol": "kw_cls",
-  "children": [],
-  "text": "CLS",
-  "variant": null
-}
+SyntaxError: Cannot use 'import.meta' outside a module
+  at grammar-json-path.esm.js
 ```
 
-**Required output:**
+Import chain today:
 
-```json
-{
-  "symbol": "cls_stmt",
-  "children": [
-    { "symbol": "kw_cls", "text": "CLS", "children": [] }
-  ],
-  "variant": null
-}
 ```
-
-**Input:** `CLS WITH foo`
-
-**Required output (variant optional but symbol must stay `cls_stmt`):**
-
-```json
-{
-  "symbol": "cls_stmt",
-  "children": [
-    { "symbol": "kw_cls", "text": "CLS", "children": [] },
-    { "symbol": "kw_with", "text": "WITH", "children": [] },
-    { "symbol": "ident", "text": "foo", "children": [] }
-  ],
-  "variant": null
-}
+dist/lib/index.js
+  → grammar/index.js
+    → read-grammar.js
+      → meta-grammar-table.js  (readFileSync grammar.json at module load)
+        → grammar-json-path.esm.js  (uses import.meta.url)
 ```
 
-### Semantics proposal
+`readGrammar()` is not called; meta-grammar still loads because it sits on the public barrel.
 
-`pass(slot)` where `slot` is bound to production `P`:
+### Required fix (pick one)
 
-1. Always emit an AST node whose `symbol` is `P` (the production name).
-2. Children are the transformed slots of the matched alternative (terminals and subtrees).
-3. Set `variant` from the alternative label (`#program`, `#bare`, …) when present.
-4. **Never** hoist a sole child terminal to replace the `P` node unless the transform explicitly says `pass(thatTerminal)` at the **same** rule (not a parent rule).
+**Option A (preferred):** Lazy-load meta-grammar inside `readGrammar()` / `metaGrammarTable()` only. Do not import `meta-grammar-table.js` from `grammar/index.js` at top level. Split exports:
 
-### EduBASIC statements affected (bare input → wrong symbol today)
+- `parser-lr` — parse runtime (`ParseContext`, `AstNode`, lexer, shift-reduce, transform)
+- `parser-lr/grammar` or `parser-lr/read-grammar` — grammar file parsing (`readGrammar`, `validateGrammarTable`)
 
-| Input | Expected symbol | Actual symbol today |
-|-------|-----------------|---------------------|
-| `CLS` | `cls_stmt` | `kw_cls` |
-| `PRINT` | `print_stmt` | `kw_print` |
-| `END` | `end_stmt` (`variant: program`) | `kw_end` |
-| `ELSE` | `else_stmt` | `kw_else` |
-| `WEND` | `wend_stmt` | `kw_wend` |
-| `UEND` | `uend_stmt` | `kw_uend` |
-| `TRY` | `try_stmt` | `kw_try` |
-| `CATCH` | `catch_stmt` | `kw_catch` |
-| `FINALLY` | `finally_stmt` | `kw_finally` |
-| `RETURN` | `return_stmt` | `kw_return` |
-| `NEXT` | `next_stmt` | `kw_next` |
-| `DO` | `do_stmt` (`variant: bare`) | `kw_do` |
-| `LOOP` | `loop_stmt` (`variant: bare`) | `kw_loop` |
-| `RANDOMIZE` | `randomize_stmt` | `kw_randomize` |
-
-`END IF` correctly yields `end_stmt` with `variant: if` because multiple children prevent collapse.
-
-### Consumer cleanup after fix
-
-Delete [`keyword-fallbacks.ts`](../src/lang/parsing/ast-bridge/statements/keyword-fallbacks.ts) and remove the fallback call from [`dispatch.ts`](../src/lang/parsing/ast-bridge/statements/dispatch.ts). Remove duplicate `buildNullaryControlFlowStatement` paths that exist only for `*_stmt` vs `kw_*` pairs.
-
-### Suggested parser-lr tests
-
-Add fixtures under `grammars/fixtures/pass-preserves-production/`:
-
-- `bare-terminal.grammar` (reproducer above)
-- `labeled-variant.grammar` (`end_stmt` with `#program` / `#if`)
-- `optional-present.grammar` (`CLS WITH x`)
-- `optional-absent.grammar` (`CLS`)
-
-Assert `node.symbol` after transform, not only parse success.
-
-### Suggested CLI warning
-
-At `table generate` time, warn when:
-
-- Parent transform uses `pass(boundSlot)`
-- Bound production has **no** `transform` rule
-- Production can match with exactly one terminal child
-
----
-
-## Priority 2: Statement-level `ast` + `transform` (parity with expressions)
-
-### Problem
-
-EduBASIC `ast` section today only describes expression shapes. Statements cannot use `build` / `flatten` / labeled variants.
-
-### Target pattern for EduBASIC
-
-After Priority 1, EduBASIC should be able to add rules like:
-
-```ebnf
-ast
-    cls_stmt =
-        #bare kw_cls
-      | #with kw_cls kw_with [bg]:expr
-      ;
-
-    print_stmt =
-        #bare kw_print
-      | #items kw_print [list]:print_list
-      ;
+**Option B:** Ensure `dist/lib-cjs/` is safe under Jest without `import.meta`, and document that table-only consumers must `require('parser-lr')` (CJS). EduBASIC can point Jest at CJS, but the ESM entry should still not pull meta-grammar for consumers that only call `ParseContext.fromTableJson`.
 
-    print_list =
-        #list [first]:print_segment { [rest]:print_segment }
-      ;
-
-    print_segment =
-        #bare [value]:expr
-      | #trailingComma [value]:expr [comma]:comma
-      | #trailingSemicolon [value]:expr [semi]:semicolon
-      ;
-
-    end_stmt =
-        #program kw_end
-      | #if kw_end kw_if
-      | #unless kw_end kw_unless
-      | #select kw_end kw_select
-      | #sub kw_end kw_sub
-      | #try kw_end kw_try
-      ;
+### Acceptance test (parser-lr repo)
 
-transform
-    cls_stmt ->
-        #bare cls_stmt.#bare(kw_cls)
-      | #with cls_stmt.#with(kw_cls, kw_with, bg) ;
-
-    print_stmt ->
-        #bare print_stmt.#bare(kw_print)
-      | #items print_stmt.#items(kw_print, list) ;
-
-    print_list ->
-        #list flatten(print_list.#list, first, rest) ;
-
-    print_segment ->
-        #bare print_segment.#bare(value)
-      | #trailingComma print_segment.#trailingComma(value, comma)
-      | #trailingSemicolon print_segment.#trailingSemicolon(value, semi) ;
-
-    end_stmt ->
-        #program end_stmt.#program(kw_end)
-      | #if end_stmt.#if(kw_end, kw_if)
-      | … ;
+```javascript
+// table-only-smoke.cjs — must not throw under plain node
+const { ParseContext } = require('parser-lr');
+const table = require('./grammars/calc.table.json'); // or generate inline
+const ctx = ParseContext.fromTableJson(JSON.stringify(table));
+console.log(ctx.parseSource('1 + 2')?.symbol);
 ```
 
-Bridge code then becomes:
-
-```typescript
-export function buildClsStatement(node: AstNode): ClsStatement
-{
-    if (node.variant === 'with')
-    {
-        return new ClsStatement(buildExpression(findChildBySymbol(node, 'bg')!));
-    }
-
-    return new ClsStatement();
-}
+```javascript
+// table-only-smoke.mjs — same for ESM default entry
+import { ParseContext } from 'parser-lr';
 ```
 
-No scanning for `kw_cls` at the root, no `findExpressionRoot` guessing.
-
-### Enhancement requests for parser-lr
-
-1. **Document** recommended statement authoring pattern (mirror expression docs).
-2. **Optional shorthand:** if `ast` defines `cls_stmt` but `transform` omits it, apply identity build `cls_stmt.#alt(...)` from grammar bindings (opt-in flag `--infer-identity-transforms`).
-3. **Table validation:** error if `transform` references `type.#variant` not declared in `ast`.
+Neither import may read `grammar.json` or evaluate `import.meta`.
 
 ---
 
-## Priority 3: Stable shapes for nested statement helpers
+## 3. Preserve intermediate production nodes (high)
 
-### 3a. `help_topic` collapse
-
-**Grammar:**
-
-```ebnf
-help_stmt = kw_help help_topic ;
-help_topic = #keyword help_kw | #punct help_punct ;
-```
-
-**Input:** `HELP PRINT`
-
-**Observed:** `help_stmt` with children `kw_help`, `kw_print` (no `help_topic` wrapper).
-
-**Desired:** either preserve `help_topic` node:
-
-```json
-{
-  "symbol": "help_stmt",
-  "children": [
-    { "symbol": "kw_help", "text": "HELP" },
-    {
-      "symbol": "help_topic",
-      "variant": "keyword",
-      "children": [{ "symbol": "kw_print", "text": "PRINT" }]
-    }
-  ]
-}
-```
-
-or require explicit transform:
+### Problem
 
-```ebnf
-help_topic ->
-    #keyword help_topic.#keyword(help_kw)
-  | #punct help_topic.#punct(help_punct) ;
-```
+`pass()` fix covers **bound slots** on statement dispatch (`[stmt]:cls_stmt`). Nested productions used inside statements still **flatten** when they have no `transform` rule, even when the grammar names them explicitly.
 
-**Consumer workaround today:** [`buildHelpStatement`](../src/lang/parsing/ast-bridge/statements/io.ts) scans for any child that is not `kw_help`.
+EduBASIC bridge code must scan for raw tokens or alternate shapes.
 
-### 3b. `case_selector` and `comparison_op`
+### 3a. `comparison_op` inside `case_selector`
 
-**Grammar:**
+**Grammar (already in edu-basic):**
 
 ```ebnf
 case_selector =
-    #value expr
-  | #range expr kw_to expr
-  | #relational kw_is comparison_op expr
+    #relational kw_is comparison_op expr
   ;
 
 comparison_op =
@@ -328,221 +138,200 @@ comparison_op =
   | … ;
 ```
 
-**Input:** `CASE IS < 0`
-
-**Observed `case_selector` (variant `relational`) children:** `kw_is`, `less`, `postfix_expr` — no `comparison_op` node.
-
-**Desired:**
-
-```json
-{
-  "symbol": "case_selector",
-  "variant": "relational",
-  "children": [
-    { "symbol": "kw_is", "text": "IS" },
-    {
-      "symbol": "comparison_op",
-      "variant": "less",
-      "children": [{ "symbol": "less", "text": "<" }]
-    },
-    { "symbol": "postfix_expr", "…": "…" }
-  ]
-}
-```
-
-With transform:
+`comparison_op` **has** expression-level transforms:
 
 ```ebnf
-case_selector ->
-    #value case_selector.#value(expr)
-  | #range case_selector.#range(expr, kw_to, expr)
-  | #relational case_selector.#relational(kw_is, comparison_op, expr) ;
-
 comparison_op ->
-    #less comparison_op.#less(less)
-  | #greater_equal comparison_op.#greaterEqual(greater_equal)
+    #less pass(tok)
+  | #greaterEqual pass(tok)
   | … ;
 ```
 
-**Consumer workaround today:** [`buildCaseSelector`](../src/lang/parsing/ast-bridge/statements/control-flow.ts) matches raw token names (`less_equal`) via `isComparisonOpSymbol`.
+**Input:** `CASE IS < 0`
+
+**Actual `case_selector` children (variant `relational`):** `kw_is`, `less`, `expr`
+
+**Required:** `kw_is`, `comparison_op` (variant `less`, child `less`), `expr`
 
-### 3c. `print_list` / repeat tails
+Without this, consumers match lexer token names (`less`, `greater_equal`) instead of the grammar non-terminal `comparison_op`.
+
+### 3b. `let_target` inside `let_stmt`
 
 **Grammar:**
 
 ```ebnf
-print_stmt = kw_print [ print_list ] ;
-print_list = print_segment { print_segment } ;
+let_stmt = kw_let let_target compound_op expr ;
+let_target = identifier assn_path_suffix ;
 ```
 
-Bridge must handle:
+**Input:** `LET x% = 1`
 
-- `print_list` wrapper present or absent
-- `print_list$repeat_0` flatten tails
-- bare trailing `postfix_expr` siblings (when list flattening inlines items)
+**Actual:** flat `identifier`, `equal`, `expr` under `let_stmt` (no `let_target` wrapper).
 
-**Desired:** consistent `flatten(print_list.#list, first, rest)` output (same as `expr_list` for expressions).
+**Required:** `let_stmt` children include `let_target` wrapping `identifier` (and optional `assn_path_suffix`).
 
-**Consumer workaround today:** [`buildPrintSegmentsFromStatement`](../src/lang/parsing/ast-bridge/statements/io.ts) accepts `print_list`, `print_segment`, or raw expression children interchangeably.
+EduBASIC workaround: [`assignment-helpers.ts`](../src/lang/parsing/ast-bridge/assignment-helpers.ts) `buildLetAssignmentTarget` accepts bare `identifier` at statement root.
 
-### 3d. `let_target` / assignment paths
+### 3c. `print_list` / `print_segment`
 
 **Grammar:**
 
 ```ebnf
-let_stmt = kw_let let_target compound_op expr ;
-let_target = identifier assn_path_suffix ;
+print_stmt = kw_print [ print_list ] ;
+print_list = print_segment { print_segment } ;
+print_segment = #bare expr | #trailingComma expr comma | … ;
 ```
 
-Simple `LET x% = 1` often arrives as flat `identifier`, `equal`, `expr` without `let_target` wrapper.
-
-**Desired:** always `let_target` node with `identifier` child and optional `assn_path_suffix` list (possibly empty).
+Bridge must accept: `print_list` wrapper, `print_list$repeat_*` tails, bare `print_segment`, or trailing `postfix_expr` siblings interchangeably ([`io.ts`](../src/lang/parsing/ast-bridge/statements/io.ts) `buildPrintSegmentsFromStatement`).
 
-**Consumer workaround today:** [`assignment-helpers.ts`](../src/lang/parsing/ast-bridge/assignment-helpers.ts) handles both `let_target` and bare `identifier` at the statement root.
-
----
+**Required:** stable list shape matching expression `flatten` output (same as `expr_list`).
 
-## Priority 4: `flatten()` repeat semantics
+### Proposed semantics
 
-### Problem
+When a CST node is a **non-terminal production** `P` and `P` has **no** `transform` rule:
 
-EduBASIC relies on `flatten` for expression lists, array literals, struct members, and (target) print lists. Bridge code defends against:
+1. Emit AST node `{ symbol: P, variant: <alt label>, children: [ transformed children ] }`.
+2. Do **not** hoist single-child terminals to replace `P`.
+3. Apply existing `transform` rules when present (as with `comparison_op` in expression context).
 
-- Empty repeat tail nodes (`postfix_expr` with `variant: primary` and zero children) — see [`isEmptyPostfixTail`](../src/lang/parsing/ast-bridge/ast-node-helpers.ts)
-- Repeat segments named `foo$repeat_0` that drop or duplicate items
+This generalizes the 0.5.0 `pass()` bound-slot fix to **all referenced non-terminals**.
 
-### Minimal reproducer grammar
+### Minimal reproducer grammar (add to parser-lr fixtures)
 
 ```ebnf
-name "flatten-repeat-repro" ;
+name "nested-production-repro" ;
 
 tokens
+    kw_is = /IS/i ;
+    kw_case = /CASE/i ;
+    less = /</ ;
     ident = /[a-z]+/ ;
-    comma = /,/ ;
+    integer = /[0-9]+/ ;
 
-start list ;
+start line ;
 
 grammar
-    list = item { comma item } ;
+    line = kw_case case_selector ;
+    case_selector = #relational kw_is comparison_op integer ;
+    comparison_op = #less less ;
 
 ast
-    list = #list [first]:item { [rest]:item } ;
+    comparison_op =
+        #less [tok]:less
+      ;
 
 transform
-    list -> flatten(list.#list, first, rest) ;
+    comparison_op ->
+        #less comparison_op.#less(tok) ;
 ```
 
-**Input:** `a,b,c`
-
-**Required:** `list` node with three `item` payloads in order; no spurious empty tail nodes that confuse consumers.
-
-### Migration note
+**Input:** `CASE IS < 0`
 
-EduBASIC previously carried a local patch to `applyFlatten` in `node_modules/parser-lr` for repeat-list correctness. That fix belongs upstream with fixture tests.
+**Assert:** `case_selector` child at index 1 has `symbol === "comparison_op"`, not `less`.
 
 ---
 
-## Priority 5: `build()` optional slot handling
+## 4. `table validate` must work on edu-basic grammar (medium)
 
-### Problem
-
-When a production has optional slots (`[ kw_with expr ]`) and transform uses `build`, absent optionals should be omitted from the child list (or surfaced as explicit `null`), not shift subsequent bindings.
-
-### Minimal reproducer
-
-```ebnf
-cls_stmt = kw_cls [ kw_with ident ] ;
+Depends on **§1** (CLI packaging).
 
-ast
-    cls_stmt =
-        #main kw_cls [withKw]:kw_with [target]:ident
-      ;
+Once the CLI runs, validate this consumer grammar:
 
-transform
-    cls_stmt -> cls_stmt.#main(kw_cls, withKw, target) ;
+```bash
+npx parser-lr table validate -g src/lang/parsing/grammars/edu-basic.grammar
 ```
 
-**Input:** `CLS` — `withKw` and `target` absent.
-
-**Required:** `cls_stmt` node with only `kw_cls` child; optional named slots not required for downstream indexing.
+Useful warnings (already described in README) should include:
 
-### Migration note
+- `pass(boundSlot)` where bound production has no `transform` and can match a single terminal (legacy warning; should disappear after §3).
+- `transform` references `type.#variant` not declared in `ast`.
+- Duplicate `grammar` / `ast` / `transform` sections (edu-basic currently duplicates statement blocks; validator should flag).
 
-EduBASIC previously patched `applyBuild` optional-slot skip in `node_modules/parser-lr`.
+`--strict` should be usable in CI.
 
 ---
 
-## Priority 6: Labeled alternatives on unary productions
+## 5. Document transform contract (medium)
 
-### Problem
+Update [`docs/grammar.md`](https://github.com/adamrmoss/parser-lr/blob/main/docs/grammar.md) with explicit rules:
 
-Productions like `end_stmt` use labeled alternatives:
+| Transform | Behavior |
+|-----------|----------|
+| `pass(slot)` | Preserve bound production symbol; never collapse to sole terminal child. |
+| No rule for production `P` | Identity node `{ symbol: P, children }` (proposed §3). |
+| `build(type.#variant, …)` | Absent optional slots omitted from children, not shifted. |
+| `flatten(type.#list, head, tail)` | Repeat tails: no empty placeholder nodes; no dropped items. |
 
-```ebnf
-end_stmt =
-    #program kw_end
-  | #if kw_end kw_if
-  ;
-```
+Include before/after JSON for `CLS`, `CASE IS < 0`, and `LET x = 1`.
 
-When Priority 1 is fixed, `variant` on the output `end_stmt` node must reflect `#program` vs `#if` even for bare `END` (single child `kw_end`).
+---
 
-**Input:** `END` → `{ symbol: "end_stmt", variant: "program", children: […] }`
+## 6. Regression fixtures to add in parser-lr (medium)
 
-**Input:** `END IF` → `{ symbol: "end_stmt", variant: "if", children: […] }`
+| Fixture | Covers |
+|---------|--------|
+| `pass-preserves-production/` | Bare optional production (`cls_stmt = kw_cls [ … ]`) |
+| `nested-production-repro/` | §3 `comparison_op` inside parent without parent transform |
+| `let-target-repro/` | §3b `let_target` wrapper |
+| `flatten-repeat/` | `a,b,c` list with no spurious empty tails |
+| `build-optional-slots/` | Optional grammar slots absent in `build()` output |
+| `table-only-import/` | §2 smoke scripts |
 
-Same for `do_stmt` / `loop_stmt` (`#bare`, `#while`, `#until`).
+Each fixture: `.grammar`, input line(s), expected AST JSON golden file.
 
 ---
 
-## Priority 7: Tooling and packaging
+## EduBASIC verification (run after parser-lr release)
 
-| Item | Rationale |
-|------|-----------|
-| `parser-lr table validate` | Check transform/`ast` consistency, pass-collapse warnings |
-| Fixture corpus | Grammars + inputs + expected AST JSON (like EduBASIC cases above) |
-| CommonJS `require` entry | Jest consumers (see `jest.config.js` `moduleNameMapper` for `parser-lr`) |
-| Document `pass` vs `build` vs `flatten` | Include “do not collapse production symbol” rule |
+Run these locally after bumping `parser-lr` and regenerating the table:
 
----
+```bash
+npm install parser-lr@<version>
+npm run parser:table
+npm run parser:check
+npm test
+```
 
-## What “elegant EduBASIC grammar” looks like after fixes
+Spot checks:
 
-1. **Remove** duplicate `grammar` / `ast` / `transform` blocks (EduBASIC currently duplicates statement sections ~lines 611–1400 and ~1694–2123).
-2. **Add** `ast` + `transform` for all `*_stmt` productions (or rely on Priority 1 + identity build).
-3. **Delete** [`keyword-fallbacks.ts`](../src/lang/parsing/ast-bridge/statements/keyword-fallbacks.ts).
-4. **Shrink** bridge helpers that only exist for flat/collapsed trees (`buildPrintSegmentsFromStatement` multi-path scan, `buildHelpStatement` flat child scan, `isComparisonOpSymbol` for `CASE IS`).
-5. **Keep** [`dispatch.ts`](../src/lang/parsing/ast-bridge/statements/dispatch.ts) as a thin `symbol → builder` table keyed on stable `*_stmt` names.
+```bash
+node -e "
+import { ParseContext } from 'parser-lr';
+import table from './src/lang/parsing/edu-basic.table.json' with { type: 'json' };
+const ctx = ParseContext.fromTableJson(JSON.stringify(table));
+for (const line of ['CLS', 'PRINT', 'CASE IS < 0', 'LET x% = 1', 'HELP PRINT']) {
+  const ast = ctx.parseSource(line);
+  console.log(line, '=>', ast?.symbol, JSON.stringify(ast?.children?.map(c => c.symbol)));
+}
+"
+```
 
-Rough expected line reduction in `ast-bridge/`: on the order of **15–25%**, mostly from deleting fallback and defensive tree-walk code.
+Expected after all items above:
 
----
+| Line | Root symbol | Notable children |
+|------|-------------|------------------|
+| `CLS` | `cls_stmt` | `kw_cls` |
+| `PRINT` | `print_stmt` | `kw_print` |
+| `CASE IS < 0` | `case_stmt` | selector child includes `comparison_op` |
+| `LET x% = 1` | `let_stmt` | includes `let_target` |
+| `HELP PRINT` | `help_stmt` | `kw_help`, `help_topic` |
 
-## Suggested implementation order for parser-lr agents
+Then remove from edu-basic:
 
-1. Fix `pass()` production-symbol preservation + tests (unblocks everything).
-2. Land `flatten` and `build` optional-slot fixes with fixtures.
-3. Add `table validate` warnings for missing statement transforms.
-4. Document statement authoring guide with full mini-grammar (calc-style, but statements).
-5. Work with EduBASIC to add statement `ast`/`transform` incrementally and delete fallbacks.
+- [`keyword-fallbacks.ts`](../src/lang/parsing/ast-bridge/statements/keyword-fallbacks.ts)
+- Flat-tree fallback branches in [`io.ts`](../src/lang/parsing/ast-bridge/statements/io.ts) (`buildHelpStatement`, `buildPrintSegmentsFromStatement`)
+- `isComparisonOpSymbol` token-name matching in [`control-flow.ts`](../src/lang/parsing/ast-bridge/statements/control-flow.ts)
+- Bare `identifier` path in [`assignment-helpers.ts`](../src/lang/parsing/ast-bridge/assignment-helpers.ts)
 
 ---
 
-## EduBASIC verification checklist
-
-After each parser-lr release, run in this repo:
-
-```bash
-npm install parser-lr@<version>
-npm run parser:table
-npm test
-```
-
-Key tests:
+## Priority summary
 
-- [`specs/units/parsers/grammar-table.spec.ts`](../specs/units/parsers/grammar-table.spec.ts) — bare `CLS`, bare `PRINT`
-- [`specs/units/parsers/ast-bridge.spec.ts`](../specs/units/parsers/ast-bridge.spec.ts) — dispatch and `kw_print` fallback (remove after Priority 1)
-- [`specs/units/parsers/parser-service.spec.ts`](../specs/units/parsers/parser-service.spec.ts) — full statement coverage
-- [`programs/SelectCaseTorture.bas`](../programs/SelectCaseTorture.BAS) — `CASE IS` relational selectors
+| Priority | Item | Blocks edu-basic |
+|----------|------|------------------|
+| P0 | §1 CLI `grammar.json` path | `npm run parser:table`, `table validate` |
+| P0 | §2 Lazy meta-grammar / split entry | Jest and any `import { ParseContext } from 'parser-lr'` |
+| P1 | §3 Intermediate production nodes | Bridge simplification; `CASE IS`, `LET`, `PRINT` |
+| P2 | §4–§6 Validate, docs, fixtures | CI confidence, upstream maintenance |
 
-When Priority 1 ships, add an assertion that `parseSource('CLS').symbol === 'cls_stmt'` and remove `keyword-fallbacks` from the codebase in the same PR that bumps the parser-lr version.
+Target: **parser-lr 0.5.1** (or 0.6.0) with tarball acceptance tests for §1 and §2.