claude-git-hooks 2.20.0 → 2.21.0

package/lib/commands/analyze-pr.js

@@ -0,0 +1,683 @@
+/**
+ * File: analyze-pr.js
+ * Purpose: Analyze a GitHub PR with team guidelines and post review comments
+ *
+ * Flow:
+ * 1. Parse GitHub PR URL
+ * 2. Fetch PR details + files via Octokit
+ * 3. Extract Linear ticket from title (optional enrichment)
+ * 4. Determine preset (labels → ticket → auto-detect → default)
+ * 5. Build prompt from ANALYZE_PR.md template + preset guidelines
+ * 6. Call Claude for analysis
+ * 7. Normalize categories + display results
+ * 8. Interactive comment workflow (confirm/skip each)
+ * 9. Post review via GitHub API
+ * 10. Record statistics
+ */
+
+import { getConfig } from '../config.js';
+import {
+    parseGitHubPRUrl,
+    fetchPullRequest,
+    fetchPullRequestFiles,
+    createPullRequestReview,
+    getGitHubToken
+} from '../utils/github-api.js';
+import { executeClaudeWithRetry, extractJSON } from '../utils/claude-client.js';
+import { loadPrompt } from '../utils/prompt-builder.js';
+import { loadPreset, listPresets } from '../utils/preset-loader.js';
+import { extractLinearTicketFromTitle, fetchTicket } from '../utils/linear-connector.js';
+import { recordPRAnalysis } from '../utils/pr-statistics.js';
+import { promptConfirmation, promptMenu } from '../utils/interactive-ui.js';
+import { colors, error, info, warning, checkGitRepo } from './helpers.js';
+import logger from '../utils/logger.js';
+import path from 'path';
+
+// ─── Category Normalization ─────────────────────────────────────────────────
+
+/**
+ * Fuzzy alias mapping for category normalization
+ * Rationale per alias documented inline
+ */
+const CATEGORY_ALIASES = {
+    // Inline category aliases
+    bugs: 'bug',
+    error: 'bug',
+    errors: 'bug',
+    defect: 'bug',
+    sec: 'security',
+    vulnerability: 'security',
+    vuln: 'security',
+    perf: 'performance',
+    slow: 'performance',
+    complexity: 'hotspot',
+    complex: 'hotspot',
+
+    // General category aliases
+    ticket: 'ticket-alignment',
+    alignment: 'ticket-alignment',
+    'ticket-match': 'ticket-alignment',
+    'scope-creep': 'scope',
+    overscope: 'scope',
+    styling: 'style',
+    formatting: 'style',
+    'code-style': 'style',
+    'best-practice': 'good-practice',
+    'best-practices': 'good-practice',
+    practice: 'good-practice',
+    extension: 'extensibility',
+    scalability: 'extensibility',
+    logging: 'observability',
+    monitoring: 'observability',
+    visibility: 'observability', // "visibility" → "observability" per spec
+    docs: 'documentation',
+    doc: 'documentation',
+    tests: 'testing',
+    test: 'testing',
+    'test-coverage': 'testing'
+};
+
+/**
+ * Normalize a category value to its canonical form
+ * @param {string} raw - Raw category from Claude response
+ * @param {string[]} allCategories - All valid canonical categories
+ * @param {Object} aliases - Alias mapping
+ * @returns {string} Canonical category or 'uncategorized'
+ */
+export const normalizeCategory = (raw, allCategories, aliases) => {
+    if (!raw || typeof raw !== 'string') return 'uncategorized';
+
+    const lower = raw.toLowerCase().trim();
+
+    // Direct match
+    if (allCategories.includes(lower)) return lower;
+
+    // Alias match
+    if (aliases[lower]) return aliases[lower];
+
+    logger.debug('analyze-pr - normalizeCategory', 'Unknown category', { raw, normalized: 'uncategorized' });
+    return 'uncategorized';
+};
+
+// ─── Preset Auto-detection ──────────────────────────────────────────────────
+
+/**
+ * Detect best preset from PR file extensions
+ * @param {Array<Object>} prFiles - PR files from GitHub API
+ * @returns {Promise<string>} Preset name or 'default'
+ */
+const detectPresetFromFiles = async (prFiles) => {
+    try {
+        const presetNames = await listPresets();
+        if (presetNames.length === 0) return 'default';
+
+        const prExtensions = prFiles.map((f) => path.extname(f.filename).toLowerCase()).filter(Boolean);
+
+        if (prExtensions.length === 0) return 'default';
+
+        let bestPreset = 'default';
+        let bestScore = 0;
+
+        for (const { name } of presetNames) {
+            try {
+                const { metadata } = await loadPreset(name);
+                const exts = metadata.fileExtensions || [];
+                const score = prExtensions.filter((ext) => exts.includes(ext)).length;
+
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestPreset = name;
+                }
+            } catch {
+                // Skip invalid presets
+            }
+        }
+
+        logger.debug('analyze-pr - detectPresetFromFiles', 'Auto-detected preset', {
+            bestPreset,
+            bestScore
+        });
+
+        return bestPreset;
+    } catch (error) {
+        logger.debug('analyze-pr - detectPresetFromFiles', 'Detection failed', {
+            error: error.message
+        });
+        return 'default';
+    }
+};
+
+// ─── Preset Resolution ──────────────────────────────────────────────────────
+
+/**
+ * Determine which preset to use, in priority order:
+ * 1. CLI --preset flag
+ * 2. PR labels matching preset names
+ * 3. Linear ticket labels matching preset names
+ * 4. Auto-detect from file extensions
+ * 5. 'default'
+ *
+ * @param {Object} options
+ * @param {string|null} options.cliPreset - --preset flag value
+ * @param {Array<Object>} options.prLabels - PR labels ({ name })
+ * @param {Array<string>} options.ticketLabels - Linear ticket labels
+ * @param {Array<Object>} options.prFiles - PR files from GitHub API
+ * @returns {Promise<string>} Resolved preset name
+ */
+const resolvePreset = async ({ cliPreset, prLabels, ticketLabels, prFiles }) => {
+    // 1. CLI override
+    if (cliPreset) {
+        logger.debug('analyze-pr - resolvePreset', 'Using CLI preset', { preset: cliPreset });
+        return cliPreset;
+    }
+
+    const presetCandidates = ['ai', 'backend', 'database', 'frontend', 'fullstack'];
+
+    // 2. PR labels
+    const prLabelNames = (prLabels || []).map((l) => l.name.toLowerCase());
+    for (const candidate of presetCandidates) {
+        if (prLabelNames.includes(candidate)) {
+            logger.debug('analyze-pr - resolvePreset', 'Matched from PR labels', {
+                preset: candidate
+            });
+            return candidate;
+        }
+    }
+
+    // 3. Linear ticket labels
+    for (const label of ticketLabels || []) {
+        const lower = label.toLowerCase();
+        if (presetCandidates.includes(lower)) {
+            logger.debug('analyze-pr - resolvePreset', 'Matched from ticket labels', {
+                preset: lower
+            });
+            return lower;
+        }
+    }
+
+    // 4. Auto-detect from file extensions
+    const detected = await detectPresetFromFiles(prFiles);
+    return detected;
+};
+
+// ─── Display Helpers ────────────────────────────────────────────────────────
+
+const SEVERITY_ICONS = {
+    critical: '\u{1F534}',
+    major: '\u{1F7E0}',
+    minor: '\u{1F535}',
+    info: '\u{26AA}'
+};
+
+/**
+ * Format a comment for display
+ * @param {Object} comment - Inline or general comment
+ * @param {number} index - 1-based index
+ * @param {boolean} isInline - Whether this is an inline comment
+ */
+const displayComment = (comment, index, isInline) => {
+    const icon = SEVERITY_ICONS[comment.severity] || '\u{26AA}';
+    const prefix = isInline ? `${comment.path}:${comment.line}` : 'General';
+
+    console.log(`  ${icon} [${index}] [${comment.category}] ${prefix}`);
+    console.log(`     ${comment.body}`);
+    if (isInline && comment.suggestion) {
+        console.log(`     ${colors.green}Suggestion: ${comment.suggestion}${colors.reset}`);
+    }
+    console.log('');
+};
+
+// ─── Main Command ───────────────────────────────────────────────────────────
+
+/**
+ * Analyze a GitHub PR with team guidelines
+ * @param {Array<string>} args - Command arguments [pr-url, ...flags]
+ */
+export async function runAnalyzePr(args) {
+    if (!checkGitRepo()) {
+        error('You are not in a Git repository.');
+        return;
+    }
+
+    // Parse arguments
+    const prUrl = args.find((a) => !a.startsWith('--'));
+    const cliPreset = args.includes('--preset')
+        ? args[args.indexOf('--preset') + 1]
+        : null;
+    const cliModel = args.includes('--model')
+        ? args[args.indexOf('--model') + 1]
+        : null;
+    const dryRun = args.includes('--dry-run');
+
+    if (!prUrl) {
+        error('Usage: claude-hooks analyze-pr <pr-url> [--preset <name>] [--model <model>] [--dry-run]');
+        return;
+    }
+
+    // Step 1: Parse URL
+    const parsed = parseGitHubPRUrl(prUrl);
+    if (!parsed) {
+        error(`Invalid GitHub PR URL: ${prUrl}`);
+        return;
+    }
+
+    const { owner, repo, number } = parsed;
+    info(`Analyzing PR #${number} in ${owner}/${repo}...`);
+
+    // Load config
+    const config = await getConfig();
+    if (config.system?.debug) {
+        logger.setDebugMode(true);
+    }
+
+    // Step 2: Validate GitHub token
+    try {
+        getGitHubToken();
+    } catch {
+        error('GitHub token not configured. Run: claude-hooks setup-github');
+        return;
+    }
+
+    const startTime = Date.now();
+
+    try {
+        // Step 3: Fetch PR details + files
+        const [prData, prFiles] = await Promise.all([
+            fetchPullRequest(owner, repo, number),
+            fetchPullRequestFiles(owner, repo, number)
+        ]);
+
+        info(`PR: "${prData.title}" (${prFiles.length} files changed)`);
+
+        // Step 4: Extract Linear ticket
+        let ticketContext = 'No ticket context available.';
+        let ticketLabels = [];
+
+        const linearId = extractLinearTicketFromTitle(prData.title);
+        if (linearId) {
+            info(`Linear ticket detected: ${linearId}`);
+            const ticket = await fetchTicket(linearId);
+
+            if (ticket) {
+                ticketContext = [
+                    `**Ticket:** ${ticket.identifier} - ${ticket.title}`,
+                    `**State:** ${ticket.state}`,
+                    ticket.description ? `**Description:** ${ticket.description}` : '',
+                    ticket.labels.length > 0 ? `**Labels:** ${ticket.labels.join(', ')}` : ''
+                ]
+                    .filter(Boolean)
+                    .join('\n');
+                ticketLabels = ticket.labels;
+            } else {
+                warning(`Could not fetch Linear ticket ${linearId}`);
+            }
+        }
+
+        // Step 5: Determine preset
+        const presetName = await resolvePreset({
+            cliPreset,
+            prLabels: prData.labels,
+            ticketLabels,
+            prFiles
+        });
+        info(`Using preset: ${presetName}`);
+
+        // Step 6: Load preset guidelines
+        let presetGuidelines = 'Standard code review guidelines apply.';
+        try {
+            const { templates } = await loadPreset(presetName);
+            const fs = await import('fs/promises');
+
+            const guidelinesParts = [];
+            if (templates.guidelines) {
+                const content = await fs.readFile(templates.guidelines, 'utf8');
+                guidelinesParts.push(content);
+            }
+            if (templates.prompt) {
+                const content = await fs.readFile(templates.prompt, 'utf8');
+                guidelinesParts.push(content);
+            }
+
+            if (guidelinesParts.length > 0) {
+                presetGuidelines = guidelinesParts.join('\n\n');
+            }
+        } catch {
+            warning(`Could not load preset "${presetName}" guidelines, using defaults`);
+        }
+
+        // Step 7: Build category strings from config
+        const inlineCategories = config.prAnalysis?.inlineCategories || [
+            'bug',
+            'security',
+            'performance',
+            'hotspot'
+        ];
+        const generalCategories = config.prAnalysis?.generalCategories || [
+            'ticket-alignment',
+            'scope',
+            'style',
+            'good-practice',
+            'extensibility',
+            'observability',
+            'documentation',
+            'testing'
+        ];
+        const allCategories = [...inlineCategories, ...generalCategories];
+
+        const inlineCategoriesStr = inlineCategories
+            .map((c) => `- \`${c}\``)
+            .join('\n');
+        const generalCategoriesStr = generalCategories
+            .map((c) => `- \`${c}\``)
+            .join('\n');
+
+        // Build file list and diff for template
+        const filesStr = prFiles
+            .map(
+                (f) =>
+                    `- ${f.filename} (+${f.additions}/-${f.deletions}) [${f.status}]`
+            )
+            .join('\n');
+
+        const diffStr = prFiles
+            .filter((f) => f.patch)
+            .map((f) => `--- ${f.filename} ---\n${f.patch}`)
+            .join('\n\n');
+
+        // Step 8: Build prompt
+        const model = cliModel || config.prAnalysis?.model || 'sonnet';
+        const timeout = config.prAnalysis?.timeout || 300000;
+
+        const prompt = await loadPrompt('ANALYZE_PR.md', {
+            PR_TITLE: prData.title,
+            PR_BODY: prData.body || 'No description provided.',
+            PR_FILES: filesStr,
+            PR_DIFF: diffStr || 'No diff available.',
+            TICKET_CONTEXT: ticketContext,
+            PRESET_GUIDELINES: presetGuidelines,
+            INLINE_CATEGORIES: inlineCategoriesStr,
+            GENERAL_CATEGORIES: generalCategoriesStr
+        });
+
+        // Step 9: Call Claude
+        info('Running analysis...');
+        const response = await executeClaudeWithRetry(prompt, {
+            timeout,
+            model,
+            telemetryContext: { hook: 'analyze-pr', fileCount: prFiles.length }
+        });
+
+        logger.debug('analyze-pr - runAnalyzePr', 'Claude response received', {
+            responseLength: response.length,
+            responsePreview: response.substring(0, 300)
+        });
+
+        let result;
+        try {
+            result = extractJSON(response);
+        } catch (jsonErr) {
+            // Surface the actual response so users can diagnose prompt issues
+            const preview = response.substring(0, 500);
+            error(`Failed to parse Claude response as JSON. Claude returned:\n${preview}${response.length > 500 ? '\n...(truncated)' : ''}`);
+            throw jsonErr;
+        }
+
+        // Step 10: Normalize categories
+        const inlineComments = (result.inlineComments || []).map((c) => ({
+            ...c,
+            category: normalizeCategory(c.category, allCategories, CATEGORY_ALIASES)
+        }));
+        const generalComments = (result.generalComments || []).map((c) => ({
+            ...c,
+            category: normalizeCategory(c.category, allCategories, CATEGORY_ALIASES)
+        }));
+
+        // Step 11: Display results
+        const elapsed = Date.now() - startTime;
+        const seconds = (elapsed / 1000).toFixed(1);
+
+        console.log('');
+        console.log('================================================================');
+        console.log('                      PR ANALYSIS RESULTS                        ');
+        console.log('================================================================');
+        console.log('');
+        console.log(`${colors.blue}Verdict:${colors.reset} ${result.verdict || 'comment'}`);
+        console.log(`${colors.blue}Summary:${colors.reset} ${result.summary || 'No summary.'}`);
+        console.log(`${colors.blue}Preset:${colors.reset} ${presetName}`);
+        console.log(`${colors.blue}Model:${colors.reset} ${model}`);
+        console.log(
+            `${colors.blue}Issues:${colors.reset} ${inlineComments.length} inline, ${generalComments.length} general`
+        );
+        console.log('');
+
+        if (inlineComments.length > 0) {
+            console.log(`${colors.green}--- Inline Comments ---${colors.reset}`);
+            console.log('');
+            inlineComments.forEach((c, i) => displayComment(c, i + 1, true));
+        }
+
+        if (generalComments.length > 0) {
+            console.log(`${colors.green}--- General Comments ---${colors.reset}`);
+            console.log('');
+            generalComments.forEach((c, i) => displayComment(c, i + 1, false));
+        }
+
+        if (inlineComments.length === 0 && generalComments.length === 0) {
+            console.log(`${colors.green}No issues found. This PR looks good!${colors.reset}`);
+        }
+
+        console.log(`${colors.blue}Analysis completed in ${seconds}s${colors.reset}`);
+        console.log('');
+
+        // Step 12: Interactive comment workflow
+        if (dryRun) {
+            info('Dry run mode: skipping comment posting.');
+            recordStats({
+                prUrl,
+                number,
+                owner,
+                repo,
+                presetName,
+                result,
+                inlineComments,
+                generalComments,
+                commentsPosted: 0,
+                commentsSkipped: inlineComments.length + generalComments.length
+            });
+            return;
+        }
+
+        if (inlineComments.length === 0 && generalComments.length === 0) {
+            info('No comments to post.');
+            recordStats({
+                prUrl,
+                number,
+                owner,
+                repo,
+                presetName,
+                result,
+                inlineComments,
+                generalComments,
+                commentsPosted: 0,
+                commentsSkipped: 0
+            });
+            return;
+        }
+
+        // Ask user to confirm posting
+        const postChoice = await promptMenu(
+            'What would you like to do with the review?',
+            [
+                { key: 'a', label: 'Post all comments as a review' },
+                { key: 's', label: 'Select which comments to post' },
+                { key: 'n', label: 'Skip posting (analysis only)' }
+            ],
+            'a'
+        );
+
+        let confirmedInline = [];
+        let confirmedGeneral = [];
+
+        if (postChoice === 'n') {
+            info('Skipping comment posting.');
+            recordStats({
+                prUrl,
+                number,
+                owner,
+                repo,
+                presetName,
+                result,
+                inlineComments,
+                generalComments,
+                commentsPosted: 0,
+                commentsSkipped: inlineComments.length + generalComments.length
+            });
+            return;
+        }
+
+        if (postChoice === 'a') {
+            confirmedInline = inlineComments;
+            confirmedGeneral = generalComments;
+        } else if (postChoice === 's') {
+            // Select inline comments
+            for (const comment of inlineComments) {
+                displayComment(comment, inlineComments.indexOf(comment) + 1, true);
+                const keep = await promptConfirmation('Post this inline comment?', true);
+                if (keep) confirmedInline.push(comment);
+            }
+
+            // Select general comments
+            for (const comment of generalComments) {
+                displayComment(comment, generalComments.indexOf(comment) + 1, false);
+                const keep = await promptConfirmation('Include this general comment?', true);
+                if (keep) confirmedGeneral.push(comment);
+            }
+        }
+
+        // Step 13: Post review
+        if (confirmedInline.length === 0 && confirmedGeneral.length === 0) {
+            info('No comments selected for posting.');
+            recordStats({
+                prUrl,
+                number,
+                owner,
+                repo,
+                presetName,
+                result,
+                inlineComments,
+                generalComments,
+                commentsPosted: 0,
+                commentsSkipped: inlineComments.length + generalComments.length
+            });
+            return;
+        }
+
+        // Build review body from general comments
+        let reviewBody = `## PR Analysis (${presetName} preset)\n\n`;
+        reviewBody += `**Verdict:** ${result.verdict || 'comment'}\n\n`;
+
+        if (result.summary) {
+            reviewBody += `${result.summary}\n\n`;
+        }
+
+        if (confirmedGeneral.length > 0) {
+            reviewBody += '### Review Observations\n\n';
+            for (const comment of confirmedGeneral) {
+                const icon = SEVERITY_ICONS[comment.severity] || '\u{26AA}';
+                reviewBody += `${icon} **[${comment.category}]** ${comment.body}\n\n`;
+            }
+        }
+
+        // Determine review event
+        const event = result.verdict === 'approve' ? 'APPROVE' : 'COMMENT';
+
+        // Format inline comments for API
+        const apiComments = confirmedInline.map((c) => {
+            let body = `**[${c.category}]** ${c.body}`;
+            if (c.suggestion) {
+                body += `\n\n**Suggestion:**\n\`\`\`suggestion\n${c.suggestion}\n\`\`\``;
+            }
+            return {
+                path: c.path,
+                line: c.line,
+                side: c.side || 'RIGHT',
+                body
+            };
+        });
+
+        info('Posting review...');
+        await createPullRequestReview(owner, repo, number, reviewBody, apiComments, event);
+
+        const totalPosted = confirmedInline.length + confirmedGeneral.length;
+        const totalSkipped =
+            inlineComments.length +
+            generalComments.length -
+            totalPosted;
+
+        console.log(
+            `${colors.green}Review posted: ${confirmedInline.length} inline comments, ${confirmedGeneral.length} general observations${colors.reset}`
+        );
+
+        // Step 14: Record statistics
+        recordStats({
+            prUrl,
+            number,
+            owner,
+            repo,
+            presetName,
+            result,
+            inlineComments,
+            generalComments,
+            commentsPosted: totalPosted,
+            commentsSkipped: totalSkipped
+        });
+    } catch (e) {
+        if (e.name === 'GitHubAPIError') {
+            error(`GitHub API error: ${e.message}`);
+        } else {
+            error(`Error analyzing PR: ${e.message}`);
+            logger.debug('analyze-pr - runAnalyzePr', 'Full error details', {
+                name: e.name,
+                message: e.message,
+                context: e.context ? JSON.stringify(e.context).substring(0, 500) : undefined,
+                stack: e.stack
+            });
+        }
+    }
+}
+
+/**
+ * Record analysis statistics
+ * @private
+ */
+function recordStats({
+    prUrl,
+    number,
+    owner,
+    repo,
+    presetName,
+    result,
+    inlineComments,
+    generalComments,
+    commentsPosted,
+    commentsSkipped
+}) {
+    const issuesByCategory = {};
+    [...inlineComments, ...generalComments].forEach((c) => {
+        issuesByCategory[c.category] = (issuesByCategory[c.category] || 0) + 1;
+    });
+
+    recordPRAnalysis({
+        url: prUrl,
+        number,
+        repo: `${owner}/${repo}`,
+        preset: presetName,
+        verdict: result.verdict || 'comment',
+        totalIssues: inlineComments.length + generalComments.length,
+        issuesByCategory,
+        inlineCount: inlineComments.length,
+        generalCount: generalComments.length,
+        commentsPosted,
+        commentsSkipped
+    });
+}