kodevu 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# Kodevu
+
+A Node.js tool that polls new SVN revisions or Git commits, fetches each change diff directly from the repository, sends the diff to a supported reviewer CLI, and writes the result to Markdown files.
+
+## Workflow
+
+1. Detect the configured repository type, or use the explicit `vcs` setting.
+2. Read the latest change from `target`.
+3. Find changes that have not been reviewed yet.
+4. For each change:
+   - load metadata and changed paths from SVN or Git
+   - generate a unified diff for that single revision or commit
+   - send the diff and change metadata to the configured reviewer CLI
+   - allow the reviewer to inspect related local repository files in read-only mode when a local workspace is available
+   - write the result to `reports/`
+5. Update `data/state.json` so the same change is not reviewed twice.
+
+## Setup
+
+```bash
+npm install
+copy config.example.json config.json
+```
+
+Then edit `config.json` and set `target`.
+
+Install as a CLI package:
+
+```bash
+npm install -g kodevu
+copy config.example.json config.json
+```
+
+## Run
+
+Run one cycle:
+
+```bash
+npm run once
+```
+
+Or run directly as the published CLI:
+
+```bash
+kodevu --once
+```
+
+Use `npx` without installing globally:
+
+```bash
+npx kodevu --once --config ./config.json
+```
+
+Start the scheduler:
+
+```bash
+npm start
+```
+
+Published CLI form:
+
+```bash
+kodevu --config ./config.json
+```
+
+Use a custom config path:
+
+```bash
+node src/index.js --config ./config.json --once
+```
+
+Equivalent `npx` usage:
+
+```bash
+npx kodevu --config ./config.json --once
+```
+
+## Config
+
+- `target`: required repository target
+- `vcs`: `auto`, `svn`, or `git`; default `auto`
+- `reviewer`: `codex` or `gemini`; default `codex`
+- `pollCron`: cron schedule, default every 10 minutes
+- `reviewPrompt`: saved into the report as review context
+- `outputDir`: report output directory; default `./reports`
+- `commandTimeoutMs`: timeout for a single review command execution in milliseconds
+- `bootstrapToLatest`: if no state exists, start by reviewing only the current latest change instead of replaying the full history
+- `maxRevisionsPerRun`: cap the number of pending changes per polling cycle
+
+Internal defaults:
+
+- review state is always stored in `./data/state.json`
+- the tool always invokes `git`, `svn`, and the configured reviewer CLI from `PATH`
+- command output is decoded as `utf8`
+
+## Target Rules
+
+- For SVN, `target` can be a working copy path or repository URL.
+- For Git, `target` must be a local repository path or a subdirectory inside a local repository.
+- When `vcs` is `auto`, the tool tries Git first for existing local paths, then falls back to SVN.
+- Legacy `svnTarget` is still accepted for backward compatibility.
+
+## Notes
+
+- `reviewer: "codex"` uses `codex exec` with the diff embedded in the prompt.
+- `reviewer: "gemini"` uses `gemini -p` in non-interactive mode.
+- For Git targets and local SVN working copies, the reviewer command runs from the repository workspace so it can inspect related files beyond the diff when needed.
+- For remote SVN URLs without a local working copy, the review still relies on the diff and change metadata only.
+- SVN reports keep the `r123.md` naming style.
+- Git reports are written as `git-<full-commit-hash>.md`.
+- `data/state.json` stores per-project checkpoints keyed by repository identity; only the v2 multi-project structure is supported.
+- If the reviewer command exits non-zero or times out, the report is still written, but the state is not advanced so the change can be retried later.

package/config.example.json

@@ -0,0 +1,11 @@
+{
+  "target": "C:/path/to/your/repository-or-subdirectory",
+  "vcs": "auto",
+  "reviewer": "codex",
+  "pollCron": "*/10 * * * *",
+  "reviewPrompt": "请严格审查当前变更，优先指出 bug、回归风险、兼容性问题、安全问题、边界条件缺陷和缺失测试。请使用简体中文输出 Markdown；如果没有明确缺陷，请写“未发现明确缺陷”，并补充剩余风险。",
+  "outputDir": "./reports",
+  "commandTimeoutMs": 600000,
+  "bootstrapToLatest": true,
+  "maxRevisionsPerRun": 5
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "kodevu",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Poll SVN revisions or Git commits, send each change diff to a reviewer CLI, and write Markdown review reports.",
+  "bin": {
+    "kodevu": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "config.example.json"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "once": "node src/index.js --once",
+    "check": "node --check src/index.js && node --check src/config.js && node --check src/review-runner.js && node --check src/svn-client.js && node --check src/git-client.js && node --check src/vcs-client.js && node --check src/shell.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "fast-xml-parser": "^5.2.5",
+    "iconv-lite": "^0.6.3",
+    "node-cron": "^4.2.1"
+  }
+}

package/src/config.js

