@trofimyukdev/repo-truth 0.0.0-stage → 0.1.0

package/dist/snapshot-refreshes.js

@@ -0,0 +1,202 @@
+/**
+ * Snapshot refreshes.
+ *
+ * A snapshot test passes when the output matches what was recorded, so the
+ * cheapest way to make a failing one pass is to record again. This check
+ * reports every snapshot `base..candidate` rewrites or deletes, and says
+ * whether a commit that did it also changed a file that is neither a snapshot
+ * nor a test. A new snapshot, or one only renamed with its content unchanged,
+ * is not a finding. Inline snapshots are not this version's.
+ *
+ * Only the range's changes are read, through git with an argument vector: the
+ * diff from the merge base of the two revisions to the candidate, with renames
+ * detected, and the paths each commit of `base..candidate` changed. A snapshot
+ * the base changed before the range is not reported.
+ */
+import { execFile } from "node:child_process";
+import { SANCTION_KEY, WEAKENING_SPELLINGS } from "./weakened-tests.js";
+const NAME = "RT-16";
+/**
+ * The shapes of a snapshot path, each tested against a path relative to the
+ * repository root. The check reads this list each time it runs, so a consumer
+ * appends its own shape.
+ */
+export const SNAPSHOT_PATHS = [/(?:^|\/)__snapshots__\//, /\.snap$/, /\.ambr$/];
+function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { cwd, maxBuffer: 1024 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(stderr.trim() || error.message));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+/** Escape everything outside printable ASCII, so evidence cannot replay a control sequence. */
+function escapeText(text) {
+    let escaped = "";
+    for (const char of text) {
+        const codePoint = char.codePointAt(0) ?? 0;
+        escaped += codePoint >= 0x20 && codePoint <= 0x7e ? char : `\\u{${codePoint.toString(16).padStart(4, "0")}}`;
+    }
+    return escaped;
+}
+function quote(text) {
+    return `"${escapeText(text)}"`;
+}
+async function resolveCommit(cwd, revision) {
+    // A revision that begins with a dash would be read as an option.
+    if (typeof revision !== "string" || revision.length === 0 || revision.startsWith("-")) {
+        throw new Error(`revision ${quote(String(revision))} does not name a commit`);
+    }
+    let hash = "";
+    try {
+        hash = (await runGit(cwd, ["rev-parse", "--verify", "--quiet", `${revision}^{commit}`])).trim();
+    }
+    catch (error) {
+        throw new Error(`revision ${quote(revision)} does not name a commit: ${error.message}`);
+    }
+    if (hash.length === 0) {
+        throw new Error(`revision ${quote(revision)} does not name a commit`);
+    }
+    return hash;
+}
+function parseRaw(out) {
+    const tokens = out.split("\0");
+    const entries = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const meta = tokens[i] ?? "";
+        if (!meta.startsWith(":")) {
+            continue;
+        }
+        const fields = meta.slice(1).split(" ");
+        const status = (fields[4] ?? "").charAt(0);
+        const oldPath = tokens[i + 1] ?? "";
+        let newPath = oldPath;
+        if (status === "R" || status === "C") {
+            newPath = tokens[i + 2] ?? "";
+            i += 2;
+        }
+        else {
+            i += 1;
+        }
+        entries.push({ status, contentChanged: (fields[2] ?? "") !== (fields[3] ?? ""), oldPath, newPath });
+    }
+    return entries;
+}
+function matchesAny(patterns, path) {
+    return patterns.some((pattern) => {
+        pattern.lastIndex = 0;
+        const hit = pattern.test(path);
+        pattern.lastIndex = 0;
+        return hit;
+    });
+}
+function draftsOf(entries, isSnapshot) {
+    const drafts = [];
+    for (const entry of entries) {
+        const { status, oldPath, newPath } = entry;
+        if (status === "A" || status === "C" || !isSnapshot(oldPath)) {
+            continue;
+        }
+        if (status === "R" && !entry.contentChanged) {
+            continue;
+        }
+        if (status === "D" || !isSnapshot(newPath)) {
+            drafts.push({ category: "snapshot-deleted", path: oldPath, paths: [oldPath, newPath] });
+        }
+        else if (entry.contentChanged) {
+            drafts.push({ category: "snapshot-refreshed", path: newPath, paths: [oldPath, newPath] });
+        }
+    }
+    return drafts;
+}
+/** The commits of the range, oldest first, with what each changed. */
+async function readCommits(cwd, from, to) {
+    const ids = (await runGit(cwd, ["rev-list", "--reverse", `${from}..${to}`, "--"])).split("\n").filter(Boolean);
+    const commits = [];
+    for (const id of ids) {
+        const raw = await runGit(cwd, ["diff-tree", "--root", "-r", "-M", "-z", "--raw", "--no-commit-id", id, "--"]);
+        commits.push({ id, entries: parseRaw(raw) });
+    }
+    return commits;
+}
+async function readSanctionLines(cwd, from, to) {
+    const out = await runGit(cwd, ["log", "--format=%B%x00", `${from}..${to}`, "--"]);
+    const prefix = `${SANCTION_KEY}:`;
+    return out
+        .split(/[\n\0]/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith(prefix))
+        .map((line) => line.slice(prefix.length).trim());
+}
+function sanctionFor(id, lines, given) {
+    const reason = Object.hasOwn(given, id) ? given[id] : undefined;
+    if (typeof reason === "string" && reason.trim().length > 0) {
+        return reason.trim();
+    }
+    for (const line of lines) {
+        const rest = line.slice(id.length);
+        if (line.startsWith(id) && /^\s+\S/.test(rest)) {
+            return rest.trim();
+        }
+    }
+    return null;
+}
+/**
+ * Report the snapshots `base..candidate` rewrites or deletes. Fails while any
+ * finding is unsanctioned, and fails closed: a revision that names no commit,
+ * or any git invocation that fails, is a `fail` record naming the cause.
+ */
+export async function checkSnapshotRefreshes(options) {
+    try {
+        const { cwd, base, candidate } = options;
+        const baseCommit = await resolveCommit(cwd, base);
+        const candidateCommit = await resolveCommit(cwd, candidate);
+        let ancestor;
+        try {
+            ancestor = (await runGit(cwd, ["merge-base", baseCommit, candidateCommit])).trim();
+        }
+        catch (error) {
+            throw new Error(`no merge base of ${quote(base)} and ${quote(candidate)}: ${error.message}`);
+        }
+        const snapshotPatterns = [...SNAPSHOT_PATHS];
+        const testPatterns = [...WEAKENING_SPELLINGS.testFiles];
+        const isSnapshot = (path) => matchesAny(snapshotPatterns, path);
+        const isCode = (path) => !isSnapshot(path) && !matchesAny(testPatterns, path);
+        const raw = await runGit(cwd, ["diff", "-z", "--raw", "-M", "--no-ext-diff", ancestor, candidateCommit, "--"]);
+        const drafts = draftsOf(parseRaw(raw), isSnapshot);
+        if (drafts.length === 0) {
+            return { name: NAME, status: "pass", evidence: ["no snapshot refreshed or deleted"] };
+        }
+        const commits = await readCommits(cwd, baseCommit, candidateCommit);
+        const lines = await readSanctionLines(cwd, baseCommit, candidateCommit);
+        const given = options.sanctions ?? {};
+        let open = 0;
+        const evidence = drafts.map((draft) => {
+            const id = `${draft.category}:${draft.path}`;
+            const beside = commits
+                .filter((commit) => commit.entries.some((entry) => entry.status !== "A" &&
+                (draft.paths.includes(entry.oldPath) || draft.paths.includes(entry.newPath)) &&
+                (entry.status === "D" || entry.contentChanged)) && commit.entries.some((entry) => isCode(entry.oldPath) || isCode(entry.newPath)))
+                .map((commit) => commit.id);
+            const word = draft.category === "snapshot-deleted" ? "deleted" : "refreshed";
+            let line = `${escapeText(draft.path)}: ${word}`;
+            if (beside.length > 0) {
+                line += ` beside a code change in ${beside.join(", ")}`;
+            }
+            const reason = sanctionFor(id, lines, given);
+            if (reason === null) {
+                open += 1;
+                return `${line} - awaiting a sanction`;
+            }
+            return `${line} - sanctioned: ${escapeText(reason)}`;
+        });
+        return { name: NAME, status: open > 0 ? "fail" : "pass", evidence };
+    }
+    catch (error) {
+        return { name: NAME, status: "fail", evidence: [escapeText(error instanceof Error ? error.message : String(error))] };
+    }
+}
+//# sourceMappingURL=snapshot-refreshes.js.map

