rvlib-shipkit 0.38.1 → 1.0.0

package/src/problems/extract.ts

@@ -0,0 +1,182 @@
+// file:line findings out of what a check printed, one function per format the
+// floor meets: tsc, oxlint (both its piped and its graphical output), eslint's
+// stylish output, a failing bun test, and a shipkit wire line naming a file.
+// Every one feeds the one Problem shape (problem-line.ts).
+//
+// a finding the source cannot anchor in a file is dropped rather than pinned
+// to a guess: the pane is for things an edit can fix, and the check's own
+// page still carries every line it printed.
+import { existsSync } from 'fs'
+import { isAbsolute, relative, resolve } from 'path'
+import type { Line } from '../core/wire.ts'
+import type { Problem, Severity } from './problem-line.ts'
+
+export type ExtractCtx = {
+    /** the repo root every file is made relative to */
+    root: string
+    /** where the tool ran, for the relative paths it printed (default: root) */
+    cwd?: string
+    /** the check id each finding is filed under */
+    check: string
+    /** is this file there? Injected so a fixture needs no tree on disk */
+    exists?: (abs: string) => boolean
+}
+
+const stripAnsi = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, '').replace(/\r/g, '')
+
+/** repo-relative, forward slashes. null when the path is not a file this
+ *  repo has, which is what keeps a url or a `host:port` out of the pane */
+function repoFile(ctx: ExtractCtx, raw: string, mustExist: boolean): string | null {
+    const p = raw.trim().replace(/^file:\/\//, '')
+    if (p === '') return null
+    const abs = isAbsolute(p) ? p : resolve(ctx.cwd ?? ctx.root, p)
+    const rel = relative(ctx.root, abs).replace(/\\/g, '/')
+    if (rel === '' || rel.startsWith('../') || isAbsolute(rel)) return null
+    if (mustExist && !(ctx.exists ?? existsSync)(abs)) return null
+    return rel
+}
+
+const TSC = /^(.+?)\((\d+),(\d+)\): (error|warning) (TS\d+): (.*)$/
+
+/** `src/a.ts(3,7): error TS2322: msg`, and the indented elaboration lines
+ *  under it, joined into the one message */
+export function fromTsc(text: string, ctx: ExtractCtx): Problem[] {
+    const out: Problem[] = []
+    let last: Problem | null = null
+    let depth = 0
+    const indent = (s: string): number => /^\s*/.exec(s)![0].length
+    for (const raw of stripAnsi(text).split('\n')) {
+        const m = TSC.exec(raw)
+        if (m != null) {
+            const file = repoFile(ctx, m[1]!, false)
+            last = file == null ? null : { file, line: Number(m[2]), col: Number(m[3]), severity: m[4] as Severity, check: ctx.check, message: `${m[5]} ${m[6]!.trim()}` }
+            depth = indent(raw)
+            if (last != null) out.push(last)
+            continue
+        }
+        // an elaboration sits deeper than the diagnostic it belongs to
+        if (last != null && raw.trim() !== '' && indent(raw) > depth) last.message += ` ${raw.trim()}`
+        else last = null
+    }
+    return out
+}
+
+const OXLINT_PIPED = /^(.+?):(\d+):(\d+): (error|warning) (\S+?): (.*)$/
+const OXLINT_HEAD = /^\s*(x|!|×|⚠)\s+(.+)$/
+const OXLINT_AT = /^\s*(?:,-|╭─)\[(.+):(\d+):(\d+)\]\s*$/
+
+/** oxlint piped (`src/a.ts:1:7: warning eslint(no-unused-vars): msg`, what
+ *  the gate sees) and graphical (a `x rule: msg` head, then `,-[file:l:c]`) */
+export function fromOxlint(text: string, ctx: ExtractCtx): Problem[] {
+    const out: Problem[] = []
+    let head: { severity: Severity; message: string } | null = null
+    for (const raw of stripAnsi(text).split('\n')) {
+        const piped = OXLINT_PIPED.exec(raw)
+        if (piped != null && /\(|\//.test(piped[5]!)) {
+            const file = repoFile(ctx, piped[1]!, false)
+            if (file != null) out.push({ file, line: Number(piped[2]), col: Number(piped[3]), severity: piped[4] as Severity, check: ctx.check, message: `${piped[5]} ${piped[6]!.replace(/\s+help: .*$/, '').trim()}` })
+            continue
+        }
+        const h = OXLINT_HEAD.exec(raw)
+        if (h != null) { head = { severity: h[1] === 'x' || h[1] === '×' ? 'error' : 'warning', message: h[2]!.trim() }; continue }
+        const at = OXLINT_AT.exec(raw)
+        if (at != null && head != null) {
+            const file = repoFile(ctx, at[1]!, false)
+            if (file != null) out.push({ file, line: Number(at[2]), col: Number(at[3]), severity: head.severity, check: ctx.check, message: head.message })
+            head = null
+        }
+    }
+    return out
+}
+
+const ESLINT_HEAD = /^(?:\/|[A-Za-z]:\\)[^:()]*\.\w+\s*$/
+const ESLINT_ROW = /^\s+(\d+):(\d+)\s+(error|warning)\s+(.*?)(?:\s{2,}(\S+))?\s*$/
+
+/** eslint stylish: a file path alone on its line, then `  2:7  error  msg  rule` */
+export function fromEslint(text: string, ctx: ExtractCtx): Problem[] {
+    const out: Problem[] = []
+    let file: string | null = null
+    for (const raw of stripAnsi(text).split('\n')) {
+        if (raw.trim() === '') { file = null; continue }
+        // stylish always prints the header as an absolute path, alone
+        if (!/^\s/.test(raw)) { file = ESLINT_HEAD.test(raw) ? repoFile(ctx, raw, false) : null; continue }
+        const m = ESLINT_ROW.exec(raw)
+        if (m == null || file == null) continue
+        const rule = m[5] == null ? '' : `${m[5]} `
+        out.push({ file, line: Number(m[1]), col: Number(m[2]), severity: m[3] as Severity, check: ctx.check, message: `${rule}${m[4]!.trim()}` })
+    }
+    return out
+}
+
+const BUN_SUITE = /^(\S.*\.(?:test|spec)\.[cm]?[jt]sx?):$/
+const BUN_ERROR = /^(?:error|\w*Error): (.*)$/
+const BUN_FRAME = /^\s+at .*?\(?((?:\/|[A-Za-z]:\\|\.{0,2}\/?[\w@.-]+\/)[^()]*?):(\d+):(\d+)\)?\s*$/
+const BUN_FAIL = /^\(fail\) (.+?)(?: \[[\d.]+m?s\])?$/
+
+/** a failing bun test: the `error:` line, the first stack frame inside this
+ *  repo and outside node_modules, and the `(fail) name` line that closes it.
+ *  With no frame in the repo it anchors at line 1 of the suite file */
+export function fromBunTest(text: string, ctx: ExtractCtx): Problem[] {
+    const out: Problem[] = []
+    let suite: string | null = null
+    let error: string | null = null
+    let at: { file: string; line: number; col: number } | null = null
+    for (const raw of stripAnsi(text).split('\n')) {
+        const s = BUN_SUITE.exec(raw)
+        if (s != null) { suite = repoFile(ctx, s[1]!, false); error = null; at = null; continue }
+        const e = BUN_ERROR.exec(raw)
+        if (e != null) { error = e[1]!.trim(); at = null; continue }
+        const f = BUN_FRAME.exec(raw)
+        if (f != null && error != null && at == null && !f[1]!.includes('node_modules')) {
+            const file = repoFile(ctx, f[1]!, false)
+            if (file != null) at = { file, line: Number(f[2]), col: Number(f[3]) }
+            continue
+        }
+        const fail = BUN_FAIL.exec(raw)
+        if (fail != null) {
+            const where = at ?? (suite == null ? null : { file: suite, line: 1, col: 1 })
+            if (where != null) out.push({ ...where, severity: 'error', check: ctx.check, message: `${fail[1]!.trim()}${error == null ? '' : `: ${error}`}` })
+            error = null
+            at = null
+        }
+    }
+    return out
+}
+
+const WIRE_REF = /((?:[\w@.~-]+\/)*[\w@.~-]+\.[A-Za-z0-9]+):(\d+)(?::(\d+))?/g
+
+/** a FAIL or WARN wire line naming `path:line` or `path:line:col`. The path
+ *  must be a file this repo has: a url and a `host:port` look the same */
+export function fromWire(lines: Line[], ctx: ExtractCtx): Problem[] {
+    const out: Problem[] = []
+    for (const l of lines) {
+        if (l.kind !== 'fail' && l.kind !== 'warn') continue
+        const severity: Severity = l.kind === 'fail' ? 'error' : 'warning'
+        const message = l.text.replace(/^\[[^\]]+\]\s*/, '').trim()
+        for (const m of l.text.matchAll(WIRE_REF)) {
+            const before = l.text.slice(0, m.index)
+            if (/[a-z]+:\/\/\S*$/i.test(before)) continue
+            const file = repoFile(ctx, m[1]!, true)
+            if (file == null) continue
+            out.push({ file, line: Number(m[2]), col: m[3] == null ? 1 : Number(m[3]), severity, check: ctx.check, message })
+        }
+    }
+    return out
+}
+
+/** every format, over what one check printed: its wire lines and, for a
+ *  subprocess, its whole raw output. One finding is reported once */
+export function extractProblems(src: { lines: Line[]; output?: string }, ctx: ExtractCtx): Problem[] {
+    const text = src.output ?? ''
+    const all = [
+        ...fromWire(src.lines, ctx),
+        ...(text === '' ? [] : [...fromTsc(text, ctx), ...fromOxlint(text, ctx), ...fromEslint(text, ctx), ...fromBunTest(text, ctx)]),
+    ]
+    const seen = new Set<string>()
+    return all.filter((p) => {
+        const k = `${p.file}:${p.line}:${p.col}:${p.severity}:${p.message}`
+        if (seen.has(k)) return false
+        seen.add(k)
+        return true
+    })
+}

package/src/problems/problem-board.ts

@@ -0,0 +1,37 @@
+// the latest verdict of every check, as the problems pane shows it. A run that
+// asked about three checks replaces those three and leaves the rest standing:
+// vscode clears the whole pane at every frame, so a narrowed run that printed
+// only its own findings would erase every other check's.
+import { frameLines, type Problem } from './problem-line.ts'
+
+export class ProblemBoard {
+    private readonly byCheck = new Map<string, Problem[]>()
+
+    /** a check reached a verdict. What it carries has already passed the pane
+     *  rule (problem-line.ts feedsProblemsPane), so an empty list clears it */
+    set(check: string, problems: Problem[]): void {
+        if (problems.length === 0) this.byCheck.delete(check)
+        else this.byCheck.set(check, problems)
+    }
+
+    /** every finding standing, sorted by file then line, so a frame reads the
+     *  same whatever order the checks finished in */
+    all(): Problem[] {
+        return [...this.byCheck.values()].flat().sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col || a.check.localeCompare(b.check))
+    }
+
+    /** one check's verdict, as the runner reports it. A skip is no verdict
+     *  and what the check last said stands, except a check turned off, which
+     *  has nothing to say anymore. Returns whether the board moved */
+    take(e: { id: string; status: string; note?: string; problems?: Problem[] }): boolean {
+        if (e.status === 'skip' && e.note !== 'off') return false
+        const next = e.status === 'skip' ? [] : e.problems ?? []
+        const before = JSON.stringify(this.byCheck.get(e.id) ?? [])
+        this.set(e.id, next)
+        return JSON.stringify(next) !== before
+    }
+
+    frame(): string[] {
+        return frameLines(this.all())
+    }
+}

