parseman 0.46.0 → 0.47.0

package/src/analysis/diagnose-render.ts

@@ -0,0 +1,625 @@
+/**
+ * The human layer over `GrammarDiagnosis`.
+ *
+ * Three layers, not two: `gating.ts`/`corpus.ts` produce data, `diagnose.ts` decides
+ * `ok` (the CI verdict), and this file makes either readable. Nothing here computes a
+ * finding and nothing here decides pass or fail. A gate consumes the object; a person
+ * reads this. If a number appears below that is not in the report, that is a bug here.
+ *
+ * GROUPED BY CAUSE, NOT BY SITE
+ * -----------------------------
+ * The first version grouped by site: thirteen findings, each carrying its own copy of
+ * the explanation, the `do` line and the `ok as-is?` line. Measured on
+ * `examples/css/parser.ts`, that was three distinct explanations rendered nine times
+ * across 146 lines. Density that comes from repetition is not detail — it is the same
+ * sentence again, and it buries the arm tables, which are the part a reader acts on.
+ *
+ * A cause is now stated ONCE, given a glyph, and followed by its sites. That also
+ * disposes of the question a glossary would have answered: the glyph is defined at the
+ * head of the only group it labels, so there is nothing to look up. Shipping a glossary
+ * AND the inline explanations would just re-create the duplication this removes.
+ *
+ * WHAT CARRIES MEANING
+ * --------------------
+ *   colour  — severity, and importance WITHIN a finding. Exactly one span per block is
+ *             the brightest thing in it; provenance and accept keys recede.
+ *   glyph   — the cause class, so sites are scannable without reading prose.
+ *   rules   — group boundaries, so the report is blocks rather than a paragraph.
+ *   columns — the arm table is aligned, so an ANY arm or an overlap is visible as a
+ *             shape before it is read as text.
+ *
+ * All of that lives in the STYLED path. The plain path is the same content with the same
+ * padding and no escapes, so `docs/samples/` stays diffable and the two cannot drift.
+ */
+import { examinedNothing, type GrammarDiagnosis, type DiagnosisFinding } from './diagnose.ts'
+import type { ChoiceCorpusCost } from './corpus.ts'
+import {
+  DEFAULT_WIDTH, TONE, blank, codeFrame, groupDigits, pad, render, rule, t, wrap,
+  type Line, type RenderTarget, type Tone,
+} from './terminal.ts'
+
+export type DiagnoseRenderOptions = RenderTarget & {
+  /** Grammar label for the header. The CLI passes a cwd-relative path. */
+  name?: string
+  /** Sites to expand. Default 20; the report always holds all of them. */
+  limit?: number
+  /** Corpus cost per choice id, from `measureChoiceCost`. */
+  cost?: ReadonlyMap<string, ChoiceCorpusCost>
+  /** Per-arm first-set renderings per choice id, in arm order. */
+  armFirstSets?: ReadonlyMap<string, readonly string[]>
+  /** Per-arm leading-term labels per choice id, in arm order. */
+  armLabels?: ReadonlyMap<string, readonly string[]>
+  /** Absolute corpus root, used ONLY for the frame's terminal hyperlink. */
+  corpusRoot?: string
+  /**
+   * Finding ids for which `proposeFixes` PROVED a rewrite — applied it, recompiled, and
+   * re-parsed the corpus with identical output. Only these may carry the wrench. A
+   * candidate that was proposed and rejected must never appear here: offering a fix that
+   * does not exist would destroy the one guarantee the feature has.
+   */
+  fixable?: ReadonlySet<string>
+  /** The command that would apply them, printed verbatim so nobody has to guess it. */
+  fixCommand?: string
+}
+
+export { groupDigits }
+
+/**
+ * Cause glyphs, in assignment order.
+ *
+ * Deliberately distinct in SHAPE, not just in colour: a report has to stay readable for
+ * a reader who cannot distinguish red from green, and in a log that has been stripped of
+ * colour entirely — which is exactly what `docs/samples/` is.
+ */
+const GLYPHS = ['◆', '▲', '●', '■', '◇', '△', '○', '□'] as const
+
+/** A short label per finding code, used in a group headline. */
+const CODE_LABEL: Record<string, { one: string; many: string }> = {
+  'ungated-choice': {
+    one: 'choice the parser cannot narrow down',
+    many: 'choices the parser cannot narrow down',
+  },
+  'anti-pattern': { one: 'arm that hides its first character', many: 'arms that hide their first character' },
+  unanalysable: { one: 'rule parseman could not examine at all', many: 'rules parseman could not examine at all' },
+  degraded: { one: 'place the compiler took a slower route', many: 'places the compiler took a slower route' },
+  'stale-accept': {
+    one: 'accept-list entry that no longer matches anything',
+    many: 'accept-list entries that no longer match anything',
+  },
+}
+
+/**
+ * The cause an anti-pattern finding belongs to, keyed by KIND.
+ *
+ * The finding's own message names the specific word it found, which is right for the
+ * site line and wrong for the group: keying on the whole message split one cause into
+ * one group per site, which is the duplication this rendering exists to remove. The
+ * group says what the pattern is; the site says where and which word.
+ */
+const ANTI_KIND_BLURB: Record<string, string> = {
+  'keyword-regex':
+    'These arms match a fixed word using a regular expression. parseman cannot always tell '
+    + 'from a regular expression which character it starts with, so the parser cannot skip '
+    + 'the arm when that character rules it out.\n'
+    + "To fix: write the word with word('…') or keywords([…]). Same match, same compiled "
+    + 'character scan, but parseman then knows the first character.',
+  'double-not':
+    'These arms use not(not(X)) — a hand-written way of saying "X must come next, but do not '
+    + 'consume it". It hides the first character, so the arm can never be skipped, and among '
+    + 'arms that share a first character it can pick the wrong one.\n'
+    + 'To fix: write peek(X). Same check, and parseman still knows the first character.',
+  'leading-not':
+    'These arms begin with not(...), which matches no text and so reveals no first character. '
+    + 'The parser cannot skip the arm and enters it at every position.\n'
+    + 'To fix: put the term that actually consumes text first, and keep not(...) after it as a '
+    + 'trailing boundary check.',
+}
+
+/**
+ * A first set, said in words.
+ *
+ * `'#','*','-'-'.'` is how the model writes it and is unreadable to anyone who has not
+ * met the model. What a reader needs is the sentence: this arm can only begin with these
+ * characters, therefore the parser can skip it everywhere else.
+ */
+function startsWithPhrase(fs: string): string {
+  if (fs === 'ANY') return 'can start with any character'
+  if (fs === '(empty)') return 'matches nothing'
+  const parts = fs.split(',')
+  const pretty = parts.map(x => x.replace(/'/g, '')).join(' ')
+  if (parts.length === 1) return `starts with "${pretty}"`
+  if (parts.length > 4) return `starts with ${groupDigits(parts.length)} char ranges`
+  return `starts with one of ${pretty.length > 20 ? `${pretty.slice(0, 19)}…` : pretty}`
+}
+
+/** The fallback explanation for a code whose findings carry no `fix:` of their own. */
+const CODE_BLURB: Record<string, string> = {
+  'ungated-choice': 'The parser cannot tell from the next character which alternative to try, so it '
+    + 'tries them in order and undoes the ones that do not match.',
+  'anti-pattern': 'The arm is written in a way that hides which character it starts with, so the parser '
+    + 'cannot skip it when it cannot match.',
+  unanalysable: 'parseman could not read these rules at all, so it has NO opinion about them — good or '
+    + 'bad. Anything reported elsewhere is therefore incomplete.',
+  degraded: 'The compiler could not use its fast route here and fell back to a slower one that produces '
+    + 'the same result.',
+  'stale-accept': 'This entry in your accept list no longer matches any finding — the grammar was fixed '
+    + 'and the line was left behind. Delete it.',
+}
+
+type CauseGroup = {
+  glyph: string
+  /** The one-per-cause explanation. */
+  text: string
+  code: string
+  severity: 'blocking' | 'advisory'
+  findings: DiagnosisFinding[]
+}
+
+/** Every `fix:` a finding carries, in order. The first is its primary cause. */
+function suggestionsOf(f: DiagnosisFinding): string[] {
+  const out: string[] = []
+  for (const d of f.details) {
+    const i = d.indexOf('\nfix: ')
+    if (i === -1) continue
+    const s = d.slice(i + 6)
+    if (!out.includes(s)) out.push(s)
+  }
+  return out
+}
+
+/**
+ * Group findings by primary cause.
+ *
+ * A finding with two causes is listed ONCE, under its first, with the others flagged
+ * inline. Listing it under both would print its arm table twice, which is the
+ * duplication this grouping exists to remove.
+ */
+function groupByCause(findings: readonly DiagnosisFinding[]): CauseGroup[] {
+  const groups: CauseGroup[] = []
+  const byKey = new Map<string, CauseGroup>()
+  for (const f of findings) {
+    // An anti-pattern's message names the specific word found at THIS site, which is
+    // right for the site line and wrong for the group: keying on it split one pattern
+    // into one group per site — the exact duplication this grouping removes. Key on the
+    // KIND, and let the site line carry the word.
+    const kind = f.code === 'anti-pattern' ? /^\[([^\]]+)\]/.exec(f.message)?.[1] : undefined
+    const text = suggestionsOf(f)[0]
+      ?? (kind === undefined ? undefined : ANTI_KIND_BLURB[kind])
+      ?? (f.code === 'anti-pattern' ? f.message.replace(/^\[[^\]]+\]\s*/, '') : undefined)
+      ?? CODE_BLURB[f.code]
+      ?? f.message
+    // JSON, not a delimiter character: a raw separator inside a template literal made
+    // this file binary to git once already (see 9dab15d), and a printable one can still
+    // collide with the text it separates.
+    const key = JSON.stringify([f.code, kind ?? text])
+    let g = byKey.get(key)
+    if (g === undefined) {
+      g = { glyph: '', text, code: f.code, severity: f.severity, findings: [] }
+      byKey.set(key, g)
+      groups.push(g)
+    }
+    g.findings.push(f)
+  }
+  groups.forEach((g, i) => { g.glyph = GLYPHS[i] ?? String.fromCharCode(65 + i) })
+  return groups
+}
+
+/** The lines a diagnosis renders to — data, so a caller can compose them into a larger
+ *  report without going through a string. */
+export function diagnosisLines(d: GrammarDiagnosis, opts: DiagnoseRenderOptions = {}): Line[] {
+  const limit = opts.limit ?? 20
+  const name = opts.name ?? 'grammar'
+  const width = opts.width ?? DEFAULT_WIDTH
+  const s = d.summary
+  const out: Line[] = []
+
+  // SUCCESS IS TWO LINES. It is the rendering people see most, and the one usually
+  // neglected into a wall of zero-valued tables.
+  if (d.ok && s.unanalysable === 0) {
+    const parts = [`${groupDigits(s.gated)}/${groupDigits(s.totalChoices)} choices gate on first char`]
+    if (s.recoverable > 0) parts.push(`${groupDigits(s.recoverable)} recoverable`)
+    if (s.accepted > 0) parts.push(`${groupDigits(s.accepted)} accepted`)
+    if (s.deferred > 0) parts.push(`${groupDigits(s.deferred)} deferred to the fusing artifact`)
+    if (s.staleAccepts > 0) parts.push(`${groupDigits(s.staleAccepts)} stale accept line(s) to prune`)
+    out.push([t('✓ ', TONE.good), t(name, TONE.strong), t(' — nothing to fix', TONE.good)])
+    out.push([t(`  ${parts.join(' · ')}`, TONE.quiet)])
+    return out
+  }
+
+  // NOTHING WAS EXAMINED. Rendered as its own report, not as the finding report with a
+  // warning bolted on. The finding report's every sentence — "N problems", "underlying
+  // cause", "fixing one fixes every choice listed under it", "none of this is a
+  // correctness bug" — is a claim about defects parseman FOUND, and there are none:
+  // there is one blocking finding per rule it could not read. Printed over an opaque
+  // artifact that produced `176 problems, 176 failing the check, 1 cause`, which reads
+  // as 176 discovered defects and means the tool inspected zero choices.
+  if (examinedNothing(d)) return unexaminedLines(d, name, width, limit)
+
+  const groups = groupByCause(d.findings)
+  const blocking = d.findings.filter(f => f.severity === 'blocking')
+  /** Findings that are things parseman FOUND — never the rules it could not read. */
+  const problems = d.findings.length - s.unanalysable
+
+  out.push([
+    t('✗ ', TONE.loud),
+    t(name, TONE.strong),
+    t(' — ', TONE.quiet),
+    // `findings` and `totalChoices` count different things — an anti-pattern is a
+    // finding about an ARM, not a choice — so they must not be phrased as a ratio. They
+    // were, and a two-arm grammar reported "3 of 1 choices".
+    //
+    // `unanalysable` is excluded from the problem count on purpose: it is not something
+    // parseman FOUND in the grammar, it is a rule parseman could not look at. Counting
+    // the two together is what let a report that inspected nothing print a confident
+    // problem tally. It is stated separately, on the PARTIAL line below.
+    t(`${groupDigits(problems)} problem${problems === 1 ? '' : 's'} `
+      + `in ${groupDigits(s.totalChoices)} choice${s.totalChoices === 1 ? '' : 's'}`, TONE.loud),
+  ])
+  out.push([
+    t('  '),
+    t(`${groupDigits(groups.length)} underlying cause${groups.length === 1 ? '' : 's'}`, TONE.strong),
+    t(groups.length < d.findings.length ? '; fixing one fixes every choice listed under it.' : '.', TONE.quiet),
+  ])
+  for (const l of wrap(
+    (s.gated > 0
+      ? `${groupDigits(s.gated)} other choice${s.gated === 1 ? '' : 's'} already `
+        + `${s.gated === 1 ? 'picks' : 'pick'} the right `
+        + 'alternative straight from the next character. '
+      : '')
+    + 'None of this is a correctness bug — the grammar parses the same either way; it is work '
+    + 'the parser does and did not need to.',
+    width - 2, '  ')) out.push([t(l, TONE.faint)])
+  // Unanalysable is called out at the top as well as in its group: "no findings" over a
+  // grammar that was never walked is precisely the failure being reported.
+  if (s.unanalysable > 0) {
+    out.push([t(`  PARTIAL — ${groupDigits(s.unanalysable)} rule(s) could not be examined; `
+      + 'an empty list below does NOT mean the grammar is clean.', TONE.warn)])
+  }
+
+  // ONE definition of the only term of art that survives, placed immediately before the
+  // first table that uses it. A reader meets `arm` here and nowhere earlier.
+  let defined = false
+
+  let shown = 0
+  for (const g of groups) {
+    const tone: Tone = g.severity === 'blocking' ? TONE.bad : TONE.warn
+    out.push(blank())
+    out.push(rule(width, TONE.frame))
+    const fixableHere = g.findings.filter(f => opts.fixable?.has(f.id) === true).length
+    out.push([
+      t(` ${g.glyph} `, tone),
+      t(`${groupDigits(g.findings.length)} `
+        + `${g.findings.length === 1 ? CODE_LABEL[g.code]?.one ?? g.code : CODE_LABEL[g.code]?.many ?? g.code}`,
+      TONE.strong),
+      t(g.severity === 'blocking' ? '   fails the check' : '   worth knowing', TONE.faint),
+    ])
+    for (const l of wrap(g.text, width - 6, '')) out.push([t('    '), t(l, TONE.quiet)])
+    if (!defined) {
+      defined = true
+      out.push(blank())
+      out.push([t('    Each numbered line below is one alternative of a choice — an "arm" — in the',
+        TONE.faint)])
+      out.push([t('    order the parser tries them.', TONE.faint)])
+    }
+    out.push(blank())
+
+    // ONE site per cause is expanded — its full arm ordering, and the corpus frame that
+    // illustrates the cause. The rest are a table: the same shape repeated thirteen
+    // times is what made the first version unreadable, and a reader who needs another
+    // site's ordering asks for it by id. `--limit` still governs how many are listed.
+    // +2 so the longest cell in a column still has a gap after it. Without it the
+    // widest row runs its term straight into the annotation, which is exactly the kind
+    // of ragged table this pass exists to remove.
+    const idW = Math.min(30, Math.max(...g.findings.map(f => f.id.length))) + 2
+    const headW = Math.min(34, Math.max(...g.findings.map(f => headlineOf(f, opts).term.length))) + 2
+    let expanded = false
+    for (const f of g.findings) {
+      if (shown >= limit) break
+      shown++
+      // Expand only when there IS an ordering to show. An anti-pattern finding names one
+      // arm and has no table, so an "expanded" version of it is just a lonelier line.
+      if (!expanded && opts.armFirstSets?.get(f.id) !== undefined) {
+        expanded = true
+        out.push(...siteLines(f, g, opts, true).lines)
+        if (g.findings.length > 1) out.push(blank())
+        continue
+      }
+      const h = headlineOf(f, opts)
+      out.push([
+        t(` ${g.glyph} `, tone),
+        t(f.id, TONE.ident, idW),
+        t(h.arm, TONE.faint, 8),
+        t(h.term, TONE.strong, headW),
+        t(h.note, h.loud ? TONE.loud : TONE.faint),
+        // LAST, always: the wrench is an emoji and may occupy two terminal columns, so
+        // nothing may be aligned after it.
+        t(opts.fixable?.has(f.id) === true ? '  🔧 fixable' : '', TONE.good),
+      ])
+    }
+    if (shown >= limit) break
+  }
+
+  if (shown < d.findings.length) {
+    out.push(blank())
+    out.push([t(`  … ${groupDigits(d.findings.length - shown)} more site(s) — `, TONE.quiet),
+      t(`--limit ${d.findings.length}`, TONE.strong),
+      t(' shows them, --json holds them all', TONE.quiet)])
+  }
+
+  // ONE accept line, carrying the whole set. A reader who wants to accept these wants a
+  // single pasteable thing, not one line per site saying the same thing differently.
+  if (!d.ok && d.acceptSnapshot.length > 0) {
+    out.push(blank())
+    out.push(rule(width, TONE.frame))
+    const snap = `{ accept: [${d.acceptSnapshot.map(i => `'${i}'`).join(', ')}] }`
+    out.push([t(' Meant to be this way? Pass this and they stop being reported:', TONE.quiet)])
+    for (const l of wrap(snap, width - 3, '')) out.push([t('   '), t(l, TONE.faint)])
+  }
+
+  // THE FOOTER, in a linter's shape and for a linter's reason: after a hundred lines the
+  // header has scrolled away, and the last thing on screen is what a person actually
+  // reads. It carries the tally, the exit code IN WORDS (the number is for the gate, the
+  // sentence is for the human) and — only when a rewrite has actually been proved — the
+  // exact command that applies it.
+  out.push(blank())
+  const fixCount = opts.fixable?.size ?? 0
+  const parts = [
+    `${groupDigits(problems)} problem${problems === 1 ? '' : 's'}`,
+    `${groupDigits(blocking.length - s.unanalysable)} failing the check`,
+    `${groupDigits(groups.length)} cause${groups.length === 1 ? '' : 's'}`,
+    // Never folded into the tally above. A rule that could not be read is a hole in the
+    // measurement, and a footer is the last thing a reader sees.
+    ...(s.unanalysable > 0 ? [`${groupDigits(s.unanalysable)} rule(s) NOT examined`] : []),
+  ]
+  out.push([
+    t('✗ ', TONE.loud),
+    t(parts.join(', '), TONE.strong),
+    t(`  ·  exiting 1 (problems found)`, TONE.faint),
+  ])
+  if (fixCount > 0 && opts.fixCommand !== undefined) {
+    out.push([t(' 🔧 ', TONE.good),
+      t(`${groupDigits(fixCount)} of them can be fixed automatically. Run:`, TONE.good)])
+    for (const l of wrap(opts.fixCommand, width - 6, '')) out.push([t('    '), t(l, TONE.strong)])
+    for (const l of wrap('Each change is applied, the parser rebuilt and your files parsed again '
+      + 'before it is offered, so nothing is suggested that has not been checked.',
+    width - 6, '')) out.push([t('    '), t(l, TONE.faint)])
+  }
+  return out
+}
+
+/** What each `Unanalysable.kind` means and what the reader can do about it. Stated once
+ *  per kind, at the head of the group it labels — the same rule the cause groups follow. */
+const KIND_BLURB: Record<string, string> = {
+  'fused-rule':
+    'These rules are compiled functions. Fusion lowers every rule to executable code and '
+    + 'discards the combinator graph, so there is nothing left to read.\n'
+    + 'To analyse them: point this at the grammar SOURCE, or at a grammar value that still '
+    + 'carries its IR (a rules() map, or a compose() result — those keep their pieces).',
+  'opaque-artifact':
+    'These rules come from a precompiled artifact that carries rule functions rather than '
+    + 're-lowerable IR, so its choices cannot be examined.\n'
+    + 'To analyse them: recompile the contributing grammar so it carries IR — the macro '
+    + 'emits IR by default.',
+  'not-a-combinator':
+    'The value handed to parseman was not a grammar it knows how to walk.\n'
+    + 'To analyse it: pass a combinator, a rules() map, a compose() result, or name the '
+    + 'export that holds one with --export.',
+}
+
+/**
+ * The report for a run that examined NOTHING.
+ *
+ * Deliberately not the finding report with a banner on top. Everything that report says
+ * is a claim about defects found — the tally, the "underlying cause", the "fixing one
+ * fixes every choice listed under it", the "none of this is a correctness bug". None of
+ * it is true here, and printed together they read as a confident audit of a grammar the
+ * tool never opened.
+ */
+function unexaminedLines(
+  d: GrammarDiagnosis, name: string, width: number, limit: number,
+): Line[] {
+  const out: Line[] = []
+  const items = d.gating.unanalysable
+  out.push([t('✗ ', TONE.loud), t(name, TONE.strong), t(' — ', TONE.quiet),
+    t('COULD NOT ANALYSE', TONE.loud)])
+  out.push([t(`  0 choices examined · ${groupDigits(items.length)} `
+    + `rule${items.length === 1 ? '' : 's'} unreadable`, TONE.warn)])
+  for (const l of wrap(
+    'parseman has NO verdict about this grammar — not "clean", not "problems". Every line '
+    + 'below is a rule it could not read, not a defect it found.',
+    width - 2, '  ')) out.push([t(l, TONE.faint)])
+
+  // Grouped by KIND: the kind is what a reader acts on, and one artifact usually
+  // contributes hundreds of rules for one reason.
+  const byKind = new Map<string, typeof items[number][]>()
+  for (const u of items) {
+    const g = byKind.get(u.kind)
+    if (g === undefined) byKind.set(u.kind, [u])
+    else g.push(u)
+  }
+  let shown = 0
+  for (const [kind, group] of byKind) {
+    out.push(blank())
+    out.push(rule(width, TONE.frame))
+    out.push([
+      t(' ■ ', TONE.warn),
+      t(`${groupDigits(group.length)} rule${group.length === 1 ? '' : 's'} could not be read`, TONE.strong),
+      t(`   [${kind}]`, TONE.faint),
+    ])
+    for (const l of wrap(KIND_BLURB[kind] ?? group[0]!.reason, width - 6, '')) {
+      out.push([t('    '), t(l, TONE.quiet)])
+    }
+    out.push(blank())
+    for (const u of group) {
+      if (shown >= limit) break
+      shown++
+      out.push([t('   '), t(u.rule, TONE.ident)])
+    }
+    if (shown >= limit) break
+  }
+  if (shown < items.length) {
+    out.push(blank())
+    out.push([t(`  … ${groupDigits(items.length - shown)} more — `, TONE.quiet),
+      t(`--limit ${items.length}`, TONE.strong), t(' shows them, --json holds them all', TONE.quiet)])
+  }
+
+  out.push(blank())
+  // The exit code IN WORDS, and it is 2 — not 1. 1 means "measured, and it failed";
+  // this run did not measure. See the CLI's exit-code contract.
+  out.push([t('✗ ', TONE.loud),
+    t(`could not analyse — 0 of ${groupDigits(items.length)} rule(s) examined`, TONE.strong),
+    t('  ·  exiting 2 (analysis did not run)', TONE.faint)])
+  return out
+}
+
+export function renderDiagnosis(d: GrammarDiagnosis, opts: DiagnoseRenderOptions = {}): string {
+  return render(diagnosisLines(d, opts), opts)
+}
+
+/**
+ * The one arm a site is about, for the compact table rows.
+ *
+ * A reader scanning a group needs the site's NAME and the term that poisons it; the full
+ * ordering only matters once they start editing that rule, and the expanded exemplar
+ * above shows what that ordering looks like for this cause.
+ */
+function headlineOf(f: DiagnosisFinding, opts: DiagnoseRenderOptions): {
+  arm: string; term: string; note: string; loud: boolean
+} {
+  const sets = opts.armFirstSets?.get(f.id)
+  const labels = opts.armLabels?.get(f.id)
+  const cost = opts.cost?.get(f.id)
+  const anyIdx = sets?.findIndex(x => x === 'ANY') ?? -1
+  if (anyIdx >= 0) {
+    const c = cost?.arms[anyIdx]
+    return {
+      arm: `arm ${anyIdx}`,
+      term: (labels?.[anyIdx] ?? '').slice(0, 34),
+      note: c === undefined
+        ? 'any character — never skippable'
+        : `same — tried at all ${groupDigits(c.positions)}`,
+      loud: true,
+    }
+  }
+  const overlap = f.details.map(d => d.split('\n')[0]!).find(x => x.includes('overlap on'))
+  if (overlap !== undefined) {
+    const m = /arm\[(\d+)\] ∩ arm\[(\d+)\] overlap on (.*)$/.exec(overlap)
+    if (m !== null) {
+      return { arm: `arm ${m[1]}`, term: `and arm ${m[2]}`, note: `can both start with ${m[3]}`, loud: false }
+    }
+  }
+  const m = /^(.*)#arm(\d+)$/.exec(f.id)
+  if (m !== null) {
+    // The specific thing found at THIS site — the word, from the finding's own message.
+    const word = /`([^`]+)`/.exec(f.message)?.[1]
+    return { arm: `arm ${m[2]}`, term: `of ${m[1]}`, note: word === undefined ? '' : `matches \`${word}\``, loud: false }
+  }
+  return { arm: '', term: '', note: f.message.split('\n')[0]!.slice(0, 40), loud: false }
+}
+
+/** One site under its cause: the arm ordering, and nothing the group already said. */
+function siteLines(
+  f: DiagnosisFinding,
+  g: CauseGroup,
+  opts: DiagnoseRenderOptions,
+  wantFrame: boolean,
+): { lines: Line[]; framed: boolean } {
+  const out: Line[] = []
+  const cost = opts.cost?.get(f.id)
+  const sets = opts.armFirstSets?.get(f.id)
+  const labels = opts.armLabels?.get(f.id)
+  let framed = false
+
+  out.push([
+    t(` ${g.glyph} `, f.severity === 'blocking' ? TONE.bad : TONE.warn),
+    t(f.id, TONE.ident),
+    t(cost === undefined
+      ? ''
+      : `  —  reached at ${groupDigits(cost.positions)} places in your corpus`,
+    TONE.faint),
+    t(suggestionsOf(f).length > 1 ? '  (+ another cause)' : '', TONE.warn),
+    t(opts.fixable?.has(f.id) === true ? '  🔧 fixable' : '', TONE.good),
+  ])
+
+  // WORLD 1 — the grammar site: the ordering, one column per meaning. This is the part
+  // worth keeping per site; everything that used to surround it was the repetition.
+  if (sets !== undefined) {
+    const lw = Math.min(26, Math.max(8, ...(labels ?? ['']).map(l => l.length)))
+    sets.forEach((fs, i) => {
+      const armCost = cost?.arms[i]
+      const any = fs === 'ANY'
+      // Every column says what it MEANS. `'('` and `ANY` were the model's vocabulary,
+      // not a sentence: a reader had to already know what a first-set was to read them.
+      const starts = startsWithPhrase(fs)
+      const note = armCost === undefined
+        ? ''
+        : any
+          ? `→ tried at all ${groupDigits(cost!.positions)}`
+          : `→ could match at ${groupDigits(armCost.positions)}`
+      out.push([
+        t('     ', undefined),
+        t(`arm ${pad(String(i), 2)}`, any ? TONE.bad : TONE.faint, 8),
+        t(' '),
+        t((labels?.[i] ?? '').slice(0, lw), any ? TONE.strong : TONE.quiet, lw),
+        t(' '),
+        t(starts, any ? TONE.loud : TONE.quiet, 29),
+        t(note, any ? TONE.loud : TONE.faint),
+      ])
+    })
+  }
+  // THE CONSEQUENCE, spelled out. The table above is an observation; this is why the
+  // reader should care, and it is the entire point of the tool.
+  if (sets !== undefined && cost !== undefined) {
+    const anyIdx = sets.findIndex(x => x === 'ANY')
+    if (anyIdx >= 0) {
+      for (const l of wrap(
+        `Because arm ${anyIdx} can begin with any character, no single-character test can rule it `
+        + `out. At all ${groupDigits(cost.positions)} of those places the parser has to enter it — set `
+        + 'up, try, undo — instead of skipping it for nothing.',
+        (opts.width ?? DEFAULT_WIDTH) - 7, '')) out.push([t('     '), t(l, TONE.quiet)])
+    }
+  }
+
+  // Overlaps name a PAIR, which the arm table alone does not show.
+  for (const detail of f.details) {
+    const first = detail.split('\n')[0]!
+    if (first.includes('overlap on')) {
+      const m = /arm\[(\d+)\] ∩ arm\[(\d+)\] overlap on (.*)$/.exec(first)
+      const text = m === null
+        ? first
+        : `arm ${m[1]} and arm ${m[2]} can both start with ${m[3]}, so that character cannot tell `
+          + 'the parser which to try'
+      for (const l of wrap(text, (opts.width ?? DEFAULT_WIDTH) - 7, '')) out.push([t('     '), t(l, TONE.warn)])
+    }
+    else if (sets === undefined && !detail.includes('\nfix: ')) {
+      for (const l of wrap(first, (opts.width ?? DEFAULT_WIDTH) - 6, '')) out.push([t('     '), t(l)])
+    }
+  }
+
+  // WORLD 2 — the input that pays for it, drawn once per cause. Point at a place a REAL
+  // arm wants, not at byte 0: an ANY arm's "first site" is always the first character of
+  // the corpus, which tells the reader nothing.
+  if (wantFrame && cost !== undefined) {
+    const broad = cost.arms.find(a => a.any)
+    const concrete = cost.arms.find(a => !a.any && a.firstSite !== undefined)
+    const site = (concrete ?? cost.arms.find(a => a.firstSite !== undefined))?.firstSite
+    if (site !== undefined) {
+      out.push(...codeFrame({
+        path: site.sample,
+        fullPath: opts.corpusRoot === undefined ? site.sample : `${opts.corpusRoot}/${site.sample}`,
+        line: site.line,
+        column: site.column,
+        lineText: site.lineText.replace(/\t/g, ' '),
+        message: broad === undefined
+          ? 'one of those places in your corpus'
+          : `one of the ${groupDigits(cost.positions)} places, in your own input`,
+        shortMessage: broad !== undefined && concrete !== undefined
+          ? `arm ${concrete.index} matches here; arm ${broad.index} is entered first anyway`
+          : 'the first place in your corpus this choice is reached',
+        type: 'warning',
+      }, opts, '     '))
+      framed = true
+    }
+  }
+  return { lines: out, framed }
+}