rvlib-shipkit 1.5.0 → 1.7.0

package/src/home/insights.ts

@@ -0,0 +1,90 @@
+// the insights page's data: every package.json a scope of repos tracks, read
+// and turned into boxes (insights-shape.ts). Two scopes: the house repos, or
+// every folder of ~/dev with a package.json or a .git, so a package used in an
+// unwired repo can still be found and reused.
+//
+// the one constraint a reader breaks first: this runs only when the page or
+// `sk insights` asks (no tick), and an answer is kept per scope for
+// INSIGHTS_TTL_MS, so a page left open never walks ~/dev twice a minute.
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { gitBin } from '../core/git-bin.ts'
+import { boxesOf, type InsightsAnswer, type Manifest, type Scope } from './insights-shape.ts'
+
+export * from './insights-shape.ts'
+
+export const INSIGHTS_TTL_MS = 5 * 60_000
+export const INSIGHTS_CONCURRENCY = 12
+
+export type InsightRepo = { name: string; path: string }
+
+/** every folder of ~/dev that holds a package.json or a .git, by name */
+export function devRepos(userHome: string = homedir()): InsightRepo[] {
+    const root = join(userHome, 'dev')
+    let names: string[] = []
+    try {
+        names = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name)
+    } catch {
+        return []
+    }
+    return names
+        .map((name) => ({ name, path: join(root, name) }))
+        .filter((r) => existsSync(join(r.path, 'package.json')) || existsSync(join(r.path, '.git')))
+        .sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** the package.json paths a repo tracks; the root one alone outside git */
+async function manifestPaths(dir: string): Promise<string[]> {
+    if (!existsSync(join(dir, '.git'))) return existsSync(join(dir, 'package.json')) ? ['package.json'] : []
+    const p = Bun.spawn([gitBin(), 'ls-files', '-z', '--', 'package.json', '**/package.json'], { cwd: dir, stdout: 'pipe', stderr: 'ignore', env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } })
+    const [out, code] = await Promise.all([new Response(p.stdout).text(), p.exited])
+    if (code !== 0) return existsSync(join(dir, 'package.json')) ? ['package.json'] : []
+    return out.split('\0').filter(Boolean)
+}
+
+/** one repo's manifests, read; a file that does not parse is an error line */
+export async function repoManifests(r: InsightRepo): Promise<{ manifests: Manifest[]; errors: string[] }> {
+    const manifests: Manifest[] = []
+    const errors: string[] = []
+    for (const rel of await manifestPaths(r.path)) {
+        const where = rel === 'package.json' ? '' : rel.slice(0, -'/package.json'.length)
+        try {
+            manifests.push({ repo: r.name, where, json: JSON.parse(readFileSync(join(r.path, rel), 'utf8')) })
+        } catch (e) {
+            // a deleted but still tracked file is no error, only nothing to read
+            if ((e as NodeJS.ErrnoException).code !== 'ENOENT') errors.push(`${r.name}/${rel}: ${(e as Error).message}`)
+        }
+    }
+    return { manifests, errors }
+}
+
+/** THE computation: the daemon's route and `sk insights` both call it */
+export async function insightsOf(repos: InsightRepo[], scope: Scope, now = Date.now()): Promise<InsightsAnswer> {
+    const t0 = performance.now()
+    const all: { manifests: Manifest[]; errors: string[] }[] = []
+    for (let i = 0; i < repos.length; i += INSIGHTS_CONCURRENCY) all.push(...(await Promise.all(repos.slice(i, i + INSIGHTS_CONCURRENCY).map(repoManifests))))
+    const manifests = all.flatMap((a) => a.manifests)
+    return { now, scope, repos: repos.length, files: manifests.length, boxes: boxesOf(manifests), errors: all.flatMap((a) => a.errors), ms: Math.round(performance.now() - t0) }
+}
+
+/** one answer per scope, shared for INSIGHTS_TTL_MS; `fresh` always reads */
+export class InsightsCache {
+    private kept = new Map<Scope, InsightsAnswer>()
+    private running = new Map<Scope, Promise<InsightsAnswer>>()
+
+    constructor(private o: { ttlMs?: number; now?: () => number } = {}) {}
+
+    get(scope: Scope, repos: () => InsightRepo[], o: { fresh?: boolean } = {}): Promise<InsightsAnswer> {
+        const now = (this.o.now ?? Date.now)()
+        const k = this.kept.get(scope)
+        if (k != null && o.fresh !== true && now - k.now < (this.o.ttlMs ?? INSIGHTS_TTL_MS)) return Promise.resolve(k)
+        const going = this.running.get(scope)
+        if (going != null) return going
+        const p = insightsOf(repos(), scope, now)
+            .then((a) => { this.kept.set(scope, a); return a })
+            .finally(() => this.running.delete(scope))
+        this.running.set(scope, p)
+        return p
+    }
+}

