@jameslovespancakes/pi-plus 1.0.10 → 1.0.12

package/src/domains/workflows/runtime/review/review-fix-workflow.ts

@@ -0,0 +1,153 @@
+import { initialPatchValidation, PatchEvaluationSchema, validateCandidatePatch, type PatchValidation } from "./patch-validation.ts";
+import { isFatalWorkflowError } from "../cancellation.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
+import type { ParallelSettledError } from "../concurrency.ts";
+import type { IsolatedAgentResult, LoadedWorkflow, WorkflowApi, WorkflowModule } from "../types.ts";
+import type { WorktreeBaseline } from "../worktree.ts";
+import { loadWorkflow } from "../workflow-module.ts";
+import { serializeReviewIssue, type ReviewIssue } from "./review-issues.ts";
+import type { ReviewContext } from "./review-report.ts";
+import { serializeReviewContext } from "./review-report.ts";
+
+const REVIEW_FIX_PHASE = "Generate patch previews";
+const REVIEW_FIX_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+export interface ReviewFixPreview {
+  readonly findingId: string;
+  readonly result: string;
+  readonly patch: string;
+  readonly changed: boolean;
+  readonly validation: PatchValidation;
+}
+
+export interface ReviewFixFailure {
+  readonly findingId: string;
+  readonly error: ParallelSettledError;
+}
+
+export type ReviewFixOutcome = ReviewFixPreview | ReviewFixFailure;
+
+export interface ReviewFixWorkflowResult {
+  readonly summary: string;
+  readonly fixes: readonly ReviewFixOutcome[];
+}
+
+export type ReviewFixWorkflowApi = Pick<WorkflowApi, "agent" | "parallel" | "phase" | "cwd" | "signal">;
+
+/** Build an ephemeral workflow that generates one isolated patch preview per finding. */
+export function createReviewFixWorkflow(
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  baseline: WorktreeBaseline,
+): LoadedWorkflow {
+  const module: WorkflowModule = {
+    meta: {
+      name: "code-review-fix-previews",
+      description: "Generate isolated patch previews for selected code-review findings.",
+      phases: [{ title: REVIEW_FIX_PHASE }, { title: "Validate patch previews" }],
+    },
+    default: (api) => runReviewFixWorkflow(api, issues, context, baseline),
+  };
+  return loadWorkflow(
+    module,
+    {
+      kind: "unverifiable",
+      reason: "ephemeral review-fix workflows capture runtime findings and do not have immutable module provenance",
+    },
+    baseline,
+  );
+}
+
+export function buildFixAgentPrompt(issue: ReviewIssue, context: ReviewContext | undefined): string {
+  return `Generate a patch preview for exactly one verified code-review finding in your disposable git worktree.
+
+Selected finding JSON:
+\`\`\`json
+${JSON.stringify({ context: serializeReviewContext(context), issue: serializeReviewIssue(issue) })}
+\`\`\`
+
+Instructions:
+- Inspect the finding and cited evidence before editing.
+- Make the smallest edit that addresses only this finding.
+- Preserve unrelated user changes and avoid broad refactors.
+- Run focused validation if an appropriate local check is available.
+- Do not create commits or branches; the engine captures your worktree diff automatically.
+- Do not post GitHub PR comments or any upstream review comments.
+- Finish with a concise summary of changed files and validation results; this text is returned alongside the captured patch.`;
+}
+
+export async function runReviewFixWorkflow(
+  api: ReviewFixWorkflowApi,
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  baseline: WorktreeBaseline,
+): Promise<ReviewFixWorkflowResult> {
+  api.phase(REVIEW_FIX_PHASE);
+  const settled = await api.parallel(
+    issues.map((issue) => async (): Promise<ReviewFixPreview> => {
+      const isolated = await api.agent(buildFixAgentPrompt(issue, context), {
+        isolation: "worktree",
+        label: `fix:${issue.id}`,
+        phase: REVIEW_FIX_PHASE,
+        profile: "medium",
+        cacheKey: `review-fix:${issue.id}`,
+        tools: [...REVIEW_FIX_TOOLS],
+        toolHints: ["search"],
+      });
+      const validation = await evaluateReviewFix(api, { issue, context, baseline, isolated });
+      return {
+        findingId: issue.id,
+        result: isolated.result,
+        patch: isolated.patch,
+        changed: isolated.changed,
+        validation,
+      };
+    }),
+    { settled: true },
+  );
+
+  const fixes = settled.map((entry, index): ReviewFixOutcome =>
+    entry.ok ? entry.value : { findingId: issues[index]!.id, error: entry.error },
+  );
+  const successful = fixes.filter(isReviewFixPreview);
+  const count = (status: PatchValidation["status"]) => successful.filter((fix) => fix.validation.status === status).length;
+  const failed = fixes.length - successful.length;
+
+  return {
+    summary: `${count("verified")} verified candidate(s); ${count("rejected")} rejected; ${count("blocked")} blocked; ${count("no-patch")} no-patch; ${failed} attempt(s) failed.`,
+    fixes,
+  };
+}
+
+function isReviewFixPreview(outcome: ReviewFixOutcome): outcome is ReviewFixPreview {
+  return "patch" in outcome;
+}
+
+async function evaluateReviewFix(api: ReviewFixWorkflowApi, input: {
+  issue: ReviewIssue; context: ReviewContext | undefined; baseline: WorktreeBaseline; isolated: IsolatedAgentResult<string>;
+}): Promise<PatchValidation> {
+  const { issue, context, baseline, isolated } = input;
+  const validation = initialPatchValidation(baseline, isolated.baselineOid, isolated.patch);
+  if (!isolated.patch.trim()) return validation;
+  if (!isolated.baselineOid) return { ...validation, reason: "Candidate has no recorded baseline identity." };
+  if (!context?.snapshot) return { ...validation, reason: "Reviewed snapshot identity is unavailable." };
+  if (validation.baselineFingerprint !== context.snapshot.baselineFingerprint) {
+    return { ...validation, status: "rejected", reason: "Stale reviewed baseline identity." };
+  }
+  try {
+    const evaluated = await api.agent(
+      `Independently evaluate a candidate repair. Your fresh worktree contains the exact reviewed baseline plus the captured patch. The implementer's report is not validation evidence. Inspect the finding, callers and tests. Reject incorrect repairs; return blocked if required validation is unavailable. Select at most six focused deterministic checks with executable and argument arrays. Require at least one meaningful behavior check. If a regression test is applicable, supply a test-only baselinePatch and specific expectedFailure so the engine can prove it fails before the repair and passes after. Do not edit, install dependencies, commit or change branches. The engine will execute checks independently.\nFinding: ${JSON.stringify(serializeReviewIssue(issue))}\nBaseline: ${isolated.baselineOid}\nPatch SHA-256: ${validation.patchHash}\nPatch:\n${isolated.patch}`,
+      { isolation: "worktree", candidatePatch: { baselineOid: isolated.baselineOid, patch: isolated.patch },
+        label: `evaluate:${issue.id}`, phase: "Validate patch previews", profile: "medium", resume: "off",
+        tools: ["read", "bash", "grep", "find", "ls"], toolHints: ["search"], schema: PatchEvaluationSchema },
+    );
+    if (evaluated.baselineOid !== isolated.baselineOid || evaluated.patch !== isolated.patch) {
+      return { ...validation, status: "rejected", reason: "Evaluator changed the candidate or used a different baseline.", evaluation: evaluated.result };
+    }
+    return await validateCandidatePatch({ cwd: api.cwd, baseline, expectedFingerprint: context.snapshot.baselineFingerprint,
+        baselineOid: isolated.baselineOid, patch: isolated.patch, evaluation: evaluated.result, signal: api.signal });
+  } catch (error) {
+    if (isFatalWorkflowError(error, api.signal)) throw error;
+    return { ...validation, status: "blocked", reason: unknownErrorMessage(error) };
+  }
+}