package/src/problems/problem-line.ts

@@ -0,0 +1,77 @@
+// the ONE shape a problem takes on the hub terminal, and the vscode problem
+// matcher that reads it back. The printer and every tasks.json writer import
+// this file, so the line the hub prints and the regex the editor matches can
+// never drift apart.
+//
+// a run prints one FRAME: the begin line, one problem line per finding, the
+// end line. The matcher is a background one, so vscode clears the pane at the
+// begin line and refills it from what sits before the end line.
+
+export type Severity = 'error' | 'warning'
+
+/** one finding, anchored in a file of this repo */
+export type Problem = {
+    /** repo-relative, forward slashes */
+    file: string
+    line: number
+    /** 1 when the source names no column */
+    col: number
+    severity: Severity
+    /** the check that produced it, printed where vscode shows the code */
+    check: string
+    /** one line, no newline */
+    message: string
+}
+
+export const FRAME_BEGIN = 'shipkit problems: begin'
+const FRAME_END_HEAD = 'shipkit problems: end'
+
+export function frameEnd(problems: Problem[]): string {
+    const errors = problems.filter((p) => p.severity === 'error').length
+    return `${FRAME_END_HEAD}, ${errors} error(s), ${problems.length - errors} warning(s)`
+}
+
+export const BEGINS_PATTERN = `^${FRAME_BEGIN}$`
+export const ENDS_PATTERN = `^${FRAME_END_HEAD}\\b`
+
+/** file, line, column, severity, check id, message. The file is lazy and the
+ *  check id cannot hold a space, so a path with spaces and an id with a colon
+ *  (`imports:check`) both split right */
+export const PROBLEM_PATTERN = '^(.+?):(\\d+):(\\d+): (error|warning) (\\S+?): (.*)$'
+
+export function formatProblem(p: Problem): string {
+    const message = p.message.replace(/\s*\n\s*/g, ' ').trim()
+    return `${p.file}:${p.line}:${p.col}: ${p.severity} ${p.check}: ${message}`
+}
+
+/** the frame, ready to print line by line */
+export function frameLines(problems: Problem[]): string[] {
+    return [FRAME_BEGIN, ...problems.map(formatProblem), frameEnd(problems)]
+}
+
+/** what a tasks.json hub task carries, byte for byte the same everywhere */
+export function hubProblemMatcher(): Record<string, unknown> {
+    return {
+        owner: 'shipkit',
+        source: 'shipkit',
+        fileLocation: ['relative', '${workspaceFolder}'],
+        pattern: { regexp: PROBLEM_PATTERN, file: 1, line: 2, column: 3, severity: 4, code: 5, message: 6 },
+        background: { activeBegin: false, beginsPattern: BEGINS_PATTERN, endsPattern: ENDS_PATTERN },
+    }
+}
+
+/** how a check is remembered, read from what it declares */
+export type Population = 'content' | 'world' | 'reads' | 'neither'
+
+export function populationOf(d: { inputs?: string[]; ttl?: string; never?: string; reads?: boolean }): Population {
+    if (d.ttl != null && d.ttl !== '') return 'world'
+    if (d.inputs != null) return 'content'
+    if (d.reads === true && (d.never == null || d.never === '')) return 'reads'
+    return 'neither'
+}
+
+/** THE rule for the pane: the latest verdict of every check feeds it, measured
+ *  or replayed, except a world check. A world answer (a cred, a domain, a
+ *  service) is not a problem in the code, and it needs hands rather than an
+ *  edit, so it stays on the needs surface */
+export const feedsProblemsPane = (p: Population): boolean => p !== 'world'

