parseman 0.46.0 → 0.47.0

package/src/analysis/choice-cost-gate.ts

@@ -0,0 +1,359 @@
+/**
+ * CHOICE COST — the policy layer.
+ * ===============================
+ *
+ * Analysis says what the grammar costs. This says which of those numbers fail a build.
+ * They are separate because they have different consumers and different lifetimes: a
+ * developer wants the ranked list on every run, CI wants one bit, and the threshold
+ * that produces that bit is a decision the owner makes once and writes down.
+ *
+ * This module is PURE — it takes a report and a baseline and returns a verdict. It
+ * reads no files, spawns nothing, and prints nothing, so it is testable without a
+ * fixture checkout and cannot be the reason a gate is flaky.
+ *
+ * THE BASELINE IS ABSOLUTE, NOT DIFFERENTIAL
+ * ------------------------------------------
+ * Gating each commit against its parent lets +2% per commit land forever: every
+ * individual step is under tolerance and the total is unbounded. So the committed
+ * baseline records the ACTUAL byte counts, and drift is measured against those
+ * numbers, not against yesterday's.
+ *
+ * A baseline is committed DATA, reviewed like any other diff. Nothing here writes one.
+ * Rebaselining is a deliberate act with a reviewable artifact and owner sign-off; there
+ * is no automatic refresh, because a gate that rebaselines itself is a gate that
+ * records regressions rather than catching them.
+ *
+ * AND IT IS TWO-SIDED — A WIN MUST BE BANKED
+ * ------------------------------------------
+ * Growth past the committed number fails, and so does an unbanked IMPROVEMENT. This is
+ * the half usually left to a comment asking a human politely, and it is the half that
+ * rots: `bench/grammar-density/config.json` and `bench/workloads/config.json` each
+ * carried exactly such a comment and sat unbumped for TEN releases. If a reorder takes
+ * a site from 7,846 wasted bytes to 2,000 and the baseline does not move with it, 5,846
+ * bytes of fresh headroom silently become budget for the next regression — and the gate
+ * that was supposed to catch that regression reads green through the whole of it.
+ *
+ * So the committed number is a BAND, not a floor: leaving it in either direction fails,
+ * and only the remedy differs. Raising a number needs owner sign-off; lowering one is
+ * mandatory. Both are the same one-line rebaseline and the same reviewable diff.
+ *
+ * `bench/size-guard.ts` is the shape this follows — it earned the tightness in 0.45 by
+ * catching +0.14% moves a 1% tolerance would have waved through.
+ *
+ * A BASELINE CANNOT LAUNDER A CEILING
+ * -----------------------------------
+ * If a ceiling is configured, a baseline that records a number ABOVE it is rejected as
+ * invalid rather than honoured. Otherwise the ceiling would be waivable by rebaselining,
+ * which makes it a suggestion. (`bench/size-guard.ts` validates its own baseline for
+ * exactly this reason; this follows it.)
+ *
+ * FAILS CLOSED
+ * ------------
+ * Every way of not having measured is a failure, never a pass: a missing baseline, a
+ * baseline of the wrong shape, an empty baseline, a report over zero corpus files, a
+ * report where no site was instrumentable, a report whose grammar walk was incomplete
+ * (`unresolvedRoots` non-empty), a baselined key that no longer exists, and a measured
+ * key with no baseline entry. This repo already contains the alternative — `ratio:
+ * ordered.length === 0 ? 1` in src/coverage.ts reports 100% covered when nothing was
+ * analysable — and the whole point of a gate is to not be that.
+ */
+
+import type { WastedWorkReport } from './choice-cost.ts'
+
+export type WastedWorkBaseline = {
+  readonly schema: 'parseman.wasted-work-baseline/1'
+  /** Informational: which revision produced the numbers. Never compared. */
+  gitRev: string
+  /** Informational, `YYYY-MM-DD`. Never compared — comparing it would make the
+   *  verdict depend on the clock. */
+  updatedAt: string
+  /**
+   * Absolute per-corpus totals, keyed by corpus id.
+   *
+   * `totalWastedBytes` is the INTERPRETED column, and that is deliberate even though
+   * `WastedWorkReport` names `totalGatedWastedBytes` as the headline. For BYTES the two
+   * are the same number, structurally: the modelled first-char guard is derived from the
+   * arm's first SET, which over-approximates what the arm can start with, so wherever the
+   * guard rejects, the arm's own leading terminal would have rejected at the same position
+   * having consumed nothing. Measured over four dialect grammars, zero arms differ (see the
+   * header of `choice-cost.ts`). What the guard removes is ATTEMPTS, not rescanned bytes —
+   * so `gatedAttempts`, `gatedFailures` and the inversion ranking DO read the gated columns,
+   * and only the byte totals are recorded from the interpreted one, where it is additionally
+   * the conservative UPPER bound of the two.
+   *
+   * That identity is not enforced anywhere it could be relied on silently: `checkWastedWork`
+   * judges the compiled column against this same band wherever the two columns part, so a
+   * divergence goes red instead of unnoticed.
+   */
+  totals: Record<string, { corpusBytes: number; totalWastedBytes: number; instrumentedSites: number }>
+  /** Absolute per-site wasted bytes, keyed by `<corpus>::<siteKey>`. Interpreted column,
+   *  for the reason given on `totals` above. */
+  sites: Record<string, number>
+}
+
+export type WastedWorkPolicy = {
+  /**
+   * Maximum wasted bytes per corpus byte. A hard ceiling no rebaseline can waive.
+   * Omit for drift-only gating; a project should set it once it knows its own number.
+   */
+  ceilingRatio?: number
+  /**
+   * Half-width of the band around each committed number, as a percentage. Default 1.
+   *
+   * SYMMETRIC: a measurement more than this ABOVE its baseline is a regression, and a
+   * measurement more than this BELOW it is an unbanked win. Both fail.
+   *
+   * This is not a noise allowance — the metric is a deterministic count of input bytes,
+   * so its noise floor is exactly zero and any non-zero value here is pure headroom.
+   * It exists only so incidental one-byte churn does not thrash the baseline in both
+   * directions. Set it as near zero as the corpus permits; `bench/choice-cost-guard.ts`
+   * runs at 0.1, matching `bench/size-guard.ts`'s ratchet slack.
+   */
+  driftTolerancePct?: number
+  /**
+   * Fail on an ordering inversion — an arm that failed every one of its attempts while
+   * a later arm at the same site matched. Off by default: on an existing grammar this
+   * fires immediately, and a gate that is red on arrival for a pre-existing condition
+   * gets disabled rather than fixed. Turn it on once the backlog is empty, to keep it
+   * empty.
+   */
+  failOnInversions?: boolean
+}
+
+export type GateBreach = {
+  /** `drift` is growth past the band; `shrank` is an improvement that was not banked.
+   *  Both are failures, and the `detail` says which remedy applies. */
+  kind: 'ceiling' | 'drift' | 'shrank' | 'unbaselined' | 'stale' | 'inversion' | 'unmeasurable' | 'invalid-baseline'
+  key: string
+  /** One line. Says what happened and what number to look at — never advice. */
+  detail: string
+}
+
+export type GateVerdict = {
+  readonly schema: 'parseman.wasted-work-verdict/1'
+  ok: boolean
+  /** Ascending by (kind, key). Deterministic, so a verdict is diffable. */
+  breaches: readonly GateBreach[]
+  checkedCorpora: number
+  checkedSites: number
+}
+
+const KIND_ORDER: GateBreach['kind'][] = [
+  'invalid-baseline', 'unmeasurable', 'ceiling', 'drift', 'shrank', 'inversion', 'unbaselined', 'stale',
+]
+
+const pct = (actual: number, base: number): number => base === 0 ? (actual === 0 ? 0 : Infinity) : (actual / base - 1) * 100
+
+/**
+ * Judge one or more measured corpora against a committed baseline.
+ *
+ * `reports` is keyed by corpus id — a grammar is usually gated over more than one body
+ * of input, and a single blended number would let a regression on one hide behind an
+ * improvement on another.
+ */
+export function checkWastedWork(
+  reports: Readonly<Record<string, WastedWorkReport>>,
+  baseline: unknown,
+  policy: WastedWorkPolicy = {},
+): GateVerdict {
+  const breaches: GateBreach[] = []
+  const tolerance = policy.driftTolerancePct ?? 1
+
+  const add = (kind: GateBreach['kind'], key: string, detail: string): void => { breaches.push({ kind, key, detail }) }
+
+  const finish = (checkedCorpora: number, checkedSites: number): GateVerdict => {
+    breaches.sort((a, b) =>
+      KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind)
+      || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    return {
+      schema: 'parseman.wasted-work-verdict/1',
+      ok: breaches.length === 0,
+      breaches,
+      checkedCorpora,
+      checkedSites,
+    }
+  }
+
+  // ── the baseline must be a baseline ───────────────────────────────────────
+  const b = baseline as Partial<WastedWorkBaseline> | null | undefined
+  if (b === null || b === undefined || typeof b !== 'object') {
+    add('invalid-baseline', '<baseline>', 'no baseline supplied — a gate with no baseline measures nothing, and passing here is how a budget stops being enforced')
+    return finish(0, 0)
+  }
+  if (b.schema !== 'parseman.wasted-work-baseline/1') {
+    add('invalid-baseline', '<baseline>', `baseline schema is ${JSON.stringify(b.schema)}, expected "parseman.wasted-work-baseline/1"`)
+    return finish(0, 0)
+  }
+  // `typeof null === 'object'`, so a `"totals": null` would pass a bare `typeof` test
+  // and reach `Object.keys` below as an uncaught TypeError. A baseline of the wrong
+  // shape is a documented `invalid-baseline` breach, not a crash.
+  const isRecord = (v: unknown): v is Record<string, unknown> =>
+    typeof v === 'object' && v !== null && !Array.isArray(v)
+  if (!isRecord(b.totals) || !isRecord(b.sites)) {
+    add('invalid-baseline', '<baseline>', 'baseline `totals` or `sites` is missing or is not an object')
+    return finish(0, 0)
+  }
+  if (Object.keys(b.totals).length === 0) {
+    add('invalid-baseline', '<baseline>', 'baseline records ZERO corpora')
+    return finish(0, 0)
+  }
+
+  // EVERY recorded value must be a finite number, checked before any of them is read.
+  // `baseline` is `unknown` — parsed JSON off disk — and a non-numeric value does not
+  // announce itself at the comparison: `pct` returns NaN, and `NaN > tolerance` and
+  // `NaN < -tolerance` are BOTH false, so the entry yields no breach and the gate
+  // reports a pass over a number it never compared. That is the fail-open this module
+  // exists to not be, and it is silent, so it is caught at the shape check instead.
+  const finite = (v: unknown): boolean => typeof v === 'number' && Number.isFinite(v)
+  for (const [id, t] of Object.entries(b.totals).sort(([x], [y]) => (x < y ? -1 : 1))) {
+    if (!isRecord(t) || !finite(t.corpusBytes) || !finite(t.totalWastedBytes)) {
+      add('invalid-baseline', id, 'baseline entry has no finite numeric `corpusBytes` / `totalWastedBytes` — the comparison against it would silently produce NaN and no breach')
+    }
+  }
+  for (const [key, v] of Object.entries(b.sites).sort(([x], [y]) => (x < y ? -1 : 1))) {
+    if (!finite(v)) add('invalid-baseline', key, 'baseline site value is not a finite number — the comparison against it would silently produce NaN and no breach')
+  }
+  if (breaches.length > 0) return finish(0, 0)
+  if (policy.ceilingRatio !== undefined) {
+    for (const [id, t] of Object.entries(b.totals).sort(([x], [y]) => (x < y ? -1 : 1))) {
+      if (t.corpusBytes > 0 && t.totalWastedBytes / t.corpusBytes > policy.ceilingRatio) {
+        add('invalid-baseline', id,
+          `baseline records ${t.totalWastedBytes} wasted / ${t.corpusBytes} corpus bytes = `
+          + `${(t.totalWastedBytes / t.corpusBytes).toFixed(3)}x, above the ${policy.ceilingRatio}x ceiling — `
+          + 'a rebaseline cannot accept an over-ceiling number')
+      }
+    }
+    if (breaches.length > 0) return finish(0, 0)
+  }
+
+  if (Object.keys(reports).length === 0) {
+    add('unmeasurable', '<reports>', 'no corpus was measured — refusing to report a pass on an empty measurement')
+    return finish(0, 0)
+  }
+
+  let checkedSites = 0
+
+  for (const id of Object.keys(reports).sort()) {
+    const r = reports[id]!
+
+    // ── could this report have measured anything? ───────────────────────────
+    if (r.corpusFiles === 0) { add('unmeasurable', id, 'report covers ZERO corpus files'); continue }
+    if (r.instrumentedSites === 0) { add('unmeasurable', id, 'report instrumented ZERO choice sites — the total below would be zero for a reason unrelated to the grammar'); continue }
+    if (r.unresolvedRoots.length > 0) {
+      add('unmeasurable', id,
+        `${r.unresolvedRoots.length} rule(s) could not be resolved and were NOT walked `
+        + `(${r.unresolvedRoots.slice(0, 4).join(', ')}${r.unresolvedRoots.length > 4 ? ', …' : ''}) — `
+        + 'the total is a lower bound over an unknown fraction of the grammar')
+      continue
+    }
+
+    const base = b.totals[id]
+    if (base === undefined) {
+      add('unbaselined', id, `measured but absent from the baseline (${r.totalWastedBytes} wasted bytes over ${r.corpusBytes})`)
+      continue
+    }
+
+    if (policy.ceilingRatio !== undefined && r.corpusBytes > 0) {
+      const ratio = r.totalWastedBytes / r.corpusBytes
+      if (ratio > policy.ceilingRatio) {
+        add('ceiling', id, `${r.totalWastedBytes} wasted / ${r.corpusBytes} corpus bytes = ${ratio.toFixed(3)}x, over the ${policy.ceilingRatio}x ceiling`)
+      }
+    }
+
+    // The corpus itself is part of the measurement. If it changed, the totals are
+    // not comparable and a "no drift" verdict would be meaningless.
+    if (r.corpusBytes !== base.corpusBytes) {
+      add('unmeasurable', id, `corpus changed: baseline ${base.corpusBytes} bytes, measured ${r.corpusBytes} — totals are not comparable until the baseline is refreshed`)
+      continue
+    }
+
+    // Two-sided. Growth is a regression; an unbanked win is next quarter's regression
+    // budget. Same band, same rebaseline, different sentence.
+    const d = pct(r.totalWastedBytes, base.totalWastedBytes)
+    if (d > tolerance) {
+      add('drift', id, `total wasted ${base.totalWastedBytes} -> ${r.totalWastedBytes} bytes (${d >= 0 ? '+' : ''}${d.toFixed(2)}%, band ±${tolerance}%)`)
+    } else if (d < -tolerance) {
+      add('shrank', id, `total wasted ${base.totalWastedBytes} -> ${r.totalWastedBytes} bytes (${d.toFixed(2)}%, band ±${tolerance}%) — BANK THE WIN: rebaseline so the ${base.totalWastedBytes - r.totalWastedBytes} bytes you just saved cannot become headroom for the next regression`)
+    }
+
+    // AND THE COMPILED COLUMN IS HELD TO THE SAME BAND. See `WastedWorkBaseline` for
+    // why the INTERPRETED column is the one recorded. While the two agree — which is
+    // structural, not a property of these corpora — this adds nothing, so it is only
+    // evaluated where they part, and there it says so rather than judging one column
+    // and reporting the other.
+    if (r.totalGatedWastedBytes !== r.totalWastedBytes) {
+      const dg = pct(r.totalGatedWastedBytes, base.totalWastedBytes)
+      if (dg > tolerance) {
+        add('drift', id, `compiled-model total wasted ${base.totalWastedBytes} -> ${r.totalGatedWastedBytes} bytes (${dg >= 0 ? '+' : ''}${dg.toFixed(2)}%, band ±${tolerance}%) — the compiled and interpreted columns have PARTED (${r.totalGatedWastedBytes} vs ${r.totalWastedBytes}); the baseline records the interpreted one`)
+      } else if (dg < -tolerance) {
+        add('shrank', id, `compiled-model total wasted ${base.totalWastedBytes} -> ${r.totalGatedWastedBytes} bytes (${dg.toFixed(2)}%, band ±${tolerance}%) — the compiled and interpreted columns have PARTED (${r.totalGatedWastedBytes} vs ${r.totalWastedBytes}); the baseline records the interpreted one`)
+      }
+    }
+
+    for (const s of r.sites) {
+      const key = `${id}::${s.siteKey}`
+      const bs = b.sites[key]
+      if (bs === undefined) {
+        if (s.wastedBytes > 0) add('unbaselined', key, `site measured ${s.wastedBytes} wasted bytes but has no baseline entry`)
+        continue
+      }
+      checkedSites++
+      const sd = pct(s.wastedBytes, bs)
+      if (sd > tolerance) add('drift', key, `${bs} -> ${s.wastedBytes} bytes (${sd >= 0 ? '+' : ''}${sd.toFixed(2)}%, band ±${tolerance}%)`)
+      else if (sd < -tolerance) add('shrank', key, `${bs} -> ${s.wastedBytes} bytes (${sd.toFixed(2)}%, band ±${tolerance}%) — BANK THE WIN: rebaseline, or this site's ${bs - s.wastedBytes} recovered bytes become budget`)
+
+      if (s.gatedWastedBytes !== s.wastedBytes) {
+        const sg = pct(s.gatedWastedBytes, bs)
+        if (sg > tolerance) add('drift', key, `compiled-model ${bs} -> ${s.gatedWastedBytes} bytes (${sg >= 0 ? '+' : ''}${sg.toFixed(2)}%, band ±${tolerance}%) — columns PARTED (${s.gatedWastedBytes} vs ${s.wastedBytes})`)
+        else if (sg < -tolerance) add('shrank', key, `compiled-model ${bs} -> ${s.gatedWastedBytes} bytes (${sg.toFixed(2)}%, band ±${tolerance}%) — columns PARTED (${s.gatedWastedBytes} vs ${s.wastedBytes})`)
+      }
+    }
+
+    if (policy.failOnInversions === true) {
+      for (const inv of r.inversions) {
+        add('inversion', `${id}::${inv.siteKey}#${inv.arm}`,
+          // The GATED columns, because that is what `inversions` was computed from
+          // (choice-cost.ts filters on `gatedAttempts`/`gatedFailures`). Printing the
+          // interpreted counts here would state "failed all N" with an N the condition
+          // never tested — the two differ wherever `firstCharGated` is true.
+          `arm ${inv.arm} (${inv.label}) failed all ${inv.gatedAttempts} compiled entries while a later arm matched; ${inv.gatedWastedBytes} bytes re-scanned`)
+      }
+    }
+  }
+
+  const measuredKeys = new Set<string>()
+  for (const id of Object.keys(reports)) for (const s of reports[id]!.sites) measuredKeys.add(`${id}::${s.siteKey}`)
+  for (const key of Object.keys(b.sites).sort()) {
+    if (!measuredKeys.has(key)) {
+      add('stale', key, 'baselined site matches no measured site — a rule was renamed or removed, and ignoring it silently shrinks the gated set')
+    }
+  }
+  for (const id of Object.keys(b.totals).sort()) {
+    if (reports[id] === undefined) add('stale', id, 'baselined corpus was not measured')
+  }
+
+  return finish(Object.keys(reports).length, checkedSites)
+}
+
+/**
+ * Build the baseline a passing measurement would record.
+ *
+ * Deliberately NOT called by the gate. It exists so a rebaseline is one explicit
+ * command whose output is a file in the diff — the reviewable record — rather than
+ * something the gate can do to itself on a red run.
+ */
+export function buildWastedWorkBaseline(
+  reports: Readonly<Record<string, WastedWorkReport>>,
+  meta: { gitRev: string; updatedAt: string },
+): WastedWorkBaseline {
+  const totals: WastedWorkBaseline['totals'] = {}
+  const sites: WastedWorkBaseline['sites'] = {}
+  for (const id of Object.keys(reports).sort()) {
+    const r = reports[id]!
+    totals[id] = { corpusBytes: r.corpusBytes, totalWastedBytes: r.totalWastedBytes, instrumentedSites: r.instrumentedSites }
+    for (const s of [...r.sites].sort((a, c) => (a.siteKey < c.siteKey ? -1 : 1))) {
+      if (s.wastedBytes > 0) sites[`${id}::${s.siteKey}`] = s.wastedBytes
+    }
+  }
+  return { schema: 'parseman.wasted-work-baseline/1', gitRev: meta.gitRev, updatedAt: meta.updatedAt, totals, sites }
+}