package/src/domains/workflows/runtime/review/review-format.ts

@@ -0,0 +1,133 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { truncateDisplay, type WorkflowThemeColor } from "../ui/workflow-format.ts";
+import { formatIssueLocation, type ReviewIssue } from "./review-issues.ts";
+
+export interface RenderIssuesTableOptions {
+  readonly maxRows?: number;
+}
+
+const DEFAULT_MAX_ROWS = 12;
+const ID_WIDTH = 4;
+const SEVERITY_WIDTH = 6;
+const CONFIDENCE_WIDTH = 6;
+const CATEGORY_WIDTH = 8;
+const LOCATION_WIDTH = 30;
+const SUMMARY_WIDTH = 58;
+
+export function renderIssuesTable(issues: readonly ReviewIssue[], theme: Theme, options: RenderIssuesTableOptions = {}): string {
+  const maxRows = options.maxRows ?? DEFAULT_MAX_ROWS;
+  const visible = maxRows >= 0 ? issues.slice(0, maxRows) : issues;
+  const lines = [
+    renderRow(["ID", "Sev", "Conf", "Cat", "Location", "Summary"], theme.fg("dim", "│"), theme, true),
+    theme.fg("dim", renderSeparator()),
+  ];
+
+  for (const issue of visible) {
+    lines.push(
+      renderRow(
+        [
+          issue.id,
+          issue.finding.severity,
+          issue.finding.confidence,
+          issue.finding.category,
+          formatIssueLocation(issue),
+          issue.finding.summary,
+        ],
+        theme.fg("dim", "│"),
+        theme,
+        false,
+        issue,
+      ),
+    );
+  }
+
+  if (issues.length > visible.length) {
+    lines.push(theme.fg("dim", `… ${issues.length - visible.length} more finding(s)`));
+  }
+
+  return lines.join("\n");
+}
+
+export function renderIssueDetails(issue: ReviewIssue, theme: Theme): string {
+  return renderIssueDetailLines(issue, theme, 120).join("\n");
+}
+
+export function renderIssueDetailLines(issue: ReviewIssue, theme: Theme, width: number): string[] {
+  const finding = issue.finding;
+  const metadata = `${finding.category} · severity ${finding.severity} · confidence ${finding.confidence}${finding.verdict ? ` · ${finding.verdict}` : ""}`;
+  const lines = [`${theme.fg("accent", issue.id)} ${theme.fg("text", finding.summary)}`];
+  lines.push(...fieldLines("Metadata", metadata, width, theme));
+  if (finding.sourceCandidateIds?.length) lines.push(...fieldLines("Sources", finding.sourceCandidateIds.join(", "), width, theme));
+  lines.push(...fieldLines("Location", formatIssueLocation(issue), width, theme, "accent"));
+  lines.push(...fieldLines("Impact", finding.impact, width, theme));
+  lines.push(...fieldLines("Evidence", finding.evidence.join("; ") || "(none cited)", width, theme));
+  lines.push(...fieldLines("Recommendation", finding.recommendation, width, theme));
+  return lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(10, width)));
+}
+
+function fieldLines(label: string, value: string, width: number, theme: Theme, valueColor: WorkflowThemeColor = "muted"): string[] {
+  const prefix = `  ${theme.fg("dim", `${label}:`)}`;
+  const separator = " ";
+  const valueText = theme.fg(valueColor, value);
+  const available = Math.max(10, width - visibleWidth(`${label}:  `) - 2);
+  const wrapped = wrapTextWithAnsi(valueText, available);
+  if (wrapped.length === 0) return [`${prefix}${separator}`];
+  const continuation = " ".repeat(visibleWidth(`${label}:  `) + 2);
+  return wrapped.map((line, index) => (index === 0 ? `${prefix}${separator}${line}` : `${continuation}${line}`));
+}
+
+function renderRow(
+  cells: readonly [string, string, string, string, string, string],
+  separator: string,
+  theme: Theme,
+  header: boolean,
+  issue?: ReviewIssue,
+): string {
+  const rendered = [
+    cell(cells[0], ID_WIDTH),
+    colorCell(cell(cells[1], SEVERITY_WIDTH), header ? "dim" : severityColor(issue?.finding.severity ?? "low"), theme),
+    colorCell(cell(cells[2], CONFIDENCE_WIDTH), header ? "dim" : confidenceColor(issue?.finding.confidence ?? "low"), theme),
+    cell(cells[3], CATEGORY_WIDTH),
+    cell(cells[4], LOCATION_WIDTH),
+    cell(cells[5], SUMMARY_WIDTH),
+  ];
+  if (header) {
+    return rendered.map((entry) => theme.fg("dim", entry)).join(` ${separator} `);
+  }
+  return rendered.join(` ${separator} `);
+}
+
+function cell(value: string, width: number): string {
+  return truncateDisplay(value, width).padEnd(width, " ");
+}
+
+function colorCell(value: string, color: WorkflowThemeColor, theme: Theme): string {
+  return theme.fg(color, value);
+}
+
+function renderSeparator(): string {
+  return [ID_WIDTH, SEVERITY_WIDTH, CONFIDENCE_WIDTH, CATEGORY_WIDTH, LOCATION_WIDTH, SUMMARY_WIDTH].map((width) => "─".repeat(width)).join("─┼─");
+}
+
+function severityColor(severity: ReviewIssue["finding"]["severity"]): WorkflowThemeColor {
+  switch (severity) {
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}
+
+function confidenceColor(confidence: ReviewIssue["finding"]["confidence"]): WorkflowThemeColor {
+  switch (confidence) {
+    case "high":
+      return "success";
+    case "medium":
+      return "warning";
+    case "low":
+      return "muted";
+  }
+}

package/src/domains/workflows/runtime/review/review-handoff.ts

@@ -0,0 +1,38 @@
+import { serializeReviewIssue, type ReviewIssue } from "./review-issues.ts";
+import type { ReviewContext } from "./review-report.ts";
+import { serializeReviewContext } from "./review-report.ts";
+
+export function buildCommentHandoffPrompt(
+  issues: readonly ReviewIssue[],
+  context: ReviewContext | undefined,
+  verifiedHead: string,
+  reason: string,
+): string {
+  return `Use the workflow-code-review-actions skill if available.
+
+Mode: post inline GitHub PR comments for selected code-review findings.
+
+Fallback reason: ${reason}
+
+Selected findings JSON:
+\`\`\`json
+${JSON.stringify(toHandoffPayload(issues, context))}
+\`\`\`
+
+Instructions:
+- Do not edit files or make code changes.
+- Prefer installed GitHub MCP/tools if present; otherwise use the GitHub CLI (gh).
+- Before posting, resolve the current PR head and require it to equal the verified reviewed head \`${verifiedHead}\`; stop if it differs.
+- With gh, resolve the PR using \`gh pr view\` and \`gh repo view\`, then call \`gh api repos/{owner}/{repo}/pulls/{number}/comments\` with \`commit_id\`, \`path\`, \`line\`, and \`side=RIGHT\`.
+- Do not post duplicate comments.
+- Do not post line-less findings as inline comments.
+- Ask the user if the upstream PR cannot be identified.
+- Summarize posted, skipped, and failed comments when done.`;
+}
+
+function toHandoffPayload(issues: readonly ReviewIssue[], context: ReviewContext | undefined) {
+  return {
+    context: serializeReviewContext(context),
+    issues: issues.map(serializeReviewIssue),
+  };
+}

package/src/domains/workflows/runtime/review/review-issues.ts

@@ -0,0 +1,87 @@
+import type { AdvisoryFinding, AdvisoryReport } from "../advisory-schema.ts";
+
+export type ReviewIssueAction = "fix" | "comment" | "close";
+
+export interface ReviewIssueSelection {
+  readonly action: ReviewIssueAction;
+  readonly issueIds: readonly string[];
+}
+
+export interface ReviewIssue {
+  readonly id: string;
+  readonly index: number;
+  readonly workflowName: string;
+  readonly file?: string;
+  readonly line?: number;
+  readonly symbol?: string;
+  readonly finding: AdvisoryFinding;
+}
+
+/** Stable prompt-facing representation shared by review follow-up actions. */
+export interface SerializedReviewIssue {
+  readonly id: string;
+  readonly summary: string;
+  readonly category: string;
+  readonly severity: string;
+  readonly confidence: string;
+  readonly location: {
+    readonly file?: string;
+    readonly line?: number;
+    readonly symbol?: string;
+    readonly display: string;
+  };
+  readonly impact: string;
+  readonly evidence: readonly string[];
+  readonly recommendation: string;
+}
+
+export function toReviewIssues(name: string, report: Pick<AdvisoryReport, "findings">): ReviewIssue[] {
+  return report.findings.map((finding, index) => {
+    const location = finding.reviewAnchor ?? finding.locations[0];
+    return {
+      id: formatIssueId(index),
+      index,
+      workflowName: name,
+      file: location?.file,
+      line: location?.line,
+      symbol: location?.symbol,
+      finding,
+    };
+  });
+}
+
+export function formatIssueLocation(issue: ReviewIssue): string {
+  if (!issue.file) return "(no location)";
+  const line = issue.line != null ? `:${issue.line}` : "";
+  const symbol = issue.symbol ? ` (${issue.symbol})` : "";
+  return `${issue.file}${line}${symbol}`;
+}
+
+export function serializeReviewIssue(issue: ReviewIssue): SerializedReviewIssue {
+  return {
+    id: issue.id,
+    summary: issue.finding.summary,
+    category: issue.finding.category,
+    severity: issue.finding.severity,
+    confidence: issue.finding.confidence,
+    location: {
+      file: issue.file,
+      line: issue.line,
+      symbol: issue.symbol,
+      display: formatIssueLocation(issue),
+    },
+    impact: issue.finding.impact,
+    evidence: issue.finding.evidence,
+    recommendation: issue.finding.recommendation,
+  };
+}
+
+export function isCommentableIssue(
+  issue: ReviewIssue,
+): issue is ReviewIssue & { readonly file: string; readonly line: number } {
+  return typeof issue.file === "string" && issue.file.trim().length > 0 && typeof issue.line === "number" && Number.isFinite(issue.line);
+}
+
+function formatIssueId(index: number): string {
+  return `R${String(index + 1).padStart(3, "0")}`;
+}

package/src/domains/workflows/runtime/review/review-report.ts

@@ -0,0 +1,42 @@
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+import { AdvisoryReportWithStatsSchema } from "../advisory-schema.ts";
+import { formatReviewDiffTarget, isReviewDiffTarget, ReviewDiffTargetSchema } from "../review-diff-target.ts";
+
+/** Atomic identity of the exact diff and post-change snapshot that were reviewed. */
+export const ReviewSnapshotIdentitySchema = Type.Object({
+  diffFingerprint: Type.String({ pattern: "^[0-9a-fA-F]{64}$" }),
+  baselineFingerprint: Type.String({ pattern: "^[0-9a-fA-F]{64}$" }),
+});
+
+export const ReviewContextSchema = Type.Object({
+  workflowName: Type.String(),
+  target: Type.String(),
+  diffTarget: ReviewDiffTargetSchema,
+  files: Type.Array(Type.String()),
+  summary: Type.Optional(Type.String()),
+  snapshot: Type.Optional(ReviewSnapshotIdentitySchema),
+});
+
+export const ReviewReportSchema = Type.Object({
+  ...AdvisoryReportWithStatsSchema.properties,
+  reviewContext: Type.Optional(ReviewContextSchema),
+});
+
+export type ReviewSnapshotIdentity = Static<typeof ReviewSnapshotIdentitySchema>;
+export type ReviewContext = Static<typeof ReviewContextSchema>;
+export type ReviewReport = Static<typeof ReviewReportSchema>;
+
+export function isReviewReport(value: unknown): value is ReviewReport {
+  if (!Value.Check(ReviewReportSchema, value)) return false;
+  return value.reviewContext === undefined || isReviewContext(value.reviewContext);
+}
+
+export function isReviewContext(value: unknown): value is ReviewContext {
+  return Value.Check(ReviewContextSchema, value) && isReviewDiffTarget(value.diffTarget);
+}
+
+/** Prompt-facing context retains the canonical display command without persisting duplicate identity. */
+export function serializeReviewContext(context: ReviewContext | undefined): (ReviewContext & { readonly diffCommand: string }) | undefined {
+  return context ? { ...context, diffCommand: formatReviewDiffTarget(context.diffTarget) } : undefined;
+}

package/src/domains/workflows/runtime/review/review-results-flow.ts

@@ -0,0 +1,52 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowRunOptions } from "../types.ts";
+import { toReviewIssues, type ReviewIssue, type ReviewIssueSelection } from "./review-issues.ts";
+import { isReviewReport, type ReviewReport } from "./review-report.ts";
+import { ReviewResultsViewer } from "./review-results-viewer.ts";
+import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "../ui/workflow-viewer-layout.ts";
+
+export type ReviewResultsPresentationDecision =
+  | {
+      readonly kind: "send";
+      readonly reason: "not-code-review" | "not-advisory" | "no-findings" | "disabled" | "not-tui" | "not-requested";
+    }
+  | { readonly kind: "open"; readonly issues: readonly ReviewIssue[] };
+
+export interface ReviewResultsDecisionInput {
+  readonly workflowName: string;
+  readonly result: unknown;
+  readonly mode?: string;
+  readonly hasUI: boolean;
+  readonly resultViewer?: WorkflowRunOptions["resultViewer"];
+}
+
+export function codeReviewReport(workflowName: string, result: unknown): ReviewReport | undefined {
+  return workflowName === "code-review" && isReviewReport(result) ? result : undefined;
+}
+
+export interface ReviewResultsViewerContext {
+  readonly ui: Pick<ExtensionContext["ui"], "custom">;
+}
+
+export function decideReviewResultsPresentation(input: ReviewResultsDecisionInput): ReviewResultsPresentationDecision {
+  if (input.workflowName !== "code-review") return { kind: "send", reason: "not-code-review" };
+  const report = codeReviewReport(input.workflowName, input.result);
+  if (!report) return { kind: "send", reason: "not-advisory" };
+  if (report.findings.length === 0) return { kind: "send", reason: "no-findings" };
+  if (input.resultViewer === "skip") return { kind: "send", reason: "disabled" };
+  if (input.mode !== "tui" || !input.hasUI) return { kind: "send", reason: "not-tui" };
+
+  if (input.resultViewer !== "open") return { kind: "send", reason: "not-requested" };
+
+  return { kind: "open", issues: toReviewIssues(input.workflowName, report) };
+}
+
+export async function showReviewResultsViewer(
+  ctx: ReviewResultsViewerContext,
+  issues: readonly ReviewIssue[],
+): Promise<ReviewIssueSelection> {
+  return await ctx.ui.custom<ReviewIssueSelection>(
+    (tui, theme, _keybindings, done) => new ReviewResultsViewer(issues, "code-review", tui, theme, done),
+    WORKFLOW_VIEWER_OVERLAY_OPTIONS,
+  );
+}