rvlib-shipkit 0.38.0 → 1.0.0

package/src/checks/SK017-vscode-hub-task.check.ts

@@ -0,0 +1,197 @@
+// SK017 vscode hub task (build/vscode-tasks.md): the folder-open hub task
+// carries the problem matcher the hub prints for, it opens with the folder
+// itself when nothing else does, and no `👁  TSC` watcher runs beside a gate
+// that already runs `typecheck`.
+//
+// the file is hand-written jsonc, so the fixer edits spans: it removes the TSC
+// task, a wrapper that only starts the hub, and their dependsOn entries, and
+// writes the hub's matcher and folder-open run option. Every other byte stays
+// as its author left it.
+import { basename } from 'path'
+import { check } from '../check.ts'
+import type { CheckCtx } from '../core/check-ctx.ts'
+import { checkFloorReader, resolveFloor } from '../core/floor-resolve.ts'
+import { whenOfTask } from '../core/when.ts'
+import { hubProblemMatcher } from '../problems/problem-line.ts'
+import { indentAt, parseSpans, plain, removalSpan, type Node } from '../scaffold/jsonc-spans.ts'
+
+export const TSC_LABEL = '👁  TSC'
+const TASKS = '.vscode/tasks.json'
+
+type Obj = Extract<Node, { kind: 'object' }>
+type Arr = Extract<Node, { kind: 'array' }>
+
+const prop = (o: Obj, key: string): Node | undefined => o.props.find((p) => p.key === key)?.value
+
+/** the house type checker task and nothing that only looks like it: the exact
+ *  label, a tsc binary, in watch mode */
+function isTscWatcher(t: Record<string, unknown>): boolean {
+    const cmd = typeof t['command'] === 'string' ? t['command'] : ''
+    const args = Array.isArray(t['args']) ? t['args'] : []
+    return t['label'] === TSC_LABEL && basename(cmd) === 'tsc' && args.includes('--watch')
+}
+
+/** the hub task: `bun run hub`, or the house label */
+function isHub(t: Record<string, unknown>): boolean {
+    const args = Array.isArray(t['args']) ? t['args'] : []
+    return (t['command'] === 'bun' && args[0] === 'run' && args[1] === 'hub') || (typeof t['label'] === 'string' && /^🚀\s+shipkit\b/.test(t['label']))
+}
+
+/** a task that only starts other tasks: no command of its own */
+const isWrapper = (t: Record<string, unknown>): boolean => t['command'] == null && t['type'] == null && t['dependsOn'] != null
+
+export type RepairOpts = {
+    /** the gate runs an enabled `typecheck` check. Without one the TSC task is
+     *  the only type checker this repo has, so it stays */
+    typecheckOn: boolean
+}
+
+/** what this file needs, applied: the text to write, one line per change, and
+ *  one line per thing it deliberately left. No change means the text comes
+ *  back byte for byte */
+export function repairTasks(text: string, o: RepairOpts): { text: string; changes: string[]; kept: string[] } {
+    const root = parseSpans(text)
+    if (root.kind !== 'object') throw new Error('tasks.json is not an object')
+    const tasks = prop(root, 'tasks')
+    if (tasks == null || tasks.kind !== 'array') return { text, changes: [], kept: [] }
+    const edits: { start: number; end: number; body: string }[] = []
+    const changes: string[] = []
+    const kept: string[] = []
+    const record = (t: Node): Record<string, unknown> => plain(text, t) as Record<string, unknown>
+    const labelOf = (t: Node): string => String(record(t)['label'] ?? '?')
+    const items = tasks.items.filter((n): n is Obj => n.kind === 'object')
+    const hubs = items.filter((t) => isHub(record(t)))
+
+    const tscAt = tasks.items.flatMap((n, i) => (n.kind === 'object' && isTscWatcher(record(n)) ? [i] : []))
+    const dropTsc = tscAt.length > 0 && o.typecheckOn
+    if (tscAt.length > 0 && !o.typecheckOn) kept.push(`kept the '${TSC_LABEL}' task: this repo's gate has no enabled typecheck check, so it is the only type checker here`)
+    if (dropTsc) for (const i of tscAt) {
+        const [start, end] = removalSpan(text, tasks, i)
+        edits.push({ start, end, body: '' })
+        changes.push(`removed the '${TSC_LABEL}' task`)
+    }
+
+    // a folder-open wrapper whose only job is starting the hub is a second
+    // task on screen for nothing: the hub opens with the folder itself
+    const hub = hubs.length === 1 ? hubs[0]! : null
+    const hubLabel = hub == null ? null : labelOf(hub)
+    const depsOf = (t: Node): string[] => {
+        const d = record(t)['dependsOn']
+        const list = Array.isArray(d) ? d.map(String) : [String(d)]
+        return dropTsc ? list.filter((x) => x !== TSC_LABEL) : list
+    }
+    const wrapperAt = hub == null ? -1 : tasks.items.findIndex((n) => n.kind === 'object' && isWrapper(record(n)) && depsOf(n).length === 1 && depsOf(n)[0] === hubLabel)
+    const wrapper = wrapperAt < 0 ? null : (tasks.items[wrapperAt] as Obj)
+    if (wrapper != null) {
+        const [start, end] = removalSpan(text, tasks, wrapperAt)
+        edits.push({ start, end, body: '' })
+        changes.push(`folded the '${labelOf(wrapper)}' wrapper into '${hubLabel}', which now opens with the folder`)
+        if (/\/\/.*(master task|subtask)/i.test(text)) changes.push('a comment still describes a master task with subtasks: rewrite it by hand')
+    }
+
+    if (dropTsc) {
+        for (const t of items) {
+            if (t === wrapper) continue
+            const d = prop(t, 'dependsOn')
+            if (d?.kind === 'array') {
+                const idx = d.items.findIndex((x) => x.kind === 'scalar' && x.value === TSC_LABEL)
+                if (idx < 0) continue
+                const [start, end] = removalSpan(text, d as Arr, idx)
+                edits.push({ start, end, body: '' })
+                changes.push(`dropped '${TSC_LABEL}' from the dependsOn of '${labelOf(t)}'`)
+            } else if (d?.kind === 'scalar' && d.value === TSC_LABEL) {
+                edits.push({ start: d.start, end: d.end, body: '[]' })
+                changes.push(`dropped '${TSC_LABEL}' from a dependsOn`)
+            }
+        }
+    }
+
+    const want = hubProblemMatcher()
+    for (const h of hubs) {
+        const first = h.props[0]
+        const hubIndent = indentAt(text, h.start)
+        const propIndent = first != null ? indentAt(text, first.keyStart) : `${hubIndent}   `
+        const unit = propIndent.length > hubIndent.length ? propIndent.slice(hubIndent.length) : '   '
+        const render = (v: unknown): string => JSON.stringify(v, null, unit).split('\n').join(`\n${propIndent}`)
+        const added: string[] = []
+        const current = prop(h, 'problemMatcher')
+        if (current == null || JSON.stringify(plain(text, current)) !== JSON.stringify(want)) {
+            if (current != null) edits.push({ start: current.start, end: current.end, body: render(want) })
+            else added.push(`"problemMatcher": ${render(want)}`)
+            changes.push(`wrote the shipkit problem matcher on '${labelOf(h)}'`)
+        }
+        if (h === hub && wrapper != null) {
+            const ro = prop(h, 'runOptions')
+            const was = ro != null && ro.kind === 'object' ? record(ro) : {}
+            const inline = `{ ${Object.entries(Object.assign({ runOn: 'folderOpen', instanceLimit: 1 }, was, { runOn: 'folderOpen' })).map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`).join(', ')} }`
+            if (ro != null) edits.push({ start: ro.start, end: ro.end, body: inline })
+            else added.push(`"runOptions": ${inline}`)
+            const wg = prop(wrapper, 'group')
+            if (wg != null) {
+                const body = text.slice(wg.start, wg.end)
+                const g = prop(h, 'group')
+                if (g != null) edits.push({ start: g.start, end: g.end, body })
+                else added.push(`"group": ${body}`)
+            }
+        }
+        if (added.length === 0) continue
+        const last = h.props.at(-1)
+        const joined = added.join(`,\n${propIndent}`)
+        if (last == null) edits.push({ start: h.start + 1, end: h.start + 1, body: `\n${propIndent}${joined}\n${hubIndent}` })
+        else edits.push({ start: last.value.end, end: last.value.end, body: `,\n${propIndent}${joined}` })
+    }
+
+    let out = text
+    for (const e of edits.sort((a, b) => b.start - a.start)) out = out.slice(0, e.start) + e.body + out.slice(e.end)
+    return { text: out, changes, kept }
+}
+
+/** whether this repo's gate runs a typecheck: a floor slot or a task that
+ *  resolves, and no `when` turning it off */
+export function typecheckOn(c: CheckCtx): boolean {
+    const config = c.config
+    let floor: ReturnType<typeof resolveFloor>
+    try { floor = resolveFloor(config, c.root, checkFloorReader(c)) } catch { return false }
+    const t = [...floor.tasks, ...(config.tasks ?? [])].find((x) => x.id === 'typecheck')
+    return t != null && whenOfTask(config, t).at !== 'off'
+}
+
+/** the tasks file this check may touch: none, or left alone because .vscode/
+ *  is a link to a dir shared with other repos */
+function ownTasks(c: CheckCtx): { text: string } | 'none' | 'linked' {
+    if (!c.exists(TASKS)) return 'none'
+    if (c.isLink('.vscode')) return 'linked'
+    const text = c.read(TASKS)
+    return text == null ? 'none' : { text }
+}
+
+export const vscodeHubTask = check({
+    id: 'SK017',
+    // a stale editor file is behind, not broken: it warns, and the fix pass
+    // repairs it
+    blocking: false,
+    title: 'vscode hub task',
+    description: 'the vscode hub task carries the problem matcher and no extra tsc watcher runs',
+    owner: 'build/vscode-tasks.md',
+    run: (c) => {
+        const own = ownTasks(c)
+        if (own === 'none') return c.ok(`no ${TASKS}, so there is no hub task to wire`)
+        if (own === 'linked') return c.ok(`.vscode/ is a link to a shared dir, left alone`)
+        let r: { changes: string[]; kept: string[] }
+        try { r = repairTasks(own.text, { typecheckOn: typecheckOn(c) }) }
+        catch (e) { return c.warn(`${TASKS} does not parse (${(e as Error).message}), so the hub task was not checked`) }
+        for (const k of r.kept) c.note(`${TASKS}: ${k}`)
+        if (r.changes.length === 0) return c.ok(`${TASKS}: the hub task feeds the problems pane`)
+        for (const ch of r.changes) c.fail(`${TASKS}: ${ch.replace(/^removed/, 'should remove').replace(/^dropped/, 'should drop').replace(/^wrote/, 'should write').replace(/^folded/, 'should fold')}`)
+    },
+    fix: (c) => {
+        const own = ownTasks(c)
+        if (typeof own === 'string') return { changed: false, summary: `no ${TASKS} to repair` }
+        const r = repairTasks(own.text, { typecheckOn: typecheckOn(c) })
+        if (r.changes.length === 0) return { changed: false, summary: `${TASKS} already current` }
+        c.write(TASKS, r.text)
+        return { changed: true, summary: `${TASKS}: ${r.changes.join(', ')}` }
+    },
+})
+
+export default vscodeHubTask

package/src/checks/SK018-test-files-run.check.ts

@@ -0,0 +1,28 @@
+// SK018 — every test file runs in a check (build/shipkit.md, the test checks).
+// A `*.test.ts` that no check runs is a green nobody measured: the file says
+// something is proved, and nothing proves it. Each file belongs to the release
+// unit whose dir holds it (the root takes the rest), and the unit's own
+// `bun test` must reach it. A file kept out on purpose goes under a bunfig
+// `pathIgnorePatterns` entry, which is where the reason is written.
+import { check } from '../check.ts'
+import { isTestFile, TEST_GLOB, testPlanOf } from '../suite/test-units.ts'
+
+export const testFilesRun = check({
+    id: 'SK018',
+    blocking: true,
+    title: 'test files run',
+    description: 'every test file in the repo runs in a test check or is ignored on purpose',
+    owner: 'build/shipkit.md',
+    run: (c) => {
+        const files = c.list(TEST_GLOB).filter(isTestFile)
+        if (files.length === 0) return c.ok('no test file in this repo')
+        const plan = testPlanOf({ config: c.config, files, read: (rel) => c.read(rel) })
+        for (const o of plan.orphans) c.fail(`${o.file} runs in no check: ${o.why}`, 'move it under a test root, fix the `bun test` arguments, or add it to bunfig.toml [test] pathIgnorePatterns with the reason in a comment')
+        for (const id of plan.opaque) c.note(`${id}: its script is not a plain \`bun test\`, so which files it runs cannot be read`)
+        const per = [...plan.runs].filter(([id, f]) => f.length > 0 || id === 'test').map(([id, f]) => `${id} ${f.length}`)
+        const ignored = plan.ignored.length > 0 ? `, ${plan.ignored.length} ignored on purpose` : ''
+        if (plan.orphans.length === 0) c.ok(`${files.length} test file(s) all run: ${per.join(', ')}${ignored}`)
+    },
+})
+
+export default testFilesRun

