hprof-analyzer 0.2.0

//! OQL parser for the supported subset: a logos-derived lexer feeding a chumsky
//! combinator parser, with ariadne caret diagnostics for error rendering.
//!
//! Public entry points:
//!   - [`parse`] — production parse returning a compact single-line
//!     [`QueryError`] (`unexpected <found> at <line>:<col>`) for programmatic
//!     callers and tests.
//!   - [`parse_or_report`] — same parse but on failure returns a rendered
//!     ariadne diagnostic (caret + red underline) for CLI/REPL display.

use ariadne::{Color, Label, Report, ReportKind, Source};
use chumsky::input::{Stream, ValueInput};
use chumsky::prelude::*;
use logos::Logos;

use crate::query::QueryError;
use crate::query::ast::{
    AggFunc, ArithOp, Attr, ClassSpec, CompareOp, Expr, FromSource, OrderBy, PathOperand,
    Predicate, Query, RefRole, SelectItem, SortDir, UnaryOp, Value,
};

/// OQL token kinds, lexed directly by logos.
///   - identifiers may contain `.`, `$`, and a trailing/embedded `*` glob
///   - `@attr` stores the name without the leading `@`
///   - strings are double-quoted, stored without quotes
///   - a bare `*` (not part of an ident) is `Star`
///   - arithmetic operators `+`, `-`, `/`, `*` are dedicated tokens; unary
///     minus is handled at the grammar level (no leading `-` in number literals)
///
/// Derives `Debug, Clone, PartialEq` — chumsky and the tests rely on them.
#[derive(Logos, Debug, Clone, PartialEq)]
#[logos(skip r"[ \t\r\n]+")]
pub enum Token {
    #[token("(")]
    LParen,
    #[token(")")]
    RParen,
    #[token(",")]
    Comma,
    #[token("[")]
    LBracket,
    #[token("]")]
    RBracket,
    #[token(":")]
    Colon,
    #[token("=")]
    Eq,
    #[token("!=")]
    Ne,
    #[token("<=")]
    Le,
    #[token("<")]
    Lt,
    #[token(">=")]
    Ge,
    #[token(">")]
    Gt,
    #[token("*")]
    Star,
    #[token("+")]
    Plus,
    #[token("-")]
    Minus,
    #[token("/")]
    Divide,

    // @attribute — capture the name after '@' (must be non-empty).
    #[regex(r"@[A-Za-z_][A-Za-z0-9_.$]*", |lex| lex.slice()[1..].to_string())]
    At(String),

    // double-quoted string — capture inner text (no escapes).
    #[regex(r#""[^"]*""#, |lex| { let s = lex.slice(); s[1..s.len()-1].to_string() })]
    Str(String),

    // Numeric + char literals. All int forms collapse to Int(i64); all float
    // forms to Float(f64) (our Value has no int/long/float/double/char split).
    // Order: float before int so "1.5" isn't split. Char and all int forms all
    // attach to Int. No leading '-': unary minus is a grammar operator.
    //
    // Float: `[digits].[digits]`, `[digits].`, dotless-with-suffix `[digits][fFdD]`,
    // and exponent forms; optional trailing f/F/d/D stripped before parse.
    // priority=4 beats Ident (default 2) so dotless 5F/5D lex as Float, not Ident
    #[regex(
        r"[0-9]+\.[0-9]*([eE][+-]?[0-9]+)?[fFdD]?|[0-9]+([eE][+-]?[0-9]+)[fFdD]?|[0-9]+[fFdD]",
        |lex| {
            let s = lex.slice();
            let core = s.trim_end_matches(['f', 'F', 'd', 'D']);
            core.parse::<f64>().ok()
        },
        priority = 4
    )]
    Float(f64),
    // Char: exactly one char between single quotes, no escapes (MAT CHARACTER_LITERAL).
    #[regex(r"'[^'\\\n\r]'", |lex| {
        let s = lex.slice();
        s[1..s.len() - 1].chars().next().map(|c| c as i64)
    })]
    // Hex: 0x… with optional L suffix. Parsed as u64 then reinterpreted as i64
    // (bit-preserving) so high-bit heap addresses (> i64::MAX) round-trip.
    #[regex(r"0[xX][0-9a-fA-F]+[lL]?", |lex| {
        let s = lex.slice().trim_end_matches(['l', 'L']);
        u64::from_str_radix(&s[2..], 16).ok().map(|v| v as i64)
    }, priority = 3)]
    // Octal: leading 0 followed by 1+ octal digits, optional L. (Lone `0` and
    // `08`/`09` fall through to the decimal arm — lenient MAT divergence.)
    // leading 0 is a valid octal digit; from_str_radix(_, 8) handles the full slice.
    // Parsed as u64 then bit-reinterpreted as i64 (see hex arm).
    #[regex(r"0[0-7]+[lL]?", |lex| {
        let s = lex.slice().trim_end_matches(['l', 'L']);
        u64::from_str_radix(s, 8).ok().map(|v| v as i64)
    }, priority = 3)]
    // Decimal int/long: digits with optional L. Also catches lone `0`, `08`, `09`.
    // Parsed as u64 then bit-reinterpreted as i64 (see hex arm).
    #[regex(r"[0-9]+[lL]?", |lex| {
        let s = lex.slice().trim_end_matches(['l', 'L']);
        s.parse::<u64>().ok().map(|v| v as i64)
    })]
    Int(i64),

    // identifier / keyword / dotted class or field name, optional embedded '*'
    // glob, optional trailing '[]' pairs so array classes (e.g. `char[]`,
    // `java.lang.String[]`) are nameable in the FROM clause.
    #[regex(r"[A-Za-z_][A-Za-z0-9_.$*]*(\[\])*", |lex| lex.slice().to_string())]
    Ident(String),
}

/// Return a human-readable representation of a token for use in error messages.
/// Punctuation tokens are shown as the literal character(s) (e.g. `'['`);
/// value-carrying tokens show their payload.
fn token_display(t: &Token) -> String {
    match t {
        Token::LParen => "'('".into(),
        Token::RParen => "')'".into(),
        Token::Comma => "','".into(),
        Token::LBracket => "'['".into(),
        Token::RBracket => "']'".into(),
        Token::Colon => "':'".into(),
        Token::Eq => "'='".into(),
        Token::Ne => "'!='".into(),
        Token::Le => "'<='".into(),
        Token::Lt => "'<'".into(),
        Token::Ge => "'>='".into(),
        Token::Gt => "'>'".into(),
        Token::Star => "'*'".into(),
        Token::Plus => "'+'".into(),
        Token::Minus => "'-'".into(),
        Token::Divide => "'/'".into(),
        Token::At(s) => format!("'@{s}'"),
        Token::Str(s) => format!("\"{s}\""),
        Token::Float(f) => format!("{f}"),
        Token::Int(i) => format!("{i}"),
        Token::Ident(s) => format!("'{s}'"),
    }
}

/// Tokenize with byte-span tracking, producing the `(Token, SimpleSpan)` stream
/// consumed by the chumsky parser. On an unrecognized byte the error carries the
/// offending offset and slice.
pub fn tokenize_spanned(src: &str) -> Result<Vec<(Token, SimpleSpan)>, String> {
    let mut out = Vec::new();
    let mut lex = Token::lexer(src);
    while let Some(res) = lex.next() {
        let span = lex.span();
        match res {
            Ok(tok) => out.push((tok, (span.start..span.end).into())),
            Err(()) => {
                let slice = &src[span.clone()];
                if slice.starts_with('\'') {
                    // logos stops at the first byte that breaks the char-literal
                    // rule, so `slice` is just the opening `'` plus one char (e.g.
                    // "'f" for 'foo'). Recover the full single-quoted run from the
                    // source to tell an attempted string (SQL habit) from a genuine
                    // bad char literal. OQL strings use double quotes.
                    let rest = &src[span.start + 1..];
                    if let Some(close) = rest.find('\'') {
                        let inner = &rest[..close];
                        if inner.chars().count() != 1 {
                            return Err(format!(
                                "OQL strings use double quotes, not single: write {:?} \
                                 (single quotes are only a one-character literal, e.g. 'a')",
                                inner
                            ));
                        }
                    }
                    return Err(format!(
                        "character literal must contain exactly one character: {slice:?} \
                         (single-quoted, no escapes)"
                    ));
                }
                if slice.chars().next().is_some_and(|c| c.is_ascii_digit()) {
                    return Err(format!(
                        "numeric literal out of range for a 64-bit integer (unsigned range, \
                         0..=0xffffffffffffffff): {slice:?}"
                    ));
                }
                return Err(format!(
                    "unexpected character(s) at offset {}: {:?}",
                    span.start,
                    &src[span.clone()]
                ));
            }
        }
    }
    Ok(out)
}

fn ident_ci<'a, I>(
    kw: &'static str,
) -> impl Parser<'a, I, String, extra::Err<Rich<'a, Token>>> + Clone
where
    I: ValueInput<'a, Token = Token, Span = SimpleSpan>,
{
    select! { Token::Ident(s) if s.eq_ignore_ascii_case(kw) => s }.labelled(kw)
}

fn any_ident<'a, I>() -> impl Parser<'a, I, String, extra::Err<Rich<'a, Token>>> + Clone
where
    I: ValueInput<'a, Token = Token, Span = SimpleSpan>,
{
    select! { Token::Ident(s) => s }
}

/// Parses a `name ( ident )` dominator function form, yielding the single alias
/// identifier. A missing/malformed argument (e.g. `dominators()`) produces the
/// actionable `"<name>(x) requires a single alias argument, e.g. <name>(s)"`
/// error the callers assert on.
fn dom_fn<'a, I>(
    name: &'static str,
) -> impl Parser<'a, I, String, extra::Err<Rich<'a, Token>>> + Clone
where
    I: ValueInput<'a, Token = Token, Span = SimpleSpan>,
{
    ident_ci(name)
        .ignore_then(just(Token::LParen))
        .ignore_then(any_ident().or_not())
        .then_ignore(just(Token::RParen))
        .validate(move |arg, e, emitter| match arg {
            Some(a) => a,
            None => {
                emitter.emit(Rich::custom(
                    e.span(),
                    format!("{name}(x) requires a single alias argument, e.g. {name}(s)"),
                ));
                String::new()
            }
        })
}

