claude-git-hooks 2.12.0 → 2.14.1

package/lib/utils/git-operations.js

@@ -13,8 +13,10 @@
  */
 
 import { execSync } from 'child_process';
+import fs from 'fs';
 import path from 'path';
 import logger from './logger.js';
+import { sanitizeBranchName } from './sanitize.js';
 
 /**
  * Custom error for git operation failures
@@ -130,6 +132,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 +578,122 @@ 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'
+        };
+    }
+};
+
+/**
+ * Stages files for commit
+ * Why: Prepares specific files for git commit (used by version bumping, changelog generation)
+ *
+ * @param {Array<string>} filePaths - Array of absolute file paths to stage
+ * @returns {Object} Result: { success: boolean, stagedFiles: Array<string>, error: string }
+ */
+const stageFiles = (filePaths) => {
+    logger.debug('git-operations - stageFiles', 'Staging files', { count: filePaths.length });
+
+    if (!Array.isArray(filePaths) || filePaths.length === 0) {
+        logger.warning('git-operations - stageFiles', 'No files provided');
+        return {
+            success: false,
+            stagedFiles: [],
+            error: 'No files provided to stage'
+        };
+    }
+
+    try {
+        const repoRoot = getRepoRoot();
+        const stagedFiles = [];
+
+        // Stage each file individually for granular error handling
+        for (const filePath of filePaths) {
+            // Convert to repo-relative path
+            const relativePath = path.relative(repoRoot, filePath);
+
+            // Verify file exists
+            if (!fs.existsSync(filePath)) {
+                logger.warning('git-operations - stageFiles', 'File not found, skipping', { filePath });
+                continue;
+            }
+
+            try {
+                execGitCommand(`add "${relativePath}"`);
+                stagedFiles.push(filePath);
+                logger.debug('git-operations - stageFiles', 'File staged', { relativePath });
+            } catch (error) {
+                logger.warning('git-operations - stageFiles', 'Failed to stage file', {
+                    filePath,
+                    error: error.message
+                });
+                // Continue staging other files
+            }
+        }
+
+        if (stagedFiles.length === 0) {
+            return {
+                success: false,
+                stagedFiles: [],
+                error: 'No files were successfully staged'
+            };
+        }
+
+        logger.debug('git-operations - stageFiles', 'Files staged successfully', {
+            count: stagedFiles.length
+        });
+
+        return {
+            success: true,
+            stagedFiles,
+            error: ''
+        };
+
+    } catch (error) {
+        logger.error('git-operations - stageFiles', 'Staging failed', error);
+
+        return {
+            success: false,
+            stagedFiles: [],
+            error: error.message || 'Unknown staging error'
+        };
+    }
+};
+
 /**
  * Pushes branch to remote
  * Why: Publishes local branch to remote before creating PR
@@ -537,9 +741,332 @@ const pushBranch = (branchName, { setUpstream = false } = {}) => {
     }
 };
 
+/**
+ * Fetches latest from remote
+ * Why: Ensures local git has up-to-date remote refs before comparing branches
+ *
+ * @param {string} [remoteName='origin'] - Remote name
+ */
+const fetchRemote = (remoteName = 'origin') => {
+    logger.debug('git-operations - fetchRemote', 'Fetching from remote', { remoteName });
+
+    // Sanitize remote name
+    const sanitizedRemote = sanitizeBranchName(remoteName);
+    if (!sanitizedRemote) {
+        throw new GitError('Invalid remote name', { command: 'fetch', output: remoteName });
+    }
+
+    try {
+        execGitCommand(`fetch ${sanitizedRemote}`);
+        logger.debug('git-operations - fetchRemote', 'Fetch successful', { remoteName: sanitizedRemote });
+    } catch (error) {
+        logger.error('git-operations - fetchRemote', 'Fetch failed', error);
+        throw new GitError('Failed to fetch from remote', {
+            command: `git fetch ${sanitizedRemote}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Checks if a branch reference exists
+ * Why: Validates branch refs before attempting operations to avoid failures
+ *
+ * @param {string} branchRef - Branch reference to verify (e.g., 'origin/main')
+ * @returns {boolean}
+ */
+const branchExists = (branchRef) => {
+    logger.debug('git-operations - branchExists', 'Checking if branch exists', { branchRef });
+
+    // Sanitize branch reference
+    const sanitizedRef = sanitizeBranchName(branchRef);
+    if (!sanitizedRef) {
+        logger.debug('git-operations - branchExists', 'Invalid branch reference', { branchRef });
+        return false;
+    }
+
+    try {
+        // Why: rev-parse --verify exits with 0 if ref exists, non-zero otherwise
+        // Why execSync instead of execGitCommand: Expected failures should not log at error level.
+        // branchExists() is a probe — failure is a valid outcome, not an error.
+        execSync(`git rev-parse --verify ${sanitizedRef}`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        logger.debug('git-operations - branchExists', 'Branch exists', { branchRef: sanitizedRef });
+        return true;
+    } catch (error) {
+        logger.debug('git-operations - branchExists', 'Branch does not exist', { branchRef: sanitizedRef });
+        return false;
+    }
+};
+
+/**
+ * Gets remote branch names (stripped of remote prefix)
+ * Why: Used by resolveBaseBranch to suggest similar branches
+ *
+ * @param {string} [remoteName='origin'] - Remote name
+ * @returns {string[]} Branch names without remote prefix
+ */
+const getRemoteBranches = (remoteName = 'origin') => {
+    try {
+        const output = execSync(`git branch -r --list "${remoteName}/*"`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+
+        if (!output) return [];
+
+        return output
+            .split(/\r?\n/)
+            .map(line => line.trim())
+            .filter(line => !line.includes('->'))  // Skip HEAD -> origin/main
+            .map(line => line.replace(`${remoteName}/`, ''));
+    } catch {
+        return [];
+    }
+};
+
+/**
+ * Finds remote branches similar to the target by shared keywords
+ *
+ * @param {string} target - Branch name to match against
+ * @param {string[]} branches - Available branch names
+ * @returns {string[]} Similar branch names, sorted by relevance
+ */
+const findSimilarBranches = (target, branches) => {
+    const targetWords = target.toLowerCase().split(/[/\-_.]/).filter(w => w.length > 1);
+
+    const scored = branches
+        .map(branch => {
+            const branchWords = branch.toLowerCase().split(/[/\-_.]/).filter(w => w.length > 1);
+            const matches = targetWords.filter(tw => branchWords.some(bw => bw.includes(tw) || tw.includes(bw)));
+            return { branch, score: matches.length };
+        })
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score);
+
+    return scored.map(({ branch }) => branch);
+};
+
+/**
+ * Resolves base branch on remote.
+ * Verifies origin/{target} exists. If not, throws with suggestions
+ * of similar remote branches to help the user correct the name.
+ *
+ * @param {string} targetBranch - Requested base branch
+ * @returns {string} Resolved remote ref (e.g., 'origin/main')
+ * @throws {GitError} If branch not found (message includes suggestions)
+ */
+const resolveBaseBranch = (targetBranch) => {
+    logger.debug('git-operations - resolveBaseBranch', 'Resolving base branch', { targetBranch });
+
+    // Sanitize target branch
+    const sanitizedTarget = sanitizeBranchName(targetBranch);
+    if (!sanitizedTarget) {
+        throw new GitError('Invalid target branch name', { command: 'resolveBaseBranch', output: targetBranch });
+    }
+
+    // Try requested branch with origin/ prefix
+    const targetRef = `origin/${sanitizedTarget}`;
+    if (branchExists(targetRef)) {
+        logger.debug('git-operations - resolveBaseBranch', 'Target branch found', { ref: targetRef });
+        return targetRef;
+    }
+
+    // Branch not found — build helpful error with suggestions
+    const remoteBranches = getRemoteBranches();
+    const similar = findSimilarBranches(sanitizedTarget, remoteBranches);
+
+    let suggestion = '';
+    if (similar.length > 0) {
+        const shown = similar.slice(0, 5);
+        suggestion = `\n\nSimilar branches on remote:\n${shown.map(b => `  - ${b}`).join('\n')}`;
+    } else if (remoteBranches.length > 0) {
+        const shown = remoteBranches.slice(0, 10);
+        suggestion = `\n\nAvailable branches on remote:\n${shown.map(b => `  - ${b}`).join('\n')}`;
+        if (remoteBranches.length > 10) {
+            suggestion += `\n  ... and ${remoteBranches.length - 10} more`;
+        }
+    }
+
+    throw new GitError(`Branch '${sanitizedTarget}' not found on remote${suggestion}`, {
+        command: 'resolveBaseBranch',
+        output: `target: ${targetBranch}`
+    });
+};
+
+/**
+ * Gets list of files changed between two refs
+ * Why: Shows which files differ between branches for PR context
+ *
+ * @param {string} baseRef - Base reference (e.g., 'origin/main')
+ * @param {string} [headRef='HEAD'] - Head reference
+ * @returns {string[]} Array of changed file paths
+ */
+const getChangedFilesBetweenRefs = (baseRef, headRef = 'HEAD') => {
+    logger.debug('git-operations - getChangedFilesBetweenRefs', 'Getting changed files', { baseRef, headRef });
+
+    // Sanitize refs
+    const sanitizedBase = sanitizeBranchName(baseRef);
+    const sanitizedHead = sanitizeBranchName(headRef);
+
+    if (!sanitizedBase || !sanitizedHead) {
+        throw new GitError('Invalid branch reference', {
+            command: 'getChangedFilesBetweenRefs',
+            output: `base: ${baseRef}, head: ${headRef}`
+        });
+    }
+
+    try {
+        // Why: --name-only shows just file paths, ... compares merge-base to head
+        const output = execGitCommand(`diff --name-only ${sanitizedBase}...${sanitizedHead}`);
+
+        if (!output) {
+            logger.debug('git-operations - getChangedFilesBetweenRefs', 'No changed files', { baseRef, headRef });
+            return [];
+        }
+
+        const files = output.split(/\r?\n/).filter(f => f.length > 0);
+
+        logger.debug('git-operations - getChangedFilesBetweenRefs', 'Changed files retrieved', {
+            baseRef,
+            headRef,
+            fileCount: files.length
+        });
+
+        return files;
+
+    } catch (error) {
+        logger.error('git-operations - getChangedFilesBetweenRefs', 'Failed to get changed files', error);
+        throw new GitError('Failed to get changed files between refs', {
+            command: `git diff --name-only ${sanitizedBase}...${sanitizedHead}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Gets full diff between two refs.
+ *
+ * Complements the existing getFileDiff() which operates on a single file's
+ * staged/unstaged diff (git diff [--cached] -- <file>). This function operates
+ * on the comparison between two branch refs (git diff origin/main...HEAD) —
+ * the branch-level counterpart that is currently missing, which is why both
+ * analyze-diff.js and create-pr.js resort to raw execSync.
+ *
+ * Returns the raw diff string. Truncation/reduction is handled by
+ * buildDiffPayload() in pr-metadata-engine.js, not here.
+ *
+ * @param {string} baseRef - Base reference
+ * @param {string} [headRef='HEAD'] - Head reference
+ * @param {Object} [options]
+ * @param {number} [options.contextLines=3] - Lines of context around changes (-U flag)
+ * @returns {string} Raw unified diff
+ */
+const getDiffBetweenRefs = (baseRef, headRef = 'HEAD', { contextLines = 3 } = {}) => {
+    logger.debug('git-operations - getDiffBetweenRefs', 'Getting diff between refs', {
+        baseRef,
+        headRef,
+        contextLines
+    });
+
+    // Sanitize refs
+    const sanitizedBase = sanitizeBranchName(baseRef);
+    const sanitizedHead = sanitizeBranchName(headRef);
+
+    if (!sanitizedBase || !sanitizedHead) {
+        throw new GitError('Invalid branch reference', {
+            command: 'getDiffBetweenRefs',
+            output: `base: ${baseRef}, head: ${headRef}`
+        });
+    }
+
+    try {
+        // Why: -U flag sets context lines, ... compares merge-base to head
+        const contextFlag = `-U${contextLines}`;
+        const output = execGitCommand(`diff ${contextFlag} ${sanitizedBase}...${sanitizedHead}`);
+
+        logger.debug('git-operations - getDiffBetweenRefs', 'Diff retrieved', {
+            baseRef,
+            headRef,
+            contextLines,
+            diffSize: output.length
+        });
+
+        return output;
+
+    } catch (error) {
+        logger.error('git-operations - getDiffBetweenRefs', 'Failed to get diff', error);
+        throw new GitError('Failed to get diff between refs', {
+            command: `git diff -U${contextLines} ${sanitizedBase}...${sanitizedHead}`,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Gets commit log between two refs
+ * Why: Shows commit history for PR description and context
+ *
+ * @param {string} baseRef - Base reference
+ * @param {string} [headRef='HEAD'] - Head reference
+ * @param {Object} [options]
+ * @param {string} [options.format='oneline'] - Git log format
+ * @returns {string} Commit log output
+ */
+const getCommitsBetweenRefs = (baseRef, headRef = 'HEAD', { format = 'oneline' } = {}) => {
+    logger.debug('git-operations - getCommitsBetweenRefs', 'Getting commits between refs', {
+        baseRef,
+        headRef,
+        format
+    });
+
+    // Sanitize refs
+    const sanitizedBase = sanitizeBranchName(baseRef);
+    const sanitizedHead = sanitizeBranchName(headRef);
+
+    if (!sanitizedBase || !sanitizedHead) {
+        throw new GitError('Invalid branch reference', {
+            command: 'getCommitsBetweenRefs',
+            output: `base: ${baseRef}, head: ${headRef}`
+        });
+    }
+
+    try {
+        // Why: --format specifies output format, ... shows commits on head not on base
+        const output = execGitCommand(`log --format=${format} ${sanitizedBase}...${sanitizedHead}`);
+
+        if (!output) {
+            logger.debug('git-operations - getCommitsBetweenRefs', 'No commits found', { baseRef, headRef });
+            return '';
+        }
+
+        const commitCount = output.split(/\r?\n/).filter(line => line.length > 0).length;
+
+        logger.debug('git-operations - getCommitsBetweenRefs', 'Commits retrieved', {
+            baseRef,
+            headRef,
+            format,
+            commitCount
+        });
+
+        return output;
+
+    } catch (error) {
+        logger.error('git-operations - getCommitsBetweenRefs', 'Failed to get commits', error);
+        throw new GitError('Failed to get commits between refs', {
+            command: `git log --format=${format} ${sanitizedBase}...${sanitizedHead}`,
+            cause: error
+        });
+    }
+};
+
 export {
     GitError,
     getStagedFiles,
+    getUnstagedFiles,
+    getAllTrackedFiles,
     getFileDiff,
     getFileContentFromStaging,
     isNewFile,
@@ -550,5 +1077,14 @@ export {
     getRemoteName,
     verifyRemoteExists,
     getBranchPushStatus,
-    pushBranch
+    pushBranch,
+    stageFiles,
+    createCommit,
+    fetchRemote,
+    branchExists,
+    getRemoteBranches,
+    resolveBaseBranch,
+    getChangedFilesBetweenRefs,
+    getDiffBetweenRefs,
+    getCommitsBetweenRefs
 };

package/lib/utils/git-tag-manager.js

@@ -65,16 +65,35 @@ function execGitTagCommand(command) {
     }
 }
 
+/**
+ * Checks if a tag is a valid semver tag
+ * Why: Filter out non-version tags (Docker tags, etc.)
+ *
+ * @param {string} tagName - Tag name to check
+ * @returns {boolean} True if tag matches semver pattern
+ */
+export function isSemverTag(tagName) {
+    // Match: v1.2.3, 1.2.3, v1.2.3-SNAPSHOT, 1.2.3-RC1, etc.
+    const semverPattern = /^v?\d+\.\d+\.\d+(-[\w.]+)?$/;
+    return semverPattern.test(tagName);
+}
+
 /**
  * Parses tag name to extract version
  * Why: Tags have 'v' prefix (v2.7.0), need clean version
  *
  * @param {string} tagName - Tag name (e.g., "v2.7.0-SNAPSHOT")
- * @returns {string} Version without 'v' prefix
+ * @returns {string|null} Version without 'v' prefix, or null if not a semver tag
  */
 export function parseTagVersion(tagName) {
     logger.debug('git-tag-manager - parseTagVersion', 'Parsing tag version', { tagName });
 
+    // Check if it's a valid semver tag first
+    if (!isSemverTag(tagName)) {
+        logger.debug('git-tag-manager - parseTagVersion', 'Not a semver tag, skipping', { tagName });
+        return null;
+    }
+
     // Remove 'v' prefix if present
     const version = tagName.replace(/^v/, '');
 
@@ -136,7 +155,7 @@ export function getLocalTags() {
  * Gets latest local tag (by version order)
  * Why: Determines current version for alignment checks
  *
- * @returns {string|null} Latest tag name or null if no tags
+ * @returns {string|null} Latest semver tag name or null if no tags
  */
 export function getLatestLocalTag() {
     logger.debug('git-tag-manager - getLatestLocalTag', 'Getting latest local tag');
@@ -151,9 +170,24 @@ export function getLatestLocalTag() {
         }
 
         const tags = output.split(/\r?\n/).filter(t => t.length > 0);
-        const latestTag = tags[0] || null;
 
-        logger.debug('git-tag-manager - getLatestLocalTag', 'Latest tag found', { latestTag });
+        // Filter to only semver tags
+        const semverTags = tags.filter(isSemverTag);
+
+        if (semverTags.length === 0) {
+            logger.debug('git-tag-manager - getLatestLocalTag', 'No semver tags found', {
+                totalTags: tags.length
+            });
+            return null;
+        }
+
+        const latestTag = semverTags[0];
+
+        logger.debug('git-tag-manager - getLatestLocalTag', 'Latest semver tag found', {
+            latestTag,
+            totalTags: tags.length,
+            semverTags: semverTags.length
+        });
 
         return latestTag;
 
@@ -214,7 +248,7 @@ export async function getRemoteTags(remoteName = null) {
  * Why: Compare local version with deployed version
  *
  * @param {string} remoteName - Remote name (default: 'origin')
- * @returns {Promise<string|null>} Latest tag name or null
+ * @returns {Promise<string|null>} Latest semver tag name or null
  */
 export async function getLatestRemoteTag(remoteName = null) {
     logger.debug('git-tag-manager - getLatestRemoteTag', 'Getting latest remote tag');
@@ -227,12 +261,24 @@ export async function getLatestRemoteTag(remoteName = null) {
             return null;
         }
 
+        // Filter to only semver tags
+        const semverTags = tags.filter(isSemverTag);
+
+        if (semverTags.length === 0) {
+            logger.debug('git-tag-manager - getLatestRemoteTag', 'No semver tags found', {
+                totalTags: tags.length
+            });
+            return null;
+        }
+
         // Sort tags by version (descending)
-        // Why: Reuse compareVersions for consistency and maintainability
-        const sortedTags = tags.sort((a, b) => {
+        const sortedTags = semverTags.sort((a, b) => {
             const versionA = parseTagVersion(a);
             const versionB = parseTagVersion(b);
 
+            // Both should be valid since we filtered, but check anyway
+            if (!versionA || !versionB) return 0;
+
             try {
                 // compareVersions returns: 1 if a > b, -1 if a < b, 0 if equal
                 // For descending sort, we need to reverse the comparison
@@ -250,7 +296,11 @@ export async function getLatestRemoteTag(remoteName = null) {
 
         const latestTag = sortedTags[0];
 
-        logger.debug('git-tag-manager - getLatestRemoteTag', 'Latest remote tag found', { latestTag });
+        logger.debug('git-tag-manager - getLatestRemoteTag', 'Latest remote semver tag found', {
+            latestTag,
+            totalTags: tags.length,
+            semverTags: semverTags.length
+        });
 
         return latestTag;