rvlib-shipkit 1.5.0 → 1.6.0

package/src/core/ignored-inputs.ts

@@ -0,0 +1,47 @@
+// IGNORED INPUTS, the pure half: the kept audit's shape and what a task's key
+// takes from it and from `repo.config.ts ignoredInputs`. No fs here, so a
+// check keyed on its reads can import it (core/audit-report.ts reads the file).
+
+export type AuditTask = {
+    id: string
+    /** `audited` when its trace had no hole, else why it could not be */
+    status: 'audited' | 'unaudited'
+    why?: string
+    /** ignored paths it read that its key does not cover */
+    uncovered: string[]
+    /** the fewest `ignoredInputs` entries that cover them */
+    propose: string[]
+}
+
+export type AuditReport = {
+    at: number
+    /** why nothing was traced on this machine, when nothing was */
+    skipped?: string
+    tasks: AuditTask[]
+}
+
+/** what the kept audit says this task reads outside its key */
+export function auditedExtras(r: AuditReport | null, id: string): string[] {
+    if (r == null || r.skipped != null) return []
+    return r.tasks.find((x) => x.id === id)?.propose ?? []
+}
+
+/** the audit's entries that `have` does not carry yet, per task */
+export function pendingByTask(r: AuditReport | null, have: IgnoredInputs): IgnoredInputs {
+    const out: IgnoredInputs = {}
+    if (r == null || r.skipped != null) return out
+    for (const t of r.tasks) {
+        const missing = (t.propose ?? []).filter((p) => !(have['*'] ?? []).includes(p) && !(have[t.id] ?? []).includes(p))
+        if (missing.length > 0) out[t.id] = missing
+    }
+    return out
+}
+
+/** `ignoredInputs`: task id → gitignored paths it reads, `'*'` for every task */
+export type IgnoredInputs = Record<string, string[]>
+
+/** the entries that join one task's key */
+export const ignoredFor = (ii: IgnoredInputs | undefined, id: string): string[] => [...(ii?.['*'] ?? []), ...(ii?.[id] ?? [])]
+
+/** `task: a, b; other: c`, for a line */
+export const describeByTask = (by: IgnoredInputs): string => Object.entries(by).map(([t, ps]) => `${t}: ${ps.join(', ')}`).join('; ')

package/src/core/jobs.ts

@@ -58,7 +58,14 @@ let seq = 0
 /** what a job the daemon starts carries beside its flags: the run's options
  *  as the runner takes them, one lib copy for the repo config, and the
  *  machine's one background turn for a run nobody waits on */
-export type JobOpts = { opts: Record<string, unknown>; oneLib?: boolean; turn?: boolean }
+export type JobOpts = {
+    opts: Record<string, unknown>
+    oneLib?: boolean
+    turn?: boolean
+    /** the switches the asking terminal had set (home/via-hub.ts): the job
+     *  starts from the daemon's env, which never saw them */
+    env?: Record<string, string>
+}
 
 /** start `shipkit <kind> <args> --job <id>` detached from this process and
  *  its terminal, and return at once */
