claude-git-hooks 2.13.0 → 2.14.4

package/lib/utils/pr-metadata-engine.js

@@ -0,0 +1,474 @@
+/**
+ * File: pr-metadata-engine.js
+ * Purpose: PR metadata generation engine - single source of truth for PR analysis
+ *
+ * Why this exists: Both analyze-diff and create-pr need to:
+ * - Extract branch context (diff, commits, files)
+ * - Generate PR metadata (title, description, test plan)
+ * - Handle large diffs through tiered reduction
+ *
+ * By extracting this logic, we:
+ * - Eliminate code duplication between commands
+ * - Provide output-format agnostic data
+ * - Enable timeout resilience through intelligent diff reduction
+ * - Ensure consistent behavior across commands
+ *
+ * Dependencies:
+ * - git-operations: Branch comparison, diff extraction
+ * - claude-client: Claude CLI execution with retry
+ * - prompt-builder: Template loading and variable replacement
+ * - logger: Debug and error logging
+ */
+
+import {
+    getCurrentBranch,
+    fetchRemote,
+    resolveBaseBranch,
+    getChangedFilesBetweenRefs,
+    getDiffBetweenRefs,
+    getCommitsBetweenRefs
+} from './git-operations.js';
+import { executeClaudeWithRetry, extractJSON } from './claude-client.js';
+import { loadPrompt } from './prompt-builder.js';
+import { getConfig } from '../config.js';
+import logger from './logger.js';
+
+/**
+ * @typedef {Object} BranchContext
+ * @property {string} baseBranch - e.g., 'origin/main'
+ * @property {string} headRef - e.g., 'HEAD'
+ * @property {string} currentBranch - e.g., 'feature/add-auth'
+ * @property {string[]} files - Changed file paths
+ * @property {string} diff - Full diff (possibly truncated)
+ * @property {string} commits - Commit log
+ * @property {number} filesCount
+ * @property {boolean} isTruncated - True if any tier of reduction was applied
+ * @property {{ fullDiff: number, statOnly: number, contextLines: number }} [truncationDetails] - Present when isTruncated=true
+ */
+
+/**
+ * @typedef {Object} PRMetadata
+ * @property {string} prTitle
+ * @property {string} prDescription
+ * @property {string} suggestedBranchName
+ * @property {string} changeType - feat, fix, refactor, etc.
+ * @property {boolean} breakingChanges
+ * @property {string} testingNotes
+ * @property {BranchContext} context
+ */
+
+/**
+ * Internal defaults (not documented in config.example.json)
+ * Why: Convention over configuration - sensible defaults for 95% of cases
+ */
+const DEFAULTS = {
+    timeout: 180000,                    // 3 minutes
+    maxDiffSize: 50000,                 // 50KB
+};
+
+/**
+ * Builds diff payload with tiered reduction strategy
+ * Why: Large diffs cause timeouts - reduce intelligently while preserving essential info
+ *
+ * Tiered Reduction Strategy:
+ * - Always included: file list + per-file stats (never truncated)
+ * - Tier 1: Reduce context lines from -U3 to -U1
+ * - Tier 2: Allocate proportional budget per file
+ * - Tier 3: Replace oversized files with stat-only summary
+ *
+ * @param {string} baseRef - Base reference (e.g., 'origin/main')
+ * @param {string} headRef - Head reference (e.g., 'HEAD')
+ * @param {string[]} files - Changed file paths
+ * @param {number} maxSize - Maximum diff size in bytes (default: 50KB)
+ * @returns {{ payload: string, isTruncated: boolean, truncationDetails: Object }}
+ */
+const buildDiffPayload = (baseRef, headRef, files, maxSize = DEFAULTS.maxDiffSize) => {
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'Building diff payload', {
+        baseRef,
+        headRef,
+        fileCount: files.length,
+        maxSize
+    });
+
+    // Always include file stats (never truncated)
+    const statsOutput = getDiffBetweenRefs(baseRef, headRef, { contextLines: 0 })
+        .split('\n')
+        .filter(line => line.match(/^\s*[\w/.-]+\s*\|\s*\d+\s*[+-]*$/))
+        .join('\n');
+
+    const statsSummary = `Files changed: ${files.length}\n\n${statsOutput}\n\n`;
+    const summarySize = statsSummary.length;
+
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'File stats summary created', {
+        summarySize,
+        filesCount: files.length
+    });
+
+    // Tier 1: Try with reduced context (U1)
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 1: Fetching diff with -U1 context');
+    const fullDiff = getDiffBetweenRefs(baseRef, headRef, { contextLines: 1 });
+
+    if (fullDiff.length + summarySize <= maxSize) {
+        logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 1: Diff fits within budget', {
+            diffSize: fullDiff.length,
+            totalSize: fullDiff.length + summarySize
+        });
+
+        return {
+            payload: statsSummary + fullDiff,
+            isTruncated: false,
+            truncationDetails: {
+                fullDiff: files.length,
+                statOnly: 0,
+                contextLines: 1
+            }
+        };
+    }
+
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 1: Exceeded budget, applying Tier 2', {
+        diffSize: fullDiff.length,
+        maxSize
+    });
+
+    // Tier 2: Split diff by file and allocate proportional budget
+    const diffPattern = /^diff --git a\/.+ b\/.+$/gm;
+    const fileDiffs = [];
+    let lastIndex = 0;
+    let match;
+
+    while ((match = diffPattern.exec(fullDiff)) !== null) {
+        if (lastIndex > 0) {
+            fileDiffs.push(fullDiff.substring(lastIndex, match.index));
+        }
+        lastIndex = match.index;
+    }
+    if (lastIndex > 0) {
+        fileDiffs.push(fullDiff.substring(lastIndex));
+    }
+
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 2: Split diff into per-file chunks', {
+        chunkCount: fileDiffs.length
+    });
+
+    const availableBudget = maxSize - summarySize;
+    const budgetPerFile = Math.floor(availableBudget / files.length);
+
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 2: Allocated per-file budget', {
+        availableBudget,
+        budgetPerFile,
+        fileCount: files.length
+    });
+
+    let finalDiff = '';
+    let fullDiffCount = 0;
+    let statOnlyCount = 0;
+    const oversizedFiles = [];
+
+    // Apply per-file budget
+    for (let i = 0; i < fileDiffs.length; i++) {
+        const fileDiff = fileDiffs[i];
+
+        if (fileDiff.length <= budgetPerFile) {
+            // File fits within budget - include full diff
+            finalDiff += fileDiff;
+            fullDiffCount++;
+        } else {
+            // File exceeds budget - mark for Tier 3
+            oversizedFiles.push({ index: i, diff: fileDiff, size: fileDiff.length });
+        }
+    }
+
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 2: Applied budget allocation', {
+        fullDiffCount,
+        oversizedCount: oversizedFiles.length
+    });
+
+    // Tier 3: Replace oversized files with stat-only summary
+    if (oversizedFiles.length > 0) {
+        logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 3: Replacing oversized files with stat-only');
+
+        for (const { diff } of oversizedFiles) {
+            // Extract file path and stats from diff header
+            const filePathMatch = diff.match(/^diff --git a\/(.+?) b\/(.+?)$/m);
+            if (filePathMatch) {
+                const filePath = filePathMatch[2];
+                // Extract stat line for this file
+                const statLine = statsOutput.split('\n').find(line => line.includes(filePath));
+                if (statLine) {
+                    finalDiff += `\n--- ${filePath} (truncated - stat only) ---\n${statLine}\n`;
+                    statOnlyCount++;
+                }
+            }
+        }
+
+        logger.debug('pr-metadata-engine - buildDiffPayload', 'Tier 3: Stat-only demotion complete', {
+            statOnlyCount
+        });
+    }
+
+    const payload = statsSummary + finalDiff;
+    const isTruncated = statOnlyCount > 0 || fullDiff.length > maxSize;
+
+    logger.debug('pr-metadata-engine - buildDiffPayload', 'Diff payload built', {
+        totalSize: payload.length,
+        isTruncated,
+        fullDiffCount,
+        statOnlyCount
+    });
+
+    return {
+        payload,
+        isTruncated,
+        truncationDetails: {
+            fullDiff: fullDiffCount,
+            statOnly: statOnlyCount,
+            contextLines: 1
+        }
+    };
+};
+
+/**
+ * Gets branch context for PR creation
+ * Why: Extracts all git information needed for PR metadata generation
+ *
+ * @param {string} [targetBranch] - Target base branch (optional)
+ * @returns {Promise<{ success: boolean, context?: BranchContext, error?: string }>}
+ */
+export const getBranchContext = async (targetBranch) => {
+    logger.debug('pr-metadata-engine - getBranchContext', 'Getting branch context', { targetBranch });
+
+    try {
+        // Get current branch
+        const currentBranch = getCurrentBranch();
+
+        if (!currentBranch || currentBranch === 'unknown') {
+            return {
+                success: false,
+                error: 'Not on a valid branch'
+            };
+        }
+
+        logger.debug('pr-metadata-engine - getBranchContext', 'Current branch identified', { currentBranch });
+
+        // Fetch remote references
+        try {
+            fetchRemote();
+            logger.debug('pr-metadata-engine - getBranchContext', 'Remote fetched successfully');
+        } catch (fetchError) {
+            logger.warning('pr-metadata-engine - getBranchContext', 'Failed to fetch remote', fetchError);
+            // Continue anyway - may work with cached remote refs
+        }
+
+        // Resolve base branch (throws with suggestions if not found)
+        const target = targetBranch || currentBranch;
+        const baseBranch = resolveBaseBranch(target);
+
+        logger.debug('pr-metadata-engine - getBranchContext', 'Base branch resolved', {
+            requestedBranch: target,
+            baseBranch
+        });
+
+        // Get changed files
+        const files = getChangedFilesBetweenRefs(baseBranch, 'HEAD');
+
+        if (files.length === 0) {
+            return {
+                success: false,
+                error: `No differences found between '${baseBranch}' and HEAD`
+            };
+        }
+
+        logger.debug('pr-metadata-engine - getBranchContext', 'Changed files retrieved', {
+            fileCount: files.length
+        });
+
+        // Get commits
+        const commits = getCommitsBetweenRefs(baseBranch, 'HEAD', { format: 'oneline' });
+
+        logger.debug('pr-metadata-engine - getBranchContext', 'Commits retrieved');
+
+        // Build diff payload with tiered reduction
+        const { payload: diff, isTruncated, truncationDetails } = buildDiffPayload(
+            baseBranch,
+            'HEAD',
+            files,
+            DEFAULTS.maxDiffSize
+        );
+
+        logger.debug('pr-metadata-engine - getBranchContext', 'Diff payload built', {
+            diffSize: diff.length,
+            isTruncated
+        });
+
+        const context = {
+            baseBranch,
+            headRef: 'HEAD',
+            currentBranch,
+            files,
+            diff,
+            commits,
+            filesCount: files.length,
+            isTruncated,
+            ...(isTruncated && { truncationDetails })
+        };
+
+        logger.debug('pr-metadata-engine - getBranchContext', 'Branch context complete', {
+            filesCount: context.filesCount,
+            isTruncated: context.isTruncated
+        });
+
+        return {
+            success: true,
+            context
+        };
+
+    } catch (error) {
+        logger.error('pr-metadata-engine - getBranchContext', 'Failed to get branch context', error);
+
+        return {
+            success: false,
+            error: error.message || 'Failed to get branch context'
+        };
+    }
+};
+
+/**
+ * Generates PR metadata from branch context
+ * Why: Sends context to Claude and parses structured PR information
+ *
+ * @param {BranchContext} context - Branch context from getBranchContext
+ * @param {Object} [options] - Generation options
+ * @param {number} [options.timeout] - Claude timeout in ms (default: 180000)
+ * @param {string} [options.hook] - Hook name for telemetry (default: 'pr-metadata')
+ * @returns {Promise<PRMetadata>}
+ * @throws {Error} If metadata generation fails
+ */
+export const generatePRMetadata = async (context, options = {}) => {
+    const config = await getConfig();
+    const configTimeout = config.analysis?.timeout;
+    const { timeout = configTimeout || DEFAULTS.timeout, hook = 'pr-metadata' } = options;
+
+    logger.debug('pr-metadata-engine - generatePRMetadata', 'Generating PR metadata', {
+        filesCount: context.filesCount,
+        timeout,
+        hook
+    });
+
+    try {
+        // Build context description for prompt
+        const contextDescription = `${context.currentBranch} vs ${context.baseBranch}`;
+
+        // Build prompt from template using existing ANALYZE_DIFF.md template
+        // Template variables match analyze-diff.js:148-154 for compatibility
+        const prompt = await loadPrompt('ANALYZE_DIFF.md', {
+            CONTEXT_DESCRIPTION: contextDescription,
+            SUBAGENT_INSTRUCTION: '', // Engine uses single Claude spawn, no subagents
+            COMMITS: context.commits,
+            DIFF_FILES: context.files.join('\n'),
+            FULL_DIFF: context.diff
+        });
+
+        logger.debug('pr-metadata-engine - generatePRMetadata', 'Prompt built', {
+            promptLength: prompt.length
+        });
+
+        // Prepare telemetry context
+        const telemetryContext = {
+            fileCount: context.filesCount,
+            batchSize: context.filesCount,
+            totalBatches: 1,
+            model: 'sonnet',
+            hook
+        };
+
+        logger.debug('pr-metadata-engine - generatePRMetadata', 'Calling Claude CLI');
+
+        // Call Claude with retry logic
+        const response = await executeClaudeWithRetry(prompt, {
+            timeout,
+            telemetryContext
+        });
+
+        logger.debug('pr-metadata-engine - generatePRMetadata', 'Claude response received', {
+            responseLength: response.length
+        });
+
+        // Parse JSON response
+        const result = extractJSON(response, telemetryContext);
+
+        logger.debug('pr-metadata-engine - generatePRMetadata', 'JSON parsed successfully', {
+            hasPrTitle: !!result.prTitle,
+            hasPrDescription: !!result.prDescription
+        });
+
+        // Return PRMetadata with context attached
+        return {
+            prTitle: result.prTitle,
+            prDescription: result.prDescription,
+            suggestedBranchName: result.suggestedBranchName,
+            changeType: result.changeType,
+            breakingChanges: result.breakingChanges || false,
+            testingNotes: result.testingNotes || '',
+            context
+        };
+
+    } catch (error) {
+        logger.error('pr-metadata-engine - generatePRMetadata', 'Failed to generate PR metadata', error);
+        throw error;
+    }
+};
+
+/**
+ * Analyzes branch for PR (convenience wrapper)
+ * Why: Single function call for complete PR analysis workflow
+ *
+ * @param {string} [targetBranch] - Target base branch (optional)
+ * @param {Object} [options] - Analysis options
+ * @param {number} [options.timeout] - Claude timeout in ms
+ * @param {string} [options.hook] - Hook name for telemetry
+ * @returns {Promise<{ success: boolean, result?: PRMetadata, error?: string }>}
+ */
+export const analyzeBranchForPR = async (targetBranch, options = {}) => {
+    logger.debug('pr-metadata-engine - analyzeBranchForPR', 'Starting PR analysis', {
+        targetBranch,
+        options
+    });
+
+    try {
+        // Step 1: Get branch context
+        const contextResult = await getBranchContext(targetBranch);
+
+        if (!contextResult.success) {
+            logger.error('pr-metadata-engine - analyzeBranchForPR', 'Failed to get branch context', {
+                error: contextResult.error
+            });
+
+            return {
+                success: false,
+                error: contextResult.error
+            };
+        }
+
+        logger.debug('pr-metadata-engine - analyzeBranchForPR', 'Branch context retrieved', {
+            filesCount: contextResult.context.filesCount
+        });
+
+        // Step 2: Generate PR metadata
+        const metadata = await generatePRMetadata(contextResult.context, options);
+
+        logger.debug('pr-metadata-engine - analyzeBranchForPR', 'PR metadata generated successfully');
+
+        return {
+            success: true,
+            result: metadata
+        };
+
+    } catch (error) {
+        logger.error('pr-metadata-engine - analyzeBranchForPR', 'PR analysis failed', error);
+
+        return {
+            success: false,
+            error: error.message || 'Failed to analyze branch for PR'
+        };
+    }
+};

