@fyeeme/pi-review 2.0.1 → 2.1.1

package/src/loop.ts

@@ -0,0 +1,266 @@
+/**
+ * src/loop.ts — /code-review --loop: extension-driven fix→re-review cycles.
+ *
+ * Ported from the standalone Codex-style review extension's loop fixing
+ * (review → blocking-check → fix → re-review, bounded), with one deliberate
+ * deviation: the blocking decision reads the structured `review_report` JSON
+ * the skill must have written under the project's pi config dir
+ * (<cwd>/.pi/review/ by default — CONFIG_DIR_NAME) instead of scraping the
+ * assistant's markdown. The tool call is the report, so the JSON is the
+ * reliable artifact; markdown scraping was only ever a fallback.
+ *
+ * Loop shape (single-pass levels only — low/medium/high):
+ *   review turn → read newest report → OPEN P0/P1 findings (P0/P1 without a
+ *     decided outcome — a fix turn's re-report marks its findings
+ *     fixed/skipped/no_change_needed)?
+ *     none            → done
+ *     some, rounds left → fix prompt (followUp) → idle → re-review prompt → next round
+ *     some, rounds spent → stop with a safety-limit note
+ * Esc/abort or a missing report stops the loop.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { OUTCOME_VALUES } from "./tools/review_report.ts";
+
+// --- pure helpers (unit-tested) ---------------------------------------------
+
+export const BLOCKING_PRIORITIES = ["P0", "P1"] as const;
+
+/** Strip a --loop flag out of the trailing args; report whether it was there.
+ *  Pure — unit-testable. */
+export function extractLoopFlag(rest: string): { wantLoop: boolean; rest: string } {
+	const tokens = (rest ?? "").split(/\s+/).filter(Boolean);
+	const kept = tokens.filter((t) => t !== "--loop");
+	return { wantLoop: kept.length !== tokens.length, rest: kept.join(" ") };
+}
+
+/** A blocking finding as surfaced back to the fix prompt. */
+export interface BlockingFinding {
+	file: string;
+	line?: number;
+	priority: string;
+	summary: string;
+}
+
+/** Extract P0/P1 findings from a parsed review_report JSON (lenient: any
+ *  shape mismatch → no findings rather than a throw). Pure — unit-testable. */
+export function blockingFindings(report: unknown): BlockingFinding[] {
+	if (!report || typeof report !== "object" || Array.isArray(report)) return [];
+	const raw = (report as { findings?: unknown }).findings;
+	if (!Array.isArray(raw)) return [];
+	const out: BlockingFinding[] = [];
+	for (const f of raw) {
+		if (!f || typeof f !== "object" || Array.isArray(f)) continue;
+		const rec = f as Record<string, unknown>;
+		if (rec.priority !== "P0" && rec.priority !== "P1") continue;
+		if (typeof rec.file !== "string" || rec.file.length === 0) continue;
+		// A decided outcome (a fix turn re-reports its findings with one, per
+		// the skill's fixed-later obligation) un-blocks the finding —
+		// re-prompting a fixed/skipped/declined finding just burns rounds.
+		if (typeof rec.outcome === "string" && (OUTCOME_VALUES as readonly string[]).includes(rec.outcome)) {
+			continue;
+		}
+		out.push({
+			file: rec.file,
+			line: typeof rec.line === "number" ? rec.line : undefined,
+			priority: rec.priority,
+			summary: typeof rec.summary === "string" ? rec.summary : "",
+		});
+	}
+	return out;
+}
+
+/** Newest `*.json` report under `dir` modified after `sinceMs`, or null.
+ *  Missing/unreadable dir → null. Pure — unit-testable. */
+export function latestReportFile(dir: string, sinceMs: number): string | null {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return null;
+	}
+	let newest: { file: string; mtime: number } | null = null;
+	for (const e of entries) {
+		if (!e.isFile() || !e.name.endsWith(".json")) continue;
+		const file = path.join(dir, e.name);
+		try {
+			const mtime = fs.statSync(file).mtimeMs;
+			if (mtime <= sinceMs) continue;
+			if (!newest || mtime > newest.mtime) newest = { file, mtime };
+		} catch {
+			/* stat failed — skip this entry */
+		}
+	}
+	return newest?.file ?? null;
+}
+
+/** Parse a report JSON file; garbage → null (the loop must not crash on a
+ *  half-written or hand-edited file). */
+function readReport(file: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+// --- loop driver -------------------------------------------------------------
+
+/** Minimal session view for the quiescence wait — structural, so
+ *  ExtensionCommandContext satisfies it and tests can drive the logic
+ *  without a live session. */
+export interface QuiescenceView {
+	isIdle(): boolean;
+	hasPendingMessages(): boolean;
+	waitForIdle(): Promise<void>;
+	signal?: { aborted: boolean };
+}
+
+/** Wait until the session is fully quiescent: nothing running AND nothing
+ *  queued. A single `waitForIdle()` is NOT enough — it resolves at the first
+ *  idle point even while follow-ups are still queued (a queued message does
+ *  not flip `isIdle` until its run actually starts), which is exactly the
+ *  window between `sendUserMessage(…, followUp)` and that turn's first
+ *  token. Aborts return false; there is no timeout — Esc is the escape
+ *  hatch, same as for the bare waitForIdle call. */
+export async function waitForQuiescent(session: QuiescenceView): Promise<boolean> {
+	for (;;) {
+		if (session.signal?.aborted) return false;
+		if (!session.isIdle() || session.hasPendingMessages()) {
+			await session.waitForIdle();
+			continue;
+		}
+		return true;
+	}
+}
+
+/** Poll until the review turn has started (idle → busy or a new assistant
+ *  message appears), then wait for it to finish. Returns false on timeout
+ *  or abort. Mirrors the reference extension's waitForLoopTurnToStart. */
+async function waitForTurnSettled(ctx: ExtensionCommandContext, baselineAssistantId: string): Promise<boolean> {
+	const START_TIMEOUT_MS = 15_000;
+	const POLL_MS = 50;
+	const deadline = Date.now() + START_TIMEOUT_MS;
+
+	const lastAssistantId = (): string | undefined => {
+		const branch = ctx.sessionManager.getBranch();
+		for (let i = branch.length - 1; i >= 0; i--) {
+			const entry = branch[i]!;
+			if (entry.type === "message" && entry.message.role === "assistant") return entry.id;
+		}
+		return undefined;
+	};
+
+	while (Date.now() < deadline) {
+		if (ctx.signal?.aborted) return false;
+		const current = lastAssistantId();
+		if (!ctx.isIdle() || ctx.hasPendingMessages() || (current && current !== baselineAssistantId)) {
+			// Wait past every queued message, not merely to the next idle
+			// point — waitForIdle() alone returns inside the gap between
+			// queueing a followUp and its run actually starting.
+			return waitForQuiescent(ctx);
+		}
+		await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+	}
+	return false;
+}
+
+function baselineAssistantId(ctx: ExtensionCommandContext): string {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i]!;
+		if (entry.type === "message" && entry.message.role === "assistant") return entry.id;
+	}
+	return "";
+}
+
+function fixPrompt(findings: BlockingFinding[]): string {
+	const list = findings
+		.map((f) => `- \`${f.file}${f.line != null ? `:${f.line}` : ""}\` [${f.priority}] ${f.summary}`)
+		.join("\n");
+	return [
+		"Fix the following blocking findings from the code review you just reported",
+		"(full failure scenarios are in the latest report JSON under .pi/review/):",
+		"",
+		list,
+		"",
+		"Apply minimal, surgical fixes — no drive-by refactors. Then re-report these",
+		"findings via the `review_report` tool with `outcome` set per finding",
+		"(fixed / skipped / no_change_needed) and run the verification guidance from",
+		"the review trigger message. Never leave the working tree verified-broken.",
+	].join("\n");
+}
+
+function reReviewPrompt(level: string): string {
+	return [
+		`Fixes applied. Re-run the code-review SINGLE-PASS flow for effort ${level} now`,
+		"— the diff has changed: re-resolve it, re-check the fixed locations and",
+		"sweep for regressions or newly exposed issues, then report via the",
+		"`review_report` tool again (fresh findings list, empty array if clean).",
+	].join("\n");
+}
+
+export interface LoopOptions {
+	/** The effort level the review runs at (echoed in re-review prompts). */
+	level: string;
+	/** Max fix→re-review rounds (config maxTurns.loop). */
+	passes: number;
+	/** Directory the review_report JSON files land in. */
+	reviewDir: string;
+}
+
+/**
+ * Drive the fix→re-review rounds after the FIRST review prompt has already
+ * been sent by the dispatcher. Each iteration reads the newest report (the
+ * first iteration sees the initial review's report, later ones the previous
+ * round's re-review) and sends at most one fix prompt. Runs at most `passes`
+ * fix→re-review rounds; the final iteration only reads the last re-review's
+ * verdict for the safety-limit message. Returns the number of fix rounds run.
+ */
+export async function runLoopFixing(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	options: LoopOptions,
+): Promise<number> {
+	const { level, passes, reviewDir } = options;
+	const baseline = baselineAssistantId(ctx);
+	const loopStart = Date.now();
+
+	let fixes = 0;
+	for (;;) {
+		if (!(await waitForTurnSettled(ctx, baseline))) return fixes;
+
+		const reportFile = latestReportFile(reviewDir, loopStart);
+		if (reportFile === null) {
+			ctx.ui.notify("/code-review --loop: no review_report JSON found — stopping the loop.", "warning");
+			return fixes;
+		}
+		const findings = blockingFindings(readReport(reportFile));
+		if (findings.length === 0) {
+			ctx.ui.notify(
+				fixes === 0
+					? "/code-review --loop: no P0/P1 findings — nothing to fix, loop done."
+					: `/code-review --loop: clean after ${fixes} fix round(s) — no open P0/P1 findings remain.`,
+				"info",
+			);
+			return fixes;
+		}
+		if (fixes === passes) {
+			ctx.ui.notify(
+				`/code-review --loop: ${findings.length} P0/P1 finding(s) still open after ${passes} fix round(s) — safety limit reached, stopping.`,
+				"warning",
+			);
+			return fixes;
+		}
+
+		fixes++;
+		ctx.ui.notify(
+			`/code-review --loop: ${findings.length} blocking finding(s) — fixing (round ${fixes}/${passes})…`,
+			"info",
+		);
+		await pi.sendUserMessage(fixPrompt(findings), { deliverAs: "followUp" });
+		if (!(await waitForTurnSettled(ctx, baseline))) return fixes;
+		pi.sendUserMessage(reReviewPrompt(level), { deliverAs: "followUp" });
+	}
+}

