rvlib-shipkit 0.35.8 → 0.37.0

package/src/hooks/run-hooks.ts

@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { commitMessageOffenses } from './commit-message.ts'
-import { globalKeywordFile, maskPattern, runLeakGuard } from './leak-guard.ts'
+import { globalAllowFile, globalKeywordFile, maskPattern, patternFingerprint, runLeakGuard, type LeakAllowEntry, type LeakHit, type LeakWaiver } from './leak-guard.ts'
 import { runRootIdentity } from './root-identity.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -21,6 +21,14 @@ export type HooksConfig = {
     commitMsg?: { id: string; cmd: string[] }[]
     /** keyword file for the leak guard (default '.rv-private/banned-keywords.txt') */
     keywordFile?: string
+    /** known-good leak-guard matches this repo waives: a lockfile whose
+     *  dependency names or integrity hashes collide with a keyword is the
+     *  motivating case. Each entry carries a reason, and a waiver that fires
+     *  PRINTS, so nothing passes silently. This file is tracked, so an entry
+     *  names a pattern by fingerprint (`fp:…`, printed beside every hit) and
+     *  never by value. The machine-global twin is ~/.rv-private/leak-allow.json.
+     *  hooks/leak-guard.ts */
+    leakAllow?: LeakAllowEntry[]
     /** staged-path prefixes that may never enter git (local state like
      *  '.comfy-ts/'). gitignore is advisory and editable; this gate is not. */
     blockedPaths?: string[]
@@ -148,6 +156,29 @@ function seedKeywordFile(root: string, keywordFile?: string): string | null {
 
 export type GateOutcome = { id: string; ok: boolean; lines: string[] }
 
+/** a hit line: the masked pattern plus its FINGERPRINT, which is the token a
+ *  waiver is written against, so nobody has to type the private word to
+ *  exempt it. The file rides along for a content hit; a staged-PATH hit adds
+ *  nothing, because there the path IS what matched. */
+const hitLine = (x: LeakHit): string =>
+    `      ${x.where}${x.where === 'staged content' && x.file != null ? ` ${x.file}` : ''}: ${maskPattern(x.pattern)} [${patternFingerprint(x.pattern)}]`
+
+/** what the allowlist let through, one line per waiver. An allowlist that
+ *  fires invisibly is a silent weakening, so a waived match is as loud as a
+ *  blocked one and carries the reason its author wrote. */
+function waivedLines(waived: LeakWaiver[]): string[] {
+    const rows = new Map<string, { pattern: string; reason: string; source: string; targets: Set<string> }>()
+    for (const w of waived) {
+        const key = `${w.pattern} ${w.source}`
+        const row = rows.get(key) ?? { pattern: w.pattern, reason: w.reason, source: w.source, targets: new Set<string>() }
+        row.targets.add(w.file ?? w.where)
+        rows.set(key, row)
+    }
+    return [...rows.values()].map(
+        (r) => `      waived ${maskPattern(r.pattern)} [${patternFingerprint(r.pattern)}] in ${r.targets.size} target(s) — ${r.reason} (${r.source})`,
+    )
+}
+
 /** the pre-commit gate: built-in leak guard, then the repo's own commands.
  *  A commit takes ~1s (build/shipkit.md): the gate times itself, and going
  *  over budget WARNs naming the fix, so drift back to slow commits is loud. */
@@ -156,16 +187,27 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
     const h = config.hooks ?? {}
     const out: GateOutcome[] = []
     if (!(h.disable ?? []).includes('leak-guard')) {
-        const r = runLeakGuard(root, { keywordFile: h.keywordFile })
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile, allow: h.leakAllow })
         if (r.status === 'skipped') out.push({ id: 'leak-guard', ok: true, lines: [`skip: leak-guard (${r.reason})`] })
