ralph-review 0.2.1 → 0.2.3

package/README.md

@@ -13,7 +13,7 @@ Orchestrating coding agents for code review, verification, and fixing via the Ra
 
 - [How It Works](#how-it-works)
 - [Reviewer and Fixer Flow](#reviewer-and-fixer-flow)
-- [Interactive Mode](#interactive-mode)
+- [Workflows](#workflows)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
@@ -97,24 +97,131 @@ findings remain unresolved, Ralph Review keeps the remediation worktree availabl
 
 ---
 
-## Interactive Mode
+## Workflows
 
-Run `rr` with no command to open Interactive Mode. It shows active sessions, recent session history,
-review output, findings, fix results, and handoff status.
+Ralph Review fits into a few common loops. Each workflow below shows the scenario
+first, then the exact commands.
 
-Keyboard shortcuts:
+### 1. Review what you are about to commit
 
-| Key | Action |
-|-----|--------|
-| `r` | Start a new review session |
-| `f` | Fix pending findings when a session has actionable findings |
-| `s` | Stop a running review session |
-| `l` | View session logs |
-| `o` | Toggle the output drawer |
-| `Tab`, `←`, `→` | Switch panel focus |
-| `↑`, `↓`, `j`, `k` | Scroll the focused panel |
-| `h`, `?` | Toggle help |
-| `Esc`, `q` | Quit Interactive Mode without stopping reviews |
+You just finished a feature on a working branch. Before you stage and push, you
+want a second pair of eyes on staged, unstaged, and untracked changes.
+
+```bash
+rr run --uncommitted
+```
+
+Findings are printed and persisted. You can keep coding while the reviewer runs
+in the background and come back to triage when it is done.
+
+### 2. Review your branch against the base
+
+You are preparing a pull request against `main` and want the reviewer to look at
+the full diff, not just your last commit.
+
+```bash
+rr run --base main
+```
+
+Add a focus instruction when the diff is large:
+
+```bash
+rr run --base main "focus on auth boundaries and input validation"
+```
+
+### 3. Re-review a single commit
+
+CI flagged something on a specific commit, or you are auditing a hotfix in
+isolation.
+
+```bash
+rr run --commit 9f3a2b1
+```
+
+### 4. Review now, fix later (the default loop)
+
+`rr run` only reviews. Findings get a stable ID (`F001`, `F002`, ...) and a
+priority (`P0` through `P3`). Triage them, then fix exactly what you want:
+
+```bash
+rr run
+rr fix --session SESSION --priority P0,P1
+# or pick by ID
+rr fix --session SESSION --id F003 --id F007
+```
+
+When the fixer is done it either applies the patch to your working tree
+automatically, or leaves a pending handoff that you apply explicitly:
+
+```bash
+rr apply
+```
+
+### 5. Review and auto-fix in one shot
+
+Trusted change, low risk, you want the loop to close itself:
+
+```bash
+rr run --auto --priority P0,P1
+```
+
+The reviewer runs first, then the fixer immediately remediates only matching
+priorities in a disposable worktree and hands the result back to you.
+
+> Auto Setup picks the reviewer model based on Factory.ai's public code review
+> benchmark. See [Why these models?](#why-these-models-auto-setup-model-selection)
+> below.
+
+### 6. Pre-PR / team review workflow
+
+Before opening a PR, run a base-branch review and let auto-fix clean up the
+obvious stuff. Anything left becomes review notes you can paste into the PR
+description.
+
+```bash
+rr run --base main --auto --priority P0
+rr log -n 1            # grab the latest review log
+rr log --json          # or pipe into your own tooling
+```
+
+For an org-wide loop, persisted review logs (`rr log --json --global`) make it
+easy to feed findings into dashboards or follow-up issues.
+
+### 7. Triage with Interactive Mode
+
+Run `rr` with no arguments to open Interactive Mode. It shows active sessions,
+recent history, review output, findings, fix results, and handoff status in a
+single view, which is convenient when several reviews are in flight.
+
+### Why these models? (Auto Setup model selection)
+
+`rr init` with Auto Setup chooses your reviewer and fixer's model. That list is
+informed by Factory.ai's public code review benchmark, which scored 13 frontier
+and open-weight models against a golden set of 50 human-curated bugs across
+five real-world repositories (Sentry, Grafana, Keycloak, Discourse, and
+cal.com).
+
+The reviewer model priority (highest first) is currently:
+
+1. GPT-5.2
+2. Claude Opus 4.6
+3. Claude Sonnet 4.6
+4. Claude Opus 4.7
+5. GLM 5.1
+6. GPT-5.3 Codex
+7. Gemini 3.1 Pro Preview
+8. Kimi K2.6
+
+Models near the top scored highest on the benchmark for finding real bugs at a
+reasonable cost. The fixer priority is tuned separately and favors models that
+are strong at code edits rather than at finding issues.
+
+For the methodology and full results, see Factory.ai's writeup:
+[Which Model Reviews Code Best?](https://factory.ai/news/code-review-benchmark).
+
+You can always override the auto selection by running `rr init` and choosing
+Customize Setup, or by editing `reviewer.model` and `fixer.model` in your
+configuration directly.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-review",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Orchestrating coding agents for code review, verification and fixing via the ralph loop.",
   "license": "MIT",
   "type": "module",
@@ -53,15 +53,16 @@
     "publish:recover": "bun run scripts/publish.ts --recover",
     "publish:recover:execute": "bun run scripts/publish.ts --recover --execute",
     "rr": "bun run src/cli.ts",
-    "test": "bun test",
+    "test": "AGENT=1 bun test",
     "prepublishOnly": "bun test",
     "typecheck": "tsc --noEmit",
     "knip": "knip-bun",
+    "check-duplicates": "bunx jscpd src tests --exitCode 1 --reporters ai",
     "lint": "biome check --write .",
     "lint:ci": "biome ci .",
     "lint-staged": "lint-staged",
-    "check": "bun run typecheck && bun run knip && bun run lint && AGENT=1 bun test --coverage",
-    "check:ci": "bun run typecheck && bun run knip && bun run lint:ci && AGENT=1 bun test --coverage",
+    "check": "bun run typecheck && bun run knip && bun run lint && bun run check-duplicates && AGENT=1 bun test --coverage",
+    "check:ci": "bun run typecheck && bun run knip && bun run lint:ci && bun run check-duplicates && AGENT=1 bun test --coverage",
     "prepare": "husky && bun run setup-hooks",
     "setup-hooks": "bun -e 'await Bun.write(\".husky/pre-commit\", \"#!/usr/bin/env sh\\n\\nbun run knip && bun run lint-staged\\n\")' && chmod +x .husky/pre-commit"
   },
@@ -70,6 +71,7 @@
     "@types/bun": "latest",
     "@types/react": "^19.0.0",
     "husky": "^9.1.7",
+    "jscpd": "^4.0.9",
     "knip": "^5.82.1",
     "lint-staged": "^16.2.7",
     "typescript": "^5",

package/src/cli-core.ts

@@ -1,5 +1,52 @@
 import { type CommandDef, formatCommandHelp, formatMainHelp } from "./lib/cli-parser";
 
+const RUN_REVIEW_OPTIONS: CommandDef["options"] = [
+  { name: "max", alias: "m", type: "number", description: "Max iterations" },
+  {
+    name: "force",
+    alias: "f",
+    type: "boolean",
+    description: "Run full max iterations even if no issues are found",
+  },
+  {
+    name: "auto",
+    type: "boolean",
+    description: "Automatically run remediation after review completes",
+  },
+  {
+    name: "priority",
+    type: "string",
+    placeholder: "P0,P1",
+    description: "Priority filter for --auto using comma-separated values",
+  },
+];
+
+const FIX_SELECTION_OPTIONS: CommandDef["options"] = [
+  {
+    name: "session",
+    alias: "s",
+    type: "string",
+    description: "Session ID whose persisted findings should be fixed",
+  },
+  {
+    name: "all",
+    type: "boolean",
+    description: "Select all persisted findings for remediation",
+  },
+  {
+    name: "priority",
+    type: "string",
+    placeholder: "P0,P1,P2,P3",
+    description: "Select findings by priority (comma-separated values)",
+  },
+  {
+    name: "id",
+    type: "string",
+    placeholder: "F001",
+    description: "Select findings by ID (repeatable)",
+  },
+];
+
 export const COMMANDS: CommandDef[] = [
   {
     name: "init",
@@ -67,24 +114,7 @@ export const COMMANDS: CommandDef[] = [
     name: "run",
     description: "Run review only and persist findings for later fixing",
     options: [
-      { name: "max", alias: "m", type: "number", description: "Max iterations" },
-      {
-        name: "force",
-        alias: "f",
-        type: "boolean",
-        description: "Run full max iterations even if no issues are found",
-      },
-      {
-        name: "auto",
-        type: "boolean",
-        description: "Automatically run remediation after review completes",
-      },
-      {
-        name: "priority",
-        type: "string",
-        placeholder: "P0,P1",
-        description: "Priority filter for --auto using comma-separated values",
-      },
+      ...RUN_REVIEW_OPTIONS,
       {
         name: "base",
         type: "string",
@@ -130,31 +160,7 @@ export const COMMANDS: CommandDef[] = [
   {
     name: "fix",
     description: "Fix selected findings from a persisted review session",
-    options: [
-      {
-        name: "session",
-        alias: "s",
-        type: "string",
-        description: "Session ID whose persisted findings should be fixed",
-      },
-      {
-        name: "all",
-        type: "boolean",
-        description: "Select all persisted findings for remediation",
-      },
-      {
-        name: "priority",
-        type: "string",
-        placeholder: "P0|P1|P2|P3",
-        description: "Select findings by priority (repeatable)",
-      },
-      {
-        name: "id",
-        type: "string",
-        placeholder: "F001",
-        description: "Select findings by ID (repeatable)",
-      },
-    ],
+    options: FIX_SELECTION_OPTIONS,
     examples: [
       "rr fix --session session-123 --all",
       "rr fix --session session-123 --priority P0,P1",
@@ -312,56 +318,13 @@ export const COMMANDS: CommandDef[] = [
     name: "_run-foreground",
     description: "Internal: run review session in tmux foreground",
     hidden: true,
-    options: [
-      { name: "max", type: "number", description: "Max iterations" },
-      {
-        name: "force",
-        alias: "f",
-        type: "boolean",
-        description: "Run full max iterations even if no issues are found",
-      },
-      {
-        name: "auto",
-        type: "boolean",
-        description: "Automatically run remediation after review completes",
-      },
-      {
-        name: "priority",
-        type: "string",
-        placeholder: "P0,P1",
-        description: "Priority filter for --auto using comma-separated values",
-      },
-    ],
+    options: RUN_REVIEW_OPTIONS,
   },
   {
     name: "_fix-foreground",
     description: "Internal: run fixer session in tmux foreground",
     hidden: true,
-    options: [
-      {
-        name: "session",
-        alias: "s",
-        type: "string",
-        description: "Session ID whose persisted findings should be fixed",
-      },
-      {
-        name: "all",
-        type: "boolean",
-        description: "Select all persisted findings for remediation",
-      },
-      {
-        name: "priority",
-        type: "string",
-        placeholder: "P0|P1|P2|P3",
-        description: "Select findings by priority (repeatable)",
-      },
-      {
-        name: "id",
-        type: "string",
-        placeholder: "F001",
-        description: "Select findings by ID (repeatable)",
-      },
-    ],
+    options: FIX_SELECTION_OPTIONS,
   },
 ];
 

package/src/cli-rrr.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import { printCommandHelp } from "@/cli-core";
+import { CONSOLE_ERROR, CONSOLE_LOG, PROCESS_EXIT } from "@/cli-io";
 import { startReview } from "@/commands/run";
 
 export interface RrrDeps {
@@ -11,10 +12,6 @@ export interface RrrDeps {
   exit: (code: number) => void;
 }
 
-const CONSOLE_LOG = console.log.bind(console) as (message: string) => void;
-const CONSOLE_ERROR = console.error.bind(console) as (message: string) => void;
-const PROCESS_EXIT = process.exit.bind(process) as (code: number) => void;
-
 const DEFAULT_RRR_DEPS: RrrDeps = {
   printCommandHelp,
   startReview,

package/src/cli.ts

@@ -2,6 +2,7 @@
 
 import * as p from "@clack/prompts";
 import { getCommandDef, getVersion, parseArgs, printCommandHelp, printUsage } from "./cli-core";
+import { CONSOLE_LOG, PROCESS_EXIT } from "./cli-io";
 import { runApply } from "./commands/apply";
 import { runConfig } from "./commands/config";
 import { runDoctor } from "./commands/doctor";
@@ -55,10 +56,8 @@ export interface CliDeps {
   exit: (code: number) => void;
 }
 
-const CONSOLE_LOG = console.log.bind(console) as (message: string) => void;
 const CLACK_ERROR = p.log.error.bind(p.log) as (message: string) => void;
 const CLACK_MESSAGE = p.log.message.bind(p.log) as (message: string) => void;
-const PROCESS_EXIT = process.exit.bind(process) as (code: number) => void;
 const IS_INTERACTIVE_TERMINAL = (): boolean =>
   process.stdin.isTTY === true && process.stdout.isTTY === true;
 

package/src/commands/apply.ts

@@ -1,7 +1,9 @@
 import * as p from "@clack/prompts";
-import { getCommandDef } from "@/cli";
 import { resolvePendingHandoffSelection } from "@/commands/handoff-selection";
-import type { CommandDef } from "@/lib/cli-parser";
+import {
+  createInteractiveCommandDeps,
+  type InteractiveCommandDeps,
+} from "@/commands/interactive-deps";
 import { parseCommand } from "@/lib/cli-parser";
 import { applyPendingHandoff, listProjectPendingHandoffs } from "@/lib/handoff";
 import { appendLog } from "@/lib/logger";
@@ -10,19 +12,9 @@ interface ApplyOptions {
   session?: string;
 }
 
-interface ApplyDeps {
-  getCommandDef: (name: string) => CommandDef | undefined;
-  logError: (message: string) => void;
-  exit: (code: number) => void;
-  isTTY: () => boolean;
-}
+type ApplyDeps = InteractiveCommandDeps;
 
-const DEFAULT_APPLY_DEPS: ApplyDeps = {
-  getCommandDef,
-  logError: (message: string) => p.log.error(message),
-  exit: (code: number) => process.exit(code),
-  isTTY: () => process.stdout.isTTY === true,
-};
+const DEFAULT_APPLY_DEPS = createInteractiveCommandDeps();
 
 const NO_PENDING_HANDOFFS_MESSAGE = "No pending review handoffs for current working directory.";
 

package/src/commands/config-handlers.ts

@@ -39,6 +39,11 @@ interface ParsedShowArgs extends ParsedScopedArgs {
   verbose: boolean;
 }
 
+type LoadedEffectiveConfig = Awaited<
+  ReturnType<ConfigCommandDeps["loadEffectiveConfigWithDiagnostics"]>
+>;
+type ValidEffectiveConfig = LoadedEffectiveConfig & { config: Config };
+
 const SHOW_USAGE = "Usage: rr config show [--local|--global] [--json] [--verbose]";
 
 function shellQuote(value: string): string {
@@ -61,61 +66,72 @@ function printValue(value: unknown, print: (value: string) => void): void {
   print(String(value));
 }
 
+async function warnIfEffectiveConfigInvalid(
+  deps: ConfigCommandDeps,
+  remediation: string
+): Promise<ValidEffectiveConfig | null> {
+  const effective = await deps.loadEffectiveConfigWithDiagnostics(deps.cwd());
+  const errors = collectEffectiveConfigValidationErrors(effective);
+  if (!effective.config || errors.length > 0) {
+    deps.log.warn(
+      formatConfigValidationMessage(
+        getEffectiveConfigErrorHeader(effective),
+        errors.length > 0 ? errors : ["Configuration format is invalid."],
+        remediation
+      )
+    );
+    return null;
+  }
+
+  return { ...effective, config: effective.config };
+}
+
 function parseScopedArgs(args: string[], defaultScope: ResolvedReadScope): ParsedScopedArgs {
   const positional: string[] = [];
-  let scope = defaultScope;
-  let sawLocal = false;
-  let sawGlobal = false;
+  const state = { scope: defaultScope, sawLocal: false, sawGlobal: false };
 
   for (const arg of args) {
-    if (arg === "--local") {
-      if (sawGlobal) {
-        throw new Error("Cannot use --local and --global together.");
-      }
-      sawLocal = true;
-      scope = "local";
-      continue;
+    if (!parseScopeFlag(arg, state)) {
+      positional.push(arg);
     }
+  }
 
-    if (arg === "--global") {
-      if (sawLocal) {
-        throw new Error("Cannot use --local and --global together.");
-      }
-      sawGlobal = true;
-      scope = "global";
-      continue;
+  return { scope: state.scope, positional };
+}
+
+function parseScopeFlag(
+  arg: string,
+  state: { scope: ResolvedReadScope; sawLocal: boolean; sawGlobal: boolean }
+): boolean {
+  if (arg === "--local") {
+    if (state.sawGlobal) {
+      throw new Error("Cannot use --local and --global together.");
     }
+    state.sawLocal = true;
+    state.scope = "local";
+    return true;
+  }
 
-    positional.push(arg);
+  if (arg === "--global") {
+    if (state.sawLocal) {
+      throw new Error("Cannot use --local and --global together.");
+    }
+    state.sawGlobal = true;
+    state.scope = "global";
+    return true;
   }
 
-  return { scope, positional };
+  return false;
 }
 
 function parseShowArgs(args: string[]): ParsedShowArgs {
   const positional: string[] = [];
-  let scope: ResolvedReadScope = "effective";
-  let sawLocal = false;
-  let sawGlobal = false;
+  const scopeState = { scope: "effective" as ResolvedReadScope, sawLocal: false, sawGlobal: false };
   let json = false;
   let verbose = false;
 
   for (const arg of args) {
-    if (arg === "--local") {
-      if (sawGlobal) {
-        throw new Error("Cannot use --local and --global together.");
-      }
-      sawLocal = true;
-      scope = "local";
-      continue;
-    }
-
-    if (arg === "--global") {
-      if (sawLocal) {
-        throw new Error("Cannot use --local and --global together.");
-      }
-      sawGlobal = true;
-      scope = "global";
+    if (parseScopeFlag(arg, scopeState)) {
       continue;
     }
 
@@ -132,7 +148,7 @@ function parseShowArgs(args: string[]): ParsedShowArgs {
     positional.push(arg);
   }
 
-  return { scope, positional, json, verbose };
+  return { scope: scopeState.scope, positional, json, verbose };
 }
 
 export async function runShow(args: string[], deps: ConfigCommandDeps): Promise<void> {
@@ -296,17 +312,10 @@ export async function runSet(args: string[], deps: ConfigCommandDeps): Promise<v
   await deps.saveConfig(normalized.config);
   deps.log.success(`Updated "${key}" to ${formatValue(parsedValue)}.`);
 
-  const effective = await deps.loadEffectiveConfigWithDiagnostics(deps.cwd());
-  const effectiveErrors = collectEffectiveConfigValidationErrors(effective);
-  if (!effective.config || effectiveErrors.length > 0) {
-    deps.log.warn(
-      formatConfigValidationMessage(
-        getEffectiveConfigErrorHeader(effective),
-        effectiveErrors.length > 0 ? effectiveErrors : ["Configuration format is invalid."],
-        "Fix the repo-local override or restore compatible global values, then try again."
-      )
-    );
-  }
+  await warnIfEffectiveConfigInvalid(
+    deps,
+    "Fix the repo-local override or restore compatible global values, then try again."
+  );
 }
 
 export async function runEdit(args: string[], deps: ConfigCommandDeps): Promise<void> {
@@ -347,16 +356,11 @@ export async function runEdit(args: string[], deps: ConfigCommandDeps): Promise<
   }
 
   if (parsed.scope === "local") {
-    const effective = await deps.loadEffectiveConfigWithDiagnostics(deps.cwd());
-    const errors = collectEffectiveConfigValidationErrors(effective);
-    if (!effective.config || errors.length > 0) {
-      deps.log.warn(
-        formatConfigValidationMessage(
-          getEffectiveConfigErrorHeader(effective),
-          errors.length > 0 ? errors : ["Configuration format is invalid."],
-          'Run "rr init" and choose Repo-local config to regenerate the file, or fix it manually.'
-        )
-      );
+    const effective = await warnIfEffectiveConfigInvalid(
+      deps,
+      'Run "rr init" and choose Repo-local config to regenerate the file, or fix it manually.'
+    );
+    if (!effective) {
       return;
     }
 
@@ -378,16 +382,11 @@ export async function runEdit(args: string[], deps: ConfigCommandDeps): Promise<
     return;
   }
 
-  const effective = await deps.loadEffectiveConfigWithDiagnostics(deps.cwd());
-  const effectiveErrors = collectEffectiveConfigValidationErrors(effective);
-  if (!effective.config || effectiveErrors.length > 0) {
-    deps.log.warn(
-      formatConfigValidationMessage(
-        getEffectiveConfigErrorHeader(effective),
-        effectiveErrors.length > 0 ? effectiveErrors : ["Configuration format is invalid."],
-        "Fix the repo-local override or restore compatible global values, then try again."
-      )
-    );
+  const effective = await warnIfEffectiveConfigInvalid(
+    deps,
+    "Fix the repo-local override or restore compatible global values, then try again."
+  );
+  if (!effective) {
     return;
   }