@@ -0,0 +1,109 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const defaultConfig = {
+  vcs: "auto",
+  reviewer: "codex",
+  target: "",
+  pollCron: "*/10 * * * *",
+  outputDir: "./reports",
+  commandTimeoutMs: 600000,
+  reviewPrompt:
+    "请严格审查当前变更，优先指出 bug、回归风险、兼容性问题、安全问题、边界条件缺陷和缺失测试。请使用简体中文输出 Markdown；如果没有明确缺陷，请写“未发现明确缺陷”，并补充剩余风险。",
+  bootstrapToLatest: true,
+  maxRevisionsPerRun: 20
+};
+
+export function parseCliArgs(argv) {
+  const args = {
+    configPath: "config.json",
+    once: false,
+    help: false
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+
+    if (value === "--once") {
+      args.once = true;
+      continue;
+    }
+
+    if (value === "--help" || value === "-h") {
+      args.help = true;
+      continue;
+    }
+
+    if (value === "--config" || value === "-c") {
+      args.configPath = argv[index + 1];
+      index += 1;
+      continue;
+    }
+  }
+
+  return args;
+}
+
+export async function loadConfig(configPath) {
+  const absoluteConfigPath = path.resolve(configPath);
+  const raw = await fs.readFile(absoluteConfigPath, "utf8");
+  const config = {
+    ...defaultConfig,
+    ...JSON.parse(raw)
+  };
+
+  if (!config.target && config.svnTarget) {
+    config.target = config.svnTarget;
+  }
+
+  if (!config.target) {
+    throw new Error(`Missing required config field "target" (or legacy "svnTarget") in ${absoluteConfigPath}`);
+  }
+
+  config.vcs = String(config.vcs || "auto").toLowerCase();
+  config.reviewer = String(config.reviewer || "codex").toLowerCase();
+
+  if (!["auto", "svn", "git"].includes(config.vcs)) {
+    throw new Error(`"vcs" must be one of "auto", "svn", or "git" in ${absoluteConfigPath}`);
+  }
+
+  if (!["codex", "gemini"].includes(config.reviewer)) {
+    throw new Error(`"reviewer" must be one of "codex" or "gemini" in ${absoluteConfigPath}`);
+  }
+
+  config.configPath = absoluteConfigPath;
+  config.baseDir = path.dirname(absoluteConfigPath);
+  config.outputDir = path.resolve(config.baseDir, config.outputDir);
+  config.stateFilePath = path.resolve(config.baseDir, "./data/state.json");
+  config.maxRevisionsPerRun = Number(config.maxRevisionsPerRun);
+  config.commandTimeoutMs = Number(config.commandTimeoutMs);
+
+  if (!Number.isInteger(config.maxRevisionsPerRun) || config.maxRevisionsPerRun <= 0) {
+    throw new Error(`"maxRevisionsPerRun" must be a positive integer in ${absoluteConfigPath}`);
+  }
+
+  if (!Number.isInteger(config.commandTimeoutMs) || config.commandTimeoutMs <= 0) {
+    throw new Error(`"commandTimeoutMs" must be a positive integer in ${absoluteConfigPath}`);
+  }
+
+  return config;
+}
+
+export function printHelp() {
+  console.log(`Kodevu
+
+Usage:
+  kodevu [--config config.json] [--once]
+  npx kodevu [--config config.json] [--once]
+
+Options:
+  --config, -c   Path to config json. Default: ./config.json
+  --once         Run one polling cycle and exit
+  --help, -h     Show help
+
+Config highlights:
+  vcs            auto | svn | git
+  reviewer       codex | gemini
+  target         Repository target path (Git) or SVN working copy / URL
+`);
+}

package/src/git-client.js

