hid-rgb-ctl 0.2.6

//! HID report descriptor parser and device discovery.
//!
//! Parses binary HID report descriptors to find devices implementing:
//! - Usage Page 0x59 (Lighting and Illumination) -- HID LampArray protocol
//! - Usage Page 0x08 (LED Page) with Usage 0x52 (RGB LED) -- Legacy RGB LED
//!
//! Reference: USB HID Usage Tables v1.4
//!   - Section 26: Lighting and Illumination Page (0x59)
//!   - Section 11.7: Multicolor (RGB) LED on LED Page (0x08)

use std::fs;
use std::path::Path;

// --- Usage Page constants ---

const USAGE_PAGE_LED: u32 = 0x08;
const USAGE_PAGE_LIGHTING: u32 = 0x59;

// Usage IDs for Lighting and Illumination Page (0x59), Section 26
const USAGE_LAMP_ARRAY: u32 = 0x01; // LampArray application collection
const USAGE_LAMP_ARRAY_ATTRIBUTES_REPORT: u32 = 0x02;
const USAGE_LAMP_ATTR_REQUEST_REPORT: u32 = 0x20;
const USAGE_LAMP_ATTR_RESPONSE_REPORT: u32 = 0x22;
const USAGE_LAMP_MULTI_UPDATE_REPORT: u32 = 0x50;
const USAGE_LAMP_RANGE_UPDATE_REPORT: u32 = 0x60;
const USAGE_LAMP_ARRAY_CONTROL_REPORT: u32 = 0x70;

// Usage IDs for LED Page (0x08), Section 11.7
const USAGE_RGB_LED: u32 = 0x52;
const USAGE_RED_LED_CHANNEL: u32 = 0x53;
const USAGE_BLUE_LED_CHANNEL: u32 = 0x54; // Note: Blue before Green in spec
const USAGE_GREEN_LED_CHANNEL: u32 = 0x55;
const USAGE_LED_INTENSITY: u32 = 0x56;

// HID item tags (prefix byte with size bits masked out)
// Global items
const TAG_USAGE_PAGE: u8 = 0x04;
const TAG_LOGICAL_MIN: u8 = 0x14;
const TAG_LOGICAL_MAX: u8 = 0x24;
const TAG_REPORT_SIZE: u8 = 0x74;
const TAG_REPORT_ID: u8 = 0x84;
const TAG_REPORT_COUNT: u8 = 0x94;

// Local items
const TAG_USAGE: u8 = 0x08;
const TAG_USAGE_MIN: u8 = 0x18;
const TAG_USAGE_MAX: u8 = 0x28;

// Main items
const TAG_INPUT: u8 = 0x80;
const TAG_OUTPUT: u8 = 0x90;
const TAG_FEATURE: u8 = 0xB0;
const TAG_COLLECTION: u8 = 0xA0;
const TAG_END_COLLECTION: u8 = 0xC0;

// Collection types
const COLLECTION_APPLICATION: u32 = 0x01;
const COLLECTION_LOGICAL: u32 = 0x02;

// --- HID report type ---

/// The type of a HID report (Feature, Output, or Input).
///
/// Determines how the report is communicated on Linux HIDRAW:
/// - Feature: via ioctl (HIDIOCSFEATURE / HIDIOCGFEATURE)
/// - Output: via write() syscall
/// - Input: via read() syscall
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReportType {
    Feature,
    Output,
    Input,
}

/// Identifies which LampArray sub-report collection we are inside.
#[derive(Debug, Clone, Copy)]
enum LampArrayReportKind {
    Attributes,
    AttrRequest,
    AttrResponse,
    MultiUpdate,
    RangeUpdate,
    Control,
}

impl LampArrayReportKind {
    /// Map from LampArray collection usage to report kind.
    fn from_usage(usage: u32) -> Option<Self> {
        match usage {
            USAGE_LAMP_ARRAY_ATTRIBUTES_REPORT => Some(Self::Attributes),
            USAGE_LAMP_ATTR_REQUEST_REPORT => Some(Self::AttrRequest),
            USAGE_LAMP_ATTR_RESPONSE_REPORT => Some(Self::AttrResponse),
            USAGE_LAMP_MULTI_UPDATE_REPORT => Some(Self::MultiUpdate),
            USAGE_LAMP_RANGE_UPDATE_REPORT => Some(Self::RangeUpdate),
            USAGE_LAMP_ARRAY_CONTROL_REPORT => Some(Self::Control),
            _ => None,
        }
    }
}

