iterate-plugin 2.8.0 → 2.8.1

package/src/client/index.ts

@@ -492,17 +492,6 @@ function setThemeEnabled(enabled: boolean): void {
 
 // ─── Components (React.createElement trees) ──────────────────────────────────
 
-/** Obtain a session snapshot defensively from the slot props. */
-function sessionSnapshot(props: SlotProps) {
-  let session: unknown = null
-  const useSession = props && typeof props.useSession === 'function' ? props.useSession as () => unknown : null
-  if (useSession) {
-    try { session = useSession() } catch (err) { log('useSession failed', err) }
-  }
-  if (!session && props && props.session) session = props.session
-  return session
-}
-
 /** Find the latest report inside a session snapshot (normalized). */
 function latestReport(session: unknown): ReviewReport | null {
   if (!session) return null
@@ -529,7 +518,15 @@ function TrendChart({ points }: { points: Array<{ round: number; count: number }
 /** Dashboard: live convergence strip above the composer. */
 function ConvergenceDashboard(props: SlotProps) {
   const [pulseKey, setPulseKey] = React.useState(0)
-  const report = latestReport(sessionSnapshot(props))
+  // useSession is a SnapshotSelectorHook — it requires a selector fn (identity
+  // returns the whole snapshot). Call it unconditionally at the top level to
+  // satisfy the React hooks contract; the owner share (props.session) is the
+  // fallback when the hook is absent.
+  const useSession = props && typeof props.useSession === 'function'
+    ? props.useSession as (sel: (s: unknown) => unknown) => unknown
+    : null
+  const session = useSession ? useSession((s: unknown) => s) : (props && props.session ? props.session : null)
+  const report = latestReport(session)
 
   React.useEffect(() => {
     if (!report) return

package/src/config-loader.ts

@@ -49,7 +49,12 @@ export function defaultConfig(): IterateConfig {
       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/src/evidence.ts

@@ -59,7 +59,10 @@ interface Locatable {
 /** Number of physical lines in `text`. A trailing newline does not add a line. */
 export function countLines(text: string): number {
   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] === '') return parts.length - 1
@@ -113,9 +116,9 @@ export function verifyFinding(
     }
   }
 
-  let text: string
+  let raw: Buffer
   try {
-    text = readFileSync(resolved, 'utf-8')
+    raw = readFileSync(resolved)
   } catch {
     return {
       file: relFile,
@@ -127,6 +130,22 @@ export function verifyFinding(
     }
   }
 
+  // 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/src/git-scope.ts

@@ -0,0 +1,129 @@
+/**
+ * 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'
+
+/** A resolved changed-only scope result. */
+export interface GitScopeResult {
+  /** Effective scope for the review plan. */
+  scope: 'full' | 'changed-only'
+  /** Files to review (relative paths). Empty for `full` / fallback. */
+  changedFiles: string[]
+  /** True when the configured scope was changed-only but no changes were found. */
+  fallbackToFull: boolean
+  /** Non-empty when git resolution itself failed (scope falls back to full). */
+  error?: string
+}
+
+/**
+ * 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: string): string[] {
+  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: string, files: string[]): string[] {
+  const out: string[] = []
+  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: string[]): {
+  scope: 'full' | 'changed-only'
+  fallbackToFull: boolean
+} {
+  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: string[],
+  cwd: string,
+): Promise<{ ok: boolean; stdout: string; stderr: string; exitCode: number }> {
+  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: string,
+  targetBranch: string,
+): Promise<GitScopeResult> {
+  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/src/meta-review.ts

@@ -16,6 +16,7 @@
 
 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. */
@@ -52,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
@@ -69,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.
  *
@@ -285,12 +295,43 @@ export function metaReviewReport(report: ReviewReport): MetaReviewResult {
  * 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,
-  opts: { evidence?: EvidenceAudit | null } = {},
+  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
@@ -299,14 +340,32 @@ export function buildFinalReviewReport(
         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.',
         })
       }
@@ -320,6 +379,7 @@ export function buildFinalReviewReport(
     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
+}