parser-lr 0.4.1 → 0.6.0

package/dist/lib-cjs/transform/grammar-fixture.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixtureGrammarPath = fixtureGrammarPath;
+exports.findChildrenBySymbol = findChildrenBySymbol;
+exports.findChildBySymbol = findChildBySymbol;
+exports.parseFixture = parseFixture;
+exports.discoverFixtures = discoverFixtures;
+exports.runFixtureCase = runFixtureCase;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const parse_context_js_1 = require("../parse-context.js");
+/**
+ * Returns the `.grammar` file for one fixture directory.
+ *
+ * Fixture grammars are named after their directory (for example
+ * `bare-terminal/bare-terminal.grammar`). The meta-grammar keeps the reserved
+ * name `grammar.grammar` at the repo root only.
+ *
+ * @param fixtureDir - Directory containing a fixture grammar and input files.
+ */
+function fixtureGrammarPath(fixtureDir) {
+    const grammarPath = (0, node_path_1.join)(fixtureDir, `${(0, node_path_1.basename)(fixtureDir)}.grammar`);
+    return (0, node_fs_1.existsSync)(grammarPath) ? grammarPath : null;
+}
+/**
+ * Returns child AST nodes matching a symbol name.
+ *
+ * @param node - Parent AST node.
+ * @param symbol - Child symbol to find.
+ */
+function findChildrenBySymbol(node, symbol) {
+    return node.children.filter((child) => child.symbol === symbol);
+}
+/**
+ * Returns the first child AST node matching a symbol name.
+ *
+ * @param node - Parent AST node.
+ * @param symbol - Child symbol to find.
+ */
+function findChildBySymbol(node, symbol) {
+    return node.children.find((child) => child.symbol === symbol) ?? null;
+}
+/**
+ * Parses one fixture grammar and input file into an AST.
+ *
+ * @param fixtureDir - Directory containing a named fixture grammar and an input file.
+ * @param inputFileName - Input file name within the fixture directory.
+ */
+function parseFixture(fixtureDir, inputFileName = 'input.txt') {
+    const grammarPath = fixtureGrammarPath(fixtureDir);
+    if (grammarPath === null) {
+        throw new Error(`fixture grammar not found in ${fixtureDir}`);
+    }
+    const grammarSource = (0, node_fs_1.readFileSync)(grammarPath, 'utf8');
+    const input = (0, node_fs_1.readFileSync)((0, node_path_1.join)(fixtureDir, inputFileName), 'utf8').trimEnd();
+    const context = parse_context_js_1.ParseContext.fromGrammar(grammarSource, 'lr1');
+    return context.parseSource(input);
+}
+/**
+ * Discovers fixture directories containing a named `.grammar` file under a root path.
+ *
+ * @param rootDir - Root directory to scan recursively.
+ */
+function discoverFixtures(rootDir) {
+    const fixtures = [];
+    const visit = (directory) => {
+        const grammarPath = fixtureGrammarPath(directory);
+        if (grammarPath !== null) {
+            const inputFiles = (0, node_fs_1.readdirSync)(directory)
+                .filter((name) => name.startsWith('input') && name.endsWith('.txt'))
+                .sort();
+            for (const inputFile of inputFiles) {
+                const baseName = inputFile.replace(/^input/, '').replace(/\.txt$/, '');
+                const expectedName = baseName === '' ? 'expected.json' : `expected${baseName}.json`;
+                const expectedPath = (0, node_path_1.join)(directory, expectedName);
+                fixtures.push({
+                    name: `${directory.split('/').slice(-2).join('/')}/${inputFile}`,
+                    grammarPath,
+                    inputPath: (0, node_path_1.join)(directory, inputFile),
+                    expectedPath: (0, node_fs_1.existsSync)(expectedPath) ? expectedPath : null,
+                });
+            }
+        }
+        for (const entry of (0, node_fs_1.readdirSync)(directory, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                visit((0, node_path_1.join)(directory, entry.name));
+            }
+        }
+    };
+    visit(rootDir);
+    return fixtures;
+}
+/**
+ * Parses a fixture case and compares to expected JSON when present.
+ *
+ * @param fixture - Fixture metadata.
+ */
+function runFixtureCase(fixture, expectFn) {
+    const grammarSource = (0, node_fs_1.readFileSync)(fixture.grammarPath, 'utf8');
+    const input = (0, node_fs_1.readFileSync)(fixture.inputPath, 'utf8').trimEnd();
+    const context = parse_context_js_1.ParseContext.fromGrammar(grammarSource, 'lr1');
+    const ast = context.parseSource(input);
+    if (fixture.expectedPath !== null) {
+        const expected = JSON.parse((0, node_fs_1.readFileSync)(fixture.expectedPath, 'utf8'));
+        expectFn(ast).toEqual(expected);
+    }
+    return ast;
+}
+//# sourceMappingURL=grammar-fixture.js.map