@@ -69,7 +76,7 @@ export function startJob(root: string, o: { cli: string; kind: JobKind; args: st
     mkdirSync(dir, { recursive: true })
     if (o.job != null) atomicWrite(jobOpts(root, id), JSON.stringify(o.job))
     const out = openSync(join(dir, 'out.log'), 'a')
-    const child = spawn(process.execPath, [o.cli, o.kind, ...o.args, '--job', id], { cwd: root, detached: true, stdio: ['ignore', out, out], env: process.env })
+    const child = spawn(process.execPath, [o.cli, o.kind, ...o.args, '--job', id], { cwd: root, detached: true, stdio: ['ignore', out, out], env: { ...process.env, ...o.job?.env } })
     closeSync(out)
     child.unref()
     const pid = child.pid ?? 0

package/src/core/one-lib.ts

@@ -2,11 +2,14 @@
 // (the home) makes every `rvlib-shipkit` import, from any repo config or check
 // file, land on its OWN copy. A repo's install is never loaded, so there is one
 // module instance per lib file: one mobx, one class identity, one version.
+// The same holds for a package whose objects cross between a repo file and
+// the toolkit (SHARED): a repo's brand draws on a canvas the toolkit made,
+// and a native class only accepts instances of its own copy.
 //
 // the one constraint a reader breaks first: register it BEFORE the first repo
 // config is imported. A module already loaded keeps the copy it resolved.
-import { readFileSync, realpathSync } from 'fs'
-import { extname, join } from 'path'
+import { existsSync, readFileSync, realpathSync } from 'fs'
+import { dirname, extname, join } from 'path'
 import { LIB_ROOT } from './lib-root.ts'
 
 const NAME = 'rvlib-shipkit'
@@ -54,6 +57,46 @@ const real = (p: string): string => {
     }
 }
 
+/** packages a repo file and the toolkit hand objects of to each other */
+export const SHARED: readonly string[] = ['@napi-rs/canvas', 'comfy-ts']
+
+/** a file of ANOTHER copy of a shared package, as the path inside that copy,
+ *  else null. `host` is the root of the copy this process loads */
+export function foreignSharedPath(path: string, name: string, host: string | null): string | null {
+    const at = path.lastIndexOf(`/node_modules/${name}/`)
+    if (at === -1) return null
+    const root = path.slice(0, at + `/node_modules/${name}`.length)
+    if (host == null || root === host || real(root) === real(host)) return null
+    return path.slice(root.length + 1)
+}
+
+const hostRoot = (name: string, from: string): string | null => {
+    try {
+        return dirname(Bun.resolveSync(`${name}/package.json`, from))
+    } catch {
+        return null
+    }
+}
+
+/** where a foreign copy's file lands in the host copy: its entry on the
+ *  host's entry (the two can name different files), any other file on the
+ *  same path, else on the entry */
+const sharedTarget = (path: string, sub: string, name: string, host: string): string => {
+    const entry = Bun.resolveSync(name, host)
+    const foreignDir = path.slice(0, path.length - sub.length - 1)
+    try {
+        if (real(Bun.resolveSync(name, foreignDir)) === real(path)) return entry
+    } catch {
+        /* a foreign copy with no entry of its own: its files map by path */
+    }
+    return existsSync(join(host, sub)) ? join(host, sub) : entry
+}
+
+const reexport = (target: string): { contents: string; loader: 'ts' } => {
+    const t = JSON.stringify(target)
+    return { contents: `export * from ${t}\nimport * as own from ${t}\nexport default (own as { default?: unknown }).default\n`, loader: 'ts' }
+}
+
 const LOADERS: Record<string, 'ts' | 'tsx' | 'js' | 'jsx'> = { '.ts': 'ts', '.tsx': 'tsx', '.js': 'js', '.mjs': 'js', '.jsx': 'jsx' }
 
 let installed = false
@@ -77,9 +120,21 @@ export function useOneLib(root: string = LIB_ROOT): void {
                 const loader = LOADERS[extname(a.path)] ?? 'ts'
                 const sub = foreignLibPath(a.path, root)
                 if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader }
-                const target = JSON.stringify(join(root, sub))
-                return { contents: `export * from ${target}\nimport * as own from ${target}\nexport default (own as { default?: unknown }).default\n`, loader: 'ts' }
+                return reexport(join(root, sub))
             })
+            for (const name of SHARED) {
+                const host = hostRoot(name, root)
+                if (host == null) continue
+                // the host copy never matches: a CommonJS file read back here
+                // loses the named exports bun infers for it
+                const esc = (s: string): string => s.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+                const skip = [...new Set([host, real(host)])].map((h) => `(?!${esc(h)}/)`).join('')
+                build.onLoad({ filter: new RegExp(`^${skip}.*/node_modules/${esc(name)}/`) }, (a) => {
+                    const sub = foreignSharedPath(a.path, name, host)
+                    if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader: LOADERS[extname(a.path)] ?? 'js' }
+                    return reexport(sharedTarget(a.path, sub, name, host))
+                })
+            }
         },
     })
 }

package/src/core/read-set.ts

@@ -9,8 +9,8 @@
 // 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'
