claude-hooks/CONTRIBUTING.md

# Contributing to Claude Hooks

Thank you for your interest in contributing to Claude Hooks! This document provides guidelines for contributing to the project.

## 🚀 Getting Started

### Prerequisites

- Node.js 16.0.0 or higher
- npm 8.0.0 or higher
- Claude Code CLI installed
- Git for version control

### Development Setup

1. **Fork and clone the repository:**
   ```bash
   git clone https://git.supported.systems/your-username/claude-hooks.git
   cd claude-hooks
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Link for local development:**
   ```bash
   npm link
   ```

4. **Run tests:**
   ```bash
   npm test
   ```

5. **Test integration with Claude Code:**
   ```bash
   claude-hooks test
   ```

## 🏗️ Project Structure

```
claude-hooks/
├── bin/                    # CLI executable
│   └── claude-hooks.js
├── hooks/                  # Hook implementations
│   ├── context-monitor.js
│   ├── command-validator.js
│   ├── session-logger.js
│   └── session-finalizer.js
├── lib/                    # Core libraries
│   ├── shadow-learner.js
│   ├── backup-manager.js
│   ├── session-state.js
│   └── context-monitor.js
├── config/                 # Configuration templates
├── docs/                   # Diátaxis documentation
└── tests/                  # Test suites
```

## 🧪 Testing

### Test Levels

1. **Unit Tests** - Individual component testing
2. **Integration Tests** - Hook pipeline testing
3. **End-to-End Tests** - Full Claude Code integration

### Running Tests

```bash
# All tests
npm test

# Specific test categories
npm run test:unit
npm run test:integration
npm run test:e2e

# Coverage report
npm run test:coverage
```

### Writing Tests

Example hook test:
```javascript
const { testHook } = require('../tests/test-utils');

describe('CommandValidator', () => {
  it('should block dangerous commands', async () => {
    const input = {
      tool: 'Bash',
      parameters: { command: 'rm -rf /' }
    };
    
    const result = await testHook('command-validator.js', input);
    
    expect(result.allow).toBe(false);
    expect(result.message).toContain('dangerous');
  });
});
```

## 📝 Code Style

### JavaScript Standards

- **ES2020+** syntax
- **CommonJS** modules (for Claude Code compatibility)
- **JSDoc** comments for public APIs
- **Async/await** for asynchronous operations

### Linting and Formatting

```bash
# Lint code
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format
```

### Example Code Style

```javascript
/**
 * Validates a bash command for safety and provides suggestions
 * @param {Object} input - Hook input data
 * @param {string} input.tool - Tool name (should be 'Bash')
 * @param {Object} input.parameters - Tool parameters
 * @returns {Promise<Object>} Validation result
 */
async function validateCommand(input) {
  const { tool, parameters } = input;
  
  if (tool !== 'Bash') {
    return { allow: true };
  }
  
  const { command } = parameters;
  const dangerousPatterns = [
    /rm\s+-rf\s+\//,
    /mkfs\./
  ];
  
  for (const pattern of dangerousPatterns) {
    if (pattern.test(command)) {
      return {
        allow: false,
        message: '⛔ Command blocked: Dangerous pattern detected'
      };
    }
  }
  
  return { allow: true };
}
```

## 🎯 Contribution Types

### 🐛 Bug Reports

Use the issue template:
```markdown
**Bug Description:**
Brief description of the bug

**Steps to Reproduce:**
1. Step one
2. Step two
3. Expected vs actual behavior

**Environment:**
- OS: [e.g., macOS 13.0]
- Node.js version: [e.g., 18.17.0]
- Claude Code version: [e.g., 1.2.3]
- claude-hooks version: [e.g., 1.0.0]

