kodevu 0.1.54 → 0.1.56

package/README.md

@@ -1,5 +1,7 @@
 # Kodevu
 
+> The name **Kodevu** is a phonetic play on "code review".
+
 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.
 
 ## Pure & Zero Config
@@ -19,6 +21,7 @@ npx kodevu .
 ```
 
 Review reports are saved to `~/.kodevu/` by default.
+Console output is intentionally concise by default; detailed execution logs are written to `~/.kodevu/logs/`.
 
 ## Usage
 
@@ -42,7 +45,7 @@ npx kodevu [target] [options]
 - `--openai-model`: Model used when `--reviewer openai` (default: `gpt-5-mini`).
 - `--openai-org`: Optional OpenAI organization ID.
 - `--openai-project`: Optional OpenAI project ID.
-- `--debug, -d`: Print debug information.
+- `--debug, -d`: Show extra debug information on the console.
 - `--version, -V`: Print the current version and exit.
 
 > [!IMPORTANT]
@@ -127,13 +130,6 @@ npx kodevu . \
   --openai-model gpt-5-mini
 ```
 
-## How it Works
-
-- **Git Targets**: `target` must be a local repository or subdirectory.
-- **SVN Targets**: `target` can be a working copy path or repository URL.
-- **Reviewer "auto"**: Probes `codex`, `gemini`, and `copilot` in your `PATH` and selects one.
-- **Reviewer "openai"**: Calls the OpenAI Chat Completions API directly. `auto` does not select `openai`, so API-based use stays explicit.
-- **Contextual Review**: For local repositories, the reviewer can inspect related files beyond the diff to provide deeper insights.
 
 ## License
 

package/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: kodevu
-description: A tool to fetch Git commits or SVN revisions, send the diff to a supported AI reviewer CLI, and write configurable review reports.
+description: A tool to fetch Git/SVN diffs, send them to an AI reviewer, and generate configurable code review reports.
 ---
 
 # Kodevu Skill
 
-Kodevu is 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.
+Kodevu is 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. It is designed to be **stateless** and requires **no configuration files**.
 
 ## Usage
 
-Use `npx kodevu` to review a codebase. It is designed to be stateless and requires no configuration files.
+Use `npx kodevu` to review a codebase.
 
 ### Reviewing the latest commit
 
@@ -29,13 +29,19 @@ npx kodevu . --rev <commit-hash>
 npx kodevu . --last 3
 ```
 
+### Reviewing uncommitted changes
+
+```bash
+npx kodevu . --uncommitted
+```
+
 ### Supported Reviewers
 
-`kodevu` supports several AI reviewer CLIs: `auto`, `openai`, `gemini`, `codex`, `copilot`. The default is `auto`. Use the `--reviewer` option to override.
+`kodevu` supports several AI reviewer backends: `auto`, `openai`, `gemini`, `codex`, `copilot`. The default is `auto`, which probes available CLI tools in your `PATH`.
 
 Example using OpenAI:
 ```bash
-npx kodevu . --reviewer openai --openai-api-key <YOUR_API_KEY> --openai-model gpt-4o
+npx kodevu . --reviewer openai --openai-api-key <YOUR_API_KEY> --openai-model gpt-5-mini
 ```
 
 ### Generating JSON Reports
@@ -45,19 +51,31 @@ By default, review reports are generated as Markdown files in `~/.kodevu/`. You
 npx kodevu . --format json --output ./reports
 ```
 
-### Formatting the Prompt
+### Custom Prompts
 
-You can provide clear instructions to the reviewer using `--prompt`:
+You can provide additional instructions to the reviewer using `--prompt`:
 ```bash
 npx kodevu . --prompt "Focus on security issues and suggest optimizations."
 ```
 Or from a file: `--prompt @my-rules.txt`
 
+### Environment Variables
+
+All options can also be set via environment variables to avoid repetitive flags:
+
+- `KODEVU_REVIEWER` – Default reviewer.
+- `KODEVU_LANG` – Default output language.
+- `KODEVU_OUTPUT_DIR` – Default output directory.
+- `KODEVU_PROMPT` – Default prompt instructions.
+- `KODEVU_OPENAI_API_KEY` – API key for `openai`.
+- `KODEVU_OPENAI_BASE_URL` – Base URL for `openai`.
+- `KODEVU_OPENAI_MODEL` – Model for `openai`.
+
 ## Working with Target Repositories
 
