rvlib-shipkit 0.35.8 → 0.36.0

package/src/fleet/scan-fleet.ts

@@ -0,0 +1,142 @@
+// The fleet: every repo on this disk that depends on the toolkit, and how far
+// behind each one is.
+//
+// Why a scan and not a registry: `local-projects.md` only holds repos whose
+// `docsBase` points at a wiki, which is 4 of the 10 that actually install the
+// libs. A repo that never reported is exactly the repo most likely to be
+// stale, so a registry is the wrong source for this question.
+//
+// This module DISCOVERS and REPORTS. It never updates: rule SK005 owns the
+// update, with the lease, the dirty-tree guard and the frozen guard that took
+// three bugs to get right. `--update` runs each repo's own `shipkit check`,
+// so the fix travels through that one code path.
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+
+export type Pkg = { name?: string; version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+
+export type FleetDep = {
+    name: string
+    /** the range in package.json, or `link:…` for a source-linked dep */
+    pin: string
+    /** what node_modules actually carries, null when nothing is installed */
+    installed: string | null
+    /** npm latest, null when the registry was not consulted or not reachable */
+    latest: string | null
+}
+
+/** a jump that changes the MAJOR, which is a porting job rather than a bump.
+ *
+ *  Deliberately NOT the semver rule. On a `0.x` package npm treats every
+ *  minor as breaking, and by that rule every repo here is breaking, including
+ *  the `0.24 → 0.35` shipkit jumps that rule SK005 already performs by itself
+ *  every day. A flag that fires on everything is a flag nobody reads. What
+ *  survives is the case a human has to own: `rvlib-pb-mobx 0.2.0 → 2.0.0`. */
+export function isBreaking(installed: string, latest: string): boolean {
+    const major = (v: string) => Number(v.split('-')[0]!.split('.')[0]) || 0
+    return major(installed) !== major(latest)
+}
+
+export type FleetRepo = {
+    name: string
+    dir: string
+    deps: FleetDep[]
+    /** a repo pointing at a checkout rather than a published version. Never
+     *  updated: the source IS the version, and that is a deliberate choice. */
+    linked: boolean
+    /** whether this repo can run the update itself (it has a shipkit binary) */
+    hasShipkit: boolean
+    behind: FleetDep[]
+    /** the subset of `behind` whose jump crosses a breaking boundary */
+    breaking: FleetDep[]
+}
+
+const readPkg = (dir: string): Pkg | null => {
+    const p = join(dir, 'package.json')
+    if (!existsSync(p)) return null
+    try {
+        return JSON.parse(readFileSync(p, 'utf8')) as Pkg
+    } catch {
+        return null
+    }
+}
+
+const installedVersion = (dir: string, name: string): string | null => readPkg(join(dir, 'node_modules', name))?.version ?? null
+
+/** semver-ish compare, enough to answer "is this one behind that one". A
+ *  prerelease tag sorts before its release, which is the safe direction: it
+ *  reports behind rather than pretending parity. */
+export function isBehind(installed: string, latest: string): boolean {
+    const part = (v: string) => v.split('-')[0]!.split('.').map((n) => Number(n) || 0)
+    const [a, b] = [part(installed), part(latest)]
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) < (b[i] ?? 0)) return true
+        if ((a[i] ?? 0) > (b[i] ?? 0)) return false
+    }
+    return installed.includes('-') && !latest.includes('-')
+}
+
+export function scanFleet(root: string, o: { prefix?: string } = {}): FleetRepo[] {
+    const prefix = o.prefix ?? 'rvlib-'
+    const out: FleetRepo[] = []
+    let entries: string[]
+    try {
+        entries = readdirSync(root)
+    } catch {
+        return out
+    }
+    for (const e of entries.sort()) {
+        if (e.startsWith('.')) continue
+        const dir = join(root, e)
+        try {
+            if (!statSync(dir).isDirectory()) continue
+        } catch {
+            continue
+        }
+        const pkg = readPkg(dir)
+        if (pkg == null) continue
+        const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
+        const names = Object.keys(all).filter((n) => n.startsWith(prefix))
+        if (names.length === 0) continue
+        const deps: FleetDep[] = names.sort().map((name) => ({ name, pin: all[name]!, installed: installedVersion(dir, name), latest: null }))
+        out.push({
+            name: e,
+            dir,
+            deps,
+            linked: deps.some((d) => d.pin.startsWith('link:') || d.pin.startsWith('file:')),
+            hasShipkit: existsSync(join(dir, 'node_modules', 'rvlib-shipkit', 'src', 'cli.ts')),
+            behind: [],
+            breaking: [],
+        })
+    }
+    return out
+}
+
+/** npm latest per PACKAGE, fetched once and shared across every repo that
+ *  depends on it. Ten repos on one lib is one request, not ten. */
+export async function resolveLatest(repos: FleetRepo[], fetchLatest: (name: string) => Promise<string | null>): Promise<Map<string, string | null>> {
+    const names = new Set<string>()
+    for (const r of repos) for (const d of r.deps) if (!d.pin.startsWith('link:') && !d.pin.startsWith('file:')) names.add(d.name)
+    const latest = new Map<string, string | null>()
+    await Promise.all(
+        [...names].map(async (n) => {
+            try {
+                latest.set(n, await fetchLatest(n))
+            } catch {
+                latest.set(n, null)
+            }
+        }),
+    )
+    for (const r of repos) {
+        for (const d of r.deps) d.latest = latest.get(d.name) ?? null
+        r.behind = r.deps.filter((d) => d.installed != null && d.latest != null && isBehind(d.installed, d.latest))
+        r.breaking = r.behind.filter((d) => isBreaking(d.installed!, d.latest!))
+    }
+    return latest
+}
+
+export async function npmLatest(name: string): Promise<string | null> {
+    const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(10_000) })
+    if (!res.ok) return null
+    return ((await res.json()) as Pkg).version ?? null
+}

