@unifan/pi-review-zh 1.0.0

package/src/target-workspace.ts

@@ -0,0 +1,239 @@
+/**
+ * Target workspace prep — clone (or worktree) the target repository so
+ * reviewer children can read its source, history and unchanged files.
+ *
+ * Real failure (PR #18689): reviewers shared cwd with the plugin repo, so
+ * `history-context` and `code-comments` had no relevant code. The plugin now
+ *   - for PRs: shallow-clones `owner/repo` into a scratch dir (gh first so
+ *     private repos use the gh credential), checks out the PR head from
+ *     FETCH_HEAD, and verifies the landed SHA against the diff's head SHA.
+ *   - for local-git dirty: uses the user's cwd directly (already correct).
+ *   - for local-git clean vs default branch: uses the user's cwd after
+ *     `git fetch origin <base>`.
+ *
+ * The workspace is **read-only by convention**: reviewers are not given
+ * write tools and the plugin never modifies it.
+ *
+ * A failed PR clone is a hard error (not a silent fallback to the user's
+ * cwd): a fresh GitHub diff plus a stale local checkout is the #1 false
+ * positive source observed in the field (diff@new, files@old).
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { parsePrRepo } from "./review-report.js";
+
+export type RunCmd = (
+	cmd: string,
+	args: string[],
+	opts: { cwd: string },
+) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
+
+let _runCmd: RunCmd = defaultRunCmd;
+export function setTargetWorkspaceCmd(fn: RunCmd): void {
+	_runCmd = fn;
+}
+export function resetTargetWorkspaceCmd(): void {
+	_runCmd = defaultRunCmd;
+}
+
+async function defaultRunCmd(
+	cmd: string,
+	args: string[],
+	opts: { cwd: string },
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	return new Promise((resolve) => {
+		try {
+			const child = spawn(cmd, args, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+			let stdout = "";
+			let stderr = "";
+			child.stdout?.setEncoding("utf-8");
+			child.stderr?.setEncoding("utf-8");
+			child.stdout?.on("data", (d: string) => (stdout += d));
+			child.stderr?.on("data", (d: string) => (stderr += d));
+			child.on("error", () => resolve({ stdout, stderr, exitCode: 1 }));
+			child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 1 }));
+		} catch {
+			resolve({ stdout: "", stderr: "spawn failed", exitCode: 1 });
+		}
+	});
+}
+
+/** Allocate a scratch root under the OS tmpdir; created on disk. */
+export function allocateWorkspaceRoot(prefix = "pi-review-ws"): string {
+	const root = join(
+		tmpdir(),
+		`${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+	);
+	mkdirSync(root, { recursive: true });
+	return root;
+}
+
+/** Best-effort cleanup; ignores errors. */
+export function removeWorkspaceRoot(path: string): void {
+	try {
+		rmSync(path, { recursive: true, force: true });
+	} catch {
+		/* ignore */
+	}
+}
+
+export interface WorkspaceResult {
+	/** Absolute path reviewers should use as cwd. */
+	workspacePath: string;
+	/** True when `git log` / `blame` will work in the workspace. */
+	historyAvailable: boolean;
+	/** Optional failure note — when set, reviewers must `skipped` the affected lane. */
+	warning?: string;
+	/** Whether we cloned (true) or reused the user cwd (false). */
+	cloned: boolean;
+	/** HEAD SHA landed in the workspace, when determinable. */
+	workspaceHeadSha?: string;
+}
+
+/**
+ * Resolve the right workspace for a given target. `cwd` is the user's cwd.
+ * Pure function with side effects limited to fs + git/gh subprocesses.
+ */
+export async function prepareWorkspace(input: {
+	cwd: string;
+	target: {
+		kind: "pr" | "diff-file" | "local-git";
+		prRef?: string;
+		/** Diff-side head SHA to verify the checkout against. */
+		expectedHeadSha?: string;
+	};
+}): Promise<WorkspaceResult> {
+	const { cwd, target } = input;
+
+	if (target.kind === "local-git") {
+		// Reuse the user's cwd; reviewers will read source directly.
+		const inRepo = await isGitRepo(cwd);
+		return {
+			workspacePath: cwd,
+			historyAvailable: inRepo,
+			cloned: false,
+			warning: inRepo ? undefined : "Not a git repository — history-context will skip.",
+		};
+	}
+
+	if (target.kind !== "pr" || !target.prRef) {
+		return {
+			workspacePath: cwd,
+			historyAvailable: false,
+			cloned: false,
+			warning: "PR target missing prRef — reviewers will see only the diff.",
+		};
+	}
+
+	const parsed = parsePrRepo(target.prRef);
+	if (!parsed) {
+		return {
+			workspacePath: cwd,
+			historyAvailable: false,
+			cloned: false,
+			warning: "Could not parse PR URL — reviewers will see only the diff.",
+		};
+	}
+
+	const root = allocateWorkspaceRoot();
+	const cloneDir = join(root, `${parsed.repo}-${parsed.number}`);
+	mkdirSync(cloneDir, { recursive: true });
+
+	// Clone (gh first so private repos ride the gh credential; plain https
+	// fallback for anonymous/public setups). depth 50 keeps history-context
+	// usable without a full clone.
+	const url = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+	const ghClone = await _runCmd(
+		"gh",
+		["repo", "clone", `${parsed.owner}/${parsed.repo}`, cloneDir, "--", "--depth", "50"],
+		{ cwd: root },
+	);
+	const clone = ghClone.exitCode === 0
+		? ghClone
+		: await _runCmd("git", ["clone", "--depth", "50", url, cloneDir], { cwd: root });
+	if (clone.exitCode !== 0) {
+		removeWorkspaceRoot(root);
+		throw new Error(
+			`pi-review: could not clone ${parsed.owner}/${parsed.repo} (${(ghClone.stderr || clone.stderr).trim().slice(0, 200)}). A fresh diff over a stale local checkout produces false positives, so the review stops here — check gh auth / network and re-run.`,
+		);
+	}
+
+	// Fetch the PR head into FETCH_HEAD and detach onto it (no named branch →
+	// nothing stale can survive between runs).
+	const headFetch = await _runCmd(
+		"git",
+		["fetch", "origin", `pull/${parsed.number}/head`, "--quiet"],
+		{ cwd: cloneDir },
+	);
+	if (headFetch.exitCode !== 0) {
+		removeWorkspaceRoot(root);
+		throw new Error(
+			`pi-review: git fetch pull/${parsed.number}/head failed (${headFetch.stderr.trim().slice(0, 200)}) — aborting instead of reviewing a mismatched checkout.`,
+		);
+	}
+	const fetchHead = (await _runCmd("git", ["rev-parse", "FETCH_HEAD"], { cwd: cloneDir })).stdout.trim();
+	if (
+		target.expectedHeadSha &&
+		fetchHead &&
+		fetchHead !== target.expectedHeadSha
+	) {
+		// One refetch — a force-push may have raced the clone.
+		const retry = await _runCmd(
+			"git",
+			["fetch", "origin", `pull/${parsed.number}/head`, "--quiet"],
+			{ cwd: cloneDir },
+		);
+		const retryHead = retry.exitCode === 0
+			? (await _runCmd("git", ["rev-parse", "FETCH_HEAD"], { cwd: cloneDir })).stdout.trim()
+			: "";
+		if (retryHead && retryHead !== target.expectedHeadSha) {
+			removeWorkspaceRoot(root);
+			throw new Error(
+				`pi-review: PR ${parsed.number} head moved to ${retryHead.slice(0, 12)} while the diff was captured at ${target.expectedHeadSha.slice(0, 12)} — re-run /review to get a consistent pair.`,
+			);
+		}
+	}
+	const headCheckout = await _runCmd("git", ["checkout", "--detach", "FETCH_HEAD"], { cwd: cloneDir });
+	if (headCheckout.exitCode !== 0) {
+		removeWorkspaceRoot(root);
+		throw new Error(
+			`pi-review: checkout of PR ${parsed.number} head failed (${headCheckout.stderr.trim().slice(0, 200)}).`,
+		);
+	}
+
+	const workspaceHeadSha = await safeHead(cloneDir);
+	return { workspacePath: cloneDir, historyAvailable: true, cloned: true, workspaceHeadSha };
+}
+
+async function safeHead(cwd: string): Promise<string | undefined> {
+	const r = await _runCmd("git", ["rev-parse", "HEAD"], { cwd });
+	if (r.exitCode !== 0) return undefined;
+	return r.stdout.trim() || undefined;
+}
+
+async function isGitRepo(cwd: string): Promise<boolean> {
+	const r = await _runCmd("git", ["rev-parse", "--git-dir"], { cwd });
+	return r.exitCode === 0;
+}
+
+/** Optional: write a `.pi-review-meta.json` so reviewers can find the run dir. */
+export function writeWorkspaceMarker(workspacePath: string, payload: Record<string, unknown>): void {
+	const path = join(workspacePath, ".pi-review-meta.json");
+	try {
+		writeFileSync(path, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+	} catch {
+		/* read-only fs, etc. */
+	}
+}
+
+/** Quiet helper to remove the marker when the workspace is torn down. */
+export function clearWorkspaceMarker(workspacePath: string): void {
+	try {
+		rmSync(join(workspacePath, ".pi-review-meta.json"), { force: true });
+	} catch {
+		/* ignore */
+	}
+}

package/src/tool-wrapper.ts

@@ -0,0 +1,75 @@
+/**
+ * Thin wrapper that adapts `runReportTool` to `pi.registerTool`. The tool
+ * loads the manifest, validates the workflow return value's reviewer/gate
+ * structuredOutput, runs the deterministic verdict + report builder, and
+ * persists a session entry.
+ */
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { runReportTool } from "./report-tool.js";
+
+export function registerReviewReportTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "pi_review_report",
+		label: "pi-review Report",
+		description:
+			"Finalize a pi-review run. Inputs: runId + the workflow return value from the reviewer's `runs.all`/`runs.run` call. Loads the manifest, enforces the verdict in code, and persists a session entry.",
+		parameters: Type.Object({
+			runId: Type.String({ description: "Run id from the prepared manifest (e.g. 'xyz123-abc')." }),
+			workflowReturn: Type.Any({
+				description: "The workflow return value `{ reviewers, gate }` from the most recent subagent() call.",
+			}),
+			threshold: Type.Optional(Type.Integer({ minimum: 0, maximum: 10 })),
+			verdictPolicy: Type.Optional(Type.Union([
+				Type.Literal("strict"),
+				Type.Literal("legacy"),
+			])),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const result = runReportTool({
+				runId: params.runId,
+				workflowReturn: params.workflowReturn,
+				threshold: params.threshold,
+				verdictPolicy: params.verdictPolicy,
+				cwd: ctx.cwd,
+			});
+			if (!result.ok) {
+				return {
+					content: [{ type: "text", text: `pi_review_report failed: ${result.error}` }],
+					details: { error: result.error },
+				};
+			}
+			// Persist a session entry so the TUI renderer can render a
+			// collapsible card and `/review-show` can re-render later.
+			try {
+				pi.appendEntry("pi-review", {
+					runId: result.runId,
+					verdict: result.verdict,
+					markdown: result.markdown,
+					report: result.report,
+					createdAt: Date.now(),
+				});
+			} catch {
+				// appendEntry is best-effort; the agent still has the markdown.
+			}
+			// Also push the markdown into chat so the user sees the report.
+			pi.sendMessage({
+				customType: "pi-review",
+				content: result.markdown,
+				display: true,
+			});
+			void ctx;
+			const t = result.report.totals.bySeverity;
+			return {
+				content: [
+					{
+						type: "text",
+						text: `pi-review result: ${result.verdict} · ${t.blocker} blocker · ${t.major} major · ${t.minor} minor · ${t.nit} nit — full report rendered in the pi-review card below.`,
+					},
+				],
+				details: { runId: result.runId, verdict: result.verdict, report: result.report },
+			};
+		},
+	});
+}

package/src/tui-renderer.ts

@@ -0,0 +1,92 @@
+import { Box, Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { IssueSeverity, Verdict } from "./types.js";
+
+interface SeverityTotals {
+	blocker: number;
+	major: number;
+	minor: number;
+	nit: number;
+}
+
+interface ReportHeader {
+	verdict: Verdict | "no-gate" | "error" | "partial";
+	totals?: SeverityTotals;
+}
+
+function extractHeader(markdown: string): ReportHeader {
+	const m = markdown.match(/(?:Verdict|审查裁决):\s*([A-Za-z_\u4e00-\u9fa5]+)\s*(?:（[^)]*）|\([^)]*\))?\s*\*{0,2}\s*\(([^)]*)\)/);
+	if (!m) return { verdict: "comment" };
+	const raw = m[1]?.toLowerCase();
+	let verdict: ReportHeader["verdict"] = "comment";
+	if (raw?.includes("approve") || raw?.includes("通过")) verdict = "approve";
+	else if (raw?.includes("request_changes") || raw?.includes("需要修改")) verdict = "request_changes";
+	else if (raw?.includes("no-gate") || raw?.includes("无门禁")) verdict = "no-gate";
+	else if (raw?.includes("error") || raw?.includes("异常")) verdict = "error";
+	else if (raw?.includes("partial") || raw?.includes("部分")) verdict = "partial";
+	else verdict = "comment";
+
+	const counts = (m[2] ?? "").match(/(\d+)\s*(?:blocker|致命阻断)\s*[·•]\s*(\d+)\s*(?:major|严重)\s*[·•]\s*(\d+)\s*(?:minor|次要)\s*[·•]\s*(\d+)\s*(?:nit|细节优化)/);
+	const totals: SeverityTotals | undefined = counts
+		? {
+				blocker: Number(counts[1] ?? 0),
+				major: Number(counts[2] ?? 0),
+				minor: Number(counts[3] ?? 0),
+				nit: Number(counts[4] ?? 0),
+			}
+		: undefined;
+	return { verdict, totals };
+}
+
+function displayVerdict(v: ReportHeader["verdict"]): string {
+	switch (v) {
+		case "approve":
+			return "审核通过 (Approve)";
+		case "request_changes":
+			return "需要修改 (Request Changes)";
+		case "comment":
+			return "普通建议 (Comment)";
+		case "no-gate":
+			return "无门禁 (No Gate)";
+		case "error":
+			return "审查异常 (Error)";
+		case "partial":
+			return "部分完成 (Partial)";
+	}
+}
+
+export function summaryLine(header: ReportHeader): string {
+	const t = header.totals;
+	const counts = t
+		? ` · ${t.blocker} 致命阻断 · ${t.major} 严重 · ${t.minor} 次要 · ${t.nit} 细节优化`
+		: "";
+	return `pi-review 代码审查裁决: ${displayVerdict(header.verdict)}${counts}`;
+}
+
+export function registerPiReviewRenderer(pi: ExtensionAPI): void {
+	pi.registerMessageRenderer("pi-review", (message, _options, theme) => {
+		const contentText = typeof message.content === "string"
+			? message.content
+			: (() => {
+					const parts: string[] = [];
+					for (const block of message.content) {
+						if (block.type === "text") parts.push(block.text);
+					}
+					return parts.join("\n");
+				})();
+		if (contentText.startsWith("/review")) {
+			const echo = theme.fg("toolTitle", "[pi-review] ") + contentText;
+			const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+			box.addChild(new Text(echo, 0, 0));
+			return box;
+		}
+		const header = extractHeader(contentText);
+		const summary = theme.bold(theme.fg("toolTitle", summaryLine(header)));
+		const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+		box.addChild(new Text(summary, 0, 0));
+		box.addChild(new Text("", 0, 0));
+		box.addChild(new Text(contentText, 0, 0));
+		return box;
+	});
+}

package/src/types.ts

@@ -0,0 +1,207 @@
+/**
+ * Shared type definitions for pi-review (v0.7+).
+ *
+ * The active path is the foreground workflowScript:
+ *   /review → plugin prep (diff + target workspace + manifest)
+ *          → main agent runs one subagent({ workflowScript })
+ *          → pi_review_report tool renders the deterministic report
+ *
+ * No legacy spawn-pipeline types remain.
+ */
+
+/** Final verdict produced by the code-side gate enforcement. */
+export type Verdict = "approve" | "request_changes" | "comment";
+
+/** Issue severity bucket. */
+export type IssueSeverity = "blocker" | "major" | "minor" | "nit";
+
+/** Issue category — informs routing and which reviewer surfaced it. */
+export type IssueCategory =
+	| "compliance"
+	| "bug"
+	| "convention"
+	| "history"
+	| "security"
+	| "performance"
+	| "docs"
+	| "other";
+
+/** A single finding reported by a reviewer (or surfaced by the gate). */
+export interface Issue {
+	/** Repo-relative path, or "global" for cross-cutting findings. */
+	file: string;
+	/** 1-indexed line in the file. Omit for findings that span ranges or are file-wide. */
+	line?: number;
+	/** Optional line in the **introduced** diff this finding maps to. */
+	relatedChangedLine?: number;
+	category: IssueCategory;
+	severity: IssueSeverity;
+	/** 1-10 confidence score (calibrated like Claude's code-review plugin). */
+	confidence: number;
+	/** Short evidence quote or paraphrase. Max 280 chars. */
+	evidence: string;
+	/** Stable id for cross-reviewer dedupe (file:line:category[:short-hash]). */
+	fingerprint?: string;
+}
+
+/** Per-reviewer status (separate from runtime `ok`/`failed`). */
+export type ReviewerStatus = "ok" | "limited" | "skipped" | "failed";
+
+/** Structured payload a reviewer subagent must produce. */
+export interface ReviewerOutput {
+	status: ReviewerStatus;
+	issues: Issue[];
+	summary: string;
+	coverage: {
+		filesChecked: string[];
+		commandsRun: string[];
+		limitations: string[];
+	};
+}
+
+/** Per-candidate disposition emitted by the gate for audit. */
+export interface GateDisposition {
+	fingerprint: string;
+	decision: "kept" | "dropped" | "merged";
+	originalConfidence: number;
+	finalConfidence: number;
+	sourceReviewers: string[];
+	reason: string;
+}
+
+/** Structured payload the gate subagent must produce. */
+export interface GateOutput {
+	status: ReviewerStatus;
+	verdict: Verdict;
+	issues: Issue[];
+	dispositions: GateDisposition[];
+	reason: string;
+	coverage: {
+		limitations: string[];
+	};
+}
+
+/** Definition of a single reviewer, loaded from config + bundled prompt. */
+export interface ReviewerSpec {
+	id: string;
+	label: string;
+	enabled: boolean;
+	/** "inherit" resolves to the parent session model at run time. */
+	model: string | "inherit";
+	/** Optional per-reviewer thinking level ("off"|"low"|"medium"|"high"|...). */
+	thinking?: string;
+	/**
+	 * Optional absolute path override to the reviewer prompt markdown.
+	 * When omitted, the runner derives `agents/<id>.md` from `id`.
+	 */
+	promptPath?: string;
+}
+
+/** Per-run outcome of a single reviewer subagent. */
+export interface ReviewerRunResult {
+	id: string;
+	label: string;
+	/** Resolved model id (post-"inherit" substitution). */
+	model: string;
+	ok: boolean;
+	output?: ReviewerOutput;
+	error?: string;
+	/** Process exit code. null = killed by timeout or signal. undefined = never started. */
+	exitCode?: number | null;
+	durationMs: number;
+}
+
+/** Aggregated verdict produced by the code-side gate enforcement. */
+export interface GateVerdict {
+	verdict: Verdict;
+	/** Deduped + threshold-filtered issues from the reviewer pool. */
+	issues: Issue[];
+	/** Per-candidate audit trail (kept / dropped / merged). */
+	dispositions: GateDisposition[];
+	/** Reviewer status reflecting coverage (e.g. "limited" if bugbot failed). */
+	status: ReviewerStatus;
+	/** One-sentence rationale, max 500 chars. */
+	reason: string;
+}
+
+/** Per-run outcome of the gate subagent. */
+export interface GateRunResult {
+	ok: boolean;
+	verdict?: GateVerdict;
+	error?: string;
+	/** Process exit code. null = killed by timeout or signal. undefined = never started. */
+	exitCode?: number | null;
+	durationMs: number;
+	model: string;
+}
+
+/** Verdict policy used by the code-side gate enforcement. */
+export type VerdictPolicy = "strict" | "legacy";
+
+/** Adaptive routing controls whether obviously-inapplicable lanes are dropped up front. */
+export type RoutingMode = "adaptive" | "all";
+
+/** Top-level user-editable config (v0.7). */
+export interface PiReviewConfig {
+	schemaVersion: 1;
+	gate: {
+		/** "inherit" → parent session model at run time. */
+		model: string | "inherit";
+		thinking?: string;
+		/** When false, gate is always skipped. */
+		enabled: boolean;
+		/** Default confidence floor for the gate (issues with confidence < threshold are dropped). */
+		threshold: number;
+		/** Verdict policy: strict (any blocker/major) | legacy (≥3 majors). */
+		verdictPolicy: VerdictPolicy;
+	};
+	/** Adaptive routing: drop clearly-inapplicable reviewer lanes up front. */
+	routing: {
+		mode: RoutingMode;
+	};
+	reviewers: Record<string, Omit<ReviewerSpec, "promptPath"> & { promptPath?: string }>;
+	/**
+	 * Optional budgets for the foreground directive path (pi-subagents).
+	 * turnBudget.maxTurns defaults to 20 (cap 48).
+	 */
+	budgets?: {
+		turnBudget?: { maxTurns?: number; graceTurns?: number };
+	};
+}
+
+/**
+ * What to review — agent-driven (v0.4+). The plugin does **not** embed a full
+ * diff; the extension prepares the diff + target workspace, then reviewer
+ * children read it.
+ */
+export type ReviewTargetKind = "pr" | "diff-file" | "local-git";
+
+export interface ReviewTarget {
+	kind: ReviewTargetKind;
+	/** Short human label for the report header. */
+	label: string;
+	/** CC-style freeform user context (PR URL, instructions, etc.). */
+	userContext?: string;
+	/** Parsed PR URL or number when kind === "pr". */
+	prRef?: string;
+	/** Absolute path to an explicit `--diff` file when kind === "diff-file". */
+	diffPath?: string;
+	/** Hint for local-git: dirty working tree vs base...HEAD. */
+	hint?: string;
+	/** Optional short probe note for dry-run. */
+	probeNote?: string;
+}
+
+/** Top-level run report. */
+export interface ReviewReport {
+	startedAt: number;
+	durationMs: number;
+	input: ReviewTarget;
+	reviewers: ReviewerRunResult[];
+	gate: GateRunResult | null;
+	totals: {
+		issues: number;
+		bySeverity: Record<IssueSeverity, number>;
+	};
+	verdict: Verdict | "no-gate" | "error" | "partial";
+}