iterate-plugin 2.12.1 → 2.12.3

package/dist/tools/review.js

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { loadEffectiveConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { runWithJob } from "../jobs.js";
 import { buildReviewPlan, buildReviewReport, sanitizeRounds, validateRoundsSchema, } from "../review.js";
 import { buildFinalReviewReport, metaReviewReport } from "../meta-review.js";
 import { evidenceToPlain, verifyFindings } from "../evidence.js";
@@ -65,6 +66,15 @@ export function registerReviewTool(ctx) {
                 description: 'For `meta-review`: the ReviewReport JSON (as returned by `aggregate`) to audit for ' +
                     'internal consistency and produce the final review report.',
             },
+            attachments: {
+                type: 'json',
+                description: 'Optional (plan only): image/visual attachments to thread into the review, e.g. ' +
+                    '[{"path":"screens/hits.png","caption":"reproduced layout bug"}]. Each entry: ' +
+                    '{path?, data?, media_type?, caption?} — path resolves relative to the project root, ' +
+                    'data is a base64 payload (media_type e.g. image/png), caption gives human context. ' +
+                    'Injected as a mandatory clause into every dimension reviewer prompt so screenshots/' +
+                    'mockups/failure repros are weighed alongside the code.',
+            },
             fixedCount: {
                 type: 'integer',
                 description: 'For `aggregate` (normal mode only): number of atomic fixes applied so far. ' +
@@ -107,134 +117,145 @@ export function registerReviewTool(ctx) {
             ],
         },
         async execute(args, exec) {
-            const resolved = resolveProjectRootForExec(exec, args.path);
-            if (!resolved.ok) {
-                return { operation: args.operation, error: resolved.reason };
-            }
-            const projectRoot = resolved.root;
-            // 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
-                    ?.known_intentional;
-                // changed-only scope: resolve the changed-file set against
-                // git.target_branch before building the plan so reviewers get the
-                // concrete file list (and the plan auto-falls back to full when there
-                // are no changes). git failures degrade to a full-scope plan.
-                let changedFiles;
-                if (config.review?.scope === 'changed-only') {
-                    const gitScope = await resolveChangedFiles(projectRoot, config.git?.target_branch ?? 'main');
-                    changedFiles = gitScope.changedFiles;
+            const { result } = await runWithJob(ctx, 'iterate-review', `iterate_review ${String(args.operation ?? '')} (${String(args.mode ?? 'dry-run')})`, async () => {
+                const resolved = resolveProjectRootForExec(exec, args.path);
+                if (!resolved.ok) {
+                    return { operation: args.operation, error: resolved.reason };
                 }
-                // Full-codebase review: pre-collect the source inventory so
-                // buildReviewPlan can batch it into per-chunk reviewer tasks
-                // (coverage enforcement).
-                let scopeFiles;
-                if (config.review?.scope === 'full') {
-                    scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' });
-                }
-                const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles });
-                return { operation: 'plan', mode, found: true, plan: plan };
-            }
-            if (args.operation === 'aggregate') {
-                const rawRounds = Array.isArray(args.rounds) ? args.rounds : [];
-                const rounds = rawRounds
-                    .map((r) => {
-                    const rr = r;
-                    const findings = Array.isArray(rr?.findings) ? rr.findings : [];
-                    const readFiles = Array.isArray(rr?.readFiles)
-                        ? rr.readFiles.filter((f) => typeof f === 'string')
+                const projectRoot = resolved.root;
+                // 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
+                        ?.known_intentional;
+                    // changed-only scope: resolve the changed-file set against
+                    // git.target_branch before building the plan so reviewers get the
+                    // concrete file list (and the plan auto-falls back to full when there
+                    // are no changes). git failures degrade to a full-scope plan.
+                    let changedFiles;
+                    if (config.review?.scope === 'changed-only') {
+                        const gitScope = await resolveChangedFiles(projectRoot, config.git?.target_branch ?? 'main');
+                        changedFiles = gitScope.changedFiles;
+                    }
+                    // Full-codebase review: pre-collect the source inventory so
+                    // buildReviewPlan can batch it into per-chunk reviewer tasks
+                    // (coverage enforcement).
+                    let scopeFiles;
+                    if (config.review?.scope === 'full') {
+                        scopeFiles = collectScopeFiles(projectRoot, { scope: 'full' });
+                    }
+                    // Thread image/visual attachments (screenshots/mockups/failure repros)
+                    // into the plan so every reviewer prompt weighs them alongside code.
+                    const attachments = Array.isArray(args.attachments)
+                        ? args.attachments.filter((a) => Boolean(a) &&
+                            typeof a === 'object' &&
+                            ((typeof a.path === 'string' && a.path.length > 0) ||
+                                (typeof a.data === 'string' && a.data.length > 0)))
                         : [];
-                    return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles };
-                })
-                    .filter((r) => r.round > 0);
-                if (rounds.length === 0) {
+                    const plan = buildReviewPlan({ config, mode, maxReviewRounds, knownIntentional, changedFiles, scopeFiles, attachments });
+                    return { operation: 'plan', mode, found: true, plan: plan };
+                }
+                if (args.operation === 'aggregate') {
+                    const rawRounds = Array.isArray(args.rounds) ? args.rounds : [];
+                    const rounds = rawRounds
+                        .map((r) => {
+                        const rr = r;
+                        const findings = Array.isArray(rr?.findings) ? rr.findings : [];
+                        const readFiles = Array.isArray(rr?.readFiles)
+                            ? rr.readFiles.filter((f) => typeof f === 'string')
+                            : [];
+                        return { round: typeof rr?.round === 'number' ? rr.round : 0, findings, readFiles };
+                    })
+                        .filter((r) => 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 ?? [];
+                    // Output schema validation gate (reviewer.output_schema_validation,
+                    // default true): validate every round's findings against the findings
+                    // schema, then drop schema-invalid entries before the deterministic
+                    // core so malformed reviewer output can never crash dedupe/sort or
+                    // leak into fixes. The `schemaValidation` array is surfaced so the
+                    // workflow can retry failing rounds (≤2 times) with a strict-JSON
+                    // nudge. When disabled, non-object entries are still dropped for
+                    // crash-safety.
+                    const schemaEnabled = config.reviewer?.output_schema_validation !== false;
+                    const schemaValidation = schemaEnabled ? validateRoundsSchema(rounds) : null;
+                    const cleanRounds = sanitizeRounds(rounds, schemaValidation);
+                    const report = buildReviewReport({
+                        mode,
+                        goal,
+                        dimensions,
+                        maxReviewRounds,
+                        rounds: cleanRounds,
+                        knownIntentional: args.knownIntentional,
+                        fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
+                    });
                     return {
                         operation: 'aggregate',
                         mode,
-                        error: 'rounds must be a non-empty array of {round, findings}.',
+                        report: report,
+                        schemaValidation: (schemaValidation ?? null),
                     };
                 }
-                const maxReviewRounds = args.maxReviewRounds ?? config.max_rounds ?? DEFAULT_MAX_REVIEW_ROUNDS;
-                const goal = args.goal ?? config.goal ?? '';
-                const dimensions = config.dimensions ?? [];
-                // Output schema validation gate (reviewer.output_schema_validation,
-                // default true): validate every round's findings against the findings
-                // schema, then drop schema-invalid entries before the deterministic
-                // core so malformed reviewer output can never crash dedupe/sort or
-                // leak into fixes. The `schemaValidation` array is surfaced so the
-                // workflow can retry failing rounds (≤2 times) with a strict-JSON
-                // nudge. When disabled, non-object entries are still dropped for
-                // crash-safety.
-                const schemaEnabled = config.reviewer?.output_schema_validation !== false;
-                const schemaValidation = schemaEnabled ? validateRoundsSchema(rounds) : null;
-                const cleanRounds = sanitizeRounds(rounds, schemaValidation);
-                const report = buildReviewReport({
-                    mode,
-                    goal,
-                    dimensions,
-                    maxReviewRounds,
-                    rounds: cleanRounds,
-                    knownIntentional: args.knownIntentional,
-                    fixedCount: typeof args.fixedCount === 'number' ? args.fixedCount : undefined,
-                });
-                return {
-                    operation: 'aggregate',
-                    mode,
-                    report: report,
-                    schemaValidation: (schemaValidation ?? null),
-                };
-            }
-            if (args.operation === 'meta-review') {
-                const source = args.report;
-                if (!source || typeof source !== 'object') {
+                if (args.operation === 'meta-review') {
+                    const source = args.report;
+                    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);
+                    // 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;
+                    // Prompt-informative coverage: compare the reviewer's self-reported
+                    // reads against the assigned scope inventory (never flips the
+                    // verdict). Disable via config `reviewer.coverage_validation: false`.
+                    const coverageEnabled = config.reviewer?.coverage_validation !== false;
+                    let coverage = null;
+                    if (coverageEnabled) {
+                        const assigned = collectScopeFiles(projectRoot, {
+                            scope: config.review?.scope === 'changed-only' ? 'changed-only' : 'full',
+                        });
+                        const readFiles = Array.isArray(source.readFiles)
+                            ? source.readFiles
+                            : null;
+                        if (readFiles && readFiles.length > 0) {
+                            coverage = computeCoverage(assigned, readFiles);
+                        }
+                    }
+                    const finalReport = buildFinalReviewReport(source, { evidence, coverage });
                     return {
                         operation: 'meta-review',
                         mode,
-                        error: 'report must be a ReviewReport JSON object (as returned by `aggregate`).',
+                        found: true,
+                        report: audit,
+                        evidence: evidence ? evidenceToPlain(evidence) : null,
+                        coverage: coverage ? coverageToDict(coverage) : null,
+                        finalReport: finalReport,
                     };
                 }
-                const audit = metaReviewReport(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;
-                // Prompt-informative coverage: compare the reviewer's self-reported
-                // reads against the assigned scope inventory (never flips the
-                // verdict). Disable via config `reviewer.coverage_validation: false`.
-                const coverageEnabled = config.reviewer?.coverage_validation !== false;
-                let coverage = null;
-                if (coverageEnabled) {
-                    const assigned = collectScopeFiles(projectRoot, {
-                        scope: config.review?.scope === 'changed-only' ? 'changed-only' : 'full',
-                    });
-                    const readFiles = Array.isArray(source.readFiles)
-                        ? source.readFiles
-                        : null;
-                    if (readFiles && readFiles.length > 0) {
-                        coverage = computeCoverage(assigned, readFiles);
-                    }
-                }
-                const finalReport = buildFinalReviewReport(source, { evidence, coverage });
                 return {
-                    operation: 'meta-review',
-                    mode,
-                    found: true,
-                    report: audit,
-                    evidence: evidence ? evidenceToPlain(evidence) : null,
-                    coverage: coverage ? coverageToDict(coverage) : null,
-                    finalReport: finalReport,
+                    operation: args.operation,
+                    error: `Unknown operation "${args.operation}". Use "plan", "aggregate", or "meta-review".`,
                 };
-            }
-            return {
-                operation: args.operation,
-                error: `Unknown operation "${args.operation}". Use "plan", "aggregate", or "meta-review".`,
-            };
+            });
+            return result;
         },
     }));
 }