@@ -0,0 +1,221 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "./shell.js";
+
+const GIT_COMMAND = "git";
+const COMMAND_ENCODING = "utf8";
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function splitLines(text) {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function buildPathArgs(targetInfo) {
+  return targetInfo.targetPathspec ? ["--", targetInfo.targetPathspec] : [];
+}
+
+async function statPath(targetPath) {
+  try {
+    return await fs.stat(targetPath);
+  } catch {
+    return null;
+  }
+}
+
+async function runGit(config, args, options = {}) {
+  return await runCommand(GIT_COMMAND, args, {
+    encoding: COMMAND_ENCODING,
+    ...options
+  });
+}
+
+export async function getTargetInfo(config) {
+  const requestedTargetPath = path.resolve(config.baseDir, config.target);
+  const targetStat = await statPath(requestedTargetPath);
+
+  if (!targetStat) {
+    throw new Error(`Git target path does not exist: ${requestedTargetPath}`);
+  }
+
+  const lookupCwd = targetStat.isDirectory() ? requestedTargetPath : path.dirname(requestedTargetPath);
+  const topLevelResult = await runGit(config, ["rev-parse", "--show-toplevel"], {
+    cwd: lookupCwd,
+    trim: true
+  });
+  const repoRootPath = path.resolve(topLevelResult.stdout);
+  const relativeTargetPath = toPosixPath(path.relative(repoRootPath, requestedTargetPath));
+  const branchResult = await runGit(config, ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd: repoRootPath,
+    trim: true
+  });
+
+  return {
+    repoRootPath,
+    requestedTargetPath,
+    targetDisplay: requestedTargetPath,
+    targetPathspec: relativeTargetPath ? relativeTargetPath : "",
+    branchName: branchResult.stdout || "HEAD",
+    stateKey: `git:${repoRootPath}:${relativeTargetPath || "."}`
+  };
+}
+
+export async function getLatestCommit(config, targetInfo) {
+  const result = await runGit(
+    config,
+    ["log", "--format=%H", "-n", "1", "HEAD", ...buildPathArgs(targetInfo)],
+    { cwd: targetInfo.repoRootPath, trim: true }
+  );
+  const latestCommit = splitLines(result.stdout)[0];
+
+  if (!latestCommit) {
+    throw new Error(`Unable to determine the latest Git commit for ${targetInfo.targetDisplay}`);
+  }
+
+  return latestCommit;
+}
+
+export async function isValidCheckpoint(config, targetInfo, checkpointCommit, latestCommit) {
+  if (!checkpointCommit) {
+    return true;
+  }
+
+  const commitExists = await runGit(config, ["cat-file", "-e", `${checkpointCommit}^{commit}`], {
+    cwd: targetInfo.repoRootPath,
+    allowFailure: true,
+    trim: true
+  });
+
+  if (commitExists.code !== 0) {
+    return false;
+  }
+
+  const ancestorResult = await runGit(config, ["merge-base", "--is-ancestor", checkpointCommit, latestCommit], {
+    cwd: targetInfo.repoRootPath,
+    allowFailure: true,
+    trim: true
+  });
+
+  return ancestorResult.code === 0;
+}
+
+export async function getPendingCommits(config, targetInfo, startExclusive, endInclusive, limit) {
+  const args = ["rev-list", "--reverse"];
+
+  if (startExclusive) {
+    args.push(endInclusive, `^${startExclusive}`);
+  } else {
+    args.push(endInclusive);
+  }
+
+  args.push(...buildPathArgs(targetInfo));
+
+  const result = await runGit(config, args, {
+    cwd: targetInfo.repoRootPath,
+    trim: true
+  });
+
+  return splitLines(result.stdout).slice(0, limit);
+}
+
+export async function getCommitDiff(config, targetInfo, commitHash) {
+  const result = await runGit(
+    config,
+    [
+      "show",
+      "--format=",
+      "--find-renames",
+      "--find-copies",
+      "--no-ext-diff",
+      commitHash,
+      ...buildPathArgs(targetInfo)
+    ],
+    { cwd: targetInfo.repoRootPath, trim: false }
+  );
+
+  return result.stdout;
+}
+
+function parseNameStatus(stdout) {
+  const entries = stdout.split("\0").filter(Boolean);
+  const changedPaths = [];
+
+  for (let index = 0; index < entries.length; index += 1) {
+    const status = entries[index];
+
+    if (!status) {
+      continue;
+    }
+
+    const action = status[0];
+
+    if (status.startsWith("R") || status.startsWith("C")) {
+      const oldPath = entries[index + 1];
+      const newPath = entries[index + 2];
+
+      if (newPath) {
+        changedPaths.push({
+          action,
+          relativePath: newPath,
+          previousPath: oldPath || null
+        });
+      }
+
+      index += 2;
+      continue;
+    }
+
+    const filePath = entries[index + 1];
+
+    if (filePath) {
+      changedPaths.push({
+        action,
+        relativePath: filePath,
+        previousPath: null
+      });
+    }
+
+    index += 1;
+  }
+
+  return changedPaths;
+}
+
+export async function getCommitDetails(config, targetInfo, commitHash) {
+  const metaResult = await runGit(
+    config,
+    ["show", "--no-patch", "--format=%H%x00%an%x00%aI%x00%B", commitHash],
+    { cwd: targetInfo.repoRootPath, trim: false }
+  );
+  const [hash = "", author = "", date = "", ...messageParts] = metaResult.stdout.split("\0");
+  const message = messageParts.join("\0").trim();
+  const changedFilesResult = await runGit(
+    config,
+    [
+      "diff-tree",
+      "--no-commit-id",
+      "--name-status",
+      "-r",
+      "--root",
+      "-z",
+      "-M",
+      "-C",
+      commitHash,
+      ...buildPathArgs(targetInfo)
+    ],
+    { cwd: targetInfo.repoRootPath, trim: false }
+  );
+
+  return {
+    commitHash: hash.trim() || commitHash,
+    author: author.trim() || "unknown",
+    date: date.trim(),
+    message,
+    changedPaths: parseNameStatus(changedFilesResult.stdout)
+  };
+}

