rvlib-shipkit 0.38.0 → 1.0.0

package/src/collections/reflections.ts

@@ -0,0 +1,41 @@
+// reflections collection — this repo's own `.shipkit/reflections/` queue: the
+// friction it logged against the wiki it follows, one row per file still
+// waiting to be folded into its owning page and deleted. Orange, always: the
+// file waits on a human process and nothing here is broken, so it reaches
+// the needs feed and never the red pings. The seed README is not a row.
+import { join } from 'path'
+import { listReflections, REFLECTIONS_DIR } from '../reflections/reflections-queue.ts'
+import type { Collection, Instance } from './collection-types.ts'
+import { mdBody } from './md-body.ts'
+
+export function reflectionsCollection(root: string): Collection {
+    return {
+        id: 'reflections',
+        title: 'reflections',
+        media: 'text',
+        list: async () =>
+            listReflections(root).map((r): Instance => {
+                const path = `${REFLECTIONS_DIR}/${r.file}`
+                const shape = r.unreadable
+                    ? 'UNREADABLE'
+                    : !r.isRequest
+                        ? 'note'
+                        : r.missing.length === 0
+                            ? 'change request'
+                            : `change request, MISSING: ${r.missing.join(', ')}`
+                return {
+                    id: `reflection:${r.file}`,
+                    text: `${path} — ${shape}: ${r.title}`,
+                    // the tree row is the line whoever logged it wrote, and
+                    // the shape sits in the slot beside it
+                    label: r.title,
+                    slot: r.unreadable ? 'unreadable' : r.isRequest ? 'request' : 'note',
+                    type: 'reflection',
+                    path,
+                    file: path,
+                    severity: 'yellow',
+                    md: mdBody(join(root, path)),
+                }
+            }),
+    }
+}

package/src/collections/state-rules.ts

@@ -0,0 +1,73 @@
+// WHAT COLOUR A ROW IS, one pure rule per kind, in ONE file. The answer used
+// to be spread over the providers that happened to build the instance, so a
+// kind could be red on the tree and yellow in the feed, and a kind nobody
+// wrote a rule for came out white.
+//
+// Two axes, and they are not the same axis. `state` is the colour on the
+// tree. `severity` is what reaches `shipkit needs` and the once ever ping
+// (red pings, yellow never does). A rule that wants colour WITHOUT a feed
+// line returns a bare `state`, which is how "nothing measured this" says so
+// on screen and stays out of a queue of things asking for his hands.
+import type { Instance } from './collection-types.ts'
+
+export type StateRule = Pick<Instance, 'state' | 'severity'>
+
+/** what a hub row needs to know about one asset */
+export type AssetFacts = { manual: boolean; rolls: number; picked: boolean; stale: boolean }
+
+/** THE asset rule: a pick is a decision made, so it reads green. Rolls with
+ *  nothing picked is taste pending, a stale pick is the same question asked
+ *  again, a manual asset with nothing uploaded is broken, and an asset nobody
+ *  has generated yet is plain */
+export const assetState = (f: AssetFacts): StateRule => {
+    if (f.manual && f.rolls === 0) return { severity: 'red' }
+    if (f.rolls === 0) return {}
+    if (!f.picked || f.stale) return { severity: 'yellow' }
+    return { state: 'ok' }
+}
+
+/** what the run record says about ONE secret, through the check that
+ *  probes it (`creds[].probedBy`):
+ *  pass        its last run passed, inside its ttl
+ *  fail        its last run failed
+ *  warn        its last run warned, or it names a check this repo lacks
+ *  stale       it passed, and the pass is older than the check's ttl
+ *  unmeasured  it never ran here, was skipped, or said it did not measure
+ *  none        no check probes this secret */
+export type SecretProbe = 'pass' | 'fail' | 'warn' | 'stale' | 'unmeasured' | 'none'
+
+/** THE secret rule. Being there is half the answer and working is the other
+ *  half, so present plus a probe that passed is the only green. A value that
+ *  is there and fails its probe is red on the tree, and its feed line stays
+ *  yellow: the probing check does not block, and its own row already carries
+ *  the same failure. A pass past its ttl, or a probe that never measured, is
+ *  plain: nothing is known to be wrong. A secret no check probes is dim,
+ *  because there is no verdict to wait for. Missing while a page requires it
+ *  is the broken case, whatever any probe said */
+export const secretState = (f: { missing: boolean; probe: SecretProbe }): StateRule => {
+    if (f.missing) return { severity: 'red' }
+    if (f.probe === 'pass') return { state: 'ok' }
+    if (f.probe === 'fail') return { state: 'red', severity: 'yellow' }
+    if (f.probe === 'warn') return { severity: 'yellow' }
+    if (f.probe === 'none') return { state: 'quiet' }
+    return { state: 'idle' }
+}
+
+/** THE graph rule: a graph is valid or it is not, and lint says which. Clean
+ *  is a measured pass, anything else is red on the tree. The feed line is
+ *  yellow, because a dangling link is work and never a reason to ping. A graph
+ *  whose lint belongs to another repo is never double judged here, so it
+ *  claims no colour at all */
+export const graphState = (f: { lint: boolean; issues: number }): StateRule => {
+    if (!f.lint) return {}
+    return f.issues > 0 ? { state: 'red', severity: 'yellow' } : { state: 'ok' }
+}
+
+/** a graph judged by the repo's own checks: red when one of them last
+ *  failed, green when every one has a verdict and none failed. Each check
+ *  carries its own feed line already, so the graph adds none. Nothing
+ *  measured yet claims no colour */
+export const graphChecksState = (last: (string | null)[]): StateRule => {
+    if (last.some((s) => s === 'fail')) return { state: 'red' }
+    return last.length > 0 && last.every((s) => s != null) ? { state: 'ok' } : {}
+}

