rvlib-shipkit 1.9.0 → 2.0.1

package/src/core/pre-commit-discovery.ts

@@ -0,0 +1,106 @@
+// discovery for the pre-commit gate: import ONLY the check files that run a
+// body at commit. Full discovery imports every check file to read one field,
+// and a repo file that imports heavy modules at its top level then costs every
+// commit, seconds once its sources moved since the last transpile.
+//
+// A table beside the per worktree git dir remembers, per file, whether it
+// declares `onPreCommit`, keyed on the file's mtime and size. A file whose
+// stamp still matches and that runs nothing at commit is never imported. A
+// file that moved is imported again, and every import is timed, so a slow
+// one is named on the commit that pays for it.
+//
+// The stamp is the file's own: a check that takes its `runs` from another
+// module is re-read when its own file moves, or when the table is dropped.
+import { mkdirSync, readFileSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { gitRoot } from './git-root.ts'
+import { atomicWrite } from './locked-write.ts'
+import { BUILTIN_CHECK_DIR, discoverChecks, type DiscoveredCheck } from './discover-checks.ts'
+
+/** a repo check file whose import takes longer than this, warm, is named */
+export const SLOW_IMPORT_MS = 30
+
+const TABLE_VERSION = 1
+
+type Row = { stamp: string; preCommit: boolean }
+type Table = { v: number; files: Record<string, Row> }
+
+export const declarationsTable = (root: string): string | null => {
+    const dir = gitRoot(root)?.gitDir
+    return dir == null ? null : join(dir, 'shipkit', 'check-declarations.json')
+}
+
+function readTable(path: string | null): Table {
+    if (path == null) return { v: TABLE_VERSION, files: {} }
+    try {
+        const t = JSON.parse(readFileSync(path, 'utf8')) as Table
+        if (t.v === TABLE_VERSION && t.files != null && typeof t.files === 'object') return t
+    } catch {}
+    return { v: TABLE_VERSION, files: {} }
+}
+
+const stampOf = (path: string): string | null => {
+    try {
+        const s = statSync(path)
+        return `${s.mtimeMs}:${s.size}`
+    } catch {
+        return null
+    }
+}
+
+export type PreCommitDiscovery = {
+    /** what discovery returns, minus the files the table skipped */
+    checks: DiscoveredCheck[]
+    /** repo check files whose import took longer than SLOW_IMPORT_MS */
+    slow: { path: string; ms: number }[]
+    /** how many files were imported, and how many the table skipped */
+    imported: number
+    skipped: number
+}
+
+export async function discoverPreCommit(root: string): Promise<PreCommitDiscovery> {
+    const path = declarationsTable(root)
+    const table = readTable(path)
+    const stamps = new Map<string, string | null>()
+    const stamp = (f: string): string | null => {
+        if (!stamps.has(f)) stamps.set(f, stampOf(f))
+        return stamps.get(f) ?? null
+    }
+    let changed = false
+    let skipped = 0
+    let imported = 0
+    const slow: { path: string; ms: number }[] = []
+    const checks = await discoverChecks(root, {
+        skip: (f) => {
+            const row = table.files[f]
+            const hit = row != null && !row.preCommit && row.stamp === stamp(f)
+            if (hit) skipped++
+            return hit
+        },
+        imported: (f, ms, def, loaded) => {
+            imported++
+            if (!f.startsWith(`${BUILTIN_CHECK_DIR}/`) && ms > SLOW_IMPORT_MS) slow.push({ path: f, ms })
+            const s = stamp(f)
+            // a file that did not load is asked again next time: its error is
+            // the gate's to show, never the table's to remember
+            if (!loaded || s == null) return
+            const row: Row = { stamp: s, preCommit: def != null && def.runs.onPreCommit !== false }
+            const prev = table.files[f]
+            if (prev?.stamp === row.stamp && prev.preCommit === row.preCommit) return
+            table.files[f] = row
+            changed = true
+        },
+    })
+    if (changed && path != null) {
+        // a row whose file is gone is dropped, so the table never outgrows the repo
+        for (const f of Object.keys(table.files)) if (stamp(f) == null) delete table.files[f]
+        try {
+            mkdirSync(dirname(path), { recursive: true })
+            atomicWrite(path, JSON.stringify(table))
+        } catch {
+            // a table that cannot be written costs the next commit the full
+            // import, never its answer
+        }
+    }
+    return { checks, slow, imported, skipped }
+}

package/src/core/retired-checks.ts

@@ -2,6 +2,8 @@
 // id is never reused, so a doc or a changelog may still name one, and
 // discovery refuses a built-in that takes one again.
 export const RETIRED_CHECK_IDS: Readonly<Record<string, string>> = {
+    SK009: 'the AI attribution guard is gone: no rule polices commit trailers',
+    SK014: 'the STE prose rule is gone: no rule polices prose style',
     SK021: "the gh login is a machine fact: the house repo's github-login check runs src/core/gh-login.ts",
     SK023: "the store caps are the machine daemon's health: the house repo's stores-under-cap check",
 }

package/src/core/run-ci.ts

@@ -137,18 +137,22 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // what the reader never acts on: kept for STATUS.md and --verbose, never
     // printed on a default run, where every line costs a reader tokens
     const detail = (l: string): void => { collected.push(l); if (o.verbose === true) print(l) }
+    // a check that answered green says nothing a reader acts on: the verdict
+    // counts it. What needs a reader (a WARN, a FAIL and its fix, a wait for a
+    // machine slot) always prints
+    const checkLine = (l: string): void => (/^(ok|skip): /.test(l) && !/^ok: waiting\b/.test(l) ? detail : sink)(l)
     let c = o.config ?? (await loadRepoConfig(root))
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
-    // a NARROWED run repairs nothing unless --fix asks, and even then only the
-    // mechanical slots. `bun run test` routes here and must answer the one
+    // a NARROWED run repairs nothing unless --fix asks, and even then only
+    // what the named checks own: their own ci repair and the fixer slot that
+    // governs one of them. `bun run test` routes here and must answer the one
     // question its name promises without leaving files in the agent's diff
-    // that it never wrote: in a shared tree the formatter rewrites every other
-    // agent's files too. The structural rule fixers rewrite package.json and
-    // repo config, and arming rewrites hooks/: the full gate's price alone
+    // that it never wrote: in a shared tree a tree wide fixer rewrites every
+    // other agent's files too. Arming rewrites hooks/: the full gate's price alone
     const narrowed = (o.onlyIds ?? []).length > 0
     if (fixPassRuns(o)) {
-        const pass = await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink, detail })
+        const pass = await runFixPass(root, c, { rules: o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink, detail, ...(narrowed ? { only: o.onlyIds } : {}) })
         fixFailed = pass.failed
         // a fixer that rewrote the config or moved a check file leaves the
         // config above describing a repo that is gone, so the gate reads the
