rvlib-shipkit 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.1.0
+
+- **SK027 requires exhaustive agent/ indexes.** Every `agent/` page is listed by an index (a bullet, numbered item, table row, `→` pointer or `@` include names it or its folder), and every index is loaded from CLAUDE.md or listed by a loaded file. A page linked only from prose now fails, with the page that already names it as the fix. The template's house `[lint]` block makes `typescript/no-empty-object-type` an error.
+- **The store sweep clears what it measures.** A job past its 7 day keep window is swept even when its pid is alive, because a pid that old has been reused. The answers measure leaves out the forever answers the sweep keeps, so a decided fact never reads as over cap.
+- **SK031 states a task it cannot trace as one note.** A binary macOS will not trace is the platform, so it no longer prints one WARN per task.
+
+## 2.0.2
+
+- **SK001 clears its own lint shadow.** A `lint` or `fmt` script that routes through `shipkit ci` beside the bunfig section of the same name is deleted by the repair, with its `:raw` half, so `bun lint` runs the built-in. A script whose body is a tool stays named for a human.
+
 ## 2.0.1
 
 - **`sk fleet --update --major` crosses the major again.** Each repo's guarded run now stays in its own process (`SHIPKIT_NO_HOME`), because a check the home answered never saw `SHIPKIT_ALLOW_MAJOR` and refused the breaking jump, naming the very command that was running.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "2.0.1",
+    "version": "2.1.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/checks/SK001-package-json-shape.check.ts

