@mrclrchtr/supi-review 2.8.0 → 3.0.0

package/src/tool/review-tools.ts

@@ -0,0 +1,119 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { listReviewFiles, readReviewDiff, readReviewFile, searchReviewFiles } from "../git.ts";
+import { normalizeReviewSubmission } from "../review-result.ts";
+import type { ReviewSnapshot, ReviewSubmission } from "../types.ts";
+import { DEFAULT_PAGE_CHARACTERS, MAX_PAGE_CHARACTERS, pageText } from "./output-page.ts";
+import { reviewSubmissionSchema } from "./schemas.ts";
+
+const paginationProperties = {
+  offset: Type.Optional(
+    Type.Integer({ minimum: 0, default: 0, description: "UTF-16 character offset." }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: MAX_PAGE_CHARACTERS,
+      default: DEFAULT_PAGE_CHARACTERS,
+      description: "Maximum characters for this page.",
+    }),
+  ),
+};
+
+function pagedResult(text: string, offset?: number, limit?: number) {
+  const page = pageText(text, offset, limit);
+  return {
+    content: [{ type: "text" as const, text: page.text }],
+    details: {
+      offset: page.offset,
+      nextOffset: page.nextOffset,
+      totalCharacters: page.totalCharacters,
+    },
+  };
+}
+
+/** Build the complete fixed tool set for one resolved review target. */
+export function createReviewTools(
+  cwd: string,
+  snapshot: ReviewSnapshot,
+  submission: { value?: ReviewSubmission },
+) {
+  return [
+    defineTool({
+      name: "list_review_files",
+      label: "List Review Files",
+      description: "List after-side target files. Use offset to continue paged output.",
+      parameters: Type.Object(paginationProperties, { additionalProperties: false }),
+      execute: async (_id, args) =>
+        pagedResult((await listReviewFiles(cwd, snapshot)).join("\n"), args.offset, args.limit),
+    }),
+    defineTool({
+      name: "read_review_diff",
+      label: "Read Review Diff",
+      description: "Read one changed file's exact target diff. Use offset to continue.",
+      parameters: Type.Object(
+        { path: Type.String({ minLength: 1 }), ...paginationProperties },
+        { additionalProperties: false },
+      ),
+      execute: async (_id, args) =>
+        pagedResult(await readReviewDiff(cwd, snapshot, args.path), args.offset, args.limit),
+    }),
+    defineTool({
+      name: "read_review_file",
+      label: "Read Review File",
+      description: "Read a before/after target file. Use offset to continue paged output.",
+      parameters: Type.Object(
+        {
+          path: Type.String({ minLength: 1 }),
+          side: Type.Optional(
+            StringEnum(["before", "after"] as const, {
+              default: "after",
+              description: "Target side to read; defaults to after.",
+            }),
+          ),
+          ...paginationProperties,
+        },
+        { additionalProperties: false },
+      ),
+      execute: async (_id, args) => {
+        const content = await readReviewFile(cwd, snapshot, args.path, args.side ?? "after");
+        return pagedResult(content ?? "[file unavailable on this side]", args.offset, args.limit);
+      },
+    }),
+    defineTool({
+      name: "search_review_files",
+      label: "Search Review Files",
+      description: "Search literal after-side target text. Use offset to continue paged output.",
+      parameters: Type.Object(
+        {
+          query: Type.String({ minLength: 1 }),
+          path: Type.Optional(Type.String({ minLength: 1 })),
+          ...paginationProperties,
+        },
+        { additionalProperties: false },
+      ),
+      execute: async (_id, args) =>
+        pagedResult(
+          (await searchReviewFiles(cwd, snapshot, args.query, args.path)) || "No matches.",
+          args.offset,
+          args.limit,
+        ),
+    }),
+    defineTool({
+      name: "submit_review",
+      label: "Submit Review",
+      description: "Submit the final structured result for this review task.",
+      parameters: reviewSubmissionSchema,
+      execute: async (_id, args) => {
+        const { verdict: _, ...normalized } = normalizeReviewSubmission(args as ReviewSubmission);
+        submission.value = normalized;
+        return {
+          content: [{ type: "text" as const, text: "Review submitted." }],
+          details: normalized,
+          terminate: true,
+        };
+      },
+    }),
+  ];
+}

package/src/tool/review-workflow.ts

