iterate-plugin 2.3.6

package/src/tools/review.ts

@@ -0,0 +1,174 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { loadEffectiveConfig } from '../config-loader.ts'
+import { buildReviewPlan, buildReviewReport } from '../review.ts'
+import { buildFinalReviewReport, metaReviewReport } from '../meta-review.ts'
+import type { KnownIntentional, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
+
+/** Default round cap when neither the arg nor config provides one. */
+const DEFAULT_MAX_REVIEW_ROUNDS = 3
+
+/**
+ * Register the `iterate_review` tool.
+ *
+ * Two operations:
+ *  - `plan`:      deterministic review plan for a mode (normal | dry-run).
+ *                 Returns the goal, scope, per-dimension reviewer prompts,
+ *                 the findings schema, and the max round cap. The orchestrator
+ *                 uses this instead of inventing prompts ad hoc.
+ *  - `aggregate`: deterministic aggregation of raw per-round findings.
+ *                 Applies known_intentional filtering, cross-round dedupe,
+ *                 severity sort, and convergence stats; returns a ReviewReport.
+ *                 Purely computational — NEVER touches the filesystem.
+ */
+export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_review',
+      description:
+        'Deterministic review engine for the iterate workflow. ' +
+        'Use `plan` to generate the review plan (dimensions, reviewer prompts, findings schema, round cap) ' +
+        'for normal or dry-run mode. Use `aggregate` to merge raw per-round findings into a deduped, ' +
+        'severity-sorted report with multi-round convergence statistics, and to audit that report ' +
+        '(`meta-review`) producing a final review report. ' +
+        '`aggregate`/`meta-review` are purely computational — they never modify any file.',
+
+      parameters: {
+        operation: {
+          type: 'string',
+          required: true,
+          description: '"plan" to build the review plan, "aggregate" to merge findings, "meta-review" to audit a report.',
+          enum: ['plan', 'aggregate', 'meta-review'],
+        },
+        mode: {
+          type: 'string',
+          description: 'Review mode: "dry-run" (pure review, no fixes) or "normal" (autonomous loop). Default: dry-run.',
+          enum: ['dry-run', 'normal'],
+        },
+        rounds: {
+          type: 'json',
+          description:
+            'For `aggregate`: array of per-round findings, e.g. ' +
+            '[{"round":1,"findings":[...]},{"round":2,"findings":[...]}]. Each finding: ' +
+            '{dimension,file,line?,severity,summary,failure_scenario,suggested_fix,is_atomic}.',
+        },
+        maxReviewRounds: {
+          type: 'integer',
+          description: 'Round cap for dry-run convergence. Default: config.max_rounds, else 3.',
+        },
+        goal: {
+          type: 'string',
+          description: 'Optional goal override for `aggregate` (defaults to config goal).',
+        },
+        knownIntentional: {
+          type: 'json',
+          description:
+            'For `aggregate`: known-intentional entries to filter out, e.g. ' +
+            '[{"file":"db/queries.py","line":42,"dimension":"security","reason":"..."}]. line=0/omitted = whole file.',
+        },
+        report: {
+          type: 'json',
+          description:
+            'For `meta-review`: the ReviewReport JSON (as returned by `aggregate`) to audit for ' +
+            'internal consistency and produce the final review report.',
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            operation: { type: 'string', required: true },
+            mode: { type: 'string' },
+            found: { type: 'boolean' },
+            plan: { type: 'json' },
+            report: { type: 'json' },
+            finalReport: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [
+          { type: 'text', text: JSON.stringify(value, null, 2) },
+        ],
+      },
+
+      async execute(args) {
+        const projectRoot = args.path ?? process.cwd()
+        // Effective config = defaults merged with project overrides. Never
+        // null, so `plan`/`aggregate` work even without a config file.
+        const { config } = loadEffectiveConfig(projectRoot)
+        const mode = args.mode ?? 'dry-run'
+
+        if (args.operation === 'plan') {
+          const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS
+          const knownIntentional = (config.personalization as { known_intentional?: KnownIntentional[] } | undefined)
+            ?.known_intentional
+          const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional })
+          return { operation: 'plan', mode, found: true, plan: plan as unknown as JsonValue }
+        }
+
+        if (args.operation === 'aggregate') {
+          const rawRounds = Array.isArray(args.rounds) ? args.rounds : []
+          const rounds: ReviewRound[] = rawRounds
+            .map((r) => {
+              const rr = r as { round?: number; findings?: unknown }
+              const findings = Array.isArray(rr?.findings) ? (rr.findings as ReviewFinding[]) : []
+              return { round: typeof rr?.round === 'number' ? rr.round : 0, findings }
+            })
+            .filter((r: ReviewRound) => r.round > 0)
+
+          if (rounds.length === 0) {
+            return {
+              operation: 'aggregate',
+              mode,
+              error: 'rounds must be a non-empty array of {round, findings}.',
+            }
+          }
+
+          const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS
+          const goal = args.goal ?? config.goal ?? ''
+          const dimensions = config.dimensions ?? []
+          const report = buildReviewReport({
+            mode,
+            goal,
+            dimensions,
+            maxReviewRounds,
+            rounds,
+            knownIntentional: args.knownIntentional as KnownIntentional[] | undefined,
+          })
+          return { operation: 'aggregate', mode, report: report as unknown as JsonValue }
+        }
+
+        if (args.operation === 'meta-review') {
+          const source = args.report as ReviewReport | undefined
+          if (!source || typeof source !== 'object') {
+            return {
+              operation: 'meta-review',
+              mode,
+              error: 'report must be a ReviewReport JSON object (as returned by `aggregate`).',
+            }
+          }
+          const audit = metaReviewReport(source)
+          const finalReport = buildFinalReviewReport(source)
+          return {
+            operation: 'meta-review',
+            mode,
+            found: true,
+            report: audit as unknown as JsonValue,
+            finalReport: finalReport as unknown as JsonValue,
+          }
+        }
+
+        return {
+          operation: args.operation,
+          error: `Unknown operation "${args.operation}". Use "plan", "aggregate", or "meta-review".`,
+        }
+      },
+    }),
+  )
+}

