kglite 0.16.7

//! Cypher parser: MATCH / OPTIONAL MATCH clause + pattern extraction.

use super::super::ast::*;
use super::super::tokenizer::{keyword_name_token, reserved_literal_name_token, CypherToken};
use super::{describe_with_hint, describe_with_hint_opt, CypherParser};

impl CypherParser {
    // ========================================================================
    // MATCH Clause
    // ========================================================================

    pub(super) fn parse_match_clause(&mut self, optional: bool) -> Result<Clause, String> {
        self.expect(&CypherToken::Match)?;

        let mut path_assignments = Vec::new();

        // Check for path assignment: p = shortestPath(...)
        // Pattern: Identifier Equals [Identifier("shortestPath") LParen] pattern [RParen]
        let patterns = if self.is_path_assignment() {
            let path_var = self.consume_identifier()?;
            self.expect(&CypherToken::Equals)?;

            // Check for shortestPath( / allShortestPaths( wrapper
            let is_all_shortest = self.is_all_shortest_paths_call();
            let is_shortest = is_all_shortest || self.is_shortest_path_call();
            if is_shortest {
                self.advance(); // consume the wrapper identifier
                self.expect(&CypherToken::LParen)?;
            }

            let patterns = self.parse_match_patterns()?;

            if is_shortest {
                self.expect(&CypherToken::RParen)?;
            }

            path_assignments.push(PathAssignment {
                variable: path_var,
                pattern_index: 0,
                is_shortest_path: is_shortest,
                all_shortest: is_all_shortest,
            });
            patterns
        } else {
            self.parse_match_patterns()?
        };

        // `Match = ['OPTIONAL'] 'MATCH' Pattern [Where]` — a WHERE directly
        // after OPTIONAL MATCH is part of *this* clause, so it filters
        // candidates during matching and a row whose candidates all fail is
        // null-extended rather than deleted. A plain MATCH's WHERE keeps its
        // own `Clause::Where` (identical semantics there, and every
        // MATCH+WHERE planner pass matches on that adjacency) — see
        // `MatchClause::where_clause`.
        let where_clause = if optional && self.check(&CypherToken::Where) {
            self.advance(); // consume WHERE
            Some(WhereClause {
                predicate: self.parse_predicate()?,
            })
        } else {
            None
        };

        let clause = MatchClause {
            patterns,
            path_assignments,
            limit_hint: None,
            distinct_node_hint: None,
            where_clause,
            node_anchors: Vec::new(),
        };
        if optional {
            Ok(Clause::OptionalMatch(clause))
        } else {
            Ok(Clause::Match(clause))
        }
    }

    /// Check if current position looks like: Identifier = [shortestPath(] ...
    pub(super) fn is_path_assignment(&self) -> bool {
        matches!(self.peek(), Some(CypherToken::Identifier(_)))
            && self.peek_at(1) == Some(&CypherToken::Equals)
    }

    /// Check if current position is shortestPath( — called AFTER consuming "var ="
    pub(super) fn is_shortest_path_call(&self) -> bool {
        if let Some(CypherToken::Identifier(name)) = self.peek() {
            name.eq_ignore_ascii_case("shortestPath")
                && self.peek_at(1) == Some(&CypherToken::LParen)
        } else {
            false
        }
    }

    /// Check if current position is allShortestPaths( — called AFTER consuming "var ="
    pub(super) fn is_all_shortest_paths_call(&self) -> bool {
        if let Some(CypherToken::Identifier(name)) = self.peek() {
            name.eq_ignore_ascii_case("allShortestPaths")
                && self.peek_at(1) == Some(&CypherToken::LParen)
        } else {
            false
        }
    }

    /// Consume an identifier token and return the string
    pub(super) fn consume_identifier(&mut self) -> Result<String, String> {
        match self.advance() {
            Some(CypherToken::Identifier(s)) => Ok(s.clone()),
            other => Err(format!(
                "Expected identifier, got {}",
                describe_with_hint_opt(other)
            )),
        }
    }

