rvlib-shipkit 0.38.1 → 1.0.0

package/src/core/config-keys.ts

@@ -0,0 +1,256 @@
+// the config surface describing itself: every `repo.config.ts` key, and every
+// key nested under one, rendered from the JSDoc that sits above the field.
+// The TYPE is the one source. A hand-written key list is a second one, and it
+// drifts the day a key lands, which is how eight keys came to exist in the
+// code and on no page.
+//
+// The reader is a tiny scanner rather than the TypeScript compiler: the shapes
+// it must read are plain `export type X = { ... }` object literals, the toolkit
+// already owns a module graph but not a type checker, and a config surface that
+// needs a compiler to document itself is a surface nobody documents.
+import { existsSync, readFileSync } from 'fs'
+import { dirname, resolve } from 'path'
+
+export type ConfigKey = {
+    /** dotted path from the root type, `serve.port` */
+    path: string
+    name: string
+    /** the type text as the source writes it */
+    type: string
+    /** false = the field carries no `?`, so a repo that declares the parent must declare this */
+    optional: boolean
+    /** the JSDoc above the field, collapsed to one line. Empty = undocumented */
+    doc: string
+    /** 1 for a top-level key */
+    depth: number
+}
+
+export type Member = {
+    name: string
+    optional: boolean
+    /** the type text, comments stripped and whitespace collapsed, for display */
+    type: string
+    /** the type text as the source wrote it, which is what the walk reads: an
+     *  inline object keeps its line breaks, and those are its separators */
+    raw: string
+    doc: string
+}
+
+/** the type text a page prints: no nested doc comments, one line. An inline
+ *  object separates its fields by NEWLINE in the source, so the newline
+ *  becomes the `;` a reader expects on one line. */
+export const displayType = (raw: string): string =>
+    raw
+        // one pass, whichever comment opens first owns the text
+        .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '\n')
+        .replace(/[^\S\n]+/g, ' ')
+        .replace(/\s*\n+\s*/g, '; ')
+        .replace(/([{([,;])\s*;\s*/g, '$1 ')
+        .replace(/;\s*([)\]}])/g, ' $1')
+        .replace(/\s+/g, ' ')
+        .replace(/^;\s*|\s*;$/g, '')
+        .trim()
+
+/** the `{ ... }` body of `type <name> = {`, braces balanced. null = no such type here */
+export function typeBody(src: string, name: string): string | null {
+    const decl = new RegExp(String.raw`(?:^|\n)\s*(?:export\s+)?type\s+${name}\s*=\s*\{`).exec(src)
+    if (decl == null) return null
+    const open = src.indexOf('{', decl.index + decl[0].length - 1)
+    const end = matchBrace(src, open)
+    return end === -1 ? null : src.slice(open + 1, end)
+}
+
+/** index of the `}` closing the `{` at `open`, strings and comments skipped */
+function matchBrace(src: string, open: number): number {
+    let depth = 0
+    for (let i = open; i < src.length; i++) {
+        const ch = src[i]!
+        if (ch === '/' && src[i + 1] === '*') { i = src.indexOf('*/', i); if (i === -1) return -1; i++; continue }
+        if (ch === '/' && src[i + 1] === '/') { const nl = src.indexOf('\n', i); if (nl === -1) return -1; i = nl; continue }
+        if (ch === "'" || ch === '"' || ch === '`') { i = skipString(src, i); continue }
+        if (ch === '{') depth++
+        else if (ch === '}' && --depth === 0) return i
+    }
+    return -1
+}
+
+function skipString(src: string, i: number): number {
+    const quote = src[i]!
+    for (let j = i + 1; j < src.length; j++) {
+        if (src[j] === '\\') { j++; continue }
+        if (src[j] === quote) return j
+    }
+    return src.length
+}
+
+const DOC_LINE = /^\s*\*\s?/
+
+/** a JSDoc block collapsed to ONE line: the page renders one bullet per key,
+ *  and a comment's line breaks are its own formatting, not sentences. */
+export function collapseDoc(raw: string): string {
+    return raw
+        .replace(/^\/\*\*/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map((l) => l.replace(DOC_LINE, '').trim())
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+}
+
+/** the members of one object-type body, in source order, each with the JSDoc
+ *  that precedes it. Anything the scanner cannot read is skipped rather than
+ *  guessed at: a wrong doc line is worse than a missing one. */
+export function parseMembers(body: string): Member[] {
+    const out: Member[] = []
+    let doc = ''
+    let i = 0
+    while (i < body.length) {
+        const ch = body[i]!
+        if (ch === '/' && body[i + 1] === '*') {
+            const end = body.indexOf('*/', i)
+            const raw = body.slice(i, end === -1 ? body.length : end + 2)
+            doc = body[i + 2] === '*' ? collapseDoc(raw) : doc
+            i = end === -1 ? body.length : end + 2
+            continue
+        }
+        if (ch === '/' && body[i + 1] === '/') { const nl = body.indexOf('\n', i); i = nl === -1 ? body.length : nl + 1; continue }
+        if (/\s|;|,/.test(ch)) { i++; continue }
+        const m = /^(?:readonly\s+)?([A-Za-z_$][\w$]*)(\?)?\s*:/.exec(body.slice(i))
+        if (m == null) { i = skipToSeparator(body, i); doc = ''; continue }
+        const start = i + m[0].length
+        const end = skipToSeparator(body, start)
+        const raw = body.slice(start, end).trim()
+        out.push({ name: m[1]!, optional: m[2] != null, type: displayType(raw), raw, doc })
+        doc = ''
+        i = end
+    }
+    return out
+}
+
+/** index of the `;`, `,`, trailing `//` or newline that ends a member, at
+ *  nesting depth 0. Generics count as nesting, or `Record<string, string>`
+ *  ends a key halfway through its own type. */
+function skipToSeparator(body: string, from: number): number {
+    let depth = 0
+    for (let i = from; i < body.length; i++) {
+        const ch = body[i]!
+        // a comment INSIDE an inline object is skipped whole: its backticks and
+        // apostrophes are prose, and reading them as string quotes walks the
+        // scanner past the member it is measuring
+        if (ch === '/' && body[i + 1] === '*') { const e = body.indexOf('*/', i); i = e === -1 ? body.length : e + 1; continue }
+        if (ch === '/' && body[i + 1] === '/') {
+            if (depth === 0) return i
+            const nl = body.indexOf('\n', i)
+            i = nl === -1 ? body.length : nl
+            continue
+        }
+        if (ch === "'" || ch === '"' || ch === '`') { i = skipString(body, i); continue }
+        if (ch === '{' || ch === '[' || ch === '(' || ch === '<') depth++
+        // `=>` is an arrow, never a closing generic
+        else if (ch === '}' || ch === ']' || ch === ')' || (ch === '>' && body[i - 1] !== '=')) depth--
+        else if (depth === 0 && (ch === ';' || ch === ',' || ch === '\n')) return i
+    }
+    return body.length
+}
+
+/** `import type { A, B } from './x.ts'` → name → absolute file. Where a type
+ *  LIVES is what lets the walk follow `serve?: ServeConfig` into another
+ *  module, which is where most of the nested keys are. */
+export function importMap(src: string, file: string): Map<string, string> {
+    const out = new Map<string, string>()
+    const dir = dirname(file)
+    for (const m of src.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
+        const spec = m[2]!
+        if (!spec.startsWith('.')) continue
+        for (const raw of m[1]!.split(',')) {
+            const name = raw.replace(/^\s*type\s+/, '').trim().split(/\s+as\s+/)[0]
+            if (name != null && name !== '') out.set(name, resolve(dir, spec))
+        }
+    }
+    return out
+}
+
+/** the named type a member's text points at, or null when nothing can be
+ *  followed: a function type, a union of literals, a `Record<>`, a primitive.
+ *  Only a bare identifier (with an optional `[]`) is followed, because a
+ *  scanner guessing its way INTO a type is how a page ends up documenting the
+ *  wrong shape. */
+export function namedTypeOf(type: string): string | null {
+    const t = type.replace(/\[\]$/, '').trim()
+    return /^[A-Z][\w$]*$/.test(t) ? t : null
+}
+
+/** the inline `{ ... }` body a member declares, or null */
+export function inlineBodyOf(type: string): string | null {
+    const open = type.indexOf('{')
+    if (open === -1) return null
+    const end = matchBrace(type, open)
+    return end === -1 ? null : type.slice(open + 1, end)
+}
+
+const MAX_DEPTH = 3
+
+/** every key of `root`, depth first, nested keys included. Each file is read
+ *  once, and a type already on the current branch is never re-entered. */
+export function configKeys(file: string, root: string, maxDepth: number = MAX_DEPTH): ConfigKey[] {
+    const cache = new Map<string, string>()
+    const read = (f: string): string => {
+        const hit = cache.get(f)
+        if (hit != null) return hit
+        const text = existsSync(f) ? readFileSync(f, 'utf8') : ''
+        cache.set(f, text)
+        return text
+    }
+    const out: ConfigKey[] = []
+    const walk = (body: string, ownerFile: string, prefix: string, depth: number, seen: string[]): void => {
+        for (const m of parseMembers(body)) {
+            const path = prefix === '' ? m.name : `${prefix}.${m.name}`
+            out.push({ path, name: m.name, type: m.type, optional: m.optional, doc: m.doc, depth })
+            if (depth >= maxDepth) continue
+            const inline = inlineBodyOf(m.raw)
+            if (inline != null) { walk(inline, ownerFile, path, depth + 1, seen); continue }
+            const named = namedTypeOf(m.raw)
+            if (named == null || seen.includes(named)) continue
+            const src = read(ownerFile)
+            const own = typeBody(src, named)
+            if (own != null) { walk(own, ownerFile, path, depth + 1, [...seen, named]); continue }
+            const from = importMap(src, ownerFile).get(named)
+            if (from == null) continue
+            const nested = typeBody(read(from), named)
+            if (nested != null) walk(nested, from, path, depth + 1, [...seen, named])
+        }
+    }
+    const rootBody = typeBody(read(file), root)
+    if (rootBody == null) throw new Error(`config-keys: no type ${root} in ${file}`)
+    walk(rootBody, file, '', 1, [root])
+    return out
+}
+
+/** one bullet per key, nested keys indented under their parent. The type text
+ *  rides in the bullet because half of these keys are objects, and a name and
+ *  a sentence do not say what to type. */
+export function renderKeys(keys: ConfigKey[]): string {
+    const lines = keys.map((k) => {
+        const indent = '  '.repeat(k.depth - 1)
+        const sig = `\`${k.name}${k.optional ? '?' : ''}: ${k.type}\``
+        const required = k.optional ? '' : ' REQUIRED.'
+        const doc = k.doc === '' ? 'undocumented in the source' : k.doc
+        return `${indent}- ${sig} —${required} ${doc}`
+    })
+    return lines.join('\n')
+}
+
+/** the keys a source file declares but never documents. The page is generated,
+ *  so a missing sentence is a defect in the TYPE, and this is what names it. */
+export const undocumented = (keys: ConfigKey[]): string[] => keys.filter((k) => k.doc === '').map((k) => k.path)
+
+export const BEGIN = '<!-- shipkit:config-keys -->'
+export const END = '<!-- /shipkit:config-keys -->'
+
+/** the second generated block on the same page: the CHECK shape. A check is not
+ *  config, it is a file, but its fields are the other half of what a repo
+ *  declares, and a field that lands with no doc line is a surface nobody can
+ *  find. Generated from the type for the same reason the first block is. */
+export const CHECK_BEGIN = '<!-- shipkit:check-keys -->'
+export const CHECK_END = '<!-- /shipkit:check-keys -->'

package/src/core/config-rewrite.ts

@@ -0,0 +1,77 @@
+// THE CONFIG HALF of the SK016 migration, in its own process. Writing the
+// managed block and reading the result back both LOAD repo.config.ts as a
+// module, which no check context read can stand for, so the fixer reaches it
+// through `c.exec` and the check file itself never imports the loader.
+//
+//   bun config-rewrite.ts <root> '<plan json>'   → one json line on stdout
+//
+// The order is the migration's: the `when` entries first, then each key is
+// dropped only once what leaned on it has a home, then the result is read
+// back through the loader and the previous bytes go back when it does not
+// survive.
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { atomicWrite } from './locked-write.ts'
+import { dropConfigKey } from './legacy-shapes.ts'
+import { writeGateBlock } from './when-block.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+export type ConfigPlan = {
+    /** check id → `when` value, written into the managed block */
+    when: Record<string, string>
+    /** keys to drop, in order. `afterWhen` drops only once the block took the entries */
+    drop: { key: string; why: string; afterWhen?: boolean }[]
+    /** the config's `name` before the rewrite: what the read back must still say */
+    name: string
+}
+
+export type ConfigRewrite = {
+    did: string[]
+    hand: string[]
+    /** set when the rewrite did not load back and the previous bytes went back */
+    restored?: string
+}
+
+export async function rewriteConfig(root: string, plan: ConfigPlan): Promise<ConfigRewrite> {
+    const did: string[] = []
+    const hand: string[] = []
+    let whenWritten = false
+    if (Object.keys(plan.when).length > 0) {
+        try {
+            await writeGateBlock(root, { when: plan.when })
+            whenWritten = true
+            did.push(`${Object.keys(plan.when).length} when entr(ies) written into the managed block`)
+        } catch (e) {
+            hand.push(`the \`when\` block refused the rewrite (${String(e).slice(0, 160)}) — write ${JSON.stringify(plan.when)} into it by hand`)
+        }
+    }
+    const path = join(root, 'repo.config.ts')
+    const before = readFileSync(path, 'utf8')
+    let text = before
+    for (const d of plan.drop) {
+        if (d.afterWhen === true && !whenWritten) continue
+        const next = dropConfigKey(text, d.key)
+        if (next == null) hand.push(`repo.config.ts \`${d.key}\`: ${d.why}, and the key could not be read mechanically — delete it by hand`)
+        else { text = next; did.push(`repo.config.ts drops \`${d.key}\``) }
+    }
+    if (text !== before) {
+        atomicWrite(path, text)
+        try {
+            const after = await loadRepoConfig(root, { fresh: true })
+            if (after.name !== plan.name) throw new Error(`the config reads as '${String(after.name)}'`)
+        } catch (e) {
+            atomicWrite(path, before)
+            return { did, hand, restored: String(e).slice(0, 160) }
+        }
+    }
+    return { did, hand }
+}
+
+if (import.meta.main) {
+    const [root, plan] = process.argv.slice(2)
+    if (root == null || plan == null) {
+        console.error('usage: bun config-rewrite.ts <root> <plan json>')
+        process.exit(2)
+    }
+    console.log(JSON.stringify(await rewriteConfig(root, JSON.parse(plan) as ConfigPlan)))
+}

