iterate-plugin 2.7.3 → 2.8.1

package/src/meta-review.ts

@@ -15,6 +15,8 @@
  */
 
 import type { ReviewFinding, ReviewReport } from './types.ts'
+import type { EvidenceAudit } from './evidence.ts'
+import type { CoverageResult } from './review-scope.ts'
 import { sortFindings } from './review.ts'
 
 /** A single defect found while auditing a review report. */
@@ -51,6 +53,9 @@ export interface FinalReviewReport {
   source: ReviewReport
   /** Deterministic audit of the source report's internal consistency. */
   metaReview: MetaReviewResult
+  /** Prompt-informative scope coverage result (absent when coverage validation
+   *  is disabled or there is nothing to compare). Never flips the verdict. */
+  coverage?: CoverageResult | null
   /** Rolled-up summary that mirrors the source but adds the verdict. */
   summary: {
     totalFindings: number
@@ -68,6 +73,12 @@ export interface FinalReviewReport {
 /** 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.
  *
@@ -278,15 +289,97 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
 /**
  * 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: ReviewReport): FinalReviewReport {
+export function buildFinalReviewReport(
+  report: ReviewReport,
+  opts: {
+    evidence?: EvidenceAudit | null
+    coverage?: CoverageResult | null
+  } = {},
+): FinalReviewReport {
   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: FinalReviewVerdict = 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/src/method-scope.ts

@@ -0,0 +1,201 @@
+/**
+ * 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.
+ */
+
+/** A method/function signature found in source text. */
+export interface MethodSignature {
+  name: string
+  /** 1-based line of the signature. */
+  line: number
+}
+
+/** Approximate span a signature "owns": signature line → before the next. */
+export interface MethodSpan {
+  name: string
+  startLine: number
+  endLine: number
+}
+
+/** One changed region (unified-diff hunk, line numbers are 1-based). */
+export interface ChangedRegion {
+  oldStart: number
+  oldLines: number
+  newStart: number
+  newLines: number
+}
+
+/** 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: Array<{ kind: string; re: RegExp; nameIndex: number }> = [
+  // 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: string): MethodSignature[] {
+  const lines = text.split('\n')
+  const out: MethodSignature[] = []
+  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: string): number {
+  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: string): MethodSpan[] {
+  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: number, floor: number): number {
+    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: MethodSpan[] = []
+  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: number, spanEnd: number, regionStart: number, regionEnd: number): boolean {
+  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: string,
+  after: string,
+  hunks: ChangedRegion[],
+): number {
+  if (hunks.length === 0) return 0
+  const beforeSpans = collectMethodSpans(before)
+  const afterSpans = collectMethodSpans(after)
+  const touched = new Set<string>()
+  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/src/review-scope.ts

@@ -0,0 +1,203 @@
+/**
+ * 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'
+
+export interface CoverageResult {
+  assigned: string[]
+  read: string[]
+  covered: string[]
+  uncovered: string[]
+  ratio: number
+}
+
+/** 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: string): string {
+  const cleaned = path.replace(/\\/g, SEP)
+  const parts: string[] = []
+  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: string): boolean {
+  const dot = path.lastIndexOf('.')
+  if (dot < 0) return false
+  return SOURCE_EXTENSIONS.has(path.slice(dot).toLowerCase())
+}
+
+function isIgnoredDir(name: string): boolean {
+  return IGNORED_DIRS.has(name)
+}
+
+/** Collect the sorted relative-path inventory for a review scope. */
+export function collectScopeFiles(
+  root: string,
+  opts: { scope: 'full' | 'changed-only'; changedFiles?: string[] },
+): string[] {
+  if (opts.scope === 'changed-only') return collectChanged(opts.changedFiles ?? [])
+  return collectFull(root)
+}
+
+function collectChanged(changedFiles: string[]): string[] {
+  const out = new Set<string>()
+  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: string): string[] {
+  // Deterministic recursive walk built on Node's fs; a code reviewer never
+  // anchors findings to lock files, images, or vendored builds.
+  const out: string[] = []
+  const walk = (dir: string): void => {
+    let entries: import('node:fs').Dirent[]
+    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: string[], perChunk?: number): string[][] {
+  const size = perChunk === undefined || perChunk < 1 ? DEFAULT_SCOPE_CHUNK_SIZE : perChunk
+  const ordered = [...files].sort()
+  const chunks: string[][] = []
+  let current: string[] = []
+  let lastDir: string | undefined
+  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: string[],
+  readFiles?: string[] | null,
+): CoverageResult {
+  const readNorm = new Set<string>()
+  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): p is string => typeof p === 'string'))].sort(),
+    covered,
+    uncovered,
+    ratio,
+  }
+}
+
+/** Serialize a coverage result for the tool-layer JSON wire shape. */
+export function coverageToDict(c: CoverageResult): Record<string, unknown> {
+  return {
+    assigned: c.assigned,
+    read: c.read,
+    covered: c.covered,
+    uncovered: c.uncovered,
+    ratio: c.ratio,
+    met: c.ratio >= COVERAGE_TARGET,
+  }
+}