.coderabbit.yaml

reviews:
  request_changes_workflow: true
  pre_merge_checks:
    enabled: true

  # Per-path natural-language review instructions.
  # See https://docs.coderabbit.ai/getting-started/configure-coderabbit
  path_instructions:
    - path: "src/platforms/*.impl.cpp.hpp"
      instructions: |
        FastLED platform dispatch file. Verify:
        - Dispatcher files are named `<component>.impl.cpp.hpp` and live in `src/platforms/` (root only — subdirectory `.cpp.hpp` files are translation-unit fragments, not dispatchers, and are out of scope for this rule).
        - They start with `// IWYU pragma: private` and use `#if defined(FL_IS_*)` to
          select platform fragments.
        - The `#else` branch must include a no-op fallback from `src/platforms/shared/`
          named `<component>_noop.hpp` (suffix is literally `_noop`, not `_null`, `_stub`,
          or `_dummy`). Flag any other fallback naming.
        - Platform fragments included by the dispatcher use the suffix `*.impl.hpp` (not
          `*.cpp.hpp` — that suffix is reserved for the dispatcher itself).
        - The `.impl.cpp.hpp` extension means "implementation router, include from exactly
          one translation unit." If a header includes this file, that's a violation.
        Reference: `agents/docs/cpp-standards.md` → "Naming convention (future standard)"
        and "No-op Fallback (`_noop.hpp`)".
    - path: "src/platforms/shared/*_noop.hpp"
      instructions: |
        FastLED no-op fallback header. Verify:
        - Header is marked `// IWYU pragma: private`.
        - All functions are `inline` and live in the `fl::platforms::` namespace
          (NOT `fl::` directly).
        - Function bodies return `0`, `false`, `nullptr`, or empty span — never assert,
          throw, or call FL_WARN/FL_DBG. The whole point is unconditional compilation.
        - If the parent subsystem declares `FL_<COMPONENT>_HAS_<FEATURE>` capability
          flags, the no-op must define NONE of the boolean flags but MUST define every
          numeric property to a sensible zero/default.
        Reference: `agents/docs/cpp-standards.md` → "No-op Fallback (`_noop.hpp`)".
    - path: "src/**/*.{h,hpp,cpp,cpp.hpp,impl.hpp}"
      instructions: |
        Macro naming — three types are recognized:
        1. `FL_IS_<PLATFORM>` — platform detection, defined-or-undefined, no value.
        2. `FASTLED_<NAME>` — **LEGACY-ONLY** configuration macros with explicit
           0/1/numeric values. **Frozen vocabulary** — do not invent new `FASTLED_*`
           names. All new configuration macros use the `FL_*` prefix.
        3. `FL_<COMPONENT>_HAS_<FEATURE>` — per-subsystem capability flag, defined-or-
           undefined, no value. `FL_<COMPONENT>_<NUMERIC>` — numeric property, explicit
           value. `FL_<COMPONENT>_<NAME>` — new configuration / tuning macros with
           explicit value (replaces the legacy `FASTLED_*` form).
        Critical rule: `<COMPONENT>` is the SPELLED-OUT name, NOT an acronym. The macro
        and the public API share a single vocabulary. If the API is `FastLED.watchdog()`,
        the macros are `FL_WATCHDOG_*`, NOT `FL_WDT_*`. If a PR introduces acronym-style
        capability macros, flag them and request the spelled-out form.

        **NEW MACRO PREFIX RULE (HIGH severity):** Any newly introduced `#define`,
        `-D<NAME>=...` build flag, or `defined(...)` check whose identifier starts with
        `FASTLED_` is a violation. Use `FL_<COMPONENT>_<NAME>` instead. Renaming an
        existing `FASTLED_*` macro is out of scope here — only NEW additions are flagged.
        Existing `FASTLED_*` references in the diff (touched but not introduced) are
        grandfathered. Examples:
          - ❌ `#define FASTLED_LPC_PWM_DMA 1`        →  ✅ `#define FL_LPC_PWM_DMA 1`
          - ❌ `#define FASTLED_LPC_RX_SCT_WS2812 1`  →  ✅ `#define FL_LPC_RX_SCT_WS2812 1`
          - ❌ `-DFASTLED_NEW_FEATURE=1` in build_flags →  ✅ `-DFL_NEW_FEATURE=1`
        Reference: `agents/docs/cpp-standards.md` → "Type 3: Component Capability Flags".

        Decayed fixed-size array parameter rule (HIGH severity):
        Do not allow function parameters spelled as `T value[N]` or `T value[]`.
        In C++, those parameters decay to pointers, so the declared extent is not
        enforced. Flag these in declarations, definitions, callback signatures, and
        small output-buffer APIs.

        Replacements:
          - For ISR / `FL_IRAM` APIs, require an array reference:
            `T (&value)[N]`.
          - For non-ISR APIs, use either `fl::span<T, N>` or `T (&value)[N]`.
          - For domain values like xy pairs, a concrete value type such as
            `fl::vec2f` is also acceptable.

        Examples:
          - Bad: `void cct_to_xy(int cct, float out[2]);`
          - Bad: `void encode(fl::u8 output[4]);`
          - Good: `void cct_to_xy(int cct, fl::span<float, 2> out);`
          - Good for ISR: `FL_IRAM void encode(fl::u8 (&output)[4]);`

        Suppress only intentional C ABI or platform compatibility cases with
        `// ok array parameter`. Reference: `agents/docs/cpp-standards.md` ->
        "`fl::span` for Callback Typedefs and Small Fixed-Size Arrays" and
        FastLED issue #3233.

    - path: "**/platformio.ini"
      instructions: |
        PlatformIO `build_flags` macro prefix rule (matches the `FL_*` vs `FASTLED_*`
        rule applied to C/C++ sources):

        Any NEWLY ADDED `-D<NAME>...` build flag whose identifier starts with `FASTLED_`
        is a HIGH-severity violation. Use the `FL_*` prefix instead. The `FASTLED_*`
        vocabulary is frozen — it exists only for backwards compatibility with
        already-shipped macros.

        Example violation (from PR diff):
          build_flags =
            -DRELEASE
            -DFASTLED_LPC_PWM_DMA=1         ; ❌ flag — should be -DFL_LPC_PWM_DMA=1
            -DFASTLED_LPC_RX_SCT_WS2812=1   ; ❌ flag — should be -DFL_LPC_RX_SCT_WS2812=1

        Existing `-DFASTLED_*` flags that the PR merely moves or reformats (without
        introducing a brand-new identifier) are grandfathered. Flag only new identifiers.
        Reference: `agents/docs/cpp-standards.md` → "Type 3: Component Capability Flags".

    - path: "**/meson.build"
      instructions: |
        Meson build macro prefix rule (matches the `FL_*` vs `FASTLED_*` rule applied
        to C/C++ sources and PlatformIO):

        Any NEWLY ADDED `-D<NAME>...` entry — typically inside
        `add_project_arguments`, `cpp_args`, `c_args`, `args:`, or
        `compile_args` — whose identifier starts with `FASTLED_` is a
        HIGH-severity violation. Use the `FL_*` prefix instead. The `FASTLED_*`
        vocabulary is frozen — it exists only for backwards compatibility with
        already-shipped macros.

        Example violations:
          add_project_arguments('-DFASTLED_LPC_PWM_DMA=1', language: 'cpp')  ; ❌
          cpp_args = ['-DFASTLED_NEW_FEATURE=1']                              ; ❌
        Rewrites:
          add_project_arguments('-DFL_LPC_PWM_DMA=1', language: 'cpp')       ; ✅
          cpp_args = ['-DFL_NEW_FEATURE=1']                                   ; ✅

        Existing `-DFASTLED_*` entries that the PR merely moves or reformats (without
        introducing a brand-new identifier) are grandfathered. Flag only new identifiers.
        Reference: `agents/docs/cpp-standards.md` → "Type 3: Component Capability Flags".

    - path: "**/CMakeLists.txt"
      instructions: |
        CMake macro prefix rule (matches the `FL_*` vs `FASTLED_*` rule applied to
        C/C++ sources and PlatformIO):

        Any NEWLY ADDED compile definition or flag — `add_compile_definitions(...)`,
        `target_compile_definitions(...)`, `add_definitions(-D...)`, or a raw
        `-D<NAME>=...` token inside `set(... CMAKE_CXX_FLAGS ...)` / `string(APPEND
        CMAKE_CXX_FLAGS ...)` — whose identifier starts with `FASTLED_` is a
        HIGH-severity violation. Use the `FL_*` prefix instead. The `FASTLED_*`
        vocabulary is frozen.

        Example violations:
          add_compile_definitions(FASTLED_LPC_PWM_DMA=1)                            ; ❌
          target_compile_definitions(fastled PRIVATE FASTLED_LPC_RX_SCT_WS2812=1)   ; ❌
          add_definitions(-DFASTLED_NEW_FEATURE=1)                                  ; ❌
        Rewrites:
          add_compile_definitions(FL_LPC_PWM_DMA=1)                                 ; ✅
          target_compile_definitions(fastled PRIVATE FL_LPC_RX_SCT_WS2812=1)        ; ✅
          add_definitions(-DFL_NEW_FEATURE=1)                                       ; ✅

        Existing `FASTLED_*` entries that the PR merely moves or reformats (without
        introducing a brand-new identifier) are grandfathered. Flag only new identifiers.
        Reference: `agents/docs/cpp-standards.md` → "Type 3: Component Capability Flags".

    - path: ".github/workflows/**/*.{yml,yaml}"
      instructions: |
        GitHub Actions macro prefix rule (matches the `FL_*` vs `FASTLED_*` rule
        applied to C/C++ sources and other build systems):

        Any NEWLY ADDED `-D<NAME>=...` token in a workflow step — typically inside
        `env: { CXXFLAGS: ... }`, `env: { CFLAGS: ... }`, a `run:` script that
        forwards build flags, or an `args:` list passed to a build wrapper — whose
        identifier starts with `FASTLED_` is a HIGH-severity violation. Use the
        `FL_*` prefix instead.

        Example violations:
          env:
            CXXFLAGS: "-DFASTLED_LPC_PWM_DMA=1"            ; ❌
          run: bash compile lpc --extra-flags=-DFASTLED_NEW_FEATURE=1   ; ❌
        Rewrites:
          env:
            CXXFLAGS: "-DFL_LPC_PWM_DMA=1"                 ; ✅
          run: bash compile lpc --extra-flags=-DFL_NEW_FEATURE=1        ; ✅

        Existing `-DFASTLED_*` tokens that the PR merely moves or reformats (without
        introducing a brand-new identifier) are grandfathered. Flag only new identifiers.
        Reference: `agents/docs/cpp-standards.md` → "Type 3: Component Capability Flags".

    - path: "src/**/*.h"
      instructions: |
        Header file. Verify it does NOT contain function definitions, function-local
        statics with non-trivial constructors (Teensy 3.x `__cxa_guard` conflict), or
        the `.cpp.hpp` / `.impl.hpp` content patterns. If function definitions are
        needed, they belong in `.cpp.hpp` or `.impl.hpp` files.
    - path: "src/fl/**/*.h"
      instructions: |
        FastLED Public Settings Pattern (see agents/docs/cpp-standards.md):

        Any NEW public free function in the fl:: namespace whose name matches
        `^set_|^enable_|^disable_|^use_` AND that mutates library-wide /
        global / namespace-scope state MUST also be exposed as a method on
        the `CFastLED` god instance in `src/FastLED.h`.

        The CFastLED method is a thin `inline` one-liner that delegates to
        the fl:: free function — that is the canonical pattern. Exemplar:
        `CFastLED::setPowerModel` (FastLED.h:1455) → `fl::set_power_model`.

        Flag as HIGH severity when a PR adds a `fl::set_*` / `fl::enable_*` /
        `fl::disable_*` / `fl::use_*` public declaration WITHOUT a matching
        `CFastLED::setX()` wrapper in `src/FastLED.h`. The fix is to add the
        wrapper in the same PR; the user-facing documented call site should
        be `FastLED.setX(...)`, never `fl::set_x(...)`.

        No grandfathered exceptions: every public global setter under
        `fl::` must have a `CFastLED` wrapper. Functions added without one
        — including bare `fl::set_input_gamut` (#2710) and any future
        additions — must be wrapped in the same PR.

        Does NOT apply to: helpers, constructors, factories, functions that
        only mutate caller-owned objects (e.g. fl::fill_solid(span, color)),
        per-object/per-strip configuration on the object's own API, or
        anything under fl::detail:: / anonymous namespaces.

    - path: "src/FastLED.h"
      instructions: |
        FastLED Public Settings Pattern (see agents/docs/cpp-standards.md):

        New `CFastLED` methods that configure library-wide state SHOULD be
        thin `inline` delegators to a free function in `fl::` namespace
        (testability + ADL), not embed configuration logic inline.

        Exemplar pattern (FastLED.h:1455):
          inline void setPowerModel(const PowerModelRGB& m) {
              set_power_model(m);
          }

        Flag CFastLED setters that embed non-trivial logic instead of
        delegating to a fl:: free function.

    - path: "src/fl/gfx/**"
      instructions: |
        Color / colorimetric profile setters that affect default behavior
        for all strips (e.g. set_rgbw_colorimetric_profile, set_input_gamut)
        MUST be wrapped on CFastLED per the Public Settings Pattern. If
        adding such a function, also add the `FastLED.setX(...)` wrapper in
        `src/FastLED.h` and document the god-instance form in the PR
        description / examples.

    - path: "src/fl/log/**"
      instructions: |
        FL_WARN / FL_ERROR default-visibility invariant (#2886 Stage 1):

        FL_WARN and FL_ERROR MUST remain active by default on NON-release
        builds. Flag changes that:

        1. Add an outer guard around FL_WARN(...) / FL_ERROR(...) that
           requires an opt-in macro to fire on debug/non-release builds.
        2. Change the unset default of FASTLED_LOG_VERBOSITY so that
           non-release builds (no NDEBUG) default below 1. Release builds
           (NDEBUG defined) default to 0 — that is intentional and not
           a violation.
        3. Add a new logging knob whose default suppresses FL_WARN /
           FL_ERROR on non-release builds without explicit user opt-in.

        Rationale: developers depend on warnings / errors firing during
        development. The bloat-reduction work in #2886 is scoped to
        release builds via NDEBUG; it explicitly preserves the
        debug-build default at verbosity 1.

        Resolution order (the contract): FASTLED_TESTING => 1, NDEBUG
        => 0, otherwise => 1. See src/fl/log/log.h.

        Flag any PR that wraps an existing or new FL_WARN(...) /
        FL_ERROR(...) site in an additional `#if !defined(...)` or
        `#ifdef FASTLED_LOG_*` block that would suppress the call on
        non-release builds by default — that breaks the
        developer-visibility contract above.