package/src/core/discover-checks.ts

@@ -1,102 +1,178 @@
-// *.check.ts auto-discovery — THE way a repo registers its OWN checks
-// (built-in SK rules come from rules/rule-registry.ts): drop a
-// `<name>.check.ts` anywhere in the repo and `shipkit check` runs it as a
-// subprocess — wire
-// output parsed back, exit code is truth. Skipped dirs: node_modules, dist,
-// tmp, references (templates for other repos), and every dot-dir (.git,
-// caches, .rv-* contract folders).
-
-import { readdirSync, readFileSync } from 'fs'
+// `*.check.ts` discovery — THE way anything gets into a gate. Drop a file
+// anywhere in the repo, default-export `check({...})`, and every surface sees
+// it with no config edit. The toolkit's own built-ins are the same files
+// under `src/checks/`, walked by this same code, so a built-in and a repo
+// check differ by `from` and by nothing else.
+//
+// Discovery IMPORTS each check file. That is what buys the shape a function
+// body, a fixer and a typed declaration instead of four regexes, and it is why
+// a check file keeps its metadata imports at the top level and its BODY's
+// imports inside `run` or behind `import.meta.main`. The budget is 300ms for a
+// real repo, pinned by tests/check-shape.test.ts.
+//
+// The suffix is shared with the legacy check SCRIPT (named `export const`
+// declarations, a body that runs on import), read through 0.40 by
+// core/discover-legacy-checks.ts. A script must never be imported, so the two
+// are told apart by reading the source first (`isLegacyCheckSource`).
+//
+// Skipped dirs: node_modules, dist, tmp, references (templates for other
+// repos), and every dot-dir.
+import { readdirSync, readFileSync, realpathSync, statSync } from 'fs'
 import { basename, join, relative } from 'path'
