claude-git-hooks 2.0.0 → 2.3.0

package/templates/presets/ai/PRE_COMMIT_GUIDELINES.md

@@ -0,0 +1,176 @@
+# AI/CLI Code Quality Guidelines
+
+## Claude API Best Practices
+
+### Model Selection
+✅ **Haiku**: Simple tasks, fast responses, cost-effective
+✅ **Sonnet**: Balanced performance, most use cases
+✅ **Opus**: Complex reasoning, highest quality
+❌ Don't use Opus when Haiku would suffice
+
+### API Usage
+✅ Implement proper timeout handling
+✅ Handle rate limiting gracefully
+✅ Retry with exponential backoff on failures
+✅ Validate API responses before use
+✅ Log API errors (but never log API keys!)
+✅ Calculate and monitor token usage
+
+### Error Handling
+```javascript
+// ✅ Good
+try {
+    const response = await callClaudeAPI(prompt);
+    if (!response || !response.content) {
+        throw new Error('Invalid API response');
+    }
+    return parseResponse(response);
+} catch (error) {
+    if (error.status === 429) {
+        // Handle rate limiting
+    } else if (error.status === 500) {
+        // Handle server error
+    }
+    logger.error('API call failed', error);
+    throw new UserFriendlyError('Failed to analyze code');
+}
+```
+
+## Prompt Engineering
+
+### Structure
+✅ Clear role/context at the beginning
+✅ Specific task instructions
+✅ Well-defined output format (usually JSON)
+✅ Relevant examples when helpful
+✅ Appropriate length (token-efficient)
+
+### Quality Checklist
+✅ Instructions are unambiguous
+✅ Output format is machine-parseable
+✅ Context is sufficient but not excessive
+✅ Examples match expected usage
+✅ Placeholders are replaced correctly
+
+### Common Prompt Issues
+❌ Vague instructions
+❌ No output format specification
+❌ Too much unnecessary context
+❌ Ambiguous requirements
+❌ Missing examples for complex tasks
+
+## CLI User Experience
+
+### Error Messages
+✅ Clear, actionable error messages
+✅ Suggest solutions when possible
+✅ Use appropriate log levels
+✅ Color-code for readability (error=red, success=green)
+✅ Include context (what was being attempted)
+
+### User Feedback
+✅ Show progress for long operations
+✅ Confirm destructive operations
+✅ Provide helpful usage information
+✅ Display meaningful results
+✅ Log debug info only when debug mode enabled
+
+## Git Operations Safety
+
+### Safe Practices
+✅ Validate repository state before operations
+✅ Use `--cached` for staged changes
+✅ Handle special characters in filenames
+✅ Cross-platform path handling
+✅ Graceful handling of git errors
+
+### Dangerous Operations
+❌ Never run git commands that modify history without explicit user confirmation
+❌ Avoid hard resets
+❌ Be careful with force pushes
+❌ Validate before bulk operations
+
+## Security
+
+### API Keys
+✅ Load from environment variables
+✅ Never log or display API keys
+✅ Never commit API keys to repository
+✅ Use secure storage methods
+✅ Clear keys from memory when done
+
+### Command Injection
+✅ Validate all user input
+✅ Use parameterized commands when possible
+✅ Escape special characters
+✅ Avoid `eval()` and similar
+✅ Sanitize file paths
+
+### Sensitive Data
+✅ Don't send secrets to Claude API
+✅ Filter sensitive data from diffs
+✅ Be careful with error messages (don't expose internals)
+✅ Implement SKIP_ANALYSIS for sensitive code
+
+## Code Organization
+
+### File Structure
+```
+lib/
+  hooks/         # Git hook implementations
+  utils/         # Utility functions
+    claude-client.js
+    git-operations.js
+    file-operations.js
+    logger.js
+  config.js      # Configuration management
+templates/       # Prompt templates
+bin/            # CLI entry points
+```
+
+### Module Design
+✅ Single responsibility principle
+✅ Clear, descriptive function names
+✅ Comprehensive error handling
+✅ Proper logging at decision points
+✅ Export reusable functions
+
+## Common Issues to Avoid
+
+### Critical Issues
+❌ Exposed API keys or secrets
+❌ Command injection vulnerabilities
+❌ Destructive git operations without confirmation
+❌ Unhandled promise rejections
+
+### Major Issues
+❌ Missing error handling
+❌ Poor user experience (unclear errors)
+❌ Cross-platform incompatibility
+❌ Memory leaks (large file handling)
+❌ Missing input validation
+
+### Minor Issues
+❌ Insufficient logging
+❌ Unclear variable names
+❌ Missing documentation
+❌ Inefficient token usage
+❌ Poor code organization
+
+## Testing
+
+✅ Test with various input sizes
+✅ Test error scenarios (API failures, git errors)
+✅ Test cross-platform compatibility
+✅ Mock external dependencies (Claude API, git)
+✅ Test with edge cases (special characters, large files)
+✅ Verify token usage calculations
+
+## Documentation
+
+✅ Document API usage patterns
+✅ Explain prompt design decisions
+✅ Document configuration options
+✅ Provide usage examples
+✅ Keep README up to date
+✅ Document breaking changes

package/templates/presets/ai/config.json

@@ -0,0 +1,12 @@
+{
+  "analysis": {
+    "maxFileSize": 100000,
+    "maxFiles": 10,
+    "timeout": 120000
+  },
+  "subagents": {
+    "enabled": false,
+    "model": "sonnet",
+    "batchSize": 3
+  }
+}

package/templates/presets/ai/preset.json

@@ -0,0 +1,42 @@
+{
+  "name": "ai",
+  "displayName": "AI/CLI (Node.js + Claude)",
+  "description": "Node.js CLI tools with Claude API integration",
+  "version": "1.0.0",
+
+  "techStack": [
+    "Node.js",
+    "ES Modules",
+    "Claude API",
+    "CLI tools",
+    "Git hooks",
+    "Bash scripting",
+    "Markdown templates"
+  ],
+
+  "fileExtensions": [
+    ".js",
+    ".json",
+    ".md",
+    ".sh"
+  ],
+
+  "focusAreas": [
+    "Claude API usage and best practices",
+    "Prompt engineering quality",
+    "CLI user experience",
+    "Error handling and logging",
+    "Git operations safety",
+    "Cross-platform compatibility",
+    "Token usage optimization",
+    "Security (API keys, secrets)"
+  ],
+
+  "templates": {
+    "analysis": "ANALYSIS_PROMPT.md",
+    "guidelines": "PRE_COMMIT_GUIDELINES.md",
+    "commitMessage": "../shared/COMMIT_MESSAGE.md",
+    "analyzeDiff": "../shared/ANALYZE_DIFF.md",
+    "resolution": "../shared/RESOLUTION_PROMPT.md"
+  }
+}

package/templates/presets/backend/ANALYSIS_PROMPT.md

@@ -0,0 +1,85 @@
+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. **Security First**: Check for OWASP Top 10 vulnerabilities, especially:
+   - SQL injection risks
+   - Authentication/authorization flaws
+   - Sensitive data exposure
+   - XML external entities (XXE)
+   - Insecure deserialization
+
+2. **Spring Boot Best Practices**:
+   - Proper use of `@Transactional`
+   - Correct exception handling
+   - Appropriate use of DTOs vs Entities
+   - Proper dependency injection
+   - Configuration management
+
+3. **JPA/Hibernate**:
+   - N+1 query problems
+   - Lazy loading issues
+   - Proper use of relationships
+   - Query optimization
+   - Transaction boundaries
+
+4. **Code Quality**:
+   - SOLID principles
+   - DRY violations
+   - Proper error handling
+   - Logging best practices
+   - Test coverage
+
+## 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",
+      "file": "path/to/file.java",
+      "line": 123,
+      "message": "Clear description of the issue"
+    }
+  ],
+  "securityHotspots": 0,
+  "blockingIssues": ["List of critical issues that must be fixed"]
+}
+```
+
+## Analysis Rules
+
+- **Block commit** if: Security vulnerabilities, critical bugs, or blocker issues found
+- **Pass** if: Only minor issues, info messages, or no issues
+- Be strict but fair - focus on real problems, not style preferences
+- Provide actionable, specific feedback with line numbers

package/templates/presets/backend/PRE_COMMIT_GUIDELINES.md

@@ -0,0 +1,87 @@
+# Backend Code Quality Guidelines
+
+## Spring Boot Standards
+
+### Controllers
+- Use proper HTTP methods and status codes
+- Validate input with `@Valid`
+- Handle exceptions with `@ExceptionHandler`
+- Keep controllers thin - business logic in services
+- Use DTOs for API contracts
+
+### Services
+- Use `@Transactional` appropriately
+- Handle exceptions properly
+- Keep methods focused and small
+- Avoid business logic in controllers or repositories
+
+### Repositories
+- Extend appropriate Spring Data interfaces
+- Use method naming conventions for queries
+- Optimize queries with `@Query` when needed
+- Avoid N+1 problems with `@EntityGraph`
+
+### Entities
+- Use Lombok annotations appropriately
+- Define proper relationships (`@OneToMany`, `@ManyToOne`, etc.)
+- Use `@Version` for optimistic locking
+- Never expose entities in API - use DTOs
+
+## Security Requirements
+
+### Authentication & Authorization
+- Never hardcode credentials
+- Use Spring Security properly
+- Validate JWT tokens correctly
+- Check permissions before operations
+
+### Data Validation
+- Validate all user input
+- Use parameterized queries (JPA does this by default)
+- Sanitize data before logging
+- Never trust client-side validation alone
+
+### SQL Injection Prevention
+- Always use JPA/JPQL or prepared statements
+- Never concatenate SQL strings
+- Be careful with native queries
+- Use `@Query` with proper parameter binding
+
+## Performance
+
+### Database
+- Use pagination for large result sets
+- Optimize queries with proper indexes
+- Avoid loading unnecessary data
+- Use projections when you don't need full entities
+
+### Threading
+- Be careful with `@Async` methods
+- Use proper thread pool configuration
+- Avoid blocking operations in async methods
+- Handle exceptions in async methods
+
+### Caching
+- Use `@Cacheable` appropriately
+- Clear caches when data changes
+- Don't cache sensitive data without encryption
+
+## Testing
+
+- Write unit tests for business logic
+- Use `@DataJpaTest` for repository tests
+- Use `@WebMvcTest` for controller tests
+- Mock external dependencies
+- Aim for 80%+ coverage on new code
+
+## Common Issues to Avoid
+
+❌ Returning entities from controllers
+❌ Missing `@Transactional` on write operations
+❌ N+1 query problems
+❌ Hardcoded secrets or credentials
+❌ Catching and ignoring exceptions
+❌ Missing input validation
+❌ Exposing sensitive data in logs
+❌ Using `SELECT *` in queries
+❌ Not handling null values properly

package/templates/presets/backend/config.json

@@ -0,0 +1,12 @@
+{
+  "analysis": {
+    "maxFileSize": 100000,
+    "maxFiles": 10,
+    "timeout": 120000
+  },
+  "subagents": {
+    "enabled": true,
+    "model": "sonnet",
+    "batchSize": 3
+  }
+}

package/templates/presets/backend/preset.json

@@ -0,0 +1,49 @@
+{
+  "name": "backend",
+  "displayName": "Backend (Spring Boot + SQL Server)",
+  "description": "Java backend with Spring Boot, JPA, SQL Server, AWS",
+  "version": "1.0.0",
+
+  "techStack": [
+    "Spring Boot 2.6+",
+    "JPA",
+    "Hibernate",
+    "SQL Server",
+    "Spring Security",
+    "JWT",
+    "MapStruct",
+    "Lombok",
+    "AWS SDK",
+    "Maven",
+    "Cucumber",
+    "JUnit",
+    "JaCoCo"
+  ],
+
+  "fileExtensions": [
+    ".java",
+    ".xml",
+    ".yml",
+    ".yaml"
+  ],
+
+  "focusAreas": [
+    "REST API design and best practices",
+    "JPA entities and repositories",
+    "Service layer patterns",
+    "Security vulnerabilities (OWASP Top 10)",
+    "SQL injection prevention",
+    "Performance (threads, async operations)",
+    "Transaction management",
+    "DTO mappings",
+    "Test coverage"
+  ],
+
+  "templates": {
+    "analysis": "ANALYSIS_PROMPT.md",
+    "guidelines": "PRE_COMMIT_GUIDELINES.md",
+    "commitMessage": "../shared/COMMIT_MESSAGE.md",
+    "analyzeDiff": "../shared/ANALYZE_DIFF.md",
+    "resolution": "../shared/RESOLUTION_PROMPT.md"
+  }
+}

package/templates/presets/database/ANALYSIS_PROMPT.md

@@ -0,0 +1,114 @@
+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 database code quality analysis focusing on these areas:
+
+{{FOCUS_AREAS}}
+
+## Analysis Guidelines
+
+1. **Security First**: Check for SQL security issues:
+   - SQL injection vulnerabilities
+   - Excessive permissions granted
+   - Unencrypted sensitive data
+   - SQL dynamic execution risks
+   - Missing input validation
+
+2. **Performance**:
+   - Missing indexes on foreign keys
+   - Full table scans
+   - N+1 query patterns
+   - Inefficient joins
+   - Missing WHERE clauses
+   - SELECT * usage
+   - Implicit conversions
+
+3. **Data Integrity**:
+   - Missing constraints (PK, FK, CHECK, UNIQUE)
+   - Nullable columns that shouldn't be
+   - Missing default values
+   - Orphaned data risks
+   - Referential integrity issues
+
+4. **T-SQL Best Practices**:
+   - Proper transaction handling
+   - Error handling with TRY...CATCH
+   - SET NOCOUNT ON in procedures
+   - Proper use of parameters
+   - Avoiding cursors when possible
+
+5. **Maintainability**:
+   - Code clarity and comments
+   - Consistent naming conventions
+   - Proper formatting
+   - Avoiding magic numbers
+   - Version control for schema changes
+
+## Common Database Anti-Patterns to Check
+
+❌ **No WHERE clause on UPDATE/DELETE** (dangerous!)
+❌ **Missing indexes on foreign keys**
+❌ **Using SELECT \*** in production code
+❌ **No error handling in stored procedures**
+❌ **Implicit conversions** (kills index usage)
+❌ **Cursors for set-based operations**
+❌ **Dynamic SQL without parameterization**
+❌ **Missing transaction handling**
+❌ **No constraints** (relying on app logic only)
+❌ **Excessive permissions** (granting db_owner)
+
+## 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|PERFORMANCE",
+      "file": "path/to/file.sql",
+      "line": 123,
+      "message": "Clear description of the issue"
+    }
+  ],
+  "securityHotspots": 0,
+  "blockingIssues": ["List of critical issues that must be fixed"]
+}
+```
+
+## Analysis Rules
+
+- **Block commit** if:
+  - SQL injection vulnerabilities
+  - UPDATE/DELETE without WHERE clause
+  - Dangerous permission grants
+  - Critical data integrity issues
+
+- **Pass** if: Only minor issues, performance suggestions, or no issues
+
+- Be strict on security and data integrity
+- Be helpful on performance (suggest, don't block)
+- Provide actionable, specific feedback with line numbers