    /// Parse one or more comma-separated patterns in MATCH
    pub(super) fn parse_match_patterns(
        &mut self,
    ) -> Result<Vec<crate::graph::core::pattern_matching::Pattern>, String> {
        let mut patterns = Vec::new();

        loop {
            // Reconstruct the pattern string from tokens until we hit a comma (at top-level)
            // or a clause boundary
            let pattern_str = self.extract_pattern_string()?;
            if pattern_str.is_empty() {
                return Err("Expected a pattern in MATCH clause".to_string());
            }

            let pattern = crate::graph::core::pattern_matching::parse_pattern(&pattern_str)
                .map_err(|e| format!("Pattern parse error: {}", e))?;
            patterns.push(pattern);

            // Check for comma to continue with more patterns
            if self.check(&CypherToken::Comma) {
                self.advance();
            } else {
                break;
            }
        }

        Ok(patterns)
    }

    /// Parse patterns inside EXISTS { ... } — same as parse_match_patterns but uses
    /// extract_exists_pattern_string which stops at RBrace instead of clause boundaries.
    /// Returns the patterns plus their clause-group ids (comma-joined
    /// patterns share a group; each MATCH keyword starts a new one).
    pub(super) fn parse_exists_patterns(
        &mut self,
    ) -> Result<
        (
            Vec<crate::graph::core::pattern_matching::Pattern>,
            Vec<usize>,
        ),
        String,
    > {
        // Default delimiter for `EXISTS { ... }` / `count { ... }`: closing brace.
        self.parse_pattern_subquery_patterns(&CypherToken::RBrace)
    }

    /// Parse one or more comma/MATCH-separated patterns until a delimiter
    /// token at top level. Used by EXISTS/count (delimiter = `}`) and the
    /// 0.9.0 §6 `size((pattern))` form (delimiter = `)`).
    ///
    /// The second return value assigns each pattern a clause-group id:
    /// comma-separated patterns share the group of the pattern before them
    /// (they form ONE clause, subject to the relationship-uniqueness trail
    /// rule); a `MATCH` keyword separator starts a new group (a separate
    /// clause — relationships may be re-used across it, as across separate
    /// MATCH clauses).
    pub(super) fn parse_pattern_subquery_patterns(
        &mut self,
        end_token: &CypherToken,
    ) -> Result<
        (
            Vec<crate::graph::core::pattern_matching::Pattern>,
            Vec<usize>,
        ),
        String,
    > {
        let mut patterns = Vec::new();
        let mut groups: Vec<usize> = Vec::new();
        let mut group = 0usize;

        loop {
            let pattern_str = self.extract_pattern_subquery_string(end_token)?;
            if pattern_str.is_empty() {
                if patterns.is_empty() {
                    return Err("Expected a pattern inside EXISTS { }".to_string());
                }
                break;
            }

            let pattern = crate::graph::core::pattern_matching::parse_pattern(&pattern_str)
                .map_err(|e| format!("Pattern parse error in EXISTS: {}", e))?;
            patterns.push(pattern);
            groups.push(group);

            if self.check(&CypherToken::Comma) {
                self.advance();
            } else if self.check(&CypherToken::Match) {
                // Subquery form: EXISTS { MATCH (a)-[:R]->(b) MATCH (c)-[:R2]->(d) ... }
                // Don't advance — the next iteration's
                // extract_exists_pattern_string will skip the MATCH at its
                // start (same path as the optional first MATCH).
                group += 1;
            } else {
                break;
            }
        }

        Ok((patterns, groups))
    }

    /// Extract tokens forming a pattern inside EXISTS { ... }, stopping at RBrace or comma.
    /// Re-serialize an identifier, adding backticks if it contains spaces or
    /// special chars, or if the secondary pattern lexer would read the bare
    /// word back as something other than an identifier.
    ///
    /// Quoting always routes through [`backtick_quote`], so an identifier that
    /// itself contains a backtick survives the round trip through the secondary
    /// pattern lexer instead of terminating the quote early.
    ///
    /// The second condition is the one that closes the mint-but-never-query
    /// trap: a token that reached the parser as `` `TRUE` `` is a plain
    /// `Identifier` by then, and emitting it bare handed the secondary lexer a
    /// boolean. The word list lives with that lexer
    /// ([`crate::graph::core::pattern_matching::parser::bare_word_needs_quoting`])
    /// because it is a property of *its* grammar, not of this emitter.
    pub(super) fn quote_identifier(s: &str) -> String {
        if s.contains(' ')
            || s.contains('-')
            || s.contains('/')
            || s.contains('.')
            || s.contains('(')
            || s.contains(')')
            || s.contains('`')
            || crate::graph::core::pattern_matching::parser::bare_word_needs_quoting(s)
        {
            backtick_quote(s)
        } else {
            s.to_string()
        }
    }