/// Check if a tag is a main data tag (Input, Output, or Feature).
fn is_main_data_tag(tag: u8) -> bool {
    matches!(tag, TAG_INPUT | TAG_OUTPUT | TAG_FEATURE)
}

// --- Public types ---

/// Parsed HID report metadata.
#[derive(Debug, Clone)]
pub struct ReportInfo {
    pub report_id: u8,
    /// Total data bytes (excluding report ID byte).
    pub size: usize,
}

/// Parsed HID report metadata for all LampArray report types.
///
/// Each field corresponds to a specific LampArray report collection.
/// `None` means the report was not found in the device's descriptor.
#[derive(Debug, Clone, Default)]
pub struct LampArrayReports {
    pub attributes: Option<ReportInfo>,
    pub attr_request: Option<ReportInfo>,
    pub attr_response: Option<ReportInfo>,
    pub multi_update: Option<ReportInfo>,
    pub range_update: Option<ReportInfo>,
    pub control: Option<ReportInfo>,
}

/// LED Page RGB channel layout (Usage Page 0x08, Section 11.7).
///
/// The RGB LED collection (Usage 0x52) contains:
///   - Red LED Channel (Usage 0x53)
///   - Blue LED Channel (Usage 0x54)  -- Note: Blue before Green per spec
///   - Green LED Channel (Usage 0x55)
///   - LED Intensity (Usage 0x56, optional)
///
/// Byte offsets are parsed from the descriptor to handle any report layout.
#[derive(Debug, Clone)]
pub struct LedRgbChannelInfo {
    pub report_id: u8,
    /// Total data bytes (excluding report ID).
    pub report_size: usize,
    /// Byte offset of Red channel within report data.
    pub red_offset: usize,
    /// Byte offset of Blue channel.
    pub blue_offset: usize,
    /// Byte offset of Green channel.
    pub green_offset: usize,
    /// Byte offset of Intensity (None if absent).
    pub intensity_offset: Option<usize>,
    /// Bits per channel (typically 8).
    pub channel_size: u32,
    /// The HID report type (Feature or Output).
    pub report_type: ReportType,
    /// LogicalMaximum per color channel from the descriptor (typically 255).
    pub red_logical_max: u32,
    pub green_logical_max: u32,
    pub blue_logical_max: u32,
    /// LogicalMaximum of the Intensity channel (spec recommends 100).
    /// None if the device has no intensity channel.
    pub intensity_logical_max: Option<u32>,
}

/// Type-specific device data.
#[derive(Debug, Clone)]
pub enum DeviceKind {
    /// HID LampArray (Usage Page 0x59).
    LampArray(LampArrayReports),
    /// LED Page RGB LED (Usage Page 0x08, Section 11.7).
    LedRgb(LedRgbChannelInfo),
}

/// Discovered HID RGB device.
///
/// Common fields (path, name) are stored directly; type-specific data
/// lives in the [`DeviceKind`] enum.
#[derive(Debug, Clone)]
pub struct DeviceInfo {
    pub hidraw_path: String,
    pub name: String,
    pub kind: DeviceKind,
}

// --- HID Report Descriptor Parser ---

/// Accumulates LED RGB channel offsets during descriptor parsing.
#[derive(Debug)]
struct LedRgbChannelBuilder {
    report_id: u8,
    report_size: usize,
    red_offset: Option<usize>,
    blue_offset: Option<usize>,
    green_offset: Option<usize>,
    intensity_offset: Option<usize>,
    channel_size: u32,
    /// The HID report type (Feature, Output, or Input) for this RGB LED.
    report_type: ReportType,
    /// LogicalMaximum per color channel (typically 255 for all).
    red_logical_max: u32,
    green_logical_max: u32,
    blue_logical_max: u32,
    /// LogicalMaximum of the Intensity channel (spec recommends 100).
    intensity_logical_max: Option<u32>,
}