package/src/home/open-app.ts

@@ -13,10 +13,10 @@ if (import.meta.main) {
     try {
         if (first === '--process' && second != null) {
             const d = JSON.parse(second) as WrapperOf
-            const cmd = openProcessApp(d, { version: LIB_VERSION, warn })
+            const cmd = await openProcessApp(d, { version: LIB_VERSION, warn })
             console.log(`shipkit: opened ${d.id} as its own app: ${cmd.join(' ')}`)
         } else if (first != null && first !== '--process') {
-            const cmd = openWindow(first, { version: LIB_VERSION, warn })
+            const cmd = await openWindow(first, { version: LIB_VERSION, warn })
             console.log(`shipkit: opened ${first} as an app window: ${cmd.join(' ')}`)
         } else {
             console.error('usage: bun open-app.ts <url> | --process <json>')

package/src/home/serve-web.ts

@@ -14,7 +14,7 @@ import { hubBase } from './home-paths.ts'
 /** the page routes: ONE app for the overview, the plan, and the hub page of
  *  each known repo, which moves between them in place (home-st.ts) */
 export function pageRoutes<T>(names: string[], page: T): Record<string, T> {
-    const out: Record<string, T> = { '/': page, '/planned': page, '/activity': page, '/archived': page }
+    const out: Record<string, T> = { '/': page, '/planned': page, '/activity': page, '/archived': page, '/insights': page }
     for (const n of names) out[`${hubBase(n)}/`] = page
     return out
 }
@@ -51,8 +51,8 @@ export const REPO_ANSWER_MS = 30_000
 export const LIST_EVERY_MS = 30_000
 export const LIST_RETRY_MS = 1_000
 
-/** the home answers that can wait on git: the activity page's first read of a window, and a repo's git page */
-export const readsGit = (path: string): boolean => path === '/api/home/activity.json' || path === '/api/home/git.json'
+/** the home answers that can wait on git: the activity page's first read of a window, a repo's git page, and the insights page's read of every manifest */
+export const readsGit = (path: string): boolean => path === '/api/home/activity.json' || path === '/api/home/git.json' || path === '/api/home/insights.json'
 
 /** a run or a check run streams for minutes, and a silent one is never cut */
 export const streams = (path: string): boolean => /\/api\/(run|check\/run)$/.test(path)

package/src/home/via-hub.ts

@@ -17,6 +17,18 @@ import { daemonUp, daemonUrl, hubBase, WORKER_ENV } from './home-paths.ts'
 import { homeWanted, startHome } from './home-start.ts'
 import { RUN_EXIT, RUN_JOB } from './home-words.ts'
 import { followJob, type FollowOpts } from '../core/job-follow.ts'
+import { TRACE_ENV } from '../trace/tracer.ts'
+import { FRESH_ENV } from '../ledger/store.ts'
+import { LEDGER_ENV } from '../ledger/ledger.ts'
+import { PARALLEL_ENV } from '../core/parallel.ts'
+
+/** the env switches a gate reads, which a terminal may set for one run: the
+ *  job the home starts runs with the daemon's env, so they travel with it */
+export const FORWARDED_ENV = [TRACE_ENV, FRESH_ENV, LEDGER_ENV, PARALLEL_ENV] as const
+
+/** the forwarded switches this env sets */
+export const forwardedEnv = (env: Env = process.env): Record<string, string> =>
+    Object.fromEntries(FORWARDED_ENV.filter((k) => env[k] != null && env[k] !== '').map((k) => [k, env[k]!]))
 
 type Env = Record<string, string | undefined>
 const set = (v: string | undefined): boolean => v != null && v !== ''
@@ -46,10 +58,12 @@ export async function runViaHub(root: string, kind: 'ci' | 'check', opts: Record
     }
     // what the terminal knows and the hub does not: its tier and whether it is a terminal
     const full = process.env.SHIPKIT_TEST_FULL === '1'
+    const env = forwardedEnv()
     const sent = {
         ...opts,
         ...(full ? (kind === 'ci' ? { tests: opts.tests ?? 'full' } : { tier: opts.tier ?? 'full' }) : {}),
         color: process.stdout.isTTY === true && process.env.NO_COLOR == null,
+        ...(Object.keys(env).length > 0 ? { env } : {}),
     }
     // the home waits for a hub still loading before it answers
     const post = (): Promise<Response> => fetch(`${daemonUrl()}${hubBase(name)}/api/run`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind, opts: sent }) })

