iterate-plugin 2.4.0 → 2.5.0

package/lib/parse.js

@@ -456,4 +456,335 @@ export function collectIgnoredEntries(triageState, findings) {
     })
   }
   return entries
+}
+
+// ─── Finding filtering ──────────────────────────────────────────────────────
+
+/**
+ * Normalize a caller-supplied filter into a stable shape.
+ * Unknown severity values are dropped; search is lower-cased + trimmed.
+ *
+ * @param {{ severities?: string[], dimensions?: string[], search?: string } | null | undefined} filter
+ * @returns {{ severities: string[], dimensions: string[], search: string }}
+ */
+export function normalizeFindingFilter(filter) {
+  const f = filter && typeof filter === 'object' ? filter : {}
+  const severities = Array.isArray(f.severities)
+    ? f.severities.filter((s) => SEVERITY_ORDER.includes(String(s)))
+    : []
+  const dimensions = Array.isArray(f.dimensions)
+    ? f.dimensions.filter((d) => typeof d === 'string' && d.length > 0)
+    : []
+  const search = typeof f.search === 'string' ? f.search.trim().toLowerCase() : ''
+  return { severities, dimensions, search }
+}
+
+/**
+ * Whether a single finding matches a normalized filter.
+ * An empty filter matches everything.
+ *
+ * @param {Record<string, unknown>} finding
+ * @param {{ severities: string[], dimensions: string[], search: string }} filter
+ * @returns {boolean}
+ */
+export function findingMatches(finding, filter) {
+  const f = normalizeFindingFilter(filter)
+  const sev = String(finding.severity ?? 'low')
+  if (f.severities.length > 0 && !f.severities.includes(sev)) return false
+  const dim = String(finding.dimension ?? '')
+  if (f.dimensions.length > 0 && !f.dimensions.includes(dim)) return false
+  if (f.search) {
+    const haystack = [
+      String(finding.file ?? ''),
+      String(finding.summary ?? ''),
+      String(finding.dimension ?? ''),
+      String(finding.suggested_fix ?? ''),
+    ].join(' ').toLowerCase()
+    if (haystack.indexOf(f.search) < 0) return false
+  }
+  return true
+}
+
+/**
+ * Filter a findings array, returning only the matches.
+ *
+ * @param {Array<Record<string, unknown>>} findings
+ * @param {{ severities?: string[], dimensions?: string[], search?: string } | null | undefined} filter
+ * @returns {Array<Record<string, unknown>>}
+ */
+export function filterFindings(findings, filter) {
+  const f = normalizeFindingFilter(filter)
+  return (Array.isArray(findings) ? findings : []).filter((finding) => findingMatches(finding, f))
+}
+
+/**
+ * Filter a findings array, returning the matches together with their ORIGINAL
+ * indices. Batch operations act on these indices so the triage state (keyed by
+ * original index) stays consistent even when some findings are hidden.
+ *
+ * @param {Array<Record<string, unknown>>} findings
+ * @param {{ severities?: string[], dimensions?: string[], search?: string } | null | undefined} filter
+ * @returns {{ filtered: Array<Record<string, unknown>>, indices: number[] }}
+ */
+export function filterFindingsWithIndices(findings, filter) {
+  const f = normalizeFindingFilter(filter)
+  const list = Array.isArray(findings) ? findings : []
+  const filtered = []
+  const indices = []
+  for (let i = 0; i < list.length; i++) {
+    if (findingMatches(list[i], f)) {
+      filtered.push(list[i])
+      indices.push(i)
+    }
+  }
+  return { filtered, indices }
+}
+
+/**
+ * Build the severity + dimension filter options with per-option counts, so the
+ * UI can render chips/selects and show how many findings each filters down to.
+ *
+ * @param {Array<Record<string, unknown>>} findings
+ * @returns {{ severities: Array<{ value: string, count: number }>, dimensions: Array<{ value: string, count: number }> }}
+ */
+export function buildFilterOptions(findings) {
+  const list = Array.isArray(findings) ? findings : []
+  const severities = SEVERITY_ORDER.map((value) => ({ value, count: 0 }))
+  /** @type {Record<string, number>} */
+  const dimCounts = {}
+  for (const f of list) {
+    const sev = String(f.severity ?? 'low')
+    const sv = severities.find((s) => s.value === sev)
+    if (sv) sv.count++
+    const dim = String(f.dimension ?? 'unknown')
+    dimCounts[dim] = (dimCounts[dim] ?? 0) + 1
+  }
+  return {
+    severities: severities.map((s) => ({ ...s })),
+    dimensions: Object.keys(dimCounts).map((value) => ({ value, count: dimCounts[value] })),
+  }
+}
+
+// ─── Triage batch operations ────────────────────────────────────────────────
+
+/**
+ * Count how many findings carry each verdict.
+ *
+ * @param {Record<string, 'keep' | 'skip' | 'ignore'>} triageState
+ * @returns {{ keep: number, skip: number, ignore: number }}
+ */
+export function countVerdicts(triageState) {
+  const counts = { keep: 0, skip: 0, ignore: 0 }
+  for (const v of Object.values(triageState ?? {})) {
+    if (v === 'keep' || v === 'skip' || v === 'ignore') counts[v]++
+  }
+  return counts
+}
+
+/**
+ * Set the verdict for a list of finding indices. Returns a NEW state
+ * (the input is never mutated).
+ *
+ * @param {Record<string, 'keep' | 'skip' | 'ignore'>} triageState
+ * @param {number[]} indices
+ * @param {'keep' | 'skip' | 'ignore'} verdict
+ * @returns {Record<string, 'keep' | 'skip' | 'ignore'>}
+ */
+export function batchSetVerdict(triageState, indices, verdict) {
+  if (verdict !== 'keep' && verdict !== 'skip' && verdict !== 'ignore') return triageState
+  if (!Array.isArray(indices) || indices.length === 0) return triageState
+  const next = { ...triageState }
+  for (const idx of indices) {
+    if (typeof idx === 'number' && Number.isInteger(idx) && idx >= 0) {
+      next[String(idx)] = verdict
+    }
+  }
+  return next
+}
+
+/**
+ * Set the verdict for ALL findings (or only the given index whitelist).
+ *
+ * @param {Record<string, 'keep' | 'skip' | 'ignore'>} triageState
+ * @param {'keep' | 'skip' | 'ignore'} verdict
+ * @param {number[]} [indices]
+ * @returns {Record<string, 'keep' | 'skip' | 'ignore'>}
+ */
+export function setAllVerdicts(triageState, verdict, indices) {
+  const targets = Array.isArray(indices)
+    ? indices
+    : Object.keys(triageState ?? {}).map(Number)
+  return batchSetVerdict(triageState, targets, verdict)
+}
+
+// ─── History & trend ────────────────────────────────────────────────────────
+
+/**
+ * Per-round finding counts (including severity breakdown), oldest first.
+ * Derived from `report.rounds`.
+ *
+ * @param {Record<string, unknown>} report
+ * @returns {Array<{ round: number, count: number, critical: number, high: number, medium: number, low: number }>}
+ */
+export function buildRoundHistory(report) {
+  const rounds = Array.isArray(report.rounds) ? report.rounds : []
+  return rounds.map((r) => {
+    const rr = /** @type {Record<string, unknown>} */ (r)
+    const findings = Array.isArray(rr.findings) ? rr.findings : []
+    const sev = severityStats({ findings })
+    return {
+      round: typeof rr.round === 'number' ? rr.round : 0,
+      count: findings.length,
+      critical: sev.critical,
+      high: sev.high,
+      medium: sev.medium,
+      low: sev.low,
+    }
+  })
+}
+
+/**
+ * Findings-by-round trend points. Prefers the explicit
+ * `convergence.findingsByRound` when present, otherwise derives from rounds.
+ *
+ * @param {Record<string, unknown>} report
+ * @returns {Array<{ round: number, count: number }>}
+ */
+export function buildFindingTrend(report) {
+  const conv = /** @type {Record<string, unknown>} */ (report.convergence ?? {})
+  if (Array.isArray(conv.findingsByRound)) {
+    return conv.findingsByRound.map((n, i) => ({ round: i + 1, count: typeof n === 'number' ? n : 0 }))
+  }
+  return buildRoundHistory(report).map((h) => ({ round: h.round, count: h.count }))
+}
+
+/**
+ * Trend metrics for the dashboard chart + summary line.
+ *
+ * @param {Record<string, unknown>} report
+ * @returns {{ points: Array<{ round: number, count: number }>, total: number, firstRound: number, lastRound: number, reductionPercent: number, converged: boolean }}
+ */
+export function computeTrendMetrics(report) {
+  const conv = /** @type {Record<string, unknown>} */ (report.convergence ?? {})
+  const points = buildFindingTrend(report)
+  const total = points.reduce((sum, p) => sum + p.count, 0)
+  const firstRound = points.length > 0 ? points[0].count : 0
+  const lastRound = points.length > 0 ? points[points.length - 1].count : 0
+  const reductionPercent = firstRound > 0 ? Math.round(((firstRound - lastRound) / firstRound) * 100) : 0
+  return {
+    points,
+    total,
+    firstRound,
+    lastRound,
+    reductionPercent,
+    converged: conv.converged === true,
+  }
+}
+
+/**
+ * Peak count among trend points (for chart scaling). Never returns 0 so the
+ * chart always has a sane baseline.
+ *
+ * @param {Array<{ round: number, count: number }>} points
+ * @returns {number}
+ */
+export function trendMax(points) {
+  let max = 1
+  for (const p of Array.isArray(points) ? points : []) {
+    if (typeof p.count === 'number' && p.count > max) max = p.count
+  }
+  return max
+}
+
+// ─── Completion notification ────────────────────────────────────────────────
+
+/**
+ * One-line completion summary for notifications ("已收敛 / 已达最大轮数").
+ *
+ * @param {Record<string, unknown>} report
+ * @returns {string}
+ */
+export function buildCompletionSummary(report) {
+  const conv = /** @type {Record<string, unknown>} */ (report.convergence ?? {})
+  const rounds = getCurrentRound(report)
+  const total = getTotalRounds(report)
+  const stats = severityStats(report)
+  const converged = conv.converged === true
+  const reason = converged ? '已收敛' : `已达最大轮数 ${total}`
+  const totalFindings = stats.critical + stats.high + stats.medium + stats.low
+  return `iterate 评审完成 · ${rounds}/${total} 轮 · ${totalFindings} 项发现 · ${reason}`
+}
+
+// ─── Config edit guidance ───────────────────────────────────────────────────
+
+/**
+ * Editable config fields (key + label + hint), used by the settings guide.
+ * @type {Array<{ key: string, label: string, hint: string }>}
+ */
+export const CONFIG_EDIT_FIELDS = [
+  { key: 'goal', label: '目标', hint: '一句话描述本次迭代目标（字符串）' },
+  { key: 'dimensions', label: '审查维度', hint: '数组，如 ["correctness","security"]' },
+  { key: 'max_rounds', label: '最大轮数', hint: '正整数' },
+  { key: 'review.scope', label: '审查范围', hint: '"full" 或 "changed-only"' },
+  { key: 'atomic.max_lines', label: '原子修复上限行数', hint: '正整数' },
+  { key: 'git.push_per_round', label: '每轮推送', hint: 'true / false' },
+]
+
+/**
+ * Static copy-paste config editing guide (shown in the settings page).
+ *
+ * @returns {string}
+ */
+export function buildConfigEditGuide() {
+  const lines = [
+    'iterate 配置编辑指引',
+    '---------------------',
+    '配置文件：项目根目录 iterate.config.yaml。',
+    '',
+    '可编辑字段：',
+    ...CONFIG_EDIT_FIELDS.map((f) => `- ${f.key}（${f.label}）：${f.hint}`),
+    '',
+    '让模型帮你改：',
+    '1. 调用 iterate_config({ operation: "read" }) 查看当前配置；',
+    '2. 说明想改的字段，例如「把 max_rounds 改成 5，dimensions 只保留 correctness 和 security」；',
+    '3. 模型会调用 iterate_config({ operation: "write", updates: {...} }) 写入，写入前自动备份，失败自动回滚。',
+  ]
+  return lines.join('\n')
+}
+
+/**
+ * Build a copy-paste instruction for a desired config change. The user picks
+ * the fields they want to change; the resulting text is meant to be pasted to
+ * the model to trigger an `iterate_config` write.
+ *
+ * @param {Record<string, unknown>} desiredChanges
+ * @returns {string}
+ */
+export function buildConfigEditInstruction(desiredChanges) {
+  const payload = JSON.stringify({ operation: 'write', updates: desiredChanges }, null, 2)
+  return `请调用 \`iterate_config\` 写入以下配置更新：\n\n\`\`\`json\n${payload}\n\`\`\``
+}
+
+/**
+ * Keyboard shortcut → triage verdict mapping (used by the triage panel).
+ * @type {Record<string, 'keep' | 'skip' | 'ignore'>}
+ */
+export const VERDICT_SHORTCUTS = {
+  y: 'keep',
+  Y: 'keep',
+  n: 'skip',
+  N: 'skip',
+  a: 'ignore',
+  A: 'ignore',
+}
+
+/**
+ * Map a keyboard event key to a triage verdict, or null when the key is not a
+ * triage shortcut.
+ *
+ * @param {string} key
+ * @returns {'keep' | 'skip' | 'ignore' | null}
+ */
+export function keyToVerdict(key) {
+  return VERDICT_SHORTCUTS[key] ?? null
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
   "type": "module",
   "license": "MIT",

package/src/config-write.ts

@@ -0,0 +1,181 @@
+/**
+ * src/config-write.ts — shared helpers for safely WRITING iterate.config.yaml.
+ *
+ * Used by the `iterate_config` write operation. Provides:
+ *   - validateConfigUpdates : validate a caller-supplied partial update
+ *   - applyConfigUpdates    : merge a partial update into the current config
+ *   - writeConfigFile       : backup + write + rollback on failure
+ *
+ * The security posture mirrors the triage tool: never overwrite a malformed
+ * config, always back up before writing, roll back on failure.
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+
+/** Config file name (must match config-loader). */
+export const CONFIG_FILE = 'iterate.config.yaml'
+
+/** Backup suffix helper (filesystem-safe timestamp). */
+export function configBackupSuffix(now = new Date()): string {
+  return now.toISOString().replace(/[:.]/g, '-')
+}
+
+/**
+ * Validate a partial config update.
+ * Returns an array of error strings (empty when the update is valid).
+ */
+export function validateConfigUpdates(updates: Record<string, unknown>): string[] {
+  const errors: string[] = []
+  if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
+    return ['updates must be a JSON object']
+  }
+
+  if ('goal' in updates && typeof updates.goal !== 'string') {
+    errors.push('updates.goal must be a string')
+  }
+  if ('language' in updates && updates.language !== 'zh' && updates.language !== 'en') {
+    errors.push('updates.language must be "zh" or "en"')
+  }
+  if ('dimensions' in updates) {
+    if (!Array.isArray(updates.dimensions) || updates.dimensions.some((d) => typeof d !== 'string' || d.trim().length === 0)) {
+      errors.push('updates.dimensions must be an array of non-empty strings')
+    }
+  }
+  if ('max_rounds' in updates) {
+    if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) || updates.max_rounds < 1) {
+      errors.push('updates.max_rounds must be a positive integer')
+    }
+  }
+  if ('review' in updates) {
+    const r = updates.review as Record<string, unknown> | undefined
+    if (!r || typeof r !== 'object') {
+      errors.push('updates.review must be an object')
+    } else if (r.scope !== undefined && r.scope !== 'full' && r.scope !== 'changed-only') {
+      errors.push('updates.review.scope must be "full" or "changed-only"')
+    }
+  }
+  if ('atomic' in updates) {
+    const a = updates.atomic as Record<string, unknown> | undefined
+    if (!a || typeof a !== 'object') {
+      errors.push('updates.atomic must be an object')
+    } else {
+      if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1)) {
+        errors.push('updates.atomic.max_lines must be a positive integer')
+      }
+      if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0)) {
+        errors.push('updates.atomic.max_adjacent_methods must be a non-negative number')
+      }
+    }
+  }
+  if ('git' in updates) {
+    const g = updates.git as Record<string, unknown> | undefined
+    if (!g || typeof g !== 'object') {
+      errors.push('updates.git must be an object')
+    } else {
+      if (g.target_branch !== undefined && typeof g.target_branch !== 'string') {
+        errors.push('updates.git.target_branch must be a string')
+      }
+      for (const boolKey of ['use_worktree', 'push_per_round', 'auto_merge'] as const) {
+        if (g[boolKey] !== undefined && typeof g[boolKey] !== 'boolean') {
+          errors.push(`updates.git.${boolKey} must be a boolean`)
+        }
+      }
+    }
+  }
+  if ('validation' in updates) {
+    const v = updates.validation as Record<string, unknown> | undefined
+    if (!v || typeof v !== 'object') {
+      errors.push('updates.validation must be an object')
+    } else if ('commands' in v && v.commands !== undefined && typeof v.commands !== 'object') {
+      errors.push('updates.validation.commands must be an object of command arrays')
+    }
+  }
+  if ('personalization' in updates && (!updates.personalization || typeof updates.personalization !== 'object')) {
+    errors.push('updates.personalization must be an object')
+  }
+  if ('onboarding' in updates && (!updates.onboarding || typeof updates.onboarding !== 'object')) {
+    errors.push('updates.onboarding must be an object')
+  }
+  return errors
+}
+
+/** Recursively merge `updates` over `base` (arrays replaced wholesale). */
+export function applyConfigUpdates(
+  base: Record<string, unknown>,
+  updates: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(updates)) {
+    if (value === undefined) continue
+    const baseValue = out[key]
+    if (
+      baseValue &&
+      typeof baseValue === 'object' &&
+      !Array.isArray(baseValue) &&
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value)
+    ) {
+      out[key] = applyConfigUpdates(baseValue as Record<string, unknown>, value as Record<string, unknown>)
+    } else {
+      out[key] = value
+    }
+  }
+  return out
+}
+
+/**
+ * Read the raw config object from disk (empty object when missing).
+ * Throws when the file exists but cannot be parsed as a YAML mapping
+ * (never overwrite a malformed config).
+ */
+export function readRawConfig(configPath: string): Record<string, unknown> {
+  if (!existsSync(configPath)) return {}
+  const content = readFileSync(configPath, 'utf-8')
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content)
+  } catch {
+    throw new Error('existing iterate.config.yaml is not a valid YAML mapping')
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('existing iterate.config.yaml is not a valid YAML mapping')
+  }
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * Write a config object to disk with backup + rollback.
+ * Returns `{ ok: true, backupPath }` or `{ ok: false, error }`.
+ */
+export function writeConfigFile(
+  projectRoot: string,
+  config: Record<string, unknown>,
+): { ok: true; backupPath: string | null } | { ok: false; error: string } {
+  const configPath = join(projectRoot, CONFIG_FILE)
+  const hadFile = existsSync(configPath)
+  const backupPath = hadFile ? `${configPath}.bak-${configBackupSuffix()}` : null
+
+  if (backupPath) {
+    try {
+      copyFileSync(configPath, backupPath)
+    } catch (err) {
+      return { ok: false, error: `failed to create backup: ${String(err)}` }
+    }
+  }
+
+  try {
+    writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8')
+  } catch (err) {
+    try {
+      if (backupPath) copyFileSync(backupPath, configPath)
+    } catch {
+      // Rollback failure is reported, never swallowed silently.
+    }
+    return { ok: false, error: `failed to write config: ${String(err)}` }
+  }
+
+  return { ok: true, backupPath }
+}