impl Default for LedRgbChannelBuilder {
    fn default() -> Self {
        Self {
            report_id: 0,
            report_size: 0,
            red_offset: None,
            blue_offset: None,
            green_offset: None,
            intensity_offset: None,
            channel_size: 8, // Typical default per HID spec
            report_type: ReportType::Feature,
            red_logical_max: 255,
            green_logical_max: 255,
            blue_logical_max: 255,
            intensity_logical_max: None,
        }
    }
}

impl LedRgbChannelBuilder {
    fn with_report_id(report_id: u8) -> Self {
        Self {
            report_id,
            ..Self::default()
        }
    }

    /// True when all mandatory channels (R, G, B) have been found.
    fn is_complete(&self) -> bool {
        self.red_offset.is_some() && self.blue_offset.is_some() && self.green_offset.is_some()
    }
}

/// Usage entry stored during parsing -- either a plain usage ID
/// or a pending min value awaiting a USAGE_MAX to expand the range.
#[derive(Debug, Clone, Copy)]
enum UsageEntry {
    Single(u32),
    Min(u32),
}

/// Mutable state for the HID descriptor parser.
struct ParserState {
    // Global items (persist across Main items)
    usage_page: u32,
    report_id: u8,
    report_size: u32,
    report_count: u32,
    logical_min: i32,
    logical_max: i32,
    /// Raw unsigned interpretation of LogicalMaximum payload.
    /// Used when `logical_min >= 0 && logical_max < 0` to resolve the HID 1.11
    /// §6.2.2.7 sign-extension ambiguity (e.g. 1-byte 0xFF = 255, not -1).
    logical_max_unsigned: u32,

    // Local items (reset after each Main item)
    usages: Vec<UsageEntry>,

    // Accumulated results
    lamp_array_reports: LampArrayReports,
    led_rgb_channels: Vec<LedRgbChannelBuilder>,

    // Per-report accumulated data bits for final size calculation
    report_data_bits: Vec<(u8, u32)>,

    // Collection / context tracking
    collection_depth: u32,

    // Depth at which each context flag was set (for precise end-collection reset).
    // `is_some()` replaces the former `in_*` boolean flags (single source of truth).
    lamp_array_app_depth: Option<u32>,
    /// (depth, kind) — replaces the former separate depth + kind fields.
    lighting_report: Option<(u32, LampArrayReportKind)>,
    rgb_led_collection_depth: Option<u32>,
}

impl ParserState {
    fn new() -> Self {
        Self {
            usage_page: 0,
            report_id: 0,
            report_size: 0,
            report_count: 0,
            logical_min: 0,
            logical_max: 0,
            logical_max_unsigned: 0,
            usages: Vec::new(),
            lamp_array_reports: LampArrayReports::default(),
            led_rgb_channels: Vec::new(),
            report_data_bits: Vec::new(),
            collection_depth: 0,
            lamp_array_app_depth: None,
            lighting_report: None,
            rgb_led_collection_depth: None,
        }
    }

    // --- Global item handlers ---

    fn handle_global(&mut self, tag: u8, val: u32, payload: &[u8]) {
        match tag {
            TAG_USAGE_PAGE => self.usage_page = val,
            TAG_LOGICAL_MIN => self.logical_min = payload_value_signed(payload),
            TAG_LOGICAL_MAX => {
                self.logical_max = payload_value_signed(payload);
                self.logical_max_unsigned = val;
            }
            TAG_REPORT_ID => self.report_id = val as u8,
            TAG_REPORT_SIZE => self.report_size = val,
            TAG_REPORT_COUNT => self.report_count = val,
            _ => {}
        }
    }

    // --- Local item handlers ---

    fn handle_local(&mut self, tag: u8, val: u32) {
        match tag {
            TAG_USAGE => {
                self.usages.push(UsageEntry::Single(val));
            }
            TAG_USAGE_MIN => {
                self.usages.push(UsageEntry::Min(val));
            }
            TAG_USAGE_MAX => {
                // Expand usage range from the last USAGE_MIN
                if let Some(UsageEntry::Min(umin)) = self.usages.last().copied() {
                    self.usages.pop();
                    for u in umin..=val {
                        self.usages.push(UsageEntry::Single(u));
                    }
                }
            }
            _ => {}
        }
    }

