pi-harness-runtime 1.1.407 → 1.1.408

package/packages/two-phase-review/src/scope.ts

@@ -0,0 +1,247 @@
+/**
+ * The review scope.
+ *
+ * The scope of the review is the diff of the task: the changes since the
+ * revision the task started at, including the uncommitted ones. It is never
+ * the whole repository. A large scope is split into logical chunks so the
+ * review can run per module.
+ */
+
+import { spawnSync } from "node:child_process";
+import type { ReviewChunk } from "./types.js";
+
+/** Directories that never belong to a review scope. */
+export const EXCLUDED_SCOPE_PREFIXES: string[] = [
+	"node_modules",
+	"dist",
+	"build",
+	"out",
+	"coverage",
+	".next",
+	".turbo",
+	".cache",
+	"vendor",
+	"__pycache__",
+];
+
+/** Is the path part of a review scope? */
+export function isReviewablePath(file: string): boolean {
+	const path = file.trim().replace(/^\.\//, "");
+	if (!path) return false;
+	// An excluded directory is excluded everywhere in the path, not only at
+	// its root: "packages/foo/dist/index.js" is generated as well.
+	const segments = path.split("/").filter(Boolean);
+	return !segments.some((segment) => EXCLUDED_SCOPE_PREFIXES.includes(segment));
+}
+
+interface GitResult {
+	ok: boolean;
+	stdout: string;
+}
+
+function runGit(root: string, args: string[]): GitResult {
+	try {
+		const result = spawnSync("git", ["-C", root, ...args], {
+			encoding: "utf8",
+			timeout: 20_000,
+			shell: false,
+			maxBuffer: 16 * 1024 * 1024,
+		});
+		if (result.error || result.status !== 0) return { ok: false, stdout: "" };
+		return { ok: true, stdout: result.stdout ?? "" };
+	} catch {
+		return { ok: false, stdout: "" };
+	}
+}
+
+/** Is the workspace a Git repository? */
+export function isGitRepository(root: string): boolean {
+	const result = runGit(root, ["rev-parse", "--is-inside-work-tree"]);
+	return result.ok && result.stdout.trim() === "true";
+}
+
+/** The current revision of the workspace. */
+export function currentRevision(root: string): string | null {
+	const result = runGit(root, ["rev-parse", "HEAD"]);
+	const revision = result.stdout.trim();
+	return result.ok && revision ? revision : null;
+}
+
+/** Does the revision exist in the repository? */
+export function revisionExists(root: string, revision: string): boolean {
+	return runGit(root, ["cat-file", "-e", `${revision}^{commit}`]).ok;
+}
+
+/** The measured size of a scope. */
+export interface ScopeMetrics {
+	files: number;
+	modules: number;
+	changedLines: number;
+}
+
+/** The scope of the review. */
+export interface ScopeResult {
+	files: string[];
+	detected: boolean;
+	reason: string;
+	metrics: ScopeMetrics;
+}
+
+/** The module a file belongs to (the review chunk it is grouped in). */
+export function moduleKey(file: string): string {
+	const parts = file.split("/").filter(Boolean);
+	if (parts.length >= 2) {
+		const root = parts[0];
+		if (root === "packages" || root === "apps" || root === "services") {
+			return `${root}/${parts[1]}`;
+		}
+		if (root === "harness") {
+			return parts.length >= 3 ? `harness/${parts[1]}` : "harness";
+		}
+		return root;
+	}
+	return "root";
+}
+
+/** Count the modules a scope crosses. */
+export function countModules(files: string[]): number {
+	return new Set(files.map((file) => moduleKey(file))).size;
+}
+
+/** Parse `git diff --numstat` into the changed line count. */
+export function parseNumstat(output: string): number {
+	let lines = 0;
+	for (const row of output.split("\n")) {
+		const parts = row.split("\t");
+		if (parts.length < 3) continue;
+		const added = Number.parseInt(parts[0] ?? "", 10);
+		const removed = Number.parseInt(parts[1] ?? "", 10);
+		if (Number.isFinite(added)) lines += added;
+		if (Number.isFinite(removed)) lines += removed;
+	}
+	return lines;
+}
+
+/**
+ * Collect the files the review has to cover.
+ *
+ * The scope is the diff since the start revision (committed and uncommitted)
+ * plus the untracked files. A workspace that is not a Git repository has no
+ * honest scope, so nothing is reviewed.
+ */
+export function collectScope(root: string, startRevision: string | null): ScopeResult {
+	const empty: ScopeResult = {
+		files: [],
+		detected: false,
+		reason: "the workspace is not a Git repository",
+		metrics: { files: 0, modules: 0, changedLines: 0 },
+	};
+
+	if (!isGitRepository(root)) return empty;
+
+	let base = startRevision;
+	if (base && !revisionExists(root, base)) {
+		// A missing baseline would silently reduce the scope to the last
+		// commit, so the scope is empty instead of incomplete.
+		return {
+			...empty,
+			reason: `the revision the task started at (${base.slice(0, 7)}) does not exist`,
+		};
+	}
+	const revision = base ?? "HEAD";
+
+	const diff = runGit(root, ["diff", "--name-only", revision]);
+	if (!diff.ok) {
+		return { ...empty, reason: `the diff against ${revision} could not be read` };
+	}
+
+	const files = new Set<string>();
+	for (const line of diff.stdout.split("\n")) {
+		const file = line.trim();
+		if (file) files.add(file);
+	}
+
+	const untracked = runGit(root, ["ls-files", "--others", "--exclude-standard"]);
+	if (!untracked.ok) {
+		// Without the untracked files the scope would miss new work.
+		return { ...empty, reason: "the untracked files of the workspace could not be read" };
+	}
+	for (const line of untracked.stdout.split("\n")) {
+		const file = line.trim();
+		if (file) files.add(file);
+	}
+
+	const scopeFiles = [...files]
+		.filter((file) => isReviewablePath(file))
+		.sort((a, b) => a.localeCompare(b));
+	const numstat = runGit(root, ["diff", "--numstat", revision]);
+
+	return {
+		files: scopeFiles,
+		detected: true,
+		reason: base ? `the diff since ${base.slice(0, 7)}` : "the diff since HEAD",
+		metrics: {
+			files: scopeFiles.length,
+			modules: countModules(scopeFiles),
+			changedLines: numstat.ok ? parseNumstat(numstat.stdout) : 0,
+		},
+	};
+}
+
+/** The default number of files one review chunk covers. */
+export const DEFAULT_CHUNK_SIZE = 12;
+
+/**
+ * Split a scope into independent review chunks.
+ *
+ * The chunks follow the modules of the change, so a reviewer of one chunk
+ * does not read the same files as a reviewer of another one.
+ */
+export function chunkScope(
+	files: string[],
+	options: { maxFilesPerChunk?: number } = {},
+): ReviewChunk[] {
+	const maxFiles = Math.max(1, options.maxFilesPerChunk ?? DEFAULT_CHUNK_SIZE);
+	const groups = new Map<string, string[]>();
+	for (const file of files) {
+		const key = moduleKey(file);
+		const group = groups.get(key) ?? [];
+		group.push(file);
+		groups.set(key, group);
+	}
+
+	const ordered = [...groups.entries()].sort(
+		(a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]),
+	);
+
+	const chunks: ReviewChunk[] = [];
+	let index = 0;
+	for (const [key, group] of ordered) {
+		for (let start = 0; start < group.length; start += maxFiles) {
+			const slice = group.slice(start, start + maxFiles);
+			index += 1;
+			chunks.push({
+				id: `chunk-${index}`,
+				label: `${key} (${slice.length} file${slice.length === 1 ? "" : "s"})`,
+				files: slice,
+				status: "pending",
+			});
+		}
+	}
+	return chunks;
+}
+
+/**
+ * Is the scope large enough to be split?
+ *
+ * The threshold is measured, not assumed: a scope counts as large when it
+ * crosses many modules or many files.
+ */
+export function shouldChunkScope(
+	metrics: ScopeMetrics,
+	thresholds: { maxFiles?: number; maxModules?: number } = {},
+): boolean {
+	const maxFiles = thresholds.maxFiles ?? 12;
+	const maxModules = thresholds.maxModules ?? 3;
+	return metrics.files > maxFiles || metrics.modules > maxModules;
+}

