.coderabbit.yaml

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

# CodeRabbit Configuration
# StringManipulation PHP 8.3+ Library
# Enforces strict quality standards: PHPStan MAX, SOLID principles, PER-CS2.0

# Language and Tone
language: en-ZA
early_access: true
tone_instructions: >-
  Expert PHP reviewer proficient in PER Coding Style 2.0, SOLID, and FOOP.
  Advise on immutable data, pure functions, and functional composition.
  Provide concise, actionable feedback.

# Review configuration
reviews:
  # Review profile and behaviour
  profile: "assertive"
  request_changes_workflow: true
  high_level_summary: true
  high_level_summary_placeholder: "@coderabbitai summary"
  poem: false
  review_status: true
  commit_status: true
  fail_commit_status: false
  collapse_walkthrough: true

  # Walkthrough features
  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: true
  auto_assign_reviewers: false

  # Path filters (exclude generated files, vendor, etc.)
  path_filters:
    - "!vendor/**"
    - "!reports/**"
    - "!node_modules/**"
    - "!*.lock"
    - "src/**"
    - "tests/**"

  # Path-specific instructions
  path_instructions:
    - path: "**/*.php"
      instructions: |
        Review PHP code for adherence to PER Coding Style 2.0 guidelines.
        Ensure proper namespace usage, code organisation, and separation
        of concerns. Verify that SOLID principles are followed and
        encourage FOOP techniques—such as immutable data, pure functions,
        and functional composition—to improve maintainability,
        testability, and performance.

        Specific checks:
        - Strict typing: `declare(strict_types=1);` is required
        - Explicit type declarations for all parameters and return types
        - Final classes with static methods where appropriate
        - Comprehensive docblocks with @param, @return, and @example tags
        - No methods exceeding 100 lines (PHPMD rule)
        - PHP 8.3+ features and patterns
        - Proper error handling and null safety

    - path: "tests/**/*.php"
      instructions: |
        Review test code for:
        - TDD compliance (tests should be clear and comprehensive)
        - PHPUnit best practices
        - 100% coverage for critical paths, 90%+ for standard code
        - Fast execution (unit tests <100ms, integration <5s)
        - Independent, deterministic tests
        - Descriptive test names and clear assertions
        - Proper mocking and test isolation

  # Automatic review settings
  auto_review:
    enabled: true
    auto_incremental_review: true
    ignore_title_keywords:
      - "WIP"
      - "DO NOT MERGE"
      - "DRAFT"
    drafts: false
    base_branches:
      - "main"
      - "develop"
      - "feat/.*"
      - "fix/.*"
      - "refactor/.*"

  # Finishing touches
  finishing_touches:
    docstrings:
      enabled: true
    unit_tests:
      enabled: true

  # Pre-merge checks
  pre_merge_checks:
    docstrings:
      mode: "error"
      threshold: 80

    title:
      mode: "warning"
      requirements: "Follow conventional commits format: type(scope): description. Types: feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|security|deps|config|release"

    description:
      mode: "warning"

    issue_assessment:
      mode: "warning"

    custom_checks:
      - mode: "error"
        name: "Strict Type Declarations"
        instructions: "All PHP files in src/ must begin with `declare(strict_types=1);` after the opening PHP tag and before the namespace declaration."

      - mode: "error"
        name: "No Debugging Functions"
        instructions: "Production code (src/ directory) must not contain debugging functions: var_dump(), var_export(), print_r(), dd(), or dump()."

      - mode: "warning"
        name: "Test Coverage"
        instructions: "New code must have corresponding PHPUnit tests. Critical features require 100% line coverage; standard features require 90% coverage."

      - mode: "warning"
        name: "Performance Complexity"
        instructions: "Algorithms should avoid O(n²) or worse time complexity. Document Big O time complexity for non-trivial algorithms."

      - mode: "warning"
        name: "Security Best Practices"
        instructions: "Validate all user input. Use parameterised statements for SQL queries. Never hardcode secrets, credentials, or API keys."

  # Tools configuration
  tools:
    # GitHub Checks - MAX TIMEOUT (15 minutes)
    github-checks:
      enabled: true
      timeout_ms: 900000

    # PHP Tools
    phpstan:
      enabled: true
      level: "max"

    phpmd:
      enabled: true

    phpcs:
      enabled: true

    # Security and quality tools
    gitleaks:
      enabled: true

    actionlint:
      enabled: true

    semgrep:
      enabled: true

    # Documentation and style
    languagetool:
      enabled: true
      level: "default"
      enabled_only: false

    # Disable non-PHP tools to reduce noise
    shellcheck:
      enabled: false

    ruff:
      enabled: false

    eslint:
      enabled: false

    yamllint:
      enabled: true

# Chat configuration
chat:
  auto_reply: true
  art: true

# Knowledge base
knowledge_base:
  opt_out: false

  web_search:
    enabled: true

  code_guidelines:
    enabled: true
    filePatterns:
      - "**/CLAUDE.md"
      - "**/.cursorrules"
      - ".github/copilot-instructions.md"
      - "docs/coding-standards.md"

  learnings:
    scope: "auto"

  issues:
    scope: "local"

  pull_requests:
    scope: "local"

# Code Generation Configuration
code_generation:
  # Docstring Generation
  docstrings:
    language: en-ZA
    path_instructions:
      - path: "src/**/*.php"
        instructions: |
          Focus on explaining business behaviour and functionality, not obvious implementation.
          Use South African English spelling (organisation, optimisation, analyse, behaviour).
          Include @param and @return tags with proper types.
          Add @throws for exceptions.
          Add @example tags demonstrating usage.
          Reference related documentation with @see tags.
          Follow PER Coding Style 2.0 conventions.

  # Unit Test Generation
  unit_tests:
    path_instructions:
      - path: "src/**/*.php"
        instructions: |
          Generate PHPUnit tests following TDD principles:
          - Test names must describe behaviour: test_methodName_condition_expectedBehaviour
          - Each test must follow the AAA pattern (Arrange-Act-Assert)
          - Include unit tests for all public methods, edge cases, and error conditions
          - Tests must be independent and deterministic
          - Target fast execution (<100ms for unit tests)
          - Use data providers with #[DataProvider] for testing multiple scenarios
          - Focus on critical functionality and edge cases