package/src/collections/test-time.ts

@@ -0,0 +1,288 @@
+// WHERE A TEST CHECK'S TIME GOES: the page behind a `test` / `test:<unit>`
+// group of the tree, and the `tests` page above them. Pure over what the
+// caller read: the test files as the tests collection shaped them, the run
+// record (the check's own wall time) and the suite runner's own record (its
+// phases, its workers).
+//
+// Nothing here decides what is red: a file is failing when its TestFacts
+// carry the testFilesToFix verdict (ledger/run-timeline.ts), the same one the
+// tree and the runs page tab read.
+import type { RunRow } from '../ledger/run-log.ts'
+import type { SuiteRunRow } from '../ledger/suite-log.ts'
+import { testId, type TestFacts, type TestRun } from './collection-types.ts'
+
+/** past this share of the parallel phase, one file IS the wall */
+export const TAIL_SHARE = 0.6
+/** under this share of the wall, the file phases are not where it goes */
+export const FILES_SHARE = 0.5
+/** past this share of the workers, the files keep the pool busy */
+export const BUSY_SHARE = 0.6
+/** how far after the runner wrote its rows the check that hosted it may end
+ *  and still be that run */
+const HOST_WINDOW_MS = 120_000
+/** a trend arrow needs a real move: this share of the average, and this much */
+const TREND_SHARE = 0.2
+const TREND_MIN_MS = 50
+
+export type Trend = 'up' | 'down' | 'flat'
+
+export type FileTime = {
+    file: string
+    /** the resource id its page opens by */
+    id: string
+    inUnit: string
+    /** the last recorded duration in the shared run, null when it never ran
+     *  here */
+    ms: number | null
+    /** the time the budget judged, when an alone rerun replaced it (its own
+     *  CPU, or its wall alone). null when it is `ms` */
+    judgedMs: number | null
+    at: number | null
+    /** CPU it burned alone, when a process ran it alone */
+    cpuMs: number | null
+    /** it ran in the check's last run, so it has a share of it */
+    inLastRun: boolean
+    /** of the sum of file times of that last run, 0..1 */
+    share: number | null
+    budgetMs: number
+    /** a quick run over its budget, on a file the quick tier holds to one */
+    over: boolean
+    /** mean of its earlier recorded runs in the same tier */
+    avgMs: number | null
+    trend: Trend | null
+    tier: 'quick' | 'full'
+    phase: string | null
+    status: 'pass' | 'fail' | null
+}
+
+export type FailingFile = {
+    file: string
+    id: string
+    inUnit: string
+    check: string | null
+    at: number | null
+    ms: number | null
+    failLine: string | null
+}
+
+export type Shape = 'tail' | 'volume' | 'overhead'
+
+export type Phases = {
+    /** the runner before its first phase: probing bun, the bunfig, the pool */
+    setupMs: number
+    parallelMs: number
+    parallelCpuMs: number | null
+    /** 0 = one file at a time */
+    workers: number
+    serialMs: number | null
+    serialFiles: number
+    /** the over budget files, run again alone before they can fail */
+    aloneMs: number
+    aloneFiles: number
+    /** the runner, first line to the record write */
+    runnerMs: number
+    /** the check's wall minus the runner's: the process that hosts it, its
+     *  start and its module load. null when the check's run is not on record */
+    hostMs: number | null
+    load1: number | null
+    cores: number | null
+}
+
+export type LastRun = {
+    at: number
+    files: number
+    /** the sum of every file's time in that run */
+    sumMs: number
+    /** the check's own wall time for that run, else the runner's */
+    wallMs: number | null
+    wallFrom: 'check' | 'runner' | null
+    workers: number | null
+    /** sum / wall: how many files ran at once on average */
+    ratio: number | null
+    shape: Shape | null
+    /** the verdict, in one sentence */
+    shapeWords: string
+    top: { file: string; id: string; inUnit: string; ms: number; share: number }[]
+    phases: Phases | null
+    /** the whole summary as one line, for a terminal or an agent */
+    line: string
+}
+
+export type TestCheckView = {
+    checkId: string
+    last: LastRun | null
+    failing: FailingFile[]
+    /** every file the check runs, slowest first, the never ran ones last */
+    files: FileTime[]
+}
+
+export type TestCheckRow = {
+    checkId: string
+    files: number
+    failing: number
+    at: number | null
+    wallMs: number | null
+    sumMs: number | null
+    slowest: { file: string; id: string; inUnit: string; ms: number } | null
+    shape: Shape | null
+}
+
+export type TestsRootView = {
+    /** slowest wall first, the never ran ones last */
+    checks: TestCheckRow[]
+    failing: FailingFile[]
+}
+
+export type TestTimeInput = {
+    facts: TestFacts[]
+    runs: RunRow[]
+    suiteRuns: SuiteRunRow[]
+}
+
+const ms0 = (n: number): string => `${Math.round(n)}ms`
+const pct = (n: number): string => `${Math.round(n * 100)}%`
+
+/** what a file cost the shared run: its phase wall, where the record kept it */
+const costOf = (r: TestRun): number => r.phaseMs ?? r.ms
+
+const ranIn = (checkId: string) => (f: TestFacts): boolean => f.checkId === checkId && f.standing === 'runs'
+
+function trendOf(f: TestFacts): { avgMs: number | null; trend: Trend | null } {
+    const [last, ...rest] = f.runs
+    if (last == null) return { avgMs: null, trend: null }
+    const same = rest.filter((r) => r.tier === last.tier)
+    if (same.length === 0) return { avgMs: null, trend: null }
+    const avgMs = same.reduce((n, r) => n + costOf(r), 0) / same.length
+    const d = costOf(last) - avgMs
+    const moved = Math.abs(d) > avgMs * TREND_SHARE && Math.abs(d) > TREND_MIN_MS
+    return { avgMs: Math.round(avgMs), trend: !moved ? 'flat' : d > 0 ? 'up' : 'down' }
+}
+
+export function failingOf(facts: TestFacts[]): FailingFile[] {
+    return facts
+        .filter((f) => f.toFix?.red === true)
+        .map((f) => ({ file: f.file, id: testId(f.file), inUnit: f.inUnit, check: f.checkId, at: f.runs[0]?.at ?? null, ms: f.runs[0]?.ms ?? null, failLine: f.runs[0]?.failLine ?? null }))
+        .sort((a, b) => (a.check ?? '').localeCompare(b.check ?? '') || a.file.localeCompare(b.file))
+}
+
+/** the check's own measured run that hosted the runner run ending at `at` */
+function hostRun(runs: RunRow[], checkId: string, at: number): RunRow | null {
+    let best: RunRow | null = null
+    for (const r of runs) {
+        if (r.id !== checkId || r.replayed || r.status === 'skip') continue
+        if (r.at < at || r.at - at > HOST_WINDOW_MS) continue
+        if (best == null || r.at < best.at) best = r
+    }
+    return best
+}
+
+/** the verdict, and the one sentence that says it. In order: the file
+ *  phases are not where the wall goes (then the biggest other part is named),
+ *  one file sets the phase, the files keep the workers busy, or the workers
+ *  mostly wait */
+function verdict(o: { top: { inUnit: string; ms: number }; sumMs: number; wallMs: number | null; workers: number | null; sr: SuiteRunRow | null; hostMs: number | null }): { shape: Shape; words: string } | null {
+    const files = o.sr == null ? null : o.sr.parallelMs + (o.sr.serialMs ?? 0)
+    if (o.sr != null && files != null && o.wallMs != null && files < o.wallMs * FILES_SHARE) {
+        const parts: [string, number][] = [
+            [`running ${o.sr.aloneFiles} over budget files again alone takes ${ms0(o.sr.aloneMs)}`, o.sr.aloneMs],
+            [`the runner's setup takes ${ms0(o.sr.setupMs)}`, o.sr.setupMs],
+            [`the process around the runner takes ${ms0(o.hostMs ?? 0)}`, o.hostMs ?? 0],
+            [`the runner's own bookkeeping takes ${ms0(o.sr.wallMs - o.sr.setupMs - files - o.sr.aloneMs)}`, o.sr.wallMs - o.sr.setupMs - files - o.sr.aloneMs],
+        ]
+        const [what] = parts.sort((a, b) => b[1] - a[1])[0]!
+        return { shape: 'overhead', words: `outside the files: they run in ${ms0(files)} of the ${ms0(o.wallMs)} wall, and ${what}` }
+    }
+    const span = o.sr?.parallelMs ?? o.wallMs
+    if (span == null || span <= 0) return null
+    if (o.top.ms >= span * TAIL_SHARE) return { shape: 'tail', words: `a long tail: ${o.top.inUnit} alone takes most of the wall, so faster others change nothing` }
+    const workers = Math.max(1, o.workers ?? 1)
+    if (o.sumMs / span >= workers * BUSY_SHARE)
+        return { shape: 'volume', words: `volume: the files keep ${o.workers == null || o.workers === 0 ? 'the runner' : `all ${o.workers} workers`} busy, so the wall is the sum, cut the sum` }
+    return { shape: 'overhead', words: `the ${workers} workers mostly wait: the files are few or short, and the wall is fixed cost around them` }
+}
+
+export function shapeTestCheck(checkId: string, o: TestTimeInput): TestCheckView {
+    const mine = o.facts.filter(ranIn(checkId))
+    const lastAt = mine.reduce<number | null>((m, f) => (f.runs[0] == null ? m : m == null ? f.runs[0].at : Math.max(m, f.runs[0].at)), null)
+    const inLast = lastAt == null ? [] : mine.filter((f) => f.runs[0]?.at === lastAt)
+    const sumMs = inLast.reduce((n, f) => n + costOf(f.runs[0]!), 0)
+
+    const files: FileTime[] = mine.map((f) => {
+        const r = f.runs[0]
+        const inLastRun = r != null && r.at === lastAt
+        return {
+            file: f.file,
+            id: testId(f.file),
+            inUnit: f.inUnit,
+            ms: r == null ? null : costOf(r),
+            judgedMs: r == null || r.phaseMs == null || r.phaseMs === r.ms ? null : r.ms,
+            at: r?.at ?? null,
+            cpuMs: r?.cpuMs ?? null,
+            inLastRun,
+            share: inLastRun && sumMs > 0 ? costOf(r) / sumMs : null,
+            budgetMs: f.budgetMs,
+            over: r != null && r.tier === 'quick' && f.tier === 'quick' && r.ms > f.budgetMs,
+            ...trendOf(f),
+            tier: f.tier,
+            phase: r?.phase == null || r.phase === '' ? null : r.phase,
+            status: r?.status ?? null,
+        }
+    }).sort((a, b) => (b.ms ?? -1) - (a.ms ?? -1) || a.file.localeCompare(b.file))
+
+    return { checkId, last: lastAt == null ? null : lastRunOf(checkId, lastAt, files, sumMs, o), failing: failingOf(mine), files }
+}
+
+function lastRunOf(checkId: string, at: number, files: FileTime[], sumMs: number, o: TestTimeInput): LastRun {
+    const ran = files.filter((f) => f.inLastRun)
+    const sr = [...o.suiteRuns].reverse().find((r) => r.check === checkId && r.at === at) ?? null
+    const host = hostRun(o.runs, checkId, at)
+    const wallMs = host?.ms ?? sr?.wallMs ?? null
+    const wallFrom = host != null ? 'check' : sr != null ? 'runner' : null
+    const workers = sr?.workers ?? null
+    const ratio = wallMs != null && wallMs > 0 ? sumMs / wallMs : null
+    const top = ran.slice(0, 3).map((f) => ({ file: f.file, id: f.id, inUnit: f.inUnit, ms: f.ms!, share: f.share ?? 0 }))
+    const hostMs = host == null || sr == null ? null : Math.max(0, host.ms - sr.wallMs)
+    const v = top[0] == null ? null : verdict({ top: top[0], sumMs, wallMs, workers, sr, hostMs })
+    const shape = v?.shape ?? null
+    const shapeWords = v?.words ?? 'not enough recorded to say'
+    const phases: Phases | null = sr == null ? null : {
+        setupMs: sr.setupMs,
+        parallelMs: sr.parallelMs,
+        parallelCpuMs: sr.parallelCpuMs,
+        workers: sr.workers,
+        serialMs: sr.serialMs,
+        serialFiles: sr.serialFiles,
+        aloneMs: sr.aloneMs,
+        aloneFiles: sr.aloneFiles,
+        runnerMs: sr.wallMs,
+        hostMs,
+        load1: sr.load1,
+        cores: sr.cores,
+    }
+    const line = [
+        `${ran.length} files, sum ${ms0(sumMs)}`,
+        wallMs == null ? 'wall not recorded' : `wall ${ms0(wallMs)}${wallFrom === 'runner' ? ' (runner)' : ''}`,
+        workers == null ? null : workers === 0 ? 'one at a time' : `${workers} workers`,
+        ratio == null ? null : `sum/wall ${ratio.toFixed(1)}x`,
+    ].filter((x) => x != null).join(', ') + `: ${shapeWords}. top ${top.length}: ${top.map((t) => `${t.inUnit} ${ms0(t.ms)} (${pct(t.share)})`).join(', ')}`
+    return { at, files: ran.length, sumMs, wallMs, wallFrom, workers, ratio, shape, shapeWords, top, phases, line }
+}
+
+export function shapeTestsRoot(o: TestTimeInput): TestsRootView {
+    const ids = [...new Set(o.facts.filter((f) => f.standing === 'runs' && f.checkId != null).map((f) => f.checkId!))]
+    const checks = ids.map((checkId): TestCheckRow => {
+        const v = shapeTestCheck(checkId, o)
+        const top = v.files.find((f) => f.ms != null)
+        return {
+            checkId,
+            files: v.files.length,
+            failing: v.failing.length,
+            at: v.last?.at ?? null,
+            wallMs: v.last?.wallMs ?? null,
+            sumMs: v.last?.sumMs ?? null,
+            slowest: top == null ? null : { file: top.file, id: top.id, inUnit: top.inUnit, ms: top.ms! },
+            shape: v.last?.shape ?? null,
+        }
+    }).sort((a, b) => (b.wallMs ?? -1) - (a.wallMs ?? -1) || a.checkId.localeCompare(b.checkId))
+    return { checks, failing: failingOf(o.facts) }
+}

