.coderabbit.yaml

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
# https://docs.coderabbit.ai/getting-started/configure-coderabbit

# CodeRabbit Configuration
# Optimized for Python 3.13 / FastAPI RESTful API project

language: en-US
early_access: true

reviews:
  profile: chill
  request_changes_workflow: false
  high_level_summary: true
  high_level_summary_placeholder: "@coderabbitai summary"
  review_status: true
  commit_status: true
  fail_commit_status: false
  collapse_walkthrough: false
  changed_files_summary: true
  sequence_diagrams: true
  estimate_code_review_effort: true
  assess_linked_issues: true
  related_issues: true
  related_prs: true
  suggested_labels: true
  auto_apply_labels: false
  suggested_reviewers: false
  poem: false
  abort_on_close: true

  path_instructions:
    - path: "**/*.py"
      instructions: |
        - Follow PEP 8 style guide and Black formatting (88 char line length)
        - Use type hints for function parameters and return values
        - Follow async/await patterns for all I/O operations
        - Use Google-style docstrings for modules, classes, and functions
        - Verify imports follow proper grouping (stdlib → third-party → local)
        - Check that SQLAlchemy 2.0+ style is used (select() not legacy Query)

    - path: "routes/**/*.py"
      instructions: |
        - Routes should be thin - delegate to services
        - Verify proper HTTP status codes and FastAPI response models
        - Check that dependency injection is used (Depends(generate_async_session))
        - Ensure Pydantic models are used for request/response validation
        - Validate async route handlers (async def)
        - Check for proper cache headers (X-Cache: HIT/MISS)

    - path: "services/**/*.py"
      instructions: |
        - Services should contain business logic
        - Verify async database operations via repositories/database layer
        - Check cache invalidation on POST/PUT/DELETE operations
        - Ensure proper error handling with try/except where needed
        - Validate that Pydantic models are converted properly (model_dump())

    - path: "databases/**/*.py"
      instructions: |
        - Verify AsyncSession usage with proper async context managers
        - Check that async_session generator uses yield pattern
        - Ensure SQLAlchemy engine is configured with aiosqlite
        - Validate database initialization in lifespan handler

    - path: "schemas/**/*.py"
      instructions: |
        - SQLAlchemy ORM schemas should use declarative base
        - Check proper column types and constraints
        - Verify table names are explicitly set
        - Ensure relationships are defined if needed

    - path: "models/**/*.py"
      instructions: |
        - Pydantic models should use Field for validation
        - Verify camelCase aliasing with model_config = ConfigDict(alias_generator=to_camel)
        - Check that validation constraints match business rules
        - Ensure models are separate from database schemas

    - path: "tests/**/*.py"
      instructions: |
        - Tests should use pytest with fixtures from conftest.py
        - Verify test naming follows test_request_{method}_{resource}_{param_or_context}_response_{outcome} pattern
        - Check that TestClient is used for endpoint testing
        - Ensure test data uses stubs (e.g., player_stub.py)
        - Validate coverage targets (80% minimum)

    - path: "main.py"
      instructions: |
        - Verify FastAPI app initialization with proper settings
        - Check lifespan handler for database initialization
        - Ensure router registration is correct
        - Validate CORS and middleware configuration

    - path: "**/Dockerfile"
      instructions: |
        - Verify Python 3.13 base image (python:3.13.3-slim-bookworm)
        - Check multi-stage build using pyproject.toml + uv.lock → uv export → wheelhouse
        - Ensure runtime stage installs from prebuilt wheels with no network access
        - Ensure non-root user is used for security
        - Validate HEALTHCHECK instruction is present
        - Check that uv version is pinned for reproducibility

    - path: "pyproject.toml"
      instructions: |
        - Verify Black configuration (line-length = 88, target-version = ["py313"])
        - Check pytest configuration matches test execution
        - Ensure tool configurations are consistent with CI
        - Dependencies are managed via uv with PEP 735 dependency groups
        - Verify [dependency-groups] has test, lint, and dev groups defined
        - Check that uv.lock is present and up to date

    - path: ".github/workflows/*.yml"
      instructions: |
        - Verify uv is set up via astral-sh/setup-uv with a pinned version
        - Check that dependencies are installed via uv pip install --group dev
        - Ensure pytest runs with -v for verbosity and --cov for coverage reporting
        - Validate coverage report upload step is present

  path_filters:
    - "!**/__pycache__/**"
    - "!**/.pytest_cache/**"
    - "!**/htmlcov/**"
    - "!**/*.pyc"
    - "!**/.venv/**"
    - "!**/venv/**"
    - "!**/storage/**"
    - "!**/*.db"
    - "!**/*.db-shm"
    - "!**/*.db-wal"
    - "!**/postman_collections/**"
    - "!**/uv.lock"

  auto_review:
    enabled: true
    auto_incremental_review: true
    ignore_title_keywords:
      - "WIP"
      - "DO NOT REVIEW"
      - "wip"
    drafts: false
    base_branches:
      - master
      - main

  finishing_touches:
    docstrings:
      enabled: true
    unit_tests:
      enabled: true
    custom:
      - name: "sync documentation"
        instructions: |
          This is a PoC/learning project targeting developers unfamiliar with the stack.
          Documentation is a first-class concern. Review the PR changes and perform the
          following three checks:

          ## 1. Method/function docstrings
          For every public function, method, or handler touched in the PR:
          - If it lacks a docstring/doc comment, add one using the idiomatic format
            for the language and framework in use.
          - If it has one but no longer matches the current signature, parameters,
            or behavior, update it.
          - Docstrings should explain *why* and *what*, not just restate the signature.
            Assume the reader is learning the language.

          ## 2. README.md
          Check whether the PR introduces or removes endpoints, changes behavior,
          adds dependencies, or modifies how to run the project.
          If so, update the relevant sections of README.md to reflect the current state.
          Do not rewrite sections unrelated to the changes.

          ## 3. .github/copilot-instructions.md
          If the PR introduces patterns, conventions, or architectural decisions that
          should guide future AI-assisted contributions, add or update the relevant
          instructions in .github/copilot-instructions.md.
          Focus on things a developer (or AI assistant) unfamiliar with this specific
          stack implementation should know before writing code here.

      - name: "enforce http error handling"
        instructions: |
          Audit all HTTP handler functions in the changed files.
          Verify that errors return appropriate HTTP status codes (400 for bad input,
          404 for not found, 500 for unexpected errors) and a consistent JSON error
          body with at least a "message" field.
          Flag handlers that return 200 on error, swallow errors silently, or use
          bare status-only responses without a JSON body.
          Do not make changes; only report findings as a comment so fixes can be
          applied consistently across the entire codebase.

      - name: "idiomatic review"
        instructions: |
          Review the changed files for non-idiomatic patterns given the language and
          framework in use. Flag code that looks like it was translated from another
          language rather than written naturally for this stack. Suggest idiomatic
          alternatives with brief explanations. This is a PoC comparison project,
          so idiomatic usage is a first-class concern.

      - name: "verify api contract"
        instructions: |
          Review the changed files and verify that all HTTP endpoints (method, path,
          request body shape, and response shape) match the project's intended REST API
          contract. Check the README or any spec/contract file in the repo for reference.
          Flag any deviations — missing fields, wrong status codes, inconsistent naming.
          Do not make changes; only report findings as a comment.

  pre_merge_checks:
    docstrings:
      mode: warning
      threshold: 80
    title:
      mode: warning
      requirements: |
        - Use Conventional Commits format (feat:, fix:, chore:, docs:, test:, refactor:, ci:, perf:)
        - Keep under 80 characters
        - Be descriptive and specific
    description:
      mode: off
    issue_assessment:
      mode: off

  tools:
    # Secret scanners
    gitleaks:
      enabled: true
    trufflehog:
      enabled: true

    # IaC / infrastructure
    checkov:
      enabled: true
    trivy:
      enabled: true
    hadolint:
      enabled: true

    # General static analysis
    semgrep:
      enabled: true
    opengrep:
      enabled: true
    ruff:
      enabled: true

    # File-type linters
    yamllint:
      enabled: true
    actionlint:
      enabled: true
    markdownlint:
      enabled: true
    dotenvLint:
      enabled: true
    checkmake:
      enabled: true
    osvScanner:
      enabled: true
    github-checks:
      enabled: true
      timeout_ms: 120000

    # Prefer ruff over legacy Python linters (flake8, pylint)
    flake8:
      enabled: false
    pylint:
      enabled: false
    # Disable tools for other languages/platforms
    shellcheck:
      enabled: false
    biome:
      enabled: false
    swiftlint:
      enabled: false
    phpstan:
      enabled: false
    phpmd:
      enabled: false
    phpcs:
      enabled: false
    golangci-lint:
      enabled: false
    detekt:
      enabled: false
    eslint:
      enabled: false
    rubocop:
      enabled: false
    buf:
      enabled: false
    regal:
      enabled: false
    pmd:
      enabled: false
    clang:
      enabled: false
    cppcheck:
      enabled: false
    clippy:
      enabled: false
    sqlfluff:
      enabled: false
    prismaLint:
      enabled: false
    oxc:
      enabled: false
    shopifyThemeCheck:
      enabled: false
    luacheck:
      enabled: false
    brakeman:
      enabled: false
    htmlhint:
      enabled: false
    languagetool:
      enabled: false
    circleci:
      enabled: false
    fortitudeLint:
      enabled: false
    stylelint:
      enabled: false
    blinter:
      enabled: false
    psscriptanalyzer:
      enabled: false

