rvlib-shipkit 0.38.0 → 1.0.0

package/src/core/floor-resolve.ts

@@ -0,0 +1,264 @@
+// resolveFloor — which task fills each floor slot (lint, typecheck, test,
+// imports:check, cycles) and, when nothing can, the reason it stays empty.
+// Beside the slots it derives two checks per declared sub-unit,
+// `test:<unit id>` (suite/test-units.ts owns which file each one runs) and,
+// when the unit has a tsconfig of its own, `typecheck:<unit id>`.
+//
+// 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.
+//
+// No disk access of its own: every read goes through the FloorReader it is
+// handed. core/floor.ts hands it plain fs, a check hands it the check context
+// (checkFloorReader), so SK001 and SK017, which ask how the floor resolves,
+// are keyed on exactly the files it read.
+import { join, posix } from 'path'
+import { fileURLToPath } from 'url'
+import { rawName, slotBody } from './canonical-scripts.ts'
+import type { CheckCtx } from './check-ctx.ts'
+import { checkUnitReader, type UnitReader } from '../release/unit-resolve.ts'
+import { parseJsonc } from '../ts/jsonc.ts'
+import { resolveTypecheckProjects } from '../ts/tsconfig-resolve.ts'
+import { parseBunTestScript, suiteFlags } from '../suite/judge-suites.ts'
+import { declaredTestUnits, siblingUnits, testCheckId, unitIgnores, unitTestBody, unitTsconfig, type TestUnitDecl } from '../suite/test-units.ts'
+import { describeFirst, type TaskDef } from '../check.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+/** how the floor reads the repo, by repo-relative path, plus the one lookup
+ *  outside it: a binary on PATH */
+export type FloorReader = UnitReader & { which: (bin: string) => string | null }
+
+/** the check context as a floor reader. A PATH lookup is not a repo read, so
+ *  it marks the answer untracked, and only a repo with no local tsc and no
+ *  typecheck script ever asks it */
+export function checkFloorReader(c: CheckCtx): FloorReader {
+    return {
+        ...checkUnitReader(c),
+        which: (bin) => {
+            c.untrack(`looked ${bin} up on PATH, outside the repo`)
+            return Bun.which(bin)
+        },
+    }
+}
+
+export const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
+
+/** what a floor slot asserts, whatever fills it: the row's description on
+ *  every surface. With units, the root `test` runs only the files
+ *  outside them, since each unit has its own `test:<unit>` */
+export function slotDescription(id: string, withUnits: boolean): string {
+    if (id === 'lint') return 'the linter reports no problem in the repo'
+    if (id === 'typecheck') return 'tsc finds no type error in the repo'
+    if (id === 'test') return withUnits ? 'every test file outside the units passes' : 'every test file in the repo passes'
+    if (id === 'imports:check') return 'every local import is absolute, carries its extension and resolves'
+    if (id === 'cycles') return 'no import cycle between modules'
+    throw new Error(`no description for floor slot '${id}'`)
+}
+
+/** what a unit's own test check asserts */
+export const unitTestDescription = (u: { id: string; rel: string }): string =>
+    describeFirst(`every test file under ${u.rel} passes`, `every test file of unit ${u.id} passes`)
+
+/** what a unit's own typecheck asserts */
+export const unitTypecheckDescription = (u: { id: string; rel: string }): string =>
+    describeFirst(`tsc finds no type error under ${u.rel}`, `tsc finds no type error in unit ${u.id}`)
+
+export type FloorSource = 'package.json script' | 'repo.config override' | 'built-in (shipkit)' | 'built-in (tsc)' | 'unit'
+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>
+    /** skip lines about how a slot runs, printed by the gate */
+    notes?: string[]
+}
+
+/** a package.json body for a slot. A plain `bun test` in the test slot runs
+ *  through the suite runner (parallel, timed against the budget), anything
+ *  else runs as written and the gate says what that costs */
+function scriptCmd(c: RepoConfig, id: string, name: string, body: string, notes: string[], subs: TestUnitDecl[]): string[] {
+    if (id !== 'test') return ['bun', 'run', name]
+    const args = parseBunTestScript(body)
+    if (args == null) {
+        notes.push(`skip: suite runner (script '${name}' is not a plain \`bun test\`, so its suites run as written: not in parallel, not timed against a budget${subs.length > 0 ? ', and the units\' own suites may run in it too' : ''})`)
+        return ['bun', 'run', name]
+    }
+    // each sub-unit's suites belong to its own check, run in its own dir
+    const unitArgs = subs.length === 0 ? [] : ['--unit', 'root']
+    return ['bun', SUITE_CLI, ...suiteFlags(c.tests), ...unitArgs, '--', ...args, ...unitIgnores(subs).map((g) => `--path-ignore-patterns=${g}`)]
+}
+
+const SUITE_CLI = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/suite/suite-cli.ts'))
+
+/** one test check per declared sub-unit, `test:<unit id>`, a `release: false`
+ *  one included, run in the unit's own dir through the suite runner, so its
+ *  bunfig, its preload and its `units[].tests` budget apply, after the checks
+ *  its `deps` name. Its inputs are its dir and the dirs of the
+ *  sibling units its package.json names, derived rather than declared */
+function unitTestTasks(c: RepoConfig, root: string, io: FloorReader, subs: TestUnitDecl[], siblings: Map<string, string[]>, notes: string[], unfilled: { id: string; reason: string }[]): TaskDef[] {
+    const read = io.text
+    const out: TaskDef[] = []
+    for (const u of subs) {
+        const id = testCheckId(u.id)
+        if (!io.exists(u.rel)) { unfilled.push({ id, reason: `unit '${u.id}': '${u.rel}' is not a directory` }); continue }
+        const { script, body } = unitTestBody(read(join(u.rel, 'package.json')))
+        const args = parseBunTestScript(body)
+        let cmd: string[]
+        if (args == null) {
+            notes.push(`skip: suite runner for ${id} (script '${script}' is not a plain \`bun test\`, so its suites run as written: not in parallel, not timed against a budget)`)
+            cmd = ['bun', 'run', script!]
+        } else cmd = ['bun', SUITE_CLI, ...suiteFlags(u.tests), '--declared-in', `repo.config.ts units['${u.rel}'].tests (paths relative to ${u.rel})`, '--unit', u.id, '--', ...args]
+        out.push({ id, description: unitTestDescription(u), cmd, cwd: join(root, u.rel), inputs: [u.rel, ...(siblings.get(u.id) ?? [])], ...(u.deps == null ? {} : { deps: u.deps }) })
+    }
+    return out
+}
+
+/** one typecheck per declared sub-unit with a tsconfig of its own,
+ *  `typecheck:<unit id>`: the root tsconfig excludes a unit's dir (it compiles
+ *  standalone), so without this a green root typecheck hides every error only
+ *  the unit's tsconfig sees. It runs the same runner the root slot falls back
+ *  to, so a solution style config is checked project by project and says what
+ *  it checked. tsc comes from the unit's node_modules, else the repo's, else
+ *  PATH. Keyed and ordered like the unit's test check */
+function unitTypecheckTasks(root: string, io: FloorReader, subs: TestUnitDecl[], siblings: Map<string, string[]>, unfilled: { id: string; reason: string }[]): TaskDef[] {
+    const out: TaskDef[] = []
+    for (const u of subs) {
+        const id = `typecheck:${u.id}`
+        const tsconfig = unitTsconfig(u)
+        if (!io.exists(tsconfig, 'file')) {
+            if (u.tsconfig != null) unfilled.push({ id, reason: `units['${u.rel}'].tsconfig names '${u.tsconfig}', which does not exist` })
+            continue
+        }
+        const local = join(u.rel, 'node_modules/.bin/tsc')
+        const tsc = io.exists(local) ? join(root, local) : io.exists('node_modules/.bin/tsc') ? join(root, 'node_modules/.bin/tsc') : io.which('tsc')
+        if (tsc == null) { unfilled.push({ id, reason: `unit '${u.id}' has a tsconfig and no tsc resolves (its node_modules, the repo's, PATH): add typescript` }); continue }
+        const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/typecheck-cli.ts'))
+        const outside = tsconfigChain(tsconfig, io).filter((f) => f !== u.rel && !f.startsWith(`${u.rel}/`))
+        out.push({ id, description: unitTypecheckDescription(u), cmd: ['bun', cli, tsc, join(root, tsconfig)], cwd: join(root, u.rel), inputs: [u.rel, ...(siblings.get(u.id) ?? []), ...outside], ...(u.deps == null ? {} : { deps: u.deps }) })
+    }
+    return out
+}
+
+/** a tsconfig and every config its `extends` reaches by a relative path,
+ *  repo-relative: a base config outside the unit dir decides what compiles,
+ *  so it belongs to the key. A package specifier (`@tsconfig/bun`) lives in
+ *  node_modules and is left to the toolchain */
+function tsconfigChain(rel: string, io: FloorReader): string[] {
+    const out: string[] = []
+    for (let at: string | null = posix.normalize(rel); at != null && !out.includes(at) && !at.startsWith('../'); ) {
+        out.push(at)
+        const text = io.text(at)
+        let ext: unknown = null
+        try { ext = text == null ? null : (parseJsonc(text) as { extends?: unknown } | null)?.extends } catch { ext = null }
+        at = typeof ext === 'string' && ext.startsWith('.') ? posix.normalize(posix.join(posix.dirname(at), ext.endsWith('.json') ? ext : `${ext}.json`)) : null
+    }
+    return out
+}
+
+// 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, io: FloorReader): { 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') {
+        const tsconfig = join(root, 'tsconfig.json')
+        if (!io.exists('tsconfig.json')) return `no 'typecheck' script and no tsconfig.json`
+        const local = join(root, 'node_modules/.bin/tsc')
+        const tsc = io.exists('node_modules/.bin/tsc') ? local : io.which('tsc')
+        if (tsc == null) return `no 'typecheck' script and tsc not found — add typescript or a typecheck script`
+        // `tsc --noEmit` over a solution-style config (`files: []` plus
+        // `references`) compiles ZERO files and exits 0, so the slot reports a
+        // green nobody measured. only a config that is its OWN single project
+        // keeps the plain command; everything else goes through the runner,
+        // which resolves and REPORTS what it checked.
+        //
+        // a config that compiles nothing, or references a path that is gone,
+        // registers the runner too rather than leaving the slot unfilled: an
+        // unfilled slot is a skip, `shipkit ci` still exits 0, and a repo with
+        // no typecheck coverage would look the same as a repo that passed.
+        let plain = false
+        try {
+            const projects = resolveTypecheckProjects(tsconfig, io, root)
+            plain = projects.projects.length === 1 && projects.projects[0] === tsconfig && projects.missing.length === 0
+        } catch { plain = false }
+        if (plain) return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
+        const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/typecheck-cli.ts'))
+        return { task: { id, cmd: ['bun', cli, tsc, tsconfig] }, source: 'built-in (tsc)' }
+    }
+    return `no package.json '${id}' script`
+}
+
+// NOTHING here declares a read set on a repo's behalf, and that is a decision
+// rather than an omission. A floor slot with no `inputs` is measured every run,
+// which costs speed and never correctness (ledger/git-key.ts owns that default).
+//
+// The tempting shortcut is `['.']`, on the reasoning that the whole tree cannot
+// under declare. It can. `['.']` is the TRACKED tree: git-scan force-adds only a
+// path a declaration NAMES, so an ignored path enters the key by name and never
+// by content. Every floor slot reads ignored content in an ordinary repo, a
+// suite through its fixtures and a local database, tsc and the graph walks
+// through generated types and node_modules. Shipped for one day, that made the
+// gate print `ok: test (replayed)` over a suite that exits 1
+// (tests/floor-cache-safety.test.ts holds the repro).
+//
+// Speed here is bought by a REPO saying what its own tasks read, in
+// `defaults`, which is the only declaration with a real hit rate anyway.
+// `shipkit init` scaffolds the line, `shipkit keys --burn-down` names what is
+// still undeclared, and the gate prints the cost of it once per run.
+
+export function resolveFloor(c: RepoConfig, root: string, io: FloorReader): FloorResolution {
+    const pkg = io.text('package.json')
+    let scripts: Record<string, string> = {}
+    if (pkg != null) {
+        // unparseable package.json must NOT silently empty the floor — the
+        // gate would run only `contracts` and report green
+        try { scripts = (JSON.parse(pkg) 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> = {}
+    const notes: string[] = []
+    const subs = declaredTestUnits(c.units)
+    for (const id of FLOOR_IDS) {
+        const override = c.defaults?.[id]
+        const description = slotDescription(id, subs.length > 0)
+        const slot = slotBody(id, override, scripts)
+        if (slot.kind === 'off') { disabled.push(id); continue }
+        if (slot.kind === 'override') {
+            tasks.push({ description, ...(override as TaskDef), id: (override as TaskDef).id ?? id })
+            sources[id] = 'repo.config override'
+            continue
+        }
+        // an override with no body DECORATES the slot: that is how a repo
+        // declares what its `test` script reads without restating the command
+        const decorate = (b: TaskDef): TaskDef => {
+            const t = { description, ...b }
+            return override == null || override === false ? t : { ...t, ...override, id }
+        }
+        if (slot.kind === 'script') { tasks.push(decorate({ id, cmd: scriptCmd(c, id, slot.name, slot.body, notes, subs) })); sources[id] = 'package.json script'; continue }
+        const b = builtinFloorTask(id, root, io)
+        // 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: slot.kind === 'routed-empty' ? `script '${id}' routes to shipkit and there is no '${rawName(id)}' body to run` : b })
+        else { tasks.push(decorate(b.task)); sources[id] = b.source }
+    }
+    const siblings = siblingUnits(subs, io.text)
+    for (const t of unitTestTasks(c, root, io, subs, siblings, notes, unfilled)) { tasks.push(t); sources[t.id] = 'unit' }
+    for (const t of unitTypecheckTasks(root, io, subs, siblings, unfilled)) { tasks.push(t); sources[t.id] = 'unit' }
+    return { tasks, disabled, unfilled, sources, notes }
+}

package/src/core/floor.ts

@@ -1,145 +1,28 @@
-// 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'
+// the floor as read from the disk: plain fs behind core/floor-resolve.ts, which
+// owns the resolution. Every caller outside a check resolves here; a check
+// resolves through its context (checkFloorReader) so it stays keyed on its reads.
+import { existsSync } from 'fs'
 import { join } from 'path'
-import { fileURLToPath } from 'url'
-import { rawName, routesToShipkit } from './canonical-scripts.ts'
-import { resolveTypecheckProjects } from '../ts/tsconfig-projects.ts'
-import { parseBunTestScript, suiteFlags } from '../suite/judge-suites.ts'
-import type { TaskDef } from './task-runner.ts'
+import { gitBin } from './git-bin.ts'
+import { fsUnitReader } from '../release/units.ts'
+import { resolveFloor as resolveWith, type FloorReader, type FloorResolution } from './floor-resolve.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
-export const FLOOR_IDS = ['lint', 'typecheck', 'test', 'imports:check', 'cycles'] as const
+export * from './floor-resolve.ts'
 
-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>
-    /** skip lines about how a slot runs, printed by the gate */
-    notes?: string[]
-}
-
-/** a package.json body for a slot. A plain `bun test` in the test slot runs
- *  through the suite runner (parallel, timed against the budget), anything
- *  else runs as written and the gate says what that costs */
-function scriptCmd(c: RepoConfig, id: string, name: string, body: string, notes: string[]): string[] {
-    if (id !== 'test') return ['bun', 'run', name]
-    const args = parseBunTestScript(body)
-    if (args == null) {
-        notes.push(`skip: suite runner (script '${name}' is not a plain \`bun test\`, so its suites run as written: not in parallel, not timed against a budget)`)
-        return ['bun', 'run', name]
-    }
-    return ['bun', fileURLToPath(import.meta.resolve('rvlib-shipkit/src/suite/suite-cli.ts')), ...suiteFlags(c.tests), '--', ...args]
-}
+export const fsFloorReader = (root: string): FloorReader => ({ ...fsUnitReader(root), which: (bin) => Bun.which(bin) })
 
-// 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') {
-        const tsconfig = join(root, 'tsconfig.json')
-        if (!existsSync(tsconfig)) 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`
-        // `tsc --noEmit` over a solution-style config (`files: []` plus
-        // `references`) compiles ZERO files and exits 0, so the slot reports a
-        // green nobody measured. only a config that is its OWN single project
-        // keeps the plain command; everything else goes through the runner,
-        // which resolves and REPORTS what it checked.
-        //
-        // a config that compiles nothing, or references a path that is gone,
-        // registers the runner too rather than leaving the slot unfilled: an
-        // unfilled slot is a skip, `shipkit ci` still exits 0, and a repo with
-        // no typecheck coverage would look the same as a repo that passed.
-        let plain = false
-        try {
-            const projects = resolveTypecheckProjects(tsconfig)
-            plain = projects.projects.length === 1 && projects.projects[0] === tsconfig && projects.missing.length === 0
-        } catch { plain = false }
-        if (plain) return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
-        const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/typecheck-cli.ts'))
-        return { task: { id, cmd: ['bun', cli, tsc, tsconfig] }, source: 'built-in (tsc)' }
-    }
-    return `no package.json '${id}' script`
+export function resolveFloor(c: RepoConfig, root: string, io: FloorReader = fsFloorReader(root)): FloorResolution {
+    return resolveWith(c, root, io)
 }
 
-// NOTHING here declares a read set on a repo's behalf, and that is a decision
-// rather than an omission. A floor slot with no `inputs` is measured every run,
-// which costs speed and never correctness (ledger/git-key.ts owns that default).
-//
-// The tempting shortcut is `['.']`, on the reasoning that the whole tree cannot
-// under declare. It can. `['.']` is the TRACKED tree: git-scan force-adds only a
-// path a declaration NAMES, so an ignored path enters the key by name and never
-// by content. Every floor slot reads ignored content in an ordinary repo, a
-// suite through its fixtures and a local database, tsc and the graph walks
-// through generated types and node_modules. Shipped for one day, that made the
-// gate print `ok: test (replayed)` over a suite that exits 1
-// (tests/floor-cache-safety.test.ts holds the repro).
-//
-// Speed here is bought by a REPO saying what its own tasks read, in
-// `defaults`, which is the only declaration with a real hit rate anyway.
-// `shipkit init` scaffolds the line, `shipkit keys --burn-down` names what is
-// still undeclared, and the gate prints the cost of it once per run.
-
-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> = {}
-    const notes: string[] = []
-    for (const id of FLOOR_IDS) {
-        const override = c.defaults?.[id]
-        if (override === false) { disabled.push(id); continue }
-        // a FULL override brings its own body and replaces the slot. One that
-        // brings none DECORATES whatever fills it, which is how a repo declares
-        // what its `test` script reads without restating the command: the read
-        // set is repo knowledge, the command is not.
-        if (override != null && (override.cmd != null || override.logic != null)) {
-            tasks.push({ ...override, id: override.id ?? id } as TaskDef)
-            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 decorate = (t: TaskDef): TaskDef => (override == null ? t : { ...t, ...override, id })
-        const raw = scripts[rawName(id)]
-        if (raw != null) { tasks.push(decorate({ id, cmd: scriptCmd(c, id, rawName(id), raw, notes) })); sources[id] = 'package.json script'; continue }
-        if (scripts[id] != null && !routesToShipkit(scripts[id]!)) { tasks.push(decorate({ id, cmd: scriptCmd(c, id, id, scripts[id]!, notes) })); 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(decorate(b.task)); sources[id] = b.source }
-    }
-    return { tasks, disabled, unfilled, sources, notes }
+/** every file git sees here (tracked, or untracked and not ignored), repo
+ *  relative: the listing test discovery and the root test key read. Outside
+ *  git, a disk walk with installs and dot dirs left out */
+export function listRepoFiles(root: string): string[] {
+    const p = Bun.spawnSync([gitBin(), 'ls-files', '-co', '--exclude-standard', '-z'], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+    if (p.exitCode === 0) return p.stdout.toString().split('\0').filter((f) => f !== '' && existsSync(join(root, f))).sort()
+    try {
+        return [...new Bun.Glob('**/*').scanSync({ cwd: root, onlyFiles: true, dot: false })].map((f) => f.replace(/\\/g, '/')).filter((f) => !f.split('/').includes('node_modules')).sort()
+    } catch { return [] }
 }

package/src/core/git-bin.ts

@@ -0,0 +1,24 @@
+// the git executable to spawn, resolved once per process.
+//
+// on macOS `git` on PATH is usually /usr/bin/git, an xcrun shim that looks up
+// the active developer dir on every call: measured 15ms a spawn against 5ms for
+// the binary it forwards to. a gate spawns git a dozen times, so the shim is
+// most of what a cached gate costs. `git --exec-path` names the real
+// git-core directory, which holds the real `git`, and that is what we spawn.
+// anything unexpected keeps plain `git`, which is always correct, only slower.
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+let resolved: string | null = null
+
+export function gitBin(): string {
+    if (resolved != null) return resolved
+    resolved = 'git'
+    if (process.platform !== 'darwin') return resolved
+    try {
+        const p = Bun.spawnSync(['git', '--exec-path'], { stdout: 'pipe', stderr: 'ignore' })
+        const dir = p.exitCode === 0 ? p.stdout.toString().trim() : ''
+        if (dir !== '' && existsSync(join(dir, 'git'))) resolved = join(dir, 'git')
+    } catch {}
+    return resolved
+}

package/src/core/git-root.ts

@@ -0,0 +1,108 @@
+// where a directory sits in git: its git dir, the common dir, the work tree
+// root and its prefix inside it. One rev-parse answers all four, and the answer
+// is remembered per directory, because one gate asks it from a dozen places
+// (store, run record, scan, nesting, three rules) and each ask is a process
+// spawn. A directory with no `.git` in reach is answered without asking. Every remembered answer is re-validated with a few stats on each hit,
+// so a `git init` or a deleted repo is seen at once in a long-lived process.
+import { existsSync, realpathSync, statSync } from 'fs'
+import { dirname, join, resolve } from 'path'
+import { gitBin } from './git-bin.ts'
+
+export type GitRoot = {
+    /** absolute git dir of this work tree (per worktree) */
+    gitDir: string
+    /** absolute common dir, shared by every linked worktree */
+    commonDir: string
+    /** absolute work tree root, realpath as git prints it */
+    top: string
+    /** the directory relative to `top`, posix: '' at the root, else ending in '/' */
+    prefix: string
+}
+
+type Probe = { root: GitRoot | null; error: string }
+
+const known = new Map<string, Probe>()
+
+/** a positive answer holds while its git dir exists and no `.git` appeared
+ *  between the directory and the work tree root (a repo nested in after the
+ *  fact). A negative one holds while no `.git` exists at or above it, so an
+ *  answer git gave despite a `.git` in reach is never remembered at all. */
+function stillValid(dir: string, p: Probe): boolean {
+    if (p.root != null && !existsSync(join(p.root.gitDir, 'HEAD'))) return false
+    let cur: string
+    try {
+        cur = realpathSync(dir)
+    } catch {
+        return false
+    }
+    for (;;) {
+        if (p.root != null && cur === p.root.top) return true
+        if (existsSync(join(cur, '.git'))) return false
+        const up = dirname(cur)
+        if (up === cur) return p.root == null
+        cur = up
+    }
+}
+
+/** the facts, or git's own words for why there are none */
+export function probeGitRoot(at: string): Probe {
+    // absolute, so a relative ask never reads an answer given for another cwd
+    const dir = resolve(at)
+    const hit = known.get(dir)
+    if (hit != null && stillValid(dir, hit)) return hit
+    const p = ask(dir)
+    if (stillValid(dir, p)) known.set(dir, p)
+    else known.delete(dir)
+    return p
+}
+
+/** the variables that let git find a repo with no `.git` in reach */
+const LOCATING_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR']
+
+/** git's discovery walks up looking for `.git`. With none at or above and no
+ *  variable pointing elsewhere, its answer is already known, and a gate or a
+ *  test suite that probes fresh temp dirs would spawn a process per dir for it */
+function nothingInReach(dir: string): boolean {
+    if (LOCATING_ENV.some((k) => (process.env[k] ?? '') !== '')) return false
+    let cur: string
+    try {
+        cur = realpathSync(dir)
+    } catch {
+        return false
+    }
+    for (;;) {
+        if (existsSync(join(cur, '.git'))) return false
+        const up = dirname(cur)
+        if (up === cur) return true
+        cur = up
+    }
+}
+
+function ask(dir: string): Probe {
+    if (nothingInReach(dir)) return { root: null, error: 'fatal: not a git repository (or any of the parent directories): .git' }
+    let p: ReturnType<typeof Bun.spawnSync>
+    try {
+        p = Bun.spawnSync([gitBin(), 'rev-parse', '--path-format=absolute', '--absolute-git-dir', '--git-common-dir', '--show-toplevel', '--show-prefix'], {
+            cwd: dir,
+            stdout: 'pipe',
+            stderr: 'pipe',
+        })
+    } catch (e) {
+        return { root: null, error: e instanceof Error ? e.message : String(e) }
+    }
+    if (p.exitCode !== 0) return { root: null, error: p.stderr?.toString().trim() ?? `git rev-parse exited ${p.exitCode}` }
+    const [gitDir = '', commonDir = '', top = '', prefix = ''] = (p.stdout?.toString() ?? '').split('\n')
+    if (gitDir === '' || commonDir === '' || top === '') return { root: null, error: `git rev-parse printed no work tree for ${dir}` }
+    return { root: { gitDir, commonDir, top, prefix }, error: '' }
+}
+
+/** the facts, or null outside a git work tree */
+export const gitRoot = (dir: string): GitRoot | null => probeGitRoot(dir).root
+
+/** a LINKED worktree, where `.git` is a file pointing at the main checkout
+ *  rather than a directory. Cheap on purpose: it runs on every check pass and
+ *  every hub tick, and spawning git to learn it would cost more than the
+ *  answer is worth. */
+export function isLinkedWorktree(root: string): boolean {
+    try { return statSync(join(root, '.git')).isFile() } catch { return false }
+}