Module query 

Query language: tokenizer, AST, and recursive descent parser.

Implements the grammar from the project doc’s “Notes → Query language grammar (v1)” section verbatim. AND-only per the 2026-04-19 decisions log entry — OR is deferred to v2.

This module owns only the parse step: &str → QueryNode. Translating a QueryNode into SQL and binding parameters is milestone 4’s executor. Resolving relative time ranges like last 2h against wall-clock time is also the executor’s job; the AST just carries the raw spec.

Grammar (from the doc, reproduced for reference)

query     := clause (AND clause)*
clause    := field OP value
           | field CONTAINS string
           | TIME_RANGE
field     := [a-zA-Z_][a-zA-Z0-9_.]*
OP        := "=" | "!=" | ">" | "<"
value     := string | number | bool
string    := '"' .* '"' | bare_word
TIME_RANGE := "last" duration | "since" datetime
duration  := number ("m" | "h" | "d")

Structs

Duration

A relative duration parsed from last <N><unit>.

QueryParseError

Parse error with a byte offset into the original input.

Enums

Clause

A single clause — the atomic unit a query is built from.

CompareOp

Comparison operator for field OP value clauses.

DurationUnit

QueryNode

The top-level query: one or more clauses joined by AND.

QueryValue

A literal value appearing on the right-hand side of a comparison.

Functions

parse

Parse a query string into a QueryNode.