package/src/tools/validate.ts

@@ -0,0 +1,159 @@
+import { exec } from 'node:child_process'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { loadEffectiveConfig, isCommandAllowed, flattenCommands } from '../config-loader.ts'
+import type { ValidationResult } from '../types.ts'
+
+const DEFAULT_TIMEOUT_MS = 120_000
+
+/**
+ * Run a single shell command with timeout and return structured results.
+ * Pure function (no side effects beyond the exec call).
+ */
+async function runCommand(
+  command: string,
+  cwd: string,
+  timeoutMs: number,
+): Promise<ValidationResult> {
+  const start = performance.now()
+  return new Promise<ValidationResult>((resolve) => {
+    exec(
+      command,
+      {
+        cwd,
+        timeout: timeoutMs,
+        maxBuffer: 10 * 1024 * 1024, // 10 MB
+        env: { ...process.env, PAGER: 'cat' },
+      },
+      (error, stdout, stderr) => {
+        const durationMs = Math.round(performance.now() - start)
+        // error.code is the exit code when the command ran; error.killed means timeout
+        resolve({
+          command,
+          exitCode: error?.code ?? (error ? 1 : 0),
+          stdout: stdout ?? '',
+          stderr: stderr ?? '',
+          timedOut: error?.killed === true,
+          durationMs,
+        })
+      },
+    )
+  })
+}
+
+/**
+ * Register the `iterate_validate` tool.
+ * Runs validation commands defined in iterate.config.yaml `validation.commands`.
+ * Enforces exact-match — a command not listed there (exactly) is rejected.
+ */
+export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_validate',
+      description:
+        'Run a validation command that is PRECONFIGURED in iterate.config.yaml `validation.commands`. ' +
+        'The command must exactly match one of the configured commands (they are the only ones the user trusts). ' +
+        'Returns exit code, stdout, stderr, and duration. ' +
+        'Use this after making fixes to verify correctness.',
+
+      parameters: {
+        command: {
+          type: 'string',
+          required: true,
+          description: 'One of the commands listed in iterate.config.yaml validation.commands (exact match required, e.g. "pytest tests/ -x -q").',
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+        timeout: {
+          type: 'integer',
+          description: 'Timeout in milliseconds (default: 120000).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            allowed: { type: 'boolean', required: true },
+            command: { type: 'string', required: true },
+            exitCode: { type: 'integer', required: true },
+            stdout: { type: 'string', required: true },
+            stderr: { type: 'string', required: true },
+            timedOut: { type: 'boolean', required: true },
+            durationMs: { type: 'integer', required: true },
+            rejectReason: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [
+          {
+            type: 'text',
+            text: value.allowed
+              ? [
+                  `Command: ${value.command}`,
+                  `Exit code: ${value.exitCode}`,
+                  `Duration: ${value.durationMs}ms`,
+                  value.timedOut ? '⚠ Timed out' : '',
+                  '',
+                  value.stdout ? `[stdout]\n${value.stdout}` : '',
+                  value.stderr ? `[stderr]\n${value.stderr}` : '',
+                ]
+                  .filter(Boolean)
+                  .join('\n')
+              : `Command rejected: ${value.rejectReason}`,
+          },
+        ],
+      },
+
+      async execute(args) {
+        const projectRoot = args.path ?? process.cwd()
+        // Effective config = defaults merged with project overrides. Never null.
+        const { config, source } = loadEffectiveConfig(projectRoot)
+        const timeout = args.timeout ?? DEFAULT_TIMEOUT_MS
+
+        // Only commands predefined in validation.commands may run — the
+        // user trusts exactly these, and nothing else. This replaces the
+        // old prefix-match whitelist, which let e.g. `python3 -c "..."`
+        // slip through on a `python3` prefix.
+        const predefinedCommands = flattenCommands(config.validation.commands)
+        if (predefinedCommands.length === 0) {
+          return {
+            allowed: false,
+            command: args.command,
+            exitCode: -1,
+            stdout: '',
+            stderr: '',
+            timedOut: false,
+            durationMs: 0,
+            rejectReason:
+              (source === 'defaults'
+                ? 'No iterate.config.yaml at project root — running on built-in defaults, which configure NO trusted validation commands. '
+                : 'No validation.commands configured in iterate.config.yaml. ') +
+              'Nothing can be validated until you define trusted commands in `validation.commands`.',
+          }
+        }
+        if (!isCommandAllowed(args.command, predefinedCommands)) {
+          return {
+            allowed: false,
+            command: args.command,
+            exitCode: -1,
+            stdout: '',
+            stderr: '',
+            timedOut: false,
+            durationMs: 0,
+            rejectReason:
+              `Command must exactly match a command predefined in iterate.config.yaml validation.commands. ` +
+              `Allowed commands: ${predefinedCommands.join(' | ')}`,
+          }
+        }
+
+        const result = await runCommand(args.command, projectRoot, timeout)
+        return {
+          allowed: true,
+          ...result,
+        }
+      },
+    }),
+  )
+}