@@ -179,7 +183,9 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         // the harness refused it the raw runner, so the line says what to add
         // rather than leaving it with `unknown check id` and no next move
         if ((o.onlyIds ?? []).includes(u.id))
-            sink(`      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
+            sink(u.id === 'lint'
+                ? `      fix: add a [lint] section to bunfig.toml, then \`shipkit ci --only lint\` runs \`bun lint\` (build/typescript.md)`
+                : `      fix: add a '${u.id}:raw' script holding the tool, then \`shipkit ci --only ${u.id}\` runs it (meta/rv-conventions/package-json.md)`)
     }
     // the run record: one run id for every check of this gate, so a breakdown
     // of the wall time is reconstructable. It is never read here, only written
@@ -252,7 +258,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         runLog,
         onCheck: o.onCheck,
         reportHome: false,
-        print: sink,
+        print: checkLine,
         detail,
     })
     // what the suite ACTUALLY ran, from its own headline. A flag that was set
@@ -289,10 +295,10 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
         // why every check that did not replay ran, grouped: a re-run nobody
         // can explain costs a reader more than the line does
-        for (const { line, quiet } of ledger.explain()) (quiet ? detail : sink)(formatLine(line, false))
+        for (const { line } of ledger.explain()) detail(formatLine(line, false))
     }
     // one write for the whole gate, after everything has finished
