rvlib-shipkit 1.4.0 → 1.6.0

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,27 +11,29 @@
 // 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'
 import { ruleCacheExtra } from '../rules/rule.ts'
 import { discoverChecks } from '../core/discover-checks.ts'
-import { checkCacheExtra, describeFirst, type TaskDef, type CheckFrom, type CheckEnv } from '../check.ts'
+import { checkCacheExtra, describeFirst, type TaskDef, type CheckFrom, type CheckEnv, type CheckDef } from '../check.ts'
 import { CHECK_TIMEOUT_MS, type RunnableCheck, type CheckBody } from '../core/check-runner.ts'
-import { ttlMsOf } from '../core/wire.ts'
+import { FOREVER, ttlMsOf } from '../core/wire.ts'
 import { budgetOf } from '../core/budget.ts'
-import { whenOfLegacyCheck, whenOfDisabledSlot, whenOfRule, whenOfTask, whenOfCheck, type WhenDecl } from '../core/when.ts'
-import type { CheckDecl } from './git-key.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 { 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'
 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'
-import type { PlanDecl } from '../plan/cadence.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
@@ -74,18 +76,6 @@ export async function allTasks(c: RepoConfig, root: string): Promise<FloorResolu
 /** 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. */
-/** a check's `planOff`, read now; one that throws stays planned, and says so */
-function planOffOf(id: string, fn: ((env: CheckEnv) => string | null) | undefined, env: CheckEnv): { planOff?: string } {
-    if (fn == null) return {}
-    try {
-        const why = fn(env)
-        return why == null ? {} : { planOff: why }
-    } catch (e) {
-        console.error(`WARN ${id} planOff threw, so it stays planned: ${(e as Error).message}`)
-        return {}
-    }
-}
-
 export type CheckRow = {
     decl: CheckDecl
     /** the display name an operator reads (its title, else the id) */
@@ -126,16 +116,16 @@ export type CheckRow = {
      *  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) */
+    /** WHERE IT RUNS, every context resolved: what the check file declared,
+     *  or what the code deriving the row wrote, with the repo's `off`
+     *  override laid over it (core/runs.ts, core/when.ts) */
+    runs: ResolvedRuns
+    /** how its answer is kept, as one short cell (core/runs.ts cacheText) */
+    cache: string
+    /** the coarse word the runs read as, for the surfaces that show one */
     when: WhenDecl
     /** what it waits on, null when it waits on nothing */
     deps: string[] | null
-    /** when the planner runs it on its own (check.ts `every`, `cron`,
-     *  `whenInactive`). Absent: nothing declared, the planner's defaults */
-    plan?: PlanDecl
-    /** why the plan leaves this check out in this repo (check.ts `planOff`) */
-    planOff?: string
     /** 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
@@ -178,7 +168,7 @@ function runnableOf(row: CheckRow, body: CheckBody, o: { fix?: unknown; pointer?
         owner: row.owner ?? row.decl.id,
         blocking: row.blocking,
         build: row.build,
-        when: row.when,
+        runs: row.runs,
         deps: row.deps ?? [],
         group: row.group,
         timeoutMs: row.timeoutMs ?? (row.build ? BUILD_TIMEOUT_MS : CHECK_TIMEOUT_MS),
@@ -211,6 +201,59 @@ function rootTestKey(root: string, c: RepoConfig, floor: FloorResolution): { inp
 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 default range a repo row nothing can key runs on, so it is asked
+ *  about once a day and never in step with its siblings */
+const DAILY: [string, string] = ['20h', '28h']
+
+/** the runs of a row with no file to declare them in (a floor slot, a config
+ *  task, a legacy rule or script), written out in full with the reason. It
+ *  keeps what the planner and the gate did with such a row before the
+ *  declaration was explicit: a ttl is the cadence ('once' for a forever
+ *  fact), a save moves a keyed row or a fact, a gate build step nothing keys
+ *  reruns after every save burst, and any other row nothing keys runs about
+ *  once a day */
+function derivedRuns(o: { gate: boolean; build: boolean; inputs?: string[]; ttl?: string; kind: string; repair: boolean }): ResolvedRuns {
+    const keyed = o.inputs != null
+    const ttl = o.ttl != null && o.ttl !== '' ? o.ttl : null
+    const fact = ttl === FOREVER
+    const parked = o.build && !o.gate
+    const onClock: Runs['onClock'] = parked ? false : fact ? 'once' : ttl != null ? { every: ttl, inactive: 'wait' } : o.build || keyed ? false : { every: DAILY, inactive: 'wait' }
+    const onSave: Runs['onSave'] = parked ? false : fact || (keyed && ttl == null) ? 'moved' : ttl == null && o.build ? 'burst' : false
+    const r: Runs = { ...NOWHERE, onCi: o.gate, onFull: o.gate, onRelease: o.gate, onHealth: !o.build, onSave, onClock }
+    const fix = !o.repair ? 'none' : o.gate ? 'ci' : 'manual'
+    const clock = onClock === false ? '' : onClock === 'once' ? ', once while its fact is unknown' : `, on the clock every ${ttl ?? DAILY.join('..')}`
+    const save = onSave === 'moved' ? ', the daemon when its key moves' : onSave === 'burst' ? ', the daemon after every save burst since nothing keys it' : ''
+    const where = parked ? 'parked: only --with or --only names it' : `${o.gate ? 'every gate' : 'no gate'}${o.build ? ', never the health pass' : ' and the health pass'}${save}${clock}`
+    return sourced(r, fix, 'derived', `${o.kind}: ${where}`)
+}
+
+/** the cache half of a check file, as the key layer reads it */
+function declOfCache(cache: CacheDecl, env: CheckEnv): { inputs?: string[]; ttl?: string; never?: string; key?: string; reads?: boolean } {
+    switch (cache.by) {
+        case 'files': return { inputs: cache.inputs, key: cache.key?.(env) }
+        case 'reads': return { reads: true }
+        case 'ttl': return { ttl: cache.span, key: cache.key?.(env) }
+        case 'fact': return { ttl: FOREVER, key: cache.key(env) }
+        case 'never': return { never: cache.why }
+    }
+}
+
+/** a legacy row's cache, as one cell */
+const legacyCacheText = (d: { inputs?: string[]; ttl?: string; never?: string }): string =>
+    d.inputs != null ? filesText(d.inputs) : d.ttl != null && d.ttl !== '' ? (d.ttl === FOREVER ? 'fact' : `ttl ${d.ttl}`) : d.never != null ? `never: ${d.never}` : 'never: nothing declared'
+
+/** a check file's own runs, resolved: its declaration, n/a where it does not
+ *  apply, then the repo's override */
+function fileRuns(def: CheckDef, id: string, c: RepoConfig, env: CheckEnv): ResolvedRuns {
+    const own = sourced(def.runs, def.fix, 'check file')
+    let na: string | null = null
+    if (typeof def.applies === 'function') {
+        try { na = def.applies(env) } catch (e) { console.error(`WARN ${id} applies threw, so it applies: ${(e as Error).message}`) }
+    }
+    const base = na == null ? own : { ...own, off: `n/a here: ${na}` }
+    return withRepoOff(base, repoOff(c, id))
+}
+
 /** THE enumeration. Everything below reads it, nothing else walks. */
 export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts = {}): Promise<GateCheck[]> {
     const out: GateCheck[] = []
@@ -249,13 +292,29 @@ 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 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 = {
             decl: {
                 id: t.id,
-                inputs: own?.inputs ?? t.inputs,
+                inputs,
                 ttl: t.ttl,
                 never: t.never,
                 argv: t.cmd,
@@ -266,7 +325,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             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,
+            gate: runs.off == null && runs.onCi,
             build: true,
             // a build step IS the build: it has no non-blocking mode
             blocking: true,
@@ -278,7 +337,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             // 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),
+            runs,
+            cache: legacyCacheText({ inputs, ttl: t.ttl, never: t.never }),
+            when: whenSummary(runs, repoOff(c, t.id), false),
             deps: t.deps ?? null,
             from: taskFrom(t.id),
         }
@@ -293,6 +354,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
     // 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 runs = sourced(NOWHERE, 'none', 'repo.config.ts', null, `defaults.${id}: false`)
         const row: CheckRow = {
             decl: { id, never: `turned off by defaults.${id}: false, so there is no command to key` },
             title: id,
@@ -306,7 +368,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             budgetMs: budgetOf(id, undefined, { build: true, cmd: false, world: false }, c.budgets),
             optIn: false,
             fixable: false,
-            when: whenOfDisabledSlot(id),
+            runs,
+            cache: `never: turned off by defaults.${id}: false`,
+            when: whenSummary(runs, { reason: `defaults.${id}: false`, source: 'defaults' }, false),
             deps: null,
             // the repo wrote the line that turned it off
             from: 'repo',
@@ -319,46 +383,47 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
     const configs = new Map<string, RvtConfig>()
     const texts = new Map<string, string>()
     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, texts) : null
-        const reads = undeclared && raw == null
-        const extra = checkCacheExtra({ id: u.id, cacheKey: u.def.cacheKey }, env, w)
+        const runs = fileRuns(u.def, u.id, c, env)
+        const cache = declOfCache(u.def.cache, env)
+        // a body 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. Any module
+        // its body can reach that touches the disk or a process around `c`
+        // contradicts the declaration (core/raw-access.ts), and says so loud
+        const raw = cache.reads === true && u.def.run != null ? rawAccessOf(root, u, configs, texts) : null
+        const extra = checkCacheExtra(cache.key, runs.off)
         const row: CheckRow = {
             decl: {
                 id: u.id,
-                inputs: u.def.inputs,
+                inputs: cache.inputs,
                 code: u.rel == null ? undefined : [u.rel],
-                ttl: u.def.ttl,
-                never: u.def.never,
+                // 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,
-                extra: reads ? `${extra ?? ''}|tier=${full ? 'full' : 'quick'}` : extra,
+                extra: cache.reads === true ? `${extra ?? ''}|tier=${full ? 'full' : 'quick'}` : extra,
                 writes: u.def.writes,
-                ...(reads ? { reads: true } : {}),
-                ...(raw != null ? { uncacheable: raw } : {}),
+                ...(cache.reads === true && raw == null ? { reads: true } : {}),
+                ...(raw != null ? { declError: `declares cache reads, but ${raw}` } : {}),
             },
             title: u.title,
             description: u.description,
-            gate: w.at !== 'health',
+            gate: runs.off == null && runs.onCi,
             build: u.def.build === true,
             blocking: u.def.blocking,
             owner: u.owner,
             group: u.def.group ?? null,
             timeoutMs: u.def.timeoutMs ?? null,
-            budgetMs: budgetOf(u.id, u.def.budgetMs, { build: u.def.build === true, cmd: u.def.cmd != null, world: u.def.ttl != null || u.def.never != null }, c.budgets),
+            budgetMs: budgetOf(u.id, u.def.budgetMs, { build: u.def.build === true, cmd: u.def.cmd != null, world: cache.ttl != null || cache.never != null }, c.budgets),
             optIn: false,
-            fixable: u.def.fix != null,
-            when: w,
+            fixable: u.def.repair != null,
+            runs,
+            cache: cacheText(u.def.cache),
+            when: whenSummary(runs, repoOff(c, u.id), true),
             deps: u.def.deps ?? null,
             from: u.from,
-            ...(u.def.every !== undefined || u.def.cron != null || u.def.whenInactive != null ? { plan: { every: u.def.every, cron: u.def.cron, whenInactive: u.def.whenInactive } } : {}),
-            ...planOffOf(u.id, u.def.planOff, env),
         }
         const body: CheckBody = {
             ...(u.def.cmd == null ? {} : { cmd: u.def.cmd }),
@@ -367,11 +432,12 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             // 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 }) })
+        out.push({ row, runnable: runnableOf(row, body, { fix: u.def.repair, 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 runs = withRepoOff(derivedRuns({ gate: true, build: false, inputs: r.inputs, ttl: r.ttl, kind: 'a legacy repo.config.ts rule', repair: r.fix != null }), repoOff(c, r.id))
         const row: CheckRow = {
             decl: {
                 id: r.id,
@@ -383,7 +449,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             },
             title: r.title,
             description: describeFirst(r.title, `rule ${r.id} holds`),
-            gate: true,
+            gate: runs.off == null && runs.onCi,
             build: false,
             blocking: r.blocking,
             owner: r.owner,
@@ -392,7 +458,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             budgetMs: budgetOf(r.id, undefined, { build: false, cmd: false, world: r.ttl != null || r.never != null }, c.budgets),
             optIn: false,
             fixable: r.fix != null,
-            when: whenOfRule(c, r.id),
+            runs,
+            cache: legacyCacheText(r),
+            when: whenSummary(runs, repoOff(c, r.id), false),
             deps: null,
             from: 'repo',
         }
@@ -409,12 +477,14 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
         // 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 li = { inputs: d.inputs ?? (cached ? undefined : task?.inputs), ttl: d.ttl ?? (cached ? undefined : task?.ttl), never: d.never ?? (cached ? undefined : task?.never) }
+        const runs = withRepoOff(derivedRuns({ gate: d.gate, build: false, inputs: li.inputs, ttl: li.ttl, kind: 'a legacy check script', repair: false }), repoOff(c, d.name))
         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),
+                inputs: li.inputs,
+                ttl: li.ttl,
+                never: li.never,
                 code: [rel],
                 argv: ['bun', rel],
                 // no `extra`, so WHERE it runs stays out of a legacy check's
@@ -425,7 +495,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             },
             title: d.name,
             description: describeFirst(`\`bun ${rel}\` exits 0`, `${d.name} exits 0`),
-            gate: d.gate,
+            gate: runs.off == null && runs.onCi,
             build: false,
             // the file wins, then the repo default, then nothing: an
             // unclassified check is an error, never a guess
@@ -437,7 +507,9 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             optIn: false,
             // the reader is a source scanner, so it cannot carry a function
             fixable: false,
-            when: whenOfLegacyCheck(c, d),
+            runs,
+            cache: legacyCacheText(li),
+            when: whenSummary(runs, repoOff(c, d.name), false),
             deps: task?.deps ?? null,
             from: 'repo',
         }