package/src/collections/tests.ts

@@ -0,0 +1,181 @@
+// THE TEST FILES, one resource each: every file bun would discover, filed
+// under the test check that runs it (`test`, `test:<unit>`), plus the files a
+// bunfig ignore keeps out on purpose and the ones no check reaches.
+//
+// Everything here is READ. Which check runs a file is suite/test-units.ts
+// testPlanOf, the same plan rule SK018 judges, and whether a file needs fixing
+// is ledger/run-timeline.ts testFilesToFix, the same function the runs page
+// tab lists. A second answer to either would drift from the first.
+import { posix } from 'path'
+import { CheckCtx } from '../core/check-ctx.ts'
+import { testFilesToFix } from '../ledger/run-timeline.ts'
+import { runsPath } from '../ledger/run-log.ts'
+import { readSuites, type SuiteRow } from '../ledger/suite-log.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { rawName } from '../core/canonical-scripts.ts'
+import { DEFAULT_BUDGET_MS, normSuitePath } from '../suite/judge-suites.ts'
+import { declaredSlowFiles, isTestFile, TEST_GLOB, testCheckId, testPlanOf, type TestUnitDecl } from '../suite/test-units.ts'
+import { NO_CHECK, testId, type Collection, type Instance, type ResourceState, type SuiteFacts, type TestFacts, type TestStanding } from './collection-types.ts'
+
+/** how many recorded runs a test file's page lists */
+export const TEST_RUNS_KEPT = 10
+
+export type TestsOpts = {
+    /** injected by tests; production lists what git sees */
+    files?: string[]
+    /** injected by tests; production reads the disk. null = absent */
+    read?: (rel: string) => string | null
+    /** injected by tests; production reads the suite record */
+    suites?: SuiteRow[]
+}
+
+/** the colour of a file's row: red when its last run failed or no check
+ *  reaches it, warn when it broke its budget, green only when a run passed */
+function stateOf(f: TestFacts): ResourceState {
+    if (f.standing === 'orphan' || f.toFix?.red === true) return 'red'
+    if (f.standing === 'missing' || f.toFix?.slow === true) return 'warn'
+    if (f.standing === 'ignored') return 'quiet'
+    if (f.runs.length > 0 && f.runs[0]!.status === 'pass') return 'ok'
+    return 'idle'
+}
+
+/** the one short fact on the row: the tier it runs in, or why it runs in none */
+const SLOT: Record<TestStanding, (f: TestFacts) => string> = {
+    runs: (f) => (f.tier === 'full' ? 'release only' : 'quick'),
+    ignored: () => 'ignored',
+    orphan: () => 'no check',
+    opaque: () => 'unknown',
+    missing: () => 'missing',
+}
+
+/** the feed line: a terminal has no slots */
+function sentence(f: TestFacts): string {
+    const last = f.runs[0]
+    const what = last == null ? 'never ran here' : `${last.status === 'fail' ? 'failed' : 'passed'} in ${Math.round(last.ms)}ms of a ${f.budgetMs}ms budget`
+    if (f.standing === 'orphan') return `${f.file} runs in no check: ${f.why}`
+    if (f.standing === 'ignored') return `${f.file} is ignored on purpose by ${f.why}`
+    if (f.standing === 'opaque') return `${f.file}: ${f.why}`
+    if (f.standing === 'missing') return `${f.file} is declared slow but is not on disk`
+    return `${f.file} runs in ${f.checkId}, ${what}`
+}
+
+export function testsCollection(root: string, c: RepoConfig, o: TestsOpts = {}): Collection {
+    return {
+        id: 'tests',
+        title: 'tests',
+        media: 'health',
+        list: async () => {
+            let files = o.files
+            let read = o.read
+            if (files == null || read == null) {
+                const disk = CheckCtx.open({ root, config: c })
+                files ??= disk.list(TEST_GLOB)
+                read ??= (rel) => disk.read(rel)
+            }
+            let suites = o.suites
+            if (suites == null) {
+                try { suites = readSuites(runsPath(root)) } catch { suites = [] }
+            }
+            return testInstances({ config: c, files: files.filter(isTestFile), read, suites })
+        },
+    }
+}
+
+/** every test file as a resource, pure over what the caller read */
+export function testInstances(o: { config: RepoConfig; files: string[]; read: (rel: string) => string | null; suites: SuiteRow[] }): Instance[] {
+    const plan = testPlanOf({ config: o.config, files: o.files, read: o.read })
+    const slow = declaredSlowFiles(o.config)
+    const toFix = new Map(testFilesToFix(o.suites, slow).map((r) => [r.file, r]))
+    const byFile = new Map<string, SuiteRow[]>()
+    for (const s of o.suites) {
+        const list = byFile.get(s.file) ?? []
+        list.push(s)
+        byFile.set(s.file, list)
+    }
+    const decl = slowDeclarations(o.config)
+    const unitOf = (file: string): TestUnitDecl | null =>
+        plan.units.filter((u) => file === u.rel || file.startsWith(`${u.rel}/`)).sort((a, b) => b.rel.length - a.rel.length)[0] ?? null
+    const hasRaw = (dir: string): boolean => {
+        try {
+            const pkg = JSON.parse(o.read(dir === '' ? 'package.json' : posix.join(dir, 'package.json')) ?? '{}') as { scripts?: Record<string, string> }
+            return pkg.scripts?.[rawName('test')] != null
+        } catch {
+            return false
+        }
+    }
+
+    const facts = (file: string, standing: TestStanding, checkId: string | null, why: string | null): TestFacts => {
+        const u = unitOf(file)
+        const unitDir = u?.rel ?? ''
+        const inUnit = unitDir === '' ? file : file.slice(unitDir.length + 1)
+        const budgetMs = (u == null ? o.config.tests?.budgetMs : u.tests?.budgetMs) ?? DEFAULT_BUDGET_MS
+        const runs = (byFile.get(file) ?? [])
+            .slice()
+            .sort((a, b) => b.at - a.at)
+            .slice(0, TEST_RUNS_KEPT)
+            .map((s): TestFacts['runs'][number] => ({
+                at: s.at, ms: s.ms, status: s.status, tier: s.tier, budgetMs: s.budgetMs,
+                ...(s.cpuMs == null ? {} : { cpuMs: s.cpuMs }),
+                ...(s.phase == null || s.phase === '' ? {} : { phase: s.phase }),
+                ...(s.phaseMs == null ? {} : { phaseMs: s.phaseMs }),
+                ...(s.failLine == null || s.failLine === '' ? {} : { failLine: s.failLine }),
+            }))
+        const fix = toFix.get(file)
+        const suite = decl.get(file)
+        return {
+            file,
+            inUnit,
+            unit: u?.id ?? 'root',
+            unitDir,
+            checkId,
+            standing,
+            why,
+            tier: suite != null ? 'full' : 'quick',
+            budgetMs,
+            toFix: fix == null ? null : { red: fix.red, slow: fix.slow },
+            runs,
+            cmd: { cwd: unitDir, line: `${hasRaw(unitDir) ? `bun run ${rawName('test')}` : 'bun test'} ./${inUnit}` },
+            ...(suite == null ? {} : { suite }),
+        }
+    }
+
+    const all: TestFacts[] = []
+    for (const [checkId, list] of plan.runs) for (const file of list) all.push(facts(file, 'runs', checkId, null))
+    for (const i of plan.ignored) all.push(facts(i.file, 'ignored', i.checkId, i.pattern))
+    for (const x of plan.orphans) all.push(facts(x.file, 'orphan', null, x.why))
+    for (const x of plan.unread) all.push(facts(x.file, 'opaque', x.checkId, `${x.checkId} runs a script that is not a plain \`bun test\`, so which files it runs cannot be read`))
+    const seen = new Set(all.map((f) => f.file))
+    for (const [file, suite] of decl) {
+        if (seen.has(file)) continue
+        const u = unitOf(file)
+        all.push(facts(file, 'missing', testCheckId(u?.id ?? 'root'), `${suite.configPath} declares it slow`))
+    }
+
+    return all.map((f): Instance => {
+        const folder = f.checkId == null || f.standing === 'orphan' ? NO_CHECK : f.checkId
+        return {
+            id: testId(f.file),
+            type: 'test',
+            path: `tests/${folder}/${f.inUnit}`,
+            virtual: true,
+            label: posix.basename(f.inUnit),
+            text: sentence(f),
+            slot: SLOT[f.standing](f),
+            state: stateOf(f),
+            ...(f.standing === 'missing' ? {} : { file: f.file }),
+            test: f,
+        }
+    })
+}
+
+/** every slow declaration, by the repo relative file it names */
+function slowDeclarations(c: RepoConfig): Map<string, SuiteFacts> {
+    const out = new Map<string, SuiteFacts>()
+    const add = (dir: string | null, s: { file: string; catches: string; whyNotFast: string }, budgetMs: number): void => {
+        const rel = normSuitePath(dir == null ? s.file : posix.join(dir, s.file))
+        out.set(rel, { file: s.file, catches: s.catches, whyNotFast: s.whyNotFast, configPath: 'repo.config.ts', unit: dir, budgetMs })
+    }
+    for (const s of c.tests?.slow ?? []) add(null, s, c.tests?.budgetMs ?? DEFAULT_BUDGET_MS)
+    for (const u of c.units ?? []) if (typeof u.dir === 'string') for (const s of u.tests?.slow ?? []) add(u.dir, s, u.tests?.budgetMs ?? DEFAULT_BUDGET_MS)
+    return out
+}

