probatio 0.0.0-stage → 0.0.1

package/dist/flags.js

@@ -0,0 +1,87 @@
+/** `--key value`, `--key=value`, `--flag`, `--no-flag`. Words before the first flag are the command. */
+export function parseArgs(argv) {
+    const command = [];
+    const flags = new Map();
+    let seenFlag = false;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--") {
+            seenFlag = true;
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            if (!seenFlag)
+                command.push(token);
+            else
+                push(flags, "_", token);
+            continue;
+        }
+        seenFlag = true;
+        const body = token.slice(2);
+        const eq = body.indexOf("=");
+        if (eq !== -1) {
+            push(flags, body.slice(0, eq), body.slice(eq + 1));
+            continue;
+        }
+        if (body.startsWith("no-") && body.length > 3) {
+            push(flags, body.slice(3), false);
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith("--"))
+            push(flags, body, true);
+        else {
+            push(flags, body, next);
+            i++;
+        }
+    }
+    const human = flags.get("human")?.some((value) => value === true) ?? false;
+    return { command, flags, human };
+}
+function push(flags, key, value) {
+    const list = flags.get(key);
+    if (list)
+        list.push(value);
+    else
+        flags.set(key, [value]);
+}
+export function text(flags, key) {
+    const values = flags.get(key);
+    if (!values || values.length === 0)
+        return undefined;
+    const last = values[values.length - 1];
+    if (typeof last === "boolean")
+        return undefined;
+    return last;
+}
+export function texts(flags, key) {
+    return (flags.get(key) ?? []).filter((value) => typeof value === "string");
+}
+export function bool(flags, key, fallback) {
+    const values = flags.get(key);
+    if (!values || values.length === 0)
+        return fallback;
+    const last = values[values.length - 1];
+    if (typeof last === "boolean")
+        return last;
+    if (last === "true")
+        return true;
+    if (last === "false")
+        return false;
+    return fallback;
+}
+export function int(flags, key) {
+    const raw = text(flags, key);
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error(`--${key} must be a non-negative integer`);
+    return value;
+}
+export function requireText(flags, key) {
+    const value = text(flags, key);
+    if (!value)
+        throw new Error(`--${key} is required`);
+    return value;
+}

package/dist/golden/check.js