package/src/analysis/choice-cost-render.ts

@@ -0,0 +1,293 @@
+/**
+ * CHOICE COST — the human layer.
+ * ==============================
+ *
+ * Three layers, not two:
+ *
+ *   ANALYSIS   src/analysis/choice-cost.ts  — what the sites are and what they cost.
+ *   POLICY     bench/choice-cost-guard.ts   — which of those numbers fail a build.
+ *   RENDERING  this file                    — how a person reads either of them.
+ *
+ * The structured report is the source of truth. Nothing here computes a finding, and
+ * nothing here decides pass or fail; a gate consumes the data and never this text. If
+ * a number appears below that is not in the report, that is a bug in this file.
+ *
+ * WHAT A PARSER GENERATOR CAN SHOW THAT A COMPILER CANNOT
+ * -------------------------------------------------------
+ * A type error has one source to point at. A wasted-work finding has TWO, and relating
+ * them is the whole diagnostic:
+ *
+ *   - the GRAMMAR site — the ordered choice whose arm ordering costs the time
+ *   - the COST — measured, over a real corpus, per alternative
+ *
+ * So the ordering is printed WITH its measured cost beside each arm, which makes the
+ * fix self-evident without a paragraph explaining it:
+ *
+ *   StylesheetAtRule › dispatch[0]              1.31 MB rescanned
+ *     0  RoutedAtRuleStatement    failed 4,182 / 4,271     1.31 MB
+ *     1  RoutedLayerBlock         matched 4,182
+ *
+ * Reading that, nobody needs to be told what to do.
+ *
+ * QUIET BY DEFAULT
+ * ----------------
+ * Nothing in this module prints. It returns strings. There is no console call and no
+ * process-wide default-on channel, deliberately: importing `examples/css/parser.ts`
+ * already emits roughly sixty lines of gating advice before any user code runs, and a
+ * beautiful diagnostic that nobody reads because it is buried in build noise is not
+ * beautiful. This one is available on request — from the CLI gate, or by calling it —
+ * and silent otherwise.
+ *
+ * DETERMINISM BINDS THE RENDERING TOO
+ * -----------------------------------
+ * The rendering is diffable: it preserves the report's ordering, contains no timings,
+ * no dates, no absolute paths, and colour is opt-in rather than auto-detected, so the
+ * same report always renders to the same bytes. A renderer that sniffed `isTTY` would
+ * produce two different outputs from one report and break exactly that.
+ */
+
+import type {
+  ChoiceInventoryReport, ChoiceInventoryEntry, WastedWorkReport, ArmDeclineReason, SiteDeclineReason,
+} from './choice-cost.ts'
+import { groupDigits } from './format-number.ts'
+
+export type RenderOptions = {
+  /** Rows to show. Default 20. The report always holds all of them. */
+  limit?: number
+  /**
+   * ANSI colour. Default false — NOT auto-detected from `isTTY`, because a renderer
+   * whose bytes depend on where it is piped cannot be diffed or snapshotted.
+   */
+  color?: boolean
+}
+
+// ── formatting primitives ────────────────────────────────────────────────────
+
+/**
+ * Deterministic thousands grouping. `toLocaleString()` is locale-dependent and
+ * would make the output differ between machines — the one thing a gateable
+ * rendering cannot do.
+ *
+ * DEFINED IN `./format-number.ts` and re-exported here because this module's own
+ * callers import it from here. It was a byte-identical second copy: `./terminal.ts`
+ * declared one, this file declared another, and the two were one edit away from
+ * disagreeing about how a report reads on two different screens.
+ */
+export { groupDigits }
+
+/** Byte counts at a glance. Binary units, fixed to one decimal, so 1,376,256 renders
+ *  as `1.3 MB` on every machine. */
+export function bytes(n: number): string {
+  if (n < 1024) return `${groupDigits(n)} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} kB`
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`
+}
+
+// Written as \u001B escapes, never as raw ESC bytes. A raw control byte makes the
+// whole file BINARY to git: `git diff --numstat` shows `- -`, GitHub declines to
+// render it, and `grep -rn` skips it SILENTLY — no output and exit 0. Enforced by
+// `pnpm check:control-bytes`.
+const ESC = '\u001B'
+const ANSI = {
+  dim: `${ESC}[2m`, bold: `${ESC}[1m`, red: `${ESC}[31m`,
+  yellow: `${ESC}[33m`, cyan: `${ESC}[36m`, reset: `${ESC}[0m`,
+} as const
+
+const paint = (on: boolean) => (code: keyof typeof ANSI, s: string): string =>
+  on ? `${ANSI[code]}${s}${ANSI.reset}` : s
+
+const pad = (s: string, w: number): string => s.length >= w ? s : s + ' '.repeat(w - s.length)
+const padStart = (s: string, w: number): string => s.length >= w ? s : ' '.repeat(w - s.length) + s
+
+// ── why a site declined, in one line each ────────────────────────────────────
+
+/**
+ * Every entry lands in exactly one of two states — ACTIONABLE (here is the rewrite) or
+ * LOCATED (here is the site and the precise reason no rewrite can be offered). There
+ * is no third "consider refactoring" state; a sentence of advice with no location and
+ * no rewrite is what this table exists to replace.
+ */
+const ARM_DECLINE_LINE: Record<ArmDeclineReason, string> = {
+  'not-a-sequence':
+    'arm is not a sequence, so there is no leading term to lift out',
+  'sequence-shorter-than-2':
+    'arm is a one-term sequence; lifting its only term would leave an empty arm',
+  'lead-case-insensitive-literal':
+    'leading literal is case-insensitive, so the matched text can differ from the literal — a lifted prefix would carry the wrong string',
+  'lead-not-concrete-terminal':
+    'leading term is not a bare literal or regex; lifting it would change the arm’s value or capture shape',
+}
+
+const SITE_DECLINE_LINE: Record<SiteDeclineReason, string> = {
+  'disjoint-dispatch':      'first-char dispatch already selects one arm — nothing is re-scanned',
+  'gated-arms':             'an arm carries a runtime gate; per-arm predicates are incompatible with factoring',
+  'strategy-preempted':     'a stronger non-backtracking strategy already applies',
+  'fewer-than-two-arms':    'fewer than two arms',
+  'arms-not-factorable':    'at least one arm cannot contribute a leading term (see below)',
+  'leads-differ':           'the arms do not all begin with the same term',
+}
+
+/**
+ * The combinator source a left-factoring would produce, ready to paste.
+ *
+ * Offered ONLY for the shape where it is mechanical and total: every arm of the choice
+ * in one group. A partial group needs the author to decide which arms move and in what
+ * order — an ordering decision that changes what the grammar accepts, which no
+ * generated rewrite may make silently.
+ *
+ * This is a PREVIEW. It is not applied, and — until the digest-verification loop
+ * described in `docs/` is wired — it is not yet proven behaviour-preserving, so it is
+ * labelled a candidate rather than offered as a fix. An unverified rewrite presented
+ * as verified is worse than no suggestion at all.
+ */
+export function leftFactorPreview(e: ChoiceInventoryEntry): string | null {
+  if (e.factored) return null
+  if (e.groups.length !== 1) return null
+  const g = e.groups[0]!
+  if (g.members.length !== e.arity) return null
+  const tails = g.members.map(i => `sequence(…arm[${i}] tail…)`).join(',\n    ')
+  return `sequence(\n  ${g.render === '' ? '<prefix>' : (g.render.startsWith('/') ? `regex(${g.render})` : `literal(${g.render})`)},\n  choice(\n    ${tails},\n  ),\n)`
+}
+
+// ── static inventory rendering ───────────────────────────────────────────────
+
+export function renderChoiceInventory(r: ChoiceInventoryReport, opts: RenderOptions = {}): string {
+  const c = paint(opts.color === true)
+  const limit = opts.limit ?? 20
+  const out: string[] = []
+
+  out.push(c('bold', 'shared-prefix inventory'))
+  out.push(c('dim', '  Static grammar shape only. A site listed here may already cost nothing at runtime:'))
+  out.push(c('dim', '  compiled output gates each arm on its first character. Rank with profileWastedWork().'))
+  out.push(`  ${groupDigits(r.rules)} rules, ${groupDigits(r.choiceSites)} choice sites`)
+  out.push(`  ${groupDigits(r.factoredSites)} left-factored by the compiler`)
+  out.push(`  ${groupDigits(r.backlogSites)} sites where alternatives share a leading term and the compiler DECLINED (${groupDigits(r.backlogArms)} arms)`)
+
+  const backlog = r.entries
+    .filter(e => !e.factored && e.groups.length > 0
+      && e.declineReason !== 'disjoint-dispatch' && e.declineReason !== 'strategy-preempted')
+    .sort((a, b) => b.unfactoredArms - a.unfactoredArms || (a.siteKey < b.siteKey ? -1 : 1))
+
+  if (backlog.length === 0) {
+    out.push('')
+    out.push('  no declined shared prefixes.')
+    return out.join('\n')
+  }
+
+  out.push('')
+  for (const e of backlog.slice(0, limit)) {
+    out.push(`  ${c('cyan', e.siteKey)}  ${c('dim', `${e.arity} arms · ${e.strategy}`)}`)
+    for (const g of e.groups) {
+      out.push(`    arms ${g.members.join(', ')} all begin with ${c('bold', g.render)}`)
+    }
+    out.push(`    ${c('yellow', 'declined')}: ${SITE_DECLINE_LINE[e.declineReason!]}`)
+    for (const a of e.armDeclines) {
+      out.push(`      arm[${a.arm}] — ${ARM_DECLINE_LINE[a.reason]}`)
+    }
+    const fix = leftFactorPreview(e)
+    if (fix !== null) {
+      out.push(`    ${c('dim', 'candidate rewrite (preview — not applied, not yet digest-verified):')}`)
+      for (const line of fix.split('\n')) out.push(`      ${line}`)
+    }
+    out.push('')
+  }
+  if (backlog.length > limit) out.push(`  … and ${groupDigits(backlog.length - limit)} more (the report holds all of them)`)
+  return out.join('\n')
+}
+
+// ── wasted-work rendering ────────────────────────────────────────────────────
+
+/**
+ * The ranked list, with each top site expanded into its arm ordering.
+ *
+ * The expansion is the point. A ranked list of site keys tells you WHERE; the arm
+ * breakdown beside it tells you WHY, and "arm 0 failed 4,182 of 4,271 times" is an
+ * argument for moving arm 0 that needs no prose attached.
+ */
+export function renderWastedWork(r: WastedWorkReport, opts: RenderOptions = {}): string {
+  const c = paint(opts.color === true)
+  const limit = opts.limit ?? 20
+  const out: string[] = []
+  const removed = r.arms.reduce((n, a) => n + (a.attempts - a.gatedAttempts), 0)
+  const totalAttempts = r.arms.reduce((n, a) => n + a.attempts, 0)
+
+  out.push(c('bold', 'wasted work — input bytes re-scanned after a failed alternative'))
+  out.push(...interpretedBanner(c, removed, totalAttempts))
+  out.push(`  corpus: ${groupDigits(r.corpusFiles)} files, ${bytes(r.corpusBytes)} (${groupDigits(r.parsedOk)} parsed, ${groupDigits(r.parsedFailed)} failed)`)
+  out.push(`  sites:  ${groupDigits(r.instrumentedSites)} instrumented, ${groupDigits(r.uninstrumentableSites)} not instrumentable`)
+  if (r.unresolvedRoots.length > 0) {
+    out.push(`  ${c('yellow', 'PARTIAL')}: ${groupDigits(r.unresolvedRoots.length)} rule(s) could not be resolved and were NOT walked — the total below is a lower bound`)
+  }
+  out.push(`  total:  ${c('bold', bytes(r.totalGatedWastedBytes))} re-scanned` +
+    (r.corpusBytes > 0 ? ` — ${(r.totalGatedWastedBytes / r.corpusBytes).toFixed(2)}x the corpus` : '') +
+    (r.totalWastedBytes === r.totalGatedWastedBytes ? '' : `  (interpreted: ${bytes(r.totalWastedBytes)})`))
+
+  const ranked = r.sites.filter(s => s.gatedWastedBytes > 0 || s.wastedBytes > 0)
+  if (ranked.length === 0) {
+    out.push('')
+    out.push('  no alternative failed on this corpus.')
+    return out.join('\n')
+  }
+
+  out.push('')
+  out.push(c('dim', '  per arm: "entered" counts what the COMPILED parser reaches; the parenthesised'))
+  out.push(c('dim', '  number is the interpreted count, shown only where the first-char gate differs.'))
+  out.push('')
+  const w = Math.min(52, Math.max(...ranked.slice(0, limit).map(s => s.siteKey.length)))
+  for (const s of ranked.slice(0, limit)) {
+    const share = r.totalGatedWastedBytes > 0 ? ` ${padStart((100 * s.gatedWastedBytes / r.totalGatedWastedBytes).toFixed(1) + '%', 7)}` : ''
+    out.push(`  ${c('cyan', pad(s.siteKey.slice(0, w), w))} ${padStart(bytes(s.gatedWastedBytes), 10)}${c('dim', share)}`)
+    const arms = r.arms.filter(a => a.siteKey === s.siteKey).sort((a, b) => a.arm - b.arm)
+    for (const a of arms) {
+      const entered = a.gatedAttempts === a.attempts
+        ? groupDigits(a.attempts)
+        : `${groupDigits(a.gatedAttempts)} (${groupDigits(a.attempts)} interp)`
+      // A 100%-failure arm is the actionable shape, but only if the SHIPPED parser
+      // enters it — so the verdict reads the gated columns.
+      // PAD FIRST, PAINT SECOND. `pad` measures `s.length`, so padding a string that
+      // already carries ANSI escapes spends the column width on invisible bytes and the
+      // arm table loses its alignment in colour mode. Every other cell here does it in
+      // this order; this one is not allowed to be the exception.
+      const verdict: { text: string; color: 'dim' | 'red' | null } = a.gatedAttempts === 0
+        ? { text: 'never entered when compiled', color: 'dim' }
+        : a.gatedFailures === a.gatedAttempts
+          ? { text: `failed ALL ${entered}`, color: 'red' }
+          : a.gatedFailures === 0
+            ? { text: `matched ${entered}`, color: 'dim' }
+            : { text: `failed ${groupDigits(a.gatedFailures)} / ${entered}`, color: null }
+      const cell = verdict.color === null ? pad(verdict.text, 34) : c(verdict.color, pad(verdict.text, 34))
+      out.push(`    ${padStart(String(a.arm), 2)}  ${pad(a.label.slice(0, 30), 30)} ${cell} ${a.gatedWastedBytes > 0 ? padStart(bytes(a.gatedWastedBytes), 10) : ''}`)
+    }
+    out.push('')
+  }
+  if (ranked.length > limit) out.push(`  … and ${groupDigits(ranked.length - limit)} more sites (the report holds all of them)`)
+
+  if (r.inversions.length > 0) {
+    out.push(c('bold', '  ordering inversions — arm failed EVERY compiled entry while a later arm matched'))
+    out.push(c('dim', '  ranked by entries, not bytes: an arm can fail 100% of the time and re-scan nothing.'))
+    for (const a of r.inversions.slice(0, limit)) {
+      out.push(`    ${c('cyan', pad(a.siteKey.slice(0, w), w))} arm ${padStart(String(a.arm), 2)}  ${pad(a.label.slice(0, 26), 26)} ${padStart(groupDigits(a.gatedAttempts), 8)} entries  ${a.gatedWastedBytes > 0 ? padStart(bytes(a.gatedWastedBytes), 10) : padStart('0 B', 10)}`)
+    }
+    if (r.inversions.length > limit) out.push(`    … and ${groupDigits(r.inversions.length - limit)} more`)
+  }
+  return out.join('\n')
+}
+
+/**
+ * The interpreted-vs-compiled warning, on EVERY rendered report.
+ *
+ * Not a footnote and not a docs link. A consumer who reads only the ranking must be
+ * told, in the ranking, that first-set gating — the largest parse lever this project
+ * has — is modelled rather than measured, or they will chase arms codegen already
+ * skips for free. The measured share of removed entries is included because "some
+ * attempts are gated" is ignorable and "78% of them are" is not.
+ */
+function interpretedBanner(c: (k: 'dim' | 'bold' | 'red' | 'yellow' | 'cyan', s: string) => string, removed: number, total: number): string[] {
+  const share = total > 0 ? ` — ${(100 * removed / total).toFixed(0)}% of interpreted arm entries` : ''
+  return [
+    c('yellow', '  MEASURED IN THE INTERPRETER. Compiled output gates each arm on its first'),
+    c('yellow', `  character; ${groupDigits(removed)} entries below never happen in the shipped parser${share}.`),
+    c('dim', '  Counts shown are the modelled COMPILED ones. Byte totals are unaffected by the'),
+    c('dim', '  gate (a gated-out arm consumes nothing); entry counts and failure RATES are not.'),
+  ]
+}