@@ -282,6 +282,19 @@ export const packageJsonShape = check({
         // none, so scaffolding this into a repo without any turns the gate red
         // on work the fixer itself did. a fixer must never manufacture a failure.
         if (pkg.scripts['test'] == null && hasTestFiles(testFiles(c))) { pkg.scripts['test'] = 'bun test'; changes.push(`script 'test' added`) }
+        // a script beside its declared bunfig section only shadows the built-in.
+        // A routed body and its `<id>:raw` are house wiring, so they go. A tool
+        // body is a repo's own answer and stays named
+        const bunfig = c.read('bunfig.toml')
+        for (const n of ['lint', 'fmt'] as const) {
+            const body = pkg.scripts[n]
+            if (body == null || !bunfigDeclares(bunfig, n)) continue
+            if (!routesToShipkit(body)) { notes.push(`'${n}' shadows \`bun ${n}\` — its body is a tool, left for a human`); continue }
+            delete pkg.scripts[n]
+            const gone: string[] = [n]
+            if (pkg.scripts[rawName(n)] != null) { delete pkg.scripts[rawName(n)]; gone.push(rawName(n)) }
+            changes.push(`script ${gone.map((g) => `'${g}'`).join(' and ')} deleted (bunfig.toml [${n}] runs \`bun ${n}\`)`)
+        }
         // ONE WAY IN, last so it also routes whatever this pass just added:
         // the tool body slides to `<id>:raw` and `<id>` becomes the shipkit
         // call. Both keys keep their place in the file, so the diff a human

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -1,42 +1,50 @@
 // SK027 agent wiki links (build/shipkit/built-in-checks.md): a repo's agent/
-// IS an md wiki (entry index.md, the CLAUDE.md include), so an orphan page or
-// a dangling ref there fails. A link that leaves agent/ but stays in the repo
-// is checked on disk; a pointer out of the repo (a house wiki) is backticked,
+// IS an md wiki, entered by agent/index.md. Every page is LISTED by an index
+// (src/wiki/agent-index.ts: one bullet, numbered item, table row or @ include
+// names it or its folder), every index is in sight of what a session loads,
+// and a dangling ref fails. A link that leaves agent/ but stays in the repo is
+// checked on disk; a pointer out of the repo (a house wiki) is backticked,
 // never a bare → or @. A repo without agent/index.md skips.
-// agent/global-contribution.md is no orphan: the house index links it (SK033).
+// agent/global-contribution.md is listed by the house index (SK033), never agent/'s.
 import { existsSync, readFileSync } from 'fs'
-import { basename, join } from 'path'
+import { basename, dirname, join } from 'path'
 import { check } from '../check.ts'
 import { CONTRIBUTION_FILE } from '../core/global-contribution.ts'
+import { indexCovers, indexesOutOfSight, loadedFiles, unlisted } from '../wiki/agent-index.ts'
 import { lintMd } from '../wiki/lint-md.ts'
 
 export const agentWikiLinks = check({
     id: 'SK027',
     blocking: true,
     title: 'agent wiki links',
-    description: 'every agent/ page is linked from somewhere, and every agent/ link resolves',
+    description: 'every agent/ page is listed by an index a session sees, and every agent/ link resolves',
     owner: 'meta/agent-folder.md',
     runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
-    // the md lint walks agent/ on disk rather than through `c`: agent/ is all it reads
-    cache: { by: 'files', inputs: ['agent'], key: null },
+    // the md lint walks agent/ on disk rather than through `c`; the loaded context starts at CLAUDE.md
+    cache: { by: 'files', inputs: ['agent', 'CLAUDE.md', 'CLAUDE.local.md'], key: null },
     fix: 'none',
     applies: 'always',
     run: (c) => {
         if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
         const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })
-        // the global contribution is the house index's to link (SK033), never agent/'s
-        const orphans = lint.orphans.filter((f) => `agent/${f}` !== CONTRIBUTION_FILE)
-        const linked = lint.pages.filter((p) => !orphans.includes(p))
-        for (const f of orphans) {
-            const by = namingPage(c.root, f, linked)
-            const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
-            c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`, { at: { file: `agent/${f}` } })
+        const read = (p: string): string | null => {
+            try { return readFileSync(join(c.root, p), 'utf8') } catch { return null }
         }
+        const pages = new Map(lint.pages.map((p) => [`agent/${p}`, read(`agent/${p}`) ?? '']))
+        const folders = new Set([...pages.keys()].map((p) => dirname(p)))
+        for (const f of unlisted(pages, new Set([CONTRIBUTION_FILE]))) {
+            // only an index that can list the page is worth naming as the fix
+            const by = namingPage(c.root, f.slice('agent/'.length), lint.pages.filter((p) => indexCovers(`agent/${p}`, f, folders)))
+            const where = by != null ? `${by}, which already names it (make that mention a listing line)` : 'agent/index.md or the index of its folder'
+            c.fail(`${f}: no index lists it: add one bullet or table row naming it to ${where}; delete it only if the page is dead`, { at: { file: f } })
+        }
+        for (const f of indexesOutOfSight(pages, loadedFiles(read), read))
+            c.fail(`${f}: an index no session sees: list it on one line of agent/index.md (or another loaded index), or include it with @`, { at: { file: f } })
         for (const d of lint.dangling) {
             const file = `agent/${d.from}`
             c.fail(`${file}:${d.line}: dangling ref → ${d.token}, target not found on disk: fix the path or delete the pointer (a pointer out of this repo, into a house wiki or another repo, goes in backticks)`, { at: { file, line: d.line } })
         }
-        if (!c.failed) c.ok('agent/ has no orphans and no dangling refs')
+        if (!c.failed) c.ok(`agent/: ${pages.size} pages, each listed by an index in sight; no dangling refs`)
     },
 })
 

package/src/checks/SK031-trace-audit.check.ts

@@ -27,7 +27,9 @@ export const traceAuditCheck = check({
         let out: { skipped?: string; tasks: { id: string; status: string; why?: string; uncovered: string[]; propose: string[] }[] }
         try { out = JSON.parse(r.out.trim().split('\n').at(-1) ?? '') } catch { return c.fail(`sk trace-audit did not answer (exit ${r.code}: ${r.out.trim().slice(0, 160)})`) }
         if (out.skipped != null) return c.note(`nothing traced: ${out.skipped}`)
-        for (const t of out.tasks.filter((x) => x.status === 'unaudited')) c.warn(`${t.id} could not be audited: ${t.why}`)
+        // a binary macOS will not trace is the platform, never the repo: nobody can clear it, so it is a note
+        const unaudited = out.tasks.filter((x) => x.status === 'unaudited').map((x) => x.id)
+        if (unaudited.length > 0) c.note(`${unaudited.length} task(s) not auditable here, a binary ran untraced (macOS traces no system binary): ${unaudited.join(', ')}`)
         const missing = out.tasks.filter((x) => x.uncovered.length > 0)
         // a finding joins its task's key at once (core/audit-report.ts), so it
         // is news, never a failure: SK032 carries it into repo.config.ts

package/src/core/jobs.ts

@@ -177,9 +177,11 @@ export function sweepJobs(root: string, now = Date.now(), o: { keepMs?: number;
         })
     } catch { return /* no jobs yet: nothing to sweep */ }
     dirs.sort((a, b) => b.mtime - a.mtime).forEach((d, i) => {
-        if (d.mtime > now - (o.keepMs ?? JOBS_KEEP_MS) && i < (o.max ?? JOBS_MAX)) return
+        const fresh = d.mtime > now - (o.keepMs ?? JOBS_KEEP_MS)
+        if (fresh && i < (o.max ?? JOBS_MAX)) return
+        // past the keep window a live pid is a reused one: no gate runs for a week
         const j = readJson<Job>(join(d.dir, 'job.json'))
-        if (j != null && alive(j.pid)) return
+        if (fresh && j != null && alive(j.pid)) return
         try { rmSync(d.dir, { recursive: true, force: true }) } catch { /* raced: gone either way */ }
     })
 }

package/src/ledger/store.ts

@@ -193,8 +193,9 @@ export class Answers {
         return r == null ? 'none' : `${r.n}/${r.last ?? 0}`
     }
 
+    /** the rows the cap governs: a forever answer is kept by the sweep, so it is no use against the cap */
     use(): AnswersUse | null {
-        const r = this.with(READ_BUSY_MS, (h) => h.query('select count(*) as n, min(used) as oldest from answers').get() as { n: number; oldest: number | null } | null)
+        const r = this.with(READ_BUSY_MS, (h) => h.query('select count(*) as n, min(used) as oldest from answers where coalesce(keeps, 0) < ?').get(FOREVER_MS) as { n: number; oldest: number | null } | null)
         return r == null ? null : { count: Number(r.n), oldestUsed: r.oldest }
     }
 

package/src/scaffold/files/bunfig.toml

@@ -9,3 +9,7 @@ tabWidth = 4
 ignorePatterns = ["*.md", "*.json", "*.jsonc", "*.yaml", "*.yml", "*.toml"]
 
 [lint]
+
+[lint.rules]
+# `{}` as a type accepts any non nullish value: name the shape, or write Record<string, never>
+"typescript/no-empty-object-type" = "error"

package/src/wiki/agent-index.ts

@@ -0,0 +1,114 @@
+// every agent/ page is LISTED: a bullet, a numbered item, a table row or an `@`
+// include of an index page names it, or names a folder that holds it. A link in
+// prose does not count, so an agent finds every page by reading indexes, never
+// by luck. Index pages: agent/index.md and any `index.md` under agent/ (they
+// list any page), `agent/<dir>.md` (it lists the pages of `agent/<dir>/`). Every
+// index page is in sight of what a session loads: loaded, or named by a listing
+// line of a loaded file. Pure: callers pass the texts, so the rule tests in memory.
+import { dirname, join, normalize } from 'path'
+
+export const ROOT_INDEX = 'agent/index.md'
+
+/** the files a session loads first, before any include */
+export const ENTRIES = ['CLAUDE.md', 'CLAUDE.local.md'] as const
+
+const MAX_HOPS = 5
+
+/** a line that lists: a bullet, a numbered item, a table row (not its rule), an `@` include, a `→` pointer */
+const LISTING = /^\s*(?:[-*+]\s|\d+\.\s|\|(?!\s*:?-{3})|@\S|→\s)/
+
+/** the `@` paths of a page, code fences and code spans left out */
+export function includesOf(text: string): string[] {
+    const prose = text.replace(/^```[\s\S]*?^```/gm, '').replace(/`[^`\n]*`/g, '')
+    return [...prose.matchAll(/(?:^|\s)@([^\s]+)/g)].map((m) => m[1]!)
+}
+
+/** an include as a repo path, or null when it leaves the repo (`~/…`, absolute, `../` past the root) */
+function repoPath(from: string, include: string): string | null {
+    if (include.startsWith('~') || include.startsWith('/')) return null
+    const p = normalize(join(dirname(from), include))
+    return p.startsWith('..') ? null : p
+}
+
+/** every repo file a session loads: each entry, then its `@` includes inside the repo */
+export function loadedFiles(read: (path: string) => string | null): string[] {
+    const seen = new Set<string>()
+    const visit = (path: string, hops: number): void => {
+        if (seen.has(path)) return
+        const text = read(path)
+        if (text == null) return
+        seen.add(path)
+        if (hops >= MAX_HOPS) return
+        for (const include of includesOf(text)) {
+            const next = repoPath(path, include)
+            if (next != null) visit(next, hops + 1)
+        }
+    }
+    // agent/index.md is in sight by contract: its include in CLAUDE.md is another rule's
+    for (const e of [...ENTRIES, ROOT_INDEX]) visit(e, 0)
+    return [...seen]
+}
+
+/** the md pages and folders (ending in `/`) one listing line names, as repo paths */
+function named(line: string, from: string): string[] {
+    const dir = dirname(from)
+    const out: string[] = []
+    const add = (raw: string): void => {
+        const p = raw.split('#')[0]!.replace(/^@/, '')
+        if (/^[a-z]+:/.test(p) || !(p.endsWith('.md') || p.endsWith('/'))) return
+        const abs = p.startsWith('agent/') ? normalize(p) : normalize(join(dir, p))
+        out.push(p.endsWith('/') && !abs.endsWith('/') ? `${abs}/` : abs)
+    }
+    for (const m of line.matchAll(/\]\(([^)\s]+)\)/g)) add(m[1]!)
+    for (const m of line.matchAll(/(?:^|[\s`(@])((?:\.{0,2}\/)?(?:[\w.-]+\/)*[\w.-]+(?:\.md|\/))(?=[\s`),.;:|]|$)/g)) add(m[1]!)
+    return out
+}
+
+/** the folder an index page lists, '' for every page, null when the page is no index */
+function scopeOf(path: string, folders: ReadonlySet<string>): string | null {
+    if (path === ROOT_INDEX || path.endsWith('/index.md')) return ''
+    const sibling = path.slice(0, -'.md'.length)
+    return folders.has(sibling) ? `${sibling}/` : null
+}
+
+/** can `index` list `page`: it is an index page and its folder holds the page */
+export function indexCovers(index: string, page: string, folders: ReadonlySet<string>): boolean {
+    const scope = scopeOf(index, folders)
+    return scope != null && index !== page && page.startsWith(scope)
+}
+
+/** what the listing lines of `path` name, code fences and html comments left out */
+function listedBy(path: string, text: string): string[] {
+    const out: string[] = []
+    let fence = false
+    for (const line of text.replace(/<!--[\s\S]*?-->/g, '').split('\n')) {
+        if (/^\s*(?:```|~~~)/.test(line)) fence = !fence
+        if (!fence && LISTING.test(line)) out.push(...named(line, path))
+    }
+    return out
+}
+
+const covers = (names: ReadonlySet<string>, page: string): boolean =>
+    names.has(page) || [...names].some((n) => n.endsWith('/') && n !== 'agent/' && page.startsWith(n))
+
+/** every page of `pages` (repo path → text) that no index lists, sorted */
+export function unlisted(pages: ReadonlyMap<string, string>, exempt: ReadonlySet<string> = new Set()): string[] {
+    const folders = new Set([...pages.keys()].map((p) => dirname(p)))
+    const listed = new Set<string>([ROOT_INDEX])
+    for (const [path, text] of pages) {
+        const scope = scopeOf(path, folders)
+        if (scope == null) continue
+        // naming its own folder lists no page: each page gets its own line
+        const own = new Set([`${dirname(path)}/`, scope])
+        for (const p of listedBy(path, text)) if (p !== path && p.startsWith(scope) && !own.has(p)) listed.add(p)
+    }
+    return [...pages.keys()].filter((p) => !exempt.has(p) && !covers(listed, p)).sort()
+}
+
+/** every index page that no loaded file includes or names on a listing line, sorted */
+export function indexesOutOfSight(pages: ReadonlyMap<string, string>, loaded: readonly string[], read: (path: string) => string | null): string[] {
+    const folders = new Set([...pages.keys()].map((p) => dirname(p)))
+    const seen = new Set<string>(loaded)
+    for (const path of loaded) for (const p of listedBy(path, read(path) ?? '')) seen.add(p)
+    return [...pages.keys()].filter((p) => scopeOf(p, folders) != null && !covers(seen, p)).sort()
+}