headquarter/docs/development/quality-gates.md

# Quality Gates

## Overview

All code changes must pass quality gates before being merged. These gates ensure code consistency, type safety, and prevent common issues.

## Backend Quality Gates

### 1. Code Formatting (ruff)

**Purpose**: Enforce consistent code style

```bash
cd apps/api
ruff check src/ tests/
ruff format src/ tests/
```

**Configuration** (`pyproject.toml`):
```toml
[tool.ruff]
line-length = 100
target-version = "py311"
select = ["E", "F", "I", "W", "UP"]
ignore = ["E501"]

[tool.ruff.lint.pydocstyle]
convention = "google"
```

**Pre-commit hook**:
```bash
# Install pre-commit
pip install pre-commit
pre-commit install

# Run manually
pre-commit run --all-files
```

### 2. Type Checking (mypy)

**Purpose**: Catch type errors before runtime

```bash
cd apps/api
mypy src/
```

**Configuration** (`pyproject.toml`):
```toml
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_ignores = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
```

**Common issues**:
- Missing type hints on function parameters
- Returning wrong type
- None checks needed

### 3. Unit Tests (pytest)

**Purpose**: Verify functionality works as expected

```bash
cd apps/api
pytest -v
```

**Requirements**:
- All tests must pass
- New code should have tests
- Coverage should not decrease

### 4. Security Checks

**Bandit** (security linter):
```bash
bandit -r src/
```

**Safety** (dependency vulnerabilities):
```bash
safety check
```

## Frontend Quality Gates

### 1. Type Checking (TypeScript)

**Purpose**: Catch type errors at build time

```bash
cd apps/web
npm run typecheck
```

**Configuration** (`tsconfig.json`):
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}
```

### 2. Linting (ESLint)

**Purpose**: Enforce code style and catch issues

```bash
cd apps/web
npm run lint
npm run lint:fix
```

**Configuration** (`.eslintrc.cjs`):
```javascript
module.exports = {
  root: true,
  env: { browser: true, es2020: true },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react-hooks/recommended',
  ],
  parser: '@typescript-eslint/parser',
  plugins: ['react-refresh'],
  rules: {
    'react-refresh/only-export-components': [
      'warn',
      { allowConstantExport: true },
    ],
  },
}
```

### 3. Build Check

**Purpose**: Ensure production build succeeds

```bash
cd apps/web
npm run build
```

**Requirements**:
- No TypeScript errors
- No build warnings
- Bundle size reasonable

### 4. Unit Tests (Vitest)

```bash
cd apps/web
npm run test
```

**Requirements**:
- All tests pass
- No test failures
- Coverage maintained

## Running All Gates

### Backend

```bash
cd apps/api

# Run all gates
ruff check src/ tests/ && \
mypy src/ && \
pytest

# Or use Makefile
make lint      # ruff + mypy
make test      # pytest
make check     # All backend gates
```

### Frontend

```bash
cd apps/web

# Run all gates
npm run lint && \
npm run typecheck && \
npm run test && \
npm run build

# Or use package.json scripts
npm run check  # All frontend gates
```

### Full Project

```bash
# From root
make check-all  # Run all backend and frontend gates
```

## Continuous Integration

All quality gates run automatically on:
- Every Pull Request
- Every push to main branch

**CI Pipeline**:
```yaml
stages:
  - lint
  - test
  - build

backend-lint:
  stage: lint
  script:
    - cd apps/api && ruff check src/ tests/
    - cd apps/api && mypy src/

backend-test:
  stage: test
  script:
    - cd apps/api && pytest -v

frontend-lint:
  stage: lint
  script:
    - cd apps/web && npm run lint
    - cd apps/web && npm run typecheck

frontend-test:
  stage: test
  script:
    - cd apps/web && npm run test

frontend-build:
  stage: build
  script:
    - cd apps/web && npm run build
```

## Fixing Common Issues

### Backend

**ruff: Line too long**
```python
# Bad
result = some_very_long_function_name(with_many_parameters, that_make_the_line_too_long)

# Good
result = some_very_long_function_name(
    with_many_parameters, 
    that_make_the_line_too_long,
)
```

**mypy: Missing return type**
```python
# Bad
def get_user(user_id):
    return User.query.get(user_id)

# Good
def get_user(user_id: str) -> User | None:
    return User.query.get(user_id)
```

### Frontend

**TypeScript: Implicit any**
```typescript
// Bad
function processData(data) {
  return data.map(item => item.name);
}

// Good
function processData(data: DataItem[]) {
  return data.map(item => item.name);
}
```

**ESLint: Unused variable**
```typescript
// Bad
const [count, setCount] = useState(0);
// count is never used

// Good
const [count] = useState(0);
// Or remove if not needed
```

## IDE Integration

### VS Code

**Settings** (`.vscode/settings.json`):
```json
{
  "python.linting.enabled": true,
  "python.linting.mypyEnabled": true,
  "python.formatting.provider": "ruff",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}
```

### PyCharm

1. **File** → **Settings** → **Tools** → **External Tools**
2. Add ruff and mypy as external tools
3. Set up pre-commit hooks

## Pre-commit Hooks

`.pre-commit-config.yaml`:
```yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format
  
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.7.0
    hooks:
      - id: mypy
        additional_dependencies: [types-all]
  
  - repo: local
    hooks:
      - id: frontend-lint
        name: Frontend Lint
        entry: bash -c 'cd apps/web && npm run lint'
        language: system
        files: ^apps/web/
```

## Resources

- [ruff Documentation](https://docs.astral.sh/ruff/)
- [mypy Documentation](https://mypy.readthedocs.io/)
- [ESLint Documentation](https://eslint.org/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)