-    for (const l of runLog.flush()) sink(formatLine(l, false))
+    for (const l of runLog.flush()) checkLine(formatLine(l, false))
     const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownOff.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
     // THE VERDICT, one line and only on a pass: a red run already said so in
     // its FAIL lines. The whole gate adds the tier and the cache counts, which

package/src/core/run-fix.ts

@@ -15,6 +15,10 @@ import type { RepoConfig } from '../repo-config.ts'
 
 export type FixOpts = {
     ids?: string[]
+    /** the gate's `--only` names: of the ci repairs, only the ones these
+     *  name, by check id or by group, and silently none for a name that has
+     *  no repair */
+    scope?: string[]
     /** drop the closing advisory: inside the ci fix pass it is noise, and it is
      *  not wire-shaped, which the frozen output contract forbids */
     quiet?: boolean
@@ -55,6 +59,11 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
 
     // no ids: the repairs declared for the gate. A manual one runs by name
     let targets = all.filter((r) => r.fix != null && r.when === 'ci')
+    if (o.scope != null) {
+        const named = new Set(o.scope)
+        const groups = new Map((await gateInventory(root, config)).map((r) => [r.decl.id, r.group]))
+        targets = targets.filter((r) => named.has(r.id) || named.has(groups.get(r.id) ?? ''))
+    }
     if (o.ids != null && o.ids.length > 0) {
         for (const id of o.ids) {
             const r = all.find((x) => x.id === id)

package/src/core/run-fixers.ts

@@ -1,20 +1,20 @@
 // what `shipkit ci` repairs before it gates.
 //
-// mechanical slots only (formatter, import canonicaliser): they rewrite the
-// files the agent is already editing and their output is total. structural
-// SK rule fixers rewrite repo config, so they stay behind --fix-rules.
+// mechanical slots only (the import canonicaliser): it rewrites the files the
+// agent is already editing and its output is total. structural SK rule fixers
+// rewrite repo config, so they stay behind --fix-rules. no formatter runs
+// here: formatting is a manual `bun fmt`, never a gate step.
 //
 // under CI the same fixers run in verify mode instead: a gate that silently
 // rewrites the tree it checks can turn red green with no commit. one
-// mechanism, two modes, rather than a formatter plus a format:check that
-// drift apart.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+// mechanism, two modes, rather than a fixer plus a check that drift apart.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { dirname, isAbsolute, join } from 'path'
 import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { runFix } from './run-fix.ts'
-import { routesToShipkit } from './canonical-scripts.ts'
+import { repoOff } from './when.ts'
 import { discoverLegacyChecks } from './discover-legacy-checks.ts'
 import { repoCheckFiles } from './discover-checks.ts'
 import { mutateLease, withMutateLease } from './locked-write.ts'
@@ -24,6 +24,8 @@ import { spawnWithTimeout } from './spawn-timeout.ts'
 import { gitBin } from './git-bin.ts'
 import { LAYOUT } from './layout.ts'
 import { gateBinary, toolchainIdentity } from '../ledger/toolchain-identity.ts'
+import { isVendored } from './vendored.ts'
+import { readVendored } from './vendored-read.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
 
@@ -35,8 +37,6 @@ export type FixerSlot = {
 
 export type FixerResolution = {
     slots: FixerSlot[]
-    /** slots nothing could fill, printed, never silent */
-    unfilled: { id: string; reason: string }[]
     /** slots the repo turned off, printed with the same vocabulary the task
      *  side uses, so a disable is never invisible in the output */
     disabled: { id: string; reason: string }[]
@@ -47,10 +47,6 @@ export type FixerResolution = {
 // anyway is the config saying one thing and the tool doing another.
 const GOVERNED_BY: Record<string, string> = { 'imports:fix': 'imports:check' }
 
-// one fixer per mechanical concern. `fmt` accepts the two names the house
-// vocabulary allows so a repo that calls it `format` is not silently unfixed.
-const FMT_SCRIPTS = ['fmt', 'format'] as const
-
 export function resolveFixers(root: string, config?: RepoConfig): FixerResolution {
     const pkgPath = join(root, 'package.json')
     let scripts: Record<string, string> = {}
@@ -59,31 +55,23 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
         catch (e) { throw new Error(`package.json unparseable — fixers cannot register: ${String(e).slice(0, 120)}`) }
     }
     const slots: FixerSlot[] = []
-    const unfilled: { id: string; reason: string }[] = []
     const disabled: { id: string; reason: string }[] = []
     const offByConfig = (id: string): boolean => {
         const governing = GOVERNED_BY[id]
         if (governing == null) return false
-        if (config?.defaults?.[governing] !== false) return false
-        disabled.push({ id, reason: `skipped-by-config (defaults: { '${governing}': false })` })
+        const off = config == null ? null : repoOff(config, governing)
+        if (off == null) return false
+        disabled.push({ id, reason: `skipped-by-config (${governing} is off: ${off.reason})` })
         return true
     }
 
-    // `fmt` is the one slot the fix pass invokes BY SCRIPT, so it is the one
-    // name ONE WAY IN deliberately leaves raw: a routed body here would make
-    // the fixer spawn the gate that spawns the fixer
-    const fmtName = FMT_SCRIPTS.find((n) => scripts[n] != null && !routesToShipkit(scripts[n]!))
-    if (fmtName != null) slots.push({ id: 'fmt', cmd: ['bun', 'run', fmtName], source: 'package.json script' })
-    else if (FMT_SCRIPTS.some((n) => scripts[n] != null)) unfilled.push({ id: 'fmt', reason: `the 'fmt' script routes back to shipkit — the fix pass runs it, so it holds the formatter itself` })
-    else unfilled.push({ id: 'fmt', reason: `no 'fmt' or 'format' script — formatting stays a manual step` })
-
     if (offByConfig('imports:fix')) { /* the repo said no, in the one place that governs both directions */ }
     else if (scripts['imports:fix'] != null) slots.push({ id: 'imports:fix', cmd: ['bun', 'run', 'imports:fix'], source: 'package.json script' })
     else {
         const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
         slots.push({ id: 'imports:fix', cmd: ['bun', cli, 'imports', '--fix'], source: 'built-in (shipkit)' })
     }
-    return { slots, unfilled, disabled }
+    return { slots, disabled }
 }
 
 /** worktree fingerprint: every dirty path mapped to its CONTENT hash, or null
@@ -101,10 +89,9 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
  *  bytes attributes only what a fixer can actually have done.
  *
  *  It watches the WHOLE tree on purpose. A narrower porcelain was tried and
- *  deleted: the only fixer whose targets are declarable is the formatter, and
- *  the same pass also runs the rule fixers, which rewrite package.json,
- *  .gitignore, CLAUDE.md and .claude/, none of them inside a formatter's
- *  scope. Narrowing to the formatter's paths therefore hid real rewrites from
+ *  deleted: the same pass also runs the rule fixers, which rewrite
+ *  package.json, .gitignore, CLAUDE.md and .claude/, none of them inside a
+ *  source fixer's scope. Narrowing to the fixers' paths therefore hid real rewrites from
  *  the verify mode, which is a silent green on a tree a fixer changed. What
  *  actually stops another agent's work being reported here is the lease plus
  *  the byte comparison, not a path list. */
@@ -125,6 +112,50 @@ function treeState(root: string): Map<string, string> | null {
     return m
 }
 
+/** the vendored files whose work tree differs from the index, each with its
+ *  bytes (null when deleted). One pathspec limited diff, paths relative to
+ *  `root` even in a nested repo, so a repo with no vendored dir costs nothing */
+function vendoredState(root: string, dirs: readonly string[]): Map<string, Buffer | null> {
+    const m = new Map<string, Buffer | null>()
+    if (dirs.length === 0) return m
+    const p = Bun.spawnSync([gitBin(), 'diff', '--name-only', '--relative', '-z', '--', ...dirs], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+    if (p.exitCode !== 0) return m
+    for (const path of p.stdout.toString().split('\0')) {
+        if (path === '' || !isVendored(path, dirs)) continue
+        try { m.set(path, readFileSync(join(root, path))) } catch { m.set(path, null) }
+    }
+    return m
+}
+
+/** put back every vendored file a fixer changed since `before`: its bytes from
+ *  before when it differed from the index then, the index's otherwise */
+function restoreVendored(root: string, dirs: readonly string[], before: Map<string, Buffer | null>): { restored: string[]; failed: string[] } {
+    const restored: string[] = []
+    const failed: string[] = []
+    const fromIndex: string[] = []
+    const now = vendoredState(root, dirs)
+    const putBack = (path: string, was: Buffer | null): void => {
+        try {
+            if (was === null) rmSync(join(root, path), { force: true })
+            else writeFileSync(join(root, path), was)
+            restored.push(path)
+        } catch { failed.push(path) }
+    }
+    for (const [path, bytes] of now) {
+        const was = before.get(path)
+        if (was === undefined) fromIndex.push(path)
+        else if (was === null ? bytes !== null : bytes === null || !was.equals(bytes)) putBack(path, was)
+    }
+    // differed from the index before and matches it now: a fixer undid an edit
+    for (const [path, was] of before) if (!now.has(path)) putBack(path, was)
+    if (fromIndex.length > 0) {
+        const p = Bun.spawnSync([gitBin(), 'checkout', '--', ...fromIndex], { cwd: root, stdout: 'ignore', stderr: 'ignore' })
+        if (p.exitCode === 0) restored.push(...fromIndex)
+        else failed.push(...fromIndex)
+    }
+    return { restored: restored.sort(), failed: failed.sort() }
+}
+
 /** where the key of the last clean fix pass is kept, per checkout */
 const memoPath = (root: string): string => join(root, LAYOUT.tmp, 'fix-pass.key')
 
@@ -173,7 +204,11 @@ export type FixPassOpts = {
      *  mutate the tree they are about to ship) */
     armHooks?: boolean
     print: (line: string) => void
-    /** where the lines nobody acts on go (a clean pass, an unfilled slot).
+    /** a narrowed pass (`sk ci --only <ids> --fix`): only the repairs these
+     *  ids own, their own ci repair and the fixer slot that governs one of
+     *  them */
+    only?: string[]
+    /** where the lines nobody acts on go (a clean pass, a disabled slot).
      *  Default: print. `shipkit ci` shows them only under --verbose */
     detail?: (line: string) => void
 }
@@ -194,7 +229,7 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     // not clean, and the gate says so instead of quietly repairing it
     const verify = process.env.CI != null && process.env.CI !== ''
     // EVERY write this function makes sits inside one lease. Three agents in
-    // one checkout is the normal case, and two formatters rewriting the same
+    // one checkout is the normal case, and two fixers rewriting the same
     // file at once, or two runs arming hooks and rewriting package.json
     // together, is the one hazard a snapshot diff cannot even detect. The
     // loser waits rather than skipping, because a skipped repair never
@@ -260,17 +295,34 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
         else if (armed.state === 'failed') o.print(`WARN hooks could not arm: ${armed.detail}`)
     }
     const detail = o.detail ?? o.print
-    const { slots, unfilled, disabled } = resolveFixers(root, config)
-    for (const u of unfilled) detail(`skip: ${u.id} (${u.reason})`)
+    const resolution = resolveFixers(root, config)
+    const { disabled } = resolution
+    const named = o.only == null ? null : new Set(o.only)
+    const slots = named == null ? resolution.slots : resolution.slots.filter((s) => named.has(GOVERNED_BY[s.id] ?? ''))
+    if (named != null) for (const s of resolution.slots) if (!slots.includes(s)) detail(`skip: ${s.id} (--only ${o.only!.join(', ')} names no check it repairs)`)
     for (const d of disabled) detail(`skip: ${d.id} (${d.reason})`)
     const before = treeState(root)
     // the fixers already ran clean over exactly this tree (HEAD, every dirty
     // path's bytes, the toolchain, the commands): running them again rewrites
-    // nothing and costs a whole formatter pass. CI never skips: there the
+    // nothing and costs a whole fixer pass. CI never skips: there the
     // pass IS the check
     const memo = verify || before == null ? null : fixMemo(root, before, slots.map((s) => s.cmd))
     const skip = memo != null && readMemo(root) === memo
     let fixersOk = true
+    // third party code stays byte identical: whatever a fixer wrote under a
+    // vendored dir goes back at once, and the fixer is named so the repo
+    // scopes it (it walked those files for nothing)
+    let vendored: string[] = []
+    try { vendored = readVendored(root) } catch (e) { o.print(`WARN vendored dirs unreadable, nothing guards them this pass: ${String((e as Error)?.message ?? e).slice(0, 160)}`) }
+    let guard = vendoredState(root, vendored)
+    const putBack = (who: string): void => {
+        if (vendored.length === 0) return
+        const { restored, failed } = restoreVendored(root, vendored, guard)
+        if (restored.length > 0) o.print(`WARN ${who} rewrote ${restored.length} vendored file(s), put back byte for byte: ${restored.slice(0, 4).join(' ')}${restored.length > 4 ? ` … +${restored.length - 4}` : ''}`)
+        if (restored.length > 0) o.print(`      fix: scope ${who} to leave ${vendored.join(', ')} out (repo.config.ts \`vendored\`)`)
+        if (failed.length > 0) o.print(`WARN ${who} rewrote vendored file(s) that could not be put back: ${failed.slice(0, 4).join(' ')} — restore them with git checkout`)
+        guard = vendoredState(root, vendored)
+    }
     if (skip) detail(`ok: fixers skipped, the tree is unchanged since they last ran clean (${slots.length} fixer(s))`)
     else for (const s of slots) {
         const r = await spawnWithTimeout(s.cmd, { cwd: root, timeoutMs: FIXER_TIMEOUT_MS })
@@ -280,9 +332,13 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
             fixersOk = false
             o.print(`WARN fix ${s.id} failed (exit ${r.code}) — ${r.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}; the gate below still ran`)
         }
+        putBack(`fix ${s.id} (${s.cmd.join(' ').slice(0, 60)})`)
     }
     // structural repo-config repair is never implicit, and never in verify mode
-    if (o.rules === true && !verify) await runFix(root, { quiet: true, print: o.print, detail: o.detail, config })
+    if (o.rules === true && !verify) {
+        await runFix(root, { quiet: true, print: o.print, detail: o.detail, config, ...(o.only == null ? {} : { scope: o.only }) })
+        putBack('the rule repairs')
+    }
 
     const after = treeState(root)
     const reshaped = shapeStamp(root) !== shapeBefore

package/src/core/runs-matrix.ts

@@ -5,6 +5,9 @@
 import type { CheckRow } from '../ledger/gate-checks.ts'
 import { cellText, RUNS_KEYS, type RunsAxis, type RunsSource } from './runs.ts'
 
+/** the commit column's words for a commit gate (hooks/hook-gates.ts HookName) */
+const HOOK_WORDS: readonly string[] = ['pre-commit', 'commit-msg', 'both']
+
 export type MatrixAxis = RunsAxis | 'fix'
 
 export const MATRIX_AXES: readonly MatrixAxis[] = [...RUNS_KEYS, 'fix']
@@ -103,6 +106,9 @@ export function runsCellsOf(row: CheckRow): RunsCells {
     const r = row.runs
     const cells = Object.fromEntries(MATRIX_AXES.map((k) => {
         const v = k === 'fix' ? r.fix : r[k]
+        // a commit gate runs in a git hook rather than as an onPreCommit body,
+        // and the commit column names which hook
+        if (k === 'onPreCommit' && row.hook != null) return [k, { text: row.hook, on: r.off == null, source: r.source[k] }]
         const on = r.off == null && v !== false && v !== 'none'
         return [k, { text: cellText(r, k), on, source: r.source[k] }]
     })) as Record<MatrixAxis, RunsCell>
@@ -127,6 +133,7 @@ export function runsWords(c: RunsCells): string {
  *  prints short (yes, ·, moved, 24h); the legend names the declared value */
 export function cellMeaning(k: MatrixAxis | 'cache', text: string): string {
     const values = RUNS_LEGEND.find((a) => a.axis === k)!.values
+    if (k === 'onPreCommit' && HOOK_WORDS.includes(text)) return 'a commit gate: that git hook runs it on every commit, and `shipkit hooks list` shows it'
     const declared = k === 'cache'
         ? text.split(/[\s:]/)[0]!
         : text === 'yes' ? 'true'

package/src/core/slots.ts

@@ -5,7 +5,7 @@
 // holder died is free at once, and a live holder heartbeats it.
 //
 // A slot is a check, and a check is often a whole multi core tool (bun test
-// workers, oxlint threads, tsc), so slots alone never bound the CPU. Past the
+// workers, linter threads, tsc), so slots alone never bound the CPU. Past the
 // cores the pool admits fewer slots in proportion to the 1 minute load, never
 // fewer than one (admittedSlots). A slot already held is never taken back.
 //

package/src/core/vendored-read.ts

@@ -0,0 +1,39 @@
+// the disk half of core/vendored.ts: a repo's vendored dirs, read off its
+// config text, remembered per root while the file holds still.
+import { existsSync, readFileSync, statSync } from 'fs'
+import { dirname, join, resolve } from 'path'
+import { vendoredOfText } from './vendored.ts'
+
+const CONFIG_FILE = 'repo.config.ts'
+
+const memo = new Map<string, { stamp: string; dirs: string[] }>()
+
+/** the vendored dirs of the repo at `root`, from its config text. Empty with
+ *  no config. Remembered per root while the file's size and mtime hold */
+export function readVendored(root: string): string[] {
+    const path = join(root, CONFIG_FILE)
+    let stamp: string
+    try {
+        const s = statSync(path)
+        stamp = `${s.size}:${s.mtimeMs}`
+    } catch {
+        return []
+    }
+    const hit = memo.get(root)
+    if (hit?.stamp === stamp) return hit.dirs
+    const dirs = vendoredOfText(readFileSync(path, 'utf8'))
+    memo.set(root, { stamp, dirs })
+    return dirs
+}
+
+/** the repo a dir sits in (the nearest dir up holding repo.config.ts) and its
+ *  vendored dirs, null outside any shipkit repo */
+export function vendoredAround(dir: string): { root: string; dirs: string[] } | null {
+    let cur = resolve(dir)
+    for (;;) {
+        if (existsSync(join(cur, CONFIG_FILE))) return { root: cur, dirs: readVendored(cur) }
+        const up = dirname(cur)
+        if (up === cur) return null
+        cur = up
+    }
+}

package/src/core/vendored.ts

@@ -0,0 +1,82 @@
+// `vendored` in repo.config.ts: repo-relative dirs of THIRD PARTY code (a git
+// subtree, a copied library) that no shipkit tool lints, formats, rewrites or
+// analyses as the repo's own source. Read as TEXT, never by loading the
+// config: the source-graph cli, the md scan and the file listings run where
+// the config is never loaded, and a prefix test per path is the whole cost.
+// loadRepoConfig refuses a config whose loaded value and text disagree.
+// Pure, so a check's closure can import it: the disk half is vendored-read.ts.
+//
+// the one constraint a reader breaks first: cache keys and watchers still
+// read vendored files. Vendored code is still an INPUT to builds and tests;
+// only the tools that treat the tree as the repo's own source omit it.
+import { configDepths } from './identity-color.ts'
+
+const CONFIG_FILE = 'repo.config.ts'
+
+const KEY_RE = /(?:^|[{,])\s*(['"]?)vendored\1\s*:\s*/gm
+
+/** an entry as every tool compares it: posix, no `./`, no trailing `/` */
+export const normalizeVendored = (d: string): string => d.replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '')
+
+/** why an entry cannot be a vendored dir, null when it can */
+export function vendoredProblem(entry: unknown): string | null {
+    if (typeof entry !== 'string' || entry.trim() === '') return 'is not a repo-relative dir path'
+    const d = normalizeVendored(entry)
+    if (d === '' || d === '.') return 'is the repo root: it would omit the whole repo from every tool'
+    if (entry.startsWith('/') || d.split('/').includes('..')) return 'leaves the repo: name a dir inside it'
+    if (/[*?[\]{}!]/.test(d)) return 'is a glob: name the dir itself, every path under it is omitted'
+    return null
+}
+
+/** the `vendored` entries the config text declares, normalized. Empty when
+ *  the key is absent. Throws when the value is anything but a literal array
+ *  of string literals, which a reader of the text cannot evaluate */
+export function vendoredOfText(text: string): string[] {
+    const depth = configDepths(text)
+    const found: string[][] = []
+    for (const m of text.matchAll(KEY_RE)) {
+        const sep = /^[{,]/.test(m[0]) ? m.index : m.index - 1
+        const colon = m.index + m[0].lastIndexOf(':')
+        if (sep < 0 || depth[sep] !== 1 || depth[colon] !== 1) continue
+        const open = m.index + m[0].length
+        if (text[open] !== '[') throw new Error(`${CONFIG_FILE}: \`vendored\` must be a literal array of strings, the tools that never load the config read it as text`)
+        let close = open + 1
+        while (close < text.length && !(text[close] === ']' && depth[close] === 1)) close++
+        if (close >= text.length) throw new Error(`${CONFIG_FILE}: \`vendored\` has no closing \`]\``)
+        const body = text.slice(open + 1, close).replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '')
+        const items: string[] = []
+        const rest = body.replace(/(['"])((?:\\.|(?!\1).)*)\1/g, (_, _q: string, s: string) => { items.push(s); return '' })
+        if (!/^[\s,]*$/.test(rest)) throw new Error(`${CONFIG_FILE}: \`vendored\` must list string literals only, the tools that never load the config read it as text`)
+        found.push(items.map(normalizeVendored))
+    }
+    if (found.length > 1) throw new Error(`${CONFIG_FILE} declares \`vendored\` more than once`)
+    return found[0] ?? []
+}
+
+/** is this repo-relative path a vendored dir or inside one */
+export function isVendored(rel: string, dirs: readonly string[]): boolean {
+    if (dirs.length === 0) return false
+    const n = rel.replace(/\\/g, '/').replace(/^(\.\/)+/, '')
+    return dirs.some((d) => n === d || n.startsWith(`${d}/`))
+}
+
+/** the glob's fixed leading dirs, before its first wildcard */
+const globBase = (glob: string): string => {
+    const segs = glob.replace(/^(\.\/)+/, '').split('/')
+    const fixed: string[] = []
+    for (const s of segs.slice(0, -1)) {
+        if (/[*?[\]{}!]/.test(s)) break
+        fixed.push(s)
+    }
+    return fixed.join('/')
+}
+
+/** a listing with the vendored files left out, unless the glob itself names a
+ *  path inside a vendored dir: a check that asks for `vendor/lib/src/**`
+ *  wants exactly those files */
+export function listingWithoutVendored(files: readonly string[], glob: string, dirs: readonly string[]): string[] {
+    if (dirs.length === 0) return [...files]
+    const base = globBase(glob)
+    if (base !== '' && isVendored(base, dirs)) return [...files]
+    return files.filter((f) => !isVendored(f, dirs))
+}