rvlib-shipkit 0.38.1 → 1.0.0

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

@@ -0,0 +1,245 @@
+// THE RUNS PAGE: four lists behind four tabs, one visible at a time: every
+// invocation on record as a tree of one line runs whose checks unfold as
+// child lines, the test files to fix, the slowest checks, the longest runs.
+// The tab rides in the address (`#item:runs:runs:files`), so a reload restores it.
+// Every line sits on a grid of fixed columns (the .rline grids in hub.css):
+// numbers right aligned in tabular figures, ran and cached each a column of
+// their own told apart by colour, and no separator glyph on any line. The
+// shaping is the server's (ledger/run-timeline.ts). The chart of every run in
+// time is the live strip under the header, not this page.
+import { observer } from 'mobx-react-lite'
+import { useEffect } from 'react'
+import { CACHED, RAN } from '../../core/outcome-words.ts'
+import type { InvocationSummary, SlowCheck, SuiteToFix, Timeline, TimelineBar, TimelineInvocation } from '../../ledger/run-timeline.ts'
+import { byWords, verdictWords } from './timeline-chart.tsx'
+import { durationTone, fmtMs } from './dur.ts'
+import { Help } from './help.tsx'
+import type { HubSt } from './hub-st.ts'
+import { TimeAgo, stampWords } from './time-ago.tsx'
+import { checkName, editorHref } from './check-words.ts'
+import { RUNS_TABS, runsTab, runsTabId, type RunsTab } from './runs-tabs.ts'
+export { RUNS_TABS, runsTab, runsTabId, type RunsTab }
+import type { Resource } from './hub-types.ts'
+
+export type TabBadge = { n: number; tone: 'red' | 'warn' | 'zero' }
+
+/** a tab's count, or null where a count says nothing: the red runs, the test
+ *  files to fix (a zero is news too), the flagged checks */
+export function tabBadge(tab: RunsTab, d: Timeline): TabBadge | null {
+    if (tab === 'runs') {
+        const n = d.invocations.filter((i) => i.reds > 0).length
+        return n > 0 ? { n, tone: 'red' } : null
+    }
+    if (tab === 'files') return d.suitesRecorded ? { n: d.testFiles.length, tone: d.testFiles.length > 0 ? 'red' : 'zero' } : null
+    if (tab === 'slowest') {
+        const n = d.slowest.filter((r) => r.flag != null).length
+        return n > 0 ? { n, tone: d.slowest.some((r) => r.flag === 'over') ? 'red' : 'warn' } : null
+    }
+    return null
+}
+
+/** who started a run, as a tag short enough for one fixed column. A starter
+ *  this build does not name reads as the word the record holds */
+export const BY_TAG: Record<string, string> = { cli: 'terminal', hub: 'hub', schedule: 'daily', save: 'save', unknown: 'unknown' }
+export const byTag = (by: string): string => BY_TAG[by] ?? by
+
+/** a check's verdict, as the label's colour class: the tree's `tl` tones */
+const verdictTone = (b: TimelineBar): string => (b.status === 'fail' ? 'red' : b.status === 'warn' ? 'warn' : b.status === 'skip' ? 'quiet' : 'ok')
+
+const Who = ({ by }: { by: string }) => <span className="rwho" title={`started from ${byWords(by)}`}>{byTag(by)}</span>
+
+const Reds = ({ n }: { n: number }) => <span className="rred">{n > 0 ? `${n} red` : ''}</span>
+
+/** the ran and the cached columns of a run, a count and its word each */
+const Counts = ({ checks, cached }: { checks: number; cached: number }) => {
+    const ran = checks - cached
+    return (
+        <>
+            <span className={`rran${ran === 0 ? ' zero' : ''}`}>{`${ran} ${RAN}`}</span>
+            <span className={`rcached${cached === 0 ? ' zero' : ''}`}>{`${cached} ${CACHED}`}</span>
+        </>
+    )
+}
+
+/** a check's name on a child line: its title, with its id as the small tag
+ *  the tree gives it, and its description for the tooltip */
+export type ChildName = { tag: string | null; title: string; description: string | null }
+
+/** every check the hub lists, by id, named the way the tree names it */
+export function checkNames(resources: readonly Resource[]): Map<string, ChildName> {
+    const out = new Map<string, ChildName>()
+    for (const r of resources) {
+        if (r.check == null) continue
+        out.set(r.check.checkId, { ...checkName(r.check.checkId, r.title), description: r.check.description })
+    }
+    return out
+}
+
+/** a check the hub no longer lists (removed since the run) is named by its id */
+export const nameOf = (names: Map<string, ChildName>, id: string): ChildName => names.get(id) ?? { tag: null, title: id, description: null }
+
+/** an unfolded run's order: its reds, then what ran, slowest first, then what
+ *  the cache answered, so what matters shows without scrolling */
+export function childOrder(bars: readonly TimelineBar[]): TimelineBar[] {
+    const rank = (b: TimelineBar): number => (b.status === 'fail' ? 0 : b.replayed ? 2 : 1)
+    return bars
+        .map((b, i) => ({ b, i }))
+        .sort((x, y) => rank(x.b) - rank(y.b) || (rank(x.b) === 2 ? 0 : y.b.ms - x.b.ms) || x.i - y.i)
+        .map((x) => x.b)
+}
+
+/** one check of a run, a child line on the run's grid: its word sits in the
+ *  column its run counts it in */
+const CheckLine = ({ app, b, name }: { app: HubSt; b: TimelineBar; name: ChildName }) => (
+    <div className={`rline rchild${b.status === 'fail' ? ' red' : ''}`} onClick={() => app.timeline.openCheck(b.id)}
+        title={[name.description ?? '', `${b.id}: ${verdictWords(b)}`, stampWords(b.start)].filter((x) => x !== '').join('\n')}>
+        <span />
+        <span className="rid"><span className={`rname tl ${verdictTone(b)}`}>{name.tag == null ? null : <span className="tid">{name.tag}</span>}{name.title}</span></span>
+        <span className={`rnum ${b.replayed ? 'dim' : durationTone(b.ms) ?? ''}`}>{b.replayed ? '' : fmtMs(b.ms)}</span>
+        <span className="rran">{b.replayed ? '' : RAN}</span>
+        <span className="rcached">{b.replayed ? CACHED : ''}</span>
+        <span className={`rflag ${b.status === 'fail' ? 'red' : 'warn'}`}>{b.status === 'fail' ? 'red' : b.status === 'warn' ? 'warn' : ''}</span>
+    </div>
+)
+
+const RunLine = observer(({ app, inv, n }: { app: HubSt; inv: TimelineInvocation; n: number }) => {
+    const open = app.timeline.isOpen(inv.runId, n)
+    return (
+        <>
+            <div className={`rline rrun${inv.reds > 0 ? ' red' : ''}`} onClick={() => app.timeline.toggle(inv.runId, n)}>
+                <span className="rcaret">{open ? '▾' : '▸'}</span>
+                <TimeAgo clock={app.clock} at={inv.started} />
+                <Who by={inv.by} />
+                <span className="rwhat">{inv.label}</span>
+                <span className="rnum">{fmtMs(inv.wallMs)}</span>
+                <Counts checks={inv.bars.length} cached={inv.replays} />
+                <Reds n={inv.reds} />
+            </div>
+            {open ? <RunChecks app={app} bars={inv.bars} /> : null}
+        </>
+    )
+})
+
+/** the checks of an unfolded run, in a box of their own that scrolls: a full
+ *  gate is fifty checks, which would push every other run off the page */
+const RunChecks = observer(({ app, bars }: { app: HubSt; bars: TimelineBar[] }) => {
+    const names = checkNames(app.cols.resources)
+    return <div className="rkids">{childOrder(bars).map((b) => <CheckLine key={`${b.id}:${b.start}`} app={app} b={b} name={nameOf(names, b.id)} />)}</div>
+})
+
+const Runs = ({ app, rows }: { app: HubSt; rows: TimelineInvocation[] }) => (
+    rows.length === 0 ? <div className="rempty">no run on record yet</div> : <>{rows.map((inv, n) => <RunLine key={inv.runId} app={app} inv={inv} n={n} />)}</>
+)
+
+/** what a test file to fix did: `red`, or its time against the budget */
+export const suiteWords = (r: SuiteToFix): string => (r.red ? 'red' : `over ${fmtMs(r.budgetMs)}`)
+
+/** a sub-unit's file, named from its unit's dir: the tag beside it already
+ *  says which unit, and the repo path is the tooltip */
+const inUnit = (r: SuiteToFix): string => {
+    if (r.unit === '' || r.unit === 'root') return r.file
+    const at = r.file.indexOf(`/${r.unit}/`)
+    return at < 0 ? r.file : r.file.slice(at + r.unit.length + 2)
+}
+
+const TestFiles = ({ app, rows, recorded }: { app: HubSt; rows: SuiteToFix[]; recorded: boolean }) => {
+    if (!recorded) return <div className="rempty">no test file run recorded yet: the next run of a test check records one</div>
+    if (rows.length === 0) return <div className="rempty">every test file passed and fits the budget</div>
+    return (
+        <>
+            {rows.map((r) => {
+                return (
+                    <div key={`${r.check}:${r.file}`} className={`rline rtest${r.red ? ' red' : ''}`} title={r.failLine ?? undefined} onClick={() => app.timeline.openTest(r.file)}>
+                        <span className={`rtag${r.check === '' ? ' dim' : ''}`} title={r.check === '' ? 'recorded before the record named its check' : `the check that ran it: ${r.check}`}
+                            onClick={(e) => { if (r.check === '') return; e.stopPropagation(); app.timeline.openCheck(r.check) }}>{r.check === '' ? 'unnamed' : r.check}</span>
+                        <span className="rwhat" title={r.file}>{inUnit(r)}</span>
+                        <span className={`rnum ${r.slow ? 'bad' : ''}`}>{fmtMs(r.ms)}</span>
+                        <span className={r.red ? 'rflag red' : 'rflag warn'}>{suiteWords(r)}</span>
+                        <TimeAgo clock={app.clock} at={r.at} />
+                    </div>
+                )
+            })}
+        </>
+    )
+}
+
+const FLAG_WORD = { over: 'at its ceiling', near: 'past half its ceiling' } as const
+
+/** two numbers side by side need their names once, above the column */
+const Slowest = ({ app, rows }: { app: HubSt; rows: SlowCheck[] }) => {
+    if (rows.length === 0) return <div className="rempty">nothing ran yet</div>
+    return (
+        <>
+            <div className="rhead rslow"><span /><span>mean</span><span>worst</span><span /></div>
+            {rows.map((r) => (
+                <div key={r.id} className="rline rslow" onClick={() => app.timeline.openCheck(r.id)}>
+                    <span className="rtag">{r.id}</span>
+                    <span className={`rnum ${durationTone(r.meanMs, r.ceilingMs) ?? ''}`} title="mean of the runs that ran">{fmtMs(r.meanMs)}</span>
+                    <span className={`rnum ${durationTone(r.worstMs, r.ceilingMs) ?? ''}`} title="the worst run that ran">{fmtMs(r.worstMs)}</span>
+                    <span className={r.flag === 'over' ? 'rflag red' : 'rflag warn'} title={r.ceilingMs == null ? undefined : `ceiling ${fmtMs(r.ceilingMs)}`}>{r.flag == null ? '' : FLAG_WORD[r.flag]}</span>
+                </div>
+            ))}
+        </>
+    )
+}
+
+const Longest = ({ app, rows }: { app: HubSt; rows: InvocationSummary[] }) => {
+    if (rows.length === 0) return <div className="rempty">no run on record yet</div>
+    return (
+        <>
+            {rows.map((r) => (
+                <div key={r.runId} className={`rline rrun${r.reds > 0 ? ' red' : ''}`} title={stampWords(r.started)}>
+                    <span />
+                    <TimeAgo clock={app.clock} at={r.started} />
+                    <Who by={r.by} />
+                    <span className="rwhat">{r.label}</span>
+                    <span className="rnum">{fmtMs(r.wallMs)}</span>
+                    <Counts checks={r.checks} cached={r.replays} />
+                    <Reds n={r.reds} />
+                </div>
+            ))}
+        </>
+    )
+}
+
+const Tabs = observer(({ app, on }: { app: HubSt; on: RunsTab }) => {
+    const t = app.timeline
+    const d = t.data
+    return (
+        <div className="rtabs">
+            {RUNS_TABS.map((tab) => {
+                const b = d == null ? null : tabBadge(tab.key, d)
+                return (
+                    <button key={tab.key} className={`rtab${tab.key === on ? ' on' : ''}`} onClick={() => app.cols.select('runs', runsTabId(tab.key))}>
+                        {tab.label}
+                        {b == null ? null : <span className={`rbadge ${b.tone}`}>{b.n}</span>}
+                    </button>
+                )
+            })}
+            <Help text={RUNS_TABS.find((x) => x.key === on)!.help} />
+            <span className="sp" />
+            <button disabled={t.loading} onClick={() => void t.load()}>{t.loading ? 'reading…' : 'reload'}</button>
+        </div>
+    )
+})
+
+export const TimelineView = observer(({ app }: { app: HubSt }) => {
+    const t = app.timeline
+    useEffect(() => { void t.load() }, [t])
+    const d = t.data
+    const on = runsTab(app.sel?.t === 'item' ? app.sel.id : null)
+    return (
+        <div className="colcard tlcard">
+            <Tabs app={app} on={on} />
+            {t.error !== '' ? <div className="warnline">{t.error}</div> : null}
+            {d == null ? <div className="dim">reading the run record…</div> : (
+                <div className={`rlist ${on}`}>
+                    {on === 'runs' ? <Runs app={app} rows={d.invocations} />
+                        : on === 'files' ? <TestFiles app={app} rows={d.testFiles} recorded={d.suitesRecorded} />
+                            : on === 'slowest' ? <Slowest app={app} rows={d.slowest} />
+                                : <Longest app={app} rows={d.longest} />}
+                </div>
+            )}
+        </div>
+    )
+})