package/src/types.ts

@@ -0,0 +1,100 @@
+/** Parsed iterate.config.yaml */
+export interface IterateConfig {
+  goal: string
+  max_rounds: number
+  language: 'zh' | 'en'
+  dimensions: string[]
+  review: { scope: 'full' | 'changed-only' }
+  atomic: { max_lines: number; max_adjacent_methods: number }
+  git: {
+    target_branch: string
+    use_worktree: boolean
+    push_per_round: boolean
+    auto_merge: boolean
+  }
+  validation: {
+    command_whitelist: string[]
+    commands: Record<string, string[]>
+  }
+  reviewer: { output_schema_validation: boolean }
+  onboarding?: Record<string, unknown>
+  personalization?: Record<string, unknown>
+}
+
+/** One entry in the append-only decision log */
+export interface DecisionLogEntry {
+  timestamp: string
+  round: number
+  type:
+    | 'round_start'
+    | 'review_result'
+    | 'atomic_fix'
+    | 'architectural_fix'
+    | 'revert'
+    | 'validation'
+    | 'decision'
+    | 'report'
+  data: Record<string, unknown>
+}
+
+/** Result of running a validation command */
+export interface ValidationResult {
+  command: string
+  exitCode: number
+  stdout: string
+  stderr: string
+  timedOut: boolean
+  durationMs: number
+}
+
+/** A single finding from a dimension review */
+export interface ReviewFinding {
+  dimension: string
+  file: string
+  line?: number
+  severity: 'critical' | 'high' | 'medium' | 'low'
+  summary: string
+  failure_scenario: string
+  suggested_fix: string
+  /** true if the fix fits within atomic thresholds (single file, single function, ≤ max_lines). */
+  is_atomic: boolean
+}
+
+/** Review report (dry-run or normal mode) */
+export interface ReviewReport {
+  mode: 'dry-run' | 'normal'
+  goal: string
+  dimensions: string[]
+  maxReviewRounds: number
+  rounds: ReviewRound[]
+  /** Globally deduped, known-intentional-filtered, severity-sorted findings. */
+  findings: ReviewFinding[]
+  convergence: {
+    totalRounds: number
+    findingsByRound: number[]
+    converged: boolean
+    stoppedReason: 'converged' | 'max_rounds_reached'
+  }
+  summary: {
+    totalFindings: number
+    critical: number
+    high: number
+    medium: number
+    low: number
+    byDimension: Record<string, number>
+  }
+}
+
+/** One round of review */
+export interface ReviewRound {
+  round: number
+  findings: ReviewFinding[]
+}
+
+/** Known intentional entry (filtered out from findings) */
+export interface KnownIntentional {
+  file: string
+  line?: number
+  dimension: string
+  reason: string
+}