+import { check, type CheckDef, type CheckFrom } from '../check.ts'
+
+import { CHECK_SUFFIX as SUFFIX, fallbackNames, isLegacyCheckSource, SKIPPED_DIRS as IGNORED_DIRS } from './check-file-names.ts'
+
+export { fallbackNames, isLegacyCheckSource } from './check-file-names.ts'
 
-const IGNORED_DIRS = new Set(['node_modules', 'dist', 'tmp', 'references'])
-const SUFFIX = '.check.ts'
+/** where the toolkit keeps its own checks. A second discovery root, never a
+ *  registry: adding a built-in is adding a file here. */
+export const BUILTIN_CHECK_DIR = join(import.meta.dir, '../checks')
+
+/** an SK id lives in the FILE NAME, so the built-in id namespace is readable
+ *  without importing one body. `defineRepo` needs it at config load, which
+ *  is synchronous, and a second hand written list would drift. */
+const BUILTIN_ID_RE = /^([A-Z]{2,4}\d{3})-/
 
 export type DiscoveredCheck = {
-    /** absolute path to the check file */
+    /** what the file declared */
+    def: CheckDef
+    /** absolute path to the file */
     path: string
-    /** display + cache name — file base, disambiguated by relative path on collision */
-    name: string
-    /** `export const blocking = true | false`, read statically. null = the file
-     *  never said, which is an error: a check that silently does not block is
-     *  the failure nobody sees. */
-    blocking: boolean | null
-    /** `export const inputs = ['a', 'b']`, read statically — the repo-relative
-     *  paths this check reads. Declares the CONTENT population for the ledger
-     *  key layer (ledger/git-key.ts). null = never cached, which is the safe
-     *  default and the whole point of default deny. */
-    inputs: string[] | null
-    /** `export const ttl = '24h'`, read statically — declares the WORLD
-     *  population: this check probes something no file on disk describes. */
-    ttl: string | null
-    /** `export const never = 'why'`, read statically — a DECIDED never
-     *  cacheable, which takes the check off the burn-down list. */
-    never: string | null
-    /** `export const gate = false`, read statically — this check is NOT part of
-     *  `shipkit ci`. `ci` answers "is my change good"; a check that answers
-     *  something else, and that can sit red for months without anything being
-     *  wrong, does not belong in the answer. `shipkit check` still runs it.
-     *  Default true: a check is in the gate unless it opts out by name. */
-    gate: boolean
+    /** repo-relative path, null for a built-in: it lives outside the repo,
+     *  and the toolchain identity already covers the toolkit's own source */
+    rel: string | null
+    /** the name every surface uses: the declared id, else the file basename,
+     *  else the repo-relative path when two files share a basename */
+    id: string
+    title: string
+    /** the one sentence the file wrote about itself, always present: the
+     *  shape refuses a check file without one */
+    description: string
+    /** where the answer is owned: a wiki page, else the file itself */
+    owner: string
+    from: CheckFrom
+}
+
+function walk(dir: string, out: string[]): void {
+    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)
+        } else if (e.name.endsWith(SUFFIX)) out.push(join(dir, e.name))
+    }
+}
+
+/** every `*.check.ts` file under a repo root, check files and legacy
+ *  scripts alike, by the same walk discovery takes, without importing one.
+ *  Sorted. */
+export function repoCheckFiles(root: string): string[] {
+    const out: string[] = []
+    walk(root, out)
+    return out.sort()
 }
 