package/src/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import cron from "node-cron";
+import { loadConfig, parseCliArgs, printHelp } from "./config.js";
+import { runReviewCycle } from "./review-runner.js";
+
+const cliArgs = parseCliArgs(process.argv.slice(2));
+
+if (cliArgs.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const config = await loadConfig(cliArgs.configPath);
+
+let running = false;
+
+async function runOnce() {
+  if (running) {
+    console.log("A review cycle is already running, skipping this trigger.");
+    return;
+  }
+
+  running = true;
+
+  try {
+    await runReviewCycle(config);
+  } catch (error) {
+    console.error(error?.stack || String(error));
+    process.exitCode = 1;
+  } finally {
+    running = false;
+  }
+}
+
+if (cliArgs.once) {
+  await runOnce();
+  process.exit(process.exitCode || 0);
+}
+
+await runOnce();
+
+console.log(`Scheduler started. Cron: ${config.pollCron}`);
+
+cron.schedule(config.pollCron, () => {
+  void runOnce();
+});

package/src/review-runner.js

@@ -0,0 +1,353 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runCommand } from "./shell.js";
+import { resolveRepositoryContext } from "./vcs-client.js";
+
+const REVIEWERS = {
+  codex: {
+    displayName: "Codex",
+    responseSectionTitle: "Codex Response",
+    emptyResponseText: "_No final response returned from codex exec._",
+    async run(config, workingDir, promptText, diffText) {
+      const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "kodevu-"));
+      const outputFile = path.join(tempDir, "codex-last-message.md");
+      const args = [
+        "exec",
+        "--skip-git-repo-check",
+        "--sandbox",
+        "read-only",
+        "--color",
+        "never",
+        "--output-last-message",
+        outputFile,
+        "-"
+      ];
+
+      try {
+        const execResult = await runCommand("codex", args, {
+          cwd: workingDir,
+          input: [promptText, "Unified diff:", diffText].join("\n\n"),
+          allowFailure: true,
+          timeoutMs: config.commandTimeoutMs
+        });
+
+        let message = "";
+
+        try {
+          message = await fs.readFile(outputFile, "utf8");
+        } catch {
+          message = execResult.stdout;
+        }
+
+        return {
+          ...execResult,
+          message
+        };
+      } finally {
+        await fs.rm(tempDir, { recursive: true, force: true });
+      }
+    }
+  },
+  gemini: {
+    displayName: "Gemini",
+    responseSectionTitle: "Gemini Response",
+    emptyResponseText: "_No final response returned from gemini._",
+    async run(config, workingDir, promptText, diffText) {
+      const execResult = await runCommand("gemini", ["-p", promptText], {
+        cwd: workingDir,
+        input: ["Unified diff:", diffText].join("\n\n"),
+        allowFailure: true,
+        timeoutMs: config.commandTimeoutMs
+      });
+
+      return {
+        ...execResult,
+        message: execResult.stdout
+      };
+    }
+  }
+};
+
+async function ensureDir(targetPath) {
+  await fs.mkdir(targetPath, { recursive: true });
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function loadState(stateFile) {
+  if (!(await pathExists(stateFile))) {
+    return { version: 2, projects: {} };
+  }
+
+  const raw = await fs.readFile(stateFile, "utf8");
+  return normalizeStateFile(JSON.parse(raw));
+}
+
+async function saveState(stateFile, state) {
+  await ensureDir(path.dirname(stateFile));
+  await fs.writeFile(stateFile, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function normalizeStateFile(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) {
+    throw new Error('State file must be a JSON object with shape {"version":2,"projects":{...}}.');
+  }
+
+  if (state.version !== 2) {
+    throw new Error('State file version must be 2.');
+  }
+
+  if (!state.projects || typeof state.projects !== "object" || Array.isArray(state.projects)) {
+    throw new Error('State file must contain a "projects" object.');
+  }
+
+  return {
+    version: 2,
+    projects: state.projects
+  };
+}
+
+function getProjectState(stateFile, targetInfo) {
+  return stateFile.projects?.[targetInfo.stateKey] ?? {};
+}
+
+function updateProjectState(stateFile, targetInfo, projectState) {
+  return {
+    version: 2,
+    projects: {
+      ...(stateFile.projects || {}),
+      [targetInfo.stateKey]: projectState
+    }
+  };
+}
+
+async function writeTextFile(filePath, contents) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, contents, "utf8");
+}
+
+function formatChangedPaths(changedPaths) {
+  if (changedPaths.length === 0) {
+    return "_No changed files captured._";
+  }
+
+  return changedPaths
+    .map((item) => {
+      const renameSuffix = item.previousPath ? ` (from ${item.previousPath})` : "";
+      return `- \`${item.action}\` ${item.relativePath}${renameSuffix}`;
+    })
+    .join("\n");
+}
+
+function getReviewWorkspaceRoot(config, backend, targetInfo) {
+  if (backend.kind === "git" && targetInfo.repoRootPath) {
+    return targetInfo.repoRootPath;
+  }
+
+  if (backend.kind === "svn" && targetInfo.workingCopyPath) {
+    return targetInfo.workingCopyPath;
+  }
+
+  return config.baseDir;
+}
+
+function buildPrompt(config, backend, targetInfo, details) {
+  const fileList = details.changedPaths.map((item) => `${item.action} ${item.relativePath}`).join("\n");
+  const workspaceRoot = getReviewWorkspaceRoot(config, backend, targetInfo);
+  const canReadRelatedFiles = backend.kind === "git" || Boolean(targetInfo.workingCopyPath);
+
+  return [
+    config.reviewPrompt,
+    canReadRelatedFiles
+      ? `You are running inside a read-only workspace rooted at: ${workspaceRoot}`
+      : "No local repository workspace is available for this review run.",
+    canReadRelatedFiles
+      ? "Besides the diff below, you may read other related files in the workspace when needed to understand call sites, shared utilities, configuration, tests, or data flow. Do not modify files or rely on shell commands."
+      : "Review primarily from the diff below. Do not assume access to other local files, shell commands, or repository history.",
+    "Use plain text file references like path/to/file.js:123. Do not emit clickable workspace links.",
+    "Write the final review in Simplified Chinese.",
+    `Repository Type: ${backend.displayName}`,
+    `Change ID: ${details.displayId}`,
+    `Author: ${details.author}`,
+    `Date: ${details.date || "unknown"}`,
+    `Changed files:\n${fileList || "(none)"}`,
+    `Commit message:\n${details.message || "(empty)"}`
+  ].join("\n\n");
+}
+
+function buildReport(config, backend, targetInfo, details, diffText, reviewer, reviewerResult) {
+  const lines = [
+    `# ${backend.displayName} Review Report: ${details.displayId}`,
+    "",
+    `- Repository Type: \`${backend.displayName}\``,
+    `- Target: \`${targetInfo.targetDisplay || config.target}\``,
+    `- Change ID: \`${details.displayId}\``,
+    `- Author: \`${details.author}\``,
+    `- Commit Date: \`${details.date || "unknown"}\``,
+    `- Generated At: \`${new Date().toISOString()}\``,
+    `- Reviewer: \`${reviewer.displayName}\``,
+    `- Reviewer Exit Code: \`${reviewerResult.code}\``,
+    `- Reviewer Timed Out: \`${reviewerResult.timedOut ? "yes" : "no"}\``,
+    "",
+    "## Changed Files",
+    "",
+    formatChangedPaths(details.changedPaths),
+    "",
+    "## Commit Message",
+    "",
+    details.message ? "```text\n" + details.message + "\n```" : "_Empty_",
+    "",
+    "## Review Context",
+    "",
+    "```text",
+    buildPrompt(config, backend, targetInfo, details),
+    "```",
+    "",
+    "## Diff",
+    "",
+    "```diff",
+    diffText.trim() || "(empty diff)",
+    "```",
+    "",
+    `## ${reviewer.responseSectionTitle}`,
+    "",
+    reviewerResult.message?.trim() ? reviewerResult.message.trim() : reviewer.emptyResponseText
+  ];
+
+  return `${lines.join("\n")}\n`;
+}
+
+async function runReviewerPrompt(config, backend, targetInfo, details, diffText) {
+  const reviewer = REVIEWERS[config.reviewer];
+  const reviewWorkspaceRoot = getReviewWorkspaceRoot(config, backend, targetInfo);
+  const promptText = buildPrompt(config, backend, targetInfo, details);
+  return {
+    reviewer,
+    result: await reviewer.run(config, reviewWorkspaceRoot, promptText, diffText)
+  };
+}
+
+function readLastReviewedId(state, backend, targetInfo) {
+  if (state.vcs && state.vcs !== backend.kind) {
+    return null;
+  }
+
+  if (state.targetKey && state.targetKey !== targetInfo.stateKey) {
+    return null;
+  }
+
+  return backend.fromStateValue(state);
+}
+
+function buildStateSnapshot(backend, targetInfo, changeId) {
+  const state = {
+    vcs: backend.kind,
+    targetKey: targetInfo.stateKey,
+    lastReviewedId: backend.toStateValue(changeId),
+    updatedAt: new Date().toISOString()
+  };
+
+  return backend.extendState(state, changeId);
+}
+
+async function reviewChange(config, backend, targetInfo, changeId) {
+  const details = await backend.getChangeDetails(config, targetInfo, changeId);
+
+  if (details.changedPaths.length === 0) {
+    const skippedReport = [
+      `# ${backend.displayName} Review Report: ${details.displayId}`,
+      "",
+      "No file changes were captured for this change under the configured target."
+    ].join("\n");
+
+    const outputFile = path.join(config.outputDir, backend.getReportFileName(changeId));
+    await writeTextFile(outputFile, `${skippedReport}\n`);
+    return { success: true, outputFile };
+  }
+
+  const diffText = await backend.getChangeDiff(config, targetInfo, changeId);
+  const { reviewer, result: reviewerResult } = await runReviewerPrompt(config, backend, targetInfo, details, diffText);
+  const report = buildReport(config, backend, targetInfo, details, diffText, reviewer, reviewerResult);
+  const outputFile = path.join(config.outputDir, backend.getReportFileName(changeId));
+  await writeTextFile(outputFile, report);
+
+  if (reviewerResult.code !== 0 || reviewerResult.timedOut) {
+    throw new Error(`${reviewer.displayName} failed for ${details.displayId}; report written to ${outputFile}`);
+  }
+
+  return { success: true, outputFile, details };
+}
+
+function formatChangeList(backend, changeIds) {
+  return changeIds.map((changeId) => backend.formatChangeId(changeId)).join(", ");
+}
+
+export async function runReviewCycle(config) {
+  await ensureDir(config.outputDir);
+
+  const { backend, targetInfo } = await resolveRepositoryContext(config);
+  const latestChangeId = await backend.getLatestChangeId(config, targetInfo);
+  const stateFile = await loadState(config.stateFilePath);
+  const projectState = getProjectState(stateFile, targetInfo);
+  let lastReviewedId = readLastReviewedId(projectState, backend, targetInfo);
+
+  if (lastReviewedId) {
+    const checkpointIsValid = await backend.isValidCheckpoint(config, targetInfo, lastReviewedId, latestChangeId);
+
+    if (!checkpointIsValid) {
+      console.log("Saved review state no longer matches repository history. Resetting checkpoint.");
+      lastReviewedId = null;
+    }
+  }
+
+  let changeIdsToReview = [];
+
+  if (!lastReviewedId && config.bootstrapToLatest) {
+    changeIdsToReview = [latestChangeId];
+    console.log(`Initialized state to review the latest ${backend.changeName} ${backend.formatChangeId(latestChangeId)} first.`);
+  } else {
+    changeIdsToReview = await backend.getPendingChangeIds(
+      config,
+      targetInfo,
+      lastReviewedId,
+      latestChangeId,
+      config.maxRevisionsPerRun
+    );
+  }
+
+  if (changeIdsToReview.length === 0) {
+    const lastKnownId = lastReviewedId ? backend.formatChangeId(lastReviewedId) : "(none)";
+    console.log(`No new ${backend.changeName}s. Last reviewed: ${lastKnownId}`);
+    return;
+  }
+
+  console.log(`Reviewing ${backend.displayName} ${backend.changeName}s ${formatChangeList(backend, changeIdsToReview)}`);
+
+  for (const changeId of changeIdsToReview) {
+    const result = await reviewChange(config, backend, targetInfo, changeId);
+    console.log(`Reviewed ${backend.formatChangeId(changeId)}: ${result.outputFile}`);
+    const nextProjectState = buildStateSnapshot(backend, targetInfo, changeId);
+    await saveState(config.stateFilePath, updateProjectState(stateFile, targetInfo, nextProjectState));
+    stateFile.projects[targetInfo.stateKey] = nextProjectState;
+  }
+
+  const remainingChanges = await backend.getPendingChangeIds(
+    config,
+    targetInfo,
+    changeIdsToReview[changeIdsToReview.length - 1],
+    latestChangeId,
+    1
+  );
+
+  if (remainingChanges.length > 0) {
+    console.log(`Backlog remains. Latest ${backend.changeName} is ${backend.formatChangeId(latestChangeId)}.`);
+  }
+}

