@fyeeme/pi-review 1.1.1 → 2.0.1

package/src/strategy.ts

@@ -0,0 +1,76 @@
+/**
+ * src/strategy.ts — declarative parallel-strategy evaluation.
+ *
+ * v1's decideSimplifyMode hardcoded its thresholds in the command handler;
+ * v2 declares them as data in the prompt templates' frontmatter and this
+ * module evaluates the declared guards against runtime variables. Same
+ * semantics, different authority: editing a template's `parallel-when`
+ * block changes the strategy with no code change.
+ *
+ * Fallback-when-unguarded rules (v1 semantics, kept in code because they
+ * are safety invariants, not tuning knobs): unmeasurable context and an
+ * unavailable fan-out tool always select single-pass.
+ */
+
+/** Guards declared in a template's `parallel-when` frontmatter block. */
+export interface ParallelGuards {
+	/** Select single-pass when context usage is at or above this fraction. */
+	readonly contextBelow?: number;
+	/** Select single-pass when the diff reaches this many chars. */
+	readonly diffCharsBelow?: number;
+}
+
+/** Runtime variables gathered by the dispatcher. */
+export interface StrategyRuntime {
+	readonly tokens: number | null;
+	readonly contextWindow: number;
+	readonly diffChars: number;
+	/** Whether fan-out tools are registered in this process (the recursion
+	 *  guard): single-pass is the only option when false. */
+	readonly fanoutAvailable: boolean;
+}
+
+export type ReviewVariant = "parallel" | "single-pass";
+
+/**
+ * Evaluate the declared guards. Returns the variant plus the reasons that
+ * produced it (rendered into the trigger message so the decision stays
+ * observable). Pure — unit-testable.
+ */
+export function selectVariant(
+	guards: ParallelGuards,
+	runtime: StrategyRuntime,
+): { variant: ReviewVariant; reasons: string[] } {
+	const { tokens, contextWindow, diffChars, fanoutAvailable } = runtime;
+	const reasons: string[] = [];
+	// Conservative safety invariant (not a tunable): if we can't measure
+	// context (tokens unknown / window 0), don't risk fan-out.
+	if (tokens == null || contextWindow <= 0) reasons.push("context usage unknown");
+	if (
+		guards.contextBelow != null &&
+		tokens != null &&
+		contextWindow > 0 &&
+		tokens / contextWindow >= guards.contextBelow
+	)
+		reasons.push(`context ${Math.round((tokens / contextWindow) * 100)}% full`);
+	if (guards.diffCharsBelow != null && diffChars >= guards.diffCharsBelow)
+		reasons.push(`diff too large (${Math.round(diffChars / 1024)} KB ≥ fan-out threshold)`);
+	if (!fanoutAvailable) reasons.push("fan-out unavailable in this context (subagent recursion guard)");
+	return { variant: reasons.length > 0 ? "single-pass" : "parallel", reasons };
+}
+
+/** Parse the `parallel-when` block out of a template's frontmatter map.
+ *  Unknown/garbage fields are dropped (silent — garbage becomes absent). */
+export function parseGuards(frontmatter: Record<string, unknown>): ParallelGuards {
+	const raw = frontmatter["parallel-when"];
+	if (!raw || typeof raw !== "object") return {};
+	const r = raw as Record<string, unknown>;
+	const out: { contextBelow?: number; diffCharsBelow?: number } = {};
+	if (typeof r["context-below"] === "number" && r["context-below"] > 0 && r["context-below"] <= 1) {
+		out.contextBelow = r["context-below"];
+	}
+	if (typeof r["diff-chars-below"] === "number" && r["diff-chars-below"] > 0) {
+		out.diffCharsBelow = r["diff-chars-below"];
+	}
+	return out;
+}

package/src/tools/review_report.ts

@@ -7,7 +7,8 @@
  * no host finding-renderer, so this tool does double duty: it renders a tidy
  * Chinese Markdown report (table + details) back to the conversation AND writes
  * a machine-readable JSON (findings + level + outcome) to
- * `<cwd>/.pi/review/<id>.json` so CI / --fix / --comment can consume it.
+ * `<cwd>/<CONFIG_DIR_NAME>/review/<id>.json` so CI / --fix / --comment can
+ * consume it.
  *
  * `verdict` (CONFIRMED/PLAUSIBLE) and `outcome` (fixed/skipped/no_change_needed)
  * enums follow the CC ReportFindings shape — values verified against the CC
