.coderabbit.yaml

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

language: "en-US"
early_access: false

reviews:
  # Assertive and advisory, as in CheatEngine.SDK: CodeRabbit reviews thoroughly but never approves, requests changes or
  # sets a required status. The only required check is "CI / Gate".
  profile: "assertive"
  request_changes_workflow: false
  high_level_summary: true
  review_status: false
  commit_status: false
  fail_commit_status: false
  poem: false
  pre_merge_checks:
    # Every check is a warning: none of them can block a merge. No required check enforces the title or changelog
    # rules; this review is the only thing that flags a miss.
    title:
      mode: "warning"
      requirements: >-
        Pull requests are squash-merged, so the title becomes the commit subject on main (a single-commit pull request
        keeps its commit's subject, which follows the same convention); a pull request that contains a commit listed in
        .git-blame-ignore-revs is merged with a merge commit instead, whose message repeats the title under GitHub's
        "Merge pull request" subject. The convention: an imperative sentence (Add, Fix, Keep...) starting with an
        uppercase letter, at most 72 characters, no Conventional Commit prefix such as "feat:" or "fix(scope):", no
        trailing period.
    description:
      mode: "warning"
    docstrings:
      mode: "off" # CS1591 already fails the build for an undocumented public API
    custom_checks:
      - name: "Workflow and Gate contract"
        mode: "warning"
        instructions: >-
          Applies only to changes under .github/; otherwise pass. Fail when: an action is referenced by tag or branch
          instead of a full 40-character commit SHA with a version comment; a workflow uses pull_request_target, adds a
          merge_group trigger or relies on a merge queue; pull-request-ci.yml gains paths or paths-ignore;
          actions/checkout omits persist-credentials: false; a job added to ci.yml is missing from the
          needs of the gate job; the Gate accepts a skipped or failed result for any job other than sonar, or accepts a
          skipped sonar while SONAR_EXPECTED is true; the if: expression of the sonar job and the SONAR_EXPECTED
          expression of the Gate differ; a job runs on a label other than windows-2025 or ubuntu-24.04 or has no
          timeout-minutes; ci.yml, sonar.yml, codeql.yml or release.yml enables a NuGet package cache (the Sonar
          analyzer cache saved only from main is the single exception); a job that runs dotnet does not use
          ./.github/actions/setup-dotnet with its locked restore; a run: script expands a user-controlled ${{ }} value
          instead of reading it from env:; a PowerShell step runs a native command without checking $LASTEXITCODE; a
          workflow grants write permissions at the top level; the caller job id ci named CI or the reusable job gate
          named Gate is renamed; SONAR_TOKEN can reach fork or Dependabot runs; or an
          uploaded artifact name is not in the reserved list of WorkflowContractTests. Otherwise pass.
      - name: "Public API, documentation and changelog"
        mode: "warning"
        instructions: >-
          Applies when public or protected API in libs/, src/ or source-generators/ is added, removed or changes
          signature or behavior, when a diagnostic identifier or message changes, or when the template under templates/
          changes what it generates; otherwise pass. Pass when the owning project's PublicAPI.Unshipped.txt declares the
          API change, every new public member has XML documentation, the sibling README.md is updated where it
          documents the contract, and CHANGELOG.md has an entry under "## [Unreleased]" in the matching category
          (Added for an extension, Changed for a semantic correction, Security for a hardened refusal, Deployment for
          what is built, packed, pinned or published). Also fail when PublicAPI.Shipped.txt changes outside a release
          pull request, which promotes Unshipped to Shipped once, as its last API commit (the 1.0.0 release pull request
          started from Shipped files that held only "#nullable enable"). From 1.0.0 on, also fail when a stable public
          API listed in a PublicAPI.Shipped.txt file is removed or changes signature or meaning before a new major
          version, when the value of a public enum member changes, or when an interface whose remarks say Implementable
          gains, loses or changes a member (the README section "Versioning and compatibility" lists them); an interface
          whose remarks say Call-only may gain members in a minor release, and an API marked
          [Experimental("CECLIENT500x")] may change in one. Fail otherwise.
      - name: "SDK boundary and pin"
        mode: "warning"
        instructions: >-
          Fail when: a public Client signature exposes LuaState, CEObject, Owned<T>, a native pointer, an
          activation-bound handle or another SDK ownership type, or an SDK type outside the allowlist of
          tests/CheatEngine.Client.Tests/PublicClientSignatureBoundaryTests.cs; a Core implementation type becomes
          public; Client code declares a native import or binds a Lua global itself (the architecture ratchet in
          tests/CheatEngine.Client.Tests/Architecture refuses both); Client code uses the SDK Lua stack or an SDK owner
          directly, outside the sanctioned typed SDK surface of that ratchet, without a registered exception that
          states its reason and names the missing CheatEngine.SDK primitive; Client code references or suppresses an
          [Experimental] CheatEngine.SDK member (CESDK5xxx); a CheatEngine.SDK version literal appears outside
          eng/CheatEngineSdk.props; CheatEngineSdkUpperBound or _CheatEngineClientSupportedSdkMajor changes, which moves
          the Client to another CheatEngine.SDK major: that is a new Client major version and a deliberate, reviewed
          migration, never part of a 1.x change (there is no automated migration guide; the bump procedure and the major
          migration checklist are documented in eng/CheatEngineSdk.props itself); a CheatEngine.SDK version change
          within the major skips a step of that bump procedure; or a packages.lock.json changes without a project or
          package change that explains it. Otherwise pass.
      - name: "Qualification evidence"
        mode: "warning"
        instructions: >-
          Pass when every validation claimed in the description states its level: C0 static contract, C1 managed tests
          or doubles, C2 native fixture, C3 exact Cheat Engine host with a loaded plugin, C4 several components (two
          plugins, a target switch). Fail when a C1 or C2 result, a CI run or a Native AOT publication is presented as
          Cheat Engine host qualification; when a capability is described as available without host evidence; when a
          document claims a host qualification, a scenario result or a live run id that the committed evidence under
          tests/CheatEngine.Client.Tests/LiveQualification/Evidence does not hold; or when an
          [Experimental("CECLIENT500x")] attribute, or the [CECLIENT500x] prefix of its PublicAPI lines, is removed
          before that evidence covers every scenario its capability requires (RELEASING.md, "Qualification gate").
          Otherwise pass.

  # The GitHub App performs automatic reviews. No CodeRabbit token, CLI, or workflow is used here.
  auto_review:
    enabled: true
    auto_incremental_review: true
    auto_pause_after_reviewed_commits: 0
    drafts: false
    base_branches: ["main"]
    ignore_usernames: ["dependabot[bot]"]

  tools:
    github-checks:
      enabled: true
    # actionlint and zizmor run in the "Lint" job of ci.yml on every event, pinned and checksum-verified; do not
    # duplicate them here.
    actionlint:
      enabled: false

  path_filters:
    - "!artifacts/**"
    - "!TestResults/**"
    - "!**/bin/**"
    - "!**/obj/**"
    - "!**/packages.lock.json"
    - "!**/*.nupkg"
    - "!**/*.snupkg"
    - "!**/*.g.cs"
    - "!**/*.generated.cs"

  path_instructions:
    - path: "libs/CheatEngine.Client.Abstractions/**"
      instructions: |
        Preserve a public, high-level Client API. Do not expose LuaState, CEObject, Owned<T>, native pointers,
        activation-bound handles, or SDK lifetime ownership. SDK values that cross this API must be stable copied values.
        Every public interface says in its remarks whether it is Call-only or Implementable: within 1.x a Call-only
        interface may gain members in a minor release, an Implementable one never changes. Public enums are int enums
        with explicit values that never change meaning; an outcome enum (Kind, Status, State, Effect, Scope) keeps
        Unknown = 0. Every public change is declared in PublicAPI.Unshipped.txt, and an experimental API keeps its
        [Experimental("CECLIENT500x")] attribute and the [CECLIENT500x] prefix of its PublicAPI lines.

    - path: "libs/CheatEngine.Client.Core/**"
      instructions: |
        Treat Core as the internal execution adapter to CheatEngine.SDK. Verify SDK mappings stay internal, partial
        effects and operational errors remain observable, and Client resources are released before SDK detachment.
        Flag any public Client API that leaks an SDK handle or an SDK lifetime responsibility, and any SDK exception
        that can escape a Try* method.

    - path: "libs/CheatEngine.Client.Hosting/**"
      instructions: |
        Review activation lifecycle changes carefully: construction must not invoke Cheat Engine, DI scopes are per
        activation, cleanup is deterministic, and no state survives a disable/enable cycle.

    - path: "src/**"
      instructions: |
        Keep the facade developer-focused and independent from ABI, Lua binding, native ownership, and dispatcher
        details. Direct SDK dependencies must not bypass the Client Core layer. The packed README may contain absolute
        https links only.

    - path: "source-generators/**"
      instructions: |
        Require deterministic generated output and diagnostics that preserve public-boundary protections. Do not relax
        lifetime or interop safeguards without focused tests, and do not introduce public SDK-bound handles.

    - path: "templates/**"
      instructions: |
        Keep templates approachable for plugin developers while preserving the explicit SDK bootstrap and generation
        assets they require. Package and template smoke coverage belongs in the C# test suite. Template code must not
        log addresses, values, Lua text or raw failures.

    - path: "tests/**"
      instructions: |
        Require behavior tests for success, failure, cancellation, cleanup, and lifecycle transitions. Tests use
        xUnit v3 on Microsoft.Testing.Platform; CI runs the whole solution once in Debug and once in Release with
        --fail-skips on, so a skipped test fails both: select tests by trait, never hide one with Skip. The package
        consumption tests consume the packages the Release leg packed (CHEATENGINE_CLIENT_PACKAGE_SOURCE) and keep
        realistic Client plus SDK dependencies. Distinguish managed, fixture and Native AOT probes from live Cheat
        Engine host qualification.

    - path: "tests/**/Architecture/**"
      instructions: |
        The architecture ratchet freezes the Client's ADR-01 debt. Shrinking a frozen list is always acceptable.
        FrozenLuaGlobals stays empty. Growing FrozenLuaUsage requires a registered exception, in the ratchet itself,
        with its reason and the name of the CheatEngine.SDK primitive that is missing (AwaitingSdkPrimitive); flag an
        exception that names no missing SDK primitive, and a new Permanent entry outside UnsafeLuaClient (there is no
        separate migration guide file). SanctionedSdkLuaSurface is exact: each typed SDK Lua member the Client uses
        carries its reason. SdkExperimentalApiRatchetTests forbids any reference to or suppression of an [Experimental]
        SDK member.

    - path: ".github/**"
      instructions: |
        pull-request-ci.yml, main-ci.yml and release.yml are thin callers of the reusable ci.yml through the job id
        ci named CI; there is no merge queue and no merge_group trigger. Exactly one check is required: "CI / Gate";
        never rename it or add a path filter to pull-request-ci.yml. The Gate evaluates toJSON(needs): every ci.yml
        job (build-test Debug and Release, aot, sonar, lint, format, dependency-review, lock-files) must succeed, and
        only sonar may be skipped, exactly when SONAR_EXPECTED is false (fork or Dependabot pull request, release
        run); the sonar if: expression repeats SONAR_EXPECTED textually. A job missing from gate.needs, an unpinned
        action, a runner label other than windows-2025 or ubuntu-24.04, a job without timeout-minutes or an
        unreserved artifact name fails WorkflowContractTests. The Lint job runs actionlint and the offline zizmor
        audits on every event; do not ask for a duplicate CodeRabbit actionlint run. Every dotnet job uses
        ./.github/actions/setup-dotnet (locked restore, cache off); no NuGet cache in ci.yml, sonar.yml, codeql.yml or
        release.yml. Require SHA-pinned actions, least privilege, persist-credentials: false, user text through env:
        only and $LASTEXITCODE checks. CodeQL, Scorecard, zizmor-online and dependency-submission are advisory.
        scorecard.yml intentionally has no defaults, env or run steps. Write permissions are granted per job with a
        reason comment: outside release.yml, contents: write exists only in the dependency-submission.yml job submit.
        Never use pull_request_target. In dependabot.yml, every ecosystem keeps a cooldown of at least 7 days,
        CheatEngine.SDK majors stay ignored, and CheatEngine.SDK stays out of every group, version and security updates
        alike (DependabotConfigurationTests).

    - path: ".github/workflows/release.yml"
      instructions: |
        Keep the contract order verify -> ci -> stage -> attest -> draft-release -> publish -> verify-publication ->
        finalize-release. The ci job calls ci.yml with package-version and package-retention-days: 90 and never passes
        sonar. No package cache and no binary log in the release path. NuGet/login stays in the publish job, behind
        the nuget environment and the tag and repository guard; a dispatch run stays a dry run, and stage, the only
        job after ci that it runs, keeps a read-only token without id-token.

    - path: "{SECURITY.md,.github/CODEOWNERS,.github/ISSUE_TEMPLATE/**}"
      instructions: |
        Keep the required fields of the compatibility form aligned with the Client release tuple (package versions,
        consumed CheatEngine.SDK identity, native bridge, host profile), and the version placeholders on the Client
        line and the pinned CheatEngine.SDK (IssueFormTests). SECURITY.md lists the supported Client line with the
        CheatEngine.SDK range it requires. Vulnerabilities are reported privately, never in public issues. CODEOWNERS
        stays informational.

    - path: "eng/CheatEngineSdk.props"
      instructions: |
        The consumed CheatEngine.SDK pin has this single source; there is no separate identity file or bump script.
        A version change updates the reviewed identity literals it names (in PackagedClientFeedFixture.cs and
        LockFileTests.cs), regenerates every packages.lock.json, and updates the SDK version named in prose, all in
        one reviewed pull request. Moving to another major is a deliberate migration, not a dependency bump.

    - path: "{Directory.Build.props,Directory.Build.targets,Directory.Packages.props,global.json}"
      instructions: |
        Preserve the net10/MTP/package validation contracts and central dependency management. The exact SDK pin
        (rollForward: disable), the analysis level, the NuGet audit policy and the lock-file requirement are guarded by
        CHEATENGINECLIENT9030-9032. Flag a change that weakens the Client to SDK layering rules or makes builds and
        tests less reproducible.

    - path: "CHANGELOG.md"
      instructions: |
        Keep a Changelog 1.1.0 with the exact heading "## [Unreleased]" and its four categories in order: Added,
        Changed, Security, Deployment. The release workflow reads that section for the release notes.

    - path: "{README.md,ROADMAP.md}"
      instructions: |
        Keep the architecture boundary explicit: CheatEngine.SDK owns ABI, native bindings, Lua globals, dispatcher,
        and native resource ownership; CheatEngine.Client owns high-level workflows, policies, and developer ergonomics.
        Never present a managed, fixture or CI result as Cheat Engine host qualification.

knowledge_base:
  code_guidelines:
    enabled: true
    filePatterns:
      - "CONTRIBUTING.md"
  linked_repositories:
    - repository: "CheatEngineNet/CheatEngine.SDK"
      instructions: |
        This is the authoritative low-level SDK. Use it to assess API/package compatibility and invariants around ABI,
        native ownership, dispatcher behavior, and Lua bridging. Client changes must not duplicate or expose these
        implementation responsibilities.

chat:
  # Keep conversations opt-in with an explicit @coderabbitai mention.
  auto_reply: false