package/package.json

@@ -1,60 +1,60 @@
-{
-    "name": "claude-git-hooks",
-    "version": "2.13.0",
-    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
-    "type": "module",
-    "bin": {
-        "claude-hooks": "./bin/claude-hooks"
-    },
-    "scripts": {
-        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
-        "lint": "eslint lib/ bin/",
-        "lint:fix": "eslint lib/ bin/ --fix",
-        "format": "prettier --write \"lib/**/*.js\" \"bin/**\""
-    },
-    "keywords": [
-        "git",
-        "hooks",
-        "claude",
-        "ai",
-        "code-review",
-        "commit-messages",
-        "pre-commit",
-        "automation"
-    ],
-    "author": "Pablo Rovito",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/pablorovito/claude-git-hooks.git"
-    },
-    "engines": {
-        "node": ">=16.9.0"
-    },
-    "engineStrict": false,
-    "os": [
-        "darwin",
-        "linux",
-        "win32"
-    ],
-    "preferGlobal": true,
-    "files": [
-        "bin/",
-        "lib/",
-        "templates/",
-        "README.md",
-        "CHANGELOG.md",
-        "LICENSE"
-    ],
-    "dependencies": {
-        "@octokit/rest": "^21.0.0"
-    },
-    "devDependencies": {
-        "@types/jest": "^29.5.0",
-        "eslint": "^8.57.0",
-        "jest": "^29.7.0",
-        "prettier": "^3.2.0"
-    }
-}
+{
+    "name": "claude-git-hooks",
+    "version": "2.14.4",
+    "description": "Git hooks with Claude CLI for code analysis and automatic commit messages",
+    "type": "module",
+    "bin": {
+        "claude-hooks": "./bin/claude-hooks"
+    },
+    "scripts": {
+        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+        "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+        "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+        "lint": "eslint lib/ bin/",
+        "lint:fix": "eslint lib/ bin/ --fix",
+        "format": "prettier --write \"lib/**/*.js\" \"bin/**\""
+    },
+    "keywords": [
+        "git",
+        "hooks",
+        "claude",
+        "ai",
+        "code-review",
+        "commit-messages",
+        "pre-commit",
+        "automation"
+    ],
+    "author": "Pablo Rovito",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/pablorovito/claude-git-hooks.git"
+    },
+    "engines": {
+        "node": ">=16.9.0"
+    },
+    "engineStrict": false,
+    "os": [
+        "darwin",
+        "linux",
+        "win32"
+    ],
+    "preferGlobal": true,
+    "files": [
+        "bin/",
+        "lib/",
+        "templates/",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "@octokit/rest": "^21.0.0"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.0",
+        "eslint": "^8.57.0",
+        "jest": "^29.7.0",
+        "prettier": "^3.2.0"
+    }
+}