rvlib-shipkit 0.38.0 → 1.0.0

package/src/core/one-way-in-policy.ts

@@ -108,9 +108,16 @@ const PROGRAM_WORD = /^[\w./@+-]+$/
  *  bodies are dense and multi-line, so this is not a corner case here, it is
  *  the most common shape of command an agent runs. */
 export function shellSegments(command: string): string[] {
+    return shellParts(command).map((p) => p.seg)
+}
+
+/** each segment with the operator that ENDS it: `|` for a pipe (`|&` too),
+ *  `;` for every other separator, `` after the last one. A redirection's `&`
+ *  (`2>&1`, `&>log`) and the `|` of `>|` stay inside their segment */
+export function shellParts(command: string): { seg: string; op: '|' | ';' | '' }[] {
     // everything after a heredoc opener is the document, never a command
     const shell = command.split(/<<-?\s*['"]?\w+/)[0] ?? command
-    const out: string[] = []
+    const out: { seg: string; op: '|' | ';' | '' }[] = []
     let cur = ''
     let quote: '"' | "'" | null = null
     for (let i = 0; i < shell.length; i++) {
@@ -122,19 +129,80 @@ export function shellSegments(command: string): string[] {
             continue
         }
         if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue }
+        const prev = shell[i - 1]
+        const next = shell[i + 1]
+        if ((ch === '&' && (prev === '>' || prev === '<' || next === '>')) || (ch === '|' && prev === '>')) { cur += ch; continue }
         if (ch === '\n' || ch === ';' || ch === '|' || ch === '&') {
+            let op: '|' | ';' = ';'
             // `&&` and `||` are one operator, and a lone `&` backgrounds
-            if ((ch === '&' || ch === '|') && shell[i + 1] === ch) i++
-            out.push(cur)
+            if ((ch === '&' || ch === '|') && next === ch) i++
+            else if (ch === '|') {
+                op = '|'
+                if (next === '&') i++
+            }
+            out.push({ seg: cur, op })
             cur = ''
             continue
         }
         cur += ch
     }
-    out.push(cur)
+    out.push({ seg: cur, op: '' })
     return out
 }
 
+/** the words of a segment from its program on: leading `VAR=value`
+ *  assignments, then wrapper words with their own flags and durations
+ *  (`timeout 60 bun test`), dropped repeatedly */
+function programWords(seg: string): string[] {
+    let s = seg.trim().replace(/^[(){}\s]+/, '')
+    let wrapped = false
+    for (;;) {
+        const next = s.replace(/^\w+=(?:"[^"]*"|'[^']*'|\S*)\s+/, '')
+        if (next !== s) { s = next; continue }
+        const w = /^(\S+)\s+/.exec(s)
+        if (w != null && WRAPPERS.has(w[1]!.split('/').pop() ?? '')) { s = s.slice(w[0].length); wrapped = true; continue }
+        if (wrapped && w != null && /^(?:-\S*|\d+[smhd]?)$/.test(w[1]!)) { s = s.slice(w[0].length); continue }
+        break
+    }
+    return s.split(/\s+/).filter((w) => w !== '')
+}
+
+/** true when the words run a GATE: `shipkit ci`, the cli by path
+ *  (`bun <dir>/cli.ts ci`), or the `test` and `ci` package scripts. One suite
+ *  while iterating (`bun run test:raw <file>`) is not a gate */
+function isGate(words: string[]): boolean {
+    const [a, b, c] = words.map((w) => w.split('/').pop() ?? w)
+    if (a === 'shipkit') return b === 'ci'
+    if ((a === 'bunx' || a === 'npx') && b === 'shipkit') return c === 'ci'
+    if (a === 'cli.ts') return b === 'ci'
+    if (a === 'bun' || a === 'node') {
+        if (b === 'cli.ts') return c === 'ci'
+        if (b === 'run') return c === 'test' || c === 'ci'
+    }
+    return false
+}
+
+/** the segment of a command that pipes a gate into something else, or null.
+ *  A pipeline exits with its LAST command's code, so `shipkit ci | tail`
+ *  reports the green of tail over a red gate. A `>` redirect keeps the gate's
+ *  own exit code and stays allowed, and so does a pipeline under
+ *  `set -o pipefail` */
+export function pipedGateIn(command: string): string | null {
+    const parts = shellParts(command)
+    if (parts.some((p) => /^\s*set\s.*\bpipefail\b/.test(p.seg))) return null
+    for (const p of parts) {
+        if (p.op !== '|') continue
+        const words = programWords(p.seg)
+        if (words[0] != null && PROGRAM_WORD.test(words[0]) && isGate(words)) return p.seg.trim()
+    }
+    return null
+}
+
+/** what a piped gate refusal says: why, what to type instead, how to lift it */
+export function pipedGateRefusal(segment: string): string {
+    return `\`${segment.slice(0, 80)}\` pipes a gate: a pipeline exits with its LAST command's code, so a red gate reads green. Run the gate bare (a \`> file\` redirect keeps its exit code and is fine), then read its output in a separate call. Lifting this: put \`set -o pipefail;\` first, or remove the one-way-in-guard hook from .claude/settings.json (agent/process.md, never pipe a gating command).`
+}
+
 /** the raw runner this shell command reaches for, plus the segment that
  *  offended, or null.
  *
@@ -156,19 +224,7 @@ export function rawRunnerHit(command: string, only?: ReadonlySet<string>): { run
         .filter((r) => only == null || only.has(r.head))
         .sort((a, b) => b.head.length - a.head.length)
     for (const seg of shellSegments(command)) {
-        let s = seg.trim().replace(/^[(){}\s]+/, '')
-        // leading VAR=value assignments, then a wrapper word, repeatedly. A
-        // wrapper's own flags and durations go with it (`timeout 60 bun test`)
-        let wrapped = false
-        for (;;) {
-            const next = s.replace(/^\w+=(?:"[^"]*"|'[^']*'|\S*)\s+/, '')
-            if (next !== s) { s = next; continue }
-            const w = /^(\S+)\s+/.exec(s)
-            if (w != null && WRAPPERS.has(w[1]!.split('/').pop() ?? '')) { s = s.slice(w[0].length); wrapped = true; continue }
-            if (wrapped && w != null && /^(?:-\S*|\d+[smhd]?)$/.test(w[1]!)) { s = s.slice(w[0].length); continue }
-            break
-        }
-        const words = s.split(/\s+/).filter((w) => w !== '')
+        const words = programWords(seg)
         const first = words[0]
         if (first == null || !PROGRAM_WORD.test(first)) continue
         // a path-qualified binary counts: ./node_modules/.bin/tsc IS tsc

package/src/core/outcome-words.ts

@@ -0,0 +1,45 @@
+// the words every surface prints for what a run did with a check. One word
+// per outcome, shared, so the cli, the hub and the docs never drift apart.
+//   ran           the body executed this run
+//   cached        the answer came back from the cache, nothing executed
+//   never cached  the check declares nothing a cache key can describe
+//   attached      another run was executing the same question, this one took its answer
+
+export const RAN = 'ran'
+export const CACHED = 'cached'
+export const NEVER_CACHED = 'never cached'
+export const ATTACHED = 'attached'
+
+export type Outcome = typeof RAN | typeof CACHED
+
+/** the one word for a finished check: `replayed` is the run record's column */
+export const outcomeWord = (replayed: boolean): Outcome => (replayed ? CACHED : RAN)
+
+/** `1 check`, `2 checks` */
+export const plural = (n: number, one: string, many = `${one}s`): string => `${n} ${n === 1 ? one : many}`
+
+export type OutcomeCounts = { cached: number; ran: number; attached?: number; neverCached?: number }
+
+/** `41 cached, 8 ran`, plus `2 attached to another run` and `9 never cached`
+ *  when given. Attached shows only when some check attached */
+export function outcomeCounts(c: OutcomeCounts): string {
+    const parts = [`${c.cached} ${CACHED}`, `${c.ran} ${RAN}`]
+    if ((c.attached ?? 0) > 0) parts.push(`${c.attached} ${ATTACHED} to another run`)
+    if (c.neverCached != null) parts.push(`${c.neverCached} ${NEVER_CACHED}`)
+    return parts.join(', ')
+}
+
+/** a check's last recorded verdict in words, the same on the hub tree and in
+ *  the feed line `shipkit needs` prints */
+export const checkVerdictWords = (status: 'pass' | 'warn' | 'fail' | 'skip' | null, o: { replayed: boolean; advisory: boolean }): string =>
+    status === 'fail'
+        ? o.advisory ? 'failed, does not block the gate' : 'failed'
+        : status === 'warn' ? 'warned'
+            : status === 'skip' ? 'skipped'
+                : status === 'pass' ? (o.replayed ? `passed, ${CACHED}` : 'passed') : 'never ran here'
+
+/** the stamp on the first line of a cached check: `(cached, 5.6s saved)` */
+export const cachedStamp = (savedMs: number): string => `(${CACHED}, ${(savedMs / 1000).toFixed(1)}s saved)`
+
+/** the stamp on the first line of an attached check */
+export const attachedStamp = (pid: number, ranMs: number): string => `(${ATTACHED} to pid ${pid}, ${RAN} there in ${(ranMs / 1000).toFixed(1)}s)`

package/src/core/package-manager.ts

@@ -0,0 +1,86 @@
+// which package manager a repo updates with, decided by its lock files. a
+// repo whose deploy runs `npm ci` is broken by an update made with another
+// manager: package.json moves, package-lock.json does not, and `npm ci`
+// refuses a lock that disagrees with the manifest, so the failure lands at
+// deploy time with every local gate green.
+//
+// TRACKED locks decide, because an untracked bun.lock is exactly what a wrong
+// update leaves behind, and reading it as the repo's choice would make that
+// first mistake permanent. Nothing tracked (a fresh tree, no git) falls back
+// to what sits on disk. Among several, the order below IS the preference, and
+// the loser is named so the drift is visible. No lock at all is bun, the
+// house default.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { gitBin } from './git-bin.ts'
+
+export type PackageManagerName = 'bun' | 'npm' | 'pnpm' | 'yarn'
+
+export type PackageManager = {
+    name: PackageManagerName
+    /** the lock files it writes, for a git dirty probe over the manifest */
+    locks: string[]
+    /** install what is already declared */
+    install: string[]
+    /** move these deps to their latest version, manifest AND lock in one call */
+    update: (names: string[]) => string[]
+    /** set when several managers own a lock here, so the pick is a guess */
+    warn?: string
+}
+
+const BUN_LOCKS = ['bun.lock', 'bun.lockb']
+export const LOCK_FILES = [...BUN_LOCKS, 'pnpm-lock.yaml', 'yarn.lock', 'package-lock.json']
+
+const bun: PackageManager = {
+    name: 'bun',
+    locks: BUN_LOCKS,
+    install: ['bun', 'install'],
+    update: (names) => ['bun', 'update', '--latest', ...names],
+}
+const npm: PackageManager = {
+    name: 'npm',
+    locks: ['package-lock.json'],
+    install: ['npm', 'install'],
+    update: (names) => ['npm', 'install', ...names.map((n) => `${n}@latest`)],
+}
+const pnpm: PackageManager = {
+    name: 'pnpm',
+    locks: ['pnpm-lock.yaml'],
+    install: ['pnpm', 'install'],
+    update: (names) => ['pnpm', 'update', '--latest', ...names],
+}
+// berry dropped `upgrade` and classic never had `up`, and a .yarnrc.yml is
+// the cheap separator between the two
+const yarn = (berry: boolean): PackageManager => ({
+    name: 'yarn',
+    locks: ['yarn.lock'],
+    install: ['yarn', 'install'],
+    update: berry ? (names) => ['yarn', 'up', ...names.map((n) => `${n}@latest`)] : (names) => ['yarn', 'upgrade', '--latest', ...names],
+})
+
+/** lock files git tracks at the root, empty outside a repo */
+export function trackedLocks(root: string): string[] {
+    try {
+        const p = Bun.spawnSync([gitBin(), 'ls-files', '--', ...LOCK_FILES], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+        if (p.exitCode !== 0) return []
+        return p.stdout.toString().split('\n').map((l) => l.trim()).filter((l) => l !== '')
+    } catch {
+        return []
+    }
+}
+
+/** the manager this repo installs with, read off its lock files */
+export function detectPackageManager(root: string, tracked: string[] = trackedLocks(root)): PackageManager {
+    const present = LOCK_FILES.filter((f) => existsSync(join(root, f)))
+    const owned = present.filter((f) => tracked.includes(f))
+    const locks = owned.length > 0 ? owned : present
+    const has = (f: string): boolean => locks.includes(f)
+    let pick = bun
+    if (BUN_LOCKS.some(has)) pick = bun
+    else if (has('pnpm-lock.yaml')) pick = pnpm
+    else if (has('yarn.lock')) pick = yarn(existsSync(join(root, '.yarnrc.yml')))
+    else if (has('package-lock.json')) pick = npm
+    const others = locks.filter((f) => !pick.locks.includes(f))
+    if (others.length === 0) return pick
+    return { ...pick, warn: `several lock files at the root (${locks.join(', ')}) — updating with ${pick.name}, so ${others.join(', ')} will drift; delete the one this repo does not install with` }
+}

package/src/core/parallel.ts

@@ -0,0 +1,21 @@
+// THE POOL SIZE: how many checks this MACHINE measures at once, across every
+// shipkit process (core/slots.ts owns the pool). One function, so the runner
+// and the hub read the same number. A machine resource, not a
+// repo fact: only the machine's environment sets it.
+export const PARALLEL_ENV = 'SHIPKIT_PARALLEL'
+
+/** the machine's cores, never below 2 (one slow check must not starve the
+ *  rest) and never above 8 (each check is often a whole tool process) */
+export const defaultParallel = (): number => Math.max(2, Math.min(8, navigator.hardwareConcurrency || 4))
+
+/** the size and where it came from. A value nobody can use is named rather
+ *  than guessed at, and the default holds. */
+export function parallelCapInfo(): { cap: number; source: 'env' | 'default'; problem: string | null } {
+    const raw = process.env[PARALLEL_ENV]
+    if (raw == null || raw === '') return { cap: defaultParallel(), source: 'default', problem: null }
+    const n = Number(raw)
+    if (Number.isInteger(n) && n >= 1) return { cap: n, source: 'env', problem: null }
+    return { cap: defaultParallel(), source: 'default', problem: `${PARALLEL_ENV}=${raw} is not a whole number of at least 1, so the default ${defaultParallel()} holds` }
+}
+
+export const parallelCap = (): number => parallelCapInfo().cap

package/src/core/process-tree.ts

@@ -0,0 +1,44 @@
+// THE PROCESS TREE: one `ps` read of who is whose parent, shared by the
+// spawn timeout's tree kill and the restart reap (core/instance.ts).
+
+/** one `ps` snapshot, `pid ppid` per line, the same invocation on darwin and
+ *  linux. Unreadable means an empty tree, never a thrown kill. */
+export function psSnapshot(): string {
+    const ps = Bun.which('ps')
+    if (ps == null) return ''
+    try {
+        const r = Bun.spawnSync([ps, '-Ao', 'pid=,ppid='])
+        return r.success ? r.stdout.toString() : ''
+    } catch {
+        return ''
+    }
+}
+
+/** every descendant of `root`, DEEPEST FIRST, so a child is signalled before
+ *  the parent that could spawn another one. Enumerate before killing: once the
+ *  parent dies its children are reparented and the link to `root` is gone. */
+export function descendantPids(root: number, snapshot?: string): number[] {
+    const kids = new Map<number, number[]>()
+    for (const line of (snapshot ?? psSnapshot()).split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line)
+        if (m == null) continue
+        const pid = Number(m[1])
+        const ppid = Number(m[2])
+        if (pid === ppid || pid === 0) continue
+        const list = kids.get(ppid)
+        if (list == null) kids.set(ppid, [pid])
+        else list.push(pid)
+    }
+    const out: number[] = []
+    const seen = new Set<number>([root])
+    const walk = (pid: number): void => {
+        for (const kid of kids.get(pid) ?? []) {
+            if (seen.has(kid)) continue // a ppid loop is impossible, a stale snapshot is not
+            seen.add(kid)
+            walk(kid)
+            out.push(kid)
+        }
+    }
+    walk(root)
+    return out
+}

package/src/core/raw-access.ts

@@ -0,0 +1,93 @@
+// RAW ACCESS, found statically. A `run` check is cached on what it read through
+// `c` only while nothing it can call reads the disk or spawns a process around
+// `c`. So its repo-local import closure (installs excluded) is scanned for the
+// shapes that could, and ONE hit keeps it uncached.
+//
+// Conservative on purpose: a module that imports `fs` only to write, or never
+// calls the import, still counts. A false "never cached" costs speed, a missed
+// read costs a wrong green, and the two are not symmetric.
+import { readFileSync } from 'fs'
+import { join, relative } from 'path'
+import { loadConfig, type RvtConfig } from '../ts/config.ts'
+import { importClosure } from '../ts/source-graph.ts'
+
+/** where a module reaches the disk or a process around the check context */
+export type RawAccess = { file: string; line: number; what: string }
+
+const IMPORTS = { re: /\b(?:from\s*|import\s*\(\s*|require\s*\(\s*|import\s+)(['"])(?:node:)?(fs(?:\/promises)?|child_process)\1/, what: (m: RegExpMatchArray) => `imports ${m[2]}` }
+/** the load time half: a dynamic `import()` or `require()` is left to the call that runs it */
+const STATIC_IMPORTS = { re: /\b(?:from\s*|import\s+)(['"])(?:node:)?(fs(?:\/promises)?|child_process)\1/, what: (m: RegExpMatchArray) => `imports ${m[2]}` }
+const CALLS = { re: /\bBun\s*\.\s*(file|spawn|spawnSync|write|\$)(?![\w$])\s*[(`]/, what: (m: RegExpMatchArray) => `calls Bun.${m[1]}` }
+
+/** what closure a walk follows. A CHECK file's body can run anything it
+ *  imports, dynamically or not, so its walk follows `import()` too. The
+ *  CONFIG's value is what its module LOAD computes, so a literal `import()`
+ *  inside a function it exports is not part of it: `dynamic: false` */
+export type ClosureKind = { dynamic?: boolean }
+
+/** the first raw access in one source text, 1-based line, comments skipped */
+export function rawAccessInSource(src: string, o: ClosureKind = {}): { line: number; what: string } | null {
+    const memo = o.dynamic === false ? staticHits : allHits
+    const hit = memo.get(src)
+    if (hit !== undefined) return hit == null ? null : { ...hit }
+    const found = scanSource(src, o)
+    if (memo.size >= HITS_MEMO_MAX) memo.clear()
+    memo.set(src, found)
+    return found == null ? null : { ...found }
+}
+
+/** a pure function of the text, asked of the same closures by every gate, so
+ *  the answer is remembered per text */
+const allHits = new Map<string, { line: number; what: string } | null>()
+const staticHits = new Map<string, { line: number; what: string } | null>()
+const HITS_MEMO_MAX = 4000
+
+function scanSource(src: string, o: ClosureKind): { line: number; what: string } | null {
+    const SHAPES = [o.dynamic === false ? STATIC_IMPORTS : IMPORTS, CALLS]
+    const lines = src.split('\n')
+    let inBlock = false
+    for (let i = 0; i < lines.length; i++) {
+        let l = lines[i]!
+        if (inBlock) {
+            const end = l.indexOf('*/')
+            if (end < 0) continue
+            l = l.slice(end + 2)
+            inBlock = false
+        }
+        l = l.replace(/\/\*.*?\*\//g, '')
+        const open = l.indexOf('/*')
+        if (open >= 0) { inBlock = true; l = l.slice(0, open) }
+        l = l.replace(/(^|\s)\/\/.*$/, '$1')
+        if (/^\s*import\s+type\b/.test(l)) continue
+        for (const s of SHAPES) {
+            const m = l.match(s.re)
+            if (m != null) return { line: i + 1, what: s.what(m) }
+        }
+    }
+    return null
+}
+
+/** the first raw access in the import closure of `file`, walked from `root`
+ *  (the repo for a repo check, the toolkit for a built-in). Installs are never
+ *  scanned, and neither is `skip`, the toolkit's own tree when it sits inside
+ *  the repo: the toolchain id covers it exactly as it covers an install.
+ *  Throws when the closure cannot be walked, which the caller counts as a hit */
+export function rawAccessInClosure(root: string, file: string, o: { skip?: string; configs?: Map<string, RvtConfig> } & ClosureKind = {}): RawAccess | null {
+    // one pass over many checks under one root hands in `configs`, so the
+    // root's config (a walk of its source tree) is read once for all of them
+    let loaded = o.configs?.get(root)
+    if (loaded == null) { loaded = loadConfig(root); o.configs?.set(root, loaded) }
+    const cfg = { ...loaded, root }
+    const skipped = (f: string): boolean => f.split('/').includes('node_modules') || (o.skip != null && join(root, f).startsWith(`${o.skip}/`))
+    const files = importClosure(cfg, [relative(root, file).replace(/\\/g, '/')], o).filter((f) => !skipped(f))
+    for (const f of files) {
+        let src: string
+        try { src = readFileSync(join(root, f), 'utf8') } catch { continue }
+        const hit = rawAccessInSource(src, o)
+        if (hit != null) return { file: f, ...hit }
+    }
+    return null
+}
+
+/** the one line a surface prints about a hit */
+export const rawAccessLine = (r: RawAccess): string => `raw access in ${r.file}:${r.line} (${r.what}): read through c, or declare inputs or never`

package/src/core/read-set.ts

@@ -0,0 +1,152 @@
+// WHAT A CHECK READ, as it read it. The check context (core/check-ctx.ts) is
+// the only door a `run` body has to the repo, so every file, existence probe
+// and listing it asked for lands here with the hash of what it saw. The ledger
+// stores that set beside the answer, and a later run replays the answer only
+// while every entry still hashes the same.
+//
+// A file is hashed from the bytes the check actually read, with git's own blob
+// formula, so the record describes what the body saw even when the file moved
+// a millisecond later: the next run hashes the disk again, the two differ, and
+// the check runs. Nothing here can turn a mid-run edit into a replay.
+import { createHash } from 'crypto'
+import { lstatSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+
+/** `file` or `dir` when the path was there, null when it was not */
+export type PathKind = 'file' | 'dir' | null
+
+/** one check's reads, sorted and serialisable: what the ledger stores */
+export type ReadSet = {
+    /** repo-relative path → git blob id of the bytes read, null = absent */
+    files: Record<string, string | null>
+    /** repo-relative path → what stood there when it was asked */
+    exists: Record<string, PathKind>
+    /** glob → hash of the sorted listing it returned */
+    lists: Record<string, string>
+    /** repo-relative dir → hash of its entries as read from the disk, null =
+     *  no dir there. Absent from a set stored before it existed */
+    dirs?: Record<string, string | null>
+    /** repo-relative path → whether a symlink stood there. Absent from a set
+     *  stored before it existed */
+    links?: Record<string, boolean>
+}
+
+/** one entry of a directory, as `c.entries` returns it */
+export type DirEntry = { name: string; kind: 'file' | 'dir' }
+
+/** git's blob id of these bytes, computed in process */
+export function blobOid(bytes: Uint8Array): string {
+    return createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex')
+}
+
+/** the identity of one listing: the paths, sorted, as one hash */
+export function listingHash(paths: readonly string[]): string {
+    return createHash('sha256').update(paths.join('\n')).digest('hex').slice(0, 16)
+}
+
+export function kindOf(abs: string): PathKind {
+    try {
+        const s = statSync(abs)
+        return s.isDirectory() ? 'dir' : 'file'
+    } catch {
+        return null
+    }
+}
+
+/** whether a symlink stands at `abs` itself, not what it points at */
+export function isLinkAt(abs: string): boolean {
+    try {
+        return lstatSync(abs).isSymbolicLink()
+    } catch {
+        return false
+    }
+}
+
+/** the entries directly inside `abs`, from the disk (ignored ones included),
+ *  sorted by name, null when no dir stands there. A symlink takes the kind of
+ *  what it points at, and a dangling one is left out, as nothing is there */
+export function dirEntries(abs: string): DirEntry[] | null {
+    let names: string[]
+    try {
+        if (!statSync(abs).isDirectory()) return null
+        names = readdirSync(abs)
+    } catch {
+        return null
+    }
+    const out: DirEntry[] = []
+    for (const name of names.sort()) {
+        const kind = kindOf(join(abs, name))
+        if (kind != null) out.push({ name, kind })
+    }
+    return out
+}
+
+/** the identity of one dir read, null for no dir */
+export function entriesHash(entries: readonly DirEntry[] | null): string | null {
+    return entries == null ? null : listingHash(entries.map((e) => `${e.kind === 'dir' ? 'd' : 'f'} ${e.name}`))
+}
+
+/** the blob id of the file on disk now, null when there is no file to read */
+export function oidOnDisk(abs: string): string | null {
+    try {
+        return blobOid(readFileSync(abs))
+    } catch {
+        return null
+    }
+}
+
+/** the recorder a context writes into. Merging is how a shared scan's reads
+ *  reach every check that used it. */
+export class Reads {
+    readonly files = new Map<string, string | null>()
+    readonly exists = new Map<string, PathKind>()
+    readonly lists = new Map<string, string>()
+    readonly dirs = new Map<string, string | null>()
+    readonly links = new Map<string, boolean>()
+
+    file(path: string, oid: string | null): void { this.files.set(path, oid) }
+    exist(path: string, kind: PathKind): void { this.exists.set(path, kind) }
+    list(glob: string, hash: string): void { this.lists.set(glob, hash) }
+    dir(path: string, hash: string | null): void { this.dirs.set(path, hash) }
+    link(path: string, is: boolean): void { this.links.set(path, is) }
+
+    merge(o: Reads): void {
+        for (const [k, v] of o.files) this.files.set(k, v)
+        for (const [k, v] of o.exists) this.exists.set(k, v)
+        for (const [k, v] of o.lists) this.lists.set(k, v)
+        for (const [k, v] of o.dirs) this.dirs.set(k, v)
+        for (const [k, v] of o.links) this.links.set(k, v)
+    }
+
+    snapshot(): ReadSet {
+        const sorted = <V>(m: Map<string, V>): Record<string, V> => Object.fromEntries([...m].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        return { files: sorted(this.files), exists: sorted(this.exists), lists: sorted(this.lists), dirs: sorted(this.dirs), links: sorted(this.links) }
+    }
+}
+
+/** the first entry of `set` that no longer holds, or null when every one
+ *  does. `list` answers a glob the way `c.list` would right now, and returns
+ *  null when it cannot answer honestly (no git scan), which counts as drift. */
+export function readSetDrift(root: string, set: ReadSet, list: (glob: string) => readonly string[] | null): string | null {
+    for (const [p, oid] of Object.entries(set.files)) {
+        const now = oidOnDisk(join(root, p))
+        if (now !== oid) return `${p} ${oid == null ? 'appeared' : now == null ? 'is gone' : 'changed'}`
+    }
+    for (const [p, kind] of Object.entries(set.exists)) {
+        const now = kindOf(join(root, p))
+        if (now !== kind) return `${p} ${kind == null ? 'appeared' : now == null ? 'is gone' : `is a ${now} now`}`
+    }
+    for (const [g, hash] of Object.entries(set.lists)) {
+        const now = list(g)
+        if (now == null) return `${g} cannot be listed without a git scan`
+        if (listingHash(now) !== hash) return `the files matching ${g} changed`
+    }
+    for (const [d, hash] of Object.entries(set.dirs ?? {})) {
+        const now = entriesHash(dirEntries(join(root, d)))
+        if (now !== hash) return `${d}/ ${hash == null ? 'appeared' : now == null ? 'is gone' : 'changed its entries'}`
+    }
+    for (const [p, was] of Object.entries(set.links ?? {})) {
+        if (isLinkAt(join(root, p)) !== was) return `${p} ${was ? 'is no longer a link' : 'became a link'}`
+    }
+    return null
+}