-// 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.
-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
-// (a computed list, a spread) is deliberately unreadable here and lands as no
-// declaration, which means never cached: a scanner guessing at a program is
-// how a key comes to describe files the unit does not read.
-const INPUTS_RE = /^\s*export\s+const\s+inputs\s*(?::[^=]*)?=\s*\[([^\]]*)\]/m
-const TTL_RE = /^\s*export\s+const\s+ttl\s*(?::\s*string\s*)?=\s*['"]([^'"]+)['"]/m
-const NEVER_RE = /^\s*export\s+const\s+never\s*(?::\s*string\s*)?=\s*['"]([^'"]+)['"]/m
-// `export const gate = false` takes a check out of `shipkit ci`. Only the
-// literal false opts out: anything unreadable stays in the gate, because a
-// scanner that guesses its way to SKIPPING a check is how coverage disappears
-const GATE_RE = new RegExp(String.raw`^\s*export\s+const\s+gate\s*(?::\s*boolean\s*)?=\s*false` + TAIL, 'm')
-const STRING_ITEM_RE = /['"]([^'"]+)['"]/g
+/** the same question about a file on disk. An unreadable file is a check
+ *  file, so the import names what is wrong with it */
+export function isLegacyCheckFile(path: string): boolean {
+    try { return isLegacyCheckSource(readFileSync(path, 'utf8')) } catch { return false }
+}
 