package/dist/snapshot-refreshes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-refreshes.js","sourceRoot":"","sources":["../src/snapshot-refreshes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAExE,MAAM,IAAI,GAAG,OAAO,CAAC;AAErB;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAa,CAAC,yBAAyB,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAY1F,SAAS,MAAM,CAAC,GAAW,EAAE,IAAuB;IAClD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,KAAK,EACL,IAAgB,EAChB,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EACxD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;gBAClD,OAAO;YACT,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+FAA+F;AAC/F,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,IAAI,SAAS,IAAI,IAAI,IAAI,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IAC/G,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,KAAK,CAAC,IAAY;IACzB,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC;AACjC,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,QAAgB;IACxD,iEAAiE;IACjE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,yBAAyB,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,QAAQ,CAAC,4BAA6B,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IACrG,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAYD,SAAS,QAAQ,CAAC,GAAW;IAC3B,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAY,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,OAAO,GAAG,OAAO,CAAC;QACtB,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACrC,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9B,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;aAAM,CAAC;YACN,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,QAA2B,EAAE,IAAY;IAC3D,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAC/B,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QACtB,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QACtB,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;AACL,CAAC;AASD,SAAS,QAAQ,CAAC,OAAyB,EAAE,UAAqC;IAChF,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QAC3C,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7D,SAAS;QACX,CAAC;QACD,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC;YAC5C,SAAS;QACX,CAAC;QACD,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC1F,CAAC;aAAM,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAOD,sEAAsE;AACtE,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,IAAY,EAAE,EAAU;IAC9D,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,IAAI,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/G,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9G,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,GAAW,EAAE,IAAY,EAAE,EAAU;IACpE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,IAAI,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;IAClF,MAAM,MAAM,GAAG,GAAG,YAAY,GAAG,CAAC;IAClC,OAAO,GAAG;SACP,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;SACzC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,WAAW,CAAC,EAAU,EAAE,KAAwB,EAAE,KAAuC;IAChG,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3D,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAAiC;IAC5E,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;QACzC,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClD,MAAM,eAAe,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC5D,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,SAAS,CAAC,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1G,CAAC;QAED,MAAM,gBAAgB,GAAG,CAAC,GAAG,cAAc,CAAC,CAAC;QAC7C,MAAM,YAAY,GAAG,CAAC,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;QACxD,MAAM,UAAU,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,UAAU,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QACjF,MAAM,MAAM,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAE/F,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/G,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;QAEnD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,kCAAkC,CAAC,EAAE,CAAC;QACxF,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;QACpE,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;QACxE,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;QAEtC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACpC,MAAM,EAAE,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAG,OAAO;iBACnB,MAAM,CACL,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,OAAO,CAAC,IAAI,CACjB,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,MAAM,KAAK,GAAG;gBACpB,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC5E,CAAC,KAAK,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,cAAc,CAAC,CACjD,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CACtF;iBACA,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,KAAK,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;YAC7E,IAAI,IAAI,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAChD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,IAAI,IAAI,4BAA4B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1D,CAAC;YACD,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YAC7C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,IAAI,IAAI,CAAC,CAAC;gBACV,OAAO,GAAG,IAAI,wBAAwB,CAAC;YACzC,CAAC;YACD,OAAO,GAAG,IAAI,kBAAkB,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACvD,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC;IACtE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,UAAU,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACxH,CAAC;AACH,CAAC"}

