rvlib-shipkit 1.0.1 → 1.1.1

package/src/ledger/gate-checks.ts

@@ -22,6 +22,7 @@ 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 { 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 { populationOf } from '../problems/problem-line.ts'
@@ -34,9 +35,9 @@ import { declaredTestUnits, inputsOutsideUnits, isTestFile } from '../suite/test
 /** 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 {
+function rawAccessOf(root: string, u: DiscoveredCheck, configs: Map<string, RvtConfig>, texts: Map<string, string>): string | null {
     try {
-        const r = u.rel == null ? rawAccessInClosure(LIB_ROOT, u.path, { configs }) : rawAccessInClosure(root, u.path, { skip: LIB_ROOT, configs })
+        const r = u.rel == null ? rawAccessInClosure(LIB_ROOT, u.path, { configs, texts }) : rawAccessInClosure(root, u.path, { skip: LIB_ROOT, configs, texts })
         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`
@@ -103,6 +104,9 @@ export type CheckRow = {
     /** the wall clock ceiling it DECLARED, null when it named none and takes
      *  the default for its kind of body */
     timeoutMs: number | null
+    /** what a healthy run takes, RESOLVED: the repo's `budgets`, else what
+     *  the check declared, else the default for its kind (core/budget.ts) */
+    budgetMs: number
     /** excluded from a default run unless named with `--with` */
     optIn: boolean
     /** an idempotent repair exists: `shipkit check --fix <id>` applies it,
@@ -150,7 +154,7 @@ const ttlMsOf = (ttl: string | undefined): number => (ttl == null || 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 {
+function runnableOf(row: CheckRow, body: CheckBody, o: { fix?: unknown; pointer?: string | null; unbudgeted?: boolean } = {}): RunnableCheck {
     return {
         id: row.decl.id,
         title: row.title,
@@ -161,6 +165,7 @@ function runnableOf(row: CheckRow, body: CheckBody, o: { fix?: unknown; pointer?
         deps: row.deps ?? [],
         group: row.group,
         timeoutMs: row.timeoutMs ?? (row.build ? BUILD_TIMEOUT_MS : CHECK_TIMEOUT_MS),
+        ...(o.unbudgeted === true ? {} : { budgetMs: row.budgetMs }),
         ttlMs: ttlMsOf(row.decl.ttl),
         rotation: row.decl.extra,
         writes: row.decl.writes === true,
@@ -251,6 +256,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             owner: t.cmd == null ? null : t.cmd.join(' '),
             group: t.group ?? null,
             timeoutMs: t.timeoutMs ?? null,
+            budgetMs: budgetOf(t.id, undefined, { build: true, cmd: t.cmd != null, world: t.ttl != null }, c.budgets),
             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
@@ -259,7 +265,10 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             deps: t.deps ?? null,
             from: taskFrom(t.id),
         }
-        out.push({ row, runnable: runnableOf(row, taskBody(t)) })
+        // at the full tier a build step runs every slow suite on purpose, and
+        // its env (and so its cache key) differs from the quick run, so its
+        // time is not judged and its answer never stands in for a quick one
+        out.push({ row, runnable: runnableOf(row, taskBody(t), { unbudgeted: full }) })
     }
     // 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
@@ -277,6 +286,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             owner: null,
             group: null,
             timeoutMs: null,
+            budgetMs: budgetOf(id, undefined, { build: true, cmd: false, world: false }, c.budgets),
             optIn: false,
             fixable: false,
             when: whenOfDisabledSlot(id),
@@ -290,6 +300,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
     }
     // every `*.check.ts` this repo and the toolkit declare
     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
@@ -299,7 +310,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
         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 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 row: CheckRow = {
@@ -323,6 +334,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             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 }, c.budgets),
             optIn: false,
             fixable: u.def.fix != null,
             when: w,
@@ -358,6 +370,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             owner: r.owner,
             group: null,
             timeoutMs: null,
+            budgetMs: budgetOf(r.id, undefined, { build: false, cmd: false, world: r.ttl != null }, c.budgets),
             optIn: false,
             fixable: r.fix != null,
             when: whenOfRule(c, r.id),
@@ -401,6 +414,7 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             owner: rel,
             group: task?.group ?? null,
             timeoutMs: task?.timeoutMs ?? null,
+            budgetMs: budgetOf(d.name, undefined, { build: false, cmd: true, world: d.ttl != null }, c.budgets),
             optIn: false,
             // the reader is a source scanner, so it cannot carry a function
             fixable: false,

package/src/ledger/git-key.ts

@@ -173,6 +173,9 @@ export type KeyLayerOpts = {
     cliEntry: string
     /** module-graph config; loaded from the repo when omitted */
     cfg?: RvtConfig
+    /** the checks this run executes. Only they are scanned and hashed, and any
+     *  other id gets no key. Omitted = every check */
+    scope?: ReadonlySet<string>
 }
 
 /**
@@ -191,6 +194,7 @@ export class KeyLayer {
         private readonly codeOids: Map<string, string>,
         private readonly toolchain: { id: string; uncacheable: string[] },
         private readonly scanPathsUsed: string[],
+        private readonly scope: ReadonlySet<string> | null,
         /** wall time of the WHOLE layer: toolchain identity, the module-graph
          *  closures, the git scan and the closure hashing. Reported rather
          *  than the scan alone, because the scan alone is the flattering
@@ -237,7 +241,8 @@ export class KeyLayer {
         const closureByCheck = new Map<string, string[]>()
         // computed for EVERY check with code, not only the content ones: a
         // world check's TTL cache must break when the probe itself is rewritten
-        for (const d of decls) {
+        const scoped = o.scope == null ? decls : decls.filter((d) => o.scope!.has(d.id))
+        for (const d of scoped) {
             const entries = d.code ?? []
             if (entries.length > 0) closureByCheck.set(d.id, importClosure(cfg, entries))
         }
@@ -246,14 +251,13 @@ export class KeyLayer {
         // are mostly directories, mostly unchanged, and git's stat cache
         // answers them without reading a byte.
         const paths = new Set<string>()
-        for (const d of decls) {
+        for (const d of scoped) {
             if (classify(d).population !== 'content') continue
             for (const p of d.inputs ?? []) paths.add(p)
         }
 
         // the closure is INDIVIDUAL FILES belonging to no declared path, so it
-        // goes through one `hash-object --stdin-paths` instead of one `git
-        // add` spawn per file (measured: 15ms for the whole set)
+        // is hashed in process (hashFiles) instead of staged one `git add` each
         const closureFiles = new Set<string>()
         for (const files of closureByCheck.values()) for (const f of files) closureFiles.add(f)
 
@@ -268,7 +272,7 @@ export class KeyLayer {
             // downstream may key on it. Loud, and the whole run goes uncached.
             scanError = e instanceof GitScanError ? e.message : String(e)
         }
-        return new KeyLayer(root, decls, registration, scan, scanError, closureByCheck, codeOids, toolchain, [...paths].sort(), performance.now() - started)
+        return new KeyLayer(root, decls, registration, scan, scanError, closureByCheck, codeOids, toolchain, [...paths].sort(), o.scope ?? null, performance.now() - started)
     }
 
     /** the key for one check, or the reason there is none. */
