amql_selector/

selector.rs

//! Structural selector parser.
//!
//! Parses selectors like:
//!   `controller[method="POST"]`
//!   `function[async]`
//!   `class > method[name="create"]`
//!   `[owner="@backend"]`

use crate::types::TagName;
pub use amql_predicates::{AttrOp, AttrPredicate, Predicate, PredicateOp, PredicateValue};
use serde::Serialize;

/// Parsed selector AST — a chain of compound selectors.
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[derive(Debug, Clone, Serialize)]
pub struct SelectorAst {
    /// Ordered chain of compound selectors (left-to-right).
    pub compounds: Vec<CompoundSelector>,
}

/// A single compound selector: optional tag + zero or more attribute predicates.
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[derive(Debug, Clone, Serialize)]
pub struct CompoundSelector {
    /// Tag filter, if any (e.g. "function").
    pub tag: Option<TagName>,
    /// Attribute predicates within brackets.
    pub attrs: Vec<AttrPredicate>,
    /// Combinator linking this compound to the previous one.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub combinator: Option<Combinator>,
}

/// Combinator between compound selectors.
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
#[non_exhaustive]
pub enum Combinator {
    /// `>` — direct child
    Child,
    /// ` ` — descendant
    Descendant,
    /// `+` — adjacent sibling
    AdjacentSibling,
    /// `~` — general sibling
    GeneralSibling,
}

/// Parse a selector string into an AST.
#[must_use = "parsing a selector is useless without inspecting the result"]
pub fn parse_selector(input: &str) -> Result<SelectorAst, String> {
    let trimmed = input.trim();
    if trimmed.is_empty() {
        return Err("Empty selector".to_string());
    }
    let mut parser = SelectorParser::new(trimmed);
    let ast = parser.parse()?;
    // Reject selectors where all compounds are empty (no tag, no attrs)
    if ast
        .compounds
        .iter()
        .all(|c| c.tag.is_none() && c.attrs.is_empty())
    {
        return Err("Empty selector".to_string());
    }
    // Reject sibling combinators — they are not supported
    for compound in &ast.compounds {
        if matches!(
            compound.combinator,
            Some(Combinator::AdjacentSibling) | Some(Combinator::GeneralSibling)
        ) {
            return Err("Sibling combinators (+, ~) are not supported".to_string());
        }
    }
    Ok(ast)
}

struct SelectorParser<'a> {
    input: &'a str,
    bytes: &'a [u8],
    pos: usize,
}

impl<'a> SelectorParser<'a> {
    fn new(input: &'a str) -> Self {
        Self {
            input,
            bytes: input.as_bytes(),
            pos: 0,
        }
    }