package/src/tools/review_report.ts

@@ -31,12 +31,19 @@ import * as path from "node:path";
 const VERDICT_VALUES = ["CONFIRMED", "PLAUSIBLE"] as const;
 const Verdict = StringEnum(VERDICT_VALUES);
 
-const OUTCOME_VALUES = ["fixed", "skipped", "no_change_needed"] as const;
 /** CC ReportFindings `outcome` 三档（2.1.227 二进制实证）。fixed-later 再上报时更新。 */
+export const OUTCOME_VALUES = ["fixed", "skipped", "no_change_needed"] as const;
 const Outcome = StringEnum(OUTCOME_VALUES);
 
+/** --loop 的 blocking 阈值：P0/P1 触发修复→再评审一轮（P2/P3 只入报告）。 */
+const PRIORITY_VALUES = ["P0", "P1", "P2", "P3"] as const;
+const Priority = StringEnum(PRIORITY_VALUES, {
+	description:
+		"优先级 P0（阻断，立刻修）/ P1（高）/ P2（中）/ P3（低）。--loop 循环修复以 P0/P1 为 blocking 阈值；省略视为 P2。",
+});
+
 // 供 SKILL-schema 同步测试引用（防漂移：SKILL 流程契约不得与常量脱节）。
-export { OUTCOME_VALUES, VERDICT_VALUES };
+export { PRIORITY_VALUES, VERDICT_VALUES };
 
 const Level = StringEnum([
 	"low",
@@ -59,6 +66,7 @@ const FindingParams = Type.Object({
 			"产生该发现的角度 slug：correctness / reuse / simplification / efficiency / altitude / conventions（或更具体如 test-coverage）。",
 	}),
 	verdict: Type.Optional(Verdict),
+	priority: Type.Optional(Priority),
 	short_summary: Type.Optional(
 		Type.String({
 			description:
@@ -91,6 +99,31 @@ const ReviewReportParams = Type.Object({
 	),
 });
 
+/**
+ * 结果 schema——与落盘 `.pi/review/*.json` 对象同构(design D2 单一事实源):
+ * `structuredContent` 与磁盘 JSON 消费方(codemode 脚本 vs CI/--fix)观察同值。
+ * 字段单一来源:复用 FindingParams.properties(入参与出参同形,仅追加 note)。
+ */
+const FindingOutput = Type.Object({
+	...FindingParams.properties,
+	/** normalize 附注(非法 outcome 归一化说明),仅详情渲染用。 */
+	note: Type.Optional(Type.String()),
+});
+
+const ReviewReportOutput = Type.Object({
+	level: Level,
+	reportId: Type.Union([Type.String(), Type.Null()]),
+	target: Type.Union([Type.String(), Type.Null()]),
+	filesChanged: Type.Union([Type.Number(), Type.Null()]),
+	fannedOut: Type.Union([Type.Boolean(), Type.Null()]),
+	generatedAt: Type.String(),
+	findings: Type.Array(FindingOutput),
+});
+
+/** Static 派生类型:reportData 的类型即出参 schema,类型层单一事实源(消除断言)。 */
+type FindingOut = Static<typeof FindingOutput>;
+type ReviewReportOut = Static<typeof ReviewReportOutput>;
+
 interface ReviewReportDetails {
 	level: string;
 	findingsCount: number;
@@ -108,6 +141,7 @@ type LooseFinding = {
 	line?: number;
 	category: string;
 	verdict?: string;
+	priority?: string;
 	short_summary?: string;
 	summary: string;
 	failure_scenario: string;
@@ -126,7 +160,10 @@ function sanitizeFinding(f: LooseFinding): { f: LooseFinding; note?: string } |
 		note = `（outcome "${outcome}" 非法，已归一化为 skipped）`;
 		outcome = "skipped";
 	}
-	return { f: { ...f, outcome }, note };
+	// 非法 priority 静默丢弃（降至未标注），不影响该条 finding 存活。
+	const priority =
+		f.priority !== undefined && (PRIORITY_VALUES as readonly string[]).includes(f.priority) ? f.priority : undefined;
+	return { f: { ...f, outcome, priority }, note };
 }
 
 /**
@@ -150,25 +187,13 @@ function normalizeFindings(findings: LooseFinding[]): { findings: LooseFinding[]
 
 // --- render -----------------------------------------------------------------
 
-interface FindingInput {
-	file: string;
-	line?: number;
-	category: string;
-	verdict?: string;
-	short_summary?: string;
-	summary: string;
-	failure_scenario: string;
-	outcome?: string;
-	/** normalize 附注（如非法 outcome 归一化说明），仅渲染进详情块。 */
-	note?: string;
-}
 interface ReportInput {
 	level: string;
 	target?: string;
 	files_changed?: number;
 	fanned_out?: boolean;
 	reportId?: string;
-	findings: FindingInput[];
+	findings: FindingOut[];
 }
 
 function fmtLoc(f: { file: string; line?: number }): string {
@@ -202,13 +227,14 @@ function renderReport(p: ReportInput): string {
 	lines.push("|---|------|------|------|------|");
 	for (let i = 0; i < p.findings.length; i++) {
 		const f = p.findings[i]!;
-		lines.push(`| ${i + 1} | ${escapeCell(f.verdict ?? "")} | ${escapeCell(f.category)} | ${escapeCell(fmtLoc(f))} | ${escapeCell(f.short_summary ?? f.summary)} |`);
+		const verdictCell = [f.priority, f.verdict].filter(Boolean).join(" · ");
+		lines.push(`| ${i + 1} | ${escapeCell(verdictCell)} | ${escapeCell(f.category)} | ${escapeCell(fmtLoc(f))} | ${escapeCell(f.short_summary ?? f.summary)} |`);
 	}
 	lines.push("");
 	lines.push("**详情**");
 	lines.push("");
 	p.findings.forEach((f, i) => {
-		const v = f.verdict ? ` *(${f.verdict})*` : "";
+		const v = [f.priority, f.verdict].filter(Boolean).length > 0 ? ` *(${[f.priority, f.verdict].filter(Boolean).join(" · ")})*` : "";
 		const out = f.outcome ? `\n修复结果：\`${f.outcome}\`` : "";
 		const note = f.note ? `\n${f.note}` : "";
 		lines.push(`**${i + 1}. ${fmtLoc(f)} — ${f.category}**${v}`);
@@ -233,6 +259,9 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 		"Use `review_report` only when the code-review skill instructs reporting findings; otherwise follow the active output format.",
 	],
 	parameters: ReviewReportParams,
+	// codemode 脚本/程序化调用方拿到 structuredContent(与磁盘 JSON 同构)而非文本;
+	// 模型侧行为(content/renderResult/落盘)不变。
+	outputSchema: ReviewReportOutput,
 
 	// 主防御：schema 校验之前清洗非法值（模型路径下校验失败即 throw、工具不执行，
 	// 因此 execute 内的防御对模型不可达）。返回符合 schema 的对象——非法 verdict
@@ -254,7 +283,38 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 		const { findings: cleaned, notes } = normalizeFindings(
 			(params.findings ?? []) as unknown as LooseFinding[],
 		);
-		const findings: FindingInput[] = cleaned.map((f, i) => ({ ...f, note: notes.get(i) }));
+		// 仅含已赋值字段的 finding:显式 undefined 键会让磁盘 JSON(serialize 丢弃)与
+		// structuredContent(原样返回)键集分叉;条件赋值保证两个视图逐键一致。
+		const findings: FindingOut[] = cleaned.map((f, i) => {
+			const note = notes.get(i);
+			const out: FindingOut = {
+				file: f.file,
+				category: f.category,
+				summary: f.summary,
+				failure_scenario: f.failure_scenario,
+			};
+			if (f.line !== undefined) out.line = f.line;
+			// 值域由 sanitizeFinding/normalizeFindings 保证(非法值已剔除/归一化),枚举收窄安全。
+			if (f.verdict !== undefined) out.verdict = f.verdict as FindingOut["verdict"];
+			if (f.priority !== undefined) out.priority = f.priority as FindingOut["priority"];
+			if (f.short_summary !== undefined) out.short_summary = f.short_summary;
+			if (f.outcome !== undefined) out.outcome = f.outcome as FindingOut["outcome"];
+			if (note !== undefined) out.note = note;
+			return out;
+		});
+
+		// 单一事实源(design D2):同一对象写盘 + 作 structuredContent;类型即出参
+		// schema 的 Static 派生,无需断言。
+		const now = new Date();
+		const reportData: ReviewReportOut = {
+			level: params.level,
+			reportId: params.report_id ?? null,
+			target: params.target ?? null,
+			filesChanged: params.files_changed ?? null,
+			fannedOut: params.fanned_out ?? null,
+			generatedAt: now.toISOString(),
+			findings,
+		};
 
 		const report = renderReport({
 			level: params.level,
@@ -267,7 +327,6 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 
 		let outFile: string | null = null;
 		let writeError: string | null = null;
-		const now = new Date();
 		try {
 			const dir = path.join(ctx.cwd, CONFIG_DIR_NAME, "review");
 			await fs.promises.mkdir(dir, { recursive: true });
@@ -276,19 +335,7 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 			const fp = path.join(dir, `${ts}-${safeId}.json`);
 			await fs.promises.writeFile(
 				fp,
-				JSON.stringify(
-					{
-						level: params.level,
-						reportId: params.report_id ?? null,
-						target: params.target ?? null,
-						filesChanged: params.files_changed ?? null,
-						fannedOut: params.fanned_out ?? null,
-						generatedAt: now.toISOString(),
-						findings,
-					},
-					null,
-					2,
-				),
+				JSON.stringify(reportData, null, 2),
 				{ encoding: "utf-8", mode: 0o600 },
 			);
 			outFile = fp;
@@ -308,6 +355,7 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 		};
 		return {
 			content: [{ type: "text" as const, text: report + tail }],
+			structuredContent: reportData,
 			details,
 		};
 	},