iterate-plugin 2.3.6

package/src/meta-review.ts

@@ -0,0 +1,289 @@
+/**
+ * Meta-review engine: review a ReviewReport and produce a final review report.
+ *
+ * This is the "纯反复审查" closing step: after the review loop converges on
+ * zero new findings, we don't just trust the aggregated report — we audit the
+ * report itself for internal consistency (counts, severity buckets, dimension
+ * sums, sort order, convergence math). The result is a deterministic
+ * `MetaReviewResult` plus a `FinalReviewReport` that pairs the source report
+ * with a verdict.
+ *
+ * Like `review.ts`, this module contains NO I/O and NO agent spawning — it is
+ * the pure, testable core. The workflow script (skill-prompt.ts) orchestrates
+ * the actual subagent-driven meta-review critique; all deterministic math
+ * lives here.
+ */
+
+import type { ReviewFinding, ReviewReport } from './types.ts'
+import { sortFindings } from './review.ts'
+
+/** A single defect found while auditing a review report. */
+export interface MetaReviewIssue {
+  /** Stable machine-readable code, e.g. 'SEVERITY_SUM_MISMATCH'. */
+  code: string
+  severity: 'critical' | 'high' | 'medium' | 'low'
+  summary: string
+  detail: string
+}
+
+/** Deterministic audit result for a ReviewReport. */
+export interface MetaReviewResult {
+  /** Whether the report passed every consistency check (no issues). */
+  passed: boolean
+  /** Human-readable verdict: 'approved' when passed, else 'revise'. */
+  verdict: 'approved' | 'revise'
+  /** Number of consistency checks performed. */
+  checksRun: number
+  /** Defects found while auditing the report. Empty when passed. */
+  issues: MetaReviewIssue[]
+}
+
+/** Verdict for the overall final report. */
+export type FinalReviewVerdict =
+  | 'approved'
+  | 'needs_revision'
+
+/** The final deliverable: the audited report plus its meta-review. */
+export interface FinalReviewReport {
+  /** Verdict of the meta-review over the source report. */
+  verdict: FinalReviewVerdict
+  /** The (unchanged) source review report being audited. */
+  source: ReviewReport
+  /** Deterministic audit of the source report's internal consistency. */
+  metaReview: MetaReviewResult
+  /** Rolled-up summary that mirrors the source but adds the verdict. */
+  summary: {
+    totalFindings: number
+    critical: number
+    high: number
+    medium: number
+    low: number
+    converged: boolean
+    totalRounds: number
+    reportIssues: number
+    verdict: FinalReviewVerdict
+  }
+}
+
+/** Number of distinct consistency checks performed by `metaReviewReport`. */
+export const META_REVIEW_CHECKS = 6
+
+/**
+ * Audit a ReviewReport for internal consistency.
+ *
+ * Checks (all deterministic, no I/O):
+ *  1. COUNT_MATCH: summary.totalFindings === findings.length
+ *  2. SEVERITY_SUM: summary severity buckets (critical+high+medium+low) total
+ *     to summary.totalFindings AND match the actual per-severity counts.
+ *  3. DIMENSION_SUM: summary.byDimension values sum to totalFindings and every
+ *     finding's dimension is present in report.dimensions.
+ *  4. SORT_ORDER: findings are severity-sorted (most severe first).
+ *  5. CONVERGENCE: findingsByRound sums to totalFindings and the `converged`
+ *     flag is consistent with the last round's new-finding count.
+ *  6. ROUND_SHAPE: every round has a positive round number; no round is
+ *     missing from the sequence. A round with zero findings is only flagged
+ *     when it is NOT the last round — an empty FINAL round means the review
+ *     converged (the last pass found nothing new), which is the expected,
+ *     successful termination of a dry-run, not a defect.
+ *
+ * Returns a MetaReviewResult; `passed` is true only when all checks pass.
+ */
+export function metaReviewReport(report: ReviewReport): MetaReviewResult {
+  const issues: MetaReviewIssue[] = []
+  const add = (
+    code: string,
+    severity: MetaReviewIssue['severity'],
+    summary: string,
+    detail: string,
+  ): void => {
+    issues.push({ code, severity, summary, detail })
+  }
+
+  // Guard: a null/undefined report is a hard failure, not a crash.
+  if (!report || typeof report !== 'object') {
+    return {
+      passed: false,
+      verdict: 'revise',
+      checksRun: META_REVIEW_CHECKS,
+      issues: [
+        {
+          code: 'REPORT_UNDEFINED',
+          severity: 'critical',
+          summary: 'Report is missing or not an object',
+          detail: 'metaReviewReport received no valid ReviewReport to audit.',
+        },
+      ],
+    }
+  }
+
+  const findings = Array.isArray(report.findings) ? report.findings : []
+  const summary = report.summary ?? {}
+  const total = Number(summary.totalFindings ?? 0)
+  const dimensions = Array.isArray(report.dimensions) ? report.dimensions : []
+
+  // 1. COUNT_MATCH
+  if (total !== findings.length) {
+    add(
+      'COUNT_MATCH',
+      'high',
+      `summary.totalFindings (${total}) does not match findings.length (${findings.length})`,
+      `The report claims ${total} findings but lists ${findings.length}.`,
+    )
+  }
+
+  // 2. SEVERITY_SUM
+  const sevCounts = { critical: 0, high: 0, medium: 0, low: 0 } as Record<
+    ReviewFinding['severity'],
+    number
+  >
+  for (const f of findings) {
+    const s = f?.severity as ReviewFinding['severity'] | undefined
+    if (s && s in sevCounts) sevCounts[s]++
+  }
+  const bucketSum = sevCounts.critical + sevCounts.high + sevCounts.medium + sevCounts.low
+  const declaredSeveritySum =
+    Number(summary.critical ?? 0) +
+    Number(summary.high ?? 0) +
+    Number(summary.medium ?? 0) +
+    Number(summary.low ?? 0)
+  if (declaredSeveritySum !== total || bucketSum !== total) {
+    add(
+      'SEVERITY_SUM',
+      'high',
+      'Severity bucket counts are inconsistent with totalFindings',
+      `declared buckets sum to ${declaredSeveritySum}, actual buckets sum to ${bucketSum}, ` +
+        `but totalFindings is ${total}.`,
+    )
+  }
+
+  // 3. DIMENSION_SUM
+  const byDim = summary.byDimension ?? {}
+  let dimSum = 0
+  for (const v of Object.values(byDim)) dimSum += Number(v) || 0
+  if (dimSum !== total) {
+    add(
+      'DIMENSION_SUM',
+      'high',
+      'byDimension counts do not sum to totalFindings',
+      `byDimension sums to ${dimSum}, but totalFindings is ${total}.`,
+    )
+  }
+  const invalidDim = findings.find((f) => !dimensions.includes(f?.dimension))
+  if (invalidDim) {
+    add(
+      'DIMENSION_UNKNOWN',
+      'medium',
+      `Finding references unknown dimension "${invalidDim.dimension}"`,
+      `dimension "${invalidDim.dimension}" is not in report.dimensions ` +
+        `(${dimensions.join(', ') || 'none'}).`,
+    )
+  }
+
+  // 4. SORT_ORDER
+  const sorted = sortFindings(findings)
+  const isSorted = sorted.every((f, i) => f === findings[i])
+  if (!isSorted) {
+    add(
+      'SORT_ORDER',
+      'low',
+      'Findings are not severity-sorted',
+      'findings should be ordered most-severe first (critical > high > medium > low).',
+    )
+  }
+
+  // 5. CONVERGENCE
+  const findingsByRound = Array.isArray(report.convergence?.findingsByRound)
+    ? report.convergence.findingsByRound
+    : []
+  const convSum = findingsByRound.reduce((a, b) => a + Number(b) || 0, 0)
+  if (convSum !== total) {
+    add(
+      'CONVERGENCE_SUM',
+      'high',
+      'convergence.findingsByRound does not sum to totalFindings',
+      `findingsByRound ${JSON.stringify(findingsByRound)} sums to ${convSum}, ` +
+        `but totalFindings is ${total}.`,
+    )
+  }
+  const lastRoundNew = findingsByRound.length > 0 ? Number(findingsByRound[findingsByRound.length - 1]) : null
+  const expectedConverged = lastRoundNew === 0
+  if (report.convergence?.converged !== expectedConverged) {
+    add(
+      'CONVERGENCE_FLAG',
+      'medium',
+      'convergence.converged flag is inconsistent with the last round',
+      `last round reported ${lastRoundNew} new findings, so converged should be ` +
+        `${expectedConverged}, but it is ${report.convergence?.converged}.`,
+    )
+  }
+
+  // 6. ROUND_SHAPE
+  const rounds = Array.isArray(report.rounds) ? report.rounds : []
+  const seenRounds = new Set<number>()
+  for (const [index, r] of rounds.entries()) {
+    if (!r || typeof r.round !== 'number' || r.round < 1) {
+      add(
+        'ROUND_NUMBER',
+        'medium',
+        'A round has a missing or non-positive round number',
+        `round: ${JSON.stringify(r)}`,
+      )
+      continue
+    }
+    seenRounds.add(r.round)
+    const isLastRound = index === rounds.length - 1
+    if (!Array.isArray(r.findings) || (r.findings.length === 0 && !isLastRound)) {
+      add(
+        'ROUND_EMPTY',
+        'low',
+        `Round ${r.round} has no findings`,
+        'A recorded round should contain at least one finding — except a final converged round, ' +
+          'which finding nothing new is the expected success signal.',
+      )
+    }
+  }
+  for (let i = 1; i <= rounds.length; i++) {
+    if (!seenRounds.has(i)) {
+      add(
+        'ROUND_GAP',
+        'medium',
+        `Round ${i} is missing from the round sequence`,
+        `rounds present: ${[...seenRounds].sort((a, b) => a - b).join(', ') || 'none'}.`,
+      )
+    }
+  }
+
+  const passed = issues.length === 0
+  return {
+    passed,
+    verdict: passed ? 'approved' : 'revise',
+    checksRun: META_REVIEW_CHECKS,
+    issues,
+  }
+}
+
+/**
+ * Build the final review report: pair the source report with its meta-review
+ * verdict and a rolled-up summary. Pure and deterministic.
+ */
+export function buildFinalReviewReport(report: ReviewReport): FinalReviewReport {
+  const meta = metaReviewReport(report)
+  const summary = report?.summary ?? {}
+  const verdict: FinalReviewVerdict = meta.passed ? 'approved' : 'needs_revision'
+  return {
+    verdict,
+    source: report,
+    metaReview: meta,
+    summary: {
+      totalFindings: Number(summary.totalFindings ?? 0),
+      critical: Number(summary.critical ?? 0),
+      high: Number(summary.high ?? 0),
+      medium: Number(summary.medium ?? 0),
+      low: Number(summary.low ?? 0),
+      converged: Boolean(report?.convergence?.converged),
+      totalRounds: Number(report?.convergence?.totalRounds ?? 0),
+      reportIssues: meta.issues.length,
+      verdict,
+    },
+  }
+}