    fn slice(&self, start: usize, end: usize) -> &'a str {
        &self.input[start..end]
    }

    fn parse(&mut self) -> Result<SelectorAst, String> {
        let mut compounds = vec![self.parse_compound()?];

        while self.pos < self.bytes.len() {
            let combinator = match self.parse_combinator() {
                Some(c) => c,
                None => break,
            };
            let mut compound = self.parse_compound()?;
            compound.combinator = Some(combinator);
            compounds.push(compound);
        }

        self.skip_whitespace();
        if self.pos < self.bytes.len() {
            return Err(format!(
                "Unexpected character '{}' at position {}",
                self.bytes[self.pos] as char, self.pos
            ));
        }

        Ok(SelectorAst { compounds })
    }

    fn parse_compound(&mut self) -> Result<CompoundSelector, String> {
        self.skip_whitespace();
        let tag = self.parse_tag();
        let attrs = self.parse_attr_list()?;
        Ok(CompoundSelector {
            tag,
            attrs,
            combinator: None,
        })
    }

    fn parse_tag(&mut self) -> Option<TagName> {
        let start = self.pos;
        while self.pos < self.bytes.len() && self.is_ident_char(self.bytes[self.pos]) {
            self.pos += 1;
        }
        if self.pos > start {
            Some(TagName::from(self.slice(start, self.pos)))
        } else {
            None
        }
    }

    fn parse_attr_list(&mut self) -> Result<Vec<AttrPredicate>, String> {
        let mut attrs = Vec::new();
        while self.pos < self.bytes.len() && self.bytes[self.pos] == b'[' {
            self.pos += 1; // skip '['

            // Extract bracket content and delegate to amql-predicates
            let start = self.pos;
            let mut depth = 1;
            while self.pos < self.bytes.len() && depth > 0 {
                match self.bytes[self.pos] {
                    b'[' => depth += 1,
                    b']' => depth -= 1,
                    b'"' | b'\'' => {
                        let quote = self.bytes[self.pos];
                        self.pos += 1;
                        while self.pos < self.bytes.len() && self.bytes[self.pos] != quote {
                            if self.bytes[self.pos] == b'\\' {
                                self.pos += 1;
                            }
                            self.pos += 1;
                        }
                    }
                    _ => {}
                }
                if depth > 0 {
                    self.pos += 1;
                }
            }

            if depth != 0 {
                return Err(format!("Unclosed '[' at position {}", start - 1));
            }

            let bracket_content = self.slice(start, self.pos);
            self.pos += 1; // skip closing ']'

            let parsed = amql_predicates::parse_predicate_list(bracket_content)?;
            attrs.extend(parsed);
        }
        Ok(attrs)
    }

    fn parse_combinator(&mut self) -> Option<Combinator> {
        let before_space = self.pos;
        self.skip_whitespace();

        if self.pos >= self.bytes.len() {
            return None;
        }

        let ch = self.bytes[self.pos];
        if ch == b'>' || ch == b'+' || ch == b'~' {
            self.pos += 1;
            self.skip_whitespace();
            return Some(match ch {
                b'>' => Combinator::Child,
                b'+' => Combinator::AdjacentSibling,
                b'~' => Combinator::GeneralSibling,
                _ => unreachable!(),
            });
        }

        // If we consumed whitespace and next char starts a compound, it's a descendant combinator
        if self.pos > before_space && self.pos < self.bytes.len() {
            let next = self.bytes[self.pos];
            if self.is_ident_char(next) || next == b'[' {
                return Some(Combinator::Descendant);
            }
        }

        None
    }

    fn skip_whitespace(&mut self) {
        while self.pos < self.bytes.len() && self.bytes[self.pos].is_ascii_whitespace() {
            self.pos += 1;
        }
    }

    fn is_ident_char(&self, ch: u8) -> bool {
        ch.is_ascii_alphanumeric() || ch == b'_' || ch == b'-'
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parses_basic_selectors() {
        // Arrange
        let bare_tag = "controller";
        let tag_attr_presence = "function[async]";
        let tag_attr_value = r#"controller[method="POST"]"#;
        let attr_only = r#"[owner="@backend"]"#;

        // Act
        let bare = parse_selector(bare_tag).unwrap();
        let presence = parse_selector(tag_attr_presence).unwrap();
        let value = parse_selector(tag_attr_value).unwrap();
        let attr = parse_selector(attr_only).unwrap();

        // Assert
        assert_eq!(bare.compounds.len(), 1);
        assert_eq!(bare.compounds[0].tag.as_deref(), Some("controller"));
        assert!(bare.compounds[0].attrs.is_empty());

        assert_eq!(presence.compounds.len(), 1);
        assert_eq!(presence.compounds[0].tag.as_deref(), Some("function"));
        assert_eq!(
            presence.compounds[0].attrs,
            vec![AttrPredicate {
                name: "async".to_string(),
                op: None,
                value: None,
            }]
        );

        assert_eq!(value.compounds.len(), 1);
        assert_eq!(value.compounds[0].tag.as_deref(), Some("controller"));
        assert_eq!(
            value.compounds[0].attrs,
            vec![AttrPredicate {
                name: "method".to_string(),
                op: Some(AttrOp::Eq),
                value: Some(PredicateValue::String("POST".to_string())),
            }]
        );

        assert_eq!(attr.compounds.len(), 1);
        assert!(attr.compounds[0].tag.is_none());
        assert_eq!(
            attr.compounds[0].attrs,
            vec![AttrPredicate {
                name: "owner".to_string(),
                op: Some(AttrOp::Eq),
                value: Some(PredicateValue::String("@backend".to_string())),
            }]
        );
    }

    #[test]
    fn parses_multiple_and_quoted() {
        // Arrange
        let multi_attrs = r#"function[name="create",async]"#;
        let single_quoted = "controller[method='POST']";

        // Act
        let multi = parse_selector(multi_attrs).unwrap();
        let quoted = parse_selector(single_quoted).unwrap();

        // Assert
        assert_eq!(multi.compounds[0].attrs.len(), 2);
        assert_eq!(
            multi.compounds[0].attrs[0],
            AttrPredicate {
                name: "name".to_string(),
                op: Some(AttrOp::Eq),
                value: Some(PredicateValue::String("create".to_string())),
            }
        );
        assert_eq!(
            multi.compounds[0].attrs[1],
            AttrPredicate {
                name: "async".to_string(),
                op: None,
                value: None,
            }
        );

        assert_eq!(
            quoted.compounds[0].attrs[0],
            AttrPredicate {
                name: "method".to_string(),
                op: Some(AttrOp::Eq),
                value: Some(PredicateValue::String("POST".to_string())),
            }
        );
    }

    #[test]
    fn parses_operators() {
        // Arrange
        let starts = r#"[name^="handle"]"#;
        let contains = r#"[name*="user"]"#;
        let ends = r#"[name$="Controller"]"#;

        // Act
        let starts_ast = parse_selector(starts).unwrap();
        let contains_ast = parse_selector(contains).unwrap();
        let ends_ast = parse_selector(ends).unwrap();

        // Assert
        assert_eq!(
            starts_ast.compounds[0].attrs[0],
            AttrPredicate {
                name: "name".to_string(),
                op: Some(AttrOp::StartsWith),
                value: Some(PredicateValue::String("handle".to_string())),
            }
        );

        assert_eq!(
            contains_ast.compounds[0].attrs[0],
            AttrPredicate {
                name: "name".to_string(),
                op: Some(AttrOp::Contains),
                value: Some(PredicateValue::String("user".to_string())),
            }
        );

        assert_eq!(
            ends_ast.compounds[0].attrs[0],
            AttrPredicate {
                name: "name".to_string(),
                op: Some(AttrOp::EndsWith),
                value: Some(PredicateValue::String("Controller".to_string())),
            }
        );
    }

    #[test]
    fn parses_combinators() {
        // Arrange
        let child = "class > method";
        let descendant = "class method";
        let complex = r#"class[name="UserService"] > method[async]"#;

        // Act
        let child_ast = parse_selector(child).unwrap();
        let desc_ast = parse_selector(descendant).unwrap();
        let complex_ast = parse_selector(complex).unwrap();

        // Assert
        assert_eq!(child_ast.compounds.len(), 2);
        assert_eq!(child_ast.compounds[0].tag.as_deref(), Some("class"));
        assert_eq!(child_ast.compounds[1].tag.as_deref(), Some("method"));
        assert_eq!(child_ast.compounds[1].combinator, Some(Combinator::Child));

        assert_eq!(desc_ast.compounds.len(), 2);
        assert_eq!(desc_ast.compounds[0].tag.as_deref(), Some("class"));
        assert_eq!(desc_ast.compounds[1].tag.as_deref(), Some("method"));
        assert_eq!(
            desc_ast.compounds[1].combinator,
            Some(Combinator::Descendant)
        );

        assert_eq!(complex_ast.compounds.len(), 2);
        assert_eq!(complex_ast.compounds[0].tag.as_deref(), Some("class"));
        assert_eq!(
            complex_ast.compounds[0].attrs,
            vec![AttrPredicate {
                name: "name".to_string(),
                op: Some(AttrOp::Eq),
                value: Some(PredicateValue::String("UserService".to_string())),
            }]
        );
        assert_eq!(complex_ast.compounds[1].tag.as_deref(), Some("method"));
        assert_eq!(
            complex_ast.compounds[1].attrs,
            vec![AttrPredicate {
                name: "async".to_string(),
                op: None,
                value: None,
            }]
        );
        assert_eq!(complex_ast.compounds[1].combinator, Some(Combinator::Child));
    }

    #[test]
    fn handles_escape_sequences() {
        // Arrange & Act
        let escaped_quote = parse_selector(r#"[name="foo\"bar"]"#).unwrap();
        let escaped_backslash = parse_selector(r#"[name="foo\\bar"]"#).unwrap();

        // Assert
        assert_eq!(
            escaped_quote.compounds[0].attrs[0].value,
            Some(PredicateValue::String(r#"foo"bar"#.to_string()))
        );
        assert_eq!(
            escaped_backslash.compounds[0].attrs[0].value,
            Some(PredicateValue::String(r"foo\bar".to_string()))
        );
    }

    #[test]
    fn rejects_empty_selectors() {
        // Arrange & Act & Assert
        assert!(parse_selector("").is_err());
        assert!(parse_selector("   ").is_err());
    }

    #[test]
    fn rejects_sibling_combinators() {
        // Arrange & Act & Assert
        assert!(parse_selector("a + b").is_err());
        assert!(parse_selector("a ~ b").is_err());
    }

    #[test]
    fn parses_numeric_operators_in_selector() {
        // Arrange & Act
        let ast = parse_selector("[count>=5]").unwrap();

        // Assert
        assert_eq!(
            ast.compounds[0].attrs[0].op,
            Some(AttrOp::Gte),
            "should parse >= operator"
        );
        assert_eq!(
            ast.compounds[0].attrs[0].value,
            Some(PredicateValue::Number(5.0)),
            "should parse numeric value"
        );
    }
}