iterate-plugin 2.7.2 → 2.8.0

package/README.md

@@ -7,6 +7,14 @@
 
 > **Developed and reviewed in the [iterate-skill monorepo](https://github.com/jingzhao-l/iterate-skill)**: the plugin code is maintained in the main repository and synced here via `git subtree`; **releases and npm publishing happen in this (plugin) repository**, which is the canonical publish point for the dsh ecosystem. Please **star / fork the main repository** and file issues at the [main repository Issues](https://github.com/jingzhao-l/iterate-skill/issues).
 
+<p align="center">
+  <a href="https://github.com/jingzhao-l/iterate-plugin"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-plugin?style=social&label=Star" alt="Stars"></a>
+  <a href="https://github.com/jingzhao-l/iterate-skill"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=Main%20Repo%20Star" alt="Main Repo Stars"></a>
+  <a href="https://www.npmjs.com/package/iterate-plugin"><img src="https://img.shields.io/npm/dt/iterate-plugin?label=Downloads&logo=npm&logoColor=white" alt="npm downloads"></a>
+</p>
+
+> ⭐ If this helps your dsh workflow, give the main repo a star — it means a lot!
+
 ## About This Plugin
 
 **iterate** is an open-source project that gives AI coding assistants the ability to review and fix code in multi-round autonomous loops. It targets a concrete pain point:
@@ -221,6 +229,19 @@ All tests pass:
 - **212 unit tests green**, type-check clean
 - Coverage: dedupe, filter, sort, multi-round convergence, meta-review audit, path safety, timeout clamping, config read/write + rollback, triage merge, diff computation, checkpoint validation, fix registry, history read + filter, prune cleanup report + dry-run semantics, UI pure functions (select-all key, runtime status guide).
 
+## ⚠️ Disclaimer
+
+This project is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.
+
+**Automated code review and fixing carries inherent risk.** All changes produced in normal mode are generated by AI models and may introduce bugs, regressions, or unintended behavior. Before merging, you should:
+
+- Review every diff before applying it to your main branch or pushing.
+- Make sure your project is under git control and can be rolled back (`git restore`, revert, or restore from backup).
+- Run your project's own test suite and build checks after each round of fixes.
+- Never run this on secrets, credentials, `.env`, or files that must not be modified — configure `protected_paths` accordingly.
+
+Users are solely responsible for the code that is generated, modified, or committed as a result of using this project. By using it, you acknowledge that neither the maintainers nor contributors are liable for any loss, damage, or legal consequences arising from its use.
+
 ## License
 
 MIT

package/README.zh-CN.md

@@ -7,6 +7,14 @@
 
 > **开发与评审在 [iterate-skill 主仓库](https://github.com/jingzhao-l/iterate-skill) 完成**：插件代码由主仓库统一维护，通过 `git subtree` 同步到本仓库；**版本发版与 npm 发布在本仓库（插件仓库）进行**，作为 dsh 生态的正式发布位。欢迎 **star / fork 主仓库** 并在 [主仓库 Issues](https://github.com/jingzhao-l/iterate-skill/issues) 反馈问题。
 
+<p align="center">
+  <a href="https://github.com/jingzhao-l/iterate-plugin"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-plugin?style=social&label=Star" alt="Stars"></a>
+  <a href="https://github.com/jingzhao-l/iterate-skill"><img src="https://img.shields.io/github/stars/jingzhao-l/iterate-skill?style=social&label=主仓库%20Star" alt="主仓库 Stars"></a>
+  <a href="https://www.npmjs.com/package/iterate-plugin"><img src="https://img.shields.io/npm/dt/iterate-plugin?label=Downloads&logo=npm&logoColor=white" alt="npm downloads"></a>
+</p>
+
+> ⭐ 如果这个插件对你的 dsh 工作流有帮助，欢迎为主仓库点亮 Star，这是对开源维护最大的支持！
+
 ## 这是什么 / About This Plugin
 
 **iterate** 是一个让 AI 编程助手具备多轮自主代码审查与修复能力的开源项目。它解决很具体的痛点：
@@ -221,6 +229,19 @@ npm test
 - **212 个单元测试全绿**，类型检查通过
 - 覆盖：去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数（select-all 键、运行时状态指引）等
 
+## ⚠️ 免责声明
+
+本项目按「现状」（AS IS）提供，不附带任何明示或暗示的担保，包括但不限于对适销性、特定用途适用性及不侵权性的担保。
+
+**自动化的代码审查与修复存在固有风险。** normal 模式下产生的改动均由 AI 模型生成，可能引入缺陷、回归或非预期行为。在合并改动前，你应当：
+
+- 在应用到主分支或推送前，逐条 review 每一处 diff。
+- 确保项目处于 git 版本控制之下，并可随时回滚（`git restore`、revert 或从备份恢复）。
+- 在每轮修复后运行项目自身的测试与构建检查。
+- 切勿在密钥、凭证、`.env` 或任何不允许修改的文件上运行本项目；请在配置中设置 `protected_paths` 予以保护。
+
+使用者需为本项目使用过程中所产生、修改或提交的代码负全部责任。使用本项目即表示你同意：维护者与贡献者不对因使用本项目而导致的任何损失、损害或法律后果承担责任。
+
 ## License
 
 MIT

package/dist/config-loader.js

@@ -48,7 +48,7 @@ export function defaultConfig() {
             auto_merge: false,
         },
         validation: { command_whitelist: [], commands: {} },
-        reviewer: { output_schema_validation: true },
+        reviewer: { output_schema_validation: true, evidence_validation: true },
     };
 }
 /**

package/dist/evidence.js

@@ -0,0 +1,143 @@
+/**
+ * Deterministic code-evidence verification for review findings.
+ *
+ * Mirror of `iterate_harness/iterate/evidence.py` for the iterate-plugin.
+ *
+ * The iterate review loop requires that reviewer subagent findings ANCHOR to
+ * real code instead of speculating. This module enforces it:
+ *
+ * - a finding's `file` must resolve to an existing file under the project root
+ *   (traversal-safe), otherwise evidence is poisoned (`file_not_found`);
+ * - a finding with an explicit line must reference a line that actually exists
+ *   in that file (`line_out_of_range`);
+ * - a whole-file finding (line 0 / undefined) must still reference an existing
+ *   file, so even structural findings cannot point at nothing;
+ * - `readVerified` is a best-effort, NON-gating hint: the plugin's reviewers are
+ *   subagents whose reads are not aggregated here, so it is only set when a
+ *   read set is explicitly provided and never fails the audit.
+ *
+ * Gate rule (user preference): ANY localizable finding with poisoned evidence
+ * flips the whole audit to `passed: false`, so the meta-review forces revision.
+ *
+ * The pure math (`countLines`, `verifyLineBounds`) is separated from the
+ * filesystem half (`verifyFinding`) to stay unit-testable without touching disk.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+/** Sentinel for whole-file findings (line 0 or omitted means the whole file). */
+export const WHOLE_FILE_LINE = 0;
+/** Number of physical lines in `text`. A trailing newline does not add a line. */
+export function countLines(text) {
+    if (text === '')
+        return 0;
+    const parts = text.split(/\r\n|\r|\n/);
+    // 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;
+    return parts.length;
+}
+/** Resolve `root/rel` and reject any path escaping `root` (returns null). */
+export function resolveWithin(root, rel) {
+    const resolved = resolve(root, rel);
+    const rootResolved = resolve(root);
+    if (resolved === rootResolved)
+        return resolved;
+    const prefix = rootResolved.endsWith(sep) ? rootResolved : rootResolved + sep;
+    if (!resolved.startsWith(prefix))
+        return null;
+    return resolved;
+}
+/**
+ * Pure check that `line` (if anchored) exists in `text`.
+ * Whole-file findings (undefined/0) are always bounds-valid.
+ */
+export function verifyLineBounds(line, text) {
+    const lineTotal = countLines(text);
+    if (line === undefined || line === null || line === WHOLE_FILE_LINE) {
+        return { inBounds: true, lineTotal };
+    }
+    if (line < 1)
+        return { inBounds: false, lineTotal };
+    return { inBounds: line <= lineTotal, lineTotal };
+}
+/** Verify a single finding's location against the real filesystem. */
+export function verifyFinding(root, input, opts = {}) {
+    const relFile = input.file ?? '';
+    const line = typeof input.line === 'number' ? input.line : null;
+    const resolved = resolveWithin(root, relFile);
+    if (resolved === null || !existsSync(resolved)) {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    let text;
+    try {
+        text = readFileSync(resolved, 'utf-8');
+    }
+    catch {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    const { inBounds, lineTotal } = verifyLineBounds(line, text);
+    if (!inBounds) {
+        return {
+            file: relFile,
+            line,
+            lineTotal,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'line_out_of_range',
+        };
+    }
+    const outcome = {
+        file: relFile,
+        line,
+        lineTotal,
+        resolvedPath: resolved,
+        verified: true,
+    };
+    if (opts.readSet !== undefined) {
+        outcome.readVerified = opts.readSet.has(resolved);
+    }
+    return outcome;
+}
+/** Attest every finding in a list. */
+export function verifyFindings(root, findings, opts = {}) {
+    const results = findings.map((f) => verifyFinding(root, f, opts));
+    return { checked: results.length, results };
+}
+/** `passed` is true only when no real existence failure exists (read is a hint). */
+export function evidencePassed(audit) {
+    return audit.results.every((r) => r.error === undefined);
+}
+/** Violating (non-grounded) results. */
+export function evidenceViolations(audit) {
+    return audit.results.filter((r) => r.error !== undefined);
+}
+/** Serialize an audit for tool payloads (pure). */
+export function evidenceToPlain(audit) {
+    const computable = audit.results.filter((r) => r.readVerified !== undefined);
+    const readRatio = computable.length === 0
+        ? null
+        : Number((computable.filter((r) => r.readVerified === true).length / computable.length).toFixed(3));
+    return {
+        checked: audit.checked,
+        passed: evidencePassed(audit),
+        violations: audit.results
+            .filter((r) => r.error !== undefined)
+            .map((r) => ({ file: r.file, line: r.line, lineTotal: r.lineTotal, verified: r.verified, error: r.error })),
+        readVerifiedRatio: readRatio,
+    };
+}

package/dist/meta-review.js

@@ -157,9 +157,37 @@ export function metaReviewReport(report) {
 /**
  * Build the final review report: pair the source report with its meta-review
  * verdict and a rolled-up summary. Pure and deterministic.
+ *
+ * `evidence` (an EvidenceAudit produced against the real repo) is the hard
+ * code-evidence gate: every finding whose file/line does not resolve to
+ * 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.
  */
-export function buildFinalReviewReport(report) {
+export function buildFinalReviewReport(report, opts = {}) {
     const meta = metaReviewReport(report);
+    const evidence = opts.evidence ?? null;
+    if (evidence !== null) {
+        meta.checksRun += 1;
+        if (evidence.results.some((r) => r.error !== undefined)) {
+            for (const violation of evidence.results) {
+                if (violation.error === undefined)
+                    continue;
+                const detail = violation.error === 'line_out_of_range'
+                    ? `${violation.line} is beyond this file's ${violation.lineTotal} lines`
+                    : `${violation.file} does not exist at all (verifiable read required)`;
+                meta.issues.push({
+                    code: 'EVIDENCE_VIOLATION',
+                    severity: 'critical',
+                    summary: `Finding references non-existent code: ${violation.file}` +
+                        (violation.line ? `:${violation.line}` : ''),
+                    detail: detail + '. Review results must anchor to real, read code.',
+                });
+            }
+            meta.passed = false;
+            meta.verdict = 'revise';
+        }
+    }
     const summary = report?.summary ?? {};
     const verdict = meta.passed ? 'approved' : 'needs_revision';
     return {

package/dist/review.js

@@ -290,9 +290,17 @@ export function reviewerTaskPrompt(input) {
     else {
         parts.push('This is round 1 — report every issue you find in this dimension.');
     }
+    parts.push('EVIDENCE RULE (mandatory): read every file you report on with the ' +
+        'read_file tool BEFORE judging it. NEVER report a location you did not ' +
+        'actually read — speculation about code you never inspected is a ' +
+        'disqualifying failure, and fabricated line numbers are treated as ' +
+        'poisoned evidence. Anchor every finding to real code.');
     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), ' +
+        'line (REQUIRED positive integer — the exact line you READ for an ' +
+        'anchored, line-targeted issue; use 0 for whole-file/module-level ' +
+        'issues), severity (critical/high/medium/low), summary (one line), ' +
+        'failure_scenario (how/when it fails, backed by the code you actually ' +
+        'read), suggested_fix (the concrete fix), ' +
         `is_atomic (true if the fix is <= ${input.maxLines} lines within a SINGLE file/function, else false).`, `Write summaries and details in ${input.outputLanguage}.`);
     return parts.join('\n');
 }

package/dist/skill-prompt.js

@@ -121,10 +121,11 @@ return {
 
 Key rules for dry-run:
 - **NEVER call a fixer / never edit files / never create branches or worktree.** Reviewers read only.
+- **Every reviewer MUST actually read each file it reports on (read_file) BEFORE judging it, and anchor every finding to a real location. Fabricated file paths or invented line numbers are poisoned evidence and fail the run.** Subagents never report on code they didn't inspect.
 - Each round feeds the already-known findings to reviewers so they hunt NEW issues only → that is what drives convergence.
 - Stop when a round reports 0 new findings (converged) or maxReviewRounds is reached.
 - The report (with per-round convergence stats + suggested fix priorities) is the deliverable.
-- **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The \`finalReport.verdict\` is \`approved\` only when the report passes every check; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
+- **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The meta-review ALSO runs the hard code-evidence gate (default on): every finding's file/line is validated against real files on disk, so any fabricated location surfaces as a critical \`EVIDENCE_VIOLATION\` and flips the verdict to \`needs_revision\`. The \`finalReport.verdict\` is \`approved\` only when the report passes every check AND every finding anchors to real, read code; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
 - Only a single \`report\` entry may be appended to the decision log; nothing else is written.
 
 ### Normal-mode workflow (autonomous closed loop)
@@ -328,11 +329,12 @@ Key rules for normal mode:
 - Close with \`iterate_status\` metrics and surface the convergence indicators (fixed count, remaining architectural count, abort reason) in the final summary.
 
 ### Finding schema (for reviewer agents)
-{ "dimension": string, "file": string (relative path), "line": number (optional),
+{ "dimension": string, "file": string (relative path), "line": number (REQUIRED for line-targeted issues — the exact line you READ; use 0 for whole-file/module-level issues),
   "severity": "critical" | "high" | "medium" | "low", "summary": string (one line),
   "failure_scenario": string (how/when it fails), "suggested_fix": string (the concrete fix),
   "is_atomic": boolean (true if fix ≤ max_lines within a single file/function) }
 Atomic = is_atomic true (single file, single function, ≤ config.atomic.max_lines lines change). Architectural = everything else.
+Every finding MUST reference a file the reviewer actually read (read_file) and a real location — never speculate about code that was never inspected. Fabricated paths/lines are poisoned evidence and fail the meta-review evidence gate.
 
 ### Workflow meta
 Always pass \`meta: { name: "iterate", description: "Autonomous iterate loop" }\`.

package/dist/tools/review.js

@@ -2,6 +2,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRoot } from "../config-loader.js";
 import { buildReviewPlan, buildReviewReport } from "../review.js";
 import { buildFinalReviewReport, metaReviewReport } from "../meta-review.js";
+import { evidenceToPlain, verifyFindings } from "../evidence.js";
 /** Default round cap when neither the arg nor config provides one. */
 const DEFAULT_MAX_REVIEW_ROUNDS = 3;
 /**
@@ -82,6 +83,7 @@ export function registerReviewTool(ctx) {
                     found: { type: 'boolean' },
                     plan: { type: 'json' },
                     report: { type: 'json' },
+                    evidence: { type: 'json' },
                     finalReport: { type: 'json' },
                     error: { type: 'string' },
                 },
@@ -147,12 +149,19 @@ export function registerReviewTool(ctx) {
                     };
                 }
                 const audit = metaReviewReport(source);
-                const finalReport = buildFinalReviewReport(source);
+                // Hard code-evidence gate (default on): every finding's file/line is
+                // validated against real files on disk before folding into the final
+                // verdict. Disable via config `reviewer.evidence_validation: false`.
+                const evidenceEnabled = config.reviewer?.evidence_validation !== false;
+                const findings = Array.isArray(source.findings) ? source.findings : [];
+                const evidence = evidenceEnabled ? verifyFindings(projectRoot, findings) : null;
+                const finalReport = buildFinalReviewReport(source, { evidence });
                 return {
                     operation: 'meta-review',
                     mode,
                     found: true,
                     report: audit,
+                    evidence: evidence ? evidenceToPlain(evidence) : null,
                     finalReport: finalReport,
                 };
             }