builder-assistant-engineer 0.2.0

package/dist/review/integrity.js

@@ -0,0 +1,150 @@
+import { isTestFile } from "../digest/baseline.js";
+import { isLockfile, languageOf } from "../digest/files.js";
+import { accept, findingId } from "../gates/findings.js";
+import { executed } from "../gates/results.js";
+import { t } from "../i18n/index.js";
+import { inScope, scopePaths } from "./scope.js";
+import { annotatedCount, assertionCount, EXPECTED_FAILURES, exclusionKeys, isExpectedOutput, isRunnerConfig, isTestChange, markerCounts, suppressionLines, testNames, } from "./tests.js";
+export function staticIntegrity(task, changes, acceptance) {
+    const scope = scopePaths(task);
+    const listed = (file) => inScope(file, scope);
+    const texts = new Map(changes.added.map((item) => [item.path, item.text]));
+    const before = new Map(changes.removed.map((item) => [item.path, item.text]));
+    const findings = [
+        ...changes.deleted
+            .filter((file) => isTestFile(file) && !movedElsewhere(file, changes))
+            .map((file) => scoped(listed(file), blocker(file, t("integrity.deleted"), "deleted"))),
+        ...changes.added.filter(isTestChange).flatMap((item) => addedMarkers(item.text, before.get(item.path) ?? "").map((marker) => {
+            const finding = blocker(item.path, t("integrity.skipMarker", { marker }), marker);
+            return EXPECTED_FAILURES.has(marker) ? finding : scoped(listed(item.path), finding);
+        })),
+        ...removedTests(changes).map((finding) => scoped(listed(finding.file ?? ""), finding)),
+        ...lostAssertions(changes, listed),
+        ...changes.added.flatMap((item) => suppressionFindings(item, before.get(item.path) ?? "")),
+        ...changes.files.filter(isExpectedOutput).map((file) => {
+            const finding = blocker(file, t("integrity.expectedOutput"), "expected-output");
+            if (listed(file))
+                return scoped(true, finding);
+            return changes.untracked.includes(file)
+                ? { ...finding, severity: "major" }
+                : finding;
+        }),
+        ...changes.untracked.filter(isRunnerConfig).flatMap((path) => {
+            const keys = exclusionKeys(texts.get(path) ?? "");
+            if (keys.length === 0)
+                return [];
+            return [blocker(path, t("integrity.exclusion", { keys: keys.join(", ") }), keys.join(","))];
+        }),
+    ];
+    return findings.map((finding) => finding.severity === "blocker"
+        ? accept(acceptance, finding, listed(finding.file ?? ""))
+        : finding);
+}
+export function countIntegrity(checks, acceptance, planned = false) {
+    const findings = comparable(checks).flatMap(({ check, now, before }) => {
+        const vars = { command: check.command, now: describe(now), before: describe(before) };
+        return [
+            ...(executed(now) < executed(before)
+                ? [counted(check, "fewer", t("integrity.fewerTests", vars))]
+                : []),
+            ...(now.skipped > before.skipped
+                ? [counted(check, "skipped", t("integrity.moreSkipped", vars))]
+                : []),
+        ];
+    });
+    return findings.map((finding) => planned
+        ? {
+            ...finding,
+            severity: "major",
+            message: `${finding.message} ${t("integrity.planned")}`,
+        }
+        : accept(acceptance, finding, true));
+}
+export function testsGrew(checks) {
+    return comparable(checks).some(({ now, before }) => executed(now) > executed(before));
+}
+function comparable(checks) {
+    return checks.flatMap((check) => check.key === "test" && check.counts && check.before?.counts
+        ? [{ check, now: check.counts, before: check.before.counts }]
+        : []);
+}
+function movedElsewhere(file, changes) {
+    const removed = changes.removed.find((item) => item.path === file);
+    const names = testNames(removed?.text ?? "");
+    if (names.length === 0)
+        return false;
+    const kept = new Set(changes.added.filter(isTestChange).flatMap((item) => testNames(item.text)));
+    return names.every((name) => kept.has(name));
+}
+function removedTests(changes) {
+    const kept = new Set(changes.added.filter(isTestChange).flatMap((item) => testNames(item.text)));
+    const added = new Map(changes.added.map((item) => [item.path, annotatedCount(item.text)]));
+    return changes.removed
+        .filter((item) => isTestChange(item) || isTestFile(item.path))
+        .flatMap((item) => {
+        const names = [...new Set(testNames(item.text))].filter((name) => !kept.has(name));
+        const annotated = annotatedCount(item.text) - (added.get(item.path) ?? 0);
+        if (names.length === 0 && annotated <= 0)
+            return [];
+        const what = names.length > 0 ? names.join(", ") : String(annotated);
+        return [blocker(item.path, t("integrity.removedTests", { tests: what }), `removed:${what}`)];
+    });
+}
+function lostAssertions(changes, listed) {
+    const tally = (items) => new Map(items.filter(isTestChange).map((item) => [item.path, assertionCount(item.text)]));
+    const removed = tally(changes.removed);
+    const added = tally(changes.added);
+    return [...removed.entries()]
+        .filter(([path, count]) => count > (added.get(path) ?? 0))
+        .map(([path, count]) => {
+        const lost = count - (added.get(path) ?? 0);
+        const finding = blocker(path, t("integrity.lostAssertions", { count: lost }), `assertions:${lost}`);
+        return scoped(listed(path), finding);
+    });
+}
+function addedMarkers(added, removed) {
+    const now = markerCounts(added);
+    const then = markerCounts(removed);
+    return [...now.entries()]
+        .filter(([name, count]) => count > (then.get(name) ?? 0))
+        .map(([name]) => name);
+}
+function suppressionFindings(item, removed) {
+    if (isLockfile(item.path) || !languageOf(item.path))
+        return [];
+    const net = (specific) => {
+        const count = (text) => suppressionLines(text).filter((line) => line.specific === specific);
+        const names = count(item.text).map((line) => line.name);
+        const gone = count(removed).map((line) => line.name);
+        return names.length > gone.length ? [...new Set(names)] : [];
+    };
+    const blanket = net(false);
+    const specific = net(true);
+    const found = (names) => blocker(item.path, t("integrity.suppression", { markers: names.join(", ") }), `suppress:${names.join(", ")}`);
+    return [
+        ...(blanket.length > 0 ? [found(blanket)] : []),
+        ...(specific.length > 0 ? [{ ...found(specific), severity: "major" }] : []),
+    ];
+}
+function scoped(authorized, finding) {
+    if (!authorized)
+        return finding;
+    return {
+        ...finding,
+        severity: "major",
+        justify: true,
+        message: `${finding.message} ${t("integrity.scoped")}`,
+    };
+}
+export function hasComparableCounts(checks) {
+    return comparable(checks).length > 0;
+}
+function blocker(file, message, detail) {
+    return { severity: "blocker", id: findingId("integrity", file, detail), file, message };
+}
+function counted(check, kind, message) {
+    return { severity: "blocker", id: findingId("integrity", check.command, kind), message };
+}
+function describe(counts) {
+    return `${executed(counts)} run, ${counts.skipped} skipped`;
+}