package/src/git-bootstrap.ts

@@ -101,7 +101,7 @@ const samePath = (a: string, b: string): boolean => {
     }
 }
 
-type RepoView = { nameWithOwner?: string; isPrivate?: boolean; url?: string; sshUrl?: string }
+type RepoView = { nameWithOwner?: string; isPrivate?: boolean; sshUrl?: string }
 
 /** phase one: this dir IS a git work tree root. false means the caller must
  *  not publish anything (a subdirectory of another repo, or git refused), and
@@ -194,7 +194,7 @@ export async function publishRepo(root: string, opts: PublishOpts = {}): Promise
     const login = firstGhLine(user.out)
     if (!NAME_RE.test(login)) return void p(`WARN no remote wired: gh did not answer with a login (${login})`)
     const target = `${login}/${name}`
-    const viewArgs = ['repo', 'view', target, '--json', 'nameWithOwner,isPrivate,url,sshUrl']
+    const viewArgs = ['repo', 'view', target, '--json', 'nameWithOwner,isPrivate,sshUrl']
 
     let view = await gh(viewArgs)
     let created = false
@@ -217,9 +217,15 @@ export async function publishRepo(root: string, opts: PublishOpts = {}): Promise
     }
 
     const info = carveGhJson<RepoView>(view.out)
-    const proto = await gh(['config', 'get', 'git_protocol'])
-    const url = (firstGhLine(proto.out) === 'ssh' ? info?.sshUrl : info?.url) ?? info?.url ?? info?.sshUrl
-    if (url == null) return void p(`WARN no remote wired: gh answer unreadable (${firstGhLine(view.out)})`)
+    // ALWAYS the ssh url gh gave, never the https one and never `gh config
+    // get git_protocol`: an https origin re-asks for a credential on every
+    // push, and a machine answering `https` there wires a remote that reports
+    // success and fails at the first push. An answer carrying no sshUrl is
+    // unreadable, not an invitation to build one: this module knows no host,
+    // and a guessed `github.com` remote against an enterprise gh is the same
+    // silent failure one host over
+    const url = info?.sshUrl
+    if (url == null) return void p(`WARN no remote wired: gh answered without an ssh url (${firstGhLine(view.out)})`)
 
     const add = await git(['remote', 'add', 'origin', url])
     if (add.code !== 0) return void p(`WARN no remote wired: git remote add failed (${firstGhLine(add.out)})`)

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(', ')