#[allow(clippy::type_complexity)]
pub(crate) fn parser<'a, I>() -> impl Parser<'a, I, Query, extra::Err<Rich<'a, Token>>>
where
    I: ValueInput<'a, Token = Token, Span = SimpleSpan>,
{
    // attribute: [alias.]@built-in | classof(x) | bare field
    //
    // `@attr`, optionally alias-qualified as `alias.@attr`. The greedy ident
    // regex swallows the trailing `.`, so `s.@objectId` tokenizes as `Ident("s.")`
    // then `At("objectId")`; consume the optional trailing-dot prefix here so it
    // is not swallowed as a `Field`. A prefix of exactly one segment (`s.`) is the
    // FROM alias and is dropped. A MULTI-segment prefix (`s.value.`) carries
    // reference hops before the `@attr` tail (e.g. `s.value.@length`): the
    // segments are kept as raw `RefPath` hops here and `normalize_attr` strips the
    // leading alias hop once the FROM alias is known. Unknown names emit an
    // actionable error but still yield a placeholder so the `@`-token stays
    // committed (no backtracking into the bare-field arm, which would otherwise
    // mask the `unknown @attribute` message).
    let at_attr = select! { Token::Ident(p) if p.ends_with('.') => p }
        .or_not()
        .then(select! { Token::At(name) => name })
        .validate(|(prefix, name): (Option<String>, String), e, emitter| {
            let base = match name.as_str() {
                "objectId" => Attr::ObjectId,
                "objectAddress" => Attr::ObjectAddress,
                "usedHeapSize" | "shallowHeapSize" | "shallowSize" => Attr::UsedHeapSize,
                "retainedHeapSize" | "retainedHeap" => Attr::RetainedHeapSize,
                "displayName" => Attr::DisplayName,
                "name" => Attr::DisplayName,
                "length" => Attr::Length,
                "inbounds" => Attr::Inbounds,
                "outbounds" => Attr::Outbounds,
                "valueArray" => Attr::ValueArray,
                "referenceArray" => Attr::ReferenceArray,
                "GCRoots" => Attr::GcRoots,
                "GCRootInfo" | "info" => Attr::GcRootInfo,
                other => {
                    // Suggest the nearest known @attribute on a typo
                    // (@objectAdress -> @objectAddress). ATTRIBUTES carries the
                    // `@`-prefixed names; match against the bare form.
                    let msg = match did_you_mean(
                        other,
                        ATTRIBUTES.iter().map(|a| a.trim_start_matches('@')),
                    ) {
                        Some(s) => format!("unknown @attribute: @{other} — did you mean `@{s}`?"),
                        None => format!("unknown @attribute: @{other}"),
                    };
                    emitter.emit(Rich::custom(e.span(), msg));
                    Attr::ObjectId
                }
            };
            // A prefix with intermediate segments (more than the leading alias)
            // is a reference path: `s.value.@length` → hops carry `["s","value"]`
            // (raw); `normalize_attr` strips the leading alias. A single-segment
            // prefix (`s.`) is just the alias and carries no hops → bare attr.
            match prefix {
                Some(p) => {
                    let segs: Vec<String> = p
                        .trim_end_matches('.')
                        .split('.')
                        .map(str::to_string)
                        .collect();
                    if segs.len() >= 2 {
                        Attr::RefPath {
                            hops: segs,
                            tail: Box::new(base),
                            role: RefRole::ProjectionOnly,
                        }
                    } else {
                        base
                    }
                }
                None => base,
            }
        });
    let attr = at_attr
        .or(ident_ci("classof")
            .ignore_then(just(Token::LParen))
            .ignore_then(any_ident())
            .then_ignore(just(Token::RParen))
            .map(|_| Attr::ClassOf))
        .or(dom_fn("dominators").map(Attr::Dominators))
        .or(dom_fn("dominatorof").map(Attr::DominatorOf))
        .or(dom_fn("toString").map(Attr::ToString))
        .or(any_ident().map(Attr::Field))
        .labelled("attribute");

    // Arithmetic expression combinator: precedence-climbing over attr/literal primaries.
    // Defined here (after `attr`) so it can be reused in both the SELECT item and the
    // WHERE compare production. Bool/null ARE included as primaries so that compare
    // expressions like `flag = true` and `x != null` still parse. A bare single-leaf
    // expr is folded back to `SelectItem::Attr` by the caller; this combinator always
    // returns `Expr`.
    let expr = recursive(|expr| {
        let lit = select! {
            Token::Int(n) => Value::Int(n),
            Token::Float(f) => Value::Float(f),
            Token::Str(s) => Value::Str(s),
            Token::Ident(s) if s.eq_ignore_ascii_case("true") => Value::Bool(true),
            Token::Ident(s) if s.eq_ignore_ascii_case("false") => Value::Bool(false),
            Token::Ident(s) if s.eq_ignore_ascii_case("null") => Value::Null,
        }
        .map(Expr::Lit);

        let tohex = ident_ci("toHex")
            .ignore_then(just(Token::LParen))
            .ignore_then(expr.clone())
            .then_ignore(just(Token::RParen))
            .map(|arg| Expr::Attr(Attr::ToHex(Box::new(arg))));

        let coalesce_expr = ident_ci("COALESCE")
            .ignore_then(just(Token::LParen))
            .ignore_then(
                expr.clone()
                    .separated_by(just(Token::Comma))
                    .collect::<Vec<_>>(),
            )
            .then_ignore(just(Token::RParen))
            .validate(|args, e, emitter| {
                if args.is_empty() {
                    emitter.emit(Rich::custom(
                        e.span(),
                        "COALESCE requires at least one argument",
                    ));
                }
                Expr::Coalesce(args)
            });

        let nullif_expr = ident_ci("NULLIF")
            .ignore_then(just(Token::LParen))
            .ignore_then(expr.clone())
            .then_ignore(just(Token::Comma))
            .then(expr.clone())
            .then_ignore(just(Token::RParen))
            .map(|(lhs, rhs)| Expr::NullIf {
                lhs: Box::new(lhs),
                rhs: Box::new(rhs),
            });

        // `receiver.name(args)` — the greedy Ident regex swallows `s.getName` as a
        // single token. We match any dotted ident (contains `.`, does NOT end with
        // `.`) immediately followed by `(…)`, splitting on the last `.` to separate
        // the receiver alias from the method name. Zero-arg → empty Vec.
        let method_call = select! {
            Token::Ident(s) if s.contains('.') && !s.ends_with('.') => s
        }
        .then(
            just(Token::LParen)
                .ignore_then(
                    expr.clone()
                        .separated_by(just(Token::Comma))
                        .collect::<Vec<_>>(),
                )
                .then_ignore(just(Token::RParen)),
        )
        .map(|(dotted, args): (String, Vec<Expr>)| {
            let (recv, meth) = dotted.rsplit_once('.').unwrap();
            Expr::Method {
                receiver: Box::new(Expr::Attr(Attr::Field(recv.to_string()))),
                name: meth.to_string(),
                args,
            }
        });

        // `COUNT(*)`, `SUM(@field)`, etc. used in HAVING position.
        // Parses the same syntax as the select-item `agg` arm but produces
        // `Expr::Aggregate` so it can appear on either side of a comparison.
        let agg_star = just(Token::Star).to(SelectItem::Star);
        let agg_attr_arg = attr.clone().map(SelectItem::Attr);
        let agg_arg = agg_star.or(agg_attr_arg);
        let agg_expr_arm = select! {
            Token::Ident(s) if agg_func(&s).is_some() => agg_func(&s).unwrap(),
        }
        .then_ignore(just(Token::LParen))
        .then(agg_arg)
        .then_ignore(just(Token::RParen))
        .map(|(func, arg)| Expr::Aggregate {
            func,
            arg: Box::new(arg),
        });

        let primary = agg_expr_arm
            .or(method_call)
            .or(coalesce_expr)
            .or(nullif_expr)
            .or(tohex)
            .or(lit)
            .or(just(Token::LParen)
                .ignore_then(expr.clone())
                .then_ignore(just(Token::RParen)))
            .or(
                // `attr[expr]` (index) or `attr[start:end]` (slice), or bare `attr`.
                attr.clone()
                    .then(
                        just(Token::LBracket)
                            .ignore_then(
                                // Optional start expression (None for `[:end]`).
                                expr.clone().or_not().then(
                                    just(Token::Colon)
                                        .ignore_then(expr.clone().or_not())
                                        .or_not(),
                                ),
                            )
                            .then_ignore(just(Token::RBracket))
                            .or_not(),
                    )
                    .map(|(base, postfix)| {
                        let attr_val = match postfix {
                            None => base,
                            Some((Some(idx_expr), None)) => {
                                // `base[idx]` — single index (no colon)
                                Attr::ArrayIndex {
                                    base: Box::new(base),
                                    index: Box::new(idx_expr),
                                }
                            }
                            Some((start, Some(end))) => {
                                // `base[start:end]` / `base[:end]` / `base[start:]`
                                Attr::ArraySlice {
                                    base: Box::new(base),
                                    start: start.map(Box::new),
                                    end: end.map(Box::new),
                                }
                            }
                            Some((None, None)) => {
                                // bare `[]` without colon — treat as identity (unusual)
                                base
                            }
                        };
                        Expr::Attr(attr_val)
                    }),
            );

        let unary = just(Token::Minus)
            .to(UnaryOp::Neg)
            .or(just(Token::Plus).to(UnaryOp::Pos))
            .or_not()
            .then(primary)
            .map(|(u, p)| match u {
                None | Some(UnaryOp::Pos) => p,
                Some(UnaryOp::Neg) => match p {
                    Expr::Lit(Value::Int(n)) => Expr::Lit(Value::Int(-n)),
                    Expr::Lit(Value::Float(f)) => Expr::Lit(Value::Float(-f)),
                    other => Expr::Unary {
                        op: UnaryOp::Neg,
                        arg: Box::new(other),
                    },
                },
            });

        let mul = unary.clone().foldl(
            just(Token::Star)
                .to(ArithOp::Mul)
                .or(just(Token::Divide).to(ArithOp::Div))
                .then(unary)
                .repeated(),
            |lhs, (op, rhs)| Expr::Binary {
                op,
                lhs: Box::new(lhs),
                rhs: Box::new(rhs),
            },
        );

        mul.clone().foldl(
            just(Token::Plus)
                .to(ArithOp::Add)
                .or(just(Token::Minus).to(ArithOp::Sub))
                .then(mul)
                .repeated(),
            |lhs, (op, rhs)| Expr::Binary {
                op,
                lhs: Box::new(lhs),
                rhs: Box::new(rhs),
            },
        )
    });

    // Symbolic comparison operators tokenized by logos.
    let sym_op = select! {
        Token::Eq => CompareOp::Eq,
        Token::Ne => CompareOp::Ne,
        Token::Lt => CompareOp::Lt,
        Token::Le => CompareOp::Le,
        Token::Gt => CompareOp::Gt,
        Token::Ge => CompareOp::Ge,
    };
    // Word operators `LIKE` and `NOT LIKE` (Java-regex full-match; see
    // `compare_values`). `NOT LIKE` is a two-token operator sequence that sits in
    // OPERATOR position (right after the attribute LHS), which is structurally
    // distinct from prefix `NOT` wrapping a whole predicate — prefix `NOT` is
    // handled by the `not` combinator before any attribute is seen, so the two
    // never collide. Try `NOT LIKE` before bare `LIKE`.
    let not_like = ident_ci("NOT")
        .ignore_then(ident_ci("LIKE"))
        .to(CompareOp::NotLike);
    let like = ident_ci("LIKE").to(CompareOp::Like);
    let op = sym_op.or(not_like).or(like).labelled("comparison operator");

    // Optional `AS RETAINED SET` select modifier. `AS RETAINED` without a
    // trailing `SET` is a hard, actionable error rather than a silent miss.
    let retained_set = ident_ci("AS")
        .ignore_then(ident_ci("RETAINED"))
        .ignore_then(
            ident_ci("SET").to(true).or(any().or_not().validate(|_, e, emitter| {
                emitter.emit(Rich::custom(
                    e.span(),
                    "expected SET after 'AS RETAINED' (usage: SELECT <expr> AS RETAINED SET FROM ...)",
                ));
                true
            })),
        )
        .or_not()
        .map(|r| r.unwrap_or(false));

    let base_query = recursive(|base_query| {
        // FROM target: a parenthesized subquery `( <base_query> )`, or a class
        // pattern. INSTANCEOF applies only to the class form. UNION is not
        // reachable inside the parens (base_query has no UNION tail), so
        // `UNION` inside a subquery fails to parse — the intended rejection.
        let from_subquery = just(Token::LParen)
            .ignore_then(base_query.clone())
            .then_ignore(just(Token::RParen))
            .map(|inner: Query| FromSource::Subquery(Box::new(inner)));
        let from_class = ident_ci("INSTANCEOF")
            .or_not()
            .map(|i| i.is_some())
            .then(
                any_ident()
                    .labelled("class name")
                    .map(|name| (name, false))
                    .or(select! { Token::Str(s) => (s, true) }.labelled("class regex")),
            )
            .validate(|(instanceof, (class_name, is_regex)), e, emitter| {
                if instanceof && is_regex {
                    emitter.emit(Rich::custom(
                        e.span(),
                        "INSTANCEOF requires a bare class name, not a quoted regex \
                         (usage: FROM INSTANCEOF java.lang.Object, or drop INSTANCEOF \
                         and use FROM \"<regex>\" for regex matching)",
                    ));
                }
                FromSource::Class(ClassSpec {
                    instanceof,
                    class_name,
                    is_regex,
                })
            });
        // `FROM OBJECTS <address>`: a bare integer literal (decimal, hex, or
        // octal — all collapse to `Token::Int`) names one heap object by address.
        let from_object = select! { Token::Int(n) => n }.map(|n| FromSource::Object(n as u64));
        // `FROM INSTANCEOF <address>` is a common mistake: INSTANCEOF takes a
        // class, not an address. Detect INSTANCEOF followed by an int and emit an
        // actionable error rather than a bare parse failure.
        let instanceof_addr = ident_ci("INSTANCEOF")
            .ignore_then(select! { Token::Int(_) => () })
            .validate(|_, e, emitter| {
                emitter.emit(Rich::custom(
                    e.span(),
                    "INSTANCEOF <address> is not supported; use INSTANCEOF <class> \
                     (e.g. FROM INSTANCEOF java.lang.Thread)",
                ));
                FromSource::Object(0)
            });
        // `FROM OBJECTS (<expr>)` (arithmetic/boolean seed expressions) is a
        // deferred MAT feature. A leading `(` here (after OBJECTS was consumed and
        // it is NOT a `( SELECT ... )` subquery) means a not-yet-supported seed
        // expression. `from_subquery` is tried first (see `from_source`), so this
        // only fires for a `(` that failed to parse as a subquery.
        let from_object_expr = just(Token::LParen).rewind().validate(|_, e, emitter| {
            emitter.emit(Rich::custom(
                e.span(),
                "arithmetic/boolean FROM-OBJECTS expressions are not yet supported; \
                 use FROM OBJECTS <address> (e.g. FROM OBJECTS 0x1295e2f8) or FROM <class>",
            ));
            FromSource::Object(0)
        });
        let from_source = from_subquery
            .or(from_object)
            .or(instanceof_addr)
            .or(from_object_expr)
            .or(from_class);

        // Predicate grammar. Defined inside the `base_query` recursive closure so
        // the `IN (<subquery>)` alternative can reuse `base_query` for the inner
        // (non-correlated) query. UNION is unreachable inside the parens, so
        // `IN (... UNION ...)` fails to parse — the intended rejection.
        let predicate = recursive(|pred| {
            let paren = just(Token::LParen)
                .ignore_then(pred.clone())
                .then_ignore(just(Token::RParen));
            let instanceof = attr
                .clone()
                .then_ignore(ident_ci("INSTANCEOF"))
                .then(any_ident())
                .map(|(_lhs, cname)| Predicate::InstanceOf(cname));
            let in_subquery = attr
                .clone()
                .then_ignore(ident_ci("IN"))
                .then_ignore(just(Token::LParen))
                .then(base_query.clone())
                .then_ignore(just(Token::RParen))
                .map(|(lhs, inner): (Attr, Query)| Predicate::InSubquery {
                    lhs,
                    inner: Box::new(inner),
                });
            // `expr IN (v1, v2, …)` — value-list form (desugars to OR chain of = compares).
            // Must be tried before `compare` so `IN` is not parsed as a field name.
            // Uses `expr` (not just `attr`) so `toString(s) IN (…)` works.
            // Also handles `NOT IN (…)` (negated IN list).
            let in_list = {
                let lit_val = select! {
                    Token::Int(n) => Value::Int(n),
                    Token::Float(f) => Value::Float(f),
                    Token::Str(s) => Value::Str(s),
                };
                let null_val = ident_ci("NULL").to(Value::Null);
                let bool_val = ident_ci("TRUE")
                    .to(Value::Bool(true))
                    .or(ident_ci("FALSE").to(Value::Bool(false)));
                let val = null_val.or(bool_val).or(lit_val);
                let not_in = ident_ci("NOT").then_ignore(ident_ci("IN")).to(true);
                let just_in = ident_ci("IN").to(false);
                let in_kw = not_in.or(just_in);
                expr.clone()
                    .then(in_kw)
                    .then_ignore(just(Token::LParen))
                    .then(
                        val.clone()
                            .then(
                                just(Token::Comma)
                                    .ignore_then(val)
                                    .repeated()
                                    .collect::<Vec<_>>(),
                            )
                            .map(|(first, rest)| {
                                let mut vals = vec![first];
                                vals.extend(rest);
                                vals
                            }),
                    )
                    .then_ignore(just(Token::RParen))
                    .map(|((lhs, negated), vals): ((Expr, bool), Vec<Value>)| {
                        if negated {
                            // NOT IN: desugar to AND chain of != compares
                            let mut terms = vals.into_iter().map(|v| Predicate::Compare {
                                lhs: lhs.clone(),
                                op: CompareOp::Ne,
                                rhs: Expr::Lit(v),
                            });
                            let first = terms.next().unwrap();
                            terms.fold(first, |acc, t| Predicate::And(Box::new(acc), Box::new(t)))
                        } else {
                            // IN: desugar to OR chain of = compares
                            let mut terms = vals.into_iter().map(|v| Predicate::Compare {
                                lhs: lhs.clone(),
                                op: CompareOp::Eq,
                                rhs: Expr::Lit(v),
                            });
                            let first = terms.next().unwrap();
                            terms.fold(first, |acc, t| Predicate::Or(Box::new(acc), Box::new(t)))
                        }
                    })
            };
            let compare = expr.clone().then(op).then(expr.clone()).validate(
                |((lhs, op), rhs), e, emitter| {
                    // LIKE/NOT LIKE RHS must be a string literal (MAT parity).
                    if matches!(op, CompareOp::Like | CompareOp::NotLike)
                        && !matches!(&rhs, Expr::Lit(Value::Str(_)))
                    {
                        emitter.emit(Rich::custom(
                            e.span(),
                            "LIKE right-hand side must be a string literal, \
                             e.g. LIKE \"java\\\\..*\"",
                        ));
                    }
                    Predicate::Compare { lhs, op, rhs }
                },
            );
            // `expr BETWEEN a AND b` desugars to `expr >= a AND expr <= b`.
            // `expr NOT BETWEEN a AND b` desugars to `expr < a OR expr > b`.
            // Must be tried before `compare` so `AND` is not consumed as a
            // boolean AND continuation.
            let between_kw = ident_ci("NOT")
                .then_ignore(ident_ci("BETWEEN"))
                .to(true)
                .or(ident_ci("BETWEEN").to(false));
            let between_pred = expr
                .clone()
                .then(between_kw)
                .then(expr.clone())
                .then_ignore(ident_ci("AND"))
                .then(expr.clone())
                .map(|(((subject, negated), lo), hi)| {
                    if negated {
                        Predicate::Or(
                            Box::new(Predicate::Compare {
                                lhs: subject.clone(),
                                op: CompareOp::Lt,
                                rhs: lo,
                            }),
                            Box::new(Predicate::Compare {
                                lhs: subject,
                                op: CompareOp::Gt,
                                rhs: hi,
                            }),
                        )
                    } else {
                        Predicate::And(
                            Box::new(Predicate::Compare {
                                lhs: subject.clone(),
                                op: CompareOp::Ge,
                                rhs: lo,
                            }),
                            Box::new(Predicate::Compare {
                                lhs: subject,
                                op: CompareOp::Le,
                                rhs: hi,
                            }),
                        )
                    }
                });
            // `expr IS NULL` / `expr IS NOT NULL` — SQL-standard null-check sugar.
            // Desugars to `expr = null` / `expr != null`.
            let is_null = expr
                .clone()
                .then_ignore(ident_ci("IS"))
                .then(ident_ci("NOT").or_not().map(|n| n.is_some()))
                .then_ignore(ident_ci("NULL"))
                .map(|(lhs, negated)| Predicate::Compare {
                    lhs,
                    op: if negated {
                        CompareOp::Ne
                    } else {
                        CompareOp::Eq
                    },
                    rhs: Expr::Lit(Value::Null),
                });
            // `in_subquery` before `compare` so `IN` isn't consumed as a bare field.
            // `between_pred` before `compare` so `BETWEEN ... AND` is not split.
            // `exists_pred` (bare EXISTS) before `compare` so EXISTS is not confused with a field.
            // `is_null` before `compare` so IS is not confused with a field/typo.
            let exists_pred = ident_ci("EXISTS")
                .ignore_then(just(Token::LParen))
                .ignore_then(base_query.clone())
                .then_ignore(just(Token::RParen))
                .map(|inner| Predicate::Exists {
                    inner: Box::new(inner),
                    negated: false,
                });
            let primary = paren
                .or(instanceof)
                .or(in_subquery)
                .or(in_list)
                .or(between_pred)
                .or(is_null)
                .or(exists_pred)
                .or(compare);
            let not = recursive(|not| {
                // `NOT EXISTS (...)` must be tried before the general `NOT <pred>` recursive
                // arm so the `EXISTS` keyword is not mistakenly parsed as a predicate.
                let not_exists = ident_ci("NOT")
                    .ignore_then(ident_ci("EXISTS"))
                    .ignore_then(just(Token::LParen))
                    .ignore_then(base_query.clone())
                    .then_ignore(just(Token::RParen))
                    .map(|inner| Predicate::Exists {
                        inner: Box::new(inner),
                        negated: true,
                    });
                not_exists
                    .or(ident_ci("NOT")
                        .ignore_then(not)
                        .map(|p| Predicate::Not(Box::new(p))))
                    .or(primary)
            });
            let and = not
                .clone()
                .foldl(ident_ci("AND").ignore_then(not).repeated(), |l, r| {
                    Predicate::And(Box::new(l), Box::new(r))
                });
            and.clone()
                .foldl(ident_ci("OR").ignore_then(and).repeated(), |l, r| {
                    Predicate::Or(Box::new(l), Box::new(r))
                })
                .labelled("predicate expression")
        });

        // CASE WHEN <pred> THEN <expr> [WHEN <pred> THEN <expr>]* [ELSE <expr>] END
        // Defined here (inside base_query) so it can reuse `predicate`.
        let case_expr = ident_ci("CASE")
            .ignore_then(
                ident_ci("WHEN")
                    .ignore_then(predicate.clone())
                    .then_ignore(ident_ci("THEN"))
                    .then(expr.clone())
                    .repeated()
                    .at_least(1)
                    .collect::<Vec<_>>(),
            )
            .then(ident_ci("ELSE").ignore_then(expr.clone()).or_not())
            .then_ignore(ident_ci("END"))
            .map(|(branches, else_)| Expr::Case {
                branches,
                else_: else_.map(Box::new),
            });

        // select item: AGG(item) | path(a, b) | toString(s) | * | case_expr | expr
        // Each item may be followed by an optional `AS <name>` alias.
        // Guard: `AS RETAINED` is NOT consumed here — it belongs to the retained_set
        // modifier parsed at the SELECT level.
        let select_item = recursive(|item| {
            let agg = select! {
                Token::Ident(s) if agg_func(&s).is_some() => agg_func(&s).unwrap(),
            }
            .then_ignore(just(Token::LParen))
            .then(item.clone())
            .then_ignore(just(Token::RParen))
            .map(
                |(func, (arg, _alias)): (AggFunc, (SelectItem, Option<String>))| {
                    (
                        SelectItem::Aggregate {
                            func,
                            arg: Box::new(arg),
                        },
                        None::<String>,
                    )
                },
            );

            // `PERCENTILE(<arg>, <p>)` — two-arg aggregate.
            let percentile_item = ident_ci("PERCENTILE")
                .ignore_then(just(Token::LParen))
                .ignore_then(item.clone())
                .then_ignore(just(Token::Comma))
                .then(select! { Token::Int(n) => n })
                .then_ignore(just(Token::RParen))
                .validate(|((arg, _alias), p): ((SelectItem, Option<String>), i64), e, emitter| {
                    if !(1..=100).contains(&p) {
                        emitter.emit(Rich::custom(
                            e.span(),
                            format!(
                                "PERCENTILE(<arg>, p): p must be an integer between 1 and 100, got {p}"
                            ),
                        ));
                    }
                    let clamped = p.clamp(1, 100) as u8;
                    (
                        SelectItem::Aggregate {
                            func: AggFunc::Percentile(clamped),
                            arg: Box::new(arg),
                        },
                        None::<String>,
                    )
                });

            let path_operand = any_ident().map(|s: String| {
                if s.contains('.') || s.contains('*') {
                    PathOperand::Class(s)
                } else {
                    PathOperand::Alias(s)
                }
            });
            let path_item = ident_ci("path")
                .ignore_then(just(Token::LParen))
                .ignore_then(path_operand.clone())
                .then_ignore(just(Token::Comma))
                .then(path_operand)
                .then_ignore(just(Token::RParen))
                .map(|(from, to)| (SelectItem::Path { from, to }, None::<String>));

            let star = just(Token::Star).map(|_| (SelectItem::Star, None::<String>));

            let tostring_item =
                dom_fn("toString").map(|a| (SelectItem::ToString(a), None::<String>));

            // CASE WHEN … THEN … ELSE … END as a select item.
            let case_item = case_expr
                .clone()
                .map(|e| (SelectItem::Expr(Box::new(e)), None::<String>));

            // A bare `@alias` select item that preserves the written alias name as the
            // column header when a non-canonical alias is used (e.g. `@shallowHeapSize`
            // displays as `@shallowHeapSize`, not `@usedHeapSize`).
            let select_attr_item = select! { Token::Ident(p) if p.ends_with('.') => p }
                .or_not()
                .then(select! { Token::At(name) => name })
                // Peek at the next token: if it's an arithmetic op, bail and let
                // expr_item parse the full `@attr + ...` expression instead.
                .then(
                    one_of([Token::Plus, Token::Minus, Token::Star, Token::Divide])
                        .rewind()
                        .or_not(),
                )
                .map(
                    |((prefix, name), next_arith): ((Option<String>, String), _)| {
                        if next_arith.is_some() {
                            return None; // arithmetic follows; hand off to expr_item
                        }
                        let (attr, canonical) = match name.as_str() {
                            "usedHeapSize" => (Attr::UsedHeapSize, "@usedHeapSize"),
                            "shallowHeapSize" => (Attr::UsedHeapSize, "@usedHeapSize"),
                            "shallowSize" => (Attr::UsedHeapSize, "@usedHeapSize"),
                            "retainedHeapSize" => (Attr::RetainedHeapSize, "@retainedHeapSize"),
                            "retainedHeap" => (Attr::RetainedHeapSize, "@retainedHeapSize"),
                            _ => return None,
                        };
                        // Single-segment prefix is just the FROM alias; strip it.
                        let has_hops = prefix
                            .as_deref()
                            .map(|p| p.trim_end_matches('.').contains('.'))
                            .unwrap_or(false);
                        if has_hops {
                            return None; // leave to expr_item for full RefPath handling
                        }
                        let written = format!("@{name}");
                        let auto_alias = if written != canonical {
                            Some(written)
                        } else {
                            None
                        };
                        Some((SelectItem::Attr(attr), auto_alias))
                    },
                )
                .filter_map(|x| x);

            // `expr_item` covers all arithmetic expressions AND bare attrs (folded back).
            let expr_item = expr.clone().map(|e| {
                let item = match e {
                    Expr::Attr(a) => SelectItem::Attr(a),
                    other => SelectItem::Expr(Box::new(other)),
                };
                (item, None::<String>)
            });
            // IMPORTANT: `star` must come before `expr_item`.
            // `case_item` before `expr_item` so CASE is not swallowed as a bare field.
            // `select_attr_item` before `expr_item` so alias attr names get column headers.
            let base_item = percentile_item
                .or(agg)
                .or(path_item)
                .or(tostring_item)
                .or(star)
                .or(case_item)
                .or(select_attr_item)
                .or(expr_item);

            let alias_name = ident_ci("AS").ignore_then(
                select! { Token::Str(s) => s }.or(any_ident().and_is(ident_ci("RETAINED").not())),
            );

            base_item
                .then(alias_name.or_not())
                // Explicit AS alias wins; fall back to the pre-computed alias from
                // select_attr_item (e.g. "@shallowHeapSize" when that alias was written).
                .map(|((item, pre_alias), explicit_alias)| {
                    (item, explicit_alias.map(Some).unwrap_or(pre_alias))
                })
                .labelled("expression")
        });

        // Collect aliased items, then unzip into parallel vecs.
        let select_list = select_item
            .separated_by(just(Token::Comma))
            .at_least(1)
            .collect::<Vec<_>>()
            .map(|pairs: Vec<(SelectItem, Option<String>)>| {
                let (items, aliases): (Vec<_>, Vec<_>) = pairs.into_iter().unzip();
                (items, aliases)
            });

        ident_ci("SELECT")
            .ignore_then(ident_ci("DISTINCT").or_not().map(|d| d.is_some()))
            // Leading `AS RETAINED SET` (MAT also accepts this before the select list).
            .then(retained_set.clone())
            // `OBJECTS` between SELECT head and select list is a no-op projection marker.
            .then_ignore(ident_ci("OBJECTS").or_not())
            .then(select_list)
            // Trailing `AS RETAINED SET` (existing MAT form, kept for compatibility).
            .then(retained_set.clone())
            .then_ignore(ident_ci("FROM"))
            // MAT allows `FROM OBJECTS <class>` as a no-op synonym for `FROM <class>`.
            .then_ignore(ident_ci("OBJECTS").or_not())
            .then(from_source)
            .then(any_ident().and_is(reserved_ident().not()).or_not())
            .then(ident_ci("WHERE").ignore_then(predicate.clone()).or_not())
            // GROUP BY <expr> [, <expr>]*
            .then(
                ident_ci("GROUP")
                    .ignore_then(ident_ci("BY"))
                    .ignore_then(
                        case_expr
                            .clone()
                            .or(expr.clone())
                            .separated_by(just(Token::Comma))
                            .at_least(1)
                            .collect::<Vec<_>>(),
                    )
                    .or_not()
                    .map(|v| v.unwrap_or_default()),
            )
            // HAVING <predicate>
            .then(ident_ci("HAVING").ignore_then(predicate.clone()).or_not())
            .then(
                ident_ci("ORDER")
                    .ignore_then(ident_ci("BY"))
                    .ignore_then(attr.clone())
                    .then(
                        ident_ci("ASC")
                            .to(SortDir::Asc)
                            .or(ident_ci("DESC").to(SortDir::Desc))
                            .or_not()
                            .map(|d| d.unwrap_or(SortDir::Asc)),
                    )
                    .map(|(key, dir)| OrderBy { key, dir })
                    .or_not(),
            )
            .then(
                ident_ci("LIMIT")
                    .ignore_then(
                        select! { Token::Int(n) if n >= 0 => n as u64 }.labelled("LIMIT count"),
                    )
                    .or_not(),
            )
            .then(
                ident_ci("OFFSET")
                    .ignore_then(
                        select! { Token::Int(n) if n >= 0 => n as u64 }.labelled("OFFSET count"),
                    )
                    .or_not(),
            )
            .map(
                |(
                    (
                        (
                            (
                                (
                                    (
                                        (
                                            (
                                                (
                                                    (
                                                        (distinct, leading_retained),
                                                        (select, select_aliases),
                                                    ),
                                                    trailing_retained,
                                                ),
                                                from,
                                            ),
                                            alias,
                                        ),
                                        where_,
                                    ),
                                    group_by,
                                ),
                                having,
                            ),
                            order_by,
                        ),
                        limit,
                    ),
                    offset,
                )| {
                    let mut q = Query {
                        distinct,
                        select,
                        select_aliases,
                        retained_set: leading_retained || trailing_retained,
                        from,
                        alias,
                        where_,
                        order_by,
                        limit,
                        offset,
                        union_branches: Vec::new(),
                        union_limit: None,
                        group_by,
                        having,
                        intersect_branches: Vec::new(),
                        except_branches: Vec::new(),
                    };
                    // Now the alias is known, rewrite dotted `Field`s into N-hop
                    // `RefPath`s (a single segment after alias-strip stays a Field).
                    normalize_query_ref_paths(&mut q);
                    q
                },
            )
    });

    // Top level: a base query, then a flat `UNION`-separated tail folded into the
    // head's `union_branches`. Tail branches keep empty `union_branches` (the
    // list is flat, left-associative concatenation with UNION ALL semantics).
    //
    // A UNION branch may be bare (`UNION SELECT ...`) or parenthesized
    // (`UNION (SELECT ...)`, MAT's canonical form). Parens around a branch are
    // cosmetic; unwrap to the same `Query`. The `(` here sits at the top-level
    // UNION-branch position (before any SELECT), so it is unambiguous with the
    // FROM-subquery paren, which only follows `SELECT ... FROM`.
    let paren_branch = just(Token::LParen)
        .ignore_then(base_query.clone())
        .then_ignore(just(Token::RParen))
        .map(|q| (q, true)); // (branch, parenthesized?)
    let union_branch = paren_branch.or(base_query.clone().map(|q| (q, false)));
    // Optional trailing top-level LIMIT combinator, reused from the single-query
    // path (same `LIMIT <non-negative int>` shape). This only becomes reachable
    // AFTER a parenthesized last branch — a bare last branch's own `base_query`
    // greedily swallows any trailing LIMIT into that branch's `limit`, so the
    // top-level LIMIT here never fires for the bare form. We recover the bare-
    // form union-wide binding below by lifting the last branch's swallowed LIMIT.
    let trailing_limit = ident_ci("LIMIT")
        .ignore_then(select! { Token::Int(n) if n >= 0 => n as u64 }.labelled("LIMIT count"))
        .or_not();
    // INTERSECT and EXCEPT tails: a bare `SELECT ...` branch (no parenthesized
    // form needed — unlike UNION, INTERSECT/EXCEPT do not have a trailing LIMIT).
    let intersect_tail = ident_ci("INTERSECT")
        .ignore_then(base_query.clone())
        .repeated()
        .collect::<Vec<Query>>();
    let except_tail = ident_ci("EXCEPT")
        .ignore_then(base_query.clone())
        .repeated()
        .collect::<Vec<Query>>();
    base_query
        .clone()
        .then(
            ident_ci("UNION")
                .ignore_then(union_branch)
                .repeated()
                .collect::<Vec<_>>(),
        )
        .then(intersect_tail)
        .then(except_tail)
        .then(trailing_limit)
        .then_ignore(end())
        .validate(
            |((((mut head, union_tail), intersects), excepts), trailing): (
                (((Query, Vec<(Query, bool)>), Vec<Query>), Vec<Query>),
                Option<u64>,
            ),
             e,
             emitter| {
                // DECISION (MAT gap #6): a trailing `LIMIT n` after a UNION binds
                // UNION-WIDE (applied to the whole concatenated result), matching
                // Eclipse MAT — NOT to a single branch. Two forms reach here:
                //   • parenthesized last branch `... UNION (SELECT ...) LIMIT n`:
                //     the `LIMIT n` sits at the top level and is captured in
                //     `trailing` directly.
                //   • bare last branch `... UNION SELECT ... LIMIT n`: the last
                //     branch's own `base_query` greedily absorbed the `LIMIT n`
                //     into the last branch's `limit`, so `trailing` is None. We
                //     LIFT that swallowed LIMIT up to the union level so the bare
                //     form matches MAT too. A LIMIT written INSIDE a branch's own
                //     parens is a genuine per-branch limit and is left untouched
                //     (we only lift when the last branch was NOT parenthesized).
                let last_was_paren = union_tail.last().map(|(_, p)| *p).unwrap_or(false);
                head.union_branches = union_tail.into_iter().map(|(q, _)| q).collect();
                if !head.union_branches.is_empty() {
                    if let Some(n) = trailing {
                        head.union_limit = Some(n);
                    } else if !last_was_paren {
                        // Bare-form: lift the last branch's swallowed LIMIT and ORDER BY
                        // to the head so they apply to the whole UNION result, not just
                        // the final branch. (Only lift when the last branch is not
                        // parenthesized — an ORDER BY inside parens is branch-local.)
                        if let Some(last) = head.union_branches.last_mut() {
                            if let Some(n) = last.limit.take() {
                                head.union_limit = Some(n);
                            }
                            if last.order_by.is_some() {
                                head.order_by = last.order_by.take();
                            }
                        }
                    }
                }
                // INTERSECT and EXCEPT: validate that they are not mixed in the
                // same chain (without subquery parentheses).
                if !intersects.is_empty() && !excepts.is_empty() {
                    emitter.emit(Rich::custom(
                        e.span(),
                        "cannot mix INTERSECT and EXCEPT in one chain without subquery \
                         parentheses — wrap one side in a subquery: \
                         (SELECT ... INTERSECT ...) EXCEPT ...",
                    ));
                }
                head.intersect_branches = intersects;
                head.except_branches = excepts;
                head
            },
        )
}

/// Rewrite dotted `Attr::Field` values in a query into N-hop `Attr::RefPath`s,
/// now that the FROM alias is known. A field whose text contains a `.` is a
/// reference path: strip a leading `<alias>.` (the alias denotes the FROM
/// object itself), then split the remainder on `.`. If ≥ 2 segments remain, the
/// last is the scalar/attr tail and the earlier ones are reference hops. A
/// single remaining segment stays a plain `Field`. Role defaults to
/// `ProjectionOnly`; the planner fixes it to `PredicateCritical` for WHERE uses.
/// Only touches the query's own clauses — subqueries are normalized when they
/// are themselves parsed.
fn normalize_query_ref_paths(q: &mut Query) {
    let alias = q.alias.clone();
    for item in &mut q.select {
        normalize_select_item(item, alias.as_deref());
    }
    if let Some(pred) = &mut q.where_ {
        normalize_predicate(pred, alias.as_deref());
    }
    if let Some(ob) = &mut q.order_by {
        normalize_attr(&mut ob.key, alias.as_deref());
    }
    for e in &mut q.group_by {
        normalize_expr(e, alias.as_deref());
    }
    if let Some(pred) = &mut q.having {
        normalize_predicate(pred, alias.as_deref());
    }
}