@@ -284,6 +288,7 @@ export class KeyLayer {
             codeKey: own.length === 0 || !ownReadable ? null : createHash('sha256').update(codeLines.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' }
         if (c.population === 'world') return { ...base, reason: `world check — TTL ${d.ttl}, no content key` }
         if (c.population === 'none') return { ...base, reason: c.reason ?? 'undeclared' }
         if (this.scanError != null) return { ...base, reason: `git scan failed, nothing may be keyed: ${this.scanError}` }

package/src/ledger/git-scan.ts

@@ -35,6 +35,7 @@ import { isAbsolute, join, normalize, resolve } from 'path'
 import { probeGitRoot } from '../core/git-root.ts'
 import { treePrefix } from '../core/nesting.ts'
 import { gitBin } from '../core/git-bin.ts'
+import { blobOid } from '../core/read-set.ts'
 
 /** what a scan measured. Every OID is a git object id of the CURRENT disk
  *  content, tracked or not. */
@@ -59,6 +60,14 @@ export type ScanResult = {
 
 export class GitScanError extends Error {}
 
+export type ScanOpts = {
+    /** the caller reads the whole tree's id and nothing else, so git is never
+     *  asked what it ignores: that answer only feeds force-adds and the
+     *  excluded list, and `git add -- .` leaves ignored files out by itself.
+     *  `excluded` and `ignored` come back empty */
+    treeOnly?: boolean
+}
+
 /** the scratch index FORMAT. Bump it whenever what the scan stages changes.
  *  The index is persistent, and anything staged into it stays there until
  *  something stages over it: a run that force-added a path a later version no
@@ -208,10 +217,15 @@ const underNodeModules = (p: string): boolean => p.split('/').includes('node_mod
  * stale describes files nobody has, and a key built on it is a false green
  * waiting for its first hit.
  */
-export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult): ScanResult {
+export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult, o: ScanOpts = {}): ScanResult {
     const started = performance.now()
+    if (o.treeOnly === true && (rawPaths.length !== 1 || normalizeInput(rawPaths[0]!) !== WHOLE_TREE))
+        throw new GitScanError(`treeOnly scans the whole tree and nothing else, asked for: ${rawPaths.join(', ')}`)
     const { scratch: indexFile, ignored: ignoredIndex, real: realIndex } = indexPaths(root)
     const wanted = [...new Set(rawPaths.map(normalizeInput))].sort()
+    // nothing asked for: the repo is still validated above, and no tree is
+    // written that nobody reads (a run of read checks declares no path)
+    if (wanted.length === 0) return { treeOid: '', oidByPath: new Map(), missing: [], excluded: new Map(), ignored: [], ignoredTreeOid: null, ms: performance.now() - started }
     const missing = wanted.filter((p) => !existsSync(join(root, p)))
     const present = wanted.filter((p) => existsSync(join(root, p)))
     const toAdd = dropCovered(present)
@@ -227,7 +241,9 @@ export function scanPaths(root: string, rawPaths: string[], prior?: ScanResult):
     // A path that became ignored in between makes its plain add fail, which
     // throws, and a throw stores nothing: the one failure mode stays loud.
     const sameMissing = prior != null && prior.missing.join('\n') === [...new Set(missing)].sort().join('\n')
-    const ignored = prior != null && sameMissing
+    const ignored = o.treeOnly === true
+        ? []
+        : prior != null && sameMissing
         ? prior.ignored
         : toAdd.length === 0
         ? []
@@ -363,14 +379,16 @@ function excludedBy(wanted: string[], ignored: string[], forced: Set<string>): M
 }
 
 /**
- * blob ids for a list of FILES, one process, no index, no lock.
+ * blob ids for a list of FILES, hashed in process: no git, no index, no lock.
  *
  * The scratch index is the right tool for a declared input, which is usually a
  * directory and usually unchanged (git's stat cache answers without reading).
  * It is the wrong tool for the module-graph closure: those are individual
- * files, they belong to no declared path, and staging each one would cost a
- * `git add` spawn per file. `hash-object --stdin-paths` reads them all in one
- * call and returns exactly what a blob of that content would be.
+ * files, they belong to no declared path, and a check's code is a handful of
+ * small sources that cost less to read than one spawn. The id is the blob id
+ * of the bytes on disk, the same one the read recorder uses (`blobOid`). Git
+ * would apply clean filters (eol, lfs) first, so this id is only ever STRICTER:
+ * a filter-only change is a miss, never a false hit.
  *
  * A file that is not on disk is skipped and reported, never guessed at.
  */
@@ -379,16 +397,10 @@ export function hashFiles(root: string, files: string[]): { oids: Map<string, st
     const wanted = [...new Set(files.map(normalizeInput))].sort()
     const missing = wanted.filter((f) => !existsSync(join(root, f)))
     const present = wanted.filter((f) => existsSync(join(root, f)))
-    if (present.length === 0) return { oids, missing }
-    const p = Bun.spawnSync([gitBin(), 'hash-object', '--stdin-paths'], {
-        cwd: root,
-        stdin: Buffer.from(`${present.join('\n')}\n`),
-        stdout: 'pipe',
-        stderr: 'pipe',
-    })
-    if (p.exitCode !== 0) throw new GitScanError(`git hash-object exited ${p.exitCode}: ${p.stderr.toString().trim().split('\n').slice(0, 3).join(' / ')}`)
-    const lines = p.stdout.toString().split('\n').filter((l) => l !== '')
-    if (lines.length !== present.length) throw new GitScanError(`git hash-object answered ${lines.length} of ${present.length} files`)
-    present.forEach((f, i) => oids.set(f, lines[i]!.trim()))
+    for (const f of present) {
+        try { oids.set(f, blobOid(readFileSync(join(root, f)))) } catch (e) {
+            throw new GitScanError(`cannot read ${f} to hash it: ${e instanceof Error ? e.message : String(e)}`)
+        }
+    }
     return { oids, missing }
 }

package/src/ledger/ledger.ts

@@ -92,6 +92,8 @@ export type LedgerOpts = {
     fresh?: boolean
     /** module-graph config, loaded from the repo when omitted */
     cfg?: RvtConfig
+    /** the checks this run executes (KeyLayerOpts.scope) */
+    scope?: ReadonlySet<string>
     now?: () => number
 }
 
@@ -133,7 +135,7 @@ export class Ledger {
     ) {}
 
     static open(root: string, decls: CheckDecl[], o: LedgerOpts): Ledger {
-        const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg })
+        const layer = KeyLayer.open(root, decls, { cliEntry: o.cliEntry, cfg: o.cfg, scope: o.scope })
         const fresh = o.fresh === true || process.env[FRESH_ENV] != null
         const reading = (o.read ?? ledgerReadEnabled()) && !fresh
         return new Ledger(layer, storeRoot(root), reading, o.now ?? Date.now)
@@ -166,7 +168,7 @@ export class Ledger {
         if (!this.reading) { this.misses++; return null }
         const e = readStored<Stored>(this.path(k), k.key)
         if (e == null || !Array.isArray(e.payload.lines)) { this.misses++; return null }
-        if (k.population === 'reads' && (e.payload.reads == null || this.driftOf(e.payload.reads, this.view()) != null)) { this.misses++; return null }
+        if (k.population === 'reads' && (e.payload.reads == null || this.driftOf(e.payload.reads, () => this.view()) != null)) { this.misses++; return null }
         this.hits++
         return e.payload
     }
@@ -178,8 +180,14 @@ export class Ledger {
         return readStored<Stored>(this.path(k), k.key)?.payload.reads ?? null
     }
 
-    private driftOf(reads: ReadSet, view: RepoView): string | null {
-        return readSetDrift(this.layer.root, reads, (g) => (view.fallback != null ? null : view.list(g)))
+    /** the view is asked for only when a glob needs it: a read set with no
+     *  listing is validated on file content alone, and a whole tree git scan
+     *  per replay would buy nothing */
+    private driftOf(reads: ReadSet, view: () => RepoView): string | null {
+        return readSetDrift(this.layer.root, reads, (g) => {
+            const v = view()
+            return v.fallback != null ? null : v.list(g)
+        })
     }
 
     /** where askers of this check's exact question meet while one of them is
@@ -230,11 +238,11 @@ export class Ledger {
         // a fresh list, never this run's: the question is whether the tree
         // still is what the body read
         let fresh: RepoView | null = null
+        const freshView = (): RepoView => (fresh ??= RepoView.open(this.layer.root, this.viewMemo))
         for (const [id, outcome] of this.buffered) {
             if (touched.has(id)) { discarded.push(id); continue }
             if (outcome.reads != null) {
-                fresh ??= RepoView.open(this.layer.root, this.viewMemo)
-                const moved = this.driftOf(outcome.reads, fresh)
+                const moved = this.driftOf(outcome.reads, freshView)
                 if (moved != null) { discarded.push(id); drifted.push(moved); continue }
             }
             const k = this.key(id)

package/src/ledger/repo-view.ts

@@ -23,12 +23,12 @@ export class RepoView {
         readonly scan: ScanResult | null = null,
     ) {}
 
-    /** `prior`: an earlier view of the same root in this run. Its scan
-     *  answers git's ignore question again, and the tree is still staged and
-     *  hashed fresh, so the list is today's */
+    /** `prior`: an earlier view of the same root in this run. The tree is
+     *  still staged and hashed fresh, so the list is today's, and an unchanged
+     *  tree reuses the prior's answer */
     static open(root: string, prior?: RepoView | null): RepoView {
         try {
-            const scan = scanPaths(root, [WHOLE_TREE], prior?.scan ?? undefined)
+            const scan = scanPaths(root, [WHOLE_TREE], prior?.scan ?? undefined, { treeOnly: true })
             const tree = scan.oidByPath.get(WHOLE_TREE)
             if (tree == null) throw new GitScanError('git could not name the work tree')
             return new RepoView(filesOf(root, tree), null, scan)
@@ -45,14 +45,16 @@ export class RepoView {
 }
 
 /** a tree id names its content, so its file list is a pure function of the
- *  id and one listing serves every view of that tree */
+ *  id and one listing serves every view of that tree. `--full-tree` keeps it
+ *  so: without it git filters the listing by the cwd's path under the work
+ *  tree, and a nested folder's own subtree lists nothing */
 const listed = new Map<string, string[]>()
 const LISTED_MAX = 64
 
 function filesOf(root: string, tree: string): string[] {
     const hit = listed.get(tree)
     if (hit != null) return hit
-    const p = Bun.spawnSync([gitBin(), 'ls-tree', '-r', '-z', '--name-only', tree], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    const p = Bun.spawnSync([gitBin(), 'ls-tree', '--full-tree', '-r', '-z', '--name-only', tree], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
     if (p.exitCode !== 0) throw new GitScanError(`git ls-tree exited ${p.exitCode}: ${p.stderr.toString().trim()}`)
     const files = p.stdout.toString().split('\0').filter((f) => f !== '').sort()
     if (listed.size >= LISTED_MAX) listed.delete(listed.keys().next().value!)

package/src/ledger/run-log.ts

@@ -21,7 +21,7 @@
 import { Database } from 'bun:sqlite'
 import { existsSync } from 'fs'
 import type { Line } from '../core/wire.ts'
-import { dbPath, INSERT_RUN, openDb, UPSERT_INVOCATION, UPSERT_LAST, UPSERT_LIVE } from './db.ts'
+import { BUSY_MS, dbPath, INSERT_RUN, openDb, UPSERT_INVOCATION, UPSERT_LAST, UPSERT_LIVE } from './db.ts'
 import { LIVE_BEAT_MS, liveRowDead, type LiveRow, type LiveState } from './live-runs.ts'
 import { KEEP_MS } from './store.ts'
 
@@ -187,10 +187,16 @@ export class RunLog {
         const hadLive = this.liveSent !== ''
         this.quiet()
         this.liveSent = ''
-        try { this.liveDb?.close() } catch { /* already gone */ }
+        // the live row's handle writes the run too: an open and a close are
+        // most of what a write costs. It waits like a fresh one would
+        const live = this.liveDb
         this.liveDb = null
-        if (this.path === '' || (rows.length === 0 && last.length === 0 && !hadLive)) return []
-        const opened = openDb(this.path, { busyMs: this.busyMs })
+        if (this.path === '' || (rows.length === 0 && last.length === 0 && !hadLive)) { try { live?.close() } catch { /* already gone */ } return [] }
+        let opened: { db: Database } | null = null
+        if (live != null) {
+            try { live.exec(`pragma busy_timeout = ${Math.max(0, Math.round(this.busyMs ?? BUSY_MS))}`); opened = { db: live } } catch { try { live.close() } catch { /* already gone */ } }
+        }
+        opened ??= openDb(this.path, { busyMs: this.busyMs })
         if (opened == null) return unwritable(this.path)
         try {
             const insert = opened.db.query(INSERT_RUN)

package/src/ledger/run-timeline.ts

@@ -45,7 +45,9 @@ export type TimelineInvocation = {
 /** an invocation in a list: its numbers without its lanes */
 export type InvocationSummary = Omit<TimelineInvocation, 'bars'> & { checks: number }
 
-export type SlowCheck = { id: string; meanMs: number; worstMs: number; samples: number; ceilingMs: number | null; flag: 'over' | 'near' | null }
+/** `over` its ceiling, `near` it (past half), or over its `budget` on the
+ *  mean of its quick tier runs */
+export type SlowCheck = { id: string; meanMs: number; worstMs: number; samples: number; ceilingMs: number | null; budgetMs: number | null; flag: 'over' | 'near' | 'budget' | null }
 
 export type SuiteToFix = {
     check: string; unit: string; file: string; at: number; ms: number; budgetMs: number; tier: 'quick' | 'full'; red: boolean; slow: boolean
@@ -72,6 +74,8 @@ export type TimelineInput = {
     suites: SuiteRow[]
     /** each check's kill time, ms */
     ceilings: Record<string, number>
+    /** each check's resolved budget (core/budget.ts), for the slowest list */
+    budgets?: Record<string, number>
     /** the checks the repo declares today. Given, `slowest` lists only these:
      *  a deleted check's rows stay in the run history, and no edit can make it
      *  faster */
@@ -120,23 +124,31 @@ export function invocationsOf(runs: RunRow[], invocations: InvocationRow[]): Tim
 }
 
 /** the checks that cost the most when they really run: mean and worst of the
- *  MEASURED runs, flagged when the worst reached its ceiling or half of it */
-export function slowestChecks(runs: RunRow[], ceilings: Record<string, number>, size = TIMELINE_LIST, inventory?: readonly string[]): SlowCheck[] {
+ *  MEASURED runs, flagged when the worst reached its ceiling or half of it,
+ *  else when the mean of its QUICK tier runs is over its budget (the full
+ *  tier runs every slow suite on purpose, and is never judged) */
+export function slowestChecks(runs: RunRow[], ceilings: Record<string, number>, size = TIMELINE_LIST, inventory?: readonly string[], budgets: Record<string, number> = {}): SlowCheck[] {
     const live = inventory == null ? null : new Set(inventory)
     const ms = new Map<string, number[]>()
+    const quick = new Map<string, number[]>()
+    const add = (m: Map<string, number[]>, id: string, v: number): void => { m.set(id, [...(m.get(id) ?? []), v]) }
     for (const r of runs) {
         if (r.replayed || r.status === 'skip') continue
         if (live != null && !live.has(r.id)) continue
-        const list = ms.get(r.id) ?? []
-        list.push(r.ms)
-        ms.set(r.id, list)
+        add(ms, r.id, r.ms)
+        if (r.full !== true) add(quick, r.id, r.ms)
     }
+    const mean = (list: number[]): number => Math.round(list.reduce((a, b) => a + b, 0) / list.length)
     const out: SlowCheck[] = []
     for (const [id, list] of ms) {
         const worstMs = Math.max(...list)
         const ceilingMs = ceilings[id] ?? null
-        const flag = ceilingMs == null ? null : worstMs >= ceilingMs ? 'over' : worstMs > ceilingMs * NEAR_CEILING_SHARE ? 'near' : null
-        out.push({ id, meanMs: Math.round(list.reduce((a, b) => a + b, 0) / list.length), worstMs, samples: list.length, ceilingMs, flag })
+        const budgetMs = budgets[id] ?? null
+        const q = quick.get(id) ?? []
+        const flag = ceilingMs != null && worstMs >= ceilingMs ? 'over'
+            : ceilingMs != null && worstMs > ceilingMs * NEAR_CEILING_SHARE ? 'near'
+                : budgetMs != null && q.length > 0 && mean(q) > budgetMs ? 'budget' : null
+        out.push({ id, meanMs: mean(list), worstMs, samples: list.length, ceilingMs, budgetMs, flag })
     }
     return out.sort((a, b) => b.meanMs - a.meanMs || a.id.localeCompare(b.id)).slice(0, size)
 }
@@ -164,7 +176,7 @@ export function shapeTimeline(o: TimelineInput): Timeline {
     const size = o.listSize ?? TIMELINE_LIST
     return {
         invocations: all.slice(0, o.keep ?? TIMELINE_INVOCATIONS),
-        slowest: slowestChecks(o.runs, o.ceilings, size, o.inventory),
+        slowest: slowestChecks(o.runs, o.ceilings, size, o.inventory, o.budgets),
         longest: [...all].sort((a, b) => b.wallMs - a.wallMs || b.started - a.started).slice(0, size).map(({ bars, ...rest }) => ({ ...rest, checks: bars.length })),
         testFiles: testFilesToFix(o.suites, o.declaredSlow),
         suitesRecorded: o.suites.length > 0,

package/src/problems/problem-board.ts

@@ -2,10 +2,21 @@
 // asked about three checks replaces those three and leaves the rest standing:
 // vscode clears the whole pane at every frame, so a narrowed run that printed
 // only its own findings would erase every other check's.
-import { frameLines, type Problem } from './problem-line.ts'
+import type { HubProblem } from '../serve/hub-problems.ts'
+import { frameLines, hubProblemLine, type Problem } from './problem-line.ts'
 
 export class ProblemBoard {
     private readonly byCheck = new Map<string, Problem[]>()
+    private hub: Problem[] = []
+
+    /** what is wrong with the hub itself (serve/hub-problems.ts), which no
+     *  check owns. Returns whether the board moved */
+    setHub(problems: HubProblem[]): boolean {
+        const next = problems.map(hubProblemLine)
+        const moved = JSON.stringify(next) !== JSON.stringify(this.hub)
+        this.hub = next
+        return moved
+    }
 
     /** a check reached a verdict. What it carries has already passed the pane
      *  rule (problem-line.ts feedsProblemsPane), so an empty list clears it */
@@ -17,7 +28,7 @@ export class ProblemBoard {
     /** every finding standing, sorted by file then line, so a frame reads the
      *  same whatever order the checks finished in */
     all(): Problem[] {
-        return [...this.byCheck.values()].flat().sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col || a.check.localeCompare(b.check))
+        return [...this.hub, ...this.byCheck.values()].flat().sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.col - b.col || a.check.localeCompare(b.check))
     }
 
     /** one check's verdict, as the runner reports it. A skip is no verdict

package/src/problems/problem-line.ts

@@ -39,6 +39,15 @@ export const ENDS_PATTERN = `^${FRAME_END_HEAD}\\b`
  *  (`imports:check`) both split right */
 export const PROBLEM_PATTERN = '^(.+?):(\\d+):(\\d+): (error|warning) (\\S+?): (.*)$'
 
+/** where a problem of the hub itself is anchored: it has no file, and the
+ *  matcher needs one, so it sits on line 1 of the file that declares the
+ *  hub. Check id `hub` */
+export const HUB_ANCHOR = 'repo.config.ts'
+
+export function hubProblemLine(p: { text: string; severity: 'red' | 'yellow' }): Problem {
+    return { file: HUB_ANCHOR, line: 1, col: 1, severity: p.severity === 'red' ? 'error' : 'warning', check: 'hub', message: p.text }
+}
+
 export function formatProblem(p: Problem): string {
     const message = p.message.replace(/\s*\n\s*/g, ' ').trim()
     return `${p.file}:${p.line}:${p.col}: ${p.severity} ${p.check}: ${message}`

package/src/repo-config.ts

@@ -20,6 +20,7 @@ import { validateSmokeConfig, type SmokeConfig } from './smoke/run-smoke.ts'
 import { RULE_ID_RE, validateRules } from './rules/rule.ts'
 import { builtinCheckIds } from './core/discover-checks.ts'
 import { parseWhen } from './core/when.ts'
+import { budgetValueProblem } from './core/budget.ts'
 import type { Rule } from './check.ts'
 import { leakAllowProblems } from './hooks/leak-guard.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
@@ -104,6 +105,14 @@ export type RepoConfig = {
          *  Its last recorded run, from a gate or a health pass, is the secret's
          *  verdict. Absent: no check probes it, and the row says so */
         probedBy?: string
+        /** how much breaks without it, which decides its colour when it is
+         *  missing or its probe fails. `core`: the toolkit's own features stop
+         *  (a push, creating a repo, a release), so it is red, and a missing
+         *  one reaches `shipkit needs` as red. `used`: a feature this repo uses today, so
+         *  it is orange, a needs line that never pings. `minor`: proactive,
+         *  for something nothing uses yet, so it is dim and stays out of
+         *  `shipkit needs`. Default `used` */
+        level?: 'core' | 'used' | 'minor'
     }[]
     /** store-command template for a missing secret tile, `{name}` substituted, as in your secret manager's set command */
     credsCommand?: string
@@ -144,6 +153,12 @@ export type RepoConfig = {
      *  reason, and on an id no check carries. The hub writes this
      *  map through the managed block in this file (core/when-block.ts). */
     when?: Record<string, string>
+    /** WHAT A HEALTHY RUN OF EACH CHECK TAKES, in ms, keyed by check id. A
+     *  check that passes over its budget prints a WARN and reads yellow, and
+     *  never blocks. It wins over the check's own `budgetMs` and the default
+     *  for its kind (core/budget.ts). An id no check carries fails the run,
+     *  the same as a `when` entry. */
+    budgets?: Record<string, number>
     /** DEPRECATED, read into `when` as `off:<reason>`: rule id → the reason
      *  this repo breaks that invariant on purpose. An exempted rule does not
      *  lint and prints a skip line carrying the reason. `defineRepo` throws on
@@ -241,7 +256,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -319,6 +334,12 @@ export function defineRepo(c: RepoConfig): RepoConfig {
         if (RULE_ID_RE.test(id) && !builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))
             throw new Error(`defineRepo: when.${id} names no rule, the ids are in \`shipkit checks\``)
     }
+    // a budget turns a slow pass yellow, so a value it cannot compare with dies here
+    for (const [id, v] of Object.entries(c.budgets ?? {})) {
+        if (id.trim() === '') throw new Error(`defineRepo: budgets has an entry with no check id`)
+        const bad = budgetValueProblem(v)
+        if (bad != null) throw new Error(`defineRepo: budgets.${id} ${bad}`)
+    }
     // an exemption silences a gate, so it names a rule that exists and says why
     for (const [id, reason] of Object.entries(c.ruleExempt ?? {})) {
         if (!builtinCheckIds().includes(id) && !(c.rules ?? []).some((r) => r.id === id))

package/src/serve/hub-app/check-view.tsx

@@ -47,10 +47,10 @@ const VERDICT_WORD: Record<'pass' | 'warn' | 'fail' | 'skip', string> = {
 // ── the pieces ───────────────────────────────────────────────────────────
 
 /** one duration, in the one unit, in the one tone */
-const Dur = ({ ms, ceiling }: { ms: number | null | undefined; ceiling?: number }) =>
+const Dur = ({ ms, ceiling, budget }: { ms: number | null | undefined; ceiling?: number; budget?: number }) =>
     ms == null
         ? <span className="dim">not timed yet</span>
-        : <span className={`dnum ${durationTone(ms, ceiling) ?? ''}`}>{fmtMs(ms)}</span>
+        : <span className={`dnum ${durationTone(ms, ceiling, budget) ?? ''}`}>{fmtMs(ms)}</span>
 
 const MdHelp = ({ text }: { text: string }) => <Help text={<span className="md" dangerouslySetInnerHTML={{ __html: renderMd(text) }} />} />
 
@@ -177,14 +177,14 @@ const RunWhen = observer(({ app, u }: { app: HubSt; u: CheckFacts }) => {
 
 /** the last N outcomes as a bar row: an average hides the shape, and the
  *  reds it cannot even see */
-const Bars = ({ runs, ceiling }: { runs: RecentRun[]; ceiling: number }) => {
+const Bars = ({ runs, ceiling, budget }: { runs: RecentRun[]; ceiling: number; budget: number }) => {
     if (runs.length === 0) return <div className="dim">no run on record yet</div>
     const top = Math.max(...runs.map((r) => r.ms), 1)
     return (
         <div className="bars">
             {runs.map((r, n) => (
                 <i key={`${r.at}-${n}`}
-                    className={`bar ${r.replayed ? 'rep' : r.status === 'fail' ? 'red' : r.status === 'warn' ? 'warn' : r.status === 'skip' ? 'rep' : durationTone(r.ms, ceiling) ?? 'plain'}`}
+                    className={`bar ${r.replayed ? 'rep' : r.status === 'fail' ? 'red' : r.status === 'warn' ? 'warn' : r.status === 'skip' ? 'rep' : durationTone(r.ms, ceiling, budget) ?? 'plain'}`}
                     style={{ height: `${r.replayed ? 8 : Math.max(10, Math.round((r.ms / top) * 100))}%` }}
                     title={`${stampWords(r.at)}: ${r.replayed ? CACHED : `${VERDICT_WORD[r.status]} in ${fmtMs(r.ms)}`}`} />
             ))}
@@ -200,22 +200,23 @@ export const LastRunValue = observer(({ app, u }: { app: HubSt; u: CheckFacts })
         <>
             <span className={`tl ${l.tone}`}>{l.word}</span>
             {u.lastAt == null ? null : <> <TimeAgo clock={app.clock} at={u.lastAt} /></>}
-            {u.lastMs == null || u.replayed ? null : <> in <Dur ms={u.lastMs} ceiling={u.timeoutMs} /></>}
+            {u.lastMs == null || u.replayed ? null : <> in <Dur ms={u.lastMs} ceiling={u.timeoutMs} budget={u.budgetMs} /></>}
             {l.verdict == null ? null : <span className={`tl ${l.tone}`}>, {l.verdict}</span>}
         </>
     )
 })
 
 export const Timings = ({ u }: { u: CheckFacts }) => (
-    <Row k="timings" wide help="what this check costs: its last run, the mean of the runs that really ran, the worst one on record, and the limit it is killed at">
+    <Row k="timings" wide help="what this check costs: its last run, the mean of the runs that really ran, the worst one on record, what a healthy run takes, and the limit it is killed at">
         <span className="ctimes">
-            <span><span className="ck">last</span> <Dur ms={u.lastMs} ceiling={u.timeoutMs} /></span>
-            <span><span className="ck">average</span> {u.samples === 0 ? <span className="dim">not timed yet</span> : <><Dur ms={u.avgMs} ceiling={u.timeoutMs} /> <span className="dim">over {u.samples}</span></>}</span>
-            <span><span className="ck">slowest</span> <Dur ms={u.slowestMs} ceiling={u.timeoutMs} />{u.failures > 0 ? <span className="dim">, {u.failures} red</span> : null}</span>
-            {/* a limit, never a measurement: it wears no tone of its own */}
+            <span><span className="ck">last</span> <Dur ms={u.lastMs} ceiling={u.timeoutMs} budget={u.budgetMs} /></span>
+            <span><span className="ck">average</span> {u.samples === 0 ? <span className="dim">not timed yet</span> : <><Dur ms={u.avgMs} ceiling={u.timeoutMs} budget={u.budgetMs} /> <span className="dim">over {u.samples}</span></>}</span>
+            <span><span className="ck">slowest</span> <Dur ms={u.slowestMs} ceiling={u.timeoutMs} budget={u.budgetMs} />{u.failures > 0 ? <span className="dim">, {u.failures} red</span> : null}</span>
+            {/* a budget and a limit, never measurements: they wear no tone of their own */}
+            <span><span className="ck">budget</span> <span className="dnum dim">{fmtMs(u.budgetMs)}</span> <Help term="budget" /></span>
             <span><span className="ck">limit</span> <span className="dnum dim">{fmtMs(u.timeoutMs)}</span> <Help term="ceiling" /></span>
         </span>
-        <Bars runs={u.recent ?? []} ceiling={u.timeoutMs} />
+        <Bars runs={u.recent ?? []} ceiling={u.timeoutMs} budget={u.budgetMs} />
     </Row>
 )