rvlib-shipkit 0.38.1 → 1.0.0

package/src/checks/SK004-gitignore-policy.check.ts

@@ -0,0 +1,309 @@
+// SK004 — the .gitignore policy block (meta/contracts.md git policy;
+// .shipkit/tmp/ spelled out because shipkit writes its per-run logs there in
+// every repo). A marker-keyed managed block so the always-gitignored contract
+// surfaces can never silently rot per repo. Ecosystem-specific names the
+// published lib may not carry ride as repo-contributed lines:
+// `defineRepo({ gitignore: [...] })` renders them INSIDE the block, so the
+// whole policy is machine-enforced. A well-formed block is rewritten IN
+// PLACE — lines below it (e.g. a live venue's `!.shipkit/itch/` override, where
+// last-match-wins) keep their position; everything outside the block is
+// never touched. `shipkit init` writes the same block through this fixer.
+//
+// It reads and writes `.gitignore` through `c`, and asks git through `c.exec`.
+// It still declares the WHOLE TREE as its input: what git ignores and tracks
+// depends on the index, `.git/info/exclude` and the user's global excludes
+// file, which no read set records exactly, and a body that asked git through
+// `c.exec` is never stored on its reads.
+import { readdirSync } from 'fs'
+import type { RepoConfig } from '../repo-config.ts'
+import { GENERATED_IGNORE_LINES, GENERATED_TRACKED_PATHS, untrackGenerated } from '../rules/untrack-generated.ts'
+import { check, type CheckCtx, type FixResult } from '../check.ts'
+import { gitBin } from '../core/git-bin.ts'
+import { LAYOUT, SHIPKIT_DIR, TRACKED_DIRS } from '../core/layout.ts'
+import { LEGACY_CONTRACT_PREFIX, LEGACY_IGNORED, LEGACY_TMP, LEGACY_VENUES, legacyLayoutLeft, migrateLayout } from '../core/migrate-layout.ts'
+
+/** what this check reads, writes and asks git through */
+type Disk = Pick<CheckCtx, 'root' | 'read' | 'write' | 'exists' | 'exec'>
+
+const BEGIN = '# >>> shipkit gitignore policy (SK004) — managed block, edit outside only'
+const END = '# <<< shipkit gitignore policy'
+const CONTRIB = '# repo-contributed lines (repo.config.ts gitignore:)'
+
+export const POLICY_LINES = [
+    // everything shipkit keeps lives under .shipkit/ (core/layout.ts). Local
+    // by default: the private notes, drafts, venue listings and caches, and the
+    // leak guard's keyword list, which cannot itself be committable. Only the
+    // authored folders come back in. A live venue re-includes its own folder
+    // below the block, `!.shipkit/itch/`, where the last match wins
+    `${SHIPKIT_DIR}/*`,
+    ...TRACKED_DIRS.map((d) => `!${d}/`),
+    `${LAYOUT.assets}/out/`,
+    // already covered by the line above, and spelled out anyway so this check
+    // asks git about it: a negation below the block that exposed the keyword
+    // list would otherwise pass as a venue override
+    `${LAYOUT.private}/`,
+    // the scratch and the review files, spelled out for the same reason: a
+    // review narrates agent process, and a plan names what nobody published
+    `${LAYOUT.tmp}/`,
+    `${LAYOUT.reviews}/`,
+    // a root scratch stays out of git too: the fix pass moves it under
+    // .shipkit/, and until it runs, a plan there is still private
+    `${LEGACY_TMP}/`,
+    'CLAUDE.local.md',
+    // atomicWrite lands every file via `.<name>.tmp-<pid>` next to its target,
+    // so a run killed mid write leaves one behind ANYWHERE in the tree, and an
+    // agent finds untracked debris it did not create. The ignore row ships in
+    // the same policy that started writing them.
+    '.*.tmp-*',
+    // comfy-ts state and per-workflow lora tags name a private model collection;
+    // shipkit itself writes .comfy-ts/ at hub boot, so every consumer repo needs
+    // these ignored before its first commit. The DRAFTS are re-included on
+    // purpose: a draft is the tuning behind a whole KIND of asset, its loras,
+    // steps and cfg, so it is authored state and belongs in the repo, unlike the
+    // schema dump, the lora previews and the raw run outputs beside it
+    '.comfy-ts/*',
+    '!.comfy-ts/drafts/',
+    '*.loras.local.txt',
+    // shipkit's own per-run output. Ignoring is only half of it: the fixer
+    // also removes these from the index, because .gitignore does nothing to a
+    // file already tracked (untrack-generated.ts owns the pair)
+    ...GENERATED_IGNORE_LINES,
+]
+
+const LEGACY = '# the old root layout, ignored until the fix pass moves it under .shipkit/'
+
+/** `legacy`: the repo still carries contract folders at its root from before `.shipkit/`. Their names
+ *  stay ignored until they move, so no private file is ever exposed by a block
+ *  that is newer than the tree it guards */
+export function expectedBlock(config: RepoConfig, legacy = false): string {
+    const extra = config.gitignore ?? []
+    return [BEGIN, ...POLICY_LINES, ...(legacy ? [LEGACY, ...LEGACY_IGNORED] : []), ...(extra.length > 0 ? [CONTRIB, ...extra] : []), END].join('\n')
+}
+
+export function policyPatterns(config: RepoConfig, legacy = false): string[] {
+    return [...POLICY_LINES.filter((l) => !l.startsWith('#')), ...(legacy ? LEGACY_IGNORED : []), ...(config.gitignore ?? [])]
+}
+
+/** does the root still hold a contract folder from before `.shipkit/` */
+function hasLegacy(root: string): boolean {
+    try { return readdirSync(root).some((e) => e.startsWith(LEGACY_CONTRACT_PREFIX)) } catch { return false }
+}
+
+/** the .gitignore text with its policy block rendered, every repo line kept
+ *  where it was. The layout migration writes it before it moves a single
+ *  folder, with `legacy` on while an old folder is still on disk */
+export const renderPolicy = (text: string, config: RepoConfig, legacy = false): string => withBlock(text, config, legacy)
+
+function endsWithNewline(d: Disk): boolean {
+    const text = d.read('.gitignore')
+    return text == null || text === '' || text.endsWith('\n')
+}
+
+// a venue folder is DESIGNED to be unignored below the block once a listing
+// is live (last-match-wins), so an override on one of them is the mechanism
+// working. Every other policy path is a claim the block makes, and a claim git
+// contradicts is a bug.
+const OVERRIDABLE = new Set(LEGACY_VENUES)
+
+/** a path git can be asked about, for a pattern that may be a glob or a dir */
+function probePath(pattern: string): string {
+    if (pattern.endsWith('/')) return `${pattern}probe`
+    // `.*.tmp-*` and `*.loras.local.txt`: a literal standing in for the glob
+    return pattern.includes('*') ? pattern.replace(/\*/g, 'probe') : pattern
+}
+
+/** which of `paths` git does NOT ignore. null when this is not a git repo, so
+ *  a rule can say it did not measure rather than report a green it invented */
+export async function notIgnored(d: Disk, paths: string[]): Promise<string[] | null> {
+    if (paths.length === 0) return []
+    // -n -v: one call, every path, and `-n` makes git print a row for the
+    // MISSES too, which is the answer we want. `-z` needs `--stdin`, and the
+    // probes are plain ascii paths of our own, so the text rows parse exactly
+    const r = await d.exec([gitBin(), 'check-ignore', '-n', '-v', '--', ...paths], { cwd: d.root })
+    // exit 1 means "none of them are ignored", which is an ANSWER, and git
+    // still wrote the rows we parse. Anything else (no repo, no git) is not
+    if (r.code !== 0 && r.code !== 1) return null
+    // a row is `source:line:pattern<TAB>path`, and an unignored path has all
+    // three empty: `::<TAB>path`
+    const miss: string[] = []
+    for (const row of r.out.split('\n')) {
+        const tab = row.indexOf('\t')
+        if (tab > 0 && row.slice(0, tab) === '::') miss.push(row.slice(tab + 1))
+    }
+    return miss
+}
+
+/** every declared generated path this repo still carries in its index, in
+ *  ONE git spawn (rules/untrack-generated.ts owns the list) */
+async function trackedGenerated(d: Disk): Promise<string[]> {
+    if (!d.exists('.git')) return []
+    const r = await d.exec([gitBin(), 'ls-files', '-z', '--', ...GENERATED_TRACKED_PATHS], { cwd: d.root })
+    if (r.code !== 0) return []
+    const listed = new Set(r.out.split('\0').filter((l) => l !== ''))
+    return GENERATED_TRACKED_PATHS.filter((p) => listed.has(p))
+}
+
+type Parsed = { text: string; crlf: boolean; lines: string[]; b: number; e: number }
+
+function parse(d: Disk): Parsed | null {
+    return parseText(d.read('.gitignore'))
+}
+
+function parseText(text: string | null): Parsed | null {
+    if (text == null) return null
+    const crlf = text.includes('\r\n')
+    const lines = text.split('\n').map((l) => l.replace(/\r$/, ''))
+    return { text, crlf, lines, b: lines.indexOf(BEGIN), e: lines.indexOf(END) }
+}
+
+type BlockState = 'missing-file' | 'missing-block' | 'corrupted' | 'stale' | 'current'
+
+function blockState(d: Disk, config: RepoConfig, legacy: boolean): BlockState {
+    const f = parse(d)
+    if (f == null) return 'missing-file'
+    if (f.b === -1 && f.e === -1) return 'missing-block'
+    if (f.b === -1 || f.e === -1 || f.e < f.b) return 'corrupted'
+    return f.lines.slice(f.b, f.e + 1).join('\n') === expectedBlock(config, legacy) ? 'current' : 'stale'
+}
+
+function writeBlock(d: Disk, config: RepoConfig, legacy: boolean): void {
+    d.write('.gitignore', withBlock(d.read('.gitignore'), config, legacy))
+}
+
+/** PURE: the .gitignore text with the current block in it */
+function withBlock(text: string | null, config: RepoConfig, legacy: boolean): string {
+    const f = parseText(text)
+    const block = expectedBlock(config, legacy).split('\n')
+    let out: string[]
+    if (f == null) out = block
+    else if (f.b !== -1 && f.e !== -1 && f.e >= f.b)
+        // well-formed block: rewrite IN PLACE so below-block overrides
+        // (last-match-wins) keep working
+        out = [...f.lines.slice(0, f.b), ...block, ...f.lines.slice(f.e + 1)]
+    else {
+        // absent or corrupted: drop stray markers, keep every repo line
+        // visible, append the canonical block
+        const kept = (f.b === -1 && f.e === -1 ? f.lines : f.lines.filter((l) => l !== BEGIN && l !== END))
+        while (kept.length > 0 && kept.at(-1)!.trim() === '') kept.pop()
+        out = kept.length > 0 ? [...kept, '', ...block] : block
+    }
+    const eol = f?.crlf === true ? '\r\n' : '\n'
+    return `${out.join(eol)}${out.at(-1) === '' ? '' : eol}`
+}
+
+export const gitignorePolicy = check({
+    id: 'SK004',
+    blocking: true,
+    title: '.gitignore',
+    description: 'the managed .gitignore block keeps private contract folders out of git',
+    owner: 'meta/contracts.md',
+    // .gitignore plus what git currently TRACKS and IGNORES, which the tree
+    // carries and no read set records (the header says why)
+    inputs: ['.'],
+    // it untracks generated files (a commit) unless the run is frozen
+    writes: true,
+    run: async (c) => {
+        // a generated path still in the index is the half-applied state the
+        // managed block cannot fix on its own
+        const tracked = await trackedGenerated(c)
+        if (tracked.length > 0) {
+            c.fail(`${tracked.join(', ')} generated on every run but TRACKED — gitignore does not apply to a tracked file, so it dirties every tree`)
+            c.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) untracks it in one commit, the file stays on disk' })
+        }
+        // the old root layout is a move a machine makes, so it is red until made
+        const left = legacyLayoutLeft(c.root, c.config)
+        if (left.length > 0) {
+            c.fail(`old layout: ${left.join(' ')} still at the repo root, shipkit keeps them under ${SHIPKIT_DIR}/`)
+            c.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) moves them and lands one commit' })
+        }
+        const legacy = hasLegacy(c.root)
+        const s = blockState(c, c.config, legacy)
+        switch (s) {
+            case 'missing-file': return c.fail('.gitignore missing — the contract git policy is unenforced')
+            case 'missing-block': return c.fail('.gitignore has no shipkit policy block — contract surfaces can leak into git')
+            case 'corrupted': return c.fail('.gitignore policy block corrupted (unpaired marker)')
+            case 'stale': return c.fail('.gitignore policy block is stale — the policy or repo-contributed lines moved since it was written')
+        }
+        // an unterminated last line is a TRAP, not a cosmetic defect: the next
+        // `>> .gitignore` fuses onto it and the result is one pattern that
+        // ignores neither path, with the file ending in a newline afterwards
+        // so nothing textual looks wrong
+        if (!endsWithNewline(c)) {
+            c.fail('.gitignore does not end with a newline — the next append fuses onto its last line and ignores neither path')
+            c.lines.push({ kind: 'fix-fail', text: 'shipkit ci (or check --fix SK004) terminates it' })
+            return
+        }
+        // the block states what must be ignored. git is the only thing that
+        // knows whether it IS: a stray negation below the block, or a line
+        // fused into another, leaves the text current over a broken repo
+        // a '!' line is the policy RE-INCLUDING a path on purpose, so git
+        // reporting it as not ignored is the rule working, not a break. It is
+        // a claim all the same, and the opposite one: a repo line BELOW the
+        // block re-ignoring the parent leaves the re-inclusion dead while the
+        // block text stays current, which is the same silent contradiction
+        const patterns = policyPatterns(c.config, legacy)
+        const claimed = patterns.filter((p) => !OVERRIDABLE.has(p) && !p.startsWith('!'))
+        const probes = new Map(claimed.map((p) => [probePath(p), p]))
+        const backProbes = new Map(patterns.filter((p) => p.startsWith('!')).map((p) => [probePath(p.slice(1)), p]))
+        const miss = await notIgnored(c, [...probes.keys(), ...backProbes.keys()])
+        if (miss == null) {
+            // not a git repo (a fixture, or a dir before `git init`). Say the
+            // verification did not run rather than reporting a green nothing
+            // measured, and stay quiet: there is nothing wrong here to fix
+            c.ok(`.gitignore policy block current (${claimed.length} patterns)`)
+            c.lines.push({ kind: 'skip', text: 'not a git repo here, so nothing verified the block against what git actually ignores' })
+            return
+        }
+        const unignored = miss.filter((m) => probes.has(m))
+        if (unignored.length > 0) {
+            const names = [...new Set(unignored.map((m) => probes.get(m) ?? m))]
+            c.fail(`.gitignore block claims ${names.join(', ')} ignored, git says otherwise — a negation below the block, or a line fused into its neighbour`)
+            c.lines.push({ kind: 'fix-fail', text: `git check-ignore -v ${unignored[0]} names the line that wins` })
+            return
+        }
+        const dead = [...backProbes.keys()].filter((p) => !miss.includes(p))
+        if (dead.length > 0) {
+            const names = [...new Set(dead.map((d) => backProbes.get(d) ?? d))]
+            c.fail(`.gitignore block re-includes ${names.join(', ')}, git ignores it anyway — a line below the block re-ignores its parent folder`)
+            c.lines.push({ kind: 'fix-fail', text: `git check-ignore -v ${dead[0]} names the line that wins` })
+            return
+        }
+        c.ok(`.gitignore policy block current, ${claimed.length + backProbes.size} patterns verified against git`)
+    },
+    fix: async (c): Promise<FixResult> => {
+        // the move first: it writes the new block itself, before any folder moves
+        const moved = process.env.SHIPKIT_FROZEN === '1' ? null : migrateLayout(c.root, { config: c.config, renderGitignore: (t, legacy) => renderPolicy(t, c.config, legacy) })
+        const layout = moved == null ? null
+            : moved.deferred != null ? `layout move deferred: ${moved.deferred}`
+            : moved.moved.length === 0 && moved.removed.length === 0 ? null
+            : `moved ${moved.moved.map((m) => m.from).join(', ')} under ${SHIPKIT_DIR}/${moved.commit != null ? ` (committed as ${moved.commit})` : moved.uncommitted === true ? ', the commit did not land' : ''}`
+        const legacy = hasLegacy(c.root)
+        const before = blockState(c, c.config, legacy)
+        // terminate an unterminated file even when the block itself is current:
+        // that missing byte is what the next append fuses onto
+        let terminated: string | null = null
+        if (before === 'current' && !endsWithNewline(c)) {
+            c.write('.gitignore', `${c.read('.gitignore') ?? ''}\n`)
+            terminated = '.gitignore terminated with a newline (the next append would have fused onto its last line)'
+        }
+        const blockSummary = before === 'current'
+            ? null
+            : before === 'missing-file' ? '.gitignore created with the policy block'
+            : before === 'missing-block' ? 'policy block appended (repo lines untouched)'
+            : before === 'corrupted' ? 'policy block rebuilt (stray markers dropped, repo lines kept visible)'
+            : 'policy block rewritten in place (repo lines untouched)'
+        if (blockSummary != null) writeBlock(c, c.config, legacy)
+        // the block must be written FIRST: untracking a path the ignore list
+        // does not yet carry leaves it staged for re-add on the next `git add`.
+        // The untrack is a git COMMIT through the hooks, so it stays in the
+        // module that owns that migration (rules/untrack-generated.ts)
+        const un = untrackGenerated(c.root, { enabled: c.config.untrackGenerated })
+        const parts = [layout, blockSummary, terminated]
+        if (un.did === 'untracked') parts.push(`untracked ${un.paths.join(', ')} (generated, now gitignored, committed as ${un.commit})`)
+        if (un.did === 'refused') parts.push(`left ${(await trackedGenerated(c)).join(', ')} tracked: ${un.why}`)
+        const summary = parts.filter((x): x is string => x != null).join(' · ')
+        return { changed: layout != null || blockSummary != null || terminated != null || un.did === 'untracked', summary: summary === '' ? 'policy block already current' : summary }
+    },
+})
+
+export default gitignorePolicy

