claude-git-hooks 2.1.0 → 2.3.0

package/lib/utils/prompt-builder.js

@@ -38,14 +38,22 @@ class PromptBuilderError extends Error {
  * Why absolute path: Ensures templates are found regardless of cwd (cross-platform)
  *
  * @param {string} templateName - Name of template file
- * @param {string} baseDir - Base directory (default: .claude)
+ * @param {string} baseDir - Base directory (default: try .claude, fallback to templates)
  * @returns {Promise<string>} Template content
  * @throws {PromptBuilderError} If template not found
  */
 const loadTemplate = async (templateName, baseDir = '.claude') => {
     // Why: Use repo root for absolute path (works on Windows/PowerShell/Git Bash)
     const repoRoot = getRepoRoot();
-    const templatePath = path.join(repoRoot, baseDir, templateName);
+    let templatePath = path.join(repoRoot, baseDir, templateName);
+
+    // Try .claude first, fallback to templates/ if not found
+    try {
+        await fs.access(templatePath);
+    } catch {
+        // Try templates/ directory as fallback
+        templatePath = path.join(repoRoot, 'templates', templateName);
+    }
 
     logger.debug(
         'prompt-builder - loadTemplate',
@@ -104,6 +112,57 @@ const replaceTemplate = (template, variables) => {
     }, template);
 };
 
+/**
+ * Loads a prompt template and replaces variables
+ * Why: High-level interface that combines loading and variable replacement
+ *
+ * @param {string} templateName - Name of template file
+ * @param {Object} variables - Variables to replace in template
+ * @param {string} baseDir - Base directory (default: .claude)
+ * @returns {Promise<string>} Prompt with replaced variables
+ * @throws {PromptBuilderError} If template not found
+ *
+ * Example:
+ * const prompt = await loadPrompt('COMMIT_MESSAGE.md', {
+ *   FILE_LIST: 'file1.js\nfile2.js',
+ *   FILE_COUNT: 2,
+ *   INSERTIONS: 10,
+ *   DELETIONS: 5
+ * });
+ */
+const loadPrompt = async (templateName, variables = {}, baseDir = '.claude') => {
+    logger.debug(
+        'prompt-builder - loadPrompt',
+        'Loading prompt with variables',
+        { templateName, variableCount: Object.keys(variables).length }
+    );
+
+    try {
+        // Load template
+        const template = await loadTemplate(templateName, baseDir);
+
+        // Replace variables
+        const prompt = replaceTemplate(template, variables);
+
+        logger.debug(
+            'prompt-builder - loadPrompt',
+            'Prompt loaded successfully',
+            { templateName, promptLength: prompt.length }
+        );
+
+        return prompt;
+
+    } catch (error) {
+        logger.error(
+            'prompt-builder - loadPrompt',
+            `Failed to load prompt: ${templateName}`,
+            error
+        );
+
+        throw error;
+    }
+};
+
 /**
  * Formats file information for prompt
  * Why: Structures file data in readable format for Claude
@@ -144,6 +203,7 @@ const formatFileSection = ({ path, diff, content, isNew }) => {
  * @param {string} options.guidelinesName - Guidelines filename
  * @param {Array<Object>} options.files - Array of file data objects
  * @param {Object} options.metadata - Additional metadata (repo name, branch, etc.)
+ * @param {Object} options.subagentConfig - Subagent configuration (optional)
  * @returns {Promise<string>} Complete analysis prompt
  *
  * File data object structure:
@@ -158,12 +218,13 @@ const buildAnalysisPrompt = async ({
     templateName = 'CLAUDE_ANALYSIS_PROMPT_SONAR.md',
     guidelinesName = 'CLAUDE_PRE_COMMIT_SONAR.md',
     files = [],
-    metadata = {}
+    metadata = {},
+    subagentConfig = null
 } = {}) => {
     logger.debug(
         'prompt-builder - buildAnalysisPrompt',
         'Building analysis prompt',
-        { templateName, guidelinesName, fileCount: files.length }
+        { templateName, guidelinesName, fileCount: files.length, subagentsEnabled: subagentConfig?.enabled }
     );
 
     try {
@@ -176,6 +237,22 @@ const buildAnalysisPrompt = async ({
         // Start with template
         let prompt = template;
 
+        // Add subagent instruction if enabled and 3+ files
+        if (subagentConfig?.enabled && files.length >= 3) {
+            try {
+                const subagentInstruction = await loadTemplate('SUBAGENT_INSTRUCTION.md');
+                const subagentVariables = {
+                    BATCH_SIZE: subagentConfig.batchSize || 3,
+                    MODEL: subagentConfig.model || 'haiku'
+                };
+                prompt += '\n\n' + replaceTemplate(subagentInstruction, subagentVariables) + '\n';
+
+                logger.info(`🚀 Batch optimization enabled: ${files.length} files, ${subagentVariables.BATCH_SIZE} per batch, ${subagentVariables.MODEL} model`);
+            } catch (error) {
+                logger.warning('Subagent instruction template not found, proceeding without parallel analysis');
+            }
+        }
+
         // Add guidelines section
         prompt += '\n\n=== EVALUATION GUIDELINES ===\n';
         prompt += guidelines;
@@ -212,72 +289,11 @@ const buildAnalysisPrompt = async ({
     }
 };
 
-/**
- * Builds commit message generation prompt
- * Why: Used by prepare-commit-msg hook
- *
- * @param {Object} options - Build options
- * @param {Array<Object>} options.files - Array of changed files with diffs
- * @param {Object} options.stats - Staging statistics
- * @returns {Promise<string>} Complete commit message prompt
- *
- * Stats object structure:
- * {
- *   totalFiles: number,
- *   addedFiles: number,
- *   modifiedFiles: number,
- *   deletedFiles: number,
- *   insertions: number,
- *   deletions: number
- * }
- */
-const buildCommitMessagePrompt = async ({ files = [], stats = {} } = {}) => {
-    logger.debug(
-        'prompt-builder - buildCommitMessagePrompt',
-        'Building commit message prompt',
-        { fileCount: files.length, stats }
-    );
-
-    let prompt = `Generate a conventional commit message for the following changes.\n\n`;
-
-    // Add statistics
-    prompt += `=== STATISTICS ===\n`;
-    prompt += `Files changed: ${stats.totalFiles || files.length}\n`;
-    prompt += `Added: ${stats.addedFiles || 0}, Modified: ${stats.modifiedFiles || 0}, Deleted: ${stats.deletedFiles || 0}\n`;
-    prompt += `Insertions: ${stats.insertions || 0}, Deletions: ${stats.deletions || 0}\n\n`;
-
-    // Add file changes
-    prompt += `=== CHANGED FILES ===\n`;
-    files.forEach(({ path, diff }) => {
-        prompt += `\n--- ${path} ---\n`;
-        if (diff) {
-            prompt += `${diff}\n`;
-        }
-    });
-
-    // Add instructions
-    prompt += `\n\n=== INSTRUCTIONS ===\n`;
-    prompt += `Generate a concise commit message following Conventional Commits format:\n`;
-    prompt += `- type: feat, fix, docs, style, refactor, test, chore\n`;
-    prompt += `- Format: "type: description" or "type(scope): description"\n`;
-    prompt += `- Description: Clear, imperative mood, no period at end\n`;
-    prompt += `- Optional body: Detailed explanation if needed\n\n`;
-    prompt += `Respond with ONLY the commit message, no explanations.\n`;
-
-    logger.debug(
-        'prompt-builder - buildCommitMessagePrompt',
-        'Commit message prompt built',
-        { promptLength: prompt.length }
-    );
-
-    return prompt;
-};
-
 export {
     PromptBuilderError,
     loadTemplate,
     replaceTemplate,
+    loadPrompt,
     formatFileSection,
-    buildAnalysisPrompt,
-    buildCommitMessagePrompt
+    buildAnalysisPrompt
 };

package/lib/utils/resolution-prompt.js

@@ -179,14 +179,20 @@ ${content}
 const generateResolutionPrompt = async (
     analysisResult,
     {
-        outputPath = 'claude_resolution_prompt.md',
+        outputPath = null,
         templatePath = '.claude/CLAUDE_RESOLUTION_PROMPT.md',
         fileCount = 0
     } = {}
 ) => {
     // Why: Use repo root for absolute paths (works on Windows/PowerShell/Git Bash)
     const repoRoot = getRepoRoot();
-    const absoluteOutputPath = path.join(repoRoot, outputPath);
+
+    // Load config to get default output path
+    const { getConfig } = await import('../config.js');
+    const config = await getConfig();
+    const finalOutputPath = outputPath || config.output.resolutionFile;
+
+    const absoluteOutputPath = path.join(repoRoot, finalOutputPath);
     const absoluteTemplatePath = path.join(repoRoot, templatePath);
 
     logger.debug(
@@ -226,6 +232,10 @@ const generateResolutionPrompt = async (
             .replace(/{{BLOCKING_ISSUES}}/g, issuesFormatted)
             .replace(/{{FILE_CONTENTS}}/g, fileContentsFormatted);
 
+        // Ensure output directory exists
+        const outputDir = path.dirname(absoluteOutputPath);
+        await fs.mkdir(outputDir, { recursive: true });
+
         // Write resolution prompt file
         await fs.writeFile(absoluteOutputPath, prompt, 'utf8');
 

package/package.json

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

package/templates/ANALYZE_DIFF.md

@@ -0,0 +1,33 @@
+Analyze the following changes. CONTEXT: {{CONTEXT_DESCRIPTION}}
+{{SUBAGENT_INSTRUCTION}}
+Please generate:
+1. A concise and descriptive PR title (maximum 72 characters)
+2. A detailed PR description that includes:
+   - Summary of changes
+   - Motivation/context
+   - Type of change (feature/fix/refactor/docs/etc)
+   - Recommended testing
+3. A suggested branch name following the format: type/short-description (example: feature/add-user-auth, fix/memory-leak)
+
+IMPORTANT: If these are local changes without push, the suggested branch name should be for creating a new branch from the current one.
+
+Respond EXCLUSIVELY with a valid JSON with this structure:
+```json
+{
+  "prTitle": "Interesting PR title",
+  "prDescription": "detailed PR description with markdown",
+  "suggestedBranchName": "type/suggested-branch-name",
+  "changeType": "feature|fix|refactor|docs|test|chore",
+  "breakingChanges": false,
+  "testingNotes": "notes on necessary testing or 'None'"
+}
+```
+
+## COMMITS
+{{COMMITS}}
+
+## CHANGED FILES
+{{DIFF_FILES}}
+
+## FULL DIFF
+{{FULL_DIFF}}

package/templates/COMMIT_MESSAGE.md

@@ -0,0 +1,24 @@
+Analyze the following changes and generate a commit message following the Conventional Commits format.
+
+Respond ONLY with a valid JSON:
+
+```json
+{
+  "type": "feat|fix|docs|style|refactor|test|chore|ci|perf",
+  "scope": "optional scope (e.g.: api, frontend, db)",
+  "title": "short description in present tense (max 50 chars)",
+  "body": "optional detailed description"
+}
+```
+
+## CHANGES TO ANALYZE
+
+### Modified files:
+{{FILE_LIST}}
+
+### Summary of changes:
+Files changed: {{FILE_COUNT}}
+Insertions: {{INSERTIONS}}, Deletions: {{DELETIONS}}
+
+### Detailed diffs:
+{{FILE_DIFFS}}

package/templates/SUBAGENT_INSTRUCTION.md

@@ -0,0 +1 @@
+IMPORTANT OPTIMIZATION: When analyzing multiple files (3+), mentally organize your analysis into focused batches of {{BATCH_SIZE}} files at a time. This helps maintain quality while processing efficiently. For each file, perform thorough analysis following all guidelines and OUTPUT_SCHEMA requirements. After analyzing all files, consolidate into SINGLE JSON response: (1) merge all blockingIssues arrays, (2) merge all details arrays, (3) sum issue counts across all files, (4) worst-case metrics (lowest rating found), (5) QUALITY_GATE=FAILED if ANY file has blockers/criticals, (6) approved=false if any file is disapproved. Your response must be a single consolidated JSON object, not separate results per file.

package/templates/config.example.json

@@ -0,0 +1,41 @@
+{
+  "preset": null,
+  "analysis": {
+    "maxFileSize": 100000,
+    "maxFiles": 10,
+    "timeout": 120000,
+    "contextLines": 3,
+    "ignoreExtensions": []
+  },
+  "commitMessage": {
+    "autoKeyword": "auto",
+    "timeout": 180000
+  },
+  "subagents": {
+    "enabled": true,
+    "model": "haiku",
+    "batchSize": 3
+  },
+  "templates": {
+    "baseDir": ".claude",
+    "analysis": "CLAUDE_ANALYSIS_PROMPT_SONAR.md",
+    "guidelines": "CLAUDE_PRE_COMMIT_SONAR.md",
+    "commitMessage": "COMMIT_MESSAGE.md",
+    "analyzeDiff": "ANALYZE_DIFF.md",
+    "resolution": "CLAUDE_RESOLUTION_PROMPT.md",
+    "subagentInstruction": "SUBAGENT_INSTRUCTION.md"
+  },
+  "output": {
+    "outputDir": ".claude/out",
+    "debugFile": ".claude/out/debug-claude-response.json",
+    "resolutionFile": ".claude/out/claude_resolution_prompt.md",
+    "prAnalysisFile": ".claude/out/pr-analysis.json"
+  },
+  "system": {
+    "debug": false,
+    "wslCheckTimeout": 3000
+  },
+  "git": {
+    "diffFilter": "ACM"
+  }
+}

package/templates/presets/ai/ANALYSIS_PROMPT.md

@@ -0,0 +1,133 @@
+You are analyzing a **{{PRESET_NAME}}** project with the following technology stack:
+
+**Tech Stack:** {{TECH_STACK}}
+
+**Analyzing files matching:** {{FILE_EXTENSIONS}}
+
+## Your Task
+
+Perform a comprehensive code quality analysis focusing on these areas:
+
+{{FOCUS_AREAS}}
+
+## Analysis Guidelines
+
+1. **Claude API Best Practices**:
+   - Proper use of Claude API endpoints
+   - Correct model selection (haiku/sonnet/opus)
+   - Token usage optimization
+   - Error handling for API failures
+   - Rate limiting considerations
+   - Timeout handling
+
+2. **Prompt Engineering**:
+   - Clear and specific instructions
+   - Well-structured prompts
+   - Appropriate context inclusion
+   - Effective use of examples
+   - Proper output format specifications
+   - Token-efficient prompting
+
+3. **CLI User Experience**:
+   - Clear, helpful error messages
+   - Appropriate use of colors/formatting
+   - Progress indicators for long operations
+   - Helpful usage instructions
+   - Graceful error recovery
+   - Cross-platform compatibility
+
+4. **Git Operations**:
+   - Safe git command execution
+   - Proper error handling
+   - Repository state validation
+   - Avoiding destructive operations
+   - Cross-platform path handling
+
+5. **Security**:
+   - API key protection (never log/expose)
+   - Secure credential storage
+   - Input validation
+   - Avoiding command injection
+   - Sensitive data handling in prompts
+
+6. **Code Quality**:
+   - Proper error handling
+   - Comprehensive logging
+   - Modular, reusable functions
+   - Clear documentation
+   - Maintainable code structure
+
+## Specific Checks
+
+### Claude API Usage
+✅ Using appropriate model for task (haiku for simple, sonnet for complex)
+✅ Implementing proper error handling (network, API, rate limit)
+✅ Token usage calculated and optimized
+✅ Prompts are well-structured and clear
+✅ Output parsing is robust
+✅ API keys never logged or exposed
+
+### Git Operations
+✅ Using proper git commands
+✅ Handling errors gracefully
+✅ Cross-platform path compatibility
+✅ Avoiding destructive operations without confirmation
+✅ Proper handling of special characters in filenames
+
+### Template Quality
+✅ Clear instructions for Claude
+✅ Well-defined output format
+✅ Appropriate context provided
+✅ Token-efficient design
+✅ Placeholders used correctly
+
+## Output Format
+
+Respond with a valid JSON following the SonarQube format:
+
+```json
+{
+  "QUALITY_GATE": "PASSED|FAILED",
+  "approved": true|false,
+  "metrics": {
+    "reliability": "A|B|C|D|E",
+    "security": "A|B|C|D|E",
+    "maintainability": "A|B|C|D|E",
+    "coverage": 0-100,
+    "duplications": 0-100,
+    "complexity": "number"
+  },
+  "issues": {
+    "blocker": 0,
+    "critical": 0,
+    "major": 0,
+    "minor": 0,
+    "info": 0
+  },
+  "details": [
+    {
+      "severity": "BLOCKER|CRITICAL|MAJOR|MINOR|INFO",
+      "type": "BUG|VULNERABILITY|CODE_SMELL|PROMPT_QUALITY",
+      "file": "path/to/file",
+      "line": 123,
+      "message": "Clear description of the issue"
+    }
+  ],
+  "securityHotspots": 0,
+  "blockingIssues": ["List of critical issues that must be fixed"]
+}
+```
+
+## Analysis Rules
+
+- **Block commit** if:
+  - Exposed API keys or secrets
+  - Security vulnerabilities
+  - Critical bugs in git operations
+  - Destructive operations without safeguards
+
+- **Pass** if: Only minor issues, suggestions, or no issues
+
+- Be constructive about prompt quality - suggest improvements
+- Focus on safety and user experience
+- Provide actionable, specific feedback with line numbers