-- `target`: Repository path (Git) or SVN URL/Working copy (default: `.`).
+- **Git**: `target` must be a local repository or subdirectory.
+- **SVN**: `target` can be a working copy path or repository URL.
 
-For example, to run on a specific path, you can use:
 ```bash
 npx kodevu /path/to/project --last 1
 ```

package/package.json

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

@@ -373,7 +373,7 @@ Options:
   --openai-model    Model used when reviewer=openai (default: gpt-5-mini)
   --openai-org      Optional OpenAI organization ID
   --openai-project  Optional OpenAI project ID
-  --debug, -d       Print extra debug information
+  --debug, -d       Show extra debug information on the console
   --help, -h        Show help
   --version, -V     Show version
 

package/src/index.js

@@ -30,33 +30,57 @@ try {
 
   if (config.reviewerWasAutoSelected) {
     logger.info(
-      `Reviewer "auto" selected ${config.reviewer}${config.reviewerCommandPath ? ` (${config.reviewerCommandPath})` : ""}.`
-    );
-  }
-
-  if (config.debug) {
-    logger.debug(
-      `Resolved config: ${JSON.stringify({
+      `Reviewer "auto" selected ${config.reviewer}${config.reviewerCommandPath ? ` (${config.reviewerCommandPath})` : ""}.`,
+      {
+        scope: "session",
         reviewer: config.reviewer,
-        reviewerCommandPath: config.reviewerCommandPath,
-        reviewerWasAutoSelected: config.reviewerWasAutoSelected,
-        openaiBaseUrl: config.openaiBaseUrl,
-        openaiModel: config.openaiModel,
-        openaiOrganization: config.openaiOrganization,
-        openaiProject: config.openaiProject,
-        target: config.target,
-        outputDir: config.outputDir,
-        lang: config.lang,
-        debug: config.debug
-      })}`
+        reviewerCommandPath: config.reviewerCommandPath || "",
+        console: true
+      }
     );
   }
 
-  logger.info(`Session started. Target: ${config.target}`);
+  logger.debug("Resolved config", {
+    scope: "session",
+    reviewer: config.reviewer,
+    reviewerCommandPath: config.reviewerCommandPath || "",
+    reviewerWasAutoSelected: config.reviewerWasAutoSelected || false,
+    openaiBaseUrl: config.openaiBaseUrl,
+    openaiModel: config.openaiModel,
+    openaiOrganization: config.openaiOrganization || "",
+    openaiProject: config.openaiProject || "",
+    target: config.target,
+    outputDir: config.outputDir,
+    lang: config.lang,
+    resolvedLang: config.resolvedLang,
+    debug: config.debug,
+    outputFormats: config.outputFormats,
+    mode: config.uncommitted ? "uncommitted" : config.rev ? "rev" : "last",
+    rev: config.rev || "",
+    last: config.last || 0,
+    console: "debug"
+  });
+
+  logger.info("Session started", {
+    scope: "session",
+    target: config.target,
+    reviewer: config.reviewer,
+    outputDir: config.outputDir,
+    mode: config.uncommitted ? "uncommitted" : config.rev ? "rev" : "last",
+    rev: config.rev || "",
+    last: config.last || 0
+  });
   await runReviewCycle(config);
-  logger.info("Session completed successfully.");
+  logger.info("Session completed successfully", {
+    scope: "session",
+    target: config.target,
+    reviewer: config.reviewer
+  });
 } catch (error) {
-  logger.error("Session failed with error", error);
+  logger.error("Session failed", error, {
+    scope: "session",
+    console: true
+  });
   process.exitCode = 1;
 }
 process.exit(process.exitCode || 0);

package/src/logger.js

@@ -2,16 +2,87 @@ import fs from "node:fs";
 import path from "node:path";
 import { formatDate } from "./utils.js";
 
