kodevu 0.1.29 → 0.1.31

package/README.md

@@ -1,63 +1,55 @@
 # 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 review results to report files.
+A Node.js tool that fetches Git commits or SVN revisions, sends the diff to a supported AI reviewer CLI, and writes review results to report files.
 
 ## Workflow
 
 1. Detect the repository type automatically (Git or SVN).
-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 `~/.kodevu/` (Markdown by default; optional JSON via config)
-5. Update `~/.kodevu/state.json` so the same change is not reviewed twice.
+2. Fetch the specified revision(s) as requested by the user:
+   - A single specific revision/commit via `--rev`.
+   - The latest $N$ revisions/commits via `--last` (default: 1).
+3. 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 `~/.kodevu/` (Markdown by default; optional JSON via config).
+
+**Note**: Kodevu is stateless. It does not track which changes have been reviewed previously.
 
 ## Quick start
 
+Review the latest commit in your repository:
+
 ```bash
 npx kodevu /path/to/your/repo
 ```
 
-No config file is required for the default flow.
-Review reports are written to `~/.kodevu/` as Markdown (`.md`) by default, and review state is stored at `~/.kodevu/state.json`.
-
-If you want a config file, run `npx kodevu init` to create `./config.json` in the current directory.
-
-## Setup
+Review the latest 3 commits:
 
 ```bash
-npx kodevu init
+npx kodevu /path/to/your/repo --last 3
 ```
 
-This creates `config.json` in the current directory from built-in defaults.
-You only need this when you want to override defaults such as `reviewer` or output paths.
-
-If you want a different path:
+Review a specific commit:
 
 ```bash
-npx kodevu init --config ./config.current.json
+npx kodevu /path/to/your/repo --rev abc1234
 ```
 
-Then edit `config.json` if you want custom settings.
+Review reports are written to `~/.kodevu/` as Markdown (`.md`) by default.
 
-If you do not pass `--config`, Kodevu will try to load `./config.json` from the current directory only when that file exists. Otherwise it runs with built-in defaults.
-
-## Run
+## Setup
 
-Run:
+If you want to customize settings beyond the defaults:
 
 ```bash
-npx kodevu /path/to/your/repo
+npx kodevu init
 ```
 
-Run with debug logs:
+This creates `config.json` in the current directory. You only need this when you want to override defaults such as `reviewer` or output paths.
 
-```bash
-npx kodevu /path/to/your/repo --debug
-```
+## Run
 
 Specify the output language (e.g., Chinese):
 
@@ -65,60 +57,43 @@ Specify the output language (e.g., Chinese):
 npx kodevu /path/to/your/repo --lang zh
 ```
 
-Use a custom config path only when needed:
+Run with debug logs:
 
 ```bash
-npx kodevu --config ./config.current.json
+npx kodevu /path/to/your/repo --debug
 ```
 
-Or combine a config file with a positional target override:
+Use a custom config path:
 
 ```bash
