kodevu 0.1.10 → 0.1.13

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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.
 
 ## Workflow
 
@@ -12,9 +12,20 @@ A Node.js tool that polls new SVN revisions or Git commits, fetches each change
    - 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/`
+   - 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.
 
+## Quick start
+
+```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
 
 ```bash
@@ -36,13 +47,13 @@ If you do not pass `--config`, Kodevu will try to load `./config.json` from the
 
 ## Run
 
-Run once:
+Run:
 
 ```bash
 npx kodevu /path/to/your/repo
 ```
 
-Run once with debug logs:
+Run with debug logs:
 
 ```bash
 npx kodevu /path/to/your/repo --debug
@@ -68,6 +79,7 @@ npx kodevu /path/to/your/repo --config ./config.current.json
 - `reviewer`: `codex`, `gemini`, or `auto`; default `auto`
 - `prompt`: saved into the report as review context
 - `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
@@ -92,7 +104,8 @@ Internal defaults:
 - 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.
-- SVN reports are written as `<YYYYMMDD-HHmmss>-svn-r<revision>.md`.
-- Git reports are written as `<YYYYMMDD-HHmmss>-git-<short-commit-hash>.md`.
+- 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.

package/config.example.json

@@ -5,5 +5,8 @@
   "outputDir": "~/.kodevu",
   "stateFilePath": "~/.kodevu/state.json",
   "commandTimeoutMs": 600000,
-  "maxRevisionsPerRun": 5
+  "maxRevisionsPerRun": 5,
+  "outputFormats": [
+    "markdown"
+  ]
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "kodevu",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "type": "module",
-  "description": "Poll SVN revisions or Git commits, send each change diff to a reviewer CLI, and write Markdown review reports.",
+  "description": "Poll SVN revisions or Git commits, send each change diff to a reviewer CLI, and write configurable review reports.",
   "bin": {
     "kodevu": "./src/index.js"
   },

package/src/config.js

@@ -16,7 +16,8 @@ const defaultConfig = {
   commandTimeoutMs: 600000,
   prompt:
     "请严格审查当前变更，优先指出 bug、回归风险、兼容性问题、安全问题、边界条件缺陷和缺失测试。请使用简体中文输出 Markdown；如果没有明确缺陷，请写“未发现明确缺陷”，并补充剩余风险。",
-  maxRevisionsPerRun: 20
+  maxRevisionsPerRun: 20,
+  outputFormats: ["markdown"]
 };
 
 function resolveConfigPath(baseDir, value) {
@@ -39,6 +40,29 @@ function resolveConfigPath(baseDir, value) {
   return path.isAbsolute(value) ? value : path.resolve(baseDir, value);
 }
 
+
+function normalizeOutputFormats(outputFormats, loadedConfigPath) {
+  const source = outputFormats == null ? ["markdown"] : outputFormats;
+  const values = Array.isArray(source) ? source : [source];
+  const normalized = [...new Set(values.map((item) => String(item || "").trim().toLowerCase()).filter(Boolean))];
+  const supported = ["markdown", "json"];
+  const invalid = normalized.filter((item) => !supported.includes(item));
+
+  if (invalid.length > 0) {
+    throw new Error(
+      `"outputFormats" contains unsupported value(s): ${invalid.join(", ")}. Use any of: ${supported.join(", ")}${
+        loadedConfigPath ? ` in ${loadedConfigPath}` : ""
+      }`
+    );
+  }
+
+  if (normalized.length === 0) {
+    throw new Error(`"outputFormats" must include at least one format${loadedConfigPath ? ` in ${loadedConfigPath}` : ""}`);
+  }
+
+  return normalized;
+}
+
 async function resolveAutoReviewers(debug, loadedConfigPath) {
   const availableReviewers = [];
 
@@ -200,6 +224,7 @@ export async function loadConfig(configPath, cliArgs = {}) {
   config.stateFilePath = resolveConfigPath(config.baseDir, config.stateFilePath);
   config.maxRevisionsPerRun = Number(config.maxRevisionsPerRun);
   config.commandTimeoutMs = Number(config.commandTimeoutMs);
+  config.outputFormats = normalizeOutputFormats(config.outputFormats, loadedConfigPath);
 
   if (!Number.isInteger(config.maxRevisionsPerRun) || config.maxRevisionsPerRun <= 0) {
     throw new Error(`"maxRevisionsPerRun" must be a positive integer${loadedConfigPath ? ` in ${loadedConfigPath}` : ""}`);
@@ -233,6 +258,7 @@ Options:
 Config highlights:
   reviewer       codex | gemini | auto
   target         Repository target path (Git) or SVN working copy / URL; CLI positional target overrides config
+  outputFormats  ["markdown"] by default; set to include "json" when needed
 `);
 }
 

