# Code Review Rules Index

This directory contains externalized review rules for the multi-dimensional code review skill.

## Directory Structure

```
rules/
├── index.md                    # This file
├── correctness-rules.json      # CORR - Logic and error handling
├── security-rules.json         # SEC  - Security vulnerabilities
├── performance-rules.json      # PERF - Performance issues
├── readability-rules.json      # READ - Code clarity
├── testing-rules.json          # TEST - Test quality
└── architecture-rules.json     # ARCH - Design patterns
```

## Rule File Schema

Each rule file follows this JSON schema:

```json
{
  "dimension": "string",        // Dimension identifier
  "prefix": "string",           // Finding ID prefix (4 chars)
  "description": "string",      // Dimension description
  "rules": [
    {
      "id": "string",           // Unique rule identifier
      "category": "string",     // Rule category within dimension
      "severity": "critical|high|medium|low",
      "pattern": "string",      // Detection pattern
      "patternType": "regex|includes|ast",
      "negativePatterns": [],   // Patterns that exclude matches
      "caseInsensitive": false, // For regex patterns
      "contextPattern": "",     // Additional context requirement
      "contextPath": [],        // Path patterns for context
      "lineThreshold": 0,       // For size-based rules
      "methodThreshold": 0,     // For complexity rules
      "description": "string",  // Issue description
      "recommendation": "string", // How to fix
      "fixExample": "string"    // Code example
    }
  ]
}
```

## Dimension Summary

| Dimension | Prefix | Rules | Focus Areas |
|-----------|--------|-------|-------------|
| Correctness | CORR | 5 | Null checks, error handling, type safety |
| Security | SEC | 5 | XSS, injection, secrets, crypto |
| Performance | PERF | 5 | Complexity, I/O, memory leaks |
| Readability | READ | 5 | Naming, length, nesting, magic values |
| Testing | TEST | 5 | Assertions, coverage, mock quality |
| Architecture | ARCH | 5 | Dependencies, layering, coupling |

## Severity Levels

| Severity | Description | Action |
|----------|-------------|--------|
| **critical** | Security vulnerability or data loss risk | Must fix before release |
| **high** | Bug or significant quality issue | Fix in current sprint |
| **medium** | Code smell or maintainability concern | Plan to address |
| **low** | Style or minor improvement | Address when convenient |

## Pattern Types

### regex
Standard regular expression pattern. Supports flags via `caseInsensitive`.

```json
{
  "pattern": "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}",
  "patternType": "regex"
}
```

### includes
Simple substring match. Faster than regex for literal strings.

```json
{
  "pattern": "innerHTML",
  "patternType": "includes"
}
```

### ast (Future)
AST-based detection for complex structural patterns.

```json
{
  "pattern": "function[params>5]",
  "patternType": "ast"
}
```

## Usage in Code

```javascript
// Load rules
const rules = JSON.parse(fs.readFileSync('correctness-rules.json'));

// Apply rules
for (const rule of rules.rules) {
  const matches = detectByPattern(content, rule.pattern, rule.patternType);
  for (const match of matches) {
    // Check negative patterns
    if (rule.negativePatterns?.some(np => match.context.includes(np))) {
      continue;
    }
    findings.push({
      id: `${rules.prefix}-${counter++}`,
      severity: rule.severity,
      category: rule.category,
      description: rule.description,
      recommendation: rule.recommendation,
      fixExample: rule.fixExample
    });
  }
}
```

## Adding New Rules

1. Identify the appropriate dimension
2. Create rule with unique `id` within dimension
3. Choose appropriate `patternType`
4. Provide clear `description` and `recommendation`
5. Include practical `fixExample`
6. Test against sample code

## Rule Maintenance

- Review rules quarterly for relevance
- Update patterns as language/framework evolves
- Track false positive rates
- Collect feedback from users