+import { lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from 'fs'
+import { isAbsolute, join } from 'path'
 
 /** `file` or `dir` when the path was there, null when it was not */
 export type PathKind = 'file' | 'dir' | null
@@ -29,6 +29,60 @@ export type ReadSet = {
     /** repo-relative path → whether a symlink stood there. Absent from a set
      *  stored before it existed */
     links?: Record<string, boolean>
+    /** path → its stat signature (`statSig`). For a path in `files` it is a
+     *  fast path: an unchanged signature skips the content hash. For an
+     *  absolute path outside the repo it is the whole record: a traced task
+     *  reads its runtime and its tools there, which are too big to hash on
+     *  every replay and never shared between checkouts anyway */
+    sigs?: Record<string, string>
+    /** local port → `closed`: a traced task met a refusal there, and its
+     *  answer holds only while nothing listens on it */
+    ports?: Record<string, 'closed'>
+    /** symlink → its target, null when no link stands there: what a traced
+     *  task learned from readlink or lstat */
+    targets?: Record<string, string | null>
+}
+
+/** the target a symlink at `abs` points to, null when none stands there */
+export function linkTarget(abs: string): string | null {
+    try {
+        return readlinkSync(abs)
+    } catch {
+        return null
+    }
+}
+
+let listenMemo: { at: number; ports: Set<string> } | null = null
+
+/** the TCP ports something listens on right now, on any local address. One
+ *  netstat per second at most: a replay asks for several at once */
+export function listeningPorts(now = Date.now()): Set<string> {
+    if (listenMemo != null && now - listenMemo.at < 1_000) return listenMemo.ports
+    const ports = new Set<string>()
+    const r = Bun.spawnSync(['/usr/sbin/netstat', '-an', '-p', 'tcp'], { stdout: 'pipe', stderr: 'pipe' })
+    for (const line of r.stdout.toString().split('\n')) {
+        if (!/\bLISTEN\b/.test(line)) continue
+        const local = line.trim().split(/\s+/)[3] ?? ''
+        const port = local.slice(local.lastIndexOf('.') + 1)
+        if (/^\d+$/.test(port)) ports.add(port)
+    }
+    listenMemo = { at: now, ports }
+    return ports
+}
+
+/** a path as recorded: repo-relative, or absolute for one outside the repo */
+const at = (root: string, p: string): string => (isAbsolute(p) ? p : join(root, p))
+
+/** what stat says about a file: size, modification time to the nanosecond
+ *  and inode, `-` when nothing is there. Content can change under an equal
+ *  signature only when a tool restores the mtime on purpose */
+export function statSig(abs: string): string {
+    try {
+        const s = statSync(abs, { bigint: true })
+        return `${s.size}:${s.mtimeNs}:${s.ino}`
+    } catch {
+        return '-'
+    }
 }
 
 /** one entry of a directory, as `c.entries` returns it */
@@ -103,6 +157,9 @@ export class Reads {
     readonly lists = new Map<string, string>()
     readonly dirs = new Map<string, string | null>()
     readonly links = new Map<string, boolean>()
+    readonly sigs = new Map<string, string>()
+    readonly ports = new Map<string, 'closed'>()
+    readonly targets = new Map<string, string | null>()
 
     file(path: string, oid: string | null): void { this.files.set(path, oid) }
     exist(path: string, kind: PathKind): void { this.exists.set(path, kind) }
@@ -116,11 +173,26 @@ export class Reads {
         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)
+        for (const [k, v] of o.sigs) this.sigs.set(k, v)
+        for (const [k, v] of o.ports) this.ports.set(k, v)
+        for (const [k, v] of o.targets) this.targets.set(k, v)
+    }
+
+    /** a whole set, as a traced process read it (trace/read-trace.ts) */
+    mergeSet(s: ReadSet): void {
+        for (const [k, v] of Object.entries(s.files)) this.files.set(k, v)
+        for (const [k, v] of Object.entries(s.exists)) this.exists.set(k, v)
+        for (const [k, v] of Object.entries(s.lists)) this.lists.set(k, v)
+        for (const [k, v] of Object.entries(s.dirs ?? {})) this.dirs.set(k, v)
+        for (const [k, v] of Object.entries(s.links ?? {})) this.links.set(k, v)
+        for (const [k, v] of Object.entries(s.sigs ?? {})) this.sigs.set(k, v)
+        for (const [k, v] of Object.entries(s.ports ?? {})) this.ports.set(k, v)
+        for (const [k, v] of Object.entries(s.targets ?? {})) this.targets.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) }
+        return { files: sorted(this.files), exists: sorted(this.exists), lists: sorted(this.lists), dirs: sorted(this.dirs), links: sorted(this.links), ...(this.sigs.size > 0 ? { sigs: sorted(this.sigs) } : {}), ...(this.ports.size > 0 ? { ports: sorted(this.ports) } : {}), ...(this.targets.size > 0 ? { targets: sorted(this.targets) } : {}) }
     }
 }
 