    // --- Main item handlers ---

    fn handle_main(&mut self, tag: u8, val: u32) {
        match tag {
            TAG_COLLECTION => self.on_collection(val),
            TAG_END_COLLECTION => self.on_end_collection(),
            t if is_main_data_tag(t) => self.on_data_item(t),
            _ => {}
        }
    }

    /// Check if the current usage list contains a specific usage ID.
    fn has_usage(&self, target: u32) -> bool {
        self.usages
            .iter()
            .any(|e| matches!(e, UsageEntry::Single(u) if *u == target))
    }

    /// Find the first matching usage and transform it via `f`.
    fn find_usage_map<T>(&self, f: impl Fn(u32) -> Option<T>) -> Option<T> {
        self.usages.iter().find_map(|e| match e {
            UsageEntry::Single(u) => f(*u),
            _ => None,
        })
    }

    fn on_collection(&mut self, collection_type: u32) {
        self.collection_depth += 1;

        // LampArray Application collection (Usage Page 0x59, Usage 0x01)
        if self.usage_page == USAGE_PAGE_LIGHTING
            && collection_type == COLLECTION_APPLICATION
            && self.has_usage(USAGE_LAMP_ARRAY)
        {
            self.lamp_array_app_depth = Some(self.collection_depth);
        }

        // LampArray sub-report collections: only match inside a LampArray app collection
        if self.usage_page == USAGE_PAGE_LIGHTING && self.lamp_array_app_depth.is_some() {
            if let Some(kind) = self.find_usage_map(LampArrayReportKind::from_usage) {
                self.lighting_report = Some((self.collection_depth, kind));
            }
        }

        // RGB LED collection: per Section 11.7, RGB LED is a Logical collection (CL)
        if self.usage_page == USAGE_PAGE_LED
            && collection_type == COLLECTION_LOGICAL
            && self.has_usage(USAGE_RGB_LED)
        {
            self.rgb_led_collection_depth = Some(self.collection_depth);
            if !self
                .led_rgb_channels
                .iter()
                .any(|b| b.report_id == self.report_id)
            {
                self.led_rgb_channels
                    .push(LedRgbChannelBuilder::with_report_id(self.report_id));
            }
        }

        self.usages.clear();
    }

    fn on_end_collection(&mut self) {
        // Check BEFORE decrementing — we are leaving the collection at this depth.
        if self
            .lighting_report
            .is_some_and(|(d, _)| d == self.collection_depth)
        {
            self.lighting_report = None;
        }
        if self.rgb_led_collection_depth == Some(self.collection_depth) {
            self.rgb_led_collection_depth = None;
        }
        if self.lamp_array_app_depth == Some(self.collection_depth) {
            self.lamp_array_app_depth = None;
        }
        self.collection_depth = self.collection_depth.saturating_sub(1);
        self.usages.clear();
    }