-npx kodevu /path/to/your/repo --config ./config.current.json
+npx kodevu --config ./my-config.json
 ```
 
-`--debug` / `-d` is a CLI-only switch. It is not read from `config.json`.
-
-## Config
-
-- `target`: required repository target; can be provided by config or as the CLI positional argument
-- `reviewer`: `codex`, `gemini`, `copilot`, or `auto`; default `auto`
-- `prompt`: additional instructions for the reviewer; usually empty by default as the core instructions are built-in
-- `lang`: output language for the review (e.g., `zh`, `en`, `auto`); default `auto`
-- `outputDir`: report output directory; default `~/.kodevu`
-- `outputFormats`: report formats to generate; supports `markdown` and `json`; default `["markdown"]`
-- `stateFilePath`: review state file path; default `~/.kodevu/state.json`
-- `commandTimeoutMs`: timeout for a single review command execution in milliseconds
-- `maxRevisionsPerRun`: cap the number of pending changes per polling cycle
-
-Internal defaults:
+## Config / CLI Options
 
-- by default, review reports and state are stored under `~/.kodevu`; first run starts from the current latest change instead of replaying full history
-- if `./config.json` is absent, Kodevu still runs with built-in defaults as long as you pass a positional `target`
-- Kodevu invokes `git`, `svn`, and the configured reviewer CLI from `PATH`; when `reviewer` is `auto`, it randomly selects one from the installed reviewer CLIs it can find in `PATH`; debug logging is enabled only by passing `--debug` or `-d`
+- `target`: Repository target path or SVN URL. (CLI positional argument overrides config)
+- `reviewer`: `codex`, `gemini`, `copilot`, or `auto` (default: `auto`).
+- `rev`: A specific revision or commit hash to review.
+- `last`: Number of latest revisions to review (default: 1 if `rev` is not set).
+- `lang`: Output language for the review (e.g., `zh`, `en`, `auto`).
+- `prompt`: Additional instructions for the reviewer.
+- `outputDir`: Report output directory (default: `~/.kodevu`).
+- `outputFormats`: Report formats to generate (supports `markdown` and `json`; default: `["markdown"]`).
+- `commandTimeoutMs`: Timeout for a single review command execution in milliseconds.
+- `maxRevisionsPerRun`: Cap the number of revisions handled in one run.
 
 ## 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.
-- The tool tries Git first for existing local paths, then falls back to SVN.
+- The tool tries Git first, then falls back to SVN.
 
 ## Notes
 
-- `reviewer: "codex"` uses `codex exec` with the diff embedded in the prompt.
-- `reviewer: "gemini"` uses `gemini -p` in non-interactive mode.
-- `reviewer: "copilot"` uses `copilot -p` in non-interactive mode.
-- `reviewer: "auto"` probes `codex`, `gemini`, and `copilot` in `PATH`, then randomly chooses one of the available CLIs for this run.
-- Large diffs are truncated before being sent to the reviewer or written into the report once they exceed the configured line or character limits.
-- 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.
-- By default, SVN reports are written as `<YYYYMMDD-HHmmss>-svn-r<revision>.md`.
-- By default, Git reports are written as `<YYYYMMDD-HHmmss>-git-<short-commit-hash>.md`.
-- If `outputFormats` includes `json`, matching `.json` files are generated alongside Markdown reports.
-- `~/.kodevu/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.
-- Review instructions are built into the tool in English to ensure consistent logic across reviewers. The `lang` setting (CLI `--lang` or config `lang`) determines the language AI uses for the resulting review. When set to `auto`, Kodevu detects the language from the system environment (`LANG`, `LC_ALL`, or system locale).
-- Each report includes a `Token Usage` section recording token consumption for the review task. When the reviewer CLI outputs token statistics (via stderr), those are used directly (`source: "reviewer"`). Otherwise tokens are estimated at ~4 characters per token (`source: "estimate"`). The JSON report contains a `tokenUsage` object with `inputTokens`, `outputTokens`, `totalTokens`, and `source`.
+- `reviewer: "auto"` probes `codex`, `gemini`, and `copilot` in `PATH`, then selects an available one.
+- Large diffs are truncated based on internal limits to fit AI context windows.
+- 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.
+- If the reviewer command exits non-zero or times out, the report is still written containing the error details.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodevu",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "license": "MIT",
   "type": "module",
   "description": "Poll SVN revisions or Git commits, send each change diff to a reviewer CLI, and write configurable review reports.",

package/src/config.js

