basalt-ui 1.27.0 → 1.29.0

package/src/charts/utils/ticks.ts

@@ -1,12 +1,101 @@
 import { VX } from '../../tokens'
+import type { ChartTier } from '../primitives/chart-frame-layout'
+import { maxTextWidth } from './measure-text'
 
-/** Pick evenly-spaced tick values that fit the available width */
-export function smartTicks(dates: string[], xMax: number): string[] {
+/** The gap one x tick label wants from its neighbour, on top of its measured width. */
+const X_TICK_LABEL_GAP = 8
+
+/**
+ * The horizontal room one x tick label needs: the widest string in `labels`, plus breathing space
+ * to its neighbour. Feeds `smartTicks`, which otherwise thinned the axis by a constant that knew
+ * nothing about what was actually painted (`docs/CHARTS-SPEC.md` §1). Shared by `CartesianChart`,
+ * `useBandPlot` and `DualPanel` — the three call sites that used to reimplement this formula.
+ *
+ * `fontPx` defaults to `VX.axisFont`; a phone-tier chart passes its own smaller tick font
+ * (`chartTierMetrics().axisFont`) so the spacing is derived from the size actually painted.
+ */
+export function xLabelPxFor(labels: string[], fontPx: number = VX.axisFont): number {
+  return maxTextWidth(labels, fontPx) + X_TICK_LABEL_GAP
+}
+
+/**
+ * Pick evenly-spaced tick values that fit the available width.
+ *
+ * `labelPx` is the width one formatted label actually needs (measured, plus the gap it wants from
+ * its neighbour) and overrides the `VX.minPxPerTick` floor whenever it is wider. Without it the
+ * spacing came from that constant alone regardless of what was painted, so a `formatX` returning
+ * `Mar 08 14:00` overlapped at every width — the one side of the chart that did not follow §1's
+ * "measure what you paint" law. Omit it and nothing moves.
+ *
+ * The final key is still appended when the step misses the last index — a thinned axis would
+ * otherwise paint no label at the right edge at all — but it no longer prints ON TOP of its
+ * neighbour. An appended tick lands a PARTIAL step from the last one on the grid, so at any tick
+ * count wide enough labels overlap there; measured at `/charts-stress` block (f1), `Mar 13 14:00`
+ * and `Mar 14 14:00` printed over each other at 1440px. When that gap is narrower than one label,
+ * the grid tick before it is dropped instead. Index 0 is never dropped: the left edge is the one
+ * label a reader orients from.
+ */
+export function smartTicks(dates: string[], xMax: number, labelPx?: number): string[] {
   if (dates.length === 0) return []
-  const maxTicks = Math.max(2, Math.floor(xMax / VX.minPxPerTick))
+  const perTick = Math.max(VX.minPxPerTick, labelPx ?? 0)
+  const maxTicks = Math.max(2, Math.floor(xMax / perTick))
   if (dates.length <= maxTicks) return dates
   const step = Math.ceil(dates.length / maxTicks)
-  return dates.filter((_, i) => i % step === 0 || i === dates.length - 1)
+  const last = dates.length - 1
+
+  const keep = new Set<number>()
+  for (let i = 0; i <= last; i += step) keep.add(i)
+
+  const lastOnGrid = Math.floor(last / step) * step
+  if (lastOnGrid !== last) {
+    // `scalePoint({ padding: 0.5 })` spreads N points over `xMax`, so one index is `xMax / N` wide.
+    const pxPerIndex = dates.length > 0 ? xMax / dates.length : 0
+    const gapPx = (last - lastOnGrid) * pxPerIndex
+    if (lastOnGrid > 0 && gapPx > 0 && gapPx < perTick) keep.delete(lastOnGrid)
+    keep.add(last)
+  }
+
+  return dates.filter((_, i) => keep.has(i))
+}
+
+/**
+ * Which of a BAND axis's category labels may be painted so that no two neighbours overlap — the
+ * same measured law {@link smartTicks} applies to a point axis, for a chart that lays its labels
+ * out itself instead of through the `Axis*` primitives.
+ *
+ * `Heatmap` was the one kind rendering labels as plain `<text>`, and therefore the one kind exempt
+ * from §1's measured-margin law: it printed all 12 columns at 390px, ten of them overlapping. Here
+ * `bandPx` is the pitch between two neighbouring labels (a cell's width for columns, its height for
+ * rows) and `labelPx` the room one label needs ({@link xLabelPxFor} for a horizontal run, the line
+ * box for a vertical one); a label is kept every `ceil(labelPx / bandPx)` bands, so the gap between
+ * two painted labels is never narrower than one label.
+ *
+ * The first and last band always keep theirs — they are the two a reader orients from — and when
+ * the last one lands a partial step from the grid, the grid label before it is dropped rather than
+ * printed underneath, exactly as `smartTicks` does with its appended final tick.
+ */
+export function thinLabels(
+  labels: readonly string[],
+  bandPx: number,
+  labelPx: number,
+): Set<number> {
+  const keep = new Set<number>()
+  const last = labels.length - 1
+  if (last < 0) return keep
+  keep.add(0)
+  if (last === 0) return keep
+  if (bandPx <= 0 || labelPx <= 0) {
+    keep.add(last)
+    return keep
+  }
+  const step = Math.max(1, Math.ceil(labelPx / bandPx))
+  for (let i = 0; i <= last; i += step) keep.add(i)
+  const lastOnGrid = Math.floor(last / step) * step
+  if (lastOnGrid !== last && lastOnGrid > 0 && (last - lastOnGrid) * bandPx < labelPx) {
+    keep.delete(lastOnGrid)
+  }
+  keep.add(last)
+  return keep
 }
 
 /** Variant of smartTicks that targets an exact tick count rather than deriving from width. */
@@ -16,3 +105,59 @@ export function smartTicksEvery(dates: string[], count: number): string[] {
   const step = Math.ceil(dates.length / count)
   return dates.filter((_, i) => i % step === 0 || i === dates.length - 1)
 }
+
+/**
+ * The fewest x ticks an axis may thin down to before rotating is the cheaper trade. Two ticks
+ * (`smartTicks`' own floor) is a labelled left edge and a labelled right edge and nothing to read
+ * between them — at that point the axis has stopped being an axis.
+ */
+const MIN_HORIZONTAL_TICKS = 3
+
+/** Horizontal projection of a 45°-rotated label — `cos 45°`. A tilted label still competes for
+ * horizontal room, just for `0.71×` of it. */
+const COS_45 = Math.SQRT1_2
+
+/**
+ * The phone tier's default x-label rotation: 45° when the labels are so wide that fewer than
+ * {@link MIN_HORIZONTAL_TICKS} of them fit side by side, else none.
+ *
+ * `xLabelRotate` already existed as the answer to a `formatX` too wide to repeat horizontally
+ * (`docs/CHARTS-SPEC.md` §1) — it just had to be reached for by hand, per chart, by someone who
+ * had already seen it collide on a phone. This makes it the DEFAULT at phone width and only there:
+ * rotating trades horizontal crowding for bottom-gutter depth, which is the cheap axis on a narrow
+ * viewport and the expensive one on a wide screen that had room all along. Opt out with an
+ * explicit `xLabelRotate: 0`.
+ *
+ * Deliberately measured against the same `labelPx` `smartTicks` thins by, so the decision and the
+ * thinning cannot disagree about how wide a label is.
+ *
+ * **Wanting to rotate is not the same as rotating fitting.** A rotated label reaches into the LEFT
+ * gutter (`rotatedLabelExtents`), so rotating BUYS bottom-gutter depth and SPENDS plot width — and
+ * at a narrow enough box it spends more than it buys. `/charts-stress` block (f1) is the case:
+ * three clean horizontal labels at 390, and at 320 an auto-rotation that reached off the left edge
+ * and bought not one extra label for it. So the trade is CHECKED, not assumed. Pass `rotatedXMax`
+ * (the width left once `autoMargin({ rotate: 45 })` has taken its deeper left gutter) and the
+ * rotation is taken only when the rotated axis paints MORE labels than the flat one at its
+ * projected pitch (`labelPx · cos 45°`), and at least two of them. Otherwise the axis stays flat
+ * and `smartTicks` thins further — two readable horizontal labels beat two tilted ones in a
+ * narrower plot. Omit `rotatedXMax` and the check is skipped.
+ */
+export function autoXLabelRotate(input: {
+  tier: ChartTier
+  /** Plot width available to the x axis, from the UNROTATED margin. */
+  xMax: number
+  /** What one x label needs horizontally ({@link xLabelPxFor}). */
+  labelPx: number
+  /** Plot width that would REMAIN once the rotated margin takes its deeper left gutter
+   * (`autoMargin({ rotate: 45 })`). Omit to skip the fit check. */
+  rotatedXMax?: number
+}): 0 | 45 {
+  const { tier, xMax, labelPx, rotatedXMax } = input
+  if (tier !== 'phone') return 0
+  if (labelPx <= 0 || xMax <= 0) return 0
+  const flatLabels = Math.floor(xMax / labelPx)
+  if (flatLabels >= MIN_HORIZONTAL_TICKS) return 0
+  if (rotatedXMax === undefined) return 45
+  const rotatedLabels = Math.floor(rotatedXMax / (labelPx * COS_45))
+  return rotatedLabels >= 2 && rotatedLabels > flatLabels ? 45 : 0
+}

package/src/cli/audit-allows.ts

@@ -0,0 +1,371 @@
+/**
+ * `check-theme --audit-allows` — split out of `src/cli/index.ts` (C2) so the dispatcher file holds
+ * routing only. Imports its shared plumbing (config/project resolution) back from `./index`.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import {
+  checkSource,
+  findAllowAnnotations,
+  neutralizeAllowAnnotation,
+  unmatchedExemptPatterns,
+} from '../guard'
+import type { Finding, GuardConfig, GuardKind } from '../guard'
+import type { BasaltConfig, ExemptRuleEntry } from './index'
+import { exemptRulePaths, exemptRuleReason, resolveRoots } from './index'
+
+// ── check-theme --audit-allows — every waiver, and whether it still suppresses anything ─────────
+
+/** `relPath:line:kind` — a finding's identity for set arithmetic across two runs of the same file. */
+function findingKey(f: Finding): string {
+  return `${f.relPath}:${f.line}:${f.kind}`
+}
+
+/** One annotation the guard cannot judge, queued for the oxlint half of the audit. */
+type PluginProbe = {
+  /** Index into the report's line array, so the verdict lands where the placeholder sits. */
+  readonly slot: number
+  readonly rel: string
+  /** 1-based line of the annotation, as {@link findAllowAnnotations} reports it. */
+  readonly line: number
+  readonly ids: readonly string[]
+  readonly site: string
+  readonly suffix: string
+}
+
+/** One oxlint diagnostic, as `--format=json` renders it — only the fields the audit reads. */
+type OxlintDiagnostic = {
+  code?: unknown
+  filename?: unknown
+  labels?: { span?: { line?: unknown } }[]
+}
+
+/** The nearest `node_modules/.bin/<name>` walking up from `dir`, else `name` if it is on PATH. */
+function resolveToolBin(dir: string, name: string): string | null {
+  let current = dir
+  for (;;) {
+    const candidate = resolve(current, 'node_modules/.bin', name)
+    if (existsSync(candidate)) return candidate
+    const parent = resolve(current, '..')
+    if (parent === current) break
+    current = parent
+  }
+  const probe = spawnSync(name, ['--version'], { stdio: 'ignore', timeout: 10_000 })
+  return probe.error === undefined && probe.status === 0 ? name : null
+}
+
+/** `line:rule` counts for one file's diagnostics — a multiset, so two findings on a line differ. */
+function diagnosticCounts(
+  diagnostics: readonly OxlintDiagnostic[],
+  filename: string,
+): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const d of diagnostics) {
+    if (d.filename !== filename) continue
+    const code = typeof d.code === 'string' ? d.code : ''
+    const rule = /^basalt\((.+)\)$/.exec(code)?.[1]
+    if (rule === undefined) continue
+    const line = d.labels?.[0]?.span?.line
+    const key = `${typeof line === 'number' ? line : 0}:${rule}`
+    counts.set(key, (counts.get(key) ?? 0) + 1)
+  }
+  return counts
+}
+
+/**
+ * The oxlint half of the audit: what each plugin-rule annotation still suppresses.
+ *
+ * The `check-theme` half proves a verdict by re-running `checkSource` with one occurrence
+ * neutralized. The `error`-severity design rules do not live there — they live in the oxlint
+ * plugin — so the audit declined to judge them and printed "not a check-theme kind". In a
+ * chart-heavy consumer that was 8 of 8 and 11 of 14: a CI gate that exited 0 having inspected
+ * nothing. The method generalizes exactly, one level over: neutralize the annotation, re-run
+ * oxlint over that file, and the findings that appear are what it covers.
+ *
+ * oxlint has no stdin mode, so a probe has to be a real file. It is written BESIDE the original —
+ * same directory, so the same `.oxlintrc.json`, the same `charts/` path segment, the same nearest
+ * `package.json` — and removed in a `finally`. Returns null when oxlint cannot be run at all, which
+ * is a "cannot judge", never a "dead".
+ */
+function probePluginRules(
+  cwd: string,
+  guardCfg: GuardConfig,
+  probes: readonly PluginProbe[],
+  sources: ReadonlyMap<string, string>,
+): Map<number, string[]> | null {
+  if (probes.length === 0) return new Map()
+  const bin = resolveToolBin(cwd, 'oxlint')
+  if (bin === null) return null
+
+  const written: string[] = []
+  const probePaths = new Map<number, string>()
+  try {
+    for (const probe of probes) {
+      // Neutralized by the guard's own helper, so the oxlint probe and the checkSource probe can
+      // never differ by a substitution detail — a verdict that disagrees between the two halves of
+      // one audit is worse than no verdict.
+      const probed = neutralizeAllowAnnotation(sources.get(probe.rel) ?? '', probe.line, guardCfg)
+      const dot = probe.rel.lastIndexOf('.')
+      const rel =
+        dot === -1
+          ? `${probe.rel}.basalt-audit-${probe.slot}`
+          : `${probe.rel.slice(0, dot)}.basalt-audit-${probe.slot}${probe.rel.slice(dot)}`
+      const abs = resolve(cwd, rel)
+      if (existsSync(abs)) continue
+      writeFileSync(abs, probed, 'utf8')
+      written.push(abs)
+      probePaths.set(probe.slot, rel)
+    }
+    if (probePaths.size === 0) return null
+
+    const targets = [...new Set(probes.map((p) => p.rel)), ...probePaths.values()]
+    const run = spawnSync(bin, ['--format=json', '--no-error-on-unmatched-pattern', ...targets], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 120_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    if (run.error !== undefined || typeof run.stdout !== 'string') return null
+    let diagnostics: OxlintDiagnostic[]
+    try {
+      diagnostics =
+        (JSON.parse(run.stdout) as { diagnostics?: OxlintDiagnostic[] }).diagnostics ?? []
+    } catch {
+      return null
+    }
+
+    const verdicts = new Map<number, string[]>()
+    for (const probe of probes) {
+      const probeRel = probePaths.get(probe.slot)
+      if (probeRel === undefined) continue
+      const before = diagnosticCounts(diagnostics, probe.rel)
+      const after = diagnosticCounts(diagnostics, probeRel)
+      const revealed: string[] = []
+      for (const [key, count] of after) {
+        if (count <= (before.get(key) ?? 0)) continue
+        const [line = '', rule = ''] = key.split(':')
+        revealed.push(`${rule}@${line}`)
+      }
+      verdicts.set(probe.slot, revealed.toSorted())
+    }
+    return verdicts
+  } finally {
+    for (const abs of written) {
+      try {
+        unlinkSync(abs)
+      } catch {
+        // The probe is a temp file basalt owns; a failed unlink must not mask the audit's verdict.
+      }
+    }
+  }
+}
+
+/**
+ * `check-theme --audit-allows` — list every active waiver and prove, per waiver, whether it still
+ * suppresses anything.
+ *
+ * The accountability release shipped `theme-allow-unscoped`, which reports a waiver that names no
+ * rule — but a waiver that is perfectly well written and covers a finding that no longer exists is
+ * invisible to it, and to everything else. Two consumers found five of those by hand, by editing
+ * the token out and re-running the guard. This is that method, automated: for each annotation the
+ * file is re-checked with THAT occurrence neutralized, and the findings that appear are exactly
+ * what it suppresses. Nothing is inferred from the annotation's text, so the audit cannot disagree
+ * with the scan — it IS the scan, run twice.
+ *
+ * `basalt.exemptRules` entries are audited the same way, one pattern at a time. That also answers
+ * the question the key could never answer for itself: a pattern that matches no scanned file (a
+ * real relative path, say, where the matcher takes whole path SEGMENTS) suppresses nothing and is
+ * reported as dead rather than passing silently.
+ *
+ * Exit 1 when anything is dead, so it can be wired into CI as a gate. A waiver nobody re-checks is
+ * how a rule quietly stops applying to the file that needed the exception most.
+ */
+export function auditAllows(
+  cwd: string,
+  cfg: BasaltConfig,
+  guardCfg: GuardConfig,
+  scanned: string[],
+): number {
+  const token = guardCfg.allowComment
+  const lines: string[] = [`\nbasalt-ui check-theme --audit-allows — ${cwd}\n`]
+  let dead = 0
+  let live = 0
+  let outOfReach = 0
+  let unaccountable = 0
+
+  // ── theme-allow annotations ─────────────────────────────────────────────────
+  const waiverLines: string[] = []
+  const pluginProbes: PluginProbe[] = []
+  const sources = new Map<string, string>()
+  for (const rel of scanned) sources.set(rel, readFileSync(resolve(cwd, rel), 'utf8'))
+
+  for (const rel of scanned) {
+    const text = sources.get(rel) ?? ''
+    if (!text.includes(token)) continue
+    const baseline = checkSource(text, rel, guardCfg)
+    const baselineKeys = new Set(
+      baseline.filter((f) => f.kind !== 'theme-allow-unscoped').map(findingKey),
+    )
+    const unscopedAt = new Map(
+      baseline.filter((f) => f.kind === 'theme-allow-unscoped').map((f) => [f.line, f.token]),
+    )
+    // Enumerated by the guard, never by a regex kept here: `findAllowAnnotations` shares its
+    // collector with `checkSource`, so the audit lists exactly the annotations the scan honours.
+    // The private mirror this replaced was already one comment shape behind.
+    for (const site of findAllowAnnotations(text, rel, guardCfg)) {
+      const revealed = checkSource(
+        neutralizeAllowAnnotation(text, site.line, guardCfg),
+        rel,
+        guardCfg,
+      )
+        .filter((f) => f.kind !== 'theme-allow-unscoped' && !baselineKeys.has(findingKey(f)))
+        .map((f) => `${f.kind}@${f.line}`)
+      const note = unscopedAt.get(site.line)
+      if (note !== undefined) unaccountable++
+      const label = `  ${rel}:${site.line}`.padEnd(52)
+      const suffix = note === undefined ? '' : ` [${note}]`
+      if (revealed.length > 0) {
+        live++
+        waiverLines.push(`${label} suppresses ${[...new Set(revealed)].join(', ')}${suffix}`)
+        continue
+      }
+      // Nothing in check-theme's reach moved. If the annotation names a PLUGIN rule, the oxlint
+      // half decides it — a placeholder holds the slot so the report stays in file/line order.
+      if (site.pluginRules.length > 0 && site.guardKinds.length === 0) {
+        pluginProbes.push({
+          slot: waiverLines.length,
+          rel,
+          line: site.line,
+          ids: site.pluginRules,
+          site: label,
+          suffix,
+        })
+        waiverLines.push('')
+        continue
+      }
+      if (site.guardKinds.length === 0 && site.unknownRules.length > 0) {
+        outOfReach++
+        waiverLines.push(
+          `${label} scoped to ${site.unknownRules.join(', ')} — names no guard kind and no ` +
+            'plugin rule, so this audit cannot judge it (most likely a typo, which ' +
+            `theme-allow-unscoped reports)${suffix}`,
+        )
+        continue
+      }
+      dead++
+      waiverLines.push(`${label} SUPPRESSES NOTHING — dead, delete it${suffix}`)
+    }
+  }
+
+  // ── the oxlint half — plugin-rule annotations, judged the same way ──────────
+  const pluginVerdicts = probePluginRules(cwd, guardCfg, pluginProbes, sources)
+  for (const probe of pluginProbes) {
+    const revealed = pluginVerdicts?.get(probe.slot)
+    if (revealed === undefined) {
+      outOfReach++
+      waiverLines[probe.slot] =
+        `${probe.site} scoped to ${probe.ids.join(', ')} — an oxlint plugin rule, and oxlint ` +
+        `could not be run here, so this audit cannot judge it${probe.suffix}`
+      continue
+    }
+    if (revealed.length > 0) {
+      live++
+      waiverLines[probe.slot] =
+        `${probe.site} suppresses ${revealed.join(', ')} (oxlint)${probe.suffix}`
+      continue
+    }
+    dead++
+    waiverLines[probe.slot] =
+      `${probe.site} SUPPRESSES NOTHING — dead, delete it (proved by re-running oxlint over the ` +
+      `file with this annotation neutralized)${probe.suffix}`
+  }
+
+  lines.push(`${token} annotations (${waiverLines.length}):`)
+  lines.push(...(waiverLines.length === 0 ? ['  (none)'] : waiverLines))
+
+  // ── basalt.exemptRules entries ──────────────────────────────────────────────
+  const exemptLines: string[] = []
+  let exemptCount = 0
+  const declared = Object.entries(cfg.exemptRules ?? {}) as [GuardKind, ExemptRuleEntry][]
+  if (declared.length > 0) {
+    const baselineKeys = new Set<string>()
+    for (const rel of scanned) {
+      for (const f of checkSource(sources.get(rel) ?? '', rel, guardCfg))
+        baselineKeys.add(findingKey(f))
+    }
+    for (const [kind, entry] of declared) {
+      const reason = exemptRuleReason(entry)
+      for (const pattern of exemptRulePaths(entry)) {
+        exemptCount++
+        const probeCfg: GuardConfig = {
+          ...guardCfg,
+          exemptRules: {
+            ...guardCfg.exemptRules,
+            [kind]: exemptRulePaths(entry).filter((p) => p !== pattern),
+          },
+        }
+        const revealed = new Set<string>()
+        for (const rel of scanned) {
+          for (const f of checkSource(sources.get(rel) ?? '', rel, probeCfg)) {
+            if (!baselineKeys.has(findingKey(f))) revealed.add(f.relPath)
+          }
+        }
+        const site = `  ${kind}: "${pattern}"`.padEnd(52)
+        const why = reason === null ? ' [no reason recorded]' : ` — ${reason}`
+        if (revealed.size === 0) {
+          dead++
+          const unmatched = unmatchedExemptPatterns(guardCfg, scanned).find(
+            (u) => u.kind === kind && u.pattern === pattern,
+          )
+          exemptLines.push(
+            `${site} SUPPRESSES NOTHING — ` +
+              (unmatched === undefined
+                ? 'the files it matches have no such finding; delete it'
+                : unmatched.reason === 'unknown-kind'
+                  ? 'it names no guard kind (a typo, or a renamed kind)'
+                  : 'it matches no scanned file at all') +
+              why,
+          )
+        } else {
+          live++
+          exemptLines.push(
+            `${site} suppresses findings in ${[...revealed].toSorted().join(', ')}${why}`,
+          )
+        }
+      }
+    }
+  }
+  lines.push(`\nbasalt.exemptRules entries (${exemptCount}):`)
+  lines.push(...(exemptLines.length === 0 ? ['  (none)'] : exemptLines))
+
+  lines.push(
+    `\n${live} live, ${dead} dead, ${outOfReach} unjudgeable, ${unaccountable} ` +
+      'unaccountable (reported as theme-allow-unscoped by a normal run).',
+  )
+  // The audit reads exactly what `check-theme` reads, and that is `scannableFiles` — which is
+  // WIDER than `basalt.roots`: it also takes each root's sibling `index.html` and `public/` tree
+  // (see appShellFiles) and anything named in `basalt.include`. Two consumers reported a live
+  // `public/site.webmanifest` waiver under a scope line saying files outside `roots` are not
+  // audited; the line was wrong, not the scan. Saying the scope out loud is the difference between
+  // "0 dead" and "0 dead, over these files" — so it has to name every class actually reached.
+  const includes = cfg.include ?? []
+  lines.push(
+    `Scope: the ${scanned.length} file(s) check-theme scans — everything under basalt.roots ` +
+      `(${resolveRoots(cfg).join(', ')}), plus each root's sibling index.html and public/ tree, ` +
+      (includes.length === 0
+        ? 'plus anything named in basalt.include (none). '
+        : `plus basalt.include (${includes.join(', ')}). `) +
+      'A waiver in a file none of those reach is not audited — widen roots, or name it in ' +
+      'basalt.include, or accept that nothing polices that file.',
+  )
+  if (dead > 0) {
+    lines.push(
+      'A dead waiver is not harmless: it is an exception nobody re-checked, and it will silently ' +
+        'cover the next real finding on that line.',
+    )
+  }
+  console.log(lines.join('\n'))
+  return dead > 0 ? 1 : 0
+}