package/src/checks/SK019-tests-run-in-units.check.ts

@@ -0,0 +1,76 @@
+// SK019 — tests run through the generated test checks only (build/shipkit.md,
+// the test checks). The floor `test` slot and one `test:<unit>` per declared
+// unit are the ONE way tests run: in the unit's dir with its bunfig and
+// preload, parallel, timed against the budget, and planned file by file by
+// SK018. A hand written check that runs `bun test` itself is a second runner
+// none of that reaches. The allowed shapes are never scanned: the generated
+// checks are not files, and `defaults.test` IS the floor slot.
+//
+// Its own id rather than a line of SK018: SK018 answers "does every test file
+// run", this one "does anything else run them", and each is read from
+// different files (test files and bunfigs there, check sources and the config
+// here), so each keeps its own key, row and `when` switch.
+import { dirname, posix, relative } from 'path'
+import { check } from '../check.ts'
+import { repoCheckSources } from '../core/legacy-shapes.ts'
+import { argvRunsTests, commandRunsTests, sourceRunsTests, type ScriptReader } from '../suite/runner-shapes.ts'
+import type { CheckCtx } from '../core/check-ctx.ts'
+
+/** the scripts of the package.json in `dir` (repo relative), then the root's */
+const scriptsIn = (c: CheckCtx, dir: string): ScriptReader => {
+    const read = (d: string): Record<string, string> => {
+        try { return (JSON.parse(c.read(d === '' || d === '.' ? 'package.json' : posix.join(d, 'package.json')) ?? '{}') as { scripts?: Record<string, string> }).scripts ?? {} } catch { return {} }
+    }
+    const own = read(dir)
+    const root = read('')
+    return (name) => own[name] ?? root[name] ?? null
+}
+
+/** the floor slots besides `test`, whose package.json body must not run tests either */
+const OTHER_SLOTS = ['lint', 'typecheck', 'imports:check', 'cycles']
+
+const FIX = 'declare a unit instead (units in repo.config.ts): each unit gets its own generated `test:<unit>` check, run in its dir'
+
+export const testsRunInUnits = check({
+    id: 'SK019',
+    blocking: true,
+    title: 'tests run in unit checks',
+    description: 'no check runs the test runner itself: tests run only in the generated test checks',
+    owner: 'build/shipkit.md',
+    run: (c) => {
+        // the toolkit's own checks (this file's dir) live inside the repo that
+        // hosts it, and a built-in that WRITES a test script (SK001) is not a
+        // runner. Read off import.meta, since importing discovery pulls in fs
+        const builtins = relative(c.root, import.meta.dir).replace(/\\/g, '/')
+        const files = repoCheckSources(c).filter((f) => !f.rel.startsWith(`${builtins}/`))
+        let hits = 0
+        const say = (where: string, how: string): void => { hits++; c.fail(`${where} runs ${how} itself`, FIX) }
+        const root = scriptsIn(c, '')
+        const cwdOf = (cwd: string | undefined): string => (cwd == null ? '' : relative(c.root, posix.resolve(c.root, cwd)))
+        for (const f of files) for (const how of sourceRunsTests(f.src ?? '', scriptsIn(c, dirname(f.rel)))) say(f.rel, how)
+        for (const t of c.config.tasks ?? []) {
+            const scripts = scriptsIn(c, cwdOf(t.cwd))
+            const how = t.cmd != null ? argvRunsTests(t.cmd, scripts) : null
+            if (how != null) say(`repo.config.ts tasks '${t.id}'`, how)
+            else if (t.logic != null) for (const h of sourceRunsTests(String(t.logic), scripts)) say(`repo.config.ts tasks '${t.id}'`, h)
+        }
+        for (const r of c.config.rules ?? []) for (const h of sourceRunsTests(String(r.lint), root)) say(`repo.config.ts rules '${r.id}'`, h)
+        const defaults = c.config.defaults ?? {}
+        for (const [id, d] of Object.entries(defaults)) {
+            if (id === 'test' || d === false || d.cmd == null) continue
+            const how = argvRunsTests(d.cmd, scriptsIn(c, cwdOf(d.cwd)))
+            if (how != null) say(`repo.config.ts defaults '${id}'`, how)
+        }
+        // a slot the package.json fills: its raw body, else its own script
+        for (const id of OTHER_SLOTS) {
+            if (defaults[id] === false || (defaults[id] as { cmd?: unknown } | undefined)?.cmd != null) continue
+            const name = root(`${id}:raw`) != null ? `${id}:raw` : id
+            const body = root(name)
+            const how = body == null ? null : commandRunsTests(body, (n) => (n === name ? null : root(n)))
+            if (how != null) say(`package.json script '${name}' (the ${id} slot)`, how)
+        }
+        if (hits === 0) c.ok(`${files.length} check file(s) read, none runs the test runner: tests run only in the generated test checks`)
+    },
+})
+
+export default testsRunInUnits

