kodevu 0.1.34 → 0.1.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodevu",
-  "version": "0.1.34",
+  "version": "0.1.37",
   "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

@@ -266,8 +266,8 @@ Options:
   --reviewer, -r    Reviewer (codex | gemini | copilot | auto, default: auto)
   --prompt, -p      Additional instructions or @file.txt to read from file
   --lang, -l        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)
+  --rev, -v         Review specific revision(s), hashes, branches or ranges (comma-separated)
+  --last, -n        Review the latest N revisions (ignored if --rev is provided) (default: 1)
   --output, -o      Output directory (default: ~/.kodevu)
   --format, -f      Output formats (markdown, json, comma-separated)
   --debug, -d       Print extra debug information

package/src/git-client.js

@@ -105,6 +105,25 @@ export async function isValidCheckpoint(config, targetInfo, checkpointCommit, la
   return ancestorResult.code === 0;
 }
 
+export async function resolveCommits(config, targetInfo, revSpec) {
+  const result = await runGit(
+    config,
+    ["rev-list", revSpec],
+    { cwd: targetInfo.repoRootPath, trim: true, allowFailure: true }
+  );
+
+  if (result.code !== 0) {
+    // Attempt fallback to a single hash resolution if rev-list fails (e.g. for non-standard specs)
+    const single = await runGit(config, ["rev-parse", revSpec], {
+      cwd: targetInfo.repoRootPath, trim: true, allowFailure: true
+    });
+    if (single.code === 0) return [single.stdout.trim()];
+    throw new Error(`Failed to resolve Git revision: ${revSpec}`);
+  }
+
+  return splitLines(result.stdout);
+}
+
 export async function getPendingCommits(config, targetInfo, startExclusive, endInclusive, limit) {
   const args = ["rev-list", "--reverse"];
 

package/src/report-generator.js

@@ -2,11 +2,65 @@ export function getCoreReviewInstruction(lang) {
   const lowLang = (lang || "").toLowerCase();
   if (lowLang.startsWith("zh")) {
     if (lowLang === "zh-tw" || lowLang === "zh-hk") {
-      return "請嚴格審查目前的更改，優先考慮錯誤、回歸風險、相容性問題、安全問題、邊界條件缺陷和缺失的測試。請使用 Markdown 進行回覆。如果未發現明顯缺陷，請寫「未發現明顯缺陷」並補充風險。";
+      return `你是一位擁有 10 年以上經驗的高級軟體架構師和代碼審查專家。你的任務是對以下代碼變更進行嚴格且高質量的審查。
+你的目標是：
+1. 發現代碼中的 Bug、邏輯缺陷和潛在的回歸風險。
+2. 識別性能瓶頸、記憶體洩漏或不必要的計算。
+3. 檢查安全漏洞（如注入、越權、敏感信息洩露等）。
+4. 評估代碼的可維護性、可讀性和是否符合最佳實踐。
+5. 檢查是否涵蓋了必要的單元測試和邊界條件。
+
+你的輸出格式必須清晰，請使用以下 Markdown 結構：
+### 1. 變更總結 (Summary)
+簡要描述這次提交的主要目的和影響面。
+### 2. 核心缺陷 (Critical Issues)
+列出 Bug、安全隱患或會導致程序崩潰/邏輯錯誤的問題。請註明檔案名和行號。
+### 3. 改進建議 (Suggestions)
+列出關於代碼風格、性能優化或架構設計的改進點。
+### 4. 審查結論 (Conclusion)
+如果發現明顯缺陷，總結修復建議；如果未發現明顯缺陷，請說明「未發現明顯缺陷」並指出可能的殘留風險。
+
+注意：你正處於唯讀審查模式，請勿表現出「正在應用補丁」或「準備執行代碼」的行為。只需提供文字審查分析。`;
     }
-    return "请严格审查当前的更改，优先处理 Bug、回归风险、兼容性问题、安全问题、边界条件缺陷和缺失的测试。请使用 Markdown 进行回复。如果未发现明显缺陷，请写“未发现明显缺陷”并补充残留风险。";
+    return `你是一位拥有 10 年以上经验的高级软件架构师和代码审查专家。你的任务是对以下代码变更进行严格且高质量的审查。
+你的目标是：
+1. 发现代码中的 Bug、逻辑缺陷和潜在的回归风险。
+2. 识别性能瓶颈、内存泄漏或不必要的计算。
+3. 检查安全漏洞（如注入、越权、敏感信息泄露等）。
+4. 评估代码的可维护性、可读性和是否符合最佳实践。
+5. 检查是否涵盖了必要的单元测试和边界条件。
+
+你的输出格式必须清晰，请使用以下 Markdown 结构：
+### 1. 变更总结 (Summary)
+简要描述这次提交的主要目的和影响面。
+### 2. 核心缺陷 (Critical Issues)
+列出 Bug、安全隐患或会导致程序崩溃/逻辑错误的问题。请注明文件名和行号。
+### 3. 改进建议 (Suggestions)
+列出关于代码风格、性能优化或架构设计的改进点。
+### 4. 审查结论 (Conclusion)
+如果发现明显缺陷，总结修复建议；如果未发现明显缺陷，请说明“未发现明显缺陷”并指出可能的残留风险。
+
+注意：你正处于只读审查模式，请勿表现出“正在应用补丁”或“准备执行代码”的行为。只需提供文字审查分析。`;
   }
-  return "Please strictly review the current changes, prioritizing bugs, regression risks, compatibility issues, security concerns, boundary condition flaws, and missing tests. Please use Markdown for your response. If no clear flaws are found, write \"No clear flaws found\" and supplement with residual risks.";
+  return `You are a Senior Software Engineer and Code Review Expert with over 10 years of experience. Your task is to perform a rigorous and high-quality review of the following code changes.
+Your goals are to:
+1. Identify bugs, logical flaws, and potential regression risks.
+2. Spot performance bottlenecks, memory leaks, or unnecessary computations.
+3. Check for security vulnerabilities (e.g., injection, authorization issues, sensitive data leaks).
+4. Evaluate maintainability, readability, and adherence to best practices.
+5. Verify coverage of necessary unit tests and boundary conditions.
+
+Your output must be structured using the following Markdown headers:
+### 1. Summary
+Briefly describe the purpose and impact of this change.
+### 2. Critical Issues
+List bugs, security risks, or problems that could cause crashes or logical errors. Include file names and line numbers.
+### 3. Suggestions
+List points for improvement regarding code style, performance, or architectural design.
+### 4. Conclusion
+Summarize with a "Pass" or "Needs Revision". If no clear flaws are found, state "No clear flaws found" and mention any residual risks.
+
+Note: You are in a read-only review mode. Do not act as if you are "applying the patch" or "executing code". Provide only textual analysis and feedback.`;
 }
 
 export function getReviewWorkspaceRoot(config, backend, targetInfo) {
@@ -40,52 +94,52 @@ function getLanguageDisplayName(lang) {
 
 const LOCALIZED_PHRASES = {
   en: {
-    workspaceRoot: "You are running inside a read-only workspace rooted at:",
+    workspaceRoot: "Workspace context (read-only):",
     noWorkspace: "No local repository workspace is available for this review run.",
-    besidesDiff: "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.",
-    reviewFromDiff: "Review primarily from the diff below. Do not assume access to other local files, shell commands, or repository history.",
-    fileRefs: "Use plain text file references like path/to/file.js:123. Do not emit clickable workspace links.",
+    besidesDiff: "You can read related files in the workspace to understand call sites, shared utilities, configuration, or data flow.",
+    reviewFromDiff: "Review primarily based on the provided diff. Do not assume access to other local files or shell commands.",
+    fileRefs: "Reference files using plain text like 'path/to/file.js:123'. Do not generate clickable workspace links.",
     repoType: "Repository Type",
     changeId: "Change ID",
     author: "Author",
     date: "Date",
     changedFiles: "Changed files",
     commitMessage: "Commit message",
-    diffNoteTruncated: "Diff delivery note: the diff was truncated before being sent to the reviewer to stay within configured size limits. Original diff size was {originalLineCount} lines / {originalCharCount} chars, and the included excerpt is {outputLineCount} lines / {outputCharCount} chars. Use the changed file list and inspect related workspace files when needed.",
-    diffNoteFull: "Diff delivery note: the full diff is included. Size is {originalLineCount} lines / {originalCharCount} chars.",
-    langRule: "--- IMPORTANT LANGUAGE RULE ---\nYou MUST respond strictly in {langName}. No other language should be used for the explanation and comments."
+    diffNoteTruncated: "Note: The diff was truncated to fit size limits. Original: {originalLineCount} lines / {originalCharCount} chars. Included: {outputLineCount} lines / {outputCharCount} chars.",
+    diffNoteFull: "Note: Full diff provided ({originalLineCount} lines / {originalCharCount} chars).",
+    langRule: "--- LANGUAGE RULE ---\nYour entire response must be in {langName}. No other language allowed."
   },
   zh: {
-    workspaceRoot: "你正运行在一个只读工作区内，根目录为：",
+    workspaceRoot: "只读工作区上下文：",
     noWorkspace: "此审查运行没有可用的本地仓库工作区。",
-    besidesDiff: "除了下面的 Diff，你可以在需要时阅读工作区中的其他相关文件，以了解调用点、共享工具、配置、测试或数据流。请勿修改文件或依赖 Shell 命令。",
-    reviewFromDiff: "主要根据下面的 Diff 进行审查。不要假设可以访问其他本地文件、Shell 命令或仓库历史。",
-    fileRefs: "使用纯文本文件引用，如 path/to/file.js:123。不要生成可点击的工作区链接。",
+    besidesDiff: "你可以阅读工作区中的其他文件以了解调用点、工具类、配置或数据流。",
+    reviewFromDiff: "主要根据提供的 Diff 进行审查。不要假设可以访问其他文件或执行 Shell 命令。",
+    fileRefs: "使用纯文本引用文件，如 'path/to/file.js:123'。不要生成可点击的链接。",
     repoType: "仓库类型",
     changeId: "变更 ID",
     author: "作者",
     date: "日期",
     changedFiles: "已变更文件",
     commitMessage: "提交信息",
-    diffNoteTruncated: "Diff 交付说明：Diff 在发送给审查者之前已被截斷，以保持在配置的大小限制内。原始 Diff 大小为 {originalLineCount} 行 / {originalCharCount} 个字符，包含的摘录为 {outputLineCount} 行 / {outputCharCount} 个字符。在需要时使用已更正文件列表并检查相关工作区文件。",
-    diffNoteFull: "Diff 交付说明：包含完整的 Diff。大小为 {originalLineCount} 行 / {originalCharCount} 个字符。",
-    langRule: "--- 重要语言规则 ---\n你必须严格使用 {langName} 进行回复。解释、评论和总结均不得使用其他语言。"
+    diffNoteTruncated: "注意：Diff 已截断。原始：{originalLineCount} 行 / {originalCharCount} 字符。包含：{outputLineCount} 行 / {outputCharCount} 字符。",
+    diffNoteFull: "注意：包含完整 Diff ({originalLineCount} 行 / {originalCharCount} 字符)。",
+    langRule: "--- 语言规则 ---\n你必须完全使用 {langName} 进行回复。不得使用其他语言进行解释或总结。"
   },
   "zh-tw": {
-    workspaceRoot: "你正運行在一個唯讀工作區內，根目錄為：",
+    workspaceRoot: "唯讀工作區上下文：",
     noWorkspace: "此審查運行沒有可用的本地倉庫工作區。",
-    besidesDiff: "除了下面的 Diff，你可以在需要時閱讀工作區中的其他相關文件，以了解調用點、共享工具、配置、測試或資料流。請勿修改文件或依賴 Shell 命令。",
-    reviewFromDiff: "主要根據下面的 Diff 進行審查。不要假設可以訪問其他本地文件、Shell 命令或倉庫歷史。",
-    fileRefs: "使用純文本文件引用，如 path/to/file.js:123。不要生成可點擊的工作區連結。",
+    besidesDiff: "你可以閱讀工作區中的其他文件以了解調用點、工具類、配置或資料流。",
+    reviewFromDiff: "主要根據提供的 Diff 進行審查。不要假設可以訪問其他文件或執行 Shell 命令。",
+    fileRefs: "使用純文本引用文件，如 'path/to/file.js:123'。不要生成可點擊的連結。",
     repoType: "倉庫類型",
     changeId: "變更 ID",
     author: "作者",
     date: "日期",
     changedFiles: "已變更文件",
     commitMessage: "提交信息",
-    diffNoteTruncated: "Diff 交付說明：Diff 在傳送給審查者之前已被截斷，以保持在配置的大小限制內。原始 Diff 大小為 {originalLineCount} 行 / {originalCharCount} 個字符，包含的摘錄為 {outputLineCount} 行 / {outputCharCount} 個字符。在需要時使用已更正文件列表並檢查相關工作區文件。",
-    diffNoteFull: "Diff 交付說明：包含完整的 Diff。大小為 {originalLineCount} 行 / {originalCharCount} 個字符。",
-    langRule: "--- 重要語言規則 ---\n你必須嚴格使用 {langName} 進行回覆。解釋、評論和總結均不得使用其他語言。"
+    diffNoteTruncated: "注意：Diff 已截斷。原始：{originalLineCount} 行 / {originalCharCount} 字符。包含：{outputLineCount} 行 / {outputCharCount} 字符。",
+    diffNoteFull: "注意：包含完整 Diff ({originalLineCount} 行 / {originalCharCount} 字符)。",
+    langRule: "--- 語言規則 ---\n你必須完全使用 {langName} 進行回覆。不得使用其他語言進行解釋或總結。"
   }
 };
 
@@ -109,51 +163,52 @@ export function buildPrompt(config, backend, targetInfo, details, reviewDiffPayl
   const langName = getLanguageDisplayName(lang);
   const lowLang = lang.toLowerCase();
 
-  let langInstruction = `IMPORTANT: Your entire response MUST be in ${langName}. All explanations, comments, and structure should strictly follow the ${langName} language rules.`;
-
+  let langInstruction = `CRITICAL: YOUR ENTIRE RESPONSE MUST BE IN ${langName.toUpperCase()}.`;
   if (lowLang.startsWith("zh")) {
     if (lowLang === "zh-tw" || lowLang === "zh-hk") {
-      langInstruction += "\n請務必使用繁體中文進行回覆，所有的審查評論和分析都必須以繁體中文呈現。";
+      langInstruction += "\n請務必完全使用繁體中文進行回覆。";
     } else {
-      langInstruction += "\n请务必使用简体中文进行回复，所有的审查评论和分析都必须以简体中文呈现。";
+      langInstruction += "\n请务必完全使用简体中文进行回复。";
     }
   }
 
-  return [
-    langInstruction,
-    getCoreReviewInstruction(lang),
-    config.prompt,
-    canReadRelatedFiles
-      ? `${getPhrase("workspaceRoot", lang)} ${workspaceRoot}`
-      : getPhrase("noWorkspace", lang),
-    canReadRelatedFiles
-      ? getPhrase("besidesDiff", lang)
-      : getPhrase("reviewFromDiff", lang),
-    getPhrase("fileRefs", lang),
+  const metadata = [
     `${getPhrase("repoType", lang)}: ${backend.displayName}`,
     `${getPhrase("changeId", lang)}: ${details.displayId}`,
     `${getPhrase("author", lang)}: ${details.author}`,
     `${getPhrase("date", lang)}: ${details.date || "unknown"}`,
     `${getPhrase("changedFiles", lang)}:\n${fileList || "(none)"}`,
-    `${getPhrase("commitMessage", lang)}:\n${details.message || "(empty)"}`,
-    reviewDiffPayload.wasTruncated
-      ? getPhrase("diffNoteTruncated", lang, {
-          originalLineCount: reviewDiffPayload.originalLineCount,
-          originalCharCount: reviewDiffPayload.originalCharCount,
-          outputLineCount: reviewDiffPayload.outputLineCount,
-          outputCharCount: reviewDiffPayload.outputCharCount
-        })
-      : getPhrase("diffNoteFull", lang, {
-          originalLineCount: reviewDiffPayload.originalLineCount,
-          originalCharCount: reviewDiffPayload.originalCharCount
-        }),
-    getPhrase("langRule", lang, { langName }) +
-      (lowLang.startsWith("zh")
-        ? lowLang === "zh-tw" || lowLang === "zh-hk"
-          ? "\n請務必完全使用繁體中文進行回覆，所有的審查分析、注釋和總結都必須使用繁體中文。"
-          : "\n请务必完全使用简体中文进行回复，所有的审查分析、注释和总结都必须使用简体中文。"
-        : "")
-  ].filter(Boolean).join("\n\n");
+    `${getPhrase("commitMessage", lang)}:\n${details.message || "(empty)"}`
+  ].join("\n");
+
+  const diffNote = reviewDiffPayload.wasTruncated
+    ? getPhrase("diffNoteTruncated", lang, {
+        originalLineCount: reviewDiffPayload.originalLineCount,
+        originalCharCount: reviewDiffPayload.originalCharCount,
+        outputLineCount: reviewDiffPayload.outputLineCount,
+        outputCharCount: reviewDiffPayload.outputCharCount
+      })
+    : getPhrase("diffNoteFull", lang, {
+        originalLineCount: reviewDiffPayload.originalLineCount,
+        originalCharCount: reviewDiffPayload.originalCharCount
+      });
+
+  const sections = [
+    langInstruction,
+    getCoreReviewInstruction(lang),
+    config.prompt ? `### Additional User Instructions:\n${config.prompt}` : null,
+    "### Change Context:",
+    metadata,
+    diffNote,
+    "### Environment:",
+    canReadRelatedFiles
+      ? `${getPhrase("workspaceRoot", lang)} ${workspaceRoot}\n${getPhrase("besidesDiff", lang)}`
+      : getPhrase("noWorkspace", lang),
+    getPhrase("fileRefs", lang),
+    getPhrase("langRule", lang, { langName })
+  ];
+
+  return sections.filter(Boolean).join("\n\n");
 }
 
 export function formatTokenUsage(tokenUsage) {

package/src/review-runner.js

@@ -20,6 +20,7 @@ async function reviewChange(config, backend, targetInfo, changeId, progress) {
   logger.info(`Starting review for ${backend.changeName} ${displayId}`);
   progress?.update(0.05, "loading change details");
   const details = await backend.getChangeDetails(config, targetInfo, changeId);
+  const resolvedChangeId = details.id;
 
   if (details.changedPaths.length === 0) {
     progress?.update(0.7, "writing skipped report");
@@ -29,7 +30,7 @@ async function reviewChange(config, backend, targetInfo, changeId, progress) {
       "No file changes were captured for this change under the configured target."
     ].join("\n");
 
-    const markdownReportFile = path.join(config.outputDir, backend.getReportFileName(changeId));
+    const markdownReportFile = path.join(config.outputDir, backend.getReportFileName(resolvedChangeId));
     const jsonReportFile = markdownReportFile.replace(/\.md$/i, ".json");
 
     if (shouldWriteFormat(config, "markdown")) {
@@ -55,7 +56,7 @@ async function reviewChange(config, backend, targetInfo, changeId, progress) {
   }
 
   progress?.update(0.2, "loading diff");
-  const diffText = await backend.getChangeDiff(config, targetInfo, changeId);
+  const diffText = await backend.getChangeDiff(config, targetInfo, resolvedChangeId);
   const reviewersToTry = [config.reviewer, ...(config.fallbackReviewers || [])];
 
   let reviewer;
@@ -99,7 +100,7 @@ async function reviewChange(config, backend, targetInfo, changeId, progress) {
   progress?.update(0.82, "writing report");
   logger.debug(`Token usage: input=${tokenUsage.inputTokens} output=${tokenUsage.outputTokens} total=${tokenUsage.totalTokens} source=${tokenUsage.source}`);
   const report = buildReport(currentReviewerConfig, backend, targetInfo, details, diffPayloads, reviewer, reviewerResult, tokenUsage);
-  const outputFile = path.join(config.outputDir, backend.getReportFileName(changeId));
+  const outputFile = path.join(config.outputDir, backend.getReportFileName(resolvedChangeId));
   const jsonOutputFile = outputFile.replace(/\.md$/i, ".json");
 
   if (shouldWriteFormat(config, "markdown")) {
@@ -156,7 +157,7 @@ export async function runReviewCycle(config) {
   let changeIdsToReview = [];
 
   if (config.rev) {
-    changeIdsToReview = [config.rev];
+    changeIdsToReview = await backend.resolveChangeIds(config, targetInfo, config.rev);
   } else {
     changeIdsToReview = await backend.getLatestChangeIds(config, targetInfo, config.last || 1);
   }

package/src/vcs-client.js

@@ -36,6 +36,10 @@ function createSvnBackend() {
       return `${datePrefix}-svn-r${revision}.md`;
     },
 
+    async resolveChangeIds(config, targetInfo, revString) {
+      if (!revString) return [];
+      return String(revString).split(',').map(s => s.trim()).filter(Boolean);
+    },
     async getTargetInfo(config) {
       return await svnClient.getTargetInfo(config);
     },
@@ -83,6 +87,16 @@ function createGitBackend() {
       return `${datePrefix}-git-${commitHash.slice(0, 12)}.md`;
     },
 
+    async resolveChangeIds(config, targetInfo, revString) {
+      if (!revString) return [];
+      const specs = String(revString).split(',').map(s => s.trim()).filter(Boolean);
+      const allHashes = [];
+      for (const spec of specs) {
+        const hashes = await gitClient.resolveCommits(config, targetInfo, spec);
+        allHashes.push(...hashes);
+      }
+      return [...new Set(allHashes)];
+    },
     async getTargetInfo(config) {
       return await gitClient.getTargetInfo(config);
     },
@@ -99,8 +113,8 @@ function createGitBackend() {
       const details = await gitClient.getCommitDetails(config, targetInfo, commitHash);
 
       return {
-        id: commitHash,
-        displayId: commitHash.slice(0, 12),
+        id: details.commitHash,
+        displayId: details.commitHash.slice(0, 12),
         author: details.author,
         date: details.date,
         message: details.message,