package/dist/review/mechanical.js

@@ -0,0 +1,62 @@
+import { isTestFile } from "../digest/baseline.js";
+import { isBuildOutput, isLockfile } from "../digest/files.js";
+import { accept, findingId, newAcceptance } from "../gates/findings.js";
+import { t } from "../i18n/index.js";
+import { staticIntegrity } from "./integrity.js";
+import { inScope, scopePaths } from "./scope.js";
+import { secretFindings } from "./secrets.js";
+import { assertionCount, isTestChange } from "./tests.js";
+const ALWAYS_IN_SCOPE = new Set([".gitignore"]);
+export function mechanicalReview(task, changes, acceptance = newAcceptance(), facts = { testsGrew: false }) {
+    const own = sourceChanges(changes);
+    const findings = [
+        ...secretFindings(changes, facts.secrets ?? { allow: [] }, facts.history).map((finding) => accept(acceptance, finding, true)),
+        ...staticIntegrity(task, own, acceptance),
+        ...testFindings(task, own, facts).map((finding) => accept(acceptance, finding, true)),
+        ...scopeFindings(task, own),
+    ];
+    return { passed: !findings.some((finding) => finding.severity === "blocker"), findings };
+}
+function sourceChanges(changes) {
+    const keep = (path) => !isBuildOutput(path);
+    return {
+        files: changes.files.filter(keep),
+        added: changes.added.filter((item) => keep(item.path)),
+        removed: changes.removed.filter((item) => keep(item.path)),
+        deleted: changes.deleted.filter(keep),
+        untracked: changes.untracked.filter(keep),
+    };
+}
+function testFindings(task, changes, facts) {
+    if (task.meta.tests !== "required" || facts.testsGrew)
+        return [];
+    if (netAssertions(changes, facts.counted ?? false) > 0)
+        return [];
+    return [
+        {
+            severity: "blocker",
+            id: findingId("integrity", task.path, "tests-required"),
+            message: t("mechanical.noTests"),
+        },
+    ];
+}
+function scopeFindings(task, changes) {
+    const patterns = scopePaths(task);
+    if (patterns.length === 0)
+        return [];
+    const outside = changes.files.filter((file) => !inScope(file, patterns) &&
+        !isTestFile(file) &&
+        !isLockfile(file) &&
+        !ALWAYS_IN_SCOPE.has(file));
+    if (outside.length === 0)
+        return [];
+    return [
+        { severity: "major", message: t("mechanical.outOfScope", { files: outside.join(", ") }) },
+    ];
+}
+function netAssertions(changes, counted) {
+    const fresh = new Set(changes.untracked);
+    const total = (items) => items.filter(isTestChange).reduce((sum, item) => sum + assertionCount(item.text), 0);
+    const added = changes.added.filter((item) => !(counted && fresh.has(item.path)));
+    return total(added) - total(changes.removed);
+}

