pi-workflow-engine 0.12.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -1,34 +1,29 @@
+import { challengeFindings, parseChallengeArgs } from "../src/advisory-challenge.ts";
 import { Type } from "typebox";
 import {
-  AdvisoryCandidatesSchema,
-  AdvisoryReportSchema,
-  AdvisoryVerdictSchema,
-  type AdvisoryCandidate,
-  type AdvisoryVerdict,
-} from "../src/advisory-schema.ts";
-import {
-  backfillAdvisoryFindings,
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  concludeLensReview,
+  emptyAdvisoryReport,
+  finishAdvisoryReport,
   formatEvidence,
   formatLocation,
-  normalizePath,
-  primaryLocation,
-  publishVerifiedKeptProgress,
-  recordVerdictProgress,
+  runLensVerificationPipeline,
+  EMPTY_LENS_REVIEW_STATS,
   verdictConfidence,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import { compactResults } from "../src/concurrency.ts";
 import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../src/review-diff-target.ts";
-import { buildCodeReviewScopeBlock, dedupeCodeReviewCandidates } from "../src/review/code-review-orchestration.ts";
+import { changedLines, diffAnchor } from "../src/review/review-diff-lines.ts";
 import type { ReviewContext } from "../src/review/review-report.ts";
-import { captureReviewMaterial, type ReviewMaterialCaptureResult } from "../src/review/review-snapshot.ts";
-import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
+import { captureReviewMaterial } from "../src/review/review-snapshot.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
   name: "code-review",
   description: "Fan-out review of the branch's open PR (or branch vs main): scope → per-angle find → independent verify → synthesize.",
-  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Synthesize" }],
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
 // ─── Schemas (the contracts that make orchestration plain code) ───
@@ -39,85 +34,50 @@ const ScopeSchema = Type.Object({
   conventions: Type.Optional(Type.String({ description: "Relevant AGENTS.md / project conventions" })),
 });
 
-type Candidate = AdvisoryCandidate;
-
-interface Angle {
-  label: string;
-  kind: "bug" | "cleanup";
-  text: string;
-}
-interface Verified extends Candidate {
-  verdict: AdvisoryVerdict["verdict"];
-  evidence: string[];
-  kind: "bug" | "cleanup";
-}
-
 // The review lenses — this is the part you customise to your codebase's real failure modes.
-const ANGLES: Angle[] = [
-  { label: "logic-bugs", kind: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
-  { label: "error-paths", kind: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
-  { label: "edge-cases", kind: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
-  { label: "simplification", kind: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
-  { label: "conventions", kind: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
+const ANGLES: AdvisoryLens[] = [
+  { label: "logic-bugs", category: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
+  { label: "error-paths", category: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
+  { label: "edge-cases", category: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
+  { label: "simplification", category: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
+  { label: "conventions", category: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
 ];
 
-const TOOLS = DEFAULT_ADVISORY_TOOLS;
-const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_ANGLE = 6;
 
-/** Parse a unified diff into the set of added/changed new-file line numbers per file. */
-export function changedLines(diff: string): Map<string, Set<number>> {
-  const byFile = new Map<string, Set<number>>();
-  let file: string | null = null;
-  let newLine = 0;
-  for (const raw of diff.split("\n")) {
-    if (raw.startsWith("+++ ")) {
-      const path = raw.slice(4).trim();
-      file = path === "/dev/null" ? null : normalizePath(path);
-      if (file && !byFile.has(file)) byFile.set(file, new Set());
-    } else if (raw.startsWith("@@")) {
-      const match = /\+(\d+)/.exec(raw);
-      newLine = match ? Number(match[1]) : 0;
-    } else if (file === null || raw.startsWith("---") || raw.startsWith("\\")) {
-      // file header, deletion, or "No newline" marker — record nothing
-    } else if (raw.startsWith("+")) {
-      byFile.get(file)!.add(newLine++);
-    } else if (!raw.startsWith("-")) {
-      newLine++; // context line advances the new-file counter; deletions do not
-    }
-  }
-  return byFile;
-}
-
-/** Is a finding inside the diff? File-level findings count if the file changed; ±1 line of fuzz. */
-export function inDiff(changed: Map<string, Set<number>>, file: string, line?: number): boolean {
-  const set = changed.get(normalizePath(file));
-  if (!set) return false;
-  if (line == null) return true;
-  return set.has(line) || set.has(line - 1) || set.has(line + 1);
+const DIFF_EMBED_CAP = 60_000;
+
+export function buildCodeReviewScopeBlock(input: {
+  readonly diffCommand: string;
+  readonly files: readonly string[];
+  readonly summary: string;
+  readonly conventions?: string;
+  readonly diffText: string;
+  readonly target: string;
+}): string {
+  const diffBlock = input.diffText
+    ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
+        input.diffText.length > DIFF_EMBED_CAP
+          ? `${input.diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${input.diffCommand}\` for the full diff)`
+          : input.diffText
+      }\n\`\`\`\n`
+    : "";
+  return (
+    `## Diff command\n${input.diffCommand}\n\n## Changed files\n${input.files.map((file) => `- ${file}`).join("\n")}\n\n` +
+    `## Summary\n${input.summary}\n\n## Conventions\n${input.conventions ?? "(none noted)"}\n` +
+    diffBlock +
+    (input.target ? `\n## User instructions (verbatim)\n${input.target}\n` : "")
+  );
 }
 
 export interface CodeReviewDependencies {
-  readonly captureReviewMaterial?: (
-    target: Parameters<typeof captureReviewMaterial>[0],
-    cwd: string,
-    signal?: AbortSignal,
-  ) => Promise<ReviewMaterialCaptureResult>;
+  readonly captureReviewMaterial?: typeof captureReviewMaterial;
 }
 
 export default async function run(api: WorkflowApi, dependencies: CodeReviewDependencies = {}): Promise<unknown> {
-  const { agent, parallel, phase, log, progress, args, cwd, signal } = api;
-  const target = args.trim();
-  let fileCount = 0;
-  let rawCandidateCount = 0;
-  let droppedCandidateCount = 0;
-  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
-    files: fileCount,
-    candidates: rawCandidateCount,
-    verified,
-    kept,
-    dropped: droppedCandidateCount,
-  });
+  const { agent, phase, log, progress, args, cwd, signal } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const target = challengeConfig.args;
 
   // ─── Phase 0: Scope ───
   phase("Scope");
@@ -138,14 +98,9 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       "Then: list the changed files, summarize the change in one paragraph (mention the PR if one was found), " +
       "and read any relevant AGENTS.md or project docs noting conventions a reviewer should know.\n" +
       "Return diffCommand exactly as a reviewer should run it. Structured output only.",
-    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
-  if (!scope) {
-    return { summary: "No changes found to review.", findings: [], nextSteps: ["Provide a PR, ref range, or changed files to review."], stats: makeStats(0, 0) };
-  }
-
-  fileCount = scope.files.length;
   progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
   const diffTarget = parseAllowedDiffCommand(scope.diffCommand);
   if ("error" in diffTarget) {
@@ -153,11 +108,11 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
   }
   const diffCommand = formatReviewDiffTarget(diffTarget);
   progress({ type: "summary", key: "diffCommand", value: diffCommand });
-  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "counter", key: "files", label: "files", value: scope.files.length });
+  const noChanges = (summary: string, nextSteps = ["Provide a PR, ref range, or changed files to review."]) =>
+    finishAdvisoryReport(emptyAdvisoryReport(summary, nextSteps, { ...EMPTY_LENS_REVIEW_STATS, files: scope.files.length }), []);
 
-  if (scope.files.length === 0) {
-    return { summary: "No changes found to review.", findings: [], nextSteps: ["Provide a PR, ref range, or changed files to review."], stats: makeStats(0, 0) };
-  }
+  if (scope.files.length === 0) return noChanges("No changes found to review.");
 
   log(`${scope.files.length} changed files`);
 
@@ -169,6 +124,14 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
   const diffText = reviewMaterial.diff;
   const changed = changedLines(diffText);
   progress({ type: "summary", key: "diffBytes", value: Buffer.byteLength(diffText) });
+  // Findings anchor only on files with a new-side text hunk; without one, skip the finder fan-out.
+  if (changed.size === 0) {
+    if (!diffText.trim()) return noChanges(`No changes found to review: \`${diffCommand}\` has no added or modified files.`);
+    return noChanges(
+      `Nothing to review line by line: \`${diffCommand}\` only deletes or renames files, changes file modes, or touches binary files; there are no added lines to anchor findings on.`,
+      ["Inspect the deleted, renamed, mode-changed or binary files directly; code-review anchors findings on added lines only."],
+    );
+  }
   if (reviewMaterial.snapshot.status === "unavailable") {
     log(`review snapshot unavailable (${reviewMaterial.snapshot.reason}) — patch previews will be unavailable`);
   }
@@ -184,7 +147,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       : {}),
   };
 
-  const scopeBlock = buildCodeReviewScopeBlock({
+  const scopeBlock = `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
     diffCommand,
     files: scope.files,
     summary: scope.summary,
@@ -193,113 +156,48 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
     target,
   });
 
-  // ─── Find barrier → dedup → Verify ───
-  phase("Find");
-  const perAngle = await parallel(
-    ANGLES.map((angle) => async () => {
-      const found = await agent(
-        `## Code-review finder — ${angle.label}\n\n${scopeBlock}\n` +
-          `Review the change through ONLY this lens:\n${angle.text}\n` +
-          "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
-          "You may read surrounding files for context, but never report issues in unchanged code. " +
-          `Surface up to ${PER_ANGLE} candidates. Use category exactly "${angle.kind}". Each candidate must include a one-line summary, ` +
-          "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
-          "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
-        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, toolHints: TOOL_HINTS, profile: "small", schema: AdvisoryCandidatesSchema },
-      );
-      const raw = (found?.candidates ?? []).slice(0, PER_ANGLE);
-      rawCandidateCount += raw.length;
-      progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
-      const bounded = raw.filter((candidate) => inDiff(changed, primaryLocation(candidate).file, primaryLocation(candidate).line));
-      const dropped = raw.length - bounded.length;
-      if (dropped > 0) {
-        droppedCandidateCount += dropped;
-        progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-        log(`find:${angle.label}: dropped ${dropped} out-of-diff candidate(s)`);
-      }
-      for (const candidate of bounded) {
-        progress({
-          type: "lane_item",
-          lane: "Candidates",
-          title: candidate.summary,
-          subtitle: formatLocation(candidate),
-          status: "pending",
-          details: candidate.impact,
-        });
-      }
-      return { angle, candidates: bounded };
-    }),
-  );
-
-  // Dedup after all finders complete so verifier agents cannot consume the global cap before full candidate discovery.
-  const novel = dedupeCodeReviewCandidates(compactResults(perAngle));
-
-  phase("Verify");
-  const verdicts = await parallel(
-    novel.map(({ angle, candidate }) => async (): Promise<Verified | null> => {
-      const location = primaryLocation(candidate);
-      const judged = await agent(
-        `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-          `Location: ${formatLocation(candidate)}\n` +
-          `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
-          "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / REFUTED) " +
-          "with evidence quoting the line(s). Default toward REFUTED if you cannot substantiate it. Structured output only.",
-        {
-          phase: "Verify",
-          label: `verify:${location.file.split("/").pop() ?? location.file}`,
-          tools: TOOLS,
-          toolHints: TOOL_HINTS,
-          profile: "small",
-          schema: AdvisoryVerdictSchema,
-        },
-      );
-      if (!judged) return null;
-      recordVerdictProgress(progress, candidate, judged);
-      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind };
-    }),
-  );
-
-  const verified = compactResults(verdicts);
-  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
-  const stats = makeStats(verified.length, surviving.length);
-  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
-
-  if (surviving.length === 0) {
-    return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext };
-  }
-
-  // ─── Synthesize: rank, merge, report ───
-  phase("Synthesize");
-  const rank = (finding: Verified): number => (finding.kind === "cleanup" ? 2 : 0) + (finding.verdict === "PLAUSIBLE" ? 1 : 0);
-  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
-  const block = ranked
-    .map(
-      (finding, index) =>
-        `### [${index}] ${formatLocation(finding)} (${finding.verdict}${finding.kind === "cleanup" ? ", cleanup" : ""})\n` +
-        `Category: ${finding.kind}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
-        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}`,
-    )
-    .join("\n\n");
-
-  const report = await agent(
-    `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
-      "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
-      "Return summary, findings, and nextSteps. For each finding: category must be bug or cleanup; severity is impact level (low/medium/high), not category; " +
-      "confidence must be high for CONFIRMED and medium for PLAUSIBLE; copy locations and evidence arrays from the verified finding; impact is the concrete failure or maintenance scenario; recommendation is an advisory fix direction, not an edit. Structured output only.",
-    {
-      phase: "Synthesize",
-      label: "synthesize",
-      tools: [],
-      profile: "medium",
-      resume: "read-only",
-      schema: AdvisoryReportSchema,
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    lenses: ANGLES,
+    perLens: PER_ANGLE,
+    boundCandidate: (candidate, lens) => {
+      const reviewAnchor = candidate.reviewAnchor
+        ? diffAnchor(changed, candidate.reviewAnchor)
+        : candidate.locations.map((location) => diffAnchor(changed, location)).find((anchor) => anchor !== undefined);
+      return reviewAnchor ? { ...candidate, category: lens.category, reviewAnchor } : undefined;
     },
-  );
-
-  if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats, reviewContext };
-
-  const findings = backfillAdvisoryFindings(report.findings, ranked, {
-    impact: "Impact not restated by synthesis.",
+    finderPrompt: (lens) =>
+      `## Code-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      `Review the change through ONLY this lens:\n${lens.text}\n` +
+      "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
+      "Set reviewAnchor to the changed line causing the issue; locations and discoveryEvidence may include unchanged callers and other files. " +
+      `Surface up to ${PER_ANGLE} candidates. Use category exactly "${lens.category}". Each candidate must include a one-line summary, ` +
+      "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
+      "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\n` +
+      `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
+      "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
+      "with evidence quoting the line(s). Use NOT_SUBSTANTIATED when evidence is insufficient; use REFUTED only for concrete disproof. Structured output only.",
   });
-  return { ...report, findings, stats, reviewContext };
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
+  const report = await concludeLensReview(api, pipelineResult, verified, {
+    files: scope.files.length,
+    rank,
+    formatFinding: (finding, index) =>
+      `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}${finding.category === "cleanup" ? ", cleanup" : ""})\n` +
+      `Category: ${finding.category}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
+      `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}`,
+    empty: { summary: "No findings survived verification.", nextSteps: ["No code-review action is recommended from this workflow run."] },
+    synthesisPrompt: (block, ranked) =>
+      `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
+      "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
+      "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only.",
+  });
+  return { ...report, reviewContext };
+}
+
+function rank(finding: AdvisoryVerified): number {
+  return (finding.category === "cleanup" ? 2 : 0) + (finding.verdict !== "CONFIRMED" ? 1 : 0);
 }