rvlib-shipkit 0.33.0 → 0.35.0

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

@@ -12,12 +12,13 @@
 // 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, writeFileSync } from 'fs'
+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'
@@ -44,6 +45,11 @@ export function guardCommand(bin?: string): string {
     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
@@ -81,6 +87,9 @@ export const oneWayInPolicy: Rule = {
     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')
@@ -98,10 +107,21 @@ export const oneWayInPolicy: Rule = {
             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)
-            if (missing != null)
+            // 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`,
-                    `bun install (or bun add -d rvlib-shipkit)`,
+                    `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`)
@@ -130,7 +150,7 @@ export const oneWayInPolicy: Rule = {
         }
         if (changes.length === 0) return { changed: false, summary: `${SETTINGS_PATH} already closes every raw runner` }
         mkdirSync(dirname(p), { recursive: true })
-        writeFileSync(p, JSON.stringify(s, null, 2) + '\n')
+        atomicWrite(p, JSON.stringify(s, null, 2) + '\n')
         return { changed: true, summary: `${SETTINGS_PATH}: ${changes.join(', ')}` }
     },
 }

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/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 tests, run through `shipkit ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <name filter>` is the narrow way in.
+- 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

package/src/ts/source-graph.ts

@@ -0,0 +1,158 @@
+// the module graph, ONE resolver, two traversals.
+//
+// `cycles` needs the WHOLE graph (tarjan wants every node). The ledger key
+// layer needs the transitive import closure of a handful of entry files and
+// nothing else, and building the whole graph to answer that costs the repo's
+// entire source tree per run. Both go through `resolveSpec` here, so what a
+// cycle sees and what a key sees can never disagree about where an import
+// points.
+import { existsSync, readFileSync, readdirSync } 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'
+
+/** repo-relative posix paths of every source file under the config roots */
+export function crawlSources(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)) crawlSources(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
+}
+
+/** THE resolution rule. `has` decides what exists: a prebuilt file set for the
+ *  whole-graph walk, a disk probe for the lazy closure. Returns null for
+ *  third-party specifiers and for anything outside the config roots. */
+export function resolveSpec(cfg: RvtConfig, fromFile: string, spec: string, has: (rel: string) => boolean): 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 {
+      // a root-relative specifier ('src/a.ts'), or anything else the caller's
+      // `has` recognises. Third-party names die in the candidate loop below
+      // rather than here: `has` is what decides existence, and a resolution
+      // rule that also decided membership made every specifier outside the
+      // crawl roots invisible, which is where the checks in this repo live.
+      base = spec
+   }
+   for (const candidate of [base, base.replace(/\.js$/, '.ts'), `${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]) {
+      if (has(candidate)) return candidate
+   }
+   return null
+}
+
+export type SourceGraph = {
+   /** every source file under the roots, repo-relative posix, sorted */
+   files: string[]
+   /** file → the local files it imports at runtime, sorted */
+   adj: Map<string, string[]>
+}
+
+/** the WHOLE graph — every file under the roots crawled and resolved. */
+export function buildSourceGraph(cfg: RvtConfig = loadConfig()): SourceGraph {
+   const files: string[] = []
+   for (const root of cfg.roots) crawlSources(cfg, root, files)
+   files.sort()
+   const fileSet = new Set(files)
+   const has = (p: string): boolean => fileSet.has(p)
+   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, has)
+         if (target != null && target !== file) targets.add(target)
+      }
+      adj.set(file, [...targets].sort())
+   }
+   return { files, adj }
+}
+
+/**
+ * the transitive import closure of `entries`, entries included, WITHOUT
+ * crawling the repo: files are read only as the walk reaches them.
+ *
+ * This is what puts a unit's own code in its cache key. A check that imports a
+ * shared helper carries that helper's identity, so fixing the helper moves the
+ * check's key. An entry that does not exist is dropped: the caller already
+ * knows a missing declared path makes a unit uncacheable, and a throw here
+ * would turn a stale declaration into a dead gate.
+ */
+export function importClosure(cfg: RvtConfig, entries: string[]): string[] {
+   const probe = new Map<string, boolean>()
+   const has = (p: string): boolean => {
+      let r = probe.get(p)
+      if (r == null) {
+         r = /\.tsx?$/.test(p) && existsSync(join(cfg.root, p))
+         probe.set(p, r)
+      }
+      return r
+   }
+   const seen = new Set<string>()
+   const queue = entries.map((e) => toPosix(e)).filter((e) => has(e))
+   for (const e of queue) seen.add(e)
+   while (queue.length > 0) {
+      const file = queue.shift()!
+      let content: string
+      try {
+         content = readFileSync(join(cfg.root, file), 'utf8')
+      } catch {
+         continue
+      }
+      for (const spec of extractSpecs(content)) {
+         const target = resolveSpec(cfg, file, spec, has)
+         if (target == null || seen.has(target)) continue
+         seen.add(target)
+         queue.push(target)
+      }
+   }
+   return [...seen].sort()
+}

package/src/ts/tsconfig-projects.ts

@@ -0,0 +1,101 @@
+// which tsconfig files a typecheck must actually visit.
+//
+// `tsc --noEmit -p <solution>` on a solution-style config (`files: []` plus
+// `references`) compiles ZERO files and exits 0. The gate then prints
+// `ok: typecheck` while a type error sits in src, which is the single worst
+// output this repo can produce: an unmeasured green nobody can tell from a
+// measured one. tsc will not warn about it, so the caller has to resolve the
+// leaves itself and refuse when there are none.
+import { existsSync, readFileSync, statSync } from 'fs'
+import { dirname, isAbsolute, join, resolve } from 'path'
+import { parseJsonc } from 'rvlib-shipkit/src/ts/config.ts'
+
+export type TypecheckProjects = {
+    /** absolute paths, in declaration order, of the configs that compile files */
+    projects: string[]
+    /** nothing would be compiled: the check would pass without checking */
+    vacuous: boolean
+    /** references pointing at a path that does not exist, verbatim as declared */
+    missing: string[]
+}
+
+type RawConfig = {
+    files?: unknown
+    include?: unknown
+    references?: { path?: unknown }[]
+}
+
+/** a reference may name a directory, a config file, or a dir with no config */
+function configPathFor(base: string, declared: string): string | null {
+    const p = isAbsolute(declared) ? declared : resolve(base, declared)
+    if (!existsSync(p)) return null
+    try { if (statSync(p).isDirectory()) return existsSync(join(p, 'tsconfig.json')) ? join(p, 'tsconfig.json') : null }
+    catch { return null }
+    return p
+}
+
+/**
+ * whether tsc would compile anything for THIS config, ignoring its references.
+ *
+ * tsc's rule, and every branch here is a shape found in the field:
+ * - `files` non-empty, or `include` non-empty: compiles those
+ * - neither key present: the default `include` is `**\/*`, so it compiles the
+ *   whole directory tree, which is why a bare `{ references: [...] }` is NOT
+ *   a solution config
+ * - `files: []` with no `include`: the solution-style marker, compiles nothing
+ * - `include: []`: compiles nothing whatever `files` says, unless `files` lists
+ *   something
+ */
+function compilesOwnFiles(cfg: RawConfig): boolean {
+    const files = Array.isArray(cfg.files) ? cfg.files : null
+    const include = Array.isArray(cfg.include) ? cfg.include : null
+    if (files != null && files.length > 0) return true
+    if (include != null) return include.length > 0
+    return files == null
+}
+
+function read(path: string): RawConfig {
+    let text: string
+    try { text = readFileSync(path, 'utf8') }
+    catch (e) { throw new Error(`tsconfig unreadable at ${path}: ${String(e).slice(0, 120)}`) }
+    try { return (parseJsonc(text) ?? {}) as RawConfig }
+    catch (e) { throw new Error(`tsconfig unparseable at ${path}: ${String(e).slice(0, 120)}`) }
+}
+
+/**
+ * Walk `references` to the leaves. A leaf that declares `files: []` with no
+ * `include` compiles nothing and is dropped, so a solution whose every leaf is
+ * empty comes back `vacuous` rather than as a command that passes for free.
+ */
+export function resolveTypecheckProjects(tsconfigPath: string): TypecheckProjects {
+    const start = resolve(tsconfigPath)
+    const projects: string[] = []
+    const missing: string[] = []
+    // a reference loop is legal to WRITE and would otherwise recurse forever
+    const seen = new Set<string>()
+
+    const visit = (path: string): void => {
+        if (seen.has(path)) return
+        seen.add(path)
+        const cfg = read(path)
+        // references are checked FIRST so the list reads dependencies before
+        // dependents, the order `tsc -b` would build in
+        for (const r of Array.isArray(cfg.references) ? cfg.references : []) {
+            const declared = typeof r?.path === 'string' ? r.path : null
+            if (declared == null) continue
+            const next = configPathFor(dirname(path), declared)
+            if (next == null) missing.push(declared)
+            else visit(next)
+        }
+        // `references` does NOT suppress a config's own inputs: only an empty
+        // `files` with no `include` does, and that is what makes a config
+        // solution-style. Skipping a referencing config outright is how the
+        // first version of this file reintroduced the false green it exists to
+        // kill, on `{ include: ['src'], references: [...] }`, which is the
+        // ordinary monorepo package shape
+        if (compilesOwnFiles(cfg)) projects.push(path)
+    }
+
+    visit(start)
+    return { projects, vacuous: projects.length === 0, missing }
+}

package/src/ts/typecheck-cli.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env bun
+// the typecheck floor for a repo that has no typecheck script, as one small
+// binary the gate spawns, for the same reason source-graph-cli.ts exists: a
+// tool the gate REQUIRES must not be a published version behind the repo it
+// gates.
+//
+// One tsc run per project, sequential, output streamed straight through so the
+// task log and its last-line summary behave like any other subprocess task. It
+// runs EVERY project rather than stopping at the first red, because a caller
+// who fixes the one error tsc showed and re-runs into a second one has been
+// told the truth twice and believed it once.
+import { resolveTypecheckProjects } from 'rvlib-shipkit/src/ts/tsconfig-projects.ts'
+
+export function typecheckCli(argv: string[]): number {
+    const [tsc, tsconfig] = argv
+    if (tsc == null || tsconfig == null) {
+        console.log('usage: typecheck <tsc-path> <tsconfig-path>')
+        return 2
+    }
+    let resolved: ReturnType<typeof resolveTypecheckProjects>
+    try { resolved = resolveTypecheckProjects(tsconfig) }
+    catch (e) { console.log(`FAIL: ${String((e as Error)?.message ?? e)}`); return 2 }
+
+    // a reference pointing nowhere means whatever it covered is NOT being
+    // checked, which is a coverage hole wearing a green
+    for (const m of resolved.missing)
+        console.log(`FAIL: ${tsconfig} references '${m}', which does not exist, so whatever that project covered is unchecked`)
+    if (resolved.vacuous)
+        console.log(`FAIL: ${tsconfig} compiles no files of its own and reaches no project that does, so a typecheck over it proves nothing`)
+
+    let worst = 0
+    for (const p of resolved.projects) {
+        const r = Bun.spawnSync([tsc, '--noEmit', '-p', p], { stdout: 'inherit', stderr: 'inherit' })
+        if (r.exitCode !== 0) {
+            console.log(`FAIL: ${p}`)
+            worst = r.exitCode ?? 1
+        }
+    }
+    // a pass that does not say what it checked is the shape this file exists to
+    // remove, so it always names the projects
+    if (worst === 0 && resolved.missing.length === 0 && !resolved.vacuous)
+        console.log(`ok: ${resolved.projects.length} project(s) checked: ${resolved.projects.join(', ')}`)
+    return worst !== 0 ? worst : resolved.missing.length > 0 || resolved.vacuous ? 2 : 0
+}
+
+if (import.meta.main) process.exit(typecheckCli(process.argv.slice(2)))