package/src/review.ts

@@ -0,0 +1,360 @@
+/**
+ * Deterministic review engine for the iterate review loop (dry-run and normal).
+ *
+ * This module contains NO I/O and NO agent spawning — it is the pure,
+ * testable core of the multi-round convergence loop:
+ *
+ *   1. dedupe findings across rounds (file + dimension + normalized summary)
+ *   2. filter out `known_intentional` entries from personalization
+ *   3. sort by severity (critical > high > medium > low)
+ *   4. compute multi-round convergence stats ("纯反复审查" 收敛统计)
+ *   5. assemble the ReviewReport
+ *   6. build reviewer task prompts + structured-output schema for subagents
+ *
+ * The workflow script (see skill-prompt.ts) does the orchestration:
+ * spawn parallel reviewers, feed back already-known findings each round,
+ * and stop when a round yields 0 new findings or the round cap is reached.
+ * All deterministic math lives here so it can be unit-tested.
+ */
+
+import type {
+  IterateConfig,
+  KnownIntentional,
+  ReviewFinding,
+  ReviewReport,
+  ReviewRound,
+} from './types.ts'
+
+/** Severity ordering: lower rank = more severe. */
+export const SEVERITY_RANK: Record<ReviewFinding['severity'], number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+}
+
+/** Sort findings by severity (most severe first), then by file path. */
+export function sortFindings(findings: ReviewFinding[]): ReviewFinding[] {
+  return [...findings].sort((a, b) => {
+    const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+    if (bySeverity !== 0) return bySeverity
+    const byFile = a.file.localeCompare(b.file)
+    if (byFile !== 0) return byFile
+    return (a.line ?? 0) - (b.line ?? 0)
+  })
+}
+
+/** Normalize a summary so near-identical duplicates collapse to one key. */
+export function normalizeSummary(summary: string): string {
+  return summary
+    .trim()
+    .toLowerCase()
+    .replace(/[\s\n\t]+/g, ' ')
+}
+
+/** Dedupe key: same file + same dimension + similar summary. */
+export function findingKey(f: ReviewFinding): string {
+  return `${f.file}|${f.dimension}|${normalizeSummary(f.summary)}`
+}
+
+/**
+ * Remove duplicate findings within a list.
+ * Keeps the first occurrence of each dedupe key.
+ */
+export function dedupeFindings(findings: ReviewFinding[]): ReviewFinding[] {
+  const seen = new Set<string>()
+  const out: ReviewFinding[] = []
+  for (const f of findings) {
+    const key = findingKey(f)
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(f)
+  }
+  return out
+}
+
+/**
+ * Filter out findings that match a `known_intentional` entry.
+ * Match rule (mirrors SKILL.md Phase 1 FILTER):
+ *  - same `file` AND same `dimension`, AND
+ *  - entry `line` is 0/undefined (whole file) OR equals the finding's line.
+ */
+export function filterKnownIntentional(
+  findings: ReviewFinding[],
+  known: KnownIntentional[] | undefined,
+): ReviewFinding[] {
+  if (!known || known.length === 0) return findings
+  return findings.filter((f) => {
+    const matched = known.some((k) => {
+      const sameFile = k.file === f.file
+      const sameDim = k.dimension === f.dimension
+      if (!sameFile || !sameDim) return false
+      const wholeFile = k.line === undefined || k.line === 0
+      if (wholeFile) return true
+      return k.line === f.line
+    })
+    return !matched
+  })
+}
+
+/**
+ * Merge per-round findings into one globally-deduped stream while tracking
+ * which round first surfaced each finding. This is the deterministic core of
+ * "反复多轮审查直至收敛":
+ *  - `findingsByRound[r]` = number of GLOBALLY new findings first seen in round r
+ *  - `converged` = the last executed round produced 0 new findings
+ *  - `stoppedReason` = 'converged' | 'max_rounds_reached'
+ */
+export function aggregateRounds(
+  rounds: ReviewRound[],
+  maxReviewRounds: number,
+): {
+  findings: ReviewFinding[]
+  findingsByRound: number[]
+  firstRoundByKey: Map<string, number>
+} {
+  const seen = new Set<string>()
+  const firstRoundByKey = new Map<string, number>()
+  const merged: ReviewFinding[] = []
+
+  for (const round of rounds) {
+    for (const f of round.findings) {
+      const key = findingKey(f)
+      if (seen.has(key)) continue
+      seen.add(key)
+      firstRoundByKey.set(key, round.round)
+      merged.push(f)
+    }
+  }
+
+  const findingsByRound: number[] = []
+  for (let r = 1; r <= rounds.length; r++) {
+    let count = 0
+    for (const key of firstRoundByKey.keys()) {
+      if (firstRoundByKey.get(key) === r) count++
+    }
+    findingsByRound.push(count)
+  }
+
+  return { findings: dedupeFindings(merged), findingsByRound, firstRoundByKey }
+}
+
+/**
+ * Compute convergence statistics for a dry-run review.
+ */
+export function computeConvergence(
+  rounds: ReviewRound[],
+  maxReviewRounds: number,
+): ReviewReport['convergence'] {
+  const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds)
+  const totalRounds = rounds.length
+  const lastRoundCount = totalRounds > 0 ? findingsByRound[totalRounds - 1] ?? 0 : 0
+  const converged = totalRounds > 0 && lastRoundCount === 0
+  return {
+    totalRounds,
+    findingsByRound,
+    converged,
+    stoppedReason:
+      totalRounds === 0
+        ? 'max_rounds_reached'
+        : converged
+          ? 'converged'
+          : 'max_rounds_reached',
+  }
+}
+
+/** Build a severity/summary breakdown map for the report. */
+function summarize(findings: ReviewFinding[]): ReviewReport['summary'] {
+  const summary: ReviewReport['summary'] = {
+    totalFindings: findings.length,
+    critical: 0,
+    high: 0,
+    medium: 0,
+    low: 0,
+    byDimension: {},
+  }
+  for (const f of findings) {
+    if (f.severity === 'critical') summary.critical++
+    else if (f.severity === 'high') summary.high++
+    else if (f.severity === 'medium') summary.medium++
+    else summary.low++
+    summary.byDimension[f.dimension] = (summary.byDimension[f.dimension] ?? 0) + 1
+  }
+  return summary
+}
+
+/**
+ * Assemble the final ReviewReport from raw per-round findings.
+ * Applies known_intentional filtering, cross-round dedupe, severity sort,
+ * and convergence stats in one deterministic pass. Shared by dry-run (pure
+ * review) and normal (autonomous loop) modes — the mode only records intent;
+ * the math is identical.
+ */
+export function buildReviewReport(input: {
+  mode: 'dry-run' | 'normal'
+  goal: string
+  dimensions: string[]
+  maxReviewRounds: number
+  rounds: ReviewRound[]
+  knownIntentional?: KnownIntentional[]
+}): ReviewReport {
+  // 1. Filter known-intentional per round (before cross-round dedupe).
+  const filteredRounds = input.rounds.map((r) => ({
+    round: r.round,
+    findings: filterKnownIntentional(r.findings, input.knownIntentional),
+  }))
+
+  // 2. Cross-round dedupe + per-round "first seen" tracking.
+  const { findings, findingsByRound } = aggregateRounds(
+    filteredRounds,
+    input.maxReviewRounds,
+  )
+
+  // 3. Severity sort the global result.
+  const sorted = sortFindings(findings)
+
+  return {
+    mode: input.mode,
+    goal: input.goal,
+    dimensions: input.dimensions,
+    maxReviewRounds: input.maxReviewRounds,
+    rounds: filteredRounds,
+    findings: sorted,
+    convergence: {
+      totalRounds: filteredRounds.length,
+      findingsByRound,
+      converged: filteredRounds.length > 0 && (findingsByRound[filteredRounds.length - 1] ?? 0) === 0,
+      stoppedReason:
+        filteredRounds.length === 0
+          ? 'max_rounds_reached'
+          : (findingsByRound[filteredRounds.length - 1] ?? 0) === 0
+            ? 'converged'
+            : 'max_rounds_reached',
+    },
+    summary: summarize(sorted),
+  }
+}
+
+/**
+ * JSON Schema for reviewer subagent structured output.
+ * Object-rooted (dsh `agent` opts.schema requires object-rooted schemas with
+ * only type/properties/required/additionalProperties/items/enum/const/oneOf).
+ */
+export function findingsSchema(): Record<string, unknown> {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            dimension: { type: 'string' },
+            file: { type: 'string' },
+            line: { type: 'integer' },
+            severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
+            summary: { type: 'string' },
+            failure_scenario: { type: 'string' },
+            suggested_fix: { type: 'string' },
+            is_atomic: { type: 'boolean' },
+          },
+          required: [
+            'dimension',
+            'file',
+            'severity',
+            'summary',
+            'failure_scenario',
+            'suggested_fix',
+            'is_atomic',
+          ],
+        },
+      },
+    },
+    required: ['findings'],
+  }
+}
+
+/**
+ * Build the task prompt for one dimension's reviewer subagent.
+ * In dry-run mode, pass `alreadyKnown` (the findings from earlier rounds) so the
+ * reviewer hunts for NEW issues only — that is what makes "反复审查" converge.
+ */
+export function reviewerTaskPrompt(input: {
+  dimension: string
+  goal: string
+  scope: 'full' | 'changed-only'
+  mode: 'normal' | 'dry-run'
+  alreadyKnown?: ReviewFinding[]
+  outputLanguage: string
+}): string {
+  const parts: string[] = []
+  parts.push(
+    `You are the "${input.dimension}" reviewer for the iterate review.`,
+    `Goal: ${input.goal}`,
+    `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`,
+  )
+  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.',
+    )
+  }
+  if (input.alreadyKnown && input.alreadyKnown.length > 0) {
+    parts.push(
+      'Already-known findings from earlier rounds (do NOT re-report these; find NEW issues only):',
+      JSON.stringify(input.alreadyKnown, null, 2),
+    )
+  } else {
+    parts.push('This is round 1 — report every issue you find in this dimension.')
+  }
+  parts.push(
+    `Return a JSON object: {"findings": [...]}.`,
+    `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
+      'line (optional integer), severity (critical/high/medium/low), summary (one line), ' +
+      'failure_scenario (how/when it fails, specific evidence), suggested_fix (the concrete fix), ' +
+      'is_atomic (true if the fix is <= {atomic.max_lines} lines within a SINGLE file/function, else false).',
+    `Write summaries and details in ${input.outputLanguage}.`,
+  )
+  return parts.join('\n')
+}
+
+/**
+ * Build a review plan: how many rounds, which dimensions, and the reviewer
+ * prompt template for each dimension. Used by the `iterate_review` tool's
+ * `plan` operation to give the orchestrator a canonical spec.
+ */
+export function buildReviewPlan(input: {
+  config: IterateConfig
+  mode: 'normal' | 'dry-run'
+  maxReviewRounds: number
+  knownIntentional?: KnownIntentional[]
+}): {
+  mode: 'normal' | 'dry-run'
+  goal: string
+  scope: 'full' | 'changed-only'
+  dimensions: { id: string; reviewerPrompt: string; findingsSchema: Record<string, unknown> }[]
+  maxReviewRounds: number
+  knownIntentional: KnownIntentional[]
+} {
+  const language = input.config.language === 'zh' ? 'Chinese (中文)' : 'English'
+  return {
+    mode: input.mode,
+    goal: input.config.goal,
+    scope: input.config.review.scope,
+    dimensions: input.config.dimensions.map((d) => ({
+      id: d,
+      reviewerPrompt: reviewerTaskPrompt({
+        dimension: d,
+        goal: input.config.goal,
+        scope: input.config.review.scope,
+        mode: input.mode,
+        alreadyKnown: [],
+        outputLanguage: language,
+      }),
+      findingsSchema: findingsSchema(),
+    })),
+    maxReviewRounds: input.maxReviewRounds,
+    knownIntentional: input.knownIntentional ?? [],
+  }
+}