package/dist/stray-files.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stray files.
+ *
+ * A range that adds a scratch script, a debug log, an editor backup, a
+ * coverage directory, a build artefact or a copied-aside file added it because
+ * an agent was working, not because anyone decided to keep it. This check reads
+ * the paths `base..candidate` ADDS and reports two separate things:
+ *
+ * - a path whose name matches a shape in `STRAY_SHAPES` - the fix is to delete
+ *   the file;
+ * - a path the repository's own ignore rules would exclude, though it is
+ *   tracked - the fix is either to delete the file or to correct the rules,
+ *   because the tree and the rules disagree.
+ *
+ * Only ADDED paths count. A modification, or a rename of a file, is not an
+ * addition, so an ordinary rename of a legitimately-named file is never a
+ * finding. The paths come from git's diff of the two commits, never from the
+ * working tree, so a file a developer has locally is not a finding against a
+ * candidate that does not contain it.
+ */
+import type { CheckRecord } from "./index.js";
+/** Where to look, and which two revisions bound the range. */
+export interface StrayFilesOptions {
+    /** The git repository to run in. */
+    readonly cwd: string;
+    /** The revision the range starts after. */
+    readonly base: string;
+    /** The revision the range ends at. */
+    readonly candidate: string;
+}
+/** One stated stray shape. */
+export interface StrayShape {
+    /** Short stable name; it is what a finding prints. */
+    readonly name: string;
+    /** Why a path of this shape is probably not meant to be kept. */
+    readonly description: string;
+    /** Tested against the added path, relative to the repository root, with `/` separators. */
+    readonly pattern: RegExp;
+}
+/**
+ * The stray shapes. The list is read each time the check runs, so a consumer
+ * with its own conventions appends an entry (`STRAY_SHAPES.push({...})`)
+ * instead of forking the matcher. Order is only the order findings print in.
+ */
+export declare const STRAY_SHAPES: StrayShape[];
+/**
+ * Check the paths `base..candidate` adds for stray shapes and for paths the
+ * ignore rules would exclude. Fails closed: a revision that names no commit,
+ * or any git invocation that fails, is a `fail` record naming the cause -
+ * never a `pass`, and never a thrown error.
+ */
+export declare function checkStrayFiles(options: StrayFilesOptions): Promise<CheckRecord>;

