Add CI to auto-refresh the README highlighter bench

New workflow .github/workflows/readme-bench.yml regenerates the head-to-head
block in README.md and commits it back to master whenever the grammar, bench,
scope-roles, or issue-cases change (or on manual dispatch).

- Deterministic: grades the adversarial bug-ledger (all in-repo) against a
  PINNED official grammar fetched from a vscode tag, so the block is
  byte-reproducible in CI. The parser-conformance corpus (a heavy,
  version-sensitive TS clone) is left out of the auto-block and kept as a
  hand-written balance note beside it.
- No loop: the bot's README-only commit isn't in the trigger paths, and the
  commit carries [skip ci] as a backstop, so it can't re-trigger the workflow.
- bench: --write-readme now respects --corpus; bench:readme is adversarial-only.

The committed block was regenerated from the pinned grammar (vscode 1.96.0 —
identical numbers to a local VS Code), so the first CI run is a no-op.

Author: johnsoncodehk

.github/workflows/readme-bench.yml

@@ -0,0 +1,72 @@
+name: README bench
+
+# Auto-refreshes the highlighter head-to-head block in README.md (between the
+# <!-- bench:start --> / <!-- bench:end --> markers) and commits it back to master.
+#
+# Determinism: the block is the ADVERSARIAL corpus only (the documented-bug ledger
+# in test/issue-cases.ts, all in-repo) graded against a PINNED official grammar
+# fetched below — so the same inputs always yield the same block. The
+# parser-conformance corpus (a heavy, version-sensitive TypeScript clone) is left
+# out on purpose; that axis lives in a hand-written note next to the block.
+#
+# No infinite loop: the bot commit touches only README.md, which is NOT in the
+# paths filter below, so it cannot re-trigger this workflow ([skip ci] is a backstop).
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'examples/typescript.tmLanguage.json'
+      - 'test/highlight-bench.ts'
+      - 'test/scope-roles.ts'
+      - 'test/issue-cases.ts'
+      - '.github/workflows/readme-bench.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: readme-bench-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Pinned VS Code tag whose bundled TypeScript grammar is the "official" baseline.
+  # Bump this deliberately to re-baseline against a newer official grammar.
+  OFFICIAL_TM_TAG: '1.96.0'
+
+jobs:
+  update-readme:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Node 24+ runs the .ts sources directly (native type stripping) — no build, no tsx.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - run: npm ci
+
+      - name: Fetch pinned official TypeScript grammar
+        run: |
+          curl -fsSL \
+            "https://raw.githubusercontent.com/microsoft/vscode/${OFFICIAL_TM_TAG}/extensions/typescript-basics/syntaxes/TypeScript.tmLanguage.json" \
+            -o "${RUNNER_TEMP}/official-ts.tmLanguage.json"
+
+      - name: Regenerate the README bench block
+        env:
+          MONOGRAM_OFFICIAL_TM: ${{ runner.temp }}/official-ts.tmLanguage.json
+        run: npm run bench:readme
+
+      - name: Commit the refreshed block (if it changed)
+        run: |
+          if git diff --quiet -- README.md; then
+            echo "README bench block already current — nothing to commit."
+            exit 0
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          git commit -m "chore: refresh README highlighter bench results [skip ci]"
+          git push

README.md

@@ -78,11 +78,14 @@ Independently-verified **Monogram fixes** — official structurally wrong, Monog
 | corpus | Official | Monogram |
 |---|---|---|
 | documented bug ledger (534 tokens) | 83.5% | 94.2% |
-| TS parser conformance (15856 tokens) | 99.0% | 96.3% |
+
+<sub>Parser-conformance row omitted — run with the TS corpus cloned to `/tmp/ts-repo` to include it.</sub>
 
 <sub>Regenerate: `node test/highlight-bench.ts --write-readme`. Neutral oracle + frozen scope→role table: [`test/scope-roles.ts`](test/scope-roles.ts).</sub>
 <!-- bench:end -->
 
+> **The other side of the ledger (honesty check).** On the *broad* TS parser-conformance corpus — not just the documented bugs — raw token-role accuracy flips: the official grammar's decade of hardening leads (~99% vs ~96%). Monogram's gap there is specific backlog (Unicode identifiers, qualified type names), **not** the ambiguity class above. Clone the TS corpus to `/tmp/ts-repo` and run `node test/highlight-bench.ts` to see both corpora.
+
 ## What you get
 
 From one grammar definition (a small TypeScript combinator API), three outputs are **fully functional**:

package.json

@@ -7,7 +7,7 @@
     "test": "node test/sanity-check.ts",
     "conformance": "node test/run-conformance.ts",
     "bench": "node test/highlight-bench.ts",
-    "bench:readme": "node test/highlight-bench.ts --write-readme"
+    "bench:readme": "node test/highlight-bench.ts --corpus adversarial --write-readme"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

test/highlight-bench.ts

@@ -647,7 +647,7 @@ async function allTs(dir: string): Promise<string[]> {
 
 // ── run selected corpora ──────────────────────────────────────────────────────
 const WRITE_README = argv.includes('--write-readme');
-const WHICH = WRITE_README ? 'both' : (getFlag('--corpus') ?? 'both');
+const WHICH = getFlag('--corpus') ?? 'both'; // --write-readme respects --corpus (CI uses adversarial = deterministic, no TS clone)
 
 let parserSummary: BenchSummary | null = null;
 let advSummary: BenchSummary | null = null;