-export function discoverChecks(root: string): DiscoveredCheck[] {
+/** every built-in id, from the file names alone. Sync and import free, so
+ *  `defineRepo` can read the namespace at config load. Read once per
+ *  process: the toolkit's own files cannot appear mid run, and `defineRepo`
+ *  asks for the list once per `when` entry. */
+let builtinIds: string[] | null = null
+export function builtinCheckIds(): string[] {
+    if (builtinIds != null) return builtinIds
     const files: string[] = []
-    const walk = (dir: string): void => {
-        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))
-            } else if (e.name.endsWith(SUFFIX)) files.push(join(dir, e.name))
+    walk(BUILTIN_CHECK_DIR, files)
+    builtinIds = files.map((f) => {
+        const base = basename(f).slice(0, -SUFFIX.length)
+        return BUILTIN_ID_RE.exec(base)?.[1] ?? base
+    })
+    return builtinIds
+}
+
+/** the module, re-imported whenever the file on disk moves. An ES module is
+ *  cached by path for the life of the process, so a repo that rewrites a
+ *  check file mid process would keep running the old body without this. */
+async function load(path: string): Promise<CheckDef> {
+    let stamp = ''
+    // no dot in the stamp: a query ending `.1234` reads as the module's
+    // extension, and a load plugin then never sees the file
+    try { stamp = String(statSync(path).mtimeMs).replace('.', '_') } catch {}
+    // the path rides on every message from here down, because `check()` knows
+    // the object and not where it was written, and an agent reading a refused
+    // declaration needs the file before it needs the rule
+    try {
+        // the REAL path: through a linked one, the resolver misses a file
+        // created after it first listed the directory, which is exactly the
+        // file a fix pass just wrote
+        let real = path
+        try { real = realpathSync(path) } catch {}
+        const mod = (await import(`${real}?v=${stamp}`)) as { default?: unknown }
+        const d = mod.default
+        if (d == null || typeof d !== 'object' || (!('run' in d) && !('cmd' in d)))
+            throw new Error(`a check file must \`export default check({...})\` with a \`run\` or a \`cmd\``)
+        // re-validated here rather than trusted: a file can build the object
+        // any way it likes, and only what `check()` accepts may reach a gate
+        return check(d as CheckDef)
+    } catch (e) {
+        throw new Error(`${path}: ${(e as Error).message.replace(/^check( \S+)?: /, '')}`)
+    }
+}
+
+/** every check this repo can run: its own files, plus the toolkit's. Throws
+ *  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. */
+export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
+    const builtins: string[] = []
+    walk(BUILTIN_CHECK_DIR, builtins)
+    const found: string[] = []
+    walk(root, found)
+    // 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,
+    // because a consumer reaches the same files through a linked node_modules
+    const real = (f: string): string => { try { return realpathSync(f) } catch { return f } }
+    const shipped = new Set(builtins.map(real))
+    const all = found.filter((f) => !shipped.has(real(f))).sort()
+    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 base = (f: string): string => basename(f).slice(0, -SUFFIX.length)
+
+    const out: DiscoveredCheck[] = []
+    const ids = new Set<string>()
+    for (const f of [...builtins, ...own]) {
+        const isBuiltin = builtins.includes(f)
+        const def = await load(f)
+        const rel = isBuiltin ? null : relative(root, f).replace(/\\/g, '/')
+        const fallback = isBuiltin
+            ? (BUILTIN_ID_RE.exec(base(f))?.[1] ?? base(f))
+            : names.get(f)!
+        const id = def.id ?? fallback
+        if (isBuiltin) {
+            if (id !== fallback) throw new Error(`${f}: declares id '${id}' but its file name says '${fallback}' — a built-in id is its file name`)
+            if ((def.owner ?? '') === '') throw new Error(`${f}: a built-in check names the page that OWNS the invariant`)
+        } else if (id.startsWith('SK')) {
+            throw new Error(`${rel}: id '${id}' uses the reserved SK prefix — a repo check picks its own (e.g. RV${id.slice(-3)}) or plain words`)
         }
+        if (ids.has(id)) throw new Error(`${isBuiltin ? f : rel}: duplicate check id '${id}'`)
+        ids.add(id)
+        out.push({
+            def,
+            path: f,
+            rel,
+            id,
+            title: def.title ?? id,
+            description: def.description,
+            owner: def.owner ?? rel ?? f,
+            from: isBuiltin ? 'shipkit' : 'repo',
+        })
     }
