evalhub_query/grammar.rs
1//! The `dsl-kit` grammar of a query and the parser derived from it.
2//!
3//! ```text
4//! query := { where?: filter, sort?: [sort], limit?: int, cursor?: string,
5//! expand?: [expand], version?: "latest" | "all" }
6//! filter := { and: [filter+] } | { or: [filter+] } | { not: filter } | leaf
7//! leaf := { path, op: scalar_op, value }
8//! | { path, op: "exists" }
9//! | { path, op: "any", match: { key: (value | { op, value }) ... } }
10//! scalar_op := eq | ne | gt | gte | lt | lte | in | prefix | contains
11//! sort := { path, dir: "asc" | "desc" }
12//! expand := relations | badges | fingerprints | changed
13//! ```
14//!
15//! The filter AST is declared once, as the `dsl-kit` enum [`Filter`], and
16//! from it come the conformance check, the typed builder, and the JSON
17//! Schema of the `where` value that `evalhub_schema::query` leaves open.
18//! `path` is a string at this stage; its meaning is assigned in
19//! [`crate::typecheck`].
20//!
21//! `any` with `match` is the one non-trivial construct. It applies to the
22//! array paths of a record (`results`, `relations`, `attachments`) and
23//! matches if any element satisfies every key in `match`; a key's value is
24//! either a literal (implicit `eq`) or `{ op, value }`. This is how
25//! `results` is filtered by metric and value at once without exposing array
26//! indices. An Eval's runs are not an array path: they are rows of their
27//! own, read through the run projection, whose table has no array paths
28//! (see [`crate::typecheck`]).
29//!
30//! The grammar is the same for both targets, record queries and the run
31//! projection; only the path table a request is checked against differs.
32//!
33//! # Two shapes of vocabulary, and which one is hand-written
34//!
35//! `dsl-kit`'s JSON front end reads the internally-tagged convention
36//! (`{"type": "And", "children": […]}`), while the wire format above is
37//! key-tagged (`{"and": […]}`). [`parse`] therefore lowers the wire JSON
38//! into the tagged shape before handing it to
39//! `dsl_kit_parse::serde_bridge`, and the lowering is the only place in the
40//! workspace that names a construct by hand. It distinguishes exactly five
41//! shapes — `and`, `or`, `not`, and the two leaf forms that carry no scalar
42//! value (`exists`, `any`) — because each is a different *node shape*, and
43//! a node shape is what a `dsl-kit` variant is.
44//!
45//! The **operator vocabulary** is not hand-written anywhere: `op` is a
46//! payload field of type [`ScalarOp`], which the derived builder
47//! deserialises through `serde`. Adding `matches` or `between` to the
48//! language is one variant on that enum plus its row in the type table;
49//! no parser arm changes. That is the property the crate doc claims, and
50//! it is worth stating precisely rather than loosely, because the looser
51//! claim ("no hand-written match anywhere") is not true of the lowering.
52//!
53//! # Why the payloads are `serde_json::Value`
54//!
55//! A leaf's `value` is any JSON scalar (or an array, for `in`), and a
56//! `match` term's value likewise. `dsl-kit` payload fields convert through
57//! `serde`, so [`serde_json::Value`] is a legal field type and keeps the
58//! grammar honest about what it does *not* decide: whether `0.2` suits
59//! `generation.temperature` is a question for the type check, which has the
60//! schema. The grammar's job is shape.
61
62use std::collections::BTreeMap;
63use std::fmt;
64use std::str::FromStr;
65
66use dsl_kit_core::{IdGen, NodeId};
67use dsl_kit_macros::{DslBuild, DslNode, DslSchema};
68use dsl_kit_parse::DslBuild as _;
69use dsl_kit_parse::serde_bridge;
70use dsl_kit_schema::DslSchema as _;
71use evalhub_schema::error::{ErrorCode, ErrorEntry};
72use serde::{Deserialize, Serialize};
73use serde_json::{Map, Value, json};
74
75/// The filter AST: what a `where` clause means, before any path has been
76/// given a meaning.
77///
78/// Every variant carries the `id: NodeId` that `dsl-kit` mints, which is
79/// what lets a diagnostic point at a node rather than at a byte range.
80#[derive(Debug, Clone, PartialEq, DslNode, DslSchema, DslBuild)]
81pub enum Filter {
82 /// Every child must match. `{"and": [...]}`.
83 And {
84 /// Node identity, minted by the builder.
85 id: NodeId,
86 /// The conjuncts.
87 children: Vec<Filter>,
88 },
89 /// At least one child must match. `{"or": [...]}`.
90 Or {
91 /// Node identity, minted by the builder.
92 id: NodeId,
93 /// The disjuncts.
94 children: Vec<Filter>,
95 },
96 /// The child must not match. `{"not": {...}}`.
97 Not {
98 /// Node identity, minted by the builder.
99 id: NodeId,
100 /// The negated filter.
101 child: Box<Filter>,
102 },
103 /// A scalar comparison. `{"path": …, "op": …, "value": …}`.
104 Compare {
105 /// Node identity, minted by the builder.
106 id: NodeId,
107 /// The query path, uninterpreted here.
108 path: String,
109 /// The operator.
110 op: ScalarOp,
111 /// The literal to compare against; an array for `in`.
112 value: Value,
113 },
114 /// The path has a value, `null` included. `{"path": …, "op": "exists"}`.
115 Exists {
116 /// Node identity, minted by the builder.
117 id: NodeId,
118 /// The query path, uninterpreted here.
119 path: String,
120 },
121 /// At least one element of an array path satisfies every term.
122 /// `{"path": …, "op": "any", "match": {…}}`.
123 Any {
124 /// Node identity, minted by the builder.
125 id: NodeId,
126 /// The array path, uninterpreted here.
127 path: String,
128 /// The terms, keyed by the element field they constrain.
129 terms: BTreeMap<String, MatchTerm>,
130 },
131}
132
133/// The scalar operators, declared once.
134///
135/// This enum *is* the operator vocabulary: the builder deserialises `op`
136/// into it, [`request_schema`] lists its spellings in the published JSON
137/// Schema, and [`crate::typecheck`] decides which types each one suits.
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
139#[serde(rename_all = "snake_case")]
140pub enum ScalarOp {
141 /// Equal.
142 Eq,
143 /// Not equal.
144 Ne,
145 /// Greater than.
146 Gt,
147 /// Greater than or equal.
148 Gte,
149 /// Less than.
150 Lt,
151 /// Less than or equal.
152 Lte,
153 /// One of a list.
154 In,
155 /// Starts with.
156 Prefix,
157 /// Contains.
158 Contains,
159}
160
161impl ScalarOp {
162 /// Every operator, in declaration order. Used to publish the
163 /// vocabulary without a second list.
164 pub const ALL: [ScalarOp; 9] = [
165 ScalarOp::Eq,
166 ScalarOp::Ne,
167 ScalarOp::Gt,
168 ScalarOp::Gte,
169 ScalarOp::Lt,
170 ScalarOp::Lte,
171 ScalarOp::In,
172 ScalarOp::Prefix,
173 ScalarOp::Contains,
174 ];
175
176 /// The wire spelling.
177 pub const fn as_str(self) -> &'static str {
178 match self {
179 ScalarOp::Eq => "eq",
180 ScalarOp::Ne => "ne",
181 ScalarOp::Gt => "gt",
182 ScalarOp::Gte => "gte",
183 ScalarOp::Lt => "lt",
184 ScalarOp::Lte => "lte",
185 ScalarOp::In => "in",
186 ScalarOp::Prefix => "prefix",
187 ScalarOp::Contains => "contains",
188 }
189 }
190}
191
192impl fmt::Display for ScalarOp {
193 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
194 f.write_str(self.as_str())
195 }
196}
197
198impl FromStr for ScalarOp {
199 type Err = UnknownOperator;
200
201 fn from_str(s: &str) -> Result<Self, Self::Err> {
202 ScalarOp::ALL
203 .into_iter()
204 .find(|op| op.as_str() == s)
205 .ok_or_else(|| UnknownOperator(s.to_string()))
206 }
207}
208
209/// A spelling that names no operator.
210#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
211#[error("unknown operator `{0}`")]
212pub struct UnknownOperator(pub String);
213
214/// One term of an `any` match: an operator (`eq` when the wire form was a
215/// bare literal) and the value to compare against.
216#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
217#[serde(deny_unknown_fields)]
218pub struct MatchTerm {
219 /// How to compare. Absent on the wire means `eq`.
220 #[serde(default = "MatchTerm::default_op")]
221 pub op: ScalarOp,
222 /// The literal to compare against.
223 pub value: Value,
224}
225
226impl MatchTerm {
227 const fn default_op() -> ScalarOp {
228 ScalarOp::Eq
229 }
230}
231
232impl FromStr for MatchTerm {
233 type Err = serde_json::Error;
234
235 /// Present so the term satisfies `dsl-kit`'s payload bound, which asks
236 /// for both `serde` and `FromStr` so the JSON and canonical-text front
237 /// ends cannot diverge. evalhub only uses the JSON one.
238 fn from_str(s: &str) -> Result<Self, Self::Err> {
239 serde_json::from_str(s)
240 }
241}
242
243/// The operators that change a leaf's *shape* rather than its comparison,
244/// and therefore name a `dsl-kit` variant instead of a [`ScalarOp`].
245const EXISTS_OP: &str = "exists";
246/// See [`EXISTS_OP`].
247const ANY_OP: &str = "any";
248
249/// Parse a `where` value into the filter AST.
250///
251/// Returns every structural problem it found, not just the first: a
252/// caller fixing a query should see the whole bag. Paths in the returned
253/// entries are JSON pointers into the *request* (`/where/and/1/op`), which
254/// this function tracks itself — `dsl-kit`'s JSON front end reports no
255/// position, because it reads a [`serde_json::Value`] and there is no byte
256/// offset left to report by then.
257pub fn parse(value: &Value) -> Result<Filter, Vec<ErrorEntry>> {
258 let mut errors = Vec::new();
259 let tagged = lower(value, "/where", &mut errors);
260 if !errors.is_empty() {
261 return Err(errors);
262 }
263
264 let schema = Filter::schema();
265 let tree = serde_bridge::from_json_value(&tagged, &schema)
266 .map_err(|e| diagnostics_to_entries(&e, "/where"))?;
267 Filter::from_parse_tree(&tree, &IdGen::new()).map_err(|e| diagnostics_to_entries(&e, "/where"))
268}
269
270/// Turn `dsl-kit` diagnostics into error entries. The location is always
271/// the clause as a whole, for the reason given on [`parse`]; the code is
272/// `schema`, because every one of them is a shape violation.
273fn diagnostics_to_entries(error: &dsl_kit_parse::BuildError, pointer: &str) -> Vec<ErrorEntry> {
274 error
275 .diagnostics
276 .iter()
277 .map(|d| ErrorEntry {
278 path: pointer.to_string(),
279 code: ErrorCode::Schema,
280 hint: Some(d.message.clone()),
281 })
282 .collect()
283}
284
285fn shape_error(pointer: &str, hint: impl Into<String>) -> ErrorEntry {
286 ErrorEntry {
287 path: pointer.to_string(),
288 code: ErrorCode::Schema,
289 hint: Some(hint.into()),
290 }
291}
292
293/// Lower one wire-shaped filter into `dsl-kit`'s tagged convention,
294/// recording shape problems against their JSON pointer.
295///
296/// On error the returned value is a placeholder; [`parse`] checks the
297/// error list before looking at it.
298fn lower(value: &Value, pointer: &str, errors: &mut Vec<ErrorEntry>) -> Value {
299 let Some(object) = value.as_object() else {
300 errors.push(shape_error(
301 pointer,
302 "a filter is an object: {\"and\": [...]}, {\"or\": [...]}, {\"not\": {...}} \
303 or {\"path\": ..., \"op\": ..., \"value\": ...}",
304 ));
305 return Value::Null;
306 };
307
308 // The three connectives are keyed by their name.
309 for (key, variant) in [("and", "And"), ("or", "Or")] {
310 if let Some(children) = object.get(key) {
311 if object.len() > 1 {
312 errors.push(shape_error(
313 pointer,
314 format!("`{key}` is the only key a `{key}` filter may carry"),
315 ));
316 return Value::Null;
317 }
318 let Some(items) = children.as_array() else {
319 errors.push(shape_error(
320 &format!("{pointer}/{key}"),
321 format!("`{key}` takes an array of filters"),
322 ));
323 return Value::Null;
324 };
325 let lowered: Vec<Value> = items
326 .iter()
327 .enumerate()
328 .map(|(i, child)| lower(child, &format!("{pointer}/{key}/{i}"), errors))
329 .collect();
330 return json!({ "type": variant, "children": lowered });
331 }
332 }
333 if let Some(child) = object.get("not") {
334 if object.len() > 1 {
335 errors.push(shape_error(
336 pointer,
337 "`not` is the only key a `not` filter may carry",
338 ));
339 return Value::Null;
340 }
341 let lowered = lower(child, &format!("{pointer}/not"), errors);
342 return json!({ "type": "Not", "child": lowered });
343 }
344
345 lower_leaf(object, pointer, errors)
346}
347
348fn lower_leaf(object: &Map<String, Value>, pointer: &str, errors: &mut Vec<ErrorEntry>) -> Value {
349 let Some(path) = object.get("path") else {
350 errors.push(shape_error(
351 pointer,
352 "a leaf filter needs a `path`; a connective needs `and`, `or` or `not`",
353 ));
354 return Value::Null;
355 };
356 let Some(path) = path.as_str() else {
357 errors.push(shape_error(
358 &format!("{pointer}/path"),
359 "`path` is a string",
360 ));
361 return Value::Null;
362 };
363 let Some(op) = object.get("op") else {
364 errors.push(shape_error(
365 pointer,
366 format!(
367 "a leaf filter needs an `op`: one of {}, `{EXISTS_OP}` or `{ANY_OP}`",
368 operator_list()
369 ),
370 ));
371 return Value::Null;
372 };
373 let Some(op) = op.as_str() else {
374 errors.push(shape_error(&format!("{pointer}/op"), "`op` is a string"));
375 return Value::Null;
376 };
377
378 match op {
379 EXISTS_OP => {
380 reject_extra_keys(object, &["path", "op"], pointer, errors);
381 json!({ "type": "Exists", "path": path })
382 }
383 ANY_OP => {
384 reject_extra_keys(object, &["path", "op", "match"], pointer, errors);
385 let Some(terms) = object.get("match") else {
386 errors.push(shape_error(
387 pointer,
388 "`any` needs a `match` object naming the element fields to constrain",
389 ));
390 return Value::Null;
391 };
392 let Some(terms) = terms.as_object() else {
393 errors.push(shape_error(
394 &format!("{pointer}/match"),
395 "`match` is an object",
396 ));
397 return Value::Null;
398 };
399 let lowered: Map<String, Value> = terms
400 .iter()
401 .map(|(key, term)| {
402 (
403 key.clone(),
404 lower_term(term, &format!("{pointer}/match/{key}"), errors),
405 )
406 })
407 .collect();
408 json!({ "type": "Any", "path": path, "terms": lowered })
409 }
410 _ => {
411 reject_extra_keys(object, &["path", "op", "value"], pointer, errors);
412 let Some(value) = object.get("value") else {
413 errors.push(shape_error(
414 pointer,
415 format!("`{op}` needs a `value`; only `{EXISTS_OP}` stands alone"),
416 ));
417 return Value::Null;
418 };
419 json!({ "type": "Compare", "path": path, "op": op, "value": value })
420 }
421 }
422}
423
424/// A `match` term is either a bare literal (meaning `eq`) or
425/// `{ op, value }`. Both are lowered to the explicit form, which is what
426/// [`MatchTerm`] deserialises from; `dsl-kit` hands each entry of a keyed
427/// scalar slot to `serde` verbatim.
428fn lower_term(term: &Value, pointer: &str, errors: &mut Vec<ErrorEntry>) -> Value {
429 match term.as_object() {
430 Some(object) if object.contains_key("op") || object.contains_key("value") => {
431 reject_extra_keys(object, &["op", "value"], pointer, errors);
432 if !object.contains_key("value") {
433 errors.push(shape_error(
434 pointer,
435 "a match term with an `op` also needs a `value`",
436 ));
437 return Value::Null;
438 }
439 json!({
440 "op": object.get("op").cloned().unwrap_or_else(|| json!("eq")),
441 "value": object.get("value"),
442 })
443 }
444 // Any other value — including an object that is plainly a literal —
445 // is the implicit-`eq` form.
446 _ => json!({ "op": "eq", "value": term }),
447 }
448}
449
450fn reject_extra_keys(
451 object: &Map<String, Value>,
452 allowed: &[&str],
453 pointer: &str,
454 errors: &mut Vec<ErrorEntry>,
455) {
456 for key in object.keys() {
457 if !allowed.contains(&key.as_str()) {
458 errors.push(shape_error(
459 &format!("{pointer}/{key}"),
460 format!("unknown key `{key}`; this filter takes {}", list(allowed)),
461 ));
462 }
463 }
464}
465
466fn list(items: &[&str]) -> String {
467 items
468 .iter()
469 .map(|i| format!("`{i}`"))
470 .collect::<Vec<_>>()
471 .join(", ")
472}
473
474fn operator_list() -> String {
475 ScalarOp::ALL
476 .iter()
477 .map(|op| format!("`{op}`"))
478 .collect::<Vec<_>>()
479 .join(", ")
480}
481
482/// The wire key a connective is spelled with, so that the type check can
483/// rebuild the JSON pointer of a nested filter without a second table of
484/// shape names. Leaves have no key of their own: they sit where their
485/// parent put them.
486pub(crate) fn wire_key(filter: &Filter) -> &'static str {
487 match filter {
488 Filter::And { .. } => "and",
489 Filter::Or { .. } => "or",
490 Filter::Not { .. } => "not",
491 Filter::Compare { .. } | Filter::Exists { .. } | Filter::Any { .. } => "",
492 }
493}
494
495/// The JSON Schema of a `where` value, for the OpenAPI document.
496///
497/// `evalhub_schema::query::QueryRequest` leaves `where` open because the
498/// filter's shape belongs to this crate; the server splices this schema in
499/// so a generated client sees the real thing.
500///
501/// The schema describes the *wire* shape, which is the inverse of the
502/// lowering in [`parse`]: `dsl-kit`'s [`dsl_kit_schema::NodeSchema`]
503/// describes the tagged shape, so it is read for the variant and field
504/// names rather than copied. What it cannot express is carried here
505/// instead: which keys pair with which operator. The operator list comes
506/// from [`ScalarOp::ALL`], so the published vocabulary cannot drift from
507/// the one the parser accepts.
508pub fn request_schema() -> schemars::Schema {
509 let node = Filter::schema();
510 // Read the leaf field names off the declared schema rather than
511 // spelling them again; if a variant is renamed the schema follows.
512 let compare = node
513 .variant("Compare")
514 .map(|v| v.fields.iter().map(|f| f.name.clone()).collect::<Vec<_>>())
515 .unwrap_or_default();
516 let path_key = compare
517 .iter()
518 .find(|f| *f == "path")
519 .cloned()
520 .unwrap_or_else(|| "path".to_string());
521 let value_key = compare
522 .iter()
523 .find(|f| *f == "value")
524 .cloned()
525 .unwrap_or_else(|| "value".to_string());
526 let ops: Vec<Value> = ScalarOp::ALL.iter().map(|op| json!(op.as_str())).collect();
527
528 let filter_ref = json!({ "$ref": "#/$defs/filter" });
529 let term = json!({
530 "description": "A literal (meaning `eq`), or an operator and a literal.",
531 "oneOf": [
532 { "type": ["string", "number", "boolean", "null"] },
533 {
534 "type": "object",
535 "properties": {
536 "op": { "enum": ops.clone() },
537 &value_key: true,
538 },
539 "required": [&value_key],
540 "additionalProperties": false,
541 },
542 ],
543 });
544
545 let document = json!({
546 "$ref": "#/$defs/filter",
547 "$defs": {
548 "filter": {
549 "description": "A filter: a connective or a leaf.",
550 "oneOf": [
551 {
552 "type": "object",
553 "properties": { "and": { "type": "array", "items": filter_ref } },
554 "required": ["and"],
555 "additionalProperties": false,
556 },
557 {
558 "type": "object",
559 "properties": { "or": { "type": "array", "items": filter_ref } },
560 "required": ["or"],
561 "additionalProperties": false,
562 },
563 {
564 "type": "object",
565 "properties": { "not": filter_ref },
566 "required": ["not"],
567 "additionalProperties": false,
568 },
569 {
570 "description": "A scalar comparison.",
571 "type": "object",
572 "properties": {
573 &path_key: { "type": "string" },
574 "op": { "enum": ops },
575 &value_key: true,
576 },
577 "required": [&path_key, "op", &value_key],
578 "additionalProperties": false,
579 },
580 {
581 "description": "The path has a value, `null` included.",
582 "type": "object",
583 "properties": {
584 &path_key: { "type": "string" },
585 "op": { "const": EXISTS_OP },
586 },
587 "required": [&path_key, "op"],
588 "additionalProperties": false,
589 },
590 {
591 "description": "At least one element of an array path satisfies every term.",
592 "type": "object",
593 "properties": {
594 &path_key: { "type": "string" },
595 "op": { "const": ANY_OP },
596 "match": { "type": "object", "additionalProperties": term },
597 },
598 "required": [&path_key, "op", "match"],
599 "additionalProperties": false,
600 },
601 ],
602 },
603 },
604 });
605 // `json!` of an object literal is always an object, and schemars builds
606 // a schema from one directly.
607 match document {
608 Value::Object(map) => schemars::Schema::from(map),
609 _ => schemars::Schema::default(),
610 }
611}