# Contributing to the Enterprise-Grade Software Framework

## Welcome Contributors

Thank you for your interest in contributing to this project! While this appears to be an MCP server for SQL
Server, you're actually contributing to **a comprehensive framework demonstrating enterprise-grade software
development practices**. Your contributions help maintain and extend a reference implementation for rigorous software
engineering.

## Philosophy

Before diving into code, please read our [**Software Engineering Manifesto**](MANIFESTO.md) to understand the principles that guide this project. Every contribution should uphold these standards:

- **Testing as a First-Class Citizen**: No code without comprehensive tests
- **Security by Design**: Security considerations in every change
- **Observability by Default**: Proper logging and monitoring for all features
- **Production Readiness**: Code that's ready for enterprise deployment

**🚀 New to this project?** Review our [Architecture Guide](docs/ARCHITECTURE.md) and choose your preferred setup:

- **[Warp Terminal Quick Start Guide](docs/QUICKSTART.md)** - Original 5-minute setup
- **[VS Code Quick Start Guide](docs/QUICKSTART-VSCODE.md)** - Complete VS Code + Warp integration

These guides will help you understand both the technical architecture and practical usage.

## Development Setup

### Prerequisites

- Node.js 18.0.0 or higher
- npm (comes with Node.js)
- SQL Server instance (for integration testing - optional)

### 🧪 Test-Driven Development (TDD) - MANDATORY

**🎯 This project strictly follows Test-Driven Development. ALL new functionality must be test-driven.**

#### TDD is enforced through

- Pre-commit hooks that require passing tests
- Code review process that validates TDD practices
- CI/CD pipeline that enforces test coverage requirements
- Security testing requirements for all SQL-related functionality

### Getting Started

1. **Clone the repository**

   ```bash
   git clone <repository-url>
   cd warp-sql-server-mcp
   ```

2. **Install dependencies**

   ```bash
   npm install
   ```

3. **Install git hooks** (recommended for contributors)
   ```bash
   npm run hooks:install
   # or
   ./install-git-hooks.sh
   ```

## Development Workflow

### Code Quality Tools

This project uses several tools to maintain code quality:

- **ESLint**: JavaScript linting
- **Prettier**: Code formatting
- **markdownlint**: Markdown formatting
- **Vitest**: Testing framework

### Available Scripts

```bash
# Testing
npm test                    # Run all tests
npm run test:watch         # Run tests in watch mode
npm run test:coverage      # Run tests with coverage report
npm run test:ui            # Run tests with UI interface

# Linting and Formatting
npm run lint               # Check code with ESLint
npm run lint:fix           # Fix ESLint issues automatically
npm run format             # Format code with Prettier
npm run format:check       # Check if code is properly formatted
npm run markdown:lint      # Lint markdown files
npm run markdown:fix       # Fix markdown issues automatically

# Git Hooks
npm run hooks:install      # Install git hooks
npm run hooks:uninstall    # Remove git hooks

# Pre-commit checks (manual)
npm run precommit          # Run all pre-commit checks
npm run ci                 # Run all CI checks locally

# Utilities
npm run clean              # Clean build artifacts
npm run audit:fix          # Fix npm security issues
```

### Git Hooks

When you run `npm run hooks:install`, two git hooks are installed:

1. **pre-commit**: Runs before each commit
   - ESLint on staged JavaScript files
   - Prettier formatting check on staged files
   - markdownlint on staged markdown files
   - Quick test suite

2. **pre-push**: Runs before each push
   - Full test suite
   - Test coverage check
   - Security audit (`npm audit --audit-level=high`)
   - Comprehensive linting (ESLint, Prettier)
   - Markdown formatting validation
   - Dead link checking

### Testing

This project uses Vitest for testing. Tests are located in the `test/` directory.

- **Unit tests**: Test individual functions and methods
- **Integration tests**: Test the MCP server functionality
- **Coverage**: Aim for >80% code coverage

Run tests with:

```bash
npm test                    # Single run
npm run test:watch         # Watch mode for development
npm run test:coverage      # With coverage report
```

### Code Style

The project follows these style guidelines:

- **JavaScript**: ES6 modules, 2-space indentation, single quotes
- **Prettier**: Automatic formatting with 100 character line limit
- **ESLint**: Enforces Node.js best practices
- **Markdown**: markdownlint rules with 100 character line limit

### CI/CD

GitHub Actions automatically runs:

- **Tests** on Node.js 18, 20, and 22
- **Linting** with ESLint, Prettier, and markdownlint
- **Security audit** with npm audit
- **Coverage reporting** with Codecov (when configured)

## 🔒 Safety Testing Requirements (CRITICAL)

### Security Testing for Contributors

**⚠️ ALL SQL-related functionality MUST include comprehensive safety tests.**

#### Mandatory Safety Test Categories

For any new MCP tool or functionality that interacts with the database:

1. **Read-Only Mode Testing**

   ```javascript
   describe('new_tool read-only mode', () => {
     beforeEach(() => {
       // Set up read-only mode
       process.env.SQL_SERVER_READ_ONLY = 'true';
       process.env.SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS = 'false';
       process.env.SQL_SERVER_ALLOW_SCHEMA_CHANGES = 'false';
     });

     test('should allow SELECT operations', async () => {
       // Test that SELECT operations work
     });

     test('should block non-SELECT operations', async () => {
       // Test that INSERT/UPDATE/DELETE/CREATE/etc are blocked
       // Must return proper error message explaining the restriction
     });
   });
   ```

2. **Destructive Operations Testing**

   ```javascript
   describe('new_tool destructive operations', () => {
     test('should respect destructive operations setting', async () => {
       // Test with SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS=false
       // Ensure DML operations are blocked
     });

     test('should allow DML when enabled', async () => {
       // Test with SQL_SERVER_ALLOW_DESTRUCTIVE_OPERATIONS=true
       // Ensure DML operations work
     });
   });
   ```