    fn on_data_item(&mut self, tag: u8) {
        let total_bits = self.report_size * self.report_count;
        let rid = self.report_id;

        // Capture absolute bit offset before this item for channel positioning
        let bit_offset_before = self
            .report_data_bits
            .iter()
            .find(|(r, _)| *r == rid)
            .map(|(_, bits)| *bits)
            .unwrap_or(0);
        match self.report_data_bits.iter_mut().find(|(r, _)| *r == rid) {
            Some((_, bits)) => *bits += total_bits,
            None => self.report_data_bits.push((rid, total_bits)),
        }

        // Determine report type from the Main item tag
        let report_type = match tag {
            TAG_OUTPUT => ReportType::Output,
            TAG_INPUT => ReportType::Input,
            _ => ReportType::Feature,
        };

        // Lighting Page (0x59): record report info
        if self.usage_page == USAGE_PAGE_LIGHTING {
            if let Some((_, kind)) = self.lighting_report {
                let rinfo = ReportInfo {
                    report_id: rid,
                    size: 0,
                };
                let slot = match kind {
                    LampArrayReportKind::Attributes => &mut self.lamp_array_reports.attributes,
                    LampArrayReportKind::AttrRequest => &mut self.lamp_array_reports.attr_request,
                    LampArrayReportKind::AttrResponse => &mut self.lamp_array_reports.attr_response,
                    LampArrayReportKind::MultiUpdate => &mut self.lamp_array_reports.multi_update,
                    LampArrayReportKind::RangeUpdate => &mut self.lamp_array_reports.range_update,
                    LampArrayReportKind::Control => &mut self.lamp_array_reports.control,
                };
                if slot.is_none() {
                    *slot = Some(rinfo);
                }
            }
        }

        // LED Page (0x08): record channel byte offsets (absolute within report)
        if self.usage_page == USAGE_PAGE_LED && self.rgb_led_collection_depth.is_some() {
            let builder = match self
                .led_rgb_channels
                .iter_mut()
                .find(|b| b.report_id == rid)
            {
                Some(b) => b,
                None => {
                    self.led_rgb_channels
                        .push(LedRgbChannelBuilder::with_report_id(rid));
                    self.led_rgb_channels.last_mut().unwrap()
                }
            };
            builder.report_type = report_type;

            // HID 1.11 §6.2.2.7: LogicalMin/Max are signed, but when LogicalMin
            // is non-negative and LogicalMax appears negative after sign extension,
            // the intended range is unsigned (e.g. 1-byte 0xFF = 255, not -1).
            // Section 11.7: LED Page channels use LogicalMin=0.
            // MS reference (WaratahCmd) avoids this by using 2-byte payloads for
            // LogicalMax(255), but third-party devices may use 1-byte payloads.
            let lmax = if self.logical_min >= 0 && self.logical_max < 0 {
                self.logical_max_unsigned
            } else {
                self.logical_max.max(0) as u32
            };
            for (i, entry) in self.usages.iter().enumerate() {
                if let UsageEntry::Single(usage) = entry {
                    let byte_off = ((bit_offset_before + i as u32 * self.report_size) / 8) as usize;
                    match *usage {
                        USAGE_RED_LED_CHANNEL => {
                            builder.red_offset = Some(byte_off);
                            builder.channel_size = self.report_size;
                            builder.red_logical_max = lmax;
                        }
                        USAGE_BLUE_LED_CHANNEL => {
                            builder.blue_offset = Some(byte_off);
                            builder.blue_logical_max = lmax;
                        }
                        USAGE_GREEN_LED_CHANNEL => {
                            builder.green_offset = Some(byte_off);
                            builder.green_logical_max = lmax;
                        }
                        USAGE_LED_INTENSITY => {
                            builder.intensity_offset = Some(byte_off);
                            builder.intensity_logical_max = Some(lmax);
                        }
                        _ => {}
                    }
                }
            }
        }

        self.usages.clear();
    }

    // --- Finalize ---

    fn finalize(mut self) -> (LampArrayReports, Vec<LedRgbChannelBuilder>) {
        // Helper to look up accumulated bits for a report ID.
        let bits_for = |rid: u8| -> u32 {
            self.report_data_bits
                .iter()
                .find(|(r, _)| *r == rid)
                .map(|(_, bits)| *bits)
                .unwrap_or(0)
        };

        // Fill in byte sizes for LampArray reports
        for rinfo in [
            &mut self.lamp_array_reports.attributes,
            &mut self.lamp_array_reports.attr_request,
            &mut self.lamp_array_reports.attr_response,
            &mut self.lamp_array_reports.multi_update,
            &mut self.lamp_array_reports.range_update,
            &mut self.lamp_array_reports.control,
        ]
        .into_iter()
        .flatten()
        {
            rinfo.size = bits_for(rinfo.report_id).div_ceil(8) as usize;
        }

        // Collect complete LED RGB channel builders with computed sizes
        let complete = self
            .led_rgb_channels
            .into_iter()
            .filter_map(|mut builder| {
                if builder.is_complete() {
                    builder.report_size = bits_for(builder.report_id).div_ceil(8) as usize;
                    Some(builder)
                } else {
                    None
                }
            })
            .collect();

        (self.lamp_array_reports, complete)
    }
}