package/src/serve/hub-app/tree-build.ts

@@ -0,0 +1,410 @@
+// The trie, as pure functions over one flat Resource[]. No react, no mobx,
+// no dom: TreeSvc caches these as computeds and the tests drive them
+// headless. Both tabs (by path, by type) are the SAME array grouped twice,
+// never a second list.
+import { NO_CHECK, type Resource, type ResourceState, type TestFacts } from '../../collections/collection-types.ts'
+import { checkVerdictWords, plural } from '../../core/outcome-words.ts'
+import { checkName } from './check-words.ts'
+import { durationTone, fmtMs, type DurTone } from './dur.ts'
+import type { HashSel } from './hash-route.ts'
+
+export type TreeNode = {
+    /** stable across reloads: the expansion set and the cursor are keys */
+    key: string
+    label: string
+    state: ResourceState
+    /** null on a directory */
+    res: Resource | null
+    /** a by type group: the kind it gathers, so its row wears that kind's
+     *  mark. null on a real folder and on a leaf */
+    kind: string | null
+    /** leaves under this node, and how many of them are red */
+    total: number
+    reds: number
+    /** every gate check under this node: the row pulses while one of them runs */
+    checks: string[]
+    /** the archive: everything under it is already done. It stays in the
+     *  tree and out of every count above it */
+    archived: boolean
+    /** a folder with a page of its own: its label opens the page, its
+     *  chevron folds. null on every other folder and on a leaf */
+    page: HashSel | null
+    children: TreeNode[]
+}
+
+export type TreeRow = {
+    key: string
+    label: string
+    depth: number
+    dir: boolean
+    state: ResourceState
+    res: Resource | null
+    kind: string | null
+    total: number
+    reds: number
+    checks: string[]
+    page: HashSel | null
+}
+
+// a directory wears the WORST state under it, so a collapsed branch can
+// never hide a red, and OK outranks idle: a folder of passing checks read as
+// plain white because one unmeasured row in it outvoted twenty nine greens
+const RANK: Record<ResourceState, number> = { red: 4, warn: 3, ok: 2, idle: 1, quiet: 0 }
+const worst = (a: ResourceState, b: ResourceState): ResourceState => (RANK[b] > RANK[a] ? b : a)
+
+/** an ask that is already done: it rides quiet under `done/`, filed away so
+ *  past answers stay consultable. Everything else a repo owns is either open
+ *  or a check, so this is the one archive the tree has */
+const isDone = (r: Resource): boolean => r.type === 'ask' && r.slot === 'done'
+
+type Build = { dirs: Map<string, Build>; leaves: Resource[] }
+const emptyBuild = (): Build => ({ dirs: new Map(), leaves: [] })
+
+const byLabel = (a: TreeNode, b: TreeNode): number => {
+    const ad = a.res == null
+    const bd = b.res == null
+    if (ad !== bd) return ad ? -1 : 1 // directories first, then leaves
+    return a.label.localeCompare(b.label)
+}
+
+const leafNode = (r: Resource): TreeNode => ({
+    // the resource id, never its path: two resources may share a file
+    key: r.id,
+    // the TITLE, never the path segment: the path decides where a row sits,
+    // the title is what a reader reads
+    label: r.title,
+    state: r.state,
+    res: r,
+    kind: null,
+    total: 1,
+    reds: r.state === 'red' ? 1 : 0,
+    checks: r.check == null ? [] : [r.check.checkId],
+    archived: isDone(r),
+    page: null,
+    children: [],
+})
+
+const rollup = (children: TreeNode[]): Pick<TreeNode, 'state' | 'total' | 'reds' | 'checks' | 'archived'> => {
+    const archived = children.length > 0 && children.every((c) => c.archived)
+    return {
+        state: children.reduce<ResourceState>((acc, c) => worst(acc, c.state), 'quiet'),
+        // an archive is out of the count of the folder that holds it: an
+        // asks row reading 25 when 9 of them want hands answers a question
+        // nobody asked. The archive itself still counts its own, so the row
+        // says how much is filed in there
+        total: children.reduce((n, c) => n + (archived || !c.archived ? c.total : 0), 0),
+        reds: children.reduce((n, c) => n + c.reds, 0),
+        checks: children.flatMap((c) => c.checks),
+        archived,
+    }
+}
+
+/** a chain of directories with one child and nothing of its own renders as
+ *  ONE row (wiki/build/shipkit rather than three nested rows), and keeps the
+ *  DEEPEST path as its key so an expansion survives a reload */
+const dirNode = (prefix: string, label: string, b: Build): TreeNode => {
+    if (b.leaves.length === 0 && b.dirs.size === 1) {
+        const [seg, only] = [...b.dirs.entries()][0]!
+        return dirNode(`${prefix}/${seg}`, `${label}/${seg}`, only)
+    }
+    const children = [
+        ...[...b.dirs.entries()].map(([seg, sub]) => dirNode(`${prefix}/${seg}`, seg, sub)),
+        ...b.leaves.map(leafNode),
+    ].sort(byLabel)
+    return { key: prefix, label, res: null, kind: null, ...rollup(children), page: pathPage(prefix, children), children }
+}
+
+const holdsTests = (nodes: TreeNode[]): boolean => nodes.some((n) => n.res?.test != null || holdsTests(n.children))
+
+/** the virtual `tests/` root of the path tab, and each `tests/<check>` under
+ *  it, open the pages of the same groups on the by type tab. A real `tests/`
+ *  folder that holds no test resource stays a plain folder */
+function pathPage(prefix: string, children: TreeNode[]): HashSel | null {
+    if (!holdsTests(children)) return null
+    if (prefix === 'tests') return { t: 'tests', check: null }
+    const m = prefix.match(/^tests\/([^/]+)$/)
+    return m == null || m[1] === NO_CHECK ? null : { t: 'tests', check: m[1]! }
+}
+
+/** the by type groups of test files: `tests` itself, and one group per test
+ *  check. The files no check reaches have no time to show */
+function typePage(key: string, label: string): HashSel | null {
+    if (key === 'type:test') return { t: 'tests', check: null }
+    return key.startsWith('type:test:') && label !== NO_CHECK ? { t: 'tests', check: label } : null
+}
+
+export function buildPathTree(resources: Resource[]): TreeNode[] {
+    const root = emptyBuild()
+    for (const r of resources) {
+        const segs = r.path.split('/').filter((s) => s !== '')
+        let cur = root
+        for (const seg of segs.slice(0, -1)) {
+            let next = cur.dirs.get(seg)
+            if (next == null) {
+                next = emptyBuild()
+                cur.dirs.set(seg, next)
+            }
+            cur = next
+        }
+        cur.leaves.push(r)
+    }
+    return [
+        ...[...root.dirs.entries()].map(([seg, sub]) => dirNode(seg, seg, sub)),
+        ...root.leaves.map(leafNode),
+    ].sort(byLabel)
+}
+
+const groupNode = (key: string, label: string, kind: string, children: TreeNode[]): TreeNode => ({
+    key,
+    label,
+    res: null,
+    kind,
+    ...rollup(children),
+    page: typePage(key, label),
+    children: [...children].sort(byLabel),
+})
+
+/** a gate check is filed by WHOSE it is: shipkit ships the SK checks, a repo
+ *  owns everything it declared itself. There is no second axis, because what
+ *  a check does and when it runs are already slots on its own row. A test
+ *  file is filed under the check that runs it, since a repo holds a hundred
+ *  of them. Every other resource keeps its type word. */
+type Seg = { key: string; label: string; kind: string }
+
+const groupOf = (r: Resource): Seg[] => {
+    const u = r.check
+    if (r.test != null) {
+        const by = r.test.standing === 'orphan' || r.test.checkId == null ? NO_CHECK : r.test.checkId
+        return [{ key: 'type:test', label: 'tests', kind: 'test' }, { key: `type:test:${by}`, label: by, kind: by === NO_CHECK ? 'test' : 'check' }]
+    }
+    if (u == null)
+        return isDone(r)
+            ? [{ key: `type:${r.type}`, label: r.type, kind: r.type }, { key: `type:${r.type}:done`, label: 'done', kind: 'done' }]
+            : [{ key: `type:${r.type}`, label: r.type, kind: r.type }]
+    return u.from === 'repo'
+        ? [{ key: 'type:check:repo', label: 'from this repo', kind: 'check' }]
+        : [{ key: 'type:check:shipkit', label: 'from shipkit', kind: 'check' }]
+}
+
+type Group = { label: string; kind: string; rs: Resource[]; subs: Map<string, Group> }
+
+const groupTree = (key: string, g: Group): TreeNode =>
+    groupNode(key, g.label, g.kind, [...[...g.subs.entries()].map(([k, sub]) => groupTree(k, sub)), ...g.rs.map(leafNode)])
+
+/** by type: one level per group, plus the `done` archive under the kind
+ *  that has one, which mirrors the `asks/done/` folder the by path tab
+ *  shows. Where a check RUNS is already on the row (its note slot) and
+ *  counted above the tree, so a level for it costs a row to open and answers
+ *  nothing again. */
+export function buildTypeTree(resources: Resource[]): TreeNode[] {
+    const top = new Map<string, Group>()
+    for (const r of resources) {
+        let cur = top
+        let g: Group | null = null
+        for (const seg of groupOf(r)) {
+            let next = cur.get(seg.key)
+            if (next == null) {
+                next = { label: seg.label, kind: seg.kind, rs: [], subs: new Map() }
+                cur.set(seg.key, next)
+            }
+            g = next
+            cur = next.subs
+        }
+        g!.rs.push(r)
+    }
+    return [...top.entries()].map(([key, g]) => groupTree(key, g)).sort(byLabel)
+}
+
+/** the visible rows, in screen order — a directory nobody expanded stops
+ *  the walk, which is the whole point of the expansion set */
+export function flattenTree(nodes: TreeNode[], expanded: Set<string>, depth = 0): TreeRow[] {
+    const out: TreeRow[] = []
+    for (const n of nodes) {
+        const dir = n.res == null
+        out.push({ key: n.key, label: n.label, depth, dir, state: n.state, res: n.res, kind: n.kind, total: n.total, reds: n.reds, checks: n.checks, page: n.page })
+        if (dir && expanded.has(n.key)) out.push(...flattenTree(n.children, expanded, depth + 1))
+    }
+    return out
+}
+
+/** the one line above the tree: how much of this repo runs on every gate,
+ *  and how much does not. Counts CHECKS only, because nothing else declares a
+ *  place to run */
+export function whenCounts(resources: Resource[]): Record<'always' | 'release' | 'health' | 'off', number> {
+    const out = { always: 0, release: 0, health: 0, off: 0 }
+    for (const r of resources) if (r.check != null) out[r.check.when]++
+    return out
+}
+
+/** every directory key in the tree, which is what "expand all" writes.
+ *  `archive: false` leaves the done branches folded: a search that yields
+ *  every fold must not spill what was filed away as answered */
+export function dirKeys(nodes: TreeNode[], archive = true): string[] {
+    return nodes.flatMap((n) => (n.res != null || (!archive && n.archived) ? [] : [n.key, ...dirKeys(n.children, archive)]))
+}
+
+/** what the label slot says: a check row carries its id as a small tag before
+ *  its title, every other row its label alone */
+export function rowName(row: Pick<TreeRow, 'label' | 'res'>): { tag: string | null; title: string } {
+    const u = row.res?.check
+    return u == null ? { tag: null, title: row.label } : checkName(u.checkId, row.label)
+}
+
+// ── the row slots ────────────────────────────────────────────────────────
+// A row is a fixed grid, so the slots line up down the whole column at any
+// depth. Everything a row says in WORDS lives in `hint`, which is the
+// tooltip: a label carries a name, never a verdict.
+
+/** the six states a slot can show, one glyph each, everywhere */
+export type SlotState = 'pass' | 'fail' | 'warn' | 'running' | 'idle' | 'off'
+export const GLYPH: Record<SlotState, string> = { pass: '✓', fail: '✕', warn: '!', running: '◍', idle: '·', off: '○' }
+
+/** the glyph's colour class. `adv` is a failure that cannot block: a muted
+ *  fail rather than a word, and `run` is the one that pulses */
+export type SlotTone = 'red' | 'warn' | 'adv' | 'ok' | 'quiet' | 'idle' | 'run'
+
+export type RowSlots = {
+    state: SlotState
+    tone: SlotTone
+    /** right aligned, tabular, blank when nothing was measured */
+    dur: string
+    /** the same tone table the check page reads, so a row and the page it
+     *  opens can never disagree about a number */
+    durTone: DurTone | null
+    /** the one short fact this kind has to offer */
+    note: string
+    /** directories only: what is under it, and how much of it is red */
+    count: { total: number; reds: number } | null
+    /** every word the row does not show, as the row's tooltip */
+    hint: string
+}
+
+const DIR_STATE: Record<ResourceState, SlotState> = { red: 'fail', warn: 'warn', ok: 'pass', idle: 'idle', quiet: 'off' }
+const DIR_TONE: Record<ResourceState, SlotTone> = { red: 'red', warn: 'warn', ok: 'ok', idle: 'idle', quiet: 'quiet' }
+
+/** the four values, short enough for a 48px slot. The tooltip says them in
+ *  full, because these are abbreviations and nobody was born knowing them */
+const WHEN_NOTE = { always: 'ci', release: 'release', health: 'health', off: 'off' } as const
+const WHEN_HINT = {
+    always: 'runs on every gate',
+    release: 'runs on the release path only',
+    health: 'runs in the health pass only, never on a gate',
+    off: 'does not run',
+} as const
+
+export function rowSlots(row: TreeRow, running: boolean): RowSlots {
+    if (row.dir)
+        return {
+            state: DIR_STATE[row.state],
+            tone: DIR_TONE[row.state],
+            dur: '',
+            durTone: null,
+            note: '',
+            count: { total: row.total, reds: row.reds },
+            hint: `${row.label} · ${row.total} under it${row.reds > 0 ? `, ${row.reds} red` : ''}`,
+        }
+    const r = row.res
+    if (r == null) return { state: 'idle', tone: 'idle', dur: '', durTone: null, note: '', count: null, hint: row.label }
+    if (r.test != null) return testSlots(r, r.test)
+    const u = r.check
+    if (u == null)
+        return {
+            state: DIR_STATE[r.state],
+            tone: DIR_TONE[r.state],
+            dur: '',
+            durTone: null,
+            note: r.slot ?? '',
+            count: null,
+            hint: [r.text, r.virtual === true ? `${r.path} (no file of its own)` : r.path].join('\n'),
+        }
+    const verdict: [SlotState, SlotTone] = running
+        ? ['running', 'run']
+        : u.when === 'off'
+            ? ['off', 'quiet']
+            : u.status === 'fail'
+                ? ['fail', u.advisory ? 'adv' : 'red']
+                : u.status === 'warn'
+                    ? ['warn', 'warn']
+                    : u.status === 'skip'
+                        ? ['off', 'quiet']
+                        : u.status === 'pass'
+                            ? ['pass', u.replayed ? 'quiet' : 'ok']
+                            : ['idle', 'idle']
+    const words = running ? 'running now' : checkVerdictWords(u.status, u)
+    return {
+        state: verdict[0],
+        tone: verdict[1],
+        dur: fmtMs(u.lastMs),
+        durTone: durationTone(u.lastMs, u.timeoutMs),
+        note: WHEN_NOTE[u.when],
+        count: null,
+        hint: [
+            `${u.checkId} (${u.build ? 'build step' : u.from === 'shipkit' ? 'from shipkit' : 'from this repo'}) · ${words}`,
+            // the sentence the check wrote about itself, so a row says what it
+            // is about without being opened
+            u.description != null && u.description !== '' ? u.description : null,
+            u.lastMs != null ? `last run ${fmtMs(u.lastMs)}` : null,
+            u.samples > 0 ? `average ${fmtMs(u.avgMs)} over ${plural(u.samples, 'run')}` : null,
+            `${WHEN_HINT[u.when]}${u.whenReason != null ? `: ${u.whenReason}` : ''}`,
+        ].filter((l) => l != null).join('\n'),
+    }
+}
+
+/** a test file row: its verdict, its last time against its budget, its
+ *  tier. Over budget is red on the duration, whatever the table says, unless
+ *  it is declared slow and the budget is not its to break */
+function testSlots(r: Resource, t: TestFacts): RowSlots {
+    const last = t.runs[0]
+    const over = last != null && last.tier === 'quick' && t.tier === 'quick' && last.ms > t.budgetMs
+    return {
+        state: DIR_STATE[r.state],
+        tone: DIR_TONE[r.state],
+        dur: last == null ? '' : fmtMs(last.ms),
+        durTone: last == null ? null : over ? 'bad' : durationTone(last.ms),
+        note: r.slot ?? '',
+        count: null,
+        hint: [
+            t.file,
+            r.text,
+            last == null ? null : `last run ${fmtMs(last.ms)} of a ${fmtMs(t.budgetMs)} budget`,
+        ].filter((l) => l != null).join('\n'),
+    }
+}
+
+// ── the KIND of a row ────────────────────────────────────────────────────
+// A tree of a hundred rows said nothing about what any of them WAS. One
+// glyph and one hue per kind, in the slot right after the caret, and the hue
+// is the KIND's identity: it never carries state, which stays on the label
+// and on the state glyph at the right edge. Hues are tokens (k1..k6 on
+// :root), reused across kinds on purpose, because thirteen hues nobody can
+// tell apart is not thirteen answers. The glyph is what identifies, the hue
+// only groups.
+
+export type TypeMark = { glyph: string; hue: string; word: string }
+
+export const TYPE_MARK: Record<string, TypeMark> = {
+    folder: { glyph: '\u25a3', hue: 'k5', word: 'a folder of this repo' },
+    ask: { glyph: '\u25c9', hue: 'k2', word: 'an ask: something only a human can do' },
+    secret: { glyph: '\u25c8', hue: 'k4', word: 'a secret this repo needs, present or missing' },
+    asset: { glyph: '\u25c6', hue: 'k1', word: 'an asset of the kit, with its rolls and its pick' },
+    post: { glyph: '\u25a4', hue: 'k2', word: 'a post waiting in the social queue' },
+    workflow: { glyph: '\u29c9', hue: 'k6', word: 'a comfy workflow module' },
+    wiki: { glyph: '\u2b21', hue: 'k3', word: 'a markdown wiki, opened as its link graph' },
+    contract: { glyph: '\u00a7', hue: 'k4', word: 'a release contract of a venue' },
+    health: { glyph: '\u229e', hue: 'k5', word: 'a health row that belongs to no other kind' },
+    check: { glyph: '\u2299', hue: 'k6', word: 'a gate check: one question `shipkit ci` or `shipkit check` asks, whether it builds, guards a repo shape or probes the world. same page and same switch for all of them' },
+    test: { glyph: '\u2263', hue: 'k5', word: 'a test file: the check that runs it, its last runs against its budget, the command that runs it alone' },
+    reflection: { glyph: '\u203b', hue: 'k2', word: 'a reflection: friction this repo logged against the wiki, waiting to be folded in' },
+    done: { glyph: '\u2713', hue: 'k5', word: 'a done ask: answered, filed under done, out of every count above it' },
+}
+
+/** a kind nobody mapped still gets a mark: a blank slot in a fixed grid is a
+ *  hole, and a new resource kind must never make the tree look broken */
+const UNKNOWN: TypeMark = { glyph: '\u25cb', hue: 'k5', word: 'a kind this page does not know yet' }
+
+/** a real folder wears the folder mark, a by type group the mark of the kind
+ *  it gathers, and a leaf its own kind */
+export const markOf = (res: Resource | null | undefined, dir: boolean, kind: string | null = null): TypeMark =>
+    dir
+        ? kind == null ? TYPE_MARK.folder! : TYPE_MARK[kind] ?? UNKNOWN
+        : res == null ? UNKNOWN : isDone(res) ? TYPE_MARK.done! : TYPE_MARK[res.type] ?? UNKNOWN