package/src/review-runner.js

@@ -154,6 +154,15 @@ async function writeTextFile(filePath, contents) {
   await fs.writeFile(filePath, contents, "utf8");
 }
 
+async function writeJsonFile(filePath, payload) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+function shouldWriteFormat(config, format) {
+  return Array.isArray(config.outputFormats) && config.outputFormats.includes(format);
+}
+
 function formatChangedPaths(changedPaths) {
   if (changedPaths.length === 0) {
     return "_No changed files captured._";
@@ -351,6 +360,47 @@ function buildReport(config, backend, targetInfo, details, diffPayloads, reviewe
   return `${lines.join("\n")}\n`;
 }
 
+function buildJsonReport(config, backend, targetInfo, details, diffPayloads, reviewer, reviewerResult) {
+  return {
+    repositoryType: backend.displayName,
+    target: targetInfo.targetDisplay || config.target,
+    changeId: details.displayId,
+    author: details.author,
+    commitDate: details.date || "unknown",
+    generatedAt: new Date().toISOString(),
+    reviewer: {
+      name: reviewer.displayName,
+      exitCode: reviewerResult.code,
+      timedOut: Boolean(reviewerResult.timedOut)
+    },
+    changedFiles: details.changedPaths.map((item) => ({
+      action: item.action,
+      path: item.relativePath,
+      previousPath: item.previousPath || null
+    })),
+    commitMessage: details.message || "",
+    reviewContext: buildPrompt(config, backend, targetInfo, details, diffPayloads.review),
+    diffHandling: {
+      reviewerInput: {
+        originalLines: diffPayloads.review.originalLineCount,
+        originalChars: diffPayloads.review.originalCharCount,
+        includedLines: diffPayloads.review.outputLineCount,
+        includedChars: diffPayloads.review.outputCharCount,
+        truncated: diffPayloads.review.wasTruncated
+      },
+      reportDiff: {
+        originalLines: diffPayloads.report.originalLineCount,
+        originalChars: diffPayloads.report.originalCharCount,
+        includedLines: diffPayloads.report.outputLineCount,
+        includedChars: diffPayloads.report.outputCharCount,
+        truncated: diffPayloads.report.wasTruncated
+      }
+    },
+    diff: diffPayloads.report.text.trim(),
+    reviewerResponse: reviewerResult.message?.trim() ? reviewerResult.message.trim() : reviewer.emptyResponseText
+  };
+}
+
 async function runReviewerPrompt(config, backend, targetInfo, details, diffText) {
   const reviewer = REVIEWERS[config.reviewer];
   const reviewWorkspaceRoot = getReviewWorkspaceRoot(config, backend, targetInfo);
@@ -364,26 +414,14 @@ async function runReviewerPrompt(config, backend, targetInfo, details, 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,
+  return {
     lastReviewedId: backend.toStateValue(changeId),
     updatedAt: new Date().toISOString()
   };
-
-  return backend.extendState(state, changeId);
 }
 
 async function reviewChange(config, backend, targetInfo, changeId) {
@@ -396,9 +434,29 @@ async function reviewChange(config, backend, targetInfo, changeId) {
       "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 markdownReportFile = path.join(config.outputDir, backend.getReportFileName(changeId));
+    const jsonReportFile = markdownReportFile.replace(/\.md$/i, ".json");
+
+    if (shouldWriteFormat(config, "markdown")) {
+      await writeTextFile(markdownReportFile, `${skippedReport}\n`);
+    }
+
+    if (shouldWriteFormat(config, "json")) {
+      await writeJsonFile(jsonReportFile, {
+        repositoryType: backend.displayName,
+        target: targetInfo.targetDisplay || config.target,
+        changeId: details.displayId,
+        generatedAt: new Date().toISOString(),
+        skipped: true,
+        message: "No file changes were captured for this change under the configured target."
+      });
+    }
+
+    return {
+      success: true,
+      outputFile: shouldWriteFormat(config, "markdown") ? markdownReportFile : null,
+      jsonOutputFile: shouldWriteFormat(config, "json") ? jsonReportFile : null
+    };
   }
 
   const diffText = await backend.getChangeDiff(config, targetInfo, changeId);
@@ -435,13 +493,33 @@ async function reviewChange(config, backend, targetInfo, changeId) {
 
   const report = buildReport(currentReviewerConfig, backend, targetInfo, details, diffPayloads, reviewer, reviewerResult);
   const outputFile = path.join(config.outputDir, backend.getReportFileName(changeId));
-  await writeTextFile(outputFile, report);
+  const jsonOutputFile = outputFile.replace(/\.md$/i, ".json");
+
+  if (shouldWriteFormat(config, "markdown")) {
+    await writeTextFile(outputFile, report);
+  }
+
+  if (shouldWriteFormat(config, "json")) {
+    await writeJsonFile(
+      jsonOutputFile,
+      buildJsonReport(currentReviewerConfig, backend, targetInfo, details, diffPayloads, reviewer, reviewerResult)
+    );
+  }
 
   if (reviewerResult.code !== 0 || reviewerResult.timedOut) {
-    throw new Error(`${reviewer.displayName} failed for ${details.displayId}; report written to ${outputFile}`);
+    throw new Error(
+      `${reviewer.displayName} failed for ${details.displayId}; report written to ${outputFile}${
+        shouldWriteFormat(config, "json") ? ` and ${jsonOutputFile}` : ""
+      }`
+    );
   }
 
-  return { success: true, outputFile, details };
+  return {
+    success: true,
+    outputFile: shouldWriteFormat(config, "markdown") ? outputFile : null,
+    jsonOutputFile: shouldWriteFormat(config, "json") ? jsonOutputFile : null,
+    details
+  };
 }
 
 function formatChangeList(backend, changeIds) {
@@ -502,7 +580,11 @@ export async function runReviewCycle(config) {
   for (const changeId of changeIdsToReview) {
     debugLog(config, `Starting review for ${backend.formatChangeId(changeId)}.`);
     const result = await reviewChange(config, backend, targetInfo, changeId);
-    console.log(`Reviewed ${backend.formatChangeId(changeId)}: ${result.outputFile}`);
+    const outputLabels = [
+      result.outputFile ? `md: ${result.outputFile}` : null,
+      result.jsonOutputFile ? `json: ${result.jsonOutputFile}` : null
+    ].filter(Boolean);
+    console.log(`Reviewed ${backend.formatChangeId(changeId)}: ${outputLabels.join(" | ") || "(no report file generated)"}`);
     const nextProjectState = buildStateSnapshot(backend, targetInfo, changeId);
     await saveState(config.stateFilePath, updateProjectState(stateFile, targetInfo, nextProjectState));
     stateFile.projects[targetInfo.stateKey] = nextProjectState;

package/src/vcs-client.js

@@ -67,21 +67,8 @@ function createSvnBackend() {
       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)
-      };
+      const id = state.lastReviewedId;
+      return Number.isInteger(id) ? id : null;
     }
   };
 }
@@ -137,21 +124,8 @@ function createGitBackend() {
       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 id = state.lastReviewedId;
+      return typeof id === "string" && id ? id : null;
     }
   };
 }