codecritique 2.0.5 → 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.5",
+  "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,7 +29,7 @@ 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 { 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';
@@ -46,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)')
@@ -163,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
@@ -357,23 +361,26 @@ async function runCodeReview(options) {
     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) {
-        const message = `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);
     }
@@ -400,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:'));
@@ -973,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();
     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 {
@@ -1001,12 +1020,13 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
       // Continue with the original baseBranch name, it might work with remote refs
     }
 
-    diagnosticLog(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
@@ -1015,14 +1035,14 @@ function getChangedFiles(branch, workingDir = process.cwd()) {
       .map((file) => path.resolve(gitRoot, file)); // Get absolute path
 
     if (changedFiles.length > 0) {
-      diagnosticLog(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 };
   }
 }
 

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);