Generate per-arm CST destructurers; totality-gate them; consume them

src/gen-cst-match.ts is the VALUE-level sibling of gen-ast-types: for every
rule it emits a typed result union ({ arm: 'if_', expr, stmt, stmt2? } | ...)
and a match<Rule>(node, src) that re-derives which grammar alternative a node
matched and binds its children to named fields - the discrimination the parser
performed and the CST does not record. Each alternative compiles to a step
plan (lit / litAlt-capture / tok / node / opt / many / sep / branches) that
renders both the type and a cursor-based unifier; the unifier mirrors the
engine's matcher semantics exactly: tokenType-exact literal checks (the
$keyword-vs-Ident tie facts), the interpolated-template dual (a template token
ref accepts a Template leaf OR a '$template' node), pratt operator forms
(binaryOp/prefixOp/postfixOp synthesized beside led/nud arms), sep()'s
consumed trailing delimiter, and greedy no-backtracking quantifiers (children
always reflect the greedy success path, so local greedy decisions reproduce
the parse). Pure-literal alternations capture the matched text as a
string-literal-union field (alt('let','const','var') becomes
let_Kw: 'let' | 'const' | 'var').

Wired into the gen pipeline: npm run gen emits <grammar>.cst-match.ts for all
seven grammars. New gate test/cst-match-totality.ts (in check.ts, 29 gates):
every node of every generated-corpus CST plus a TS conformance stride sample
must destructure through its rule's matcher with full child consumption -
32,336 nodes, 0 misses on first run.

ts-ast-lowering's statement layer now CONSUMES the generated matcher
(switch on m.arm replaces the hand-probing that PAIN 3/5/7 documented), and
picked up break/continue labels and with-statements in the rewrite;
ts-ast-structure stays node-identical to tsc (32/32).

Cost today (maximal workload - destructuring EVERY node, naive ordered arm
try): +64% over the CST pass; the full tokens->CST->AST pipeline measures
0.96x vs tsc createSourceFile on the four bench files. Known v2 lever: the
dispatcher tries arms in declaration order, so late arms (pratt binaryOp) pay
~20 failed tries - a first-child discriminator switch will cut most nodes to
1-2 tries.

Author: johnsoncodehk

html.cst-match.ts