    /// Re-serialize tokens forming a pattern, stopping at the supplied
    /// delimiter (RBrace for EXISTS/count, RParen for size).
    pub(super) fn extract_pattern_subquery_string(
        &mut self,
        end_token: &CypherToken,
    ) -> Result<String, String> {
        // Skip optional MATCH keyword — standard Cypher allows EXISTS { MATCH (pattern) }
        if self.check(&CypherToken::Match) {
            self.advance();
        }

        let mut parts = Vec::new();
        let mut paren_depth = 0i32;
        let mut bracket_depth = 0i32;
        let mut brace_depth = 0i32;
        let mut prev: Option<CypherToken> = None;

        while self.has_tokens() {
            // Stop at the caller-supplied end-token (RBrace for EXISTS,
            // RParen for size). Only at top level (depth 0).
            if paren_depth == 0 && bracket_depth == 0 && self.check(end_token) {
                break;
            }

            // Stop at comma at top level (pattern separator)
            if paren_depth == 0 && bracket_depth == 0 && self.check(&CypherToken::Comma) {
                break;
            }

            // Stop at WHERE keyword (EXISTS { MATCH ... WHERE ... } subquery)
            if paren_depth == 0 && bracket_depth == 0 && self.check(&CypherToken::Where) {
                break;
            }

            // Stop at MATCH keyword at top level — multi-MATCH subquery
            // form (`EXISTS { MATCH ... MATCH ... }`). The outer
            // parse_exists_patterns loop continues on this case.
            if paren_depth == 0 && bracket_depth == 0 && self.check(&CypherToken::Match) {
                break;
            }

            let token = self.advance().unwrap().clone();

            match &token {
                CypherToken::LParen => {
                    paren_depth += 1;
                    parts.push("(".to_string());
                }
                CypherToken::RParen => {
                    paren_depth -= 1;
                    parts.push(")".to_string());
                }
                CypherToken::LBracket => {
                    bracket_depth += 1;
                    parts.push("[".to_string());
                }
                CypherToken::RBracket => {
                    bracket_depth -= 1;
                    parts.push("]".to_string());
                }
                CypherToken::LBrace => {
                    brace_depth += 1;
                    parts.push("{".to_string());
                }
                CypherToken::RBrace => {
                    brace_depth -= 1;
                    parts.push("}".to_string());
                }
                CypherToken::Colon => parts.push(":".to_string()),
                CypherToken::Comma => parts.push(",".to_string()),
                CypherToken::Dash => parts.push("-".to_string()),
                CypherToken::GreaterThan => parts.push(">".to_string()),
                CypherToken::LessThan => parts.push("<".to_string()),
                CypherToken::Star => parts.push("*".to_string()),
                CypherToken::DotDot => parts.push("..".to_string()),
                CypherToken::Dot => parts.push(".".to_string()),
                CypherToken::Identifier(s) => parts.push(Self::quote_identifier(s)),
                CypherToken::StringLit(s) => {
                    // Re-escape quotes so the pattern parser can re-tokenize correctly
                    let escaped = s.replace('\\', "\\\\").replace('\'', "\\'");
                    parts.push(format!("'{}'", escaped));
                }
                CypherToken::IntLit(n) => parts.push(n.to_string()),
                CypherToken::FloatLit(f) => parts.push(f.to_string()),
                // A value-literal word in a NAME position — see
                // `at_name_position`. Backtick its verbatim lexeme so the
                // secondary lexer reads a name, not a boolean.
                tok @ (CypherToken::True | CypherToken::False | CypherToken::Null)
                    if at_name_position(prev.as_ref(), self.peek(), brace_depth) =>
                {
                    let name = self
                        .keyword_lexeme_at(self.pos - 1)
                        .unwrap_or_else(|| reserved_literal_name_token(tok).unwrap());
                    parts.push(backtick_quote(name));
                }
                CypherToken::True => parts.push("true".to_string()),
                CypherToken::False => parts.push("false".to_string()),
                // Re-serialize `$param` so the inner pattern parser sees it
                // and the executor substitutes it (e.g.
                // `EXISTS { MATCH (a)-[:R]->(:T {id:$id}) }`). The top-level
                // MATCH-pattern extractor already does this; without it,
                // params worked everywhere except inside an EXISTS pattern.
                CypherToken::Parameter(name) => parts.push(format!("${}", name)),
                // KG-2: a reserved keyword used as a name (label / rel-type /
                // property key) — backtick its verbatim source lexeme so the
                // secondary pattern parser reads it as an identifier
                // (`[:CONTAINS]`, `(:CONTAINS)`, `{contains: 1}` keeps key
                // `contains`).
                tok if keyword_name_token(tok).is_some() => {
                    let name = self
                        .keyword_lexeme_at(self.pos - 1)
                        .unwrap_or_else(|| keyword_name_token(tok).unwrap());
                    parts.push(backtick_quote(name));
                }
                _ => {
                    return Err(format!(
                        "Unexpected token in EXISTS pattern: {}",
                        describe_with_hint(&token)
                    ));
                }
            }
            prev = Some(token);
        }

        Ok(parts.join(" "))
    }