/// Parse one HID descriptor item.
///
/// Returns (tag, item_type, payload_slice, total_item_bytes).
/// `item_type`: 0=Main, 1=Global, 2=Local, 3=reserved/long (skip).
///
/// Handles both short items (HID 1.11 §6.2.2.2) and long items (§6.2.2.3).
fn parse_item(data: &[u8], offset: usize) -> Option<(u8, u8, &[u8], usize)> {
    if offset >= data.len() {
        return None;
    }

    let prefix = data[offset];

    // Long item: prefix == 0xFE (HID 1.11 §6.2.2.3)
    // Format: 0xFE, bDataSize, bLongItemTag, data[bDataSize]
    if prefix == 0xFE {
        if offset + 2 >= data.len() {
            return None;
        }
        let data_size = data[offset + 1] as usize;
        let total = 3 + data_size;
        if offset + total > data.len() {
            return None;
        }
        // Long items have no standard tags; skip with item_type=3 (reserved)
        return Some((0xFE, 3, &[], total));
    }

    let mut size = (prefix & 0x03) as usize;
    if size == 3 {
        size = 4; // Size code 3 means 4 bytes
    }
    let tag = prefix & 0xFC;
    let item_type = (prefix >> 2) & 0x03; // 0=Main, 1=Global, 2=Local

    let end = offset + 1 + size;
    if end > data.len() {
        return None;
    }

    let payload = &data[offset + 1..end];
    Some((tag, item_type, payload, 1 + size))
}

/// Decode a HID item payload as a signed integer (sign-extended).
///
/// HID 1.11 §6.2.2.7 requires LogicalMinimum/LogicalMaximum to be
/// interpreted as signed values with sign extension based on payload size.
fn payload_value_signed(payload: &[u8]) -> i32 {
    match payload.len() {
        0 => 0,
        1 => payload[0] as i8 as i32,
        2 => i16::from_le_bytes([payload[0], payload[1]]) as i32,
        4 => i32::from_le_bytes([payload[0], payload[1], payload[2], payload[3]]),
        _ => {
            // Fallback: little-endian decode up to 4 bytes, then sign-extend
            let mut val = 0u32;
            let len = payload.len().min(4);
            for (i, &b) in payload.iter().enumerate().take(len) {
                val |= (b as u32) << (8 * i);
            }
            // Sign-extend from the actual byte width
            let shift = 32 - (len * 8) as u32;
            ((val << shift) as i32) >> shift
        }
    }
}

/// Decode a HID item payload as an unsigned integer.
fn payload_value(payload: &[u8]) -> u32 {
    match payload.len() {
        0 => 0,
        1 => payload[0] as u32,
        2 => u16::from_le_bytes([payload[0], payload[1]]) as u32,
        4 => u32::from_le_bytes([payload[0], payload[1], payload[2], payload[3]]),
        _ => {
            // Fallback: little-endian decode up to 4 bytes
            let mut val = 0u32;
            for (i, &b) in payload.iter().enumerate().take(4) {
                val |= (b as u32) << (8 * i);
            }
            val
        }
    }
}

/// Parse a binary HID report descriptor.
///
/// Returns:
///   - lamp_array_reports: map of report name -> ReportInfo for Lighting Page (0x59)
///   - led_rgb_builders: list of LedRgbChannelBuilder for LED Page (0x08) RGB LED
fn parse_descriptor(desc: &[u8]) -> (LampArrayReports, Vec<LedRgbChannelBuilder>) {
    let mut state = ParserState::new();
    let mut offset = 0;

    while offset < desc.len() {
        let Some((tag, item_type, payload, item_size)) = parse_item(desc, offset) else {
            break;
        };
        offset += item_size;
        let val = payload_value(payload);

        match item_type {
            1 => state.handle_global(tag, val, payload), // Global
            2 => state.handle_local(tag, val),           // Local
            0 => state.handle_main(tag, val), // Main (val is collection type for Collection items)
            _ => {}
        }
    }

    state.finalize()
}

// --- Device Discovery ---

/// Read HID_NAME from the device's uevent file.
fn get_hid_name(hidraw: &str) -> String {
    let uevent_path = format!("/sys/class/hidraw/{hidraw}/device/uevent");
    if let Ok(content) = fs::read_to_string(&uevent_path) {
        for line in content.lines() {
            if let Some(name) = line.strip_prefix("HID_NAME=") {
                return name.to_string();
            }
        }
    }
    "Unknown".to_string()
}

