rvlib-shipkit 0.38.1 → 1.0.0

package/src/ledger/gate-checks.ts

@@ -0,0 +1,433 @@
+// EVERY CHECK THIS REPO HAS, composed ONCE.
+//
+// One walk feeds three readers: the runner (core/check-runner.ts) gets bodies,
+// the key layer gets declarations, and every surface gets rows. They cannot
+// disagree about what exists, which is the whole reason this file is the only
+// place that enumerates.
+//
+// What feeds it: the floor slots derived from package.json scripts, the
+// repo's own `tasks: []`, every discovered `*.check.ts`, and the two legacy
+// forms still read behind the compatibility fence (`rules: []` and a legacy
+// 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 type { CheckCtx } from '../core/check-ctx.ts'
+import { type RepoConfig } from '../repo-config.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'
+import { ruleCacheExtra } from '../rules/rule.ts'
+import { discoverChecks } from '../core/discover-checks.ts'
+import { checkCacheExtra, describeFirst, type TaskDef, type CheckFrom } from '../check.ts'
+import { CHECK_TIMEOUT_MS, type RunnableCheck, type CheckBody } from '../core/check-runner.ts'
+import { parseDuration } from '../core/wire.ts'
+import { whenOfLegacyCheck, whenOfDisabledSlot, whenOfRule, whenOfTask, whenOfCheck, type WhenDecl } from '../core/when.ts'
+import 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'
+import { LIB_ROOT } from '../core/lib-root.ts'
+import type { DiscoveredCheck } from '../core/discover-checks.ts'
+import { declaredTestUnits, inputsOutsideUnits, isTestFile } from '../suite/test-units.ts'
+
+/** why an undeclared `run` check cannot be keyed on its reads, or null when it
+ *  can. A built-in is walked inside the toolkit, a repo check inside the repo
+ *  with the toolkit left out (the toolchain id covers it) */
+function rawAccessOf(root: string, u: DiscoveredCheck, configs: Map<string, RvtConfig>): string | null {
+    try {
+        const r = u.rel == null ? rawAccessInClosure(LIB_ROOT, u.path, { configs }) : rawAccessInClosure(root, u.path, { skip: LIB_ROOT, configs })
+        return r == null ? null : rawAccessLine(r)
+    } catch (e) {
+        return `the modules ${u.rel ?? u.path} imports could not be listed (${String(e).slice(0, 120)}): declare inputs or never`
+    }
+}
+
+/** the env var a repo's own suite reads to widen itself. It lives HERE because
+ *  it rewrites every build step's env, which is part of the key: a run that
+ *  asked for the quick tier and one that asked for the full tier are different
+ *  questions, and a surface that renders keys without applying it renders a
+ *  tier nobody ran. */
+export const FULL_TESTS_ENV = 'SHIPKIT_TEST_FULL'
+
+export type TestTier = 'quick' | 'full'
+
+/** the tier this process is asking for, absent an explicit choice */
+export function envTier(): TestTier {
+    return process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick'
+}
+
+/** a BUILD step's ceiling when it names none: a whole tool chain is not one
+ *  question about the world (core/check-runner.ts owns the other default) */
+export const BUILD_TIMEOUT_MS = 600_000
+
+/** the floor plus the repo's own `tasks: []`, with the slots nothing could
+ *  fill and the ones a config turned off. The gate prints those, and the TUI
+ *  draws its rows from them before anything has run. */
+export async function allTasks(c: RepoConfig, root: string): Promise<FloorResolution> {
+    const floor = resolveFloor(c, root)
+    return { ...floor, tasks: [...floor.tasks, ...(c.tasks ?? [])] }
+}
+
+/** one gate check with everything a reader asks about it, not only what the
+ *  key layer asks. The cache half stays in `decl` so `CheckDecl` never grows
+ *  fields the key layer must then decide to ignore. */
+export type CheckRow = {
+    decl: CheckDecl
+    /** the display name an operator reads (its title, else the id) */
+    title: string
+    /** the check's one line description (the shape: check.ts
+     *  descriptionProblem). Every row carries one: a check file declares it,
+     *  and a row with no file to say it in (a floor slot, a unit test check,
+     *  a task, the legacy forms) gets it from what generated the row. */
+    description: string
+    /** does `shipkit ci` run it? false = PROACTIVE: `shipkit check` reports it,
+     *  the gate never does, and it may sit red for months without anything
+     *  being wrong with the change in front of you. */
+    gate: boolean
+    /** a BUILD STEP: the gate runs it, the health pass does not. `shipkit ci`
+     *  asks "is my change good" and builds, `shipkit check` asks "is this
+     *  repo healthy" and reports, and a repo's test suite has no business in
+     *  the second question. DERIVED true for a floor slot and a `tasks: []`
+     *  entry, which have no file to say it in, and DECLARED by a `*.check.ts`
+     *  that is one (check.ts `build`). */
+    build: boolean
+    /** can a failure stop you? null = the check never said AND the repo set no
+     *  `checkDefaults.blocking`, which the runner treats as fatal. */
+    blocking: boolean | null
+    /** where the answer is owned: a wiki page, a file, a command. Null when
+     *  the check names none. */
+    owner: string | null
+    /** the group a check was filed under, for the few that declare one */
+    group: string | null
+    /** the wall clock ceiling it DECLARED, null when it named none and takes
+     *  the default for its kind of body */
+    timeoutMs: number | null
+    /** excluded from a default run unless named with `--with` */
+    optIn: boolean
+    /** an idempotent repair exists: `shipkit check --fix <id>` applies it,
+     *  then re-runs the check. `shipkit checks --fixable` is the catalog of
+     *  everything in this repo that repairs itself. */
+    fixable: boolean
+    /** WHERE IT RUNS, the one reading of the `when` key, of the three
+     *  spellings it replaces, and of a floor slot turned off (core/when.ts) */
+    when: WhenDecl
+    /** what it waits on, null when it waits on nothing */
+    deps: string[] | null
+    /** whose check it is: `shipkit` = it ships with the toolkit (a built-in
+     *  SK check, the contracts pass, a floor slot nothing in the repo filled),
+     *  `repo` = this repo declared it (a package.json script behind a floor
+     *  slot, a task, a rule, a check file, a check file). */
+    from: CheckFrom
+}
+
+/** the one axis every check answers: who wrote the declaration */
+export type { CheckFrom } from '../check.ts'
+
+/** one composed check: the row every surface reads, and the runnable the
+ *  runner takes. Two views of one declaration, never two enumerations. */
+export type GateCheck = { row: CheckRow; runnable: RunnableCheck }
+
+export type ComposeOpts = {
+    /** which tier the caller is asking for: `full` widens every build step's
+     *  env, which is part of its key */
+    tier?: TestTier
+}
+
+/** a legacy `TaskDef` as the runner takes it. The config key still reads
+ *  through the compatibility window, so the shape survives one release longer
+ *  than the word for it. */
+function taskBody(t: TaskDef): CheckBody {
+    return {
+        ...(t.cmd == null ? {} : { cmd: t.cmd }),
+        ...(t.logic == null ? {} : { run: async (ctx: CheckCtx) => { await t.logic!(ctx) } }),
+        ...(t.env == null ? {} : { env: t.env }),
+        ...(t.cwd == null ? {} : { cwd: t.cwd }),
+    }
+}
+
+const ttlMsOf = (ttl: string | undefined): number => (ttl == null || ttl === '' ? 0 : parseDuration(ttl))
+
+/** the runnable half of a row: everything the runner needs, and nothing it
+ *  has to look up again */
+function runnableOf(row: CheckRow, body: CheckBody, o: { fix?: unknown; pointer?: string | null } = {}): RunnableCheck {
+    return {
+        id: row.decl.id,
+        title: row.title,
+        owner: row.owner ?? row.decl.id,
+        blocking: row.blocking,
+        build: row.build,
+        when: row.when,
+        deps: row.deps ?? [],
+        group: row.group,
+        timeoutMs: row.timeoutMs ?? (row.build ? BUILD_TIMEOUT_MS : CHECK_TIMEOUT_MS),
+        ttlMs: ttlMsOf(row.decl.ttl),
+        rotation: row.decl.extra,
+        writes: row.decl.writes === true,
+        body,
+        fix: o.fix,
+        pointer: o.pointer ?? null,
+        population: populationOf(row.decl),
+    }
+}
+
+/** what the ROOT `test` check is keyed on, when the repo declared its read
+ *  set (`defaults.test.inputs`): its own test files ride in as code, so the
+ *  modules they import move the key, and every sub-unit dir is cut out of the
+ *  declared paths, because those suites run in `test:<unit>`. A repo that
+ *  declared nothing stays unkeyed, exactly as before (core/floor.ts says why) */
+function rootTestKey(root: string, c: RepoConfig, floor: FloorResolution): { inputs: string[]; code: string[] } | null {
+    const t = floor.tasks.find((x) => x.id === 'test')
+    if (t?.inputs == null || t.cmd == null) return null
+    const files = listRepoFiles(root)
+    const subs = declaredTestUnits(c.units)
+    const own = files.filter((f) => isTestFile(f) && !subs.some((u) => f.startsWith(`${u.rel}/`)))
+    return { inputs: subs.length === 0 ? t.inputs : inputsOutsideUnits(t.inputs, subs.map((u) => u.rel), files), code: own }
+}
+
+/** a task's own description, else its command exiting 0 */
+const taskDescription = (t: TaskDef): string =>
+    describeFirst(t.description, t.cmd == null ? null : `\`${t.cmd.join(' ')}\` exits 0`, `the ${t.id} task ${t.cmd == null ? 'passes' : 'exits 0'}`)
+
+/** THE enumeration. Everything below reads it, nothing else walks. */
+export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts = {}): Promise<GateCheck[]> {
+    const out: GateCheck[] = []
+    const checks = await discoverChecks(root)
+    const floor = resolveFloor(c, root)
+    const env = { root, config: c }
+    const full = o.tier === 'full'
+    /** a check file's own path IS its code closure, so nothing declares it */
+    const relOf = new Map(checks.filter((u) => u.rel != null).map((u) => [u.id, u.rel!]))
+    const fromOf = new Map(checks.map((u) => [u.id, u.from]))
+    // a floor slot the REPO filled (its package.json script, its config
+    // override) is the repo's; one shipkit filled with its own module or the
+    // repo's tsc is the toolkit's. A task the config declares is the repo's.
+    const taskFrom = (id: string): CheckFrom => {
+        const discovered = fromOf.get(id)
+        if (discovered != null) return discovered
+        const src = floor.sources[id]
+        if (src == null) return 'repo'
+        return src === 'package.json script' || src === 'repo.config override' || src === 'unit' ? 'repo' : 'shipkit'
+    }
+    // LEGACY: a task that runs a check file under the check's own name was
+    // that file run twice, once per engine, when tasks and checks had a
+    // namespace each. One namespace makes the pair one check: the check row
+    // runs, carrying what the task added (core/legacy-shapes.ts rewrites the
+    // pair the same way on disk)
+    const legacy = discoverLegacyChecks(root)
+    const foldedInto = new Map<string, TaskDef>()
+    for (const t of c.tasks ?? []) {
+        const d = legacy.find((x) => x.name === t.id)
+        if (d == null || t.logic != null) continue
+        const r = checkFileRunBy(t, root)
+        if (r != null && r.rest.length === 0 && r.rel === relative(root, d.path).replace(/\\/g, '/')) foldedInto.set(t.id, t)
+    }
+    // BUILD STEPS: the floor, then the repo's own `tasks: []`. The whole run
+    // carries the tier flag rather than one task id: a repo names its suites
+    // what it likes, and a gate that guesses which one is the tests will miss
+    // one.
+    const rootTest = rootTestKey(root, c, floor)
+    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 row: CheckRow = {
+            decl: {
+                id: t.id,
+                inputs: own?.inputs ?? t.inputs,
+                ttl: t.ttl,
+                never: t.never,
+                argv: t.cmd,
+                code: relOf.has(t.id) ? [relOf.get(t.id)!] : own?.code,
+                extra: t.env == null ? undefined : JSON.stringify(Object.entries(t.env).sort()),
+            },
+            title: t.id,
+            description: taskDescription(t),
+            // an optIn task is off the default run, which is the same shape as
+            // a check that opted out of the gate
+            gate: t.optIn !== true,
+            build: true,
+            // a build step IS the build: it has no non-blocking mode
+            blocking: true,
+            owner: t.cmd == null ? null : t.cmd.join(' '),
+            group: t.group ?? null,
+            timeoutMs: t.timeoutMs ?? null,
+            optIn: t.optIn === true,
+            // a build step runs a TOOL, and repairing what a tool reports is
+            // that tool's own job (a formatter, a codemod), never the gate's
+            fixable: false,
+            when: whenOfTask(c, t),
+            deps: t.deps ?? null,
+            from: taskFrom(t.id),
+        }
+        out.push({ row, runnable: runnableOf(row, taskBody(t)) })
+    }
+    // a slot `defaults: { <id>: false }` turned off never resolves to a task,
+    // so without this it had no row at all: no `runs in` value, no reason, and
+    // a count of off checks that read zero while a gate step sat dark. It has
+    // no command, which is why it declares `never` rather than joining the
+    // burn-down of checks nobody has keyed yet.
+    for (const id of floor.disabled) {
+        const row: CheckRow = {
+            decl: { id, never: `turned off by defaults.${id}: false, so there is no command to key` },
+            title: id,
+            description: slotDescription(id, declaredTestUnits(c.units).length > 0),
+            gate: false,
+            build: true,
+            blocking: true,
+            owner: null,
+            group: null,
+            timeoutMs: null,
+            optIn: false,
+            fixable: false,
+            when: whenOfDisabledSlot(id),
+            deps: null,
+            // the repo wrote the line that turned it off
+            from: 'repo',
+        }
+        // it is OFF, so the body is never reached: the runner reports the
+        // reason rather than running anything
+        out.push({ row, runnable: runnableOf(row, { run: () => {} }) })
+    }
+    // every `*.check.ts` this repo and the toolkit declare
+    const configs = new Map<string, RvtConfig>()
+    for (const u of checks) {
+        const w = whenOfCheck(c, u)
+        // an in process body declaring nothing is keyed on what it reads
+        // through its context (git-key.ts READS). The tier is part of that
+        // question: a body can read the env, and a quick answer must never
+        // stand in for a full one
+        const undeclared = u.def.run != null && u.def.inputs == null && u.def.ttl == null && u.def.never == null
+        // conservative: any module its body can reach that touches the disk or
+        // a process around `c` keeps it off its reads (core/raw-access.ts)
+        const raw = undeclared ? rawAccessOf(root, u, configs) : null
+        const reads = undeclared && raw == null
+        const extra = checkCacheExtra({ id: u.id, cacheKey: u.def.cacheKey }, env, w)
+        const row: CheckRow = {
+            decl: {
+                id: u.id,
+                inputs: u.def.inputs,
+                code: u.rel == null ? undefined : [u.rel],
+                ttl: u.def.ttl,
+                never: u.def.never,
+                argv: u.def.cmd,
+                extra: reads ? `${extra ?? ''}|tier=${full ? 'full' : 'quick'}` : extra,
+                writes: u.def.writes,
+                ...(reads ? { reads: true } : {}),
+                ...(raw != null ? { uncacheable: raw } : {}),
+            },
+            title: u.title,
+            description: u.description,
+            gate: w.at !== 'health',
+            build: u.def.build === true,
+            blocking: u.def.blocking,
+            owner: u.owner,
+            group: u.def.group ?? null,
+            timeoutMs: u.def.timeoutMs ?? null,
+            optIn: false,
+            fixable: u.def.fix != null,
+            when: w,
+            deps: u.def.deps ?? null,
+            from: u.from,
+        }
+        const body: CheckBody = {
+            ...(u.def.cmd == null ? {} : { cmd: u.def.cmd }),
+            ...(u.def.run == null ? {} : { run: u.def.run }),
+            ...(u.def.env == null ? {} : { env: u.def.env }),
+            // relative to the root, and an absolute one stands as written
+            ...(u.def.cwd == null ? {} : { cwd: resolve(root, u.def.cwd) }),
+        }
+        out.push({ row, runnable: runnableOf(row, body, { fix: u.def.fix, pointer: u.def.cmd?.join(' ') ?? null }) })
+    }
+    // LEGACY: `rules: []`, read as a check whose body is its lint. Dies with
+    // that config key once `shipkit fleet` shows no repo below 0.40.
+    for (const r of c.rules ?? []) {
+        const row: CheckRow = {
+            decl: {
+                id: r.id,
+                inputs: r.inputs,
+                code: r.code,
+                ttl: r.ttl,
+                never: r.never,
+                extra: ruleCacheExtra(r, env),
+            },
+            title: r.title,
+            description: describeFirst(r.title, `rule ${r.id} holds`),
+            gate: true,
+            build: false,
+            blocking: r.blocking,
+            owner: r.owner,
+            group: null,
+            timeoutMs: null,
+            optIn: false,
+            fixable: r.fix != null,
+            when: whenOfRule(c, r.id),
+            deps: null,
+            from: 'repo',
+        }
+        out.push({ row, runnable: runnableOf(row, { run: (ctx) => r.lint(ctx, { root: ctx.root, config: ctx.config }) }, { fix: r.fix }) })
+    }
+    // LEGACY: a check script with no check object, read as a `cmd` check
+    // running itself. The reader is a source scanner rather than an import,
+    // which is why it cannot carry a fixer or a typed declaration
+    // (core/discover-legacy-checks.ts).
+    for (const found of legacy) {
+        const rel = relative(root, found.path).replace(/\\/g, '/')
+        const task = foldedInto.get(found.name)
+        // a task that is not optIn put an off gate file in the gate, and the
+        // file's own cache declaration wins over the task's
+        const d = task == null ? found : { ...found, gate: found.gate || task.optIn !== true }
+        const cached = d.inputs != null || d.ttl != null || d.never != null
+        const row: CheckRow = {
+            decl: {
+                id: d.name,
+                inputs: d.inputs ?? (cached ? undefined : task?.inputs),
+                ttl: d.ttl ?? (cached ? undefined : task?.ttl),
+                never: d.never ?? (cached ? undefined : task?.never),
+                code: [rel],
+                argv: ['bun', rel],
+                // no `extra`, so WHERE it runs stays out of a legacy check's
+                // key, deliberately: the field is read by a source scanner
+                // that cannot carry a `cacheKey` either, and adding the
+                // rotation now would bust every field repo's TTL cache once
+                // for a file form that is refused after 0.40 anyway
+            },
+            title: d.name,
+            description: describeFirst(`\`bun ${rel}\` exits 0`, `${d.name} exits 0`),
+            gate: d.gate,
+            build: false,
+            // the file wins, then the repo default, then nothing: an
+            // unclassified check is an error, never a guess
+            blocking: d.blocking ?? c.checkDefaults?.blocking ?? null,
+            owner: rel,
+            group: task?.group ?? null,
+            timeoutMs: task?.timeoutMs ?? null,
+            optIn: false,
+            // the reader is a source scanner, so it cannot carry a function
+            fixable: false,
+            when: whenOfLegacyCheck(c, d),
+            deps: task?.deps ?? null,
+            from: 'repo',
+        }
+        // the pointer names the file the way a reader types it, never the
+        // absolute path discovery happened to hand the spawner
+        const body: CheckBody = { cmd: ['bun', d.path], ...(task?.env == null ? {} : { env: task.env }), ...(task?.cwd == null ? {} : { cwd: resolve(root, task.cwd) }) }
+        out.push({ row, runnable: runnableOf(row, body, { pointer: `bun ${rel}` }) })
+    }
+    return out
+}
+
+/** every check the gate knows, with its metadata. */
+export async function gateInventory(root: string, c: RepoConfig, o: ComposeOpts = {}): Promise<CheckRow[]> {
+    return (await composeChecks(root, c, o)).map((g) => g.row)
+}
+
+/** the same list, as the runner takes it */
+export async function gateRunnables(root: string, c: RepoConfig, o: ComposeOpts = {}): Promise<RunnableCheck[]> {
+    return (await composeChecks(root, c, o)).map((g) => g.runnable)
+}
+
+/** the inventory narrowed to the cache declaration, which is what the key
+ *  layer keys. Same walk, so a surface can never enumerate a different set. */
+export async function gateChecks(root: string, c: RepoConfig, o: ComposeOpts = {}): Promise<CheckDecl[]> {
+    return (await composeChecks(root, c, o)).map((g) => g.row.decl)
+}