# FastLED Include What You Use Mapping File
# This file tells IWYU about FastLED's specific include patterns and structure

[
  # FastLED main headers - these are the public API
  { include: ['"fastled.h"', 'public', '"FastLED.h"', 'public'] },
  
  # Core FastLED headers that should be included directly
  { include: ['"lib8tion.h"', 'public', '"lib8tion.h"', 'public'] },
  { include: ['"pixeltypes.h"', 'public', '"pixeltypes.h"', 'public'] },
  { include: ['"hsv2rgb.h"', 'public', '"hsv2rgb.h"', 'public'] },
  { include: ['"crgb.h"', 'public', '"hsv2rgb.h"', 'public'] },
  { include: ['"colorutils.h"', 'public', '"colorutils.h"', 'public'] },
  { include: ['"colorpalettes.h"', 'public', '"colorpalettes.h"', 'public'] },
  
  # Platform dispatch headers - keep these as-is (don't suggest platform-specific includes)
  { include: ['"platforms/init.h"', 'public', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/stub/init_stub.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"init_stub.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/esp/32/init_esp32.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/esp/8266/init_esp8266.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/teensy/init_teensy4.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/rp/init_rp.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/stm32/init_stm32.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/d21/init_samd21.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/d51/init_samd51.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/nrf52/init_nrf52.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/wasm/init_wasm.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/win/init_win.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/mgm240/init_mgm240.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/silabs/init_silabs.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/renesas/init_renesas.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/arm/sam/init_sam.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/apollo3/init_apollo3.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/avr/init_avr.h"', 'private', '"platforms/init.h"', 'public'] },
  { include: ['"platforms/posix/init_posix.h"', 'private', '"platforms/init.h"', 'public'] },

  # Mutex platform abstraction - all platform-specific mutex headers redirect to public API
  { include: ['"platforms/mutex.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"platforms/stub/mutex_stub.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"platforms/stub/mutex_stub_stl.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"platforms/stub/mutex_stub_noop.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"mutex_stub_stl.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"mutex_stub_noop.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"platforms/esp/32/mutex_esp32.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"platforms/arm/rp/mutex_rp.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"platforms/arm/stm32/mutex_stm32.h"', 'private', '"fl/stl/mutex.h"', 'public'] },
  { include: ['"platforms/arm/d21/mutex_samd.h"', 'private', '"fl/stl/mutex.h"', 'public'] },

  # Platform-specific headers should not be suggested directly
  # Use @"regex" syntax (IWYU does not support shell globs - * is literal)
  # Note: platforms/.*/fastled_.*\.h is now marked with pragma in source files

  # Internal headers should redirect to public API
  { include: ['"platforms/null_progmem.h"', 'private', '"fastled_progmem.h"', 'public'] },
  # Note: power_mgt.h is now marked with pragma in source files
  
  # fl/ namespace headers - the modern FastLED API
  { include: ['"fl/vector.h"', 'public', '"fl/vector.h"', 'public'] },
  { include: ['"fl/allocator.h"', 'public', '"fl/allocator.h"', 'public'] },
  { include: ['"fl/math.h"', 'public', '"fl/math.h"', 'public'] },
  { include: ['"fl/stl/compiler_control.h"', 'public', '"fl/stl/compiler_control.h"', 'public'] },
  
  # FX headers - effects system
  { include: ['"fl/fx/fx.h"', 'public', '"fl/fx/fx.h"', 'public'] },
  { include: ['"fx/fx.h"', 'public', '"fl/fx/fx.h"', 'public'] },
  { include: ['"fl/fx/fx1d.h"', 'public', '"fl/fx/fx1d.h"', 'public'] },
  { include: ['"fx/fx1d.h"', 'public', '"fl/fx/fx1d.h"', 'public'] },
  { include: ['"fl/fx/fx2d.h"', 'public', '"fl/fx/fx2d.h"', 'public'] },
  { include: ['"fx/fx2d.h"', 'public', '"fl/fx/fx2d.h"', 'public'] },
  { include: ['"fl/fx/fx_engine.h"', 'public', '"fl/fx/fx_engine.h"', 'public'] },
  { include: ['"fx/fx_engine.h"', 'public', '"fl/fx/fx_engine.h"', 'public'] },
  { include: ['"fl/fx/frame.h"', 'public', '"fl/fx/frame.h"', 'public'] },
  { include: ['"fx/frame.h"', 'public', '"fl/fx/frame.h"', 'public'] },
  { include: ['@"fx/detail/.*"', 'private', '"fl/fx/fx.h"', 'public'] },

  # Animartrix detail headers are private implementation details
  { include: ['"fl/fx/2d/animartrix_detail.h"', 'private', '"fl/fx/2d/animartrix.hpp"', 'public'] },

  # ========================================================================
  # Umbrella Header Sub-components
  # ========================================================================
  # Sub-headers that are re-exported by umbrella headers.
  # Mark as private so IWYU suggests the umbrella instead.

  # fl/math/simd.h umbrella
  { include: ['"fl/math/simd/u8x16.h"', 'private', '"fl/math/simd.h"', 'public'] },
  { include: ['"fl/math/simd/u8x32.h"', 'private', '"fl/math/simd.h"', 'public'] },
  { include: ['"fl/math/simd/u16x8.h"', 'private', '"fl/math/simd.h"', 'public'] },
  { include: ['"fl/math/simd/u16x16.h"', 'private', '"fl/math/simd.h"', 'public'] },
  { include: ['"fl/math/simd/u32x4.h"', 'private', '"fl/math/simd.h"', 'public'] },
  { include: ['"fl/math/simd/f32x4.h"', 'private', '"fl/math/simd.h"', 'public'] },
  { include: ['"fl/math/simd/types.h"', 'private', '"fl/math/simd.h"', 'public'] },

  # fl/stl/isr.h umbrella
  { include: ['"fl/stl/isr/constants.h"', 'private', '"fl/stl/isr.h"', 'public'] },
  { include: ['"fl/stl/isr/memcpy.h"', 'private', '"fl/stl/isr.h"', 'public'] },
  { include: ['"fl/stl/isr/handler.h"', 'private', '"fl/stl/isr.h"', 'public'] },
  { include: ['"fl/stl/isr/critical_section.h"', 'private', '"fl/stl/isr.h"', 'public'] },

  # fl/net/net.h umbrella
  { include: ['"fl/net/http.h"', 'private', '"fl/net/net.h"', 'public'] },
  { include: ['"fl/net/ble.h"', 'private', '"fl/net/net.h"', 'public'] },
  { include: ['"fl/net/ota.h"', 'private', '"fl/net/net.h"', 'public'] },
  { include: ['"fl/net/rpc.h"', 'private', '"fl/net/net.h"', 'public'] },

  # fl/net/http.h umbrella
  { include: ['"fl/net/http/fetch.h"', 'private', '"fl/net/http.h"', 'public'] },
  { include: ['"fl/net/http/stream_client.h"', 'private', '"fl/net/http.h"', 'public'] },
  { include: ['"fl/net/http/stream_server.h"', 'private', '"fl/net/http.h"', 'public'] },

  # fl/channels/spi.h umbrella
  { include: ['"fl/channels/spi/config.h"', 'private', '"fl/channels/spi.h"', 'public'] },
  { include: ['"fl/channels/spi/transaction.h"', 'private', '"fl/channels/spi.h"', 'public'] },
  { include: ['"fl/channels/spi/device.h"', 'private', '"fl/channels/spi.h"', 'public'] },
  { include: ['"fl/channels/spi/lane.h"', 'private', '"fl/channels/spi.h"', 'public'] },
  { include: ['"fl/channels/spi/write_result.h"', 'private', '"fl/channels/spi.h"', 'public'] },
  { include: ['"fl/channels/spi/multi_lane_device.h"', 'private', '"fl/channels/spi.h"', 'public'] },

  # fl/fx/2d/animartrix_detail/ sub-headers → animartrix_detail.h
  { include: ['@"fl/fx/2d/animartrix_detail/.*"', 'private', '"fl/fx/2d/animartrix_detail.h"', 'public'] },

  # fl/math/noise.h umbrella
  { include: ['"fl/math/noise/noise_woryley.h"', 'private', '"fl/math/noise.h"', 'public'] },
  { include: ['"fl/math/noise/perlin_s16x16_simd.h"', 'private', '"fl/math/noise.h"', 'public'] },

  # Platform dispatch re-exports (math8.h, scale8.h, simd.h)
  { include: ['"platforms/math8.h"', 'private', '"fl/math/math8.h"', 'public'] },
  { include: ['"platforms/scale8.h"', 'private', '"fl/math/scale8.h"', 'public'] },

  # Third-party headers should not be suggested for user code
  # Note: third_party/.* is now marked with pragma in source files

  # Chipset-specific headers redirect to main header
  
  # Testing headers - keep as-is for test files
  { include: ['@"test_.*\\.h"', 'public', '"test.h"', 'public'] },
  # doctest.h is private - IWYU should never recommend it
  { include: ['"doctest.h"', 'private', '"test.h"', 'public'] },

  # FastLED uses custom stdint.h replacement to avoid 500ms compile-time penalty
  # Map standard headers to FastLED equivalents
  { include: ['<stdint.h>', 'public', '"fl/stl/stdint.h"', 'public'] },
  { include: ['<stddef.h>', 'public', '"fl/stl/cstddef.h"', 'public'] },
  { include: ['<cstdint>', 'public', '"fl/stl/stdint.h"', 'public'] },
  { include: ['<cstddef>', 'public', '"fl/stl/cstddef.h"', 'public'] },

  # Map system placement new header to FastLED wrapper
  # This redirects libc++'s __new/placement_new_delete.h to our platform abstraction
  { include: ['"__new/placement_new_delete.h"', 'private', '"fl/stl/new.h"', 'public'] },
  { include: ['<new>', 'public', '"fl/stl/new.h"', 'public'] },

  # ========================================================================
  # SIMD Platform Dispatch (Internal Implementation)
  # ========================================================================
  # Platform-specific SIMD headers are internal implementation details.
  # All code should use the public API: fl/simd.h
  { include: ['"platforms/shared/simd_x86.hpp"', 'private', '"fl/simd.h"', 'public'] },
  { include: ['"platforms/shared/simd_noop.hpp"', 'private', '"fl/simd.h"', 'public'] },
  { include: ['"platforms/simd.h"', 'private', '"fl/simd.h"', 'public'] },

  # ========================================================================
  # Platform Integer Type Headers (Internal Implementation)
  # ========================================================================
  # Platform-specific integer type headers are internal implementation details.
  # All code should use the public API: fl/stl/int.h or fl/stl/stdint.h
  #
  { include: ['"platforms/shared/int_windows.h"', 'private', '"fl/stl/int.h"', 'public'] },
  { include: ['"platforms/shared/int.h"', 'private', '"fl/stl/int.h"', 'public'] },
  { include: ['"platforms/int.h"', 'private', '"fl/stl/int.h"', 'public'] },
  { include: ['@"platforms/.*/int.*\\.h"', 'private', '"fl/stl/int.h"', 'public'] },
  # fl/stl/stdint.h re-exports fl/stl/int.h (via IWYU pragma: export in source).
  # This means files including fl/stl/stdint.h don't need fl/stl/int.h separately.

  # ========================================================================
  # Platform-Specific Headers (Not Available on Host Platform)
  # ========================================================================
  # These headers are only available when compiling for specific platforms
  # (Arduino, ESP32, AVR, ARM, etc.). When IWYU runs on the host (stub)
  # platform, these headers don't exist. We mark them as 'private' so IWYU
  # doesn't suggest them, but allows them when behind #ifdef guards.

  # Arduino Core Headers
  # Arduino.h is now accessed through fl/system/arduino.h trampoline (includes Arduino.h + cleans up macros)
  # IWYU will suggest fl/system/arduino.h instead of <Arduino.h>
  { include: ['<Arduino.h>', 'private', '"fl/system/arduino.h"', 'public'] },

  # AVR Platform Headers
  # These don't exist on stub - map to FastLED's progmem abstraction
  { include: ['<avr/pgmspace.h>', 'private', '"fastled_progmem.h"', 'public'] },
  # Note: <avr/io.h> is now marked with pragma in source files

  # ESP32 Arduino HAL Headers
  { include: ['<esp32-hal-gpio.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },

  # ESP-IDF Framework Headers (driver/*)
  { include: ['<driver/gpio.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<driver/spi_master.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<driver/i2s.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<driver/rmt.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<driver/periph_ctrl.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },

  # ESP-IDF Framework Headers (esp_*)
  { include: ['<esp_heap_caps.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_intr_alloc.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_system.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_log.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_cpu.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_lcd_panel_io.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_lcd_panel_ops.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_private/periph_ctrl.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<esp_intr.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },

  # FreeRTOS Headers (used by ESP32 and some ARM platforms)
  { include: ['<freertos/FreeRTOS.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<freertos/task.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<freertos/semphr.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },
  { include: ['<freertos/queue.h>', 'private', '"platforms/esp/32/core/led_sysdefs_esp32.h"', 'public'] },

  # ARM/Teensy Platform Headers
  # Note: <kinetis.h> is now marked with pragma in source files

  # Raspberry Pi Pico SDK Headers

  # ========================================================================
  # SSE Include Chain
  # ========================================================================
  # emmintrin.h (SSE2) transitively includes xmmintrin.h (SSE1).
  # IWYU doesn't track this transitive include, so it falsely suggests
  # adding xmmintrin.h when emmintrin.h is already included.
  { include: ['"xmmintrin.h"', 'public', '<emmintrin.h>', 'public'] },

  # ========================================================================
  # MinGW Internal Headers (compiler-defined macros)
  # ========================================================================
  # _mingw_mac.h: IWYU traces _M_X64 here, but it's a compiler builtin.
  # Cannot map to a public header (would create false suggestion).
  # Fix: use "// IWYU pragma: no_include" in source files instead.

  # ========================================================================
  # CATCH-ALL: *.cpp.hpp files are private (unity build implementation files)
  # ========================================================================
  # These are implementation files, not headers. IWYU should never recommend them.
  # Only _build.cpp.hpp files include them (enforced by a separate linter).
  # Note: .*\.cpp\.hpp is now marked with pragma in source files

  # ========================================================================
  # Platform infrastructure headers (public within platform code)
  # ========================================================================
  # These headers are used directly by platform driver files and should remain
  # accessible without redirection to fl/stl/private.h. Mark as private but
  # don't redirect to avoid visibility conflicts with the catch-all rule below.
  { include: ['"platforms/memory_barrier.h"', 'private', '"platforms/memory_barrier.h"', 'private'] },

  # ========================================================================
  # libc++ Internal Headers (transitive includes IWYU shouldn't flag)
  # ========================================================================
  # These are pulled in transitively by <initializer_list> and other libc++
  # headers. They don't correspond to actual #include lines in our code.
  { include: ['<__cstddef/size_t.h>', 'private', '"fl/stl/initializer_list.h"', 'public'] },
  { include: ['<__config>', 'private', '"fl/stl/initializer_list.h"', 'public'] },
  { include: ['<version>', 'private', '"fl/stl/initializer_list.h"', 'public'] },

  # ========================================================================
  # Platform Dispatch Headers (resolved paths IWYU shouldn't flag)
  # ========================================================================
  # IWYU resolves platform #ifdef chains and reports the final resolved path.
  # These don't exist as literal #include lines in our source.
  { include: ['"platforms/arm/is_arm.h"', 'private', '"fl/stl/int.h"', 'public'] },
  { include: ['"platforms/delay.h"', 'private', '"fl/system/delay.h"', 'public'] },
  { include: ['"platforms/trig8.h"', 'private', '"fl/trig8.h"', 'public'] },
  { include: ['"platforms/fastpin.h"', 'private', '"fl/fastpin.h"', 'public'] },
  { include: ['"platforms/is_platform.h"', 'private', '"fl/stl/int.h"', 'public'] },
  { include: ['"platforms/stub/semaphore_stub.h"', 'private', '"fl/stl/semaphore.h"', 'public'] },
  { include: ['"native_client.h"', 'private', '"fl/net/http/stream_client.h"', 'public'] },
  { include: ['"native_server.h"', 'private', '"fl/net/http/stream_server.h"', 'public'] },

  # ========================================================================
  # CATCH-ALL: All other platform headers are private and redirect
  # ========================================================================
  # This must be LAST so specific rules above take priority.
  # Matches any header under platforms/ at any depth (except those listed above)
  # and redirects to fl/stl/private.h.
  # Note: Headers marked above will be processed first and won't be redirected.
  # Note: platforms/.* is now marked with pragma in source files
]