-        else if (r.status === 'clean') out.push({ id: 'leak-guard', ok: true, lines: [`ok: leak-guard clean (${r.patterns} pattern(s))`] })
+        else if (r.status === 'clean') out.push({
+            id: 'leak-guard',
+            ok: true,
+            lines: [
+                `ok: leak-guard clean (${r.patterns} pattern(s)${r.waived.length === 0 ? '' : `, ${r.waived.length} waived`})`,
+                ...waivedLines(r.waived),
+                ...r.notes.map((n) => `      WARN ${n}`),
+            ],
+        })
         else out.push({
             id: 'leak-guard',
             ok: false,
             lines: [
                 `FAIL: leak-guard matched ${r.hits.length} banned pattern(s) — this commit would leak private content`,
-                ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`),
+                ...r.hits.map(hitLine),
+                ...waivedLines(r.waived),
+                ...r.notes.map((n) => `      WARN ${n}`),
                 `      fix: remove the content, or edit the keyword file if the pattern is wrong`,
+                `      a known-good match: repo.config.ts hooks.leakAllow += { reason, paths, patterns: ['<the fp: above>'] }`,
             ],
         })
     }
@@ -242,9 +284,11 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
     // the leak guard also reads the MESSAGE, a private name pasted into a
     // commit body is as public as one pasted into a file
     if (!(h.disable ?? []).includes('leak-guard')) {
-        const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, text: [{ label: 'commit message', content: message }] })
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, allow: h.leakAllow, text: [{ label: 'commit message', content: message }] })
         if (r.status === 'hit')
-            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`)] })
+            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map(hitLine), ...waivedLines(r.waived)] })
+        else if (r.status === 'clean' && r.waived.length > 0)
+            out.push({ id: 'leak-guard', ok: true, lines: [`ok: leak-guard clean in the commit message (${r.waived.length} waived)`, ...waivedLines(r.waived)] })
     }
     for (const c of h.commitMsg ?? []) {
         const r = await spawnWithTimeout([...c.cmd, messageFile], { cwd: root, timeoutMs: 60_000 })
@@ -265,8 +309,12 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
     // a gate listed as active but unable to fire is worse than no listing:
     // this surface exists so nobody has to guess
     const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) || globalKeywordFile() != null ? '' : ` (INACTIVE, ${kw} absent and no ~/.rv-private list)`
+    // a waiver nobody can enumerate is a hole nobody can audit: the count of
+    // declared exemptions belongs on the same surface as the gate itself
+    const waivers = (h.leakAllow ?? []).length + (globalAllowFile() != null ? 1 : 0)
+    const leakAllowState = waivers === 0 ? '' : `, ${(h.leakAllow ?? []).length} repo waiver(s)${globalAllowFile() == null ? '' : ' + ~/.rv-private/leak-allow.json'}`
     return [
-        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt`,
+        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt${leakAllowState}`,
         ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),

package/src/ledger/gate-units.ts

