@dreki-gg/pi-code-reviewer 0.2.0 → 0.4.0

package/README.md

@@ -59,6 +59,13 @@ Evaluates changes for correctness and adherence to project standards.
 - note: Style suggestions
 ```
 
+> **Tools must be fast and exit on their own** (typecheck, lint, unit tests).
+> Do **not** list dev servers, watch mode, e2e suites, or full production
+> builds — they bind ports / run for minutes and belong in CI. Tools are
+> **deduped across lenses and run concurrently**, so a command shared by
+> several lenses runs once, and a slow/hanging command stalls the whole review
+> (bounded by `toolTimeoutMs`).
+
 ### Bundled lenses
 
 The package ships with four example lenses:
@@ -79,7 +86,9 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
 ```json
 {
   "lensDir": ".code-review/lenses",
-  "defaultLenses": ["code-quality", "maintainability"]
+  "defaultLenses": ["code-quality", "maintainability"],
+  "toolTimeoutMs": 60000,
+  "toolConcurrency": 4
 }
 ```
 
@@ -87,4 +96,6 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
 | --- | --- | --- |
 | `lensDir` | `.code-review/lenses` | Directory containing lens files |
 | `defaultLenses` | `[]` (all) | Lenses to run when none specified |
+| `toolTimeoutMs` | `60000` | Per-tool wall-clock timeout (ms); an exceeding tool is killed and reported as timed-out |
+| `toolConcurrency` | `4` | Max distinct tools run in parallel (tools are deduped across lenses first) |
 

package/extensions/code-reviewer/commands/review-init.ts

@@ -12,10 +12,16 @@ export function registerReviewInitCommand(pi: ExtensionAPI) {
           `Initialize a code review configuration for this project.`,
           ``,
           `1. Read the project's AGENTS.md, package.json, and any CONTEXT.md to understand the stack and conventions.`,
-          `2. Create a \`.code-review.json\` config file at the project root.`,
+          `2. Create a \`.code-review.json\` config file at the project root. Supported keys:`,
+          `   - \`lensDir\` (default \`.code-review/lenses\`), \`defaultLenses\` (lenses run when none are specified),`,
+          `   - \`toolTimeoutMs\` (per-tool timeout, default 60000), \`toolConcurrency\` (parallel tools, default 4).`,
           `3. Create lens files in \`.code-review/lenses/\` — start with: code-quality.md, maintainability.md`,
-          `4. Each lens should reference the project's actual tools (from package.json scripts).`,
-          `5. Tailor the criteria to the project's stack and conventions.`,
+          `4. Each lens's \`## Tools\` must list ONLY fast, non-side-effecting commands that EXIT on their own`,
+          `   (e.g. typecheck, lint, unit tests). Do NOT list dev servers, watch mode, e2e suites, or full`,
+          `   production builds — they bind ports / run for minutes and belong in CI. Tools are deduped across`,
+          `   lenses and run concurrently, so a slow or hanging command stalls the whole review.`,
+          `5. Tailor the criteria to the project's stack and conventions; prefer concrete, pattern-matched checks`,
+          `   (name the project's real failure modes + the diff "smells" to look for) over generic virtues.`,
           ``,
           `Config path: ${configPath}`,
         ].join('\n'),

package/extensions/code-reviewer/commands/review-lenses.ts

