.coderabbit.yaml

# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
# CodeRabbit AI Review Configuration for openshift-virtualization-tests
# Based on project-specific rules from CLAUDE.md

language: en-US

tone_instructions: "Be direct and specific. Explain WHY rules exist. Provide code examples. Distinguish critical violations from suggestions. Use severity levels: CRITICAL (blocking/security), HIGH (types/fixtures), MEDIUM (style), LOW (suggestions)."

early_access: true
enable_free_tier: true

inheritance: false

code_generation: {}

issue_enrichment: {}

reviews:
  # Explicit instructions applied to every review, including PR description validation
  path_instructions:
    - path: "utilities/unittests/**"
      instructions: |
        ## Unit Tests — Relaxed Rules
        Files under `utilities/unittests/` are unit tests for shared utilities.
        Do NOT enforce:
        - STD docstring format (Preconditions/Steps/Expected sections)
        - STP link requirements
        - RFE/Jira link requirements
        - Coverage tracking rules
        These rules apply only to feature/integration tests under `tests/`.
        DO still enforce: code quality, type hints, naming conventions, and all other coding standards.

    - path: "tests/**"
      instructions: |
        ## STP traceability — inline comments required
        When an `STP:` link is present and linked-repo analysis finds missing or misaligned
        scenarios, you MUST post an INLINE review comment on the `STP:` line (or the module
        docstring when the STP line is unchanged) containing:
        - **STP coverage: X/Y scenarios**
        - A table of each STP scenario → covered / missing / misaligned / deleted
        - CRITICAL severity for missing P0 scenarios without documented exclusion in the PR
          description (justification + follow-up Jira link per scenario)
        Do NOT report STP coverage gaps only in PR conversation chat.

        ## STP alignment on modification and deletion
        When a test referencing an `STP:` URL is modified, use the same
        inline-comment placement as the "STP traceability" section above: post on the
        changed lines (docstring, assertion, or fixture) when available, otherwise fall
        back to the `STP:` line or module docstring.

        **Modification (STP-linked tests only):** Verify the modified docstring AND test
        body still align with the linked STP scenario. Flag as HIGH with
        "STP misalignment detected" and explain what changed vs. what the STP says.
        This check does NOT apply to tests with only `Jira:` or `RFE:` links (no STP
        to compare against).

        **Deletion (any traceability link):** Handled by the "STP scenario coverage"
        pre-merge check. Do not duplicate deletion comments here.

        ## special_infra marker enforcement
        Newly added tests that use hardware or special-configuration markers from `pytest.ini`
        MUST also declare `@pytest.mark.special_infra` at module (`pytestmark`), class, or test
        level. Flag missing `special_infra` as HIGH.

        Triggering markers (require `special_infra`): `gpu`, `sriov`, `bgp`, `ibm_bare_metal`,
        `dpdk`, `swap`, `cpu_manager`, `numa`, `hugepages`, `jumbo_frame`, `rwx_default_storage`,
        `descheduler`, `high_resource_vm`.

        Exempt (do NOT require `special_infra`): `single_nic`, `remote_cluster`, `mixed_os_nodes`,
        `cclm`, and operator-only markers (`hpp`, `mtv`, `tekton`, `service_mesh`, `nmstate`).

    - path: "**"
      instructions: |
        ## Approval Policy
        You may approve the PR when ALL of the following are true:
        - All your review comments have been addressed with either:
          - a code/doc change that fixes the issue, or
          - a substantive author response that justifies no code change.
          Thread "resolved" state alone is not sufficient.
          OR you had no review comments.
        - If you posted a test execution plan comment requesting tests, and the PR author replied
          with a comment explaining why the requested tests are not needed or were already covered,
          treat that as an acceptable response — do not block approval on the test plan alone.
        - The author's explanation must be reasonable and specific (not just "N/A" or "not needed").
          Accept explanations like: "these tests were already run in CI", "this change is docs-only",
          "the affected tests are quarantined", or "verified manually on cluster X".

  # Assertive profile for strict enforcement of coding standards
  profile: assertive

  # Request changes for critical violations
  request_changes_workflow: true

  # Review display settings
  high_level_summary: true
  high_level_summary_placeholder: "@coderabbitai summary"
  auto_title_placeholder: "@coderabbitai"
  review_status: true
  commit_status: true
  review_details: true
  poem: false
  collapse_walkthrough: true

  # Auto-suggest labels
  labeling_instructions:
    - label: "new-tests"
      instructions: "Apply when the PR adds new test files (test_*.py) or new test functions (def test_*)."
    - label: "docs-only"
      instructions: "Apply when the PR only changes .md files."
  sequence_diagrams: false
  changed_files_summary: true

  # Targeted pre-merge checks - only run on changed files
  # path_filters: markdown files are reviewed (AGENTS.md, docs/*.md contain coding standards)
  path_filters:
    - "!docs/site/**"

  # Abort review if PR is closed
  abort_on_close: true

  # Pre-merge checks for PR quality
  pre_merge_checks:
    title:
      mode: error
      requirements: "Must be under 120 chars and clearly describe the change."
    description:
      mode: "off"
    docstrings:
      mode: "off"
    custom_checks:
      - name: "PR Template Sections"
        mode: error
        instructions: |
          Check the current PR description (the actual, live PR body — not a cached or
          per-file view of it) for required sections from `.github/pull_request_template.md`.
          Required sections (must be present, even if empty):
          - `##### What this PR does / why we need it:` — MUST be present AND have meaningful
            content. Fail as HIGH if the section is missing, empty, whitespace-only, contains
            only HTML comments, or contains only placeholder tokens such as `TBD`, `TBA`,
            `N/A`, `-`, `—`, `none`, or `.`.
          - `##### Which issue(s) this PR fixes:` — must be present (may be empty)
          - `##### Special notes for reviewer:` — must be present (may be empty)
          - `##### jira-ticket:` — must be present (may be empty)
          If any required section is absent, or `What this PR does / why we need it:` has no content,
          flag it as HIGH severity and ask the author to restore the missing template section(s).

      - name: "STP link required"
        mode: error
        instructions: |
          Check ONLY code that is newly added (not modified) in this PR's diff.
          SKIP this check entirely for files under `utilities/unittests/` — unit tests
          do not require STP/RFE/Jira links.

          This applies to two cases:
          A) A newly added test file (test_*.py) under `tests/`
          B) A newly added test function (def test_*) in an existing test file under `tests/`

          For each case, at least one of the following MUST appear in the
          module, class, or test function docstring:
          - A line with "STP:" followed by a URL
          - A line with "RFE:" followed by an issue tracker URL
          - A line with "Jira:" followed by an issue tracker URL

          If a module-level or class-level STP link already exists in the file,
          newly added test functions in that same file are considered covered.
          The @pytest.mark.polarion decorator alone does NOT satisfy this requirement.

          **Jira skip-marker enforcement:**
          When a `Jira:` line appears in a test docstring for traceability, it MUST
          also include `# <skip-jira-utils-check>` as an inline comment on the same line.
          This is required so the project's jira-utils checker skips traceability references.
          - Correct:   `Jira: https://redhat.atlassian.net/browse/CNV-87822  # <skip-jira-utils-check>`
          - Incorrect: `Jira: https://redhat.atlassian.net/browse/CNV-80580`
          This does NOT apply to `STP:` or `RFE:` lines — only `Jira:` lines need the marker.
          Flag a missing `# <skip-jira-utils-check>` on a `Jira:` line as HIGH severity.

          Pass if no new test files and no new test functions are added in this PR.

      - name: "STP scenario coverage"
        mode: error
        instructions: |
          Apply when this PR adds, modifies, or deletes `test_*.py` under `tests/` that
          reference an `STP:`, `Jira:`, or `RFE:` URL in a module, class, or test docstring.
          SKIP `utilities/unittests/`.

          **Behavior depends on traceability type:**

          **When `STP:` is present** — full STP scenario alignment:

          Using linked repo `RedHatQE/openshift-virtualization-tests-design-docs`, read the
          referenced STP and compare its test scenarios to STD/test declarations in the PR diff.

          *New/existing tests:*
          PASS if every STP scenario has a corresponding STD/test declaration in the PR (or
          existing file), OR the PR description documents intentional exclusion with a
          follow-up Jira link per excluded scenario.
          Exempt from direct-declaration checks: regression scenarios intentionally excluded
          from the STP scenario table, and scenarios inherited from a parent STP via
          child-STP extension (child STPs extend the parent without duplicating its scenarios).

          *Modified tests:*
          When a test referencing an STP is modified (docstring, steps, assertions, or fixtures),
          verify the modified test still aligns with its STP scenario:
          1. Check that `Preconditions:`, `Steps:`, and `Expected:` docstring sections remain
             consistent with the STP scenario description.
          2. Check that changes to test body (assertions, fixture usage, helper calls) do not
             alter what the test validates in a way that diverges from the STP scenario.
             A test whose docstring says "verify X" but whose assertions now check Y is
             misaligned even if the docstring text is unchanged.
          Also verify the modified test still contains a valid `STP:` link in its
          module, class, or test docstring. FAIL if the modification removes or
          invalidates the only STP traceability reference.
          FAIL if the modification causes misalignment with the STP.

          *Deleted tests:*
          When a test (or test class/module) referencing an STP is deleted, verify:
          1. The PR description documents the justification for deletion (scenario removed
             from STP, consolidated into another test, feature deprecated, etc.)
          2. If the STP scenario is still valid, a follow-up Jira link for re-coverage is
             included in the PR description.
          FAIL if deleted without documented justification.

          FAIL with a table: scenario summary | STP tier/priority | status (covered/missing/misaligned/deleted).
          List every missing, misaligned, or unjustified-deleted scenario explicitly.

          **When only `Jira:` or `RFE:` is present** (no STP) — traceability preservation only:

          Do NOT run STP scenario comparison (there is no STP to compare against).

          *Modified tests:*
          No STP scenario comparison. However, verify the modified test still
          contains a valid `Jira:` or `RFE:` link in its module, class, or test
          docstring. FAIL if the modification removes or invalidates the only
          traceability reference.

          *Deleted tests:*
          The PR description MUST document the justification for deletion. If the Jira/RFE
          issue is still open or the feature is still valid, a follow-up Jira link for
          re-coverage MUST be included.
          FAIL if deleted without documented justification.

  # Auto-review configuration
  auto_review:
    enabled: true
    auto_incremental_review: true
    drafts: false
    auto_pause_after_reviewed_commits: 0
    ignore_title_keywords:
      - "WIP"
    base_branches:
      - main
      - cnv-4.22
      - cnv-4.21
      - cnv-4.20
      - cnv-4.19
      - cnv-4.18


  # Enabled linting and security tools
  tools:
    # Python linting
    ruff:
      enabled: true
    # Additional Python linting (stricter checks)
    pylint:
      enabled: true
    # Note: mypy is not a supported CodeRabbit tool - type checking is enforced via pre-commit and tox
    # YAML validation
    yamllint:
      enabled: true
    # Shell script checking
    shellcheck:
      enabled: true
    # Security scanning
    gitleaks:
      enabled: true
    semgrep:
      enabled: true
    # GitHub Actions workflow validation
    actionlint:
      enabled: true
    # Dockerfile linting
    hadolint:
      enabled: true
    # Markdown linting
    markdownlint:
      enabled: true
    # GitHub checks integration
    github-checks:
      enabled: true
      timeout_ms: 90000
    # Disabled tools (no JS/TS, PHP, Ruby, Kotlin, Rust, or Terraform in this repo)
    biome:
      enabled: false
    eslint:
      enabled: false
    phpstan:
      enabled: false
    rubocop:
      enabled: false
    detekt:
      enabled: false
    clippy:
      enabled: false
    checkov:
      enabled: false
    tflint:
      enabled: false