package/dist/review/parse.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { FormatError } from "../core/errors.js";
+const reviewSchema = z.object({
+    verdict: z.enum(["pass", "fail"]),
+    findings: z
+        .array(z.object({
+        severity: z.enum(["blocker", "major", "minor"]),
+        id: z.string().optional(),
+        file: z.string().optional(),
+        message: z.string().min(1),
+        justify: z.boolean().optional(),
+    }))
+        .default([]),
+});
+export const REVIEW_FORMAT = 'JSON only: {"verdict": "pass" | "fail", "findings": [{"severity": "blocker" | "major" | "minor", "file": "optional path", "message": "..."}]}';
+export function parseReview(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end < start)
+        throw new FormatError("no JSON object found");
+    let data;
+    try {
+        data = JSON.parse(text.slice(start, end + 1));
+    }
+    catch (error) {
+        throw new FormatError(`invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = reviewSchema.safeParse(data);
+    if (!result.success)
+        throw new FormatError(z.prettifyError(result.error));
+    const object = text.slice(start, end + 1);
+    if ((object.match(/"verdict"\s*:/g) ?? []).length > 1) {
+        throw new FormatError("more than one verdict");
+    }
+    const outside = `${text.slice(0, start)} ${text.slice(end + 1)}`;
+    if (result.data.verdict === "pass" && /\bverdict\b[^\n{]{0,20}\bfail/i.test(outside)) {
+        throw new FormatError("the text around the JSON contradicts its verdict");
+    }
+    return result.data;
+}

package/dist/review/reviewer.js

@@ -0,0 +1,23 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { readTextIfExists } from "../core/fs.js";
+const AGENT_DIRS = [".claude/agents", ".opencode/agent"];
+const DEFAULT_REVIEWER = "A strict senior code reviewer. Checks that the changes meet every acceptance criterion, follow the project conventions, include tests, stay within the task scope and introduce no security issues.";
+export async function findReviewer(cwd, backend) {
+    const dirs = backend === "opencode" ? [...AGENT_DIRS].reverse() : AGENT_DIRS;
+    for (const dir of dirs) {
+        const path = join(cwd, ...dir.split("/"));
+        const name = (await listNames(path)).find((entry) => /review/i.test(entry) && entry.endsWith(".md"));
+        if (name)
+            return (await readTextIfExists(join(path, name))) ?? DEFAULT_REVIEWER;
+    }
+    return DEFAULT_REVIEWER;
+}
+async function listNames(dir) {
+    try {
+        return (await readdir(dir)).sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/review/run.js

@@ -0,0 +1,134 @@
+import { join } from "node:path";
+import { LANGUAGE_NAMES } from "../analyst/prompt.js";
+import { runWithFormatRetry } from "../analyst/retry.js";
+import { readTextIfExists } from "../core/fs.js";
+import { renderPrompt } from "../core/prompt-loader.js";
+import { truncateText } from "../digest/format.js";
+import { capturedPrompt } from "../gates/capture.js";
+import { withoutLog } from "../gates/contract.js";
+import { newAcceptance } from "../gates/findings.js";
+import { t } from "../i18n/index.js";
+import { logLines } from "../tasks/handoff.js";
+import { parseTask } from "../tasks/schema.js";
+import { committedText, taskChanges } from "./changes.js";
+import { reviewDiff } from "./diff.js";
+import { mechanicalReview } from "./mechanical.js";
+import { parseReview, REVIEW_FORMAT } from "./parse.js";
+import { scopePaths } from "./scope.js";
+const MAX_AGENTS_MD = 20_000;
+const REASONS = {
+    noGit: "review.noGit",
+    noBase: "review.noBase",
+    gitError: "review.gitError",
+};
+export function capturedTask(capture) {
+    return parseTask(capture.path, capture.task);
+}
+export async function reviewTask(ctx, capture, notes = [], acceptance = newAcceptance(), facts = { testsGrew: false }, evidence = "") {
+    const task = capturedTask(capture);
+    const view = await taskChanges(ctx.cwd, capture);
+    if (!view.ok) {
+        const reason = t(REASONS[view.reason]);
+        return view.reason === "noGit"
+            ? { status: "skipped", findings: [], reason }
+            : { status: "fail", findings: [{ severity: "blocker", message: reason }], reason };
+    }
+    const log = await currentLog(ctx.cwd, capture);
+    const scanned = {
+        ...view.changes,
+        added: [...view.changes.added, ...view.late, ...(log ? [log] : [])],
+    };
+    const history = await committedText(ctx.cwd, view.ref);
+    if (!history) {
+        const reason = t("review.gitError");
+        return { status: "fail", findings: [{ severity: "blocker", message: reason }], reason };
+    }
+    const mechanical = mechanicalReview(task, scanned, acceptance, { ...facts, history });
+    if (mechanical.passed && view.changes.files.length === 0) {
+        return { status: "pass", findings: mechanical.findings, reason: t("review.noChanges") };
+    }
+    if (!mechanical.passed) {
+        return {
+            status: "fail",
+            findings: mechanical.findings,
+            reason: t("mechanical.failed"),
+            stage: "mechanical",
+        };
+    }
+    const diff = await reviewDiff(ctx.cwd, view.ref, view.changes, scopePaths(task), view.late.map((item) => item.path));
+    if (!diff) {
+        const reason = t("review.gitError");
+        return { status: "fail", findings: [{ severity: "blocker", message: reason }], reason };
+    }
+    const prompt = renderPrompt(capturedPrompt(capture, "review"), {
+        reviewer: capture.reviewer,
+        agents_md: truncateText(capture.agentsMd ?? "(none)", MAX_AGENTS_MD),
+        task: withoutLog(capture.task),
+        diff: diff.text,
+        checks: formatFindings([...mechanical.findings, ...notes]) || "(none)",
+        evidence: evidence || t("review.noEvidence"),
+        output_language: LANGUAGE_NAMES[capture.config.lang],
+    });
+    if (ctx.flags.dryRun) {
+        ctx.print(`${prompt}\n`);
+        return { status: "skipped", findings: [], reason: t("review.dryRun") };
+    }
+    const backend = ctx.createBackend(capture.config.backend);
+    const reply = await ctx.prompter.spinner(t("review.running", { id: task.meta.id }), () => runWithFormatRetry({
+        backend,
+        prompt,
+        options: {
+            cwd: ctx.cwd,
+            access: "read",
+            timeoutMs: capture.config.agent.timeoutMinutes * 60_000,
+        },
+        parse: parseReview,
+        format: REVIEW_FORMAT,
+        fixPrompt: capturedPrompt(capture, "fix-format"),
+        onRetry: () => ctx.prompter.warn(t("format.retrying")),
+    }));
+    const blocked = reply.findings.some((finding) => finding.severity === "blocker");
+    const unjustified = mechanical.findings.filter((finding) => finding.justify && !reply.findings.some((answer) => sameFile(answer.file, finding.file)));
+    const missing = reply.verdict === "pass" && unjustified.length > 0
+        ? [
+            {
+                severity: "blocker",
+                message: t("review.unjustified", {
+                    files: [...new Set(unjustified.map((finding) => finding.file ?? ""))].join(", "),
+                }),
+            },
+        ]
+        : [];
+    return {
+        status: reply.verdict === "pass" && !blocked && missing.length === 0 ? "pass" : "fail",
+        findings: [...mechanical.findings, ...reply.findings, ...missing],
+        stage: "reviewer",
+        ...(missing[0] ? { reason: missing[0].message } : {}),
+    };
+}
+function sameFile(answer, file) {
+    if (!answer || !file)
+        return false;
+    const clean = (path) => path
+        .replace(/\\/g, "/")
+        .replace(/^\.\//, "")
+        .replace(/:\d+.*$/, "");
+    return clean(answer) === clean(file);
+}
+async function currentLog(cwd, capture) {
+    const text = await readTextIfExists(join(cwd, ...capture.path.split("/")));
+    if (text === undefined)
+        return undefined;
+    try {
+        const lines = logLines(parseTask(capture.path, text));
+        return lines.length > 0 ? { path: capture.path, text: lines.join("\n") } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function formatFindings(findings) {
+    return findings
+        .map((finding) => `- [${finding.severity}]${finding.id ? ` (${finding.id})` : ""} ${finding.file ? `${finding.file}: ` : ""}${finding.message}`)
+        .join("\n");
+}

package/dist/review/scope.js

@@ -0,0 +1,55 @@
+import { sectionText } from "../tasks/schema.js";
+const OUT_MARKER = /^\W*(out|fuera|excluded|excluido|not in scope|do not (?:change|touch|edit)|don't (?:change|touch|edit)|no (?:cambiar|tocar|modificar))\b/i;
+const CODE_SPAN = /`([^`\n]+)`/g;
+const LIST_PATH = /^\s*[-*+]\s+([\w@.[\]()*?/-]+\/[\w@.[\]()*?/-]*|[\w@-]+\.[A-Za-z]\w*)(?=\s|$|[,;:])/;
+const NEW_MARK = /\s*\((?:new|nuevo|nueva)\)$/i;
+const REDUCTION_MARK = /\s*\((?:delete|deleted|remove|removed|remove tests|borrar|eliminar)\)$/i;
+export function scopePaths(task) {
+    const scope = sectionText(task.body, "scope") ?? "";
+    const lines = scope.split(/\r?\n/);
+    const out = lines.findIndex((line) => OUT_MARKER.test(line.replace(/[`*_]/g, "")));
+    const inScope = out === -1 ? lines : lines.slice(0, out);
+    const paths = inScope.flatMap((line) => [
+        ...Array.from(line.matchAll(CODE_SPAN), (match) => match[1] ?? ""),
+        LIST_PATH.exec(line)?.[1] ?? "",
+    ]);
+    return [...new Set(paths.map(normalize).filter((path) => path !== undefined))];
+}
+export function reductionPaths(task) {
+    const scope = sectionText(task.body, "scope") ?? "";
+    return [
+        ...scope.matchAll(/`([^`\n]+)`\s*\((?:delete|deleted|remove|removed|remove tests|borrar|eliminar)\)|`([^`\n]+?)\s*\((?:delete|deleted|remove|removed|remove tests|borrar|eliminar)\)`/gi),
+    ]
+        .map((match) => normalize(match[1] ?? match[2] ?? ""))
+        .filter((path) => path !== undefined);
+}
+export function inScope(file, patterns) {
+    return patterns.some((pattern) => {
+        if (/[*?]/.test(pattern))
+            return globToRegExp(pattern).test(file);
+        const dir = pattern.endsWith("/") ? pattern : `${pattern}/`;
+        return file === pattern.replace(/\/$/, "") || file.startsWith(dir);
+    });
+}
+function normalize(raw) {
+    const path = raw.trim().replace(NEW_MARK, "").replace(REDUCTION_MARK, "").replace(/^\.\//, "");
+    if (path === "" || /\s|:\/\//.test(path))
+        return undefined;
+    if (/[*?]/.test(path) && globToRegExp(path).test("a") && globToRegExp(path).test("x/y/z.q")) {
+        return undefined;
+    }
+    return path.includes("/") || /\.[A-Za-z]\w*$/.test(path) ? path : undefined;
+}
+function globToRegExp(pattern) {
+    const source = pattern
+        .split("**/")
+        .map((part) => part
+        .split("**")
+        .map((piece) => piece
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]"))
+        .join(".*"))
+        .join("(?:.*/)?");
+    return new RegExp(`^${source}$`);
+}

package/dist/review/secrets.js

@@ -0,0 +1,163 @@
+import { isTestFile } from "../digest/baseline.js";
+import { isBinaryPath, isLockfile, isSecretPath } from "../digest/files.js";
+import { SECRET_TOKENS } from "../digest/redact.js";
+import { findingId } from "../gates/findings.js";
+import { t } from "../i18n/index.js";
+import { inScope } from "./scope.js";
+const EXAMPLE_VALUES = new Set([
+    "AKIAIOSFODNN7EXAMPLE",
+    "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+]);
+const TEST_PREFIXES = /^[spr]k_test_/;
+const KEYWORD = "(?<![A-Za-z0-9_.-])[A-Za-z0-9_.-]{0,40}(?:passw(?:or)?d|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credential)[A-Za-z0-9_.-]{0,40}";
+const ASSIGNED = new RegExp(`${KEYWORD}["']?[ \\t]*[:=][ \\t]*(["'])([^"'\\s]{8,})\\1`, "gi");
+const UNQUOTED = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${KEYWORD}[ \\t]*[:=][ \\t]*()([^\\s"'#,;]{8,})[ \\t]*(?:#.*)?$`, "gim");
+const SECRET_CONTEXT = new RegExp(`${KEYWORD}["']?[ \\t]*[:=]`, "i");
+const PUBLIC_CONTEXT = /public|pub[_-]?key|vapid|checksum|sha\d*|digest|hash|integrity|fingerprint|etag|commit|revision|nonce|uuid|id["']?\s*[:=]\s*$/i;
+const LOCAL_HOSTS = /@(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]|db|database|postgres|mysql|redis|mongo|host\.docker\.internal|example\.(?:com|org|net))(?:[:/]|$)/i;
+const SAMPLE_JWT = "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
+const IDENTIFIER = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$|^[a-z]{1,15}(_[a-z]{1,15})+$|^\d+$/;
+const CONNECTION = /\b[a-z][a-z0-9+.-]*:\/\/([^\s:@/'"]+):([^\s@/'"]+)@[^\s'"]+/gi;
+const QUOTED_BLOB = /(["'`])([A-Za-z0-9+/_-]{40,}={0,2}|[a-f0-9]{48,})\1/g;
+const LABEL = /^[\p{L}\s.,:;!?¿¡'-]+$/u;
+const PLACEHOLDER = /^(?:\$|<|\{|%|\*+$)|^(?:x+|changeme|change[-_]me|example\w*|placeholder|password\d*|pass\d*|secret\d*|dummy|fake|test\w*|your[-_]\w+|my\w*|redacted|postgres|root|admin|dev|local|mysql|guest|user|sa|app)$/i;
+const MIN_ENTROPY = 4.5;
+export function secretFindings(changes, options, history = []) {
+    const allowed = (path) => options.allow.length > 0 && inScope(path, options.allow);
+    const deleted = new Set(changes.deleted);
+    const fileFinding = (file, key) => ({
+        severity: "blocker",
+        id: findingId("secret", file),
+        file,
+        message: t(key),
+    });
+    const valueFindings = (items, key) => items.flatMap((item) => {
+        if (secretFile(item.path) || allowed(item.path))
+            return [];
+        const kinds = secretKinds(item);
+        if (kinds.length === 0)
+            return [];
+        const kind = kinds.join(", ");
+        return [
+            {
+                severity: "blocker",
+                id: findingId("secret", item.path, kind),
+                file: item.path,
+                message: t(key, { kind }),
+            },
+        ];
+    });
+    const found = [
+        ...changes.files
+            .filter((file) => secretFile(file) && !allowed(file) && !deleted.has(file))
+            .map((file) => fileFinding(file, "mechanical.secretFile")),
+        ...valueFindings(changes.added, "mechanical.secretValue"),
+        ...[...new Set(history.map((item) => item.path))]
+            .filter((file) => secretFile(file) && !allowed(file))
+            .map((file) => fileFinding(file, "mechanical.secretFileHistory")),
+        ...valueFindings(history, "mechanical.secretHistory"),
+    ];
+    const seen = new Set();
+    return found.filter((finding) => {
+        if (seen.has(finding.id ?? ""))
+            return false;
+        seen.add(finding.id ?? "");
+        return true;
+    });
+}
+export function secretFile(path) {
+    if (/\.(pem|crt|cer|tfvars)$/i.test(path))
+        return false;
+    if (/(^|\/)\.env\.(development|dev|test|ci|defaults)$/i.test(path))
+        return false;
+    return isSecretPath(path);
+}
+export function secretKinds(item) {
+    const kinds = SECRET_TOKENS.filter(([, pattern]) => [...item.text.matchAll(new RegExp(pattern.source, "g"))].some((match) => !isExample(match[0]))).map(([kind]) => kind);
+    if (item.path.startsWith("(commit "))
+        return [...new Set(kinds)];
+    const loose = !isTestName(item.path) &&
+        !isFixture(item.path) &&
+        !isLockfile(item.path) &&
+        !isBinaryPath(item.path);
+    if (loose && hasAssignedSecret(item.text))
+        kinds.push("hardcoded password or key");
+    if (hasCredentialUrl(item.text))
+        kinds.push("credentials in a connection string");
+    if (loose && !/\.(svg|map|snap)$/i.test(item.path) && hasHighEntropyBlob(item.text)) {
+        kinds.push("long random string");
+    }
+    return [...new Set(kinds)];
+}
+function isExample(value) {
+    if (EXAMPLE_VALUES.has(value) || TEST_PREFIXES.test(value) || value.endsWith(SAMPLE_JWT)) {
+        return true;
+    }
+    const body = value.replace(/^(?:AKIA|ASIA|gh[pousr]_|github_pat_|glpat-|xox[abprs]-|sk-|[rs]k_live_|AIza|npm_)/, "");
+    if (/example|sample|fake|dummy|placeholder|test|your|redacted|changeme|xxxx|0000/i.test(body)) {
+        return true;
+    }
+    return new Set(body).size <= 6 || /(.)\1{5,}/.test(body);
+}
+function isFixture(path) {
+    return (/(^|\/)(fixtures?|__fixtures__|testdata|mocks?|__mocks__)\//.test(path) ||
+        /\.(md|mdx|rst|txt)$/i.test(path));
+}
+function looksPublic(value) {
+    return (/^arn:/.test(value) ||
+        /^\^|\(\?[=!:<]|\.\{\d|\\[dws]|\[[A-Za-z]-[A-Za-z]\]/.test(value) ||
+        !/[A-Za-z0-9]/.test(value));
+}
+function hasAssignedSecret(text) {
+    return [...text.matchAll(ASSIGNED), ...text.matchAll(UNQUOTED)].some((match) => {
+        const value = match[2] ?? "";
+        if (PLACEHOLDER.test(value) || EXAMPLE_VALUES.has(value) || LABEL.test(value))
+            return false;
+        if (looksPublic(value) || isExample(value))
+            return false;
+        if (IDENTIFIER.test(value) || /^[$<{%]/.test(value))
+            return false;
+        return !value.includes("/") && !/^[\w.-]+\.[a-z]{2,4}$/i.test(value);
+    });
+}
+function isTestName(path) {
+    return (isTestFile(path) &&
+        /(\.|_)(test|spec|cy|e2e)\.|(^|\/)test_[^/]+$|_test\.\w+$|Tests?\.\w+$/.test(path));
+}
+function hasCredentialUrl(text) {
+    return [...text.matchAll(CONNECTION)].some((match) => {
+        const password = match[2] ?? "";
+        if (LOCAL_HOSTS.test(match[0].slice(match[0].indexOf("@"))))
+            return false;
+        return !PLACEHOLDER.test(password) && !/^\$\{?\w+\}?$/.test(password);
+    });
+}
+function hasHighEntropyBlob(text) {
+    return [...text.matchAll(QUOTED_BLOB)].some((match) => {
+        const value = match[2] ?? "";
+        const before = text.slice(Math.max(0, (match.index ?? 0) - 16), match.index ?? 0);
+        const context = text.slice(Math.max(0, (match.index ?? 0) - 60), match.index ?? 0);
+        const line = context.split("\n").at(-1) ?? "";
+        if (/^sha\d+-/i.test(value) || /(data:[^,]*,|integrity["']?\s*[:=]\s*)$/i.test(before)) {
+            return false;
+        }
+        if (PUBLIC_CONTEXT.test(line) && !SECRET_CONTEXT.test(line))
+            return false;
+        if (/^[a-f0-9]+$/.test(value)) {
+            return SECRET_CONTEXT.test(line) && value.length >= 32 && entropy(value) >= 3.5;
+        }
+        return (/[A-Z]/.test(value) &&
+            /[a-z]/.test(value) &&
+            /\d/.test(value) &&
+            entropy(value) >= MIN_ENTROPY);
+    });
+}
+function entropy(value) {
+    const counts = new Map();
+    for (const char of value)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    return [...counts.values()].reduce((sum, count) => {
+        const share = count / value.length;
+        return sum - share * Math.log2(share);
+    }, 0);
+}

package/dist/review/snapshot.js

@@ -0,0 +1,38 @@
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { excluded, git, gitPaths, isGitRepo } from "../core/git.js";
+const HASH_BATCH = 100;
+export async function takeSnapshot(cwd, exclude) {
+    if (!(await isGitRepo(cwd)))
+        return {};
+    const pathspec = ["--", ".", ...exclude.map(excluded)];
+    const [changed, untracked] = await Promise.all([
+        gitPaths(cwd, ["diff", "--name-only", "--no-renames", "HEAD", ...pathspec]),
+        gitPaths(cwd, ["ls-files", "--others", "--exclude-standard", ...pathspec]),
+    ]);
+    return hashPaths(cwd, [...new Set([...(changed ?? []), ...(untracked ?? [])])]);
+}
+export async function unchangedSince(cwd, snapshot, files) {
+    const known = files.filter((file) => Object.hasOwn(snapshot, file));
+    const current = await hashPaths(cwd, known);
+    return new Set(known.filter((file) => current[file] === snapshot[file]));
+}
+export async function hashPaths(cwd, paths) {
+    const snapshot = {};
+    const present = [];
+    for (const path of paths) {
+        const info = await stat(join(cwd, ...path.split("/"))).catch(() => undefined);
+        if (info?.isFile())
+            present.push(path);
+        else
+            snapshot[path] = null;
+    }
+    for (let start = 0; start < present.length; start += HASH_BATCH) {
+        const batch = present.slice(start, start + HASH_BATCH);
+        const hashes = (await git(cwd, ["hash-object", "--", ...batch]))?.split(/\r?\n/) ?? [];
+        batch.forEach((path, index) => {
+            snapshot[path] = hashes[index]?.trim() || null;
+        });
+    }
+    return snapshot;
+}