@@ -0,0 +1,309 @@
+import { resolveReviewSnapshot, summarizeReviewSnapshot } from "../git.ts";
+import { normalizeReviewSubmission } from "../review-result.ts";
+import type { ReviewPlanStore } from "../session/review-plan-store.ts";
+import { buildReviewPacket } from "../target/packet.ts";
+import type {
+  PlannerDraft,
+  PlanningRecord,
+  ReviewBatchDetails,
+  ReviewInput,
+  ReviewModelSelection,
+  ReviewSnapshot,
+  ReviewTargetSpec,
+  ReviewTaskResult,
+} from "../types.ts";
+import { createUnobservedChildFailureDiagnostics } from "./child-failure-diagnostics.ts";
+import { PLANNER_PROMPT_VERSION, runPlanner } from "./planner-runner.ts";
+import { runReviewer } from "./review-runner.ts";
+
+/** Input required by the prepare workflow: target resolution plus optional Planner run. */
+export interface PrepareReviewInput {
+  cwd: string;
+  target: ReviewTargetSpec;
+  planning: "none" | "suggest";
+  plannerContext: string;
+  reviewerModel: ReviewModelSelection;
+  plannerModel?: ReviewModelSelection;
+  planStore: ReviewPlanStore;
+  signal?: AbortSignal;
+  onUpdate?: OnUpdate;
+}
+
+/** Tool update callback signature shared across workflow adapters. */
+type OnUpdate = (result: {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+}) => void;
+
+/** Complete Direct Review request: target, full review input, and reviewer model. */
+export interface DirectRunInput {
+  mode: "direct";
+  cwd: string;
+  target: ReviewTargetSpec;
+  review: ReviewInput;
+  reviewerModel: ReviewModelSelection;
+  signal?: AbortSignal;
+  onUpdate?: OnUpdate;
+}
+
+/** One-shot Prepared Review request: plan id, explicit decision, and plan store. */
+export interface PreparedRunInput {
+  mode: "prepared";
+  cwd: string;
+  planId: string;
+  decision: { kind: "accept-draft" } | { kind: "use-review"; review: ReviewInput };
+  planStore: ReviewPlanStore;
+  signal?: AbortSignal;
+  onUpdate?: OnUpdate;
+}
+
+/** Discriminated union accepted by `runReview` for both Direct and Prepared paths. */
+export type RunReviewInput = DirectRunInput | PreparedRunInput;
+
+const MAX_PLANNER_FILE_COUNT = 200;
+const MAX_PLANNER_FILE_CHARS = 8_000;
+
+/** Canonicalize and semantically validate review input for every adapter. */
+export function normalizeReviewInput(review: ReviewInput): ReviewInput {
+  const sharedContext = review.sharedContext?.trim();
+  const tasks = review.tasks.map((task) => ({
+    id: task.id.trim(),
+    instructions: task.instructions.trim(),
+  }));
+  if (tasks.length < 1 || tasks.length > 4)
+    throw new Error("Provide between one and four review tasks.");
+  if (tasks.some((task) => !task.id || !task.instructions)) {
+    throw new Error("Review task ids and instructions must not be blank.");
+  }
+  if (tasks.some((task) => task.id.length > 64)) {
+    throw new Error("Review task ids must not exceed 64 characters.");
+  }
+  if (new Set(tasks.map((task) => task.id)).size !== tasks.length) {
+    throw new Error("Review task ids must be unique.");
+  }
+  return { ...(sharedContext ? { sharedContext } : {}), tasks };
+}
+
+function plannerFileManifest(files: string[]): string[] {
+  const lines: string[] = [];
+  let size = 0;
+  for (const file of files) {
+    const line = `- ${JSON.stringify(file)}`;
+    if (
+      lines.length >= MAX_PLANNER_FILE_COUNT ||
+      size + line.length + 1 > MAX_PLANNER_FILE_CHARS - 100
+    ) {
+      break;
+    }
+    lines.push(line);
+    size += line.length + 1;
+  }
+  const omitted = files.length - lines.length;
+  if (omitted > 0) lines.push(`- … ${omitted} additional file(s) omitted`);
+  return lines;
+}
+
+function plannerPrompt(snapshot: ReviewSnapshot, context: string): string {
+  return [
+    "# Review Planning Input",
+    "",
+    `Target: ${snapshot.title}`,
+    `Changed files: ${snapshot.changedFiles.length}`,
+    `Diff stats: +${snapshot.stats.additions} / -${snapshot.stats.deletions}`,
+    "",
+    "## Changed file names",
+    ...plannerFileManifest(snapshot.changedFiles),
+    "",
+    "## Bounded session conversation",
+    context || "No session conversation was available.",
+  ].join("\n");
+}
+
+/** Resolve and store a one-shot plan, optionally asking the advisory Planner for tasks. */
+export async function prepareReview(input: PrepareReviewInput) {
+  input.onUpdate?.({
+    content: [{ type: "text", text: "Resolving target…" }],
+    details: {},
+  });
+  const snapshot = await resolveReviewSnapshot(input.cwd, input.target);
+  if (!snapshot) return { kind: "no-target" as const, reason: "No reviewable changes found." };
+  let plannerDraft: PlannerDraft | undefined;
+  if (input.planning === "suggest") {
+    if (!input.plannerModel) throw new Error("A configured Planner model is required.");
+    input.onUpdate?.({
+      content: [{ type: "text", text: "Running planner…" }],
+      details: {},
+    });
+    const result = await runPlanner({
+      cwd: input.cwd,
+      model: input.plannerModel.model,
+      prompt: plannerPrompt(snapshot, input.plannerContext),
+      signal: input.signal,
+    });
+    if (result.kind !== "success") return { kind: "planner-failed" as const, result };
+    plannerDraft = normalizeReviewInput(result.draft);
+  }
+  const plan = input.planStore.create({
+    snapshot,
+    reviewerModel: input.reviewerModel,
+    ...(plannerDraft ? { plannerDraft } : {}),
+    ...(input.plannerModel ? { plannerModelId: input.plannerModel.canonicalId } : {}),
+    ...(plannerDraft ? { plannerPromptVersion: PLANNER_PROMPT_VERSION } : {}),
+  });
+  return { kind: "prepared" as const, plan };
+}
+
+function toTaskResult(
+  taskId: string,
+  packetHash: string,
+  result: Awaited<ReturnType<typeof runReviewer>>,
+): ReviewTaskResult {
+  const identity = { taskId, packetHash, modelId: result.modelId };
+  if (result.kind === "success") {
+    const normalized = normalizeReviewSubmission(result.submission);
+    return {
+      status: "completed",
+      ...identity,
+      verdict: normalized.verdict,
+      summary: normalized.summary,
+      findings: normalized.findings,
+    };
+  }
+  if (result.kind === "failed") {
+    return {
+      status: "failed",
+      ...identity,
+      failureCode: result.failureCode,
+      ...(result.diagnostics ? { diagnostics: result.diagnostics } : {}),
+    };
+  }
+  if (result.kind === "canceled") {
+    return { status: "canceled", ...identity, diagnostics: result.diagnostics };
+  }
+  return {
+    status: "timeout",
+    ...identity,
+    timeoutMs: result.timeoutMs,
+    diagnostics: result.diagnostics,
+  };
+}
+
+// biome-ignore lint/complexity/useMaxParams: compact internal fan-out helper
+async function execute(
+  cwd: string,
+  snapshot: ReviewSnapshot,
+  reviewInput: ReviewInput,
+  model: ReviewModelSelection,
+  signal?: AbortSignal,
+  onUpdate?: OnUpdate,
+): Promise<ReviewTaskResult[]> {
+  const review = normalizeReviewInput(reviewInput);
+  let completedCount = 0;
+  const totalCount = review.tasks.length;
+
+  return Promise.all(
+    review.tasks.map(async (task) => {
+      const packet = buildReviewPacket(snapshot, review, task, model);
+      try {
+        const result = await runReviewer({
+          cwd,
+          snapshot,
+          task,
+          prompt: packet.prompt,
+          model,
+          signal,
+        });
+        const taskResult = toTaskResult(task.id, packet.packetHash, result);
+        completedCount++;
+        const verb = taskResult.status === "completed" ? "complete" : taskResult.status;
+        onUpdate?.({
+          content: [
+            { type: "text", text: `Task ${task.id} ${verb} (${completedCount} of ${totalCount})` },
+          ],
+          details: { completedCount, totalCount },
+        });
+        return taskResult;
+      } catch {
+        const taskResult: ReviewTaskResult = {
+          status: "failed",
+          taskId: task.id,
+          packetHash: packet.packetHash,
+          modelId: model.canonicalId,
+          failureCode: "unexpected-runner-failure",
+          diagnostics: createUnobservedChildFailureDiagnostics(),
+        };
+        completedCount++;
+        onUpdate?.({
+          content: [
+            {
+              type: "text",
+              text: `Task ${task.id} failed (${completedCount} of ${totalCount})`,
+            },
+          ],
+          details: { completedCount, totalCount },
+        });
+        return taskResult;
+      }
+    }),
+  );
+}
+
+/** Execute a Direct Review or atomically consume and execute a Prepared Review. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: direct/prepared orchestration stays at one public seam
+export async function runReview(input: RunReviewInput) {
+  let snapshot: ReviewSnapshot;
+  let review: ReviewInput;
+  let model: ReviewModelSelection;
+  let planning: PlanningRecord | undefined;
+  let provenance: ReviewBatchDetails["provenance"] = "caller-supplied";
+
+  if (input.mode === "direct") {
+    const resolved = await resolveReviewSnapshot(input.cwd, input.target);
+    if (!resolved) return { kind: "no-target" as const, reason: "No reviewable changes found." };
+    snapshot = resolved;
+    review = normalizeReviewInput(input.review);
+    model = input.reviewerModel;
+  } else {
+    const plan = input.planStore.take(input.planId);
+    if (!plan) {
+      return {
+        kind: "invalid" as const,
+        reason: `Review Plan ${input.planId} was not found or was already consumed.`,
+      };
+    }
+    if (input.decision.kind === "accept-draft" && !plan.plannerDraft) {
+      return { kind: "invalid" as const, reason: "This plan has no Planner Draft." };
+    }
+    const selectedReview =
+      input.decision.kind === "accept-draft"
+        ? plan.plannerDraft
+        : normalizeReviewInput(input.decision.review);
+    if (!selectedReview) {
+      return { kind: "invalid" as const, reason: "This plan has no Planner Draft." };
+    }
+    snapshot = plan.snapshot;
+    review = selectedReview;
+    model = plan.reviewerModel;
+    if (plan.plannerDraft) provenance = "planner-assisted";
+    if (plan.plannerDraft && plan.plannerModelId && plan.plannerPromptVersion) {
+      planning = {
+        promptVersion: plan.plannerPromptVersion,
+        modelId: plan.plannerModelId,
+        draft: plan.plannerDraft,
+        effectiveReview: review,
+        decision: input.decision.kind,
+      };
+    }
+  }
+
+  const details: ReviewBatchDetails = {
+    kind: "review-batch",
+    mode: input.mode,
+    provenance,
+    snapshot: summarizeReviewSnapshot(snapshot),
+    review,
+    ...(planning ? { planning } : {}),
+    results: await execute(input.cwd, snapshot, review, model, input.signal, input.onUpdate),
+  };
+  return { kind: "completed" as const, details };
+}

package/src/tool/runner-helpers.ts

@@ -1,12 +1,7 @@
-/**
- * Shared helpers for child-session runners (brief synthesis & review).
- *
- * These were extracted from brief-runner.ts and review-runner.ts to
- * eliminate duplication.
- */
+/** Shared child-session helpers that do not retain model-generated diagnostics. */
 
