claude-git-hooks 2.12.0 → 2.13.0

package/lib/utils/analysis-engine.js

@@ -0,0 +1,469 @@
+/**
+ * File: analysis-engine.js
+ * Purpose: Shared code analysis logic for pre-commit hook and analyze command
+ *
+ * Why this exists: Both pre-commit.js and analyze.js need to:
+ * - Build file data (diff/content) for analysis
+ * - Orchestrate parallel vs sequential analysis
+ * - Consolidate results from multiple batches
+ * - Check for blocking/non-blocking issues
+ * - Display results to user
+ *
+ * By extracting this logic, we:
+ * - Eliminate code duplication
+ * - Ensure consistent behavior
+ * - Make testing easier
+ * - Simplify maintenance
+ *
+ * Dependencies:
+ * - git-operations: File diff and content retrieval
+ * - claude-client: Claude CLI execution
+ * - prompt-builder: Analysis prompt construction
+ * - logger: Debug and error logging
+ */
+
+import fs from 'fs';
+import {
+    getFileDiff,
+    getFileContentFromStaging,
+    isNewFile,
+    getRepoName,
+    getCurrentBranch
+} from './git-operations.js';
+import { analyzeCode, analyzeCodeParallel, chunkArray } from './claude-client.js';
+import { buildAnalysisPrompt } from './prompt-builder.js';
+import logger from './logger.js';
+
+/**
+ * Standard file data schema used throughout the analysis pipeline
+ * @typedef {Object} FileData
+ * @property {string} path - File path (relative to repo root)
+ * @property {string|null} diff - Git diff content (for modified files)
+ * @property {string|null} content - Full content (for new files)
+ * @property {boolean} isNew - Whether file is newly added
+ */
+
+/**
+ * Builds file data for analysis (diff or full content)
+ * Why: Unified file data extraction used by both pre-commit and analyze command
+ *
+ * @param {string} filePath - Path to file
+ * @param {Object} options - Build options
+ * @param {boolean} options.staged - Use staged content (default: true)
+ * @returns {FileData|null} File data object or null on error
+ */
+export const buildFileData = (filePath, options = {}) => {
+    const { staged = true } = options;
+
+    try {
+        // Check if new file
+        const isNew = isNewFile(filePath);
+
+        if (isNew) {
+            // For new files, use full content
+            const content = staged
+                ? getFileContentFromStaging(filePath)
+                : fs.readFileSync(filePath, 'utf8');
+
+            return {
+                path: filePath,
+                diff: null,
+                content,
+                isNew: true
+            };
+        }
+
+        // For modified files, use diff
+        const diff = getFileDiff(filePath, { cached: staged });
+
+        return {
+            path: filePath,
+            diff,
+            content: null,
+            isNew: false
+        };
+
+    } catch (err) {
+        logger.error('analysis-engine - buildFileData', `Failed to build file data: ${filePath}`, err);
+        return null;
+    }
+};
+
+/**
+ * Builds file data for multiple files
+ * Why: Batch processing with error handling
+ *
+ * @param {Array<string|{path: string}>} files - Array of file paths or file objects
+ * @param {Object} options - Build options
+ * @param {boolean} options.staged - Use staged content (default: true)
+ * @returns {Array<FileData>} Array of file data objects (excludes failures)
+ */
+export const buildFilesData = (files, options = {}) => {
+    const results = [];
+
+    for (const file of files) {
+        // Support both string paths and objects with path property
+        const filePath = typeof file === 'string' ? file : file.path;
+        const data = buildFileData(filePath, options);
+
+        if (data) {
+            results.push(data);
+        }
+    }
+
+    logger.debug('analysis-engine - buildFilesData', 'Built file data', {
+        inputCount: files.length,
+        outputCount: results.length
+    });
+
+    return results;
+};
+
+/**
+ * Consolidates multiple analysis results into one
+ * Why: Parallel analysis produces multiple results that need merging
+ *
+ * @param {Array<Object>} results - Array of analysis results
+ * @returns {Object} Consolidated result
+ */
+export const consolidateResults = (results) => {
+    const consolidated = {
+        QUALITY_GATE: 'PASSED',
+        approved: true,
+        score: 10,
+        metrics: {
+            reliability: 'A',
+            security: 'A',
+            maintainability: 'A',
+            coverage: 100,
+            duplications: 0,
+            complexity: 0
+        },
+        issues: { blocker: 0, critical: 0, major: 0, minor: 0, info: 0 },
+        details: [],
+        blockingIssues: [],
+        securityHotspots: 0
+    };
+
+    for (const result of results) {
+        // Worst-case quality gate
+        if (result.QUALITY_GATE === 'FAILED') {
+            consolidated.QUALITY_GATE = 'FAILED';
+        }
+        if (result.approved === false) {
+            consolidated.approved = false;
+        }
+        if (result.score < consolidated.score) {
+            consolidated.score = result.score;
+        }
+
+        // Worst-case metrics
+        if (result.metrics) {
+            const metricOrder = { 'A': 5, 'B': 4, 'C': 3, 'D': 2, 'E': 1 };
+            ['reliability', 'security', 'maintainability'].forEach(m => {
+                const current = metricOrder[consolidated.metrics[m]] || 5;
+                const incoming = metricOrder[result.metrics[m]] || 5;
+                if (incoming < current) {
+                    consolidated.metrics[m] = result.metrics[m];
+                }
+            });
+
+            if (result.metrics.coverage !== undefined) {
+                consolidated.metrics.coverage = Math.min(
+                    consolidated.metrics.coverage,
+                    result.metrics.coverage
+                );
+            }
+            if (result.metrics.duplications !== undefined) {
+                consolidated.metrics.duplications = Math.max(
+                    consolidated.metrics.duplications,
+                    result.metrics.duplications
+                );
+            }
+            if (result.metrics.complexity !== undefined) {
+                consolidated.metrics.complexity = Math.max(
+                    consolidated.metrics.complexity,
+                    result.metrics.complexity
+                );
+            }
+        }
+
+        // Sum issue counts
+        if (result.issues) {
+            Object.keys(consolidated.issues).forEach(severity => {
+                consolidated.issues[severity] += (result.issues[severity] || 0);
+            });
+        }
+
+        // Merge arrays
+        if (Array.isArray(result.details)) {
+            consolidated.details.push(...result.details);
+        }
+        if (Array.isArray(result.blockingIssues)) {
+            consolidated.blockingIssues.push(...result.blockingIssues);
+        }
+        if (result.securityHotspots) {
+            consolidated.securityHotspots += result.securityHotspots;
+        }
+    }
+
+    logger.debug('analysis-engine - consolidateResults', 'Results consolidated', {
+        inputCount: results.length,
+        totalIssues: Object.values(consolidated.issues).reduce((a, b) => a + b, 0),
+        qualityGate: consolidated.QUALITY_GATE
+    });
+
+    return consolidated;
+};
+
+/**
+ * Checks if result has any blocking issues (CRITICAL or BLOCKER)
+ * Why: Determines if commit should be blocked
+ *
+ * @param {Object} result - Analysis result
+ * @returns {boolean} True if has blocking issues
+ */
+export const hasBlockingIssues = (result) => {
+    const { blocker = 0, critical = 0 } = result.issues || {};
+    return blocker + critical > 0;
+};
+
+/**
+ * Checks if result has any issues at any severity level
+ * Why: Determines if user should be prompted for confirmation
+ *
+ * @param {Object} result - Analysis result
+ * @returns {boolean} True if has any issues
+ */
+export const hasAnyIssues = (result) => {
+    const { blocker = 0, critical = 0, major = 0, minor = 0, info = 0 } = result.issues || {};
+    return blocker + critical + major + minor + info > 0;
+};
+
+/**
+ * Gets total issue count
+ * Why: Convenience function for display
+ *
+ * @param {Object} result - Analysis result
+ * @returns {number} Total issue count
+ */
+export const getTotalIssueCount = (result) => {
+    const { blocker = 0, critical = 0, major = 0, minor = 0, info = 0 } = result.issues || {};
+    return blocker + critical + major + minor + info;
+};
+
+/**
+ * Creates empty/passed analysis result
+ * Why: Standard result when no files to analyze
+ *
+ * @returns {Object} Empty result with PASSED quality gate
+ */
+export const createEmptyResult = () => ({
+    QUALITY_GATE: 'PASSED',
+    approved: true,
+    issues: { blocker: 0, critical: 0, major: 0, minor: 0, info: 0 },
+    details: [],
+    blockingIssues: [],
+    securityHotspots: 0
+});
+
+/**
+ * Displays compact issue summary
+ * Why: Quick overview of issues found
+ *
+ * @param {Object} result - Analysis result
+ */
+export const displayIssueSummary = (result) => {
+    const { blocker = 0, critical = 0, major = 0, minor = 0, info = 0 } = result.issues || {};
+    const total = blocker + critical + major + minor + info;
+
+    console.log(`📊 ${total} issue(s) found`);
+    if (blocker > 0) console.log(`   🔴 Blocker: ${blocker}`);
+    if (critical > 0) console.log(`   🟠 Critical: ${critical}`);
+    if (major > 0) console.log(`   🟡 Major: ${major}`);
+    if (minor > 0) console.log(`   🔵 Minor: ${minor}`);
+    if (info > 0) console.log(`   ⚪ Info: ${info}`);
+};
+
+/**
+ * Displays detailed analysis results
+ * Why: Full structured output for code review
+ *
+ * @param {Object} result - Analysis result from Claude
+ */
+export const displayResults = (result) => {
+    console.log();
+    console.log('╔════════════════════════════════════════════════════════════════════╗');
+    console.log('║                     CODE QUALITY ANALYSIS                          ║');
+    console.log('╚════════════════════════════════════════════════════════════════════╝');
+    console.log();
+
+    // Quality Gate Status
+    const qualityGate = result.QUALITY_GATE || 'UNKNOWN';
+    if (qualityGate === 'PASSED') {
+        logger.success('Quality Gate: PASSED');
+    } else {
+        logger.error('analysis-engine - displayResults', 'Quality Gate: FAILED');
+    }
+    console.log();
+
+    // Issues Summary - Simple count
+    if (Array.isArray(result.details) && result.details.length > 0) {
+        const fileCount = new Set(result.details.map(i => i.file)).size;
+        console.log(`📊 ${result.details.length} issue(s) found across ${fileCount} file(s)`);
+    } else {
+        console.log('✅ No issues found!');
+    }
+    console.log();
+
+    // Issues Breakdown (severity counts)
+    if (result.issues && typeof result.issues === 'object') {
+        console.log('📋 ISSUES SUMMARY');
+
+        const { blocker = 0, critical = 0, major = 0, minor = 0, info = 0 } = result.issues;
+        const total = blocker + critical + major + minor + info;
+
+        console.log(`Total: ${total} issues found`);
+        if (blocker > 0) console.log(`  🔴 Blocker: ${blocker}`);
+        if (critical > 0) console.log(`  🟠 Critical: ${critical}`);
+        if (major > 0) console.log(`  🟡 Major: ${major}`);
+        if (minor > 0) console.log(`  🔵 Minor: ${minor}`);
+        if (info > 0) console.log(`  ⚪ Info: ${info}`);
+        console.log();
+    }
+
+    // Detailed Issues
+    if (Array.isArray(result.details) && result.details.length > 0) {
+        console.log('🔍 DETAILED ISSUES');
+        result.details.forEach(detail => {
+            console.log(`[${detail.severity}] ${detail.type} in ${detail.file}:${detail.line || '?'}`);
+            console.log(`   ${detail.message}`);
+            console.log();
+        });
+    }
+
+    // Security Hotspots
+    if (result.securityHotspots && result.securityHotspots > 0) {
+        console.log(`🔥 SECURITY HOTSPOTS: ${result.securityHotspots} found`);
+        console.log('   Review security-sensitive code carefully');
+        console.log();
+    }
+};
+
+/**
+ * Runs code analysis on files
+ * Why: Unified analysis orchestration for both pre-commit and analyze command
+ *
+ * @param {Array<FileData>} filesData - Array of file data objects
+ * @param {Object} config - Configuration object
+ * @param {Object} options - Analysis options
+ * @param {boolean} options.saveDebug - Save debug output (default: from config)
+ * @param {string} options.hook - Hook name for telemetry (default: 'analysis')
+ * @returns {Promise<Object>} Analysis result
+ */
+export const runAnalysis = async (filesData, config, options = {}) => {
+    const { saveDebug = config.system?.debug, hook = 'analysis' } = options;
+
+    if (filesData.length === 0) {
+        logger.debug('analysis-engine - runAnalysis', 'No files to analyze');
+        return createEmptyResult();
+    }
+
+    // Determine if parallel execution should be used
+    const subagentsEnabled = config.subagents?.enabled !== false;
+    const batchSize = config.subagents?.batchSize || 3;
+    const useParallel = subagentsEnabled && filesData.length >= 3;
+
+    logger.debug('analysis-engine - runAnalysis', 'Starting analysis', {
+        fileCount: filesData.length,
+        useParallel,
+        batchSize
+    });
+
+    let result;
+
+    if (useParallel) {
+        // Parallel execution: split files into batches
+        const fileBatches = chunkArray(filesData, batchSize);
+
+        logger.debug('analysis-engine - runAnalysis', `Split into ${fileBatches.length} batches`);
+
+        // Build one prompt per batch
+        const prompts = await Promise.all(
+            fileBatches.map(async (batch) => await buildAnalysisPrompt({
+                templateName: config.templates?.analysis,
+                guidelinesName: config.templates?.guidelines,
+                files: batch,
+                metadata: {
+                    REPO_NAME: getRepoName(),
+                    BRANCH_NAME: getCurrentBranch()
+                },
+                subagentConfig: null  // Don't add subagent instruction for parallel
+            }))
+        );
+
+        // Build telemetry context
+        const telemetryContext = {
+            fileCount: filesData.length,
+            batchSize,
+            model: config.subagents?.model || 'haiku',
+            hook
+        };
+
+        // Execute in parallel
+        const results = await analyzeCodeParallel(prompts, {
+            timeout: config.analysis?.timeout,
+            saveDebug: false,  // Don't save debug for individual batches
+            telemetryContext
+        });
+
+        // Consolidate results
+        result = consolidateResults(results);
+
+        // Save consolidated debug if enabled
+        if (saveDebug) {
+            const { saveDebugResponse } = await import('./claude-client.js');
+            await saveDebugResponse(
+                `PARALLEL ANALYSIS: ${fileBatches.length} batches`,
+                JSON.stringify(result, null, 2)
+            );
+        }
+
+    } else {
+        // Single/sequential execution
+        logger.debug('analysis-engine - runAnalysis', 'Using sequential analysis');
+
+        const prompt = await buildAnalysisPrompt({
+            templateName: config.templates?.analysis,
+            guidelinesName: config.templates?.guidelines,
+            files: filesData,
+            metadata: {
+                REPO_NAME: getRepoName(),
+                BRANCH_NAME: getCurrentBranch()
+            },
+            subagentConfig: config.subagents
+        });
+
+        // Build telemetry context
+        const telemetryContext = {
+            fileCount: filesData.length,
+            batchSize: filesData.length,
+            totalBatches: 1,
+            model: config.subagents?.model || 'haiku',
+            hook
+        };
+
+        result = await analyzeCode(prompt, {
+            timeout: config.analysis?.timeout,
+            saveDebug,
+            telemetryContext
+        });
+    }
+
+    logger.debug('analysis-engine - runAnalysis', 'Analysis complete', {
+        qualityGate: result.QUALITY_GATE,
+        totalIssues: getTotalIssueCount(result)
+    });
+
+    return result;
+};