package/src/{rules/SK005-rvlib-versions.ts → checks/SK005-rvlib-versions.check.ts}

@@ -10,8 +10,9 @@
 // Per rvlib-* dep:
 //   link:   → the symlink must resolve (a broken link dies cryptically at
 //             import time otherwise) — nothing to update, code is live
-//   semver  → installed vs npm latest; NEWER LIVE → this lint runs
-//             `bun update --latest` itself, loudly, guarded:
+//   semver  → installed vs npm latest; NEWER LIVE → this lint updates the
+//             dep itself, loudly, with the manager the repo's own lock files
+//             name (src/core/package-manager.ts), guarded:
 //             - SHIPKIT_FROZEN=1 (`check --frozen`, `ci --frozen`) → WARN,
 //               never touch
 //             - package.json/lockfile git-dirty (or no git) → WARN deferred,
@@ -25,6 +26,9 @@
 //             - the update itself failing splits by what it LEFT: a half-
 //               written package.json/lockfile is this repo and FAILs, an
 //               untouched tree is the registry and only WARNs
+//             updating an npm consumer with bun is the failure this detection
+//             exists for: package.json moves, package-lock.json does not, and
+//             the `npm ci` a deploy runs refuses that pair
 //   registry unreachable → loud skip, never red (offline is not a defect)
 // Committing the bump stays with the working agent — shipkit never commits.
 // Clean passes cache 24h (rule ttl), so the registry is fetched at most
