rvlib-shipkit 0.31.0 → 0.32.0

package/src/core/floor.ts

@@ -0,0 +1,82 @@
+// resolveFloor — which task fills each floor slot (lint, typecheck, test,
+// imports:check, cycles) and, when nothing can, the reason it stays empty.
+//
+// Its own module rather than a section of repo-config so a RULE can ask what
+// the gate would actually run: repo-config imports the rule registry, so a
+// rule importing repo-config back is a cycle that dies at module init.
+// RepoConfig arrives as a TYPE only, which is erased.
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+import { rawName, routesToShipkit } from './canonical-scripts.ts'
+import type { TaskDef } from './task-runner.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
+
+export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (shipkit)' | 'built-in (tsc)'
+export type FloorResolution = {
+    tasks: TaskDef[]
+    /** slots disabled by `defaults: { x: false }` — always printed */
+    disabled: string[]
+    /** slots nothing could fill — always printed, never silent */
+    unfilled: { id: string; reason: string }[]
+    /** where each registered slot came from (init prints this) */
+    sources: Record<string, FloorSource>
+}
+
+// zero-config floor (O6): with no script, imports:check/cycles resolve to
+// shipkit's own rvlib-ts-tools dep, typecheck to the repo's tsc. Returns
+// the task, or the reason the slot stays empty.
+function builtinFloorTask(id: string, root: string): { task: TaskDef; source: FloorSource } | string {
+    if (id === 'imports:check' || id === 'cycles') {
+        let cli: string
+        // shipkit's OWN module, resolved from this file: no dependency to be
+        // out of date with, and no resolution that can fail in a consumer tree
+        cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/source-graph-cli.ts'))
+        return {
+            task: { id, cmd: id === 'cycles' ? ['bun', cli, 'cycles'] : ['bun', cli, 'imports', '--check'] },
+            source: 'built-in (shipkit)',
+        }
+    }
+    if (id === 'typecheck') {
+        if (!existsSync(join(root, 'tsconfig.json'))) return `no 'typecheck' script and no tsconfig.json`
+        const local = join(root, 'node_modules/.bin/tsc')
+        const tsc = existsSync(local) ? local : Bun.which('tsc')
+        if (tsc == null) return `no 'typecheck' script and tsc not found — add typescript or a typecheck script`
+        return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
+    }
+    return `no package.json '${id}' script`
+}
+
+export function resolveFloor(c: RepoConfig, root: string): FloorResolution {
+    const pkgPath = join(root, 'package.json')
+    let scripts: Record<string, string> = {}
+    if (existsSync(pkgPath)) {
+        // unparseable package.json must NOT silently empty the floor — the
+        // gate would run only `contracts` and report green
+        try { scripts = (JSON.parse(readFileSync(pkgPath, 'utf8')) as { scripts?: Record<string, string> }).scripts ?? {} }
+        catch (e) { throw new Error(`package.json unparseable — floor tasks cannot register: ${String(e).slice(0, 120)}`) }
+    }
+    const tasks: TaskDef[] = []
+    const disabled: string[] = []
+    const unfilled: { id: string; reason: string }[] = []
+    const sources: Record<string, FloorSource> = {}
+    for (const id of FLOOR_IDS) {
+        const override = c.defaults?.[id]
+        if (override === false) { disabled.push(id); continue }
+        if (override != null) { tasks.push(override); sources[id] = 'repo.config override'; continue }
+        // ONE WAY IN: `<id>` routes to `shipkit ci --only <id>`, so the TOOL
+        // body lives at `<id>:raw` and that is what the gate runs. Running the
+        // routed script here would spawn the gate from inside itself, forever
+        const raw = scripts[rawName(id)]
+        if (raw != null) { tasks.push({ id, cmd: ['bun', 'run', rawName(id)] }); sources[id] = 'package.json script'; continue }
+        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push({ id, cmd: ['bun', 'run', id] }); sources[id] = 'package.json script'; continue }
+        const b = builtinFloorTask(id, root)
+        // a routed script with nothing behind it measures NOTHING, and the
+        // reason must say that rather than `no '<id>' script`, which is false
+        if (typeof b === 'string') unfilled.push({ id, reason: scripts[id] != null ? `script '${id}' routes to shipkit and there is no '${rawName(id)}' body to run` : b })
+        else { tasks.push(b.task); sources[id] = b.source }
+    }
+    return { tasks, disabled, unfilled, sources }
+}