chat:
  auto_reply: true

knowledge_base:
  opt_out: false

  linked_repositories:
    # Link to design-docs repo for STP ↔ test traceability
    - repository: "RedHatQE/openshift-virtualization-tests-design-docs"
      instructions: |
        Contains Software Test Plans (STPs) under stps/<sig>/ defining
        test requirements, scenarios, and acceptance criteria.

        STRICT ENFORCEMENT (STD and test implementation PRs):
        - CRITICAL: Every STD PR MUST cover ALL STP scenarios, except
          explicitly excluded ones with justification and follow-up
          Jira link. Missing scenarios block merge.
        - CRITICAL: Every new feature test MUST link to its STP (or
          Jira/RFE if no STP exists) in module/class/test docstring.
          Missing traceability links block merge.
        - HIGH: STD preconditions, steps, and expected results MUST
          align with the STP scenario description.
        - HIGH: Intentionally excluded STP scenarios require PR
          description justification with a follow-up Jira link.
        - HIGH: Every STP feature scenario needs a corresponding STD.
          Exempt: regression scenarios excluded from the STP table,
          and scenarios inherited from a parent STP via child-STP.
        - HIGH: STP negative/edge-case scenarios MUST have tests.
        - HIGH: Modified tests referencing an STP must keep docstring
          and test body aligned with the STP scenario. Flag drift.
        - HIGH: Deleted STP/Jira/RFE-linked tests require PR
          justification. If scenario is still valid, include a
          follow-up Jira link. Unjustified deletion blocks merge.
        - Jira/RFE-only tests skip STP comparison but must retain
          traceability links on modification, and justify deletion.
        - Partial coverage without justification blocks merge.

  # Enable code guidelines enforcement from AGENTS.md (single source of truth)
  code_guidelines:
    enabled: true
    filePatterns:
      - "AGENTS.md"
      - "docs/AI_CONTRIBUTION_POLICY.md"

  # Enable learning from repository patterns
  learnings:
    scope: auto

  # Enable learning from issues
  issues:
    scope: auto

  # Enable learning from pull requests
  pull_requests:
    scope: auto