**Additional Context:**
Hook logs, error messages, etc.
```

### ✨ Feature Requests

Include:
- **Use case**: Why is this feature needed?
- **Proposed solution**: How should it work?
- **Alternatives considered**: Other approaches
- **Breaking changes**: Any compatibility concerns

### 🔧 Code Contributions

#### Hooks Development

New hooks should:
- Follow the [Hook API Reference](docs/reference/hook-api.md)
- Include comprehensive tests
- Handle errors gracefully
- Execute within performance requirements (<50ms for PreToolUse)

#### Shadow Learner Enhancements

When extending the shadow learner:
- Maintain backward compatibility with existing pattern databases
- Include confidence scoring for new pattern types
- Document learning algorithms clearly
- Test with various failure scenarios

#### Documentation Improvements

Follow the [Diátaxis framework](https://diataxis.fr/):
- **Tutorials**: Learning-oriented, hands-on guidance
- **How-to guides**: Goal-oriented, practical steps
- **Reference**: Information-oriented, comprehensive details
- **Explanation**: Understanding-oriented, theoretical background

## 🔄 Pull Request Process

### Before Submitting

1. **Test thoroughly:**
   ```bash
   npm test
   npm run lint
   claude-hooks test
   ```

2. **Update documentation** if needed
3. **Add changelog entry** for user-facing changes
4. **Ensure backward compatibility** or document breaking changes

### PR Guidelines

1. **Clear title**: Describe what the PR does
2. **Detailed description**: 
   - What problem does this solve?
   - How does the solution work?
   - Any breaking changes or migration notes?
3. **Link related issues**
4. **Request specific reviewers** if needed

### Example PR Description

```markdown
## Summary
Add support for Python virtual environment detection in command validation

## Changes
- Extend shadow learner to detect venv/conda environments
- Update command validator to suggest environment-specific alternatives
- Add tests for virtual environment scenarios

## Testing
- [ ] Unit tests pass
- [ ] Integration tests with venv scenarios
- [ ] Manual testing in conda environment

## Breaking Changes
None - fully backward compatible

Fixes #123
```

## 🎯 Development Guidelines

### Hook Development

1. **Error Handling**: Always fail safely
   ```javascript
   try {
     // Hook logic
     return { allow: true, message: 'Success' };
   } catch (error) {
     console.error('Hook error:', error);
     return { allow: true }; // Fail open
   }
   ```

2. **Performance**: Keep hooks fast
   ```javascript
   const MAX_EXECUTION_TIME = 50; // ms for PreToolUse
   ```

3. **Logging**: Use structured logging
   ```javascript
   console.log(JSON.stringify({
     timestamp: new Date().toISOString(),
     hook: 'command-validator',
     action: 'blocked-command',
     command: sanitizeForLog(command)
   }));
   ```

### Shadow Learner Extensions

1. **Pattern Validation**: Ensure patterns are meaningful
   ```javascript
   function validatePattern(pattern) {
     return pattern.confidence > 0.1 && 
            pattern.evidence_count > 2 &&
            pattern.last_seen > Date.now() - 30 * 24 * 60 * 60 * 1000;
   }
   ```

2. **Storage Efficiency**: Keep databases compact
   ```javascript
   // Prune old patterns periodically
   function pruneOldPatterns(db) {
     const cutoff = Date.now() - 90 * 24 * 60 * 60 * 1000; // 90 days
     return db.filter(pattern => pattern.last_seen > cutoff);
   }
   ```

## 🌟 Recognition

Contributors are recognized in:
- **README.md** contributors section
- **CHANGELOG.md** for significant contributions
- **GitHub releases** with contributor highlights

## 📞 Getting Help

- **Questions**: Open a GitHub discussion
- **Bug reports**: Create an issue with the bug template
- **Development help**: Tag @maintainers in discussions
- **Real-time chat**: Join our Discord server (link in README)

## 🏆 Code of Conduct

This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). Please read and follow these guidelines to ensure a welcoming environment for all contributors.

---

**Thank you for contributing to Claude Hooks!** 🎉

Your contributions help make AI assistance more intelligent, reliable, and useful for developers worldwide.