@trofimyukdev/repo-truth 0.0.0-stage → 0.1.0

package/dist/symlinks.js

@@ -0,0 +1,193 @@
+/**
+ * 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 { execFile } from "node:child_process";
+const NAME = "RT-11";
+const SYMLINK_MODE = "120000";
+function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { cwd, maxBuffer: 1024 * 1024 * 1024, encoding: "buffer" }, (error, stdout, stderr) => {
+            if (error) {
+                const detail = stderr.toString("utf8").trim();
+                reject(new Error(detail.length > 0 ? detail : error.message));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+/** 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 decodeText(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return bytes.toString("latin1");
+    }
+}
+function splitNul(out) {
+    const fields = [];
+    let start = 0;
+    for (let i = 0; i < out.length; i += 1) {
+        if (out[i] === 0) {
+            fields.push(decodeText(out.subarray(start, i)));
+            start = i + 1;
+        }
+    }
+    return fields;
+}
+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 links the range adds, retargets or turns a file into, read from the diff of the two commits. */
+async function changedLinks(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}`);
+    }
+    let out;
+    try {
+        out = await runGit(root, [
+            "diff-tree",
+            "-r",
+            "-z",
+            "--raw",
+            "--no-renames",
+            "--no-ext-diff",
+            "--no-textconv",
+            "--no-color",
+            "--diff-filter=ACMRT",
+            "--abbrev=40",
+            ancestor,
+            candidate,
+            "--",
+        ]);
+    }
+    catch (error) {
+        throw new Error(`could not read the entries changed by the range: ${error.message}`);
+    }
+    const fields = splitNul(out);
+    const links = [];
+    // Each entry is ":oldmode newmode oldsha newsha status" then the path.
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const meta = (fields[i] ?? "").replace(/^:/, "").split(" ");
+        const path = fields[i + 1] ?? "";
+        if (meta[1] === SYMLINK_MODE && meta[3] !== undefined) {
+            links.push({ path, blob: meta[3] });
+        }
+    }
+    return links.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+async function readTarget(root, link) {
+    try {
+        return decodeText(await runGit(root, ["cat-file", "blob", link.blob]));
+    }
+    catch (error) {
+        throw new Error(`could not read the blob of link ${quote(link.path)}: ${error.message}`);
+    }
+}
+/** The rule a target breaks when the link at `path` points at it, or undefined if it stays inside. */
+function brokenRule(path, target) {
+    if (target.startsWith("/") || target.startsWith("\\\\") || /^[A-Za-z]:/.test(target)) {
+        return "absolute";
+    }
+    const stack = path.split("/").slice(0, -1);
+    for (const segment of target.split(/[\\/]/)) {
+        if (segment === "" || segment === ".") {
+            continue;
+        }
+        if (segment === "..") {
+            if (stack.length === 0) {
+                return "outside";
+            }
+            stack.pop();
+        }
+        else {
+            stack.push(segment);
+        }
+    }
+    if ((stack[0] ?? "").toLowerCase() === ".git") {
+        return ".git";
+    }
+    return undefined;
+}
+/**
+ * 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 async function checkSymlinks(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 links = await changedLinks(root, baseCommit, candidateCommit);
+        const evidence = [];
+        for (const link of links) {
+            const target = await readTarget(root, link);
+            const rule = brokenRule(link.path, target);
+            if (rule !== undefined) {
+                evidence.push(`link ${quote(link.path)} -> ${quote(target)} breaks rule [${rule}]`);
+            }
+        }
+        if (evidence.length > 0) {
+            return { name: NAME, status: "fail", evidence };
+        }
+        return {
+            name: NAME,
+            status: "pass",
+            evidence: [`${links.length} link(s) added or changed in ${quote(base)}..${quote(candidate)} stay inside the repository`],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { name: NAME, status: "fail", evidence: [escapeText(message)] };
+    }
+}
+//# sourceMappingURL=symlinks.js.map

package/dist/symlinks.js.map

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

package/dist/trailers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Task-Id trailer check.
+ *
+ * A landing says which queued task it closes in a trailer, because the
+ * trailer is the one signal a rebase or squash does not rewrite and a later
+ * reader can match exactly. The trailer block is read by git itself
+ * (`%(trailers)`), never by splitting message text on a colon, so folded
+ * values, empty values and a missing blank line before the block are all
+ * decided by git's rules.
+ *
+ * Which commit must carry one: the LANDING, which is the candidate commit.
+ * The rest of `base..candidate` is the task's intermediate work and needs
+ * none; a trailer on one of them does not count for the landing.
+ */
+import type { CheckRecord } from "./index.js";
+/** The trailer key that names the task a landing closes. */
+export declare const TASK_TRAILER_KEY = "Task-Id";
+/** The trailer key the factory writes on the merges it makes. */
+export declare const FACTORY_TRAILER_KEY = "Millwright-Task-ID";
+/** The shape of a task id: a letter, letters or digits, a hyphen, digits. */
+export declare const TASK_ID_PATTERN: RegExp;
+/** Where to look, and what range of commits to look at. */
+export interface TrailerCheckOptions {
+    /** The git repository to run in. */
+    readonly cwd: string;
+    /** The revision the range starts after (exclusive). */
+    readonly base: string;
+    /** The revision the range ends at (inclusive); the landing. */
+    readonly candidate: string;
+}
+/**
+ * Check that the landing of `base..candidate` - the candidate commit - carries
+ * a well-formed `Task-Id` trailer. Fails closed: an unknown revision or any
+ * failing git invocation is a `fail`, never a `pass` and never a throw.
+ */
+export declare function checkTrailers(options: TrailerCheckOptions): Promise<CheckRecord>;

package/dist/trailers.js

@@ -0,0 +1,110 @@
+/**
+ * Task-Id trailer check.
+ *
+ * A landing says which queued task it closes in a trailer, because the
+ * trailer is the one signal a rebase or squash does not rewrite and a later
+ * reader can match exactly. The trailer block is read by git itself
+ * (`%(trailers)`), never by splitting message text on a colon, so folded
+ * values, empty values and a missing blank line before the block are all
+ * decided by git's rules.
+ *
+ * Which commit must carry one: the LANDING, which is the candidate commit.
+ * The rest of `base..candidate` is the task's intermediate work and needs
+ * none; a trailer on one of them does not count for the landing.
+ */
+import { execFile } from "node:child_process";
+/** The trailer key that names the task a landing closes. */
+export const TASK_TRAILER_KEY = "Task-Id";
+/** The trailer key the factory writes on the merges it makes. */
+export const FACTORY_TRAILER_KEY = "Millwright-Task-ID";
+/** The shape of a task id: a letter, letters or digits, a hyphen, digits. */
+export const TASK_ID_PATTERN = /^[A-Za-z][A-Za-z0-9]*-[0-9]+$/;
+const NAME = "RT-03";
+function runGit(cwd, args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", args, { cwd, maxBuffer: 64 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+            if (error) {
+                reject(new Error(stderr.trim() || error.message));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+function fail(evidence) {
+    return { name: NAME, status: "fail", evidence };
+}
+async function resolveCommit(cwd, revision) {
+    try {
+        const out = await runGit(cwd, [
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            "--end-of-options",
+            revision + "^{commit}",
+        ]);
+        const sha = out.trim();
+        return sha.length > 0 ? sha : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The values of every `Task-Id` trailer in a commit's trailer block, as git
+ * parses and unfolds them. One entry per trailer; an empty value is "".
+ */
+async function readTaskIds(cwd, sha) {
+    const out = await runGit(cwd, [
+        "log",
+        "-1",
+        "--format=%(trailers:key=" + TASK_TRAILER_KEY + ",key=" + FACTORY_TRAILER_KEY + ",unfold,separator=%x00)",
+        sha,
+        "--",
+    ]);
+    // Each entry is `Task-Id: value` as git printed it; the key is known and
+    // colon-free, so cutting after the first colon only drops the key git matched.
+    const text = out.replace(/\n$/, "");
+    if (text.length === 0) {
+        return [];
+    }
+    return text.split("\0").map((entry) => entry.slice(entry.indexOf(":") + 1).trim());
+}
+/**
+ * Check that the landing of `base..candidate` - the candidate commit - carries
+ * a well-formed `Task-Id` trailer. Fails closed: an unknown revision or any
+ * failing git invocation is a `fail`, never a `pass` and never a throw.
+ */
+export async function checkTrailers(options) {
+    const { cwd, base, candidate } = options;
+    const range = base + ".." + candidate;
+    try {
+        const baseSha = await resolveCommit(cwd, base);
+        if (baseSha === undefined) {
+            return fail([`revision ${base} does not name a commit`]);
+        }
+        const landing = await resolveCommit(cwd, candidate);
+        if (landing === undefined) {
+            return fail([`revision ${candidate} does not name a commit`]);
+        }
+        const listed = (await runGit(cwd, ["rev-list", baseSha + ".." + landing, "--"])).trim();
+        if (listed.length === 0) {
+            return { name: NAME, status: "pass", evidence: [`range ${range} is empty`] };
+        }
+        const subject = (await runGit(cwd, ["log", "-1", "--format=%s", landing, "--"])).replace(/\n$/, "");
+        const label = `${landing.slice(0, 12)} ${subject}`;
+        const values = await readTaskIds(cwd, landing);
+        if (values.length === 0) {
+            return fail([`${label}: no ${TASK_TRAILER_KEY} trailer`]);
+        }
+        const bad = values.filter((value) => !TASK_ID_PATTERN.test(value));
+        if (bad.length > 0) {
+            return fail(bad.map((value) => `${label}: ${TASK_TRAILER_KEY} value "${value}" does not parse as a task id`));
+        }
+        return { name: NAME, status: "pass", evidence: [`${label}: closes ${values.join(", ")}`] };
+    }
+    catch (error) {
+        return fail([`could not check trailers of ${range}: ${error.message}`]);
+    }
+}
+//# sourceMappingURL=trailers.js.map

package/dist/trailers.js.map

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

package/dist/weakened-tests.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Weakened tests.
+ *
+ * The cheapest way to make a red suite green is to make it ask less: skip the
+ * failing test, focus the run on the passing ones, delete the test or the
+ * assertion that fails. Each of those leaves the build green, and each is
+ * legitimate sometimes, so this check does not judge intent. It reports every
+ * such move in `base..candidate` for a human to sanction, and fails while one
+ * is unsanctioned.
+ *
+ * Only the DIFF is read. A marker that predates the range is never reported,
+ * and a marker line the range removes and adds back unchanged is a move, not
+ * a new marker. File contents are read by blob id through git, never from the
+ * working tree, and the diff is taken from the merge base of the two
+ * revisions, as in the portable-paths check.
+ *
+ * What counts as a test file, a marker, a test or an assertion lives in one
+ * table, `WEAKENING_SPELLINGS`; a caller on another runner passes its own.
+ */
+import type { CheckRecord } from "./index.js";
+/** The kinds of move this version reports. */
+export type WeakeningCategory = "skip" | "only" | "test-file-deleted" | "test-removed" | "assertion-removed";
+/** The kinds of file a marker can apply to; `any` is every file. */
+export type MarkerScope = "test" | "config" | "any";
+/** One spelling of a marker that disables or narrows tests. */
+export interface MarkerSpelling {
+    /** `skip` for a test skipped or left todo, `only` for a focus marker. */
+    readonly category: "skip" | "only";
+    /** The kinds of file the marker counts in. */
+    readonly scope: readonly MarkerScope[];
+    /** Tested against each added or removed line, without the diff's sign. */
+    readonly pattern: RegExp;
+    /** A line `pattern` matches. */
+    readonly example: string;
+}
+/**
+ * The recognised spellings. A caller passes its own as the `spellings` option;
+ * each key it gives replaces that key of this table, so extending one list is
+ * `{ ...WEAKENING_SPELLINGS, markers: [...WEAKENING_SPELLINGS.markers, mine] }`.
+ */
+export interface WeakeningSpellings {
+    /** Paths, relative to the repository root, that are test files. */
+    readonly testFiles: readonly RegExp[];
+    /** Paths that configure a test runner. */
+    readonly configFiles: readonly RegExp[];
+    readonly markers: readonly MarkerSpelling[];
+    /**
+     * A line of a test file that declares one test. The test's name is the
+     * group named `name`, else the first group, else the whole line.
+     */
+    readonly tests: readonly RegExp[];
+    /** A line of a test file that makes an assertion. */
+    readonly assertions: readonly RegExp[];
+}
+export declare const WEAKENING_SPELLINGS: WeakeningSpellings;
+/** One move that lowers what the suite asserts. */
+export interface WeakeningFinding {
+    /** `<category>:<file>:<line>`. */
+    readonly id: string;
+    readonly category: WeakeningCategory;
+    /** The path on `side`, relative to the repository root. */
+    readonly file: string;
+    /** The line on `side`; 0 for a deleted file that had no lines. */
+    readonly line: number;
+    /** `candidate` for a line the range added, `base` for one it removed. */
+    readonly side: "base" | "candidate";
+    readonly detail: string;
+    /** The sanction's reason, or `null` while the finding is unsanctioned. */
+    readonly sanction: string | null;
+}
+export interface WeakenedTestsRecord extends CheckRecord {
+    readonly findings: readonly WeakeningFinding[];
+}
+export interface WeakenedTestsOptions {
+    /** 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;
+    /** Replaces the keys of `WEAKENING_SPELLINGS` it gives. */
+    readonly spellings?: Partial<WeakeningSpellings> | undefined;
+    /** Keys are finding ids or `<category>:<file>`; values are the reasons. */
+    readonly sanctions?: Readonly<Record<string, string>> | undefined;
+}
+/** The key that sanctions a finding in a commit message of the range. */
+export declare const SANCTION_KEY = "Sanctioned-Weakening";
+/**
+ * Report the moves of `base..candidate` that lower what the suite asserts.
+ * 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 - never a `pass`, and never a thrown error.
+ */
+export declare function checkWeakenedTests(options: WeakenedTestsOptions): Promise<WeakenedTestsRecord>;