@@ -40,44 +40,97 @@ export function tieredTasks(c: RepoConfig, root: string, tier: TestTier): TaskDe
  *  built from the unmodified list would let a quick run replay into a full one
  *  under one identity. */
 export function gateUnits(root: string, c: RepoConfig, tasks?: TaskDef[]): UnitDecl[] {
-    const out: UnitDecl[] = []
+    return gateInventory(root, c, tasks).map((r) => r.decl)
+}
+
+/** one gate unit with everything a reader asks about it, not only what the
+ *  key layer asks. The cache half stays in `decl` so `UnitDecl` never grows
+ *  fields the key layer must then decide to ignore. */
+export type UnitRow = {
+    decl: UnitDecl
+    /** the display name an operator reads (a rule's title, else the id) */
+    title: string
+    /** does `shipkit ci` run it? false = PROACTIVE: `shipkit check` reports it,
+     *  the gate never does, and it may sit red for months without anything
+     *  being wrong with the change in front of you. */
+    gate: boolean
+    /** can a failure stop you? null = the unit never said AND the repo set no
+     *  `checkDefaults.blocking`, which the check runner treats as fatal. */
+    blocking: boolean | null
+    /** where the answer is owned: a rule's wiki page, a check's file, a task's
+     *  command. Null when the unit names none. */
+    owner: string | null
+    /** the group a task was filed under, for the few that declare one */
+    group: string | null
+    /** excluded from a default run unless named with `--with` */
+    optIn: boolean
+}
+
+/** every unit the gate knows, with its metadata. `gateUnits` is this list
+ *  narrowed to the cache declaration, so the three registries are walked in
+ *  exactly one place and a surface can never enumerate a different set than
+ *  the one the key layer keyed. */
+export function gateInventory(root: string, c: RepoConfig, tasks?: TaskDef[]): UnitRow[] {
+    const out: UnitRow[] = []
     for (const t of tasks ?? allTasks(c, root).tasks) {
         out.push({
-            id: t.id,
-            kind: 'task',
-            inputs: t.inputs,
-            ttl: t.ttl,
-            never: t.never,
-            argv: t.cmd,
-            // the env a task SETS is part of what it runs, not something read
-            // off the ambient environment, so it rides as an identity string
-            extra: t.env == null ? undefined : JSON.stringify(Object.entries(t.env).sort()),
+            decl: {
+                id: t.id,
+                kind: 'task',
+                inputs: t.inputs,
+                ttl: t.ttl,
+                never: t.never,
+                argv: t.cmd,
+                extra: t.env == null ? undefined : JSON.stringify(Object.entries(t.env).sort()),
+            },
+            title: t.id,
+            // an optIn task is off the default run, which is the same shape as
+            // a check that opted out of the gate
+            gate: t.optIn !== true,
+            // a task IS the build: it has no non-blocking mode to declare
+            blocking: true,
+            owner: t.cmd == null ? null : t.cmd.join(' '),
+            group: t.group ?? null,
+            optIn: t.optIn === true,
         })
     }
     for (const r of [...RULES, ...(c.rules ?? [])]) {
         out.push({
-            id: r.id,
-            kind: 'rule',
-            inputs: r.inputs,
-            code: r.code,
-            ttl: r.ttl,
-            never: r.never,
-            extra: r.cacheKey?.({ root, config: c }),
+            decl: {
+                id: r.id,
+                kind: 'rule',
+                inputs: r.inputs,
+                code: r.code,
+                ttl: r.ttl,
+                never: r.never,
+                extra: r.cacheKey?.({ root, config: c }),
+            },
+            title: r.title,
+            gate: true,
+            blocking: r.blocking,
+            owner: r.owner,
+            group: null,
+            optIn: false,
         })
     }
     for (const d of discoverChecks(root)) {
         const rel = relative(root, d.path).replace(/\\/g, '/')
         out.push({
-            id: d.name,
-            kind: 'check',
-            inputs: d.inputs ?? undefined,
-            ttl: d.ttl ?? undefined,
-            never: d.never ?? undefined,
-            // a check IS a file, so its own code needs no declaration: the
-            // module graph walks from here through every helper it imports,
-            // which is what makes fixing a shared helper move the check's key
-            code: [rel],
-            argv: ['bun', rel],
+            decl: {
+                id: d.name,
+                kind: 'check',
+                inputs: d.inputs ?? undefined,
+                ttl: d.ttl ?? undefined,
+                never: d.never ?? undefined,
+                code: [rel],
+                argv: ['bun', rel],
+            },
+            title: d.name,
+            gate: d.gate,
+            blocking: d.blocking ?? c.checkDefaults?.blocking ?? null,
+            owner: rel,
+            group: null,
+            optIn: false,
         })
     }
     return out

package/src/ledger/store.ts

@@ -44,6 +44,11 @@ export type Stored<T> = {
     key: string
     /** when it was written, ms since epoch */
     at: number
+    /** how long THIS entry stays valid, when that is shorter than the unit's
+     *  declared TTL. A measured negative writes one, so a red about the world
+     *  clears soon after a human fixes the world, while a clean answer keeps
+     *  for the full declared window. Absent means the declared TTL. */
+    keeps?: number
     payload: T
 }
 
@@ -87,10 +92,10 @@ export function readStored<T>(path: string, key: string): Stored<T> | null {
     } catch { return null }
 }
 