@@ -38,7 +42,8 @@ import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { mutateLease, withMutateLease } from '../core/locked-write.ts'
-import type { Rule, RuleEnv } from './rule.ts'
+import { detectPackageManager } from '../core/package-manager.ts'
+import { check, type CheckEnv } from '../check.ts'
 
 type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
 
@@ -56,12 +61,15 @@ async function latestVersion(t: CheckCtx, name: string): Promise<string> {
     return v
 }
 
-export const rvlibVersions: Rule = {
+export const rvlibVersions = check({
     id: 'SK005',
     blocking: true,
     title: 'rvlib versions',
+    description: 'the rvlib packages installed here are as new as the published ones',
     owner: 'build/shipkit.md',
     ttl: '24h',
+    // it updates the rvlib deps unless the run is frozen
+    writes: true,
     cacheKey: (env) => {
         let pkg: Pkg
         try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return 'unreadable' }
@@ -71,47 +79,51 @@ export const rvlibVersions: Rule = {
             .map((n) => `${n}@${installedVersion(env.root, n) ?? 'absent'}`)
             .join(',')
     },
-    lint: async (t, env: RuleEnv) => {
+    run: async (c) => {
         let pkg: Pkg
-        try { pkg = JSON.parse(readFileSync(join(env.root, 'package.json'), 'utf8')) as Pkg } catch { return t.note('no readable package.json — rvlib versions not applicable') }
+        try { pkg = JSON.parse(readFileSync(join(c.root, 'package.json'), 'utf8')) as Pkg } catch { return c.note('no readable package.json — rvlib versions not applicable') }
         const deps = Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }).filter(([n]) => n.startsWith('rvlib-'))
-        if (deps.length === 0) return t.ok('no rvlib-* deps')
+        if (deps.length === 0) return c.ok('no rvlib-* deps')
+        const pm = detectPackageManager(c.root)
+        const manifest = ['package.json', ...pm.locks]
 
         const stale: Array<{ name: string; installed: string; latest: string }> = []
         for (const [name, spec] of deps) {
             if (spec.startsWith('link:')) {
-                if (installedVersion(env.root, name) == null) t.fail(`${name} is link: but the symlink does not resolve — re-run \`bun link ${name}\` (a broken link dies cryptically at import time)`)
-                else t.ok(`${name} (linked, live)`)
+                if (installedVersion(c.root, name) == null) c.fail(`${name} is link: but the symlink does not resolve — re-run \`bun link ${name}\` (a broken link dies cryptically at import time)`)
+                else c.ok(`${name} (linked, live)`)
                 continue
             }
-            const installed = installedVersion(env.root, name)
-            if (installed == null) { t.fail(`${name} declared (${spec}) but not installed — run: bun install`); continue }
+            const installed = installedVersion(c.root, name)
+            if (installed == null) { c.fail(`${name} declared (${spec}) but not installed — run: ${pm.install.join(' ')}`); continue }
             let latest: string
-            try { latest = await latestVersion(t, name) } catch (e) {
-                t.lines.push({ kind: 'skip', text: `${name} ${installed} — registry unreachable (${String(e).slice(0, 80)}), version drift unknown` })
+            try { latest = await latestVersion(c, name) } catch (e) {
+                c.lines.push({ kind: 'skip', text: `${name} ${installed} — registry unreachable (${String(e).slice(0, 80)}), version drift unknown` })
                 continue
             }
             // real semver order, not string difference — a dist-tag pointing
             // BEHIND the installed version (prerelease, unpublish window)
             // must never trigger a silent downgrade
             const cmp = Bun.semver.order(latest, installed)
-            if (cmp === 0) t.ok(`${name} ${installed} (latest)`)
-            else if (cmp < 0) t.ok(`${name} ${installed} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
+            if (cmp === 0) c.ok(`${name} ${installed} (latest)`)
+            else if (cmp < 0) c.ok(`${name} ${installed} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
             else stale.push({ name, installed, latest })
         }
         if (stale.length === 0) return
 
         const drift = stale.map((s) => `${s.name} ${s.installed} → ${s.latest}`).join(', ')
+        const names = stale.map((s) => s.name)
+        const cmd = pm.update(names)
+        if (pm.warn != null) c.warn(pm.warn)
         if (process.env['SHIPKIT_FROZEN'] === '1') {
-            t.warn(`newer rvlib live: ${drift} (frozen — apply with: bun update --latest ${stale.map((s) => s.name).join(' ')})`)
+            c.warn(`newer rvlib live: ${drift} (frozen — apply with: ${cmd.join(' ')})`)
             return
         }
-        const dirty = await t.exec(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb'], { cwd: env.root })
+        const dirty = await c.exec(['git', 'status', '--porcelain', '--', ...manifest], { cwd: c.root })
         if (dirty.code !== 0 || dirty.out.trim() !== '') {
-            t.warn(`newer rvlib live: ${drift} — self-update deferred (${dirty.code !== 0 ? `git says: ${dirty.out.trim().split('\n')[0] ?? `exit ${dirty.code}`}` : 'package.json/lockfile dirty'}); commit first, then re-run check`)
+            c.warn(`newer rvlib live: ${drift} — self-update deferred (${dirty.code !== 0 ? `git says: ${dirty.out.trim().split('\n')[0] ?? `exit ${dirty.code}`}` : 'package.json/lockfile dirty'}); commit first, then re-run check`)
             return
         }
-        const names = stale.map((s) => s.name)
         // this rule WRITES, and three agents in one checkout is the normal
         // case: two `bun update --latest` runs against one node_modules and
         // one lockfile is how a tree ends up half installed. The lease is what
@@ -119,17 +131,17 @@ export const rvlibVersions: Rule = {
         // report only, which would break "machine clearable red clears ITSELF".
         // The dirty probe above is re-run INSIDE the lease, because the holder
         // we waited for may have just done this exact update.
-        const leased = await withMutateLease(mutateLease(env.root, 'fix'), { label: 'self-update', print: () => {}, escape: 'SHIPKIT_FROZEN=1' }, async () => {
-            const again = await t.exec(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb'], { cwd: env.root })
+        const leased = await withMutateLease(mutateLease(c.root, 'fix'), { label: 'self-update', print: () => {}, escape: 'SHIPKIT_FROZEN=1' }, async () => {
+            const again = await c.exec(['git', 'status', '--porcelain', '--', ...manifest], { cwd: c.root })
             if (again.code === 0 && again.out.trim() !== '') return null
-            return await t.exec(['bun', 'update', '--latest', ...names], { cwd: env.root, timeoutMs: 120_000 })
+            return await c.exec(cmd, { cwd: c.root, timeoutMs: 120_000 })
         })
         if (!leased.ok) {
-            t.warn(`newer rvlib live: ${drift} — self-update deferred (${leased.warn}); re-run check once that run finishes`)
+            c.warn(`newer rvlib live: ${drift} — self-update deferred (${leased.warn}); re-run check once that run finishes`)
             return
         }
         if (leased.value == null) {
-            t.warn(`newer rvlib live: ${drift} — self-update deferred (package.json/lockfile went dirty while waiting for the write lease); commit first, then re-run check`)
+            c.warn(`newer rvlib live: ${drift} — self-update deferred (package.json/lockfile went dirty while waiting for the write lease); commit first, then re-run check`)
             return
         }
         const up = leased.value
@@ -137,21 +149,23 @@ export const rvlibVersions: Rule = {
             // which axis the failure sits on is measurable, so measure it: the
             // tree is either half-written (this repo, blocks) or untouched, and
             // a registry drop mid-download must never hard-red a healthy repo
-            const after = await t.exec(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb'], { cwd: env.root })
+            const after = await c.exec(['git', 'status', '--porcelain', '--', ...manifest], { cwd: c.root })
             const half = after.code !== 0 || after.out.trim() !== ''
-            const why = `bun update --latest ${names.join(' ')} exited ${up.code}${up.timedOut ? ', timed out' : ''}`
+            const why = `${cmd.join(' ')} exited ${up.code}${up.timedOut ? ', timed out' : ''}`
             const tail = up.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''
-            if (half) t.fail(`self-update failed (${why}) and package.json/lockfile are half-written — \`git status\`, then restore or finish it by hand: ${tail}`)
-            else t.warn(`self-update failed (${why}) and nothing was written — the registry or the network, not this repo. Retry with: bun update --latest ${names.join(' ')}: ${tail}`)
+            if (half) c.fail(`self-update failed (${why}) and package.json/lockfile are half-written — \`git status\`, then restore or finish it by hand: ${tail}`)
+            else c.warn(`self-update failed (${why}) and nothing was written — the registry or the network, not this repo. Retry with: ${cmd.join(' ')}: ${tail}`)
             return
         }
         for (const s of stale) {
-            const now = installedVersion(env.root, s.name)
+            const now = installedVersion(c.root, s.name)
             // WARN on purpose: the run MUTATED the repo and a follow-up
             // (restart watchers, commit) is owed — an ok here would be a
             // green, cacheable line replaying a past event as current state
-            if (now === s.latest) t.warn(`${s.name} ${s.installed} → ${now} self-updated — restart watchers, commit the bump`)
-            else t.warn(`${s.name} updated but reads ${now ?? 'missing'} (wanted ${s.latest}) — check the lockfile`)
+            if (now === s.latest) c.warn(`${s.name} ${s.installed} → ${now} self-updated — restart watchers, commit the bump`)
+            else c.warn(`${s.name} updated but reads ${now ?? 'missing'} (wanted ${s.latest}) — check the lockfile`)
         }
     },
-}
+})
+
+export default rvlibVersions

package/src/{rules/SK006-npm-publish-safety.ts → checks/SK006-npm-publish-safety.check.ts}

@@ -12,10 +12,9 @@
 // np/release-it deps, a control room publishing its own sub-libs) is
 // deliberately out of scope — `private: true` on the root already refuses,
 // and sanctioned sub-lib publishing must not turn this rule red.
-import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
-import { resolveUnits } from '../release/units.ts'
-import type { Rule } from './rule.ts'
+import { join, relative } from 'path'
+import { checkUnitReader, resolveUnits } from '../release/unit-resolve.ts'
+import { check } from '../check.ts'
 
 type Pkg = {
     name?: string
@@ -32,41 +31,41 @@ type Pkg = {
  *  arrival, and it fails at install time for a stranger, never here. */
 const LOCAL_PROTOCOL = /^(link|file|portal|workspace):/
 
-export const npmPublishSafety: Rule = {
+export const npmPublishSafety = check({
     id: 'SK006',
     blocking: true,
     title: 'npm publish safety',
+    description: 'a private package carries no publish machinery',
     owner: 'meta/rv-conventions/package-json.md',
-    // pure filesystem: the root package.json plus every declared unit's, at
-    // dirs the config picks, so the tree rather than a list of paths
-    inputs: ['.'],
-    lint: (t, env) => {
-        const p = join(env.root, 'package.json')
-        if (!existsSync(p)) return t.ok('no package.json — nothing publishable')
-        let pkg: Pkg
-        try { pkg = JSON.parse(readFileSync(p, 'utf8')) as Pkg } catch { return t.note('package.json unreadable — SK001 reports it') }
+    // keyed on what it reads: the root package.json and every declared release
+    // unit's, at the dirs the config picks
+    run: (c) => {
+        const json = (rel: string): Pkg | null | 'unparseable' => {
+            try { return c.json<Pkg>(rel) } catch { return 'unparseable' }
+        }
+        const pkg = json('package.json')
+        if (pkg == null) return c.ok('no package.json — nothing publishable')
+        if (pkg === 'unparseable') return c.note('package.json unreadable — SK001 reports it')
         // every block a CONSUMER resolves, for every unit that can publish:
         // the ROOT is usually private, so scanning it alone guards nothing
         const localHits: string[] = []
-        for (const u of [{ dir: env.root, id: 'root' }, ...resolveUnits(env.root, env.config).units.filter((x) => x.rel !== '')]) {
-            const up = join(u.dir, 'package.json')
-            if (!existsSync(up)) continue
-            let upkg: Pkg
-            try { upkg = JSON.parse(readFileSync(up, 'utf8')) as Pkg } catch { continue }
+        for (const u of [{ dir: c.root, id: 'root' }, ...resolveUnits(c.root, c.config, checkUnitReader(c)).units.filter((x) => x.rel !== '')]) {
+            const upkg = json(relative(c.root, join(u.dir, 'package.json')))
+            if (upkg == null || upkg === 'unparseable') continue
             if (upkg.private === true) continue
             for (const block of ['dependencies', 'peerDependencies', 'optionalDependencies'] as const)
                 for (const [dep, range] of Object.entries(upkg[block] ?? {}))
                     if (LOCAL_PROTOCOL.test(range)) localHits.push(`${u.id}: ${block}.${dep} = ${range}`)
         }
         if (localHits.length > 0)
-            t.fail(
+            c.fail(
                 `${localHits.join(', ')} — a local protocol cannot resolve on a consumer's machine, so publishing that ships a package which fails at install. Declare the version it WILL be, and keep the local wiring in overrides (npm ignores those from a dependency) or in devDependencies`,
             )
         if (pkg.name?.startsWith('rvlib-') === true) {
-            if (localHits.length === 0) t.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
+            if (localHits.length === 0) c.ok('rvlib-* package — publishes by design (distribute/npm owns it)')
             return
         }
-        if (pkg.private !== true) return t.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
+        if (pkg.private !== true) return c.note('private:true missing — SK001 reports it; publish machinery not judged until the lock is on')
         const machinery: string[] = []
         if (pkg.publishConfig != null) machinery.push('publishConfig')
         for (const s of ['prepublishOnly', 'prepublish', 'postpublish'])
@@ -74,7 +73,9 @@ export const npmPublishSafety: Rule = {
         if (pkg.scripts?.['publish'] != null && /npm publish|bun publish/.test(pkg.scripts['publish']))
             machinery.push(`scripts.publish (runs npm/bun publish)`)
         if (machinery.length > 0)
-            t.fail(`private package carries publish machinery: ${machinery.join(', ')} — dead weight now, a loaded gun the day private flips; delete it or make the repo a published lib on purpose`)
-        else if (localHits.length === 0) t.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root, no local dependency protocol in any unit`)
+            c.fail(`private package carries publish machinery: ${machinery.join(', ')} — dead weight now, a loaded gun the day private flips; delete it or make the repo a published lib on purpose`)
+        else if (localHits.length === 0) c.ok(`private package — no publishConfig / prepublish* / npm-publishing 'publish' script on the root, no local dependency protocol in any releasing unit`)
     },
-}
+})
+
+export default npmPublishSafety