iterate-plugin 2.7.3 → 2.8.1

package/README.md

@@ -229,6 +229,19 @@ All tests pass:
 - **212 unit tests green**, type-check clean
 - Coverage: dedupe, filter, sort, multi-round convergence, meta-review audit, path safety, timeout clamping, config read/write + rollback, triage merge, diff computation, checkpoint validation, fix registry, history read + filter, prune cleanup report + dry-run semantics, UI pure functions (select-all key, runtime status guide).
 
+## ⚠️ Disclaimer
+
+This project is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.
+
+**Automated code review and fixing carries inherent risk.** All changes produced in normal mode are generated by AI models and may introduce bugs, regressions, or unintended behavior. Before merging, you should:
+
+- Review every diff before applying it to your main branch or pushing.
+- Make sure your project is under git control and can be rolled back (`git restore`, revert, or restore from backup).
+- Run your project's own test suite and build checks after each round of fixes.
+- Never run this on secrets, credentials, `.env`, or files that must not be modified — configure `protected_paths` accordingly.
+
+Users are solely responsible for the code that is generated, modified, or committed as a result of using this project. By using it, you acknowledge that neither the maintainers nor contributors are liable for any loss, damage, or legal consequences arising from its use.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -229,6 +229,19 @@ npm test
 - **212 个单元测试全绿**，类型检查通过
 - 覆盖：去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数（select-all 键、运行时状态指引）等
 
+## ⚠️ 免责声明
+
+本项目按「现状」（AS IS）提供，不附带任何明示或暗示的担保，包括但不限于对适销性、特定用途适用性及不侵权性的担保。
+
+**自动化的代码审查与修复存在固有风险。** normal 模式下产生的改动均由 AI 模型生成，可能引入缺陷、回归或非预期行为。在合并改动前，你应当：
+
+- 在应用到主分支或推送前，逐条 review 每一处 diff。
+- 确保项目处于 git 版本控制之下，并可随时回滚（`git restore`、revert 或从备份恢复）。
+- 在每轮修复后运行项目自身的测试与构建检查。
+- 切勿在密钥、凭证、`.env` 或任何不允许修改的文件上运行本项目；请在配置中设置 `protected_paths` 予以保护。
+
+使用者需为本项目使用过程中所产生、修改或提交的代码负全部责任。使用本项目即表示你同意：维护者与贡献者不对因使用本项目而导致的任何损失、损害或法律后果承担责任。
+
 ## License
 
 MIT

package/dist/config-loader.js

@@ -48,7 +48,12 @@ export function defaultConfig() {
             auto_merge: false,
         },
         validation: { command_whitelist: [], commands: {} },