package/src/prose/prose-view.ts

@@ -0,0 +1,90 @@
+// The SK014 page's data: every hit of the prose check, grouped by the word
+// (or the rule, for the classes that judge a shape), noisiest first, each hit
+// with its file, its line and the sentence around it. It runs the SAME
+// module the rule runs, over the same config, so the page and the gate can
+// never count differently.
+import type { CheckCtx } from '../core/check-ctx.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { runProseCheck } from './run-prose.ts'
+import type { ProseClass, ProseHit, ProseTier, ProseWords } from './ste.ts'
+
+export type ProseViewHit = {
+    file: string
+    line: number
+    /** the source line around the hit, clipped to a readable width */
+    excerpt: string
+    /** where the hit sits inside `excerpt`, [from, to) */
+    mark: [number, number]
+    why: string
+    fix?: string
+}
+
+export type ProseGroup = {
+    /** `<class>:<word>` for a word hit, `<class>` for a shape */
+    key: string
+    cls: ProseClass
+    tier: ProseTier
+    /** the dictionary word or phrase an allow entry names; null on a shape */
+    word: string | null
+    count: number
+    hits: ProseViewHit[]
+}
+
+export type ProseView = {
+    /** false when the repo declares no prose scope: the rule skips it */
+    scoped: boolean
+    files: number
+    total: number
+    byTier: Record<ProseTier, number>
+    groups: ProseGroup[]
+    /** the repo's own lists as the config loads them */
+    words: ProseWords
+}
+
+/** how much of a long line the page shows on each side of the hit */
+const SIDE = 70
+
+/** the source line a hit sits on, clipped around it, with the hit's span
+ *  inside the clip. A hit that runs past its line (a long sentence, a
+ *  paragraph) marks to the end of the line */
+export function excerptOf(text: string, h: Pick<ProseHit, 'start' | 'end'>): { excerpt: string; mark: [number, number] } {
+    const from = text.lastIndexOf('\n', h.start - 1) + 1
+    const nl = text.indexOf('\n', h.start)
+    const to = nl < 0 ? text.length : nl
+    const line = text.slice(from, to)
+    let a = h.start - from
+    let b = Math.min(h.end, to) - from
+    let lo = Math.max(0, a - SIDE)
+    const hi = Math.min(line.length, Math.max(b, a) + SIDE)
+    // a leading indent is noise in a one line quote
+    while (lo < a && /\s/.test(line[lo]!)) lo++
+    const head = lo > 0 ? '…' : ''
+    const tail = hi < line.length ? '…' : ''
+    const excerpt = head + line.slice(lo, hi).trimEnd() + tail
+    a = a - lo + head.length
+    b = Math.min(b - lo + head.length, excerpt.length - tail.length)
+    return { excerpt, mark: [a, Math.max(a, b)] }
+}
+
+export function proseView(c: Pick<CheckCtx, 'root' | 'read' | 'list' | 'write'>, config: RepoConfig): ProseView {
+    const cfg = config.prose
+    const empty: ProseView = { scoped: false, files: 0, total: 0, byTier: { fix: 0, hard: 0, soft: 0 }, groups: [], words: cfg?.words ?? {} }
+    if (cfg == null || (cfg.include ?? []).length === 0) return empty
+    const r = runProseCheck({ c, config: cfg, keepText: true })
+    const groups = new Map<string, ProseGroup>()
+    for (const f of r.byFile)
+        for (const h of f.hits) {
+            const key = h.word == null ? h.cls : `${h.cls}:${h.word}`
+            let g = groups.get(key)
+            if (g == null) {
+                g = { key, cls: h.cls, tier: h.tier, word: h.word ?? null, count: 0, hits: [] }
+                groups.set(key, g)
+            }
+            g.count++
+            const ex = excerptOf(f.text ?? '', h)
+            g.hits.push({ file: f.file, line: h.line, ...ex, why: h.why, ...(h.fix == null ? {} : { fix: h.fix }) })
+        }
+    // the noisiest first: one allow entry on the top word clears the most
+    const sorted = [...groups.values()].sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
+    return { scoped: true, files: r.files, total: r.hits.length, byTier: r.byTier, groups: sorted, words: cfg.words ?? {} }
+}

