rvlib-shipkit 0.32.0 → 0.34.0

package/src/rules/SK005-rvlib-versions.ts

@@ -16,6 +16,12 @@
 //               never touch
 //             - package.json/lockfile git-dirty (or no git) → WARN deferred,
 //               a tool must not mix its writes into human-staged work
+//             - another run already holds the repo's mutate lease → the rule
+//               WAITS for it, re-reads the dirty probe inside the lease, and
+//               defers with a WARN if that run already did the work. Two
+//               `bun update --latest` calls against one node_modules is how a
+//               tree ends up half installed, and demoting the rule to report
+//               only instead would break "machine clearable red clears ITSELF" 
 //             - 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
@@ -31,6 +37,7 @@
 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'
 
 type Pkg = { version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
@@ -105,7 +112,27 @@ export const rvlibVersions: Rule = {
             return
         }
         const names = stale.map((s) => s.name)
-        const up = await t.exec(['bun', 'update', '--latest', ...names], { cwd: env.root, timeoutMs: 120_000 })
+        // 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
+        // lets the rule keep repairing itself instead of being demoted to
+        // 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 })
+            if (again.code === 0 && again.out.trim() !== '') return null
+            return await t.exec(['bun', 'update', '--latest', ...names], { cwd: env.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`)
+            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`)
+            return
+        }
+        const up = leased.value
         if (up.code !== 0) {
             // which axis the failure sits on is measurable, so measure it: the
             // tree is either half-written (this repo, blocks) or untouched, and

package/src/rules/SK006-npm-publish-safety.ts

@@ -37,6 +37,9 @@ export const npmPublishSafety: Rule = {
     blocking: true,
     title: 'npm publish safety',
     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')

package/src/rules/SK008-reviewer-agent.ts

@@ -7,11 +7,12 @@
 // that edits by proxy. An absent `tools:` line is the worst case of all: the
 // harness then inherits every tool. The brief itself must exist. No
 // declaration = not a reviewer repo, and the rule passes silently.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, isAbsolute, join } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
+import { atomicWrite } from '../core/locked-write.ts'
 
 /** default read-only toolset — an ALLOWLIST, not a denylist: a tool that can
  *  edit by proxy (spawning a subagent, an MCP writer) is exactly what a
@@ -72,6 +73,9 @@ export const reviewerAgent: Rule = {
     blocking: true,
     title: 'reviewer agent',
     owner: 'identity/how-we-work.md',
+    // the brief is a CONFIG path, and a `~/...` or absolute one puts it
+    // outside the repo, where no tree id can see whether it still exists
+    never: 'the reviewer brief may live outside the repo, where no tree id reaches it',
     lint: (t, env) => {
         const r = env.config.reviewer
         if (r == null) return t.ok('no reviewer agent declared (repo.config reviewer:) — skipped')
@@ -93,7 +97,7 @@ export const reviewerAgent: Rule = {
         const p = join(env.root, rel)
         if (existsSync(p)) return { changed: false, summary: `${rel} exists — remaining findings are about its content, fix them by hand` }
         mkdirSync(dirname(p), { recursive: true })
-        writeFileSync(p, canonicalAgent(r))
+        atomicWrite(p, canonicalAgent(r))
         return { changed: true, summary: `${rel} written — points at ${r.brief}, no edit tools` }
     },
 }

package/src/rules/SK009-commit-ai-tells.ts

@@ -29,6 +29,9 @@ export const commitAiTells: Rule = {
     blocking: true,
     title: 'commit ai tells',
     owner: 'identity/how-we-commit.md',
+    // it scans the full `git log` and every ref name. History and refs are not
+    // work-tree content, so nothing a scan can produce describes this answer
+    never: 'reads the full commit history and every ref name, neither of which is work-tree content',
     lint: async (t, env) => {
         const declared = env.config.visibility ?? 'private'
         if (declared !== 'public')

package/src/rules/SK010-undeclared-release-unit.ts

@@ -65,6 +65,8 @@ export const undeclaredReleaseUnit: Rule = {
     blocking: true,
     title: 'release units declared',
     owner: 'build/shipkit.md',
+    // `git ls-files` plus a walk for every package.json in the repo
+    inputs: ['.'],
     lint: (t, env) => {
         const { units, errors } = resolveUnits(env.root, env.config)
         // a DECLARED unit that does not resolve is a declaration bug and

package/src/rules/SK011-sibling-unit-ranges.ts

@@ -59,6 +59,8 @@ export const siblingUnitRanges: Rule = {
     blocking: true,
     title: 'sibling unit ranges',
     owner: 'build/shipkit.md',
+    // every declared unit's package.json, at dirs the config picks
+    inputs: ['.'],
     lint: (t, env) => {
         const { units } = resolveUnits(env.root, env.config)
         const version = new Map(units.map((u) => [u.name, u.version]))

package/src/rules/SK012-config-barrel-import.ts

@@ -10,9 +10,10 @@
 // A barrel is a fine PUBLIC surface and a terrible one to import from a config
 // file that exists to be read before anything else happens. This rule is
 // narrow on purpose: it is about repo.config.ts, not about barrels in general.
-import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import type { FixResult, Rule, RuleEnv } from './rule.ts'
+import { atomicWrite } from '../core/locked-write.ts'
 
 const CONFIG = 'repo.config.ts'
 const BARREL = /(^|\n)(\s*import\s+(?:type\s+)?\{[^}]*\}\s+from\s+)['"]rvlib-shipkit['"]/
@@ -31,6 +32,9 @@ export const configBarrelImport: Rule = {
     blocking: true,
     title: 'config import path',
     owner: 'build/shipkit.md',
+    // ONE file, and the one file shipkit guarantees exists: loadRepoConfig
+    // refuses a repo without it
+    inputs: ['repo.config.ts'],
     lint: (t, env) => {
         const p = join(env.root, CONFIG)
         if (!existsSync(p)) return void t.ok(`${CONFIG} absent — nothing to narrow`)
@@ -54,7 +58,7 @@ export const configBarrelImport: Rule = {
         // only rewrite what the narrow module actually exports: silently
         // repointing an import it cannot serve turns a slow gate into a broken one
         if (importedSymbols(line).some((s) => !CONFIG_SYMBOLS.has(s))) return { changed: false, summary: 'imports symbols the narrow module does not export — move them by hand' }
-        writeFileSync(p, src.replace(BARREL, `$1$2'${NARROW}'`))
+        atomicWrite(p, src.replace(BARREL, `$1$2'${NARROW}'`))
         return { changed: true, summary: `${CONFIG} now imports ${NARROW} (~400ms saved per run)` }
     },
 }

package/src/rules/SK013-one-way-in-policy.ts

@@ -0,0 +1,156 @@
+// SK013 — the harness half of ONE WAY IN (build/shipkit.md). Rule SK001 routes
+// the package.json scripts, and that alone is not enough: `bun test` is a bun
+// BUILTIN, so no script can intercept it and the reflex stays open. This rule
+// makes the repo carry the two things that CAN close it, and repairs them:
+//
+//   - `permissions.deny` — declarative and unbypassable (deny beats allow at
+//     every settings level, and bypassPermissions does not lift it)
+//   - a PreToolUse hook — the only way to put a REASON in front of the model.
+//     A bare deny says only that the call was denied, and a refusal with no
+//     replacement sends the agent looking for another runner.
+//
+// Both are generated from ONE table (core/one-way-in-policy.ts). The file is
+// TRACKED on purpose: `.claude/settings.local.json` is gitignored by the house
+// scaffold, so a policy written there would bind exactly one checkout.
+import { existsSync, mkdirSync, readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { inferBin } from '../core/canonical-scripts.ts'
+import { denyRules, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import type { FixResult, Rule, RuleEnv } from './rule.ts'
+import { atomicWrite } from '../core/locked-write.ts'
+
+const OWNER = 'build/shipkit.md'
+export const SETTINGS_PATH = '.claude/settings.json'
+
+type Settings = {
+    permissions?: { deny?: string[] }
+    hooks?: Record<string, Array<{ matcher?: string; hooks?: Array<{ type?: string; command?: string }> }>>
+}
+
+/** slots this repo does not route, so it must not be refused the shell command
+ *  either: ONE declaration governs the script name and the raw call together */
+export function exemptSlots(c: RepoConfig): Set<string> {
+    const off = new Set(c.oneWayIn?.exempt ?? [])
+    for (const [slot, def] of Object.entries(c.defaults ?? {})) if (def === false) off.add(slot)
+    return off
+}
+
+/** how the hook invokes the guard. `$CLAUDE_PROJECT_DIR` because a hook's cwd
+ *  is not promised to be the repo root */
+export function guardCommand(bin?: string): string {
+    const path = bin == null
+        ? 'node_modules/rvlib-shipkit/src/hooks/one-way-in-guard.ts'
+        : bin.replace(/cli\.ts$/, 'hooks/one-way-in-guard.ts')
+    return `bun "$CLAUDE_PROJECT_DIR/${path}"`
+}
+
+/** a guard under `node_modules/` that is not there yet says the dependency is
+ *  not installed, which `bun install` fixes and no edit to this repo can. Any
+ *  other unresolvable path is a config this repo chose and got wrong. */
+const isUninstalledDep = (rel: string): boolean => rel.startsWith('node_modules/')
+
+const readSettings = (root: string): Settings | null => {
+    const p = join(root, SETTINGS_PATH)
+    if (!existsSync(p)) return null
+    try { return JSON.parse(readFileSync(p, 'utf8')) as Settings } catch { return null }
+}
+
+const guardHookCommand = (s: Settings): string | null => {
+    for (const m of s.hooks?.['PreToolUse'] ?? [])
+        for (const h of m.hooks ?? [])
+            if (h.command?.includes('one-way-in-guard') === true) return h.command
+    return null
+}
+
+const hasGuardHook = (s: Settings): boolean => guardHookCommand(s) != null
+
+/** the guard file the hook command points at, resolved against the repo root.
+ *  A hook whose script does not exist errors on EVERY Bash call and refuses
+ *  nothing, so the agent sees only the bare deny, which is the one failure
+ *  this rule exists to prevent. Declaring it and never running it is worse
+ *  than not declaring it, so it FAILs. */
+function guardScriptMissing(root: string, command: string): string | null {
+    const m = /["']?\$(?:\{)?CLAUDE_PROJECT_DIR(?:\})?\/([^"'\s]+)["']?/.exec(command)
+    const rel = m?.[1]
+    if (rel == null) return null // a form this rule cannot resolve is not a form it may condemn
+    return existsSync(join(root, rel)) ? null : rel
+}
+
+const readBin = (root: string): string | undefined => {
+    try { return inferBin((JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {}) }
+    catch { return undefined }
+}
+
+export const oneWayInPolicy: Rule = {
+    id: 'SK013',
+    blocking: true,
+    title: 'one way in policy',
+    owner: OWNER,
+    // .claude/settings.json, package.json, and whether the declared guard
+    // script resolves — the last one is a config-chosen path
+    inputs: ['.'],
+    lint: (t, env) => {
+        const want = denyRules(exemptSlots(env.config))
+        if (want.length === 0) return t.ok('every governed slot is exempt (repo.config oneWayIn/defaults) — nothing to deny')
+        const s = readSettings(env.root)
+        if (s == null) {
+            t.fail(`${SETTINGS_PATH} ${existsSync(join(env.root, SETTINGS_PATH)) ? 'is unparseable' : 'missing'} — nothing stops an agent typing \`bun test\`, and a package.json script cannot intercept a bun builtin`)
+            return
+        }
+        const have = new Set(s.permissions?.deny ?? [])
+        const missing = want.filter((r) => !have.has(r))
+        if (missing.length > 0)
+            t.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
+        const guard = guardHookCommand(s)
+        if (guard == null)
+            t.fail(`${SETTINGS_PATH}: no PreToolUse guard — a bare deny tells the model only that it was denied, so it goes looking for another runner instead of the shipkit command`)
+        else {
+            const missing = guardScriptMissing(env.root, guard)
+            // the hook is DECLARED either way, so it starts working the moment
+            // the dependency lands: no second fix run, nothing to remember. An
+            // uninstalled dependency is therefore a WARN naming the command
+            // that fixes it, not a red gate on a repo nobody has installed yet,
+            // and the deny list is the floor throughout. A path this repo chose
+            // and got wrong is still a FAIL: it will never resolve on its own.
+            if (missing != null && isUninstalledDep(missing))
+                t.warn(
+                    `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which is not installed yet — until then a refusal names no replacement, and the deny list is the whole floor`,
+                    `bun install (or bun add -d rvlib-shipkit)`,
+                )
+            else if (missing != null)
+                t.fail(
+                    `${SETTINGS_PATH}: the PreToolUse guard points at ${missing}, which does not exist — every Bash call errors and no refusal ever names the shipkit command`,
+                    `point it at this repo's own copy of hooks/one-way-in-guard.ts, or delete the hook and let the deny list stand alone`,
+                )
+        }
+        if (!t.failed) t.ok(`${SETTINGS_PATH} closes ${want.length}/${RAW_RUNNERS.length} raw runner(s), with the replacement named`)
+    },
+    // MERGES, never rewrites: this file also carries the attribution silencer,
+    // a repo's own allow list and its own hooks, and clobbering those to fix a
+    // deny list would cost more than the finding it repairs
+    fix: (env: RuleEnv): FixResult => {
+        const want = denyRules(exemptSlots(env.config))
+        if (want.length === 0) return { changed: false, summary: 'every governed slot is exempt — nothing to write' }
+        const p = join(env.root, SETTINGS_PATH)
+        const existing = readSettings(env.root)
+        if (existing == null && existsSync(p)) return { changed: false, summary: `${SETTINGS_PATH} is unparseable — repair it by hand first, a merge would destroy it` }
+        const s: Settings = existing ?? {}
+        const changes: string[] = []
+        const deny = s.permissions?.deny ?? []
+        const added = want.filter((r) => !deny.includes(r))
+        if (added.length > 0) {
+            s.permissions = { ...s.permissions, deny: [...deny, ...added] }
+            changes.push(`${added.length} raw runner(s) denied`)
+        }
+        if (!hasGuardHook(s)) {
+            const pre = s.hooks?.['PreToolUse'] ?? []
+            s.hooks = { ...s.hooks, PreToolUse: [...pre, { matcher: 'Bash', hooks: [{ type: 'command', command: guardCommand(readBin(env.root)) }] }] }
+            changes.push('PreToolUse guard wired (every refusal names the shipkit command)')
+        }
+        if (changes.length === 0) return { changed: false, summary: `${SETTINGS_PATH} already closes every raw runner` }
+        mkdirSync(dirname(p), { recursive: true })
+        atomicWrite(p, JSON.stringify(s, null, 2) + '\n')
+        return { changed: true, summary: `${SETTINGS_PATH}: ${changes.join(', ')}` }
+    },
+}

package/src/rules/rule-registry.ts

@@ -15,6 +15,7 @@ import { commitAiTells } from './SK009-commit-ai-tells.ts'
 import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
 import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
 import { configBarrelImport } from './SK012-config-barrel-import.ts'
+import { oneWayInPolicy } from './SK013-one-way-in-policy.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -29,6 +30,7 @@ export const RULES: readonly Rule[] = [
     undeclaredReleaseUnit,
     siblingUnitRanges,
     configBarrelImport,
+    oneWayInPolicy,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

package/src/rules/rule.ts

@@ -28,8 +28,29 @@ export type Rule = {
      *  as the fix: pointer whenever a failing/warning lint attached none */
     owner: string
     /** clean-pass cache duration (check-suite TTL, e.g. '24h') — for rules that
-     *  probe the network; skip/WARN/FAIL runs are never cached */
+     *  probe the network; skip/WARN/FAIL runs are never cached. Declares the
+     *  WORLD population (ledger/git-key.ts). */
     ttl?: string
+    /** CONTENT population: the repo-relative paths this rule reads. A rule with
+     *  neither `inputs` nor `ttl` is never cached, which is the safe default.
+     *  A rule declared by a REPO rather than by shipkit must list the dir its
+     *  own code lives in too: shipkit's `src` tree id covers the built-ins and
+     *  cannot see a repo's. Declaring both `inputs` and `ttl` is a registration
+     *  failure — a rule reads files or it reads the world, never both. */
+    inputs?: string[]
+    /** repo-relative entry file(s) of this rule's OWN code, walked through the
+     *  module graph so a shared helper the rule imports is in its key too. A
+     *  built-in SK rule needs none: the toolchain identity content-hashes
+     *  shipkit's whole source, so editing any of it moves every key. A rule a
+     *  REPO declares is invisible to that, so it names its module here, or
+     *  includes the dir holding it in `inputs`. Without either, fixing a bug
+     *  in the rule does not move its key. */
+    code?: string[]
+    /** a DECIDED never-cacheable, with the reason: this rule reads git history,
+     *  a path that may live outside the repo, or the wall clock, so no key can
+     *  describe it. Says somebody looked, which is what takes it off the
+     *  burn-down list. */
+    never?: string
     /** cache-identity contribution for TTL'd rules whose verdict depends on
      *  config — a changed key busts the cache instantly instead of replaying
      *  a stale assertion for the TTL */

package/src/rules/run-fix.ts

@@ -47,9 +47,11 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
             continue
         }
         const f = await rule.fix!(env)
-        // an unchanged fix is the DESIGNED outcome for judgment findings —
-        // a note, not a warning
-        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `[${rule.id}] fix changed nothing — ${f.summary}`)
+        // an unchanged fix is the DESIGNED outcome for judgment findings, so
+        // it is an ok, not a warning. It carries a frozen wire prefix like
+        // every other line the fix pass emits: `shipkit ci` promises its whole
+        // output is parseable, and a bare line breaks that for every reader.
+        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `ok: [${rule.id}] fix changed nothing — ${f.summary}`)
         const after = new CheckCtx(new Map())
         await runRuleLint(rule, after, env)
         // the fix already ran: advertising it again on surviving findings

package/src/scaffold/files/claude-settings-local.json

@@ -3,10 +3,8 @@
     "allow": [
       "Bash(shipkit *)",
       "Bash(bun run *)",
-      "Bash(bun test*)",
       "Bash(bun install*)",
       "Bash(bun add *)",
-      "Bash(bunx tsc*)",
       "Bash(bunx wrangler*)",
       "Bash(git status*)",
       "Bash(git diff*)",
@@ -15,7 +13,6 @@
       "Bash(git commit*)",
       "Bash(git push*)",
       "Bash(curl *)",
-      "Bash(oxlint*)",
       "Bash(./deploy.sh)"
     ],
     "deny": []

package/src/scaffold/files/verify-skill.md

@@ -11,7 +11,7 @@ description: Prove a change in THIS project actually works — drive the real fl
 
 ## The rules (house-wide)
 - Failing repro test BEFORE the fix. Green checks ≠ verification.
-- Logic → fast headless `bun test` (tiny ~10-line test files reusing fixtures).
+- Logic → fast headless bun tests, run through `shipkit ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
 - Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
 - Verify as the end user would: drive the real flow, observe the real signal.
 

package/src/ts/config.ts

@@ -40,12 +40,72 @@ export function findRepoRoot(cwd: string = process.cwd()): string {
    return out !== '' ? out : cwd
 }
 
-// tsconfig files are JSONC — strip comments + trailing commas, loosely
-function parseJsonc(text: string): unknown {
-   const noComments = text
-      .replace(/\/\*[\s\S]*?\*\//g, '')
-      .replace(/(^|[^:])\/\/[^\n]*/g, '$1') // keep 'http://...' intact
-   return JSON.parse(noComments.replace(/,\s*([}\]])/g, '$1'))
+// tsconfig files are JSONC: strip comments and trailing commas.
+//
+// A quote-aware scanner rather than regexes, because tsconfig is the one
+// dialect where the regex version is guaranteed to be wrong: `"src/**/*"` is
+// a `/*` with its own `*/`, so a block-comment regex eats an arbitrary span of
+// a perfectly valid file. Measured across ~/dev, the regex version THREW on 8
+// real tsconfigs (this repo's included) and silently rewrote `"src/**/*.ts"`
+// to `"src*.ts"` in 8 more. This parser gates typecheck AND publish, so it
+// does not get to be loose.
+export function parseJsonc(text: string): unknown {
+   let out = ''
+   let i = 0
+   while (i < text.length) {
+      const c = text[i]!
+      if (c === '"') {
+         out += c
+         i++
+         while (i < text.length) {
+            const s = text[i]!
+            out += s
+            i++
+            if (s === '\\') { out += text[i] ?? ''; i++; continue }
+            if (s === '"') break
+         }
+         continue
+      }
+      if (c === '/' && text[i + 1] === '/') { while (i < text.length && text[i] !== '\n') i++; continue }
+      if (c === '/' && text[i + 1] === '*') {
+         i += 2
+         while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++
+         i += 2
+         continue
+      }
+      out += c
+      i++
+   }
+   return JSON.parse(dropTrailingCommas(out))
+}
+
+/** a comma before the next `}` or `]`, outside any string, is dropped */
+function dropTrailingCommas(text: string): string {
+   let out = ''
+   let i = 0
+   let pendingComma = -1 // index in `out` of a comma awaiting its next token
+   while (i < text.length) {
+      const c = text[i]!
+      if (c === '"') {
+         if (pendingComma >= 0) pendingComma = -1
+         out += c
+         i++
+         while (i < text.length) {
+            const s = text[i]!
+            out += s
+            i++
+            if (s === '\\') { out += text[i] ?? ''; i++; continue }
+            if (s === '"') break
+         }
+         continue
+      }
+      if (c === ',') { pendingComma = out.length; out += c; i++; continue }
+      if ((c === '}' || c === ']') && pendingComma >= 0) out = out.slice(0, pendingComma) + out.slice(pendingComma + 1)
+      if (!/\s/.test(c)) pendingComma = -1
+      out += c
+      i++
+   }
+   return out
 }
 
 function rootsFromTsconfig(root: string): string[] {

package/src/ts/cycles.ts

@@ -1,87 +1,14 @@
 // zero-dep circular import detector. The repo uses absolute repo-root import
 // specifiers ('src/...') with explicit .ts extensions, so resolution is string
-// identity: crawl .ts/.tsx files, regex out the runtime import specifiers
-// (type-only imports don't count), build the graph, tarjan the SCCs, enumerate
-// elementary cycles. Runs on a bare checkout, no install needed.
-import { readdirSync, readFileSync } from 'fs'
-import { dirname, join } from 'path'
-import { isSkipped, loadConfig, resolvePackageSpecifier, toPosix, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
-import { templateLineMask } from 'rvlib-shipkit/src/ts/source-mask.ts'
+// identity. The crawl, the specifier extraction and the resolution rule live
+// in source-graph.ts (shared with the ledger key layer, so a cycle and a cache
+// key can never disagree about where an import points); this file owns the
+// tarjan + elementary-cycle half. Runs on a bare checkout, no install needed.
+import { loadConfig, type RvtConfig } from 'rvlib-shipkit/src/ts/config.ts'
+import { buildSourceGraph } from 'rvlib-shipkit/src/ts/source-graph.ts'
 
 const CYCLE_CAP = 500 // bail loudly instead of exploding on a pathological graph
 
-function crawl(cfg: RvtConfig, dir: string, out: string[]): void {
-   let entries
-   try {
-      entries = readdirSync(join(cfg.root, dir), { withFileTypes: true })
-   } catch {
-      return
-   }
-   for (const entry of entries) {
-      const rel = `${dir}/${entry.name}`
-      if (entry.isDirectory()) {
-         if (!isSkipped(rel, cfg)) crawl(cfg, rel, out)
-      } else if (/\.tsx?$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
-         out.push(rel)
-      }
-   }
-}
-
-// strip comments (line comments only when preceded by whitespace, so
-// 'http://...' survives) and type-only import/export statements, then extract
-// the remaining runtime specifiers
-export function extractSpecs(content: string): string[] {
-   // template-literal content is text, a codegen emitting import lines inside
-   // a backtick block is not an import of this module. single-line templates
-   // strip in place, multiline ones blank via the shared mask (null mask =
-   // desynced walk, scan everything rather than eat code between backticks)
-   const rawLines = content.split('\n')
-   const mask = templateLineMask(rawLines)
-   const demasked = mask == null ? content : rawLines.map((l, i) => (mask[i] ? '' : l)).join('\n')
-   const cleaned = demasked
-      .replace(/\/\*[\s\S]*?\*\//g, '')
-      .replace(/(^|\s)\/\/[^\n]*/g, '$1')
-      .replace(/`(?:\\.|[^`\\\n])*`/g, '``')
-      .replace(/\b(?:import|export)\s+type\s[^'"]*?from\s*(['"])[^'"\n]*\1/g, '')
-   const specs: string[] = []
-   // import x from / export { x } from — skipped when every specifier is `type X` (erased at runtime)
-   for (const m of cleaned.matchAll(/\b(?:import|export)\s([^'";]*?)from\s*['"]([^'"\n]+)['"]/g)) {
-      const clause = (m[1] ?? '').trim()
-      if (/^\{[^{}]*\}$/.test(clause)) {
-         const items = clause.slice(1, -1).split(',').map((s) => s.trim()).filter((s) => s !== '')
-         if (items.length > 0 && items.every((s) => /^type\s/.test(s))) continue
-      }
-      if (m[2] != null) specs.push(m[2])
-   }
-   for (const re of [
-      /\bimport\s*['"]([^'"\n]+)['"]/g, // side-effect import
-      /\b(?:import|require)\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g, // dynamic import / require
-   ]) {
-      for (const m of cleaned.matchAll(re)) {
-         if (m[1] != null) specs.push(m[1])
-      }
-   }
-   return specs
-}
-
-function resolveSpec(cfg: RvtConfig, fromFile: string, spec: string, fileSet: Set<string>): string | null {
-   let base: string
-   const viaPackage = resolvePackageSpecifier(spec, cfg)
-   if (spec.startsWith('./') || spec.startsWith('../')) {
-      base = toPosix(join(dirname(fromFile), spec))
-   } else if (viaPackage != null) {
-      base = viaPackage // package-name specifier → the sub-package's dir
-   } else if (cfg.roots.some((r) => spec.startsWith(`${r}/`))) {
-      base = spec
-   } else {
-      return null // third-party
-   }
-   for (const candidate of [base, base.replace(/\.js$/, '.ts'), `${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]) {
-      if (fileSet.has(candidate)) return candidate
-   }
-   return null
-}
-
 // tarjan strongly connected components, iterative to survive deep graphs
 function tarjanSCCs(nodes: string[], adj: Map<string, string[]>): string[][] {
    const index = new Map<string, number>()
@@ -166,19 +93,7 @@ function cyclesInSCC(scc: string[], adj: Map<string, string[]>): string[][] {
 }
 
 export function findCircularDependencies(cfg: RvtConfig = loadConfig()): string[][] {
-   const files: string[] = []
-   for (const root of cfg.roots) crawl(cfg, root, files)
-   files.sort()
-   const fileSet = new Set(files)
-   const adj = new Map<string, string[]>()
-   for (const file of files) {
-      const targets = new Set<string>()
-      for (const spec of extractSpecs(readFileSync(join(cfg.root, file), 'utf8'))) {
-         const target = resolveSpec(cfg, file, spec, fileSet)
-         if (target != null && target !== file) targets.add(target)
-      }
-      adj.set(file, [...targets].sort())
-   }
+   const { files, adj } = buildSourceGraph(cfg)
    const cycles: string[][] = []
    for (const scc of tarjanSCCs(files, adj)) {
       if (scc.length < 2) continue