fn normalize_select_item(item: &mut SelectItem, alias: Option<&str>) {
    // If this item is exactly the bare alias name (no dot), rewrite it to Star —
    // the alias denotes the FROM object itself, just like `*`. This must fire
    // BEFORE the Attr branch's normalize_attr call so dotted paths (`s.field`)
    // are handled by normalize_attr while bare `s` becomes Star.
    if let SelectItem::Attr(Attr::Field(name)) = &*item {
        if let Some(al) = alias {
            if name == al && !name.contains('.') {
                *item = SelectItem::Star;
                return;
            }
        }
    }
    match item {
        SelectItem::Attr(a) => normalize_attr(a, alias),
        SelectItem::Aggregate { arg, .. } => normalize_select_item(arg, alias),
        SelectItem::Star => {}
        // `path(a, b)` operands are already resolved to Alias/Class at parse time;
        // they carry no dotted RefPath to normalize.
        SelectItem::Path { .. } => {}
        // `toString(s)` carries a single alias token; no dotted path to normalize.
        SelectItem::ToString(_) => {}
        SelectItem::Expr(e) => {
            normalize_expr(e, alias);
            // Lowering `e.getKey()`/`e.getValue()` in `normalize_expr` turns the
            // Method node into `Expr::Attr(RefPath)`. Fold that lone-attr Expr back
            // to `SelectItem::Attr` so it flows through the SAME planner/refwalk
            // path as `s.value.@length` (which the parser folds identically at
            // parse time via the `expr_item` combinator). Without this fold the
            // RefPath would sit inside a `SelectItem::Expr` that the refwalk hop
            // collector does not descend into.
            if let Expr::Attr(a) = e.as_ref() {
                *item = SelectItem::Attr(a.clone());
            }
        }
    }
}

fn normalize_predicate(pred: &mut Predicate, alias: Option<&str>) {
    match pred {
        Predicate::And(a, b) | Predicate::Or(a, b) => {
            normalize_predicate(a, alias);
            normalize_predicate(b, alias);
        }
        Predicate::Not(a) => normalize_predicate(a, alias),
        Predicate::Compare { lhs, rhs, .. } => {
            normalize_expr(lhs, alias);
            normalize_expr(rhs, alias);
        }
        // The inner query of an IN-subquery is normalized against its own alias
        // when it is parsed; the outer LHS attr is normalized here.
        Predicate::InSubquery { lhs, .. } => normalize_attr(lhs, alias),
        Predicate::InstanceOf(_) => {}
        // EXISTS inner is normalized when it is parsed; the outer has no alias to normalize.
        Predicate::Exists { .. } => {}
    }
}

/// Recurse into an `Expr`, normalizing all `Attr` leaves with `normalize_attr`.
fn normalize_expr(e: &mut Expr, alias: Option<&str>) {
    match e {
        Expr::Attr(a) => normalize_attr(a, alias),
        Expr::Lit(_) => {}
        Expr::Binary { lhs, rhs, .. } => {
            normalize_expr(lhs, alias);
            normalize_expr(rhs, alias);
        }
        Expr::Unary { arg, .. } => normalize_expr(arg, alias),
        Expr::Method {
            receiver,
            name,
            args,
        } => {
            // Lower `e.getKey()` / `e.getValue()` (zero-arg) to a one-hop RefPath so
            // they reuse the RefWalk late-resolution pipeline exactly like
            // `s.value.@length`. MAT reflects into a live Map.Entry; our static
            // analog follows the backing `key`/`value` reference field one hop and
            // projects the resolved object's ADDRESS (identity) via `project_tail`.
            // Only the exact zero-arg getKey/getValue forms with a bare-alias field
            // receiver lower; every other method stays an `Expr::Method` and flows
            // through the existing scan-time `dispatch_method`/`emulate_jvm_method`.
            let hop_field = match name.as_str() {
                "getKey" => Some("key"),
                "getValue" => Some("value"),
                _ => None,
            };
            if let (Some(field), true, Expr::Attr(Attr::Field(recv))) =
                (hop_field, args.is_empty(), receiver.as_ref())
            {
                // Build hops carrying the receiver alias first (mirrors how a RefPath
                // built during parse carries the alias until `normalize_attr` strips
                // it). `recv` here is the bare receiver token (the FROM alias).
                let mut new_attr = Attr::RefPath {
                    hops: vec![recv.clone(), field.to_string()],
                    tail: Box::new(Attr::ObjectAddress),
                    role: RefRole::ProjectionOnly,
                };
                normalize_attr(&mut new_attr, alias);
                *e = Expr::Attr(new_attr);
                return;
            }
            normalize_expr(receiver, alias);
            for a in args {
                normalize_expr(a, alias);
            }
        }
        Expr::Aggregate { .. } => {} // no Attr leaves to normalize in aggregate args
        Expr::Case { branches, else_ } => {
            for (pred, then_expr) in branches {
                normalize_predicate(pred, alias);
                normalize_expr(then_expr, alias);
            }
            if let Some(e) = else_ {
                normalize_expr(e, alias);
            }
        }
        Expr::Coalesce(args) => {
            for arg in args {
                normalize_expr(arg, alias);
            }
        }
        Expr::NullIf { lhs, rhs } => {
            normalize_expr(lhs, alias);
            normalize_expr(rhs, alias);
        }
    }
}

/// Rewrite a single `Attr::Field` into a `RefPath` when it is a multi-segment
/// reference path. Non-field attrs and single-segment fields are left as-is.
fn normalize_attr(a: &mut Attr, alias: Option<&str>) {
    // A `RefPath` built by `at_attr` (e.g. `s.value.@length`) carries its prefix
    // segments raw in `hops`, still including the leading FROM alias. Strip that
    // alias here now that it is known; a bare alias-only prefix (already filtered
    // in `at_attr`) never reaches this arm. If, after stripping, no hops remain,
    // the whole thing was just `alias.@attr` — collapse to the bare tail attr.
    if let Attr::RefPath { hops, tail, role } = a {
        if let Some(al) = alias {
            if hops.first().map(String::as_str) == Some(al) {
                hops.remove(0);
            }
        }
        if hops.is_empty() {
            *a = (**tail).clone();
        } else {
            // Recurse into the tail so a nested dotted-field tail is normalized too.
            let _ = role; // role is preserved as-is (planner may refine it).
            normalize_attr(tail, alias);
        }
        return;
    }
    // ArrayIndex: normalize the base attr and the index expression.
    if let Attr::ArrayIndex { base, index } = a {
        normalize_attr(base, alias);
        normalize_expr(index, alias);
        return;
    }
    // ArraySlice: normalize the base attr and optional start/end expressions.
    if let Attr::ArraySlice { base, start, end } = a {
        normalize_attr(base, alias);
        if let Some(s) = start {
            normalize_expr(s, alias);
        }
        if let Some(e) = end {
            normalize_expr(e, alias);
        }
        return;
    }
    let Attr::Field(name) = a else { return };
    if !name.contains('.') {
        return;
    }
    // Strip a leading `<alias>.` — the alias is the FROM object, not a hop.
    let stripped: &str = match alias {
        Some(al) => name
            .strip_prefix(al)
            .and_then(|rest| rest.strip_prefix('.'))
            .unwrap_or(name),
        None => name.as_str(),
    };
    let segs: Vec<&str> = stripped.split('.').collect();
    if segs.len() < 2 {
        // Single segment after alias-strip: a plain field. Replace the text with
        // the stripped form so `x.name` becomes `Field("name")`.
        *a = Attr::Field(stripped.to_string());
        return;
    }
    let (tail, hops) = segs.split_last().unwrap();
    *a = Attr::RefPath {
        hops: hops.iter().map(|s| s.to_string()).collect(),
        tail: Box::new(Attr::Field((*tail).to_string())),
        role: RefRole::ProjectionOnly,
    };
}

fn reserved_ident<'a, I>() -> impl Parser<'a, I, String, extra::Err<Rich<'a, Token>>> + Clone
where
    I: ValueInput<'a, Token = Token, Span = SimpleSpan>,
{
    select! { Token::Ident(s) if is_reserved(&s) => s }
}

/// Clause/grammar keywords that open or structure a query but are not reserved
/// words in predicate position. `classof` lives in [`FUNCS`] (projection form).
pub const KEYWORDS: &[&str] = &["SELECT", "DISTINCT", "FROM"];

/// Words reserved in predicate/clause position (`is_reserved`'s source set).
pub const RESERVED: &[&str] = &[
    "WHERE",
    "LIMIT",
    "OFFSET",
    "UNION",
    "AND",
    "OR",
    "NOT",
    "LIKE",
    "INSTANCEOF",
    "IN",
    "ORDER",
    "BY",
    "ASC",
    "DESC",
    // MAT no-op keyword; blocked from alias/completion slots.
    "OBJECTS",
    // Column-alias / retained-set modifier keywords.
    "AS",
    "RETAINED",
    "SET",
    // Grouping keywords.
    "GROUP",
    "HAVING",
    // CASE WHEN expression keywords.
    "CASE",
    "WHEN",
    "THEN",
    "ELSE",
    "END",
    // BETWEEN predicate keyword.
    "BETWEEN",
    // Scalar function keywords.
    "COALESCE",
    "NULLIF",
    // Subquery existence predicate.
    "EXISTS",
    // IS NULL / IS NOT NULL sugar keywords.
    "IS",
    "NULL",
    // Set operation keywords.
    "INTERSECT",
    "EXCEPT",
];

/// Aggregate function names (`agg_func`'s source set), upper-cased.
pub const AGG_FUNCS: &[&str] = &["COUNT", "SUM", "MIN", "MAX", "AVG", "PERCENTILE", "MEDIAN"];

/// Built-in scalar/graph function names used in SELECT/predicate position.
/// Source of truth for REPL completion; matches the `dom_fn` / `path` / `classof`
/// parser arms so completions can never drift from the grammar.
pub const FUNCS: &[&str] = &[
    "classof",
    "toString",
    "toHex",
    "path",
    "dominators",
    "dominatorof",
];

/// Supported method-call names for `receiver.name(args)` dispatch. Single source
/// of truth shared by the plan-time validator and (Wave H) the REPL completer, so
/// completions never drift from the dispatcher. NOTE: `get` is intentionally
/// ABSENT — indexed object-array element access is not emulable statically.
pub const METHODS: &[&str] = &[
    "length",
    "size",
    "getKey",
    "getValue",
    "equals",
    "contains",
    "intValue",
    "longValue",
    "shortValue",
    "byteValue",
    "floatValue",
    "doubleValue",
    "booleanValue",
    "charValue",
    "toString",
    "getName",
    "getObjectAddress",
    "getObjectId",
    "getUsedHeapSize",
    "getRetainedHeapSize",
    "getClazz",
];

/// `@`-prefixed built-in attribute names (matching the `attr` parser's arms),
/// including the leading `@` so they can be offered as completions directly.
pub const ATTRIBUTES: &[&str] = &[
    "@objectId",
    "@objectAddress",
    "@usedHeapSize",
    "@retainedHeapSize",
    "@displayName",
    "@name",
    "@length",
    "@inbounds",
    "@outbounds",
    "@valueArray",
    "@referenceArray",
    "@GCRoots",
    "@GCRootInfo",
    "@info",
];

/// The union of every completion-candidate slice the parser exposes. The
/// context-aware REPL completer draws from the individual slices directly; this
/// helper exists so a test can assert the slices stay collectively exhaustive
/// and mutually disjoint (the single point of truth for keyword knowledge).
#[cfg(test)]
pub fn completion_words() -> Vec<&'static str> {
    KEYWORDS
        .iter()
        .chain(RESERVED.iter())
        .chain(AGG_FUNCS.iter())
        .chain(ATTRIBUTES.iter())
        .chain(FUNCS.iter())
        .copied()
        .collect()
}

fn agg_func(s: &str) -> Option<AggFunc> {
    match () {
        _ if s.eq_ignore_ascii_case("COUNT") => Some(AggFunc::Count),
        _ if s.eq_ignore_ascii_case("SUM") => Some(AggFunc::Sum),
        _ if s.eq_ignore_ascii_case("MIN") => Some(AggFunc::Min),
        _ if s.eq_ignore_ascii_case("MAX") => Some(AggFunc::Max),
        _ if s.eq_ignore_ascii_case("AVG") => Some(AggFunc::Avg),
        _ if s.eq_ignore_ascii_case("MEDIAN") => Some(AggFunc::Median),
        _ => None,
    }
}

fn is_reserved(s: &str) -> bool {
    RESERVED.iter().any(|k| s.eq_ignore_ascii_case(k))
}

/// 1-based (line, column) of a byte offset within `src`, for compact error
/// messages. A byte offset at or past `src.len()` reports the position just
/// past the last character.
fn line_col(src: &str, byte_offset: usize) -> (usize, usize) {
    let capped = byte_offset.min(src.len());
    let mut line = 1;
    let mut col = 1;
    for (i, ch) in src.char_indices() {
        if i >= capped {
            break;
        }
        if ch == '\n' {
            line += 1;
            col = 1;
        } else {
            col += 1;
        }
    }
    (line, col)
}

/// Standard iterative Levenshtein edit distance over ASCII byte slices. Small
/// inputs only (keyword-length tokens), so the O(n*m) DP is negligible.
fn lev(a: &str, b: &str) -> usize {
    let a = a.as_bytes();
    let b = b.as_bytes();
    let mut prev: Vec<usize> = (0..=b.len()).collect();
    let mut curr = vec![0usize; b.len() + 1];
    for (i, &ca) in a.iter().enumerate() {
        curr[0] = i + 1;
        for (j, &cb) in b.iter().enumerate() {
            let cost = if ca == cb { 0 } else { 1 };
            curr[j + 1] = (prev[j + 1] + 1).min(curr[j] + 1).min(prev[j] + cost);
        }
        std::mem::swap(&mut prev, &mut curr);
    }
    prev[b.len()]
}

/// Nearest candidate (edit distance <= 2, ASCII-case-insensitive) to `token`,
/// used to append a "did you mean" hint to compact parse errors. Returns the
/// candidate in its canonical casing.
fn did_you_mean<'a>(token: &str, candidates: impl IntoIterator<Item = &'a str>) -> Option<String> {
    let t = token.to_ascii_lowercase();
    candidates
        .into_iter()
        .map(|c| (c, lev(&t, &c.to_ascii_lowercase())))
        .filter(|(_, d)| *d <= 2)
        .min_by_key(|(_, d)| *d)
        .map(|(c, _)| c.to_string())
}

/// The nearest keyword/function to an unexpected identifier `found`, if any.
/// Shared by the plain [`compact_error`] message and the ariadne
/// [`parse_or_report`] caret diagnostic so both surface the same suggestion.
fn suggest_for_found(found: Option<&Token>) -> Option<String> {
    match found {
        Some(Token::Ident(s)) => did_you_mean(
            s,
            KEYWORDS
                .iter()
                .chain(RESERVED.iter())
                .chain(AGG_FUNCS.iter())
                .chain(FUNCS.iter())
                .copied(),
        )
        // A suggestion that just echoes the token back (it already IS a keyword,
        // e.g. `BY` after a swallowed `GROUP`) is noise, not help — drop it.
        .filter(|s| !s.eq_ignore_ascii_case(found_ident_or_empty(found))),
        _ => None,
    }
}

/// The identifier text of `found` if it is `Token::Ident`, else `""`. Helper for
/// suppressing self-echoing suggestions in [`suggest_for_found`].
fn found_ident_or_empty(found: Option<&Token>) -> &str {
    match found {
        Some(Token::Ident(s)) => s,
        _ => "",
    }
}

/// A hint for an `unexpected LParen` error: when a call like `SUMM(...)` names a
/// function that doesn't exist, chumsky reports the `(` (the ident was consumed
/// as a bare field), which points a caret at the paren rather than the real
/// mistake. This looks back from the `(` at byte offset `lparen` for the callee
/// identifier and, if it is a near-miss for a known function/aggregate, returns
/// the intended name. Only known callables are candidates, so a valid call like
/// `COUNT(` never triggers it.
fn unknown_call_hint(src: &str, lparen: usize) -> Option<String> {
    let before = &src[..lparen];
    let trimmed = before.trim_end();
    let start = trimmed
        .rfind(|c: char| !c.is_ascii_alphanumeric() && c != '_')
        .map(|i| i + 1)
        .unwrap_or(0);
    let callee = &trimmed[start..];
    if callee.is_empty() {
        return None;
    }
    // Don't suggest for a name that is already a valid callable.
    let is_known = |name: &str| {
        AGG_FUNCS
            .iter()
            .chain(FUNCS.iter())
            .chain(METHODS.iter())
            .any(|k| k.eq_ignore_ascii_case(name))
    };
    if is_known(callee) {
        return None;
    }
    did_you_mean(callee, AGG_FUNCS.iter().chain(FUNCS.iter()).copied())
}

/// An actionable message for an empty or whitespace-only query, replacing the
/// cryptic "unexpected end of input" a blank string would otherwise produce.
/// Returns `None` for any non-blank input so the normal parse path runs.
fn blank_query_message(src: &str) -> Option<String> {
    if src.trim().is_empty() {
        Some("empty query — supply OQL, e.g. `SELECT * FROM java.lang.String`".to_string())
    } else {
        None
    }
}

/// A hint to append to an end-of-input parse error: if the source looks like a
/// `SELECT ...` with no `FROM` clause, the most likely mistake is a missing
/// FROM. Word-boundary, case-insensitive so `fromage` or `selection` don't
/// trigger it. Returns `None` when a FROM is present (or there is no SELECT).
fn missing_from_hint(src: &str) -> Option<&'static str> {
    let low = src.to_ascii_lowercase();
    let has_kw = |kw: &str| {
        low.split(|c: char| !c.is_ascii_alphanumeric() && c != '_')
            .any(|w| w == kw)
    };
    if has_kw("select") && !has_kw("from") {
        Some("a query needs a `FROM <class>` clause (e.g. `SELECT * FROM java.lang.String`)")
    } else {
        None
    }
}

/// A hint for an `unexpected Eq` error caused by a `==` operator: OQL equality
/// is a single `=`, so `==` lexes as two `Eq` tokens and the second one is
/// unexpected. Given the byte offset of that second `=`, confirm a `=`
/// immediately precedes it (ignoring nothing — they are adjacent) and return the
/// hint. Returns `None` for a lone `=`.
fn double_eq_hint(src: &str, eq_offset: usize) -> Option<&'static str> {
    let before = src.get(..eq_offset)?;
    if before.ends_with('=') {
        Some("use `=` for equality (OQL has no `==`)")
    } else {
        None
    }
}

/// Detect `ORDER BY COUNT(` / `ORDER BY SUM(` etc. — aggregate expressions are
/// not valid ORDER BY keys (use a column alias instead).
/// Returns an actionable hint when the token before the `(` is an agg function
/// name and `ORDER BY` appears before it in the source.
fn order_by_aggregate_hint(src: &str, lparen_offset: usize) -> Option<&'static str> {
    let before = src[..lparen_offset].trim_end();
    // Last word before the `(`
    let last_word = before.split_whitespace().next_back()?;
    let is_agg = AGG_FUNCS.iter().any(|&f| f.eq_ignore_ascii_case(last_word));
    if !is_agg {
        return None;
    }
    // Check that ORDER BY appears somewhere before
    let upper = src[..lparen_offset].to_ascii_uppercase();
    if !upper.contains("ORDER") || !upper.contains("BY") {
        return None;
    }
    Some(
        "aggregate functions are not valid ORDER BY keys; \
         use a column alias instead (e.g. `COUNT(*) AS n … ORDER BY n DESC`)",
    )
}

/// A hint for an error following `ORDER` when the `BY` keyword is missing
/// (`ORDER <key>` instead of `ORDER BY <key>`). Word-boundary, case-insensitive
/// so `reorder` doesn't trigger it. Returns `None` when `ORDER` is absent or is
/// correctly followed by `BY`.
fn missing_by_hint(src: &str) -> Option<&'static str> {
    let words: Vec<String> = src
        .split(|c: char| !c.is_ascii_alphanumeric() && c != '_')
        .filter(|w| !w.is_empty())
        .map(|w| w.to_ascii_lowercase())
        .collect();
    let it = words.iter().enumerate();
    for (i, w) in it {
        if w == "order" && words.get(i + 1).map(String::as_str) != Some("by") {
            return Some(
                "`ORDER` must be followed by `BY` (e.g. `ORDER BY @retainedHeapSize DESC`)",
            );
        }
    }
    None
}

/// Compact single-line message for one chumsky error. Custom (`Rich::custom`)
/// reasons — e.g. `dominators(x) requires ...` — are surfaced verbatim with a
/// trailing `at <line>:<col>`; positional errors keep the `unexpected <found>`
/// form. Shared by [`parse_internal`] and [`parse_or_report`] so custom
/// diagnostics never get flattened into a generic "unexpected" message.
fn compact_error(src: &str, e: &Rich<'_, Token>) -> String {
    let span = *e.span();
    let (line, col) = line_col(src, span.start);
    match e.reason() {
        chumsky::error::RichReason::Custom(msg) => format!("{msg} at {line}:{col}"),
        _ => {
            let found = e
                .found()
                .map(token_display)
                .unwrap_or_else(|| "end of input".to_string());
            // On end-of-input, a `SELECT` with no `FROM` is the likely cause;
            // otherwise fall back to the nearest-keyword hint.
            if e.found().is_none() {
                if let Some(hint) = missing_from_hint(src) {
                    return format!("unexpected {found} at {line}:{col} — {hint}");
                }
            }
            // `ORDER <key>` with no `BY` surfaces as an unexpected token right
            // after ORDER; hint the missing BY before the generic suggestion.
            if let Some(hint) = missing_by_hint(src) {
                return format!("unexpected {found} at {line}:{col} — {hint}");
            }
            // `==` lexes as two `Eq`; the second is unexpected. Hint the single `=`.
            if matches!(e.found(), Some(Token::Eq)) {
                if let Some(hint) = double_eq_hint(src, span.start) {
                    return format!("unexpected {found} at {line}:{col} — {hint}");
                }
            }
            // An `unexpected LParen` usually means the preceding word was meant to
            // be a function call but names an unknown function; suggest the nearest.
            // Special case: `ORDER BY COUNT(*)` etc — suggest using an alias.
            if matches!(e.found(), Some(Token::LParen)) {
                if let Some(hint) = order_by_aggregate_hint(src, span.start) {
                    return format!("unexpected {found} at {line}:{col} — {hint}");
                }
                if let Some(callee) = unknown_call_hint(src, span.start) {
                    return format!(
                        "unexpected {found} at {line}:{col} — did you mean `{callee}`?"
                    );
                }
            }
            let suggestion = suggest_for_found(e.found());
            match suggestion {
                Some(s) => format!("unexpected {found} at {line}:{col} — did you mean `{s}`?"),
                None => format!("unexpected {found} at {line}:{col}"),
            }
        }
    }
}

/// Tokenize (logos) → chumsky parse, returning a compact single-line message
/// `unexpected <found> at <line>:<col>` (or the tokenizer's offset message) on
/// failure. Backs [`parse`]; [`parse_or_report`] renders errors differently.
fn parse_internal(src: &str) -> Result<Query, String> {
    if let Some(msg) = blank_query_message(src) {
        return Err(msg);
    }
    let toks = tokenize_spanned(src)?;
    let eoi: SimpleSpan = (src.len()..src.len()).into();
    let stream = Stream::from_iter(toks).map(eoi, |(t, s): (Token, SimpleSpan)| (t, s));
    parser().parse(stream).into_result().map_err(|errs| {
        errs.iter()
            .map(|e| compact_error(src, e))
            .collect::<Vec<_>>()
            .join("; ")
    })
}

/// Production parse: chumsky over logos tokens. Returns a [`QueryError`] whose
/// message is a compact single-line description (no caret art) for programmatic
/// callers and tests. Production CLI/REPL paths use [`parse_or_report`] instead
/// for caret diagnostics, so this is currently reached only from tests.
#[allow(dead_code)]
pub fn parse(src: &str) -> Result<Query, QueryError> {
    parse_internal(src).map_err(QueryError)
}

