@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/testSelect.js

@@ -0,0 +1,129 @@
+/**
+ * Running every test on every merge is honest and slow. This narrows it.
+ *
+ * The serial merge queue rebases each task onto the integration branch and
+ * runs the operator's whole test command before merging. That is correct and
+ * it is quadratic: N tasks, each paying for the full cumulative suite. The
+ * graph `symbols.ts` already builds answers a cheaper question — which tests
+ * can even reach this change — by walking `dependents` (imported file -> its
+ * importers) out from the changed files until the frontier stops growing.
+ *
+ * The whole value of a test gate is that it fails when the code is wrong, so
+ * every ambiguity here resolves to running everything:
+ *
+ * - a changed file the scanner cannot read, or has never seen, or that is not
+ *   source at all (a `.yml`, a lockfile, a fixture) can affect anything;
+ * - a change no test reaches is more likely a stale graph than a change with
+ *   no coverage, and guessing wrong means merging untested code;
+ * - a module with a computed `import()` or an import that never resolved is
+ *   treated as reached by every change, because the scanner cannot prove it
+ *   is not. That keeps one opaque module from collapsing the whole selection
+ *   to `full`, while still never dropping the test that module lives in.
+ *
+ * Two things this deliberately does NOT do. It never narrows a typecheck —
+ * `tsc -p` is a whole-program question and a subset of files is a different,
+ * weaker question. And it never invents the command: the operator supplies a
+ * template with a `{files}` placeholder, and a template without one is an
+ * error rather than a silent full run reported as a selective one.
+ */
+import { extname } from 'node:path';
+import { SmithError } from './errors.js';
+import { DEFAULT_SOURCE_EXTENSIONS } from './symbols.js';
+export class TestSelectError extends SmithError {
+}
+/** `foo.test.ts`, `foo.spec.tsx`, `foo.test.mjs` — the conventional shapes. */
+const DEFAULT_TEST_PATTERN = /(^|\/)[^/]+\.(test|spec)\.[cm]?[jt]sx?$/;
+function isTest(file, options) {
+    return options.isTestFile ? options.isTestFile(file) : DEFAULT_TEST_PATTERN.test(file);
+}
+/** Modules the scanner admits it cannot fully see through. */
+function alwaysReached(graph) {
+    const opaque = new Set();
+    for (const [file, facts] of graph.modules) {
+        if (facts.opaqueImports.length > 0)
+            opaque.add(file);
+    }
+    for (const { from } of graph.unresolved)
+        opaque.add(from);
+    return opaque;
+}
+/**
+ * Which tests can reach `changedFiles`, or `full` with the reason it gave up.
+ * Pure: the graph and the change set come from the caller.
+ */
+export function selectTests(graph, changedFiles, options = {}) {
+    const allTests = [...graph.modules.keys()].filter((file) => isTest(file, options)).sort();
+    const full = (reason) => ({
+        status: 'full',
+        tests: allTests,
+        allTests,
+        reasons: [reason],
+    });
+    if (allTests.length === 0)
+        return full('the symbol graph knows no test files');
+    if (changedFiles.length === 0)
+        return full('no changed files were reported');
+    const sourceExtensions = new Set(DEFAULT_SOURCE_EXTENSIONS);
+    const unanalyzed = new Set(graph.unanalyzed);
+    for (const file of changedFiles) {
+        if (!sourceExtensions.has(extname(file))) {
+            return full(`${file} is not an analyzable source file, so it could affect any test`);
+        }
+        if (unanalyzed.has(file)) {
+            return full(`${file} is a file the scanner refused to read`);
+        }
+        if (!graph.modules.has(file)) {
+            return full(`${file} is not in the symbol graph`);
+        }
+    }
+    const reasons = [];
+    const opaque = alwaysReached(graph);
+    if (opaque.size > 0) {
+        reasons.push(`${opaque.size} module(s) with a computed import or an unresolved specifier are treated as reached`);
+    }
+    const reached = new Set();
+    const frontier = [...changedFiles, ...opaque];
+    while (frontier.length > 0) {
+        const file = frontier.pop();
+        if (file === undefined || reached.has(file))
+            continue;
+        reached.add(file);
+        for (const edge of graph.dependents.get(file) ?? []) {
+            if (!reached.has(edge.from))
+                frontier.push(edge.from);
+        }
+    }
+    const tests = [...reached].filter((file) => isTest(file, options)).sort();
+    if (tests.length === 0) {
+        return full('no test reaches the change, which is more likely a stale graph than a gap');
+    }
+    if (tests.length >= allTests.length) {
+        return full('every test is reachable from the change');
+    }
+    reasons.unshift(`${tests.length} of ${allTests.length} tests can reach the change`);
+    return { status: 'selected', tests, allTests, reasons };
+}
+/** POSIX single-quoting: the only string a shell will not reinterpret. */
+function shellQuote(value) {
+    return `'${value.replaceAll("'", String.raw `'\''`)}'`;
+}
+const FILES_PLACEHOLDER = '{files}';
+/**
+ * Reject a template with no placeholder. Called once at the CLI boundary so an
+ * unusable template fails before any git runs, and again at render time: that
+ * would run the full suite while the report said `selected`, which is the one
+ * failure mode this module must not have.
+ */
+export function assertSelectableTestCmd(template) {
+    if (!template.includes(FILES_PLACEHOLDER)) {
+        throw new TestSelectError('test-select.no-files-placeholder', `select test command has no ${FILES_PLACEHOLDER} placeholder: ${template}`, { template });
+    }
+}
+/** Substitute a selection into the operator's template. */
+export function renderSelectedTestCmd(template, tests) {
+    assertSelectableTestCmd(template);
+    if (tests.length === 0) {
+        throw new TestSelectError('test-select.empty-selection', 'refusing to render a test command for an empty selection', { template });
+    }
+    return template.replaceAll(FILES_PLACEHOLDER, tests.map(shellQuote).join(' '));
+}