/// Parse a single sysfs hidraw entry into [`DeviceInfo`](s).
///
/// Reads the device's HID report descriptor, parses it, and returns any
/// LampArray or LED RGB devices found. Device name and hidraw path are
/// read/formatted only once and shared across all results.
fn parse_hidraw_entry(sysfs_entry: &Path) -> Vec<DeviceInfo> {
    let desc_path = sysfs_entry.join("device").join("report_descriptor");
    let desc_bytes = match fs::read(&desc_path) {
        Ok(b) if !b.is_empty() => b,
        _ => return Vec::new(),
    };

    let hidraw_name = match sysfs_entry.file_name() {
        Some(n) => n.to_string_lossy(),
        None => return Vec::new(),
    };

    let (lamp_reports, led_rgb_builders) = parse_descriptor(&desc_bytes);

    // Check for LampArray (Usage Page 0x59)
    // Minimum: attributes report + at least one update report.
    // Control report (AutonomousMode) is optional per Section 26.10.1.
    let has_lamp = lamp_reports.attributes.is_some()
        && (lamp_reports.range_update.is_some() || lamp_reports.multi_update.is_some());

    if !has_lamp && led_rgb_builders.is_empty() {
        return Vec::new();
    }

    // Read name ONCE, build hidraw path ONCE
    let name = get_hid_name(&hidraw_name);
    let hidraw_path = format!("/dev/{hidraw_name}");
    let mut devices = Vec::new();

    if has_lamp {
        devices.push(DeviceInfo {
            hidraw_path: hidraw_path.clone(),
            name: name.clone(),
            kind: DeviceKind::LampArray(lamp_reports),
        });
    }

    // LED Page RGB LED (Usage Page 0x08)
    // Builders are already filtered to is_complete() by finalize()
    for builder in led_rgb_builders {
        devices.push(DeviceInfo {
            hidraw_path: hidraw_path.clone(),
            name: name.clone(),
            kind: DeviceKind::LedRgb(LedRgbChannelInfo {
                report_id: builder.report_id,
                report_size: builder.report_size,
                red_offset: builder.red_offset.expect("guaranteed by is_complete()"),
                blue_offset: builder.blue_offset.expect("guaranteed by is_complete()"),
                green_offset: builder.green_offset.expect("guaranteed by is_complete()"),
                intensity_offset: builder.intensity_offset,
                channel_size: builder.channel_size,
                report_type: builder.report_type,
                red_logical_max: builder.red_logical_max,
                green_logical_max: builder.green_logical_max,
                blue_logical_max: builder.blue_logical_max,
                intensity_logical_max: builder.intensity_logical_max,
            }),
        });
    }

    devices
}

/// Discover RGB devices at a specific hidraw path (e.g. "/dev/hidraw0").
///
/// Only parses the descriptor for the specified device, avoiding a full
/// sysfs scan. Returns an empty Vec if the path is not a valid hidraw
/// device or has no RGB capability.
pub fn discover_device(hidraw_path: &str) -> Vec<DeviceInfo> {
    let name = hidraw_path.rsplit('/').next().unwrap_or("");
    let sysfs = Path::new("/sys/class/hidraw").join(name);
    if sysfs.exists() {
        parse_hidraw_entry(&sysfs)
    } else {
        Vec::new()
    }
}

/// Scan all hidraw devices for LampArray and LED RGB support.
///
/// Reads each device's HID report descriptor from sysfs and parses it
/// to find devices implementing:
/// - Usage Page 0x59 (Lighting and Illumination) -- LampArray
/// - Usage Page 0x08 (LED Page) with Usage 0x52 (RGB LED)
///
/// Returns a list of [`DeviceInfo`] objects.
pub fn discover_devices() -> Vec<DeviceInfo> {
    let hidraw_dir = Path::new("/sys/class/hidraw");
    if !hidraw_dir.exists() {
        return Vec::new();
    }

    let mut entries: Vec<_> = match fs::read_dir(hidraw_dir) {
        Ok(rd) => rd.filter_map(|e| e.ok()).map(|e| e.path()).collect(),
        Err(_) => return Vec::new(),
    };
    entries.sort();

    entries.iter().flat_map(|e| parse_hidraw_entry(e)).collect()
}