package/dist/stray-files.js

@@ -0,0 +1,234 @@
+/**
+ * Stray files.
+ *
+ * A range that adds a scratch script, a debug log, an editor backup, a
+ * coverage directory, a build artefact or a copied-aside file added it because
+ * an agent was working, not because anyone decided to keep it. This check reads
+ * the paths `base..candidate` ADDS and reports two separate things:
+ *
+ * - a path whose name matches a shape in `STRAY_SHAPES` - the fix is to delete
+ *   the file;
+ * - a path the repository's own ignore rules would exclude, though it is
+ *   tracked - the fix is either to delete the file or to correct the rules,
+ *   because the tree and the rules disagree.
+ *
+ * Only ADDED paths count. A modification, or a rename of a file, is not an
+ * addition, so an ordinary rename of a legitimately-named file is never a
+ * finding. The paths come from git's diff of the two commits, never from the
+ * working tree, so a file a developer has locally is not a finding against a
+ * candidate that does not contain it.
+ */
+import { execFile } from "node:child_process";
+const NAME = "RT-05";
+/**
+ * The stray shapes. The list is read each time the check runs, so a consumer
+ * with its own conventions appends an entry (`STRAY_SHAPES.push({...})`)
+ * instead of forking the matcher. Order is only the order findings print in.
+ */
+export const STRAY_SHAPES = [
+    {
+        name: "log-file",
+        description: "a .log file is output of a run, not source",
+        pattern: /\.log$/i,
+    },
+    {
+        name: "editor-backup",
+        description: "an editor or tool backup (.bak, .orig, .swp, .swo, trailing ~)",
+        pattern: /(?:\.(?:bak|orig|swp|swo)|~)$/i,
+    },
+    {
+        name: "set-aside-copy",
+        description: "a copy set aside beside the original, such as 'index 2.ts' or 'index copy.ts'",
+        pattern: /(?:^|\/)[^/]*[^/ ] (?:\d+|copy(?: \d+)?|\(\d+\))(?:\.[^/ ]*)?$/i,
+    },
+    {
+        name: "scratch-script",
+        description: "a scratch or temporary script (scratch.*, tmp.*, debug.*)",
+        pattern: /(?:^|\/)(?:scratch|tmp|temp|debug)(?:[-_.][^/]*)?\.(?:[cm]?[jt]sx?|py|sh|rb)$/i,
+    },
+    {
+        name: "coverage-output",
+        description: "anything under coverage/ is generated by a test run",
+        pattern: /(?:^|\/)coverage\//,
+    },
+    {
+        name: "build-output",
+        description: "anything under dist/ or build/ is a build artefact",
+        pattern: /(?:^|\/)(?:dist|build)\//,
+    },
+    {
+        name: "os-metadata",
+        description: "operating-system folder metadata (.DS_Store, Thumbs.db)",
+        pattern: /(?:^|\/)(?:\.DS_Store|Thumbs\.db)$/,
+    },
+];
+function runGit(cwd, args, input, okCodes = [0]) {
+    return new Promise((resolve, reject) => {
+        const child = execFile("git", args, { cwd, maxBuffer: 1024 * 1024 * 1024, encoding: "buffer" }, (error, stdout, stderr) => {
+            if (error) {
+                const code = error.code;
+                if (typeof code === "number" && okCodes.includes(code)) {
+                    resolve(stdout);
+                    return;
+                }
+                const detail = stderr.toString("utf8").trim();
+                reject(new Error(detail.length > 0 ? detail : error.message));
+                return;
+            }
+            resolve(stdout);
+        });
+        if (input !== undefined) {
+            child.stdin?.on("error", () => undefined);
+            child.stdin?.end(input);
+        }
+    });
+}
+/** Escape everything outside printable ASCII so a name cannot replay a control sequence. */
+function escapeText(text) {
+    let escaped = "";
+    for (const char of text) {
+        const codePoint = char.codePointAt(0) ?? 0;
+        if (codePoint >= 0x20 && codePoint <= 0x7e) {
+            escaped += char;
+        }
+        else {
+            escaped += `\\u{${codePoint.toString(16).padStart(4, "0")}}`;
+        }
+    }
+    return escaped;
+}
+function quote(text) {
+    return `"${escapeText(text)}"`;
+}
+function decodePath(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return bytes.toString("latin1");
+    }
+}
+function splitNul(out) {
+    const paths = [];
+    let start = 0;
+    for (let i = 0; i < out.length; i += 1) {
+        if (out[i] === 0) {
+            if (i > start) {
+                paths.push(decodePath(out.subarray(start, i)));
+            }
+            start = i + 1;
+        }
+    }
+    return paths;
+}
+async function resolveCommit(cwd, revision) {
+    if (revision.length === 0 || revision.startsWith("-")) {
+        throw new Error(`revision ${quote(revision)} names no commit`);
+    }
+    try {
+        const out = await runGit(cwd, ["rev-parse", "--verify", "--quiet", `${revision}^{commit}`]);
+        const hash = out.toString("utf8").trim();
+        if (hash.length === 0) {
+            throw new Error("empty answer");
+        }
+        return hash;
+    }
+    catch (error) {
+        throw new Error(`revision ${quote(revision)} names no commit: ${error.message}`);
+    }
+}
+/** The paths the range adds: status A only, with renames detected so a rename is not one. */
+async function addedPaths(root, base, candidate) {
+    const label = `${base.slice(0, 12)} and ${candidate.slice(0, 12)}`;
+    let ancestor;
+    try {
+        ancestor = (await runGit(root, ["merge-base", base, candidate])).toString("utf8").trim();
+    }
+    catch (error) {
+        throw new Error(`no merge base of ${label}: ${error.message}`);
+    }
+    if (ancestor.length === 0) {
+        throw new Error(`no merge base of ${label}`);
+    }
+    try {
+        const out = await runGit(root, [
+            "-c",
+            "core.quotePath=false",
+            "diff",
+            "--no-ext-diff",
+            "--no-textconv",
+            "--no-color",
+            "-M",
+            "-l0",
+            "--diff-filter=A",
+            "--name-only",
+            "-z",
+            ancestor,
+            candidate,
+            "--",
+        ]);
+        return splitNul(out);
+    }
+    catch (error) {
+        throw new Error(`could not read the paths added by the range: ${error.message}`);
+    }
+}
+/** Which of the paths the repository's ignore rules would exclude, tracked or not. */
+async function ignoredPaths(root, paths) {
+    if (paths.length === 0) {
+        return new Set();
+    }
+    try {
+        const out = await runGit(root, ["check-ignore", "--no-index", "-z", "--stdin"], paths.map((path) => `${path}\0`).join(""), [0, 1]);
+        return new Set(splitNul(out));
+    }
+    catch (error) {
+        throw new Error(`could not read the ignore rules: ${error.message}`);
+    }
+}
+/**
+ * Check the paths `base..candidate` adds for stray shapes and for paths the
+ * ignore rules would exclude. Fails closed: a revision that names no commit,
+ * or any git invocation that fails, is a `fail` record naming the cause -
+ * never a `pass`, and never a thrown error.
+ */
+export async function checkStrayFiles(options) {
+    try {
+        const { cwd, base, candidate } = options;
+        const baseCommit = await resolveCommit(cwd, base);
+        const candidateCommit = await resolveCommit(cwd, candidate);
+        const root = (await runGit(cwd, ["rev-parse", "--show-toplevel"])).toString("utf8").replace(/\r?\n$/, "");
+        const added = (await addedPaths(root, baseCommit, candidateCommit)).sort();
+        const shapes = [...STRAY_SHAPES];
+        const evidence = [];
+        for (const path of added) {
+            for (const shape of shapes) {
+                shape.pattern.lastIndex = 0;
+                if (shape.pattern.test(path)) {
+                    evidence.push(`${quote(path)} matches stray shape ${quote(shape.name)}: ${shape.description}`);
+                }
+            }
+        }
+        const ignored = await ignoredPaths(root, added);
+        for (const path of added) {
+            if (ignored.has(path)) {
+                evidence.push(`${quote(path)} is added but the ignore rules exclude it: delete the file or correct the ignore rules`);
+            }
+        }
+        if (evidence.length > 0) {
+            return { name: NAME, status: "fail", evidence };
+        }
+        return {
+            name: NAME,
+            status: "pass",
+            evidence: [
+                `${added.length} path(s) added in ${quote(base)}..${quote(candidate)} match no stray shape and no ignore rule`,
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { name: NAME, status: "fail", evidence: [escapeText(message)] };
+    }
+}
+//# sourceMappingURL=stray-files.js.map

package/dist/stray-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stray-files.js","sourceRoot":"","sources":["../src/stray-files.ts"],"names":[],"mappings":"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"}

package/dist/symlinks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Symlinks.
+ *
+ * A symbolic link is committed as a blob holding its target, so a diff shows a
+ * link to `/etc/passwd` as one harmless line of text. This check reads every
+ * link `base..candidate` adds, retargets or turns a file into, takes the
+ * target from the candidate's own blob (never from the working tree), resolves
+ * it from the link's own directory and reports one that is [absolute], that
+ * climbs [outside] the repository, or that lands in the repository's [.git]
+ * directory. A target inside the repository is not a finding whether or not
+ * anything exists there.
+ */
+import type { CheckRecord } from "./index.js";
+/** Where to look, and which two revisions bound the range. */
+export interface SymlinksOptions {
+    /** The git repository to run in. */
+    readonly cwd: string;
+    /** The revision the range starts after. */
+    readonly base: string;
+    /** The revision the range ends at. */
+    readonly candidate: string;
+}
+/**
+ * Check every link `base..candidate` adds or changes. Fails closed: a revision
+ * that names no commit, or any git invocation that fails, is a `fail` record
+ * naming the cause - never a `pass`, and never a thrown error.
+ */
+export declare function checkSymlinks(options: SymlinksOptions): Promise<CheckRecord>;