flowquery 1.0.46 → 1.0.47

package/flowquery-py/src/parsing/parser.py

@@ -1,1384 +0,0 @@
-"""Main parser for FlowQuery statements."""
-
-import sys
-from typing import Dict, Iterator, List, Optional, Tuple, cast
-
-from ..graph.hops import Hops
-from ..graph.node import Node
-from ..graph.node_reference import NodeReference
-from ..graph.pattern import Pattern
-from ..graph.pattern_expression import PatternExpression
-from ..graph.relationship import Relationship
-from ..graph.relationship_reference import RelationshipReference
-from ..tokenization.token import Token
-from ..utils.object_utils import ObjectUtils
-from .alias import Alias
-from .alias_option import AliasOption
-from .ast_node import ASTNode
-from .base_parser import BaseParser
-from .components.from_ import From
-from .components.headers import Headers
-from .components.null import Null
-from .components.post import Post
-from .data_structures.associative_array import AssociativeArray
-from .data_structures.json_array import JSONArray
-from .data_structures.key_value_pair import KeyValuePair
-from .data_structures.lookup import Lookup
-from .data_structures.range_lookup import RangeLookup
-from .expressions.expression import Expression
-from .expressions.f_string import FString
-from .expressions.identifier import Identifier
-from .expressions.operator import (
-    Contains,
-    EndsWith,
-    In,
-    Is,
-    IsNot,
-    Not,
-    NotContains,
-    NotEndsWith,
-    NotIn,
-    NotStartsWith,
-    StartsWith,
-)
-from .expressions.reference import Reference
-from .expressions.string import String
-from .functions.aggregate_function import AggregateFunction
-from .functions.async_function import AsyncFunction
-from .functions.function import Function
-from .functions.function_factory import FunctionFactory
-from .functions.predicate_function import PredicateFunction
-from .logic.case import Case
-from .logic.else_ import Else
-from .logic.then import Then
-from .logic.when import When
-from .operations.aggregated_return import AggregatedReturn
-from .operations.aggregated_with import AggregatedWith
-from .operations.call import Call
-from .operations.create_node import CreateNode
-from .operations.create_relationship import CreateRelationship
-from .operations.delete_node import DeleteNode
-from .operations.delete_relationship import DeleteRelationship
-from .operations.limit import Limit
-from .operations.load import Load
-from .operations.match import Match
-from .operations.operation import Operation
-from .operations.order_by import OrderBy, SortField
-from .operations.return_op import Return
-from .operations.union import Union
-from .operations.union_all import UnionAll
-from .operations.unwind import Unwind
-from .operations.where import Where
-from .operations.with_op import With
-from .parser_state import ParserState
-
-
-class Parser(BaseParser):
-    """Main parser for FlowQuery statements.
-
-    Parses FlowQuery declarative query language statements into an Abstract Syntax Tree (AST).
-    Supports operations like WITH, UNWIND, RETURN, LOAD, WHERE, and LIMIT, along with
-    expressions, functions, data structures, and logical constructs.
-
-    Example:
-        parser = Parser()
-        ast = parser.parse("unwind [1, 2, 3, 4, 5] as num return num")
-    """
-
-    def __init__(self, tokens: Optional[List[Token]] = None):
-        super().__init__(tokens)
-        self._state = ParserState()
-
-    def parse(self, statement: str) -> ASTNode:
-        """Parses a FlowQuery statement into an Abstract Syntax Tree.
-
-        Args:
-            statement: The FlowQuery statement to parse
-
-        Returns:
-            The root AST node containing the parsed structure
-
-        Raises:
-            ValueError: If the statement is malformed or contains syntax errors
-        """
-        self.tokenize(statement)
-        return self._parse_tokenized()
-
-    def _parse_tokenized(self, is_sub_query: bool = False) -> ASTNode:
-        root = ASTNode()
-        previous: Optional[Operation] = None
-        operation: Optional[Operation] = None
-
-        while not self.token.is_eof():
-            if root.child_count() > 0:
-                self._expect_and_skip_whitespace_and_comments()
-            else:
-                self._skip_whitespace_and_comments()
-
-            # UNION separates two query pipelines — break and handle after the loop
-            if self.token.is_union():
-                break
-
-            if self.token.is_eof():
-                break
-
-            operation = self._parse_operation()
-            if operation is None and not is_sub_query:
-                raise ValueError("Expected one of WITH, UNWIND, RETURN, LOAD, OR CALL")
-            elif operation is None and is_sub_query:
-                return root
-
-            if self._state.returns > 1:
-                raise ValueError("Only one RETURN statement is allowed")
-
-            if isinstance(previous, Call) and not previous.has_yield:
-                raise ValueError(
-                    "CALL operations must have a YIELD clause unless they are the last operation"
-                )
-
-            if previous is not None:
-                previous.add_sibling(operation)
-            else:
-                root.add_child(operation)
-
-            where = self._parse_where()
-            if where is not None:
-                if isinstance(operation, Return):
-                    operation.where = where
-                else:
-                    operation.add_sibling(where)
-                    operation = where
-
-            order_by = self._parse_order_by()
-            if order_by is not None:
-                if isinstance(operation, Return):
-                    operation.order_by = order_by
-                else:
-                    operation.add_sibling(order_by)
-                    operation = order_by
-
-            limit = self._parse_limit()
-            if limit is not None:
-                if isinstance(operation, Return):
-                    operation.limit = limit
-                else:
-                    operation.add_sibling(limit)
-                    operation = limit
-
-            previous = operation
-
-        # Handle UNION: wrap left and right pipelines into a Union node
-        if not self.token.is_eof() and self.token.is_union():
-            if not isinstance(operation, (Return, Call)):
-                raise ValueError(
-                    "Each side of UNION must end with a RETURN or CALL statement"
-                )
-            union = self._parse_union()
-            assert union is not None
-            union.left = root.first_child()  # type: ignore[assignment]
-            # Save and reset parser state for right-side scope
-            state: ParserState = self._state
-            self._state = ParserState()
-            right_root = self._parse_tokenized(is_sub_query)
-            union.right = right_root.first_child()  # type: ignore[assignment]
-            # Restore parser state
-            self._state = state
-            new_root = ASTNode()
-            new_root.add_child(union)
-            return new_root
-
-        if not isinstance(operation, (Return, Call, CreateNode, CreateRelationship, DeleteNode, DeleteRelationship)):
-            raise ValueError("Last statement must be a RETURN, WHERE, CALL, CREATE, or DELETE statement")
-
-        return root
-
-    def _parse_operation(self) -> Optional[Operation]:
-        return (
-            self._parse_with() or
-            self._parse_unwind() or
-            self._parse_return() or
-            self._parse_load() or
-            self._parse_call() or
-            self._parse_match() or
-            self._parse_create() or
-            self._parse_delete()
-        )
-
-    def _parse_with(self) -> Optional[With]:
-        if not self.token.is_with():
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        distinct = False
-        if self.token.is_distinct():
-            distinct = True
-            self.set_next_token()
-            self._expect_and_skip_whitespace_and_comments()
-        expressions = self._parse_expressions(AliasOption.REQUIRED)
-        if len(expressions) == 0:
-            raise ValueError("Expected expression")
-        if distinct or any(expr.has_reducers() for expr in expressions):
-            return AggregatedWith(expressions)  # type: ignore[return-value]
-        return With(expressions)
-
-    def _parse_unwind(self) -> Optional[Unwind]:
-        if not self.token.is_unwind():
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        expression = self._parse_expression()
-        if expression is None:
-            raise ValueError("Expected expression")
-        if not ObjectUtils.is_instance_of_any(
-            expression.first_child(),
-            [JSONArray, Function, Reference, Lookup, RangeLookup]
-        ):
-            raise ValueError("Expected array, function, reference, or lookup.")
-        self._expect_and_skip_whitespace_and_comments()
-        alias = self._parse_alias()
-        if alias is not None:
-            expression.set_alias(alias.get_alias())
-        else:
-            raise ValueError("Expected alias")
-        unwind = Unwind(expression)
-        self._state.variables[alias.get_alias()] = unwind
-        return unwind
-
-    def _parse_return(self) -> Optional[Return]:
-        if not self.token.is_return():
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        distinct = False
-        if self.token.is_distinct():
-            distinct = True
-            self.set_next_token()
-            self._expect_and_skip_whitespace_and_comments()
-        expressions = self._parse_expressions(AliasOption.OPTIONAL)
-        if len(expressions) == 0:
-            raise ValueError("Expected expression")
-        if distinct or any(expr.has_reducers() for expr in expressions):
-            return AggregatedReturn(expressions)
-        self._state.increment_returns()
-        return Return(expressions)
-
-    def _parse_where(self) -> Optional[Where]:
-        self._skip_whitespace_and_comments()
-        if not self.token.is_where():
-            return None
-        self._expect_previous_token_to_be_whitespace_or_comment()
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        expression = self._parse_expression()
-        if expression is None:
-            raise ValueError("Expected expression")
-        if ObjectUtils.is_instance_of_any(
-            expression.first_child(),
-            [JSONArray, AssociativeArray]
-        ):
-            raise ValueError("Expected an expression which can be evaluated to a boolean")
-        return Where(expression)
-
-    def _parse_load(self) -> Optional[Load]:
-        if not self.token.is_load():
-            return None
-        load = Load()
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not (self.token.is_json() or self.token.is_csv() or self.token.is_text()):
-            raise ValueError("Expected JSON, CSV, or TEXT")
-        load.add_child(self.token.node)
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_from():
-            raise ValueError("Expected FROM")
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        from_node = From()
-        load.add_child(from_node)
-
-        # Check if source is async function
-        async_func = self._parse_async_function()
-        if async_func is not None:
-            from_node.add_child(async_func)
-        else:
-            expression = self._parse_expression()
-            if expression is None:
-                raise ValueError("Expected expression or async function")
-            from_node.add_child(expression)
-
-        self._expect_and_skip_whitespace_and_comments()
-        if self.token.is_headers():
-            headers = Headers()
-            self.set_next_token()
-            self._expect_and_skip_whitespace_and_comments()
-            header = self._parse_expression()
-            if header is None:
-                raise ValueError("Expected expression")
-            headers.add_child(header)
-            load.add_child(headers)
-            self._expect_and_skip_whitespace_and_comments()
-
-        if self.token.is_post():
-            post = Post()
-            self.set_next_token()
-            self._expect_and_skip_whitespace_and_comments()
-            payload = self._parse_expression()
-            if payload is None:
-                raise ValueError("Expected expression")
-            post.add_child(payload)
-            load.add_child(post)
-            self._expect_and_skip_whitespace_and_comments()
-
-        alias = self._parse_alias()
-        if alias is not None:
-            load.add_child(alias)
-            self._state.variables[alias.get_alias()] = load
-        else:
-            raise ValueError("Expected alias")
-        return load
-
-    def _parse_call(self) -> Optional[Call]:
-        if not self.token.is_call():
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        async_function = self._parse_async_function()
-        if async_function is None:
-            raise ValueError("Expected async function")
-        call = Call()
-        call.function = async_function
-        self._skip_whitespace_and_comments()
-        if self.token.is_yield():
-            self._expect_previous_token_to_be_whitespace_or_comment()
-            self.set_next_token()
-            self._expect_and_skip_whitespace_and_comments()
-            expressions = self._parse_expressions(AliasOption.OPTIONAL)
-            if len(expressions) == 0:
-                raise ValueError("Expected at least one expression")
-            call.yielded = expressions  # type: ignore[assignment]
-        return call
-
-    def _parse_match(self) -> Optional[Match]:
-        optional = False
-        if self.token.is_optional():
-            optional = True
-            self.set_next_token()
-            self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_match():
-            if optional:
-                raise ValueError("Expected MATCH after OPTIONAL")
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        patterns = list(self._parse_patterns())
-        if len(patterns) == 0:
-            raise ValueError("Expected graph pattern")
-        return Match(patterns, optional)
-
-    def _parse_create(self) -> Optional[Operation]:
-        """Parse CREATE VIRTUAL statement for nodes and relationships."""
-        if not self.token.is_create():
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_virtual():
-            raise ValueError("Expected VIRTUAL")
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-
-        node = self._parse_node()
-        if node is None:
-            raise ValueError("Expected node definition")
-
-        relationship: Optional[Relationship] = None
-        if self.token.is_subtract() and self.peek() and self.peek().is_opening_bracket():
-            self.set_next_token()  # skip -
-            self.set_next_token()  # skip [
-            if not self.token.is_colon():
-                raise ValueError("Expected ':' for relationship type")
-            self.set_next_token()
-            if not self.token.is_identifier_or_keyword():
-                raise ValueError("Expected relationship type identifier")
-            rel_type = self.token.value or ""
-            self.set_next_token()
-            if not self.token.is_closing_bracket():
-                raise ValueError("Expected closing bracket for relationship definition")
-            self.set_next_token()
-            if not self.token.is_subtract():
-                raise ValueError("Expected '-' for relationship definition")
-            self.set_next_token()
-            # Skip optional direction indicator '>'
-            if self.token.is_greater_than():
-                self.set_next_token()
-            target = self._parse_node()
-            if target is None:
-                raise ValueError("Expected target node definition")
-            relationship = Relationship()
-            relationship.type = rel_type
-            relationship.source = node
-            relationship.target = target
-
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_as():
-            raise ValueError("Expected AS")
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-
-        query = self._parse_sub_query()
-        if query is None:
-            raise ValueError("Expected sub-query")
-
-        if relationship is not None:
-            return CreateRelationship(relationship, query)
-        else:
-            return CreateNode(node, query)
-
-    def _parse_delete(self) -> Optional[Operation]:
-        """Parse DELETE VIRTUAL statement for nodes and relationships."""
-        if not self.token.is_delete():
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_virtual():
-            raise ValueError("Expected VIRTUAL")
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-
-        node = self._parse_node()
-        if node is None:
-            raise ValueError("Expected node definition")
-
-        relationship: Optional[Relationship] = None
-        if self.token.is_subtract() and self.peek() and self.peek().is_opening_bracket():
-            self.set_next_token()  # skip -
-            self.set_next_token()  # skip [
-            if not self.token.is_colon():
-                raise ValueError("Expected ':' for relationship type")
-            self.set_next_token()
-            if not self.token.is_identifier_or_keyword():
-                raise ValueError("Expected relationship type identifier")
-            rel_type = self.token.value or ""
-            self.set_next_token()
-            if not self.token.is_closing_bracket():
-                raise ValueError("Expected closing bracket for relationship definition")
-            self.set_next_token()
-            if not self.token.is_subtract():
-                raise ValueError("Expected '-' for relationship definition")
-            self.set_next_token()
-            # Skip optional direction indicator '>'
-            if self.token.is_greater_than():
-                self.set_next_token()
-            target = self._parse_node()
-            if target is None:
-                raise ValueError("Expected target node definition")
-            relationship = Relationship()
-            relationship.type = rel_type
-            relationship.source = node
-            relationship.target = target
-
-        if relationship is not None:
-            return DeleteRelationship(relationship)
-        else:
-            return DeleteNode(node)
-
-    def _parse_union(self) -> Optional[Union]:
-        """Parse a UNION or UNION ALL keyword."""
-        if not self.token.is_union():
-            return None
-        self.set_next_token()
-        self._skip_whitespace_and_comments()
-        if self.token.is_all():
-            union: Union = UnionAll()
-            self.set_next_token()
-        else:
-            union = Union()
-        return union
-
-    def _parse_sub_query(self) -> Optional[ASTNode]:
-        """Parse a sub-query enclosed in braces."""
-        if not self.token.is_opening_brace():
-            return None
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        query = self._parse_tokenized(is_sub_query=True)
-        self._skip_whitespace_and_comments()
-        if not self.token.is_closing_brace():
-            raise ValueError("Expected closing brace for sub-query")
-        self.set_next_token()
-        return query
-
-    def _parse_patterns(self) -> Iterator[Pattern]:
-        while True:
-            identifier: Optional[str] = None
-            if self.token.is_identifier():
-                identifier = self.token.value
-                self.set_next_token()
-                self._skip_whitespace_and_comments()
-                if not self.token.is_equals():
-                    raise ValueError("Expected '=' for pattern assignment")
-                self.set_next_token()
-                self._skip_whitespace_and_comments()
-            pattern = self._parse_pattern()
-            if pattern is not None:
-                if identifier is not None:
-                    pattern.identifier = identifier
-                    self._state.variables[identifier] = pattern
-                yield pattern
-            else:
-                break
-            self._skip_whitespace_and_comments()
-            if not self.token.is_comma():
-                break
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-
-    def _parse_pattern(self) -> Optional[Pattern]:
-        if not self.token.is_left_parenthesis():
-            return None
-        pattern = Pattern()
-        node = self._parse_node()
-        if node is None:
-            raise ValueError("Expected node definition")
-        pattern.add_element(node)
-        while True:
-            relationship = self._parse_relationship()
-            if relationship is None:
-                break
-            pattern.add_element(relationship)
-            node = self._parse_node()
-            if node is None:
-                raise ValueError("Expected target node definition")
-            pattern.add_element(node)
-        return pattern
-
-    def _parse_pattern_expression(self) -> Optional[PatternExpression]:
-        """Parse a pattern expression for WHERE clauses.
-
-        PatternExpression is used to test if a graph pattern exists.
-        It must start with a NodeReference (referencing an existing variable).
-        """
-        if not self.token.is_left_parenthesis():
-            return None
-        pattern = PatternExpression()
-        node = self._parse_node()
-        if node is None:
-            raise ValueError("Expected node definition")
-        pattern.add_element(node)
-        while True:
-            relationship = self._parse_relationship()
-            if relationship is None:
-                break
-            if relationship.hops and relationship.hops.multi():
-                raise ValueError("PatternExpression does not support variable-length relationships")
-            pattern.add_element(relationship)
-            node = self._parse_node()
-            if node is None:
-                raise ValueError("Expected target node definition")
-            pattern.add_element(node)
-        pattern.verify()
-        return pattern
-
-    def _parse_node(self) -> Optional[Node]:
-        if not self.token.is_left_parenthesis():
-            return None
-        self.set_next_token()
-        self._skip_whitespace_and_comments()
-        identifier: Optional[str] = None
-        if self.token.is_identifier_or_keyword():
-            identifier = self.token.value
-            self.set_next_token()
-        self._skip_whitespace_and_comments()
-        label: Optional[str] = None
-        peek = self.peek()
-        if not self.token.is_colon() and peek is not None and peek.is_identifier_or_keyword():
-            raise ValueError("Expected ':' for node label")
-        if self.token.is_colon() and (peek is None or not peek.is_identifier_or_keyword()):
-            raise ValueError("Expected node label identifier")
-        if self.token.is_colon() and peek is not None and peek.is_identifier_or_keyword():
-            self.set_next_token()
-            label = cast(str, self.token.value)  # Guaranteed by is_identifier check
-            self.set_next_token()
-        self._skip_whitespace_and_comments()
-        node = Node()
-        node.label = label
-        node.properties = dict(self._parse_properties())
-        if identifier is not None and identifier in self._state.variables:
-            reference = self._state.variables.get(identifier)
-            if reference is None or (
-                not isinstance(reference, Node)
-                and not isinstance(reference, Unwind)
-                and not isinstance(reference, Expression)
-            ):
-                raise ValueError(f"Undefined node reference: {identifier}")
-            node = NodeReference(node, reference)
-        elif identifier is not None:
-            node.identifier = identifier
-            self._state.variables[identifier] = node
-        if not self.token.is_right_parenthesis():
-            raise ValueError("Expected closing parenthesis for node definition")
-        self.set_next_token()
-        return node
-
-    def _parse_relationship(self) -> Optional[Relationship]:
-        direction = "right"
-        if self.token.is_less_than() and self.peek() is not None and self.peek().is_subtract():
-            direction = "left"
-            self.set_next_token()
-            self.set_next_token()
-        elif self.token.is_subtract():
-            self.set_next_token()
-        else:
-            return None
-        if not self.token.is_opening_bracket():
-            return None
-        self.set_next_token()
-        variable: Optional[str] = None
-        if self.token.is_identifier_or_keyword():
-            variable = self.token.value
-            self.set_next_token()
-        if not self.token.is_colon():
-            raise ValueError("Expected ':' for relationship type")
-        self.set_next_token()
-        if not self.token.is_identifier_or_keyword():
-            raise ValueError("Expected relationship type identifier")
-        rel_types: List[str] = [self.token.value or ""]
-        self.set_next_token()
-        while self.token.is_pipe():
-            self.set_next_token()
-            if self.token.is_colon():
-                self.set_next_token()
-            if not self.token.is_identifier_or_keyword():
-                raise ValueError("Expected relationship type identifier after '|'")
-            rel_types.append(self.token.value or "")
-            self.set_next_token()
-        hops = self._parse_relationship_hops()
-        properties: Dict[str, Expression] = dict(self._parse_properties())
-        if not self.token.is_closing_bracket():
-            raise ValueError("Expected closing bracket for relationship definition")
-        self.set_next_token()
-        if not self.token.is_subtract():
-            raise ValueError("Expected '-' for relationship definition")
-        self.set_next_token()
-        if self.token.is_greater_than():
-            self.set_next_token()
-        relationship = Relationship()
-        relationship.direction = direction
-        relationship.properties = properties
-        if variable is not None and variable in self._state.variables:
-            reference = self._state.variables.get(variable)
-            # Resolve through Expression -> Reference -> Relationship (e.g., after WITH)
-            first = reference.first_child() if isinstance(reference, Expression) else None
-            if isinstance(first, Reference):
-                inner = first.referred
-                if isinstance(inner, Relationship):
-                    reference = inner
-            if reference is None or not isinstance(reference, Relationship):
-                raise ValueError(f"Undefined relationship reference: {variable}")
-            relationship = RelationshipReference(relationship, reference)
-        elif variable is not None:
-            relationship.identifier = variable
-            self._state.variables[variable] = relationship
-        if hops is not None:
-            relationship.hops = hops
-        relationship.types = rel_types
-        return relationship
-
-    def _parse_properties(self) -> Iterator[Tuple[str, Expression]]:
-        parts: int = 0
-        while True:
-            self._skip_whitespace_and_comments()
-            if not self.token.is_opening_brace() and parts == 0:
-                return
-            elif not self.token.is_opening_brace() and parts > 0:
-                raise ValueError("Expected opening brace")
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-            if not self.token.is_identifier():
-                raise ValueError("Expected identifier")
-            key: str = self.token.value or ""
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-            if not self.token.is_colon():
-                raise ValueError("Expected colon")
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-            expression = self._parse_expression()
-            if expression is None:
-                raise ValueError("Expected expression")
-            self._skip_whitespace_and_comments()
-            if not self.token.is_closing_brace():
-                raise ValueError("Expected closing brace")
-            self.set_next_token()
-            yield (key, expression)
-            self._skip_whitespace_and_comments()
-            if not self.token.is_comma():
-                break
-            self.set_next_token()
-            parts += 1
-
-    def _parse_relationship_hops(self) -> Optional[Hops]:
-        if not self.token.is_multiply():
-            return None
-        hops = Hops()
-        self.set_next_token()
-        if self.token.is_number():
-            hops.min = int(self.token.value or "0")
-            self.set_next_token()
-            if self.token.is_dot():
-                self.set_next_token()
-                if not self.token.is_dot():
-                    raise ValueError("Expected '..' for relationship hops")
-                self.set_next_token()
-                if not self.token.is_number():
-                    hops.max = sys.maxsize
-                else:
-                    hops.max = int(self.token.value or "0")
-                    self.set_next_token()
-        else:
-            # Just * without numbers means unbounded
-            hops.min = 0
-            hops.max = sys.maxsize
-        return hops
-
-    def _parse_limit(self) -> Optional[Limit]:
-        self._skip_whitespace_and_comments()
-        if not self.token.is_limit():
-            return None
-        self._expect_previous_token_to_be_whitespace_or_comment()
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_number():
-            raise ValueError("Expected number")
-        limit = Limit(int(self.token.value or "0"))
-        self.set_next_token()
-        return limit
-
-    def _parse_order_by(self) -> Optional[OrderBy]:
-        self._skip_whitespace_and_comments()
-        if not self.token.is_order():
-            return None
-        self._expect_previous_token_to_be_whitespace_or_comment()
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_by():
-            raise ValueError("Expected BY after ORDER")
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        fields: list[SortField] = []
-        while True:
-            expression = self._parse_expression()
-            if expression is None:
-                raise ValueError("Expected expression in ORDER BY")
-            self._skip_whitespace_and_comments()
-            direction = "asc"
-            if self.token.is_asc():
-                direction = "asc"
-                self.set_next_token()
-                self._skip_whitespace_and_comments()
-            elif self.token.is_desc():
-                direction = "desc"
-                self.set_next_token()
-                self._skip_whitespace_and_comments()
-            fields.append(SortField(expression, direction))
-            if self.token.is_comma():
-                self.set_next_token()
-                self._skip_whitespace_and_comments()
-            else:
-                break
-        return OrderBy(fields)
-
-    def _parse_expressions(
-        self, alias_option: AliasOption = AliasOption.NOT_ALLOWED
-    ) -> List[Expression]:
-        """Parse a comma-separated list of expressions with deferred variable
-        registration.  Aliases set by earlier expressions in the same clause
-        won't shadow variables needed by later expressions
-        (e.g. ``RETURN a.x AS a, a.y AS b``)."""
-        parsed = list(self.__parse_expressions(alias_option))
-        for expression, variable_name in parsed:
-            if variable_name is not None:
-                self._state.variables[variable_name] = expression
-        return [expression for expression, _ in parsed]
-
-    def __parse_expressions(
-        self, alias_option: AliasOption
-    ) -> Iterator[Tuple[Expression, Optional[str]]]:
-        while True:
-            expression = self._parse_expression()
-            if expression is not None:
-                variable_name: Optional[str] = None
-                alias = self._parse_alias()
-                if isinstance(expression.first_child(), Reference) and alias is None:
-                    reference = expression.first_child()
-                    assert isinstance(reference, Reference)  # For type narrowing
-                    expression.set_alias(reference.identifier)
-                    variable_name = reference.identifier
-                elif (alias_option == AliasOption.REQUIRED and
-                      alias is None and
-                      not isinstance(expression.first_child(), Reference)):
-                    raise ValueError("Alias required")
-                elif alias_option == AliasOption.NOT_ALLOWED and alias is not None:
-                    raise ValueError("Alias not allowed")
-                elif alias_option in (AliasOption.OPTIONAL, AliasOption.REQUIRED) and alias is not None:
-                    expression.set_alias(alias.get_alias())
-                    variable_name = alias.get_alias()
-                yield expression, variable_name
-            else:
-                break
-            self._skip_whitespace_and_comments()
-            if not self.token.is_comma():
-                break
-            self.set_next_token()
-
-    def _parse_operand(self, expression: Expression) -> bool:
-        """Parse a single operand (without operators). Returns True if an operand was parsed."""
-        self._skip_whitespace_and_comments()
-        if self.token.is_identifier_or_keyword() and (self.peek() is None or not self.peek().is_left_parenthesis()):
-            identifier = self.token.value or ""
-            reference = Reference(identifier, self._state.variables.get(identifier))
-            self.set_next_token()
-            lookup = self._parse_lookup(reference)
-            expression.add_node(lookup)
-            return True
-        elif self.token.is_identifier_or_keyword() and self.peek() is not None and self.peek().is_left_parenthesis():
-            func = self._parse_predicate_function() or self._parse_function()
-            if func is not None:
-                lookup = self._parse_lookup(func)
-                expression.add_node(lookup)
-                return True
-        elif (
-            self.token.is_left_parenthesis()
-            and self._looks_like_node_pattern()
-        ):
-            # Possible graph pattern expression
-            pattern = self._parse_pattern_expression()
-            if pattern is not None:
-                expression.add_node(pattern)
-                return True
-        elif self.token.is_operand():
-            expression.add_node(self.token.node)
-            self.set_next_token()
-            return True
-        elif self.token.is_f_string():
-            f_string = self._parse_f_string()
-            if f_string is None:
-                raise ValueError("Expected f-string")
-            expression.add_node(f_string)
-            return True
-        elif self.token.is_left_parenthesis():
-            self.set_next_token()
-            sub = self._parse_expression()
-            if sub is None:
-                raise ValueError("Expected expression")
-            if not self.token.is_right_parenthesis():
-                raise ValueError("Expected right parenthesis")
-            self.set_next_token()
-            lookup = self._parse_lookup(sub)
-            expression.add_node(lookup)
-            return True
-        elif self.token.is_opening_brace() or self.token.is_opening_bracket():
-            json = self._parse_json()
-            if json is None:
-                raise ValueError("Expected JSON object")
-            lookup = self._parse_lookup(json)
-            expression.add_node(lookup)
-            return True
-        elif self.token.is_case():
-            case = self._parse_case()
-            if case is None:
-                raise ValueError("Expected CASE statement")
-            expression.add_node(case)
-            return True
-        elif self.token.is_not():
-            not_node = Not()
-            self.set_next_token()
-            # NOT should only bind to the next operand, not the entire expression
-            # Create a temporary expression to parse just one operand
-            temp_expr = Expression()
-            if not self._parse_operand(temp_expr):
-                raise ValueError("Expected expression after NOT")
-            temp_expr.finish()
-            not_node.add_child(temp_expr)
-            expression.add_node(not_node)
-            return True
-        return False
-
-    def _parse_expression(self) -> Optional[Expression]:
-        expression = Expression()
-        while True:
-            if not self._parse_operand(expression):
-                if expression.nodes_added():
-                    raise ValueError("Expected operand or left parenthesis")
-                else:
-                    break
-            self._skip_whitespace_and_comments()
-            if self.token.is_operator():
-                if self.token.is_is():
-                    expression.add_node(self._parse_is_operator())
-                else:
-                    expression.add_node(self.token.node)
-            elif self.token.is_in():
-                expression.add_node(self._parse_in_operator())
-            elif self.token.is_contains():
-                expression.add_node(self._parse_contains_operator())
-            elif self.token.is_starts():
-                expression.add_node(self._parse_starts_with_operator())
-            elif self.token.is_ends():
-                expression.add_node(self._parse_ends_with_operator())
-            elif self.token.is_not():
-                not_op = self._parse_not_operator()
-                if not_op is None:
-                    break
-                expression.add_node(not_op)
-            else:
-                break
-            self.set_next_token()
-
-        if expression.nodes_added():
-            expression.finish()
-            return expression
-        return None
-
-    def _looks_like_node_pattern(self) -> bool:
-        """Peek ahead from a left parenthesis to determine whether the
-        upcoming tokens form a graph-node pattern (e.g. (n:Label), (n),
-        (:Label), ()) rather than a parenthesised expression (e.g.
-        (variable.property), (a + b)).
-        """
-        saved_index = self._token_index
-        self.set_next_token()  # skip '('
-        self._skip_whitespace_and_comments()
-
-        if self.token.is_colon() or self.token.is_right_parenthesis():
-            self._token_index = saved_index
-            return True
-
-        if self.token.is_identifier_or_keyword():
-            self.set_next_token()  # skip identifier
-            self._skip_whitespace_and_comments()
-            result = (
-                self.token.is_colon()
-                or self.token.is_opening_brace()
-                or self.token.is_right_parenthesis()
-            )
-            self._token_index = saved_index
-            return result
-
-        self._token_index = saved_index
-        return False
-
-    def _parse_is_operator(self) -> ASTNode:
-        """Parse IS or IS NOT operator."""
-        # Current token is IS. Look ahead for NOT to produce IS NOT.
-        saved_index = self._token_index
-        self.set_next_token()
-        self._skip_whitespace_and_comments()
-        if self.token.is_not():
-            return IsNot()
-        # Not IS NOT — restore position to IS so the outer loop's set_next_token advances past it.
-        self._token_index = saved_index
-        return Is()
-
-    def _parse_in_operator(self) -> In:
-        """Parse IN operator."""
-        # Current token is IN. Advance past it so the outer loop's set_next_token moves correctly.
-        return In()
-
-    def _parse_contains_operator(self) -> Contains:
-        """Parse CONTAINS operator."""
-        return Contains()
-
-    def _parse_starts_with_operator(self) -> StartsWith:
-        """Parse STARTS WITH operator."""
-        # Current token is STARTS. Look ahead for WITH.
-        saved_index = self._token_index
-        self.set_next_token()
-        self._skip_whitespace_and_comments()
-        if self.token.is_with():
-            return StartsWith()
-        self._token_index = saved_index
-        raise ValueError("Expected WITH after STARTS")
-
-    def _parse_ends_with_operator(self) -> EndsWith:
-        """Parse ENDS WITH operator."""
-        # Current token is ENDS. Look ahead for WITH.
-        saved_index = self._token_index
-        self.set_next_token()
-        self._skip_whitespace_and_comments()
-        if self.token.is_with():
-            return EndsWith()
-        self._token_index = saved_index
-        raise ValueError("Expected WITH after ENDS")
-
-    def _parse_not_operator(self) -> NotIn | NotContains | NotStartsWith | NotEndsWith | None:
-        """Parse NOT IN, NOT CONTAINS, NOT STARTS WITH, or NOT ENDS WITH operator."""
-        saved_index = self._token_index
-        self.set_next_token()
-        self._skip_whitespace_and_comments()
-        if self.token.is_in():
-            return NotIn()
-        if self.token.is_contains():
-            return NotContains()
-        if self.token.is_starts():
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-            if self.token.is_with():
-                return NotStartsWith()
-            self._token_index = saved_index
-            return None
-        if self.token.is_ends():
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-            if self.token.is_with():
-                return NotEndsWith()
-            self._token_index = saved_index
-            return None
-        # Not a recognized NOT operator — restore position and let the outer loop break.
-        self._token_index = saved_index
-        return None
-
-    def _parse_lookup(self, node: ASTNode) -> ASTNode:
-        variable = node
-        lookup: Lookup | RangeLookup | None = None
-        while True:
-            if self.token.is_dot():
-                self.set_next_token()
-                if not self.token.is_identifier() and not self.token.is_keyword():
-                    raise ValueError("Expected identifier")
-                lookup = Lookup()
-                lookup.index = Identifier(self.token.value or "")
-                lookup.variable = variable
-                self.set_next_token()
-            elif self.token.is_opening_bracket():
-                self.set_next_token()
-                self._skip_whitespace_and_comments()
-                index = self._parse_expression()
-                to = None
-                self._skip_whitespace_and_comments()
-                if self.token.is_colon():
-                    self.set_next_token()
-                    self._skip_whitespace_and_comments()
-                    lookup = RangeLookup()
-                    to = self._parse_expression()
-                else:
-                    if index is None:
-                        raise ValueError("Expected expression")
-                    lookup = Lookup()
-                self._skip_whitespace_and_comments()
-                if not self.token.is_closing_bracket():
-                    raise ValueError("Expected closing bracket")
-                self.set_next_token()
-                if isinstance(lookup, RangeLookup):
-                    lookup.from_ = index or Null()
-                    lookup.to = to or Null()
-                elif isinstance(lookup, Lookup) and index is not None:
-                    lookup.index = index
-                lookup.variable = variable
-            else:
-                break
-            variable = lookup or variable
-        return variable
-
-    def _parse_case(self) -> Optional[Case]:
-        if not self.token.is_case():
-            return None
-        self.set_next_token()
-        case = Case()
-        parts = 0
-        self._expect_and_skip_whitespace_and_comments()
-        while True:
-            when = self._parse_when()
-            if when is None and parts == 0:
-                raise ValueError("Expected WHEN")
-            elif when is None and parts > 0:
-                break
-            elif when is not None:
-                case.add_child(when)
-            self._expect_and_skip_whitespace_and_comments()
-            then = self._parse_then()
-            if then is None:
-                raise ValueError("Expected THEN")
-            else:
-                case.add_child(then)
-            self._expect_and_skip_whitespace_and_comments()
-            parts += 1
-        else_ = self._parse_else()
-        if else_ is None:
-            raise ValueError("Expected ELSE")
-        else:
-            case.add_child(else_)
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_end():
-            raise ValueError("Expected END")
-        self.set_next_token()
-        return case
-
-    def _parse_when(self) -> Optional[When]:
-        if not self.token.is_when():
-            return None
-        self.set_next_token()
-        when = When()
-        self._expect_and_skip_whitespace_and_comments()
-        expression = self._parse_expression()
-        if expression is None:
-            raise ValueError("Expected expression")
-        when.add_child(expression)
-        return when
-
-    def _parse_then(self) -> Optional[Then]:
-        if not self.token.is_then():
-            return None
-        self.set_next_token()
-        then = Then()
-        self._expect_and_skip_whitespace_and_comments()
-        expression = self._parse_expression()
-        if expression is None:
-            raise ValueError("Expected expression")
-        then.add_child(expression)
-        return then
-
-    def _parse_else(self) -> Optional[Else]:
-        if not self.token.is_else():
-            return None
-        self.set_next_token()
-        else_ = Else()
-        self._expect_and_skip_whitespace_and_comments()
-        expression = self._parse_expression()
-        if expression is None:
-            raise ValueError("Expected expression")
-        else_.add_child(expression)
-        return else_
-
-    def _parse_alias(self) -> Optional[Alias]:
-        self._skip_whitespace_and_comments()
-        if not self.token.is_as():
-            return None
-        self._expect_previous_token_to_be_whitespace_or_comment()
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_identifier_or_keyword():
-            raise ValueError("Expected identifier")
-        alias = Alias(self.token.value or "")
-        self.set_next_token()
-        return alias
-
-    def _parse_predicate_function(self) -> Optional[PredicateFunction]:
-        """Parse a predicate function like sum(n in [...] | n where condition)."""
-        # Lookahead: identifier ( identifier in
-        if not self.ahead([
-            Token.IDENTIFIER(""),
-            Token.LEFT_PARENTHESIS(),
-            Token.IDENTIFIER(""),
-            Token.IN(),
-        ]):
-            return None
-        if self.token.value is None:
-            raise ValueError("Expected identifier")
-        func = FunctionFactory.create_predicate(self.token.value)
-        self.set_next_token()
-        if not self.token.is_left_parenthesis():
-            raise ValueError("Expected left parenthesis")
-        self.set_next_token()
-        self._skip_whitespace_and_comments()
-        if not self.token.is_identifier():
-            raise ValueError("Expected identifier")
-        reference = Reference(self.token.value)
-        self._state.variables[reference.identifier] = reference
-        func.add_child(reference)
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        if not self.token.is_in():
-            raise ValueError("Expected IN")
-        self.set_next_token()
-        self._expect_and_skip_whitespace_and_comments()
-        expression = self._parse_expression()
-        if expression is None:
-            raise ValueError("Expected expression")
-        if not ObjectUtils.is_instance_of_any(expression.first_child(), [
-            JSONArray,
-            Reference,
-            Lookup,
-            Function,
-        ]):
-            raise ValueError("Expected array or reference")
-        func.add_child(expression)
-        self._skip_whitespace_and_comments()
-        if not self.token.is_pipe():
-            raise ValueError("Expected pipe")
-        self.set_next_token()
-        return_expr = self._parse_expression()
-        if return_expr is None:
-            raise ValueError("Expected expression")
-        func.add_child(return_expr)
-        where = self._parse_where()
-        if where is not None:
-            func.add_child(where)
-        self._skip_whitespace_and_comments()
-        if not self.token.is_right_parenthesis():
-            raise ValueError("Expected right parenthesis")
-        self.set_next_token()
-        del self._state.variables[reference.identifier]
-        return func
-
-    def _parse_function(self) -> Optional[Function]:
-        if not self.token.is_identifier():
-            return None
-        name = self.token.value or ""
-        if not self.peek() or not self.peek().is_left_parenthesis():
-            return None
-
-        try:
-            func = FunctionFactory.create(name)
-        except ValueError:
-            raise ValueError(f"Unknown function: {name}")
-
-        # Check for nested aggregate functions
-        if isinstance(func, AggregateFunction) and self._state.context.contains_type(AggregateFunction):
-            raise ValueError("Aggregate functions cannot be nested")
-
-        self._state.context.push(func)
-        self.set_next_token()  # skip function name
-        self.set_next_token()  # skip left parenthesis
-        self._skip_whitespace_and_comments()
-
-        # Check for DISTINCT keyword
-        if self.token.is_distinct():
-            func.distinct = True
-            self.set_next_token()
-            self._expect_and_skip_whitespace_and_comments()
-
-        params = list(self._parse_function_parameters())
-        func.parameters = params
-
-        if not self.token.is_right_parenthesis():
-            raise ValueError("Expected right parenthesis")
-        self.set_next_token()
-        self._state.context.pop()
-        return func
-
-    def _parse_async_function(self) -> Optional[AsyncFunction]:
-        if not self.token.is_identifier():
-            return None
-        name = self.token.value or ""
-        if not FunctionFactory.is_async_provider(name):
-            return None
-        self.set_next_token()
-        if not self.token.is_left_parenthesis():
-            raise ValueError("Expected left parenthesis")
-        self.set_next_token()
-
-        func = FunctionFactory.create_async(name)
-        params = list(self._parse_function_parameters())
-        func.parameters = params
-
-        if not self.token.is_right_parenthesis():
-            raise ValueError("Expected right parenthesis")
-        self.set_next_token()
-        return func
-
-    def _parse_function_parameters(self) -> Iterator[ASTNode]:
-        while True:
-            self._skip_whitespace_and_comments()
-            if self.token.is_right_parenthesis():
-                break
-            expr = self._parse_expression()
-            if expr is not None:
-                yield expr
-            self._skip_whitespace_and_comments()
-            if not self.token.is_comma():
-                break
-            self.set_next_token()
-
-    def _parse_json(self) -> Optional[ASTNode]:
-        if self.token.is_opening_brace():
-            return self._parse_associative_array()
-        elif self.token.is_opening_bracket():
-            return self._parse_json_array()
-        return None
-
-    def _parse_associative_array(self) -> AssociativeArray:
-        if not self.token.is_opening_brace():
-            raise ValueError("Expected opening brace")
-        self.set_next_token()
-        array = AssociativeArray()
-        while True:
-            self._skip_whitespace_and_comments()
-            if self.token.is_closing_brace():
-                break
-            if not self.token.is_identifier() and not self.token.is_string() and not self.token.is_keyword():
-                raise ValueError("Expected key identifier or string")
-            key = self.token.value or ""
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-            if not self.token.is_colon():
-                raise ValueError("Expected colon")
-            self.set_next_token()
-            self._skip_whitespace_and_comments()
-            value = self._parse_expression()
-            if value is None:
-                raise ValueError("Expected value")
-            array.add_key_value(KeyValuePair(key, value))
-            self._skip_whitespace_and_comments()
-            if not self.token.is_comma():
-                break
-            self.set_next_token()
-        if not self.token.is_closing_brace():
-            raise ValueError("Expected closing brace")
-        self.set_next_token()
-        return array
-
-    def _parse_json_array(self) -> JSONArray:
-        if not self.token.is_opening_bracket():
-            raise ValueError("Expected opening bracket")
-        self.set_next_token()
-        array = JSONArray()
-        while True:
-            self._skip_whitespace_and_comments()
-            if self.token.is_closing_bracket():
-                break
-            value = self._parse_expression()
-            if value is None:
-                break
-            array.add_value(value)
-            self._skip_whitespace_and_comments()
-            if not self.token.is_comma():
-                break
-            self.set_next_token()
-        if not self.token.is_closing_bracket():
-            raise ValueError("Expected closing bracket")
-        self.set_next_token()
-        return array
-
-    def _parse_f_string(self) -> Optional[FString]:
-        if not self.token.is_f_string():
-            return None
-        f_string = FString()
-        while self.token.is_f_string() or self.token.is_opening_brace():
-            if self.token.is_f_string():
-                f_string.add_child(String(self.token.value or ""))
-                self.set_next_token()
-            elif self.token.is_opening_brace():
-                self.set_next_token()
-                expr = self._parse_expression()
-                if expr is not None:
-                    f_string.add_child(expr)
-                if self.token.is_closing_brace():
-                    self.set_next_token()
-        return f_string
-
-    def _skip_whitespace_and_comments(self) -> bool:
-        skipped: bool = self.previous_token.is_whitespace_or_comment() if self.previous_token else False
-        while self.token.is_whitespace_or_comment():
-            self.set_next_token()
-            skipped = True
-        return skipped
-
-    def _expect_and_skip_whitespace_and_comments(self) -> None:
-        skipped = self._skip_whitespace_and_comments()
-        if not skipped:
-            raise ValueError("Expected whitespace")
-
-    def _expect_previous_token_to_be_whitespace_or_comment(self) -> None:
-        if not self.previous_token.is_whitespace_or_comment():
-            raise ValueError("Expected previous token to be whitespace or comment")