iterate-plugin 2.8.0 → 2.8.2

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,
+  }
+}

package/src/review.ts

@@ -24,6 +24,7 @@ import type {
   ReviewReport,
   ReviewRound,
 } from './types.ts'
+import { DEFAULT_SCOPE_CHUNK_SIZE, chunkFiles } from './review-scope.ts'
 
 /** Severity ordering: lower rank = more severe. */
 export const SEVERITY_RANK: Record<ReviewFinding['severity'], number> = {
@@ -312,9 +313,201 @@ export function findingsSchema(): Record<string, unknown> {
           ],
         },
       },
+      readFiles: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'Every file you actually opened with read_file while reviewing your assigned scope. Used to audit coverage; files you never opened count as un-reviewed.',
+      },
     },
-    required: ['findings'],
+    required: ['findings', 'readFiles'],
+  }
+}
+
+// ─── Output schema validation ──────────────────────────────────────────────
+//
+// `config.reviewer.output_schema_validation` (default true) turns on a
+// deterministic schema gate at the `aggregate` boundary: reviewer subagent
+// outputs are parsed as JSON by the orchestrator, but models sometimes return
+// malformed findings (missing fields, wrong types, out-of-range severity).
+// Before any finding reaches the deterministic core (dedupe/sort/report) —
+// which would crash on e.g. a missing `summary` — we validate every entry
+// against the same shape `findingsSchema()` describes and surface the issues
+// so the workflow can retry that round (≤2 times) with a strict-JSON nudge.
+// Schema-invalid findings are dropped from the report; the workflow never
+// forwards them into fixes.
+
+/** Fields every finding object MUST carry (mirrors findingsSchema().required). */
+export const REQUIRED_FINDING_FIELDS = [
+  'dimension',
+  'file',
+  'severity',
+  'summary',
+  'failure_scenario',
+  'suggested_fix',
+  'is_atomic',
+] as const
+
+/** Allowed severity values (mirrors the schema enum). */
+export const SEVERITY_VALUES = ['critical', 'high', 'medium', 'low'] as const
+
+/** String-typed finding fields (type check only, presence handled by REQUIRED). */
+const STRING_FINDING_FIELDS = [
+  'dimension',
+  'file',
+  'summary',
+  'failure_scenario',
+  'suggested_fix',
+] as const
+
+/** One schema violation for a single finding entry. */
+export interface FindingSchemaIssue {
+  /** Index into the findings array; -1 when the whole `findings` is malformed. */
+  index: number
+  /** Field path, e.g. "findings[2].severity". */
+  field: string
+  /** Human-readable reason. */
+  message: string
+}
+
+/**
+ * Validate an arbitrary parsed value against the findings schema shape.
+ * Accepts the `{findings: [...]}` wrapper OR a bare findings array, so callers
+ * can validate either the raw reviewer output object or a round's findings.
+ * Pure and deterministic — never touches the filesystem.
+ */
+export function validateFindingsSchema(input: unknown): FindingSchemaIssue[] {
+  const raw = (input as { findings?: unknown } | null)?.findings ?? input
+  if (!Array.isArray(raw)) {
+    return [
+      {
+        index: -1,
+        field: 'findings',
+        message: 'expected a JSON array of finding objects',
+      },
+    ]
   }
+
+  const issues: FindingSchemaIssue[] = []
+  for (let i = 0; i < raw.length; i++) {
+    const item = raw[i]
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      issues.push({
+        index: i,
+        field: `findings[${i}]`,
+        message: 'expected a finding object',
+      })
+      continue
+    }
+    const f = item as Record<string, unknown>
+
+    for (const key of REQUIRED_FINDING_FIELDS) {
+      if (f[key] === undefined || f[key] === null) {
+        issues.push({
+          index: i,
+          field: `findings[${i}].${key}`,
+          message: `required field "${key}" is missing`,
+        })
+      }
+    }
+    for (const key of STRING_FINDING_FIELDS) {
+      if (f[key] !== undefined && f[key] !== null && typeof f[key] !== 'string') {
+        issues.push({
+          index: i,
+          field: `findings[${i}].${key}`,
+          message: `"${key}" must be a string`,
+        })
+      }
+    }
+    if (
+      f.severity !== undefined &&
+      f.severity !== null &&
+      !SEVERITY_VALUES.includes(f.severity as (typeof SEVERITY_VALUES)[number])
+    ) {
+      issues.push({
+        index: i,
+        field: `findings[${i}].severity`,
+        message: `severity must be one of: ${SEVERITY_VALUES.join(', ')}`,
+      })
+    }
+    if (
+      f.is_atomic !== undefined &&
+      f.is_atomic !== null &&
+      typeof f.is_atomic !== 'boolean'
+    ) {
+      issues.push({
+        index: i,
+        field: `findings[${i}].is_atomic`,
+        message: 'is_atomic must be a boolean',
+      })
+    }
+    if (
+      f.line !== undefined &&
+      f.line !== null &&
+      (typeof f.line !== 'number' || !Number.isInteger(f.line) || f.line < 0)
+    ) {
+      issues.push({
+        index: i,
+        field: `findings[${i}].line`,
+        message: 'line must be a non-negative integer (0 = whole-file)',
+      })
+    }
+  }
+  return issues
+}
+
+/** Per-round schema validation outcome. */
+export interface RoundSchemaValidation {
+  round: number
+  /** True when every finding in the round conforms to the schema. */
+  valid: boolean
+  issues: FindingSchemaIssue[]
+}
+
+/**
+ * Validate every round's findings against the findings schema.
+ * Round order matches the input `rounds` array.
+ */
+export function validateRoundsSchema(rounds: ReviewRound[]): RoundSchemaValidation[] {
+  return rounds.map((r) => {
+    const issues = validateFindingsSchema(r.findings)
+    return { round: r.round, valid: issues.length === 0, issues }
+  })
+}
+
+/**
+ * Drop schema-invalid findings before they reach the deterministic core.
+ *
+ * - With a non-null `schemaValidation` (validation enabled): drop every finding
+ *   flagged by a schema issue; a round-level issue (index -1) empties the round.
+ * - With `schemaValidation === null` (validation disabled): still drop entries
+ *   that are not plain objects, which would crash `findingKey`/dedupe.
+ *
+ * Round order and round numbers are preserved so downstream convergence math
+ * keeps working on the sanitized stream.
+ */
+export function sanitizeRounds(
+  rounds: ReviewRound[],
+  schemaValidation: RoundSchemaValidation[] | null,
+): ReviewRound[] {
+  return rounds.map((r, i) => {
+    if (schemaValidation) {
+      const issues = schemaValidation[i]?.issues ?? []
+      if (issues.some((iss) => iss.index === -1)) return { round: r.round, findings: [] }
+      const bad = new Set(issues.map((iss) => iss.index))
+      return {
+        round: r.round,
+        findings: r.findings.filter((_, fi) => !bad.has(fi)),
+      }
+    }
+    return {
+      round: r.round,
+      findings: r.findings.filter(
+        (f): f is ReviewFinding =>
+          Boolean(f) && typeof f === 'object' && !Array.isArray(f),
+      ),
+    }
+  })
 }
 
 /**
@@ -331,6 +524,21 @@ export function reviewerTaskPrompt(input: {
   outputLanguage: string
   /** Atomic fix threshold from config.atomic. */
   maxLines: number
