Code Quality Tools¶

[tool.ruff]
target-version = "py314"
line-length = 100
src = ["backend"]

[tool.ruff.lint]
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # Pyflakes
    "I",      # isort (import sorting)
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
    "ARG",    # flake8-unused-arguments
    "SIM",    # flake8-simplify
    "TCH",    # flake8-type-checking
    "PTH",    # flake8-use-pathlib
    "ERA",    # eradicate (commented-out code)
    "PL",     # Pylint
    "RUF",    # Ruff-specific rules
    "ASYNC",  # flake8-async
    "S",      # flake8-bandit (security)
]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

# Check for linting errors
uv run ruff check backend/

# Auto-fix linting errors
uv run ruff check --fix backend/

# Check formatting
uv run ruff format --check backend/

# Auto-format code
uv run ruff format backend/

[tool.mypy]
python_version = "3.14"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
ignore_missing_imports = true
plugins = ["pydantic.mypy"]

# Run type checking
uv run mypy backend/

# Run with specific options
uv run mypy backend/ --ignore-missing-imports

[tool.pytest.ini_options]
testpaths = ["backend/tests"]
python_files = ["test_*.py"]
asyncio_mode = "auto"
addopts = "-n auto --dist=worksteal -v --strict-markers --tb=short"
timeout = 5
markers = [
    "asyncio: mark test as an async test",
    "unit: mark test as a unit test",
    "integration: mark test as an integration test (5s timeout)",
    "e2e: mark test as an end-to-end pipeline test",
    "gpu: mark test as a GPU test",
    "slow: mark test as legitimately slow (30s timeout)",
    "benchmark: mark test as a benchmark test",
    "serial: mark test as requiring serial execution",
]

# Run all tests
uv run pytest backend/tests/

# Run unit tests with parallel execution
uv run pytest backend/tests/unit/ -n auto --dist=worksteal

# Run integration tests (serial execution)
uv run pytest backend/tests/integration/ -n0

# Run with coverage
uv run pytest backend/tests/ --cov=backend --cov-report=term-missing

# Run specific test file
uv run pytest backend/tests/unit/test_cameras.py -v

# Run tests matching a pattern
uv run pytest -k "test_camera" -v

[tool.hypothesis.profiles.ci]
max_examples = 100
deadline = 1000
database = "none"
print_blob = true

[tool.hypothesis.profiles.dev]
max_examples = 500
deadline = 5000
database = "directory:.hypothesis"

from hypothesis import given, strategies as st

@given(st.integers(min_value=0, max_value=100))
def test_risk_score_bounds(score):
    """Property: risk scores must be bounded."""
    assert 0 <= process_risk(score) <= 100

[tool.coverage.run]
source = ["backend"]
omit = ["backend/tests/*", "backend/examples/*", "backend/main.py"]

[tool.coverage.report]
fail_under = 95
show_missing = true
precision = 2

# Run dead code detection
uv run vulture backend/ --min-confidence 80

# With whitelist (for false positives)
uv run vulture backend/ vulture_whitelist.py --min-confidence 80

# Cyclomatic complexity (show grades A-F)
uv run radon cc backend/ -a -s

# Maintainability index
uv run radon mi backend/ -s

# Only show complex functions (grade C or worse)
uv run radon cc backend/ -a -nc

// Key enabled rule sets:
// - @eslint/js recommended
// - typescript-eslint recommended + recommendedTypeChecked
// - react, react-hooks, jsx-a11y plugins
// - import ordering

// Key rules:
'@typescript-eslint/no-floating-promises': 'error',
'@typescript-eslint/await-thenable': 'error',
'react-hooks/rules-of-hooks': 'error',
'react-hooks/exhaustive-deps': 'warn',
'import/order': ['error', { 'newlines-between': 'always' }],

cd frontend

# Run linting
npm run lint

# Auto-fix issues
npm run lint:fix

{
  "devDependencies": {
    "prettier": "^3.2.4",
    "prettier-plugin-tailwindcss": "^0.7.2"
  }
}

cd frontend

# Check formatting
npm run format:check

# Auto-format code
npm run format

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "jsx": "react-jsx"
  }
}

cd frontend

# Run type checking
npm run typecheck

# Or directly
npx tsc --noEmit

cd frontend

# Run tests in watch mode
npm test

# Run tests once
npm test -- --run

# Run with coverage
npm run test:coverage

# Run with UI
npm run test:ui

cd frontend

# Run all E2E tests
npm run test:e2e

# Run in headed mode (visible browser)
npm run test:e2e:headed

# Run in debug mode
npm run test:e2e:debug

# View test report
npm run test:e2e:report

# Run specific browser
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit

cd frontend

# Run dead code detection
npm run dead-code

# Or directly
npx knip

# Install pre-commit (if not already installed)
pip install pre-commit

# Install hooks
pre-commit install

# Install pre-push hooks (for tests)
pre-commit install --hook-type pre-push

# Run all hooks on all files
pre-commit run --all-files

# Run specific hook
pre-commit run ruff --all-files
pre-commit run mypy --all-files

# Skip hooks (emergencies only!)
SKIP=fast-test git commit -m "message"

# Run everything
./scripts/validate.sh

# Backend only
./scripts/validate.sh --backend

# Frontend only
./scripts/validate.sh --frontend

# Lint and format
uv run ruff check --fix backend/ && uv run ruff format backend/

# Type check
uv run mypy backend/

# Run tests
uv run pytest backend/tests/ -v

# Run tests with coverage
uv run pytest backend/tests/ --cov=backend --cov-report=term-missing

cd frontend

# Lint and format
npm run lint:fix && npm run format

# Type check
npm run typecheck

# Run tests
npm test -- --run

# Run E2E tests
npm run test:e2e

pre-commit run --all-files

# See what rules are being violated
uv run ruff check backend/ --show-source

# Auto-fix with unsafe fixes
uv run ruff check --fix --unsafe-fixes backend/

# Show detailed error messages
uv run mypy backend/ --show-error-codes

# Generate stubs for missing packages
uv run stubgen -p package_name

# See rule documentation
npx eslint --print-config src/App.tsx

# Disable rule for specific line
// eslint-disable-next-line @typescript-eslint/no-explicit-any

# See compiler diagnostics
npx tsc --noEmit --diagnostics

# Generate declaration files to debug types
npx tsc --declaration --emitDeclarationOnly