claude-git-hooks 2.13.0 → 2.14.4

package/CHANGELOG.md

@@ -5,6 +5,70 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.14.4] - 2026-02-06
+
+### 🔧 Changed
+- The bump-version command now uses the configured default branch (from github.pr.defaultBase) in the 'Next steps' output instead of hardcoded 'main'
+
+
+## [2.14.3] - 2026-02-06
+
+
+## [2.14.2] - 2026-02-06
+
+### ✨ Added
+- New `--push` flag for `bump-version` command to explicitly push tags to remote when desired
+
+### 🔧 Changed
+- Changed `bump-version` default behavior to keep tags local instead of automatically pushing to remote (#65)
+- Tags are now pushed by `create-pr` command or manually with `--push` flag, providing better control over the release workflow
+- Updated documentation in README.md, README-NPM.md, and CLAUDE.md to reflect new tag push behavior
+
+### ⚠️ Deprecated
+- The `--no-push` flag for `bump-version` is no longer needed as tags now stay local by default
+
+### 🗑️ Removed
+- Removed RFC-001 documentation file (pr-metadata-engine-refactor.md) as the refactor has been completed
+
+
+## [2.14.1] - 2026-02-06
+
+### 🔧 Changed
+- Improved `bump-version` command workflow - now automatically stages and commits version changes with conventional commit format before tag creation
+- Enhanced `bump-version` command flexibility - added `--no-commit` flag for manual workflows where users prefer to commit changes themselves
+- Improved error handling in `bump-version` - provides clearer guidance when staging or committing fails, with manual fallback instructions
+- Enhanced next-steps guidance in `bump-version` output - adapts instructions based on flags used (--no-commit, --no-push, --no-tag)
+
+### 🐛 Fixed
+- Fixed `bump-version` workflow inconsistency - prevented tag creation when using `--no-commit` flag, as tags should only be created after changes are committed
+- Fixed potential git history issues - version bump commits now use `--no-verify` flag to bypass pre-commit hooks and prevent circular execution
+
+### 🗑️ Removed
+- Removed redundant fallback warnings from `analyze-diff` and `create-pr` commands - warnings were unnecessary as base branch resolution now throws clear errors with suggestions instead
+
+
+## [2.14.0] - 2026-02-06
+
+### ✨ Added
+- PR metadata engine (`pr-metadata-engine.js`) - centralized module for generating PR titles, descriptions, and test plans from branch diffs with timeout resilience (#63)
+- Tiered diff reduction system - automatically truncates large diffs using context reduction, proportional budgets, and stat-only summaries to prevent timeouts
+- Extended git operations - added `fetchRemote()`, `branchExists()`, `resolveBaseBranch()`, `getChangedFilesBetweenRefs()`, `getDiffBetweenRefs()`, and `getCommitsBetweenRefs()` to `git-operations.js`
+- RFC-001 documentation - comprehensive design specification for PR metadata engine refactor with timeout resilience strategy
+
+### 🔧 Changed
+- Refactored `analyze-diff` command to use shared PR metadata engine - reduced from 262 to ~80 lines by eliminating duplicate git logic
+- Refactored `create-pr` command to use shared PR metadata engine - eliminated duplicate diff extraction logic (lines 340-420)
+- Improved timeout error handling - timeout errors now include `errorInfo` and are classified as recoverable for automatic retry with exponential backoff
+- Updated CLAUDE.md with PR metadata engine architecture, new git operations exports, and tiered diff reduction strategy
+
+### 🐛 Fixed
+- Fixed timeout failures in `analyze-diff` for large diffs - now uses tiered reduction instead of monolithic diff processing
+- Fixed inconsistent behavior between `analyze-diff` and `create-pr` commands - both now share identical analysis logic via unified engine
+
+### 🗑️ Removed
+- Removed unreliable `SUBAGENT_INSTRUCTION` text hint - replaced with deterministic tiered diff reduction for parallel processing
+
+
 ## [2.13.0] - 2026-02-05
 
 ### ✨ Added

package/README.md

@@ -110,14 +110,21 @@ claude-hooks bump-version major --update-changelog
 
 # Preview without applying
 claude-hooks bump-version patch --dry-run
+
+# Push tag immediately (otherwise pushed by create-pr)
+claude-hooks bump-version patch --push
+
+# Manual workflow (skip automatic commit)
+claude-hooks bump-version patch --no-commit
 ```
 
 **What it does:**
 - Detects project type (Node.js, Maven, or monorepo with both)
 - Updates `package.json` and/or `pom.xml`
 - Generates CHANGELOG entry with Claude (analyzes commits)
+- Commits changes automatically with conventional commit format
 - Creates annotated Git tag with `v` prefix (e.g., `v2.7.0`)
-- Pushes tag to remote automatically
+- Tags stay local by default (use `--push` to push immediately, or let `create-pr` handle it)
 
 **Version workflow:**
 ```
@@ -253,7 +260,8 @@ claude-hooks --help   # Full command reference
 | `analysis-engine.js` | **Shared analysis logic** - file data, orchestration, results (v2.13.0) | `buildFilesData()`, `runAnalysis()`, `consolidateResults()`, `displayResults()` |
 | `claude-client.js` | **Claude CLI wrapper** - spawn, retry, parallel execution | `analyzeCode()`, `analyzeCodeParallel()`, `executeClaudeWithRetry()` |
 | `prompt-builder.js` | **Prompt construction** - load templates, replace variables | `buildAnalysisPrompt()`, `loadPrompt()` |
-| `git-operations.js` | **Git abstractions** - staged files, diff, repo root | `getStagedFiles()`, `getDiff()`, `getRepoRoot()` |
+| `git-operations.js` | **Git abstractions** - staged files, diff, branch comparison | `getStagedFiles()`, `getDiff()`, `getRepoRoot()`, `resolveBaseBranch()`, `getDiffBetweenRefs()` |
+| `pr-metadata-engine.js` | **PR metadata generation** - branch context, diff reduction (v2.14.0) | `getBranchContext()`, `buildDiffPayload()`, `generatePRMetadata()`, `analyzeBranchForPR()` |
 | `github-api.js` | **Octokit integration** - PR creation, token validation | `createPullRequest()`, `validateToken()`, `saveGitHubToken()` |
 | `github-client.js` | **GitHub helpers** - CODEOWNERS parsing, reviewers | `getReviewersForFiles()`, `parseGitHubRepo()` |
 | `preset-loader.js` | **Preset system** - load tech-stack configurations | `loadPreset()`, `listPresets()` |
@@ -290,16 +298,18 @@ git commit -m "auto" → templates/prepare-commit-msg (bash wrapper)
   → write to COMMIT_EDITMSG
 ```
 
-#### PR Creation
+#### PR Metadata Generation (analyze-diff / create-pr)
 
 ```
-claude-hooks create-pr → bin/claude-hooks (router)
-  → lib/commands/create-pr.js
-  → validateToken() (github-api.js)
-  → parseGitHubRepo() (github-client.js)
-  → getReviewersForFiles() (CODEOWNERS + config)
-  → executeClaudeWithRetry() (metadata generation)
-  → createPullRequest() (Octokit API)
+claude-hooks analyze-diff|create-pr → bin/claude-hooks (router)
+  → lib/commands/analyze-diff.js or create-pr.js (thin wrapper)
+  → analyzeBranchForPR() (pr-metadata-engine.js)
+    → resolveBaseBranch() (git-operations.js)
+    → getDiffBetweenRefs() + getCommitsBetweenRefs()
+    → buildDiffPayload() with tiered reduction (context → proportional → stat-only)
+    → executeClaudeWithRetry() → PRMetadata
+  → analyze-diff: formats to console + saves JSON
+  → create-pr: additionally creates PR via Octokit API
 ```
 
 ### Config Priority

package/lib/commands/analyze-diff.js

@@ -3,15 +3,13 @@
  * Purpose: Analyze differences between branches and generate PR info
  */
 
-import { execSync } from 'child_process';
 import fs from 'fs';
-import { executeClaudeWithRetry, extractJSON } from '../utils/claude-client.js';
-import { loadPrompt } from '../utils/prompt-builder.js';
+import { analyzeBranchForPR } from '../utils/pr-metadata-engine.js';
 import { getConfig } from '../config.js';
+import logger from '../utils/logger.js';
 import {
     colors,
     error,
-    success,
     info,
     warning,
     checkGitRepo
@@ -27,156 +25,38 @@ export async function runAnalyzeDiff(args) {
         return;
     }
 
-    // Load configuration
+    // Enable debug mode from config
     const config = await getConfig();
-
-    const currentBranch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
-
-    if (!currentBranch) {
-        error('You are not in a valid branch.');
-        return;
+    if (config.system?.debug) {
+        logger.setDebugMode(true);
     }
 
-    // Update remote references
-    execSync('git fetch', { stdio: 'ignore' });
-
-    let baseBranch, compareWith, contextDescription;
-
-    if (args[0]) {
-        // Case with argument: compare current branch vs origin/specified-branch
-        const targetBranch = args[0];
-        baseBranch = `origin/${targetBranch}`;
-        compareWith = `${baseBranch}...HEAD`;
-        contextDescription = `${currentBranch} vs ${baseBranch}`;
-
-        // Check that the origin branch exists
-        try {
-            execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-        } catch (e) {
-            error(`Branch ${baseBranch} does not exist.`);
-            return;
-        }
-    } else {
-        // Case without argument: compare current branch vs origin/current-branch
-        baseBranch = `origin/${currentBranch}`;
-        compareWith = `${baseBranch}...HEAD`;
-        contextDescription = `${currentBranch} vs ${baseBranch}`;
-
-        // Check that the origin branch exists
-        try {
-            execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-        } catch (e) {
-            // Try fallback to origin/develop
-            baseBranch = 'origin/develop';
-            compareWith = `${baseBranch}...HEAD`;
-            contextDescription = `${currentBranch} vs ${baseBranch} (fallback)`;
-
-            try {
-                execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-                warning(`Branch origin/${currentBranch} does not exist. Using ${baseBranch} as fallback.`);
-            } catch (e2) {
-                // Try fallback to origin/main
-                baseBranch = 'origin/main';
-                compareWith = `${baseBranch}...HEAD`;
-                contextDescription = `${currentBranch} vs ${baseBranch} (fallback)`;
+    // Parse target branch from arguments
+    const targetBranch = args[0];
 
-                try {
-                    execSync(`git rev-parse --verify ${baseBranch}`, { stdio: 'ignore' });
-                    warning(`No origin/develop branch. Using ${baseBranch} as fallback.`);
-                } catch (e3) {
-                    error('Could not find a valid comparison branch (tried origin/current, origin/develop, origin/main).');
-                    return;
-                }
-            }
-        }
-    }
-
-    info(`Analyzing: ${contextDescription}...`);
+    info(targetBranch ? `Analyzing differences with ${targetBranch}...` : 'Analyzing differences...');
+    const startTime = Date.now();
 
-    // Get modified files
-    let diffFiles;
     try {
-        diffFiles = execSync(`git diff ${compareWith} --name-only`, { encoding: 'utf8' }).trim();
-
-        if (!diffFiles) {
-            // Check if there are staged or unstaged changes
-            const stagedFiles = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim();
-            const unstagedFiles = execSync('git diff --name-only', { encoding: 'utf8' }).trim();
+        // Call PR metadata engine
+        const { success: engineSuccess, result, error: engineError } = await analyzeBranchForPR(targetBranch, {
+            hook: 'analyze-diff'
+        });
 
-            if (stagedFiles || unstagedFiles) {
-                warning('No differences with remote, but you have uncommitted local changes.');
-                console.log('Staged changes:', stagedFiles || 'none');
-                console.log('Unstaged changes:', unstagedFiles || 'none');
-            } else {
-                success('✅ No differences. Your branch is synchronized.');
-            }
+        if (!engineSuccess) {
+            error(engineError || 'Failed to analyze branch');
             return;
         }
-    } catch (e) {
-        error('Error getting differences: ' + e.message);
-        return;
-    }
-
-    // Get the complete diff
-    let fullDiff, commits;
-    try {
-        fullDiff = execSync(`git diff ${compareWith}`, { encoding: 'utf8' });
-        commits = execSync(`git log ${baseBranch}..HEAD --oneline`, { encoding: 'utf8' }).trim();
-    } catch (e) {
-        error('Error getting diff or commits: ' + e.message);
-        return;
-    }
-
-    // Check if subagents should be used
-    const useSubagents = config.subagents.enabled;
-    const subagentModel = config.subagents.model;
-    let subagentBatchSize = config.subagents.batchSize;
-    // Validate batch size (must be >= 1)
-    if (subagentBatchSize < 1) {
-        subagentBatchSize = 1;
-    }
-    const subagentInstruction = useSubagents
-        ? `\n\nIMPORTANT PARALLEL PROCESSING: If analyzing 3+ files, process them in batches of ${subagentBatchSize}. For EACH batch, create that many subagents in parallel using Task tool (send single message with multiple Task calls). Each subagent analyzes one file and provides insights. After ALL batches complete, consolidate into SINGLE JSON with ONE cohesive PR title/description. Model: ${subagentModel}. Example: 4 files with BATCH_SIZE=1 → 4 sequential batches of 1 subagent each. Example: 4 files with BATCH_SIZE=3 → batch 1 has 3 parallel subagents (files 1-3), batch 2 has 1 subagent (file 4).\n`
-        : '';
-
-    // Truncate full diff if too large
-    const truncatedDiff = fullDiff.length > 50000
-        ? fullDiff.substring(0, 50000) + '\n... (truncated diff)'
-        : fullDiff;
 
-    // Load prompt from template
-    const prompt = await loadPrompt('ANALYZE_DIFF.md', {
-        CONTEXT_DESCRIPTION: contextDescription,
-        SUBAGENT_INSTRUCTION: subagentInstruction,
-        COMMITS: commits,
-        DIFF_FILES: diffFiles,
-        FULL_DIFF: truncatedDiff
-    });
-
-    info('Sending to Claude for analysis...');
-    const startTime = Date.now();
-
-    // Prepare telemetry context
-    const filesChanged = diffFiles.split('\n').length;
-    const telemetryContext = {
-        fileCount: filesChanged,
-        batchSize: filesChanged,
-        totalBatches: 1,
-        model: subagentModel || 'sonnet',
-        hook: 'analyze-diff'
-    };
-
-    try {
-        // Use cross-platform executeClaudeWithRetry from claude-client.js with telemetry
-        const response = await executeClaudeWithRetry(prompt, {
-            timeout: 180000, // 3 minutes for diff analysis
-            telemetryContext
-        });
-
-        // Extract JSON from response using claude-client utility
-        const result = extractJSON(response);
+        // Log truncation details if applicable
+        if (result.context.isTruncated) {
+            logger.debug('analyze-diff', 'Diff was truncated', result.context.truncationDetails);
+        }
 
         // Show the results
+        const contextDescription = `${result.context.currentBranch} vs ${result.context.baseBranch}`;
+        const filesChanged = result.context.filesCount;
+
         console.log('');
         console.log('════════════════════════════════════════════════════════════════');
         console.log('                      DIFFERENCES ANALYSIS                      ');
@@ -215,10 +95,15 @@ export async function runAnalyzeDiff(args) {
 
         // Save the results in a file with context
         const outputData = {
-            ...result,
+            prTitle: result.prTitle,
+            prDescription: result.prDescription,
+            suggestedBranchName: result.suggestedBranchName,
+            changeType: result.changeType,
+            breakingChanges: result.breakingChanges,
+            testingNotes: result.testingNotes,
             context: {
-                currentBranch,
-                baseBranch,
+                currentBranch: result.context.currentBranch,
+                baseBranch: result.context.baseBranch,
                 contextDescription,
                 filesChanged,
                 timestamp: new Date().toISOString()
@@ -243,13 +128,7 @@ export async function runAnalyzeDiff(args) {
 
         // Contextual suggestions
         console.log('');
-        if (!args[0] && contextDescription.includes('local changes without push')) {
-            // Case of local changes without push
-            console.log(`💡 ${colors.yellow}To create new branch with these changes:${colors.reset}`);
-            console.log(`   git checkout -b ${result.suggestedBranchName}`);
-            console.log(`   git push -u origin ${result.suggestedBranchName}`);
-        } else if (currentBranch !== result.suggestedBranchName) {
-            // Normal case of comparison between branches
+        if (result.context.currentBranch !== result.suggestedBranchName) {
             console.log(`💡 ${colors.yellow}For renaming your current branch:${colors.reset}`);
             console.log(`   git branch -m ${result.suggestedBranchName}`);
         }
@@ -257,6 +136,6 @@ export async function runAnalyzeDiff(args) {
         console.log(`💡 ${colors.yellow}Tip:${colors.reset} Use this information to create your PR on GitHub.`);
 
     } catch (e) {
-        error('Error executing Claude: ' + e.message);
+        error(`Error analyzing diff: ${e.message}`);
     }
 }