package/dist/lib-cjs/transform/grammar-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar-fixture.js","sourceRoot":"","sources":["../../../src/lib/transform/grammar-fixture.ts"],"names":[],"mappings":"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"}

package/dist/lib-cjs/transform/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformCst = exports.describeProductionSlots = exports.CstTransformer = exports.referenceSlotIndex = exports.productionSlots = exports.parseRhsSymbolKey = void 0;
+var binding_map_js_1 = require("./binding-map.js");
+Object.defineProperty(exports, "parseRhsSymbolKey", { enumerable: true, get: function () { return binding_map_js_1.parseRhsSymbolKey; } });
+Object.defineProperty(exports, "productionSlots", { enumerable: true, get: function () { return binding_map_js_1.productionSlots; } });
+Object.defineProperty(exports, "referenceSlotIndex", { enumerable: true, get: function () { return binding_map_js_1.referenceSlotIndex; } });
+var cst_transformer_js_1 = require("./cst-transformer.js");
+Object.defineProperty(exports, "CstTransformer", { enumerable: true, get: function () { return cst_transformer_js_1.CstTransformer; } });
+Object.defineProperty(exports, "describeProductionSlots", { enumerable: true, get: function () { return cst_transformer_js_1.describeProductionSlots; } });
+Object.defineProperty(exports, "transformCst", { enumerable: true, get: function () { return cst_transformer_js_1.transformCst; } });
+//# sourceMappingURL=index.js.map

package/dist/lib-cjs/transform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/transform/index.ts"],"names":[],"mappings":";;;AAAA,mDAA0F;AAAjF,mHAAA,iBAAiB,OAAA;AAAE,iHAAA,eAAe,OAAA;AAAE,oHAAA,kBAAkB,OAAA;AAE/D,2DAA6F;AAApF,oHAAA,cAAc,OAAA;AAAE,6HAAA,uBAAuB,OAAA;AAAE,kHAAA,YAAY,OAAA"}

package/docs/grammar.md

@@ -155,6 +155,118 @@ transform
       ;
 ```
 
+### Choosing `pass`, `build`, and `flatten`
+
+| Transform | Use when |
+|-----------|----------|
+| `pass(slot)` | Lift one bound child unchanged. `pass(boundSlot)` preserves the bound production symbol and its `#` variant. `pass(terminalName)` at the same rule may collapse to that terminal. |
+| `build(type.#variant, …)` | Construct an AST node with a fixed shape. Omit absent optional bindings from the argument list. |
+| `flatten(type.#variant, head, tail)` | Turn a `{ repeat }` list into one AST node with ordered children. Use the repeat non-terminal (for example `list$repeat_0`) as `tail` on the head production. |
+
+**Production symbols are preserved.** When a CST node has parse-table metadata, transforms keep its production name even if it has only one terminal child. Bare `CLS` through `pass(stmt)` where `[stmt]:cls_stmt` yields an `cls_stmt` node, not `kw_cls`.
+
+### Transform contract
+
+The transformer applies these rules to every CST node:
+
+| Situation | Behavior |
+|-----------|----------|
+| `pass(slot)` | Preserve the bound production's symbol and `#` variant; never collapse to its sole terminal child. |
+| No transform rule for production `P` | Emit an identity node `{ symbol: P, variant, children }`. A named non-terminal is kept even when it has a single child; the child is not hoisted in its place. |
+| `build(type.#variant, …)` | Absent optional bindings are omitted from `children`, not shifted into other slots. |
+| `flatten(type.#list, head, tail)` | Repeat tails produce no empty placeholder nodes and drop no items. |
+
+**Nested non-terminals stay wrapped.** A production referenced inside another production keeps its own node, so consumers match the grammar non-terminal (for example `comparison_op`) rather than a lexer token name (`less`). To retain a token *inside* that wrapper, bind it: write `comparison_op = #less [tok]:less` and reference `tok` from the transform. Without the binding, `build(comparison_op.#less, tok)` has no slot to read and the child is dropped.
+
+Before / after for `CASE IS < 0` with `case_selector = #relational kw_is comparison_op integer`:
+
+```json
+{
+    "symbol": "case_selector",
+    "variant": "relational",
+    "children": [
+        { "symbol": "kw_is" },
+        { "symbol": "comparison_op", "variant": "less", "children": [ { "symbol": "less" } ] },
+        { "symbol": "integer" }
+    ]
+}
+```
+
+Run `parser-lr table validate -g mylang.grammar` to check `ast` / `transform` consistency. The validator:
+
+- warns when `pass(boundSlot)` targets a production that can match a single terminal and has no transform rule;
+- errors when a `build` / `fold` / `flatten` references a `type.#variant` not declared in `ast`;
+- warns when a production, `ast` type, or `transform` rule is declared more than once (the later definition silently overrides the earlier one).
+
+Add `--strict` to fail on warnings in CI.
+
+## Statement authoring
+
+Statements follow the same `grammar` / `ast` / `transform` pattern as expressions. Dispatch on stable `*_stmt` production names instead of keyword tokens.
+
+```ebnf
+grammar
+    statement =
+        #cls pass(stmt)
+      | #print pass(stmt)
+      | #end pass(stmt)
+      ;
+
+    cls_stmt =
+        #bare kw_cls
+      | #with kw_cls kw_with [bg]:expr
+      ;
+
+    print_stmt =
+        #bare kw_print
+      | #items kw_print [list]:print_list
+      ;
+
+    end_stmt =
+        #program kw_end
+      | #if kw_end kw_if
+      ;
+
+ast
+    cls_stmt =
+        #bare kw_cls
+      | #with kw_cls kw_with [bg]:expr
+      ;
+
+    print_stmt =
+        #bare kw_print
+      | #items kw_print [list]:print_list
+      ;
+
+    end_stmt =
+        #program kw_end
+      | #if kw_end kw_if
+      ;
+
+transform
+    statement ->
+        #cls pass(stmt)
+      | #print pass(stmt)
+      | #end pass(stmt)
+      ;
+
+    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) ;
+
+    end_stmt ->
+        #program end_stmt.#program(kw_end)
+      | #if end_stmt.#if(kw_end, kw_if) ;
+```
+
+After `pass(stmt)`, consumers see `cls_stmt`, `print_stmt`, or `end_stmt` at the statement root. Add `ast` + `transform` rules per statement production rather than scanning for keyword terminals in bridge code.
+
+See [`docs/parser-lr-enhancement-proposals.md`](parser-lr-enhancement-proposals.md) for the EduBASIC migration that motivated these conventions.
+
 ## Complete example
 
 See [`grammars/calc.grammar`](../grammars/calc.grammar) for a small working grammar with `grammar`, `ast`, and `transform` sections. [`grammars/lisp.grammar`](../grammars/lisp.grammar) and [`grammars/6502.grammar`](../grammars/6502.grammar) show larger languages.