package/src/core/motherhome.ts

@@ -10,7 +10,7 @@
 // path no longer exists are pruned on every write. Churn control: a row
 // rewrites only when its DATA changes or its last-seen day is older than
 // 7 days. Never fails the calling command.
-import { existsSync, readFileSync } from 'fs'
+import { existsSync, readFileSync, statSync } from 'fs'
 import { homedir } from 'os'
 import { join, resolve } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
@@ -46,6 +46,13 @@ function consumptionMode(root: string): string {
     } catch { return '?' }
 }
 
+/** a LINKED worktree, where `.git` is a file pointing at the main checkout
+ *  rather than a directory. Cheap on purpose: this runs on every check pass in
+ *  every repo, and spawning git to learn it would cost more than the write. */
+function isLinkedWorktree(root: string): boolean {
+    try { return statSync(join(root, '.git')).isFile() } catch { return false }
+}
+
 export type MotherhomeOutcome = { wrote: boolean; note?: string }
 
 export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {
@@ -57,6 +64,12 @@ export function reportToMotherhome(root: string, config: RepoConfig, today: stri
         if (!base.startsWith('/')) return { wrote: false }
         const page = join(base, 'build/shipkit/local-projects.md')
         if (!existsSync(page)) return { wrote: false }
+        // a gate run inside a linked worktree must not write the MAIN
+        // checkout's tracked page: the row it would add describes a temporary
+        // side checkout, and the write lands as unexplained dirt in a tree
+        // somebody else is working in. The worktree's own runs are covered
+        // when its branch merges.
+        if (isLinkedWorktree(root)) return { wrote: false, note: `motherhome: skipped (${config.name} is a linked worktree — its row belongs to the main checkout)` }
 
         const mode = consumptionMode(root)
         // source-consumed code is not the published release its version

package/src/core/run-check.ts

@@ -15,6 +15,8 @@ import { RULES } from '../rules/rule-registry.ts'
 import { runRuleLint } from '../rules/rule.ts'
 import { formatLine, parseWireOutput, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
+import { SHARE_ENV } from '../release/releases-share.ts'
+import { rmSync } from 'fs'
 
 // orchestrator cache for checks WITHOUT their own suite — short on purpose:
 // this layer only absorbs back-to-back runs, real TTLs live in the checks
@@ -42,6 +44,21 @@ export type CheckOpts = {
      *  spends a third-party API call per publish. Undeclared checks are still
      *  collected, because an unclassified check stays fatal. */
     onlyBlocking?: boolean
+    /** the caller narrowed the run to these ids (`ci --only`). Empty or absent
+     *  means everything. A `--only` that narrowed TASKS while every check still
+     *  ran made the flag actively harmful: `ci --only cycles`, a 0.03s task,
+     *  probed every third-party service the repo knows about. One flag, one
+     *  meaning, across all three surfaces. */
+    only?: string[]
+}
+
+/** does this rule or check answer to one of the `--only` ids? Matched against
+ *  every name the surface is known by (a rule's id AND its title, a discovered
+ *  check's name AND its path), because the id an operator types is whichever
+ *  one they last saw on the wire. */
+export function matchesOnly(only: string[] | undefined, ...names: string[]): boolean {
+    if (only == null || only.length === 0) return true
+    return only.some((want) => names.some((n) => n.toLowerCase() === want.toLowerCase()))
 }
 
 export type CheckRun = {
@@ -85,26 +102,41 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
         t.warned = true
     }
     for (const rule of [...RULES, ...(c.rules ?? [])]) {
+        if (!matchesOnly(o.only, rule.id, rule.title)) continue
         if (o.onlyBlocking === true && !rule.blocking) continue
         suite.addCheck({
+            blocking: rule.blocking,
             name: rule.title,
             remainValidFor: rule.ttl,
             cacheExtra: rule.cacheKey != null ? () => rule.cacheKey!({ root, config: c }) : undefined,
             logic: async (t) => { await runRuleLint(rule, t, { root, config: c }); demote(t, rule.blocking, rule.title) },
         })
     }
+    // ONE release survey for the whole run: five discovered checks call
+    // collectReports, each in its own subprocess, and the survey is ~4s of
+    // network. The path is per RUN and never reused across runs, so nothing
+    // here can serve a stale answer to a later gate (releases-share.ts).
+    // a caller that already opened one (runCi, which starts the survey next to
+    // the tasks) owns it, cleanup included; otherwise this run owns its own
+    const inherited = process.env[SHARE_ENV]
+    const sharePath = inherited != null && inherited !== '' ? inherited : join(root, 'tmp/shipkit-ci', `releases-${process.pid}-${Date.now()}.json`)
     const childEnv: Record<string, string | undefined> = {
         ...process.env,
+        [SHARE_ENV]: sharePath,
         ...(o.fresh === true ? { SHIPKIT_FRESH: '1', RV_CHECK_FRESH: '1' } : {}),
     }
     for (const d of discoverChecks(root)) {
         const rel = relative(root, d.path)
         // file wins, then the repo default, then nothing: an unclassified
         // check is an error, never a guess
+        if (!matchesOnly(o.only, d.name, rel)) continue
         const blocking = d.blocking ?? c.checkDefaults?.blocking
         if (blocking == null) undeclared.push(rel)
         if (o.onlyBlocking === true && blocking !== true) continue
         suite.addCheck({
+            // a check about the WORLD may remember a measured negative; one
+            // about this repo never does (check-suite.ts, the rule)
+            blocking: blocking ?? true,
             name: d.name,
             remainValidFor: d.selfCached ? undefined : DISCOVERED_TTL,
             logic: async (t) => {
@@ -121,6 +153,8 @@ export async function collectChecks(root: string, o: CheckOpts = {}): Promise<Ch
         })
     }
     const r = await suite.execute()
+    // the survey dies with the run that made it, and only the run that made it
+    if (inherited == null || inherited === '') for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
     if (prevFresh == null) delete process.env.SHIPKIT_FRESH; else process.env.SHIPKIT_FRESH = prevFresh
     if (prevFrozen == null) delete process.env.SHIPKIT_FROZEN; else process.env.SHIPKIT_FROZEN = prevFrozen
     // frozen = a release-shaped run: reporting would re-dirty the tree the

package/src/core/run-ci.ts

@@ -13,6 +13,11 @@ import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
 import { runTasks, type TaskResult } from './task-runner.ts'
 import { writeStatus } from './write-status.ts'
+import { rmSync } from 'fs'
+
+import { SHARE_ENV } from '../release/releases-share.ts'
+import { collectReports } from '../release/run-releases.ts'
+import { withContractsScope } from '../contracts/contracts-once.ts'
 
 export type CiOpts = {
     bail?: boolean
@@ -54,8 +59,22 @@ export type CiOpts = {
      *  loads of repo.config.ts can disagree, and the release path classifies
      *  rule-vs-probe severity from the config it holds. */
     config?: RepoConfig
+    /** which test tier the run asks the repo's suite for. 'quick' is the
+     *  working default; 'full' sets SHIPKIT_TEST_FULL=1 for every task, which
+     *  a suite reads to include the slow, real-world tiers it otherwise skips.
+     *  The release path always asks for 'full': a version published behind a
+     *  partial suite is a green nobody measured. Default reads the env var, so
+     *  `SHIPKIT_TEST_FULL=1 shipkit ci` works with no flag. */
+    tests?: TestTier
 }
 
+export type TestTier = 'quick' | 'full'
+
+/** the env var a repo's own suite reads to widen itself. Named here because
+ *  the gate is what sets it, and a suite that invents its own name is a tier
+ *  the release path cannot reach. */
+export const FULL_TESTS_ENV = 'SHIPKIT_TEST_FULL'
+
 /** what STATUS.md may claim about this run. `--with` ADDS a task, so it stays
  *  the full gate; `--only`, `--skip` and skipChecks each remove coverage, and
  *  a narrowed run that stamps the full gate's verdict is a green nobody
@@ -71,6 +90,12 @@ function ciScope(o: CiOpts): { command: string; fullGate: boolean } {
 }
 
 export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
+    // ONE gate run: the `contracts` task evaluates, rule SK002 reads what it
+    // computed instead of evaluating a second time (contracts-once.ts)
+    return await withContractsScope(() => runCiInScope(root, o))
+}
+
+async function runCiInScope(root: string, o: CiOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const collected: string[] = []
     const sink = (l: string): void => { collected.push(l); print(l) }
@@ -83,12 +108,36 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     const all = allTasks(c, root)
     const { disabled, unfilled } = all
     const skipIds = new Set(o.skipTaskIds ?? [])
-    const tasks = all.tasks.filter((t) => !skipIds.has(t.id))
+    const tier: TestTier = o.tests ?? (process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick')
+    const tasks = all.tasks
+        .filter((t) => !skipIds.has(t.id))
+        // the whole run carries the flag rather than one task id: a repo names
+        // its suites what it likes (`test`, `test:libs`, a prepublish script),
+        // and a gate that guesses which one is the tests will miss one
+        .map((t) => (tier === 'full' ? { ...t, env: { ...t.env, [FULL_TESTS_ENV]: '1' } } : t))
+    // announced BEFORE the run, so a log that died mid-way still says which
+    // tier it was asking for
+    sink(tier === 'full'
+        ? `ok: test tier FULL — every suite, the slow ones included (${FULL_TESTS_ENV}=1)`
+        : `skip: full test tier (quick run — \`shipkit ci --full\` or ${FULL_TESTS_ENV}=1 includes it)`)
     for (const t of all.tasks) if (skipIds.has(t.id)) sink(`skip: ${t.id} (not part of this release, the unit's own gate covers it)`)
     for (const d of disabled) sink(`skip: ${d} (skipped-by-config)`)
     // a floor slot nothing could fill is VISIBLE — a thin gate must never
     // look like a full one (the fresh-repo floor gap)
     for (const u of unfilled) sink(`skip: ${u.id} (${u.reason})`)
+    // the release survey is ~4s of network that five discovered checks need
+    // and the TASKS do not. Started HERE it overlaps lint/typecheck/test and
+    // costs the run nothing; started inside the first check that wants it, it
+    // is 4s nobody can overlap. Failures are the checks' to report, not this
+    // line's: a survey nobody can run just means the checks do it themselves.
+    const sharePath = join(root, 'tmp/shipkit-ci', `releases-${process.pid}-${Date.now()}.json`)
+    const priorShare = process.env[SHARE_ENV]
+    process.env[SHARE_ENV] = sharePath
+    // a NARROWED run pre-warms nothing: `--only cycles` asks one question, and
+    // paying a 4s network survey to answer it is the same bug --only was
+    // fixed for
+    const willRunChecks = o.skipChecks !== true && (o.onlyIds ?? []).length === 0
+    const survey = willRunChecks ? collectReports(root, c).catch(() => null) : null
     const summary = await runTasks({
         tasks,
         logDir: c.logDir ?? join(root, 'tmp/shipkit-ci'),
@@ -100,11 +149,23 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         print: sink,
         onTaskFinish: o.onTaskFinish,
     })
+    // what the suite ACTUALLY ran, from its own summary line. A flag that was
+    // set proves the intent; the count proves the tests
+    const ranTests = summary.results
+        .map((r) => /Ran (\d+) tests?/.exec(r.lastLine ?? '')?.[1])
+        .find((n) => n != null)
+    if (ranTests != null) sink(`ok: test tier ${tier}: ${ranTests} tests ran`)
     // the checks, in the SAME command. there is no second surface: a check
     // declares whether it blocks, and that is the only question about it.
+    // a narrowed run says what it did NOT look at: a green that only ever
+    // asked one question must not read like the full gate
+    if ((o.onlyIds ?? []).length > 0 && o.skipChecks !== true) sink(`skip: checks not named by --only (${(o.onlyIds ?? []).join(', ')})`)
+    if (survey != null) await survey
     const checks = o.skipChecks === true
         ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks })
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, onlyBlocking: o.onlyBlockingChecks, only: o.onlyIds })
+    if (priorShare == null) delete process.env[SHARE_ENV]; else process.env[SHARE_ENV] = priorShare
+    for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
     for (const u of checks.undeclared) {

package/src/core/run-fixers.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { runFix } from '../rules/run-fix.ts'
+import { routesToShipkit } from './canonical-scripts.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
@@ -60,8 +61,12 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
         return true
     }
 
-    const fmtName = FMT_SCRIPTS.find((n) => scripts[n] != null)
+    // `fmt` is the one slot the fix pass invokes BY SCRIPT, so it is the one
+    // name ONE WAY IN deliberately leaves raw: a routed body here would make
+    // the fixer spawn the gate that spawns the fixer
+    const fmtName = FMT_SCRIPTS.find((n) => scripts[n] != null && !routesToShipkit(scripts[n]!))
     if (fmtName != null) slots.push({ id: 'fmt', cmd: ['bun', 'run', fmtName], source: 'package.json script' })
+    else if (FMT_SCRIPTS.some((n) => scripts[n] != null)) unfilled.push({ id: 'fmt', reason: `the 'fmt' script routes back to shipkit — the fix pass runs it, so it holds the formatter itself` })
     else unfilled.push({ id: 'fmt', reason: `no 'fmt' or 'format' script — formatting stays a manual step` })
 
     if (offByConfig('imports:fix')) { /* the repo said no, in the one place that governs both directions */ }

package/src/ledger/toolchain-identity.ts

@@ -0,0 +1,134 @@
+// WHAT PROGRAM IS ABOUT TO RUN, as one hash.
+//
+// A cache key built from the repo's git tree answers "what source is being
+// gated". It cannot answer "what is doing the gating", and those two already
+// have different answers inside a single checkout. Three facts, each measured
+// rather than argued:
+//
+//   1. `node_modules/` is gitignored, so no git-derived key can ever see what
+//      is installed. `bun.lock` is tracked, which is not the same thing.
+//   2. Byte-identical `bun.lock`, different installed program: a repo and a
+//      linked worktree of it were found carrying different top-level packages,
+//      one of them a runtime dependency of a package both declared. A lockfile
+//      hash calls those the same program.
+//   3. The same lockfile can hold a different VERSION on disk, and the cheap
+//      proxies miss it: two releases of one package were found with
+//      package.json files of exactly the same byte length, so only the parsed
+//      `version` separates them.
+//
+// So the key has three parts: the runtime, the gate binary, and what is
+// actually installed.
+//
+// THE ONE DELIBERATE MISS: a human hand-editing a file inside `node_modules`
+// is accepted, not caught. Catching it means content-hashing the whole tree,
+// measured at 0.9s on a 6,700-file tree and 5.3s on a 33,000-file one, against
+// ~2ms and ~18ms for this key. That is 350x to 470x, which would make the
+// cache slower than the gate it caches. No tool produces that state; a human
+// debugging on purpose can delete the ledger.
+import { createHash } from 'crypto'
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'fs'
+import { isAbsolute, join, relative, resolve } from 'path'
+
+export type Toolchain = {
+    /** the identity, 16 hex chars, stable for identical programs */
+    id: string
+    /** non-empty means DO NOT CACHE this run: something in the toolchain is
+     *  neither in the repo's git tree nor pinned by a version string, so no
+     *  key can describe it. Each entry says which package and why. */
+    uncacheable: string[]
+}
+
+/** does this path live inside the repo being gated? */
+const inRepo = (repoRoot: string, p: string): boolean => {
+    const r = relative(repoRoot, p)
+    return r !== '' && !r.startsWith('..') && !isAbsolute(r)
+}
+
+/** every top-level package name, scopes expanded, sorted */
+function installedNames(nm: string): string[] {
+    const names: string[] = []
+    for (const e of readdirSync(nm, { withFileTypes: true })) {
+        if (e.name.startsWith('.')) continue
+        if (e.name.startsWith('@')) {
+            for (const n of readdirSync(join(nm, e.name))) if (!n.startsWith('.')) names.push(`${e.name}/${n}`)
+        } else names.push(e.name)
+    }
+    return names.sort()
+}
+
+/** the gate binary's own source, content-hashed. Only reached when the cli
+ *  lives OUTSIDE the repo, where the git tree key cannot see it. */
+function hashCliTree(h: ReturnType<typeof createHash>, cli: string): void {
+    const srcRoot = resolve(cli, '..')
+    const files: string[] = []
+    const walk = (d: string): void => {
+        for (const e of readdirSync(d, { withFileTypes: true })) {
+            if (e.name === 'node_modules' || e.name.startsWith('.')) continue
+            const p = join(d, e.name)
+            if (e.isDirectory()) walk(p)
+            else files.push(p)
+        }
+    }
+    walk(srcRoot)
+    files.sort()
+    for (const f of files) h.update(readFileSync(f))
+    h.update(`clifiles=${files.length}\n`)
+}
+
+/**
+ * the identity of the program about to run, for `repoRoot`, driven by `cliEntry`.
+ *
+ * Deterministic: identical trees produce identical ids, and a `touch` that
+ * moves an mtime without changing content produces no miss.
+ */
+export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain {
+    const h = createHash('sha256')
+    const uncacheable: string[] = []
+    // BOTH sides resolved, or the comparison is wrong on macOS: /var is a
+    // symlink to /private/var, so an in-repo cli under a resolved path reads
+    // as outside an unresolved root. That mistake is silent and expensive: it
+    // content-hashes the gate binary on every single run, and folds absolute
+    // paths into the id, which is what would stop two worktrees agreeing.
+    const root = ((): string => { try { return realpathSync(repoRoot) } catch { return resolve(repoRoot) } })()
+
+    // the runtime. Free, and a bun upgrade genuinely changes behaviour
+    h.update(`bun=${Bun.version}\n`)
+
+    // the gate binary. In-repo, the git tree key already covers every byte of
+    // it, so the literal is enough and the walk is skipped
+    const cli = realpathSync(cliEntry)
+    const cliInRepo = inRepo(root, cli)
+    h.update(`cli=${cliInRepo ? 'in-repo' : cli}\n`)
+    if (!cliInRepo) hashCliTree(h, cli)
+
+    // what is installed. The lockfile states the intent; the tree states the fact
+    const lock = join(root, 'bun.lock')
+    h.update(`lock=${existsSync(lock) ? createHash('sha256').update(readFileSync(lock)).digest('hex') : 'none'}\n`)
+    const nm = join(root, 'node_modules')
+    if (!existsSync(nm)) {
+        // a worktree nobody installed is a REAL difference, not a missing input
+        h.update('nm=absent\n')
+        return { id: h.digest('hex').slice(0, 16), uncacheable }
+    }
+    const names = installedNames(nm)
+    for (const n of names) {
+        const dir = join(nm, n)
+        let link = ''
+        try {
+            if (lstatSync(dir).isSymbolicLink()) {
+                const target = realpathSync(dir)
+                link = `->${target}`
+                // a `bun link`ed package is live source under someone else's
+                // edit: its content is in neither this repo's git tree nor its
+                // version string, so nothing here can describe it
+                if (!inRepo(root, target)) uncacheable.push(`${n} links outside the repo (${target})`)
+            }
+        } catch {}
+        let version = 'MISSING'
+        try { version = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }).version ?? '?' } catch {}
+        h.update(`${n}@${version}${link}\n`)
+    }
+    // the count catches a removal that leaves every survivor identical
+    h.update(`n=${names.length}\n`)
+    return { id: h.digest('hex').slice(0, 16), uncacheable }
+}