rvlib-shipkit 1.9.0 → 2.0.1

package/src/core/check-file-names.ts

@@ -83,9 +83,8 @@ export type LegacyCheck = {
 
 // read without importing: checks run as subprocesses, and discovery must stay
 // pure-fs. `export const blocking = true` (or false), nothing cleverer.
-// the tail is the gate's OWN formatter: oxfmt terminates every statement, and
-// the fix pass runs it, so a reader that refuses a semicolon refuses the shape
-// the gate itself just wrote.
+// the tail takes what a formatter on its defaults writes: it terminates every
+// statement, so a reader that refuses a semicolon refuses a formatted file.
 const TAIL = String.raw`(?:\s+as\s+const)?\s*;?\s*$`
 const BLOCKING_RE = new RegExp(String.raw`^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)` + TAIL, 'm')
 // `export const inputs = ['a', 'b']`, single or multi line. Anything cleverer

package/src/core/check-pass.ts

@@ -12,9 +12,10 @@ import { importClosure } from '../ts/source-graph.ts'
 import { LIB_ROOT } from './lib-root.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { Scan } from '../scan.ts'
+import { parseDirectives, type Directive } from './waivers.ts'
 
 /** a scan's context, and what it recorded while the scan ran */
-type ScanRecorder = ScanCtx & { readonly reads: Reads; readonly untracked: string | null }
+type ScanRecorder = ScanCtx & { readonly reads: Reads; readonly untracked: string | null; readonly marked: ReadonlyMap<string, string> }
 
 /** the config file every check that consults `c.config` depends on */
 export const CONFIG_FILE = 'repo.config.ts'
@@ -27,6 +28,7 @@ export class CheckPass {
     private readonly scans = new Map<string, { value: Promise<unknown>; ctx: ScanRecorder }>()
     private viewMemo: RepoView | null = null
     private configMemo: { files: Map<string, string | null>; untracked: string | null } | null = null
+    private readonly directiveMemo = new Map<string, { text: string; directives: Directive[] }>()
 
     constructor(
         readonly root: string,
@@ -34,6 +36,10 @@ export class CheckPass {
         /** where the file list comes from: the run's ledger shares its own,
          *  so a listing and its validation read one snapshot */
         private readonly openView: () => RepoView = () => RepoView.open(root),
+        /** false for a pass whose answers nothing stores (the pre-commit
+         *  gate): listing what the config imports is then pure cost, measured
+         *  at 12 to 70ms on the first check that reads `c.config` */
+        readonly recordsConfig = true,
     ) {
         this.configOid = oidOnDisk(join(root, CONFIG_FILE))
     }
@@ -61,6 +67,16 @@ export class CheckPass {
         return this.configMemo
     }
 
+    /** the directives of a file as read, parsed once per pass however many
+     *  checks read it */
+    directives(path: string, text: string): Directive[] {
+        const hit = this.directiveMemo.get(path)
+        if (hit != null && hit.text === text) return hit.directives
+        const directives = parseDirectives(path, text)
+        this.directiveMemo.set(path, { text, directives })
+        return directives
+    }
+
     view(): RepoView {
         this.viewMemo ??= this.openView()
         return this.viewMemo

package/src/core/check-runner.ts

@@ -450,6 +450,8 @@ type Live = RunnableCheck & CheckResult & {
     reads: ReadSet | null
     /** why its answer cannot be stored on its reads, in its own words */
     untracked: string | null
+    /** the files whose in-file directives its answer depends on */
+    waiverFiles: string[]
     /** it printed nothing of its own, so its one line is the headline below */
     synthetic: boolean
     /** what the headline carries after the id: a failure's last line, or the
@@ -506,7 +508,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     const runDir = openRunDir(o.logDir)
     const checks: Live[] = sel.selected.map((u) => ({
         ...u,
-        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, untracked: null, synthetic: false, tail: '', extra: [],
+        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, untracked: null, waiverFiles: [], synthetic: false, tail: '', extra: [],
         logPath: u.body.cmd != null ? join(runDir, `${u.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
     }))
     const selectedIds = new Set(checks.map((u) => u.id))
@@ -599,8 +601,9 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             : [ranHere(composed[0], u.ms), ...composed.slice(1)]
         // a caller printing its own verdict wants one line per green check and
         // only the warnings of a warned one; a failure prints whole
+        // a waived site is detail whatever the verdict, and its count never is
         const quiet = (l: Line, i: number): boolean =>
-            o.detail != null && (u.status === 'pass' ? i > 0 : u.status === 'warn' || u.advisory ? l.kind === 'ok' || l.kind === 'note' || l.kind === 'skip' : false)
+            o.detail != null && l.waiver !== 'count' && (l.waiver === 'site' || (u.status === 'pass' ? i > 0 : u.status === 'warn' || u.advisory ? l.kind === 'ok' || l.kind === 'note' || l.kind === 'skip' : false))
         for (const [i, l] of shown.entries()) if (quiet(l, i)) o.detail!(formatLine(l, color)); else emit(l)
         if (u.status === 'fail' && !u.advisory && u.logPath != null)
             emit({ kind: 'fix-fail', text: `full log: ${u.logPath}` })
@@ -641,6 +644,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             await runCheckBody({ id: u.id, title: u.title, owner: u.owner, run: u.body.run, fix: u.fix }, t)
             u.reads = t.untracked == null ? t.reads.snapshot() : null
             u.untracked = t.untracked
+            u.waiverFiles = t.waiverFiles()
             u.lines = t.lines
             u.problems = findings(u, t.lines)
             u.unmeasured = t.unmeasured
@@ -718,6 +722,13 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             let i = parsed.length
             while (i > 0 && (parsed[i - 1]!.kind === 'fail' || parsed[i - 1]!.kind === 'fix-fail')) i--
             u.extra = parsed.slice(i).filter((l) => !(l.kind === 'fail' && `FAIL: ${l.text}` === u.lastLine)).slice(-MAX_EXTRA)
+            // a tool that speaks no wire (a linter, tsc) ends on a recap, and
+            // its errors are the findings its output parsed into
+            if (!u.extra.some((l) => l.kind === 'fail'))
+                u.extra = u.problems
+                    .filter((p) => p.severity === 'error' && !u.lastLine.includes(p.message))
+                    .slice(0, MAX_EXTRA)
+                    .map((p) => ({ kind: 'fail', text: `${p.file}:${p.line}:${p.col}: ${p.message}` }))
         }
     }
 
@@ -732,9 +743,9 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
 
     /** what an attached asker adopts: the verdict and the lines BEFORE this
      *  run's own demotion, which the asker applies from its own declaration */
-    type Answer = Pick<Live, 'status' | 'lines' | 'problems' | 'lastLine' | 'exitCode' | 'logPath' | 'synthetic' | 'tail'> & { measuredMs: number }
+    type Answer = Pick<Live, 'status' | 'lines' | 'problems' | 'lastLine' | 'exitCode' | 'logPath' | 'synthetic' | 'tail' | 'waiverFiles'> & { measuredMs: number }
     const answerOf = (u: Live): Answer => ({
-        status: u.status, lines: u.lines, problems: u.problems, lastLine: u.lastLine, exitCode: u.exitCode, logPath: u.logPath,
+        status: u.status, lines: u.lines, problems: u.problems, lastLine: u.lastLine, exitCode: u.exitCode, logPath: u.logPath, waiverFiles: u.waiverFiles,
         synthetic: u.synthetic, tail: u.tail, measuredMs: (u.endedAt > 0 ? u.endedAt : clock()) - u.startedAt,
     })
     // only a GREEN is ever stored. A pass is one whatever the check blocks. A
@@ -777,7 +788,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         u.lines = head == null ? [] : [{ ...head, text: `${head.text}${stamp}` }, ...a.lines.slice(1)]
         u.problems = feeds(u) ? a.problems ?? [] : []
         if (o.ledger != null && storable(u))
-            o.ledger.record(u.id, { status: u.status, lines: a.lines, lastLine: a.lastLine, problems: u.problems, measuredMs: a.measuredMs })
+            o.ledger.record(u.id, { status: u.status, lines: a.lines, lastLine: a.lastLine, problems: u.problems, measuredMs: a.measuredMs }, undefined, undefined, a.waiverFiles)
     }
 
     /** ONE measurement per in flight question: an asker whose exact key
@@ -835,12 +846,14 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             u.lines = rememberWorld(o.cache, u.id, worldKey(u), u.ttlMs, {
                 lines: u.lines,
                 clean,
+                // a waiver count is a skip line: a world key cannot see the
+                // waiving file, so a waived world answer is never kept
                 unmeasured: u.unmeasured || u.lines.some((l) => l.kind === 'skip'),
                 keepNegative: u.blocking === false,
             })
         }
         if (o.ledger != null && keep)
-            o.ledger.record(u.id, { status: u.status as 'pass' | 'warn', lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads, u.untracked)
+            o.ledger.record(u.id, { status: u.status as 'pass' | 'warn', lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads, u.untracked, u.waiverFiles)
     }
 
     const start = (u: Live): void => {

package/src/core/config-rewrite.ts

@@ -13,7 +13,7 @@
 import { readFileSync } from 'fs'
 import { join } from 'path'
 import { atomicWrite } from './locked-write.ts'
-import { dropConfigKey } from './legacy-shapes.ts'
+import { dropConfigEntry, dropConfigKey } from './legacy-shapes.ts'
 import { writeGateBlock } from './when-block.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
@@ -25,6 +25,12 @@ export type ConfigPlan = {
     drop: { key: string; why: string; phase?: 'first' | 'afterOff' }[]
     /** the config's `name` before the rewrite: what the read back must still say */
     name: string
+    /** entries of an object key to lift into `off` (`hooks.disable`, a
+     *  `defaults` slot set to false), dropped once the block took them. The
+     *  comment written right above an entry becomes the reason of every id it
+     *  carries, since it is the author's own words; `reason` is the honest
+     *  fallback when there is none */
+    lift?: { parent: string; entry: string; value: string; ids: string[]; reason: Record<string, string> }[]
 }
 
 export type ConfigRewrite = {
@@ -48,17 +54,23 @@ export async function rewriteConfig(root: string, plan: ConfigPlan): Promise<Con
     let first = before
     for (const d of plan.drop.filter((x) => x.phase === 'first')) first = drop(first, d)
     if (first !== before) atomicWrite(path, first)
+    // each lifted entry's reason, read off the text before anything moves
+    const off = { ...plan.off }
+    for (const l of plan.lift ?? []) {
+        const seen = dropConfigEntry(first, l.parent, l.entry, l.value)
+        for (const id of l.ids) off[id] ??= seen?.comment ?? l.reason[id] ?? ''
+    }
     let offWritten = false
-    if (Object.keys(plan.off).length > 0) {
+    if (Object.keys(off).length > 0) {
         try {
-            await writeGateBlock(root, { off: plan.off })
+            await writeGateBlock(root, { off })
             offWritten = true
-            did.push(`${Object.keys(plan.off).length} off entr(ies) written into the managed block`)
+            did.push(`${Object.keys(off).length} off entr(ies) written into the managed block`)
         } catch (e) {
             // a key dropped first held these entries: without the block they
             // would be gone, so the file goes back as it was
-            if (first !== before) { atomicWrite(path, before); return { did: [], hand, restored: `the managed block refused off ${JSON.stringify(plan.off)}: ${String(e).slice(0, 160)}` } }
-            hand.push(`the managed block refused the rewrite (${String(e).slice(0, 160)}) — write off: ${JSON.stringify(plan.off)} into it by hand`)
+            if (first !== before) { atomicWrite(path, before); return { did: [], hand, restored: `the managed block refused off ${JSON.stringify(off)}: ${String(e).slice(0, 160)}` } }
+            hand.push(`the managed block refused the rewrite (${String(e).slice(0, 160)}) — write off: ${JSON.stringify(off)} into it by hand`)
         }
     }
     const mid = readFileSync(path, 'utf8')
@@ -67,11 +79,20 @@ export async function rewriteConfig(root: string, plan: ConfigPlan): Promise<Con
         if (d.phase === 'afterOff' && !offWritten) continue
         text = drop(text, d)
     }
+    // a lifted entry goes only once the block holds it, so it is never lost
+    for (const l of offWritten ? plan.lift ?? [] : []) {
+        const next = dropConfigEntry(text, l.parent, l.entry, l.value)
+        if (next == null) { hand.push(`repo.config.ts \`${l.parent}.${l.entry}\` is \`off\` now, and the entry could not be read mechanically — delete it by hand`); continue }
+        did.push(`repo.config.ts drops \`${l.parent}.${l.entry}\``)
+        text = next.text
+    }
     if (text !== mid) atomicWrite(path, text)
     if (text !== before) {
         try {
             const after = await loadRepoConfig(root, { fresh: true })
             if (after.name !== plan.name) throw new Error(`the config reads as '${String(after.name)}'`)
+            const lost = Object.keys(off).filter((id) => after.off?.[id] == null)
+            if (offWritten && lost.length > 0) throw new Error(`the config no longer turns ${lost.join(', ')} off`)
         } catch (e) {
             atomicWrite(path, before)
             return { did, hand, restored: String(e).slice(0, 160) }

package/src/core/discover-checks.ts

@@ -16,7 +16,7 @@
 // are told apart by reading the source first (`isLegacyCheckSource`).
 //
 // Skipped dirs: node_modules, dist, tmp, references (templates for other
-// repos), and every dot-dir.
+// repos), every dot-dir, and the repo's vendored dirs (core/vendored.ts).
 import { RETIRED_CHECK_IDS } from './retired-checks.ts'
 import { readdirSync, readFileSync, realpathSync, statSync } from 'fs'
 import { basename, join, relative } from 'path'
@@ -24,6 +24,7 @@ import { check, type CheckDef, type CheckFrom } from '../check.ts'
 
 import { CHECK_SUFFIX as SUFFIX, fallbackNames, isLegacyCheckSource, SKIPPED_DIRS as IGNORED_DIRS, UNIT_SUFFIX, unitBase } from './check-file-names.ts'
 import { unitKind } from '../shipkit-files.ts'
+import { readVendored } from './vendored-read.ts'
 
 export { fallbackNames, isLegacyCheckSource } from './check-file-names.ts'
 
@@ -56,23 +57,27 @@ export type DiscoveredCheck = {
     from: CheckFrom
 }
 
-function walk(dir: string, out: string[], suffix = SUFFIX, dirs?: string[]): void {
+function walk(dir: string, out: string[], suffix = SUFFIX, dirs?: string[], prune?: ReadonlySet<string>): void {
     dirs?.push(dir)
     let entries
     try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
     for (const e of entries) {
         if (e.isDirectory()) {
-            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), out, suffix, dirs)
+            const sub = join(dir, e.name)
+            if (!IGNORED_DIRS.has(e.name) && !e.name.startsWith('.') && prune?.has(sub) !== true) walk(sub, out, suffix, dirs, prune)
         } else if (e.name.endsWith(suffix)) out.push(join(dir, e.name))
     }
 }
 
+/** the absolute vendored dirs of a repo, which no repo walk enters */
+const vendoredPrune = (root: string): ReadonlySet<string> => new Set(readVendored(root).map((d) => join(root, d)))
+
 /** every `*.shipkit.ts` file under a repo root, by the same walk. Sorted.
  *  `dirs` collects every dir the walk read: a file added to one moves its
  *  mtime, which is how a reader tells the list moved without walking again */
 export function repoUnitFiles(root: string, dirs?: string[]): string[] {
     const out: string[] = []
-    walk(root, out, UNIT_SUFFIX, dirs)
+    walk(root, out, UNIT_SUFFIX, dirs, vendoredPrune(root))
     return out.sort()
 }
 
@@ -97,7 +102,7 @@ export async function importFresh(path: string): Promise<unknown> {
  *  Sorted. */
 export function repoCheckFiles(root: string): string[] {
     const out: string[] = []
-    walk(root, out)
+    walk(root, out, SUFFIX, undefined, vendoredPrune(root))
     return out.sort()
 }
 
@@ -175,13 +180,24 @@ const BUILTIN_OWNER = 'build/shipkit/built-in-checks.md'
  *  on a registration nobody can act on (a duplicate id, a repo check squatting
  *  the reserved prefix, a built-in with no owner page), so a broken
  *  declaration dies at load rather than half way through a gate. A broken
- *  built-in is that only in the toolkit's own repo: elsewhere it warns.
- *  `builtinDir` is the toolkit's checks dir, a parameter for tests only */
-export async function discoverChecks(root: string, builtinDir: string = BUILTIN_CHECK_DIR): Promise<DiscoveredCheck[]> {
+ *  built-in is that only in the toolkit's own repo: elsewhere it warns. */
+export type DiscoverOpts = {
+    /** a file not to import at all: the pre-commit gate skips the files its
+     *  declarations table already knows run no onPreCommit body */
+    skip?: (path: string) => boolean
+    /** every import, timed: `def` is null for a unit file of another kind,
+     *  and `loaded` is false for a file that did not load */
+    imported?: (path: string, ms: number, def: CheckDef | null, loaded: boolean) => void
+    /** the toolkit's checks dir, a parameter for tests only */
+    builtinDir?: string
+}
+
+export async function discoverChecks(root: string, o: DiscoverOpts = {}): Promise<DiscoveredCheck[]> {
+    const builtinDir = o.builtinDir ?? BUILTIN_CHECK_DIR
     const builtins: string[] = []
     walk(builtinDir, builtins)
     const found: string[] = []
-    walk(root, found)
+    walk(root, found, SUFFIX, undefined, vendoredPrune(root))
     const units = repoUnitFiles(root)
     // the repo that HOSTS the toolkit walks over `src/checks/` too, and a file
     // discovered twice is a duplicate id rather than a second check. Real paths,
@@ -195,18 +211,22 @@ export async function discoverChecks(root: string, builtinDir: string = BUILTIN_
     builtins.sort()
     const names = fallbackNames(root, all)
     // a legacy script is left to its own reader, and never imported here
-    const own = all.filter((f) => !isLegacyCheckFile(f))
+    const own = all.filter((f) => o.skip?.(f) === true || !isLegacyCheckFile(f))
     const base = (f: string): string => basename(f).slice(0, -SUFFIX.length)
 
     const out: DiscoveredCheck[] = []
     const ids = new Set<string>()
     for (const f of [...builtins, ...own, ...units]) {
         const isBuiltin = builtins.includes(f)
+        if (o.skip?.(f) === true) continue
         let def: CheckDef | null
         let loadError: string | null = null
+        const t = performance.now()
         try {
             def = await load(f)
+            o.imported?.(f, performance.now() - t, def, true)
         } catch (e) {
+            o.imported?.(f, performance.now() - t, null, false)
             // a file that does not load is ONE red row, never a dead inventory:
             // every other check still runs, and this one says why in every run
             loadError = (e as Error).message

package/src/core/floor-resolve.ts

@@ -25,6 +25,9 @@ import { parseBunTestScript, suiteFlags } from '../suite/judge-suites.ts'
 import { declaredTestUnits, siblingUnits, testCheckId, unitIgnores, unitTestBody, unitTsconfig, type TestUnitDecl } from '../suite/test-units.ts'
 import { describeFirst, type TaskDef } from '../check.ts'
 import type { RepoConfig } from '../repo-config.ts'
+import { repoOff } from './when.ts'
+import { bunfigDeclares, bunLintCmd } from './bun-builtins.ts'
+import { normalizeVendored } from './vendored.ts'
 
 /** how the floor reads the repo, by repo-relative path, plus the one lookup
  *  outside it: a binary on PATH */
@@ -65,10 +68,10 @@ export const unitTestDescription = (u: { id: string; rel: string }): string =>
 export const unitTypecheckDescription = (u: { id: string; rel: string }): string =>
     describeFirst(`tsc finds no type error under ${u.rel}`, `tsc finds no type error in unit ${u.id}`)
 
-export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (shipkit)' | 'built-in (tsc)' | 'unit'
+export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (shipkit)' | 'built-in (tsc)' | 'built-in (bun)' | 'unit'
 export type FloorResolution = {
     tasks: TaskDef[]
-    /** slots disabled by `defaults: { x: false }` — always printed */
+    /** slots the repo turned off (core/when.ts repoOff), always printed */
     disabled: string[]
     /** slots nothing could fill — always printed, never silent */
     unfilled: { id: string; reason: string }[]
@@ -161,9 +164,14 @@ function tsconfigChain(rel: string, io: FloorReader): string[] {
 }
 
 // zero-config floor (O6): with no script, imports:check/cycles resolve to
-// shipkit's own rvlib-ts-tools dep, typecheck to the repo's tsc. Returns
-// the task, or the reason the slot stays empty.
-function builtinFloorTask(id: string, root: string, io: FloorReader): { task: TaskDef; source: FloorSource } | string {
+// shipkit's own rvlib-ts-tools dep, typecheck to the repo's tsc, lint to
+// `bun lint` once bunfig.toml declares [lint]. Returns the task, or the
+// reason the slot stays empty.
+function builtinFloorTask(id: string, root: string, io: FloorReader, vendored: readonly string[]): { task: TaskDef; source: FloorSource } | string {
+    if (id === 'lint') {
+        if (!bunfigDeclares(io.text('bunfig.toml'), 'lint')) return `no 'lint' script and no [lint] section in bunfig.toml`
+        return { task: { id, cmd: bunLintCmd(vendored) }, source: 'built-in (bun)' }
+    }
     if (id === 'imports:check' || id === 'cycles') {
         let cli: string
         // shipkit's OWN module, resolved from this file: no dependency to be
@@ -234,7 +242,8 @@ export function resolveFloor(c: RepoConfig, root: string, io: FloorReader): Floo
     const notes: string[] = []
     const subs = declaredTestUnits(c.units)
     for (const id of FLOOR_IDS) {
-        const override = c.defaults?.[id]
+        // a slot the repo turned off resolves to no task, whichever spelling said so
+        const override = repoOff(c, id) != null ? false : c.defaults?.[id]
         const description = slotDescription(id, subs.length > 0)
         const slot = slotBody(id, override, scripts)
         if (slot.kind === 'off') { disabled.push(id); continue }
@@ -250,7 +259,7 @@ export function resolveFloor(c: RepoConfig, root: string, io: FloorReader): Floo
             return override == null || override === false ? t : { ...t, ...override, id }
         }
         if (slot.kind === 'script') { tasks.push(decorate({ id, cmd: scriptCmd(c, id, slot.name, slot.body, notes, subs) })); sources[id] = 'package.json script'; continue }
-        const b = builtinFloorTask(id, root, io)
+        const b = builtinFloorTask(id, root, io, (c.vendored ?? []).map(normalizeVendored))
         // a routed script with nothing behind it measures NOTHING, and the
         // reason must say that rather than `no '<id>' script`, which is false
         if (typeof b === 'string') unfilled.push({ id, reason: slot.kind === 'routed-empty' ? `script '${id}' routes to shipkit and there is no '${rawName(id)}' body to run` : b })

package/src/core/job-run.ts

@@ -4,14 +4,14 @@
 // the machine's one background turn here, so the turn outlives a daemon
 // reload the same as the run does.
 import { basename } from 'path'
-import { useOneLib } from './one-lib.ts'
+import { installOneLib } from './one-lib.ts'
 import { appendJobCheck, type JobKind, type JobOpts } from './jobs.ts'
 import { autoGatePool, takeSlot } from './slots.ts'
 import type { CheckEvent } from './check-runner.ts'
 
 export async function runJob(root: string, id: string, kind: JobKind, job: JobOpts, print: (l: string) => void): Promise<number> {
     // before the repo config loads: it imports this copy of the lib, never its own install
-    if (job.oneLib === true) useOneLib()
+    if (job.oneLib === true) installOneLib()
     const turn = job.turn === true ? await takeSlot(autoGatePool(), { repo: basename(root), check: 'auto gate' }, { pollMs: 250 }) : null
     try {
         const onCheck = (e: CheckEvent): void => appendJobCheck(root, id, e)

package/src/core/layout.ts

@@ -19,6 +19,9 @@ export const LAYOUT = {
     identity: sk('identity'),
     assets: sk('assets'),
     comfy: sk('comfy'),
+    // a bug's repro test once its fix lands: kept for the record, never run
+    // (bun test skips dot dirs), moved into the suite only when it earns its wait
+    repros: sk('repros'),
     // local: drafts, private notes, venue listings until they go live
     private: sk('private'),
     reflections: sk('reflections'),
@@ -41,7 +44,7 @@ export const LAYOUT = {
 } as const
 
 /** the children the SK004 block re-includes: everything else under `.shipkit/` stays local */
-export const TRACKED_DIRS = [LAYOUT.asks, LAYOUT.hooks, LAYOUT.identity, LAYOUT.assets, LAYOUT.comfy] as const
+export const TRACKED_DIRS = [LAYOUT.asks, LAYOUT.hooks, LAYOUT.identity, LAYOUT.assets, LAYOUT.comfy, LAYOUT.repros] as const
 
 /** the machine-global private folder, under $HOME: one keyword list and one
  *  allowlist per machine, never copied into a repo */

package/src/core/legacy-shapes.ts

@@ -221,3 +221,43 @@ export function dropConfigKey(text: string, key: string): string | null {
     while (from > 0 && lines[from - 1]!.trim().startsWith('//') && !/^\/\/ (>>>|<<<) shipkit/.test(lines[from - 1]!.trim())) from--
     return [...lines.slice(0, from), ...lines.slice(end + 1)].join('\n')
 }
+
+const esc = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** the config text without one entry of a top level object key, as in
+ *  `disable` inside `hooks` or `lint: false` inside `defaults`, plus the words
+ *  of the comment written right above the entry, which are the closest thing
+ *  to a reason the entry ever had. `value` is the entry's value as a regex
+ *  source, so only the shape the caller expects is touched. The parent goes
+ *  too once nothing is left in it. Null when the parent or the entry is not
+ *  there exactly once, or sits in a shape this reader does not follow */
+export function dropConfigEntry(text: string, parent: string, entry: string, value: string): { text: string; comment: string | null } | null {
+    const lines = text.split('\n')
+    const at = lines.map((l, i) => (new RegExp(`^\\s*${esc(parent)}\\s*:`).test(l) ? i : -1)).filter((i) => i !== -1)
+    if (at.length !== 1) return null
+    const start = at[0]!
+    const end = statementEnd(lines, start)
+    const key = `(['"]?)${esc(entry)}\\1\\s*:\\s*(?:${value})`
+    if (start === end) {
+        // one line: `hooks: { blockedPaths: [...], disable: ['leak-guard'] },`
+        const line = lines[start]!
+        const hits = line.match(new RegExp(`(?<![\\w$])${key}`, 'g')) ?? []
+        if (hits.length !== 1) return null
+        let next = line.replace(new RegExp(`,\\s*${key}`), '')
+        if (next === line) next = line.replace(new RegExp(`(?<![\\w$])${key}\\s*,\\s*`), '')
+        if (next === line) next = line.replace(new RegExp(`(?<![\\w$])${key}`), '')
+        const out = [...lines.slice(0, start), next, ...lines.slice(start + 1)].join('\n')
+        return { text: /:\s*\{\s*\}\s*,?\s*(\/\/.*)?$/.test(next) ? (dropConfigKey(out, parent) ?? out) : out, comment: null }
+    }
+    const inner = lines.map((l, i) => (i > start && i <= end && new RegExp(`^\\s*${key}\\s*,?\\s*$`).test(l) ? i : -1)).filter((i) => i !== -1)
+    if (inner.length !== 1) return null
+    const i = inner[0]!
+    let from = i
+    while (from - 1 > start && lines[from - 1]!.trim().startsWith('//')) from--
+    const comment = lines.slice(from, i).map((l) => l.trim().replace(/^\/\/\s?/, '')).join(' ').trim()
+    const kept = [...lines.slice(0, from), ...lines.slice(i + 1)]
+    const body = kept.slice(start + 1, end - (i - from + 1))
+    const empty = body.every((l) => l.trim() === '' || l.trim().startsWith('//'))
+    const out = kept.join('\n')
+    return { text: empty ? (dropConfigKey(out, parent) ?? out) : out, comment: comment === '' ? null : comment }
+}

package/src/core/one-lib.ts

@@ -102,7 +102,7 @@ const LOADERS: Record<string, 'ts' | 'tsx' | 'js' | 'jsx'> = { '.ts': 'ts', '.ts
 let installed = false
 
 /** route every import of the package to this process's copy. Idempotent */
-export function useOneLib(root: string = LIB_ROOT): void {
+export function installOneLib(root: string = LIB_ROOT): void {
     if (installed) return
     installed = true
     const exports = readExports(root)

package/src/core/one-way-in-policy.ts

@@ -14,7 +14,7 @@
 // The deny is the floor and the hook is the messenger. When the hook cannot
 // run, enforcement degrades to terse rather than to nothing.
 //
-// Subprocesses are NOT intercepted (verified): shipkit spawning oxlint or
+// Subprocesses are NOT intercepted (verified): shipkit spawning tsc or
 // `bun run test:raw` from inside a permitted `shipkit ci` is invisible to
 // these rules, which is exactly what makes the gate itself still work.
 
@@ -24,7 +24,7 @@ export type RawRunner = {
     /** the floor slot it answers, so ONE exemption governs the script name and
      *  the shell command together: a repo that keeps `test` raw is not then
      *  refused `bun test` */
-    slot: 'test' | 'lint' | 'typecheck'
+    slot: 'test' | 'typecheck'
     /** the shipkit command that answers the same question, cache and all */
     use: string
     /** the narrower way in, when there is one: iterating on a single repro
@@ -47,25 +47,118 @@ export const RAW_RUNNERS: readonly RawRunner[] = [
     { head: 'bunx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
     { head: 'npx tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
     { head: 'tsc', slot: 'typecheck', use: 'shipkit ci --only typecheck' },
-    { head: 'bunx oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
-    { head: 'npx oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
-    { head: 'oxlint', slot: 'lint', use: 'shipkit ci --only lint' },
-    { head: 'npx eslint', slot: 'lint', use: 'shipkit ci --only lint' },
-    { head: 'eslint', slot: 'lint', use: 'shipkit ci --only lint' },
 ]
 
-// the FORMATTER is deliberately absent, and that is not an oversight. It
-// answers no cached question and produces no green anyone could mistake for a
-// verification, shipkit's own fix pass runs it BY SCRIPT (`bun run fmt`), and
-// denying the bare binary while that stays open would be theatre. `shipkit ci`
-// formats before it gates, which is the only reason the reflex matters at all.
+// the LINTER and the FORMATTER are deliberately absent. `bun lint` and
+// `bun fmt` are the house way in: bun's built-ins cover a whole repo in well
+// under a second, so a cache has nothing to save, and the formatter is a
+// manual tool the gate never runs.
 
 /** the `permissions.deny` entries, in the syntax Claude Code matches:
  *  `Bash(<head>*)` is a prefix match, and a compound command is checked one
  *  segment at a time, so `cd x && bun test` is caught too */
 export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
     const off = new Set(exemptSlots)
-    return RAW_RUNNERS.filter((r) => !off.has(r.slot)).map((r) => `Bash(${r.head}*)`)
+    return [...RAW_RUNNERS.filter((r) => !off.has(r.slot)).map((r) => `Bash(${r.head}*)`), GIT_STASH_RULE]
+}
+
+// `git stash` in a tree that other agents share takes every agent's
+// uncommitted work, not just the caller's (identity/how-we-commit.md: never
+// stash as a side effect). The deny row is the floor. Claude Code matches it
+// per subcommand of a compound and inside `$(...)`, and never inside
+// `bash -c '...'`, after git's own global options (`git -C dir stash`), or
+// through `eval`: the guard closes those (stashCallIn).
+export const GIT_STASH_HEAD = 'git stash'
+export const GIT_STASH_RULE = `Bash(${GIT_STASH_HEAD}*)`
+
+/** the stash subcommands that only read, which the guard lets through */
+const STASH_READS = new Set(['list', 'show'])
+
+/** git's global options that take their value as the NEXT word */
+const GIT_VALUE_OPTS = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--config-env', '--exec-path'])
+
+const unquote = (w: string): string => w.replace(/^(['"])(.*)\1$/, '$2')
+
+/** a segment's words, a quoted run kept as one word, subshell and group
+ *  brackets dropped */
+const quotedWords = (seg: string): string[] =>
+    (seg.match(/(?:'[^']*'|"(?:[^"\\]|\\.)*"|[^\s'"])+/g) ?? []).map((w) => w.replace(/^[({]+|[)}]+$/g, '')).filter((w) => w !== '')
+
+/** the bodies of `$(...)` and backtick substitutions outside single quotes,
+ *  where a shell runs them */
+function substitutions(seg: string): string[] {
+    const out: string[] = []
+    let single = false
+    for (let i = 0; i < seg.length; i++) {
+        const ch = seg[i]!
+        if (ch === "'") { single = !single; continue }
+        if (single) continue
+        if (ch === '`') {
+            const end = seg.indexOf('`', i + 1)
+            if (end < 0) break
+            out.push(seg.slice(i + 1, end))
+            i = end
+        } else if (ch === '$' && seg[i + 1] === '(') {
+            let depth = 0
+            let j = i + 1
+            for (; j < seg.length; j++) {
+                if (seg[j] === '(') depth++
+                else if (seg[j] === ')' && --depth === 0) break
+            }
+            out.push(seg.slice(i + 2, j))
+            i = j
+        }
+    }
+    return out
+}
+
+/** the script a segment hands to another shell: `bash -c '<script>'`,
+ *  `sh -c`, `zsh -c`, or `eval <words>` */
+function innerScript(words: string[], seg: string): string | null {
+    const program = words[0]?.split('/').pop() ?? ''
+    if (program === 'eval') {
+        const all = quotedWords(seg)
+        return all.slice(all.indexOf(words[0]!) + 1).map(unquote).join(' ')
+    }
+    if (!/^(?:ba|z|da|k)?sh$/.test(program)) return null
+    const m = /\s-[a-z]*c[a-z]*\s+(?:'([^']*)'|"((?:[^"\\]|\\.)*)"|(\S+))/.exec(seg)
+    return m == null ? null : (m[1] ?? m[2] ?? m[3] ?? null)
+}
+
+/** the segment of a command that runs a stash which is not a read, or null.
+ *  Like rawRunnerHit it reads only what a shell would RUN: a heredoc body and
+ *  a quoted argument are data, so a commit message that mentions the command
+ *  is never refused. */
+export function stashCallIn(command: string, depth = 0): string | null {
+    if (depth > 3) return null
+    for (const seg of shellSegments(command)) {
+        for (const inner of substitutions(seg)) {
+            const hit = stashCallIn(inner, depth + 1)
+            if (hit != null) return hit
+        }
+        const words = programWords(seg)
+        const script = innerScript(words, seg)
+        if (script != null) {
+            const hit = stashCallIn(script, depth + 1)
+            if (hit != null) return hit
+            continue
+        }
+        if ((words[0]?.split('/').pop() ?? '') !== 'git') continue
+        // re-split with quotes kept whole: `git -C "a dir" stash`
+        const all = quotedWords(seg)
+        const g = all.findIndex((w) => w.split('/').pop() === 'git')
+        const args = all.slice(g + 1)
+        let i = 0
+        while (i < args.length && args[i]!.startsWith('-')) i += GIT_VALUE_OPTS.has(args[i]!) ? 2 : 1
+        if (unquote(args[i] ?? '') !== 'stash') continue
+        if (!STASH_READS.has(unquote(args[i + 1] ?? ''))) return seg.trim()
+    }
+    return null
+}
+
+/** what a stash refusal says: why, what to do instead, how to lift it */
+export function stashRefusal(segment: string): string {
+    return `\`${segment.slice(0, 80)}\` stashes: in a tree that other agents share, a stash takes every agent's uncommitted work, not just yours. Set your own work aside with a commit by pathspec (git commit -m … -- <paths>), and read an existing stash by revision: \`git log -g --oneline refs/stash\`, \`git show stash@{0}:<file>\`. Lifting this: delete the "${GIT_STASH_RULE}" line from .claude/settings.json permissions.deny (identity/how-we-commit.md).`
 }
 
 /** what a refusal says. Never just the ban: a refusal with no replacement