-    walk(root)
-    files.sort()
-    const baseOf = (f: string): string => basename(f).slice(0, -SUFFIX.length)
-    const seen = new Map<string, number>()
-    for (const f of files) seen.set(baseOf(f), (seen.get(baseOf(f)) ?? 0) + 1)
-    return files.map((f) => {
-        const base = baseOf(f)
-        const name = (seen.get(base) ?? 0) > 1 ? relative(root, f).slice(0, -SUFFIX.length) : base
-        let blocking: boolean | null = null
-        let inputs: string[] | null = null
-        let ttl: string | null = null
-        let never: string | null = null
-        let gate = true
-        try {
-            const src = readFileSync(f, 'utf8')
-            const m = src.match(BLOCKING_RE)
-            blocking = m == null ? null : m[1] === 'true'
-            const im = src.match(INPUTS_RE)
-            if (im != null) {
-                const items = [...im[1]!.matchAll(STRING_ITEM_RE)].map((x) => x[1]!)
-                if (items.length > 0) inputs = items
-            }
-            ttl = src.match(TTL_RE)?.[1] ?? null
-            never = src.match(NEVER_RE)?.[1] ?? null
-            gate = src.match(GATE_RE) == null
-        } catch {}
-        return { path: f, name, blocking, inputs, ttl, never, gate }
-    })
+    return out
 }