@@ -0,0 +1,346 @@
+// GENERATED by src/gen-cst-match.ts — do not edit. Per-arm CST destructurers for "html".
+/* eslint-disable */
+import type { AttrNode, CstChild, CstLeaf, DocumentNode, ElementNode, NodeNode } from "./html.cst-types.ts";
+
+const isLit = (c: readonly CstChild[], i: number, src: string, text: string, tt: string): boolean => {
+  const k = c[i] as CstLeaf | undefined;
+  return k !== undefined && k.tokenType === tt && k.end - k.offset === text.length && src.startsWith(text, k.offset);
+};
+const isTok = (c: readonly CstChild[], i: number, name: string): boolean => {
+  const k = c[i] as CstLeaf | undefined;
+  return k !== undefined && k.tokenType === name;
+};
+const isNodeOf = (c: readonly CstChild[], i: number, rule: string): boolean => {
+  const k = c[i] as { rule?: string } | undefined;
+  return k !== undefined && k.rule === rule;
+};
+
+export type ElementMatch =
+  | { arm: "lt"; voidName: CstLeaf; attr: (AttrNode)[] }
+  | { arm: "lt2"; name: CstLeaf; attr: (AttrNode)[] }
+  | { arm: "lt3"; name: CstLeaf; attr: (AttrNode)[]; node: (NodeNode)[]; name2: CstLeaf }
+  | { arm: "lt4"; name: CstLeaf; attr: (AttrNode)[]; rawText: CstLeaf };
+
+function _Element$lt(c: readonly CstChild[], src: string): ElementMatch | null {
+  let voidName: (CstLeaf) | undefined;
+  const attr: (AttrNode)[] = [];
+  let i = 0;
+  if (!isLit(c, i, src, "<", "$punct")) return null;
+  i++;
+  if (!(isTok(c, i, "VoidName"))) return null;
+  voidName = c[i] as CstLeaf;
+  i++;
+  for (;;) {
+    const _t0 = i; let _t1 = true;
+    _b2: {
+      if (!isNodeOf(c, i, "Attr")) { _t1 = false; break _b2; }
+      attr.push(c[i] as AttrNode);
+      i++;
+    }
+    if (!_t1) { i = _t0; break; }
+    if (i === _t0) break;
+  }
+  {
+    const _t3 = i; let _t4 = true;
+    _b5: {
+      if (!isLit(c, i, src, "/", "$punct")) { _t4 = false; break _b5; }
+      i++;
+    }
+    if (!_t4) i = _t3;
+  }
+  if (!isLit(c, i, src, ">", "$punct")) return null;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "lt", voidName: voidName!, attr };
+}
+
+function _Element$lt2(c: readonly CstChild[], src: string): ElementMatch | null {
+  let name: (CstLeaf) | undefined;
+  const attr: (AttrNode)[] = [];
+  let i = 0;
+  if (!isLit(c, i, src, "<", "$punct")) return null;
+  i++;
+  if (!(isTok(c, i, "Name"))) return null;
+  name = c[i] as CstLeaf;
+  i++;
+  for (;;) {
+    const _t0 = i; let _t1 = true;
+    _b2: {
+      if (!isNodeOf(c, i, "Attr")) { _t1 = false; break _b2; }
+      attr.push(c[i] as AttrNode);
+      i++;
+    }
+    if (!_t1) { i = _t0; break; }
+    if (i === _t0) break;
+  }
+  if (!isLit(c, i, src, "/", "$punct")) return null;
+  i++;
+  if (!isLit(c, i, src, ">", "$punct")) return null;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "lt2", name: name!, attr };
+}
+
+function _Element$lt3(c: readonly CstChild[], src: string): ElementMatch | null {
+  let name: (CstLeaf) | undefined;
+  const attr: (AttrNode)[] = [];
+  const node: (NodeNode)[] = [];
+  let name2: (CstLeaf) | undefined;
+  let i = 0;
+  if (!isLit(c, i, src, "<", "$punct")) return null;
+  i++;
+  if (!(isTok(c, i, "Name"))) return null;
+  name = c[i] as CstLeaf;
+  i++;
+  for (;;) {
+    const _t0 = i; let _t1 = true;
+    _b2: {
+      if (!isNodeOf(c, i, "Attr")) { _t1 = false; break _b2; }
+      attr.push(c[i] as AttrNode);
+      i++;
+    }
+    if (!_t1) { i = _t0; break; }
+    if (i === _t0) break;
+  }
+  if (!isLit(c, i, src, ">", "$punct")) return null;
+  i++;
+  for (;;) {
+    const _t3 = i; let _t4 = true;
+    _b5: {
+      if (!isNodeOf(c, i, "Node")) { _t4 = false; break _b5; }
+      node.push(c[i] as NodeNode);
+      i++;
+    }
+    if (!_t4) { i = _t3; break; }
+    if (i === _t3) break;
+  }
+  if (!isLit(c, i, src, "<", "$punct")) return null;
+  i++;
+  if (!isLit(c, i, src, "/", "$punct")) return null;
+  i++;
+  if (!(isTok(c, i, "Name"))) return null;
+  name2 = c[i] as CstLeaf;
+  i++;
+  if (!isLit(c, i, src, ">", "$punct")) return null;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "lt3", name: name!, attr, node, name2: name2! };
+}
+
+function _Element$lt4(c: readonly CstChild[], src: string): ElementMatch | null {
+  let name: (CstLeaf) | undefined;
+  const attr: (AttrNode)[] = [];
+  let rawText: (CstLeaf) | undefined;
+  let i = 0;
+  if (!isLit(c, i, src, "<", "$punct")) return null;
+  i++;
+  if (!(isTok(c, i, "Name"))) return null;
+  name = c[i] as CstLeaf;
+  i++;
+  for (;;) {
+    const _t0 = i; let _t1 = true;
+    _b2: {
+      if (!isNodeOf(c, i, "Attr")) { _t1 = false; break _b2; }
+      attr.push(c[i] as AttrNode);
+      i++;
+    }
+    if (!_t1) { i = _t0; break; }
+    if (i === _t0) break;
+  }
+  if (!isLit(c, i, src, ">", "$punct")) return null;
+  i++;
+  if (!(isTok(c, i, "RawText"))) return null;
+  rawText = c[i] as CstLeaf;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "lt4", name: name!, attr, rawText: rawText! };
+}
+
+export function matchElement(n: ElementNode, src: string): ElementMatch {
+  const c = n.children;
+  { const m = _Element$lt(c, src); if (m !== null) return m; }
+  { const m = _Element$lt2(c, src); if (m !== null) return m; }
+  { const m = _Element$lt3(c, src); if (m !== null) return m; }
+  { const m = _Element$lt4(c, src); if (m !== null) return m; }
+  throw new Error("matchElement: no arm matches" + ' @' + n.offset);
+}
+
+export type AttrMatch =
+  | { arm: "name"; name: CstLeaf; attrValue?: CstLeaf; name2?: CstLeaf; unquotedValue?: CstLeaf };
+
+function _Attr$name(c: readonly CstChild[], src: string): AttrMatch | null {
+  let name: (CstLeaf) | undefined;
+  let attrValue: (CstLeaf) | undefined;
+  let name2: (CstLeaf) | undefined;
+  let unquotedValue: (CstLeaf) | undefined;
+  let i = 0;
+  if (!(isTok(c, i, "Name"))) return null;
+  name = c[i] as CstLeaf;
+  i++;
+  {
+    const _t0 = i; let _t1 = true;
+    _b2: {
+      if (!isLit(c, i, src, "=", "$punct")) { _t1 = false; break _b2; }
+      i++;
+      {
+        let _t3 = false;
+        if (!_t3) {
+          const _t4 = i; let _t5 = true;
+          _b6: {
+            if (!(isTok(c, i, "AttrValue"))) { _t5 = false; break _b6; }
+            attrValue = c[i] as CstLeaf;
+            i++;
+          }
+          if (_t5) _t3 = true; else i = _t4;
+        }
+        if (!_t3) {
+          const _t7 = i; let _t8 = true;
+          _b9: {
+            if (!(isTok(c, i, "Name"))) { _t8 = false; break _b9; }
+            name2 = c[i] as CstLeaf;
+            i++;
+          }
+          if (_t8) _t3 = true; else i = _t7;
+        }
+        if (!_t3) {
+          const _t10 = i; let _t11 = true;
+          _b12: {
+            if (!(isTok(c, i, "UnquotedValue"))) { _t11 = false; break _b12; }
+            unquotedValue = c[i] as CstLeaf;
+            i++;
+          }
+          if (_t11) _t3 = true; else i = _t10;
+        }
+        if (!_t3) { _t1 = false; break _b2; }
+      }
+    }
+    if (!_t1) i = _t0;
+  }
+  if (i !== c.length) return null;
+  return { arm: "name", name: name!, attrValue, name2, unquotedValue };
+}
+
+export function matchAttr(n: AttrNode, src: string): AttrMatch {
+  const c = n.children;
+  { const m = _Attr$name(c, src); if (m !== null) return m; }
+  throw new Error("matchAttr: no arm matches" + ' @' + n.offset);
+}
+
+export type NodeMatch =
+  | { arm: "element"; element: ElementNode }
+  | { arm: "comment"; comment: CstLeaf }
+  | { arm: "rawText"; rawText: CstLeaf }
+  | { arm: "text"; text: CstLeaf };
+
+function _Node$element(c: readonly CstChild[], src: string): NodeMatch | null {
+  let element: (ElementNode) | undefined;
+  let i = 0;
+  if (!isNodeOf(c, i, "Element")) return null;
+  element = c[i] as ElementNode;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "element", element: element! };
+}
+
+function _Node$comment(c: readonly CstChild[], src: string): NodeMatch | null {
+  let comment: (CstLeaf) | undefined;
+  let i = 0;
+  if (!(isTok(c, i, "Comment"))) return null;
+  comment = c[i] as CstLeaf;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "comment", comment: comment! };
+}
+
+function _Node$rawText(c: readonly CstChild[], src: string): NodeMatch | null {
+  let rawText: (CstLeaf) | undefined;
+  let i = 0;
+  if (!(isTok(c, i, "RawText"))) return null;
+  rawText = c[i] as CstLeaf;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "rawText", rawText: rawText! };
+}
+
+function _Node$text(c: readonly CstChild[], src: string): NodeMatch | null {
+  let text: (CstLeaf) | undefined;
+  let i = 0;
+  if (!(isTok(c, i, "Text"))) return null;
+  text = c[i] as CstLeaf;
+  i++;
+  if (i !== c.length) return null;
+  return { arm: "text", text: text! };
+}
+
+export function matchNode(n: NodeNode, src: string): NodeMatch {
+  const c = n.children;
+  { const m = _Node$element(c, src); if (m !== null) return m; }
+  { const m = _Node$comment(c, src); if (m !== null) return m; }
+  { const m = _Node$rawText(c, src); if (m !== null) return m; }
+  { const m = _Node$text(c, src); if (m !== null) return m; }
+  throw new Error("matchNode: no arm matches" + ' @' + n.offset);
+}
+
+export type DocumentMatch =
+  | { arm: "element"; element: (ElementNode)[]; comment: (CstLeaf)[]; text: (CstLeaf)[] };
+
+function _Document$element(c: readonly CstChild[], src: string): DocumentMatch | null {
+  const element: (ElementNode)[] = [];
+  const comment: (CstLeaf)[] = [];
+  const text: (CstLeaf)[] = [];
+  let i = 0;
+  for (;;) {
+    const _t0 = i; let _t1 = true;
+    _b2: {
+      {
+        let _t3 = false;
+        if (!_t3) {
+          const _t4 = i; let _t5 = true;
+          _b6: {
+            if (!isNodeOf(c, i, "Element")) { _t5 = false; break _b6; }
+            element.push(c[i] as ElementNode);
+            i++;
+          }
+          if (_t5) _t3 = true; else i = _t4;
+        }
+        if (!_t3) {
+          const _t7 = i; let _t8 = true;
+          _b9: {
+            if (!(isTok(c, i, "Comment"))) { _t8 = false; break _b9; }
+            comment.push(c[i] as CstLeaf);
+            i++;
+          }
+          if (_t8) _t3 = true; else i = _t7;
+        }
+        if (!_t3) {
+          const _t10 = i; let _t11 = true;
+          _b12: {
+            if (!(isTok(c, i, "Text"))) { _t11 = false; break _b12; }
+            text.push(c[i] as CstLeaf);
+            i++;
+          }
+          if (_t11) _t3 = true; else i = _t10;
+        }
+        if (!_t3) { _t1 = false; break _b2; }
+      }
+    }
+    if (!_t1) { i = _t0; break; }
+    if (i === _t0) break;
+  }
+  if (i !== c.length) return null;
+  return { arm: "element", element, comment, text };
+}
+
+export function matchDocument(n: DocumentNode, src: string): DocumentMatch {
+  const c = n.children;
+  { const m = _Document$element(c, src); if (m !== null) return m; }
+  throw new Error("matchDocument: no arm matches" + ' @' + n.offset);
+}
+
+/** rule name → its matcher (generic walking; the totality gate uses this). */
+export const MATCHERS: Record<string, (n: never, src: string) => { arm: string }> = {
+  "Element": matchElement,
+  "Attr": matchAttr,
+  "Node": matchNode,
+  "Document": matchDocument,
+};