# Language-Specific Rules Configuration Guide

## Overview
This guide explains how to configure language-specific rules in SunLint projects. Language-specific rules are **opt-in** and must be explicitly enabled via project configuration.

## Core vs Language-Specific Rules

### Core Rules (Always Available)
- **Files**: `common-en.md`, `security-en.md`
- **Count**: 135 rules
- **Usage**: Included in category commands (`--security`, `--quality`)
- **Scope**: Universal rules applicable to all languages

### Language-Specific Rules (Opt-In)
- **Files**: `typescript-en.md`, `reactjs-en.md`, `java-en.md`, etc.
- **Count**: 121 rules
- **Usage**: Must be enabled via project config
- **Scope**: Rules specific to particular languages/frameworks

## Configuration Methods

### 1. Project Configuration (.sunlint.json)

Create or edit `.sunlint.json` in your project root:

```json
{
  "rules": [
    "TS001",
    "TS002", 
    "REACT001"
  ],
  "presets": ["typescript", "reactjs"],
  "categories": ["security", "quality"]
}
```

### 2. Package.json Configuration

Add sunlint config to your `package.json`:

```json
{
  "sunlint": {
    "rules": ["TS001", "TS002"],
    "presets": ["typescript"],
    "categories": ["security"]
  }
}
```

### 3. CLI Rule Selection

Use CLI flags for one-time rule selection:

```bash
# Specific language rules
sunlint --rules="TS001,TS002,REACT001"

# Mix core categories with specific rules  
sunlint --security --rules="TS001,TS002"

# Use presets
sunlint --preset=typescript
```

## Available Language-Specific Rules

### TypeScript Rules (typescript-en.md)
```bash
# Example TypeScript-specific rules
TS001 - TypeScript strict mode enforcement
TS002 - Type assertion guidelines
TS003 - Interface vs type usage
# ... more TypeScript rules
```

### React Rules (reactjs-en.md)
```bash
# Example React-specific rules
REACT001 - Component prop validation
REACT002 - State mutation prevention
REACT003 - Effect dependency handling
# ... more React rules
```

### Java Rules (java-en.md)
```bash
# Example Java-specific rules
JAVA001 - Exception handling patterns
JAVA002 - Thread safety guidelines
JAVA003 - Memory management best practices
# ... more Java rules
```

## Configuration Examples

### TypeScript Project
```json
{
  "presets": ["typescript"],
  "categories": ["security", "quality"],
  "rules": [
    "TS001",
    "TS005", 
    "TS010"
  ]
}
```

### React + TypeScript Project
```json
{
  "presets": ["typescript", "reactjs"],
  "categories": ["security"],
  "rules": [
    "TS001",
    "REACT001",
    "REACT005"
  ]
}
```

### Multi-Language Project
```json
{
  "presets": ["typescript", "java"],
  "categories": ["security", "quality"],
  "rules": [
    "TS001",
    "JAVA001",
    "JAVA010"
  ]
}
```

## Rule Priority System

SunLint follows this priority order:

1. **CLI `--rule`** (highest priority)
2. **CLI `--rules`** 
3. **CLI `--category`** (core rules only)
4. **Project config file** (lowest priority)

### Example Priority Resolution
```bash
# Command: sunlint --security --rules="TS001,TS002" --rule="CUSTOM001"
# Result: Only CUSTOM001 is used (--rule overrides everything)

# Command: sunlint --security --rules="TS001,TS002"  
# Result: TS001, TS002 are used (--rules overrides --security)

# Command: sunlint --security
# Result: 60 core security rules are used
```

## Preset Configurations

Presets provide curated rule collections for specific languages:

### Creating Custom Presets
```json
// config/presets/my-typescript-preset.json
{
  "rules": [
    "TS001", "TS002", "TS005",
    "S001", "S010", "S020",
    "C001", "C005", "C010"
  ],
  "description": "Custom TypeScript preset with security focus"
}
```

### Using Presets
```bash
# CLI usage
sunlint --preset=my-typescript-preset

# Project config usage
{
  "presets": ["my-typescript-preset"]
}
```

## Best Practices

### 1. Start with Core Categories
Begin with core categories, then add language-specific rules:
```json
{
  "categories": ["security", "quality"],
  "rules": ["TS001", "TS002"]
}
```

### 2. Use Presets for Common Configurations
Create and reuse presets for consistent team configurations:
```json
{
  "presets": ["team-typescript", "security-strict"]
}
```

### 3. Gradual Rule Adoption
Add language-specific rules incrementally:
```json
{
  "categories": ["security"],
  "rules": [
    // Week 1: Start with essential rules
    "TS001",
    
    // Week 2: Add more specific rules
    "TS002", "TS005",
    
    // Week 3: Add advanced rules
    "TS010", "TS015"
  ]
}
```

### 4. Document Team Standards
Create team-specific documentation:
```json
{
  "presets": ["team-standard"],
  "description": "Our team's agreed-upon rule set",
  "rules": ["TS001", "TS002", "REACT001"]
}
```

## Troubleshooting

### Common Issues

#### 1. Language Rules Not Applied
**Problem**: Language-specific rules don't appear in results
**Solution**: Check that rules are in project config, not just CLI categories

```bash
# This only uses core rules
sunlint --security  

# This includes language-specific rules
sunlint --security --rules="TS001,TS002"
```

#### 2. Rule Conflicts
**Problem**: Different tools report different rule counts
**Solution**: Verify same configuration is used everywhere

```json
// Ensure consistent config across tools
{
  "presets": ["typescript"],
  "categories": ["security"]
}
```

#### 3. Missing Rules
**Problem**: Expected rules don't appear
**Solution**: Check rule priority and configuration merge

```bash
# Debug with verbose output
sunlint --verbose --security
```

## Migration from Legacy Configuration

### Old Approach (Deprecated)
```json
{
  "includeLanguageRules": true,
  "language": "typescript"
}
```

### New Approach (Recommended)
```json
{
  "presets": ["typescript"],
  "categories": ["security", "quality"]
}
```

## Validation

Test your configuration:

```bash
# Verify rule selection
sunlint --input=src --verbose

# Test specific configuration
sunlint --config=.sunlint.json --verbose

# Validate rule counts
node test-category-filtering.js
```

## Related Documentation

- [Standardized Category Filtering](./STANDARDIZED-CATEGORY-FILTERING.md)
- [Configuration Guide](./CONFIGURATION.md)
- [Preset System](./PRESETS.md)
- [CLI Commands](./COMMAND-EXAMPLES.md)