docs: auto-generate the per-grammar alignment table in the README Status section

test/coverage-table.ts runs each src-coverage + scope-gap adapter, parses their ##COV## / ##SCOPEGAP## summary lines, and writes a compact per-grammar alignment table into the README Status section (between <!-- coverage:start/end -->). Both harnesses now emit a machine-readable summary line. Regenerate with: node test/coverage-table.ts --write (needs the corpora + a VS Code install for the official grammars; TS/JS use deterministic stride samples).

Replaces the standalone alignment section — the numbers now live in Status next to the per-language descriptions. Fixed a ReferenceError (nFiles -> results.length) in the src-coverage summary line.

Author: johnsoncodehk

README.md

@@ -11,6 +11,19 @@ Write a language's grammar **once**, as an executable definition. Monogram runs
 - **HTML** ([`html.ts`](html.ts)) — the engine reaching *past token streams into markup*; ~95 lines, validated against [`parse5`](https://github.com/inikulin/parse5).
 - **Vue** ([`vue.ts`](vue.ts)) — a dialect of `html.ts`: SFC blocks that embed Monogram's own TS/JS/CSS, plus directives and `{{ }}` interpolation.
 
+<!-- coverage:start -->
+Per-grammar alignment vs the **official parser** as the neutral oracle (`node test/coverage-table.ts --write`). *Parser* = Monogram's parser vs the official parser: `branch` = source-coverage-anchored branch alignment, `agree` = bidirectional accept/reject (tree-equality for structural oracles) — `test/src-coverage.ts`. *Highlighter* = Monogram's derived TextMate grammar vs the official one, both graded against the parser's token roles — `test/scope-gap.ts`, the [vscode#203212](https://github.com/microsoft/vscode/issues/203212) comparison.
+
+| Grammar | Parser (branch · agree) | Highlighter — Monogram vs official |
+|---|---|---|
+| TypeScript | 97.7% · 97.1% | 99.3% vs 99.0% |
+| JavaScript | 97.3% · 92.2% | — |
+| JSX | 100.0% · 97.1% | — |
+| TSX | 99.4% · 96.7% | — |
+| HTML | 84.3% · 77.9% | 100.0% vs 97.6% |
+| YAML | 83.0% · 63.1% | 46.5% vs 89.7% |
+<!-- coverage:end -->
+
 ## Quick start
 
 Requires Node 24+ (runs `.ts` directly — no build step, no `tsx`).
@@ -175,6 +188,7 @@ _Each hand-written **official** grammar vs Monogram's **derived** one, on the bu
 
 <sub>A sampled ledger of real tracker issues, not an exhaustive audit. Run `npm run bench:issues` to regenerate (needs the official grammars: VS Code's installed TS/JS/HTML, and the Vue fixtures — see [`test/vue-bench.ts`](test/vue-bench.ts)). Sources: [`test/issue-cases.ts`](test/issue-cases.ts), [`test/html-issue-cases.ts`](test/html-issue-cases.ts), [`test/vue-issue-cases.ts`](test/vue-issue-cases.ts).</sub>
 
+
 ### The ceiling — and the bar for claiming it
 
 Deriving from a proven parser wins the disambiguation that is *TextMate-expressible but infeasible to hand-write* — regex-vs-division, generic-vs-comparison, whitespace-fragile multiline generics — the **only-Monogram** column. The **both-miss** cases are ones neither grammar gets *today* — not, by default, ones TextMate *can't*.

test/coverage-table.ts

@@ -0,0 +1,68 @@
+// coverage-table.ts — regenerate the README per-language alignment tables. Runs each
+// src-coverage + scope-gap adapter as a subprocess, parses its ##COV## / ##SCOPEGAP## summary
+// line, and writes two tables into the README between <!-- coverage:start --> / <!-- coverage:end -->.
+//   node test/coverage-table.ts            # print the tables (don't touch the README)
+//   node test/coverage-table.ts --write    # rewrite the README region
+// Needs the corpora the adapters use (/tmp/ts-repo, /tmp/test262, /tmp/yaml-test-suite) and a VS
+// Code install for the official grammars; an adapter whose inputs are missing renders as "—".
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const WRITE = process.argv.includes('--write');
+
+function runAdapter(script: string, args: string[], marker: string): any | null {
+  try {
+    const out = execFileSync('node', [script, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 128 * 1024 * 1024 });
+    const line = out.split('\n').find((l) => l.startsWith(marker));
+    return line ? JSON.parse(line.slice(marker.length).trim()) : null;
+  } catch { return null; }
+}
+
+// TS/JS use deterministic stride subsets for speed; the rest run their full corpus.
+const COV = [
+  { lang: 'TypeScript', script: 'test/src-coverage-ts.ts', args: ['1500'] },
+  { lang: 'JavaScript', script: 'test/src-coverage-js.ts', args: ['800'] },
+  { lang: 'JSX', script: 'test/src-coverage-jsx.ts', args: [] },
+  { lang: 'TSX', script: 'test/src-coverage-tsx.ts', args: [] },
+  { lang: 'HTML', script: 'test/src-coverage-html.ts', args: [] },
+  { lang: 'YAML', script: 'test/src-coverage-yaml.ts', args: [] },
+];
+const GAP = [
+  { lang: 'TypeScript', script: 'test/scope-gap-ts.ts', args: ['800'] },
+  { lang: 'HTML', script: 'test/scope-gap-html.ts', args: [] },
+  { lang: 'YAML', script: 'test/scope-gap-yaml.ts', args: [] },
+];
+
+const pct = (v: number | null | undefined) => (v == null ? '—' : v.toFixed(1) + '%');
+
+console.error('Running src-coverage adapters…');
+const covRows = COV.map((a) => { console.error('  ' + a.lang); return { lang: a.lang, r: runAdapter(a.script, a.args, '##COV##') }; });
+console.error('Running scope-gap adapters…');
+const gapRows = GAP.map((a) => { console.error('  ' + a.lang); return { lang: a.lang, r: runAdapter(a.script, a.args, '##SCOPEGAP##') }; });
+
+const covBy = new Map(covRows.map((x) => [x.lang, x.r]));
+const gapBy = new Map(gapRows.map((x) => [x.lang, x.r]));
+const LANGS = ['TypeScript', 'JavaScript', 'JSX', 'TSX', 'HTML', 'YAML'];
+
+let md = '';
+md += "Per-grammar alignment vs the **official parser** as the neutral oracle (`node test/coverage-table.ts --write`). *Parser* = Monogram's parser vs the official parser: `branch` = source-coverage-anchored branch alignment, `agree` = bidirectional accept/reject (tree-equality for structural oracles) — `test/src-coverage.ts`. *Highlighter* = Monogram's derived TextMate grammar vs the official one, both graded against the parser's token roles — `test/scope-gap.ts`, the [vscode#203212](https://github.com/microsoft/vscode/issues/203212) comparison.\n\n";
+md += '| Grammar | Parser (branch · agree) | Highlighter — Monogram vs official |\n|---|---|---|\n';
+for (const lang of LANGS) {
+  const c = covBy.get(lang), g = gapBy.get(lang);
+  const parser = c ? `${pct(c.denoms?.[c.denoms.length - 1]?.alignment)} · ${pct(c.agreePct)}` : '—';
+  const hl = g ? `${pct(g.monogramPct)} vs ${pct(g.officialPct)}` : '—';
+  md += `| ${lang} | ${parser} | ${hl} |\n`;
+}
+
+const block = '<!-- coverage:start -->\n' + md + '<!-- coverage:end -->';
+if (!WRITE) { console.log('\n' + md); process.exit(0); }
+
+const README = 'README.md';
+let txt = readFileSync(README, 'utf8');
+if (!/<!-- coverage:start -->[\s\S]*?<!-- coverage:end -->/.test(txt)) {
+  console.error('No <!-- coverage:start/end --> markers in README.md — add them first.');
+  process.exit(1);
+}
+txt = txt.replace(/<!-- coverage:start -->[\s\S]*?<!-- coverage:end -->/, () => block);
+writeFileSync(README, txt);
+console.error('✓ README coverage region updated.');

test/scope-gap.ts

@@ -153,5 +153,11 @@ export async function run(adapter: ScopeGapAdapter): Promise<void> {
     console.log(`\n  only-official-correct tokens (Monogram wrong) — ${onlyOff.length} shown:`);
     for (const x of onlyOff.slice(0, 12)) console.log(`    «${x.text.slice(0, 18)}» ${x.role}: official «${x.o}» → monogram «${x.m}»`);
   }
+  // Machine-readable summary for the README coverage-table generator (test/coverage-table.ts).
+  console.log('##SCOPEGAP## ' + JSON.stringify({
+    name: adapter.name, official: adapter.officialPath.replace(/^.*\//, ''), tokens: tally.total,
+    officialPct: tally.total ? (100 * tally.oCorrect) / tally.total : null,
+    monogramPct: tally.total ? (100 * tally.mCorrect) / tally.total : null,
+  }));
   console.log('\nDone.');
 }

test/src-coverage.ts

@@ -157,6 +157,7 @@ export async function run(adapter: Adapter): Promise<void> {
   adapter.renderHeader?.(results, corpus);
 
   const ledgerTop = adapter.ledgerTop ?? 15;
+  const denomSummary: { label: string; alignment: number; completeness: number }[] = [];
   for (const den of adapter.denominators) {
     let totalSeen = 0, reachable = 0, agreed = 0, disagreed = 0;
     const dis: BranchState[] = [];
@@ -171,6 +172,7 @@ export async function run(adapter: Adapter): Promise<void> {
     const uncovered = totalSeen - reachable;
     const alignment = reachable ? (agreed / reachable) * 100 : 0;
     const completeness = totalSeen ? (reachable / totalSeen) * 100 : 0;
+    denomSummary.push({ label: den.label, alignment, completeness });
     console.log(`\n────── denominator: ${den.label} ──────`);
     console.log(`  total branches seen (reachable+uncovered) : ${totalSeen}`);
     console.log(`  reachable (hit >=1 file)                  : ${reachable}`);
@@ -194,5 +196,11 @@ export async function run(adapter: Adapter): Promise<void> {
   }
 
   adapter.renderFooter?.(results, corpus);
+  // Machine-readable summary line for the README coverage-table generator (test/coverage-table.ts).
+  console.log('##COV## ' + JSON.stringify({
+    name: adapter.name, oracle: adapter.oracle, files: results.length,
+    agreePct: results.length ? (100 * agreeCount) / results.length : null,
+    denoms: denomSummary,
+  }));
   console.log('\nDone.');
 }