-export function writeStored<T>(path: string, key: string, payload: T, at: number): void {
+export function writeStored<T>(path: string, key: string, payload: T, at: number, keeps?: number): void {
     try {
         mkdirSync(dirname(path), { recursive: true })
-        atomicWrite(path, JSON.stringify({ v: STORE_VERSION, key, at, payload }))
+        atomicWrite(path, JSON.stringify({ v: STORE_VERSION, key, at, keeps, payload }))
     } catch {
         // a store that cannot be written is slow, never wrong: the answer was
         // already printed, and the next run measures again

package/src/ledger/unit-table.ts

@@ -0,0 +1,105 @@
+// THE inventory render — every gate unit as one markdown row, so the question
+// "what runs here, does it block me, and how often does it really run" has a
+// surface that is read rather than reconstructed from three commands.
+//
+// Deliberately carries NO live run state: no timestamps, no key hashes, no
+// last verdict. Everything here is what a unit DECLARED about itself, so two
+// runs a week apart over an unchanged repo write identical bytes and the file
+// never churns. It is still generated, gitignored AND untracked like STATUS.md
+// (rules/untrack-generated.ts), so it is read on disk, never in git history.
+// Live keys are `shipkit keys`, live verdicts are STATUS.md.
+import { join } from 'path'
+import { atomicWrite, withFileLock } from '../core/locked-write.ts'
+import { classify } from './git-key.ts'
+import type { UnitRow } from './gate-units.ts'
+
+/** the sidecar every gate run refreshes beside STATUS.md */
+export const UNIT_TABLE_FILE = 'STATUS.full.md'
+
+/** a cell can never break the table it sits in */
+const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\n/g, ' ')
+
+export type UnitTableInput = {
+    /** repo name, for the headline */
+    name: string
+    rows: UnitRow[]
+}
+
+/** what a unit's cache declaration means for how often it actually runs */
+function cacheOf(r: UnitRow): { population: string; ttl: string; reads: string; why: string } {
+    const c = classify(r.decl)
+    const inputs = r.decl.inputs ?? []
+    if (c.error != null) return { population: 'BROKEN', ttl: '', reads: '', why: c.error }
+    if (c.population === 'content') return { population: 'content', ttl: '', reads: inputs.join(', '), why: '' }
+    // no `reads` for these two: the cache column already says "world"/"never",
+    // and restating it on every such row is a column of noise
+    if (c.population === 'world') return { population: 'world', ttl: r.decl.ttl ?? '', reads: '', why: '' }
+    if (c.decided === true) return { population: 'never', ttl: '', reads: '', why: r.decl.never ?? '' }
+    return { population: 'UNDECLARED', ttl: '', reads: '', why: 'nobody has declared what this reads, so it re-runs every single time' }
+}
+
+export function renderUnitTable(input: UnitTableInput): string {
+    const { name, rows } = input
+    const counts = { task: 0, rule: 0, check: 0 }
+    for (const r of rows) counts[r.decl.kind]++
+
+    const body: string[] = []
+    body.push(`<!-- generated by \`shipkit units\`, refreshed by every gate run, gitignored (SK004) -->`)
+    body.push(`# ${name} units — ${rows.length} total`)
+    body.push('')
+    body.push(`Everything \`shipkit ci\` and \`shipkit check\` know how to run: ${counts.task} task(s), ${counts.rule} rule(s), ${counts.check} discovered check(s).`)
+    body.push('')
+    body.push('- **runs in** — `gate` means `shipkit ci` runs it, so a red one says THIS change is broken. `proactive` means only `shipkit check` runs it: it reports the world (a box that is off, a cred nobody minted, a page nobody refreshed), it can sit red for months with nothing wrong, and it never stands between you and a commit.')
+    body.push('- **on failure** — `blocks` stops the run. `warns` prints and carries on. `UNDECLARED` is a defect, not a setting: the unit never said and the repo set no default, so the runner treats it as fatal by guess.')
+    body.push('- **cache** — `content` replays while the files it reads are untouched. `world` replays for its TTL, and a measured RED replays too, capped at one hour so the run after a fix sees the fix. `never` re-runs every time and somebody wrote down why. `UNDECLARED` re-runs every time and nobody has looked yet, which is the burn-down (`shipkit keys --burn-down`). `SHIPKIT_FRESH=1` busts all of it.')
+    const proactive = rows.filter((r) => !r.gate && !r.optIn).length
+    const warns = rows.filter((r) => r.blocking === false).length
+    const neverSaid = rows.filter((r) => r.blocking == null).length
+    const undeclared = rows.filter((r) => cacheOf(r).population === 'UNDECLARED')
+    body.push('')
+    // the most useful line in the file, so it sits ABOVE the 68 rows rather
+    // than under them
+    body.push(
+        `**${rows.length - proactive} in the gate, ${proactive} proactive · ${warns} warn instead of blocking${neverSaid > 0 ? `, ${neverSaid} never said` : ''} · ${undeclared.length} uncacheable with nobody having looked.**`,
+    )
+    body.push('')
+    body.push('| unit | kind | runs in | on failure | cache | ttl | reads | owner |')
+    body.push('|---|---|---|---|---|---|---|---|')
+    for (const r of rows) {
+        const c = cacheOf(r)
+        const blocking = r.blocking == null ? '**UNDECLARED**' : r.blocking ? 'blocks' : 'warns'
+        const runsIn = r.optIn ? 'opt-in' : r.gate ? 'gate' : 'proactive'
+        const population = c.population === 'UNDECLARED' ? '**UNDECLARED**' : c.population
+        body.push(
+            `| \`${cell(r.decl.id)}\` | ${r.decl.kind} | ${runsIn} | ${blocking} | ${population} | ${cell(c.ttl)} | ${cell(c.reads)} | ${r.owner == null ? '' : `\`${cell(r.owner)}\``} |`,
+        )
+    }
+    body.push('')
+
+    const decided = rows.filter((r) => cacheOf(r).population === 'never')
+    if (undeclared.length > 0) {
+        body.push(`## ${undeclared.length} unit(s) nothing can cache yet`)
+        body.push('')
+        body.push('Each of these runs on every single pass. Declaring `inputs` (it reads files), `ttl` (it reads the world) or `never` (nothing can describe it) is the fix, and the last one counts: a written reason is a decision, not a hole.')
+        body.push('')
+        for (const r of undeclared) body.push(`- \`${cell(r.decl.id)}\` (${r.decl.kind})${r.owner == null ? '' : ` — \`${cell(r.owner)}\``}`)
+        body.push('')
+    }
+    if (decided.length > 0) {
+        body.push(`## ${decided.length} unit(s) decided uncacheable`)
+        body.push('')
+        for (const r of decided) body.push(`- \`${cell(r.decl.id)}\` — ${cell(r.decl.never ?? '')}`)
+        body.push('')
+    }
+
+    return body.join('\n')
+}
+
+/** refresh the sidecar beside STATUS.md. Lock-guarded exactly like STATUS.md:
+ *  several runners in one checkout is the normal case, and the loser skipping
+ *  a render it would have written identically costs nothing. */
+export function writeUnitTable(root: string, input: UnitTableInput): { written: boolean; warn?: string } {
+    const target = join(root, UNIT_TABLE_FILE)
+    const r = withFileLock(target, () => { atomicWrite(target, `${renderUnitTable(input).trimEnd()}\n`) })
+    return r.ok ? { written: true } : { written: false, warn: `${UNIT_TABLE_FILE} locked by another runner — skipped this write` }
+}

package/src/prose/run-prose.ts

@@ -0,0 +1,146 @@
+// `shipkit prose` — the file-walking half of the STE checker. The judgement
+// lives in ste.ts; this module resolves WHICH files a repo puts in scope,
+// prints the wire lines, and applies the mechanical fixes.
+//
+// Scope is repo knowledge, never a hardcoded path list: a repo declares
+// `prose: { include, exempt }` in repo.config.ts. A repo that declares
+// nothing is not checked, and the rule says so instead of failing a repo
+// that never opted in.
+import { readFileSync, statSync } from 'fs'
+import { isAbsolute, join, relative, resolve } from 'path'
+import { atomicWrite } from '../core/locked-write.ts'
+import { checkProse, fixProse, tierOf, type ProseClass, type ProseHit, type ProseTier } from './ste.ts'
+
+export type ProseConfig = {
+    /** globs (repo-relative) that ARE house prose. Absent = the repo is not checked. */
+    include?: string[]
+    /** globs never checked: journals, archives, upstream snapshots, generated files */
+    exempt?: string[]
+    /** classes this repo does not check, with the reason living in repo.config.ts */
+    allow?: ProseClass[]
+    /** the 20-word procedural limit instead of the 25-word descriptive one */
+    strict?: boolean
+    /** soft-tier ratchet: the count this repo is allowed to carry. The gate
+     *  fails ABOVE it, so the number can only go down. Absent is the default,
+     *  and it means soft hits warn in `shipkit prose` and never reach a gate
+     *  or an attention surface. A four-digit count nobody can act on is worse
+     *  than no number at all. */
+    baseline?: number
+}
+
+export type FileReport = { file: string; hits: ProseHit[] }
+
+export type ProseReport = {
+    files: number
+    hits: ProseHit[]
+    byFile: FileReport[]
+    byTier: Record<ProseTier, number>
+    byClass: Record<string, number>
+    fixable: number
+    /** files rewritten by a --fix run */
+    fixed: string[]
+    scoped: boolean // did this repo declare any include globs?
+}
+
+const DEFAULT_EXEMPT = ['**/node_modules/**', '**/CHANGELOG.md', '**/dist/**', '**/.git/**']
+
+/** a generated file is not house prose, and rewriting it loses the change on
+ *  the next render */
+const isGenerated = (text: string): boolean => text.slice(0, 400).includes('<!-- generated')
+
+/** an explicitly named path, resolved against the repo and REFUSED when it
+ *  lands outside: `--fix` writes, and a checker that rewrites files outside
+ *  the repo it was pointed at is a much worse tool than one that says no. */
+export function explicitPath(root: string, p: string): string {
+    const abs = isAbsolute(p) ? p : resolve(root, p)
+    const rel = relative(root, abs)
+    if (rel === '' || rel.startsWith('..')) throw new Error(`FAIL ${p} is outside ${root} — shipkit prose only reads and writes inside the repo`)
+    return rel
+}
+
+export function proseFiles(root: string, cfg: ProseConfig): string[] {
+    const include = cfg.include ?? []
+    if (include.length === 0) return []
+    const exempt = [...DEFAULT_EXEMPT, ...(cfg.exempt ?? [])].map((g) => new Bun.Glob(g))
+    const seen = new Set<string>()
+    for (const pattern of include)
+        for (const f of new Bun.Glob(pattern).scanSync({ cwd: root, onlyFiles: true, dot: false })) {
+            const rel = f.split('\\').join('/')
+            if (exempt.some((g) => g.match(rel))) continue
+            seen.add(rel)
+        }
+    return [...seen].sort()
+}
+
+export function runProseCheck(o: { root: string; config: ProseConfig; paths?: string[]; fix?: boolean }): ProseReport {
+    const cfg = o.config
+    const files = o.paths != null && o.paths.length > 0 ? o.paths.map((p) => explicitPath(o.root, p)) : proseFiles(o.root, cfg)
+    const explicit = o.paths != null && o.paths.length > 0
+    const opts = { allow: cfg.allow, strict: cfg.strict }
+    const byFile: FileReport[] = []
+    const hits: ProseHit[] = []
+    const fixed: string[] = []
+    for (const rel of files) {
+        const abs = join(o.root, rel)
+        let text: string
+        try {
+            text = readFileSync(abs, 'utf8')
+        } catch (e) {
+            // a path a HUMAN typed that cannot be read is a loud failure. A
+            // path the glob produced can vanish between the scan and the read,
+            // and skipping that one is right.
+            if (explicit) throw new Error(`FAIL cannot read ${rel} — ${String(e)}`)
+            continue
+        }
+        if (isGenerated(text)) continue
+        if (o.fix === true) {
+            const out = fixProse(text, opts)
+            if (out.applied > 0) {
+                atomicWrite(abs, out.text)
+                fixed.push(rel)
+                text = out.text
+            }
+        }
+        const fh = checkProse(text, opts)
+        if (fh.length > 0) byFile.push({ file: rel, hits: fh })
+        hits.push(...fh)
+    }
+    const byTier: Record<ProseTier, number> = { fix: 0, hard: 0, soft: 0 }
+    const byClass: Record<string, number> = {}
+    for (const h of hits) {
+        byTier[h.tier]++
+        byClass[h.cls] = (byClass[h.cls] ?? 0) + 1
+    }
+    return {
+        files: files.length,
+        hits,
+        byFile,
+        byTier,
+        byClass,
+        fixable: hits.filter((h) => h.fix != null).length,
+        fixed,
+        scoped: (cfg.include ?? []).length > 0,
+    }
+}
+
+/** one line per hit, capped: a first STE pass on a real repo finds hundreds,
+ *  and a wall of them hides the mechanical ones that `--fix` clears in a
+ *  second. The per-class totals below the cap keep the report complete. */
+export function proseLines(r: ProseReport, o: { cap?: number; tiers?: ProseTier[] } = {}): string[] {
+    const cap = o.cap ?? 25
+    const tiers = new Set(o.tiers ?? (['fix', 'hard', 'soft'] as ProseTier[]))
+    const shown = r.hits.filter((h) => tiers.has(h.tier))
+    const out: string[] = []
+    const fileOf = new Map<ProseHit, string>()
+    for (const f of r.byFile) for (const h of f.hits) fileOf.set(h, f.file)
+    for (const h of shown.slice(0, cap))
+        out.push(`${fileOf.get(h) ?? '?'}:${h.line} [${h.cls}] ${JSON.stringify(h.text.trim())} — ${h.why}${h.fix != null ? ` (--fix writes ${JSON.stringify(h.fix.trim())})` : ''}`)
+    if (shown.length > cap) out.push(`… and ${shown.length - cap} more`)
+    return out
+}
+
+export const classSummary = (r: ProseReport): string =>
+    Object.entries(r.byClass)
+        .sort((a, b) => b[1] - a[1])
+        .map(([c, n]) => `${c} ${n}${tierOf(c as ProseClass) === 'soft' ? '' : '!'}`)
+        .join(', ')