@@ -128,25 +200,41 @@ export class Reads {
  *  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'}`
+    const sigs = set.sigs ?? {}
+    for (const [p, sig] of Object.entries(sigs)) {
+        if (p in set.files) continue
+        const now = statSig(at(root, p))
+        if (now !== sig) return `${p} ${sig === '-' ? 'appeared' : now === '-' ? 'is gone' : 'changed'}`
     }
     for (const [p, kind] of Object.entries(set.exists)) {
-        const now = kindOf(join(root, p))
+        const now = kindOf(at(root, p))
         if (now !== kind) return `${p} ${kind == null ? 'appeared' : now == null ? 'is gone' : `is a ${now} now`}`
     }
+    for (const [p, oid] of Object.entries(set.files)) {
+        const abs = at(root, p)
+        if (sigs[p] != null && statSig(abs) === sigs[p]) continue
+        const now = oidOnDisk(abs)
+        if (now !== oid) return `${p} ${oid == null ? 'appeared' : now == null ? 'is gone' : 'changed'}`
+    }
     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)))
+        const now = entriesHash(dirEntries(at(root, d)))
         if (now !== hash) return `${d}/ ${hash == null ? 'appeared' : now == null ? 'is gone' : 'changed its entries'}`
     }
+    for (const [p, t] of Object.entries(set.targets ?? {})) {
+        if (linkTarget(at(root, p)) !== t) return `${p} points elsewhere now`
+    }
+    const closed = Object.keys(set.ports ?? {})
+    if (closed.length > 0) {
+        const open = listeningPorts()
+        for (const port of closed) if (open.has(port)) return `a service listens on local port ${port} now`
+    }
     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'}`
+        if (isLinkAt(at(root, p)) !== was) return `${p} ${was ? 'is no longer a link' : 'became a link'}`
     }
     return null
 }

package/src/core/run-ci.ts

@@ -284,7 +284,12 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // stored under a key that describes the file as it was before the edit.
     // the counts line folds into the verdict; what else it says (a store
     // that failed, answers thrown away) is printed as it is
-    if (ledger != null) for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
+    if (ledger != null) {
+        for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
+        // why every check that did not replay ran, grouped: a re-run nobody
+        // can explain costs a reader more than the line does
+        for (const { line, quiet } of ledger.explain()) (quiet ? detail : sink)(formatLine(line, false))
+    }
     // one write for the whole gate, after everything has finished
     for (const l of runLog.flush()) sink(formatLine(l, false))
     const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownOff.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0

package/src/core/run-fixers.ts

@@ -9,7 +9,7 @@
 // mechanism, two modes, rather than a formatter plus a format:check that
 // drift apart.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
-import { dirname, join } from 'path'
+import { dirname, isAbsolute, join } from 'path'
 import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
@@ -136,7 +136,13 @@ function fixMemo(root: string, tree: Map<string, string>, cmds: string[][]): str
     const h = new Bun.CryptoHasher('sha256')
     h.update(`head=${head.stdout.toString().trim()}\n`)
     for (const [path, hash] of [...tree].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) h.update(`${path}\0${hash}\n`)
-    try { h.update(`toolchain=${toolchainIdentity(root, gateBinary()).id}\n`) } catch { return null }
+    // the runner, the install the fixer scripts run from, and the toolkit code
+    // this pass and its built-in fixers reach, never the toolkit as a whole
+    try {
+        const t = toolchainIdentity(root, gateBinary())
+        const own = [fileURLToPath(import.meta.url), ...cmds.flat().filter((a) => isAbsolute(a) && t.lib.owns(a))]
+        h.update(`toolchain=${t.id}:${t.install}:${t.lib.closureKey(own)}\n`)
+    } catch { return null }
     h.update(`cmds=${JSON.stringify(cmds)}\n`)
     return h.digest('hex')
 }