/// Parse, returning either the [`Query`] or a rendered ariadne diagnostic string
/// (caret + red underline) for CLI/REPL display.
pub fn parse_or_report(src: &str) -> Result<Query, String> {
    if let Some(msg) = blank_query_message(src) {
        return Err(msg);
    }
    // Tokenizer errors have no chumsky span to underline; surface the message.
    let toks = match tokenize_spanned(src) {
        Ok(t) => t,
        Err(e) => return Err(format!("tokenize error: {e}")),
    };
    let eoi: SimpleSpan = (src.len()..src.len()).into();
    let stream = Stream::from_iter(toks).map(eoi, |(t, s): (Token, SimpleSpan)| (t, s));
    match parser().parse(stream).into_result() {
        Ok(q) => Ok(q),
        Err(errs) => {
            let mut buf = Vec::new();
            for e in &errs {
                let span = *e.span();
                let msg = match e.reason() {
                    chumsky::error::RichReason::Custom(m) => m.clone(),
                    _ => {
                        let found = e
                            .found()
                            .map(token_display)
                            .unwrap_or_else(|| "end of input".to_string());
                        // Append the nearest-keyword hint (same as the plain
                        // message path) so the CLI/REPL caret diagnostic also
                        // suggests the intended keyword on a typo. On end of
                        // input, prefer the missing-FROM hint.
                        if e.found().is_none() {
                            if let Some(hint) = missing_from_hint(src) {
                                format!("unexpected {found} — {hint}")
                            } else {
                                format!("unexpected {found}")
                            }
                        } else if let Some(hint) = missing_by_hint(src) {
                            format!("unexpected {found} — {hint}")
                        } else if matches!(e.found(), Some(Token::Eq))
                            && double_eq_hint(src, span.start).is_some()
                        {
                            format!(
                                "unexpected {found} — {}",
                                double_eq_hint(src, span.start).unwrap()
                            )
                        } else if matches!(e.found(), Some(Token::LParen)) {
                            if let Some(hint) = order_by_aggregate_hint(src, span.start) {
                                format!("unexpected {found} — {hint}")
                            } else {
                                match unknown_call_hint(src, span.start) {
                                    Some(callee) => {
                                        format!("unexpected {found} — did you mean `{callee}`?")
                                    }
                                    None => format!("unexpected {found}"),
                                }
                            }
                        } else {
                            match suggest_for_found(e.found()) {
                                Some(s) => format!("unexpected {found} — did you mean `{s}`?"),
                                None => format!("unexpected {found}"),
                            }
                        }
                    }
                };
                let mut out = Vec::new();
                Report::build(ReportKind::Error, ("query", span.into_range()))
                    .with_message(&msg)
                    .with_label(
                        Label::new(("query", span.into_range()))
                            .with_message(&msg)
                            .with_color(Color::Red),
                    )
                    .finish()
                    .write(("query", Source::from(src)), &mut out)
                    .ok();
                buf.push(String::from_utf8_lossy(&out).into_owned());
            }
            Err(buf.join("\n"))
        }
    }
}

/// Completion context extracted by parsing `src[..cursor_pos]` and inspecting
/// what the parser expected at the end.
pub struct CompletionContext {
    /// Labels from `.labelled("xyz")` parsers that were expected at the cursor.
    pub labels: Vec<String>,
    /// Specific `Token` variants that were expected at the cursor.
    pub tokens: Vec<Token>,
}