    /// Extract tokens forming a single pattern and reconstruct as a string
    /// for the existing pattern_matching parser.
    /// Stops at commas (outside parens/brackets), clause keywords, or end of input.
    pub(super) fn extract_pattern_string(&mut self) -> Result<String, String> {
        let mut parts = Vec::new();
        let mut paren_depth = 0i32;
        let mut bracket_depth = 0i32;
        let mut brace_depth = 0i32;
        let mut prev: Option<CypherToken> = None;

        while self.has_tokens() {
            // Stop at clause boundaries (only at top level)
            if paren_depth == 0 && bracket_depth == 0 && self.at_clause_boundary() {
                break;
            }

            // Stop at comma at top level (pattern separator)
            if paren_depth == 0 && bracket_depth == 0 && self.check(&CypherToken::Comma) {
                break;
            }

            // Stop at tokens that legitimately *follow* a pattern expression
            // at top level: boolean operators (AND/OR/XOR in WHERE), `AS`
            // (RETURN/WITH alias), CASE keywords (THEN/ELSE/END), and the
            // comprehension/reduce separator `|`. Inside parens/brackets the
            // soft-keyword ones (AS, XOR) still round-trip as property keys
            // via the keyword_name_token arm below.
            if paren_depth == 0
                && bracket_depth == 0
                && matches!(
                    self.peek(),
                    Some(CypherToken::And)
                        | Some(CypherToken::Or)
                        | Some(CypherToken::Xor)
                        | Some(CypherToken::As)
                        | Some(CypherToken::Then)
                        | Some(CypherToken::Else)
                        | Some(CypherToken::End)
                        | Some(CypherToken::Pipe)
                )
            {
                break;
            }

            // Stop at RParen that would go negative (e.g. closing shortestPath(...))
            if paren_depth == 0 && self.check(&CypherToken::RParen) {
                break;
            }

            // Stop at a top-level RBrace — it can only be the `}` closing a
            // `CALL { ... }` subquery body (property maps live inside `()` or
            // `[]`, so any `}` belonging to a map is at paren/bracket depth
            // > 0). Without this, a MATCH that is the last clause of a
            // subquery body swallows the terminating `}` into the pattern
            // string and the body fails to close.
            if paren_depth == 0 && bracket_depth == 0 && self.check(&CypherToken::RBrace) {
                break;
            }

            let token = self.advance().unwrap().clone();

            match &token {
                CypherToken::LParen => {
                    paren_depth += 1;
                    parts.push("(".to_string());
                }
                CypherToken::RParen => {
                    paren_depth -= 1;
                    parts.push(")".to_string());
                }
                CypherToken::LBracket => {
                    bracket_depth += 1;
                    parts.push("[".to_string());
                }
                CypherToken::RBracket => {
                    bracket_depth -= 1;
                    parts.push("]".to_string());
                }
                CypherToken::LBrace => {
                    brace_depth += 1;
                    parts.push("{".to_string());
                }
                CypherToken::RBrace => {
                    brace_depth -= 1;
                    parts.push("}".to_string());
                }
                CypherToken::Colon => parts.push(":".to_string()),
                CypherToken::Comma => parts.push(",".to_string()),
                CypherToken::Dash => parts.push("-".to_string()),
                CypherToken::GreaterThan => parts.push(">".to_string()),
                CypherToken::LessThan => parts.push("<".to_string()),
                CypherToken::Star => parts.push("*".to_string()),
                CypherToken::DotDot => parts.push("..".to_string()),
                CypherToken::Dot => parts.push(".".to_string()),
                CypherToken::Pipe => parts.push("|".to_string()),
                CypherToken::Identifier(s) => parts.push(Self::quote_identifier(s)),
                CypherToken::StringLit(s) => {
                    let escaped = s.replace('\\', "\\\\").replace('\'', "\\'");
                    parts.push(format!("'{}'", escaped));
                }
                CypherToken::IntLit(n) => parts.push(n.to_string()),
                CypherToken::FloatLit(f) => parts.push(f.to_string()),
                // A value-literal word in a NAME position — see
                // `at_name_position`. Backtick its verbatim lexeme so the
                // secondary lexer reads a name, not a boolean.
                tok @ (CypherToken::True | CypherToken::False | CypherToken::Null)
                    if at_name_position(prev.as_ref(), self.peek(), brace_depth) =>
                {
                    let name = self
                        .keyword_lexeme_at(self.pos - 1)
                        .unwrap_or_else(|| reserved_literal_name_token(tok).unwrap());
                    parts.push(backtick_quote(name));
                }
                CypherToken::True => parts.push("true".to_string()),
                CypherToken::False => parts.push("false".to_string()),
                CypherToken::Parameter(name) => {
                    parts.push(format!("${}", name));
                }
                // KG-2: a reserved keyword used as a name (label / rel-type /
                // property key) — backtick its verbatim source lexeme so the
                // secondary pattern parser reads it as an identifier
                // (`[:CONTAINS]`, `(:CONTAINS)`, `{contains: 1}` keeps key
                // `contains`). Only reached at bracket/paren depth > 0
                // (depth-0 keywords break out earlier as clause boundaries).
                tok if keyword_name_token(tok).is_some() => {
                    let name = self
                        .keyword_lexeme_at(self.pos - 1)
                        .unwrap_or_else(|| keyword_name_token(tok).unwrap());
                    parts.push(backtick_quote(name));
                }
                _ => {
                    return Err(format!(
                        "Unexpected token in MATCH pattern: {}",
                        describe_with_hint(&token)
                    ));
                }
            }
            prev = Some(token);
        }

        Ok(parts.join(""))
    }