package/src/core/discover-legacy-checks.ts

@@ -0,0 +1,26 @@
+// the legacy check SCRIPT reader, for the compatibility window: a
+// `*.check.ts` with named `export const` declarations and a body that runs
+// top to bottom, spawned as a subprocess, wire output parsed back, exit code
+// is truth. It shares the suffix with the check file, and the source decides
+// which one a file is (core/check-file-names.ts `isLegacyCheckSource`). It is
+// read through the window, and SK016 names each one with the check object
+// it becomes: a port by hand. Skipped dirs: the same walk as the check file's.
+
+import { readFileSync } from 'fs'
+import { fallbackNames, readLegacyCheck, type LegacyCheck } from './check-file-names.ts'
+import { repoCheckFiles } from './discover-checks.ts'
+
+export type { LegacyCheck } from './check-file-names.ts'
+
+export function discoverLegacyChecks(root: string): LegacyCheck[] {
+    const all = repoCheckFiles(root)
+    const names = fallbackNames(root, all)
+    const out: LegacyCheck[] = []
+    for (const f of all) {
+        let src: string
+        try { src = readFileSync(f, 'utf8') } catch { continue }
+        const read = readLegacyCheck(f, names.get(f)!, src)
+        if (read != null) out.push(read)
+    }
+    return out
+}

package/src/core/doc-block.ts

@@ -0,0 +1,13 @@
+// a generated block inside a hand-written markdown page, between two html
+// comment markers. Two docs pages are built this way (the command index and
+// the config-key reference), and one splice keeps them honest: a renamed or
+// hand-mangled host returns null, so a generator can fail loud instead of
+// writing nothing.
+
+/** replace the marked block in a host file. null = the markers are gone. */
+export function spliceMarkedBlock(host: string, block: string, begin: string, end: string): string | null {
+    const a = host.indexOf(begin)
+    const b = host.indexOf(end)
+    if (a === -1 || b === -1 || b < a) return null
+    return `${host.slice(0, a + begin.length)}\n\n${block}\n\n${host.slice(b)}`
+}