@@ -163,6 +275,7 @@ See [`grammars/calc.grammar`](../grammars/calc.grammar) for a small working gram
 
 ```bash
 parser-lr table generate -g mylang.grammar -o mylang.json
+parser-lr table validate -g mylang.grammar
 parser-lr parse -i source.txt -g mylang.grammar
 parser-lr parse -i source.txt -t mylang.json
 ```

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

@@ -0,0 +1,337 @@
+# parser-lr open requests (EduBASIC)
+
+Audience: agents working on [parser-lr](https://github.com/adamrmoss/parser-lr).
+
+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.
+
+---
+
+## Resolved in 0.5.0 (no further work)
+
+| 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`. |
+
+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).
+
+---
+
+## 1. CLI cannot find `grammar.json` (blocker)
+
+### Symptom
+
+```bash
+npm run parser:table
+# ENOENT: .../node_modules/parser-lr/bin/grammar.json
+```
+
+Same failure for:
+
+```bash
+npx parser-lr table validate -g src/lang/parsing/grammars/edu-basic.grammar
+```
+
+### Actual layout in published 0.5.0
+
+| 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/`.
+
+### Required fix
+
+Bundle CLI against the same `grammarJsonDirectory()` helper the library uses, or copy `grammar.json` beside `bin/parser-lr.js` in `prepack`.
+
+### Acceptance test (parser-lr repo)
+
+```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
+```
+
+Both commands must exit 0 on a clean install from the tarball.
+
+---
+
+## 2. Table-only import must not load meta-grammar (blocker for Jest)
+
+### Symptom
+
+EduBASIC tests import `ParseContext` / `AstNode` from `parser-lr` only to parse a pre-built table. Jest fails:
+
+```
+SyntaxError: Cannot use 'import.meta' outside a module
+  at grammar-json-path.esm.js
+```
+
+Import chain today:
+
+```
+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)
+```
+
+`readGrammar()` is not called; meta-grammar still loads because it sits on the public barrel.
+
+### Required fix (pick one)
+
+**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:
+
+- `parser-lr` — parse runtime (`ParseContext`, `AstNode`, lexer, shift-reduce, transform)
+- `parser-lr/grammar` or `parser-lr/read-grammar` — grammar file parsing (`readGrammar`, `validateGrammarTable`)
+
+**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`.
+
+### Acceptance test (parser-lr repo)
+
+```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);
+```
+
+```javascript
+// table-only-smoke.mjs — same for ESM default entry
+import { ParseContext } from 'parser-lr';
+```
+
+Neither import may read `grammar.json` or evaluate `import.meta`.
+
+---
+
+## 3. Preserve intermediate production nodes (high)
+
+### Problem
+
+`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.
+
+EduBASIC bridge code must scan for raw tokens or alternate shapes.
+
+### 3a. `comparison_op` inside `case_selector`
+
+**Grammar (already in edu-basic):**
+
+```ebnf
+case_selector =
+    #relational kw_is comparison_op expr
+  ;
+
+comparison_op =
+    #less less
+  | #greater_equal greater_equal
+  | … ;
+```
+
+`comparison_op` **has** expression-level transforms:
+
+```ebnf
+comparison_op ->
+    #less pass(tok)
+  | #greaterEqual pass(tok)
+  | … ;
+```
+
+**Input:** `CASE IS < 0`
+
+**Actual `case_selector` children (variant `relational`):** `kw_is`, `less`, `expr`
+
+**Required:** `kw_is`, `comparison_op` (variant `less`, child `less`), `expr`
+
+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
+let_stmt = kw_let let_target compound_op expr ;
+let_target = identifier assn_path_suffix ;
+```
+
+**Input:** `LET x% = 1`
+
+**Actual:** flat `identifier`, `equal`, `expr` under `let_stmt` (no `let_target` wrapper).
+
+**Required:** `let_stmt` children include `let_target` wrapping `identifier` (and optional `assn_path_suffix`).
+
+EduBASIC workaround: [`assignment-helpers.ts`](../src/lang/parsing/ast-bridge/assignment-helpers.ts) `buildLetAssignmentTarget` accepts bare `identifier` at statement root.
+
+### 3c. `print_list` / `print_segment`
+
+**Grammar:**
+
+```ebnf
+print_stmt = kw_print [ print_list ] ;
+print_list = print_segment { print_segment } ;
+print_segment = #bare expr | #trailingComma expr comma | … ;
+```
+
+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`).
+
+**Required:** stable list shape matching expression `flatten` output (same as `expr_list`).
+
+### Proposed semantics
+
+When a CST node is a **non-terminal production** `P` and `P` has **no** `transform` rule:
+
+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).
+
+This generalizes the 0.5.0 `pass()` bound-slot fix to **all referenced non-terminals**.
+
+### Minimal reproducer grammar (add to parser-lr fixtures)
+
+```ebnf
+name "nested-production-repro" ;
+
+tokens
+    kw_is = /IS/i ;
+    kw_case = /CASE/i ;
+    less = /</ ;
+    ident = /[a-z]+/ ;
+    integer = /[0-9]+/ ;
+
+start line ;
+
+grammar
+    line = kw_case case_selector ;
+    case_selector = #relational kw_is comparison_op integer ;
+    comparison_op = #less less ;
+
+ast
+    comparison_op =
+        #less [tok]:less
+      ;
+
+transform
+    comparison_op ->
+        #less comparison_op.#less(tok) ;
+```
+
+**Input:** `CASE IS < 0`
+
+**Assert:** `case_selector` child at index 1 has `symbol === "comparison_op"`, not `less`.
+
+---
+
+## 4. `table validate` must work on edu-basic grammar (medium)
+
+Depends on **§1** (CLI packaging).
+
+Once the CLI runs, validate this consumer grammar:
+
+```bash
+npx parser-lr table validate -g src/lang/parsing/grammars/edu-basic.grammar
+```
+
+Useful warnings (already described in README) should include:
+
+- `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).
+
+`--strict` should be usable in CI.
+
+---
+
+## 5. Document transform contract (medium)
+
+Update [`docs/grammar.md`](https://github.com/adamrmoss/parser-lr/blob/main/docs/grammar.md) with explicit rules:
+
+| 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. |
+
+Include before/after JSON for `CLS`, `CASE IS < 0`, and `LET x = 1`.
+
+---
+
+## 6. Regression fixtures to add in parser-lr (medium)
+
+| 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 |
+
+Each fixture: `.grammar`, input line(s), expected AST JSON golden file.
+
+---
+
+## EduBASIC verification (run after parser-lr release)
+
+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
+```
+
+Spot checks:
+
+```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)));
+}
+"
+```
+
+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` |
+
+Then remove from edu-basic:
+
+- [`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)
+
+---
+
+## Priority summary
+
+| 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 |
+
+Target: **parser-lr 0.5.1** (or 0.6.0) with tarball acceptance tests for §1 and §2.