    // ========================================================================
    // WHERE Clause
    // ========================================================================
}

/// Does the token just consumed by a pattern re-serializer occupy a **name**
/// position — a label, a relationship type, or a property key — rather than a
/// value position?
///
/// The re-serializer walks a flat token stream, so this is the whole of its
/// grammar knowledge, and it is deliberately small because a pattern's
/// structure is: names follow `:` (label / relationship type) or `|` (type
/// alternation) outside any property map, and a property map's keys are the
/// tokens immediately before their `:`. Everything else at map depth 0 is a
/// variable position, where openCypher's `Variable = SymbolicName` excludes
/// the reserved words — refusing them there is what keeps MATCH symmetric with
/// CREATE, whose variable slot takes an `Identifier` only.
///
/// `brace_depth` counts open `{` of inline property maps; `prev` and `next`
/// are the surrounding tokens (`None` at the ends of the pattern).
///
/// **Extension point (T10, dynamic labels).** This is the single place that
/// answers "is this token a name here?", so a second token class joins by
/// adding one guarded arm at each of the two call sites below and reusing this
/// predicate — `$(...)` parameter labels are name-position tokens by exactly
/// this rule, and must not disturb the `$param` *value* arm that already
/// exists a few lines above them.
fn at_name_position(
    prev: Option<&CypherToken>,
    next: Option<&CypherToken>,
    brace_depth: i32,
) -> bool {
    if brace_depth > 0 {
        matches!(next, Some(CypherToken::Colon))
    } else {
        matches!(prev, Some(CypherToken::Colon) | Some(CypherToken::Pipe))
    }
}

/// Wrap `name` in backticks, doubling any backtick it contains.
///
/// This is the *only* place a quoted identifier is written back into Cypher
/// text, and it is the emitter half of the tokenizer's doubling rule: without
/// it, a re-serialized identifier carrying a backtick would close its own quote
/// in the secondary pattern lexer and the remainder would be read as grammar.
/// Round-tripping `a`b` through quote-then-lex must return `a`b`.
pub(super) fn backtick_quote(name: &str) -> String {
    let mut out = String::with_capacity(name.len() + 2);
    out.push('`');
    for ch in name.chars() {
        if ch == '`' {
            out.push('`');
        }
        out.push(ch);
    }
    out.push('`');
    out
}