package/packages/two-phase-review/src/signals.ts

@@ -0,0 +1,340 @@
+/**
+ * Review signals.
+ *
+ * A "review now" signal is any attempt to start a comprehensive review while
+ * the implementation is still running. The workflow records the signal and
+ * defers the review instead of letting it interrupt the implementation.
+ */
+
+import type { ReviewSignal } from "./types.js";
+
+/**
+ * Tool names that start a comprehensive review of the change.
+ *
+ * Task-level checks (a type error of the file that is edited right now, a
+ * failing test of that file) are deliberately absent: they belong to the
+ * implementation and stay actionable.
+ */
+export const DEFAULT_REVIEW_TOOL_PATTERNS: string[] = [
+	"code-review",
+	"code_review",
+	"code-reviewer",
+	"code_reviewer",
+	"differential-review",
+	"differential_review",
+	"variant-analysis",
+	"variant_analysis",
+	"fp-check",
+	"fp_check",
+	"semgrep",
+	"codeql",
+	"durable-review",
+	"durable_review",
+	"spec-to-code-compliance",
+	"spec_to_code_compliance",
+	"security-threat-model",
+	"security_threat_model",
+	"supply-chain",
+	"insecure-defaults",
+	"sharp-edges",
+	"agentic-actions",
+	"audit",
+];
+
+/**
+ * Command patterns that start a dedicated review runner from a shell.
+ *
+ * The list is narrow on purpose: a shell command is only a review signal when
+ * it runs a review runner, never when it merely mentions one.
+ */
+export const DEFAULT_REVIEW_COMMAND_PATTERNS: string[] = [
+	"code-review",
+	"code-reviewer",
+	"differential-review",
+	"variant-analysis",
+	"fp-check",
+	"semgrep",
+	"codeql",
+	"durable-review",
+	"security-review",
+	"security-reviewer",
+];
+
+/** The programs that run another program. */
+const LAUNCHERS = new Set([
+	"npx",
+	"bunx",
+	"bun",
+	"pnpm",
+	"pnpx",
+	"yarn",
+	"dlx",
+	"uvx",
+	"pipx",
+	"deno",
+	"node",
+	"python",
+	"python3",
+]);
+
+/** The words a launcher uses to name the program it runs. */
+const LAUNCHER_SUBCOMMANDS = new Set(["run", "x", "dlx", "exec"]);
+
+/** Normalize a name: lower case, spaces and underscores become dashes. */
+function normalizeName(name: string): string {
+	return (name ?? "")
+		.trim()
+		.toLowerCase()
+		.replace(/[\s_]+/g, "-");
+}
+
+/**
+ * The candidates of a tool name.
+ *
+ * A tool is identified by its full name and by the name behind its
+ * namespace ("mcp__pi__code-review" is "code-review").
+ */
+function toolNameCandidates(name: string): string[] {
+	const raw = (name ?? "").trim();
+	if (!raw) return [];
+	const candidates = new Set<string>();
+	const add = (value: string): void => {
+		const normalized = normalizeName(value);
+		if (normalized) candidates.add(normalized);
+	};
+	add(raw);
+	const segments = raw.split(/__|[:/]/).filter(Boolean);
+	if (segments.length > 1) add(segments[segments.length - 1]);
+	return [...candidates];
+}
+
+/**
+ * The program a shell segment runs.
+ *
+ * Only the program matters: a command that mentions a review runner as an
+ * argument ("echo code-review") does not run one.
+ */
+function commandExecutable(segment: string): string {
+	const tokens = segment.trim().split(/\s+/).filter(Boolean);
+	let index = 0;
+	while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[index])) index += 1;
+	while (
+		index < tokens.length &&
+		["sudo", "env", "command", "time", "nohup"].includes(tokens[index].toLowerCase())
+	) {
+		index += 1;
+	}
+	while (index < tokens.length && tokens[index].startsWith("-")) index += 1;
+	let executable = tokens[index] ?? "";
+	if (!executable) return "";
+	if (LAUNCHERS.has(executable.toLowerCase())) {
+		index += 1;
+		while (index < tokens.length && tokens[index].startsWith("-")) index += 1;
+		if (LAUNCHER_SUBCOMMANDS.has((tokens[index] ?? "").toLowerCase())) index += 1;
+		executable = tokens[index] ?? "";
+	}
+	const name = executable.split("/").pop() ?? "";
+	return normalizeName(name.replace(/\.(js|mjs|cjs|ts|sh)$/, ""));
+}
+
+/** Read the extra patterns a deployment configured. */
+export function parseExtraPatterns(env: NodeJS.ProcessEnv = process.env): string[] {
+	const raw = env.PI_TWO_PHASE_REVIEW_TOOLS;
+	if (!raw) return [];
+	return raw
+		.split(",")
+		.map((entry) => entry.trim().toLowerCase())
+		.filter(Boolean);
+}
+
+/**
+ * Does the tool name name a comprehensive review?
+ *
+ * The name is matched exactly: a tool that only contains the name of a
+ * review ("read_audit_log") is ordinary work.
+ */
+export function isComprehensiveReviewTool(
+	toolName: string,
+	extraPatterns: string[] = [],
+): boolean {
+	const candidates = toolNameCandidates(toolName);
+	if (candidates.length === 0) return false;
+	const patterns = [...DEFAULT_REVIEW_TOOL_PATTERNS, ...extraPatterns].map(normalizeName);
+	return candidates.some((candidate) => patterns.includes(candidate));
+}
+
+/** Does the shell command run a dedicated review runner? */
+export function isReviewCommand(command: string): boolean {
+	const text = (command ?? "").toLowerCase();
+	if (!text) return false;
+	const runners = new Set(DEFAULT_REVIEW_COMMAND_PATTERNS.map(normalizeName));
+	const segments = text.split(/(?:\|\||&&|[;\n|])/);
+	return segments.some((segment) => {
+		const executable = commandExecutable(segment);
+		return executable !== "" && runners.has(executable);
+	});
+}
+
+/** The agent name of a generic dispatch tool, when it has one. */
+export function dispatchAgentName(toolName: string, input: unknown): string {
+	if (!["subagent", "task", "dispatch_agent"].includes(toolName)) return "";
+	const args = (input ?? {}) as Record<string, unknown>;
+	const candidates = [args.agent, args.subagent_type, args.agentName, args.role];
+	for (const candidate of candidates) {
+		if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+	}
+	return "";
+}
+
+/** A review request that the harness recognized. */
+export interface ReviewInvocation {
+	/** The source of the request (tool name, agent name or command). */
+	source: string;
+	/** The files the request points at (best effort). */
+	files: string[];
+	/** One short line describing the request. */
+	reason: string;
+}
+
+const SOURCE_FILE_PATTERN =
+	/(?:^|[\s"'`(=])((?:\.{0,2}\/)?(?:[\w.@+-]+\/)*[\w.@+-]+\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs))/g;
+
+/** Pull file names out of a tool input (best effort). */
+export function extractFiles(toolName: string, input: unknown): string[] {
+	const args = (input ?? {}) as Record<string, unknown>;
+	const files = new Set<string>();
+
+	const add = (value: unknown): void => {
+		if (typeof value === "string" && value.trim()) files.add(value.trim());
+	};
+	const addList = (value: unknown): void => {
+		if (Array.isArray(value)) {
+			for (const entry of value) add(entry);
+			return;
+		}
+		add(value);
+	};
+
+	for (const key of ["files", "paths", "path", "file", "target", "targets", "scope"]) {
+		addList(args[key]);
+	}
+
+	if (toolName === "bash" && typeof args.command === "string") {
+		const matches = args.command.matchAll(SOURCE_FILE_PATTERN);
+		for (const match of matches) {
+			if (match[1]) files.add(match[1]);
+		}
+	}
+
+	return [...files].slice(0, 200);
+}
+
+/**
+ * Recognize a request to start a comprehensive review.
+ *
+ * Returns `null` when the call is an ordinary task-level check.
+ */
+export function detectReviewInvocation(
+	toolName: string,
+	input: unknown,
+	extraPatterns: string[] = [],
+): ReviewInvocation | null {
+	if (isComprehensiveReviewTool(toolName, extraPatterns)) {
+		return {
+			source: toolName,
+			files: extractFiles(toolName, input),
+			reason: `a comprehensive review was requested with ${toolName}`,
+		};
+	}
+
+	const agent = dispatchAgentName(toolName, input);
+	if (agent && isComprehensiveReviewTool(agent, extraPatterns)) {
+		return {
+			source: agent,
+			files: extractFiles(toolName, input),
+			reason: `a comprehensive review was requested with the ${agent} reviewer`,
+		};
+	}
+
+	if (toolName === "bash") {
+		const command = (input as Record<string, unknown> | null)?.command;
+		if (typeof command === "string" && isReviewCommand(command)) {
+			return {
+				source: "bash",
+				files: extractFiles(toolName, input),
+				reason: `a review runner was started: ${command.trim().slice(0, 160)}`,
+			};
+		}
+	}
+
+	return null;
+}
+
+/**
+ * A negation of a review request.
+ *
+ * The negation is read per sentence, so "do not review yet" does not silence
+ * a later "please review the diff".
+ */
+const NEGATED_REVIEW =
+	/\b(?:do not|don'?t|does not|doesn'?t|no|without|skip|avoid|postpone|defer|later|not yet|never)\b[^.!?\n]{0,40}\b(?:review|audit)\b/i;
+
+/** The ways a human asks for a review. */
+const AFFIRMATIVE_REVIEW: RegExp[] = [
+	/\b(?:please\s+)?(?:run|do|perform|start|begin|execute|launch|carry out|give)\s+(?:a\s+|an\s+|the\s+)?(?:comprehensive\s+|full\s+|complete\s+|code\s+|security\s+)?(?:review|audit)\b/i,
+	/\b(?:can|could|would|will|shall)\s+you\s+(?:please\s+)?(?:review|audit)\b/i,
+	/\b(?:review|audit)\s+(?:the|this|that|my|our|it|everything|all|each)\b/i,
+	/^\s*(?:please\s+)?(?:review|audit)\b/i,
+	/\b(?:review|audit)\s+(?:now|again)\b/i,
+];
+
+/**
+ * Did the human ask for a review explicitly?
+ *
+ * The phase order never overrides the intent of the user: an explicit request
+ * runs the review now. A sentence that talks about a review without asking
+ * for one is not a request.
+ */
+export function explicitReviewRequest(message: string): boolean {
+	if (!message) return false;
+	const sentences = message.split(/(?<=[.!?])\s+/);
+	return sentences.some((sentence) => {
+		if (NEGATED_REVIEW.test(sentence)) return false;
+		return AFFIRMATIVE_REVIEW.some((pattern) => pattern.test(sentence));
+	});
+}
+
+/** The identity of a signal: the same signal is never recorded twice. */
+export function signalKey(signal: ReviewSignal): string {
+	const files = [...signal.files].sort().join(",");
+	return `${signal.source}::${files}::${signal.reason.trim().toLowerCase()}`;
+}
+
+/** Add a signal, ignoring an identical one. */
+export function mergeSignals(
+	signals: ReviewSignal[],
+	signal: ReviewSignal,
+	limit = 50,
+): ReviewSignal[] {
+	const key = signalKey(signal);
+	if (signals.some((entry) => signalKey(entry) === key)) return signals;
+	const next = [...signals, signal];
+	return next.length > limit ? next.slice(next.length - limit) : next;
+}
+
+/** The merged view of every recorded signal. */
+export interface SignalSummary {
+	sources: string[];
+	files: string[];
+	reason: string;
+}
+
+/** Merge the recorded signals into one scope. */
+export function summarizeSignals(signals: ReviewSignal[]): SignalSummary {
+	const sources = [...new Set(signals.map((signal) => signal.source))];
+	const files = [...new Set(signals.flatMap((signal) => signal.files))];
+	const reason = [...new Set(signals.map((signal) => signal.reason.trim()).filter(Boolean))].join(
+		"; ",
+	);
+	return { sources, files, reason };
+}