package/src/core/trace-audit.ts

@@ -0,0 +1,120 @@
+// THE TRACED AUDIT: which gitignored paths a task reads that its key cannot
+// see. A task's key covers the tracked tree and the paths `ignoredInputs`
+// names; a generated type or a local fixture it reads outside those is a
+// stale green waiting for its first edit. Each gate task runs once under the
+// tracer (trace/tracer.ts), and the ignored paths it touched that no key
+// covers become that task's proposals: the keys read them at once
+// (core/audit-report.ts), and `sk trace-audit --fix` writes them into their
+// own managed block of repo.config.ts (core/ignored-block.ts).
+//
+// The tracer never decides a verdict here. A hole in the trace (a child that
+// ran untraced) costs this audit that task, said out loud, and never a green.
+//
+// The tracing costs about one traced gate, so the answer is kept under the
+// git common dir and reused while it is young: rule SK031 in
+// the health pass pays for it, and the fix pass that applies it reads it.
+import { mkdirSync, writeFileSync } from 'fs'
+import { dirname, posix } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import { composeChecks } from '../ledger/gate-checks.ts'
+import { isNamesInput } from '../ledger/git-key.ts'
+import { readTrace } from '../trace/read-trace.ts'
+import { dropTrace, learnBlind, traceUnavailable, tracedCommand } from '../trace/tracer.ts'
+import { spawnWithTimeout } from './spawn-timeout.ts'
+import { gitBin } from './git-bin.ts'
+import { auditReportPath, ignoredFor, pendingByTask, readAuditReport, type AuditReport, type AuditTask, type IgnoredInputs } from './audit-report.ts'
+import { addIgnoredInputs } from './ignored-block.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+
+/** how long an audit answers for the tree: about a day, like SK030 */
+export const AUDIT_KEEP_MS = 20 * 60 * 60 * 1000
+
+export type { AuditReport, AuditTask } from './audit-report.ts'
+export { readAuditReport } from './audit-report.ts'
+
+/** the paths of `paths` git ignores */
+function gitIgnored(root: string, paths: string[]): Set<string> {
+    if (paths.length === 0) return new Set()
+    const p = Bun.spawnSync([gitBin(), 'check-ignore', '--stdin'], { cwd: root, stdin: Buffer.from(`${paths.join('\n')}\n`), stdout: 'pipe', stderr: 'pipe' })
+    return new Set(p.stdout.toString().split('\n').filter((l) => l !== ''))
+}
+
+const under = (p: string, dir: string): boolean => p === dir || p.startsWith(`${dir}/`)
+
+/** is this ignored path already in a key: bytes under a content entry, or a
+ *  listing or probe under a names entry */
+function covered(p: string, listing: boolean, extras: string[]): boolean {
+    return extras.some((e) => (isNamesInput(e) ? listing && under(p, e.slice(0, -3)) : under(p, e)))
+}
+
+/** the fewest entries that cover what was read: each file by itself, or its
+ *  dir once more than three files there were read; each listed dir as
+ *  `dir/**`, the outermost one only */
+export function proposeInputs(content: string[], listed: string[]): string[] {
+    const byDir = new Map<string, string[]>()
+    for (const f of content) byDir.set(posix.dirname(f), [...(byDir.get(posix.dirname(f)) ?? []), f])
+    const bytes = [...byDir].flatMap(([dir, files]) => (files.length > 3 && dir !== '.' ? [dir] : files))
+    const minimal = (xs: string[]): string[] => {
+        const sorted = [...new Set(xs)].sort()
+        return sorted.filter((x) => !sorted.some((y) => y !== x && under(x, y)))
+    }
+    return [...minimal(bytes), ...minimal(listed).map((d) => `${d}/**`)].sort()
+}
+
+/** trace every gate task of the repo once and report what its key misses */
+export async function traceAudit(root: string, config: RepoConfig, o: { fresh?: boolean; now?: number; env?: Record<string, string | undefined> } = {}): Promise<AuditReport> {
+    const now = o.now ?? Date.now()
+    const kept = readAuditReport(root)
+    if (o.fresh !== true && kept != null && kept.skipped == null && now - kept.at < AUDIT_KEEP_MS) return kept
+    const env = o.env ?? process.env
+    const off = traceUnavailable(env)
+    if (off != null) return { at: now, skipped: off, tasks: [] }
+    const tasks: AuditTask[] = []
+    for (const g of await composeChecks(root, config)) {
+        const u = g.runnable
+        if (u.body.cmd == null || g.row.runs.off != null || !g.row.runs.onCi || g.row.decl.inputs == null) continue
+        const cwd = u.body.cwd ?? root
+        const t = tracedCommand(u.body.cmd, cwd, env)
+        if ('reason' in t) { tasks.push({ id: u.id, status: 'unaudited', why: t.reason, uncovered: [], propose: [] }); continue }
+        try {
+            await spawnWithTimeout(t.cmd, { timeoutMs: u.timeoutMs, env: { ...process.env, ...u.body.env, ...t.env }, cwd })
+            const r = await readTrace(t.dir, root)
+            if (r.reads == null) {
+                const learned = r.blind.length > 0 ? learnBlind(r.blind) : null
+                tasks.push({ id: u.id, status: 'unaudited', why: [r.why, learned].filter((x) => x != null).join('; '), uncovered: [], propose: [] })
+                continue
+            }
+            // bytes: a file it opened or stat'ed, or found by a probe; a
+            // listing: a dir it read the entries of, or found by a probe
+            // Finder rewrites .DS_Store at will, and no tool's verdict reads it
+            const rel = (p: string): boolean => !p.startsWith('/') && p !== '.' && !p.split('/').includes('node_modules') && !p.startsWith('.git/') && posix.basename(p) !== '.DS_Store'
+            const files = [...new Set([...Object.keys(r.reads.files), ...Object.keys(r.reads.sigs ?? {}), ...Object.entries(r.reads.exists).filter(([, k]) => k === 'file').map(([p]) => p)])].filter(rel)
+            const dirs = [...new Set([...Object.keys(r.reads.dirs ?? {}), ...Object.entries(r.reads.exists).filter(([, k]) => k === 'dir').map(([p]) => p)])].filter(rel)
+            const ignored = gitIgnored(root, [...files, ...dirs])
+            const extras = ignoredFor(config.ignoredInputs, u.id)
+            const missF = files.filter((p) => ignored.has(p) && !covered(p, false, extras))
+            const missD = dirs.filter((p) => ignored.has(p) && !covered(p, true, extras))
+            tasks.push({ id: u.id, status: 'audited', uncovered: [...missF, ...missD].sort(), propose: proposeInputs(missF, missD) })
+        } finally {
+            dropTrace(t.dir)
+        }
+    }
+    const report: AuditReport = { at: now, tasks }
+    try {
+        mkdirSync(dirname(auditReportPath(root)), { recursive: true })
+        writeFileSync(auditReportPath(root), JSON.stringify(report, null, 2))
+    } catch { /* an audit that cannot be kept is measured again next time */ }
+    return report
+}
+
+/** write what the kept audit proposes into the managed block. Nothing is
+ *  traced here, so the fix pass can call it on every run */
+export async function applyAudit(root: string): Promise<{ added: IgnoredInputs; note: string | null }> {
+    const r = readAuditReport(root)
+    if (r == null || r.skipped != null) return { added: {}, note: r?.skipped ?? 'no audit yet: sk trace-audit runs one' }
+    const added = pendingByTask(r, (await loadRepoConfig(root, { fresh: true })).ignoredInputs ?? {})
+    if (Object.keys(added).length === 0) return { added, note: null }
+    await addIgnoredInputs(root, added)
+    return { added, note: null }
+}
+