-        reviewer: { output_schema_validation: true },
+        reviewer: {
+            output_schema_validation: true,
+            evidence_validation: true,
+            coverage_validation: true,
+            scope_chunk_size: 25,
+        },
     };
 }
 /**

package/dist/evidence.js

@@ -0,0 +1,161 @@
+/**
+ * Deterministic code-evidence verification for review findings.
+ *
+ * Mirror of `iterate_harness/iterate/evidence.py` for the iterate-plugin.
+ *
+ * The iterate review loop requires that reviewer subagent findings ANCHOR to
+ * real code instead of speculating. This module enforces it:
+ *
+ * - a finding's `file` must resolve to an existing file under the project root
+ *   (traversal-safe), otherwise evidence is poisoned (`file_not_found`);
+ * - a finding with an explicit line must reference a line that actually exists
+ *   in that file (`line_out_of_range`);
+ * - a whole-file finding (line 0 / undefined) must still reference an existing
+ *   file, so even structural findings cannot point at nothing;
+ * - `readVerified` is a best-effort, NON-gating hint: the plugin's reviewers are
+ *   subagents whose reads are not aggregated here, so it is only set when a
+ *   read set is explicitly provided and never fails the audit.
+ *
+ * Gate rule (user preference): ANY localizable finding with poisoned evidence
+ * flips the whole audit to `passed: false`, so the meta-review forces revision.
+ *
+ * The pure math (`countLines`, `verifyLineBounds`) is separated from the
+ * filesystem half (`verifyFinding`) to stay unit-testable without touching disk.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+/** Sentinel for whole-file findings (line 0 or omitted means the whole file). */
+export const WHOLE_FILE_LINE = 0;
+/** Number of physical lines in `text`. A trailing newline does not add a line. */
+export function countLines(text) {
+    if (text === '')
+        return 0;
+    // Mirrors Python `str.splitlines()`: split on every line separator, not just
+    // \r\n|\r|\n — otherwise line counts diverge from the harness on files
+    // containing \v \f \x1c-\x1e \x85 \u2028 \u2029.
+    const parts = text.split(/\r\n|[\n\r\v\f\x1c\x1d\x1e\x85\u2028\u2029]/);
+    // A trailing newline leaves an empty final element that is NOT a line
+    // (mirrors Python `str.splitlines()` used by the harness).
+    if (parts[parts.length - 1] === '')
+        return parts.length - 1;
+    return parts.length;
+}
+/** Resolve `root/rel` and reject any path escaping `root` (returns null). */
+export function resolveWithin(root, rel) {
+    const resolved = resolve(root, rel);
+    const rootResolved = resolve(root);
+    if (resolved === rootResolved)
+        return resolved;
+    const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep;
+    if (!resolved.startsWith(prefix))
+        return null;
+    return resolved;
+}
+/**
+ * Pure check that `line` (if anchored) exists in `text`.
+ * Whole-file findings (undefined/0) are always bounds-valid.
+ */
+export function verifyLineBounds(line, text) {
+    const lineTotal = countLines(text);
+    if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
+        return { inBounds: true, lineTotal };
+    }
+    if (line < 1)
+        return { inBounds: false, lineTotal };
+    return { inBounds: line <= lineTotal, lineTotal };
+}
+/** Verify a single finding's location against the real filesystem. */
+export function verifyFinding(root, input, opts = {}) {
+    const relFile = input.file ?? '';
+    const line = typeof input.line === 'number' ? input.line : null;
+    const resolved = resolveWithin(root, relFile);
+    if (resolved === null || !existsSync(resolved)) {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(resolved);
+    }
+    catch {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    // A file is not line-addressable if it contains a NUL byte (binary payload).
+    // Anchored line numbers on a binary file cannot be trusted, so treat them the
+    // same as an out-of-range line rather than credulously accepting them
+    // (mirrors the harness `evidence.py` NUL check).
+    if (raw.includes(0)) {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'line_out_of_range',
+        };
+    }
+    const text = raw.toString('utf-8');
+    const { inBounds, lineTotal } = verifyLineBounds(line, text);
+    if (!inBounds) {
+        return {
+            file: relFile,
+            line,
+            lineTotal,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'line_out_of_range',
+        };
+    }
+    const outcome = {
+        file: relFile,
+        line,
+        lineTotal,
+        resolvedPath: resolved,
+        verified: true,
+    };
+    if (opts.readSet !== undefined) {
+        outcome.readVerified = opts.readSet.has(resolved);
+    }
+    return outcome;
+}
+/** Attest every finding in a list. */
+export function verifyFindings(root, findings, opts = {}) {
+    const results = findings.map((f) => verifyFinding(root, f, opts));
+    return { checked: results.length, results };
+}
+/** `passed` is true only when no real existence failure exists (read is a hint). */
+export function evidencePassed(audit) {
+    return audit.results.every((r) => r.error === undefined);
+}
+/** Violating (non-grounded) results. */
+export function evidenceViolations(audit) {
+    return audit.results.filter((r) => r.error !== undefined);
+}
+/** Serialize an audit for tool payloads (pure). */
+export function evidenceToPlain(audit) {
+    const computable = audit.results.filter((r) => r.readVerified !== undefined);
+    const readRatio = computable.length === 0
+        ? null
+        : Number((computable.filter((r) => r.readVerified === true).length / computable.length).toFixed(3));
+    return {
+        checked: audit.checked,
+        passed: evidencePassed(audit),
+        violations: audit.results
+            .filter((r) => r.error !== undefined)
+            .map((r) => ({ file: r.file, line: r.line, lineTotal: r.lineTotal, verified: r.verified, error: r.error })),
+        readVerifiedRatio: readRatio,
+    };
+}

package/dist/git-scope.js

