@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/commit.js

@@ -0,0 +1,152 @@
+import { execFileSync } from 'node:child_process';
+/** The taxonomy class raised when a task reports done with work still in the working tree. */
+export const UNCOMMITTED_WORK_CODE = 'contract.uncommitted-work';
+const PORCELAIN_STATUS_WIDTH = 3; // "XY " — two status chars plus the separator
+function git(cwd, args) {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+        .toString()
+        .trim();
+}
+function isGitWorktree(worktreeDir) {
+    try {
+        git(worktreeDir, ['rev-parse', '--is-inside-work-tree']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function headSha(worktreeDir) {
+    try {
+        return git(worktreeDir, ['rev-parse', 'HEAD']);
+    }
+    catch {
+        return null; // unborn branch — nothing has ever been committed here
+    }
+}
+function currentBranch(worktreeDir) {
+    try {
+        return git(worktreeDir, ['branch', '--show-current']) || null; // empty when detached
+    }
+    catch {
+        return null;
+    }
+}
+function resolveRef(worktreeDir, ref) {
+    try {
+        return git(worktreeDir, ['rev-parse', '--verify', `${ref}^{commit}`]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every path git currently reports as dirty, staged or untracked, `-z`-parsed
+ * so spaces and newlines in filenames survive. Renames emit destination then
+ * source; both count, since a rename left two paths uncommitted.
+ *
+ * Deliberately without `--ignored`: build output and node_modules are not work
+ * the coder forgot to commit, and a gate that blocked on `dist/` would be
+ * unusable in exactly the repos that need it most.
+ *
+ * `--untracked-files=all` for the two reasons its siblings in `claims.ts` and
+ * `immutability.ts` already pass it, and one more that only bites here (D-178):
+ * the default `normal` collapses a whole new directory into a single `src/`
+ * entry, so a certificate promising to name every dirty path named a directory
+ * instead; and the mode is *configurable*, so a repo, global, or system
+ * `status.showUntrackedFiles = no` made untracked work invisible to the read
+ * and this gate certified a worktree with uncommitted new files. Passing it
+ * explicitly makes the setting unable to weaken the check — which is the whole
+ * point of D-30. Untracked is not an edge case here: a task's first write is
+ * usually a new file.
+ */
+function dirtyPaths(worktreeDir) {
+    const output = execFileSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], {
+        cwd: worktreeDir,
+        encoding: 'utf8',
+    });
+    const fields = output.split('\0');
+    const paths = [];
+    for (let i = 0; i < fields.length; i++) {
+        const field = fields[i];
+        if (field.length <= PORCELAIN_STATUS_WIDTH)
+            continue;
+        const status = field.slice(0, 2);
+        paths.push(field.slice(PORCELAIN_STATUS_WIDTH));
+        if (status.startsWith('R') || status.startsWith('C')) {
+            const source = fields[i + 1];
+            if (source)
+                paths.push(source);
+            i++;
+        }
+    }
+    return paths;
+}
+function blocked(reason, rest) {
+    return { certified: false, reason, ...rest };
+}
+/**
+ * Certify that a task worktree holds a commit worth merging (P9-8 / D-30).
+ *
+ * The gate scores a worktree; the merge queue merges a *branch*. When a task
+ * leaves its work staged-but-uncommitted, those are two different things: every
+ * check goes green against the working tree while the merge is a no-op that
+ * still reports success. This closes that gap from the cheap end — no checkout,
+ * two git reads — by refusing to score a worktree that is dirty, and refusing
+ * one whose branch head still equals the integration base it was cut from.
+ *
+ * `baseRef` is optional: an ad-hoc `gate run` against a repo with no
+ * integration branch is not forced to invent one, and says `commitsAhead: null`
+ * rather than pretending that half ran.
+ */
+export function certifyCommit(worktreeDir, opts = {}) {
+    const baseRef = opts.baseRef ?? null;
+    const empty = { head: null, branch: null, dirty: [], baseRef, baseSha: null, commitsAhead: null };
+    if (!isGitWorktree(worktreeDir))
+        return blocked('not-a-git-worktree', empty);
+    const branch = currentBranch(worktreeDir);
+    const dirty = dirtyPaths(worktreeDir);
+    const head = headSha(worktreeDir);
+    // Dirt first: when a worktree is both dirty and unadvanced, the uncommitted
+    // work is the cause and "commit it" is the whole fix.
+    if (dirty.length > 0) {
+        return blocked('uncommitted-work', {
+            head,
+            branch,
+            dirty,
+            baseRef,
+            baseSha: null,
+            commitsAhead: null,
+        });
+    }
+    if (head === null)
+        return blocked('unborn-branch', { ...empty, branch });
+    if (baseRef === null) {
+        return {
+            certified: true,
+            reason: null,
+            head,
+            branch,
+            dirty,
+            baseRef,
+            baseSha: null,
+            commitsAhead: null,
+        };
+    }
+    const baseSha = resolveRef(worktreeDir, baseRef);
+    if (baseSha === null) {
+        return blocked('unknown-base', {
+            head,
+            branch,
+            dirty,
+            baseRef,
+            baseSha: null,
+            commitsAhead: null,
+        });
+    }
+    const commitsAhead = Number(git(worktreeDir, ['rev-list', '--count', `${baseSha}..HEAD`]));
+    if (commitsAhead === 0) {
+        return blocked('branch-not-advanced', { head, branch, dirty, baseRef, baseSha, commitsAhead });
+    }
+    return { certified: true, reason: null, head, branch, dirty, baseRef, baseSha, commitsAhead };
+}

package/factory/orchestrator/dist/coverage.js

@@ -0,0 +1,188 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { SmithError } from './errors.js';
+export class CoverageError extends SmithError {
+}
+/**
+ * Where the `json-summary` reporter writes, relative to the worktree:
+ * vitest's default `coverage.reportsDirectory` is `./coverage`, and the
+ * reporter's filename is fixed.
+ */
+export const DEFAULT_SUMMARY_PATH = 'coverage/coverage-summary.json';
+const METRIC_KEYS = ['lines', 'statements', 'functions', 'branches'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseMetric(value, where) {
+    if (!isRecord(value)) {
+        throw new CoverageError('coverage.malformed-summary', `${where} is not an object`);
+    }
+    const nums = {};
+    for (const key of ['total', 'covered', 'skipped', 'pct']) {
+        const n = value[key];
+        if (typeof n !== 'number' || !Number.isFinite(n)) {
+            throw new CoverageError('coverage.malformed-summary', `${where}.${key} is not a finite number`);
+        }
+        nums[key] = n;
+    }
+    return nums;
+}
+function parseFileCoverage(value, where) {
+    if (!isRecord(value)) {
+        throw new CoverageError('coverage.malformed-summary', `${where} is not an object`);
+    }
+    const out = {};
+    for (const key of METRIC_KEYS) {
+        // Every metric is required. Defaulting a missing one to zero would invent
+        // a number, and defaulting it to 100 would invent a pass; both are worse
+        // than refusing to read the file.
+        out[key] = parseMetric(value[key], `${where}.${key}`);
+    }
+    return out;
+}
+/**
+ * Turn one file key into a worktree-relative POSIX path. The reporter emits
+ * absolute paths; a key that resolves outside the worktree is left exactly as
+ * it came, because a `../../..` path would be a worse label than the truth.
+ */
+function relativizeKey(key, worktreeDir) {
+    if (!path.isAbsolute(key))
+        return key.split(path.sep).join('/');
+    const rel = path.relative(worktreeDir, key);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+        return key;
+    return rel.split(path.sep).join('/');
+}
+/**
+ * Parse a `coverage-summary.json` document. Strict on shape: a summary that
+ * cannot be read must raise, never come back as an empty-but-valid one — an
+ * empty summary reads as "nothing was instrumented", which is a claim, and the
+ * wrong one.
+ */
+export function parseCoverageSummary(raw, worktreeDir) {
+    if (!isRecord(raw)) {
+        throw new CoverageError('coverage.malformed-summary', 'coverage summary is not an object');
+    }
+    if (!('total' in raw)) {
+        throw new CoverageError('coverage.malformed-summary', 'coverage summary has no "total" key — it is not a json-summary report');
+    }
+    const total = parseFileCoverage(raw.total, 'total');
+    const files = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key === 'total')
+            continue;
+        files[relativizeKey(key, worktreeDir)] = parseFileCoverage(value, key);
+    }
+    return { total, files };
+}
+/**
+ * Read the summary a coverage run left behind. `null` means the file is not
+ * there; anything else that goes wrong throws, because "absent" and
+ * "unreadable" are different facts and only one of them is fixed by adding a
+ * reporter.
+ */
+export async function readCoverageSummary(worktreeDir, summaryPath = DEFAULT_SUMMARY_PATH) {
+    const abs = path.resolve(worktreeDir, summaryPath);
+    let text;
+    try {
+        text = await readFile(abs, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw new CoverageError('coverage.unreadable-summary', `could not read ${summaryPath}: ${err.message}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new CoverageError('coverage.malformed-summary', `${summaryPath} is not valid JSON: ${err.message}`);
+    }
+    return parseCoverageSummary(raw, worktreeDir);
+}
+const GLOB_CHARS = /[*?[\]{}!()]/;
+/** A claim that names one file, not a region. */
+function isLiteralClaim(claim) {
+    return !GLOB_CHARS.test(claim);
+}
+function dirOf(p) {
+    const i = p.lastIndexOf('/');
+    return i === -1 ? '' : p.slice(0, i);
+}
+/**
+ * Answer, for each file a task's criteria actually name, whether the coverage
+ * run produced a number for it. Glob claims are skipped: `src/**` names a
+ * region, and a region has no single number to report — a per-file criterion
+ * has to name a per-file path.
+ */
+export function coverageSubjects(summary, claims) {
+    const instrumentedDirs = new Set(Object.keys(summary.files).map(dirOf));
+    const seen = new Set();
+    const subjects = [];
+    for (const claim of claims) {
+        if (!isLiteralClaim(claim) || seen.has(claim))
+            continue;
+        seen.add(claim);
+        const coverage = summary.files[claim];
+        if (coverage !== undefined) {
+            subjects.push({
+                path: claim,
+                status: 'measured',
+                coverage,
+                detail: `${claim}: ${coverage.lines.pct}% lines, ${coverage.statements.pct}% statements, ${coverage.functions.pct}% functions, ${coverage.branches.pct}% branches.`,
+            });
+            continue;
+        }
+        if (instrumentedDirs.has(dirOf(claim))) {
+            subjects.push({
+                path: claim,
+                status: 'unmeasured',
+                coverage: null,
+                detail: `${claim} has no row in the coverage summary, yet other files in ${dirOf(claim) || '.'} do — the run did not measure the file the criterion names.`,
+            });
+            continue;
+        }
+        subjects.push({
+            path: claim,
+            status: 'not-instrumented',
+            coverage: null,
+            detail: `${claim} is outside the coverage include glob — nothing in ${dirOf(claim) || '.'} was instrumented.`,
+        });
+    }
+    return subjects;
+}
+/**
+ * The record a gate attaches instead of a scraped table: the per-file numbers
+ * as the reporter wrote them, plus an explicit verdict on whether they cover
+ * the files this task's criteria are about.
+ */
+export async function collectCoverageEvidence(input) {
+    const summaryPath = input.summaryPath ?? DEFAULT_SUMMARY_PATH;
+    const summary = await readCoverageSummary(input.worktreeDir, summaryPath);
+    if (summary === null) {
+        return {
+            summaryPath,
+            present: false,
+            total: null,
+            filesMeasured: 0,
+            subjects: [],
+            complete: false,
+            detail: `no ${summaryPath} after the coverage check — add "json-summary" to coverage.reporter in vitest.config.ts, because the text table hides every file at 100%.`,
+        };
+    }
+    const subjects = coverageSubjects(summary, input.claims);
+    const missing = subjects.filter((s) => s.status === 'unmeasured');
+    const filesMeasured = Object.keys(summary.files).length;
+    return {
+        summaryPath,
+        present: true,
+        total: summary.total,
+        filesMeasured,
+        subjects,
+        complete: missing.length === 0,
+        detail: missing.length === 0
+            ? `${filesMeasured} files measured; ${subjects.filter((s) => s.status === 'measured').length} of ${subjects.length} named files have a per-file number.`
+            : `no per-file number for ${missing.map((s) => s.path).join(', ')} — the criterion names a file the coverage run did not measure.`,
+    };
+}