@@ -16,8 +17,9 @@
  * normalizes stray invalid values (drop the finding / coerce to skipped) rather
  * than failing the whole call.
  */
-import { defineTool, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { defineTool, getMarkdownTheme, CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
 import { Markdown } from "@earendil-works/pi-tui";
+import { StringEnum } from "@earendil-works/pi-ai";
 import { type Static, Type } from "typebox";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -27,25 +29,25 @@ import * as path from "node:path";
 // verdict 两值与 outcome 三档在 2.1.223/226/227 三版本中一致。
 
 const VERDICT_VALUES = ["CONFIRMED", "PLAUSIBLE"] as const;
-const Verdict = Type.Union(VERDICT_VALUES.map((v) => Type.Literal(v)));
+const Verdict = StringEnum(VERDICT_VALUES);
 
 const OUTCOME_VALUES = ["fixed", "skipped", "no_change_needed"] as const;
 /** CC ReportFindings `outcome` 三档（2.1.227 二进制实证）。fixed-later 再上报时更新。 */
-const Outcome = Type.Union(OUTCOME_VALUES.map((v) => Type.Literal(v)));
+const Outcome = StringEnum(OUTCOME_VALUES);
 
 // 供 SKILL-schema 同步测试引用（防漂移：SKILL 流程契约不得与常量脱节）。
 export { OUTCOME_VALUES, VERDICT_VALUES };
 
-const Level = Type.Union([
-	Type.Literal("low"),
-	Type.Literal("medium"),
-	Type.Literal("high"),
-	Type.Literal("xhigh"),
-	Type.Literal("max"),
+const Level = StringEnum([
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
 	// simplify reuses this tool for structured apply-outcome reporting
 	// (harden-code-simplify). Not a review effort level — carries no verdict.
-	Type.Literal("simplify"),
-]);
+	"simplify",
+] as const);
 
 // --- schema -----------------------------------------------------------------
 
@@ -223,12 +225,12 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 	name: "review_report",
 	label: "Report review findings",
 	description:
-		"Report code-review findings as a typed list — Pi's counterpart to CC's ReportFindings. Use this only when the active code-review instructions tell you to report findings with this tool. Call it once with the verified findings ranked most-severe first (empty array if nothing survived verification) and do not also print the findings as text — the tool renders a tidy Chinese Markdown report back to the conversation AND writes a machine-readable JSON to <cwd>/.pi/review/ for CI / --fix / --comment. When re-reporting after applying fixes, set `outcome` on each finding. 上报结构化 code-review 发现（CC ReportFindings 的 Pi 对等物）。",
+		"Report code-review findings as a typed list — Pi's counterpart to CC's ReportFindings. Use this only when the active code-review instructions tell you to report findings with this tool. Call it once with the verified findings ranked most-severe first (empty array if nothing survived verification) and do not also print the findings as text — the tool renders a tidy Chinese Markdown report back to the conversation AND writes a machine-readable JSON to the project's pi config dir (CONFIG_DIR_NAME, typically `.pi`) under review/ for CI / --fix / --comment. When re-reporting after applying fixes, set `outcome` on each finding. 上报结构化 code-review 发现（CC ReportFindings 的 Pi 对等物）。",
 	promptSnippet: "review_report — report structured code-review findings (renders Markdown + writes JSON for CI)",
 	promptGuidelines: [
 		"After verify + dedup, call `review_report` once with { level, findings } (most-severe first; empty array if none survived). Do not also hand-write the Markdown table — this tool renders it.",
 		"On re-report after --fix, set each finding's `outcome` (fixed / skipped / no_change_needed).",
-		"Use this tool only when the code-review skill instructs reporting findings; otherwise follow the active output format.",
+		"Use `review_report` only when the code-review skill instructs reporting findings; otherwise follow the active output format.",
 	],
 	parameters: ReviewReportParams,
 
@@ -267,7 +269,7 @@ export const reviewReportTool = defineTool<typeof ReviewReportParams, ReviewRepo
 		let writeError: string | null = null;
 		const now = new Date();
 		try {
-			const dir = path.join(ctx.cwd, ".pi", "review");
+			const dir = path.join(ctx.cwd, CONFIG_DIR_NAME, "review");
 			await fs.promises.mkdir(dir, { recursive: true });
 			const safeId = toolCallId.replace(/[^\w.-]+/g, "_");
 			const ts = now.toISOString().replace(/[:.]/g, "-");

package/src/commands/code-review.ts

@@ -1,100 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { bundledSkillPath } from "../skills.ts";
-
-/** Effort levels the /code-review command accepts (mirrors CC's effort enum). */
-export const REVIEW_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
-export type ReviewLevel = (typeof REVIEW_LEVELS)[number];
-
-const DEFAULT_LEVEL: ReviewLevel = "low";
-
-/** Where the last explicitly-typed effort is persisted (CC 2.1.223 codeReviewLastEffort). */
-const STATE_FILE = path.join(os.homedir(), ".pi", ".pi-review-state.json");
-
-export type EffortSource = "explicit" | "last-used" | "default";
-
-/**
- * Parse a leading effort level out of raw args; the remainder (flags + target)
- * is returned verbatim. Pure — unit-testable. Mirrors CC's ecl()/Tjn(): the
- * first token is the level only if it matches the enum; otherwise the whole
- * string is the target/flags.
- */
-export function parseReviewArgs(args: string): { level: ReviewLevel | undefined; rest: string } {
-	const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
-	if (tokens.length === 0) return { level: undefined, rest: "" };
-	const first = tokens[0]!.toLowerCase();
-	const isLevel = (REVIEW_LEVELS as readonly string[]).includes(first);
-	return {
-		level: isLevel ? (first as ReviewLevel) : undefined,
-		rest: isLevel ? tokens.slice(1).join(" ") : tokens.join(" "),
-	};
-}
-
-/**
- * Resolve the effective effort + where it came from. Pure — unit-testable.
- * Mirrors CC 2.1.223: explicit wins; otherwise reuse the last-typed level;
- * otherwise the default. (220 defaulted straight to low with no memory.)
- */
-export function resolveEffort(
-	explicit: ReviewLevel | undefined,
-	lastUsed: ReviewLevel | undefined,
-): { level: ReviewLevel; source: EffortSource } {
-	if (explicit) return { level: explicit, source: "explicit" };
-	if (lastUsed) return { level: lastUsed, source: "last-used" };
-	return { level: DEFAULT_LEVEL, source: "default" };
-}
-
-// Best-effort persistence — sticky-effort is a convenience, not a correctness
-// invariant; a read/write failure must not break the review.
-function readLastEffort(): ReviewLevel | undefined {
-	try {
-		const raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8")) as { codeReviewLastEffort?: unknown };
-		const v = raw.codeReviewLastEffort;
-		return typeof v === "string" && (REVIEW_LEVELS as readonly string[]).includes(v)
-			? (v as ReviewLevel)
-			: undefined;
-	} catch {
-		return undefined;
-	}
-}
-function writeLastEffort(level: ReviewLevel): void {
-	try {
-		fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
-		fs.writeFileSync(STATE_FILE, JSON.stringify({ codeReviewLastEffort: level }));
-	} catch {
-		/* ignore — non-critical */
-	}
-}
-
-/**
- * Register the /code-review command — triggers the code-review skill.
- *
- * Handler decides the effective effort deterministically (CC 2.1.223): an
- * explicit level is persisted and used; with no level, the last-typed level is
- * reused; with no history, it falls back to low. The decision is announced in
- * the trigger message so it is observable — same pattern as /code-simplify.
- */
-export function registerCodeReview(pi: ExtensionAPI): void {
-	pi.registerCommand("code-review", {
-		description:
-			"Review the current diff using the code-review skill. Usage: /code-review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<pr#>|<branch>|<path>]",
-		getArgumentCompletions(prefix) {
-			const tokens = ["low", "medium", "high", "xhigh", "max", "--fix", "--comment", "--share"];
-			return tokens.filter((t) => t.startsWith(prefix)).map((t) => ({ label: t, value: t }));
-		},
-		async handler(args) {
-			const { level: explicit, rest } = parseReviewArgs(args ?? "");
-			// Skip the read when we just wrote it — resolveEffort returns `explicit` unchanged.
-			const lastUsed = explicit ? undefined : readLastEffort();
-			if (explicit) writeLastEffort(explicit); // CC 2.1.223: remember the explicit level
-			const { level, source } = resolveEffort(explicit, lastUsed);
-			pi.sendUserMessage(
-				`Run a code review now. Effective effort: ${level} (${source})${rest ? `; extra args: ${rest}` : ""}.\n\n` +
-					`First load the review skill with the read tool: ${bundledSkillPath("code-review/SKILL.md")}. ` +
-					`Then follow it exactly — use the \`subagent\` tool for any fan-out / verify / gap-hunt the skill calls for.`,
-			);
-		},
-	});
-}