package/src/prose/run-prose.ts

@@ -6,10 +6,15 @@
 // `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'
+//
+// It reads and writes ONLY through the check context it is handed, so rule
+// SK014 is cached on the scope's listings and the files in it.
+import { isAbsolute, relative, resolve } from 'path'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import { checkProse, fixProse, tierOf, type ProseClass, type ProseHit, type ProseTier, type ProseWords } from './ste.ts'
+
+/** what the walker reads and writes through: a check context */
+export type ProseDisk = Pick<CheckCtx, 'root' | 'read' | 'list' | 'write'>
 
 export type ProseConfig = {
     /** globs (repo-relative) that ARE house prose. Absent = the repo is not checked. */
@@ -20,6 +25,11 @@ export type ProseConfig = {
     allow?: ProseClass[]
     /** the 20-word procedural limit instead of the 25-word descriptive one */
     strict?: boolean
+    /** this repo's own word lists over the house dictionary: `allow` drops
+     *  every hit on a word or phrase, `ban` refuses an extra one (a hard hit,
+     *  with its replacement). They bind this repo only, and the hub's SK014
+     *  page writes them through a managed block inside this object */
+    words?: ProseWords
     /** 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
@@ -28,7 +38,13 @@ export type ProseConfig = {
     baseline?: number
 }
 
-export type FileReport = { file: string; hits: ProseHit[] }
+export type FileReport = {
+    file: string
+    hits: ProseHit[]
+    /** the file as it was judged, kept only when the caller asked, so a page
+     *  can quote the line around each hit without reading the file twice */
+    text?: string
+}
 
 export type ProseReport = {
     files: number
@@ -58,51 +74,76 @@ export function explicitPath(root: string, p: string): string {
     return rel
 }
 
-export function proseFiles(root: string, cfg: ProseConfig): string[] {
+/** does `path` match `pattern` under the dot rule: a hidden segment (one
+ *  starting with a dot) only where the pattern names a hidden segment itself,
+ *  never inside a `**` or under a wildcard segment */
+export function hiddenAllowed(pattern: string, path: string): boolean {
+    const pat = pattern.split('/')
+    const segs = path.split('/')
+    const hidden = (s: string): boolean => s.startsWith('.') && s !== '.' && s !== '..'
+    const star = pat.indexOf('**')
+    const head = star === -1 ? pat : pat.slice(0, star)
+    const tail = star === -1 ? [] : pat.slice(pat.lastIndexOf('**') + 1)
+    for (let i = 0; i < segs.length; i++) {
+        if (!hidden(segs[i]!)) continue
+        const fromEnd = segs.length - 1 - i
+        const p = i < head.length ? head[i] : fromEnd < tail.length ? tail[tail.length - 1 - fromEnd] : undefined
+        if (p == null || !p.startsWith('.')) return false
+    }
+    return true
+}
+
+/** the files in scope: what git sees (tracked, or untracked and not ignored)
+ *  matching an include glob, the dot rule applied, minus every exempt glob */
+export function proseFiles(d: Pick<ProseDisk, 'list'>, 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('/')
+        for (const rel of d.list(pattern)) {
+            if (!hiddenAllowed(pattern, rel)) continue
             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 {
+export function runProseCheck(o: { c: ProseDisk; config: ProseConfig; paths?: string[]; fix?: boolean; keepText?: 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 d = o.c
+    const files = o.paths != null && o.paths.length > 0 ? o.paths.map((p) => explicitPath(d.root, p)) : proseFiles(d, cfg)
     const explicit = o.paths != null && o.paths.length > 0
-    const opts = { allow: cfg.allow, strict: cfg.strict }
+    const opts = { allow: cfg.allow, strict: cfg.strict, words: cfg.words }
     const byFile: FileReport[] = []
     const hits: ProseHit[] = []
     const fixed: string[] = []
     for (const rel of files) {
-        const abs = join(o.root, rel)
-        let text: string
+        let text: string | null
         try {
-            text = readFileSync(abs, 'utf8')
+            text = d.read(rel)
         } 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.
+            text = null
             if (explicit) throw new Error(`FAIL cannot read ${rel} — ${String(e)}`)
+        }
+        if (text == null) {
+            // a path a HUMAN typed that cannot be read is a loud failure. A
+            // path the listing produced can vanish between the scan and the
+            // read, and skipping that one is right.
+            if (explicit) throw new Error(`FAIL cannot read ${rel} — no such file`)
             continue
         }
         if (isGenerated(text)) continue
         if (o.fix === true) {
             const out = fixProse(text, opts)
             if (out.applied > 0) {
-                atomicWrite(abs, out.text)
+                d.write(rel, out.text)
                 fixed.push(rel)
                 text = out.text
             }
         }
         const fh = checkProse(text, opts)
-        if (fh.length > 0) byFile.push({ file: rel, hits: fh })
+        if (fh.length > 0) byFile.push({ file: rel, hits: fh, ...(o.keepText === true ? { text } : {}) })
         hits.push(...fh)
     }
     const byTier: Record<ProseTier, number> = { fix: 0, hard: 0, soft: 0 }