codecritique 2.0.4 → 2.0.6

package/README.md

@@ -263,8 +263,13 @@ npx codecritique analyze --file src/components/Button.tsx
 # Analyze files matching patterns
 npx codecritique analyze --files "src/**/*.ts" "lib/*.js"
 
-# Analyze changes in feature-branch vs main branch (auto-detects base branch)
+# Review changes in a target branch against its auto-detected parent branch
 npx codecritique analyze --diff-with feature-branch
+
+# Review against an explicit base branch (overrides auto-detection).
+# Useful for stacked PRs where you know the real base, or in CI where the PR
+# base ref is authoritative.
+npx codecritique analyze --diff-with feature-B --base feature-A
 ```
 
 #### Using with Custom Guidelines
@@ -383,9 +388,6 @@ jobs:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
 
-      - name: Setup master branch for diff analysis
-        run: git fetch --no-tags --prune origin main:main
-
       - name: Code Review
         uses: cosmocoder/CodeCritique/.github/actions/pr-review@main
         with:
@@ -393,11 +395,16 @@ jobs:
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
+> No manual `git fetch` or `fetch-depth: 0` is needed. The action fetches the PR base
+> branch (the parent — which for a stacked PR is another feature branch) and deepens
+> the shallow checkout just enough to compute the diff, so parent auto-detection works
+> without the cost of a full-history clone.
+
 #### Required Setup
 
 1. **Anthropic API Key**: Store your Anthropic API key as a repository secret named `ANTHROPIC_API_KEY`
 2. **Permissions**: The workflow must have `contents: write`, `actions: read`, and `pull-requests: write` permissions
-3. **Git Setup**: Ensure the base branch is available for diff analysis (see example above)
+3. **Git Setup**: None required — the action fetches the PR base/parent branch and deepens the checkout only as much as the diff needs (no `fetch-depth: 0`)
 
 #### Input Parameters
 
@@ -450,7 +457,7 @@ codecritique analyze --file src/components/Button.tsx
 # Analyze files matching patterns
 codecritique analyze --files "src/**/*.ts" "lib/*.js"
 
-# Analyze branch diff
+# Review target branch changes against its auto-detected parent branch
 codecritique analyze --diff-with feature-branch
 
 # Generate embeddings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecritique",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "AI-powered code review tool for any programming language",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -29,9 +29,10 @@ import { cleanupClassifier, clearPRComments, getPRCommentsStats, hasPRComments }
 import { ProjectAnalyzer } from './project-analyzer.js';
 import { reviewFile, reviewFiles, reviewPullRequest } from './rag-review.js';
 import { execGitSafe } from './utils/command.js';
-import { ensureBranchExists, findBaseBranch } from './utils/git.js';
-import { verboseLog } from './utils/logging.js';
+import { ensureBranchExists, findParentBranch } from './utils/git.js';
+import { diagnosticLog, isDebugEnabled, isVerboseEnabled, verboseLog } from './utils/logging.js';
 import { collectPRLevelFindings, getFileLevelIssueCount, hasPRLevelFindings } from './utils/review-results.js';
+import { configureCleanStdoutForDataOutput, isBrokenStdoutPipeError, writeStdout } from './utils/stdout.js';
 
 // Create a default embeddings system instance
 const embeddingsSystem = getDefaultEmbeddingsSystem();
@@ -45,7 +46,11 @@ program.name('codecritique').description('CLI tool for AI-powered code review us
 program
   .command('analyze')
   .description('Analyze code using dynamic context (RAG approach)')
-  .option('-b, --diff-with <branch>', 'Analyze files changed compared to a branch (triggers PR review mode)')
+  .option(
+    '-b, --diff-with <branch>',
+    'Review the specified target branch against its auto-detected parent branch (triggers PR review mode)'
+  )
+  .option('--base <branch>', 'Base branch to diff the target against, overriding auto-detection (e.g. the authoritative PR base ref in CI)')
   .option('-f, --files <files...>', 'Specific files or glob patterns to review')
   .option('--file <file>', 'Analyze a single file')
   .option('-d, --directory <dir>', 'Working directory for git operations (use with --diff-with)')
@@ -162,12 +167,12 @@ Examples:
   $ codecritique analyze --directory src/components
   $ codecritique analyze --file src/utils/validation.ts
   $ codecritique analyze --files "src/**/*.tsx" "lib/*.js"
-  $ codecritique analyze -b main
+  $ codecritique analyze -b feature-branch
   $ codecritique analyze --doc "Our Eng Guidelines:./ENGINEERING_GUIDELINES.md" --file src/utils/validation.ts
   $ codecritique analyze --diff-with feature-branch -d /path/to/repo
   $ codecritique analyze --output json > review-results.json
   $ codecritique analyze --track-feedback --feedback-path ./feedback-artifacts --file src/utils/validation.ts
-  $ codecritique analyze --track-feedback --feedback-threshold 0.8 -b main
+  $ codecritique analyze --track-feedback --feedback-threshold 0.8 -b feature-branch
   $ codecritique embeddings:generate --directory src
   $ codecritique embeddings:generate --exclude "**/*.test.js" "**/*.spec.js"
   $ codecritique embeddings:generate --exclude-file .embedignore
@@ -213,7 +218,7 @@ else {
 
 // Register process event handlers for cleanup (embeddings cleanup primarily)
 process.on('SIGINT', async () => {
-  console.log(chalk.yellow('\nReceived SIGINT. Attempting graceful shutdown...'));
+  diagnosticLog(chalk.yellow('\nReceived SIGINT. Attempting graceful shutdown...'));
   // Set a timeout to force exit if cleanup hangs
   const forceExitTimeout = setTimeout(() => {
     console.error(chalk.red('Cleanup timed out after 10 seconds. Forcing exit...'));
@@ -221,23 +226,23 @@ process.on('SIGINT', async () => {
   }, 10000); // 10 seconds timeout
 
   try {
-    console.log(chalk.cyan('SIGINT handler: Attempting embeddingsSystem.cleanup()...'));
+    diagnosticLog(chalk.cyan('SIGINT handler: Attempting embeddingsSystem.cleanup()...'));
     await embeddingsSystem.cleanup();
-    console.log(chalk.green('embeddingsSystem.cleanup() completed.'));
+    diagnosticLog(chalk.green('embeddingsSystem.cleanup() completed.'));
     clearTimeout(forceExitTimeout); // Cleanup finished, clear the timeout
-    console.log(chalk.cyan('SIGINT handler: Exiting normally (code 0).'));
+    diagnosticLog(chalk.cyan('SIGINT handler: Exiting normally (code 0).'));
     process.exit(0); // Exit normally
   }
   catch (err) {
     console.error(chalk.red('Error during embeddingsSystem.cleanup():'), err.message);
     clearTimeout(forceExitTimeout);
-    console.log(chalk.cyan('SIGINT handler: Exiting after error (code 1).'));
+    diagnosticLog(chalk.cyan('SIGINT handler: Exiting after error (code 1).'));
     process.exit(1); // Exit with error code
   }
 });
 
 process.on('SIGTERM', async () => {
-  console.log(chalk.yellow('\nReceived SIGTERM. Attempting graceful shutdown...'));
+  diagnosticLog(chalk.yellow('\nReceived SIGTERM. Attempting graceful shutdown...'));
   // Set a timeout to force exit if cleanup hangs
   const forceExitTimeout = setTimeout(() => {
     console.error(chalk.red('Cleanup timed out after 10 seconds. Forcing exit...'));
@@ -245,17 +250,17 @@ process.on('SIGTERM', async () => {
   }, 10000);
 
   try {
-    console.log(chalk.cyan('SIGTERM handler: Attempting embeddingsSystem.cleanup()...'));
+    diagnosticLog(chalk.cyan('SIGTERM handler: Attempting embeddingsSystem.cleanup()...'));
     await embeddingsSystem.cleanup();
-    console.log(chalk.green('embeddingsSystem.cleanup() completed.'));
+    diagnosticLog(chalk.green('embeddingsSystem.cleanup() completed.'));
     clearTimeout(forceExitTimeout); // Cleanup finished, clear the timeout
-    console.log(chalk.cyan('SIGTERM handler: Exiting normally (code 0).'));
+    diagnosticLog(chalk.cyan('SIGTERM handler: Exiting normally (code 0).'));
     process.exit(0); // Exit normally
   }
   catch (err) {
     console.error(chalk.red('Error during embeddingsSystem.cleanup():'), err.message);
     clearTimeout(forceExitTimeout);
-    console.log(chalk.cyan('SIGTERM handler: Exiting after error (code 1).'));
+    diagnosticLog(chalk.cyan('SIGTERM handler: Exiting after error (code 1).'));
     process.exit(1); // Exit with error code
   }
 });
@@ -263,7 +268,7 @@ process.on('SIGTERM', async () => {
 // Ensure cleanup on normal exit
 process.on('exit', () => {
   // Note: Async cleanup might not fully complete here
-  console.log(chalk.cyan('Exiting...'));
+  diagnosticLog(chalk.cyan('Exiting...'));
 });
 
 // REMOVED: Old options processing logic for ignore/severity
@@ -273,6 +278,7 @@ process.on('exit', () => {
 
 // Main function to run the code review (Refactored to use cag-review.js)
 async function runCodeReview(options) {
+  configureCleanStdoutForDataOutput(options);
   let reviewTask = null;
   let operationDescription = '';
   const startTime = Date.now();
@@ -281,7 +287,7 @@ async function runCodeReview(options) {
   // If --directory is specified, use that as the project directory
   // Otherwise, use the current working directory
   const projectPath = options.directory ? path.resolve(options.directory) : process.cwd();
-  console.log(chalk.gray(`Using project path for analysis: ${projectPath}`));
+  diagnosticLog(chalk.gray(`Using project path for analysis: ${projectPath}`));
 
   // Parse custom documents
   const customDocs = [];
@@ -322,12 +328,12 @@ async function runCodeReview(options) {
         .trim(); // Remove leading/trailing whitespace
 
       customDocs.push({ title, content });
-      console.log(chalk.gray(`Loaded custom document '${title}' from ${filePath} (${content.length} chars)`));
+      diagnosticLog(chalk.gray(`Loaded custom document '${title}' from ${filePath} (${content.length} chars)`));
 
       // Debug: Show a clean preview of the content
       const previewLength = 200;
       const preview = content.substring(0, previewLength).replace(/\n/g, '\\n');
-      console.log(chalk.gray(`  Content preview: ${preview}${content.length > previewLength ? '...' : ''}`));
+      diagnosticLog(chalk.gray(`  Content preview: ${preview}${content.length > previewLength ? '...' : ''}`));
     }
   }
 
@@ -352,24 +358,29 @@ async function runCodeReview(options) {
   };
 
   try {
-    console.log(chalk.bold.blue('AI Code Review (RAG Approach) - Starting analysis...'));
+    diagnosticLog(chalk.bold.blue('AI Code Review (RAG Approach) - Starting analysis...'));
 
     // Determine the review mode based on options
-    // Only support: single file, specific files, or diff with branch
+    // Only support: single file, specific files, or target-branch diff review
     if (options.diffWith) {
+      const targetBranch = options.diffWith;
       // Use directory option as working directory for git commands if specified
       const gitWorkingDir = options.directory ? path.resolve(options.directory) : process.cwd();
-      const changedFiles = getChangedFiles(options.diffWith, gitWorkingDir);
+      const { changedFiles, baseBranch } = getChangedFiles(targetBranch, gitWorkingDir, options.base);
       if (changedFiles.length === 0) {
-        console.log(chalk.yellow(`No changed files found compared to branch '${options.diffWith}'. Exiting.`));
+        const message = `No changed files found in target branch '${targetBranch}' compared to its detected parent branch. Exiting.`;
+        diagnosticLog(chalk.yellow(message));
+        await emitEmptyReviewOutputIfNeeded(options, { success: true, results: [], message });
         return;
       }
-      operationDescription = `${changedFiles.length} files changed vs ${options.diffWith}`;
-      // Add the actual branch name to reviewOptions
+      operationDescription = `${changedFiles.length} files changed in target branch ${targetBranch}`;
+      // Add the actual branch name to reviewOptions. Pass the already-detected
+      // parent branch so the review pipeline doesn't re-run parent detection.
       const enhancedReviewOptions = {
         ...reviewOptions,
-        actualBranch: options.diffWith,
-        diffWith: options.diffWith,
+        actualBranch: targetBranch,
+        diffWith: targetBranch,
+        baseBranch,
       };
       reviewTask = reviewPullRequest(changedFiles, enhancedReviewOptions);
     }
@@ -383,7 +394,9 @@ async function runCodeReview(options) {
     else if (options.files && options.files.length > 0) {
       const filesToAnalyze = await expandFilePatterns(options.files);
       if (filesToAnalyze.length === 0) {
-        console.log(chalk.yellow('No files found matching the specified patterns. Exiting.'));
+        const message = 'No files found matching the specified patterns. Exiting.';
+        diagnosticLog(chalk.yellow(message));
+        await emitEmptyReviewOutputIfNeeded(options, { success: true, results: [], message });
         return;
       }
       operationDescription = `${filesToAnalyze.length} specific files/patterns`;
@@ -394,7 +407,7 @@ async function runCodeReview(options) {
       console.error(chalk.red('Error: You must specify one of the following:'));
       console.error(chalk.yellow('  --file <file>                    Analyze a single file'));
       console.error(chalk.yellow('  --files <files...>               Analyze specific files or glob patterns'));
-      console.error(chalk.yellow('  -b, --diff-with <branch>         Analyze files changed in a branch'));
+      console.error(chalk.yellow('  -b, --diff-with <branch>         Review a target branch against its auto-detected parent branch'));
       console.error(chalk.gray('\nOptional:'));
       console.error(chalk.gray('  -d, --directory <dir>            Working directory (for git operations with --diff-with)'));
       console.error(chalk.gray('\nExamples:'));
@@ -408,7 +421,7 @@ async function runCodeReview(options) {
       process.exit(1);
     }
 
-    console.log(chalk.cyan(`Starting review for ${operationDescription}...`));
+    diagnosticLog(chalk.cyan(`Starting review for ${operationDescription}...`));
 
     // Execute the selected review task
     const reviewResult = await reviewTask;
@@ -421,60 +434,77 @@ async function runCodeReview(options) {
     // Process and output results
     if (reviewResult && reviewResult.success) {
       if (reviewResult.results && reviewResult.results.length > 0) {
-        console.log(chalk.green(`Found ${reviewResult.results.length} result items to display`));
-        // Determine output function based on format option
-        const outputFn = options.output === 'json' ? outputJson : options.output === 'markdown' ? outputMarkdown : outputText;
-        // Pass the detailed results array to the output function
-        outputFn(reviewResult.results, options, reviewResult);
-        console.log(chalk.bold.green(`\nAnalysis complete for ${operationDescription}! (${duration}s)`));
+        diagnosticLog(chalk.green(`Found ${reviewResult.results.length} result items to display`));
+        await outputReviewResults(reviewResult.results, options, reviewResult);
+        diagnosticLog(chalk.bold.green(`\nAnalysis complete for ${operationDescription}! (${duration}s)`));
       }
       else {
         // No results to display (e.g., all files were excluded/skipped)
         const message = reviewResult.message || 'All files were excluded from review (e.g., config files, lock files).';
-        console.log(chalk.yellow(message));
+        diagnosticLog(chalk.yellow(message));
 
-        // Still output empty results if outputFile is specified (for CI/CD pipelines)
-        if (options.outputFile) {
-          const outputFn = options.output === 'json' ? outputJson : options.output === 'markdown' ? outputMarkdown : outputText;
-          outputFn([], options, reviewResult);
-          console.log(chalk.yellow(`Empty results written to: ${options.outputFile}`));
+        if (await emitEmptyReviewOutputIfNeeded(options, reviewResult)) {
+          if (options.outputFile) {
+            diagnosticLog(chalk.yellow(`Empty results written to: ${options.outputFile}`));
+          }
         }
 
-        console.log(chalk.bold.yellow(`\nReview complete for ${operationDescription} - no reviewable files found (${duration}s)`));
+        diagnosticLog(chalk.bold.yellow(`\nReview complete for ${operationDescription} - no reviewable files found (${duration}s)`));
       }
     }
     else {
+      const error = reviewResult?.error || 'Code review process failed.';
       console.error(chalk.red('\nCode review process failed.'));
-      if (reviewResult && reviewResult.error) {
-        console.error(chalk.red(`Error: ${reviewResult.error}`));
+      console.error(chalk.red(`Error: ${error}`));
+
+      if (await emitErrorReviewOutputIfNeeded(options, error, reviewResult || {})) {
+        if (options.outputFile) {
+          diagnosticLog(chalk.yellow(`Error results written to: ${options.outputFile}`));
+        }
       }
+      // AI review output is advisory; report review-task failures without failing CI.
     }
 
     // Clean up resources
-    console.log(chalk.cyan('Cleaning up resources...'));
+    diagnosticLog(chalk.cyan('Cleaning up resources...'));
     try {
       await embeddingsSystem.cleanup();
       await cleanupClassifier();
-      console.log(chalk.green('All resources cleaned up successfully'));
+      diagnosticLog(chalk.green('All resources cleaned up successfully'));
     }
     catch (cleanupErr) {
       console.error(chalk.yellow('Error during cleanup:'), cleanupErr.message);
-      process.exit(1);
+      process.exitCode = 1;
+      return;
     }
   }
   catch (err) {
-    console.error(chalk.red(`\nError during code review (${operationDescription}):`), err.message);
-    console.error(err.stack);
+    if (!isBrokenStdoutPipeError(err)) {
+      console.error(chalk.red(`\nError during code review (${operationDescription}):`), err.message);
+      if (shouldPrintErrorStack(options, err)) {
+        console.error(err.stack);
+      }
+    }
+
+    try {
+      await emitErrorReviewOutputIfNeeded(options, err.message, { success: false, error: err.message });
+    }
+    catch (outputErr) {
+      if (!isBrokenStdoutPipeError(outputErr)) {
+        console.error(chalk.red('Error writing review error output:'), outputErr.message);
+      }
+    }
+
     // Clean up resources even on error
     try {
       await embeddingsSystem.cleanup();
       await cleanupClassifier();
-      console.log(chalk.green('All resources cleaned up successfully'));
+      diagnosticLog(chalk.green('All resources cleaned up successfully'));
     }
     catch (cleanupErr) {
       console.error(chalk.red('Error during cleanup:'), cleanupErr.message);
     }
-    process.exit(1);
+    process.exitCode = 1;
   }
 }
 
@@ -950,24 +980,36 @@ async function expandFilePatterns(patterns, baseDir = process.cwd()) {
 }
 
 /**
- * Get list of files changed in a branch compared to the base branch (main/master).
- * This shows what changes the specified branch has compared to the base.
+ * Get list of files changed in the target branch compared to its base branch.
+ * The supplied branch is the branch being reviewed, not the base branch.
+ *
+ * When `explicitBase` is given (e.g. the authoritative PR base ref in CI) it is
+ * used directly. Otherwise the parent is auto-detected (see findParentBranch),
+ * so stacked PRs are diffed against the branch they were forked from rather than
+ * always against main/master/develop.
  *
- * @param {string} branch - Branch to analyze (the feature/target branch)
+ * @param {string} targetBranch - Branch to analyze (the feature/target branch)
  * @param {string} workingDir - Directory to run git commands in (optional, defaults to cwd)
- * @returns {Array<string>} Array of changed file paths relative to git root
+ * @param {string} [explicitBase] - Base branch to diff against, overriding auto-detection
+ * @returns {{ changedFiles: Array<string>, baseBranch: string|null }} Changed file paths
+ *   (absolute) and the base branch they were diffed against (null on error).
  */
-function getChangedFiles(branch, workingDir = process.cwd()) {
+function getChangedFiles(targetBranch, workingDir = process.cwd(), explicitBase = undefined) {
   try {
     // Get git root directory
     const gitRoot = execSync('git rev-parse --show-toplevel', { cwd: workingDir }).toString().trim();
-    console.log(chalk.gray(`Git repository: ${gitRoot}`));
+    diagnosticLog(chalk.gray(`Git repository: ${gitRoot}`));
 
-    // Ensure the branch exists locally (fetch if needed)
-    ensureBranchExists(branch, workingDir);
+    // Ensure the target branch exists locally (fetch if needed)
+    ensureBranchExists(targetBranch, workingDir);
 
-    // Find the base branch (main/master)
-    const baseBranch = findBaseBranch(workingDir);
+    // Use the explicitly provided base (authoritative, e.g. the PR base ref in CI)
+    // when given; otherwise detect the parent branch the target was forked from
+    // (main/master/develop, or another feature branch in stacked-PR workflows).
+    const baseBranch = explicitBase || findParentBranch(targetBranch, workingDir);
+    if (explicitBase) {
+      diagnosticLog(chalk.gray(`Using explicit base branch '${baseBranch}' (auto-detection skipped)`));
+    }
 
     // Ensure the base branch exists locally as well (crucial for diff operations)
     try {
@@ -978,12 +1020,13 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
       // Continue with the original baseBranch name, it might work with remote refs
     }
 
-    console.log(chalk.gray(`Comparing ${branch} against ${baseBranch}...`));
+    diagnosticLog(chalk.gray(`Reviewing target branch '${targetBranch}' against base branch '${baseBranch}'...`));
 
-    // Use three-dot notation to get changes in branch compared to base
-    // This shows commits that are in 'branch' but not in 'baseBranch'
+    // Use three-dot notation to get changes in the target branch compared to the base.
     // By adding --diff-filter=d, we exclude deleted files from the list.
-    const gitOutput = execGitSafe('git diff', ['--name-only', '--diff-filter=d', `${baseBranch}...${branch}`], { cwd: gitRoot }).toString();
+    const gitOutput = execGitSafe('git diff', ['--name-only', '--diff-filter=d', `${baseBranch}...${targetBranch}`], {
+      cwd: gitRoot,
+    }).toString();
 
     // Split, filter empty lines, resolve paths, and check existence
     const changedFiles = gitOutput
@@ -992,14 +1035,14 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
       .map((file) => path.resolve(gitRoot, file)); // Get absolute path
 
     if (changedFiles.length > 0) {
-      console.log(chalk.gray(`Found ${changedFiles.length} changed files in ${branch} vs ${baseBranch}`));
+      diagnosticLog(chalk.gray(`Found ${changedFiles.length} changed files in target branch '${targetBranch}' vs base '${baseBranch}'`));
     }
 
-    return changedFiles;
+    return { changedFiles, baseBranch };
   }
   catch (err) {
     console.error(chalk.red('Error getting git diff:'), err.message);
-    return [];
+    return { changedFiles: [], baseBranch: null };
   }
 }
 
@@ -1009,6 +1052,58 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
 // --- Output Formatting Functions --- //
 // These consume the normalized results returned by the RAG review pipeline
 
+function getReviewOutputFunction(outputFormat) {
+  if (outputFormat === 'json') {
+    return outputJson;
+  }
+  if (outputFormat === 'markdown') {
+    return outputMarkdown;
+  }
+  return outputText;
+}
+
+function shouldEmitReviewOutput(options = {}) {
+  return Boolean(options.outputFile || options.output === 'json' || options.output === 'markdown');
+}
+
+function shouldPrintErrorStack(options, error) {
+  return Boolean(error?.stack && (isVerboseEnabled(options) || isDebugEnabled()));
+}
+
+async function outputReviewResults(reviewResults, options, aggregateResult = {}) {
+  await getReviewOutputFunction(options.output)(reviewResults, options, aggregateResult);
+}
+
+async function emitEmptyReviewOutputIfNeeded(options, aggregateResult = {}) {
+  if (!shouldEmitReviewOutput(options)) {
+    return false;
+  }
+
+  await outputReviewResults([], options, aggregateResult);
+  return true;
+}
+
+async function emitErrorReviewOutputIfNeeded(options, error, aggregateResult = {}) {
+  if (!shouldEmitReviewOutput(options)) {
+    return false;
+  }
+
+  await outputReviewResults([createReviewErrorResult(error)], options, {
+    ...aggregateResult,
+    success: false,
+    error,
+  });
+  return true;
+}
+
+function createReviewErrorResult(error) {
+  return {
+    filePath: 'review',
+    success: false,
+    error,
+  };
+}
+
 /**
  * Output results in JSON format
  *
@@ -1016,7 +1111,7 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
  * @param {Object} options - Command line options
  * @param {Object} aggregateResult - Full review result with PR-level context
  */
-function outputJson(reviewResults, options, aggregateResult = {}) {
+async function outputJson(reviewResults, options, aggregateResult = {}) {
   const prLevelFindings = collectPRLevelFindings(reviewResults, aggregateResult);
   const fileLevelIssues = getFileLevelIssueCount(reviewResults);
 
@@ -1069,7 +1164,7 @@ function outputJson(reviewResults, options, aggregateResult = {}) {
   }
   else {
     // Write JSON output to stdout (process.stdout is not buffered)
-    process.stdout.write(jsonOutput);
+    await writeStdout(jsonOutput);
   }
 }
 
@@ -1080,7 +1175,7 @@ function outputJson(reviewResults, options, aggregateResult = {}) {
  * @param {Object} options - Command line options
  * @param {Object} aggregateResult - Full review result with PR-level context
  */
-function outputMarkdown(reviewResults, options, aggregateResult = {}) {
+async function outputMarkdown(reviewResults, options, aggregateResult = {}) {
   const totalFiles = reviewResults.length;
   const filesWithIssues = reviewResults.filter((r) => r.success && !r.skipped && r.results?.issues?.length > 0).length;
   const skippedFiles = reviewResults.filter((r) => r.skipped).length;
@@ -1164,7 +1259,7 @@ function outputMarkdown(reviewResults, options, aggregateResult = {}) {
     return;
   }
 
-  process.stdout.write(markdownOutput);
+  await writeStdout(markdownOutput);
 }
 
 /**

package/src/llm.js

@@ -18,7 +18,7 @@ import dotenv from 'dotenv';
 import { verboseLog } from './utils/logging.js';
 
 // Load env variables if present; do not enforce key at import time
-dotenv.config();
+dotenv.config({ quiet: true });
 
 let anthropic = null;
 

package/src/rag-review.js

@@ -10,7 +10,7 @@ import path from 'path';
 import chalk from 'chalk';
 import { runAnalysis, gatherUnifiedContextForPR } from './rag-analyzer.js';
 import { shouldProcessFile } from './utils/file-validation.js';
-import { findBaseBranch, getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
+import { ensureBranchExists, findParentBranch, getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
 import { detectFileType, detectLanguageFromExtension } from './utils/language-detection.js';
 import { verboseLog } from './utils/logging.js';
 import { shouldChunkPR, chunkPRFiles, combineChunkResults } from './utils/pr-chunking.js';
@@ -209,8 +209,9 @@ async function reviewPullRequest(changedFilePaths, options = {}) {
  * @param {boolean} [options.verbose=false] - Enable verbose progress logging
  * @param {number} [options.concurrency=3] - Maximum number of fallback per-file reviews to run in parallel
  * @param {string} [options.directory] - Working directory for git operations
- * @param {string} [options.diffWith='HEAD'] - Branch or ref to compare against
+ * @param {string} [options.diffWith='HEAD'] - Target branch or ref being reviewed against the detected base branch
  * @param {string} [options.actualBranch] - Actual target branch used for content retrieval
+ * @param {string} [options.baseBranch] - Pre-detected parent/base branch to diff against; detected here if omitted
  * @param {boolean} [options.skipChunking=false] - Skip PR chunking, used internally for chunk review recursion
  * @returns {Promise<Object>} Aggregated review results
  */
@@ -221,12 +222,27 @@ async function reviewPullRequestWithCrossFileContext(filesToReview, options = {}
 
     // Step 1: Get the base branch and collect diff info for all files in the PR
     const workingDir = options.directory ? path.resolve(options.directory) : process.cwd();
-    const baseBranch = findBaseBranch(workingDir);
     const targetBranch = options.diffWith || 'HEAD'; // The feature branch being reviewed
 
     // Get the actual branch name from options passed from index.js
     const actualTargetBranch = options.actualBranch || targetBranch;
 
+    // Prefer the parent branch already detected (and materialized locally) by the
+    // caller to avoid re-running the O(branches) detection. Only detect here when
+    // this function is invoked directly without a pre-detected base.
+    let baseBranch = options.baseBranch;
+    if (!baseBranch) {
+      baseBranch = findParentBranch(actualTargetBranch, workingDir);
+      // Detection may return a branch that exists only on the remote; ensure it
+      // resolves locally before it is used for diffing.
+      try {
+        ensureBranchExists(baseBranch, workingDir);
+      }
+      catch (error) {
+        verboseLog(verbose, chalk.yellow(`Could not ensure base branch '${baseBranch}' exists locally: ${error.message}`));
+      }
+    }
+
     verboseLog(verbose, chalk.gray(`Base branch: ${baseBranch}, Target branch: ${targetBranch}`));
 
     const prFiles = [];
@@ -319,7 +335,9 @@ async function reviewPullRequestWithCrossFileContext(filesToReview, options = {}
     verboseLog(
       verbose,
       chalk.green(
-        `De-duplicated context: ${deduplicatedCodeExamples.length} code examples, ${deduplicatedGuidelines.length} guidelines, ${deduplicatedPRComments.length} PR comments, ${deduplicatedCustomDocChunks.length} custom doc chunks`
+        `De-duplicated context: ${deduplicatedCodeExamples.length} code examples, ${deduplicatedGuidelines.length} guidelines, ${
+          deduplicatedPRComments.length
+        } PR comments, ${deduplicatedCustomDocChunks.length} custom doc chunks`
       )
     );
 

package/src/rag-review.test.js

@@ -1,7 +1,7 @@
 import { runAnalysis, gatherUnifiedContextForPR } from './rag-analyzer.js';
 import { reviewFile, reviewFiles, reviewPullRequest } from './rag-review.js';
 import { shouldProcessFile } from './utils/file-validation.js';
-import { getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
+import { ensureBranchExists, findParentBranch, getChangedLinesInfo, getFileContentFromGit } from './utils/git.js';
 import { shouldChunkPR, chunkPRFiles, combineChunkResults } from './utils/pr-chunking.js';
 
 vi.mock('./rag-analyzer.js', () => ({
@@ -19,7 +19,8 @@ vi.mock('./utils/file-validation.js', () => ({
 }));
 
 vi.mock('./utils/git.js', () => ({
-  findBaseBranch: vi.fn().mockReturnValue('main'),
+  ensureBranchExists: vi.fn(),
+  findParentBranch: vi.fn().mockReturnValue('main'),
   getChangedLinesInfo: vi.fn().mockReturnValue({
     hasChanges: true,
     addedLines: [1, 2, 3],
@@ -210,6 +211,38 @@ describe('rag-review', () => {
       expect(result.results).toEqual([]);
     });
 
+    it('should use a pre-detected baseBranch without re-running parent detection', async () => {
+      findParentBranch.mockClear();
+      getChangedLinesInfo.mockClear();
+      runAnalysis.mockResolvedValue({
+        success: true,
+        results: { issues: [], crossFileIssues: [], summary: 'OK' },
+      });
+
+      await reviewPullRequest(['/src/file.js'], { actualBranch: 'feature-B', baseBranch: 'feature-A' });
+
+      // Detection is skipped when the caller supplies the base branch...
+      expect(findParentBranch).not.toHaveBeenCalled();
+      // ...and the supplied base is what the per-file diff is computed against.
+      expect(getChangedLinesInfo).toHaveBeenCalledWith('/src/file.js', 'feature-A', 'feature-B', expect.any(String));
+    });
+
+    it('should detect and ensure the parent branch when none is supplied', async () => {
+      findParentBranch.mockClear();
+      ensureBranchExists.mockClear();
+      findParentBranch.mockReturnValue('main');
+      runAnalysis.mockResolvedValue({
+        success: true,
+        results: { issues: [], crossFileIssues: [], summary: 'OK' },
+      });
+
+      await reviewPullRequest(['/src/file.js'], { actualBranch: 'feature-X' });
+
+      expect(findParentBranch).toHaveBeenCalledWith('feature-X', expect.any(String));
+      // A detected (possibly remote-only) base must be materialized locally before diffing.
+      expect(ensureBranchExists).toHaveBeenCalledWith('main', expect.any(String));
+    });
+
     it('should skip files based on exclusion rules', async () => {
       shouldProcessFile.mockReturnValue(false);