package/src/home/widgets.ts

@@ -104,12 +104,12 @@ export class Widgets {
     }
 
     /** one render, bounded, its result or its error kept */
-    async render(s: Slot): Promise<void> {
+    async render(s: Slot, force = false): Promise<void> {
         s.busy = true
         let timer: ReturnType<typeof setTimeout> | undefined
         try {
             const html = await Promise.race([
-                Promise.resolve().then(() => s.w.def.render()),
+                Promise.resolve().then(() => s.w.def.render({ force })),
                 new Promise<never>((_, no) => { timer = setTimeout(() => no(new Error(`render took more than ${WIDGET_RENDER_MS / 1000}s`)), WIDGET_RENDER_MS) }),
             ])
             if (typeof html !== 'string') throw new Error(`render returned ${typeof html}, not an html string`)
@@ -123,6 +123,16 @@ export class Widgets {
         }
     }
 
+    /** a reader's refresh: one widget rendered now with force, its view after
+     *  it; null when no widget has that repo and id */
+    async refresh(repo: string, id: string): Promise<WidgetView | null> {
+        const s = this.slots.get(`${repo}/${id}`)
+        if (s == null) return null
+        this.readAt = this.now()
+        await this.render(s, true)
+        return s.view
+    }
+
     /** the last html of each; a read that keeps the clocks running */
     views(): WidgetView[] {
         this.readAt = this.now()

package/src/ledger/db.ts

@@ -26,20 +26,9 @@
 import { Database } from 'bun:sqlite'
 import { existsSync, mkdirSync } from 'fs'
 import { dirname, join } from 'path'
-import { gitRoot } from '../core/git-root.ts'
-import { LAYOUT } from '../core/layout.ts'
 
-/** the one dir everything this repo remembers hangs off.
- *
- *  `--git-common-dir` rather than `--git-dir`: a linked worktree has its own
- *  git dir but shares the common one, and that sharing is safe because every
- *  key component is content or a version string. A tree that is not a git
- *  repo at all still gets one, under `.shipkit/cache/`, because a scaffold in
- *  progress must not crash on it. */
-export function shipkitRoot(root: string): string {
-    const dir = gitRoot(root)?.commonDir
-    return dir == null ? join(root, LAYOUT.cache) : join(dir, 'shipkit')
-}
+import { shipkitRoot } from '../core/git-root.ts'
+export { shipkitRoot }
 
 export const DB_FILE = 'shipkit.sqlite'
 

package/src/ledger/gate-checks.ts

@@ -11,9 +11,11 @@
 // check script, a `*.check.ts` with no check object). The declaration always lives WITH the check, never in a table
 // over here: a table beside the registry is a second source of truth that
 // drifts the first time somebody adds one.
-import { relative, resolve } from 'path'
+import { existsSync } from 'fs'
+import { join, relative, resolve } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
 import { type RepoConfig } from '../repo-config.ts'
+import { auditedExtras, ignoredFor, readAuditReport } from '../core/audit-report.ts'
 import { listRepoFiles, resolveFloor, slotDescription, type FloorResolution } from '../core/floor.ts'
 import { discoverLegacyChecks } from '../core/discover-legacy-checks.ts'
 import { checkFileRunBy } from '../core/legacy-shapes.ts'
@@ -25,7 +27,7 @@ import { FOREVER, ttlMsOf } from '../core/wire.ts'
 import { budgetOf } from '../core/budget.ts'
 import { repoOff, withRepoOff, whenSummary, type WhenDecl } from '../core/when.ts'
 import { cacheText, filesText, NOWHERE, sourced, type CacheDecl, type ResolvedRuns, type Runs } from '../core/runs.ts'
-import type { CheckDecl } from './git-key.ts'
+import { isNamesInput, type CheckDecl } from './git-key.ts'
 import { populationOf } from '../problems/problem-line.ts'
 import { rawAccessInClosure, rawAccessLine } from '../core/raw-access.ts'
 import type { RvtConfig } from '../ts/config.ts'
@@ -290,10 +292,23 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
     // what it likes, and a gate that guesses which one is the tests will miss
     // one.
     const rootTest = rootTestKey(root, c, floor)
+    // a task that declares nothing is keyed on the whole work tree, plus the
+    // gitignored paths it reads. The work tree sees no ignored file, so those
+    // are named: by the config, and by the kept traced audit (SK031), whose
+    // findings join the key of the task that read them before a config write
+    // carries them to other clones. One missing from disk is left out, and
+    // its appearing moves the key
+    const onDisk = (p: string): boolean => existsSync(join(root, isNamesInput(p) ? p.slice(0, -3) : p))
+    const audit = readAuditReport(root)
+    const extrasOf = (id: string): string[] => [...new Set([...ignoredFor(c.ignoredInputs, id), ...auditedExtras(audit, id)])].filter(onDisk).sort()
     for (const raw of [...floor.tasks, ...(c.tasks ?? []).filter((t) => foldedInto.get(t.id) !== t)]) {
         const t: TaskDef = full ? { ...raw, env: { ...raw.env, [FULL_TESTS_ENV]: '1' } } : raw
         const own = t.id === 'test' && floor.tasks.includes(raw) ? rootTest : null
-        const inputs = own?.inputs ?? t.inputs
+        const declared = own?.inputs ?? t.inputs
+        // the declared extras join a declared list too: a list names what the
+        // task reads in the tree, and the audit found these outside it
+        const extras = extrasOf(t.id)
+        const inputs = declared == null && t.ttl == null && t.never == null && t.cmd != null ? ['.', ...extras] : declared == null ? declared : [...declared, ...extras]
         const kind = floor.tasks.includes(raw) ? 'a floor slot' : 'a repo.config.ts task'
         const runs = withRepoOff(derivedRuns({ gate: t.optIn !== true, build: true, inputs, ttl: t.ttl, kind, repair: false }), repoOff(c, t.id))
         const row: CheckRow = {
@@ -382,6 +397,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
                 id: u.id,
                 inputs: cache.inputs,
                 code: u.rel == null ? undefined : [u.rel],
+                // a built-in's code is the toolkit's: keyed on its own closure
+                // there, never on the toolkit as a whole
+                libCode: u.rel == null ? [u.path] : undefined,
                 ttl: cache.ttl,
                 never: cache.never,
                 argv: u.def.cmd,

package/src/ledger/git-key.ts

@@ -6,10 +6,10 @@
 // FOUR POPULATIONS, set at registration, never inferred from source:
 //
 //   CONTENT  declares `inputs` — the paths it reads. Keyed on their git object
-//            ids, plus the check's own code (module graph), plus the toolchain
-//            (which content-hashes the gate binary, so editing shipkit moves
-//            every key in every repo), plus argv and declared env. No TTL: a
-//            content key is either the same question or a different one.
+//            ids, plus the check's own code (module graph), plus the runner
+//            and the install (toolchain-identity.ts), plus argv and declared
+//            env. No TTL: a content key is either the same question or a
+//            different one.
 //   WORLD    declares `ttl` — it reads the network, the keychain, $PATH, a git
 //            remote or the clock. Nothing on disk describes its answer, so it
 //            keeps the existing clean-pass TTL and its `cacheKey`, unchanged.
@@ -24,11 +24,11 @@
 //            check that says `never`. Never cached. For those it is the
 //            DEFAULT, and it is the whole safety story: forgetting to declare
 //            costs speed, never correctness, so the burn-down list below is a
-//            to-do rather than a hazard. It holds only while nothing declares ON a check's behalf:
-//            the gate floor gives `['.']` to the four slots tracked source
-//            decides and deliberately leaves `test` here (core/floor.ts says
-//            why). Declaring BOTH is a registration failure, loud, because the
-//            two answers contradict each other.
+//            to-do rather than a hazard. A TASK that declares nothing is not
+//            here: the composer keys it on the whole work tree plus the repo's
+//            ignoredInputs (ledger/gate-checks.ts). Declaring BOTH is a
+//            registration failure, loud, because the two answers contradict
+//            each other.
 //
 // CROSS WORKTREE. Every component here is content addressed or a version
 // string; not one of them is an absolute path. Two worktrees of one repo
@@ -39,15 +39,31 @@
 // differ from main by two top-level packages. That is what makes a shared
 // ledger safe rather than a stale green in a checkout nobody looked at.
 import { createHash } from 'crypto'
-import { join } from 'path'
+import { existsSync, readdirSync, readFileSync, type Dirent } from 'fs'
+import { isAbsolute, join, relative } from 'path'
+import { gitBin } from '../core/git-bin.ts'
 import { loadConfig, type RvtConfig } from '../ts/config.ts'
-import { importClosure } from '../ts/source-graph.ts'
+import { extractSpecs, importClosure } from '../ts/source-graph.ts'
 import { GitScanError, hashFiles, normalizeInput, scanPaths, WHOLE_TREE, type ScanResult } from './git-scan.ts'
-import { installIdentity, toolchainIdentity } from './toolchain-identity.ts'
+import { installIdentity, toolchainIdentity, type LibSource } from './toolchain-identity.ts'
 
 /** the key format. Bumped when a component is added or its rendering changes,
  *  so an old ledger can never answer a new question. */
-export const KEY_VERSION = 3
+export const KEY_VERSION = 4
+
+/** `dir/**` names a dir a task only LISTS: keyed on the names under it */
+export const isNamesInput = (p: string): boolean => p.endsWith('/**')
+
+let nodeMemo: string | null = null
+/** the node a task's tools run under, from PATH: a runtime upgrade is a
+ *  different program, like a bun upgrade */
+function nodeVersion(): string {
+    if (nodeMemo == null) {
+        const node = Bun.which('node')
+        nodeMemo = node == null ? 'none' : Bun.spawnSync([node, '--version'], { stdout: 'pipe', stderr: 'pipe' }).stdout.toString().trim() || 'unknown'
+    }
+    return nodeMemo
+}
 
 export type Population = 'content' | 'world' | 'reads' | 'none'
 
@@ -63,6 +79,10 @@ export type CheckDecl = {
     /** repo-relative entry files of the check's OWN code — the module-graph
      *  roots. A discovered check gets its own file for free. */
     code?: string[]
+    /** absolute entry files of the check's own code INSIDE the toolkit: a
+     *  built-in check's file. A task whose argv runs a toolkit module gets
+     *  that module's closure without declaring it */
+    libCode?: string[]
     /** the argv a subprocess check runs */
     argv?: string[]
     /** env var NAMES whose values belong in the key */
@@ -102,10 +122,14 @@ export type CheckKey = {
     components: string[]
     /** the input paths this check was keyed on, with their object ids */
     inputOids: [string, string][]
-    /** the identity of the check's OWN code, module graph included. Set for
-     *  every check that has code, WORLD ones too: a TTL'd probe whose source
-     *  changed must not replay its previous answer, and this is the value that
-     *  busts it. null when the check has no code entry or git could not hash it. */
+    /** the toolkit files behind its `lib=` and `libused=` components,
+     *  package-relative: what `shipkit keys --why` lists */
+    libFiles?: string[]
+    /** the identity of the check's OWN code, module graph included, in the
+     *  repo and in the toolkit. Set for every check that has code, WORLD ones
+     *  too: a TTL'd probe whose source changed must not replay its previous
+     *  answer, and this is the value that busts it. null when the check has no
+     *  code entry or its code could not be hashed. */
     codeKey: string | null
 }
 
@@ -196,7 +220,7 @@ export class KeyLayer {
         private readonly scanError: string | null,
         private readonly closureByCheck: Map<string, string[]>,
         private readonly codeOids: Map<string, string>,
-        private readonly toolchain: { id: string; uncacheable: string[] },
+        private readonly toolchain: { id: string; install: string; lib: LibSource | null; uncacheable: string[] },
         private readonly scanPathsUsed: string[],
         private readonly scope: ReadonlySet<string> | null,
         /** wall time of the WHOLE layer: toolchain identity, the module-graph
@@ -208,12 +232,11 @@ export class KeyLayer {
 
     private readonly installIds = new Map<string, string>()
 
-    /** the identity of the program this run is driving: bun version, the gate
-     *  binary's whole source, and every installed package. A WORLD check needs
-     *  it too, because a TTL'd answer measured by a different shipkit is a
-     *  different answer, and the TTL alone cannot see that. */
+    /** the runner and the install a WORLD answer is remembered under: a TTL'd
+     *  answer measured by a different shipkit is a different answer, and the
+     *  TTL alone cannot see that. The probe's own code rides in `codeKey` */
     get toolchainId(): string {
-        return this.toolchain.id
+        return `${this.toolchain.id}:${this.toolchain.install}`
     }
 
     /** wall time the GIT half alone cost, ms — `openMs` is what a run pays */
@@ -232,11 +255,11 @@ export class KeyLayer {
         // a gate binary that cannot be resolved is not a crash, it is a run
         // whose program nobody can name — and the only safe answer to that is
         // no key at all
-        let toolchain: { id: string; uncacheable: string[] }
+        let toolchain: { id: string; install: string; lib: LibSource | null; uncacheable: string[] }
         try {
             toolchain = { ...toolchainIdentity(root, o.cliEntry), uncacheable: [] }
         } catch (e) {
-            toolchain = { id: 'unresolved', uncacheable: [`gate binary unreadable at ${o.cliEntry}: ${e instanceof Error ? e.message : String(e)}`] }
+            toolchain = { id: 'unresolved', install: 'unresolved', lib: null, uncacheable: [`gate binary unreadable at ${o.cliEntry}: ${e instanceof Error ? e.message : String(e)}`] }
         }
 
         // the check's OWN code, resolved through the same module graph the
@@ -257,7 +280,7 @@ export class KeyLayer {
         const paths = new Set<string>()
         for (const d of scoped) {
             if (classify(d).population !== 'content') continue
-            for (const p of d.inputs ?? []) paths.add(p)
+            for (const p of d.inputs ?? []) if (!isNamesInput(p)) paths.add(p)
         }
 
         // the closure is INDIVIDUAL FILES belonging to no declared path, so it
@@ -287,9 +310,12 @@ export class KeyLayer {
         const own = (this.closureByCheck.get(d.id) ?? []).slice().sort()
         const ownReadable = own.every((p) => this.codeOids.get(p) != null)
         const codeLines = own.map((p) => `code:${p}=${this.codeOids.get(p)!}`)
+        const lib = this.libLines(d)
         const base: CheckKey = {
-            id: d.id, population: c.population, key: null, reason: null, components: [], inputOids: [],
-            codeKey: own.length === 0 || !ownReadable ? null : createHash('sha256').update(codeLines.join('\n')).digest('hex').slice(0, 16),
+            id: d.id, population: c.population, key: null, reason: null, components: [], inputOids: [], libFiles: this.libFilesOf(d),
+            codeKey: typeof lib === 'string' || (own.length === 0 || !ownReadable) && lib.length === 0
+                ? null
+                : createHash('sha256').update([...(ownReadable ? codeLines : []), ...lib].join('\n')).digest('hex').slice(0, 16),
         }
         if (c.error != null) return { ...base, reason: c.error }
         if (this.scope != null && !this.scope.has(d.id)) return { ...base, reason: 'not one of the checks this run executes, so nothing was scanned for it' }
@@ -299,10 +325,10 @@ export class KeyLayer {
         const scan = this.scan!
         if (this.toolchain.uncacheable.length > 0)
             return { ...base, reason: `toolchain not describable: ${this.toolchain.uncacheable.join('; ')}` }
+        if (typeof lib === 'string') return { ...base, reason: lib }
         // the question alone: what it read is stored with each answer and
         // re-checked before a replay, so no read belongs in this key
         if (c.population === 'reads') {
-            // a built-in has no code entry: the toolchain id hashes its source
             if (!ownReadable) return { ...base, reason: `git could not hash this check's own source: ${own.filter((p) => this.codeOids.get(p) == null).join(', ')}` }
             const components = [
                 `v=${KEY_VERSION}`,
@@ -312,14 +338,17 @@ export class KeyLayer {
                 `toolchain=${this.toolchain.id}`,
                 'reads=recorded',
                 ...codeLines,
+                ...lib,
                 ...(d.extra != null ? [`extra=${d.extra}`] : []),
             ]
             return { ...base, key: createHash('sha256').update(components.join('\n')).digest('hex').slice(0, 32), components }
         }
 
         let inputs: string[]
+        let names: string[]
         try {
-            inputs = (d.inputs ?? []).map(normalizeInput).sort()
+            inputs = (d.inputs ?? []).filter((p) => !isNamesInput(p)).map(normalizeInput).sort()
+            names = (d.inputs ?? []).filter(isNamesInput).map((p) => normalizeInput(p.slice(0, -3))).sort()
         } catch (e) {
             return { ...base, reason: e instanceof Error ? e.message : String(e) }
         }
@@ -341,10 +370,17 @@ export class KeyLayer {
             // frozen run and a normal one measure it twice.
             ...(d.writes === true ? [`frozen=${process.env['SHIPKIT_FROZEN'] === '1'}`] : []),
             `toolchain=${this.toolchain.id}`,
+            // the repo's own tools run here, and what is installed is part of
+            // what they are
+            `install=${this.toolchain.install}`,
             `argv=${JSON.stringify(d.argv ?? [])}`,
             ...(d.env ?? []).slice().sort().map((n) => `env:${n}=${process.env[n] ?? '<unset>'}`),
             ...inputOids.map(([p, oid]) => `in:${p}=${oid}`),
+            // a dir the task only lists: the names under it, never its bytes
+            ...names.map((p) => `names:${p}=${this.namesOf(p)}`),
+            `node=${nodeVersion()}`,
             ...codeLines,
+            ...lib,
             ...(d.extra != null ? [`extra=${d.extra}`] : []),
             // ignored content nobody keyed on is part of the key's MEANING:
             // two runs that excluded different things answered different
@@ -362,6 +398,88 @@ export class KeyLayer {
         return { ...base, key, components, inputOids }
     }
 
+    /** the toolkit code a check's answer comes from, as key lines, or why it
+     *  cannot be keyed. A built-in names its file, a task running a toolkit
+     *  module names it in its argv. Everything else runs the REPO's code, and
+     *  in a repo that does not host the toolkit that code imports it by
+     *  package name, through an install the install id leaves the toolkit out
+     *  of: those carry the closure of every toolkit module the repo imports */
+    private libLines(d: CheckDecl): string[] | string {
+        const lib = this.toolchain.lib
+        if (lib == null) return []
+        const entries = [...(d.libCode ?? []), ...(d.argv ?? []).filter((a) => isAbsolute(a) && lib.owns(a))]
+        try {
+            const used = d.libCode == null ? this.libUsed() : []
+            if (typeof used === 'string') return used
+            return [...(entries.length > 0 ? [`lib=${lib.closureKey(entries)}`] : []), ...used]
+        } catch (e) {
+            return `the toolkit source this check runs could not be read: ${e instanceof Error ? e.message : String(e)}`
+        }
+    }
+
+    private libUsedMemo: string[] | string | null = null
+    private libUsedEntries: string[] = []
+
+    /** the files behind libLines, for a reader; empty when there are none */
+    private libFilesOf(d: CheckDecl): string[] {
+        const lib = this.toolchain.lib
+        if (lib == null) return []
+        const entries = [...(d.libCode ?? []), ...(d.argv ?? []).filter((a) => isAbsolute(a) && lib.owns(a)), ...(d.libCode == null ? this.libUsedEntries : [])]
+        try { return [...new Set(entries.flatMap((e) => lib.closureOf(e)))].sort() } catch { return [] }
+    }
+
+    /** the closure of every toolkit module this repo's own files import by
+     *  package name, found with one `git grep` over tracked and untracked
+     *  files. Empty in the repo that hosts the toolkit, whose own resolver
+     *  follows those imports into the code closure */
+    private libUsed(): string[] | string {
+        if (this.libUsedMemo != null) return this.libUsedMemo
+        const lib = this.toolchain.lib
+        if (lib == null || lib.name == null || !relative(this.root, lib.pkgRoot).startsWith('..')) return (this.libUsedMemo = [])
+        const p = Bun.spawnSync([gitBin(), 'grep', '-l', '--untracked', '-F', '-e', `${lib.name}/`, '--', '*.ts', '*.tsx', '*.mts', '*.cts', '*.js', '*.mjs'], { cwd: this.root, stdout: 'pipe', stderr: 'pipe' })
+        // exit 1 is "no match", anything above it is git failing
+        if (p.exitCode > 1) return (this.libUsedMemo = `git grep could not list the files importing ${lib.name}: ${p.stderr.toString().trim().split('\n')[0]}`)
+        const entries: string[] = []
+        for (const f of p.stdout.toString().split('\n').filter((l) => l !== '')) {
+            let text = ''
+            try { text = readFileSync(join(this.root, f), 'utf8') } catch { continue }
+            for (const spec of [...extractSpecs(text, { dynamic: true }), ...[...text.matchAll(/import\.meta\.resolve\(\s*['"]([^'"\n]+)['"]\s*\)/g)].map((m) => m[1]!)]) {
+                const abs = lib.fileOf(spec)
+                if (abs != null) entries.push(abs)
+            }
+        }
+        this.libUsedEntries = [...new Set(entries)].sort()
+        return (this.libUsedMemo = entries.length === 0 ? [] : [`libused=${lib.closureKey(this.libUsedEntries)}`])
+    }
+
+    private readonly namesMemo = new Map<string, string>()
+
+    /** every relative path under a dir, sorted, as one hash: what a task that
+     *  lists the dir without reading its files sees. `absent` for no dir */
+    private namesOf(rel: string): string {
+        let h = this.namesMemo.get(rel)
+        if (h == null) {
+            const abs = join(this.root, rel)
+            if (!existsSync(abs)) h = 'absent'
+            else {
+                const all: string[] = []
+                const walk = (d: string, prefix: string): void => {
+                    let entries: Dirent[] = []
+                    try { entries = readdirSync(d, { withFileTypes: true }) } catch { return }
+                    for (const e of entries) {
+                        const r = `${prefix}${e.name}`
+                        all.push(e.isDirectory() ? `${r}/` : r)
+                        if (e.isDirectory()) walk(join(d, e.name), `${r}/`)
+                    }
+                }
+                walk(abs, '')
+                h = createHash('sha256').update(all.sort().join('\n')).digest('hex').slice(0, 16)
+            }
+            this.namesMemo.set(rel, h)
+        }
+        return h
+    }
+
     /** an excluded install's identity, once per layer: several checks can name
      *  the same one, and hashing a `node_modules` twice in a run is pure cost. */
     private installOf(rel: string): string {

package/src/ledger/git-scan.ts

@@ -290,10 +290,13 @@ export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult,
     // force-adding that one entry stages the node_modules inside it.
     const declared = new Set(wanted)
     const denied = ignored.filter(underNodeModules)
-    const forceAdd = ignored.filter((p) => declared.has(p) && !underNodeModules(p) && !denied.some((d) => d.startsWith(`${p}/`)))
+    // a declared path INSIDE a wholly ignored dir comes back as that dir, so
+    // it is named by the collapsed ancestor rather than by itself
+    const underIgnored = present.filter((p) => p !== WHOLE_TREE && !ignored.includes(p) && ignored.some((d) => p.startsWith(`${d}/`)))
+    const forceAdd = [...ignored, ...underIgnored].filter((p) => declared.has(p) && !underNodeModules(p) && !denied.some((d) => d.startsWith(`${p}/`)))
     // a path git itself calls ignored must NOT get the plain add: `git add --
     // <ignored>` exits 1 and takes the whole scan down with it
-    const ignoredSet = new Set(ignored)
+    const ignoredSet = new Set([...ignored, ...underIgnored])
     const plainAdds = toAdd.filter((p) => !ignoredSet.has(p))
     if (plainAdds.length > 0) gitOrThrow(root, ['add', '--', ...plainAdds], indexFile)
     // force-adds land in their OWN index, so a path one check named can never