+  /**
+   * Files to review under `changed-only` scope (relative paths, resolved via
+   * git diff against `git.target_branch`). Omitted/empty for `full` scope or
+   * when no changes were detected (auto-fallback to full).
+   */
+  changedFiles?: string[]
+  /**
+   * The exact file inventory this reviewer is RESPONSIBLE for. When provided,
+   * a mandatory COVERAGE RULE is injected: the reviewer must actually open
+   * every listed file with read_file and return a `readFiles` array of what it
+   * opened (the enforcement half of "每个子 agent 必须逐文件读取自己负责的审查
+   * 范围"). Used for the chunked full-scope case; takes precedence over
+   * `changedFiles`.
+   */
+  scopeFiles?: string[]
 }): string {
   const parts: string[] = []
   parts.push(
@@ -338,6 +546,29 @@ export function reviewerTaskPrompt(input: {
     `Goal: ${input.goal}`,
     `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`,
   )
+  if (input.scopeFiles && input.scopeFiles.length > 0) {
+    parts.push(
+      'COVERAGE RULE (mandatory): below is the exact file inventory you are ' +
+        'assigned to review. You MUST open EVERY file in this inventory with ' +
+        'the read_file tool before judging it — do not skip, skim-declare, or ' +
+        'assume any file without reading it. Files you did not actually open ' +
+        'are considered un-reviewed and will lower your coverage score. ' +
+        'Return a `readFiles` array listing every file you actually opened.',
+      'Assigned file inventory:',
+      input.scopeFiles.map((p) => `- ${p}`).join('\n'),
+    )
+  } else if (
+    input.scope === 'changed-only' &&
+    input.changedFiles &&
+    input.changedFiles.length > 0
+  ) {
+    parts.push(
+      'Changed files to review (review ONLY these files; they are the diff against ' +
+        'the target branch). You MUST open EVERY listed file with read_file ' +
+        'before judging it — never skip or assume a file:',
+      input.changedFiles.map((p) => `- ${p}`).join('\n'),
+    )
+  }
   if (input.mode === 'dry-run') {
     parts.push(
       'MODE: dry-run / pure review. You MUST NOT modify, create, or delete ANY file. Read-only analysis only.',
@@ -359,7 +590,7 @@ export function reviewerTaskPrompt(input: {
       'poisoned evidence. Anchor every finding to real code.',
   )
   parts.push(
-    `Return a JSON object: {"findings": [...]}.`,
+    `Return a JSON object: {"findings": [...], "readFiles": [...]}.`,
     `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
       'line (REQUIRED positive integer — the exact line you READ for an ' +
       'anchored, line-targeted issue; use 0 for whole-file/module-level ' +
@@ -382,6 +613,20 @@ export function buildReviewPlan(input: {
   mode: 'normal' | 'dry-run'
   maxReviewRounds: number
   knownIntentional?: KnownIntentional[]
+  /**
+   * Files changed against `git.target_branch` (relative paths), resolved by the
+   * tool when `review.scope` is `changed-only`. When the configured scope is
+   * `changed-only` but no changes are detected, the plan auto-falls back to
+   * `full` (mirrors SKILL.md: "无改动文件时自动 fallback 为 full").
+   */
+  changedFiles?: string[]
+  /**
+   * Pre-collected source inventory for a `full`-scope review. When provided,
+   * it is split into `config.reviewer.scope_chunk_size` batches and every
+   * (dimension × batch) pair gets its own reviewer task owning a bounded,
+   * complete inventory it must open file-by-file.
+   */
+  scopeFiles?: string[]
 }): {
   mode: 'normal' | 'dry-run'
   goal: string
@@ -389,33 +634,73 @@ export function buildReviewPlan(input: {
   dimensions: { id: string; reviewerPrompt: string; findingsSchema: Record<string, unknown> }[]
   maxReviewRounds: number
   knownIntentional: KnownIntentional[]
+  /** Files reviewed under `changed-only` scope (empty for `full` / fallback). */
+  changedFiles: string[]
+  /** True when scope was `changed-only` but no changes were found. */
+  fallbackToFull: boolean
 } {
   // Defensive reads: a malformed config (e.g. `dimensions` as a non-array, or
   // `review`/`atomic` missing) must degrade to sane defaults instead of
   // throwing an uncaught TypeError inside the tool's `execute`.
   const language = input.config.language === 'zh' ? 'Chinese (中文)' : 'English'
   const goal = input.config.goal ?? ''
-  const scope = input.config.review?.scope ?? 'full'
+  const configuredScope = input.config.review?.scope ?? 'full'
   const dimensions = Array.isArray(input.config.dimensions) ? input.config.dimensions : []
   const maxLines = input.config.atomic?.max_lines ?? 20
+  const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : []
+  // changed-only with zero detected changes → auto-fallback to full scope.
+  const effectiveChangedOnly = configuredScope === 'changed-only' && changedFiles.length > 0
+  const scope: 'full' | 'changed-only' = effectiveChangedOnly ? 'changed-only' : 'full'
+  const fallbackToFull = configuredScope === 'changed-only' && changedFiles.length === 0
+
+  // Scope batching (coverage enforcement): changed-only is a single batch
+  // owning the full delta; full scope splits the collected inventory into
+  // per-chunk reviewer tasks when scopeFiles is supplied.
+  const chunkSize = Number(input.config.reviewer?.scope_chunk_size)
+  const perChunk = Number.isFinite(chunkSize) && chunkSize > 0 ? chunkSize : DEFAULT_SCOPE_CHUNK_SIZE
+  let batches: (string[] | undefined)[]
+  if (effectiveChangedOnly) {
+    batches = [undefined]
+  } else if (input.scopeFiles && input.scopeFiles.length > 0) {
+    batches = chunkFiles(input.scopeFiles, perChunk).filter((b) => b.length > 0)
+  } else {
+    batches = [undefined]
+  }
+
+  const dimensionTasks: {
+    id: string
+    reviewerPrompt: string
+    findingsSchema: Record<string, unknown>
+  }[] = []
+  for (const d of dimensions) {
+    batches.forEach((batch, index) => {
+      const dimensionId = batches.length === 1 ? d : `${d}#${index + 1}`
+      dimensionTasks.push({
+        id: dimensionId,
+        reviewerPrompt: reviewerTaskPrompt({
+          dimension: d,
+          goal,
+          scope,
+          mode: input.mode,
+          alreadyKnown: [],
+          outputLanguage: language,
+          maxLines,
+          changedFiles: effectiveChangedOnly ? changedFiles : undefined,
+          scopeFiles: batch,
+        }),
+        findingsSchema: findingsSchema(),
+      })
+    })
+  }
+
   return {
     mode: input.mode,
     goal,
     scope,
-    dimensions: dimensions.map((d) => ({
-      id: d,
-      reviewerPrompt: reviewerTaskPrompt({
-        dimension: d,
-        goal,
-        scope,
-        mode: input.mode,
-        alreadyKnown: [],
-        outputLanguage: language,
-        maxLines,
-      }),
-      findingsSchema: findingsSchema(),
-    })),
+    dimensions: dimensionTasks,
     maxReviewRounds: input.maxReviewRounds,
     knownIntentional: input.knownIntentional ?? [],
+    changedFiles: effectiveChangedOnly ? changedFiles : [],
+    fallbackToFull,
   }
 }