/// Parse `src[..cursor_pos]` and collect what the grammar expected next.
/// Returns an empty context on tokenisation failure.
pub fn parse_for_complete(src: &str, cursor_pos: usize) -> CompletionContext {
    let prefix = &src[..cursor_pos.min(src.len())];
    let toks = match tokenize_spanned(prefix) {
        Ok(t) => t,
        Err(_) => {
            return CompletionContext {
                labels: vec![],
                tokens: vec![],
            };
        }
    };
    let eoi_span: SimpleSpan = (cursor_pos..cursor_pos).into();
    let stream = Stream::from_iter(toks).map(eoi_span, |(t, s)| (t, s));
    let (_output, errors) = parser().parse(stream).into_output_errors();

    let mut labels: Vec<String> = Vec::new();
    let mut tokens: Vec<Token> = Vec::new();
    for err in &errors {
        // Only look at errors at or near the end of input
        if err.span().end + 1 < cursor_pos {
            continue;
        }
        for pat in err.expected() {
            match pat {
                chumsky::error::RichPattern::Label(s) => {
                    let s = s.to_string();
                    if !labels.contains(&s) {
                        labels.push(s);
                    }
                }
                chumsky::error::RichPattern::Token(t) if !tokens.contains(&**t) => {
                    tokens.push((**t).clone());
                }
                _ => {}
            }
        }
    }
    CompletionContext { labels, tokens }
}

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

    // ---------- helpers ----------

    fn toks(src: &str) -> Vec<Token> {
        tokenize_spanned(src)
            .unwrap_or_else(|e| panic!("tokenize failed for {src:?}: {e}"))
            .into_iter()
            .map(|(t, _)| t)
            .collect()
    }
    fn id(s: &str) -> Token {
        Token::Ident(s.into())
    }
    // AST builders
    fn field(s: &str) -> Attr {
        Attr::Field(s.into())
    }
    fn cmp(lhs: Attr, op: CompareOp, rhs: Value) -> Predicate {
        Predicate::Compare {
            lhs: Expr::Attr(lhs),
            op,
            rhs: Expr::Lit(rhs),
        }
    }
    fn and(a: Predicate, b: Predicate) -> Predicate {
        Predicate::And(Box::new(a), Box::new(b))
    }
    fn or(a: Predicate, b: Predicate) -> Predicate {
        Predicate::Or(Box::new(a), Box::new(b))
    }
    fn not(a: Predicate) -> Predicate {
        Predicate::Not(Box::new(a))
    }
    fn q(
        distinct: bool,
        select: Vec<SelectItem>,
        instanceof: bool,
        class_name: &str,
        alias: Option<&str>,
        where_: Option<Predicate>,
        limit: Option<u64>,
    ) -> Query {
        let n = select.len();
        Query {
            distinct,
            select,
            select_aliases: vec![None; n],
            retained_set: false,
            from: FromSource::Class(ClassSpec {
                instanceof,
                class_name: class_name.into(),
                is_regex: false,
            }),
            alias: alias.map(|s| s.into()),
            where_,
            order_by: None,
            limit,
            offset: None,
            union_branches: Vec::new(),
            union_limit: None,
            group_by: Vec::new(),
            having: None,
            intersect_branches: Vec::new(),
            except_branches: Vec::new(),
        }
    }
    fn star() -> Vec<SelectItem> {
        vec![SelectItem::Star]
    }
    fn attr_sel(a: Attr) -> SelectItem {
        SelectItem::Attr(a)
    }
    fn agg(func: AggFunc, arg: SelectItem) -> SelectItem {
        SelectItem::Aggregate {
            func,
            arg: Box::new(arg),
        }
    }

    #[test]
    fn parse_from_objects_numeric_id() {
        use super::FromSource;
        assert_eq!(
            super::parse("SELECT * FROM OBJECTS 1").unwrap().from,
            FromSource::Object(1)
        );
        assert_eq!(
            super::parse("SELECT * FROM OBJECTS 0x10").unwrap().from,
            FromSource::Object(16)
        );
        assert_eq!(
            super::parse("SELECT * FROM OBJECTS 0x0").unwrap().from,
            FromSource::Object(0)
        );
    }
    #[test]
    fn reject_from_objects_expr_and_instanceof_addr() {
        let e = super::parse("SELECT * FROM OBJECTS (1 + 2)").unwrap_err();
        assert!(
            e.to_string().contains("arithmetic/boolean FROM-OBJECTS"),
            "got: {e}"
        );
        let e = super::parse("SELECT * FROM INSTANCEOF 0x1").unwrap_err();
        assert!(
            e.to_string().to_lowercase().contains("instanceof"),
            "got: {e}"
        );
    }

    // ============================================================
    // Group 1 — token-stream cases (input → expected Vec<Token>)
    // 15 cases exercising each token kind + lexer edge cases.
    // ============================================================

    #[test]
    fn token_stream_cases() {
        let cases: Vec<(&str, Vec<Token>)> = vec![
            // 1: keywords + star + dotted ident + alias
            (
                "SELECT * FROM java.lang.String s",
                vec![
                    id("SELECT"),
                    Token::Star,
                    id("FROM"),
                    id("java.lang.String"),
                    id("s"),
                ],
            ),
            // 2: @attr, comparison, int, AND, ident, eq, string
            (
                "WHERE @usedHeapSize > 100 AND name = \"foo\"",
                vec![
                    id("WHERE"),
                    Token::At("usedHeapSize".into()),
                    Token::Gt,
                    Token::Int(100),
                    id("AND"),
                    id("name"),
                    Token::Eq,
                    Token::Str("foo".into()),
                ],
            ),
            // 3: all comparison operators
            (
                "= != < <= > >=",
                vec![
                    Token::Eq,
                    Token::Ne,
                    Token::Lt,
                    Token::Le,
                    Token::Gt,
                    Token::Ge,
                ],
            ),
            // 4: parens + comma
            ("( , )", vec![Token::LParen, Token::Comma, Token::RParen]),
            // 5: negative float lexes as Minus + Float (unary minus is grammar-level)
            ("-3.5", vec![Token::Minus, Token::Float(3.5)]),
            // 6: negative int lexes as Minus + Int (unary minus is grammar-level)
            ("-42", vec![Token::Minus, Token::Int(42)]),
            // 7: float before int (no split of 1.5)
            ("1.5", vec![Token::Float(1.5)]),
            // 8: trailing-dot float (regex allows empty fraction)
            ("7.", vec![Token::Float(7.0)]),
            // 9: glob class name with '*'
            ("com.acme.*", vec![id("com.acme.*")]),
            // 10: embedded glob
            ("com.a*b.C", vec![id("com.a*b.C")]),
            // 11: inner-class '$'
            ("Outer$Inner", vec![id("Outer$Inner")]),
            // 12: underscore leading ident
            ("_hidden", vec![id("_hidden")]),
            // 13: empty string literal
            ("\"\"", vec![Token::Str("".into())]),
            // 14: string with spaces preserved
            ("\"a b c\"", vec![Token::Str("a b c".into())]),
            // 15: @attr with dot/dollar in name
            ("@a.b$c", vec![Token::At("a.b$c".into())]),
            // 16: bare star vs glob-ident disambiguation
            ("* x*", vec![Token::Star, id("x*")]),
            // 17: whitespace (tabs/newlines) skipped
            (
                "SELECT\t*\nFROM\rC",
                vec![id("SELECT"), Token::Star, id("FROM"), id("C")],
            ),
            // 18: primitive array class name (trailing '[]')
            ("char[]", vec![id("char[]")]),
            // 19: object array class name (dotted + trailing '[]')
            ("java.lang.String[]", vec![id("java.lang.String[]")]),
            // 20: multi-dimensional array class name (repeated '[]')
            ("int[][]", vec![id("int[][]")]),
        ];
        for (src, expected) in cases {
            assert_eq!(toks(src), expected, "token stream mismatch for {src:?}");
        }
    }

    // ============================================================
    // Group 1b — arithmetic operator lexing
    // ============================================================

    #[test]
    fn lexes_arithmetic_operators() {
        let toks: Vec<Token> = crate::query::parse::tokenize_spanned("@a + 2 - 3 * 4 / 5")
            .unwrap()
            .into_iter()
            .map(|(t, _)| t)
            .collect();
        assert_eq!(
            toks,
            vec![
                Token::At("a".into()),
                Token::Plus,
                Token::Int(2),
                Token::Minus,
                Token::Int(3),
                Token::Star,
                Token::Int(4),
                Token::Divide,
                Token::Int(5),
            ]
        );
    }

    #[test]
    fn minus_before_number_is_operator_not_negative_literal() {
        let toks: Vec<Token> = crate::query::parse::tokenize_spanned("1-2")
            .unwrap()
            .into_iter()
            .map(|(t, _)| t)
            .collect();
        assert_eq!(toks, vec![Token::Int(1), Token::Minus, Token::Int(2)]);
    }

    // ============================================================
    // Group 2 — full-AST cases (input → expected Query)
    // 22 cases covering select/from/alias/where/limit combinations.
    // ============================================================

    #[test]
    fn ast_cases() {
        let cases: Vec<(&str, Query)> = vec![
            // 1: bare star + alias
            (
                "SELECT * FROM java.lang.String s",
                q(
                    false,
                    star(),
                    false,
                    "java.lang.String",
                    Some("s"),
                    None,
                    None,
                ),
            ),
            // 2: star, no alias
            (
                "SELECT * FROM C",
                q(false, star(), false, "C", None, None, None),
            ),
            // 3: DISTINCT
            (
                "SELECT DISTINCT name FROM C",
                q(
                    false,
                    vec![attr_sel(field("name"))],
                    false,
                    "C",
                    None,
                    None,
                    None,
                )
                .tap_distinct(),
            ),
            // 4: INSTANCEOF in FROM
            (
                "SELECT * FROM INSTANCEOF java.util.List",
                q(false, star(), true, "java.util.List", None, None, None),
            ),
            // 5: LIMIT
            (
                "SELECT * FROM C LIMIT 5",
                q(false, star(), false, "C", None, None, Some(5)),
            ),
            // 6: LIMIT 0 (zero allowed)
            (
                "SELECT * FROM C LIMIT 0",
                q(false, star(), false, "C", None, None, Some(0)),
            ),
            // 7: multiple select items
            (
                "SELECT @objectId, name, @usedHeapSize FROM C",
                q(
                    false,
                    vec![
                        attr_sel(Attr::ObjectId),
                        attr_sel(field("name")),
                        attr_sel(Attr::UsedHeapSize),
                    ],
                    false,
                    "C",
                    None,
                    None,
                    None,
                ),
            ),
            // 8: all built-in attrs
            (
                "SELECT @objectId, @objectAddress, @usedHeapSize, @displayName, @length FROM C",
                q(
                    false,
                    vec![
                        attr_sel(Attr::ObjectId),
                        attr_sel(Attr::ObjectAddress),
                        attr_sel(Attr::UsedHeapSize),
                        attr_sel(Attr::DisplayName),
                        attr_sel(Attr::Length),
                    ],
                    false,
                    "C",
                    None,
                    None,
                    None,
                ),
            ),
            // 9: classof(alias)
            (
                "SELECT classof(s) FROM java.lang.String s",
                q(
                    false,
                    vec![attr_sel(Attr::ClassOf)],
                    false,
                    "java.lang.String",
                    Some("s"),
                    None,
                    None,
                ),
            ),
            // 10: COUNT(*)
            (
                "SELECT COUNT(*) FROM C",
                q(
                    false,
                    vec![agg(AggFunc::Count, SelectItem::Star)],
                    false,
                    "C",
                    None,
                    None,
                    None,
                ),
            ),
            // 11: SUM(@usedHeapSize)
            (
                "SELECT SUM(@usedHeapSize) FROM C",
                q(
                    false,
                    vec![agg(AggFunc::Sum, attr_sel(Attr::UsedHeapSize))],
                    false,
                    "C",
                    None,
                    None,
                    None,
                ),
            ),
            // 12: MIN/MAX/AVG mixed
            (
                "SELECT MIN(x), MAX(x), AVG(x) FROM C",
                q(
                    false,
                    vec![
                        agg(AggFunc::Min, attr_sel(field("x"))),
                        agg(AggFunc::Max, attr_sel(field("x"))),
                        agg(AggFunc::Avg, attr_sel(field("x"))),
                    ],
                    false,
                    "C",
                    None,
                    None,
                    None,
                ),
            ),
            // 13: simple WHERE compare int
            (
                "SELECT * FROM C WHERE hash > 0",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(cmp(field("hash"), CompareOp::Gt, Value::Int(0))),
                    None,
                ),
            ),
            // 14: WHERE compare string
            (
                "SELECT * FROM C WHERE name = \"main\"",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(cmp(field("name"), CompareOp::Eq, Value::Str("main".into()))),
                    None,
                ),
            ),
            // 15: WHERE compare float
            (
                "SELECT * FROM C WHERE ratio <= 1.5",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(cmp(field("ratio"), CompareOp::Le, Value::Float(1.5))),
                    None,
                ),
            ),
            // 16: WHERE bool true
            (
                "SELECT * FROM C WHERE flag = true",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(cmp(field("flag"), CompareOp::Eq, Value::Bool(true))),
                    None,
                ),
            ),
            // 17: WHERE bool false + null (case-insensitive keywords)
            (
                "SELECT * FROM C WHERE a = FALSE AND b != NULL",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(and(
                        cmp(field("a"), CompareOp::Eq, Value::Bool(false)),
                        cmp(field("b"), CompareOp::Ne, Value::Null),
                    )),
                    None,
                ),
            ),
            // 18: precedence NOT/AND/OR
            (
                "SELECT * FROM C WHERE NOT a = 1 OR b = 2 AND c = 3",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(or(
                        not(cmp(field("a"), CompareOp::Eq, Value::Int(1))),
                        and(
                            cmp(field("b"), CompareOp::Eq, Value::Int(2)),
                            cmp(field("c"), CompareOp::Eq, Value::Int(3)),
                        ),
                    )),
                    None,
                ),
            ),
            // 19: parenthesized predicate overrides precedence
            (
                "SELECT * FROM C WHERE (a = 1 OR b = 2) AND c = 3",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(and(
                        or(
                            cmp(field("a"), CompareOp::Eq, Value::Int(1)),
                            cmp(field("b"), CompareOp::Eq, Value::Int(2)),
                        ),
                        cmp(field("c"), CompareOp::Eq, Value::Int(3)),
                    )),
                    None,
                ),
            ),
            // 20: predicate-level INSTANCEOF
            (
                "SELECT * FROM C WHERE s INSTANCEOF java.lang.String",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(Predicate::InstanceOf("java.lang.String".into())),
                    None,
                ),
            ),
            // 21: double negation
            (
                "SELECT * FROM C WHERE NOT NOT a = 1",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(not(not(cmp(field("a"), CompareOp::Eq, Value::Int(1))))),
                    None,
                ),
            ),
            // 22: everything at once — DISTINCT + INSTANCEOF + alias + WHERE + LIMIT
            (
                "SELECT DISTINCT @objectId, name FROM INSTANCEOF java.lang.Thread t \
                 WHERE @usedHeapSize >= 100 AND name != \"main\" LIMIT 5",
                q(
                    true,
                    vec![attr_sel(Attr::ObjectId), attr_sel(field("name"))],
                    true,
                    "java.lang.Thread",
                    Some("t"),
                    Some(and(
                        cmp(Attr::UsedHeapSize, CompareOp::Ge, Value::Int(100)),
                        cmp(field("name"), CompareOp::Ne, Value::Str("main".into())),
                    )),
                    Some(5),
                ),
            ),
            // 23: negative int literal in WHERE
            (
                "SELECT * FROM C WHERE delta = -7",
                q(
                    false,
                    star(),
                    false,
                    "C",
                    None,
                    Some(cmp(field("delta"), CompareOp::Eq, Value::Int(-7))),
                    None,
                ),
            ),
            // 24: nested aggregate arg (AGG over attr)
            (
                "SELECT COUNT(name) FROM C",
                q(
                    false,
                    vec![agg(AggFunc::Count, attr_sel(field("name")))],
                    false,
                    "C",
                    None,
                    None,
                    None,
                ),
            ),
        ];
        for (src, expected) in cases {
            let got = parse(src).unwrap_or_else(|e| panic!("parse failed for {src:?}: {}", e.0));
            assert_eq!(got, expected, "AST mismatch for {src:?}");
        }
    }

    // ============================================================
    // Group 3 — error cases: compact single-line message w/ line:col
    // 12 cases of malformed input.
    // ============================================================

    #[test]
    fn error_cases() {
        // Each entry: (src, substring the message must contain)
        let cases: Vec<(&str, &str)> = vec![
            ("", "empty query"),                            // 1 empty
            ("SELECT", "unexpected"),                       // 2 select only
            ("SELECT *", "unexpected"),                     // 3 missing FROM
            ("SELECT * FROM", "unexpected"),                // 4 FROM no class
            ("SELECT * FROM C bogus extra", "unexpected"),  // 5 trailing garbage
            ("SELECT @bogus FROM C", "bogus"),              // 6 unknown builtin attr
            ("SELECT * FROM C WHERE hash >", "unexpected"), // 7 dangling operator
            ("SELECT * FROM C WHERE hash", "unexpected"),   // 8 missing operator+rhs
            ("SELECT * FROM C LIMIT abc", "unexpected"),    // 9 non-int limit
            ("SELECT * FROM C LIMIT -1", "unexpected"),     // 10 negative limit rejected
            ("SELECT COUNT * FROM C", "unexpected"),        // 11 agg missing paren
            ("SELECT * FROM C WHERE (a = 1", "unexpected"), // 12 unbalanced paren
            ("SELECT , FROM C", "unexpected"),              // 13 empty select item
            ("SELECT * FROM C WHERE a = ", "unexpected"),   // 14 missing rhs value
            ("SELECT * FROM C WHERE a == 1", "unexpected"), // 15 bad operator ==
        ];
        for (src, needle) in cases {
            let err = parse(src)
                .err()
                .unwrap_or_else(|| panic!("expected parse error for {src:?}"))
                .0;
            assert!(!err.is_empty(), "empty error for {src:?}");
            assert!(
                !err.contains('\n'),
                "expected single-line error for {src:?}, got: {err}"
            );
            assert!(
                err.contains(needle),
                "error for {src:?} should contain {needle:?}, got: {err}"
            );
            // Compact messages carry a line:col (except tokenizer-offset errors
            // and the blank-query guard, which fires before any tokens exist).
            if !src.trim().is_empty() {
                assert!(
                    err.contains(':') || err.contains("offset"),
                    "error for {src:?} should carry a location, got: {err}"
                );
            }
        }
    }

    #[test]
    fn tokenizer_error_cases() {
        // Bytes logos can't lex: report an offset. `#` and `&` are not in any regex.
        for src in ["SELECT * FROM C WHERE a = #", "a & b", "SELECT ~ FROM C"] {
            let err = tokenize_spanned(src)
                .err()
                .unwrap_or_else(|| panic!("expected tokenize error for {src:?}"));
            assert!(err.contains("offset"), "got: {err}");
        }
        // Unterminated string: the lone `"` cannot start a valid string token.
        let err = tokenize_spanned("name = \"foo").unwrap_err();
        assert!(err.contains("offset"), "got: {err}");
    }

    #[test]
    fn single_quoted_string_hints_double_quotes() {
        // SQL users reach for single quotes; OQL strings use double quotes.
        let err = tokenize_spanned("@displayName = 'foo'").unwrap_err();
        assert!(
            err.contains("double quotes") && err.contains("\"foo\""),
            "expected a double-quote hint for 'foo', got: {err}"
        );
        // The single-char case is still a valid char literal (no error).
        assert!(
            tokenize_spanned("x = 'a'").is_ok(),
            "'a' is a valid char literal"
        );
    }

    // ---------- targeted unit tests ----------

    #[test]
    fn union_two_branches_parses() {
        let q =
            parse("SELECT * FROM java.lang.String UNION SELECT * FROM java.lang.Integer").unwrap();
        assert_eq!(q.union_branches.len(), 1);
        assert_eq!(q.union_branches[0].from.class_name(), "java.lang.Integer");
        assert!(
            q.union_branches[0].union_branches.is_empty(),
            "branches must be flat, not nested"
        );
    }
    #[test]
    fn union_three_branches_flat() {
        let q = parse("SELECT * FROM A UNION SELECT * FROM B UNION SELECT * FROM C").unwrap();
        assert_eq!(q.union_branches.len(), 2);
        assert_eq!(q.union_branches[0].from.class_name(), "B");
        assert_eq!(q.union_branches[1].from.class_name(), "C");
        assert!(q.union_branches.iter().all(|b| b.union_branches.is_empty()));
    }
    #[test]
    fn no_union_leaves_branches_empty() {
        assert!(parse("SELECT * FROM C").unwrap().union_branches.is_empty());
    }

    // ---------- top-level union-wide LIMIT (MAT gap #6) ----------

    #[test]
    fn union_wide_limit_parenthesized_form() {
        // MAT applies a trailing LIMIT to the WHOLE union. With a parenthesized
        // last branch, the trailing `LIMIT 5` sits at the top level and must land
        // in `union_limit`, NOT on any branch.
        let q =
            parse("SELECT * FROM java.lang.String UNION (SELECT * FROM java.lang.Object) LIMIT 5")
                .unwrap();
        assert_eq!(q.union_branches.len(), 1, "head + 1 branch");
        assert_eq!(
            q.union_limit,
            Some(5),
            "trailing LIMIT after `)` must be union-wide"
        );
        // The per-branch limit must be untouched (the LIMIT is not inside the parens).
        assert_eq!(q.limit, None, "head branch keeps no per-branch LIMIT");
        assert_eq!(q.union_branches[0].limit, None, "branch keeps no LIMIT");
    }

    #[test]
    fn union_wide_limit_bare_form_binds_union_wide() {
        // DECISION (pinned): the bare form `... UNION SELECT ... LIMIT 5` binds the
        // trailing LIMIT UNION-WIDE (to match Eclipse MAT), NOT to the last branch.
        // A bare branch has no closing token, so the LIMIT is parsed at the top
        // level after the branch tail and stored in `union_limit`.
        let q = parse("SELECT * FROM A UNION SELECT * FROM B LIMIT 5").unwrap();
        assert_eq!(q.union_branches.len(), 1);
        assert_eq!(
            q.union_limit,
            Some(5),
            "bare-form trailing LIMIT is union-wide"
        );
        assert_eq!(q.limit, None, "head keeps no per-branch LIMIT");
        assert_eq!(
            q.union_branches[0].limit, None,
            "last branch must NOT absorb the union-wide LIMIT"
        );
    }

    #[test]
    fn union_wide_limit_absent_is_none() {
        // No trailing LIMIT → union_limit stays None (old behavior, OVERALL cap only).
        let q = parse("SELECT * FROM A UNION SELECT * FROM B").unwrap();
        assert_eq!(q.union_limit, None);
    }

    #[test]
    fn single_query_union_limit_is_none() {
        // A non-union query never sets union_limit, even with a per-branch LIMIT.
        let q = parse("SELECT * FROM C LIMIT 5").unwrap();
        assert_eq!(q.union_limit, None, "single query has no union_limit");
        assert_eq!(q.limit, Some(5), "single-query LIMIT stays per-query");
    }

    #[test]
    fn union_wide_limit_zero_parses() {
        let q = parse("SELECT * FROM A UNION SELECT * FROM B LIMIT 0").unwrap();
        assert_eq!(q.union_limit, Some(0));
    }

    // ---------- PERCENTILE / MEDIAN aggregates ----------

    #[test]
    fn median_parses_as_single_arg_aggregate() {
        let q = parse("SELECT MEDIAN(@usedHeapSize) FROM C").unwrap();
        assert_eq!(
            q.select,
            vec![agg(AggFunc::Median, attr_sel(Attr::UsedHeapSize))]
        );
    }

    #[test]
    fn percentile_parses_with_integer_arg() {
        let q = parse("SELECT PERCENTILE(@usedHeapSize, 95) FROM C").unwrap();
        assert_eq!(
            q.select,
            vec![agg(AggFunc::Percentile(95), attr_sel(Attr::UsedHeapSize))]
        );
    }

    #[test]
    fn percentile_boundary_values_parse() {
        assert_eq!(
            parse("SELECT PERCENTILE(@usedHeapSize, 1) FROM C")
                .unwrap()
                .select,
            vec![agg(AggFunc::Percentile(1), attr_sel(Attr::UsedHeapSize))]
        );
        assert_eq!(
            parse("SELECT PERCENTILE(@usedHeapSize, 100) FROM C")
                .unwrap()
                .select,
            vec![agg(AggFunc::Percentile(100), attr_sel(Attr::UsedHeapSize))]
        );
    }

    #[test]
    fn percentile_out_of_range_is_actionable_error() {
        for bad in ["0", "101", "200"] {
            let src = format!("SELECT PERCENTILE(@usedHeapSize, {bad}) FROM C");
            let err = parse(&src).unwrap_err().0;
            assert!(
                err.contains("between 1 and 100"),
                "p={bad} should give an actionable range error, got: {err}"
            );
        }
    }

    #[test]
    fn percentile_missing_second_arg_is_error() {
        // A lone-arg PERCENTILE is not a valid MEDIAN alias; the comma+int are
        // required and its absence must not silently fall through to a field.
        assert!(parse("SELECT PERCENTILE(@usedHeapSize) FROM C").is_err());
    }

    #[test]
    fn percentile_case_insensitive() {
        let q = parse("SELECT percentile(@usedHeapSize, 50) FROM C").unwrap();
        assert_eq!(
            q.select,
            vec![agg(AggFunc::Percentile(50), attr_sel(Attr::UsedHeapSize))]
        );
    }

    #[test]
    fn union_branch_inner_limit_preserved_with_union_wide_limit() {
        // A parenthesized branch may carry its OWN LIMIT (inside the parens) AND
        // the whole union may carry a trailing union-wide LIMIT after the `)`.
        let q = parse("SELECT * FROM A UNION (SELECT * FROM B LIMIT 3) LIMIT 5").unwrap();
        assert_eq!(q.union_branches.len(), 1);
        assert_eq!(
            q.union_branches[0].limit,
            Some(3),
            "the branch's own LIMIT (inside parens) is preserved"
        );
        assert_eq!(q.union_limit, Some(5), "trailing LIMIT is union-wide");
    }

    // ---------- parenthesized UNION branches (MAT canonical form) ----------

    #[test]
    fn union_parenthesized_branch_parses() {
        let q = parse("SELECT * FROM java.lang.String UNION (SELECT * FROM java.lang.Integer)")
            .unwrap();
        assert_eq!(q.union_branches.len(), 1);
        let branch = &q.union_branches[0];
        assert_eq!(branch.from.class_name(), "java.lang.Integer");
        assert_eq!(branch.select, vec![SelectItem::Star]);
        assert!(
            branch.union_branches.is_empty(),
            "branches must be flat, not nested"
        );
    }

    #[test]
    fn union_parenthesized_branch_equals_bare_branch() {
        // A parenthesized branch unwraps to the SAME branch AST as the bare form.
        let bare =
            parse("SELECT * FROM java.lang.String UNION SELECT * FROM java.lang.Integer").unwrap();
        let paren = parse("SELECT * FROM java.lang.String UNION (SELECT * FROM java.lang.Integer)")
            .unwrap();
        assert_eq!(bare.union_branches, paren.union_branches);
    }

    #[test]
    fn union_bare_branch_still_parses() {
        // Regression: the bare (unparenthesized) branch form still works.
        let q = parse("SELECT * FROM A UNION SELECT * FROM B").unwrap();
        assert_eq!(q.union_branches.len(), 1);
        assert_eq!(q.union_branches[0].from.class_name(), "B");
    }

    #[test]
    fn union_multiple_parenthesized_branches() {
        let q = parse("SELECT * FROM A UNION (SELECT * FROM B) UNION (SELECT * FROM C)").unwrap();
        assert_eq!(q.union_branches.len(), 2);
        assert_eq!(q.union_branches[0].from.class_name(), "B");
        assert_eq!(q.union_branches[1].from.class_name(), "C");
        assert!(q.union_branches.iter().all(|b| b.union_branches.is_empty()));
    }

    #[test]
    fn union_mixed_bare_and_parenthesized_branches() {
        let q = parse("SELECT * FROM A UNION (SELECT * FROM B) UNION SELECT * FROM C").unwrap();
        assert_eq!(q.union_branches.len(), 2);
        assert_eq!(q.union_branches[0].from.class_name(), "B");
        assert_eq!(q.union_branches[1].from.class_name(), "C");
    }

    #[test]
    fn union_parenthesized_branch_with_where_and_limit() {
        // The full base_query grammar is available inside the branch parens.
        let q =
            parse("SELECT * FROM A UNION (SELECT * FROM B b WHERE b.hash > 0 LIMIT 5)").unwrap();
        assert_eq!(q.union_branches.len(), 1);
        let branch = &q.union_branches[0];
        assert_eq!(branch.from.class_name(), "B");
        assert!(branch.where_.is_some(), "branch WHERE must be populated");
        assert_eq!(branch.limit, Some(5), "branch LIMIT must be populated");
    }

    #[test]
    fn union_unterminated_parenthesized_branch_errors() {
        // Missing `)` after a parenthesized branch is an actionable parse error.
        let err = parse("SELECT * FROM A UNION (SELECT * FROM B")
            .unwrap_err()
            .0;
        assert!(
            !err.is_empty(),
            "expected non-empty error for unterminated UNION branch"
        );
    }

    #[test]
    fn from_subquery_parses() {
        let q = parse("SELECT * FROM (SELECT * FROM java.lang.String) x").unwrap();
        match &q.from {
            FromSource::Subquery(inner) => {
                assert_eq!(inner.from.class_name(), "java.lang.String");
                assert!(inner.union_branches.is_empty());
            }
            other => panic!("expected subquery FROM, got {other:?}"),
        }
        assert_eq!(q.alias.as_deref(), Some("x"));
    }

    #[test]
    fn from_class_still_parses_after_migration() {
        let q = parse("SELECT * FROM java.lang.String s").unwrap();
        assert_eq!(q.from.class_name(), "java.lang.String");
        assert!(!q.from.instanceof());
        assert!(q.from.as_subquery().is_none());
        assert_eq!(q.alias.as_deref(), Some("s"));
    }

    #[test]
    fn from_instanceof_class_sets_flag() {
        let q = parse("SELECT * FROM INSTANCEOF java.util.List").unwrap();
        assert!(
            q.from.instanceof(),
            "INSTANCEOF flag must survive migration"
        );
        assert_eq!(q.from.class_name(), "java.util.List");
    }

    // ---------- MAT gap #5: quoted/regex FROM class pattern ----------

    #[test]
    fn from_quoted_string_is_regex() {
        let q = parse(r#"SELECT * FROM "java.lang.*""#).unwrap();
        let spec = q.from.class_spec().expect("class source");
        assert_eq!(
            spec,
            &ClassSpec {
                instanceof: false,
                class_name: "java.lang.*".into(),
                is_regex: true,
            }
        );
    }

    #[test]
    fn from_quoted_alternation_regex() {
        let q = parse(r#"SELECT * FROM ".*Ab.*|java.lang.Runtime""#).unwrap();
        let spec = q.from.class_spec().expect("class source");
        assert!(spec.is_regex, "double-quoted FROM must set is_regex");
        assert_eq!(spec.class_name, ".*Ab.*|java.lang.Runtime");
    }

    #[test]
    fn from_bare_ident_is_not_regex() {
        let q = parse("SELECT * FROM java.lang.String").unwrap();
        let spec = q.from.class_spec().expect("class source");
        assert!(!spec.is_regex, "bare-ident FROM must NOT be regex");
    }

    #[test]
    fn from_bare_glob_is_not_regex() {
        let q = parse("SELECT * FROM com.acme.*").unwrap();
        let spec = q.from.class_spec().expect("class source");
        assert!(!spec.is_regex, "bare-glob FROM must NOT be regex");
        assert_eq!(spec.class_name, "com.acme.*");
    }

    #[test]
    fn instanceof_with_quoted_regex_is_rejected() {
        let err = parse(r#"SELECT * FROM INSTANCEOF "java.lang.*""#)
            .expect_err("INSTANCEOF with a quoted regex must be rejected");
        assert!(
            err.0.contains("INSTANCEOF") && err.0.to_lowercase().contains("bare class name"),
            "error must actionably explain INSTANCEOF needs a bare class name; got: {}",
            err.0
        );
    }

    #[test]
    fn instanceof_with_bare_ident_still_valid() {
        let q = parse("SELECT * FROM INSTANCEOF java.util.List").unwrap();
        let spec = q.from.class_spec().expect("class source");
        assert!(spec.instanceof);
        assert!(!spec.is_regex);
    }

    #[test]
    fn from_quoted_regex_with_alias() {
        let q = parse(r#"SELECT * FROM "java\.lang\..*" s"#).unwrap();
        let spec = q.from.class_spec().expect("class source");
        assert!(spec.is_regex);
        assert_eq!(spec.class_name, r"java\.lang\..*");
        assert_eq!(q.alias.as_deref(), Some("s"));
    }

    #[test]
    fn refpath_two_hops_parses() {
        let q = parse("SELECT x.parent.name FROM Node x").unwrap();
        match &q.select[0] {
            SelectItem::Attr(Attr::RefPath { hops, tail, .. }) => {
                assert_eq!(hops, &vec!["parent".to_string()]);
                assert!(matches!(**tail, Attr::Field(ref f) if f == "name"));
            }
            other => panic!("expected RefPath, got {other:?}"),
        }
    }

    #[test]
    fn refpath_bare_single_segment_stays_field() {
        // `x.name` — one segment after alias-strip — is a plain field, not a RefPath.
        let q = parse("SELECT x.name FROM Node x").unwrap();
        match &q.select[0] {
            SelectItem::Attr(Attr::Field(f)) => assert_eq!(f, "name"),
            other => panic!("expected bare Field, got {other:?}"),
        }
    }

    #[test]
    fn refpath_without_alias_keeps_leading_segment() {
        // No alias bound: `a.b.c` has three segments, all real hops+tail.
        let q = parse("SELECT a.b.c FROM Node").unwrap();
        match &q.select[0] {
            SelectItem::Attr(Attr::RefPath { hops, tail, .. }) => {
                assert_eq!(hops, &vec!["a".to_string(), "b".to_string()]);
                assert!(matches!(**tail, Attr::Field(ref f) if f == "c"));
            }
            other => panic!("expected RefPath, got {other:?}"),
        }
    }

    #[test]
    fn refpath_in_where_parses() {
        let q = parse("SELECT * FROM Node x WHERE x.parent.id = 7").unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::Compare {
                lhs: Expr::Attr(Attr::RefPath { hops, tail, .. }),
                ..
            } => {
                assert_eq!(hops, &vec!["parent".to_string()]);
                assert!(matches!(**tail, Attr::Field(ref f) if f == "id"));
            }
            other => panic!("expected RefPath compare, got {other:?}"),
        }
    }

    #[test]
    fn union_inside_subquery_is_rejected() {
        // UNION is unreachable inside the parenthesized base_query, so the inner
        // UNION fails to parse (located error) rather than silently nesting.
        let err = parse("SELECT * FROM (SELECT * FROM A UNION SELECT * FROM B) x")
            .unwrap_err()
            .to_string();
        assert!(
            err.contains("unexpected"),
            "expected a located parse error, got: {err}"
        );
        assert!(
            err.contains(':'),
            "error should carry a line:col location, got: {err}"
        );
    }

    #[test]
    fn in_subquery_parses() {
        let q = parse("SELECT * FROM java.lang.String s WHERE @objectAddress IN (SELECT * FROM java.lang.Integer)").unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::InSubquery { lhs, inner } => {
                assert!(matches!(lhs, Attr::ObjectAddress));
                assert_eq!(inner.from.class_name(), "java.lang.Integer");
                assert!(inner.union_branches.is_empty());
            }
            other => panic!("expected InSubquery, got {other:?}"),
        }
    }

    #[test]
    fn in_subquery_combines_with_and() {
        // `IN (...)` composes as a normal primary inside a boolean predicate.
        let q = parse(
            "SELECT * FROM java.lang.String s WHERE hash > 0 AND @objectAddress IN (SELECT * FROM C)",
        )
        .unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::And(l, r) => {
                assert!(matches!(**l, Predicate::Compare { .. }));
                assert!(matches!(**r, Predicate::InSubquery { .. }));
            }
            other => panic!("expected AND(compare, InSubquery), got {other:?}"),
        }
    }

    #[test]
    fn in_subquery_on_object_id_parses() {
        let q =
            parse("SELECT * FROM C WHERE @objectId IN (SELECT @objectId FROM java.lang.Integer)")
                .unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::InSubquery { lhs, inner } => {
                assert!(matches!(lhs, Attr::ObjectId));
                assert_eq!(inner.from.class_name(), "java.lang.Integer");
            }
            other => panic!("expected InSubquery, got {other:?}"),
        }
    }

    #[test]
    fn union_inside_in_subquery_is_rejected() {
        // UNION is unreachable inside the parenthesized base_query, so a UNION
        // within an IN-subquery is a located parse error, not a silent nesting.
        let err = parse(
            "SELECT * FROM C WHERE @objectAddress IN (SELECT * FROM A UNION SELECT * FROM B)",
        )
        .unwrap_err()
        .to_string();
        assert!(
            err.contains("unexpected"),
            "expected a located parse error, got: {err}"
        );
        assert!(
            err.contains(':'),
            "error should carry a line:col location, got: {err}"
        );
    }

    #[test]
    fn parse_dominators_attr() {
        let q = parse("SELECT dominators(s) FROM java.lang.String s").unwrap();
        assert_eq!(q.select.len(), 1);
        match &q.select[0] {
            SelectItem::Attr(Attr::Dominators(v)) => assert_eq!(v, "s"),
            other => panic!("expected Attr::Dominators, got {other:?}"),
        }
    }
    #[test]
    fn parse_dominatorof_attr() {
        let q = parse("SELECT dominatorof(s) FROM java.lang.String s").unwrap();
        match &q.select[0] {
            SelectItem::Attr(Attr::DominatorOf(v)) => assert_eq!(v, "s"),
            other => panic!("expected Attr::DominatorOf, got {other:?}"),
        }
    }
    #[test]
    fn parse_dominators_requires_arg() {
        let err = parse("SELECT dominators() FROM java.lang.String s").unwrap_err();
        assert!(
            err.to_string().contains("dominators(x) requires"),
            "unexpected error: {err}"
        );
    }
    #[test]
    fn parse_dominatorof_requires_arg() {
        let err = parse("SELECT dominatorof() FROM java.lang.String s").unwrap_err();
        assert!(
            err.to_string().contains("dominatorof(x) requires"),
            "unexpected error: {err}"
        );
    }
    #[test]
    fn dominators_in_select_list_with_other_items() {
        // A dominator attr coexists with a plain attr in the projection list.
        let q = parse("SELECT @objectId, dominators(s) FROM java.lang.String s").unwrap();
        assert_eq!(q.select.len(), 2);
        assert!(matches!(&q.select[1], SelectItem::Attr(Attr::Dominators(v)) if v == "s"));
    }
    #[test]
    fn dominatorof_report_error_names_function() {
        // The caret-rendered report also carries the actionable custom message.
        let rep = parse_or_report("SELECT dominatorof() FROM C").unwrap_err();
        assert!(
            rep.contains("dominatorof(x) requires"),
            "report missing message: {rep}"
        );
    }

    // ---------- @inbounds / @outbounds + path(a, b) ----------

    #[test]
    fn parse_inbounds_attr() {
        let q = parse("SELECT @inbounds FROM C").unwrap();
        assert_eq!(q.select, vec![attr_sel(Attr::Inbounds)]);
    }
    #[test]
    fn parse_outbounds_attr() {
        let q = parse("SELECT @outbounds FROM C").unwrap();
        assert_eq!(q.select, vec![attr_sel(Attr::Outbounds)]);
    }
    #[test]
    fn inbounds_usable_in_where() {
        // Goes through the same `attr` parser, so it is a valid compare LHS.
        let q = parse("SELECT @objectId FROM C WHERE @inbounds > 0").unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::Compare { lhs, .. } => {
                assert_eq!(lhs.as_attr().expect("Expr::Attr"), &Attr::Inbounds)
            }
            other => panic!("expected compare on @inbounds, got {other:?}"),
        }
    }
    #[test]
    fn outbounds_usable_in_where() {
        let q = parse("SELECT @objectId FROM C WHERE @outbounds != 0").unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::Compare { lhs, .. } => {
                assert_eq!(lhs.as_attr().expect("Expr::Attr"), &Attr::Outbounds)
            }
            other => panic!("expected compare on @outbounds, got {other:?}"),
        }
    }

    #[test]
    fn parse_path_alias_and_class() {
        // `path(s, java.lang.Thread)`: bare `s` → Alias, dotted → Class.
        let q = parse("SELECT path(s, java.lang.Thread) FROM C s").unwrap();
        assert_eq!(
            q.select,
            vec![SelectItem::Path {
                from: PathOperand::Alias("s".into()),
                to: PathOperand::Class("java.lang.Thread".into()),
            }]
        );
    }
    #[test]
    fn parse_path_both_aliases() {
        // Two bare idents (no `.`, no `*`) → both Alias.
        let q = parse("SELECT path(a, b) FROM C").unwrap();
        assert_eq!(
            q.select,
            vec![SelectItem::Path {
                from: PathOperand::Alias("a".into()),
                to: PathOperand::Alias("b".into()),
            }]
        );
    }
    #[test]
    fn parse_path_both_classes() {
        let q = parse("SELECT path(java.lang.String, java.lang.Integer) FROM C").unwrap();
        assert_eq!(
            q.select,
            vec![SelectItem::Path {
                from: PathOperand::Class("java.lang.String".into()),
                to: PathOperand::Class("java.lang.Integer".into()),
            }]
        );
    }
    #[test]
    fn parse_path_globbed_operand_is_class() {
        // A glob (`*`) marks a class pattern even without a `.`.
        let q = parse("SELECT path(s, com.acme.*) FROM C s").unwrap();
        assert_eq!(
            q.select,
            vec![SelectItem::Path {
                from: PathOperand::Alias("s".into()),
                to: PathOperand::Class("com.acme.*".into()),
            }]
        );
    }
    #[test]
    fn path_bare_field_without_parens_stays_field() {
        // `path` NOT followed by `(` is an ordinary field name (contextual ident).
        let q = parse("SELECT path FROM C").unwrap();
        assert_eq!(q.select, vec![attr_sel(field("path"))]);
    }
    #[test]
    fn path_dotted_field_without_parens_stays_field() {
        // `x.path` after alias-strip is a single-segment Field named `path`.
        let q = parse("SELECT x.path FROM C x").unwrap();
        assert_eq!(q.select, vec![attr_sel(field("path"))]);
    }
    #[test]
    fn path_coexists_with_other_select_items() {
        let q = parse("SELECT @objectId, path(s, C) FROM C s").unwrap();
        assert_eq!(
            q.select,
            vec![
                attr_sel(Attr::ObjectId),
                SelectItem::Path {
                    from: PathOperand::Alias("s".into()),
                    to: PathOperand::Alias("C".into()),
                },
            ]
        );
    }
    #[test]
    fn path_one_operand_is_error() {
        // `path(s)` — a single operand — must be a parse error, not silently accepted.
        let err = parse("SELECT path(s) FROM C s").unwrap_err().0;
        assert!(!err.is_empty(), "expected non-empty error for path(s)");
        assert!(
            !err.contains('\n'),
            "expected single-line error, got: {err}"
        );
    }
    #[test]
    fn inbounds_outbounds_in_attributes_const() {
        assert!(
            ATTRIBUTES.contains(&"@inbounds"),
            "ATTRIBUTES must include @inbounds"
        );
        assert!(
            ATTRIBUTES.contains(&"@outbounds"),
            "ATTRIBUTES must include @outbounds"
        );
    }

    #[test]
    fn parse_as_retained_set() {
        let q = parse("SELECT s AS RETAINED SET FROM java.lang.String s").unwrap();
        assert!(q.retained_set);
        assert_eq!(q.select.len(), 1);
    }
    #[test]
    fn parse_no_retained_set_default_false() {
        assert!(
            !parse("SELECT s FROM java.lang.String s")
                .unwrap()
                .retained_set
        );
    }
    #[test]
    fn parse_as_retained_missing_set() {
        let err = parse("SELECT s AS RETAINED FROM java.lang.String s").unwrap_err();
        assert!(
            err.to_string().contains("expected SET after 'AS RETAINED'"),
            "unexpected: {err}"
        );
    }
    #[test]
    fn parse_as_retained_set_with_where_and_limit() {
        // The modifier composes with the rest of the clause chain.
        let q = parse(
            "SELECT s AS RETAINED SET FROM java.lang.String s WHERE @retainedHeapSize > 0 LIMIT 5",
        )
        .unwrap();
        assert!(q.retained_set);
        assert!(q.where_.is_some());
        assert_eq!(q.limit, Some(5));
    }
    #[test]
    fn parse_as_retained_case_insensitive() {
        assert!(
            parse("SELECT s as retained set FROM C s")
                .unwrap()
                .retained_set
        );
    }

    #[test]
    fn parses_retained_heap_size_attr() {
        let q = parse("SELECT @retainedHeapSize FROM C").unwrap();
        assert_eq!(q.select, vec![SelectItem::Attr(Attr::RetainedHeapSize)]);
    }
    #[allow(dead_code)]
    fn retained_heap_alias_normalizes_to_retained_heap_size() {
        let q = parse("SELECT @retainedHeap FROM C").unwrap();
        assert_eq!(q.select, vec![SelectItem::Attr(Attr::RetainedHeapSize)]);
    }
    #[test]
    fn retained_heap_size_usable_in_where() {
        let q = parse("SELECT @objectId FROM C WHERE @retainedHeapSize > 1024").unwrap();
        assert!(q.where_.is_some());
    }

    #[test]
    fn parses_order_by_desc() {
        let q = parse("SELECT @objectId FROM C ORDER BY @retainedHeapSize DESC").unwrap();
        let ob = q.order_by.expect("ORDER BY parsed");
        assert_eq!(ob.key, Attr::RetainedHeapSize);
        assert_eq!(ob.dir, SortDir::Desc);
    }
    #[test]
    fn order_by_defaults_to_asc() {
        let q = parse("SELECT @objectId FROM C ORDER BY @usedHeapSize").unwrap();
        assert_eq!(q.order_by.unwrap().dir, SortDir::Asc);
    }
    #[test]
    fn order_by_before_limit() {
        let q = parse("SELECT @objectId FROM C ORDER BY @retainedHeapSize DESC LIMIT 10").unwrap();
        assert!(q.order_by.is_some());
        assert_eq!(q.limit, Some(10));
        assert_eq!(q.offset, None);
    }

    #[test]
    fn limit_with_offset() {
        let q = parse("SELECT @objectId FROM C LIMIT 5 OFFSET 10").unwrap();
        assert_eq!(q.limit, Some(5));
        assert_eq!(q.offset, Some(10));
    }

    #[test]
    fn offset_zero_is_accepted() {
        let q = parse("SELECT @objectId FROM C LIMIT 5 OFFSET 0").unwrap();
        assert_eq!(q.limit, Some(5));
        assert_eq!(q.offset, Some(0));
    }

    #[test]
    fn limit_without_offset_has_none_offset() {
        let q = parse("SELECT @objectId FROM C LIMIT 5").unwrap();
        assert_eq!(q.limit, Some(5));
        assert_eq!(q.offset, None);
    }
    #[test]
    fn no_order_by_is_none() {
        let q = parse("SELECT @objectId FROM C").unwrap();
        assert!(q.order_by.is_none());
    }

    #[test]
    fn span_tracks_byte_offsets() {
        let lg = tokenize_spanned("@usedHeapSize").expect("logos tokenizes");
        assert_eq!(lg.len(), 1);
        let (tok, span) = &lg[0];
        assert_eq!(*tok, Token::At("usedHeapSize".into()));
        assert_eq!((span.start, span.end), (0, 13));
    }

    #[test]
    fn line_col_basic() {
        assert_eq!(line_col("abc", 0), (1, 1));
        assert_eq!(line_col("abc", 2), (1, 3));
        assert_eq!(line_col("ab\ncd", 3), (2, 1));
        assert_eq!(line_col("ab\ncd", 4), (2, 2));
        assert_eq!(line_col("abc", 99), (1, 4)); // clamps past end
    }

    #[test]
    fn report_contains_caret_marker() {
        let rep = parse_or_report("SELCT * FROM C").unwrap_err();
        assert!(
            rep.contains("query:1:"),
            "expected caret location, got:\n{rep}"
        );
    }

    #[test]
    fn report_suggests_nearest_keyword_on_typo() {
        // The CLI/REPL caret diagnostic must carry the did-you-mean hint too,
        // not just the plain `parse` message the server uses.
        let rep = parse_or_report("SELCT * FROM C").unwrap_err();
        assert!(
            rep.contains("did you mean `SELECT`?"),
            "expected a SELECT suggestion in the report, got:\n{rep}"
        );
    }

    #[test]
    fn report_ok_on_valid_query() {
        assert!(parse_or_report("SELECT * FROM C").is_ok());
    }

    #[test]
    fn report_order_by_aggregate_hint_in_caret_diagnostic() {
        let rep = parse_or_report(
            "SELECT classof(x) AS class, COUNT(*) AS n \
             FROM INSTANCEOF java.lang.Object x \
             GROUP BY classof(x) \
             ORDER BY COUNT(*) DESC",
        )
        .unwrap_err();
        assert!(
            rep.contains("aggregate functions are not valid ORDER BY keys"),
            "expected aggregate hint in caret diagnostic, got:\n{rep}"
        );
    }

    #[test]
    fn report_tokenizer_error_surfaced() {
        let rep = parse_or_report("SELECT * FROM C WHERE a = #").unwrap_err();
        assert!(rep.contains("tokenize error"), "got: {rep}");
    }

    // The canonical keyword slices must stay in sync with the parser's actual
    // matching logic — otherwise the REPL completer (which sources them via
    // `completion_words`) would drift from what the grammar accepts.

    #[test]
    fn agg_funcs_const_matches_parser() {
        for &f in AGG_FUNCS {
            // PERCENTILE is a two-arg aggregate with its own parser production
            // (not routed through `agg_func`), so it is validated separately.
            if f.eq_ignore_ascii_case("PERCENTILE") {
                assert!(
                    agg_func(f).is_none(),
                    "PERCENTILE should not be a single-arg agg_func"
                );
                assert!(
                    parse(&format!("SELECT {f}(@usedHeapSize, 50) FROM C")).is_ok(),
                    "parser rejects two-arg aggregate {f:?}"
                );
                continue;
            }
            assert!(
                agg_func(f).is_some(),
                "agg_func rejects declared AGG_FUNC {f:?}"
            );
            // ...and the query actually parses as an aggregate.
            assert!(
                parse(&format!("SELECT {f}(*) FROM C")).is_ok(),
                "parser rejects aggregate {f:?}"
            );
        }
    }

    #[test]
    fn reserved_const_matches_parser() {
        for &r in RESERVED {
            assert!(
                is_reserved(r),
                "is_reserved rejects declared RESERVED {r:?}"
            );
        }
    }

    #[test]
    fn attributes_const_all_parse() {
        for &a in ATTRIBUTES {
            // Each declared @attribute must parse as a SELECT column.
            assert!(
                parse(&format!("SELECT {a} FROM C")).is_ok(),
                "parser rejects declared attribute {a:?}"
            );
        }
    }

    #[test]
    fn completion_words_covers_all_sources() {
        let words = completion_words();
        for set in [KEYWORDS, RESERVED, AGG_FUNCS, ATTRIBUTES, FUNCS] {
            for &w in set {
                assert!(words.contains(&w), "completion_words missing {w:?}");
            }
        }
        let unique: std::collections::HashSet<_> = words.iter().collect();
        assert_eq!(words.len(), unique.len(), "completion_words has duplicates");
    }

    // ============================================================
    // Group — alias-qualified @attr (MAT: `s.@objectId`)
    // ============================================================

    #[test]
    fn parse_prefixed_at_attr_single_select() {
        let q = parse("SELECT s.@objectId FROM java.lang.String s").expect("should parse");
        assert_eq!(q.select, vec![attr_sel(Attr::ObjectId)]);
    }

    #[test]
    fn parse_multi_dot_prefixed_at_attr_builds_refpath() {
        // `a.b.@objectId` lexes as `Ident("a.b.")` + `At`; the leading alias `a`
        // is stripped and the remaining `b` becomes a reference hop, with the
        // `@objectId` as the RefPath tail (previously the whole prefix was
        // dropped, silently discarding the `b` hop).
        let q = parse("SELECT a.b.@objectId FROM java.lang.Object a").expect("should parse");
        assert_eq!(
            q.select,
            vec![attr_sel(Attr::RefPath {
                hops: vec!["b".to_string()],
                tail: Box::new(Attr::ObjectId),
                role: RefRole::ProjectionOnly,
            })],
        );
    }

    #[test]
    fn parse_prefixed_at_attr_with_dotted_field() {
        let q = parse("SELECT s.@objectId, s.hash FROM java.lang.String s").expect("should parse");
        assert_eq!(
            q.select,
            vec![attr_sel(Attr::ObjectId), attr_sel(field("hash"))],
            "prefix dropped from @attr; `s.hash` alias-stripped to Field(\"hash\")"
        );
    }

    #[test]
    fn parse_value_length_builds_refpath_with_length_tail() {
        // `s.value.@length` must resolve the `value` ref hop and project the
        // walked-to array's @length (an identity attr tail on a RefPath). The
        // leading alias `s` is stripped; `value` remains as the single hop.
        let q = parse("SELECT s.value.@length FROM java.lang.String s").expect("should parse");
        assert_eq!(
            q.select,
            vec![attr_sel(Attr::RefPath {
                hops: vec!["value".to_string()],
                tail: Box::new(Attr::Length),
                role: RefRole::ProjectionOnly,
            })],
        );
    }

    #[test]
    fn parse_at_attr_tail_in_where_builds_refpath() {
        // A `@length` tail on a RefPath is also valid inside WHERE.
        let q = parse("SELECT s FROM java.lang.String s WHERE s.value.@length > 3")
            .expect("should parse");
        match q.where_.as_ref().expect("where") {
            Predicate::Compare {
                lhs: Expr::Attr(Attr::RefPath { hops, tail, .. }),
                ..
            } => {
                assert_eq!(hops, &vec!["value".to_string()]);
                assert!(matches!(**tail, Attr::Length));
            }
            other => panic!("expected RefPath compare, got {other:?}"),
        }
    }

    #[test]
    fn parse_bare_at_attr_still_works() {
        let q = parse("SELECT @objectId FROM java.lang.String").expect("should parse");
        assert_eq!(q.select, vec![attr_sel(Attr::ObjectId)]);
    }

    #[test]
    fn parse_prefixed_at_attr_mixed_columns() {
        let q = parse(
            "SELECT s.@objectAddress, s.@usedHeapSize, s.@retainedHeapSize FROM java.lang.Object s",
        )
        .expect("should parse");
        assert_eq!(
            q.select,
            vec![
                attr_sel(Attr::ObjectAddress),
                attr_sel(Attr::UsedHeapSize),
                attr_sel(Attr::RetainedHeapSize),
            ]
        );
    }

    #[test]
    fn parse_prefixed_at_attr_unknown_name_errors() {
        let err = parse("SELECT s.@bogus FROM X s").expect_err("unknown @attr should error");
        assert!(
            err.0.contains("unknown @attribute"),
            "actionable error expected, got: {}",
            err.0
        );
    }

    #[test]
    fn unknown_at_attr_suggests_nearest() {
        // A near-miss on a known attribute name gets a did-you-mean hint.
        let err = parse("SELECT @objectAdress FROM X").expect_err("typo @attr should error");
        assert!(
            err.0.contains("did you mean `@objectAddress`?"),
            "expected an @objectAddress suggestion, got: {}",
            err.0
        );
    }

    #[test]
    fn missing_from_clause_is_hinted() {
        // `SELECT @objectId` (no FROM) hits end-of-input; hint the missing FROM.
        let err = parse("SELECT @objectId").expect_err("missing FROM should error");
        assert!(
            err.0.contains("FROM"),
            "expected a missing-FROM hint, got: {}",
            err.0
        );
    }

    #[test]
    fn blank_query_gives_actionable_message() {
        // An empty or whitespace-only query should explain what OQL to supply,
        // not the cryptic "unexpected end of input".
        for src in ["", "   ", "\n\t "] {
            let err = parse(src).expect_err("blank query should error");
            assert!(
                err.0.contains("empty query") && err.0.contains("SELECT"),
                "expected an actionable blank-query message, got: {}",
                err.0
            );
        }
    }

    #[test]
    fn order_without_by_is_hinted() {
        // `ORDER @objectId` (missing BY) should hint `ORDER BY`.
        let err = parse("SELECT * FROM java.lang.Thread ORDER @objectId")
            .expect_err("ORDER without BY should error");
        assert!(
            err.0.contains("ORDER BY"),
            "expected an ORDER BY hint, got: {}",
            err.0
        );
    }

    #[test]
    fn missing_by_hint_helper_is_word_bounded() {
        // Positive: ORDER present, no BY.
        assert!(missing_by_hint("SELECT * FROM C ORDER x").is_some());
        // Negative: ORDER BY present.
        assert!(missing_by_hint("SELECT * FROM C ORDER BY x").is_none());
        // Negative: no ORDER at all.
        assert!(missing_by_hint("SELECT * FROM C").is_none());
        // Negative: `order` only as a substring must not count.
        assert!(missing_by_hint("SELECT reorder FROM C").is_none());
    }

    #[test]
    fn group_by_is_now_supported() {
        // Previously rejected; now parses successfully (planner validates semantics).
        let q = super::parse(
            "SELECT @displayName, COUNT(*) FROM java.lang.Thread GROUP BY @displayName",
        )
        .expect("GROUP BY should parse successfully");
        assert_eq!(q.group_by.len(), 1);
    }

    #[test]
    fn suggestion_never_echoes_the_found_token() {
        // A found token that already equals its nearest candidate must NOT
        // produce "did you mean `BY`?" when the token IS `BY`.
        assert_eq!(suggest_for_found(Some(&Token::Ident("BY".into()))), None);
        // But a genuine typo still suggests.
        assert_eq!(
            suggest_for_found(Some(&Token::Ident("SELCT".into()))).as_deref(),
            Some("SELECT")
        );
    }

    #[test]
    fn double_equals_is_hinted() {
        // `== ` is a common SQL-ism; OQL equality is a single `=`.
        let err = parse("SELECT * FROM java.lang.Thread WHERE @objectId == 1")
            .expect_err("== should error");
        assert!(
            err.0.contains('=') && err.0.to_lowercase().contains("equality"),
            "expected a `==` -> `=` hint, got: {}",
            err.0
        );
    }

    #[test]
    fn double_eq_hint_helper_detects_adjacent_eq() {
        // The byte offset of the SECOND `=` in `==` has a `=` immediately before.
        let src = "a == b";
        let second_eq = src.match_indices('=').nth(1).unwrap().0;
        assert!(double_eq_hint(src, second_eq).is_some());
        // A lone `=` (offset of the only `=`) has no preceding `=`.
        let src2 = "a = b";
        let eq = src2.find('=').unwrap();
        assert!(double_eq_hint(src2, eq).is_none());
    }

    #[test]
    fn missing_from_hint_helper_is_word_bounded() {
        // Positive: SELECT without FROM.
        assert!(missing_from_hint("SELECT @objectId").is_some());
        // Negative: FROM present.
        assert!(missing_from_hint("SELECT * FROM C").is_none());
        // Negative: `from` only as a substring of another word must not count.
        assert!(missing_from_hint("SELECT fromage FROM C").is_none());
        assert!(missing_from_hint("SELECT selection").is_some());
        // Negative: no SELECT at all.
        assert!(missing_from_hint("DELETE X").is_none());
    }

    #[test]
    fn unknown_function_call_suggests_nearest() {
        // `SUMM(` — a typo of the aggregate `SUM` — should suggest `SUM`
        // instead of the bare `unexpected LParen` that names the paren.
        let err = parse("SELECT SUMM(@usedHeapSize) FROM java.lang.Thread")
            .expect_err("SUMM is not a function");
        assert!(
            err.0.contains("did you mean") && err.0.contains("SUM"),
            "expected a SUM suggestion for SUMM(, got: {}",
            err.0
        );
    }

    #[test]
    fn unknown_call_hint_helper_finds_the_callee() {
        // The word immediately before `(` at the given byte offset is the callee.
        let src = "SELECT SUMM(x) FROM C";
        let lparen = src.find('(').unwrap();
        assert_eq!(unknown_call_hint(src, lparen).as_deref(), Some("SUM"));
        // A known function name yields no hint.
        let src2 = "SELECT COUNT(x) FROM C";
        let lp2 = src2.find('(').unwrap();
        assert!(unknown_call_hint(src2, lp2).is_none());
        // A wildly different name (no near match) yields no hint.
        let src3 = "SELECT zzzzzz(x) FROM C";
        let lp3 = src3.find('(').unwrap();
        assert!(unknown_call_hint(src3, lp3).is_none());
    }

    #[test]
    fn parse_prefixed_at_attr_in_where() {
        let q =
            parse("SELECT * FROM java.lang.String s WHERE s.@objectId = 0").expect("should parse");
        assert_eq!(
            q.where_,
            Some(cmp(Attr::ObjectId, CompareOp::Eq, Value::Int(0)))
        );
    }

    #[test]
    fn parse_prefixed_at_attr_alias_name_not_hardcoded() {
        let q = parse("SELECT obj.@objectId FROM java.lang.Object obj").expect("should parse");
        assert_eq!(q.select, vec![attr_sel(Attr::ObjectId)]);
    }

    #[test]
    fn parse_prefixed_at_attr_in_order_by() {
        let q = parse("SELECT * FROM java.lang.String s ORDER BY s.@retainedHeapSize DESC")
            .expect("should parse");
        assert_eq!(
            q.order_by.map(|o| (o.key, o.dir)),
            Some((Attr::RetainedHeapSize, SortDir::Desc))
        );
    }

    #[test]
    fn parse_like_operator() {
        let q = parse(r#"SELECT * FROM C WHERE name LIKE "m.*""#).unwrap();
        assert_eq!(
            q.where_.as_ref().unwrap(),
            &cmp(field("name"), CompareOp::Like, Value::Str("m.*".into()))
        );
    }

    #[test]
    fn parse_like_case_insensitive_keyword() {
        let q = parse(r#"SELECT * FROM C WHERE name like "m.*""#).unwrap();
        assert_eq!(
            q.where_.as_ref().unwrap(),
            &cmp(field("name"), CompareOp::Like, Value::Str("m.*".into()))
        );
    }

    #[test]
    fn parse_not_like_operator() {
        let q = parse(r#"SELECT * FROM C WHERE name NOT LIKE "m.*""#).unwrap();
        assert_eq!(
            q.where_.as_ref().unwrap(),
            &cmp(field("name"), CompareOp::NotLike, Value::Str("m.*".into()))
        );
    }

    #[test]
    fn parse_not_like_case_insensitive_keyword() {
        let q = parse(r#"SELECT * FROM C WHERE name not like "m.*""#).unwrap();
        assert_eq!(
            q.where_.as_ref().unwrap(),
            &cmp(field("name"), CompareOp::NotLike, Value::Str("m.*".into()))
        );
    }

    // CRITICAL DISAMBIGUATION: prefix `NOT` that wraps a whole predicate must
    // still parse as `Not(Compare{Eq})`, NOT be confused with the `NOT LIKE`
    // operator (which sits in operator position after an attribute LHS).
    #[test]
    fn parse_prefix_not_still_wraps_predicate() {
        let q = parse(r#"SELECT * FROM C WHERE NOT name = "x""#).unwrap();
        assert_eq!(
            q.where_.as_ref().unwrap(),
            &not(cmp(field("name"), CompareOp::Eq, Value::Str("x".into())))
        );
    }

    // Prefix NOT wrapping a LIKE compare — `NOT (name LIKE "x")`, distinct from
    // `name NOT LIKE "x"`. Both are valid but structurally different.
    #[test]
    fn parse_prefix_not_wrapping_like() {
        let q = parse(r#"SELECT * FROM C WHERE NOT name LIKE "m.*""#).unwrap();
        assert_eq!(
            q.where_.as_ref().unwrap(),
            &not(cmp(
                field("name"),
                CompareOp::Like,
                Value::Str("m.*".into())
            ))
        );
    }

    #[test]
    fn parse_like_combines_with_and() {
        let q = parse(r#"SELECT * FROM C WHERE name LIKE "m.*" AND id = 1"#).unwrap();
        assert_eq!(
            q.where_.as_ref().unwrap(),
            &and(
                cmp(field("name"), CompareOp::Like, Value::Str("m.*".into())),
                cmp(field("id"), CompareOp::Eq, Value::Int(1))
            )
        );
    }

    // small helper: fluent DISTINCT flip for the ast_cases table
    trait TapDistinct {
        fn tap_distinct(self) -> Self;
    }
    impl TapDistinct for Query {
        fn tap_distinct(mut self) -> Self {
            self.distinct = true;
            self
        }
    }

    // ============================================================
    // toString(s) parser AST tests (MAT gap #3)
    // ============================================================

    /// `SELECT toString(s) FROM java.lang.String s` must parse so the single
    /// SELECT item is exactly `SelectItem::ToString("s")`.
    #[test]
    fn parse_tostring_select_item() {
        let q = parse("SELECT toString(s) FROM java.lang.String s").unwrap();
        assert_eq!(q.select.len(), 1);
        match &q.select[0] {
            SelectItem::ToString(alias) => assert_eq!(alias, "s"),
            other => panic!("expected SelectItem::ToString(\"s\"), got {other:?}"),
        }
        assert_eq!(q.alias.as_deref(), Some("s"));
    }

    /// `SELECT * FROM java.lang.String s WHERE toString(s) LIKE "java.*"` must
    /// parse so the WHERE predicate is exactly `Compare { lhs: Attr::ToString("s"),
    /// op: CompareOp::Like, rhs: Value::Str("java.*") }`.
    #[test]
    fn parse_tostring_in_where_like() {
        let q =
            parse(r#"SELECT * FROM java.lang.String s WHERE toString(s) LIKE "java.*""#).unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::Compare { lhs, op, rhs } => {
                assert_eq!(
                    lhs.as_attr().expect("Compare lhs is Expr::Attr"),
                    &Attr::ToString("s".into()),
                    "WHERE LHS must be Attr::ToString(\"s\")"
                );
                assert_eq!(*op, CompareOp::Like, "operator must be Like");
                assert_eq!(
                    rhs.as_lit().expect("Compare rhs is Expr::Lit"),
                    &Value::Str("java.*".into()),
                    "RHS must be Str(\"java.*\")"
                );
            }
            other => panic!("expected Compare predicate, got {other:?}"),
        }
    }

    /// Pin the behavior of bare `toString` (without parens/arg) in a SELECT.
    /// The parser treats `toString` NOT followed by `(` as a plain field name
    /// `Attr::Field("toString")`, since the `dom_fn` combinator is contextual:
    /// it only fires when the identifier is immediately followed by `(`.
    #[test]
    fn parse_bare_tostring_without_parens_is_field_not_function() {
        let q = parse("SELECT toString FROM java.lang.String").unwrap();
        assert_eq!(q.select.len(), 1);
        match &q.select[0] {
            SelectItem::Attr(Attr::Field(name)) => assert_eq!(name, "toString"),
            other => panic!(
                "bare `toString` without parens must be Attr::Field(\"toString\"), got {other:?}"
            ),
        }
    }

    /// `toString()` — parens but NO alias argument — must be a parse error with
    /// an actionable message naming the function and the required argument form.
    #[test]
    fn parse_tostring_requires_alias_arg() {
        let err = parse("SELECT toString() FROM java.lang.String s").unwrap_err();
        assert!(
            err.to_string().contains("toString(x) requires"),
            "expected actionable error, got: {err}"
        );
    }

    /// `toString` is case-insensitive: `TOSTRING(s)` and `ToString(s)` both
    /// parse identically to `toString(s)`.
    #[test]
    fn parse_tostring_case_insensitive() {
        for variant in &["TOSTRING(s)", "ToString(s)", "tostring(s)"] {
            let src = format!("SELECT {variant} FROM java.lang.String s");
            let q = parse(&src).unwrap_or_else(|e| panic!("parse failed for {src:?}: {e}"));
            match &q.select[0] {
                SelectItem::ToString(alias) => assert_eq!(alias, "s", "for {variant}"),
                other => panic!("expected ToString for {variant}, got {other:?}"),
            }
        }
    }

    // ============================================================
    // Group — FROM OBJECTS keyword (MAT gap: 266 occurrences in OQLTest.java)
    // ============================================================

    /// `SELECT * FROM OBJECTS java.lang.String` must parse to the SAME AST as
    /// `SELECT * FROM java.lang.String` — OBJECTS is a no-op marker.
    #[test]
    fn from_objects_bare_class_parses() {
        let with_objects = parse("SELECT * FROM OBJECTS java.lang.String").unwrap();
        let without = parse("SELECT * FROM java.lang.String").unwrap();
        assert_eq!(
            with_objects.from, without.from,
            "FROM OBJECTS <class> must produce identical FROM as FROM <class>"
        );
    }

    /// The class_name and is_regex fields must be correct after OBJECTS.
    #[test]
    fn from_objects_class_name_and_is_regex() {
        let q = parse("SELECT * FROM OBJECTS java.lang.String").unwrap();
        let spec = q.from.class_spec().expect("expected class source");
        assert_eq!(
            spec.class_name, "java.lang.String",
            "class_name must be java.lang.String after OBJECTS"
        );
        assert!(
            !spec.is_regex,
            "bare-ident after OBJECTS must not be is_regex"
        );
        assert!(!spec.instanceof, "OBJECTS alone must not set instanceof");
    }

    /// `SELECT COUNT(*) FROM OBJECTS java.lang.String` — the most common MAT form.
    #[test]
    fn from_objects_count_star_parses() {
        let q = parse("SELECT COUNT(*) FROM OBJECTS java.lang.String").unwrap();
        assert_eq!(
            q.from.class_name(),
            "java.lang.String",
            "FROM OBJECTS class_name must be java.lang.String"
        );
    }

    /// `FROM OBJECTS` is case-insensitive: `from objects` and `FROM OBJECTS` both work.
    #[test]
    fn from_objects_case_insensitive() {
        for variant in &[
            "SELECT * FROM OBJECTS java.lang.String",
            "SELECT * FROM objects java.lang.String",
            "SELECT * FROM Objects java.lang.String",
        ] {
            let q = parse(variant).unwrap_or_else(|e| panic!("parse failed for {variant:?}: {e}"));
            assert_eq!(
                q.from.class_name(),
                "java.lang.String",
                "FROM {variant} must yield class java.lang.String"
            );
        }
    }

    /// `FROM OBJECTS ( <subquery> )` — OBJECTS before a parenthesized subquery.
    #[test]
    fn from_objects_subquery_parses() {
        let q = parse("SELECT * FROM OBJECTS ( SELECT * FROM java.lang.String )").unwrap();
        match &q.from {
            FromSource::Subquery(inner) => {
                assert_eq!(
                    inner.from.class_name(),
                    "java.lang.String",
                    "inner subquery must have class java.lang.String"
                );
            }
            other => panic!("expected FromSource::Subquery after OBJECTS, got {other:?}"),
        }
    }

    /// `FROM OBJECTS "java\.lang\..*"` — quoted/regex class after OBJECTS must still
    /// set is_regex = true.
    #[test]
    fn from_objects_quoted_regex_sets_is_regex() {
        let q = parse(r#"SELECT * FROM OBJECTS "java\.lang\..*""#).unwrap();
        let spec = q.from.class_spec().expect("expected class source");
        assert!(
            spec.is_regex,
            "quoted class after OBJECTS must set is_regex = true"
        );
        assert_eq!(spec.class_name, r"java\.lang\..*");
    }

    /// `FROM OBJECTS java.lang.String` with an alias — alias is correctly captured.
    #[test]
    fn from_objects_with_alias() {
        let q = parse("SELECT s FROM OBJECTS java.lang.String s").unwrap();
        assert_eq!(q.from.class_name(), "java.lang.String");
        assert_eq!(q.alias.as_deref(), Some("s"));
    }

    /// FROM OBJECTS INSTANCEOF: accepted as no-op (OBJECTS consumed first, then
    /// INSTANCEOF sets its flag). Eclipse MAT rejects this combination, but chumsky
    /// has no clean combinator path to reject it. This test pins the accepted behavior.
    #[test]
    fn from_objects_instanceof_is_accepted_as_noop() {
        let result = parse("SELECT * FROM OBJECTS INSTANCEOF java.lang.String");
        match result {
            Ok(q) => {
                assert_eq!(
                    q.from.class_name(),
                    "java.lang.String",
                    "FROM OBJECTS INSTANCEOF: class must be java.lang.String"
                );
                assert!(
                    q.from.instanceof(),
                    "FROM OBJECTS INSTANCEOF: instanceof flag must be set"
                );
            }
            Err(e) => {
                panic!(
                    "FROM OBJECTS INSTANCEOF currently accepted as no-op, \
                     but got parse error: {e}\n\
                     If you intentionally added rejection, update this test to \
                     assert the actionable error message."
                );
            }
        }
    }

    /// A bare `objects` used as a WHERE field must still work — RESERVED only blocks
    /// the alias slot, not predicate fields (which use `any_ident()`).
    #[test]
    fn objects_as_where_field_still_parses() {
        // `objects` used as a plain field name in WHERE is not affected by RESERVED.
        let q = parse("SELECT * FROM C WHERE objects = 1").unwrap();
        match q.where_.as_ref().unwrap() {
            Predicate::Compare { lhs, .. } => {
                assert_eq!(
                    lhs.as_attr().expect("Compare lhs is Expr::Attr"),
                    &Attr::Field("objects".into()),
                    "objects as a WHERE field must parse as Attr::Field(\"objects\")"
                );
            }
            other => panic!("expected Compare predicate, got {other:?}"),
        }
    }

    /// OBJECTS must appear in the RESERVED array — it should never be offered as
    /// a class-name or alias completion.
    #[test]
    fn objects_is_in_reserved() {
        assert!(
            RESERVED.iter().any(|&r| r.eq_ignore_ascii_case("OBJECTS")),
            "OBJECTS must be in RESERVED (guards alias-position and completion drift)"
        );
        assert!(
            is_reserved("OBJECTS"),
            "is_reserved(\"OBJECTS\") must return true"
        );
        assert!(
            is_reserved("objects"),
            "is_reserved is case-insensitive; must return true for \"objects\""
        );
    }

    /// `FROM OBJECTS` with a glob class pattern — should work identically to bare FROM.
    #[test]
    fn from_objects_glob_class_parses() {
        let with_objects = parse("SELECT * FROM OBJECTS java.util.*").unwrap();
        let without = parse("SELECT * FROM java.util.*").unwrap();
        assert_eq!(
            with_objects.from, without.from,
            "FROM OBJECTS glob must produce identical FROM as FROM glob"
        );
    }

    // ============================================================
    // Group N — AS <name> column alias tests
    // ============================================================

    /// 1. Bare-ident alias on a dotted-attr select item.
    #[test]
    fn alias_bare_ident_on_attr() {
        let q = parse("SELECT s.@objectId AS foo FROM java.lang.String s").unwrap();
        assert_eq!(q.select_aliases.len(), 1);
        assert_eq!(q.select_aliases[0].as_deref(), Some("foo"));
        assert_eq!(q.select, vec![SelectItem::Attr(Attr::ObjectId)]);
    }

    /// 2. Quoted alias name.
    #[test]
    fn alias_quoted_string() {
        let q = parse(r#"SELECT @usedHeapSize AS "size" FROM java.lang.String"#).unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("size"));
        assert_eq!(q.select, vec![SelectItem::Attr(Attr::UsedHeapSize)]);
    }

    /// 3. REGRESSION: `SELECT s AS RETAINED SET FROM ...` must NOT treat
    ///    RETAINED as an alias — retained_set must be true and select == [s].
    #[test]
    fn alias_as_retained_set_regression() {
        let q = parse("SELECT s AS RETAINED SET FROM java.lang.String s").unwrap();
        assert!(
            q.retained_set,
            "retained_set must be true when AS RETAINED SET is used"
        );
        // After the bare-alias fix, `s` (the FROM alias) rewrites to Star.
        assert_eq!(
            q.select,
            vec![SelectItem::Star],
            "select must be [Star] — bare alias s rewrites to Star"
        );
        assert_eq!(
            q.select_aliases[0], None,
            "item must carry no alias (RETAINED was not consumed as alias name)"
        );
    }

    /// 3b. Case-insensitive RETAINED guard: lower-case `as retained set` also
    ///     must not be treated as an alias.
    #[test]
    fn alias_as_retained_set_case_insensitive_regression() {
        let q = parse("SELECT s as retained set FROM java.lang.String s").unwrap();
        assert!(q.retained_set);
        assert_eq!(q.select_aliases[0], None);
    }

    /// 4. Alias on aggregate.
    #[test]
    fn alias_on_aggregate() {
        let q = parse("SELECT COUNT(*) AS n FROM java.lang.String").unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("n"));
        assert!(
            matches!(
                &q.select[0],
                SelectItem::Aggregate {
                    func: AggFunc::Count,
                    ..
                }
            ),
            "select must be COUNT(*)"
        );
    }

    /// 5. No alias → select_aliases entry is None; derived name unchanged.
    #[test]
    fn no_alias_means_none() {
        let q = parse("SELECT @objectId FROM java.lang.String").unwrap();
        assert_eq!(q.select_aliases.len(), 1);
        assert_eq!(q.select_aliases[0], None);
    }

    /// 6. Cross-phase attr (@retainedHeapSize) can still be aliased.
    #[test]
    fn alias_on_retained_heap_size() {
        let q = parse("SELECT @retainedHeapSize AS r FROM java.lang.String").unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("r"));
        assert_eq!(q.select, vec![SelectItem::Attr(Attr::RetainedHeapSize)]);
    }

    /// Multiple aliased columns in one SELECT.
    #[test]
    fn multiple_aliased_columns() {
        let q =
            parse("SELECT @objectId AS id, @usedHeapSize AS bytes FROM java.lang.String").unwrap();
        assert_eq!(q.select_aliases.len(), 2);
        assert_eq!(q.select_aliases[0].as_deref(), Some("id"));
        assert_eq!(q.select_aliases[1].as_deref(), Some("bytes"));
    }

    /// Mixed: first column has alias, second does not.
    #[test]
    fn mixed_aliased_and_plain_columns() {
        let q = parse("SELECT @objectId AS id, @usedHeapSize FROM java.lang.String").unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("id"));
        assert_eq!(q.select_aliases[1], None);
    }

    /// Alias combined with ORDER BY.
    #[test]
    fn alias_combined_with_order_by() {
        let q = parse(
            "SELECT @usedHeapSize AS bytes FROM java.lang.String ORDER BY @usedHeapSize DESC",
        )
        .unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("bytes"));
        assert!(q.order_by.is_some());
    }

    /// Alias after a `path(a,b)` item.
    #[test]
    fn alias_on_path_item() {
        let q = parse("SELECT path(s, java.lang.Object) AS p FROM java.lang.String s").unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("p"));
        assert!(matches!(&q.select[0], SelectItem::Path { .. }));
    }

    /// AS with a quoted name that looks like a reserved word.
    #[test]
    fn alias_quoted_reserved_word_name() {
        let q = parse(r#"SELECT * AS "FROM" FROM java.lang.String"#).unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("FROM"));
    }

    /// UNION: alias on head branch is present; tail branch alias is independent.
    #[test]
    fn alias_union_head_branch_preserved() {
        let q =
            parse("SELECT @objectId AS id FROM java.lang.String UNION SELECT @objectId FROM java.lang.Object")
                .unwrap();
        assert_eq!(q.select_aliases[0].as_deref(), Some("id"));
        // tail branch has no alias
        assert_eq!(q.union_branches[0].select_aliases[0], None);
    }

    /// select_aliases vec is always the same length as select vec.
    #[test]
    fn select_aliases_length_matches_select() {
        let queries = [
            "SELECT * FROM C",
            "SELECT @objectId, @usedHeapSize FROM C",
            "SELECT COUNT(*) AS n, SUM(@usedHeapSize) AS total FROM C",
        ];
        for oql in &queries {
            let q = parse(oql).unwrap();
            assert_eq!(
                q.select.len(),
                q.select_aliases.len(),
                "select_aliases length mismatch for: {oql}"
            );
        }
    }

    // ============================================================
    // Group: SELECT OBJECTS + leading AS RETAINED SET (Task 3)
    // ============================================================

    /// 1. SELECT OBJECTS <s> is a no-op projection marker: parses, select == [Star]
    ///    because `s` is the FROM alias and rewrites to Star.
    #[test]
    fn select_objects_is_noop() {
        let q = parse("SELECT OBJECTS s FROM java.lang.String s").unwrap();
        assert_eq!(
            q.select,
            vec![SelectItem::Star],
            "OBJECTS must be a no-op: select must be [Star] (bare alias rewrites to Star)"
        );
        assert!(!q.retained_set, "OBJECTS must not set retained_set");
        assert!(!q.distinct, "OBJECTS must not set distinct");
    }

    /// 2. Leading AS RETAINED SET: SELECT AS RETAINED SET s FROM ...
    #[test]
    fn leading_as_retained_set() {
        let q = parse("SELECT AS RETAINED SET s FROM java.lang.String s").unwrap();
        assert!(
            q.retained_set,
            "leading AS RETAINED SET must set retained_set"
        );
        // bare alias `s` rewrites to Star after the SW-1 fix
        assert_eq!(
            q.select,
            vec![SelectItem::Star],
            "select must be [Star] with leading retained (bare alias rewrites)"
        );
    }

    /// 3. SELECT OBJECTS produces the SAME select vec as SELECT (no OBJECTS).
    #[test]
    fn select_objects_same_as_select() {
        let with_objects = parse("SELECT OBJECTS s FROM java.lang.String s").unwrap();
        let without_objects = parse("SELECT s FROM java.lang.String s").unwrap();
        assert_eq!(
            with_objects.select, without_objects.select,
            "OBJECTS must be a pure no-op: selects must be identical"
        );
        assert_eq!(
            with_objects.retained_set, without_objects.retained_set,
            "OBJECTS must not change retained_set"
        );
        assert_eq!(
            with_objects.distinct, without_objects.distinct,
            "OBJECTS must not change distinct"
        );
    }

    /// 4. REGRESSION: trailing AS RETAINED SET still parses.
    #[test]
    fn trailing_as_retained_set_regression() {
        let q = parse("SELECT s AS RETAINED SET FROM java.lang.String s").unwrap();
        assert!(
            q.retained_set,
            "trailing AS RETAINED SET must still set retained_set"
        );
        // bare alias `s` rewrites to Star after the SW-1 fix
        assert_eq!(
            q.select,
            vec![SelectItem::Star],
            "select must be [Star] for trailing form (bare alias rewrites)"
        );
    }

    /// 5. Leading AS RETAINED without SET shares the actionable error message.
    #[test]
    fn leading_as_retained_missing_set_errors() {
        let err = parse("SELECT AS RETAINED s FROM java.lang.String s").unwrap_err();
        assert!(
            err.to_string().contains("expected SET after 'AS RETAINED'"),
            "leading missing-SET error must be actionable, got: {err}"
        );
    }

    /// 6. SELECT DISTINCT OBJECTS: both DISTINCT and OBJECTS together.
    #[test]
    fn select_distinct_objects() {
        let q = parse("SELECT DISTINCT OBJECTS s FROM java.lang.String s").unwrap();
        assert!(q.distinct, "distinct must be true");
        // bare alias `s` rewrites to Star after the SW-1 fix
        assert_eq!(
            q.select,
            vec![SelectItem::Star],
            "select must be [Star] with DISTINCT OBJECTS (bare alias rewrites)"
        );
        assert!(!q.retained_set);
    }

    /// 7. Leading AS RETAINED SET + OBJECTS before select list.
    #[test]
    fn leading_as_retained_set_objects() {
        let q = parse("SELECT AS RETAINED SET OBJECTS s FROM java.lang.String s").unwrap();
        assert!(
            q.retained_set,
            "retained_set must be true with leading AS RETAINED SET OBJECTS"
        );
        // bare alias `s` rewrites to Star after the SW-1 fix
        assert_eq!(q.select, vec![SelectItem::Star],);
    }

    /// 8. Case-insensitive: `select objects s from java.lang.String s` parses.
    #[test]
    fn select_objects_case_insensitive() {
        let q = parse("select objects s from java.lang.String s").unwrap();
        // bare alias `s` rewrites to Star after the SW-1 fix
        assert_eq!(q.select, vec![SelectItem::Star],);
    }

    /// 9. Leading + trailing both present: SELECT AS RETAINED SET s AS RETAINED SET FROM ...
    ///    Both set retained_set=true; combined result is true.
    #[test]
    fn leading_and_trailing_as_retained_set_both_true() {
        let q = parse("SELECT AS RETAINED SET s AS RETAINED SET FROM java.lang.String s")
            .expect("leading + trailing AS RETAINED SET must parse Ok");
        assert!(
            q.retained_set,
            "when both leading and trailing present, retained_set must be true"
        );
    }

    /// 10. OBJECTS before an aggregate: SELECT OBJECTS COUNT(*) FROM C
    ///     Pin the observed accept/reject behaviour.
    #[test]
    fn select_objects_before_aggregate() {
        let q = parse("SELECT OBJECTS COUNT(*) FROM java.lang.String")
            .expect("OBJECTS before aggregate must parse Ok");
        assert!(
            matches!(
                &q.select[0],
                SelectItem::Aggregate {
                    func: AggFunc::Count,
                    ..
                }
            ),
            "COUNT(*) after OBJECTS must still parse as aggregate"
        );
    }

    /// 11. SELECT OBJECTS * (star after OBJECTS).
    #[test]
    fn select_objects_star() {
        let q = parse("SELECT OBJECTS * FROM java.lang.String").unwrap();
        assert_eq!(q.select, vec![SelectItem::Star]);
    }

    /// 12. SELECT DISTINCT AS RETAINED SET: distinct + leading retained together.
    #[test]
    fn select_distinct_as_retained_set_leading() {
        let q = parse("SELECT DISTINCT AS RETAINED SET s FROM java.lang.String s").unwrap();
        assert!(q.distinct, "distinct must be true");
        assert!(q.retained_set, "retained_set must be true");
        // bare alias `s` rewrites to Star after the SW-1 fix
        assert_eq!(q.select, vec![SelectItem::Star],);
    }

    /// 13. SELECT AS RETAINED SET DISTINCT (wrong order) — pin reject behaviour.
    #[test]
    fn select_as_retained_set_distinct_wrong_order_pinned() {
        // DISTINCT must come before AS RETAINED SET in this grammar.
        // `SELECT AS RETAINED SET DISTINCT s` is not accepted.
        let r = parse("SELECT AS RETAINED SET DISTINCT s FROM java.lang.String s");
        // Pin: this does NOT parse successfully (DISTINCT is consumed as the select
        // expression item, or the grammar rejects it).
        // Either an error, or `distinct` is NOT set on the query.
        if let Ok(q) = r {
            assert!(
                !q.distinct,
                "DISTINCT after AS RETAINED SET should NOT set distinct flag (wrong order)"
            );
        }
        // If it errors, that is also correct behaviour — wrong order is not supported.
    }

    // ============================================================
    // Group: arithmetic expression grammar (Task 3)
    // ============================================================

    fn parse_one(s: &str) -> Query {
        super::parse(s).unwrap_or_else(|e| panic!("parse failed for {s:?}: {}", e.0))
    }

    #[test]
    fn arithmetic_precedence_mul_binds_tighter_than_add() {
        let q = parse_one("SELECT @usedHeapSize + @length * 2 FROM C");
        match &q.select[0] {
            SelectItem::Expr(e) => match e.as_ref() {
                Expr::Binary {
                    op: ArithOp::Add,
                    lhs,
                    rhs,
                } => {
                    assert!(matches!(lhs.as_ref(), Expr::Attr(_)));
                    assert!(matches!(
                        rhs.as_ref(),
                        Expr::Binary {
                            op: ArithOp::Mul,
                            ..
                        }
                    ));
                }
                other => panic!("expected Add root, got {other:?}"),
            },
            other => panic!("expected Expr item, got {other:?}"),
        }
    }

    #[test]
    fn arithmetic_parens_override_precedence() {
        let q = parse_one("SELECT (@usedHeapSize + @length) * 2 FROM C");
        match &q.select[0] {
            SelectItem::Expr(e) => assert!(matches!(
                e.as_ref(),
                Expr::Binary {
                    op: ArithOp::Mul,
                    ..
                }
            )),
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn unary_minus_on_attr_parses() {
        let q = parse_one("SELECT -@usedHeapSize FROM C");
        match &q.select[0] {
            SelectItem::Expr(e) => assert!(matches!(
                e.as_ref(),
                Expr::Unary {
                    op: UnaryOp::Neg,
                    ..
                }
            )),
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn lone_star_stays_select_star_not_multiply() {
        let q = parse_one("SELECT * FROM C");
        assert_eq!(q.select, vec![SelectItem::Star]);
    }

    #[test]
    fn bare_attr_folds_to_attr_item_not_expr() {
        let q = parse_one("SELECT @usedHeapSize FROM C");
        assert_eq!(q.select, vec![SelectItem::Attr(Attr::UsedHeapSize)]);
    }

    #[test]
    fn where_arithmetic_both_sides() {
        let q = parse_one("SELECT * FROM C WHERE @usedHeapSize / 8 > @length + 1");
        match q.where_.unwrap() {
            Predicate::Compare {
                lhs,
                op: CompareOp::Gt,
                rhs,
            } => {
                assert!(matches!(
                    lhs,
                    Expr::Binary {
                        op: ArithOp::Div,
                        ..
                    }
                ));
                assert!(matches!(
                    rhs,
                    Expr::Binary {
                        op: ArithOp::Add,
                        ..
                    }
                ));
            }
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn where_plain_compare_folds_to_leaf_exprs() {
        let q = parse_one("SELECT * FROM C WHERE @usedHeapSize > 100");
        match q.where_.unwrap() {
            Predicate::Compare {
                lhs,
                op: CompareOp::Gt,
                rhs,
            } => {
                assert_eq!(lhs, Expr::Attr(Attr::UsedHeapSize));
                assert_eq!(rhs, Expr::Lit(Value::Int(100)));
            }
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn negative_literal_folds_via_unary() {
        let q = parse_one("SELECT * FROM C WHERE delta = -5");
        match q.where_.unwrap() {
            Predicate::Compare { rhs, .. } => assert_eq!(rhs, Expr::Lit(Value::Int(-5))),
            other => panic!("got {other:?}"),
        }
    }

    #[test]
    fn like_rhs_must_be_string_literal() {
        let err = super::parse("SELECT * FROM C WHERE name LIKE @a + 1").unwrap_err();
        let msg = format!("{err:?}");
        assert!(
            msg.to_lowercase().contains("like"),
            "error should mention LIKE: {msg}"
        );
    }

    // ============================================================
    // Group: bare-alias rewrite in SELECT (SW-1 / SW-3 fix)
    // ============================================================

    /// `SELECT s FROM java.lang.String s` — the bare alias `s` must rewrite to
    /// `SelectItem::Star` (project the object itself), not `Attr::Field("s")`.
    #[test]
    fn bare_alias_in_select_rewrites_to_star() {
        let q = parse_one("SELECT s FROM java.lang.String s");
        assert_eq!(
            q.select,
            vec![SelectItem::Star],
            "bare alias s must rewrite to Star, got {:?}",
            q.select
        );
    }

    /// `SELECT COUNT(s) FROM java.lang.String s` — the aggregate arg `s` must
    /// also rewrite to `Star` so COUNT(s) becomes COUNT(*) semantics.
    #[test]
    fn bare_alias_in_count_arg_rewrites_to_star() {
        let q = parse_one("SELECT COUNT(s) FROM java.lang.String s");
        match &q.select[0] {
            SelectItem::Aggregate {
                func: AggFunc::Count,
                arg,
            } => {
                assert_eq!(
                    arg.as_ref(),
                    &SelectItem::Star,
                    "COUNT(s) arg must rewrite to Star, got {:?}",
                    arg
                );
            }
            other => panic!("expected COUNT aggregate, got {other:?}"),
        }
    }

    /// REGRESSION: `SELECT s.count FROM java.lang.String s` — dotted path must
    /// NOT be affected; it should normalize to `Attr::Field("count")`.
    #[test]
    fn dotted_alias_field_is_not_rewritten_to_star() {
        let q = parse_one("SELECT s.count FROM java.lang.String s");
        assert_eq!(
            q.select,
            vec![SelectItem::Attr(Attr::Field("count".into()))],
            "s.count must normalize to Field(\"count\"), got {:?}",
            q.select
        );
    }

    /// REGRESSION: `SELECT count FROM java.lang.String s` — a bare name that is
    /// NOT the alias must stay `Attr::Field("count")`.
    #[test]
    fn bare_non_alias_field_stays_field() {
        let q = parse_one("SELECT count FROM java.lang.String s");
        assert_eq!(
            q.select,
            vec![SelectItem::Attr(Attr::Field("count".into()))],
            "bare non-alias field must stay Field(\"count\"), got {:?}",
            q.select
        );
    }

    /// The alias-qualified `@attr` form (`s.@objectId`) still produces
    /// `Attr::ObjectId` — not affected by the bare-alias rewrite.
    #[test]
    fn alias_qualified_at_attr_still_works() {
        let q = parse_one("SELECT s.@objectId FROM java.lang.String s");
        assert_eq!(
            q.select,
            vec![SelectItem::Attr(Attr::ObjectId)],
            "s.@objectId must remain Attr::ObjectId, got {:?}",
            q.select
        );
    }

    /// Multiple columns: bare alias plus a real attr.  Only the alias column
    /// should become Star; the real attr stays untouched.
    #[test]
    fn bare_alias_mixed_columns_only_alias_rewrites() {
        let q = parse_one("SELECT s, @usedHeapSize FROM java.lang.String s");
        assert_eq!(q.select.len(), 2, "must have 2 columns");
        assert_eq!(
            q.select[0],
            SelectItem::Star,
            "first column (alias) must be Star"
        );
        assert_eq!(
            q.select[1],
            SelectItem::Attr(Attr::UsedHeapSize),
            "second column must be @usedHeapSize"
        );
    }

    /// SUM(s) on an object alias is nonsensical but must not crash; arg rewrites to Star.
    #[test]
    fn bare_alias_in_sum_arg_rewrites_to_star() {
        let q = parse_one("SELECT SUM(s) FROM java.lang.String s");
        match &q.select[0] {
            SelectItem::Aggregate {
                func: AggFunc::Sum,
                arg,
            } => {
                assert_eq!(
                    arg.as_ref(),
                    &SelectItem::Star,
                    "SUM(s) arg must rewrite to Star, got {:?}",
                    arg
                );
            }
            other => panic!("expected SUM aggregate, got {other:?}"),
        }
    }

    // ============================================================
    // Group N — numeric-literal grammar (hex/octal/long/char/float suffixes)
    // ============================================================

    #[test]
    fn lex_numeric_literal_forms() {
        use super::Token::*;
        let toks = |s: &str| {
            super::tokenize_spanned(s)
                .unwrap()
                .into_iter()
                .map(|(t, _)| t)
                .collect::<Vec<_>>()
        };
        assert_eq!(toks("100"), vec![Int(100)]);
        assert_eq!(toks("100L"), vec![Int(100)]);
        assert_eq!(toks("100l"), vec![Int(100)]);
        assert_eq!(toks("0xFF"), vec![Int(255)]);
        assert_eq!(toks("0Xff"), vec![Int(255)]);
        assert_eq!(toks("0xFFL"), vec![Int(255)]);
        assert_eq!(toks("0144"), vec![Int(100)]);
        assert_eq!(toks("0144L"), vec![Int(100)]);
        assert_eq!(toks("0"), vec![Int(0)]);
        assert_eq!(toks("08"), vec![Int(8)]); // lenient: not octal, plain decimal
        assert_eq!(toks("'a'"), vec![Int(97)]);
        assert_eq!(toks("1.5"), vec![Float(1.5)]);
        assert_eq!(toks("7."), vec![Float(7.0)]);
        assert_eq!(toks("1.5F"), vec![Float(1.5)]);
        assert_eq!(toks("2.0D"), vec![Float(2.0)]);
        assert_eq!(toks("5F"), vec![Float(5.0)]);
        assert_eq!(toks("5D"), vec![Float(5.0)]);
        assert_eq!(toks("1e5"), vec![Float(100000.0)]);
        assert_eq!(toks("1.5e-3"), vec![Float(0.0015)]);
        assert_eq!(toks("2E+2"), vec![Float(200.0)]);
    }

    #[test]
    fn lex_numeric_literal_errors() {
        assert!(super::tokenize_spanned("0xFFFFFFFFFFFFFFFFF").is_err()); // overflow
        assert!(super::tokenize_spanned("''").is_err()); // empty char
        assert!(super::tokenize_spanned("'ab'").is_err()); // multi-char
        assert!(super::tokenize_spanned("0xZZ").is_ok()); // 0 int + xZZ ident, not an error
    }

    #[test]
    fn lex_high_bit_address_roundtrips() {
        use super::Token::*;
        let toks = |s: &str| {
            super::tokenize_spanned(s)
                .unwrap()
                .into_iter()
                .map(|(t, _)| t)
                .collect::<Vec<_>>()
        };

        // High-bit address (> i64::MAX) lexes to one Int whose bits are the address.
        let t = toks("0xffff800012345678");
        assert_eq!(t.len(), 1);
        match t[0] {
            Int(x) => assert_eq!(x as u64, 0xffff_8000_1234_5678u64),
            ref other => panic!("expected Int, got {other:?}"),
        }

        // u64::MAX round-trips to -1i64 and back.
        let t = toks("0xffffffffffffffff");
        assert_eq!(t.len(), 1);
        match t[0] {
            Int(x) => assert_eq!(x as u64, u64::MAX),
            ref other => panic!("expected Int, got {other:?}"),
        }

        // Full FROM query with a high-bit address resolves to the exact address.
        assert_eq!(
            super::parse("SELECT * FROM OBJECTS 0xffff800012345678")
                .unwrap()
                .from,
            super::FromSource::Object(0xffff_8000_1234_5678)
        );

        // A literal beyond u64::MAX still errors.
        assert!(super::tokenize_spanned("999999999999999999999999999").is_err());
    }

    #[test]
    fn numeric_literals_in_arithmetic() {
        assert!(super::parse("SELECT 0xFF + 1 FROM java.lang.String").is_ok());
        assert!(super::parse("SELECT 2 * 1.5D FROM java.lang.String").is_ok());
        assert!(super::parse("SELECT -0144 FROM java.lang.String").is_ok());
    }

    #[test]
    fn parse_at_name_attribute() {
        assert!(super::parse("SELECT @name FROM java.lang.Thread").is_ok());
        assert!(
            super::parse(r#"SELECT * FROM java.lang.Thread WHERE @name = "java.lang.Thread""#)
                .is_ok()
        );
    }

    #[test]
    fn parse_at_name_aliases_displayname() {
        // `@name` must produce the SAME query AST as `@displayName`.
        let by_name = super::parse("SELECT @name FROM java.lang.Thread").unwrap();
        let by_display = super::parse("SELECT @displayName FROM java.lang.Thread").unwrap();
        assert_eq!(by_name, by_display);
    }

    #[test]
    fn parse_and_eval_tohex() {
        assert!(super::parse("SELECT toHex(@objectAddress) FROM java.lang.Thread LIMIT 1").is_ok());
        assert!(super::parse("SELECT toHex(255) FROM java.lang.Thread").is_ok());
    }

    // ============================================================
    // Group D1 — method-call postfix syntax: receiver.name(args)
    // ============================================================

    #[test]
    fn parse_method_postfix() {
        assert!(super::parse("SELECT s.getName() FROM java.lang.Thread s").is_ok());
        assert!(super::parse("SELECT i.intValue() FROM java.lang.Integer i").is_ok());
        assert!(super::parse("SELECT a.get(0) FROM java.util.ArrayList a").is_ok());
        assert!(super::parse("SELECT s.value.@length FROM java.lang.String s").is_ok());
        assert!(super::parse("SELECT i.intValue() * 2 FROM java.lang.Integer i").is_ok());
    }

    #[test]
    fn parse_method_postfix_ast_shape() {
        // s.getName() → Expr::Method { receiver: Attr::Field("s"), name: "getName", args: [] }
        let q = super::parse("SELECT s.getName() FROM java.lang.Thread s").unwrap();
        match &q.select[0] {
            SelectItem::Expr(e) => match e.as_ref() {
                Expr::Method {
                    receiver,
                    name,
                    args,
                } => {
                    assert!(
                        matches!(receiver.as_ref(), Expr::Attr(Attr::Field(f)) if f == "s"),
                        "expected Attr::Field(\"s\"), got {receiver:?}"
                    );
                    assert_eq!(name, "getName");
                    assert!(args.is_empty(), "expected no args, got {args:?}");
                }
                other => panic!("expected Expr::Method, got {other:?}"),
            },
            other => panic!("expected SelectItem::Expr, got {other:?}"),
        }

        // a.get(0) → Expr::Method { receiver: Attr::Field("a"), name: "get", args: [Lit(Int(0))] }
        let q = super::parse("SELECT a.get(0) FROM java.util.ArrayList a").unwrap();
        match &q.select[0] {
            SelectItem::Expr(e) => match e.as_ref() {
                Expr::Method {
                    receiver,
                    name,
                    args,
                } => {
                    assert!(
                        matches!(receiver.as_ref(), Expr::Attr(Attr::Field(f)) if f == "a"),
                        "expected Attr::Field(\"a\"), got {receiver:?}"
                    );
                    assert_eq!(name, "get");
                    assert_eq!(args.len(), 1, "expected 1 arg, got {args:?}");
                    assert!(
                        matches!(&args[0], Expr::Lit(Value::Int(0))),
                        "expected Int(0), got {:?}",
                        args[0]
                    );
                }
                other => panic!("expected Expr::Method, got {other:?}"),
            },
            other => panic!("expected SelectItem::Expr, got {other:?}"),
        }
    }

    #[test]
    fn parse_backing_array_attrs() {
        assert!(super::parse("SELECT @valueArray FROM java.lang.String").is_ok());
        assert!(super::parse("SELECT @referenceArray FROM java.util.ArrayList").is_ok());
    }

    // ============================================================
    // D4b — getKey()/getValue() lower to key/value ref-hops projecting
    // the resolved object's @objectAddress (identity).
    // ============================================================

    #[test]
    fn getkey_lowers_to_key_refpath_objectaddress_tail() {
        // `e.getKey()` normalizes to a one-hop RefPath: hops=["key"] (alias
        // stripped), tail=@objectAddress, projection-only. It must NOT stay an
        // Expr::Method — it rides the RefWalk late-resolution pipeline.
        let q = super::parse("SELECT e.getKey() FROM java.util.HashMap$Node e").unwrap();
        match &q.select[0] {
            SelectItem::Attr(Attr::RefPath { hops, tail, role }) => {
                assert_eq!(hops, &vec!["key".to_string()], "expected single 'key' hop");
                assert_eq!(
                    tail.as_ref(),
                    &Attr::ObjectAddress,
                    "getKey() tail must project the resolved object's address"
                );
                assert_eq!(*role, RefRole::ProjectionOnly);
            }
            other => panic!("expected SelectItem::Attr(RefPath), got {other:?}"),
        }
    }

    #[test]
    fn getvalue_lowers_to_value_refpath_objectaddress_tail() {
        let q = super::parse("SELECT e.getValue() FROM java.util.HashMap$Node e").unwrap();
        match &q.select[0] {
            SelectItem::Attr(Attr::RefPath { hops, tail, .. }) => {
                assert_eq!(hops, &vec!["value".to_string()]);
                assert_eq!(tail.as_ref(), &Attr::ObjectAddress);
            }
            other => panic!("expected SelectItem::Attr(RefPath), got {other:?}"),
        }
    }

    #[test]
    fn non_refhop_methods_are_not_lowered() {
        // getName()/intValue()/size() are scan-time emulated methods (D2/D3) and
        // must remain Expr::Method — they must NOT be lowered to a RefPath.
        for oql in [
            "SELECT s.getName() FROM java.lang.Thread s",
            "SELECT i.intValue() FROM java.lang.Integer i",
            "SELECT c.size() FROM java.util.ArrayList c",
        ] {
            let q = super::parse(oql).unwrap();
            assert!(
                matches!(&q.select[0], SelectItem::Expr(e) if matches!(e.as_ref(), Expr::Method { .. })),
                "method in `{oql}` was unexpectedly lowered away from Expr::Method: {:?}",
                q.select[0]
            );
        }
    }

    #[test]
    fn getkey_with_args_is_not_lowered() {
        // Only ZERO-arg getKey/getValue lower. A getKey(x) (unusual, but guard it)
        // stays an Expr::Method and flows through scan-time dispatch.
        let q = super::parse("SELECT e.getKey(1) FROM java.util.HashMap$Node e").unwrap();
        assert!(
            matches!(&q.select[0], SelectItem::Expr(e) if matches!(e.as_ref(), Expr::Method { .. })),
            "getKey(1) with an arg must not lower: {:?}",
            q.select[0]
        );
    }

    #[test]
    fn parse_gcroot_attrs() {
        assert!(parse("SELECT @GCRoots FROM java.lang.Thread").is_ok());
        assert!(parse("SELECT @GCRootInfo FROM java.lang.Thread").is_ok());
        assert!(parse("SELECT @info FROM java.lang.Thread").is_ok());
    }

    // ============================================================
    // Group: did-you-mean keyword suggestions in parse errors
    // ============================================================

    #[test]
    fn typo_keyword_suggests_correction() {
        let e = parse("SELCT x FROM C").unwrap_err();
        assert!(
            e.0.to_lowercase().contains("did you mean") && e.0.contains("SELECT"),
            "expected a SELECT suggestion, got: {:?}",
            e.0
        );
    }

    #[test]
    fn lev_basic_distances() {
        assert_eq!(lev("SELECT", "SELECT"), 0);
        assert_eq!(lev("SELCT", "SELECT"), 1);
        assert_eq!(lev("FRM", "FROM"), 1);
        assert_eq!(lev("abc", "xyz"), 3);
    }

    #[test]
    fn did_you_mean_finds_near_keyword() {
        assert_eq!(
            did_you_mean("SELCT", KEYWORDS.iter().copied()),
            Some("SELECT".to_string())
        );
        assert_eq!(
            did_you_mean("FRM", KEYWORDS.iter().copied()),
            Some("FROM".to_string())
        );
    }

    #[test]
    fn did_you_mean_ignores_far_tokens() {
        // A real class/identifier that is not close to any keyword must NOT trigger.
        assert_eq!(did_you_mean("java", KEYWORDS.iter().copied()), None);
    }

    #[test]
    fn no_suggestion_when_token_is_valid_identifier_far_from_keywords() {
        // A well-formed query fragment that fails for other reasons must not get a
        // spurious keyword suggestion appended.
        let e = parse("SELECT x FROM").unwrap_err();
        // "FROM" with nothing after -> unexpected end of input; found is None, no suggestion.
        assert!(
            !e.0.contains("did you mean"),
            "no spurious suggestion: {:?}",
            e.0
        );
    }

    // ============================================================
    // Group: GROUP BY and HAVING parsing
    // ============================================================

    #[test]
    fn parse_group_by_simple() {
        let q = super::parse(
            "SELECT @displayName, COUNT(*) FROM java.lang.Thread GROUP BY @displayName",
        )
        .unwrap();
        assert_eq!(q.group_by.len(), 1);
        assert!(matches!(
            &q.group_by[0],
            crate::query::ast::Expr::Attr(crate::query::ast::Attr::DisplayName)
        ));
        assert!(q.having.is_none());
    }

    #[test]
    fn parse_group_by_multi_key() {
        let q = super::parse(
            "SELECT @displayName, @usedHeapSize, COUNT(*) FROM java.lang.Thread \
             GROUP BY @displayName, @usedHeapSize",
        )
        .unwrap();
        assert_eq!(q.group_by.len(), 2);
    }

    #[test]
    fn parse_having() {
        let q = super::parse(
            "SELECT @displayName, COUNT(*) FROM java.lang.Thread \
             GROUP BY @displayName HAVING COUNT(*) > 5",
        )
        .unwrap();
        assert!(q.having.is_some());
    }

    #[test]
    fn parse_having_without_group_by_is_parsed() {
        // Parser accepts HAVING alone — plan_single validates it (Task 3).
        // So this must parse without error; the planner will reject it.
        // (If you prefer to reject in the parser, that's fine too, but then
        //  update the test accordingly and make sure the error message mentions HAVING.)
        // For now: assert it at least doesn't panic.
        let result = super::parse("SELECT COUNT(*) FROM java.lang.Thread HAVING COUNT(*) > 5");
        // Either Ok (parser accepts, planner validates) or Err with "HAVING" in message
        match result {
            Ok(q) => assert!(q.having.is_some()),
            Err(e) => assert!(e.0.to_lowercase().contains("having"), "got: {}", e.0),
        }
    }

    #[test]
    fn group_by_after_where() {
        let q = super::parse(
            "SELECT @displayName, COUNT(*) FROM java.lang.Thread \
             WHERE @usedHeapSize > 100 GROUP BY @displayName",
        )
        .unwrap();
        assert_eq!(q.group_by.len(), 1);
        assert!(q.where_.is_some());
    }

    #[test]
    fn parse_case_when_else() {
        let q = super::parse(
            r#"SELECT CASE WHEN @usedHeapSize > 1000 THEN "large" ELSE "small" END FROM java.lang.String"#,
        )
        .unwrap();
        assert_eq!(q.select.len(), 1);
        let item = &q.select[0];
        assert!(
            matches!(item, crate::query::ast::SelectItem::Expr(e)
                if matches!(e.as_ref(), crate::query::ast::Expr::Case { branches, else_, .. }
                    if branches.len() == 1 && else_.is_some())),
            "expected Case expr, got: {item:?}"
        );
    }

    #[test]
    fn parse_case_when_no_else() {
        let q = super::parse(
            r#"SELECT CASE WHEN @usedHeapSize > 100 THEN "big" END FROM java.lang.String"#,
        )
        .unwrap();
        let item = &q.select[0];
        assert!(
            matches!(item, crate::query::ast::SelectItem::Expr(e)
                if matches!(e.as_ref(), crate::query::ast::Expr::Case { else_, .. } if else_.is_none())),
            "expected Case with no else, got: {item:?}"
        );
    }

    #[test]
    fn parse_case_multi_when() {
        let q = super::parse(
            r#"SELECT CASE WHEN @usedHeapSize > 10000 THEN "xl" WHEN @usedHeapSize > 1000 THEN "lg" ELSE "sm" END FROM java.lang.String"#,
        )
        .unwrap();
        let item = &q.select[0];
        assert!(
            matches!(item, crate::query::ast::SelectItem::Expr(e)
                if matches!(e.as_ref(), crate::query::ast::Expr::Case { branches, .. } if branches.len() == 2)),
            "expected 2 branches, got: {item:?}"
        );
    }

    #[test]
    fn parse_coalesce() {
        let q = super::parse("SELECT COALESCE(@usedHeapSize, 0) FROM java.lang.String").unwrap();
        assert!(
            matches!(&q.select[0], crate::query::ast::SelectItem::Expr(e)
                if matches!(e.as_ref(), crate::query::ast::Expr::Coalesce(args) if args.len() == 2)),
            "got: {:?}",
            q.select[0]
        );
    }

    #[test]
    fn parse_nullif() {
        let q = super::parse("SELECT NULLIF(@usedHeapSize, 0) FROM java.lang.String").unwrap();
        assert!(
            matches!(&q.select[0], crate::query::ast::SelectItem::Expr(e)
                if matches!(e.as_ref(), crate::query::ast::Expr::NullIf { .. })),
            "got: {:?}",
            q.select[0]
        );
    }

    #[test]
    fn parse_between() {
        let q =
            super::parse("SELECT * FROM java.lang.String WHERE @usedHeapSize BETWEEN 10 AND 100")
                .unwrap();
        assert!(q.where_.is_some());
        assert!(
            matches!(&q.where_, Some(crate::query::ast::Predicate::And(_, _))),
            "BETWEEN should desugar to And, got: {:?}",
            q.where_
        );
    }

    #[test]
    fn parse_not_between() {
        let q = super::parse(
            "SELECT * FROM java.lang.String WHERE @usedHeapSize NOT BETWEEN 10 AND 100",
        )
        .unwrap();
        assert!(
            matches!(&q.where_, Some(crate::query::ast::Predicate::Or(_, _))),
            "NOT BETWEEN should desugar to Or(Lt, Gt), got: {:?}",
            q.where_
        );
    }

    #[test]
    fn parse_not_between_desugars_to_lt_gt() {
        use crate::query::ast::{CompareOp, Predicate};
        let q = super::parse(
            "SELECT * FROM java.lang.String s WHERE @usedHeapSize NOT BETWEEN 10 AND 100",
        )
        .unwrap();
        // NOT BETWEEN lo AND hi => Or(Lt(subj, lo), Gt(subj, hi))
        if let Some(Predicate::Or(lhs, rhs)) = &q.where_ {
            assert!(
                matches!(
                    lhs.as_ref(),
                    Predicate::Compare {
                        op: CompareOp::Lt,
                        ..
                    }
                ),
                "left branch should be Lt, got: {lhs:?}"
            );
            assert!(
                matches!(
                    rhs.as_ref(),
                    Predicate::Compare {
                        op: CompareOp::Gt,
                        ..
                    }
                ),
                "right branch should be Gt, got: {rhs:?}"
            );
        } else {
            panic!("NOT BETWEEN should produce Or, got: {:?}", q.where_);
        }
    }

    #[test]
    fn coalesce_zero_args_errors() {
        let err = super::parse("SELECT COALESCE() FROM java.lang.String")
            .expect_err("zero-arg COALESCE must error");
        assert!(
            err.0.contains("COALESCE") || err.0.to_lowercase().contains("coalesce"),
            "error must mention COALESCE, got: {}",
            err.0
        );
    }

    #[test]
    fn parse_in_value_list() {
        use crate::query::ast::{CompareOp, Predicate};
        let q = super::parse(
            r#"SELECT * FROM java.lang.String s WHERE toString(s) IN ("MONDAY", "TUESDAY")"#,
        )
        .unwrap();
        // Should desugar to OR chain of = compares
        assert!(
            matches!(&q.where_, Some(Predicate::Or(_, _))),
            "IN list should desugar to OR chain, got: {:?}",
            q.where_
        );
        // Two-element list → exactly one Or node
        if let Some(Predicate::Or(left, right)) = &q.where_ {
            assert!(matches!(
                left.as_ref(),
                Predicate::Compare {
                    op: CompareOp::Eq,
                    ..
                }
            ));
            assert!(matches!(
                right.as_ref(),
                Predicate::Compare {
                    op: CompareOp::Eq,
                    ..
                }
            ));
        }
    }

    #[test]
    fn parse_not_in_value_list() {
        use crate::query::ast::Predicate;
        let q = super::parse(
            r#"SELECT * FROM java.lang.String s WHERE toString(s) NOT IN ("MONDAY", "TUESDAY")"#,
        )
        .unwrap();
        // NOT IN desugars to AND chain of != compares
        assert!(
            matches!(&q.where_, Some(Predicate::And(_, _))),
            "NOT IN list should desugar to AND chain, got: {:?}",
            q.where_
        );
    }

    #[test]
    fn parse_exists() {
        let q = super::parse(
            "SELECT COUNT(*) FROM java.lang.String \
             WHERE EXISTS (SELECT * FROM java.lang.Thread)",
        )
        .unwrap();
        assert!(
            matches!(
                &q.where_,
                Some(crate::query::ast::Predicate::Exists { negated: false, .. })
            ),
            "got: {:?}",
            q.where_
        );
    }

    #[test]
    fn parse_not_exists() {
        let q = super::parse(
            "SELECT COUNT(*) FROM java.lang.String \
             WHERE NOT EXISTS (SELECT * FROM java.lang.Thread)",
        )
        .unwrap();
        assert!(
            matches!(
                &q.where_,
                Some(crate::query::ast::Predicate::Exists { negated: true, .. })
            ),
            "got: {:?}",
            q.where_
        );
    }

    #[test]
    fn parse_is_null_and_is_not_null() {
        use crate::query::ast::{CompareOp, Expr, Predicate, Value};
        let q = super::parse("SELECT * FROM java.lang.String s WHERE toString(s) IS NULL").unwrap();
        match &q.where_ {
            Some(Predicate::Compare {
                op: CompareOp::Eq,
                rhs,
                ..
            }) => {
                assert_eq!(rhs, &Expr::Lit(Value::Null), "IS NULL rhs must be null");
            }
            other => panic!("IS NULL should desugar to = null, got: {other:?}"),
        }
        let q2 =
            super::parse("SELECT * FROM java.lang.String s WHERE toString(s) IS NOT NULL").unwrap();
        match &q2.where_ {
            Some(Predicate::Compare {
                op: CompareOp::Ne,
                rhs,
                ..
            }) => {
                assert_eq!(rhs, &Expr::Lit(Value::Null), "IS NOT NULL rhs must be null");
            }
            other => panic!("IS NOT NULL should desugar to != null, got: {other:?}"),
        }
    }

    #[test]
    fn parse_intersect() {
        let q = super::parse(
            "SELECT @displayName FROM java.lang.Thread \
             INTERSECT \
             SELECT @displayName FROM java.lang.String",
        )
        .unwrap();
        assert_eq!(q.intersect_branches.len(), 1);
        assert!(q.except_branches.is_empty());
        assert!(q.union_branches.is_empty());
    }

    #[test]
    fn parse_except() {
        let q = super::parse(
            "SELECT @displayName FROM java.lang.Thread \
             EXCEPT \
             SELECT @displayName FROM java.lang.String",
        )
        .unwrap();
        assert_eq!(q.except_branches.len(), 1);
        assert!(q.intersect_branches.is_empty());
        assert!(q.union_branches.is_empty());
    }

    #[test]
    fn intersect_and_except_mixed_errors() {
        let err = super::parse(
            "SELECT @displayName FROM java.lang.Thread \
             INTERSECT SELECT @displayName FROM java.lang.String \
             EXCEPT SELECT @displayName FROM java.lang.Object",
        )
        .expect_err("mixing INTERSECT and EXCEPT must error");
        assert!(
            err.0.to_lowercase().contains("intersect") || err.0.to_lowercase().contains("except"),
            "error must mention INTERSECT or EXCEPT, got: {}",
            err.0
        );
    }

    #[test]
    fn parse_array_index() {
        let q = super::parse("SELECT s.value[0] FROM java.lang.String s").unwrap();
        let item = &q.select[0];
        assert!(
            matches!(
                item,
                crate::query::ast::SelectItem::Attr(crate::query::ast::Attr::ArrayIndex { .. })
            ),
            "expected ArrayIndex, got: {item:?}"
        );
    }

    #[test]
    fn parse_array_slice() {
        let q = super::parse("SELECT s.value[1:3] FROM java.lang.String s").unwrap();
        let item = &q.select[0];
        assert!(
            matches!(
                item,
                crate::query::ast::SelectItem::Attr(crate::query::ast::Attr::ArraySlice { .. })
            ),
            "expected ArraySlice, got: {item:?}"
        );
    }

    #[test]
    fn parse_array_slice_open_start() {
        let q = super::parse("SELECT s.value[:3] FROM java.lang.String s").unwrap();
        let item = &q.select[0];
        assert!(
            matches!(
                item,
                crate::query::ast::SelectItem::Attr(crate::query::ast::Attr::ArraySlice {
                    start: None,
                    ..
                })
            ),
            "expected open-start slice, got: {item:?}"
        );
    }

    #[test]
    fn parse_array_slice_open_end() {
        let q = super::parse("SELECT s.value[2:] FROM java.lang.String s").unwrap();
        let item = &q.select[0];
        assert!(
            matches!(
                item,
                crate::query::ast::SelectItem::Attr(crate::query::ast::Attr::ArraySlice {
                    end: None,
                    ..
                })
            ),
            "expected open-end slice, got: {item:?}"
        );
    }

    #[test]
    fn parse_error_uses_source_chars_not_debug_names() {
        let err = parse_or_report("[SELCT * FROM java.lang.String").unwrap_err();
        assert!(err.contains('['), "expected '[' in error, got: {err}");
        assert!(
            !err.contains("LBracket"),
            "expected no 'LBracket' in error, got: {err}"
        );
    }
}