@@ -0,0 +1,188 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { SCHEMA_VERSION } from "../contract.js";
+const WORDING_KEYS = ["next", "nextLead"];
+/** `Golden-Change: <row>: <why>`. The why starts after the first colon-and-space, so a row may contain colons. */
+export function goldenChanges(message) {
+    const named = new Map();
+    for (const match of message.matchAll(/^Golden-Change:\s*(.+?):\s+(.+)$/gm))
+        named.set(match[1], match[2]);
+    return named;
+}
+export function readGolden(file) {
+    return asTable(readFileSync(file, "utf8"));
+}
+export function checkGolden(input) {
+    const home = input.home ?? homedir();
+    const recorded = normalizeTable(input.recorded, input.roots);
+    const actual = normalizeTable(input.actual, input.roots);
+    const ids = [...new Set([...Object.keys(recorded.rows), ...Object.keys(actual.rows)])].sort();
+    const wording = [];
+    const contract = [];
+    const invariant = [];
+    for (const id of ids) {
+        const before = recorded.rows[id];
+        const after = actual.rows[id];
+        if (after) {
+            const violation = invariantOf(id, after, home);
+            if (violation)
+                invariant.push(violation);
+        }
+        if (JSON.stringify(wordingOf(before)) !== JSON.stringify(wordingOf(after)))
+            wording.push(id);
+        if (JSON.stringify(contractOf(before)) !== JSON.stringify(contractOf(after)))
+            contract.push(id);
+    }
+    const allowed = goldenChanges(input.message);
+    const unauthorized = contract.filter((id) => !allowed.has(id));
+    const canWrite = input.update !== null && invariant.length === 0 && unauthorized.length === 0;
+    const wordingWrite = canWrite && (input.update === "wording" || input.update === "all");
+    const contractWrite = canWrite && contract.every((id) => allowed.has(id));
+    const table = structuredClone(input.recorded);
+    if (wordingWrite || (canWrite && contractWrite && contract.length > 0)) {
+        for (const id of ids) {
+            const after = input.actual.rows[id];
+            const contractRow = contract.includes(id);
+            const wordingRow = wording.includes(id);
+            if (contractRow && contractWrite) {
+                if (!after)
+                    delete table.rows[id];
+                else
+                    table.rows[id] = after;
+            }
+            else if (wordingRow && wordingWrite && after && table.rows[id]) {
+                table.rows[id] = { ...table.rows[id], ...wordingOf(after) };
+            }
+            else if (wordingRow && wordingWrite && after && !table.rows[id] && !contractRow) {
+                table.rows[id] = wordingOf(after);
+            }
+        }
+    }
+    const write = invariant.length === 0 && unauthorized.length === 0 && input.update !== null && (wording.length > 0 || contract.length > 0);
+    const ok = invariant.length === 0 && unauthorized.length === 0 && (wording.length === 0 || input.update !== null);
+    const summary = ok
+        ? wording.length === 0 && contract.length === 0
+            ? "Golden rows match."
+            : `Re-recorded ${wording.length} wording row(s) and ${contract.length} contract row(s).`
+        : invariant.length > 0
+            ? `Invariant failed: ${invariant.join("; ")}.`
+            : unauthorized.length > 0
+                ? `Contract changed for ${unauthorized.join(", ")} without a Golden-Change trailer.`
+                : `Wording changed for ${wording.join(", ")}. Re-record with --update wording.`;
+    return {
+        write: write && ok,
+        table,
+        envelope: {
+            schemaVersion: SCHEMA_VERSION,
+            ok,
+            command: "golden.check",
+            summary,
+            next: ok ? "Review the re-recorded rows." : "The table was not written.",
+            nextCall: null,
+            wording,
+            contract,
+            invariant,
+            updated: write && ok,
+        },
+    };
+}
+export function goldenShape(text) {
+    if (!text.trim())
+        return "rows";
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return "rows";
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return "flat";
+    const rows = parsed.rows;
+    if (rows && typeof rows === "object" && !Array.isArray(rows))
+        return "rows";
+    return "flat";
+}
+export function writeGolden(file, table, shape = "rows") {
+    const rows = shape === "flat" ? table.rows : sortRows(table.rows);
+    const payload = shape === "flat" ? rows : { rows };
+    writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`);
+}
+function invariantOf(id, row, home) {
+    if (row.ok === true && (typeof row.reason !== "string" || row.reason.trim().length === 0)) {
+        return `${id} has ok without a reason`;
+    }
+    if (home && containsHome(row, home))
+        return `${id} contains a home path`;
+    return null;
+}
+function containsHome(value, home) {
+    if (typeof value === "string")
+        return value.includes(home);
+    if (Array.isArray(value))
+        return value.some((item) => containsHome(item, home));
+    if (value && typeof value === "object")
+        return Object.values(value).some((item) => containsHome(item, home));
+    return false;
+}
+function wordingOf(row) {
+    if (!row || typeof row !== "object" || Array.isArray(row))
+        return {};
+    const out = {};
+    for (const key of WORDING_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(row, key))
+            out[key] = row[key];
+    }
+    return out;
+}
+function contractOf(row) {
+    if (!row)
+        return {};
+    const out = {};
+    for (const key of Object.keys(row).sort()) {
+        if (WORDING_KEYS.includes(key))
+            continue;
+        out[key] = row[key];
+    }
+    return out;
+}
+function normalizeTable(table, roots) {
+    return { rows: normalize(table.rows, roots) };
+}
+function normalize(value, roots) {
+    if (typeof value === "string") {
+        let out = value;
+        for (const root of roots) {
+            if (root.length > 1 && out.includes(root))
+                out = out.split(root).join("{root}");
+        }
+        return out;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => normalize(item, roots));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[key] = normalize(item, roots);
+        return out;
+    }
+    return value;
+}
+export function asTable(text) {
+    if (!text.trim())
+        return { rows: {} };
+    const parsed = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return { rows: {} };
+    const record = parsed;
+    const rows = record.rows && typeof record.rows === "object" && !Array.isArray(record.rows)
+        ? record.rows
+        : record;
+    return { rows };
+}
+function sortRows(rows) {
+    const out = {};
+    for (const key of Object.keys(rows).sort())
+        out[key] = rows[key];
+    return out;
+}

package/dist/ledger/build.js

@@ -0,0 +1,327 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { scrub } from "../contract.js";
+import { filesInDiff, git, patchApplies, readHeader } from "../mutate/patch.js";
+/** Revert each fix commit's src diff. A clean apply becomes a forward patch. A conflict is reported, never fuzzy-applied. */
+export function buildLedger(options) {
+    const repo = realpathSync(path.resolve(options.repoDir));
+    const packageDir = realpathSync(path.resolve(options.packageDir));
+    const outDir = path.resolve(options.outDir);
+    const resolved = git(repo, ["rev-parse", "--verify", `${options.commit}^{commit}`]);
+    if (resolved.status !== 0)
+        return fail(outDir, options.commit, "that commit does not resolve");
+    const commit = resolved.stdout.trim();
+    const packageRel = path.relative(repo, packageDir);
+    if (packageRel.startsWith(".."))
+        return fail(outDir, commit, "package is outside the repository");
+    const srcPrefix = gitPath(packageRel, options.srcDir);
+    const testsPrefix = gitPath(packageRel, options.testsDir);
+    const collected = collect(repo, commit, srcPrefix, testsPrefix, options.maxCommits ?? null);
+    const candidates = collected.found;
+    mkdirSync(outDir, { recursive: true });
+    const ids = assignIds(candidates.map((item) => item.commit));
+    const disk = loadDisk(outDir);
+    let workDir = null;
+    try {
+        const entries = [];
+        const bodies = new Map();
+        for (const candidate of candidates) {
+            const id = ids.get(candidate.commit) ?? candidate.commit.slice(0, 7);
+            if (candidate.lines > options.maxLines) {
+                entries.push(entry(candidate, id, "skipped", [], `src diff is ${candidate.lines} lines, over the ${options.maxLines} line cap`));
+                continue;
+            }
+            const fixDiff = git(repo, ["diff", `${candidate.commit}^`, candidate.commit, "--", srcPrefix]).stdout;
+            const bugDiff = git(repo, ["diff", "-R", `${candidate.commit}^`, candidate.commit, "--", srcPrefix]).stdout;
+            if (!bugDiff.trim())
+                continue;
+            if (!workDir) {
+                const work = withWorktree(repo, commit);
+                if ("error" in work)
+                    return fail(outDir, commit, work.error);
+                workDir = work.dir;
+            }
+            const applied = git(workDir, ["apply", "--check", "--whitespace=nowarn", "-"], bugDiff);
+            if (applied.status === 0) {
+                bodies.set(id, historyPatch(candidate.commit, bugDiff));
+                entries.push({ ...entry(candidate, id, "clean", filesInDiff(fixDiff)), patch: `${id}.patch` });
+                continue;
+            }
+            const where = failedAt(applied.stderr) ?? filesInDiff(fixDiff)[0] ?? { file: srcPrefix, line: 1 };
+            const owned = disk.find((item) => item.kind !== "history" && (item.fix === candidate.commit || item.id === id));
+            if (owned && handmadeApplies(workDir, owned.raw)) {
+                entries.push({ ...entry(candidate, id, "handmade", [where]), patch: `${owned.id}.patch` });
+                continue;
+            }
+            const reason = owned ? "hand-made patch does not apply" : "patch does not apply";
+            entries.push(entry(candidate, id, "hand", [where], reason));
+        }
+        writeOut(outDir, commit, packageRel || ".", entries, bodies, disk);
+        return report(outDir, repo, packageDir, commit, entries, collected);
+    }
+    finally {
+        if (workDir)
+            removeWorktree(repo, workDir);
+    }
+}
+function collect(repo, commit, srcPrefix, testsPrefix, maxCommits) {
+    const args = ["rev-list", "--no-merges"];
+    if (maxCommits !== null)
+        args.push("-n", String(maxCommits + 1));
+    args.push(commit);
+    const list = git(repo, args);
+    if (list.status !== 0)
+        return { found: [], scanned: 0, budgetHit: false };
+    const shas = list.stdout.split("\n").filter((sha) => sha.length > 0);
+    const budgetHit = maxCommits !== null && shas.length > maxCommits;
+    const limited = budgetHit ? shas.slice(0, maxCommits) : shas;
+    const found = [];
+    for (const sha of limited) {
+        if (git(repo, ["rev-parse", "--verify", `${sha}^`]).status !== 0)
+            continue;
+        const rows = numstat(repo, sha);
+        let lines = 0;
+        let src = false;
+        let tests = false;
+        for (const row of rows) {
+            if (under(row.file, srcPrefix)) {
+                src = true;
+                if (row.add !== "-" && row.del !== "-")
+                    lines += Number(row.add) + Number(row.del);
+            }
+            if (under(row.file, testsPrefix))
+                tests = true;
+        }
+        if (!src)
+            continue;
+        const meta = git(repo, ["log", "-1", `--format=%cI%n%s%n%b`, sha]);
+        if (meta.status !== 0)
+            continue;
+        const [date, subject, ...rest] = meta.stdout.replace(/\n$/, "").split("\n");
+        const body = rest.join("\n");
+        const hasTrailer = /^Fixes-bug:/m.test(body);
+        if (!hasTrailer && !(src && tests))
+            continue;
+        if (!hasTrailer && lines === 0)
+            continue;
+        found.push({
+            commit: sha,
+            date: date ?? "",
+            subject: subject ?? "",
+            fixer: /^Made-by:[ \t]*\S+[ \t]*$/m.test(body) ? "agent" : "human",
+            lines,
+        });
+    }
+    return { found, scanned: limited.length, budgetHit };
+}
+function entry(candidate, id, status, files, reason) {
+    return {
+        id,
+        commit: candidate.commit,
+        date: candidate.date,
+        subject: candidate.subject,
+        fixer: candidate.fixer,
+        status,
+        lines: candidate.lines,
+        files,
+        ...(reason ? { reason } : {}),
+    };
+}
+function writeOut(outDir, commit, packageRel, entries, bodies, disk) {
+    const cleanIds = new Set(entries.filter((item) => item.status === "clean").map((item) => item.id));
+    for (const item of disk) {
+        if (item.kind === "history" && !cleanIds.has(item.id))
+            unlinkSync(path.join(outDir, `${item.id}.patch`));
+    }
+    for (const item of entries) {
+        const body = bodies.get(item.id);
+        if (item.status !== "clean" || !body)
+            continue;
+        const dest = path.join(outDir, `${item.id}.patch`);
+        const temp = `${dest}.${process.pid}.tmp`;
+        writeFileSync(temp, body);
+        renameSync(temp, dest);
+    }
+    const recorded = {
+        commit,
+        package: packageRel.split(path.sep).join("/"),
+        entries,
+    };
+    const dest = path.join(outDir, "ledger.json");
+    const temp = `${dest}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(scrub(recorded), null, 2)}\n`);
+    renameSync(temp, dest);
+}
+function report(outDir, repo, packageDir, commit, entries, collected) {
+    const clean = entries.filter((item) => item.status === "clean").length;
+    const handEntries = entries.filter((item) => item.status === "hand").sort(byNewest);
+    const handmade = entries.filter((item) => item.status === "handmade").length;
+    const skipped = entries.filter((item) => item.status === "skipped").length;
+    const shown = handEntries.slice(0, 10).map((item) => ({
+        id: item.id,
+        commit: item.commit,
+        file: item.files[0]?.file ?? "",
+        line: item.files[0]?.line ?? 0,
+    }));
+    const parts = [`${clean} fixes reverse cleanly`];
+    if (handEntries.length > 0)
+        parts.push(`${handEntries.length} need a hand-made mutant`);
+    if (handmade > 0)
+        parts.push(`${handmade} hand-made mutants apply`);
+    if (skipped > 0)
+        parts.push(`${skipped} are over the line cap`);
+    if (collected.budgetHit) {
+        const commits = collected.scanned === 1 ? "1 commit" : `${collected.scanned} commits`;
+        parts.push(`Stopped after ${commits}. History was not fully scanned`);
+    }
+    const summary = `${parts.join(". ")}.`;
+    let next = "No fix commit to revert.";
+    if (handEntries.length > 0) {
+        const first = shown[0];
+        next = first.file
+            ? `First fix that needs a hand-made mutant is ${first.id} at ${first.file}:${first.line}.`
+            : `First fix that needs a hand-made mutant is ${first.id}.`;
+    }
+    else if (clean + handmade > 0)
+        next = "Run the ledger mutants.";
+    const nextCall = handEntries.length === 0 && clean + handmade > 0
+        ? {
+            argv: [
+                "mutate",
+                "run",
+                "--package",
+                packageDir,
+                "--repo",
+                repo,
+                "--commit",
+                commit,
+                "--patches",
+                outDir,
+                "--out",
+                path.join(outDir, "runs"),
+            ],
+        }
+        : null;
+    return {
+        ok: true,
+        summary,
+        next,
+        nextCall,
+        commit,
+        clean,
+        hand: handEntries.length,
+        handmade,
+        skipped,
+        handNeeded: shown,
+        rest: Math.max(handEntries.length - shown.length, 0),
+        full: path.join(outDir, "ledger.json"),
+        historyBudgetHit: collected.budgetHit,
+        commitsScanned: collected.scanned,
+    };
+}
+function fail(outDir, commit, error) {
+    return {
+        ok: false,
+        summary: error,
+        next: "Fix that and run the same command again.",
+        nextCall: null,
+        commit,
+        clean: 0,
+        hand: 0,
+        handmade: 0,
+        skipped: 0,
+        handNeeded: [],
+        rest: 0,
+        full: path.join(outDir, "ledger.json"),
+        historyBudgetHit: false,
+        commitsScanned: 0,
+    };
+}
+function historyPatch(commit, bugDiff) {
+    const body = bugDiff.endsWith("\n") ? bugDiff : `${bugDiff}\n`;
+    return `# probatio-mutant direction=forward meaning=apply-to-introduce-the-bug\n# probatio-ledger source=history fix=${commit}\n${body}`;
+}
+function handmadeApplies(worktree, raw) {
+    const named = readHeader(raw).direction;
+    if (named)
+        return patchApplies(worktree, raw, named);
+    return patchApplies(worktree, raw, "forward");
+}
+function failedAt(stderr) {
+    const match = stderr.match(/patch failed: ([^:\n]+):(\d+)/);
+    if (!match)
+        return null;
+    return { file: match[1], line: Number(match[2]) };
+}
+function numstat(repo, sha) {
+    const result = git(repo, ["diff-tree", "-r", "--numstat", "--no-commit-id", sha]);
+    if (result.status !== 0)
+        return [];
+    const rows = [];
+    for (const line of result.stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        const [add, del, file] = line.split("\t");
+        if (!file)
+            continue;
+        rows.push({ add, del, file });
+    }
+    return rows;
+}
+function loadDisk(outDir) {
+    if (!existsSync(outDir))
+        return [];
+    const found = [];
+    for (const name of readdirSync(outDir)) {
+        if (!name.endsWith(".patch"))
+            continue;
+        const raw = readFileSync(path.join(outDir, name), "utf8");
+        const header = raw.split("\n").filter((line) => line.startsWith("#")).join("\n");
+        const kind = /source=hand\b/.test(header) ? "hand" : /source=history\b/.test(header) ? "history" : "user";
+        const fix = header.match(/\bfix=([0-9a-f]{7,40})\b/)?.[1] ?? null;
+        found.push({ id: path.basename(name, ".patch"), raw, kind, fix });
+    }
+    return found;
+}
+function assignIds(shas) {
+    const used = new Set();
+    const ids = new Map();
+    for (const sha of [...shas].sort()) {
+        let size = Math.min(7, sha.length);
+        let id = sha.slice(0, size);
+        while (used.has(id) && size < sha.length) {
+            size += 1;
+            id = sha.slice(0, size);
+        }
+        used.add(id);
+        ids.set(sha, id);
+    }
+    return ids;
+}
+function withWorktree(repo, commit) {
+    const dir = path.join(tmpdir(), `probatio-ledger-${randomBytes(4).toString("hex")}`);
+    rmSync(dir, { recursive: true, force: true });
+    const added = git(repo, ["worktree", "add", "--detach", "--quiet", dir, commit]);
+    if (added.status !== 0)
+        return { error: (added.stderr || "worktree add failed").trim() };
+    return { dir };
+}
+function removeWorktree(repo, dir) {
+    git(repo, ["worktree", "remove", "--force", dir]);
+    rmSync(dir, { recursive: true, force: true });
+    git(repo, ["worktree", "prune"]);
+}
+function gitPath(packageRel, dir) {
+    const joined = packageRel ? path.join(packageRel, dir) : dir;
+    return joined.split(path.sep).join("/");
+}
+function under(file, prefix) {
+    return file === prefix || file.startsWith(`${prefix}/`);
+}
+function byNewest(left, right) {
+    if (left.date !== right.date)
+        return right.date < left.date ? -1 : 1;
+    return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+}