@@ -0,0 +1,101 @@
+/**
+ * src/git-scope.ts — resolve the `changed-only` review scope for the iterate
+ * workflow.
+ *
+ * When `iterate.config.yaml` sets `review.scope: changed-only`, reviewers must
+ * only examine files that changed against `git.target_branch`. This module
+ * resolves that file set deterministically:
+ *
+ *   1. run `git diff --name-only <target_branch> --` in the project root
+ *      (working-tree diff vs the target branch — captures both staged and
+ *      unstaged changes, which is what an iterate round produces);
+ *   2. keep only entries that resolve to an existing file under the project
+ *      root (path-traversal-safe — a hostile diff line must never leak a path
+ *      outside the root);
+ *   3. when the configured scope is `changed-only` but ZERO files changed, the
+ *      plan auto-falls back to `full` (mirrors SKILL.md: "无改动文件时自动
+ *      fallback 为 full").
+ *
+ * The pure math (`parseChangedFiles`, `filterExistingFiles`, `decideScope`) is
+ * separated from the process call (`runGit`) so it is unit-testable without a
+ * git repo.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Parse `git diff --name-only` stdout into a list of relative paths.
+ * Pure: strips blank lines, trims whitespace, drops quotes (git can quote
+ * paths with special characters).
+ */
+export function parseChangedFiles(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trim().replace(/^"|"$/g, ''))
+        .filter((line) => line.length > 0);
+}
+/**
+ * Keep only entries that resolve to an existing regular file under `root`.
+ * Traversal-safe: rejects absolute paths and any relative path that would
+ * escape `root` via `..` (resolved against the root before stat).
+ */
+export function filterExistingFiles(root, files) {
+    const out = [];
+    for (const rel of files) {
+        if (rel.startsWith('/') || rel.includes('\0'))
+            continue;
+        const candidate = join(root, rel);
+        if (!candidate.startsWith(root + '/') && candidate !== root)
+            continue;
+        try {
+            if (existsSync(candidate) && statSync(candidate).isFile())
+                out.push(rel);
+        }
+        catch {
+            // Unreadable entry (e.g. a broken symlink) is not a valid review target.
+            continue;
+        }
+    }
+    return out;
+}
+/**
+ * Decide the effective scope from the changed-file set.
+ * changed-only + zero files → fall back to full (SKILL.md auto-fallback).
+ * Pure and deterministic.
+ */
+export function decideScope(changedFiles) {
+    const hasChanges = changedFiles.length > 0;
+    return {
+        scope: hasChanges ? 'changed-only' : 'full',
+        fallbackToFull: !hasChanges,
+    };
+}
+/**
+ * Run a git command in `cwd` and return stdout/stderr/exit code.
+ * Uses execFile (no shell), so a model-controlled branch name can never be
+ * interpreted as shell syntax.
+ */
+export function runGit(args, cwd) {
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd, timeout: 30_000, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PAGER: 'cat' } }, (error, stdout, stderr) => {
+            const exitCode = error ? (typeof error.code === 'number' ? error.code : 1) : 0;
+            resolve({ ok: exitCode === 0, stdout: stdout ?? '', stderr: stderr ?? '', exitCode });
+        });
+    });
+}
+/**
+ * Resolve the changed-file set for a project.
+ * Any git failure (not a repo, missing target branch, etc.) degrades to a
+ * `full`-scope result with `error` set — the reviewer must never crash the
+ * plan because git is unavailable.
+ */
+export async function resolveChangedFiles(root, targetBranch) {
+    const { ok, stdout, stderr } = await runGit(['diff', '--name-only', targetBranch, '--'], root);
+    if (!ok) {
+        const reason = stderr.trim() || `git diff --name-only ${targetBranch} failed`;
+        return { scope: 'full', changedFiles: [], fallbackToFull: true, error: reason };
+    }
+    const existing = filterExistingFiles(root, parseChangedFiles(stdout));
+    const decided = decideScope(existing);
+    return { scope: decided.scope, changedFiles: existing, fallbackToFull: decided.fallbackToFull };
+}

package/dist/meta-review.js

@@ -16,6 +16,11 @@
 import { sortFindings } from "./review.js";
 /** Number of distinct consistency checks performed by `metaReviewReport`. */
 export const META_REVIEW_CHECKS = 6;
