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

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

Configuration (pyproject.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:

# 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

cd apps/api
mypy src/

Configuration (pyproject.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

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):

bandit -r src/

Safety (dependency vulnerabilities):

safety check

Frontend Quality Gates

1. Type Checking (TypeScript)

Purpose: Catch type errors at build time

cd apps/web
npm run typecheck

Configuration (tsconfig.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

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

Configuration (.eslintrc.cjs):

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

cd apps/web
npm run build

Requirements:

• No TypeScript errors
• No build warnings
• Bundle size reasonable

4. Unit Tests (Vitest)

cd apps/web
npm run test

Requirements:

• All tests pass
• No test failures
• Coverage maintained

Running All Gates

Backend

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

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

# 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:

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

# 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

# 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

// Bad
function processData(data) {
  return data.map(item => item.name);
}

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

ESLint: Unused variable

// 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):

{
  "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:

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
• mypy Documentation
• ESLint Documentation
• TypeScript Handbook