@@ -7,9 +7,9 @@ export function registerReviewLensesCommand(pi: ExtensionAPI) {
   pi.registerCommand('review-lenses', {
     description: 'List available review lenses for this project',
     handler: async (_args, ctx) => {
-      const config = loadConfig(ctx.cwd);
+      const config = await loadConfig(ctx.cwd);
       const lensDir = getLensDir(ctx.cwd, config);
-      const available = discoverLenses(lensDir);
+      const available = await discoverLenses(lensDir);
 
       if (available.size === 0) {
         ctx.ui.notify(

package/extensions/code-reviewer/commands/review-tool.ts

@@ -4,9 +4,9 @@ import { Type } from 'typebox';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff, getChangedFiles } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { reviewWithLens } from '../reviewer';
-import { buildReport } from '../report';
-import type { LensResult, ReviewConfig, ReviewReport } from '../types';
+import { buildDiffSection, buildLensResult, pickLensToolOutputs, runTools } from '../reviewer';
+import type { DiffSource } from '../diff';
+import type { LensResult, ReviewConfig } from '../types';
 
 export function registerReviewTool(pi: ExtensionAPI) {
   pi.registerTool({
@@ -40,9 +40,9 @@ export function registerReviewTool(pi: ExtensionAPI) {
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const cwd = ctx.cwd;
-      const config = loadConfig(cwd);
+      const config = await loadConfig(cwd);
       const lensDir = getLensDir(cwd, config);
-      const available = discoverLenses(lensDir);
+      const available = await discoverLenses(lensDir);
 
       if (available.size === 0) {
         return {
@@ -72,6 +72,23 @@ export function registerReviewTool(pi: ExtensionAPI) {
         };
       }
 
+      const selected = lensNames.map((name) => available.get(name)!);
+
+      // Run the DISTINCT tool set once (deduped across lenses), concurrently —
+      // not once per lens. A command shared by several lenses executes a single
+      // time and its output is shared.
+      const allTools = [...new Set(selected.flatMap((lens) => lens.tools))];
+      if (allTools.length > 0) {
+        ctx.ui.setStatus('code-review', `🔍 Running ${allTools.length} tool(s)...`);
+      }
+      const toolOutputs = await runTools(
+        pi,
+        cwd,
+        allTools,
+        { timeoutMs: config.toolTimeoutMs, concurrency: config.toolConcurrency },
+        signal,
+      );
+
       const results: LensResult[] = [];
       for (let i = 0; i < lensNames.length; i++) {
         if (signal?.aborted) break;
@@ -84,26 +101,21 @@ export function registerReviewTool(pi: ExtensionAPI) {
           details: { currentLens: name, lensIndex: i + 1, totalLenses: lensNames.length },
         });
 
-        const lens = available.get(name)!;
-        const content = getLensContent(lensDir, name) ?? '';
-        const result = await reviewWithLens(pi, ctx, cwd, lens, content, diff, signal);
-        results.push(result);
+        const lens = selected[i];
+        const content = (await getLensContent(lensDir, name)) ?? '';
+        results.push(buildLensResult(lens, content, pickLensToolOutputs(lens, toolOutputs)));
       }
 
       ctx.ui.setStatus('code-review', undefined);
 
-      const report: ReviewReport = {
-        diff: diff.diff,
-        diffStat: diff.stat,
-        lenses: results,
-        generatedAt: new Date().toISOString().slice(0, 10),
-      };
-
-      const markdown = buildReport(report);
-      const toolContext = buildToolContext(results);
+      // The tool returns a pre-review skeleton + the review task. Findings are
+      // produced by the agent in its follow-up message (per the instructions
+      // below), NOT parsed back here — so we deliberately do not render a
+      // findings scoreboard that would always read "0".
+      const text = buildToolContext(results, diff);
 
       return {
-        content: [{ type: 'text', text: markdown + toolContext }],
+        content: [{ type: 'text', text }],
         details: {
           lensCount: lensNames.length,
           availableLenses: [...available.keys()],
@@ -131,17 +143,42 @@ function resolveLensNames(
   return [...available.keys()];
 }
 
-function buildToolContext(results: LensResult[]): string {
-  const prompts = results.map((r) => r._prompt).filter(Boolean);
-
-  if (prompts.length === 0) return '';
+/**
+ * Build the agent-facing review instructions appended to the report. The diff
+ * is embedded ONCE (not per lens) followed by each lens's section — large
+ * diffs would otherwise be repeated for every lens, bloating the tool output.
+ */
+function buildToolContext(results: LensResult[], diff: DiffSource): string {
+  const sections = results.map((r) => r._lensSection).filter(Boolean) as string[];
+  if (sections.length === 0) return '';
 
   return [
+    `# Code Review — ${new Date().toISOString().slice(0, 10)}`,
+    '',
+    '## Changes',
+    '```',
+    diff.stat.trim() || '(no diffstat)',
+    '```',
+    '',
+    'Evaluate the diff through each lens below; the tool outputs are automated analysis.',
+    '',
+    buildDiffSection(diff),
+    '',
+    '## Lenses',
+    '',
+    ...sections,
+    '',
+    '## Instructions',
     '',
-    '---',
+    'For each lens above, review the diff against its criteria and output a JSON array of findings:',
     '',
-    'The tool outputs above provide automated analysis. Now evaluate the diff through each lens criteria:',
+    '```json',
+    '[',
+    '  { "file": "path/to/file.ts", "line": 42, "severity": "warning", "message": "Description" }',
+    ']',
+    '```',
     '',
-    ...prompts,
+    'After each lens JSON array, write a 2-3 sentence summary.',
+    'If a lens has no findings, return an empty array `[]` and note the code looks good.',
   ].join('\n');
 }

package/extensions/code-reviewer/commands/review.ts

@@ -3,7 +3,7 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { reviewWithLens, buildDiffSection } from '../reviewer';
+import { buildDiffSection, buildLensResult, pickLensToolOutputs, runTools } from '../reviewer';
 import { parseReviewArgs } from '../parse-args';
 
 export function registerReviewCommand(pi: ExtensionAPI) {
@@ -12,9 +12,9 @@ export function registerReviewCommand(pi: ExtensionAPI) {
       'Run a multi-lens code review on working directory changes. Usage: /review [--lens name,...] [--base ref] [--staged]',
     handler: async (args, ctx) => {
       const cwd = ctx.cwd;
-      const config = loadConfig(cwd);
+      const config = await loadConfig(cwd);
       const lensDir = getLensDir(cwd, config);
-      const available = discoverLenses(lensDir);
+      const available = await discoverLenses(lensDir);
 
       if (available.size === 0) {
         ctx.ui.notify(
@@ -47,20 +47,26 @@ export function registerReviewCommand(pi: ExtensionAPI) {
       }
 
       ctx.ui.notify(`Reviewing ${diff.label} through ${lensNames.length} lens(es)...`, 'info');
-      ctx.ui.setStatus('code-review', `🔍 Reviewing (0/${lensNames.length})...`);
+
+      const selected = lensNames.map((name) => available.get(name)!);
+
+      // Run the DISTINCT tool set once (deduped across lenses), concurrently.
+      const allTools = [...new Set(selected.flatMap((lens) => lens.tools))];
+      ctx.ui.setStatus('code-review', `🔍 Running ${allTools.length} tool(s)...`);
+      const toolOutputs = await runTools(pi, cwd, allTools, {
+        timeoutMs: config.toolTimeoutMs,
+        concurrency: config.toolConcurrency,
+      });
 
       const lensSections: string[] = [];
       for (let i = 0; i < lensNames.length; i++) {
         const name = lensNames[i];
         ctx.ui.setStatus('code-review', `🔍 Lens ${i + 1}/${lensNames.length}: ${name}`);
 
-        const lens = available.get(name)!;
-        const content = getLensContent(lensDir, name) ?? '';
-        const result = await reviewWithLens(pi, ctx, cwd, lens, content, diff);
-
-        if (result._lensSection) {
-          lensSections.push(result._lensSection);
-        }
+        const lens = selected[i];
+        const content = (await getLensContent(lensDir, name)) ?? '';
+        const result = buildLensResult(lens, content, pickLensToolOutputs(lens, toolOutputs));
+        if (result._lensSection) lensSections.push(result._lensSection);
       }
 
       ctx.ui.setStatus('code-review', undefined);

package/extensions/code-reviewer/config.ts

@@ -1,30 +1,63 @@
-import { readFileSync, existsSync } from 'node:fs';
+/**
+ * Review configuration loader.
+ *
+ * Reading `.code-review.json` is an Effect program against the FileSystem
+ * service; a missing or malformed file falls back to defaults (never fails).
+ * The Promise wrapper provides the live service for imperative call sites.
+ */
+
+import { Effect } from 'effect';
 import { resolve } from 'node:path';
+
+import { FileSystem, nodeFileSystemService } from './effects/filesystem';
 import type { ReviewConfig } from './types';
 
 const CONFIG_FILE = '.code-review.json';
 const DEFAULT_LENS_DIR = '.code-review/lenses';
+const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
+const DEFAULT_TOOL_CONCURRENCY = 4;
 
-export function loadConfig(cwd: string): ReviewConfig {
-  const configPath = resolve(cwd, CONFIG_FILE);
+function defaultConfig(): ReviewConfig {
+  return {
+    lensDir: DEFAULT_LENS_DIR,
+    defaultLenses: [],
+    toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
+    toolConcurrency: DEFAULT_TOOL_CONCURRENCY,
+  };
+}
+
+/** Coerce a config value to a positive integer, falling back when absent/invalid. */
+function positiveIntOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : fallback;
+}
+
+export function loadConfigEffect(cwd: string): Effect.Effect<ReviewConfig, never, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const raw = yield* fs.readTextFile(getConfigPath(cwd)).pipe(Effect.either);
+    if (raw._tag === 'Left') return defaultConfig();
 
-  if (existsSync(configPath)) {
     try {
-      const raw = readFileSync(configPath, 'utf-8');
-      const parsed = JSON.parse(raw) as Partial<ReviewConfig>;
+      const parsed = JSON.parse(raw.right) as Partial<ReviewConfig>;
       return {
         lensDir: parsed.lensDir ?? DEFAULT_LENS_DIR,
         defaultLenses: parsed.defaultLenses ?? [],
+        toolTimeoutMs: positiveIntOr(parsed.toolTimeoutMs, DEFAULT_TOOL_TIMEOUT_MS),
+        toolConcurrency: positiveIntOr(parsed.toolConcurrency, DEFAULT_TOOL_CONCURRENCY),
       };
     } catch {
-      // Malformed config — fall back to defaults
+      // Malformed config — fall back to defaults.
+      return defaultConfig();
     }
-  }
+  });
+}
 
-  return {
-    lensDir: DEFAULT_LENS_DIR,
-    defaultLenses: [],
-  };
+export function loadConfig(cwd: string): Promise<ReviewConfig> {
+  return Effect.runPromise(
+    loadConfigEffect(cwd).pipe(Effect.provideService(FileSystem, nodeFileSystemService)),
+  );
 }
 
 export function getLensDir(cwd: string, config: ReviewConfig): string {

package/extensions/code-reviewer/diff.ts

@@ -1,4 +1,15 @@
+/**
+ * Diff collection.
+ *
+ * Git invocations run through the Executor service as typed Effects. The
+ * Promise wrappers build a live Executor from `pi` for imperative call sites.
+ */
+
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Effect } from 'effect';
+
+import { Executor, makeExecutorService } from './effects/exec';
+import type { ExecError } from './errors';
 
 export type DiffSource = {
   diff: string;
@@ -6,73 +17,94 @@ export type DiffSource = {
   label: string;
 };
 
+export type DiffOptions = { base?: string; staged?: boolean };
+
+/** git diffs are normally instant; cap them so a pathological repo can't hang
+ *  the whole review. */
+const GIT_TIMEOUT_MS = 30_000;
+
+function git(args: string[], cwd: string): Effect.Effect<string, ExecError, Executor> {
+  return Effect.gen(function* () {
+    const executor = yield* Executor;
+    const result = yield* executor.exec('git', args, { cwd, timeout: GIT_TIMEOUT_MS });
+    return result.stdout;
+  });
+}
+
 /** Collect the diff from the working directory or a specific base ref. */
-export async function collectDiff(
-  pi: ExtensionAPI,
+export function collectDiffEffect(
   cwd: string,
-  options: { base?: string; staged?: boolean },
-): Promise<DiffSource> {
-  if (options.staged) {
-    const diff = await pi.exec('git', ['diff', '--staged'], { cwd });
-    const stat = await pi.exec('git', ['diff', '--staged', '--stat'], { cwd });
-    return {
-      diff: diff.stdout,
-      stat: stat.stdout,
-      label: 'staged changes',
-    };
-  }
-
-  if (options.base) {
-    const diff = await pi.exec('git', ['diff', options.base], { cwd });
-    const stat = await pi.exec('git', ['diff', options.base, '--stat'], { cwd });
-    return {
-      diff: diff.stdout,
-      stat: stat.stdout,
-      label: `changes since ${options.base}`,
-    };
-  }
-
-  // Default: working directory changes (unstaged + staged)
-  const diff = await pi.exec('git', ['diff', 'HEAD'], { cwd });
-  const stat = await pi.exec('git', ['diff', 'HEAD', '--stat'], { cwd });
-
-  // If no HEAD diff, fall back to just working directory
-  if (!diff.stdout.trim()) {
-    const wdDiff = await pi.exec('git', ['diff'], { cwd });
-    const wdStat = await pi.exec('git', ['diff', '--stat'], { cwd });
-    return {
-      diff: wdDiff.stdout,
-      stat: wdStat.stdout,
-      label: 'working directory changes',
-    };
-  }
-
-  return {
-    diff: diff.stdout,
-    stat: stat.stdout,
-    label: 'all uncommitted changes',
-  };
+  options: DiffOptions,
+): Effect.Effect<DiffSource, ExecError, Executor> {
+  return Effect.gen(function* () {
+    if (options.staged) {
+      const diff = yield* git(['diff', '--staged'], cwd);
+      const stat = yield* git(['diff', '--staged', '--stat'], cwd);
+      return { diff, stat, label: 'staged changes' };
+    }
+
+    if (options.base) {
+      const diff = yield* git(['diff', options.base], cwd);
+      const stat = yield* git(['diff', options.base, '--stat'], cwd);
+      return { diff, stat, label: `changes since ${options.base}` };
+    }
+
+    // Default: working directory changes (unstaged + staged) relative to HEAD.
+    // `git diff HEAD` fails on a repo with no commits (HEAD is unborn), so
+    // tolerate that and fall back to the bare working-directory diff.
+    const headDiff = yield* git(['diff', 'HEAD'], cwd).pipe(Effect.either);
+
+    // No HEAD (fresh repo) or an empty HEAD diff → fall back to the working dir.
+    if (headDiff._tag === 'Left' || !headDiff.right.trim()) {
+      const wdDiff = yield* git(['diff'], cwd);
+      const wdStat = yield* git(['diff', '--stat'], cwd);
+      return { diff: wdDiff, stat: wdStat, label: 'working directory changes' };
+    }
+
+    const stat = yield* git(['diff', 'HEAD', '--stat'], cwd);
+    return { diff: headDiff.right, stat, label: 'all uncommitted changes' };
+  });
 }
 
 /** Get a list of changed file paths from the diff. */
-export async function getChangedFiles(
-  pi: ExtensionAPI,
+export function getChangedFilesEffect(
+  cwd: string,
+  options: DiffOptions,
+): Effect.Effect<string[], ExecError, Executor> {
+  return Effect.gen(function* () {
+    const args = ['diff', '--name-only'];
+    if (options.staged) args.push('--staged');
+    else if (options.base) args.push(options.base);
+    else args.push('HEAD');
+
+    const stdout = yield* git(args, cwd);
+    return stdout
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+  });
+}
+
+// ── Promise wrappers (live Executor from pi) ──────────────────────────────────
+
+export function collectDiff(
+  pi: Pick<ExtensionAPI, 'exec'>,
+  cwd: string,
+  options: DiffOptions,
+): Promise<DiffSource> {
+  return Effect.runPromise(
+    collectDiffEffect(cwd, options).pipe(Effect.provideService(Executor, makeExecutorService(pi))),
+  );
+}
+
+export function getChangedFiles(
+  pi: Pick<ExtensionAPI, 'exec'>,
   cwd: string,
-  options: { base?: string; staged?: boolean },
+  options: DiffOptions,
 ): Promise<string[]> {
-  const args = ['diff', '--name-only'];
-
-  if (options.staged) {
-    args.push('--staged');
-  } else if (options.base) {
-    args.push(options.base);
-  } else {
-    args.push('HEAD');
-  }
-
-  const result = await pi.exec('git', args, { cwd });
-  return result.stdout
-    .split('\n')
-    .map((f) => f.trim())
-    .filter(Boolean);
+  return Effect.runPromise(
+    getChangedFilesEffect(cwd, options).pipe(
+      Effect.provideService(Executor, makeExecutorService(pi)),
+    ),
+  );
 }

package/extensions/code-reviewer/effects/exec.ts

@@ -0,0 +1,47 @@
+/**
+ * Executor service — wraps `pi.exec` so shelling out (git, lens tools) becomes
+ * an injectable, typed Effect. Tests provide a fake executor instead of running
+ * real subprocesses.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Context, Effect } from 'effect';
+
+import { ExecError } from '../errors';
+
+export interface ExecOptions {
+  cwd?: string;
+  timeout?: number;
+  signal?: AbortSignal;
+}
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+}
+
+export interface ExecutorService {
+  readonly exec: (
+    command: string,
+    args: string[],
+    options?: ExecOptions,
+  ) => Effect.Effect<ExecResult, ExecError>;
+}
+
+export class Executor extends Context.Tag('CodeReviewer/Executor')<Executor, ExecutorService>() {}
+
+type ExecCapableApi = Pick<ExtensionAPI, 'exec'>;
+
+/** Build a live Executor backed by `pi.exec`. */
+export function makeExecutorService(pi: ExecCapableApi): ExecutorService {
+  return {
+    exec: (command, args, options) =>
+      Effect.tryPromise({
+        try: async () => {
+          const result = await pi.exec(command, args, options);
+          return { stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+        },
+        catch: (cause) => new ExecError({ command, args, cause }),
+      }),
+  };
+}

package/extensions/code-reviewer/effects/filesystem.ts

@@ -0,0 +1,38 @@
+/**
+ * FileSystem service — the only place the code-reviewer reads disk.
+ *
+ * Wrapping Node's `fs/promises` behind an Effect service keeps config and lens
+ * loading pure and injectable: tests swap in an in-memory implementation, and
+ * read failures surface as typed `FileReadError` values.
+ */
+
+import { Context, Effect } from 'effect';
+import { readFile, readdir } from 'node:fs/promises';
+
+import { FileReadError } from '../errors';
+
+export interface FileSystemService {
+  /** Read a UTF-8 file, failing with FileReadError when unreadable/missing. */
+  readonly readTextFile: (path: string) => Effect.Effect<string, FileReadError>;
+  /** List directory entries, failing with FileReadError when the dir is missing. */
+  readonly readDirectory: (path: string) => Effect.Effect<string[], FileReadError>;
+}
+
+export class FileSystem extends Context.Tag('CodeReviewer/FileSystem')<
+  FileSystem,
+  FileSystemService
+>() {}
+
+export const nodeFileSystemService: FileSystemService = {
+  readTextFile: (path) =>
+    Effect.tryPromise({
+      try: () => readFile(path, 'utf-8'),
+      catch: (cause) => new FileReadError({ path, cause }),
+    }),
+
+  readDirectory: (path) =>
+    Effect.tryPromise({
+      try: () => readdir(path),
+      catch: (cause) => new FileReadError({ path, cause }),
+    }),
+};

package/extensions/code-reviewer/effects/runtime.ts

@@ -0,0 +1,21 @@
+/**
+ * Live Effect layers for the code-reviewer extension.
+ *
+ * `fileSystemLayer` covers disk-only programs (config + lens loading).
+ * `makeRuntimeLayer(pi)` adds the `pi.exec`-backed Executor for git/diff and
+ * lens-tool programs.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Layer } from 'effect';
+
+import { Executor, makeExecutorService } from './exec';
+import { FileSystem, nodeFileSystemService } from './filesystem';
+
+export const fileSystemLayer = Layer.succeed(FileSystem, nodeFileSystemService);
+
+export function makeRuntimeLayer(pi: Pick<ExtensionAPI, 'exec'>) {
+  return Layer.mergeAll(fileSystemLayer, Layer.succeed(Executor, makeExecutorService(pi)));
+}
+
+export type CodeReviewerServices = FileSystem | Executor;

package/extensions/code-reviewer/errors.ts

@@ -0,0 +1,57 @@
+/**
+ * Tagged error types for the code-reviewer extension.
+ *
+ * Modeled with Effect's `Data.TaggedError` so failures are typed and carry
+ * structured context. Helpers convert them into human-readable messages and
+ * native `Error`s when an Effect crosses back into Promise-land.
+ */
+
+import { Data } from 'effect';
+
+export class FileReadError extends Data.TaggedError('FileReadError')<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    return `Failed to read ${this.path}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export class ExecError extends Data.TaggedError('ExecError')<{
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    const cmd = [this.command, ...this.args].join(' ');
+    return `Command failed: ${cmd}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export type CodeReviewerError = FileReadError | ExecError;
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+export function causeMessage(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'object' && error !== null && 'message' in error) {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === 'string') return message;
+  }
+  return String(error);
+}
+
+/** Convert a tagged/unknown error into a native Error for Promise rejection. */
+export function toNativeError(error: unknown): Error {
+  if (error instanceof Error) return error;
+  const native = new Error(errorMessage(error));
+  if (typeof error === 'object' && error !== null && '_tag' in error) {
+    native.name = String((error as { _tag: unknown })._tag);
+  }
+  return native;
+}

package/extensions/code-reviewer/lenses.ts

@@ -1,5 +1,7 @@
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import { Effect } from 'effect';
+import { basename, resolve } from 'node:path';
+
+import { FileSystem, nodeFileSystemService } from './effects/filesystem';
 import type { LensConfig, LensSeverity } from './types';
 
 type SectionKind = 'top' | 'criteria' | 'tools' | 'severity';
@@ -91,27 +93,52 @@ function parseSeverityRule(trimmed: string, rules: Record<LensSeverity, string>)
   }
 }
 
-/** Discover all lens files in a directory. */
-export function discoverLenses(lensDir: string): Map<string, LensConfig> {
-  const lenses = new Map<string, LensConfig>();
+/** Discover all lens files in a directory (missing dir → empty map). */
+export function discoverLensesEffect(
+  lensDir: string,
+): Effect.Effect<Map<string, LensConfig>, never, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const lenses = new Map<string, LensConfig>();
+
+    const entries = yield* fs.readDirectory(lensDir).pipe(Effect.either);
+    if (entries._tag === 'Left') return lenses;
+
+    for (const file of entries.right.filter((f) => f.endsWith('.md'))) {
+      const content = yield* fs.readTextFile(resolve(lensDir, file)).pipe(Effect.either);
+      if (content._tag === 'Left') continue;
+      const key = basename(file, '.md');
+      lenses.set(key, parseLensFile(content.right, file));
+    }
 
-  if (!existsSync(lensDir)) return lenses;
+    return lenses;
+  });
+}
 
-  const files = readdirSync(lensDir).filter((f) => f.endsWith('.md'));
+/** Get raw markdown content for a lens to pass to the reviewer agent. */
+export function getLensContentEffect(
+  lensDir: string,
+  lensName: string,
+): Effect.Effect<string | null, never, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const content = yield* fs.readTextFile(resolve(lensDir, `${lensName}.md`)).pipe(Effect.either);
+    return content._tag === 'Right' ? content.right : null;
+  });
+}
 
-  for (const file of files) {
-    const content = readFileSync(resolve(lensDir, file), 'utf-8');
-    const config = parseLensFile(content, file);
-    const key = basename(file, '.md');
-    lenses.set(key, config);
-  }
+// ── Promise wrappers (live FileSystem provided) ──────────────────────────────
 
-  return lenses;
+export function discoverLenses(lensDir: string): Promise<Map<string, LensConfig>> {
+  return Effect.runPromise(
+    discoverLensesEffect(lensDir).pipe(Effect.provideService(FileSystem, nodeFileSystemService)),
+  );
 }
 
-/** Get raw markdown content for a lens to pass to the reviewer agent. */
-export function getLensContent(lensDir: string, lensName: string): string | null {
-  const filePath = resolve(lensDir, `${lensName}.md`);
-  if (!existsSync(filePath)) return null;
-  return readFileSync(filePath, 'utf-8');
+export function getLensContent(lensDir: string, lensName: string): Promise<string | null> {
+  return Effect.runPromise(
+    getLensContentEffect(lensDir, lensName).pipe(
+      Effect.provideService(FileSystem, nodeFileSystemService),
+    ),
+  );
 }

package/extensions/code-reviewer/reviewer.ts

@@ -1,36 +1,70 @@
 import { platform } from 'node:os';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Effect } from 'effect';
+
 import type { DiffSource } from './diff';
+import { Executor, makeExecutorService } from './effects/exec';
 import type { LensConfig, LensResult } from './types';
 
 const isWindows = platform() === 'win32';
 
-/** Run project tools specified by a lens and collect their output. */
-async function runLensTools(
-  pi: ExtensionAPI,
+export type ToolRunOptions = { timeoutMs: number; concurrency: number };
+
+/**
+ * Run a set of project tool commands ONCE, deduped and concurrently, and
+ * collect their output keyed by the original command string.
+ *
+ * Tools are deduped across lenses by the caller (and again here defensively),
+ * so a command shared by several lenses runs a single time — not once per
+ * lens. Each command is shelled out with a bounded timeout; a failure or
+ * timeout degrades to a sentinel string instead of failing the whole review.
+ */
+export function runToolsEffect(
   cwd: string,
   tools: string[],
+  options: ToolRunOptions,
   signal?: AbortSignal,
-): Promise<Record<string, string>> {
-  const outputs: Record<string, string> = {};
-
-  for (const tool of tools) {
-    if (signal?.aborted) break;
-
-    try {
-      const [shell, shellArgs] = isWindows ? ['cmd', ['/c', tool]] : ['sh', ['-c', tool]];
-      const result = await pi.exec(shell, shellArgs, {
-        cwd,
-        timeout: 60_000,
-        signal,
-      });
-      outputs[tool] = result.stdout || result.stderr || '(no output)';
-    } catch {
-      outputs[tool] = `(tool failed or timed out: ${tool})`;
-    }
-  }
+): Effect.Effect<Record<string, string>, never, Executor> {
+  return Effect.gen(function* () {
+    const unique = [...new Set(tools)];
+    if (unique.length === 0 || signal?.aborted) return {};
+
+    const executor = yield* Executor;
+
+    const entries = yield* Effect.forEach(
+      unique,
+      (tool) =>
+        Effect.gen(function* () {
+          if (signal?.aborted) return [tool, '(skipped: review aborted)'] as const;
+
+          const [shell, shellArgs] = isWindows ? ['cmd', ['/c', tool]] : ['sh', ['-c', tool]];
+          const result = yield* executor
+            .exec(shell, shellArgs as string[], { cwd, timeout: options.timeoutMs, signal })
+            .pipe(Effect.either);
+
+          const output =
+            result._tag === 'Right'
+              ? result.right.stdout || result.right.stderr || '(no output)'
+              : `(tool failed or timed out: ${tool})`;
+          return [tool, output] as const;
+        }),
+      { concurrency: Math.max(1, options.concurrency) },
+    );
 
-  return outputs;
+    return Object.fromEntries(entries);
+  });
+}
+
+/** Pick the subset of already-run tool outputs that a given lens declares. */
+export function pickLensToolOutputs(
+  lens: LensConfig,
+  allOutputs: Record<string, string>,
+): Record<string, string> {
+  const picked: Record<string, string> = {};
+  for (const tool of lens.tools) {
+    if (tool in allOutputs) picked[tool] = allOutputs[tool];
+  }
+  return picked;
 }
 
 /** Build the shared diff section of the review prompt (included once). */
@@ -38,14 +72,20 @@ export function buildDiffSection(diff: DiffSource): string {
   const parts: string[] = [];
   const maxDiffLen = 50_000;
   const diffTruncated = diff.diff.length > maxDiffLen;
+  // Cut at the last newline within budget so we never emit a half-line of
+  // diff (which reads as a corrupt hunk); fall back to a hard slice if a
+  // single line already exceeds the budget.
+  const body = diffTruncated
+    ? diff.diff.slice(0, Math.max(diff.diff.lastIndexOf('\n', maxDiffLen), 0) || maxDiffLen)
+    : diff.diff;
 
   parts.push(`## Diff (${diff.label})`);
   parts.push('```diff');
-  parts.push(diff.diff.slice(0, maxDiffLen));
+  parts.push(body);
   parts.push('```');
   if (diffTruncated) {
     parts.push(
-      `> ⚠️ Diff truncated (${diff.diff.length} chars → ${maxDiffLen}). Some files may not appear above.`,
+      `> ⚠️ Diff truncated (${diff.diff.length} chars → ~${maxDiffLen}). Some files may not appear above; re-run scoped with \`--base\` or per-area if needed.`,
     );
   }
   parts.push('');
@@ -58,7 +98,7 @@ export function buildDiffSection(diff: DiffSource): string {
 }
 
 /** Build the lens-specific section of the review prompt (no diff duplication). */
-function buildLensSection(
+export function buildLensSection(
   lens: LensConfig,
   lensContent: string,
   toolOutputs: Record<string, string>,
@@ -90,64 +130,36 @@ function buildLensSection(
   return parts.join('\n');
 }
 
-/** Build the full review prompt for a single lens (includes diff — used by the tool path). */
-function buildReviewPrompt(
+/**
+ * Build the lens result from PRE-COMPUTED tool outputs. Pure — no IO — so tool
+ * execution happens once up front (see {@link runToolsEffect}) and is shared
+ * across every lens that declares the same command.
+ */
+export function buildLensResult(
   lens: LensConfig,
   lensContent: string,
-  diff: DiffSource,
   toolOutputs: Record<string, string>,
-): string {
-  const parts: string[] = [];
-
-  parts.push(`You are reviewing code changes through the "${lens.name}" lens.`);
-  parts.push('');
-  parts.push(buildDiffSection(diff));
-  parts.push('');
-  parts.push(buildLensSection(lens, lensContent, toolOutputs));
-  parts.push('');
-  parts.push('## Instructions');
-  parts.push('');
-  parts.push('Review the diff above through this lens. For each finding, output a JSON array:');
-  parts.push('');
-  parts.push('```json');
-  parts.push('[');
-  parts.push(
-    '  { "file": "path/to/file.ts", "line": 42, "severity": "warning", "message": "Description" }',
-  );
-  parts.push(']');
-  parts.push('```');
-  parts.push('');
-  parts.push(
-    'After the JSON array, write a 2-3 sentence summary of your review through this lens.',
-  );
-  parts.push('If there are no findings, return an empty array `[]` and note the code looks good.');
-
-  return parts.join('\n');
-}
-
-/** Execute a review for a single lens using the subagent tool. */
-export async function reviewWithLens(
-  pi: ExtensionAPI,
-  _ctx: unknown,
-  cwd: string,
-  lens: LensConfig,
-  lensContent: string,
-  diff: DiffSource,
-  signal?: AbortSignal,
-): Promise<LensResult> {
-  // Run lens tools first
-  const toolOutputs = await runLensTools(pi, cwd, lens.tools, signal);
-
-  // Build the prompt
-  const prompt = buildReviewPrompt(lens, lensContent, diff, toolOutputs);
-  const lensSection = buildLensSection(lens, lensContent, toolOutputs);
-
+): LensResult {
   return {
     lens: lens.name,
     findings: [],
     summary: '',
     toolOutputs,
-    _prompt: prompt,
-    _lensSection: lensSection,
+    _lensSection: buildLensSection(lens, lensContent, toolOutputs),
   };
 }
+
+/** Promise wrapper: run a deduped tool set once, building a live Executor from `pi`. */
+export function runTools(
+  pi: Pick<ExtensionAPI, 'exec'>,
+  cwd: string,
+  tools: string[],
+  options: ToolRunOptions,
+  signal?: AbortSignal,
+): Promise<Record<string, string>> {
+  return Effect.runPromise(
+    runToolsEffect(cwd, tools, options, signal).pipe(
+      Effect.provideService(Executor, makeExecutorService(pi)),
+    ),
+  );
+}

package/extensions/code-reviewer/types.ts

@@ -20,20 +20,22 @@ export type LensResult = {
   findings: LensFinding[];
   summary: string;
   toolOutputs?: Record<string, string>;
-  /** Review prompt built for this lens, used internally to delegate to the agent. */
-  _prompt?: string;
-  /** Lens-specific section (without diff), used by /review command to avoid diff duplication. */
+  /** Lens-specific prompt section (without the diff), assembled by the command
+   *  layer with a single shared diff to avoid per-lens duplication. */
   _lensSection?: string;
 };
 
+// NOTE: findings + summary on LensResult describe what the agent produces in
+// its follow-up message; the tool/command layer emits a review *task*, it does
+// not parse findings back into a rendered report.
+
 export type ReviewConfig = {
   lensDir: string;
   defaultLenses: string[];
-};
-
-export type ReviewReport = {
-  diff: string;
-  diffStat: string;
-  lenses: LensResult[];
-  generatedAt: string;
+  /** Per-tool wall-clock timeout in ms. A lens tool that exceeds it is killed
+   *  and reported as timed-out (it must never hang the review). */
+  toolTimeoutMs: number;
+  /** Max lens tools run in parallel. Tools are deduped across lenses first,
+   *  so this bounds the distinct command set, not lens count. */
+  toolConcurrency: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-code-reviewer",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Multi-lens code review extension for pi — configurable review criteria per project",
   "keywords": [
     "pi-package"
@@ -21,9 +21,10 @@
   "type": "module",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "oxlint extensions",
-    "format": "oxfmt --write extensions",
-    "format:check": "oxfmt --check extensions"
+    "test": "bun test",
+    "lint": "oxlint extensions test",
+    "format": "oxfmt --write extensions test",
+    "format:check": "oxfmt --check extensions test"
   },
   "pi": {
     "extensions": [
@@ -33,8 +34,12 @@
       "./skills"
     ]
   },
+  "dependencies": {
+    "effect": "^3.21.2"
+  },
   "devDependencies": {
     "@types/node": "24",
+    "bun-types": "latest",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.58.0",
     "typescript": "^6.0.0"

package/extensions/code-reviewer/report.ts

@@ -1,109 +0,0 @@
-import type { LensFinding, LensResult, LensSeverity, ReviewReport } from './types';
-
-/** Build a markdown report from lens results. */
-export function buildReport(report: ReviewReport): string {
-  const sections = [
-    `# Code Review — ${report.generatedAt}`,
-    '',
-    buildChangesSection(report.diffStat),
-    buildScoreboard(report.lenses),
-    ...report.lenses.map(buildLensSection),
-  ];
-
-  return sections.join('\n');
-}
-
-function buildChangesSection(diffStat: string): string {
-  return ['## Changes', '', '```', diffStat, '```', ''].join('\n');
-}
-
-function buildScoreboard(lenses: LensResult[]): string {
-  const counts = countFindings(lenses);
-  return [
-    '## Scoreboard',
-    '',
-    '| Metric | Count |',
-    '| --- | --- |',
-    `| **Total findings** | **${counts.total}** |`,
-    `| 🔴 Blockers | ${counts.blocker} |`,
-    `| 🟡 Warnings | ${counts.warning} |`,
-    `| 🔵 Notes | ${counts.note} |`,
-    `| Lenses applied | ${lenses.length} |`,
-    '',
-  ].join('\n');
-}
-
-function countFindings(lenses: LensResult[]): Record<LensSeverity | 'total', number> {
-  const counts = { blocker: 0, warning: 0, note: 0, total: 0 };
-  for (const lens of lenses) {
-    for (const f of lens.findings) {
-      counts[f.severity]++;
-      counts.total++;
-    }
-  }
-  return counts;
-}
-
-function buildLensSection(lens: LensResult): string {
-  const lines: string[] = [`## ${lens.lens}`, ''];
-
-  if (lens.findings.length === 0) {
-    lines.push('No findings. ✓', '');
-    if (lens.summary) lines.push(lens.summary, '');
-    return lines.join('\n');
-  }
-
-  lines.push(buildFindingsByGroup(lens.findings));
-
-  if (lens.summary) {
-    lines.push(`**Summary:** ${lens.summary}`, '');
-  }
-
-  if (lens.toolOutputs && Object.keys(lens.toolOutputs).length > 0) {
-    lines.push(buildToolOutputDetails(lens.toolOutputs));
-  }
-
-  return lines.join('\n');
-}
-
-const SEVERITY_ICONS: Record<LensSeverity, string> = {
-  blocker: '🔴',
-  warning: '🟡',
-  note: '🔵',
-};
-
-function buildFindingsByGroup(findings: LensFinding[]): string {
-  const lines: string[] = [];
-  const severities: LensSeverity[] = ['blocker', 'warning', 'note'];
-
-  for (const severity of severities) {
-    const group = findings.filter((f) => f.severity === severity);
-    if (group.length === 0) continue;
-
-    const label = severity.charAt(0).toUpperCase() + severity.slice(1);
-    lines.push(`### ${SEVERITY_ICONS[severity]} ${label}s (${group.length})`, '');
-
-    for (const f of group) {
-      const loc = f.line ? `${f.file}:${f.line}` : f.file;
-      lines.push(`- \`${loc}\` — ${f.message}`);
-    }
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-function buildToolOutputDetails(toolOutputs: Record<string, string>): string {
-  const lines = [
-    '<details>',
-    `<summary>Tool outputs (${Object.keys(toolOutputs).length})</summary>`,
-    '',
-  ];
-
-  for (const [cmd, output] of Object.entries(toolOutputs)) {
-    lines.push(`**\`${cmd}\`**`, '```', output.slice(0, 5000), '```');
-  }
-
-  lines.push('</details>', '');
-  return lines.join('\n');
-}