.coderabbit.yaml

# CodeRabbit configuration for stackctl
# Docs: https://docs.coderabbit.ai/reference/yaml-config

language: en-US

# Tone: terse, evidence-based. Verify against .github/instructions/ before
# suggesting wire-format/struct/convention changes. Anti-patterns to skip are
# listed in each path's instructions below; do not propose them.
tone_instructions: "Terse and evidence-based. Before any wire-format, struct, or convention change, VERIFY against .github/instructions/ and the backend handler. Never propose anti-patterns listed in path_instructions."

reviews:
  # Profile: CHILL is the right default for a small CLI maintained by one
  # person — avoids the noise of ASSERTIVE on every PR.
  profile: chill

  # Controls auto-approval behavior after requested changes or failing checks are
  # resolved (true enables the auto-approval workflow).
  request_changes_workflow: false

  # Skip review on paths CodeRabbit cannot meaningfully comment on.
  path_filters:
    - "!**/*.svg"
    - "!**/*.png"
    - "!**/*.jpg"
    - "!**/*.lock"
    - "!**/go.sum"
    - "!**/vendor/**"
    - "!**/testdata/**"

  # Pull in the project instruction files so CodeRabbit understands
  # project-specific conventions before commenting.
  path_instructions:
    - path: "cli/cmd/**"
      instructions: |
        Follow the rules in .github/instructions/commands.instructions.md.
        Key points:
        - All commands use RunE + SilenceUsage: true
        - --quiet outputs identifiers one per line via printer.PrintIDs or fmt.Fprintln(printer.Writer, ...)
          before the format switch. Documented quiet-mode exceptions (not numeric IDs):
            orphaned list → namespace names
            cluster nodes → node names
            cluster namespaces → namespace names
            cluster utilization → namespace names
            cluster health → derived status label (healthy/degraded/unknown)
            cluster test-connection → connection status string (success/error)
            notification prefs get/set → event_type names (the (user_id,
              event_type) tuple is the backend primary key; opaque UUID IDs
              are useless for scripting like `prefs get -q | grep failed`)
            git providers → provider type names (azure_devops, gitlab) —
              the response shape has no ID field at all
        - Destructive commands require --yes flag and stderr confirmation prompt
        - All API calls go through pkg/client via newClient()
        - parseID() for sub-resource IDs; resolveStackID() (and the
          resolveXxxID family more broadly) for name-or-ID resolution.
          resolveXxxID intentionally short-circuits via looksLikeID before
          falling back to a list+filter — do NOT suggest replacing this
          short-circuit with parseID(); it would force an extra API call
          on every command invocation that already has the ID.
        - The Args field on cobra.Command is set ONLY when positional args
          are required (e.g. Args: cobra.ExactArgs(1) for "delete <id>").
          Commands that take no positional args (list, create with flags,
          analytics subcommands, etc.) deliberately OMIT Args — matches
          the established convention in clusterListCmd, templateListCmd,
          userListCmd, etc. Do NOT suggest adding Args: cobra.NoArgs or
          cobra.ExactArgs(0) to these commands.

    - path: "cli/pkg/client/**"
      instructions: |
        Follow the rules in .github/instructions/client.instructions.md.
        Key points:
        - Every public method has a TSDoc-style Go doc comment with @see HTTP verb + route
        - Non-2xx responses are returned as *APIError (decoded from {"error":"..."} body)
        - The do() method handles all non-2xx uniformly; endpoint-specific structs are
          only populated on 200 responses
        - Query parameters on POST endpoints (e.g. ?dry_run=true on the
          cleanup-policy run route) are appended to the path string — the
          do() implementation uses url.Parse + ResolveReference which
          preserves RawQuery cleanly. This is intentional, not a bug.

    - path: "cli/pkg/output/**"
      instructions: |
        Follow the rules in .github/instructions/output.instructions.md.
        Key points:
        - printer.Quiet is a package-level var reset by ResetFlagsForTest() in tests
        - PrintIDs outputs identifiers one per line with no headers
        - Table output uses tabwriter; JSON/YAML use encoding/json and gopkg.in/yaml.v3

    - path: "cli/pkg/config/**"
      instructions: |
        Follow the rules in .github/instructions/config.instructions.md.

    - path: "cli/pkg/types/**"
      instructions: |
        Follow the rules in .github/instructions/types.instructions.md.
        Key points:
        - Every field must have both json: and yaml: struct tags
        - All ID fields are string, not int/uint
        - Resource structs embed Base; request/response-only structs do not
        - Update request structs: shape depends on backend handler semantics.
          * Partial-update backends (handler reads existing, decodes over it):
            pointer + omitempty fields (e.g. UpdateClusterRequest).
          * Full-upsert backends (handler decodes into a fresh struct and
            overwrites): plain value fields, no omitempty on bools
            (e.g. UpdateCleanupPolicyRequest). Document the full-upsert
            contract in the struct godoc.
          Do NOT suggest a pointer-field refactor without first checking
          the backend handler.
        - Every exported type must have a godoc comment stating the endpoint
          it corresponds to and when fields are populated vs zero-valued.
        - Structs only populated on HTTP 200 must state that explicitly.

    - path: "cli/**_test.go"
      instructions: |
        Follow the rules in .github/instructions/tests.instructions.md.
        Key points:
        - cmd/ tests must NOT use t.Parallel() (mutate package-level globals like printer.Quiet)
        - pkg/ tests should use t.Parallel() on both parent and subtests
        - Use httptest.NewServer for API mocking — never call real APIs in unit tests
        - Quiet-mode tests must assert names/identifiers only and assert.NotContains for
          table headers (NAME, STATUS, etc.)
        - Table-output tests assert header presence; JSON/YAML tests unmarshal and check fields
        - Do NOT suggest converting scenario tests (different mock state,
          different stdin plumbing, CRUD sequences) into table-driven form.
          The tests.instructions.md "When NOT to use table-driven tests"
          section documents which cases stay as separate Test* functions.

    - path: "cli/test/integration/**"
      instructions: |
        Integration tests run in-process against a mock server.
        - cmd.SetArgs/Execute calls share cobra's package-global flag state
          across calls within one test. ResetFlagsForTest() only resets the
          ROOT persistent flags (--output/--quiet/--api-url/etc.), NOT
          subcommand flags like --dry-run.
        - Tests that mix --dry-run states must either pass --dry-run=false
          explicitly, run the false case first, or call the test-only
          resetFlag helper. Do NOT suggest "just toggle the flag" — flag
          leakage between Execute() calls is a documented gotcha.

    - path: "cli/test/e2e/**"
      instructions: |
        E2E tests build and exec the stackctl binary against a mock server.
        - testing.Short() skip is mandatory.
        - Use runStackctl() / runStackctlWithStdin() — never spawn the
          binary directly via exec.Command.
        - Mock servers that parse /:id/<action> paths MUST reject unknown
          actions with 404 before falling through to PUT/DELETE handlers,
          to prevent /:id/<garbage> from silently mutating /:id.

  # Enable all severity levels
  high_level_summary: true
  poem: false
  review_status: true

  # Auto-summarise what changed
  auto_review:
    enabled: true
    drafts: false
    base_branches:
      - main

  # Instruct CodeRabbit to check against the project's coding conventions
  finishing_touches:
    docstrings:
      enabled: true

chat:
  auto_reply: true