3. **Schema Changes Testing**

   ```javascript
   describe('new_tool schema changes', () => {
     test('should respect schema changes setting', async () => {
       // Test with SQL_SERVER_ALLOW_SCHEMA_CHANGES=false
       // Ensure DDL operations are blocked
     });

     test('should allow DDL when enabled', async () => {
       // Test with SQL_SERVER_ALLOW_SCHEMA_CHANGES=true
       // Ensure DDL operations work
     });
   });
   ```

4. **Error Message Testing**
   ```javascript
   describe('new_tool error messages', () => {
     test('should provide clear security error messages', async () => {
       // Verify error messages explain:
       // - What was blocked
       // - Why it was blocked
       // - How to enable the functionality if needed
     });
   });
   ```

#### Safety Testing Checklist

Before submitting a PR with SQL functionality:

- [ ] **Read-only mode tests** - Verify tool respects read-only restrictions
- [ ] **DML restriction tests** - Test destructive operations controls
- [ ] **DDL restriction tests** - Test schema change controls
- [ ] **Error message validation** - Ensure clear, helpful error messages
- [ ] **Security bypass testing** - Attempt to circumvent security (must fail)
- [ ] **Edge case testing** - Test unusual SQL patterns and edge cases
- [ ] **Multi-statement testing** - Ensure multi-statement SQL is properly validated
- [ ] **Configuration matrix testing** - Test all security configuration combinations

### 🧪 TDD Workflow for Safety Features

#### Step-by-Step Safety TDD Process

1. **Write Security Tests First** (🔴 RED Phase)

   ```bash
   # Start with failing security tests
   npm run test:watch  # Keep running during development
   ```

2. **Implement Basic Functionality** (🟢 GREEN Phase)

   ```bash
   # Write minimal code to make security tests pass
   # Security validation should be implemented FIRST
   ```

3. **Add Feature Logic** (🟡 REFACTOR Phase)

   ```bash
   # Add the actual functionality while keeping security tests passing
   ```

4. **Comprehensive Testing** (🔒 SECURITY Phase)
   ```bash
   # Add edge cases, error conditions, and bypass attempts
   npm run test:coverage  # Verify coverage includes security paths
   ```

#### Security Test Examples

**Query Validation Testing:**

```javascript
test('validateQuery should block dangerous patterns', () => {
  const server = new SqlServerMCP();

  // Test various dangerous patterns
  const dangerousQueries = [
    'DROP TABLE Users',
    "INSERT INTO Users VALUES (1, 'test')",
    'DELETE FROM Users WHERE id = 1',
    "UPDATE Users SET name = 'hacked'",
    "EXEC xp_cmdshell 'dir'",
    'CREATE TABLE malicious (id int)'
  ];

  dangerousQueries.forEach(query => {
    const result = server.validateQuery(query);
    expect(result.allowed).toBe(false);
    expect(result.reason).toContain('blocked');
  });
});
```

**Multi-Configuration Testing:**

```javascript
const securityConfigs = [
  { readOnly: true, destructive: false, schema: false }, // Maximum security
  { readOnly: false, destructive: true, schema: false }, // Data analysis
  { readOnly: false, destructive: true, schema: true } // Full development
];

securityConfigs.forEach(config => {
  describe(`Security config: RO=${config.readOnly}, DML=${config.destructive}, DDL=${config.schema}`, () => {
    // Test each configuration thoroughly
  });
});
```

### Safety Testing Resources

- **Existing Tests**: See `test/sqlserver-mcp.test.js` for security test examples
- **Test Patterns**: Follow established patterns for validateQuery testing
- **Security Documentation**: Review `SECURITY.md` for threat model details
- **Mock Data**: Use existing mock data and patterns for consistency

## Making Changes

1. **Create a feature branch**

   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes (TDD Process)**
   - **STEP 1**: Write comprehensive safety tests FIRST
   - **STEP 2**: Write tests for functionality
   - **STEP 3**: Implement security validation
   - **STEP 4**: Implement core functionality
   - **STEP 5**: Update documentation as needed
   - **STEP 6**: Follow the existing code style

3. **Test locally**

   ```bash
   npm run ci  # Run all checks locally
   ```

4. **Commit your changes**

   ```bash
   git add .
   git commit -m "feat: description of your changes"
   ```

   The pre-commit hook will automatically run checks.

   **If the pre-commit hook blocks your commit:**

   ```bash
   # Fix formatting issues automatically
   npm run format

   # Fix linting issues automatically
   npm run lint:fix

   # Fix markdown issues automatically
   npm run markdown:fix

   # Then retry the commit
   git commit -m "your commit message"
   ```

5. **Push and create a Pull Request**
   ```bash
   git push origin feature/your-feature-name
   ```

## Commit Message Format

Follow conventional commits format:

- `feat:` New features
- `fix:` Bug fixes
- `docs:` Documentation changes
- `style:` Code style changes (formatting, etc.)
- `refactor:` Code refactoring
- `test:` Adding or updating tests
- `chore:` Maintenance tasks

Example:

```text
feat: add new database connection tool

- Add support for custom connection strings
- Include connection pooling options
- Update tests and documentation
```

## Getting Help

- Check existing issues: [GitHub Issues](https://github.com/egarcia74/warp-sql-server-mcp/issues)
- Ask questions: [Question Template](https://github.com/egarcia74/warp-sql-server-mcp/issues/new?template=question.yml)
- Read the documentation in `README.md` and `WARP.md`
- Look at the test files for usage examples

Thank you for contributing! 🚀