package/src/shell.js

@@ -0,0 +1,79 @@
+import spawn from "cross-spawn";
+import iconv from "iconv-lite";
+
+export async function runCommand(command, args = [], options = {}) {
+  const {
+    cwd,
+    env,
+    input,
+    encoding = "utf8",
+    allowFailure = false,
+    timeoutMs = 0,
+    trim = false
+  } = options;
+
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: {
+        ...process.env,
+        ...env
+      },
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let timedOut = false;
+    let timer = null;
+
+    child.stdout.on("data", (chunk) => {
+      stdoutChunks.push(Buffer.from(chunk));
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderrChunks.push(Buffer.from(chunk));
+    });
+
+    child.on("error", reject);
+
+    child.on("close", (code) => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+
+      const stdout = iconv.decode(Buffer.concat(stdoutChunks), encoding);
+      const stderr = iconv.decode(Buffer.concat(stderrChunks), encoding);
+      const result = {
+        code: code ?? 1,
+        timedOut,
+        stdout: trim ? stdout.trim() : stdout,
+        stderr: trim ? stderr.trim() : stderr
+      };
+
+      if ((result.code !== 0 || result.timedOut) && !allowFailure) {
+        const error = new Error(
+          `Command failed: ${command} ${args.join(" ")}\n${result.stderr || result.stdout}`.trim()
+        );
+        error.result = result;
+        reject(error);
+        return;
+      }
+
+      resolve(result);
+    });
+
+    if (input) {
+      child.stdin.write(input);
+    }
+
+    child.stdin.end();
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+      }, timeoutMs);
+    }
+  });
+}

