@trofimyukdev/repo-truth 0.0.0-stage → 0.1.0

package/dist/registry.js

@@ -0,0 +1,144 @@
+/**
+ * The registry of checks `repo-truth check` runs.
+ *
+ * This array is data the command reads when it runs; the command holds no list
+ * of its own. Adding a check means adding an entry here and nothing else.
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { OPTION_KINDS } from "./config.js";
+import { checkCommitRange } from "./commit-range.js";
+import { checkMeasurementRule } from "./measurement-rule.js";
+import { checkTrailers } from "./trailers.js";
+import { checkWeakenedTests } from "./weakened-tests.js";
+import { checkStrayFiles } from "./stray-files.js";
+import { checkLockfileDrift } from "./lockfile-drift.js";
+import { checkConflictMarkers } from "./conflict-markers.js";
+import { checkPortablePaths } from "./portable-paths.js";
+import { checkSymlinks } from "./symlinks.js";
+import { checkLargeBlobs } from "./large-blobs.js";
+import { checkLoweredThresholds } from "./lowered-thresholds.js";
+import { checkSnapshotRefreshes } from "./snapshot-refreshes.js";
+import { checkDependencySources } from "./dependency-sources.js";
+import { checkReplayedFigures } from "./replayed-figures.js";
+function entry(name, check, declared = {}) {
+    const options = Object.fromEntries(Object.entries(declared));
+    return {
+        name,
+        options,
+        run: (repo, range, given) => {
+            const handed = {};
+            if (typeof given === "object" && given !== null) {
+                for (const option of Object.keys(options)) {
+                    if (Object.hasOwn(given, option))
+                        handed[option] = given[option];
+                }
+            }
+            delete handed.config;
+            if (repo.config !== undefined)
+                handed.config = repo.config;
+            return check(Object.assign(handed, { cwd: repo.cwd, base: range.base, candidate: range.candidate }));
+        },
+    };
+}
+const RESERVED_OPTIONS = ["cwd", "base", "candidate", "sanctions", "config"];
+/** What is wrong with a module's optionKinds, or undefined when it is valid. */
+function optionKindsProblem(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return "its optionKinds is not a plain object";
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return "its optionKinds is not a plain object";
+    for (const [option, kind] of Object.entries(value)) {
+        if (RESERVED_OPTIONS.includes(option))
+            return "its optionKinds declares the option " + option + ", which is not its to declare";
+        if (typeof kind !== "string" || !OPTION_KINDS.includes(kind)) {
+            return "its optionKinds gives the option " + option + " a kind that is none of " + OPTION_KINDS.join(", ");
+        }
+    }
+    return undefined;
+}
+/** The options of every entry given, by entry name, in the form parseConfig reads. */
+export function optionKindsOf(entries) {
+    return Object.fromEntries(entries.map((e) => [e.name, Object.fromEntries(Object.entries(e.options ?? {}))]));
+}
+const OWN_ENTRIES = [
+    entry("RT-01", checkCommitRange),
+    entry("RT-02", checkMeasurementRule),
+    entry("RT-03", checkTrailers),
+    entry("RT-04", checkWeakenedTests),
+    entry("RT-05", checkStrayFiles),
+    entry("RT-06", checkLockfileDrift),
+    entry("RT-09", checkConflictMarkers),
+    entry("RT-10", checkPortablePaths),
+    entry("RT-11", checkSymlinks),
+    entry("RT-12", checkLargeBlobs, { maxBytes: "integer" }),
+    entry("RT-14", checkLoweredThresholds),
+    entry("RT-16", checkSnapshotRefreshes),
+    entry("RT-18", checkDependencySources, { registries: "strings" }),
+    entry("RT-19", checkReplayedFigures, { timeoutMs: "integer" }),
+];
+function failingEntry(file, extension, cause) {
+    const name = "checks/" + file.slice(0, -extension.length);
+    const record = { name, status: "fail", evidence: [file + ": " + cause] };
+    return { name, options: {}, run: () => record };
+}
+function isModuleFile(file, extension) {
+    return (file.endsWith(extension) &&
+        !file.endsWith(".d.ts") &&
+        !file.includes(".test.") &&
+        !file.includes(".spec."));
+}
+/**
+ * The entries for the check modules directly in one directory, in the order of
+ * their file names. A module that cannot be registered becomes an entry whose
+ * record fails and names the file and the cause. A missing directory yields none.
+ */
+export async function loadCheckDirectory(directory, extension) {
+    const path = fileURLToPath(directory);
+    let dirents;
+    try {
+        dirents = await readdir(path, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const files = dirents
+        .filter((d) => d.isFile() && isModuleFile(d.name, extension))
+        .map((d) => d.name)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const entries = [];
+    const taken = new Set(OWN_ENTRIES.map((e) => e.name));
+    for (const file of files) {
+        let problem;
+        let mod = {};
+        try {
+            mod = ((await import(pathToFileURL(join(path, file)).href)) ?? {});
+            if (typeof mod.name !== "string" || mod.name === "")
+                problem = "exports no name that is a non-empty string";
+            else if (typeof mod.check !== "function")
+                problem = "exports no check that is a function";
+            else if (taken.has(mod.name))
+                problem = "its name " + mod.name + " is already registered";
+            else if ("optionKinds" in mod)
+                problem = optionKindsProblem(mod.optionKinds);
+        }
+        catch (error) {
+            problem = "could not be loaded: " + (error instanceof Error ? error.message : String(error));
+        }
+        if (problem !== undefined) {
+            const failed = failingEntry(file, extension, problem);
+            taken.add(failed.name);
+            entries.push(failed);
+            continue;
+        }
+        taken.add(mod.name);
+        entries.push(entry(mod.name, mod.check, mod.optionKinds));
+    }
+    return entries;
+}
+export const REGISTRY = [...OWN_ENTRIES];
+REGISTRY.push(...(await loadCheckDirectory(new URL("checks/", import.meta.url), import.meta.url.endsWith(".ts") ? ".ts" : ".js")));
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/replay-plan.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Replay plans.
+ *
+ * A page or a commit quotes a git command beside a figure, and RT-19 runs
+ * that command again to see whether the figure still holds. A line of
+ * documentation is text anybody can write, so this module decides which
+ * command text may run at all, and it decides by lists of what is safe,
+ * never by a list of what is dangerous:
+ *
+ * - the text is split into words the way a POSIX shell splits it, with
+ *   nothing expanded; anything a shell would read as a second command, a
+ *   redirection, a substitution, an expansion or a glob ends the decision;
+ * - the words are `git`, one of a fixed set of read-only subcommands, and
+ *   then only options on that subcommand's list, a lone `--`, or arguments
+ *   that do not begin with a minus sign, optionally piped to `wc -l`;
+ * - every revision names a commit by its id, so the answer is the same on
+ *   any clone, whatever its branches, tags and `HEAD`.
+ *
+ * The decision is pure: it starts no process, reads and writes no file and
+ * imports nothing. A command it does not plan is not replayable, which is an
+ * answer and never an error.
+ */
+/** What RT-19 runs for a replayable command. */
+export interface ReplayPlan {
+    /** The command's words after `git` and before its pipe, quotes removed. */
+    readonly args: readonly string[];
+    /** Whether the command ends with `| wc -l`. */
+    readonly countLines: boolean;
+    /** Every commit id the revisions name, each once, in order of first naming. */
+    readonly commits: readonly string[];
+}
+/**
+ * Decide whether a quoted git command may be run again, and with what.
+ * Returns null when it is not replayable; never throws.
+ */
+export declare function planReplay(command: string): ReplayPlan | null;

package/dist/replay-plan.js

@@ -0,0 +1,196 @@
+/**
+ * Replay plans.
+ *
+ * A page or a commit quotes a git command beside a figure, and RT-19 runs
+ * that command again to see whether the figure still holds. A line of
+ * documentation is text anybody can write, so this module decides which
+ * command text may run at all, and it decides by lists of what is safe,
+ * never by a list of what is dangerous:
+ *
+ * - the text is split into words the way a POSIX shell splits it, with
+ *   nothing expanded; anything a shell would read as a second command, a
+ *   redirection, a substitution, an expansion or a glob ends the decision;
+ * - the words are `git`, one of a fixed set of read-only subcommands, and
+ *   then only options on that subcommand's list, a lone `--`, or arguments
+ *   that do not begin with a minus sign, optionally piped to `wc -l`;
+ * - every revision names a commit by its id, so the answer is the same on
+ *   any clone, whatever its branches, tags and `HEAD`.
+ *
+ * The decision is pure: it starts no process, reads and writes no file and
+ * imports nothing. A command it does not plan is not replayable, which is an
+ * answer and never an error.
+ */
+/** The characters a word may hold outside quotes. */
+const BARE = /^[A-Za-z0-9.\-_/:=^@,%]$/;
+/** What a double-quoted part may not hold: a shell expands or escapes these. */
+const DOUBLE_QUOTE_UNSAFE = /[$`\\]/;
+/** A commit id, optionally with a caret and digits after it. */
+const ID = "([0-9a-fA-F]{7,40})(?:\\^[0-9]+)?";
+/** A revision: an id, or two ids joined by `..` or `...`. */
+const REVISION = new RegExp(`^${ID}(?:\\.\\.\\.?${ID})?$`);
+const REV_LIST_OPTIONS = new Set(["--count", "--merges", "--no-merges", "--first-parent", "--reverse"]);
+const LOG_OPTIONS = new Set(["--oneline", "--merges", "--no-merges", "--first-parent", "--reverse"]);
+const GREP_OPTIONS = new Set(["-c", "-l", "-n", "-E", "-F", "-i", "-w", "-e", "--count", "--files-with-matches"]);
+const LS_TREE_OPTIONS = new Set(["-r", "-d", "-t", "--name-only", "--full-tree"]);
+function isLogOption(option) {
+    if (LOG_OPTIONS.has(option) || /^-[0-9]+$/.test(option) || option.startsWith("--date=")) {
+        return true;
+    }
+    // `%G` verifies a signature, and verifying one starts a program.
+    return (option.startsWith("--format=") || option.startsWith("--pretty=")) && !option.includes("%G");
+}
+/** Each subcommand that may be replayed, and the options it is planned with. */
+const SUBCOMMANDS = new Map([
+    ["rev-list", (option) => REV_LIST_OPTIONS.has(option)],
+    ["log", isLogOption],
+    ["grep", (option) => GREP_OPTIONS.has(option)],
+    ["ls-tree", (option) => LS_TREE_OPTIONS.has(option)],
+]);
+/**
+ * Split a command into words and pipes as a POSIX shell would, expanding
+ * nothing. Returns null for anything a shell would read as more than words
+ * and pipes, and for a quote that is not closed.
+ */
+function tokenize(command) {
+    const tokens = [];
+    let word = null;
+    const endWord = () => {
+        if (word !== null) {
+            tokens.push({ kind: "word", text: word });
+            word = null;
+        }
+    };
+    let i = 0;
+    while (i < command.length) {
+        const c = command[i];
+        if (c === " " || c === "\t") {
+            endWord();
+            i += 1;
+        }
+        else if (c === "|") {
+            endWord();
+            tokens.push({ kind: "pipe" });
+            i += 1;
+        }
+        else if (c === "'" || c === '"') {
+            const close = command.indexOf(c, i + 1);
+            if (close < 0) {
+                return null;
+            }
+            const part = command.slice(i + 1, close);
+            if (c === '"' && DOUBLE_QUOTE_UNSAFE.test(part)) {
+                return null;
+            }
+            word = (word ?? "") + part;
+            i = close + 1;
+        }
+        else if (BARE.test(c)) {
+            word = (word ?? "") + c;
+            i += 1;
+        }
+        else {
+            return null;
+        }
+    }
+    endWord();
+    return tokens;
+}
+function isWord(token, text) {
+    return token !== undefined && token.kind === "word" && token.text === text;
+}
+/**
+ * Decide whether a quoted git command may be run again, and with what.
+ * Returns null when it is not replayable; never throws.
+ */
+export function planReplay(command) {
+    if (typeof command !== "string" || command.includes("\0")) {
+        return null;
+    }
+    const tokens = tokenize(command);
+    if (tokens === null) {
+        return null;
+    }
+    let body = tokens;
+    let countLines = false;
+    const pipes = tokens.filter((token) => token.kind === "pipe").length;
+    if (pipes > 1) {
+        return null;
+    }
+    if (pipes === 1) {
+        const n = tokens.length;
+        if (tokens[n - 3]?.kind !== "pipe" || !isWord(tokens[n - 2], "wc") || !isWord(tokens[n - 1], "-l")) {
+            return null;
+        }
+        body = tokens.slice(0, n - 3);
+        countLines = true;
+    }
+    const words = body.map((token) => (token.kind === "word" ? token.text : "|"));
+    if (words[0] !== "git" || words.length < 2) {
+        return null;
+    }
+    const subcommand = words[1];
+    const isOption = SUBCOMMANDS.get(subcommand);
+    if (isOption === undefined) {
+        return null;
+    }
+    // Arguments before the first lone `--`, and every word after it, in order.
+    const before = [];
+    const after = [];
+    let dashDash = false;
+    let patternGiven = false;
+    const rest = words.slice(2);
+    for (let k = 0; k < rest.length; k += 1) {
+        const word = rest[k];
+        if (word === "--" && !dashDash) {
+            dashDash = true;
+            continue;
+        }
+        if (word.startsWith("-") && word !== "--" && !isOption(word)) {
+            return null;
+        }
+        if (dashDash) {
+            after.push(word);
+            continue;
+        }
+        if (word.startsWith("-")) {
+            if (subcommand === "grep" && word === "-e") {
+                const pattern = rest[k + 1];
+                if (pattern === undefined || (pattern.startsWith("-") && pattern !== "--" && !isOption(pattern))) {
+                    return null;
+                }
+                patternGiven = true;
+                k += 1;
+            }
+            continue;
+        }
+        before.push(word);
+    }
+    let revisions;
+    if (subcommand === "ls-tree") {
+        const first = before[0] ?? after[0];
+        revisions = first === undefined ? [] : [first];
+    }
+    else if (subcommand === "grep" && !patternGiven) {
+        revisions = before.slice(1);
+    }
+    else {
+        revisions = before;
+    }
+    if (revisions.length === 0) {
+        return null;
+    }
+    const commits = [];
+    for (const revision of revisions) {
+        const match = REVISION.exec(revision);
+        if (match === null) {
+            return null;
+        }
+        for (const id of [match[1], match[2]]) {
+            if (id !== undefined && !commits.includes(id)) {
+                commits.push(id);
+            }
+        }
+    }
+    return { args: words.slice(1), countLines, commits };
+}
+//# sourceMappingURL=replay-plan.js.map

package/dist/replay-plan.js.map

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

package/dist/replayed-figures.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Replayed figures.
+ *
+ * RT-02 asks that a figure carry the command that printed it; this runs that
+ * command again and compares. The claims a range adds are read by
+ * `readFigureClaims` (RT-21), and whether a claim's command may run at all is
+ * decided by `planReplay` (RT-20); this module holds neither a reader nor a
+ * word splitter of its own. A planned command runs as `git --no-pager` and the
+ * plan's words, as an argument vector with no shell, bounded in time, and only
+ * once every commit the plan names is held by the repository.
+ *
+ * A command `planReplay` does not plan is counted as not replayable and never
+ * failed. A different output, a commit the repository does not hold, a
+ * non-zero exit and a replay that runs out of time are findings.
+ *
+ * The check fails closed: a failure the claim reader answers, an invalid
+ * `timeoutMs` or a git invocation other than a replay that fails is a `fail`
+ * record naming the cause, never a pass and never a thrown error.
+ */
+import type { CheckRecord } from "./index.js";
+/** How long one replay may run, in milliseconds, when the caller sets no bound. */
+export declare const DEFAULT_REPLAY_TIMEOUT_MS = 10000;
+/** The most characters of an output a finding shows. */
+export declare const SHOWN_OUTPUT_LENGTH = 120;
+export interface ReplayedFiguresOptions {
+    /** 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;
+    /** How long one replay may run, in milliseconds. */
+    readonly timeoutMs?: number;
+}
+/** Replay every figure claim the range adds and compare each with what it says. */
+export declare function checkReplayedFigures(options: ReplayedFiguresOptions): Promise<CheckRecord>;

package/dist/replayed-figures.js

@@ -0,0 +1,159 @@
+/**
+ * Replayed figures.
+ *
+ * RT-02 asks that a figure carry the command that printed it; this runs that
+ * command again and compares. The claims a range adds are read by
+ * `readFigureClaims` (RT-21), and whether a claim's command may run at all is
+ * decided by `planReplay` (RT-20); this module holds neither a reader nor a
+ * word splitter of its own. A planned command runs as `git --no-pager` and the
+ * plan's words, as an argument vector with no shell, bounded in time, and only
+ * once every commit the plan names is held by the repository.
+ *
+ * A command `planReplay` does not plan is counted as not replayable and never
+ * failed. A different output, a commit the repository does not hold, a
+ * non-zero exit and a replay that runs out of time are findings.
+ *
+ * The check fails closed: a failure the claim reader answers, an invalid
+ * `timeoutMs` or a git invocation other than a replay that fails is a `fail`
+ * record naming the cause, never a pass and never a thrown error.
+ */
+import { spawn } from "node:child_process";
+import { readFigureClaims } from "./figure-claims.js";
+import { planReplay } from "./replay-plan.js";
+const NAME = "RT-19";
+/** How long one replay may run, in milliseconds, when the caller sets no bound. */
+export const DEFAULT_REPLAY_TIMEOUT_MS = 10000;
+/** The most characters of an output a finding shows. */
+export const SHOWN_OUTPUT_LENGTH = 120;
+/**
+ * Run git with an argument vector and no shell. A run still going at the
+ * bound is killed with its whole process group and answered at once, so a
+ * process it left behind holding a pipe cannot hold the check.
+ */
+function runGit(cwd, args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], detached: true });
+        const out = [];
+        const err = [];
+        child.stdout.on("data", (chunk) => out.push(chunk));
+        child.stderr.on("data", (chunk) => err.push(chunk));
+        const timer = setTimeout(() => {
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+            child.stdout.destroy();
+            child.stderr.destroy();
+            resolve({ timedOut: true, code: null, signal: null, stdout: "", stderr: "" });
+        }, timeoutMs);
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            resolve({
+                timedOut: false,
+                code,
+                signal,
+                stdout: Buffer.concat(out).toString("utf8"),
+                stderr: Buffer.concat(err).toString("utf8").trim(),
+            });
+        });
+    });
+}
+/** Escape every character outside printable ASCII so a line cannot replay a terminal sequence or split. */
+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 shown(output) {
+    const chars = [...output];
+    if (chars.length <= SHOWN_OUTPUT_LENGTH)
+        return `\`${output}\``;
+    return `\`${chars.slice(0, SHOWN_OUTPUT_LENGTH).join("")}\`...`;
+}
+function finding(claim, printed) {
+    return escapeText(`${claim.where}: \`${claim.command}\` printed ${printed} claims ${shown(claim.claimed)}`);
+}
+/** Whether the repository holds `id` as a commit. Any answer but yes or no is thrown. */
+async function holdsCommit(cwd, id, timeoutMs) {
+    const run = await runGit(cwd, ["rev-parse", "--verify", "--quiet", `${id}^{commit}`], timeoutMs);
+    if (run.code === 0)
+        return true;
+    if (run.code === 1)
+        return false;
+    const cause = run.timedOut ? "timed out" : run.stderr || `exit code ${run.code ?? run.signal}`;
+    throw new Error(`git rev-parse could not look up commit ${id}: ${cause}`);
+}
+/** Replay one planned claim; the finding it is, or `null` when it is reproduced. */
+async function replay(cwd, claim, plan, timeoutMs, held) {
+    for (const id of plan.commits) {
+        if (!held.has(id))
+            held.set(id, await holdsCommit(cwd, id, timeoutMs));
+        if (held.get(id) === false)
+            return finding(claim, `nothing: the repository does not hold ${id};`);
+    }
+    const run = await runGit(cwd, ["--no-pager", ...plan.args], timeoutMs);
+    if (run.timedOut)
+        return finding(claim, `nothing: timed out after ${timeoutMs} ms;`);
+    if (run.code !== 0) {
+        return finding(claim, run.code === null ? `nothing: killed by ${run.signal};` : `nothing: exit code ${run.code};`);
+    }
+    const output = plan.countLines
+        ? String(run.stdout.split("\n").length - 1)
+        : run.stdout.endsWith("\n")
+            ? run.stdout.slice(0, -1)
+            : run.stdout;
+    return output === claim.claimed ? null : finding(claim, shown(output));
+}
+function failure(cause) {
+    return { name: NAME, status: "fail", evidence: [escapeText(cause)] };
+}
+/** Replay every figure claim the range adds and compare each with what it says. */
+export async function checkReplayedFigures(options) {
+    try {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_REPLAY_TIMEOUT_MS;
+        if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return failure(`timeoutMs ${String(timeoutMs)} is not a positive number of milliseconds`);
+        }
+        const read = await readFigureClaims({ cwd: options.cwd, base: options.base, candidate: options.candidate });
+        // The reader's text is held as it answers it; it quotes the revision it names.
+        if ("failure" in read)
+            return { name: NAME, status: "fail", evidence: [read.failure] };
+        const findings = [];
+        const held = new Map();
+        let reproduced = 0;
+        let notReplayable = 0;
+        for (const claim of read.claims) {
+            const plan = planReplay(claim.command);
+            if (plan === null) {
+                notReplayable += 1;
+                continue;
+            }
+            const found = await replay(options.cwd, claim, plan, timeoutMs, held);
+            if (found === null)
+                reproduced += 1;
+            else
+                findings.push(found);
+        }
+        if (findings.length > 0)
+            return { name: NAME, status: "fail", evidence: findings };
+        return { name: NAME, status: "pass", evidence: [`${reproduced} reproduced, ${notReplayable} not replayable`] };
+    }
+    catch (error) {
+        return failure(`replayed-figures check could not run: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=replayed-figures.js.map

package/dist/replayed-figures.js.map

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

package/dist/snapshot-refreshes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { CheckRecord } from "./index.js";
+/**
+ * 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 declare const SNAPSHOT_PATHS: RegExp[];
+export type SnapshotCategory = "snapshot-refreshed" | "snapshot-deleted";
+export interface SnapshotRefreshesOptions {
+    readonly cwd: string;
+    readonly base: string;
+    readonly candidate: string;
+    /** Keys are finding ids; values are the reasons. */
+    readonly sanctions?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * 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 declare function checkSnapshotRefreshes(options: SnapshotRefreshesOptions): Promise<CheckRecord>;