package/src/checks/SK020-self-spawning-check.check.ts

@@ -0,0 +1,147 @@
+// SK020: a check file never spawns itself (build/shipkit/writing-a-check.md
+// owns the one body shape, `run: (c) => …`). A `cmd` that names the file's
+// own path runs the file a second time, in its own process, behind an
+// `import.meta.main` guard: a second way to write a body, with none of what
+// `c` gives (recorded reads, one pass, one runner).
+//
+// It reads each check file's SOURCE through `c`, never imports it, so it is
+// cached on the listing and the sources. A legacy check SCRIPT (no check
+// object) is SK016's, read through its window, and never counted here.
+import { check } from '../check.ts'
+import { isLegacyCheckSource } from '../core/check-file-names.ts'
+import { repoCheckSources } from '../core/legacy-shapes.ts'
+
+const OWNER = 'build/shipkit/writing-a-check.md'
+
+/** the source with every comment blanked, so a file that MENTIONS the
+ *  shape in a comment is not a file that has it, and a `/*` inside a glob
+ *  string opens no comment. `strings: false` blanks the strings too, for a
+ *  question about code rather than about an argv */
+export function codeOf(src: string, o: { strings: boolean } = { strings: true }): string {
+    let out = ''
+    let quote: string | null = null
+    for (let i = 0; i < src.length; i++) {
+        const ch = src[i]!
+        if (quote != null) {
+            const keep = o.strings || ch === quote
+            if (ch === '\\') {
+                i++
+                if (o.strings) out += ch + (src[i] ?? '')
+                continue
+            }
+            if (ch === quote) quote = null
+            if (keep) out += ch
+            continue
+        }
+        if (ch === '/' && src[i + 1] === '/') {
+            while (i < src.length && src[i] !== '\n') i++
+            out += '\n'
+            continue
+        }
+        if (ch === '/' && src[i + 1] === '*') {
+            const end = src.indexOf('*/', i + 2)
+            i = end === -1 ? src.length : end + 1
+            out += ' '
+            continue
+        }
+        // a regex literal starts where an expression may: its quotes open no
+        // string, and it is code, so it is blanked like a string
+        if (ch === '/' && /[(,=:[!&|?{};]$|^$/.test(out.trimEnd().slice(-1))) {
+            let j = i + 1
+            let cls = false
+            for (; j < src.length && src[j] !== '\n'; j++) {
+                if (src[j] === '\\') j++
+                else if (src[j] === '[') cls = true
+                else if (src[j] === ']') cls = false
+                else if (src[j] === '/' && !cls) break
+            }
+            if (src[j] === '/') {
+                out += o.strings ? src.slice(i, j + 1) : '//'
+                i = j
+                continue
+            }
+        }
+        if (ch === "'" || ch === '"' || ch === '`') quote = ch
+        out += ch
+    }
+    return out
+}
+
+/** the elements of every `cmd: [...]` array literal, split at the commas of
+ *  its own level */
+function cmdElements(code: string): string[][] {
+    const out: string[][] = []
+    for (const m of code.matchAll(/\bcmd\s*:\s*\[/g)) {
+        const items: string[] = []
+        let depth = 0
+        let quote: string | null = null
+        let cur = ''
+        for (let i = m.index! + m[0].length; i < code.length; i++) {
+            const ch = code[i]!
+            if (quote != null) {
+                cur += ch
+                if (ch === '\\') cur += code[++i] ?? ''
+                else if (ch === quote) quote = null
+                continue
+            }
+            if (ch === "'" || ch === '"' || ch === '`') quote = ch
+            else if (ch === '(' || ch === '[' || ch === '{') depth++
+            else if ((ch === ')' || ch === ']' || ch === '}') && depth > 0) depth--
+            else if (ch === ']') break
+            else if (ch === ',' && depth === 0) {
+                items.push(cur.trim())
+                cur = ''
+                continue
+            }
+            cur += ch
+        }
+        if (cur.trim() !== '') items.push(cur.trim())
+        out.push(items)
+    }
+    return out
+}
+
+/** an argv element that IS the module's own file */
+const SELF = [
+    /^import\.meta\.(path|filename)$/,
+    /^fileURLToPath\(\s*import\.meta\.url\s*\)$/,
+    /^new\s+URL\(\s*import\.meta\.url\s*\)\.pathname$/,
+    /^__filename$/,
+    /^Bun\.main$/,
+]
+
+/** why this check file runs a body of its own in a second process, null when
+ *  it does not: a `cmd` element that is the file itself, or the
+ *  `import.meta.main` guard such a body hides behind, which survives any
+ *  aliasing of the path */
+export function selfSpawn(rel: string, src: string): string | null {
+    const code = codeOf(src)
+    for (const argv of cmdElements(code))
+        for (const el of argv) {
+            if (SELF.some((re) => re.test(el))) return `its cmd runs the file itself (${el})`
+            const lit = /^(['"`])(.*)\1$/.exec(el)?.[2]
+            if (lit != null && (lit.replace(/^\.\//, '') === rel || lit.endsWith(`/${rel}`))) return `its cmd names its own path (${lit})`
+        }
+    if (/\bimport\.meta\.main\b/.test(codeOf(src, { strings: false }))) return 'it guards a body of its own behind import.meta.main'
+    return null
+}
+
+export const selfSpawningCheck = check({
+    id: 'SK020',
+    title: 'self spawning check',
+    description: 'no check file runs its own body by spawning itself',
+    owner: OWNER,
+    blocking: true,
+    run: (c) => {
+        const found = repoCheckSources(c).flatMap((f) => {
+            if (f.src == null || isLegacyCheckSource(f.src)) return []
+            const why = selfSpawn(f.rel, f.src)
+            return why == null ? [] : [`${f.rel}: ${why}`]
+        })
+        if (found.length === 0) return c.ok('no check file spawns itself: every body runs through `c`')
+        c.fail(`${found.length} check file(s) run a body of their own in a second process: ${found.join(', ')}`)
+        c.lines.push({ kind: 'fix-fail', text: `move each body into \`run: (c) => …\` and drop the \`cmd\` and the \`import.meta.main\` guard: a probe reaches the world through c.fetch, c.exec and c.tool (${OWNER})` })
+    },
+})
+
+export default selfSpawningCheck

package/src/checks/contracts.check.ts

@@ -0,0 +1,20 @@
+// the contracts check — `.shipkit/*` release-contract fulfillness. It shares ONE
+// evaluation with check SK002 (the `contractsResult` scan), and it tags with
+// that id, because the invariant has one owner and two surfaces report it. A
+// venue deploy step deps on it BY NAME, which needs nothing from this end.
+import { applyContractsResult, contractsResult } from '../contracts/apply-contracts.ts'
+import { check } from '../check.ts'
+import { contractsFulfillness } from './SK002-contracts-fulfillness.check.ts'
+
+export const contractsCheck = check({
+    id: 'contracts',
+    title: 'contracts',
+    description: 'every declared venue has the `.shipkit/*` release contract it demands',
+    owner: 'meta/contracts.md',
+    blocking: true,
+    run: async (c) => {
+        applyContractsResult(c, await c.use(contractsResult), contractsFulfillness)
+    },
+})
+
+export default contractsCheck

package/src/cli/cmd_Asks.ts

@@ -5,8 +5,9 @@ import { join } from 'path'
 import { Command, Option } from 'clipanion'
 import { checkAsks, createAsk, renderAsksTable } from '../asks/asks-queue.ts'
 import { loadRepoConfig } from '../repo-config.ts'
+import { LAYOUT } from '../core/layout.ts'
 
-const asksDir = async (root: string): Promise<string> => join(root, (await loadRepoConfig(root)).asks?.dir ?? 'asks')
+const asksDir = async (root: string): Promise<string> => join(root, (await loadRepoConfig(root)).asks?.dir ?? LAYOUT.asks)
 
 export class AsksCommand extends Command {
     static override paths = [['asks']]
@@ -21,7 +22,7 @@ export class AsksCommand extends Command {
         try {
             const root = process.cwd()
             const c = await loadRepoConfig(root)
-            renderAsksTable(join(root, c.asks?.dir ?? 'asks'), undefined, { emptyText: c.asks?.emptyText })
+            renderAsksTable(join(root, c.asks?.dir ?? LAYOUT.asks), undefined, { emptyText: c.asks?.emptyText })
             return 0
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)

package/src/cli/cmd_Assets.ts

@@ -1,4 +1,4 @@
-// shipkit assets — asset atelier: declare kinds in .rv-assets/kit.ts, roll
+// shipkit assets — asset atelier: declare kinds in .shipkit/assets/kit.ts, roll
 // (ComfyUI or procedural canvas), curate in the studio, ship with metadata
 // write-through. Thin clipanion surfaces; logic in assets/run-assets.ts.
 import { Command, Option } from 'clipanion'
@@ -85,7 +85,7 @@ export class AssetsIdentityCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Assets',
-        description: 'render favicon/logo/OG from .rv-identity/brand.ts into public/',
+        description: 'render favicon/logo/OG from .shipkit/identity/brand.ts into public/',
         examples: [['regenerate the identity outputs', 'shipkit assets identity']],
     })
 

package/src/cli/cmd_Bump.ts

@@ -9,7 +9,7 @@ export class BumpCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Gate',
-        description: 'ship a version in one word: bumps a release unit (default the repo root), run from a feature branch it merges into the release branch first, then promotes the CHANGELOG Unreleased section, bumps package.json, runs the gate and every prepublish script, commits, tags, pushes, and cuts the release. Any failure before the version commit rolls the merge back and returns you to your branch.',
+        description: 'ship a version in one word: bumps a unit (default the repo root), run from a feature branch it merges into the release branch first, then promotes the CHANGELOG Unreleased section, bumps package.json, runs the gate and every prepublish script, commits, tags, pushes, and cuts the release. Any failure before the version commit rolls the merge back and returns you to your branch.',
         examples: [
             ['a bugfix release of the repo itself', 'shipkit bump patch'],
             ['a feature release', 'shipkit bump minor'],

package/src/cli/cmd_Check.ts

@@ -1,17 +1,17 @@
 // shipkit check — periodic health, TTL-cached; `--fix` applies rule
 // autofixes then re-lints. Thin clipanion surface; logic in
-// core/run-check.ts and rules/run-fix.ts. ci NEVER fixes.
+// core/run-check.ts and core/run-fix.ts. ci NEVER fixes.
 import { Command, Option } from 'clipanion'
 import { runCheck } from '../core/run-check.ts'
 import { maybeSelfUpdateAndRestart } from '../core/self-update.ts'
-import { runFix } from '../rules/run-fix.ts'
+import { runFix } from '../core/run-fix.ts'
 
 export class CheckCommand extends Command {
     static override paths = [['check'], ['doctor']]
 
     static override usage = Command.Usage({
         category: 'Health',
-        description: 'the checks alone, without the build tasks. `shipkit ci` runs these too and is what you normally want. --fix applies rule autofixes',
+        description: 'every check except the build steps. `shipkit ci` runs these too and is what you normally want. --fix applies check autofixes',
         examples: [
             ['run (cached where valid)', 'shipkit check'],
             ['bust every cache layer', 'shipkit check --fresh'],
@@ -24,8 +24,8 @@ export class CheckCommand extends Command {
 
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
     fresh = Option.Boolean('--fresh', false, { description: 'bust every TTL cache layer (travels to child checks)' })
-    fix = Option.Boolean('--fix', false, { description: 'apply rule autofixes (all fixable rules, or only the listed SK ids), then re-lint' })
-    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining rules (SK005 never touches package.json)' })
+    fix = Option.Boolean('--fix', false, { description: 'apply check autofixes (every fixable check, or only the listed ids), then re-run them' })
+    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for the self-maintaining checks (SK005 never touches package.json)' })
     fixIds = Option.Rest()
 
     async execute(): Promise<number> {
@@ -34,7 +34,7 @@ export class CheckCommand extends Command {
         await maybeSelfUpdateAndRestart(process.cwd())
         try {
             if (this.fixIds.length > 0 && !this.fix) {
-                this.context.stderr.write(`FAIL: rule ids need --fix (shipkit check --fix ${this.fixIds.join(' ')})\n`)
+                this.context.stderr.write(`FAIL: check ids need --fix (shipkit check --fix ${this.fixIds.join(' ')})\n`)
                 return 2
             }
             if (this.fix && this.json) {

package/src/cli/cmd_Checks.ts

@@ -0,0 +1,95 @@
+// shipkit checks — THE inventory: every check this repo can run on one table,
+// with what it declared about itself. `shipkit keys` answers a different
+// question (what is a check keyed on, right now), and nothing else says
+// whether a check blocks you or only reports the world. That answer had no
+// surface, so it was reconstructed by reading source files, which is how a
+// repo ends up with checks nobody can account for.
+//
+// `--fixable` is the narrower catalog: what repairs itself, where the
+// invariant is owned, and how to apply one.
+import { writeFileSync } from 'fs'
+import { resolve } from 'path'
+import { Command, Option, type Usage } from 'clipanion'
+import { loadRepoConfig } from '../repo-config.ts'
+import { envTier, gateInventory } from '../ledger/gate-checks.ts'
+import { renderFixableLines, renderCheckLines, renderCheckTable } from '../ledger/check-table.ts'
+import { classify } from '../ledger/git-key.ts'
+
+export class ChecksCommand extends Command {
+    static override paths = [['checks']]
+
+    // widened so the hidden alias below can drop it: no usage, no help entry
+    static override usage: Usage | undefined = Command.Usage({
+        category: 'Health',
+        description: 'every gate check on one table: where it comes from, whether it blocks or only warns, whether the gate runs it or only `shipkit check`, and how it caches. Reports, never gates',
+        examples: [
+            ['the whole inventory', 'shipkit checks'],
+            ['the big markdown table, written to a file', 'shipkit checks --out STATUS.full.md'],
+            ['only the ones the gate never runs', 'shipkit checks --proactive'],
+            ['everything that repairs itself, with its owner', 'shipkit checks --fixable'],
+            ['machine-readable', 'shipkit checks --json'],
+        ],
+    })
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable CheckRow[] with the resolved cache population' })
+    md = Option.Boolean('--md', false, { description: 'the full markdown table on stdout, the same bytes --out writes' })
+    out = Option.String('--out', { required: false, description: 'write the markdown table to this file instead of stdout' })
+    blocking = Option.Boolean('--blocking', false, { description: 'only checks whose failure can stop you' })
+    proactive = Option.Boolean('--proactive', false, { description: 'only checks the gate never runs (`shipkit check` reports them)' })
+    fixable = Option.Boolean('--fixable', false, { description: 'only checks that carry an autofix, with the page that owns the invariant — `shipkit check --fix <id>` applies one' })
+    full = Option.Boolean('--full', false, { description: 'resolve every check the way a FULL-tier run resolves it' })
+
+    async execute(): Promise<number> {
+        const root = process.cwd()
+        const c = await loadRepoConfig(root)
+        const tier = this.full ? 'full' : envTier()
+        let rows = await gateInventory(root, c, { tier })
+        if (this.blocking) rows = rows.filter((r) => r.blocking !== false)
+        if (this.proactive) rows = rows.filter((r) => r.when.at !== 'always')
+        if (this.fixable) rows = rows.filter((r) => r.fixable)
+
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(rows.map((r) => ({ ...r, population: classify(r.decl).population })))}\n`)
+            return 0
+        }
+
+        if (this.md || this.out != null) {
+            const md = renderCheckTable({ name: c.name, rows })
+            if (this.out != null) {
+                const target = resolve(root, this.out)
+                writeFileSync(target, `${md.trimEnd()}\n`)
+                this.context.stdout.write(`ok: ${rows.length} check(s) written to ${this.out}\n`)
+                return 0
+            }
+            this.context.stdout.write(`${md}\n`)
+            return 0
+        }
+
+        if (this.fixable) {
+            for (const l of renderFixableLines(rows)) this.context.stdout.write(`${l}\n`)
+            return 0
+        }
+
+        // the SAME cells the markdown table is built from, so the terminal
+        // and the file can never disagree about a column
+        for (const l of renderCheckLines(rows)) this.context.stdout.write(`${l}\n`)
+        const undeclared = rows.filter((r) => { const cl = classify(r.decl); return cl.population === 'none' && cl.decided !== true }).length
+        if (undeclared > 0) this.context.stdout.write(`      why each one: shipkit keys --burn-down\n`)
+        this.context.stdout.write(`      the full table, refreshed by every gate run: STATUS.full.md\n`)
+        return 0
+    }
+}
+
+/** `shipkit units`, the name 0.38 shipped for this inventory. Hidden from the
+ *  help and the command index, it answers the same table with one WARN on
+ *  stderr, so a `--json` consumer still parses stdout. It dies with the rest
+ *  of the compatibility window at 0.40. */
+export class UnitsAliasCommand extends ChecksCommand {
+    static override paths = [['units']]
+    static override usage = undefined
+
+    override async execute(): Promise<number> {
+        this.context.stderr.write('WARN shipkit units is now shipkit checks, the old name goes at 0.40\n')
+        return await super.execute()
+    }
+}