package/src/svn-client.js

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { XMLParser } from "fast-xml-parser";
+import { runCommand } from "./shell.js";
+
+const SVN_COMMAND = "svn";
+const COMMAND_ENCODING = "utf8";
+
+const xmlParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: ""
+});
+
+function asArray(value) {
+  if (!value) {
+    return [];
+  }
+
+  return Array.isArray(value) ? value : [value];
+}
+
+function normalizeRepoPath(repoPath) {
+  if (!repoPath) {
+    return "/";
+  }
+
+  return repoPath.startsWith("/") ? repoPath : `/${repoPath}`;
+}
+
+function repoPathFromUrl(rootUrl, url) {
+  if (!url.startsWith(rootUrl)) {
+    throw new Error(`URL ${url} is not under repository root ${rootUrl}`);
+  }
+
+  const suffix = url.slice(rootUrl.length) || "/";
+  return normalizeRepoPath(suffix);
+}
+
+export async function getTargetInfo(config) {
+  const result = await runCommand(SVN_COMMAND, ["info", "--xml", config.target], {
+    encoding: COMMAND_ENCODING,
+    trim: true
+  });
+  const parsed = xmlParser.parse(result.stdout);
+  const entry = parsed?.info?.entry;
+
+  if (!entry?.url || !entry?.repository?.root) {
+    throw new Error(`Unable to read svn info for target ${config.target}`);
+  }
+
+  const repoRootUrl = entry.repository.root;
+  const targetUrl = entry.url;
+  const targetRepoPath = repoPathFromUrl(repoRootUrl, targetUrl);
+
+  return {
+    repoRootUrl,
+    targetUrl,
+    targetRepoPath,
+    targetDisplay: config.target,
+    stateKey: `svn:${targetUrl}`,
+    workingCopyPath:
+      entry["wc-info"]?.["wcroot-abspath"] || (path.isAbsolute(config.target) ? config.target : null)
+  };
+}
+
+function getRemoteTarget(targetInfo, config) {
+  return targetInfo?.targetUrl || config.target;
+}
+
+export async function getLatestRevision(config, targetInfo) {
+  const result = await runCommand(
+    SVN_COMMAND,
+    ["log", "--xml", "-r", "HEAD:1", "-l", "1", getRemoteTarget(targetInfo, config)],
+    { encoding: COMMAND_ENCODING, trim: true }
+  );
+  const parsed = xmlParser.parse(result.stdout);
+  const entry = parsed?.log?.logentry;
+  const revision = Number(entry?.revision);
+
+  if (!Number.isInteger(revision)) {
+    throw new Error(`Unable to determine latest SVN revision for ${config.target}`);
+  }
+
+  return revision;
+}
+
+export async function getPendingRevisions(config, targetInfo, startExclusive, endInclusive, limit) {
+  const startRevision = Number.isInteger(startExclusive) ? startExclusive + 1 : 1;
+
+  if (endInclusive < startRevision) {
+    return [];
+  }
+
+  const result = await runCommand(
+    SVN_COMMAND,
+    [
+      "log",
+      "--xml",
+      "--quiet",
+      "-r",
+      `${startRevision}:${endInclusive}`,
+      getRemoteTarget(targetInfo, config)
+    ],
+    { encoding: COMMAND_ENCODING, trim: true }
+  );
+  const parsed = xmlParser.parse(result.stdout);
+
+  return asArray(parsed?.log?.logentry)
+    .map((entry) => Number(entry?.revision))
+    .filter((revision) => Number.isInteger(revision))
+    .sort((left, right) => left - right)
+    .slice(0, limit);
+}
+
+export async function getRevisionDiff(config, revision) {
+  const result = await runCommand(
+    SVN_COMMAND,
+    ["diff", "--git", "--internal-diff", "--ignore-properties", "-c", String(revision), config.target],
+    { encoding: COMMAND_ENCODING, trim: false }
+  );
+
+  return result.stdout;
+}
+
+function isPathInsideTarget(targetRepoPath, repoPath) {
+  if (targetRepoPath === "/") {
+    return true;
+  }
+
+  return repoPath === targetRepoPath || repoPath.startsWith(`${targetRepoPath}/`);
+}
+
+function toRelativePath(targetRepoPath, repoPath) {
+  if (repoPath === targetRepoPath) {
+    return path.posix.basename(repoPath);
+  }
+
+  if (targetRepoPath === "/") {
+    return repoPath.replace(/^\/+/, "");
+  }
+
+  return repoPath.slice(targetRepoPath.length).replace(/^\/+/, "");
+}
+
+export async function getRevisionDetails(config, targetInfo, revision) {
+  const result = await runCommand(
+    SVN_COMMAND,
+    ["log", "--xml", "-v", "-c", String(revision), getRemoteTarget(targetInfo, config)],
+    { encoding: COMMAND_ENCODING, trim: true }
+  );
+  const parsed = xmlParser.parse(result.stdout);
+  const entry = parsed?.log?.logentry;
+
+  if (!entry?.revision) {
+    throw new Error(`Unable to load SVN log for revision r${revision}`);
+  }
+
+  const changedPaths = asArray(entry.paths?.path)
+    .map((item) => {
+      const repoPath = normalizeRepoPath(item["#text"] || item);
+      return {
+        action: item.action || "M",
+        kind: item.kind || "unknown",
+        repoPath,
+        relativePath: toRelativePath(targetInfo.targetRepoPath, repoPath),
+        copyFromPath: item["copyfrom-path"] ? normalizeRepoPath(item["copyfrom-path"]) : null,
+        copyFromRev: item["copyfrom-rev"] ? Number(item["copyfrom-rev"]) : null
+      };
+    })
+    .filter((item) => isPathInsideTarget(targetInfo.targetRepoPath, item.repoPath))
+    .filter((item) => item.relativePath.length > 0)
+    .filter((item) => item.kind === "file" || item.kind === "unknown");
+
+  return {
+    revision: Number(entry.revision),
+    author: entry.author || "unknown",
+    date: entry.date || "",
+    message: entry.msg || "",
+    changedPaths
+  };
+}