+function formatValue(value) {
+  if (value == null) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return value.trim();
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function formatMeta(meta = {}) {
+  const parts = [];
+
+  for (const [key, rawValue] of Object.entries(meta)) {
+    if (rawValue == null || rawValue === "") {
+      continue;
+    }
+
+    const value = formatValue(rawValue);
+    if (!value) {
+      continue;
+    }
+
+    if (typeof rawValue === "string") {
+      parts.push(`${key}=${JSON.stringify(value)}`);
+      continue;
+    }
+
+    if (typeof rawValue === "number" || typeof rawValue === "boolean") {
+      parts.push(`${key}=${String(rawValue)}`);
+      continue;
+    }
+
+    parts.push(`${key}=${value}`);
+  }
+
+  return parts.join(" ");
+}
+
+function formatErrorDetails(error) {
+  if (!error) {
+    return "";
+  }
+
+  if (error instanceof Error) {
+    return error.stack || error.message || String(error);
+  }
+
+  if (typeof error === "string") {
+    return error;
+  }
+
+  try {
+    return JSON.stringify(error, null, 2);
+  } catch {
+    return String(error);
+  }
+}
+
 class Logger {
   constructor() {
     this.config = null;
     this.logFile = null;
+    this.sessionId = null;
     this.initialized = false;
   }
 
   init(config) {
     if (this.initialized) return;
     this.config = config;
+    this.sessionId = this._createSessionId();
     
     if (config.logsDir) {
       try {
@@ -19,7 +90,7 @@ class Logger {
           fs.mkdirSync(config.logsDir, { recursive: true });
         }
         const date = formatDate(new Date()).split(" ")[0];
-        this.logFile = path.join(config.logsDir, `run-${date}.log`);
+        this.logFile = path.join(config.logsDir, `run-${date}-${this.sessionId}.log`);
         
         // Simple rotation: Clean up logs older than 7 days
         this._cleanupOldLogs(config.logsDir);
@@ -30,33 +101,36 @@ class Logger {
     }
   }
 
-  info(message) {
-    this._log("INFO", message);
+  info(message, meta) {
+    this._log("INFO", message, meta);
   }
 
-  warn(message) {
-    this._log("WARN", message);
+  warn(message, meta) {
+    this._log("WARN", message, { ...meta, console: meta?.console ?? true });
   }
 
-  error(message, error) {
-    let msg = message;
-    if (error) {
-      msg += `\n${error.stack || error}`;
-    }
-    this._log("ERROR", msg);
+  error(message, error, meta) {
+    this._log("ERROR", message, {
+      ...meta,
+      console: meta?.console ?? true,
+      error: formatErrorDetails(error)
+    });
   }
 
-  debug(message) {
-    if (this.config?.debug) {
-      this._log("DEBUG", message);
-    }
+  debug(message, meta) {
+    this._log("DEBUG", message, meta);
   }
 
-  _log(level, message) {
+  _log(level, message, meta = {}) {
     const timestamp = formatDate(new Date());
-    const logLine = `[${timestamp}] [${level}] ${message}`;
+    const { console: consoleMode, ...details } = meta;
+    const fields = {
+      session: this.sessionId || "uninitialized",
+      ...details
+    };
+    const metaSuffix = formatMeta(fields);
+    const logLine = `[${timestamp}] [${level}] ${message}${metaSuffix ? ` | ${metaSuffix}` : ""}`;
 
-    // Write to file
     if (this.logFile) {
       try {
         fs.appendFileSync(this.logFile, logLine + "\n");
@@ -65,21 +139,52 @@ class Logger {
       }
     }
 
-    // Console output
-    const isDebug = level === "DEBUG";
-    const isError = level === "ERROR";
-    const isWarn = level === "WARN";
-
-    // If it's debug and debug mode is off, skip console
-    if (isDebug && !this.config?.debug) return;
+    if (!this._shouldWriteToConsole(level, consoleMode)) {
+      return;
+    }
 
-    if (isError || isWarn) {
+    if (level === "ERROR" || level === "WARN") {
       console.error(logLine);
     } else {
       console.log(logLine);
     }
   }
 
+  _shouldWriteToConsole(level, consoleMode) {
+    if (consoleMode === false) {
+      return false;
+    }
+
+    if (level === "ERROR" || level === "WARN") {
+      return true;
+    }
+
+    if (level === "DEBUG") {
+      if (consoleMode === true) {
+        return Boolean(this.config?.debug);
+      }
+      return false;
+    }
+
+    if (consoleMode === true) {
+      return true;
+    }
+
+    if (consoleMode === "debug") {
+      return Boolean(this.config?.debug);
+    }
+
+    return false;
+  }
+
+  _createSessionId() {
+    return [
+      Date.now().toString(36),
+      process.pid.toString(36),
+      Math.random().toString(36).slice(2, 8)
+    ].join("-");
+  }
+
   _cleanupOldLogs(logsDir) {
     try {
       const files = fs.readdirSync(logsDir);

package/src/review-runner.js

@@ -18,7 +18,11 @@ import { runReviewerPrompt } from "./reviewers.js";
 
 async function reviewChange(config, backend, targetInfo, changeId, progress) {
   const displayId = backend.formatChangeId(changeId);
-  logger.info(`Starting review for ${backend.changeName} ${displayId}`);
+  logger.info(`Starting review for ${backend.changeName} ${displayId}`, {
+    scope: "review",
+    repository: backend.kind,
+    changeId: displayId
+  });
   progress?.update(0.05, "loading change details");
   const details = await backend.getChangeDetails(config, targetInfo, changeId);
   const resolvedChangeId = details.id;
@@ -68,7 +72,13 @@ async function reviewChange(config, backend, targetInfo, changeId, progress) {
 
   for (const reviewerName of reviewersToTry) {
     currentReviewerConfig = { ...config, reviewer: reviewerName };
-    logger.debug(`Trying reviewer: ${reviewerName}`);
+    logger.debug(`Trying reviewer: ${reviewerName}`, {
+      scope: "review",
+      repository: backend.kind,
+      changeId: details.displayId,
+      reviewer: reviewerName,
+      console: "debug"
+    });
     progress?.update(0.45, `running reviewer ${reviewerName}`);
 
     try {
@@ -88,13 +98,24 @@ async function reviewChange(config, backend, targetInfo, changeId, progress) {
         break;
       }
     } catch (err) {
-      logger.error(`Reviewer prompt failed for ${reviewerName}: ${err.message}`);
+      logger.error(`Reviewer prompt failed for ${reviewerName}`, err, {
+        scope: "review",
+        repository: backend.kind,
+        changeId: details.displayId,
+        reviewer: reviewerName,
+        console: false
+      });
       // If it's the last one, it will throw below or break loop anyway
     }
 
     if (reviewerName !== reviewersToTry[reviewersToTry.length - 1]) {
       const msg = `${reviewer?.displayName || reviewerName} failed for ${details.displayId}; trying next reviewer...`;
-      logger.warn(msg);
+      logger.warn(msg, {
+        scope: "review",
+        repository: backend.kind,
+        changeId: details.displayId,
+        reviewer: reviewerName
+      });
     }
   }
 
@@ -105,7 +126,17 @@ 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}`);
+  logger.debug("Token usage recorded", {
+    scope: "review",
+    repository: backend.kind,
+    changeId: details.displayId,
+    reviewer: reviewer.displayName,
+    inputTokens: tokenUsage.inputTokens,
+    outputTokens: tokenUsage.outputTokens,
+    totalTokens: tokenUsage.totalTokens,
+    source: tokenUsage.source,
+    console: "debug"
+  });
   const report = buildReport(currentReviewerConfig, backend, targetInfo, details, diffPayloads, reviewer, reviewerResult, tokenUsage);
   const outputFile = path.join(config.outputDir, backend.getReportFileName(resolvedChangeId));
   const jsonOutputFile = outputFile.replace(/\.md$/i, ".json");
@@ -126,7 +157,13 @@ async function reviewChange(config, backend, targetInfo, changeId, progress) {
     shouldWriteFormat(config, "json") ? `json: ${jsonOutputFile}` : null
   ].filter(Boolean);
   
-  logger.info(`Completed review for ${displayId}: ${outputLabels.join(" | ") || "(no report file generated)"}`);
+  logger.info(`Completed review for ${displayId}: ${outputLabels.join(" | ") || "(no report file generated)"}`, {
+    scope: "review",
+    repository: backend.kind,
+    changeId: displayId,
+    reviewer: reviewer.displayName,
+    console: true
+  });
 
   return {
     success: true,
@@ -149,9 +186,12 @@ export async function runReviewCycle(config) {
   await ensureDir(config.outputDir);
 
   const { backend, targetInfo } = await resolveRepositoryContext(config);
-  logger.debug(
-    `Resolved repository context: backend=${backend.kind} target=${targetInfo.targetDisplay || config.target}`
-  );
+  logger.debug("Resolved repository context", {
+    scope: "session",
+    backend: backend.kind,
+    target: targetInfo.targetDisplay || config.target,
+    console: "debug"
+  });
 
   let changeIdsToReview = [];
 
@@ -167,7 +207,12 @@ export async function runReviewCycle(config) {
   }
 
   if (changeIdsToReview.length === 0) {
-    logger.info("No changes found to review.");
+    logger.info("No changes found to review.", {
+      scope: "session",
+      backend: backend.kind,
+      target: targetInfo.targetDisplay || config.target,
+      console: true
+    });
     return;
   }
 
@@ -176,12 +221,22 @@ export async function runReviewCycle(config) {
   const batchSummary = isUncommittedBatch
     ? `Reviewing ${backend.displayName} uncommitted changes`
     : `Reviewing ${backend.displayName} ${backend.changeName}s ${formatChangeList(backend, changeIdsToReview)}`;
-  logger.info(batchSummary);
+  logger.info(batchSummary, {
+    scope: "session",
+    backend: backend.kind,
+    count: changeIdsToReview.length,
+    console: true
+  });
   const progress = createProgressReporter(`${backend.displayName} ${backend.changeName} batch`);
   progress.update(0, `0/${changeIdsToReview.length} completed`);
 
   for (const [index, changeId] of changeIdsToReview.entries()) {
-    logger.debug(`Starting review for ${backend.formatChangeId(changeId)}.`);
+    logger.debug(`Starting review for ${backend.formatChangeId(changeId)}`, {
+      scope: "review",
+      repository: backend.kind,
+      changeId: backend.formatChangeId(changeId),
+      console: "debug"
+    });
     const displayId = backend.formatChangeId(changeId);
     updateOverallProgress(progress, index, changeIdsToReview.length, 0, `starting ${displayId}`);
 

package/src/shell.js

@@ -24,13 +24,18 @@ export async function runCommand(command, args = [], options = {}) {
     debug = false
   } = options;
 
-  logger.debug(
-    `run: ${command} ${args.join(" ")}${cwd ? ` | cwd=${cwd}` : ""}${timeoutMs > 0 ? ` | timeoutMs=${timeoutMs}` : ""}${
-      input ? ` | input=${summarizeOutput(input)}` : ""
-    }`
-  );
+  logger.debug(`run: ${command}`, {
+    scope: "command",
+    command,
+    args,
+    cwd: cwd || "",
+    timeoutMs: timeoutMs || 0,
+    input: input ? summarizeOutput(input) : "",
+    console: debug ? "debug" : false
+  });
 
   return await new Promise((resolve, reject) => {
+    const startedAt = Date.now();
     const child = spawn(command, args, {
       cwd,
       env: {
@@ -54,7 +59,12 @@ export async function runCommand(command, args = [], options = {}) {
     });
 
     child.on("error", (err) => {
-      logger.error(`spawn error: ${command}`, err);
+      logger.error(`spawn error: ${command}`, err, {
+        scope: "command",
+        command,
+        args,
+        cwd: cwd || ""
+      });
       reject(err);
     });
 
@@ -71,14 +81,26 @@ export async function runCommand(command, args = [], options = {}) {
         stdout: trim ? stdout.trim() : stdout,
         stderr: trim ? stderr.trim() : stderr
       };
-
-      const level = (result.code !== 0 || result.timedOut) && !allowFailure ? "ERROR" : "DEBUG";
-      const exitMsg = `exit: ${command} code=${result.code} timedOut=${result.timedOut} stdout=${summarizeOutput(result.stdout)} stderr=${summarizeOutput(result.stderr)}`;
+      const durationMs = Date.now() - startedAt;
+
+      const exitMeta = {
+        scope: "command",
+        command,
+        args,
+        cwd: cwd || "",
+        code: result.code,
+        timedOut: result.timedOut,
+        allowFailure,
+        durationMs,
+        stdout: summarizeOutput(result.stdout),
+        stderr: summarizeOutput(result.stderr),
+        console: debug ? "debug" : false
+      };
       
-      if (level === "ERROR") {
-        logger.error(exitMsg);
+      if ((result.code !== 0 || result.timedOut) && !allowFailure) {
+        logger.error(`exit: ${command}`, null, exitMeta);
       } else {
-        logger.debug(exitMsg);
+        logger.debug(`exit: ${command}`, exitMeta);
       }
 
       if ((result.code !== 0 || result.timedOut) && !allowFailure) {

package/src/utils.js

@@ -50,9 +50,10 @@ export function formatDate(dateInput) {
   const hours = pad(d.getHours());
   const minutes = pad(d.getMinutes());
   const seconds = pad(d.getSeconds());
+  const milliseconds = String(d.getMilliseconds()).padStart(3, "0");
   const offset = `${sign}${pad(offsetHours)}:${pad(offsetMins)}`;
 
-  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} ${offset}`;
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${milliseconds} ${offset}`;
 }
 export function getTimestampPrefix() {
   const now = new Date();