-/** Extract text content from a message content value (string | content-part[]). */
-export function extractAssistantText(content: unknown): string | undefined {
+/** Extract visible text from a message content value (string or content-part array). */
+export function extractVisibleText(content: unknown): string | undefined {
   if (typeof content === "string") {
     return content || undefined;
   }

package/src/tool/schemas.ts

@@ -1,70 +1,83 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
-const reviewItemCategorySchema = StringEnum([
-  "correctness",
-  "security",
-  "performance",
-  "api",
-  "test-gap",
-  "docs",
-  "cleanup",
-  "maintainer",
-] as const);
-
-const reviewItemImpactSchema = StringEnum(["low", "medium", "high"] as const);
-
-const reviewItemEffortSchema = StringEnum(["low", "medium", "high"] as const);
-
-const reviewItemRecommendedActionSchema = StringEnum([
-  "must-fix",
-  "should-fix",
-  "consider",
-] as const);
-
-const reviewInstructionBlockIdSchema = StringEnum([
-  "public-surface",
-  "cross-layer",
-  "schema-widening",
-  "cleanup",
-] as const);
+/** TypeBox schema for one caller-defined review task (provider-visible). */
+export const reviewTaskSchema = Type.Object(
+  {
+    id: Type.String({
+      minLength: 1,
+      maxLength: 64,
+      description: "Stable caller-defined task id, such as standards or spec.",
+    }),
+    instructions: Type.String({
+      minLength: 1,
+      description: "Complete freeform methodology and acceptance instructions for this task.",
+    }),
+  },
+  { additionalProperties: false },
+);
 
-export const reviewItemSchema = Type.Object({
-  title: Type.String(),
-  body: Type.String(),
-  category: reviewItemCategorySchema,
-  impact: reviewItemImpactSchema,
-  effort: reviewItemEffortSchema,
-  recommended_action: reviewItemRecommendedActionSchema,
-  confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
-  suggested_fix: Type.String(),
-  verification_hint: Type.String(),
-  code_location: Type.Optional(
-    Type.Object({
-      absolute_file_path: Type.String(),
-      line_range: Type.Object({
-        start: Type.Number(),
-        end: Type.Number(),
-      }),
+/** TypeBox schema for the complete review input (provider-visible). */
+export const reviewInputSchema = Type.Object(
+  {
+    sharedContext: Type.Optional(
+      Type.String({ description: "Optional context shared unchanged with every task." }),
+    ),
+    tasks: Type.Array(reviewTaskSchema, {
+      minItems: 1,
+      maxItems: 4,
+      description: "One to four independent tasks executed concurrently in caller order.",
     }),
-  ),
-});
+  },
+  { additionalProperties: false },
+);
 
-export const reviewOutputSchema = Type.Object({
-  items: Type.Array(reviewItemSchema),
-  overall_explanation: Type.String(),
-  overall_confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
-});
+/** TypeBox schema for a single structured finding (provider-visible). */
+export const reviewFindingSchema = Type.Object(
+  {
+    title: Type.String({ minLength: 1, description: "Concise finding title." }),
+    description: Type.String({
+      minLength: 1,
+      description: "Concrete evidence-backed explanation of the issue.",
+    }),
+    blocksAcceptance: Type.Boolean({
+      description: "Whether this finding must be corrected before accepting the change.",
+    }),
+    impact: StringEnum(["low", "medium", "high"] as const, {
+      description: "Downside if the issue remains unfixed.",
+    }),
+    effort: StringEnum(["small", "medium", "large"] as const, {
+      description: "Estimated size of the correction.",
+    }),
+    confidence: Type.Number({
+      minimum: 0,
+      maximum: 1,
+      description: "Confidence from 0 through 1; findings are never threshold-filtered.",
+    }),
+    location: Type.Optional(
+      Type.Object(
+        {
+          path: Type.String({ minLength: 1, description: "Repository-relative target path." }),
+          startLine: Type.Integer({ minimum: 1 }),
+          endLine: Type.Integer({ minimum: 1 }),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
 
-const briefRequiredTextSchema = Type.String({ minLength: 1, maxLength: 4_000 });
-const briefListItemSchema = Type.String({ minLength: 1, maxLength: 2_000 });
+/** TypeBox schema for the submit_review tool parameters (provider-visible). */
+export const reviewSubmissionSchema = Type.Object(
+  {
+    summary: Type.String({ minLength: 1, description: "Task-level review summary." }),
+    findings: Type.Array(reviewFindingSchema, {
+      description: "Findings in the reviewer's intended order; use an empty array when none exist.",
+    }),
+  },
+  { additionalProperties: false },
+);
 
-export const reviewBriefSchema = Type.Object({
-  summary: briefRequiredTextSchema,
-  intendedOutcome: briefRequiredTextSchema,
-  constraints: Type.Array(briefListItemSchema, { maxItems: 50 }),
-  focusAreas: Type.Array(briefListItemSchema, { maxItems: 50 }),
-  riskyFiles: Type.Array(briefListItemSchema, { maxItems: 200 }),
-  unresolvedQuestions: Type.Array(briefListItemSchema, { maxItems: 50 }),
-  reviewInstructionBlockIds: Type.Array(reviewInstructionBlockIdSchema, { maxItems: 4 }),
-});
+/** Planner Draft uses the same shape as review input (shared context + tasks). */
+export const plannerDraftSchema = reviewInputSchema;