package/factory/orchestrator/dist/testerAudit.js

@@ -0,0 +1,264 @@
+import { readDispatchRecords } from './dispatchAudit.js';
+import { eventTaskId } from './events.js';
+import { taskIdsMatch } from './taskId.js';
+/**
+ * The event this audit is anchored to. `testgate-result` is emitted once per
+ * gate run (gate.ts), and it is the moment the question becomes answerable:
+ * before it, a task whose tester has not been dispatched yet is merely early.
+ */
+const TEST_GATE_EVENT = 'testgate-result';
+/**
+ * How a dispatched agent's turn is recorded as over, and which payload field
+ * names the role that ended it. Falling back to the record's `actor` is not a
+ * nicety: the older half of the log names the role there and nowhere else,
+ * and reading only the payload would report those runs as testers that never
+ * reported — an `unverifiable` about evidence the log is holding.
+ */
+const TERMINAL_ROLE_EVENTS = {
+    'task-result-recorded': 'agent',
+    'error-logged': 'agent',
+    'judge-reported': 'agent_role',
+    'judge-verdict': 'agent',
+};
+function payloadString(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Whether two task scopes can answer for each other. dispatchAudit.ts's rule,
+ * for its reasons: a record with no task id answers for anything (pre-task-id
+ * history is on disk and unrewritable), and "differ" is taskIdsMatch's
+ * question, not `===`'s, because the log writes one task both qualified and
+ * bare (D-181).
+ */
+function scopesAgree(a, b) {
+    return a === null || b === null || taskIdsMatch(a, b);
+}
+/**
+ * Flatten a session's terminal events, in log order.
+ *
+ * "Terminal" is TERMINAL_ROLE_EVENTS: the events that say an agent's turn
+ * ended. A dispatch that never reaches one of these is a dispatch whose
+ * outcome the log does not hold, and this audit says so rather than assuming
+ * the tester ran to completion.
+ */
+export function readTerminalRoleRecords(events) {
+    const records = [];
+    for (const stored of events) {
+        const record = stored.record;
+        const field = TERMINAL_ROLE_EVENTS[record.event_type];
+        if (!field)
+            continue;
+        const payload = (record.payload ?? {});
+        const role = payloadString(payload, field) ?? record.actor;
+        if (!role)
+            continue;
+        records.push({
+            eventId: stored.event_id,
+            ts: record.ts ?? '',
+            taskId: eventTaskId(record),
+            role,
+            eventType: record.event_type,
+        });
+    }
+    return records;
+}
+function readGateRecords(events) {
+    const records = [];
+    for (const stored of events) {
+        const record = stored.record;
+        if (record.event_type !== TEST_GATE_EVENT)
+            continue;
+        const payload = (record.payload ?? {});
+        records.push({
+            eventId: stored.event_id,
+            ts: record.ts ?? '',
+            taskId: eventTaskId(record),
+            results: payload.results,
+        });
+    }
+    return records;
+}
+/**
+ * The latest dispatch of `role` at or before `ts`, on a task scope that
+ * agrees.
+ *
+ * "At or before" is dispatchAudit.ts's argument on this axis too: a tester
+ * dispatched after the gate ran cannot have written what the gate graded, and
+ * taking the newest dispatch in the session would let exactly that launder a
+ * violation into a pass. The task axis is the same argument on the other
+ * coordinate — evidence about one task vouches for nothing about another
+ * (D-172).
+ */
+function latestDispatchBefore(dispatches, role, ts, scope) {
+    let best = null;
+    for (const dispatch of dispatches) {
+        if (dispatch.role !== role)
+            continue;
+        if (dispatch.ts > ts)
+            continue;
+        if (!scopesAgree(dispatch.taskId, scope))
+            continue;
+        if (!best || dispatch.ts >= best.ts)
+            best = dispatch;
+    }
+    return best;
+}
+function noPairsCheck() {
+    return {
+        taskId: null,
+        worker: '*',
+        auditor: '*',
+        status: 'unverifiable',
+        gateEventId: null,
+        checksRun: 0,
+        workerEventId: null,
+        auditorEventId: null,
+        detail: 'crosscheck.yml declares no role_isolation.pairs, so this audit asserts nothing. A policy that names no roles cannot be satisfied or violated, and reporting that as a pass would advertise a check nobody configured.',
+    };
+}
+/**
+ * Assert crosscheck.yml's `role_isolation` against what the log records: for
+ * every test gate, was the auditor role dispatched in a turn of its own,
+ * before the gate, on this task, and did it report?
+ *
+ * Every gate is checked, not just the last one. A task that got it wrong once
+ * and right on the re-run did get it wrong once.
+ */
+export function checkTesterIsolation(events, pairs, options) {
+    const taskId = options.taskId ?? null;
+    // D-181: `--task` is answered across both spellings of the id, so a gate
+    // logged qualified is not dropped from a bare-spelled scope.
+    const inScope = (scope) => (r) => r.taskId !== null && taskIdsMatch(r.taskId, scope);
+    const allDispatches = readDispatchRecords(events);
+    const dispatches = taskId ? allDispatches.filter(inScope(taskId)) : allDispatches;
+    const allGates = readGateRecords(events);
+    const gates = taskId ? allGates.filter(inScope(taskId)) : allGates;
+    const terminals = readTerminalRoleRecords(events);
+    const base = {
+        sessionId: options.sessionId,
+        taskId,
+        gatesExamined: gates.length,
+        dispatchesExamined: dispatches.length,
+    };
+    if (pairs.length === 0) {
+        return { ...base, checks: [noPairsCheck()], ok: false };
+    }
+    const checks = [];
+    for (const gate of gates) {
+        for (const pair of pairs) {
+            checks.push(checkOneGate(pair, gate, dispatches, terminals));
+        }
+    }
+    // No gate at all is not a clean run. It is a session that never reached the
+    // moment this audit reads, and saying `ok` about it would answer a question
+    // the log never posed.
+    if (gates.length === 0) {
+        for (const pair of pairs) {
+            checks.push({
+                taskId,
+                worker: pair.worker,
+                auditor: pair.auditor,
+                status: 'unverifiable',
+                gateEventId: null,
+                checksRun: 0,
+                workerEventId: null,
+                auditorEventId: null,
+                detail: `No ${TEST_GATE_EVENT} event in scope, so nothing here says whether ${pair.auditor} graded ${pair.worker}'s work.`,
+            });
+        }
+    }
+    return {
+        ...base,
+        checks,
+        ok: checks.every((c) => c.status === 'ok' || c.status === 'not-applicable'),
+    };
+}
+function checkOneGate(pair, gate, dispatches, terminals) {
+    const base = {
+        taskId: gate.taskId,
+        worker: pair.worker,
+        auditor: pair.auditor,
+        gateEventId: gate.eventId,
+        workerEventId: null,
+        auditorEventId: null,
+    };
+    if (gate.taskId === null) {
+        return {
+            ...base,
+            status: 'unverifiable',
+            checksRun: 0,
+            detail: `The ${TEST_GATE_EVENT} at ${gate.ts} names no task, so no dispatch can be paired with it.`,
+        };
+    }
+    if (!Array.isArray(gate.results)) {
+        return {
+            ...base,
+            status: 'unverifiable',
+            checksRun: 0,
+            detail: `The ${TEST_GATE_EVENT} for ${gate.taskId} records no result list, so how much was graded is unknown.`,
+        };
+    }
+    const checksRun = gate.results.length;
+    if (checksRun === 0) {
+        // Nothing ran, so nothing was self-graded. This is the one status that
+        // passes without evidence, and it is safe precisely because there is no
+        // verdict here for a coder to have written in its own favour.
+        return {
+            ...base,
+            status: 'not-applicable',
+            checksRun: 0,
+            detail: `The ${TEST_GATE_EVENT} for ${gate.taskId} ran no test checks, so there was no verdict to grade.`,
+        };
+    }
+    const auditor = latestDispatchBefore(dispatches, pair.auditor, gate.ts, gate.taskId);
+    if (!auditor) {
+        return {
+            ...base,
+            status: 'violation',
+            checksRun,
+            detail: `No ${pair.auditor} was dispatched at or before the test gate for ${gate.taskId}, so the ${checksRun} test check(s) it graded were written in some other role's turn — on this pipeline, ${pair.worker}'s.`,
+        };
+    }
+    base.auditorEventId = auditor.eventId;
+    const worker = latestDispatchBefore(dispatches, pair.worker, auditor.ts, auditor.taskId);
+    if (!worker) {
+        return {
+            ...base,
+            status: 'unverifiable',
+            checksRun,
+            detail: `${pair.auditor} was dispatched for ${gate.taskId} with no preceding ${pair.worker} dispatch to have been isolated from.`,
+        };
+    }
+    base.workerEventId = worker.eventId;
+    // A shared agent id is one turn wearing two role names, which is the exact
+    // thing the pair forbids. A MISSING id is not evidence of anything: the
+    // dispatch contract does not require `agent_id`, so demanding it would make
+    // every real log unverifiable and teach the operator to ignore this audit.
+    if (auditor.agentId && worker.agentId && auditor.agentId === worker.agentId) {
+        return {
+            ...base,
+            status: 'violation',
+            checksRun,
+            detail: `The ${pair.worker} and ${pair.auditor} dispatches for ${gate.taskId} share agent id ${auditor.agentId}, so the tests were graded in the turn that wrote the code.`,
+        };
+    }
+    const reported = terminals.find((t) => t.role === pair.auditor &&
+        t.ts >= auditor.ts &&
+        t.ts <= gate.ts &&
+        scopesAgree(t.taskId, gate.taskId));
+    if (!reported) {
+        return {
+            ...base,
+            status: 'unverifiable',
+            checksRun,
+            detail: `${pair.auditor} was dispatched for ${gate.taskId} and never reported before the gate ran, so the log does not say whose work the gate graded.`,
+        };
+    }
+    return {
+        ...base,
+        status: 'ok',
+        checksRun,
+        detail: `${pair.auditor} was dispatched for ${gate.taskId} after ${pair.worker} and reported (${reported.eventType}) before the gate graded ${checksRun} test check(s).`,
+    };
+}

package/factory/orchestrator/dist/testgate.js

@@ -0,0 +1,171 @@
+import { spawn } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const TAIL_LINES = 50;
+/**
+ * How much of a check's output survives, in UTF-16 code units.
+ *
+ * `TAIL_LINES` bounds lines, and a bound on lines is not a bound on size: one
+ * `--reporter=json` run, one minified bundle, one long `set -x` trace with no
+ * newline in it is a single "line", so the line bound returns the whole thing
+ * (D-189). Two things then have no ceiling. The `tail` goes verbatim into the
+ * `testgate-result` event, and the event log is append-only — an unbounded
+ * field there is written once and kept forever. And the output is accumulated
+ * in the orchestrator's own heap while the check runs, which the per-command
+ * timeout does not bound: a check that floods fills memory long before five
+ * minutes are up, and an orchestrator that dies of it writes no gate event at
+ * all. Generous on purpose — 50 lines of real test output fit inside this with
+ * room to spare, and output that does not was never going to be read as lines.
+ */
+const TAIL_MAX_CHARS = 64 * 1024;
+const DROPPED_NOTE = '[testgate] earlier output dropped — this is the tail, not the whole run';
+const TIMEOUT_EXIT_CODE = -1;
+function tailLines(text, n) {
+    // Drop one trailing newline first so a command's final real line doesn't
+    // show up as a spurious empty "line" that pushes real content out of the tail.
+    const trimmed = text.endsWith('\n') ? text.slice(0, -1) : text;
+    const lines = trimmed.split('\n');
+    return lines.slice(Math.max(0, lines.length - n)).join('\n');
+}
+/**
+ * Name the signal a check died from, if it died from one.
+ *
+ * Two shapes reach us, because checks run through a shell (`shell: true`):
+ * the shell itself signalled gives `signal` directly, while a signalled
+ * *grandchild* is reported by the shell as exit code 128+N. Both used to land
+ * in the results as a bare number with an empty tail, which reads as "the
+ * tests failed" and sends the reader to the wrong subsystem entirely — the
+ * mistake D-47 records. A crash is not a test failure and must not look like one.
+ *
+ * The 128+N branch is an inference, not an observation: a command free to pick
+ * its own exit codes may return 137 meaning something of its own, and nothing
+ * in the exit status distinguishes that from a shell reporting SIGKILL. The
+ * shell throws that information away before we see it. So the note for that
+ * branch is worded as the reading it is, and the caller keeps the raw code.
+ */
+function signalNote(code, signal) {
+    if (signal !== null) {
+        return `[testgate] the check process was killed by ${signal} — it crashed, it did not fail`;
+    }
+    if (code !== null && code > 128 && code < 128 + 65) {
+        const number = code - 128;
+        const name = Object.entries(osConstants.signals).find(([, n]) => n === number)?.[0];
+        if (name !== undefined) {
+            return (`[testgate] exit code ${code} is the shell's convention for a command killed by ` +
+                `${name} (128+${number}) — read it as a crash, not a test failure, unless this check ` +
+                'is known to use that exit code itself');
+        }
+    }
+    return null;
+}
+/**
+ * Run one check command in its own process group (POSIX `setsid`, via
+ * `detached: true`) so a timeout can kill the WHOLE group — `process.kill`
+ * with a negative pid signals every process in that group, not just the
+ * immediate shell child. A plain per-child kill (e.g. execFileSync's
+ * built-in `timeout`) leaves grandchildren the shell spawned (background
+ * jobs, long-lived children) running as orphans after the parent shell
+ * dies — a real leak in a 24/7 factory (reproduced: manual kill -9 needed).
+ */
+function runOne(check, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        const child = spawn(check.cmd, {
+            cwd,
+            shell: true,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let output = '';
+        let dropped = false;
+        let timedOut = false;
+        /**
+         * Keep the last `TAIL_MAX_CHARS` and drop the rest as it arrives. Trimming
+         * at the end would bound the field and not the buffer, and the buffer is
+         * the half that can take the orchestrator down with it.
+         */
+        const absorb = (chunk) => {
+            output += chunk.toString('utf8');
+            if (output.length > TAIL_MAX_CHARS) {
+                output = output.slice(-TAIL_MAX_CHARS);
+                dropped = true;
+            }
+        };
+        /** The reported tail, admitting the drop when there was one. */
+        const tailOf = (text) => {
+            const kept = tailLines(text, TAIL_LINES);
+            return dropped ? `${DROPPED_NOTE}\n${kept}` : kept;
+        };
+        child.stdout?.on('data', absorb);
+        child.stderr?.on('data', absorb);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL'); // negative pid -> whole process group
+                }
+                catch {
+                    // Group already gone (command finished between the timer firing and here) — fine.
+                }
+            }
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({
+                name: check.name,
+                pass: false,
+                exitCode: 1,
+                tail: tailOf(err.message),
+            });
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                const timeoutNote = `[testgate] "${check.name}" timed out after ${timeoutMs}ms — process group killed`;
+                resolve({
+                    name: check.name,
+                    pass: false,
+                    exitCode: TIMEOUT_EXIT_CODE,
+                    tail: tailOf(output ? `${output}\n${timeoutNote}` : timeoutNote),
+                });
+                return;
+            }
+            const exitCode = code !== null ? code : signal ? -1 : 1;
+            const note = signalNote(code, signal);
+            const annotated = note === null ? output : output ? `${output}\n${note}` : note;
+            resolve({
+                name: check.name,
+                pass: exitCode === 0,
+                exitCode,
+                tail: tailOf(annotated),
+            });
+        });
+    });
+}
+/**
+ * Run configured check commands (test/typecheck/lint/coverage/…) sequentially
+ * in a worktree, one process per command, with a per-command timeout. First
+ * failure short-circuits the remaining checks unless `runAll` is set. Thin —
+ * no test-output parsing beyond the process exit code.
+ */
+export async function run(checks, opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const results = [];
+    for (const check of checks) {
+        const result = await runOne(check, opts.cwd, timeoutMs);
+        results.push(result);
+        if (!result.pass && !opts.runAll)
+            break;
+    }
+    return { results, pass: results.length > 0 ? results.every((r) => r.pass) : true };
+}
+/**
+ * Cumulative regression gate (architecture §11): the epic's single test
+ * command, standing in for "every previously merged task's tests in the
+ * epic" — the caller is responsible for pointing `epicTestCmd` at whatever
+ * aggregate command covers that (e.g. the epic's full suite), this module
+ * has no opinion on what's inside it. A thin wrapper over `run`, not a
+ * separate code path.
+ */
+export async function runCumulative(epicTestCmd, opts) {
+    return run([{ name: 'cumulative', cmd: epicTestCmd }], opts);
+}