@juzser/blacksmith 0.1.0 → 0.2.0

package/factory/orchestrator/dist/runner.js

@@ -0,0 +1,264 @@
+// smith-run's library half (architecture §18 rule 3: "nothing that observes
+// may dispatch"). harness.ts's planWorkerTurn() renders a WorkerInvocation
+// but never spawns it — this is the one function that actually starts a
+// harness program. Imports nothing under src/db/, src/events.ts or
+// src/projector.ts on purpose (see test/runner.test.ts's own source-level
+// check): a function that can start a process has no business also being
+// able to see or extend the event log.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { REPO_ROOT } from './paths.js';
+import { extractAndValidate, extractBalancedJson } from './providers/schema-validate.js';
+import { spawnCapped } from './spawn.js';
+export class RunnerError extends SmithError {
+}
+/**
+ * harness.yml's own two shipped CLI harnesses both set an explicit
+ * `timeout_ms`; this only covers a hand-built WorkerInvocation (or a future
+ * policy entry) that leaves it null. 30 minutes, same order of magnitude as
+ * those two examples.
+ */
+export const RUNNER_DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
+/** Strips a role template's leading `---`-delimited YAML frontmatter, keeping only the markdown body. */
+function stripFrontmatter(templateText) {
+    return templateText.replace(FRONTMATTER, '');
+}
+/** Builds the child's environment from the invocation's allowlist only — never the full parent env. */
+function buildEnv(envAllowlist, parentEnv) {
+    const env = {};
+    for (const name of envAllowlist) {
+        const value = parentEnv[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+}
+const DIAGNOSTIC_TAIL_BYTES = 400;
+/** Last few hundred bytes of stderr, collapsed to one line — same convention as cli-transport.ts's tail(). */
+function tail(text) {
+    const trimmed = text.trim();
+    const cut = trimmed.length > DIAGNOSTIC_TAIL_BYTES ? trimmed.slice(-DIAGNOSTIC_TAIL_BYTES) : trimmed;
+    return cut.replace(/\s+/g, ' ');
+}
+/** codex's own `input_tokens` already includes its `cached_input_tokens` — pass through as-is. */
+function normalizeCodexUsage(raw) {
+    const input = raw.input_tokens ?? 0;
+    const output = raw.output_tokens ?? 0;
+    const cached = raw.cached_input_tokens;
+    return {
+        input_tokens: input,
+        output_tokens: output,
+        ...(cached !== undefined ? { cached_input_tokens: cached } : {}),
+        total_tokens: input + output,
+    };
+}
+/**
+ * Parses a `codex exec --json` JSONL stream: last `agent_message` item wins,
+ * `turn.completed` carries usage, and a top-level `{"type":"error", ...}`
+ * line — distinct from a non-fatal `item.completed` item whose own
+ * `item.type` is `"error"`, which stays ignored — sets `harness_error` (last
+ * one wins, same convention as `agent_message`). The process can still exit
+ * 0 and carry both an answer and a harness_error: codex reports partial
+ * progress before a failure, and neither field should hide the other.
+ */
+function parseCodexJson(combined) {
+    let answer = '';
+    let usage = null;
+    let harness_error = null;
+    for (const line of combined.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (typeof event !== 'object' || event === null)
+            continue;
+        const record = event;
+        if (record.type === 'item.completed') {
+            const item = record.item;
+            if (item !== undefined && item.type === 'agent_message' && typeof item.text === 'string') {
+                answer = item.text;
+            }
+        }
+        else if (record.type === 'turn.completed') {
+            const rawUsage = record.usage;
+            if (rawUsage !== undefined)
+                usage = normalizeCodexUsage(rawUsage);
+        }
+        else if (record.type === 'error' && typeof record.message === 'string') {
+            harness_error = record.message;
+        }
+    }
+    return { answer, usage, harness_error };
+}
+/** Anthropic's raw `input_tokens` excludes cache tokens — fold cache-creation + cache-read into it. */
+function normalizeClaudeUsage(raw) {
+    const cached = (raw.cache_creation_input_tokens ?? 0) + (raw.cache_read_input_tokens ?? 0);
+    const input = (raw.input_tokens ?? 0) + cached;
+    const output = raw.output_tokens ?? 0;
+    return {
+        input_tokens: input,
+        output_tokens: output,
+        cached_input_tokens: cached,
+        total_tokens: input + output,
+    };
+}
+/**
+ * Parses a `claude -p --output-format json` single JSON object.
+ * `is_error: true` is `claude -p`'s own way of reporting a failed turn while
+ * still exiting 0 — `harness_error` prefers `subtype` (e.g.
+ * `error_during_execution`), falls back to `result` when that is the only
+ * string the payload carries, and otherwise names the shape generically.
+ * `answer` still comes from `result` either way, unchanged from today.
+ */
+function parseClaudeJson(combined) {
+    const value = extractBalancedJson(combined);
+    if (typeof value !== 'object' || value === null) {
+        return { answer: combined.trim(), usage: null, harness_error: null };
+    }
+    const record = value;
+    const answer = typeof record.result === 'string' ? record.result : combined.trim();
+    const rawUsage = record.usage;
+    const usage = rawUsage !== undefined ? normalizeClaudeUsage(rawUsage) : null;
+    const harness_error = record.is_error === true
+        ? typeof record.subtype === 'string' && record.subtype !== ''
+            ? record.subtype
+            : typeof record.result === 'string' && record.result !== ''
+                ? record.result
+                : 'claude reported is_error'
+        : null;
+    return {
+        answer,
+        usage,
+        harness_error,
+        ...(typeof record.session_id === 'string' ? { session_id: record.session_id } : {}),
+        ...(typeof record.total_cost_usd === 'number' ? { cost_usd: record.total_cost_usd } : {}),
+    };
+}
+/** Dispatches on the invocation's declared output mode — never sniffs the payload to guess it. */
+function parseOutput(mode, combined) {
+    if (mode === 'codex-json')
+        return parseCodexJson(combined);
+    if (mode === 'claude-json')
+        return parseClaudeJson(combined);
+    return { answer: combined.trim(), usage: null, harness_error: null };
+}
+/** Validates the answer against a schema when one is set; reports failure, never throws. */
+function validate(answer, schema) {
+    if (schema === null)
+        return { validation: null, parsed: null };
+    const result = extractAndValidate(answer, schema);
+    if (result.valid)
+        return { validation: { ok: true }, parsed: result.value };
+    const errors = 'errors' in result
+        ? result.errors.map((issue) => `${issue.path}: ${issue.message}`)
+        : [result.reason];
+    return { validation: { ok: false, errors }, parsed: null };
+}
+/**
+ * Actually spawns a rendered `WorkerInvocation` — the one thing harness.ts
+ * itself is forbidden from doing. Refuses `in-process` invocations: those are
+ * Agent-tool subagent turns, not programs smith-run knows how to start.
+ */
+export async function runInvocation(invocation, opts = {}) {
+    if (invocation.kind === 'in-process') {
+        throw new RunnerError('runner.in-process', `Invocation for role "${invocation.role}" is in-process (harness "${invocation.harness}") — ` +
+            'smith-run starts programs, not Agent-tool subagents. In-process harnesses run inside the ' +
+            'orchestrator session itself and have no separate binary for smith-run to spawn.', { harness: invocation.harness, role: invocation.role });
+    }
+    const now = opts.now ?? Date.now;
+    const start = now();
+    const prompt = opts.promptText ?? readFileSync(invocation.promptFile, 'utf8');
+    const templatePath = path.join(REPO_ROOT, invocation.template);
+    const templateBody = stripFrontmatter(readFileSync(templatePath, 'utf8'));
+    const stdin = `${templateBody}\n\n${prompt}`;
+    const env = buildEnv(invocation.envAllowlist, opts.env ?? process.env);
+    const timeout_ms = invocation.budget.timeout_ms ?? RUNNER_DEFAULT_TIMEOUT_MS;
+    let outcome;
+    try {
+        outcome = await spawnCapped({
+            command: invocation.command,
+            args: [...invocation.args],
+            cwd: invocation.cwd ?? undefined,
+            env,
+        }, stdin, { timeout_ms, max_output_bytes: invocation.budget.max_output_bytes });
+    }
+    catch (err) {
+        // spawnCapped resolves rather than rejects on a spawn failure; this catch
+        // is defensive only, kept so a future change there cannot turn into an
+        // uncaught rejection here.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            harness: invocation.harness,
+            role: invocation.role,
+            taskId: invocation.taskId,
+            exitCode: null,
+            signal: null,
+            timedOut: false,
+            sizeExceeded: false,
+            spawnError: message,
+            latency_ms: now() - start,
+            answer: '',
+            parsed: null,
+            validation: null,
+            usage: null,
+            over_budget: null,
+            stderr_tail: '',
+            harness_error: null,
+        };
+    }
+    const latency_ms = now() - start;
+    if (outcome.spawnError !== undefined) {
+        const reason = outcome.spawnError.code ?? outcome.spawnError.message;
+        return {
+            harness: invocation.harness,
+            role: invocation.role,
+            taskId: invocation.taskId,
+            exitCode: null,
+            signal: null,
+            timedOut: outcome.timedOut,
+            sizeExceeded: outcome.sizeExceeded,
+            spawnError: reason,
+            latency_ms,
+            answer: '',
+            parsed: null,
+            validation: null,
+            usage: null,
+            over_budget: null,
+            stderr_tail: tail(outcome.stderr),
+            harness_error: null,
+        };
+    }
+    const { answer, usage, harness_error } = parseOutput(invocation.output, outcome.combined);
+    const { validation, parsed } = validate(answer, invocation.schema);
+    // Unknown (null) unless the harness both sets a cap and the output mode
+    // reported usage to compare it against — never guess a verdict either way.
+    const over_budget = invocation.budget.cap_tokens === null || usage === null
+        ? null
+        : usage.total_tokens > invocation.budget.cap_tokens;
+    return {
+        harness: invocation.harness,
+        role: invocation.role,
+        taskId: invocation.taskId,
+        exitCode: outcome.exitCode,
+        signal: outcome.signal,
+        timedOut: outcome.timedOut,
+        sizeExceeded: outcome.sizeExceeded,
+        spawnError: null,
+        latency_ms,
+        answer,
+        parsed,
+        validation,
+        usage,
+        over_budget,
+        stderr_tail: tail(outcome.stderr),
+        harness_error,
+    };
+}

package/factory/orchestrator/dist/scaffold.js

@@ -16,9 +16,10 @@ import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSyn
 import path from 'node:path';
 import { SmithError } from './errors.js';
 import { runGit as git } from './git.js';
-import { PROJECTS_DIR, REPO_ROOT, ROADMAP_PATH, SCAFFOLD_DIR } from './paths.js';
+import { PROJECTS_DIR, REPO_ROOT, SCAFFOLD_DIR } from './paths.js';
 import { readRoadmapText, roadmapDeclaresId } from './roadmap.js';
 import { loadStackAnswers, requireScaffoldable } from './stack.js';
+import { ensureWritableRoadmap } from './workroot.js';
 export class ScaffoldError extends SmithError {
 }
 const PROJECT_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -355,7 +356,7 @@ export function scaffoldProject(opts) {
  * gets a placeholder milestone so the Projects/Roadmap pages have something
  * to show the moment it exists, edited further as real epics get scoped).
  */
-export function registerProjectInRoadmap(projectName, roadmapPath = ROADMAP_PATH) {
+export function registerProjectInRoadmap(projectName, roadmapPath = ensureWritableRoadmap()) {
     const text = readRoadmapText(roadmapPath);
     const id = `${projectName}-bootstrap`;
     // See registerMcpMilestone: the substring `- id: <id>` is not what

package/factory/orchestrator/dist/spawn.js

@@ -0,0 +1,84 @@
+// A capped, detached-group child process — the mechanics both cli-transport.ts
+// (an external judge, no worktree, no cwd) and runner.ts (smith-run, a
+// harness that may hold a worktree) spawn a process the same way. Extracted
+// so the two do not carry two copies of a timeout/size-cap/group-kill
+// implementation that drift the way SpawnOnce's original inline copy would
+// have, the day a second caller needed it.
+import { spawn } from 'node:child_process';
+/**
+ * One spawn: detached process group (POSIX `setsid` via `detached: true`) +
+ * group-kill on timeout or size-cap breach — mirrors testgate.ts's runOne()
+ * exactly (a spawned CLI can start its own children; a plain per-child kill
+ * would orphan them the same way testgate's own regression note describes).
+ */
+export function spawnCapped(config, stdin, budget) {
+    return new Promise((resolve) => {
+        const child = spawn(config.command, config.args, {
+            cwd: config.cwd,
+            env: config.env,
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let combined = '';
+        let stderr = '';
+        let totalBytes = 0;
+        let timedOut = false;
+        let sizeExceeded = false;
+        let settled = false;
+        let spawnError;
+        const killGroup = () => {
+            if (child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch {
+                    // Group already gone — fine.
+                }
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killGroup();
+        }, budget.timeout_ms);
+        const onChunk = (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > budget.max_output_bytes) {
+                if (!sizeExceeded) {
+                    sizeExceeded = true;
+                    killGroup();
+                }
+                return;
+            }
+            combined += chunk.toString('utf8');
+        };
+        child.stdout?.on('data', onChunk);
+        child.stderr?.on('data', (chunk) => {
+            // Still folded into `combined` for extraction — a judge that writes its
+            // verdict to stderr has always worked and must keep working. The second
+            // copy exists only so a refusal reason can be reported on its own.
+            stderr += chunk.toString('utf8');
+            onChunk(chunk);
+        });
+        child.stdin?.on('error', () => {
+            // Child exited before consuming stdin (e.g. a fixture that errors
+            // immediately) — writing to a closed pipe would otherwise raise an
+            // unhandled EPIPE; the close handler below still resolves correctly.
+        });
+        child.stdin?.write(stdin);
+        child.stdin?.end();
+        const finish = (exitCode, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ combined, stderr, exitCode, signal, spawnError, timedOut, sizeExceeded });
+        };
+        child.on('error', (err) => {
+            // The child never ran (ENOENT, EACCES, …). Distinct from a child that
+            // ran and failed: 'close' carries no code in this case.
+            spawnError = err;
+            finish(null, null);
+        });
+        child.on('close', finish);
+    });
+}

package/factory/orchestrator/dist/stack.js

@@ -25,7 +25,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { SmithError } from './errors.js';
-import { REPO_ROOT, STACK_POLICY_PATH } from './paths.js';
+import { REPO_ROOT, stackPolicyReadPath } from './paths.js';
 export class StackError extends SmithError {
 }
 /**
@@ -124,7 +124,7 @@ export function parseStackAnswers(yamlText) {
     }
     return answers;
 }
-export function loadStackAnswers(filePath = STACK_POLICY_PATH) {
+export function loadStackAnswers(filePath = stackPolicyReadPath()) {
     return parseStackAnswers(readFileSync(filePath, 'utf8'));
 }
 /** Values `factory/scaffold/` can build. Everything else is a refusal, not a substitution. */
@@ -222,6 +222,14 @@ function reportFor(field, value, source) {
                 note: `The uiux agent is told to ground its specs in ${value}; with design_system_source empty, no kit is copied into scaffolded projects.`,
             };
         }
+        // A relative `design_system_source` is relative to the *package*, not to
+        // the operator's repository -- which is what it has always meant and what
+        // scaffold.ts resolves it against too. Stated here because this diff moved
+        // the file the value is typed into (stack.yml is now read from the work
+        // root under an install) without moving the base it resolves against, so a
+        // reader could reasonably assume the two travel together. They do not:
+        // changing the base is a behaviour change for every existing clone and
+        // needs a matching sentence in stack.yml, which is a policy file.
         const resolved = path.isAbsolute(source) ? source : path.join(REPO_ROOT, source);
         return existsSync(resolved)
             ? {

package/factory/orchestrator/dist/templateFragments.js

@@ -0,0 +1,178 @@
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+import { AGENTS_DIR, REPO_ROOT } from './paths.js';
+/**
+ * Shared fragments: one paragraph, stamped into several role templates.
+ *
+ * Six judges carry the same read-only rule, six workers the same
+ * `token_usage` paragraph, three judges the same finding-field rule. Before
+ * this module each copy was hand-maintained, and the copies had drifted —
+ * the same rule in three wordings, one of them a sentence short. The fix is
+ * not a template include: an agent template is what Claude Code reads
+ * *verbatim* as a system prompt, so the text has to be *in* the file. So the
+ * fragment is the source, the template carries a stamped copy inside a fence,
+ * and a test holds every fence byte-equal to its fragment. Editing the
+ * paragraph means editing the fragment and re-running the sync — editing one
+ * copy fails the gate by name.
+ */
+export class TemplateFragmentsError extends SmithError {
+}
+/**
+ * Where the fragments live. Deliberately not a `paths.ts` export: everything
+ * anchored on `REPO_ROOT` there must ship in the npm package (packaging
+ * test), and the fragments are dev-time source — the templates carry the
+ * stamped text, and nothing the CLI runs at an operator's desk reads this
+ * directory.
+ *
+ * And deliberately not `.claude/agents/_shared/`: Claude Code's agent loader
+ * recurses into `.claude/agents/`, so a fragment there with front matter
+ * registers as an agent and one without is skipped silently — neither is a
+ * fragment. `.claude/fragments/` is a directory the loader does not watch.
+ */
+export const FRAGMENTS_DIR = path.join(REPO_ROOT, '.claude', 'fragments');
+/** A fragment name is its file's basename; the fence names it the same way. */
+export const FRAGMENT_NAME = /^[a-z][a-z0-9-]*$/;
+const BEGIN_FENCE = /^<!-- BEGIN SHARED:(\S+) -->$/;
+const END_FENCE = /^<!-- END SHARED:(\S+) -->$/;
+export function beginFence(name) {
+    return `<!-- BEGIN SHARED:${name} -->`;
+}
+export function endFence(name) {
+    return `<!-- END SHARED:${name} -->`;
+}
+/**
+ * Every `<!-- BEGIN SHARED:x -->` … `<!-- END SHARED:x -->` region in a
+ * template, in file order. Fences are whole lines, so a fence quoted inside
+ * a sentence is prose, not a region. Regions do not nest: a BEGIN inside a
+ * region and an END with no open region are both errors, as is an END that
+ * names a different fragment than the BEGIN it closes — the fence pair is the
+ * unit the sync rewrites, and a mismatched pair has no single body to rewrite.
+ */
+export function parseSharedRegions(text, file = '<template>') {
+    const lines = text.split('\n');
+    const regions = [];
+    let open = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const begin = BEGIN_FENCE.exec(line);
+        if (begin) {
+            const name = begin[1];
+            if (open) {
+                throw new TemplateFragmentsError('fragments.nested-fence', `${file}:${i + 1}: BEGIN SHARED:${name} opens inside SHARED:${open.name} (opened at line ${open.start + 1}); regions do not nest.`, { file, line: i + 1, name, open: open.name });
+            }
+            assertFragmentName(name, `${file}:${i + 1}`);
+            open = { name, start: i };
+            continue;
+        }
+        const end = END_FENCE.exec(line);
+        if (end) {
+            const name = end[1];
+            if (!open || open.name !== name) {
+                throw new TemplateFragmentsError('fragments.unbalanced-fence', open
+                    ? `${file}:${i + 1}: END SHARED:${name} closes SHARED:${open.name} (opened at line ${open.start + 1}).`
+                    : `${file}:${i + 1}: END SHARED:${name} has no open BEGIN.`, { file, line: i + 1, name, open: open?.name ?? null });
+            }
+            const between = lines.slice(open.start + 1, i);
+            regions.push({
+                name,
+                start: open.start,
+                end: i,
+                body: between.length === 0 ? '' : `${between.join('\n')}\n`,
+            });
+            open = null;
+        }
+    }
+    if (open) {
+        throw new TemplateFragmentsError('fragments.unbalanced-fence', `${file}:${open.start + 1}: BEGIN SHARED:${open.name} is never closed.`, { file, line: open.start + 1, name: open.name, open: open.name });
+    }
+    return regions;
+}
+function assertFragmentName(name, where) {
+    if (!FRAGMENT_NAME.test(name)) {
+        throw new TemplateFragmentsError('fragments.invalid-fragment-name', `${where}: ${JSON.stringify(name)} is not a fragment name (expected ${FRAGMENT_NAME}).`, { name, where });
+    }
+}
+/**
+ * The fragments in a directory, by name. Every `.md` file there is a
+ * fragment and its basename is the name — the directory holds nothing else,
+ * so a README or a draft dropped in it fails by name rather than stamping
+ * itself into a template that asks for it.
+ */
+export function listFragments(dir = FRAGMENTS_DIR) {
+    const fragments = new Map();
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .sort();
+    for (const file of files) {
+        const name = path.basename(file, '.md');
+        assertFragmentName(name, path.join(dir, file));
+        fragments.set(name, readFileSync(path.join(dir, file), 'utf8'));
+    }
+    return fragments;
+}
+/**
+ * Rewrite every fenced region so its body equals the named fragment. The
+ * fences stay; only the lines between them change. Stamping a template that
+ * is already in sync returns it byte-for-byte, which is what lets the sync
+ * script run on every template without a diff to explain.
+ */
+export function stampFragments(text, fragments, file = '<template>') {
+    const regions = parseSharedRegions(text, file);
+    const lines = text.split('\n');
+    const out = [];
+    const stamped = [];
+    let cursor = 0;
+    for (const region of regions) {
+        const fragment = fragments.get(region.name);
+        if (fragment === undefined) {
+            throw new TemplateFragmentsError('fragments.unknown-fragment', `${file}:${region.start + 1}: SHARED:${region.name} names no file under the fragments directory (have: ${[...fragments.keys()].join(', ') || 'none'}).`, { file, line: region.start + 1, name: region.name, known: [...fragments.keys()] });
+        }
+        out.push(...lines.slice(cursor, region.start + 1));
+        if (fragment !== '')
+            out.push(...fragment.replace(/\n$/, '').split('\n'));
+        out.push(lines[region.end]);
+        cursor = region.end + 1;
+        stamped.push({ name: region.name, drifted: region.body !== fragment });
+    }
+    out.push(...lines.slice(cursor));
+    return { text: out.join('\n'), regions: stamped };
+}
+/**
+ * Stamp every fragment into every role template. Reads the templates
+ * non-recursively, the same set `scripts/check.sh` validates, so a file in a
+ * subdirectory is neither a template here nor an agent there.
+ */
+export function syncTemplates(opts = {}) {
+    const agentsDir = opts.agentsDir ?? AGENTS_DIR;
+    const fragments = listFragments(opts.fragmentsDir ?? FRAGMENTS_DIR);
+    const used = new Set();
+    const report = {
+        fragments: [...fragments.keys()],
+        templates: [],
+        drifted: [],
+        unused: [],
+        written: [],
+    };
+    const files = readdirSync(agentsDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map((entry) => entry.name)
+        .sort();
+    for (const file of files) {
+        const templatePath = path.join(agentsDir, file);
+        const before = readFileSync(templatePath, 'utf8');
+        const { text, regions } = stampFragments(before, fragments, templatePath);
+        report.templates.push({ file, regions });
+        for (const region of regions) {
+            used.add(region.name);
+            if (region.drifted)
+                report.drifted.push({ file, name: region.name });
+        }
+        if (opts.write && text !== before) {
+            writeFileSync(templatePath, text, 'utf8');
+            report.written.push(file);
+        }
+    }
+    report.unused = report.fragments.filter((name) => !used.has(name));
+    return report;
+}