package/src/index.ts

@@ -28,19 +28,26 @@ import { registerDecisionLogTool } from './tools/decision-log.ts'
 import { registerContextTool } from './tools/context.ts'
 import { registerReviewTool } from './tools/review.ts'
 import { registerTriageTool } from './tools/triage.ts'
+import { registerFixTool, registerDiffTool, registerRollbackTool } from './tools/fix.ts'
+import { registerCheckpointTool, registerStatusTool } from './tools/checkpoint.ts'
 import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
 
 export const name = 'iterate-plugin'
 export const inject = ['tools', 'systemPrompt']
 
 export function apply(ctx: Context): void {
-  // 1. Register the 6 core tools
+  // 1. Register the 11 tools
   registerConfigTool(ctx)
   registerValidateTool(ctx)
   registerDecisionLogTool(ctx)
   registerContextTool(ctx)
   registerReviewTool(ctx)
   registerTriageTool(ctx)
+  registerFixTool(ctx)
+  registerDiffTool(ctx)
+  registerRollbackTool(ctx)
+  registerCheckpointTool(ctx)
+  registerStatusTool(ctx)
 
   // 2. Inject the iterate skill prompt as a system prompt section
   // This teaches the model how to write iterate workflow scripts using the tools.

package/src/paths.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared filesystem layout for the iterate plugin's runtime state.
+ *
+ * All runtime artifacts live under `<projectRoot>/.iterate/`:
+ *   .iterate/decision-log.jsonl   — append-only decision log
+ *   .iterate/fixes/               — fix system: backups + fix registry
+ *   .iterate/checkpoint.json      — iteration checkpoint (resume support)
+ *
+ * Kept separate from config-loader so every tool points at the same dirs.
+ */
+
+import { join } from 'node:path'
+
+/** Runtime state root for a project (e.g. `<projectRoot>/.iterate`). */
+export function iterateDir(projectRoot: string): string {
+  return join(projectRoot, '.iterate')
+}
+
+/** Fix-system directory (backups + registry). */
+export function fixesDir(projectRoot: string): string {
+  return join(iterateDir(projectRoot), 'fixes')
+}
+
+/** Fix-registry file (JSON). */
+export function fixRegistryPath(projectRoot: string): string {
+  return join(fixesDir(projectRoot), 'registry.json')
+}
+
+/** Fix-backup file for one fix id + timestamp. */
+export function fixBackupPath(projectRoot: string, id: string, timestamp: string): string {
+  const safe = id.replace(/[^a-zA-Z0-9_-]/g, '_')
+  return join(fixesDir(projectRoot), `${safe}_${timestamp.replace(/[:.]/g, '-')}.bak`)
+}
+
+/** Iteration checkpoint file (JSON). */
+export function checkpointPath(projectRoot: string): string {
+  return join(iterateDir(projectRoot), 'checkpoint.json')
+}