chat:
  art: true
  auto_reply: true

knowledge_base:
  opt_out: false
  web_search:
    enabled: true
  code_guidelines:
    enabled: true
    filePatterns:
      - ".github/copilot-instructions.md"
  learnings:
    scope: auto
  issues:
    scope: auto
  pull_requests:
    scope: auto
  mcp:
    usage: auto

code_generation:
  docstrings:
    language: en-US
    path_instructions:
      - path: "**/*.py"
        instructions: |
          - Use Google-style docstrings with Args, Returns, Raises sections
          - Keep documentation concise and meaningful
          - Include type information in docstrings when helpful
          - Document async functions and their async behavior
  unit_tests:
    path_instructions:
      - path: "tests/**/*.py"
        instructions: |
          - Use pytest framework with async support (pytest-asyncio)
          - Follow test_request_{method}_{resource}_{param_or_context}_response_{outcome} pattern
          - Tests use arrange-act-assert structure within test body
          - Use fixtures from conftest.py for TestClient
          - Use test stubs for consistent test data
          - Ensure async tests are properly decorated
          - Run via uv: uv run pytest -v --cov=./ --cov-report=xml --cov-report=term
          - Target 80% code coverage minimum

issue_enrichment:
  auto_enrich:
    enabled: true
  planning:
    enabled: true
    auto_planning:
      enabled: true
      labels:
        - planning
  labeling:
    labeling_instructions: []
    auto_apply_labels: false