package/src/collections/wikis.ts

@@ -0,0 +1,66 @@
+// wikis collection — the MOUNTED md wikis as CHECKED section entries. The
+// mounts arrive as data from the hub's own route resolution (serve/run-serve),
+// never re-derived here: a card linking at an unmounted route renders the 404
+// body inside its iframe. Each instance carries its lint state (orphans +
+// dangling refs = red with counts; clean = green), or the last verdicts of
+// the repo checks its mount names. A graph whose lint belongs to another repo
+// is link-only, never double-judged here.
+import { checkStatsFor, type CheckStat } from '../ledger/check-stats.ts'
+import { lintMd } from '../wiki/lint-md.ts'
+import type { GraphMount } from '../wiki/graph-mount.ts'
+import type { Collection, Instance } from './collection-types.ts'
+import { graphChecksState, graphState } from './state-rules.ts'
+
+export type WikisOpts = {
+    /** injected by tests; production reads the store plus the run record */
+    stats?: Map<string, CheckStat>
+}
+
+// a wiki's graph is a VIEW, never a place: it files under wikis/<id> whatever
+// dir it scans, so the wiki and the agent graphs sit as two sibling rows.
+// Filed at the dir it scans, the agent graph read as the agent folder itself
+const wikiPath = (m: GraphMount): Pick<Instance, 'path' | 'virtual'> => ({ path: `wikis/${m.id}`, virtual: true })
+
+export function wikisCollection(mounts: GraphMount[], root: string | null = null, o: WikisOpts = {}): Collection {
+    return {
+        id: 'wikis',
+        title: 'wikis',
+        media: 'data',
+        list: async () =>
+            mounts.map((m): Instance => {
+                const id = `wiki:${m.id}`
+                const href = `/graph/${m.id}`
+                const label = m.label
+                const place = { type: 'wiki' as const, ...wikiPath(m) }
+                if (m.lint == null) return { id, text: m.label, label: m.label, md: label, href, ...place }
+                if ('checks' in m.lint) {
+                    const ids = m.lint.checks
+                    const stats = o.stats ?? (root == null ? new Map<string, CheckStat>() : checkStatsFor(root, ids.map((x) => ({ id: x }))))
+                    const last = ids.map((x) => stats.get(x)?.last?.status ?? null)
+                    const red = ids.filter((_, n) => last[n] === 'fail')
+                    return {
+                        id,
+                        text: red.length === 0 ? m.label : `${m.label}: ${red.join(', ')} red`,
+                        label: m.label,
+                        slot: red.length === 0 ? 'clean' : `${red.length} red`,
+                        md: `${label}, judged by ${ids.join(', ')}`,
+                        ...graphChecksState(last),
+                        href,
+                        ...place,
+                    }
+                }
+                const r = lintMd({ root: m.lint.root, index: m.lint.index })
+                const issues = r.orphans.length + r.dangling.length
+                return {
+                    id,
+                    text: issues === 0 ? m.label : `${m.label} — ${r.orphans.length} orphan(s), ${r.dangling.length} dangling ref(s)`,
+                    label: m.label,
+                    slot: issues === 0 ? 'clean' : `${issues} issue${issues === 1 ? '' : 's'}`,
+                    md: label,
+                    ...graphState({ lint: true, issues }),
+                    href,
+                    ...place,
+                }
+            }),
+    }
+}