# Code Quality Pipeline

**File:** `.github/workflows/code-quality.yml`  
**Purpose:** Fast quality gate for immediate feedback  
**Duration:** ~2 minutes  

## Overview
The code quality pipeline provides rapid feedback on code quality issues. It's designed for speed and runs on **every push to any branch**, ensuring immediate quality feedback during development.

## Technical Details

### Trigger Conditions
```yaml
on: 
  push:
    branches: [ "*" ]  # Every push to any branch
  # Note: No pull_request trigger to avoid duplication
```

**Strategy:** Fast quality feedback on every commit to any branch. No PR triggers to avoid duplicate runs when full pipeline executes.

### Job Configuration
```yaml
quality-checks:
  runs-on: ubuntu-latest
  name: Code Quality Checks
```

### Tools & Dependencies
```yaml
pip install ruff bandit  # Minimal install for speed
```

## Quality Checks

### 1. Ruff Linting
**Command:** `ruff check app/ --output-format=github`
**Configuration:** `pyproject.toml` [tool.ruff.lint]
**Checks:**
- Code style (E, W)
- Unused imports/variables (F)
- Import sorting (I)
- Potential bugs (B)
- Security issues (RUF)

### 2. Ruff Formatting
**Command:** `ruff format --check app/`
**Configuration:** `pyproject.toml` [tool.ruff.format]
**Checks:**
- Code formatting consistency
- Line length (88 characters)
- Quote style (double quotes)
- Indentation (spaces)

### 3. Security Scanning
**Command:** `bandit -r app/ --severity-level medium`
**Purpose:** Detect security vulnerabilities
**Threshold:** Medium and high severity issues

## Performance Characteristics

### Execution Time
- **Setup:** ~30 seconds
- **Tool Installation:** ~20 seconds
- **Quality Checks:** ~60 seconds
- **Total:** ~2 minutes

### Resource Usage
- **CPU:** Minimal (linting only)
- **Memory:** <1GB
- **Network:** Package downloads only

## Configuration Files

### Ruff Configuration (`pyproject.toml`)
```toml
[tool.ruff.lint]
select = ["E", "F", "I", "B", "C4", "UP", "N", "W", "ARG", "Q", "RUF"]
ignore = [
    "E501",  # line too long, handled by formatter
    "B008",  # do not perform function calls in argument defaults
    "C901",  # too complex
]
fixable = ["ALL"]
target-version = "py311"
line-length = 88
```

### Bandit Security Rules
- **Severity:** Medium and above
- **Exclusions:** test directories, virtual environments
- **Format:** JSON output for reporting

## Exit Criteria

### Success Conditions
✅ All Ruff linting checks pass  
✅ All Ruff formatting checks pass  
✅ No security vulnerabilities (medium+)  
✅ All steps complete successfully  

### Failure Conditions
❌ Linting errors found  
❌ Formatting issues detected  
❌ Security vulnerabilities detected  
❌ Tool installation failures  

## Local Development

### Run Locally
```bash
# Install tools
pip install ruff bandit

# Run quality checks
ruff check app/
ruff format --check app/
bandit -r app/ --severity-level medium
```

### Fix Common Issues
```bash
# Auto-fix linting issues
ruff check app/ --fix

# Auto-format code
ruff format app/
```

## Integration Points

### GitHub Integration
- **Branch Protection:** Can be set as required check
- **Status Checks:** Reports pass/fail to PR
- **Annotations:** Inline comments on code issues

### Developer Workflow
1. Developer pushes to **any branch** (feature, develop, main)
2. Quality gate runs automatically (2 minutes)
3. Fast feedback on code quality issues
4. Developer fixes issues if needed
5. Continue development cycle
6. When ready: Create PR → Full pipeline runs

## Monitoring & Metrics

### Success Rate Target
- **Target:** >95% pass rate
- **Measurement:** Weekly pipeline success ratio

### Performance Targets
- **Duration:** <3 minutes (99th percentile)
- **Setup Time:** <1 minute
- **Tool Installation:** <30 seconds

## Troubleshooting

### Common Issues

#### Ruff Errors
```bash
# Check locally first
ruff check app/

# Common fixes
ruff check app/ --fix
ruff format app/
```

#### Bandit Warnings
```bash
# Run locally with details
bandit -r app/ -f json

# Review security issues
bandit -r app/ --severity-level low -v
```

#### Pipeline Failures
1. Check tool installation logs
2. Verify pyproject.toml syntax
3. Run commands locally to reproduce

## Best Practices

### ✅ Speed Optimization
- Minimal dependencies
- Cached Python setup
- Parallel tool execution
- Early failure detection

### ✅ Developer Experience
- Clear error messages
- GitHub format output
- Fast feedback loop
- Local development support

### ✅ Quality Assurance
- Comprehensive rule set
- Security scanning
- Consistent formatting
- Modern Python practices