claude-git-hooks 2.21.0 → 2.30.2

package/lib/commands/check-coupling.js

@@ -0,0 +1,209 @@
+/**
+ * File: check-coupling.js
+ * Purpose: Detect coupled PRs before release by analyzing file overlap
+ *
+ * Flow:
+ * 1. Parse --base (default: develop) and --json flags
+ * 2. Get repository owner/repo from local git remote
+ * 3. Fetch open PRs targeting base branch via GitHub API
+ * 4. Fetch changed files for each PR in parallel
+ * 5. Build file index and detect coupling groups (Union-Find)
+ * 6. Display results (human-readable or JSON)
+ */
+
+import {
+    getGitHubToken,
+    parseGitHubRepo,
+    listOpenPullRequests,
+    fetchPullRequestFiles
+} from '../utils/github-api.js';
+import { buildFileIndex, detectCouplingGroups } from '../utils/coupling-detector.js';
+import { colors, error, info, warning, checkGitRepo } from './helpers.js';
+import logger from '../utils/logger.js';
+
+/** PRs with this many or more changed files trigger a large-PR warning */
+const LARGE_PR_FILE_THRESHOLD = 100;
+
+/**
+ * Check coupling among open PRs targeting a base branch
+ * @param {string[]} args - Command arguments [--base <branch>] [--json]
+ */
+export async function runCheckCoupling(args) {
+    if (!checkGitRepo()) {
+        error('You are not in a Git repository.');
+        return;
+    }
+
+    // Parse arguments
+    const baseIndex = args.indexOf('--base');
+    const base = baseIndex !== -1 && args[baseIndex + 1] ? args[baseIndex + 1] : 'develop';
+    const jsonOutput = args.includes('--json');
+
+    // Validate GitHub token
+    try {
+        getGitHubToken();
+    } catch {
+        error('GitHub token not configured. Run: claude-hooks setup-github');
+        return;
+    }
+
+    // Get repository info from local git remote
+    let owner, repo;
+    try {
+        const repoInfo = parseGitHubRepo();
+        owner = repoInfo.owner;
+        repo = repoInfo.repo;
+    } catch (e) {
+        error(`Could not determine repository: ${e.message}`);
+        return;
+    }
+
+    if (!jsonOutput) {
+        info(`Fetching open PRs targeting ${base}...`);
+    }
+
+    try {
+        // Fetch open PRs
+        const openPRs = await listOpenPullRequests(owner, repo, base);
+
+        if (openPRs.length === 0) {
+            if (jsonOutput) {
+                console.log(
+                    JSON.stringify({
+                        base,
+                        totalPRs: 0,
+                        coupledGroups: [],
+                        independentPRs: [],
+                        warnings: []
+                    })
+                );
+            } else {
+                info(`No open PRs targeting ${base}.`);
+            }
+            return;
+        }
+
+        if (!jsonOutput) {
+            info(
+                `Found ${openPRs.length} open PR${openPRs.length !== 1 ? 's' : ''} targeting ${base}`
+            );
+        }
+
+        // Fetch files for each PR in parallel
+        const prFiles = new Map(); // prNumber → Set<filePath>
+        const warnings = [];
+
+        await Promise.all(
+            openPRs.map(async (pr) => {
+                try {
+                    const files = await fetchPullRequestFiles(owner, repo, pr.number);
+                    if (files.length === 0) {
+                        warnings.push(`PR #${pr.number} has 0 changed files — skipped.`);
+                        return;
+                    }
+                    if (files.length >= LARGE_PR_FILE_THRESHOLD) {
+                        warnings.push(
+                            `PR #${pr.number} changes ${files.length} files — large refactor, may couple with many PRs.`
+                        );
+                    }
+                    prFiles.set(pr.number, new Set(files.map((f) => f.filename)));
+                } catch (e) {
+                    logger.debug('check-coupling', `Could not fetch files for PR #${pr.number}`, {
+                        error: e.message
+                    });
+                    warnings.push(`Could not fetch files for PR #${pr.number}: ${e.message}`);
+                }
+            })
+        );
+
+        // Build index and detect coupling groups
+        const prNumbersWithFiles = [...prFiles.keys()];
+        const fileIndex = buildFileIndex(prFiles);
+        const { coupledGroups, independentPRNumbers } = detectCouplingGroups(
+            prNumbersWithFiles,
+            fileIndex,
+            prFiles
+        );
+
+        // Build PR lookup by number
+        const prByNumber = new Map(openPRs.map((pr) => [pr.number, pr]));
+
+        if (jsonOutput) {
+            const output = {
+                base,
+                totalPRs: openPRs.length,
+                coupledGroups: coupledGroups.map((group) => ({
+                    prs: group.prNumbers.map((n) => {
+                        const pr = prByNumber.get(n);
+                        return { number: n, title: pr?.title || '', url: pr?.html_url || '' };
+                    }),
+                    sharedFiles: group.sharedFiles
+                })),
+                independentPRs: independentPRNumbers.map((n) => {
+                    const pr = prByNumber.get(n);
+                    return { number: n, title: pr?.title || '', url: pr?.html_url || '' };
+                }),
+                warnings
+            };
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+
+        // Human-readable output
+        console.log('');
+        console.log(
+            `\uD83D\uDCCB Open PRs targeting ${colors.blue}${base}${colors.reset}: ${openPRs.length}`
+        );
+
+        for (const w of warnings) {
+            warning(w);
+        }
+
+        console.log('');
+
+        if (coupledGroups.length === 0) {
+            console.log(
+                `${colors.green}\u2705 All PRs are independent (no coupling detected)${colors.reset}`
+            );
+        } else {
+            console.log(
+                `${colors.yellow}\uD83D\uDD17 Coupled groups (ship together or pull together):${colors.reset}`
+            );
+            console.log('');
+
+            coupledGroups.forEach((group, index) => {
+                console.log(`  Group ${index + 1}:`);
+                for (const prNumber of group.prNumbers) {
+                    const pr = prByNumber.get(prNumber);
+                    console.log(`    - PR #${prNumber} ${pr?.title || '(unknown title)'}`);
+                }
+                if (group.sharedFiles.length > 0) {
+                    console.log('    Shared files:');
+                    for (const file of group.sharedFiles) {
+                        console.log(`      ${file}`);
+                    }
+                }
+                console.log('');
+            });
+        }
+
+        if (independentPRNumbers.length > 0) {
+            console.log(`${colors.green}\u2705 Independent PRs (no coupling):${colors.reset}`);
+            for (const prNumber of independentPRNumbers) {
+                const pr = prByNumber.get(prNumber);
+                console.log(`    - PR #${prNumber} ${pr?.title || '(unknown title)'}`);
+            }
+            console.log('');
+        }
+    } catch (e) {
+        if (e.name === 'GitHubAPIError') {
+            error(`GitHub API error: ${e.message}`);
+        } else {
+            error(`Error checking coupling: ${e.message}`);
+            logger.debug('check-coupling', 'Full error', {
+                message: e.message,
+                stack: e.stack
+            });
+        }
+    }
+}

package/lib/commands/close-release.js

@@ -0,0 +1,485 @@
+/**
+ * File: close-release.js
+ * Purpose: close-release command — release-candidate finalization
+ *
+ * Workflow:
+ *  1. Detect active release-candidate/V* branch (current or remote)
+ *  2. Validate preconditions (clean dir, on RC, remote up-to-date)
+ *  3. Collect feature list (commit subjects since origin/main)
+ *  4. Resolve description: CLI arg > --auto-describe (Claude) > interactive prompt
+ *  5. [--dry-run] Preview + return
+ *  6. Confirm with user
+ *  7. git reset --soft origin/main — all RC changes staged
+ *  8. git commit "Release v{version}: {description}" + feature list body (--no-verify)
+ *  9. git push --force-with-lease
+ * 10. [unless --no-pr] Create PR to main with merge-commit label + reminder
+ * 11. Display summary
+ */
+
+import { execSync } from 'child_process';
+import {
+    getCurrentBranch,
+    getActiveBranch,
+    isWorkingDirectoryClean,
+    fetchRemote,
+    getDivergence,
+    getCommitsBetweenRefs,
+    resetBranch,
+    forcePush
+} from '../utils/git-operations.js';
+import {
+    showInfo,
+    showSuccess,
+    showWarning,
+    promptConfirmation,
+    promptEditField
+} from '../utils/interactive-ui.js';
+import logger from '../utils/logger.js';
+import { colors, error, checkGitRepo } from './helpers.js';
+
+/** Prefix for release-candidate branches */
+const RC_PREFIX = 'release-candidate';
+
+/** Target branch for the release PR */
+const TARGET_BRANCH = 'main';
+
+/** Label added to the created PR to signal merge-commit strategy */
+const MERGE_COMMIT_LABEL = 'merge-strategy:merge-commit';
+
+/** Body reminder prepended to PR description */
+const MERGE_COMMIT_REMINDER =
+    '> ⚠️ This PR must be merged with **merge commit** (not squash)\n\n';
+
+// ─── Argument parsing ────────────────────────────────────────────────────────
+
+/**
+ * Parse CLI arguments into structured options
+ *
+ * @param {string[]} args - Raw CLI args (args.slice(1) from router)
+ * @returns {{ description: string|null, autoDescribe: boolean, dryRun: boolean, noPr: boolean }}
+ */
+function _parseArgs(args) {
+    const flags = args.filter((a) => a.startsWith('--'));
+    const positional = args.filter((a) => !a.startsWith('--'));
+    return {
+        description: positional[0] || null,
+        autoDescribe: flags.includes('--auto-describe'),
+        dryRun: flags.includes('--dry-run'),
+        noPr: flags.includes('--no-pr')
+    };
+}
+
+// ─── Version extraction ──────────────────────────────────────────────────────
+
+/**
+ * Extract semver string from a release-candidate branch name.
+ * Supports both capital-V ("release-candidate/V2.6.0") and bare semver.
+ *
+ * @param {string} branchName - e.g. "release-candidate/V2.6.0"
+ * @returns {string|null} e.g. "2.6.0", or null if not parseable
+ */
+export function _extractVersion(branchName) {
+    const match = branchName.match(/release-candidate\/V?(\d+\.\d+\.\d+[^\s]*)/i);
+    return match ? match[1] : null;
+}
+
+// ─── Feature list ────────────────────────────────────────────────────────────
+
+/**
+ * Collect commit subjects between origin/main and HEAD.
+ *
+ * @returns {string[]} Array of subject lines (empty array if none or on error)
+ */
+export function _collectFeatureList() {
+    try {
+        const raw = getCommitsBetweenRefs('origin/main', 'HEAD', { format: '%s' });
+        if (!raw) return [];
+        return raw
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .filter(Boolean);
+    } catch (e) {
+        logger.debug('close-release - _collectFeatureList', 'Failed to collect feature list', {
+            error: e.message
+        });
+        return [];
+    }
+}
+
+// ─── Description resolution ──────────────────────────────────────────────────
+
+/**
+ * Generate a 1-line release description using Claude (--auto-describe).
+ *
+ * @param {string[]} featureList - Commit subjects
+ * @returns {Promise<string>} Short phrase describing the release
+ */
+async function _autoDescribe(featureList) {
+    const { executeClaudeWithRetry } = await import('../utils/claude-client.js');
+    const commitLines = featureList.map((f) => `- ${f}`).join('\n');
+    const prompt = `You are summarizing a software release for a Git commit message.\n\nGiven the following list of commit messages included in this release, write a single short phrase (5–10 words, no punctuation at end) that captures what this release contains.\n\nCommits:\n${commitLines}\n\nReturn only the phrase, nothing else. No quotes, no period.`;
+
+    const result = await executeClaudeWithRetry(prompt, { timeout: 60000, model: 'haiku' });
+    return result.trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Resolve the release description from all possible sources.
+ * Priority: CLI arg → --auto-describe → interactive prompt
+ *
+ * @param {{ description: string|null, autoDescribe: boolean }} options
+ * @param {string[]} featureList
+ * @returns {Promise<string>}
+ */
+export async function _resolveDescription(options, featureList) {
+    // 1. CLI argument — use directly
+    if (options.description) {
+        return options.description;
+    }
+
+    // 2. Claude auto-describe
+    if (options.autoDescribe) {
+        if (featureList.length === 0) {
+            showWarning('No commits found for auto-describe — falling back to interactive prompt');
+        } else {
+            showInfo('Generating description with Claude...');
+            try {
+                const desc = await _autoDescribe(featureList);
+                showSuccess(`Generated: "${desc}"`);
+                return desc;
+            } catch (e) {
+                showWarning(`Auto-describe failed: ${e.message} — falling back to prompt`);
+            }
+        }
+    }
+
+    // 3. Interactive prompt — show feature list then ask TL to accept or override
+    console.log('');
+    showInfo('Feature commits in this release:');
+    if (featureList.length === 0) {
+        console.log('  (no commits found since origin/main)');
+    } else {
+        featureList.forEach((f) => console.log(`  - ${f}`));
+    }
+    console.log('');
+
+    const defaultDesc =
+        featureList.length > 0 ? featureList[0] : 'maintenance release';
+    return promptEditField('description', defaultDesc);
+}
+
+// ─── Dry-run preview ─────────────────────────────────────────────────────────
+
+/**
+ * Print a preview table of what close-release would do, then return.
+ *
+ * @param {Object} p
+ * @param {string} p.rcBranch
+ * @param {string} p.version
+ * @param {string} p.description
+ * @param {string[]} p.featureList
+ * @param {{ noPr: boolean }} p.options
+ */
+function _showDryRunPreview({ rcBranch, version, description, featureList, options }) {
+    const commitTitle = `Release v${version}: ${description}`;
+
+    console.log('');
+    console.log(`${colors.yellow}═════════════════════════════════════════════════${colors.reset}`);
+    console.log(`${colors.yellow}           DRY RUN — No changes will be made     ${colors.reset}`);
+    console.log(`${colors.yellow}═════════════════════════════════════════════════${colors.reset}`);
+    console.log('');
+    console.log(`${colors.blue}Branch:${colors.reset}       ${rcBranch}`);
+    console.log(`${colors.blue}Version:${colors.reset}      v${version}`);
+    console.log(`${colors.blue}Description:${colors.reset}  ${description}`);
+    console.log('');
+    console.log('Planned actions:');
+    console.log('  1. git reset --soft origin/main');
+    console.log(`  2. git commit --no-verify -F - <<< "${commitTitle}"`);
+    if (featureList.length > 0) {
+        console.log(`     (body: ${featureList.length} feature line(s))`);
+    }
+    console.log(`  3. git push --force-with-lease origin ${rcBranch}`);
+    if (!options.noPr) {
+        console.log(`  4. Create PR: ${rcBranch} → ${TARGET_BRANCH}`);
+        console.log(`     Label: ${MERGE_COMMIT_LABEL}`);
+    } else {
+        console.log('  4. PR creation skipped (--no-pr)');
+    }
+    console.log('');
+    console.log(`${colors.yellow}Run without --dry-run to apply these changes${colors.reset}`);
+    console.log('');
+}
+
+// ─── Main command ─────────────────────────────────────────────────────────────
+
+/**
+ * close-release command.
+ * Finalizes the active release-candidate: soft-reset onto main,
+ * single clean commit, force-push, and optionally creates the PR.
+ *
+ * @param {string[]} args - CLI arguments (as passed by the router)
+ */
+export async function runCloseRelease(args) {
+    logger.debug('close-release', 'Starting close-release command', { args });
+
+    const options = _parseArgs(args);
+
+    if (!checkGitRepo()) {
+        error('Not a Git repository');
+        process.exit(1);
+    }
+
+    // ── Step 1: Detect active RC branch ──────────────────────────────────────
+
+    let rcBranch = null;
+    const currentBranch = getCurrentBranch();
+
+    if (currentBranch && currentBranch.startsWith(`${RC_PREFIX}/`)) {
+        rcBranch = currentBranch;
+        showInfo(`Using current branch: ${rcBranch}`);
+    } else {
+        // Look for a remote RC branch
+        const remoteBranch = getActiveBranch(RC_PREFIX);
+        if (!remoteBranch) {
+            error(
+                `No active ${RC_PREFIX}/V* branch found.\n` +
+                    '  Create one first:  claude-hooks create-release minor'
+            );
+            process.exit(1);
+        }
+
+        rcBranch = remoteBranch;
+        console.log('');
+        showInfo(`Found release-candidate branch: ${rcBranch}`);
+        const shouldSwitch = await promptConfirmation(`Switch to ${rcBranch}?`, true);
+        if (!shouldSwitch) {
+            showInfo('Cancelled');
+            process.exit(0);
+        }
+
+        try {
+            execSync(`git checkout ${rcBranch}`, {
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe']
+            });
+            showSuccess(`Switched to ${rcBranch}`);
+        } catch (e) {
+            error(`Could not checkout ${rcBranch}: ${e.stderr || e.message}`);
+            process.exit(1);
+        }
+    }
+
+    // ── Extract version from branch name ─────────────────────────────────────
+
+    const version = _extractVersion(rcBranch);
+    if (!version) {
+        error(`Could not extract version from branch name: ${rcBranch}`);
+        process.exit(1);
+    }
+
+    console.log('');
+    showInfo(`Version: v${version}`);
+    console.log('');
+
+    // ── Step 2: Validate preconditions ───────────────────────────────────────
+
+    if (!isWorkingDirectoryClean()) {
+        error(
+            'Working directory has uncommitted changes.\n' +
+                '  Commit or stash them before closing a release.'
+        );
+        process.exit(1);
+    }
+
+    try {
+        fetchRemote();
+    } catch (e) {
+        showWarning(`Could not fetch from remote: ${e.message} — results may be stale`);
+    }
+
+    let divergence = null;
+    try {
+        divergence = getDivergence(rcBranch, `origin/${rcBranch}`);
+    } catch (e) {
+        showWarning(`Could not check remote divergence: ${e.message}`);
+    }
+
+    if (divergence && divergence.behind > 0) {
+        error(
+            `Local branch is ${divergence.behind} commit(s) behind remote.\n` +
+                `  Pull first:  git pull origin ${rcBranch}`
+        );
+        process.exit(1);
+    }
+
+    // ── Step 3: Collect feature list ─────────────────────────────────────────
+
+    const featureList = _collectFeatureList();
+    logger.debug('close-release', 'Feature list collected', { count: featureList.length });
+
+    if (featureList.length === 0) {
+        showWarning('No commits found since origin/main — the RC may already be squashed or empty');
+    }
+
+    // ── Step 4: Resolve description ──────────────────────────────────────────
+
+    const description = await _resolveDescription(options, featureList);
+    if (!description || !description.trim()) {
+        error('Description cannot be empty');
+        process.exit(1);
+    }
+
+    // ── Step 5: Dry-run ───────────────────────────────────────────────────────
+
+    if (options.dryRun) {
+        _showDryRunPreview({ rcBranch, version, description, featureList, options });
+        return;
+    }
+
+    // ── Step 6: Confirm ───────────────────────────────────────────────────────
+
+    const commitTitle = `Release v${version}: ${description}`;
+    console.log('');
+    showInfo(`Commit message: "${commitTitle}"`);
+    if (featureList.length > 0) {
+        showInfo(`Includes ${featureList.length} feature commit(s)`);
+    }
+    console.log('');
+
+    const confirmed = await promptConfirmation(
+        'Reset RC to origin/main, commit, and force-push?',
+        true
+    );
+    if (!confirmed) {
+        showInfo('Cancelled');
+        process.exit(0);
+    }
+
+    console.log('');
+
+    try {
+        // ── Step 7: git reset --soft origin/main ─────────────────────────────
+
+        showInfo('Resetting to origin/main (--soft)...');
+        resetBranch('origin/main', { mode: 'soft' });
+        showSuccess('✓ Soft reset complete — all changes staged');
+        console.log('');
+
+        // ── Step 8: Commit with subject + body ───────────────────────────────
+
+        showInfo('Creating release commit...');
+        const bodySection =
+            featureList.length > 0
+                ? `\nIncludes:\n${featureList.map((f) => `- ${f}`).join('\n')}\n`
+                : '';
+        const fullMessage = `${commitTitle}${bodySection}`;
+
+        try {
+            execSync('git commit --no-verify -F -', {
+                input: fullMessage,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'pipe']
+            });
+        } catch (e) {
+            error(`Failed to create commit: ${e.stderr || e.message}`);
+            process.exit(1);
+        }
+
+        showSuccess(`✓ Committed: "${commitTitle}"`);
+        console.log('');
+
+        // ── Step 9: Force-push with lease ────────────────────────────────────
+
+        showInfo(`Force-pushing ${rcBranch}...`);
+        const pushResult = forcePush(rcBranch, { lease: true });
+        if (!pushResult.success) {
+            error(
+                `Force-push failed: ${pushResult.error}\n` +
+                    `  Manual push:  git push --force-with-lease origin ${rcBranch}`
+            );
+            process.exit(1);
+        }
+        showSuccess(`✓ Force-pushed ${rcBranch}`);
+        console.log('');
+
+        // ── Step 10: Create PR to main ───────────────────────────────────────
+
+        let prUrl = null;
+        if (!options.noPr) {
+            showInfo('Creating PR to main...');
+
+            const { createPullRequest, validateToken } = await import('../utils/github-api.js');
+            const { parseGitHubRepo } = await import('../utils/github-client.js');
+
+            const tokenValidation = await validateToken();
+            if (!tokenValidation.valid) {
+                showWarning(`GitHub token invalid — PR not created: ${tokenValidation.error}`);
+                console.log('');
+                console.log('Create the PR manually:');
+                console.log(
+                    `  gh pr create --base ${TARGET_BRANCH} --head ${rcBranch} --label "${MERGE_COMMIT_LABEL}"`
+                );
+            } else {
+                const repoInfo = parseGitHubRepo();
+                const featureSection =
+                    featureList.length > 0
+                        ? featureList.map((f) => `- ${f}`).join('\n')
+                        : '_No commits listed_';
+                const prBody = `${MERGE_COMMIT_REMINDER}## Includes\n\n${featureSection}`;
+
+                try {
+                    const pr = await createPullRequest({
+                        owner: repoInfo.owner,
+                        repo: repoInfo.repo,
+                        title: commitTitle,
+                        body: prBody,
+                        head: rcBranch,
+                        base: TARGET_BRANCH,
+                        labels: [MERGE_COMMIT_LABEL]
+                    });
+                    prUrl = pr.html_url;
+                    showSuccess(`✓ PR created: ${prUrl}`);
+                } catch (e) {
+                    showWarning(`PR creation failed: ${e.message}`);
+                    console.log('');
+                    console.log('Create the PR manually:');
+                    console.log(
+                        `  gh pr create --base ${TARGET_BRANCH} --head ${rcBranch} --label "${MERGE_COMMIT_LABEL}"`
+                    );
+                }
+            }
+            console.log('');
+        }
+
+        // ── Step 11: Summary ─────────────────────────────────────────────────
+
+        console.log(
+            `${colors.green}════════════════════════════════════════════════════${colors.reset}`
+        );
+        console.log(
+            `${colors.green}           Release Candidate Closed ✅               ${colors.reset}`
+        );
+        console.log(
+            `${colors.green}════════════════════════════════════════════════════${colors.reset}`
+        );
+        console.log('');
+        console.log(`${colors.blue}Branch:${colors.reset}  ${rcBranch}`);
+        console.log(`${colors.blue}Version:${colors.reset} v${version}`);
+        console.log(`${colors.blue}Commit:${colors.reset}  "${commitTitle}"`);
+        console.log(`${colors.blue}Push:${colors.reset}    force-pushed ✓`);
+        if (!options.noPr) {
+            console.log(
+                `${colors.blue}PR:${colors.reset}      ${prUrl || '(failed — create manually)'}`
+            );
+            console.log('');
+            console.log(
+                `${colors.yellow}⚠️  Merge this PR using MERGE COMMIT (not squash)${colors.reset}`
+            );
+        }
+        console.log('');
+    } catch (e) {
+        logger.error('close-release', 'Command failed unexpectedly', e);
+        error(`close-release failed: ${e.message}`);
+        process.exit(1);
+    }
+}