package/lib/utils/git-operations.js

@@ -130,6 +130,92 @@ const getStagedFiles = ({ extensions = [], includeDeleted = false } = {}) => {
     return files;
 };
 
+/**
+ * Gets list of unstaged files (modified but not staged)
+ * Why: For on-demand analysis of working tree changes
+ *
+ * @param {Object} options - Filter options
+ * @param {Array<string>} options.extensions - File extensions to filter (e.g., ['.java', '.xml'])
+ * @param {boolean} options.includeDeleted - Include deleted files (default: false)
+ * @returns {Array<string>} Array of unstaged file paths
+ */
+const getUnstagedFiles = ({ extensions = [], includeDeleted = false } = {}) => {
+    logger.debug(
+        'git-operations - getUnstagedFiles',
+        'Getting unstaged files',
+        { extensions, includeDeleted }
+    );
+
+    // Why: Without --cached flag, shows working tree changes
+    const filter = includeDeleted ? 'ACMR' : 'ACM';
+    const output = execGitCommand(`diff --name-only --diff-filter=${filter}`);
+
+    if (!output) {
+        logger.debug('git-operations - getUnstagedFiles', 'No unstaged files found');
+        return [];
+    }
+
+    const files = output.split(/\r?\n/).filter(f => f.length > 0);
+
+    if (extensions.length > 0) {
+        const filtered = files.filter(file =>
+            extensions.some(ext => file.endsWith(ext))
+        );
+
+        logger.debug(
+            'git-operations - getUnstagedFiles',
+            'Filtered files by extension',
+            { totalFiles: files.length, filteredFiles: filtered.length, extensions }
+        );
+
+        return filtered;
+    }
+
+    return files;
+};
+
+/**
+ * Gets all tracked files in repository
+ * Why: For comprehensive analysis of entire codebase
+ *
+ * @param {Object} options - Filter options
+ * @param {Array<string>} options.extensions - File extensions to filter (e.g., ['.java', '.xml'])
+ * @returns {Array<string>} Array of all tracked file paths
+ */
+const getAllTrackedFiles = ({ extensions = [] } = {}) => {
+    logger.debug(
+        'git-operations - getAllTrackedFiles',
+        'Getting all tracked files',
+        { extensions }
+    );
+
+    // Why: ls-files shows all tracked files in the repository
+    const output = execGitCommand('ls-files');
+
+    if (!output) {
+        logger.debug('git-operations - getAllTrackedFiles', 'No tracked files found');
+        return [];
+    }
+
+    const files = output.split(/\r?\n/).filter(f => f.length > 0);
+
+    if (extensions.length > 0) {
+        const filtered = files.filter(file =>
+            extensions.some(ext => file.endsWith(ext))
+        );
+
+        logger.debug(
+            'git-operations - getAllTrackedFiles',
+            'Filtered files by extension',
+            { totalFiles: files.length, filteredFiles: filtered.length, extensions }
+        );
+
+        return filtered;
+    }
+
+    return files;
+};
+
 /**
  * Gets the diff for a specific file
  * Why: Shows what changed in a file, essential for code review
@@ -490,6 +576,46 @@ const getBranchPushStatus = (branchName) => {
     return status;
 };
 
+/**
+ * Creates a git commit with the specified message
+ * Why: Allows programmatic commit creation after analysis approval
+ *
+ * @param {string} message - Commit message (use "auto" for auto-generation)
+ * @param {Object} options - Commit options
+ * @param {boolean} options.noVerify - Skip pre-commit and commit-msg hooks (default: false)
+ * @returns {Object} Result object with:
+ *   - success: boolean
+ *   - output: string (commit output including hash)
+ *   - error: string (error message if failed)
+ */
+const createCommit = (message, { noVerify = false } = {}) => {
+    logger.debug('git-operations - createCommit', 'Creating commit', { message, noVerify });
+
+    try {
+        const flags = noVerify ? '--no-verify ' : '';
+        // Escape double quotes in message for shell safety
+        const escapedMessage = message.replace(/"/g, '\\"');
+        const output = execGitCommand(`commit ${flags}-m "${escapedMessage}"`);
+
+        logger.debug('git-operations - createCommit', 'Commit successful', { output });
+
+        return {
+            success: true,
+            output,
+            error: ''
+        };
+
+    } catch (error) {
+        logger.error('git-operations - createCommit', 'Commit failed', error);
+
+        return {
+            success: false,
+            output: '',
+            error: error.output || error.cause?.message || error.message || 'Unknown commit error'
+        };
+    }
+};
+
 /**
  * Pushes branch to remote
  * Why: Publishes local branch to remote before creating PR
@@ -540,6 +666,8 @@ const pushBranch = (branchName, { setUpstream = false } = {}) => {
 export {
     GitError,
     getStagedFiles,
+    getUnstagedFiles,
+    getAllTrackedFiles,
     getFileDiff,
     getFileContentFromStaging,
     isNewFile,
@@ -550,5 +678,6 @@ export {
     getRemoteName,
     verifyRemoteExists,
     getBranchPushStatus,
-    pushBranch
+    pushBranch,
+    createCommit
 };