@trofimyukdev/repo-truth 0.0.0-stage → 0.1.0

package/dist/checks/strictness.js

@@ -0,0 +1,260 @@
+/**
+ * Compiler strictness lowered.
+ *
+ * Reads every tsconfig the range adds, deletes, changes or renames, whole
+ * through git, at each end at which the path is a tsconfig, as the compiler
+ * reads one (JSON with comments and trailing commas). Reports each strict
+ * option that held its strict value at the merge base and does not at the
+ * candidate (`strictness-lowered`) and each change of `extends`
+ * (`extends-changed`). A file the range adds is compared with nothing; one it
+ * deletes is compared with a file that sets nothing. `extends` is not followed.
+ * A file that cannot be read at an end at which it is read fails the record.
+ *
+ * A finding is sanctioned by a `Sanctioned-Weakening: <id> <reason>` line in a
+ * commit message of the range or by the caller's `sanctions`. Its id is
+ * `<category>:<file>:<option>`; `<category>:<file>` sanctions every finding of
+ * that category in that file.
+ */
+import { execFile } from "node:child_process";
+import { SANCTION_KEY } from "../weakened-tests.js";
+export const name = "RT-34";
+/** The options the check judges. A consumer appends to it; it is read at every run. */
+export const STRICT_OPTIONS = [
+    { name: "strict", strict: true, fromStrict: false },
+    ...[
+        "noImplicitAny",
+        "strictNullChecks",
+        "strictFunctionTypes",
+        "strictBindCallApply",
+        "strictPropertyInitialization",
+        "strictBuiltinIteratorReturn",
+        "noImplicitThis",
+        "alwaysStrict",
+        "useUnknownInCatchVariables",
+    ].map((option) => ({ name: option, strict: true, fromStrict: true })),
+    ...[
+        "noUncheckedIndexedAccess",
+        "exactOptionalPropertyTypes",
+        "noImplicitOverride",
+        "noImplicitReturns",
+        "noFallthroughCasesInSwitch",
+        "noPropertyAccessFromIndexSignature",
+    ].map((option) => ({ name: option, strict: true, fromStrict: false })),
+    { name: "skipLibCheck", strict: false, fromStrict: false },
+];
+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));
+            else
+                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;
+}
+const quoted = (text) => `"${escapeText(text).replace(/"/g, '\\"')}"`;
+async function resolveCommit(cwd, revision) {
+    const fail = (cause) => new Error(`revision "${escapeText(String(revision))}" does not name a commit${cause}`);
+    // A revision that begins with a dash would be read as an option.
+    if (typeof revision !== "string" || revision.length === 0 || revision.startsWith("-"))
+        throw fail("");
+    let hash = "";
+    try {
+        hash = (await runGit(cwd, ["rev-parse", "--verify", "--quiet", `${revision}^{commit}`])).trim();
+    }
+    catch (error) {
+        throw fail(`: ${error.message}`);
+    }
+    if (hash.length === 0)
+        throw fail("");
+    return hash;
+}
+/** JSON with comments and trailing commas, as the compiler reads a tsconfig. */
+export function parseTsconfig(text) {
+    const out = [];
+    let lastComma = -1; // index in `out` of a comma with only blanks and comments after it
+    for (let i = text.startsWith("") ? 1 : 0; i < text.length; i++) {
+        const char = text.charAt(i);
+        const next = text.charAt(i + 1);
+        if (char === '"') {
+            let end = i + 1;
+            while (end < text.length && text.charAt(end) !== '"')
+                end += text.charAt(end) === "\\" ? 2 : 1;
+            out.push(text.slice(i, end + 1));
+            i = end;
+            lastComma = -1;
+        }
+        else if (char === "/" && next === "/") {
+            while (i < text.length && text.charAt(i) !== "\n")
+                i++;
+            out.push("\n");
+        }
+        else if (char === "/" && next === "*") {
+            const end = text.indexOf("*/", i + 2);
+            if (end < 0)
+                throw new Error("unterminated comment");
+            i = end + 1;
+            out.push(" ");
+        }
+        else if (char === " " || char === "\t" || char === "\n" || char === "\r") {
+            out.push(char);
+        }
+        else {
+            if ((char === "}" || char === "]") && lastComma >= 0)
+                out[lastComma] = " ";
+            lastComma = char === "," ? out.length : -1;
+            out.push(char);
+        }
+    }
+    return JSON.parse(out.join(""));
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const EMPTY = { options: {}, extendsText: "" };
+async function readConfig(cwd, mode, sha) {
+    if (!mode.startsWith("100"))
+        return { problem: "is not a regular file" };
+    let parsed;
+    try {
+        parsed = parseTsconfig(await runGit(cwd, ["cat-file", "blob", sha]));
+    }
+    catch (error) {
+        return { problem: `is not JSON: ${error.message}` };
+    }
+    if (!isObject(parsed))
+        return { problem: "is not a JSON object" };
+    const options = Object.hasOwn(parsed, "compilerOptions") ? parsed["compilerOptions"] : {};
+    if (!isObject(options))
+        return { problem: "has a compilerOptions that is not an object" };
+    const ext = Object.hasOwn(parsed, "extends") ? parsed["extends"] : undefined;
+    return { options, extendsText: ext === undefined ? "" : typeof ext === "string" ? ext : JSON.stringify(ext) };
+}
+/** An option's value in a file: its own boolean, else `strict` for a member, else false. */
+function valueOf(options, option) {
+    const own = Object.hasOwn(options, option.name) ? options[option.name] : undefined;
+    if (typeof own === "boolean")
+        return own;
+    const strict = Object.hasOwn(options, "strict") ? options["strict"] : undefined;
+    return option.fromStrict && typeof strict === "boolean" ? strict : false;
+}
+function isTsconfig(path) {
+    if (path === null)
+        return false;
+    const file = path.slice(path.lastIndexOf("/") + 1);
+    return file === "tsconfig.json" || file === "jsconfig.json" || (file.startsWith("tsconfig.") && file.endsWith(".json"));
+}
+async function compare(cwd, from, to) {
+    const out = await runGit(cwd, ["diff", "--raw", "-z", "--no-abbrev", "--find-renames", "--no-relative", from, to, "--"]);
+    const fields = out.split("\0");
+    const drafts = [];
+    const problems = [];
+    for (let i = 0; i < fields.length; i++) {
+        const head = fields[i] ?? "";
+        if (!head.startsWith(":"))
+            continue;
+        const [oldMode = "", newMode = "", oldSha = "", newSha = "", status = ""] = head.slice(1).split(" ");
+        const first = fields[++i] ?? "";
+        const renamed = status.startsWith("R") || status.startsWith("C");
+        const second = renamed ? (fields[++i] ?? "") : first;
+        const oldPath = status.startsWith("A") ? null : first;
+        const newPath = status.startsWith("D") ? null : second;
+        const oldHere = isTsconfig(oldPath);
+        const newHere = isTsconfig(newPath);
+        if (!oldHere && !newHere)
+            continue;
+        const file = newHere ? newPath : (oldPath ?? "");
+        const before = oldHere ? await readConfig(cwd, oldMode, oldSha) : undefined;
+        const after = newHere ? await readConfig(cwd, newMode, newSha) : undefined;
+        if (before !== undefined && "problem" in before)
+            problems.push(`${escapeText(oldPath ?? file)}: at the merge base the file ${escapeText(before.problem)}`);
+        if (after !== undefined && "problem" in after)
+            problems.push(`${escapeText(file)}: at the candidate the file ${escapeText(after.problem)}`);
+        // Only at the candidate there is nothing to compare with; an unreadable end is already reported.
+        if (before === undefined || "problem" in before || (after !== undefined && "problem" in after))
+            continue;
+        const now = after ?? EMPTY;
+        if (before.extendsText !== now.extendsText) {
+            drafts.push({ category: "extends-changed", file, option: "extends", before: before.extendsText, after: now.extendsText });
+        }
+        for (const option of STRICT_OPTIONS) {
+            const was = valueOf(before.options, option);
+            const is = valueOf(now.options, option);
+            if (was === option.strict && is !== option.strict) {
+                drafts.push({ category: "strictness-lowered", file, option: option.name, before: was, after: is });
+            }
+        }
+    }
+    return { drafts, problems };
+}
+/** The text after the sanction key on every such line of the range's commit messages. */
+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(category, file, id, lines, given) {
+    for (const key of [id, `${category}:${file}`]) {
+        const reason = Object.hasOwn(given, key) ? given[key] : undefined;
+        if (typeof reason === "string" && reason.trim().length > 0)
+            return reason.trim();
+        for (const line of lines) {
+            const rest = line.slice(key.length);
+            if (line.startsWith(key) && /^\s+\S/.test(rest))
+                return rest.trim();
+        }
+    }
+    return null;
+}
+function describeFinding(finding) {
+    const text = finding.category === "extends-changed"
+        ? `extends changed ${quoted(String(finding.before))} -> ${quoted(String(finding.after))}`
+        : `lowered ${escapeText(finding.option)}: ${String(finding.before)} -> ${String(finding.after)}`;
+    const tail = finding.sanction === null ? "" : ` - sanctioned: ${escapeText(finding.sanction)}`;
+    return `${escapeText(finding.file)}: ${text}${tail}`;
+}
+/**
+ * Report each strict option `base..candidate` lowers and each change of
+ * `extends`. Fails closed: a revision that names no commit, or a git
+ * invocation that fails, is a `fail` record naming the cause.
+ */
+export async function check(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 "${escapeText(base)}" and "${escapeText(candidate)}": ${error.message}`);
+        }
+        const { drafts, problems } = await compare(cwd, ancestor, candidateCommit);
+        const lines = drafts.length === 0 ? [] : await readSanctionLines(cwd, baseCommit, candidateCommit);
+        const findings = drafts.map((draft) => {
+            const id = `${draft.category}:${draft.file}:${draft.option}`;
+            return { id, ...draft, sanction: sanctionFor(draft.category, draft.file, id, lines, options.sanctions ?? {}) };
+        });
+        if (findings.length === 0 && problems.length === 0) {
+            return { name, status: "pass", evidence: ["no strict option lowered"], findings };
+        }
+        const open = problems.length > 0 || findings.some((finding) => finding.sanction === null);
+        return { name, status: open ? "fail" : "pass", evidence: [...problems, ...findings.map(describeFinding)], findings };
+    }
+    catch (error) {
+        return { name, status: "fail", evidence: [escapeText(error instanceof Error ? error.message : String(error))], findings: [] };
+    }
+}
+//# sourceMappingURL=strictness.js.map

package/dist/checks/strictness.js.map

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

package/dist/checks/submodules.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Submodules added or moved.
+ *
+ * A submodule is a commit id written into the tree (a gitlink, mode 160000);
+ * the diff of a range that adds one or moves it shows a single line, and no
+ * check that reads added lines or blobs reads the code that commit holds. A
+ * `url` in .gitmodules points the next update at another repository. This
+ * check reports each gitlink the range adds (`submodule-added`) or moves to
+ * another commit (`submodule-moved`), and each `url` value .gitmodules gains,
+ * in any section (`submodule-url`, of the file .gitmodules). A gitlink the
+ * range removes or leaves at its commit is no finding.
+ *
+ * The range is read through git, from the merge base of `base` and `candidate`
+ * to `candidate`, by listing the trees of the two commits: never from the
+ * working tree, never through a diff that the repository's `diff.ignoreSubmodules`
+ * or a `submodule.<name>.ignore` could quiet. No submodule is fetched,
+ * initialised or entered. The check declares no options.
+ *
+ * A finding is sanctioned by a `Sanctioned-Weakening: <id> <reason>` line in a
+ * commit message of the range or by the caller's `sanctions`. Its id is
+ * `<category>:<path>`; for a URL it is `submodule-url:.gitmodules`.
+ */
+import type { CheckRecord } from "../index.js";
+export declare const name = "RT-87";
+export type SubmoduleCategory = "submodule-added" | "submodule-moved" | "submodule-url";
+export interface SubmodulesOptions {
+    readonly cwd: string;
+    readonly base: string;
+    readonly candidate: string;
+    /** Ids mapped to reasons. */
+    readonly sanctions?: Readonly<Record<string, string>> | undefined;
+}
+export interface SubmoduleFinding {
+    readonly id: string;
+    readonly category: SubmoduleCategory;
+    readonly path: string;
+    /** The text after `<path>: <category>` on the evidence line, before any sanction. */
+    readonly detail: string;
+    /** The sanction's reason, or `null` while unsanctioned. */
+    readonly sanction: string | null;
+}
+export interface SubmodulesRecord extends CheckRecord {
+    readonly findings: readonly SubmoduleFinding[];
+}
+/**
+ * Report each gitlink `base..candidate` adds or moves and each submodule URL it
+ * gains. 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`, never a throw.
+ */
+export declare function check(options: SubmodulesOptions): Promise<SubmodulesRecord>;

package/dist/checks/submodules.js

@@ -0,0 +1,172 @@
+/**
+ * Submodules added or moved.
+ *
+ * A submodule is a commit id written into the tree (a gitlink, mode 160000);
+ * the diff of a range that adds one or moves it shows a single line, and no
+ * check that reads added lines or blobs reads the code that commit holds. A
+ * `url` in .gitmodules points the next update at another repository. This
+ * check reports each gitlink the range adds (`submodule-added`) or moves to
+ * another commit (`submodule-moved`), and each `url` value .gitmodules gains,
+ * in any section (`submodule-url`, of the file .gitmodules). A gitlink the
+ * range removes or leaves at its commit is no finding.
+ *
+ * The range is read through git, from the merge base of `base` and `candidate`
+ * to `candidate`, by listing the trees of the two commits: never from the
+ * working tree, never through a diff that the repository's `diff.ignoreSubmodules`
+ * or a `submodule.<name>.ignore` could quiet. No submodule is fetched,
+ * initialised or entered. The check declares no options.
+ *
+ * A finding is sanctioned by a `Sanctioned-Weakening: <id> <reason>` line in a
+ * commit message of the range or by the caller's `sanctions`. Its id is
+ * `<category>:<path>`; for a URL it is `submodule-url:.gitmodules`.
+ */
+import { execFile } from "node:child_process";
+import { SANCTION_KEY } from "../weakened-tests.js";
+export const name = "RT-87";
+const GITMODULES = ".gitmodules";
+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));
+            else
+                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;
+}
+async function resolveCommit(cwd, revision) {
+    const fail = (cause) => new Error(`revision "${escapeText(String(revision))}" does not name a commit${cause}`);
+    // A revision that begins with a dash would be read as an option.
+    if (typeof revision !== "string" || revision.length === 0 || revision.startsWith("-"))
+        throw fail("");
+    let hash = "";
+    try {
+        hash = (await runGit(cwd, ["rev-parse", "--verify", "--quiet", `${revision}^{commit}`])).trim();
+    }
+    catch (error) {
+        throw fail(`: ${error.message}`);
+    }
+    if (hash.length === 0)
+        throw fail("");
+    return hash;
+}
+/** Every gitlink of a commit's tree, from its path to its commit id. */
+async function readGitlinks(cwd, commit) {
+    const out = await runGit(cwd, ["ls-tree", "-r", "-z", "--full-tree", commit]);
+    const links = new Map();
+    for (const entry of out.split("\0")) {
+        const tab = entry.indexOf("\t");
+        if (tab < 0)
+            continue;
+        const [mode = "", , sha = ""] = entry.slice(0, tab).split(" ");
+        if (mode === "160000")
+            links.set(entry.slice(tab + 1), sha);
+    }
+    return links;
+}
+/** Every `url` value .gitmodules holds in a commit, in any section; none when the file is absent. */
+async function readUrls(cwd, commit) {
+    const listed = await runGit(cwd, ["ls-tree", "-z", "--full-tree", commit, "--", GITMODULES]);
+    const mode = listed.split(" ")[0] ?? "";
+    if (!mode.startsWith("100"))
+        return [];
+    const out = await runGit(cwd, ["config", "--blob", `${commit}:${GITMODULES}`, "-z", "--list"]);
+    const urls = [];
+    for (const entry of out.split("\0")) {
+        const newline = entry.indexOf("\n");
+        if (newline < 0)
+            continue;
+        const key = entry.slice(0, newline);
+        // The variable is what follows the last dot of the key; the section, whatever it is, does not matter.
+        if (key.endsWith(".url"))
+            urls.push(entry.slice(newline + 1));
+    }
+    return urls;
+}
+/** The text after the sanction key on every such line of the range's commit messages. */
+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;
+}
+function describeFinding(finding) {
+    const tail = finding.sanction === null ? "" : ` - sanctioned: ${escapeText(finding.sanction)}`;
+    return `${escapeText(finding.path)}: ${finding.category} ${finding.detail}${tail}`;
+}
+/**
+ * Report each gitlink `base..candidate` adds or moves and each submodule URL it
+ * gains. 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`, never a throw.
+ */
+export async function check(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 "${escapeText(base)}" and "${escapeText(candidate)}": ${error.message}`);
+        }
+        const [before, after, urlsBefore, urlsAfter] = await Promise.all([
+            readGitlinks(cwd, ancestor),
+            readGitlinks(cwd, candidateCommit),
+            readUrls(cwd, ancestor),
+            readUrls(cwd, candidateCommit),
+        ]);
+        const drafts = [];
+        for (const [path, sha] of [...after].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+            const old = before.get(path);
+            if (old === undefined)
+                drafts.push({ category: "submodule-added", path, detail: sha });
+            else if (old !== sha)
+                drafts.push({ category: "submodule-moved", path, detail: `${old} -> ${sha}` });
+        }
+        const known = new Set(urlsBefore);
+        for (const url of [...new Set(urlsAfter)]) {
+            if (!known.has(url))
+                drafts.push({ category: "submodule-url", path: GITMODULES, detail: escapeText(url) });
+        }
+        if (drafts.length === 0) {
+            return { name, status: "pass", evidence: ["no submodule added or moved, and no submodule URL changed"], findings: [] };
+        }
+        const lines = await readSanctionLines(cwd, ancestor, candidateCommit);
+        const findings = drafts.map((draft) => {
+            const id = `${draft.category}:${draft.path}`;
+            return { id, ...draft, sanction: sanctionFor(id, lines, options.sanctions ?? {}) };
+        });
+        const open = findings.some((finding) => finding.sanction === null);
+        return { name, status: open ? "fail" : "pass", evidence: findings.map(describeFinding), findings };
+    }
+    catch (error) {
+        return { name, status: "fail", evidence: [escapeText(error instanceof Error ? error.message : String(error))], findings: [] };
+    }
+}
+//# sourceMappingURL=submodules.js.map

package/dist/checks/submodules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submodules.js","sourceRoot":"","sources":["../../src/checks/submodules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAG9C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC;AA0B5B,MAAM,UAAU,GAAG,aAAa,CAAC;AAEjC,SAAS,MAAM,CAAC,GAAW,EAAE,IAAuB;IAClD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CAAC,KAAK,EAAE,IAAgB,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACpH,IAAI,KAAK;gBAAE,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;;gBACxD,OAAO,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,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,KAAK,UAAU,aAAa,CAAC,GAAW,EAAE,QAAgB;IACxD,MAAM,IAAI,GAAG,CAAC,KAAa,EAAS,EAAE,CAAC,IAAI,KAAK,CAAC,aAAa,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,2BAA2B,KAAK,EAAE,CAAC,CAAC;IAC9H,iEAAiE;IACjE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC;IACtG,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,CAAC,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,wEAAwE;AACxE,KAAK,UAAU,YAAY,CAAC,GAAW,EAAE,MAAc;IACrD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,GAAG,GAAG,CAAC;YAAE,SAAS;QACtB,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,AAAD,EAAG,GAAG,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/D,IAAI,IAAI,KAAK,QAAQ;YAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,qGAAqG;AACrG,KAAK,UAAU,QAAQ,CAAC,GAAW,EAAE,MAAc;IACjD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7F,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,MAAM,IAAI,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,OAAO,GAAG,CAAC;YAAE,SAAS;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACpC,sGAAsG;QACtG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yFAAyF;AACzF,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;QAAE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACjF,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;YAAE,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,eAAe,CAAC,OAAyB;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kBAAkB,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC/F,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;AACrF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,OAA0B;IACpD,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,qBAAqB,UAAU,CAAC,IAAI,CAAC,UAAU,UAAU,CAAC,SAAS,CAAC,MAAO,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACxH,CAAC;QACD,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC/D,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC;YAC3B,YAAY,CAAC,GAAG,EAAE,eAAe,CAAC;YAClC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;YACvB,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;SAC/B,CAAC,CAAC;QACH,MAAM,MAAM,GAAgD,EAAE,CAAC;QAC/D,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtF,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,GAAG,KAAK,SAAS;gBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;iBAClF,IAAI,GAAG,KAAK,GAAG;gBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,GAAG,EAAE,EAAE,CAAC,CAAC;QACvG,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7G,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,2DAA2D,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QACzH,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;QACtE,MAAM,QAAQ,GAAuB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACxD,MAAM,EAAE,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YAC7C,OAAO,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,CAAC;QACrF,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrG,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,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,QAAQ,EAAE,EAAE,EAAE,CAAC;IAChI,CAAC;AACH,CAAC"}

package/dist/checks/suppressions.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Suppression directives.
+ *
+ * A line that no longer type-checks, a rule the change breaks, a branch no test
+ * reaches: each passes once a comment tells the gate not to look. This check
+ * reads the lines `base..candidate` removes and adds in source files, pairs each
+ * directive the range removes with one it adds in the same file, and reports an
+ * added directive left without a pair (`suppression-added`) for a human to
+ * sanction. Only the diff is read, through git.
+ *
+ * Which files and directives count lives in the exported
+ * `SUPPRESSION_DIRECTIVES`, read each time the check runs: a consumer appends
+ * its own entry. A directive only counts right after a comment opener.
+ */
+import type { CheckRecord } from "../index.js";
+export declare const name = "RT-31";
+/** One directive. */
+export interface SuppressionDirective {
+    /** The directive a finding names. */
+    readonly name: string;
+    /** Tested against a changed path. */
+    readonly files: RegExp;
+    /** Tested against each line the range removes or adds in such a file. */
+    readonly pattern: RegExp;
+}
+export declare const SUPPRESSION_DIRECTIVES: SuppressionDirective[];
+/** One directive the range added without a pair; `id` is `suppression-added:<file>:<line>`, the line in the candidate. */
+export interface SuppressionFinding {
+    readonly id: string;
+    readonly category: "suppression-added";
+    readonly file: string;
+    readonly line: number;
+    readonly name: string;
+    /** The sanction's reason, or `null` while unsanctioned. */
+    readonly sanction: string | null;
+}
+export interface SuppressionsRecord extends CheckRecord {
+    readonly findings: readonly SuppressionFinding[];
+}
+/** `sanctions` keys are finding ids or `suppression-added:<file>`; values are the reasons. */
+export interface SuppressionsOptions {
+    readonly cwd: string;
+    readonly base: string;
+    readonly candidate: string;
+    readonly sanctions?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Report the suppression directives `base..candidate` adds without a pair.
+ * 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 check(options: SuppressionsOptions): Promise<SuppressionsRecord>;