@@ -12,12 +12,13 @@ const defaultConfig = {
   target: "",
   lang: "auto",
   outputDir: defaultStorageDir,
-  stateFilePath: path.join(defaultStorageDir, "state.json"),
   logsDir: path.join(defaultStorageDir, "logs"),
   commandTimeoutMs: 600000,
   prompt: "",
   maxRevisionsPerRun: 5,
-  outputFormats: ["markdown"]
+  outputFormats: ["markdown"],
+  rev: "",
+  last: 0
 };
 
 const configTemplate = {
@@ -26,11 +27,12 @@ const configTemplate = {
   lang: defaultConfig.lang,
   prompt: defaultConfig.prompt,
   outputDir: "~/.kodevu",
-  stateFilePath: "~/.kodevu/state.json",
   logsDir: "~/.kodevu/logs",
   commandTimeoutMs: defaultConfig.commandTimeoutMs,
   maxRevisionsPerRun: defaultConfig.maxRevisionsPerRun,
-  outputFormats: defaultConfig.outputFormats
+  outputFormats: defaultConfig.outputFormats,
+  rev: "",
+  last: 1
 };
 
 function resolveConfigPath(baseDir, value) {
@@ -145,6 +147,8 @@ export function parseCliArgs(argv) {
     reviewer: "",
     lang: "",
     prompt: "",
+    rev: "",
+    last: "",
     commandExplicitlySet: false
   };
 
@@ -208,6 +212,26 @@ export function parseCliArgs(argv) {
       continue;
     }
 
+    if (value === "--rev" || value === "-v") {
+      const rev = argv[index + 1];
+      if (!rev || rev.startsWith("-")) {
+        throw new Error(`Missing value for ${value}`);
+      }
+      args.rev = rev;
+      index += 1;
+      continue;
+    }
+
+    if (value === "--last" || value === "-n") {
+      const last = argv[index + 1];
+      if (!last || last.startsWith("-")) {
+        throw new Error(`Missing value for ${value}`);
+      }
+      args.last = last;
+      index += 1;
+      continue;
+    }
+
     if (!value.startsWith("-") && args.command === "run" && !args.target) {
       args.target = value;
       continue;
@@ -258,6 +282,14 @@ export async function loadConfig(configPath, cliArgs = {}) {
     config.lang = cliArgs.lang;
   }
 
+  if (cliArgs.rev) {
+    config.rev = cliArgs.rev;
+  }
+
+  if (cliArgs.last) {
+    config.last = cliArgs.last;
+  }
+
   if (!config.target) {
     throw new Error('Missing target. Pass `npx kodevu <repo-path>` or set "target" in config.json.');
   }
@@ -284,12 +316,16 @@ export async function loadConfig(configPath, cliArgs = {}) {
   config.configPath = loadedConfigPath;
   config.baseDir = baseDir;
   config.outputDir = resolveConfigPath(config.baseDir, config.outputDir);
-  config.stateFilePath = resolveConfigPath(config.baseDir, config.stateFilePath);
   config.logsDir = resolveConfigPath(config.baseDir, config.logsDir);
   config.maxRevisionsPerRun = Number(config.maxRevisionsPerRun);
   config.commandTimeoutMs = Number(config.commandTimeoutMs);
+  config.last = Number(config.last);
   config.outputFormats = normalizeOutputFormats(config.outputFormats, loadedConfigPath);
 
+  if (!config.rev && (isNaN(config.last) || config.last <= 0)) {
+    config.last = 1;
+  }
+
   if (!Number.isInteger(config.maxRevisionsPerRun) || config.maxRevisionsPerRun <= 0) {
     throw new Error(`"maxRevisionsPerRun" must be a positive integer${loadedConfigPath ? ` in ${loadedConfigPath}` : ""}`);
   }
@@ -317,6 +353,8 @@ Options:
   --reviewer, -r Override reviewer (codex | gemini | copilot | auto)
   --prompt, -p   Override prompt
   --lang, -l     Override output language (e.g. zh, en, auto)
+  --rev, -v      Review a specific revision or commit hash
+  --last, -n     Review the latest N revisions (default: 1)
   --debug, -d    Print extra debug information to the console
   --help, -h     Show help
 

package/src/git-client.js

@@ -124,6 +124,16 @@ export async function getPendingCommits(config, targetInfo, startExclusive, endI
   return splitLines(result.stdout).slice(0, limit);
 }
 
+export async function getLatestCommitIds(config, targetInfo, limit) {
+  const result = await runGit(
+    config,
+    ["rev-list", "-n", String(limit), "HEAD", ...buildPathArgs(targetInfo)],
+    { cwd: targetInfo.repoRootPath, trim: true }
+  );
+  // Reverse to get chronological order (oldest to newest among the latest n)
+  return splitLines(result.stdout).reverse();
+}
+
 export async function getCommitDiff(config, targetInfo, commitHash) {
   const result = await runGit(
     config,

package/src/report-generator.js

@@ -13,14 +13,41 @@ export function getReviewWorkspaceRoot(config, backend, targetInfo) {
   return config.baseDir;
 }
 
+function getLanguageDisplayName(lang) {
+  if (!lang) return "English";
+  const low = lang.toLowerCase();
+  if (low.startsWith("zh")) {
+    if (low === "zh-tw" || low === "zh-hk") return "Traditional Chinese (繁體中文)";
+    return "Simplified Chinese (简体中文)";
+  }
+  if (low === "jp" || low.startsWith("ja")) return "Japanese (日本語)";
+  if (low === "kr" || low.startsWith("ko")) return "Korean (한국어)";
+  if (low === "fr") return "French (Français)";
+  if (low === "de") return "German (Deutsch)";
+  if (low === "es") return "Spanish (Español)";
+  if (low === "it") return "Italian (Italiano)";
+  if (low === "ru") return "Russian (Русский)";
+  return lang;
+}
+
 export function buildPrompt(config, backend, targetInfo, details, reviewDiffPayload) {
   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);
 
-  const langInstruction = config.resolvedLang === "zh"
-    ? "Please use Simplified Chinese for your response."
-    : `Please use ${config.resolvedLang || "English"} for your response.`;
+  const langName = getLanguageDisplayName(config.resolvedLang);
+  const lowLang = (config.resolvedLang || "").toLowerCase();
+  let langInstruction = `IMPORTANT: Your entire response MUST be in ${langName}. All explanations, comments, and structure should strictly follow the ${langName} language rules.`;
+
+  if (lowLang.startsWith("zh")) {
+    if (lowLang === "zh-tw" || lowLang === "zh-hk") {
+      langInstruction += "\n請務必使用繁體中文進行回覆，所有的審查評論和分析都必須以繁體中文呈現。";
+    } else {
+      langInstruction += "\n请务必使用简体中文进行回复，所有的审查评论和分析都必须以简体中文呈现。";
+    }
+  }
+
+
 
   return [
     CORE_REVIEW_INSTRUCTION,
@@ -41,8 +68,18 @@ export function buildPrompt(config, backend, targetInfo, details, reviewDiffPayl
     `Commit message:\n${details.message || "(empty)"}`,
     reviewDiffPayload.wasTruncated
       ? `Diff delivery note: the diff was truncated before being sent to the reviewer to stay within configured size limits. Original diff size was ${reviewDiffPayload.originalLineCount} lines / ${reviewDiffPayload.originalCharCount} chars, and the included excerpt is ${reviewDiffPayload.outputLineCount} lines / ${reviewDiffPayload.outputCharCount} chars. Use the changed file list and inspect related workspace files when needed.`
-      : `Diff delivery note: the full diff is included. Size is ${reviewDiffPayload.originalLineCount} lines / ${reviewDiffPayload.originalCharCount} chars.`
+      : `Diff delivery note: the full diff is included. Size is ${reviewDiffPayload.originalLineCount} lines / ${reviewDiffPayload.originalCharCount} chars.`,
+    `--- IMPORTANT LANGUAGE RULE ---\nYou MUST respond strictly in ${langName}. No other language should be used for the explanation and comments.${
+      lowLang.startsWith("zh")
+        ? lowLang === "zh-tw" || lowLang === "zh-hk"
+          ? "\n請務必完全使用繁體中文進行回覆，所有的審查分析、注釋和總結都必須使用繁體中文。"
+          : "\n请务必完全使用简体中文进行回复，所有的审查分析、注释和总结都必须使用简体中文。"
+        : ""
+    }`
+
   ].filter(Boolean).join("\n\n");
+
+
 }
 
 export function formatTokenUsage(tokenUsage) {

package/src/review-runner.js

@@ -7,14 +7,6 @@ import {
   writeTextFile,
   writeJsonFile
 } from "./utils.js";
-import {
-  loadState,
-  saveState,
-  getProjectState,
-  updateProjectState,
-  readLastReviewedId,
-  buildStateSnapshot
-} from "./state-manager.js";
 import {
   shouldWriteFormat,
   buildReport,
@@ -158,45 +150,19 @@ export async function runReviewCycle(config) {
 
   const { backend, targetInfo } = await resolveRepositoryContext(config);
   logger.debug(
-    `Resolved repository context: backend=${backend.kind} target=${targetInfo.targetDisplay || config.target} stateKey=${targetInfo.stateKey}`
-  );
-  const latestChangeId = await backend.getLatestChangeId(config, targetInfo);
-  const stateFile = await loadState(config.stateFilePath);
-  const projectState = getProjectState(stateFile, targetInfo);
-  let lastReviewedId = readLastReviewedId(projectState, backend, targetInfo);
-  logger.debug(
-    `Checkpoint status: latest=${backend.formatChangeId(latestChangeId)} lastReviewed=${lastReviewedId ? backend.formatChangeId(lastReviewedId) : "(none)"}`
+    `Resolved repository context: backend=${backend.kind} target=${targetInfo.targetDisplay || config.target}`
   );
 
-  if (lastReviewedId) {
-    const checkpointIsValid = await backend.isValidCheckpoint(config, targetInfo, lastReviewedId, latestChangeId);
-
-    if (!checkpointIsValid) {
-      logger.info("Saved review state no longer matches repository history. Resetting checkpoint.");
-      lastReviewedId = null;
-    }
-  }
-
   let changeIdsToReview = [];
 
-  if (!lastReviewedId) {
-    changeIdsToReview = [latestChangeId];
-    logger.info(`Initialized state to review the latest ${backend.changeName} ${backend.formatChangeId(latestChangeId)} first.`);
+  if (config.rev) {
+    changeIdsToReview = [config.rev];
   } else {
-    changeIdsToReview = await backend.getPendingChangeIds(
-      config,
-      targetInfo,
-      lastReviewedId,
-      latestChangeId,
-      config.maxRevisionsPerRun
-    );
+    changeIdsToReview = await backend.getLatestChangeIds(config, targetInfo, config.last || 1);
   }
 
-  logger.debug(`Planned ${changeIdsToReview.length} ${backend.changeName}(s) for this cycle.`);
-
   if (changeIdsToReview.length === 0) {
-    const lastKnownId = lastReviewedId ? backend.formatChangeId(lastReviewedId) : "(none)";
-    logger.info(`No new ${backend.changeName}s. Last reviewed: ${lastKnownId}`);
+    logger.info("No changes found to review.");
     return;
   }
 
@@ -215,20 +181,12 @@ export async function runReviewCycle(config) {
       updateOverallProgress(progress, index, changeIdsToReview.length, fraction, `${displayId} | ${stage}`);
     };
 
-    let result;
-
     try {
-      result = await reviewChange(config, backend, targetInfo, changeId, { update: syncOverallProgress, log: (message) => progress.log(message) });
-      syncOverallProgress(0.94, "saving checkpoint");
+      await reviewChange(config, backend, targetInfo, changeId, { update: syncOverallProgress, log: (message) => progress.log(message) });
+      updateOverallProgress(progress, index + 1, changeIdsToReview.length, 0, `finished ${displayId}`);
     } catch (error) {
       progress.fail(`failed at ${displayId} (${index}/${changeIdsToReview.length} completed)`);
       throw error;
     }
-
-    const nextProjectSnapshot = buildStateSnapshot(backend, targetInfo, changeId);
-    await saveState(config.stateFilePath, updateProjectState(stateFile, targetInfo, nextProjectSnapshot));
-    stateFile.projects[targetInfo.stateKey] = nextProjectSnapshot;
-    logger.debug(`Saved checkpoint for ${backend.formatChangeId(changeId)} to ${config.stateFilePath}.`);
-    updateOverallProgress(progress, index + 1, changeIdsToReview.length, 0, `finished ${displayId}`);
   }
 }

package/src/svn-client.js

@@ -112,6 +112,20 @@ export async function getPendingRevisions(config, targetInfo, startExclusive, en
     .slice(0, limit);
 }
 
+export async function getLatestRevisionIds(config, targetInfo, limit) {
+  const result = await runCommand(
+    SVN_COMMAND,
+    ["log", "--xml", "--quiet", "-l", String(limit), "-r", "HEAD:1", getRemoteTarget(targetInfo, config)],
+    { encoding: COMMAND_ENCODING, trim: true, debug: config.debug }
+  );
+  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);
+}
+
 export async function getRevisionDiff(config, revision) {
   const result = await runCommand(
     SVN_COMMAND,

package/src/vcs-client.js

@@ -42,8 +42,8 @@ function createSvnBackend() {
     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 getLatestChangeIds(config, targetInfo, limit) {
+      return await svnClient.getLatestRevisionIds(config, targetInfo, limit);
     },
     async getChangeDiff(config, targetInfo, revision) {
       return await svnClient.getRevisionDiff(config, revision);
@@ -59,16 +59,6 @@ function createSvnBackend() {
         message: details.message,
         changedPaths: details.changedPaths
       };
-    },
-    async isValidCheckpoint() {
-      return true;
-    },
-    toStateValue(revision) {
-      return Number(revision);
-    },
-    fromStateValue(state) {
-      const id = state.lastReviewedId;
-      return Number.isInteger(id) ? id : null;
     }
   };
 }
@@ -99,8 +89,8 @@ function createGitBackend() {
     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 getLatestChangeIds(config, targetInfo, limit) {
+      return await gitClient.getLatestCommitIds(config, targetInfo, limit);
     },
     async getChangeDiff(config, targetInfo, commitHash) {
       return await gitClient.getCommitDiff(config, targetInfo, commitHash);
@@ -116,16 +106,6 @@ function createGitBackend() {
         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) {
-      const id = state.lastReviewedId;
-      return typeof id === "string" && id ? id : null;
     }
   };
 }

package/src/state-manager.js

@@ -1,61 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { pathExists, ensureDir } from "./utils.js";
-
-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
-  };
-}
-
-export async function loadState(stateFile) {
-  if (!(await pathExists(stateFile))) {
-    return { version: 2, projects: {} };
-  }
-
-  const raw = await fs.readFile(stateFile, "utf8");
-  return normalizeStateFile(JSON.parse(raw));
-}
-
-export async function saveState(stateFile, state) {
-  await ensureDir(path.dirname(stateFile));
-  await fs.writeFile(stateFile, `${JSON.stringify(state, null, 2)}\n`, "utf8");
-}
-
-export function getProjectState(stateFile, targetInfo) {
-  return stateFile.projects?.[targetInfo.stateKey] ?? {};
-}
-
-export function updateProjectState(stateFile, targetInfo, projectState) {
-  return {
-    version: 2,
-    projects: {
-      ...(stateFile.projects || {}),
-      [targetInfo.stateKey]: projectState
-    }
-  };
-}
-
-export function readLastReviewedId(state, backend, targetInfo) {
-  return backend.fromStateValue(state);
-}
-
-export function buildStateSnapshot(backend, targetInfo, changeId) {
-  return {
-    lastReviewedId: backend.toStateValue(changeId),
-    updatedAt: new Date().toISOString()
-  };
-}