@bridge_gpt/mcp-server 0.2.14 → 0.2.16

package/build/regression-check.js

@@ -0,0 +1,820 @@
+/**
+ * regression-check — the deterministic "blast radius" core for the portable
+ * regression-reviewer. Two modes:
+ *
+ *   npx -y @bridge_gpt/mcp-server regression-check [--mode lightweight|heavy]
+ *     [--diff <range>] [--symbols a,b,c] [--json]
+ *
+ * `lightweight` (BAPI-460, default) takes a proposed change (a git diff
+ * range, defaulting to the working tree against HEAD, or an explicit
+ * --symbols list) and reports, per changed symbol: its definition location,
+ * its REAL structural call-sites (via ast-grep), and its broader textual
+ * mention set (via ripgrep — tests/mocks/strings/config). The gap between the
+ * two is the signal: a symbol with many text mentions but few real call-sites
+ * likely has untouched callers, mocks, or config that the change should
+ * account for.
+ *
+ * `heavy` (BAPI-461) takes no diff — it scans the whole repo and surfaces
+ * where FUTURE change is dangerous: high fan-in (real call-sites via
+ * ast-grep) + high temporal coupling (files that historically change
+ * together) + high complexity. Scope is seeded from churn/coupling hotspots
+ * and capped (MAX_HEAVY_HOTSPOTS / MAX_HEAVY_SYMBOLS) so runtime and LLM
+ * context stay bounded on large repos.
+ *
+ * Read-only. Makes no code changes and no network calls. Missing tools
+ * (ast-grep, ripgrep, lizard) degrade gracefully — the affected section is
+ * flagged and the command still exits 0; only usage errors and an unreadable
+ * diff (lightweight mode) exit non-zero. Mirrors the `doctor` /
+ * `agent-capabilities` CLI shape: strict arg parsing -> non-throwing
+ * collection -> format -> exit code.
+ *
+ * This module also hosts two SHARED deterministic-tooling functions —
+ * `analyzeComplexityWithLizard` and `analyzeTemporalCoupling` — used by both
+ * `heavy` mode below and BAPI-459's refactor-reviewer, so that logic has a
+ * single implementation. They are not invoked by the lightweight pipeline.
+ */
+import { createDefaultStartTicketsDeps } from "./start-tickets.js";
+import { isCommandOnPath, resolveFirstCommandOnPath } from "./start-tickets-prereqs.js";
+// ---------------------------------------------------------------------------
+// Usage / argument parsing
+// ---------------------------------------------------------------------------
+const VALID_MODES = ["lightweight", "heavy"];
+/** Symbol set cap per run — keeps downstream LLM context bounded. */
+export const MAX_SYMBOLS_PER_RUN = 40;
+/** ast-grep ships two equivalent binary names; either satisfies the prereq. */
+export const AST_GREP_CANDIDATES = ["ast-grep", "sg"];
+export function getRegressionCheckUsage() {
+    return [
+        "Usage:",
+        "  npx -y @bridge_gpt/mcp-server regression-check [--mode lightweight|heavy] [--diff <range>] [--symbols a,b,c] [--json]",
+        "",
+        "Deterministic blast-radius analysis for a proposed code change: extracts the",
+        "symbols touched by a git diff (or an explicit --symbols list), then uses",
+        "ast-grep to find their REAL structural call-sites and ripgrep for the wider",
+        "set of textual mentions (tests/mocks/strings/config). Read-only — makes no",
+        "code changes and no network calls.",
+        "",
+        "Flags:",
+        "  --mode lightweight|heavy   Analysis depth (default: lightweight). lightweight",
+        "                             traces a proposed diff's blast radius; heavy takes",
+        "                             no diff and scans the whole repo for fragile,",
+        "                             high-blast-radius locations (fan-in + temporal",
+        "                             coupling + complexity), seeded from churn/coupling",
+        "                             hotspots and bounded by a top-N cap.",
+        "  --diff <range>             A git diff range/ref to analyze, lightweight mode only (default: HEAD,",
+        "                             i.e. the working tree against HEAD)",
+        "  --symbols a,b,c            Explicit comma-separated symbol names, bypassing",
+        "                             diff parsing (searches every supported language)",
+        "  --json                     Emit machine-readable JSON instead of a human summary",
+        "  -h, --help                 Show this help",
+        "",
+        "Missing tools (ast-grep, ripgrep) degrade gracefully: the affected section is",
+        "flagged [DEGRADED] and the command still exits 0. Run",
+        "`npx -y @bridge_gpt/mcp-server doctor` to check tool availability.",
+        "",
+        "Exit code: 0 on a completed run (degraded or not); non-zero only for a usage",
+        "error or an unreadable diff.",
+    ].join("\n");
+}
+export function parseRegressionCheckArgs(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        return { status: "help", usage: getRegressionCheckUsage() };
+    }
+    let mode = "lightweight";
+    let diffRange;
+    let symbols;
+    let json = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--mode" || arg.startsWith("--mode=")) {
+            let value;
+            if (arg.startsWith("--mode=")) {
+                value = arg.slice("--mode=".length);
+            }
+            else {
+                if (i + 1 >= argv.length) {
+                    return { status: "error", message: "--mode requires a value (lightweight or heavy)." };
+                }
+                value = argv[++i];
+            }
+            if (!VALID_MODES.includes(value)) {
+                return {
+                    status: "error",
+                    message: `Invalid --mode value: '${value}' (allowed: ${VALID_MODES.join(", ")}).`,
+                };
+            }
+            mode = value;
+            continue;
+        }
+        if (arg === "--diff" || arg.startsWith("--diff=")) {
+            let value;
+            if (arg.startsWith("--diff=")) {
+                value = arg.slice("--diff=".length);
+            }
+            else {
+                if (i + 1 >= argv.length) {
+                    return { status: "error", message: "--diff requires a value (a git diff range/ref)." };
+                }
+                value = argv[++i];
+            }
+            diffRange = value;
+            continue;
+        }
+        if (arg === "--symbols" || arg.startsWith("--symbols=")) {
+            let value;
+            if (arg.startsWith("--symbols=")) {
+                value = arg.slice("--symbols=".length);
+            }
+            else {
+                if (i + 1 >= argv.length) {
+                    return { status: "error", message: "--symbols requires a value (comma-separated symbol names)." };
+                }
+                value = argv[++i];
+            }
+            symbols = value
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            if (symbols.length === 0) {
+                return { status: "error", message: "--symbols requires at least one non-empty symbol name." };
+            }
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            return { status: "error", message: `Unknown flag: ${arg}` };
+        }
+        return {
+            status: "error",
+            message: `Unexpected positional argument: '${arg}'. regression-check takes only flags.`,
+        };
+    }
+    return { status: "ok", options: { mode, diffRange, symbols, json } };
+}
+// ---------------------------------------------------------------------------
+// Secret redaction
+// ---------------------------------------------------------------------------
+const SECRET_PATTERNS = [
+    // key/token/secret/password/bearer = "<value>" style assignments.
+    /\b[A-Za-z0-9_-]*(?:api[_-]?key|token|secret|password|bearer)[A-Za-z0-9_-]*\s*[:=]\s*['"]?[A-Za-z0-9_\-./+=]{8,}['"]?/gi,
+    // Authorization: Bearer <value> headers.
+    /\bBearer\s+[A-Za-z0-9._-]{10,}/g,
+    // Common provider key prefixes (OpenAI/Anthropic-style sk-... tokens).
+    /\bsk-[A-Za-z0-9_-]{16,}/g,
+];
+/** Redact embedded credentials/tokens/secrets with a high-visibility placeholder. */
+export function redactSecrets(text) {
+    let out = text;
+    for (const pattern of SECRET_PATTERNS) {
+        out = out.replace(pattern, "[REDACTED_TOKEN]");
+    }
+    return out;
+}
+async function getDiffText(deps, diffRange) {
+    const args = diffRange ? ["diff", diffRange] : ["diff", "HEAD"];
+    const result = await deps.runCommand("git", args, { cwd: deps.cwd });
+    if (result.exitCode !== 0) {
+        return { ok: false, error: redactSecrets(result.stderr.trim() || `git diff exited ${result.exitCode}`) };
+    }
+    return { ok: true, diff: redactSecrets(result.stdout) };
+}
+// NOTE: the leading `^\s*` tolerates indentation so that *nested* definitions —
+// an indented Python method (`    def handle(self):`) or a nested TS
+// function/const — are still extracted. `content` (see below) keeps the added
+// line's original leading whitespace, so without `\s*` every indented method
+// would silently yield zero symbols.
+const PY_DEF_RE = /^\s*(?:async\s+def|def|class)\s+([A-Za-z_][A-Za-z0-9_]*)/;
+const TS_DEF_RE = /^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:function\s*\*?\s+([A-Za-z_$][\w$]*)|class\s+([A-Za-z_$][\w$]*)|(?:const|let)\s+([A-Za-z_$][\w$]*)\s*[:=])/;
+function languageForFile(file) {
+    if (file.endsWith(".py"))
+        return "python";
+    if (file.endsWith(".ts") || file.endsWith(".tsx"))
+        return "typescript";
+    return null;
+}
+/**
+ * Parse a unified diff (as produced by `git diff`) and extract every changed
+ * top-level def/class (Python) or function/class/const declaration (TS/TSX)
+ * found on an added (`+`) line, with its new-file line number. Removed-only
+ * symbols and unsupported languages are skipped. Never throws — malformed diff
+ * text simply yields fewer (or zero) symbols.
+ */
+export function extractChangedSymbolsFromDiff(diffText) {
+    const symbols = [];
+    let currentFile = null;
+    let newLineNo = 0;
+    for (const rawLine of diffText.split("\n")) {
+        if (rawLine.startsWith("+++ ")) {
+            const path = rawLine.slice(4).trim();
+            currentFile = path === "/dev/null" ? null : path.replace(/^b\//, "");
+            continue;
+        }
+        if (rawLine.startsWith("--- ") || rawLine.startsWith("diff --git") || rawLine.startsWith("index ")) {
+            continue;
+        }
+        const hunkMatch = rawLine.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+        if (hunkMatch) {
+            newLineNo = parseInt(hunkMatch[1], 10);
+            continue;
+        }
+        if (rawLine.startsWith("\\"))
+            continue; // ""
+        if (!currentFile)
+            continue;
+        if (rawLine.startsWith("-"))
+            continue; // removed line: no new-line number, not a "changed" addition
+        const isAdded = rawLine.startsWith("+");
+        const content = isAdded ? rawLine.slice(1) : rawLine.startsWith(" ") ? rawLine.slice(1) : rawLine;
+        if (isAdded) {
+            const language = languageForFile(currentFile);
+            if (language) {
+                let name = null;
+                if (language === "python") {
+                    const m = content.match(PY_DEF_RE);
+                    if (m)
+                        name = m[1];
+                }
+                else {
+                    const m = content.match(TS_DEF_RE);
+                    if (m)
+                        name = m[1] || m[2] || m[3] || null;
+                }
+                if (name) {
+                    symbols.push({ symbol: name, file: currentFile, language, line: newLineNo });
+                }
+            }
+        }
+        newLineNo += 1;
+    }
+    return symbols;
+}
+/** De-duplicate by file+symbol, then cap to {@link MAX_SYMBOLS_PER_RUN}. */
+export function capChangedSymbols(symbols, max = MAX_SYMBOLS_PER_RUN) {
+    const deduped = [];
+    const seen = new Set();
+    for (const s of symbols) {
+        const key = `${s.file ?? ""}::${s.symbol}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(s);
+    }
+    if (deduped.length <= max)
+        return { symbols: deduped, truncated: false };
+    return { symbols: deduped.slice(0, max), truncated: true };
+}
+// ---------------------------------------------------------------------------
+// ast-grep real call-sites
+// ---------------------------------------------------------------------------
+const AST_GREP_LANG = {
+    python: "python",
+    typescript: "typescript",
+};
+async function findCallSites(deps, astGrepBinary, symbol, language) {
+    const languages = language ? [language] : Object.keys(AST_GREP_LANG);
+    const byFile = {};
+    let count = 0;
+    for (const lang of languages) {
+        const pattern = `${symbol}($$$ARGS)`;
+        const result = await deps.runCommand(astGrepBinary, ["run", "--pattern", pattern, "--lang", AST_GREP_LANG[lang], "--json", "."], { cwd: deps.cwd });
+        // ast-grep exits 1 for "ran fine, zero matches" — only >=2 is a real failure.
+        if (result.exitCode >= 2) {
+            return { ok: false, error: redactSecrets(result.stderr.trim() || `ast-grep exited ${result.exitCode}`) };
+        }
+        let matches;
+        try {
+            matches = JSON.parse(result.stdout.trim() || "[]");
+        }
+        catch {
+            return { ok: false, error: "ast-grep returned non-JSON output" };
+        }
+        if (!Array.isArray(matches)) {
+            return { ok: false, error: "ast-grep JSON output was not an array" };
+        }
+        for (const m of matches) {
+            const file = m && typeof m === "object" && typeof m.file === "string"
+                ? m.file
+                : "(unknown)";
+            byFile[file] = (byFile[file] ?? 0) + 1;
+            count += 1;
+        }
+    }
+    return { ok: true, count, byFile };
+}
+async function findBroadMentions(deps, symbol) {
+    const result = await deps.runCommand("rg", ["-l", "-w", "--", symbol, "."], { cwd: deps.cwd });
+    // ripgrep exits 1 for "ran fine, zero matches" — only >=2 is a real failure.
+    if (result.exitCode >= 2) {
+        return { ok: false, error: redactSecrets(result.stderr.trim() || `ripgrep exited ${result.exitCode}`) };
+    }
+    const files = result.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    return { ok: true, files };
+}
+// ---------------------------------------------------------------------------
+// Lightweight pipeline orchestration
+// ---------------------------------------------------------------------------
+function explicitSymbolsToChangedSymbols(symbolNames) {
+    return symbolNames.map((symbol) => ({ symbol, file: null, language: null, line: null }));
+}
+export async function runLightweightRegressionCheck(deps, options) {
+    const degradedFlags = [];
+    const toolsUsed = new Set(["git"]);
+    let changedSymbols;
+    if (options.symbols && options.symbols.length > 0) {
+        changedSymbols = explicitSymbolsToChangedSymbols(options.symbols);
+    }
+    else {
+        const diffResult = await getDiffText(deps, options.diffRange);
+        if (!diffResult.ok) {
+            return { ok: false, error: `Unable to read git diff: ${diffResult.error}` };
+        }
+        changedSymbols = extractChangedSymbolsFromDiff(diffResult.diff);
+    }
+    const { symbols: capped, truncated } = capChangedSymbols(changedSymbols);
+    const astGrepBinary = await resolveFirstCommandOnPath(deps, AST_GREP_CANDIDATES);
+    if (!astGrepBinary) {
+        degradedFlags.push("ast-grep (or sg) not found on PATH — call-site analysis skipped for all symbols.");
+    }
+    else {
+        toolsUsed.add("ast-grep");
+    }
+    const ripgrepFound = await isCommandOnPath(deps, "rg");
+    if (!ripgrepFound) {
+        degradedFlags.push("ripgrep (rg) not found on PATH — broad-mention analysis skipped for all symbols.");
+    }
+    else {
+        toolsUsed.add("ripgrep");
+    }
+    const findings = [];
+    for (const sym of capped) {
+        const finding = {
+            symbol: sym.symbol,
+            file: sym.file,
+            language: sym.language,
+            definitionLocation: sym.file && sym.line ? { file: sym.file, line: sym.line } : null,
+            callSites: null,
+            broadMentions: null,
+        };
+        if (astGrepBinary) {
+            const result = await findCallSites(deps, astGrepBinary, sym.symbol, sym.language);
+            if (result.ok) {
+                finding.callSites = { count: result.count, byFile: result.byFile };
+            }
+            else {
+                degradedFlags.push(`ast-grep call-site search failed for '${sym.symbol}': ${result.error}`);
+            }
+        }
+        if (ripgrepFound) {
+            const result = await findBroadMentions(deps, sym.symbol);
+            if (result.ok) {
+                finding.broadMentions = result.files;
+            }
+            else {
+                degradedFlags.push(`ripgrep mention search failed for '${sym.symbol}': ${result.error}`);
+            }
+        }
+        findings.push(finding);
+    }
+    const report = {
+        mode: "lightweight",
+        summary: {
+            symbolsAnalyzed: findings.map((f) => (f.file ? `${f.file}:${f.symbol}` : f.symbol)),
+            truncated,
+            toolsUsed: Array.from(toolsUsed),
+            degradedFlags,
+        },
+        findings,
+    };
+    return { ok: true, report };
+}
+// ---------------------------------------------------------------------------
+// Output formatting
+// ---------------------------------------------------------------------------
+export function formatRegressionCheckJson(report) {
+    return JSON.stringify({
+        mode: report.mode,
+        summary: {
+            symbols_analyzed: report.summary.symbolsAnalyzed,
+            truncated: report.summary.truncated,
+            tools_used: report.summary.toolsUsed,
+            degraded_flags: report.summary.degradedFlags,
+        },
+        findings: report.findings.map((f) => ({
+            symbol: f.symbol,
+            file: f.file,
+            language: f.language,
+            definition_location: f.definitionLocation,
+            call_sites: f.callSites ? { count: f.callSites.count, by_file: f.callSites.byFile } : null,
+            broad_mentions: f.broadMentions,
+        })),
+    }, null, 2);
+}
+export function formatRegressionCheckReport(report) {
+    const lines = [
+        `regression-check report (${report.mode} mode)`,
+        "",
+        `Symbols analyzed: ${report.summary.symbolsAnalyzed.length}${report.summary.truncated ? " [TRUNCATED]" : ""}`,
+        `Tools used: ${report.summary.toolsUsed.length > 0 ? report.summary.toolsUsed.join(", ") : "none"}`,
+        "",
+    ];
+    if (report.findings.length === 0) {
+        lines.push("No changed symbols found.");
+    }
+    for (const f of report.findings) {
+        const loc = f.definitionLocation ? `${f.definitionLocation.file}:${f.definitionLocation.line}` : "(unknown location)";
+        lines.push(`${f.file ?? "(explicit)"}:${f.symbol}  (def @ ${loc})`);
+        if (f.callSites) {
+            const byFile = Object.entries(f.callSites.byFile)
+                .map(([file, n]) => `${file}: ${n}`)
+                .join(", ");
+            lines.push(`  real call-sites: ${f.callSites.count}${byFile ? ` (${byFile})` : ""}`);
+        }
+        else {
+            lines.push("  real call-sites: [DEGRADED] ast-grep unavailable or failed");
+        }
+        if (f.broadMentions) {
+            const list = f.broadMentions.length > 0 ? ` (${f.broadMentions.join(", ")})` : "";
+            lines.push(`  broad mentions:  ${f.broadMentions.length} file(s)${list}`);
+        }
+        else {
+            lines.push("  broad mentions:  [DEGRADED] ripgrep unavailable or failed");
+        }
+        lines.push("");
+    }
+    if (report.summary.degradedFlags.length > 0) {
+        lines.push(`[DEGRADED] ${report.summary.degradedFlags.length} issue(s):`);
+        for (const flag of report.summary.degradedFlags)
+            lines.push(`  - ${flag}`);
+    }
+    else {
+        lines.push("No degradation — all tools ran successfully.");
+    }
+    return lines.join("\n");
+}
+/** Parse one `lizard --csv` line, honoring quoted fields (no embedded-quote escaping). */
+function parseLizardCsvLine(line) {
+    const fields = [];
+    let cur = "";
+    let inQuotes = false;
+    for (const ch of line) {
+        if (ch === '"') {
+            inQuotes = !inQuotes;
+            continue;
+        }
+        if (ch === "," && !inQuotes) {
+            fields.push(cur);
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    fields.push(cur);
+    return fields;
+}
+/**
+ * Parse `lizard --csv` output. Columns (lizard's stable CSV schema): nloc, ccn,
+ * token_count, param_count, length, location, file_name, function_name,
+ * long_name, start_line, end_line.
+ */
+export function parseLizardCsv(csv) {
+    const findings = [];
+    for (const rawLine of csv.split("\n")) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const fields = parseLizardCsvLine(line);
+        if (fields.length < 11)
+            continue;
+        const [nloc, ccn, , , , , file, functionName, , startLine, endLine] = fields;
+        const ccnNum = Number(ccn);
+        const nlocNum = Number(nloc);
+        const startLineNum = Number(startLine);
+        const endLineNum = Number(endLine);
+        if (![ccnNum, nlocNum, startLineNum, endLineNum].every(Number.isFinite))
+            continue;
+        findings.push({
+            functionName,
+            file,
+            ccn: ccnNum,
+            nloc: nlocNum,
+            startLine: startLineNum,
+            endLine: endLineNum,
+        });
+    }
+    return findings;
+}
+/**
+ * Per-function cyclomatic-complexity analysis via `lizard` (the single
+ * external dependency, covering Python and TypeScript). Degrades gracefully
+ * (never throws) when lizard is missing or the run fails.
+ */
+export async function analyzeComplexityWithLizard(files, deps) {
+    if (files.length === 0)
+        return { ok: true, findings: [] };
+    const found = await isCommandOnPath(deps, "lizard");
+    if (!found)
+        return { ok: false, error: "lizard not found on PATH" };
+    const result = await deps.runCommand("lizard", ["--csv", ...files], { cwd: deps.cwd });
+    if (result.exitCode !== 0 && result.stdout.trim().length === 0) {
+        return { ok: false, error: redactSecrets(result.stderr.trim() || `lizard exited ${result.exitCode}`) };
+    }
+    return { ok: true, findings: parseLizardCsv(result.stdout) };
+}
+const TEMPORAL_COUPLING_SOURCE_EXT = /\.(py|ts|tsx)$/;
+const MIN_CO_OCCURRENCES = 4;
+const MIN_FILE_FREQUENCY = 5;
+const MIN_COUPLING_DEGREE = 0.5;
+const MAX_FILES_PER_COMMIT = 15;
+const MAX_PAIRS_RETURNED = 12;
+/**
+ * Pure computation half of the temporal-coupling script (verified ~25-line
+ * git-log script from the refactor-reviewer agent, reimplemented in
+ * TypeScript so this module never shells out to python). Mega-commits
+ * (>{@link MAX_FILES_PER_COMMIT} files) and test files are excluded as noise.
+ * When `scopeFiles` is non-empty, only commits touching at least one scoped
+ * file are considered (so callers can scope to e.g. an epic's directories);
+ * all files in a qualifying commit still participate in pairing, so the
+ * result surfaces what tends to change alongside the scoped files.
+ */
+export function computeTemporalCoupling(gitLogOutput, scopeFiles = []) {
+    const scopeSet = scopeFiles.length > 0 ? new Set(scopeFiles) : null;
+    const commits = [];
+    let current = [];
+    for (const line of gitLogOutput.split("\n")) {
+        if (line.startsWith("@")) {
+            if (current.length)
+                commits.push(current);
+            current = [];
+        }
+        else if (line.trim() && TEMPORAL_COUPLING_SOURCE_EXT.test(line.trim())) {
+            current.push(line.trim());
+        }
+    }
+    if (current.length)
+        commits.push(current);
+    const fileFreq = new Map();
+    const pairFreq = new Map();
+    for (const files of commits) {
+        const uniq = Array.from(new Set(files)).filter((f) => !f.toLowerCase().includes("test"));
+        if (uniq.length === 0 || uniq.length > MAX_FILES_PER_COMMIT)
+            continue;
+        if (scopeSet && !uniq.some((f) => scopeSet.has(f)))
+            continue;
+        for (const f of uniq)
+            fileFreq.set(f, (fileFreq.get(f) ?? 0) + 1);
+        const sorted = uniq.slice().sort();
+        for (let i = 0; i < sorted.length; i++) {
+            for (let j = i + 1; j < sorted.length; j++) {
+                const key = `${sorted[i]}${sorted[j]}`;
+                pairFreq.set(key, (pairFreq.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const rows = [];
+    for (const [key, n] of pairFreq) {
+        if (n < MIN_CO_OCCURRENCES)
+            continue;
+        const [a, b] = key.split("");
+        const fa = fileFreq.get(a) ?? 0;
+        const fb = fileFreq.get(b) ?? 0;
+        const deg = n / Math.min(fa, fb);
+        if (deg >= MIN_COUPLING_DEGREE && fa >= MIN_FILE_FREQUENCY && fb >= MIN_FILE_FREQUENCY) {
+            rows.push({ fileA: a, fileB: b, coOccurrences: n, couplingDegree: deg });
+        }
+    }
+    rows.sort((x, y) => y.couplingDegree - x.couplingDegree);
+    return rows.slice(0, MAX_PAIRS_RETURNED);
+}
+/**
+ * Temporal-coupling analysis via `git log` (no JVM, no code-maat/Gitarch
+ * dependency — git and the pure-TS computation above are the only
+ * requirements). `files` optionally scopes the commit set (see
+ * {@link computeTemporalCoupling}); pass `[]` for a whole-repo scan.
+ */
+export async function analyzeTemporalCoupling(files, deps, options = {}) {
+    const commitLimit = options.commitLimit ?? 800;
+    const result = await deps.runCommand("git", ["log", "--no-merges", "-n", String(commitLimit), "--name-only", "--pretty=format:@%H"], { cwd: deps.cwd });
+    if (result.exitCode !== 0) {
+        return { ok: false, error: redactSecrets(result.stderr.trim() || `git log exited ${result.exitCode}`) };
+    }
+    return { ok: true, pairs: computeTemporalCoupling(result.stdout, files) };
+}
+/** Top-N churn-hotspot files seeded for heavy mode (merged with coupling hotspots below). */
+export const HEAVY_CHURN_HOTSPOT_LIMIT = 30;
+/** Documented cap on the candidate-file set passed to heavy mode's complexity/fan-in analysis. */
+export const MAX_HEAVY_HOTSPOTS = 50;
+/** Documented cap on the candidate symbols sent through whole-repo ast-grep fan-in counting. */
+export const MAX_HEAVY_SYMBOLS = MAX_SYMBOLS_PER_RUN;
+const CHURN_LOG_LIMIT = 500;
+/**
+ * Find the highest-churn source files via raw `git log --name-only` output —
+ * the hotspot-seeding half of heavy mode's scope bounding. Uses the same
+ * array-based subprocess boundary (no shell pipes) as the rest of this
+ * module. Fail-open: a failed `git log` returns `ok: false` rather than
+ * throwing, so callers can degrade the signal instead of crashing.
+ */
+export async function analyzeChurnHotspots(deps, limit) {
+    const result = await deps.runCommand("git", ["log", "--no-merges", "-n", String(CHURN_LOG_LIMIT), "--name-only", "--pretty=format:"], { cwd: deps.cwd });
+    if (result.exitCode !== 0) {
+        return { ok: false, error: redactSecrets(result.stderr.trim() || `git log exited ${result.exitCode}`) };
+    }
+    const freq = new Map();
+    for (const rawLine of result.stdout.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || !TEMPORAL_COUPLING_SOURCE_EXT.test(line))
+            continue;
+        freq.set(line, (freq.get(line) ?? 0) + 1);
+    }
+    const sorted = Array.from(freq.entries()).sort((a, b) => b[1] - a[1]);
+    return { ok: true, files: sorted.slice(0, limit).map(([file]) => file) };
+}
+/**
+ * `git log`/`git diff` always report paths relative to the repo root,
+ * regardless of the invoking cwd. Heavy mode threads those paths straight
+ * into `lizard`/`ast-grep` subprocess argv (unlike the lightweight pipeline,
+ * which only pattern-matches), so it must resolve and scan from the repo
+ * root rather than trusting `deps.cwd` — otherwise running from a
+ * subdirectory silently resolves every candidate path to a non-existent
+ * location and findings come back empty. Fails open to the original `deps`
+ * (and thus the prior, cwd-relative behavior) if resolution fails.
+ */
+async function resolveRepoRootDeps(deps) {
+    const result = await deps.runCommand("git", ["rev-parse", "--show-toplevel"], { cwd: deps.cwd });
+    const root = result.exitCode === 0 ? result.stdout.trim() : "";
+    return root ? { ...deps, cwd: root } : deps;
+}
+/**
+ * Whole-repo fragility / blast-radius scan (decision D-4). Seeds candidate
+ * files from churn + temporal-coupling hotspots (deduped, capped at
+ * {@link MAX_HEAVY_HOTSPOTS}), discovers candidate symbols within that set via
+ * the SHARED `lizard` complexity tooling (capped at {@link MAX_HEAVY_SYMBOLS}),
+ * then ranks each by fan-in (ast-grep real call-sites) + coupling partners +
+ * complexity. Takes no diff. Never throws and never hard-fails — a missing
+ * tool degrades the affected signal and ranking proceeds on what remains.
+ */
+export async function runHeavyMode(deps) {
+    const repoDeps = await resolveRepoRootDeps(deps);
+    const degradedFlags = [];
+    const toolsUsed = new Set(["git"]);
+    const churnResult = await analyzeChurnHotspots(repoDeps, HEAVY_CHURN_HOTSPOT_LIMIT);
+    const churnFiles = churnResult.ok ? churnResult.files : [];
+    if (!churnResult.ok) {
+        degradedFlags.push(`git churn analysis failed: ${churnResult.error}`);
+    }
+    const couplingResult = await analyzeTemporalCoupling([], repoDeps);
+    const couplingPartners = new Map();
+    const couplingFiles = [];
+    if (couplingResult.ok) {
+        for (const pair of couplingResult.pairs) {
+            couplingFiles.push(pair.fileA, pair.fileB);
+            couplingPartners.set(pair.fileA, (couplingPartners.get(pair.fileA) ?? 0) + 1);
+            couplingPartners.set(pair.fileB, (couplingPartners.get(pair.fileB) ?? 0) + 1);
+        }
+        toolsUsed.add("git-log-temporal-coupling");
+    }
+    else {
+        degradedFlags.push(`temporal coupling analysis failed: ${couplingResult.error}`);
+    }
+    const candidateFilesAll = Array.from(new Set([...churnFiles, ...couplingFiles]));
+    const fileCapApplied = candidateFilesAll.length > MAX_HEAVY_HOTSPOTS;
+    const candidateFiles = fileCapApplied ? candidateFilesAll.slice(0, MAX_HEAVY_HOTSPOTS) : candidateFilesAll;
+    const complexityResult = await analyzeComplexityWithLizard(candidateFiles, repoDeps);
+    let candidateSymbols;
+    if (complexityResult.ok) {
+        if (candidateFiles.length > 0)
+            toolsUsed.add("lizard");
+        candidateSymbols = complexityResult.findings.map((f) => ({
+            file: f.file,
+            line: f.startLine,
+            symbol: f.functionName,
+            complexityScore: f.ccn,
+        }));
+    }
+    else {
+        degradedFlags.push(`lizard complexity analysis failed: ${complexityResult.error}`);
+        degradedFlags.push("ast-grep fan-in skipped for these hotspots — no symbol-discovery fallback exists without lizard");
+        candidateSymbols = candidateFiles.map((file) => ({ file, line: 1, symbol: null, complexityScore: null }));
+    }
+    const symbolCapApplied = candidateSymbols.length > MAX_HEAVY_SYMBOLS;
+    if (symbolCapApplied) {
+        candidateSymbols = candidateSymbols
+            .slice()
+            .sort((a, b) => (b.complexityScore ?? 0) - (a.complexityScore ?? 0))
+            .slice(0, MAX_HEAVY_SYMBOLS);
+    }
+    const astGrepBinary = await resolveFirstCommandOnPath(repoDeps, AST_GREP_CANDIDATES);
+    if (!astGrepBinary && candidateSymbols.some((s) => s.symbol)) {
+        degradedFlags.push("ast-grep (or sg) not found on PATH — fan-in analysis skipped for all symbols.");
+    }
+    const findings = [];
+    for (const candidate of candidateSymbols) {
+        let fanInCount = null;
+        if (astGrepBinary && candidate.symbol) {
+            const language = languageForFile(candidate.file);
+            const result = await findCallSites(repoDeps, astGrepBinary, candidate.symbol, language);
+            if (result.ok) {
+                fanInCount = result.count;
+                toolsUsed.add("ast-grep");
+            }
+            else {
+                degradedFlags.push(`ast-grep call-site search failed for '${candidate.symbol}': ${result.error}`);
+            }
+        }
+        const couplingPartnerCount = couplingPartners.get(candidate.file) ?? 0;
+        const fragilityRank = (fanInCount ?? 0) * 2 + couplingPartnerCount * 3 + (candidate.complexityScore ?? 0);
+        findings.push({
+            location: { file: candidate.file, line: candidate.line },
+            signals: {
+                fan_in_count: fanInCount,
+                coupling_partners: couplingPartnerCount,
+                complexity_score: candidate.complexityScore,
+            },
+            fragility_rank: fragilityRank,
+        });
+    }
+    findings.sort((a, b) => b.fragility_rank - a.fragility_rank);
+    return {
+        mode: "heavy",
+        summary: {
+            hotspots_scanned: candidateFiles.length,
+            cap_applied: fileCapApplied || symbolCapApplied,
+            tools_used: Array.from(toolsUsed),
+            degraded_flags: degradedFlags,
+        },
+        findings,
+    };
+}
+// ---------------------------------------------------------------------------
+// Heavy mode — output formatting
+// ---------------------------------------------------------------------------
+export function formatHeavyReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function formatHeavyReportText(report) {
+    const lines = [
+        "regression-check report (heavy mode)",
+        "",
+        `Hotspots scanned: ${report.summary.hotspots_scanned}${report.summary.cap_applied ? " [CAPPED]" : ""}`,
+        `Tools used: ${report.summary.tools_used.length > 0 ? report.summary.tools_used.join(", ") : "none"}`,
+        "",
+    ];
+    if (report.findings.length === 0) {
+        lines.push("No fragility findings.");
+    }
+    for (const f of report.findings) {
+        lines.push(`${f.location.file}:${f.location.line}  fragility_rank=${f.fragility_rank}`);
+        const fanIn = f.signals.fan_in_count === null ? "[DEGRADED]" : String(f.signals.fan_in_count);
+        const complexity = f.signals.complexity_score === null ? "[DEGRADED]" : String(f.signals.complexity_score);
+        lines.push(`  fan-in: ${fanIn}  coupling partners: ${f.signals.coupling_partners}  complexity: ${complexity}`);
+    }
+    lines.push("");
+    if (report.summary.degraded_flags.length > 0) {
+        lines.push(`[DEGRADED] ${report.summary.degraded_flags.length} issue(s):`);
+        for (const flag of report.summary.degraded_flags)
+            lines.push(`  - ${flag}`);
+    }
+    else {
+        lines.push("No degradation — all tools ran successfully.");
+    }
+    return lines.join("\n");
+}
+/**
+ * CLI entry for the `regression-check` subcommand. Returns a process exit
+ * code. Help returns 0; parser errors return 1; an unreadable diff returns 1;
+ * otherwise it always returns 0 (degraded findings are reported, not failed).
+ */
+export async function runRegressionCheckCli(argv, overrides = {}) {
+    const log = overrides.log ?? ((m) => console.log(m));
+    const errorLog = overrides.errorLog ?? ((m) => console.error(m));
+    const parsed = parseRegressionCheckArgs(argv);
+    if (parsed.status === "help") {
+        log(parsed.usage);
+        return 0;
+    }
+    if (parsed.status === "error") {
+        errorLog(`Error: ${parsed.message}`);
+        errorLog("");
+        errorLog(getRegressionCheckUsage());
+        return 1;
+    }
+    const deps = overrides.deps ?? createDefaultStartTicketsDeps();
+    const { options } = parsed;
+    if (options.mode === "heavy") {
+        const report = await runHeavyMode(deps);
+        log(options.json ? formatHeavyReportJson(report) : formatHeavyReportText(report));
+        return 0;
+    }
+    const result = await runLightweightRegressionCheck(deps, options);
+    if (!result.ok) {
+        errorLog(`Error: ${result.error}`);
+        return 1;
+    }
+    log(options.json ? formatRegressionCheckJson(result.report) : formatRegressionCheckReport(result.report));
+    return 0;
+}