package/src/vcs-client.js

@@ -0,0 +1,178 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import * as gitClient from "./git-client.js";
+import * as svnClient from "./svn-client.js";
+
+function isLikelyUrl(value) {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function createSvnBackend() {
+  return {
+    kind: "svn",
+    displayName: "SVN",
+    changeName: "revision",
+    formatChangeId(revision) {
+      return `r${revision}`;
+    },
+    getReportFileName(revision) {
+      return `r${revision}.md`;
+    },
+    async getTargetInfo(config) {
+      return await svnClient.getTargetInfo(config);
+    },
+    async getLatestChangeId(config, targetInfo) {
+      return await svnClient.getLatestRevision(config, targetInfo);
+    },
+    async getPendingChangeIds(config, targetInfo, startExclusive, endInclusive, limit) {
+      return await svnClient.getPendingRevisions(config, targetInfo, startExclusive, endInclusive, limit);
+    },
+    async getChangeDiff(config, targetInfo, revision) {
+      return await svnClient.getRevisionDiff(config, revision);
+    },
+    async getChangeDetails(config, targetInfo, revision) {
+      const details = await svnClient.getRevisionDetails(config, targetInfo, revision);
+
+      return {
+        id: revision,
+        displayId: `r${details.revision}`,
+        author: details.author,
+        date: details.date,
+        message: details.message,
+        changedPaths: details.changedPaths
+      };
+    },
+    async isValidCheckpoint() {
+      return true;
+    },
+    toStateValue(revision) {
+      return Number(revision);
+    },
+    fromStateValue(state) {
+      if (Number.isInteger(state.lastReviewedId)) {
+        return state.lastReviewedId;
+      }
+
+      if (Number.isInteger(state.lastReviewedRevision)) {
+        return state.lastReviewedRevision;
+      }
+
+      return null;
+    },
+    extendState(state, revision) {
+      return {
+        ...state,
+        lastReviewedRevision: Number(revision)
+      };
+    }
+  };
+}
+
+function createGitBackend() {
+  return {
+    kind: "git",
+    displayName: "Git",
+    changeName: "commit",
+    formatChangeId(commitHash) {
+      return commitHash.slice(0, 12);
+    },
+    getReportFileName(commitHash) {
+      return `git-${commitHash}.md`;
+    },
+    async getTargetInfo(config) {
+      return await gitClient.getTargetInfo(config);
+    },
+    async getLatestChangeId(config, targetInfo) {
+      return await gitClient.getLatestCommit(config, targetInfo);
+    },
+    async getPendingChangeIds(config, targetInfo, startExclusive, endInclusive, limit) {
+      return await gitClient.getPendingCommits(config, targetInfo, startExclusive, endInclusive, limit);
+    },
+    async getChangeDiff(config, targetInfo, commitHash) {
+      return await gitClient.getCommitDiff(config, targetInfo, commitHash);
+    },
+    async getChangeDetails(config, targetInfo, commitHash) {
+      const details = await gitClient.getCommitDetails(config, targetInfo, commitHash);
+
+      return {
+        id: commitHash,
+        displayId: commitHash.slice(0, 12),
+        author: details.author,
+        date: details.date,
+        message: details.message,
+        changedPaths: details.changedPaths
+      };
+    },
+    async isValidCheckpoint(config, targetInfo, checkpointCommit, latestCommit) {
+      return await gitClient.isValidCheckpoint(config, targetInfo, checkpointCommit, latestCommit);
+    },
+    toStateValue(commitHash) {
+      return String(commitHash);
+    },
+    fromStateValue(state) {
+      if (typeof state.lastReviewedId === "string" && state.lastReviewedId) {
+        return state.lastReviewedId;
+      }
+
+      if (typeof state.lastReviewedCommit === "string" && state.lastReviewedCommit) {
+        return state.lastReviewedCommit;
+      }
+
+      return null;
+    },
+    extendState(state, commitHash) {
+      return {
+        ...state,
+        lastReviewedCommit: String(commitHash)
+      };
+    }
+  };
+}
+
+const backends = {
+  svn: createSvnBackend(),
+  git: createGitBackend()
+};
+
+export async function resolveRepositoryContext(config) {
+  if (config.vcs === "svn") {
+    return {
+      backend: backends.svn,
+      targetInfo: await backends.svn.getTargetInfo(config)
+    };
+  }
+
+  if (config.vcs === "git") {
+    return {
+      backend: backends.git,
+      targetInfo: await backends.git.getTargetInfo(config)
+    };
+  }
+
+  const candidateTargetPath = path.resolve(config.baseDir, config.target);
+
+  if (!isLikelyUrl(config.target) && (await pathExists(candidateTargetPath))) {
+    try {
+      return {
+        backend: backends.git,
+        targetInfo: await backends.git.getTargetInfo(config)
+      };
+    } catch {
+      // Fall through to SVN auto-detection.
+    }
+  }
+
+  return {
+    backend: backends.svn,
+    targetInfo: await backends.svn.getTargetInfo(config)
+  };
+}