kodevu 0.1.9 → 0.1.11

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.9",
+  "version": "0.1.11",
   "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,7 +40,30 @@ function resolveConfigPath(baseDir, value) {
   return path.isAbsolute(value) ? value : path.resolve(baseDir, value);
 }
 
-async function resolveAutoReviewer(debug, loadedConfigPath) {
+
+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 = [];
 
   for (const reviewerName of SUPPORTED_REVIEWERS) {
@@ -57,7 +81,12 @@ async function resolveAutoReviewer(debug, loadedConfigPath) {
     );
   }
 
-  return availableReviewers[Math.floor(Math.random() * availableReviewers.length)];
+  for (let i = availableReviewers.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [availableReviewers[i], availableReviewers[j]] = [availableReviewers[j], availableReviewers[i]];
+  }
+
+  return availableReviewers;
 }
 
 export function parseCliArgs(argv) {
@@ -177,9 +206,11 @@ export async function loadConfig(configPath, cliArgs = {}) {
   config.reviewer = String(config.reviewer || "auto").toLowerCase();
 
   if (config.reviewer === "auto") {
-    const selectedReviewer = await resolveAutoReviewer(config.debug, loadedConfigPath);
+    const availableReviewers = await resolveAutoReviewers(config.debug, loadedConfigPath);
+    const selectedReviewer = availableReviewers[0];
     config.reviewer = selectedReviewer.reviewerName;
     config.reviewerCommandPath = selectedReviewer.commandPath;
+    config.fallbackReviewers = availableReviewers.map(r => r.reviewerName).slice(1);
     config.reviewerWasAutoSelected = true;
   } else if (!SUPPORTED_REVIEWERS.includes(config.reviewer)) {
     throw new Error(
@@ -193,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}` : ""}`);
@@ -226,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);
@@ -396,28 +446,92 @@ 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);
-  const { reviewer, diffPayloads, result: reviewerResult } = await runReviewerPrompt(
-    config,
-    backend,
-    targetInfo,
-    details,
-    diffText
-  );
-  const report = buildReport(config, backend, targetInfo, details, diffPayloads, reviewer, reviewerResult);
+  const reviewersToTry = [config.reviewer, ...(config.fallbackReviewers || [])];
+
+  let reviewer;
+  let diffPayloads;
+  let reviewerResult;
+  let currentReviewerConfig;
+
+  for (const reviewerName of reviewersToTry) {
+    currentReviewerConfig = { ...config, reviewer: reviewerName };
+    debugLog(config, `Trying reviewer: ${reviewerName}`);
+
+    const res = await runReviewerPrompt(
+      currentReviewerConfig,
+      backend,
+      targetInfo,
+      details,
+      diffText
+    );
+    reviewer = res.reviewer;
+    diffPayloads = res.diffPayloads;
+    reviewerResult = res.result;
+
+    if (reviewerResult.code === 0 && !reviewerResult.timedOut) {
+      break;
+    }
+
+    if (reviewerName !== reviewersToTry[reviewersToTry.length - 1]) {
+      console.log(`${reviewer.displayName} failed for ${details.displayId}; trying next reviewer...`);
+    }
+  }
+
+  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) {
@@ -478,7 +592,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;