+/**
+ * How many uncovered scope files are listed in a COVERAGE_GAP hint before the
+ * remainder is folded into a "+N more" suffix.
+ */
+export const COVERAGE_LIST_TRUNCATE = 10;
 /**
  * Audit a ReviewReport for internal consistency.
  *
@@ -157,15 +162,85 @@ export function metaReviewReport(report) {
 /**
  * Build the final review report: pair the source report with its meta-review
  * verdict and a rolled-up summary. Pure and deterministic.
+ *
+ * `evidence` (an EvidenceAudit produced against the real repo) is the hard
+ * code-evidence gate: every finding whose file/line does not resolve to
+ * existing code is emitted as a critical EVIDENCE_VIOLATION and flips the
+ * verdict to `needs_revision`. The audit itself reads the filesystem; this
+ * function only folds the (pure, precomputed) result in.
+ *
+ * `coverage` (a CoverageResult) is a *prompt-informative* check: a scope whose
+ * reviewer never reported reading a meaningful share of its assigned files
+ * surfaces a medium COVERAGE_GAP hint (it does NOT flip the verdict — the
+ * subagent's actual tool-call trace is not aggregated here, so coverage can
+ * only advise, never adjudicate).
  */
-export function buildFinalReviewReport(report) {
+export function buildFinalReviewReport(report, opts = {}) {
     const meta = metaReviewReport(report);
+    const coverage = opts.coverage ?? null;
+    if (coverage !== null) {
+        meta.checksRun += 1;
+        if (coverage.uncovered.length > 0) {
+            const listed = coverage.uncovered.slice(0, COVERAGE_LIST_TRUNCATE).join(', ');
+            const extra = coverage.uncovered.length - COVERAGE_LIST_TRUNCATE > 0
+                ? ` (+${coverage.uncovered.length - COVERAGE_LIST_TRUNCATE} more)`
+                : '';
+            meta.issues.push({
+                code: 'COVERAGE_GAP',
+                severity: 'medium',
+                summary: `${coverage.uncovered.length} of ${coverage.assigned.length} scope files ` +
+                    'were not (self-)reported as read',
+                detail: `The reviewer reported reading ${coverage.covered.length}/${coverage.assigned.length} ` +
+                    `assigned files. Uncovered: ${listed}${extra}. Best-effort coverage hint — ` +
+                    'verify these files were actually opened.',
+            });
+        }
+    }
+    const evidence = opts.evidence ?? null;
+    if (evidence !== null) {
+        meta.checksRun += 1;
+        if (evidence.results.some((r) => r.error !== undefined)) {
+            for (const violation of evidence.results) {
+                if (violation.error === undefined)
+                    continue;
+                const detail = violation.error === 'line_out_of_range'
+                    ? violation.lineTotal !== undefined && violation.lineTotal !== null
+                        ? `${violation.line} is beyond this file's ${violation.lineTotal} lines`
+                        : `${violation.file} is a binary/unreadable file not line-addressable`
+                    : `${violation.file} does not exist at all (verifiable read required)`;
+                let roundHint = '';
+                if (report && violation.file) {
+                    // Try to attribute the poisoned finding to the round that first
+                    // surfaced it (best-effort; report rounds carry it).
+                    for (const r of report.rounds ?? []) {
+                        const matched = (r.findings ?? []).some((fnd) => fnd.file === violation.file && fnd.line === violation.line);
+                        if (matched) {
+                            roundHint = ` (round ${r.round})`;
+                            break;
+                        }
+                    }
+                }
+                const summary = `Finding references non-existent code: ${violation.file}` +
+                    (violation.line ? `:${violation.line}` : '') +
+                    roundHint;
+                meta.issues.push({
+                    code: 'EVIDENCE_VIOLATION',
+                    severity: 'critical',
+                    summary,
+                    detail: detail + '. Review results must anchor to real, read code.',
+                });
+            }
+            meta.passed = false;
+            meta.verdict = 'revise';
+        }
+    }
     const summary = report?.summary ?? {};
     const verdict = meta.passed ? 'approved' : 'needs_revision';
     return {
         verdict,
         source: report,
         metaReview: meta,
+        coverage: coverage, // preserve the coverage result (or null) on the final report
         summary: {
             totalFindings: Number(summary.totalFindings ?? 0),
             critical: Number(summary.critical ?? 0),

package/dist/method-scope.js

@@ -0,0 +1,173 @@
+/**
+ * src/method-scope.ts — deterministic "touched method" detection for the
+ * atomic-fix gate.
+ *
+ * `config.atomic.max_adjacent_methods` caps how many ADJACENT methods a single
+ * atomic fix may touch (SKILL.md: 改动在单个函数/方法内，或最多 N 个相邻的同类方法).
+ * The fixer supplies only the new full-file content, so this module rebuilds a
+ * best-effort method map (signature line → containing span) and counts the
+ * distinct methods a diff's changed regions intersect. Purely textual and
+ * deterministic — no parsing library — so it stays unit-testable.
+ *
+ * Heuristic (documented, not hidden):
+ *  - A "method" is a line matching a conservative, language-agnostic signature
+ *    pattern (JS/TS `function` + arrow assignments + class methods, Python
+ *    `def`, Swift `func`, Go `func`, Rust `fn`, Ruby `def`, PHP `function`).
+ *  - A method's span is approximated as `signatureLine .. nextSignatureLine-1`
+ *    (no brace matching). Changes between two signatures are attributed to the
+ *    earlier method — exactly the "adjacent methods" granularity this
+ *    threshold governs.
+ *  - A diff hunk counts a method as touched when the REMOVED block intersects
+ *    a `before` span or the ADDED block intersects an `after` span. Pure
+ *    insertions/deletions are attributed through the side that actually
+ *    changed, so a single-method edit counts 1 and a deleted method does not
+ *    drag in its neighbour.
+ *  - If no method is detected around a change, `countTouchedMethods` returns 0,
+ *    so the `max_lines` gate remains the only constraint for non-method code.
+ */
+/** Language keywords that never denote a method name. */
+const RESERVED_WORDS = new Set([
+    'if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'else',
+    'do', 'try', 'case', 'new', 'typeof', 'instanceof', 'in', 'of', 'class',
+    'interface', 'type', 'enum', 'import', 'export', 'default', 'extends',
+    'implements', 'where', 'async', 'await', 'yield', 'throw', 'delete',
+    'let', 'const', 'var', 'public', 'private', 'protected', 'static',
+]);
+/**
+ * Test-framework callables that look like method declarations but are plain
+ * calls (e.g. `it('…', () => { … })`). Excluding them keeps a test-only change
+ * from falsely tripping the adjacent-method gate.
+ */
+const CALLABLE_NOISE = new Set([
+    'it', 'test', 'describe', 'expect', 'beforeEach', 'afterEach',
+    'beforeAll', 'afterAll', 'suite', 'specify',
+]);
+/** Signature patterns per language family. Each capture is the method name. */
+const SIGNATURE_PATTERNS = [
+    // JS/TS function declarations
+    { kind: 'ts', re: /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/, nameIndex: 1 },
+    // JS/TS arrow-function assignments (const f = (...) => …)
+    { kind: 'ts-arrow', re: /^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/, nameIndex: 1 },
+    // Indented class methods (JS/TS/Java/Kotlin/C# style `name(…) {`)
+    { kind: 'ts-method', re: /^\s{2,}(?:(?:public|private|protected|static|async|readonly)\s+)*(?:get\s+|set\s+)?([A-Za-z_$][\w$]*)\s*\([^;{}]*\)\s*\{/, nameIndex: 1 },
+    // Python def (module-level and class methods)
+    { kind: 'py', re: /^\s*(?:async\s+)?def\s+([A-Za-z_][\w]*)\s*\(/, nameIndex: 1 },
+    // Swift func
+    { kind: 'swift', re: /^\s*(?:(?:override|public|private|internal|fileprivate|open|static|class)\s+)*func\s+([A-Za-z_][\w]*)\s*\(/, nameIndex: 1 },
+    // Go func (plain + receiver)
+    { kind: 'go', re: /^\s*func\s+(?:\([^)]*\)\s+)?([A-Za-z_][\w]*)\s*\(/, nameIndex: 1 },
+    // Rust fn
+    { kind: 'rust', re: /^\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_][\w]*)\s*\(/, nameIndex: 1 },
+    // Ruby def (def name / def self.name / def Class.name)
+    { kind: 'ruby', re: /^\s*def\s+(?:(?:self|[A-Z][\w]*)\s*\.\s*)?([A-Za-z_][\w]*[!?]?)(?:\s|\(|$)/, nameIndex: 1 },
+    // PHP function
+    { kind: 'php', re: /^\s*(?:(?:public|private|protected|static)\s+)*function\s+([A-Za-z_][\w]*)\s*\(/, nameIndex: 1 },
+];
+/**
+ * Collect method/function signatures from `text`.
+ * Returns a sorted array of `{ name, line }` (1-based line numbers).
+ */
+export function collectMethodSignatures(text) {
+    const lines = text.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const line = i + 1;
+        for (const p of SIGNATURE_PATTERNS) {
+            const m = p.re.exec(raw);
+            if (!m)
+                continue;
+            const name = m[p.nameIndex];
+            if (!name || RESERVED_WORDS.has(name) || CALLABLE_NOISE.has(name))
+                continue;
+            // Avoid two patterns claiming the same line (e.g. TS method + arrow).
+            if (out.some((s) => s.line === line && s.name === name))
+                break;
+            out.push({ name, line });
+            break;
+        }
+    }
+    return out;
+}
+/** Number of physical lines in `text` (a trailing newline does not add a line). */
+export function countTextLines(text) {
+    if (text === '')
+        return 0;
+    const parts = text.split('\n');
+    return parts[parts.length - 1] === '' ? parts.length - 1 : parts.length;
+}
+/**
+ * Build the approximate span owned by each signature: from its own line up to
+ * (but excluding) the next signature line, trimmed of trailing blank lines so
+ * a blank separator between two methods belongs to neither. The last method's
+ * span runs to the final non-blank line of the file.
+ */
+export function collectMethodSpans(text) {
+    const signatures = collectMethodSignatures(text);
+    if (signatures.length === 0)
+        return [];
+    const lines = text.split('\n');
+    const lineCount = countTextLines(text);
+    /** Last non-blank line at or before `candidate`. */
+    function trimBlank(endCandidate, floor) {
+        let end = endCandidate;
+        while (end > floor) {
+            const raw = lines[end - 1];
+            if (raw === undefined || raw.trim().length === 0)
+                end--;
+            else
+                break;
+        }
+        return end;
+    }
+    const spans = [];
+    for (let i = 0; i < signatures.length; i++) {
+        const cur = signatures[i];
+        const next = signatures[i + 1];
+        const rawEnd = next ? next.line - 1 : lineCount;
+        spans.push({ name: cur.name, startLine: cur.line, endLine: trimBlank(rawEnd, cur.line) });
+    }
+    return spans;
+}
+/** True when `[regionStart, regionEnd]` intersects `[spanStart, spanEnd]`. */
+function intersects(spanStart, spanEnd, regionStart, regionEnd) {
+    return spanStart <= regionEnd && spanEnd >= regionStart;
+}
+/**
+ * Count the distinct methods a set of diff hunks touches.
+ *
+ * Semantics:
+ *  - REMOVED lines (oldLines > 0) are attributed against the `before` method
+ *    spans; PURE insertions (oldLines === 0) skip `before` so a deletion never
+ *    drags in the next surviving method.
+ *  - ADDED lines (newLines > 0) are attributed against the `after` spans;
+ *    PURE deletions skip `after` so an insertion never mis-attributes to the
+ *    following method.
+ *  - Methods touched by both sides are counted once (keyed name@startLine).
+ */
+export function countTouchedMethods(before, after, hunks) {
+    if (hunks.length === 0)
+        return 0;
+    const beforeSpans = collectMethodSpans(before);
+    const afterSpans = collectMethodSpans(after);
+    const touched = new Set();
+    for (const h of hunks) {
+        if (h.oldLines > 0) {
+            const oldEnd = h.oldStart + h.oldLines - 1;
+            for (const s of beforeSpans) {
+                if (intersects(s.startLine, s.endLine, h.oldStart, oldEnd)) {
+                    touched.add(`${s.name}@${s.startLine}`);
+                }
+            }
+        }
+        if (h.newLines > 0) {
+            const newEnd = h.newStart + h.newLines - 1;
+            for (const s of afterSpans) {
+                if (intersects(s.startLine, s.endLine, h.newStart, newEnd)) {
+                    touched.add(`${s.name}@${s.startLine}`);
+                }
+            }
+        }
+    }
+    return touched.size;
+}