iterate-plugin 2.8.0 → 2.8.2

package/dist/config-loader.js

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

package/dist/evidence.js

@@ -30,7 +30,10 @@ export const WHOLE_FILE_LINE = 0;
 export function countLines(text) {
     if (text === '')
         return 0;
-    const parts = text.split(/\r\n|\r|\n/);
+    // 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] === '')
@@ -76,9 +79,9 @@ export function verifyFinding(root, input, opts = {}) {
             error: 'file_not_found',
         };
     }
-    let text;
+    let raw;
     try {
-        text = readFileSync(resolved, 'utf-8');
+        raw = readFileSync(resolved);
     }
     catch {
         return {
@@ -90,6 +93,21 @@ export function verifyFinding(root, input, opts = {}) {
             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 {

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.
  *
@@ -163,9 +168,34 @@ export function metaReviewReport(report) {
  * 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, 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;
@@ -174,13 +204,29 @@ export function buildFinalReviewReport(report, opts = {}) {
                 if (violation.error === undefined)
                     continue;
                 const detail = violation.error === 'line_out_of_range'
-                    ? `${violation.line} is beyond this file's ${violation.lineTotal} lines`
+                    ? 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: `Finding references non-existent code: ${violation.file}` +
-                        (violation.line ? `:${violation.line}` : ''),
+                    summary,
                     detail: detail + '. Review results must anchor to real, read code.',
                 });
             }
@@ -194,6 +240,7 @@ export function buildFinalReviewReport(report, opts = {}) {
         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;
+}

package/dist/review-scope.js

@@ -0,0 +1,187 @@
+/**
+ * File-inventory collection, chunking, and coverage scoring for review scope.
+ *
+ * Mirrors `harness/iterate-harness/.../review_scope.py`. The iterate review
+ * loop must force each reviewer subagent to actually open EVERY file in the
+ * scope it is responsible for (not silently skip or assume files). This
+ * module supplies the deterministic building blocks:
+ *
+ * - `collectScopeFiles`: produce the sorted relative-path inventory for a
+ *   review scope (changed-only delta, or a full walk filtered to source files
+ *   and stripped of dependency/build/vendor dirs).
+ * - `chunkFiles`: split a large inventory into stable batches so `full`
+ *   reviews stay bounded; consecutive files from the same directory are kept
+ *   together to avoid splitting a module's review across two reviewers.
+ * - `computeCoverage`: compare a reviewer's self-reported `readFiles` against
+ *   the inventory it was assigned, returning a coverage ratio plus the list of
+ *   files that were not opened. Consumed by meta-review as a
+ *   *prompt-informative* metric (never a hard gate).
+ *
+ * Pure math (chunkFiles / computeCoverage) has no I/O so it unit-tests
+ * cleanly; collectScopeFiles walks the filesystem.
+ */
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Relative-scope sentinel for whole-module findings. */
+export const WHOLE_FILE_LINE = 0;
+/** Source extensions a full-scope walk includes. */
+const SOURCE_EXTENSIONS = new Set([
+    '.py', '.pyi', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.go', '.java', '.rs', '.c', '.h', '.cc', '.cpp', '.cs',
+    '.swift', '.kt', '.scala', '.rb', '.php', '.sh', '.bash', '.zsh',
+    '.sql', '.html', '.htm', '.css', '.scss', '.vue', '.svelte',
+]);
+/** Directory names always excluded from a full-scope walk. */
+const IGNORED_DIRS = new Set([
+    '.git', '.hg', '.svn', 'node_modules', '.venv', 'venv', 'env',
+    '__pycache__', '.cache', '.pytest_cache', '.mypy_cache', 'dist',
+    'build', 'out', '.next', '.nuxt', 'coverage', '.tox', '.idea',
+    '.vscode', 'target', '.release', '.dist_tmp',
+]);
+/** Default chunk size for a `full` scope review (files per batch). */
+export const DEFAULT_SCOPE_CHUNK_SIZE = 25;
+/** Coverage ratio at/above which a scope is fully covered. */
+export const COVERAGE_TARGET = 0.95;
+const SEP = '/';
+/**
+ * Canonicalize separators + dot-segments. Leading `..` PATH segments are
+ * PRESERVED (mirrors Python `os.path.normpath`, which never resolves beyond
+ * the root), so callers can still detect path-escaping (`..`) after
+ * normalization — a full `..`-driven traversal must not be silently folded
+ * into a bare filename.
+ */
+function normalizePath(path) {
+    const cleaned = path.replace(/\\/g, SEP);
+    const parts = [];
+    for (const part of cleaned.split(SEP)) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (parts.length > 0)
+                parts.pop();
+            else
+                parts.push(part); // no root segment to pop — keep the leading '..'
+            continue;
+        }
+        parts.push(part);
+    }
+    return parts.join(SEP);
+}
+function sourceExt(path) {
+    const dot = path.lastIndexOf('.');
+    if (dot < 0)
+        return false;
+    return SOURCE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+function isIgnoredDir(name) {
+    return IGNORED_DIRS.has(name);
+}
+/** Collect the sorted relative-path inventory for a review scope. */
+export function collectScopeFiles(root, opts) {
+    if (opts.scope === 'changed-only')
+        return collectChanged(opts.changedFiles ?? []);
+    return collectFull(root);
+}
+function collectChanged(changedFiles) {
+    const out = new Set();
+    for (const rel of changedFiles) {
+        if (typeof rel !== 'string' || !rel.trim())
+            continue;
+        if (rel === String(WHOLE_FILE_LINE))
+            continue;
+        const cleaned = normalizePath(rel);
+        if (cleaned.startsWith('..'))
+            continue;
+        if (!sourceExt(cleaned))
+            continue;
+        out.add(cleaned);
+    }
+    return [...out].sort();
+}
+function collectFull(root) {
+    // Deterministic recursive walk built on Node's fs; a code reviewer never
+    // anchors findings to lock files, images, or vendored builds.
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!isIgnoredDir(entry.name))
+                    walk(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!sourceExt(entry.name))
+                continue;
+            const rel = abs.startsWith(root + SEP) ? abs.slice(root.length + 1) : abs;
+            out.push(rel.split(SEP).join(SEP));
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+/** Split `files` into stable batches, keeping directory runs together. */
+export function chunkFiles(files, perChunk) {
+    const size = perChunk === undefined || perChunk < 1 ? DEFAULT_SCOPE_CHUNK_SIZE : perChunk;
+    const ordered = [...files].sort();
+    const chunks = [];
+    let current = [];
+    let lastDir;
+    for (const rel of ordered) {
+        const parent = rel.includes(SEP) ? rel.slice(0, rel.lastIndexOf(SEP)) : '.';
+        if (current.length > 0 && lastDir !== undefined && parent !== lastDir) {
+            chunks.push(current);
+            current = [];
+            lastDir = undefined;
+        }
+        current.push(rel);
+        lastDir = parent;
+        if (current.length >= size) {
+            chunks.push(current);
+            current = [];
+            lastDir = undefined;
+        }
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/** Score self-reported reads against the assigned inventory. */
+export function computeCoverage(assigned, readFiles) {
+    const readNorm = new Set();
+    for (const p of readFiles ?? []) {
+        if (typeof p === 'string' && p)
+            readNorm.add(normalizePath(p));
+    }
+    const assignedSorted = [...assigned].sort();
+    const covered = assignedSorted.filter((rel) => readNorm.has(normalizePath(rel)));
+    const uncovered = assignedSorted.filter((rel) => !readNorm.has(normalizePath(rel)));
+    const rawRatio = assignedSorted.length === 0 ? 1 : covered.length / assignedSorted.length;
+    const ratio = Math.round(rawRatio * 1000) / 1000;
+    return {
+        assigned: assignedSorted,
+        read: [...new Set((readFiles ?? []).filter((p) => typeof p === 'string'))].sort(),
+        covered,
+        uncovered,
+        ratio,
+    };
+}
+/** Serialize a coverage result for the tool-layer JSON wire shape. */
+export function coverageToDict(c) {
+    return {
+        assigned: c.assigned,
+        read: c.read,
+        covered: c.covered,
+        uncovered: c.uncovered,
+        ratio: c.ratio,
+        met: c.ratio >= COVERAGE_TARGET,
+    };
+}