package/src/home/gui-app.ts

@@ -4,12 +4,15 @@
 // and iconed after it, in its repo's `.shipkit/wrapper/`. The bundle's
 // Info.plist carries what differs (name, bundle id, start url), so a fix to
 // the window (find, the inspector, zoom) lands in every app at its next
-// build. Rebuilt only when the source, the icon or the start url changed (a
-// stamp in the bundle). No compiler, or not macOS: the caller falls back.
+// build. The icon is core/app-icon.ts: the repo's mark, its margin cut, on
+// a plate in the repo's colour. Rebuilt only when the source, the icon, the
+// colours or the start url changed (a stamp in the bundle). No compiler, or not macOS: the caller falls back.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+import { appIconOf, appIconPngs, identityOfRoot } from '../core/app-icon.ts'
+import { identityOfName, type Identity } from '../core/identity-color.ts'
 import { LAYOUT } from '../core/layout.ts'
 
 const SOURCE = fileURLToPath(new URL('./gui-app/ShipkitGui.swift', import.meta.url))
@@ -17,15 +20,6 @@ const SOURCE = fileURLToPath(new URL('./gui-app/ShipkitGui.swift', import.meta.u
 export const BUNDLE_ID = 'dev.shipkit.gui'
 export const guiAppPath = (): string => process.env.SHIPKIT_GUI_APP ?? join(homedir(), 'Applications', 'Shipkit.app')
 
-/** the icon the app wears: the repo's own mark, largest first. Only a
- *  png can become an icns */
-export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, 'public/logo.png', 'public/favicon.png']
-
-export function appIconOf(root: string): string | null {
-    for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
-    return null
-}
-
 /** what one app bundle is: the rest comes from the shared source */
 export type AppSpec = {
     /** CFBundleName: the dock, cmd-tab and the app menu say it */
@@ -34,6 +28,8 @@ export type AppSpec = {
     /** the page a launch with no url opens; null opens the home */
     url: string | null
     icon: string | null
+    /** the repo's colours: the plate behind the icon's mark */
+    identity: Identity
     /** where the bundle lands */
     app: string
     version: string
@@ -52,7 +48,7 @@ function atsOf(url: string | null): string {
     return `<dict><key>NSAllowsLocalNetworking</key><true/>${exception}</dict>`
 }
 
-export function infoPlist(o: Omit<AppSpec, 'app' | 'icon'>): string {
+export function infoPlist(o: Omit<AppSpec, 'app' | 'icon' | 'identity'>): string {
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -79,6 +75,9 @@ const runSync: Run = (cmd) => {
     return { code: p.exitCode ?? 1, err: p.stderr.toString().trim() }
 }
 
+/** bumped when the icon drawing changes, so every built app redraws its icon */
+const ICON_DRAWING = 'plate-1'
+
 /** the stamp a built bundle carries: what it was built from. The version is
  *  left out, so a shipkit release rebuilds nothing */
 export function stampOf(source: string, icon: string | null, identity = ''): string {
@@ -89,11 +88,11 @@ export function stampOf(source: string, icon: string | null, identity = ''): str
 
 /** one app, built or rebuilt when stale. Throws with the step that failed.
  *  `rebuilt` tells the caller a running copy is now the old one */
-export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {}): { app: string; rebuilt: boolean } {
+export async function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {}): Promise<{ app: string; rebuilt: boolean }> {
     const { app, icon } = spec
     const run = o.run ?? runSync
     const source = o.source ?? SOURCE
-    const stamp = stampOf(readFileSync(source, 'utf8'), icon, JSON.stringify([spec.name, spec.bundleId, spec.url]))
+    const stamp = stampOf(readFileSync(source, 'utf8'), icon, JSON.stringify([spec.name, spec.bundleId, spec.url, spec.identity, ICON_DRAWING]))
     const stampFile = join(app, 'Contents', 'Resources', 'stamp')
     if (existsSync(stampFile) && readFileSync(stampFile, 'utf8') === stamp) return { app, rebuilt: false }
     const tmp = `${app}.building-${process.pid}`
@@ -108,12 +107,10 @@ export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {})
     if (icon != null) {
         const set = join(res, 'AppIcon.iconset')
         mkdirSync(set, { recursive: true })
-        for (const n of [16, 32, 128, 256, 512]) {
-            for (const [scale, px] of [['', n], ['@2x', n * 2]] as const) {
-                const r = run(['sips', '-s', 'format', 'png', '-z', String(px), String(px), icon, '--out', join(set, `icon_${n}x${n}${scale}.png`)])
-                if (r.code !== 0) fail(`sips could not size the icon ${icon}: ${r.err.slice(0, 200)}`)
-            }
-        }
+        const files = [16, 32, 128, 256, 512].flatMap((n) => [[`icon_${n}x${n}.png`, n], [`icon_${n}x${n}@2x.png`, n * 2]] as const)
+        const pngs = await appIconPngs(readFileSync(icon), spec.identity, files.map(([, px]) => px))
+            .catch((e: Error) => fail(`could not draw the icon from ${icon}: ${e.message}`))
+        files.forEach(([file], i) => writeFileSync(join(set, file), pngs[i]!))
         const r = run(['iconutil', '-c', 'icns', set, '-o', join(res, 'AppIcon.icns')])
         rmSync(set, { recursive: true, force: true })
         if (r.code !== 0) fail(`iconutil could not build the icon: ${r.err.slice(0, 200)}`)
@@ -128,15 +125,15 @@ export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {})
 }
 
 /** the shipkit app: the shared source on the home, the house repo's icon */
-export function ensureGuiApp(o: { root: string | null; version: string; app?: string; run?: Run }): { app: string; rebuilt: boolean } {
-    return ensureApp({ name: 'shipkit', bundleId: BUNDLE_ID, url: null, icon: o.root == null ? null : appIconOf(o.root), app: o.app ?? guiAppPath(), version: o.version }, { run: o.run })
+export function ensureGuiApp(o: { root: string | null; version: string; app?: string; run?: Run }): Promise<{ app: string; rebuilt: boolean }> {
+    return ensureApp({ name: 'shipkit', bundleId: BUNDLE_ID, url: null, icon: o.root == null ? null : appIconOf(o.root), identity: o.root == null ? identityOfName('shipkit') : identityOfRoot(o.root), app: o.app ?? guiAppPath(), version: o.version }, { run: o.run })
 }
 
 /** what a global process gives its app */
 export type WrapperOf = { id: string; label: string; url: string | null; icon: string | null; root: string }
 
-/** the image icons sips reads; an emoji or an svg leaves the repo's mark */
-const RASTER = /\.(png|jpe?g|gif|webp|bmp|tiff?)$/i
+/** the images the icon renderer reads; an emoji or an svg leaves the repo's mark */
+const RASTER = /\.(png|jpe?g|gif|webp)$/i
 
 export const wrapperBundleId = (id: string): string => `dev.shipkit.app.${id.replace(/[^A-Za-z0-9-]+/g, '-')}`
 export const wrapperPath = (root: string, id: string): string => join(root, LAYOUT.wrapper, `${id.replace(/[^A-Za-z0-9._-]+/g, '-')}.app`)
@@ -147,12 +144,12 @@ export const wrapperPath = (root: string, id: string): string => join(root, LAYO
 export function wrapperSpec(d: WrapperOf, version: string): AppSpec {
     if (d.url == null) throw new Error(`${d.id} declares no url: there is no page to open as an app`)
     const declared = d.icon != null && RASTER.test(d.icon) && existsSync(join(d.root, d.icon)) ? join(d.root, d.icon) : null
-    return { name: d.label, bundleId: wrapperBundleId(d.id), url: d.url, icon: declared ?? appIconOf(d.root), app: wrapperPath(d.root, d.id), version }
+    return { name: d.label, bundleId: wrapperBundleId(d.id), url: d.url, icon: declared ?? appIconOf(d.root), identity: identityOfRoot(d.root), app: wrapperPath(d.root, d.id), version }
 }
 
-export const ensureWrapperApp = (d: WrapperOf, o: { version: string; run?: Run }): { app: string; rebuilt: boolean; bundleId: string } => {
+export const ensureWrapperApp = async (d: WrapperOf, o: { version: string; run?: Run }): Promise<{ app: string; rebuilt: boolean; bundleId: string }> => {
     const spec = wrapperSpec(d, o.version)
-    return { ...ensureApp(spec, { run: o.run }), bundleId: spec.bundleId }
+    return { ...(await ensureApp(spec, { run: o.run })), bundleId: spec.bundleId }
 }
 
 /** quits a running copy of an app, and launches nothing when none runs */