@tellaro/tql 1.4.3 → 2.0.0

package/dist/src/tokenizer.js

@@ -52,7 +52,6 @@ const l = [
   "not_all",
   "not_none"
 ], h = {
-  "==": "eq",
   "=": "eq",
   "!=": "ne",
   ">": "gt",
@@ -78,7 +77,11 @@ const l = [
   "!any": "not_any",
   "!all": "not_all",
   "!none": "not_none"
-}, d = ["AND", "OR", "NOT"], p = ["ANY", "ALL", "NONE"], k = [
+}, p = ["AND", "OR", "NOT"], b = {
+  "&&": "AND",
+  "||": "OR",
+  "!": "NOT"
+}, d = ["ANY", "ALL", "NONE"], k = [
   // String mutators
   "lowercase",
   "uppercase",
@@ -117,6 +120,14 @@ const l = [
   "min",
   "max"
 ], _ = [
+  "is_private",
+  "is_global",
+  "is_loopback",
+  "is_multicast",
+  "is_link_local"
+], A = new Set(
+  _
+), f = [
   // Counting
   "count",
   "unique_count",
@@ -145,7 +156,7 @@ const l = [
   "values",
   "unique",
   "distinct"
-], f = [
+], m = [
   "string",
   "str",
   "number",
@@ -160,8 +171,9 @@ const l = [
   "array",
   "list",
   "object",
-  "geo"
-], m = [
+  "geo",
+  "ip"
+], T = [
   "bar",
   "barchart",
   "horizontal_bar",
@@ -184,23 +196,23 @@ const l = [
   "nested_donut",
   "chord",
   "auto"
-], w = ["by", "as", "null", "true", "false", "stats", "top", "bottom"];
-class g {
+], g = ["by", "as", "null", "true", "false", "stats", "top", "bottom"];
+class w {
   input;
   position;
   line;
   column;
   tokens;
-  constructor(t) {
-    this.input = t ?? "", this.position = 0, this.line = 1, this.column = 1, this.tokens = [];
+  constructor(e) {
+    this.input = e ?? "", this.position = 0, this.line = 1, this.column = 1, this.tokens = [];
   }
   /**
    * Tokenize the entire input string
    */
   tokenize() {
     for (this.tokens = [], this.position = 0, this.line = 1, this.column = 1; !this.isAtEnd(); ) {
-      const t = this.scanToken();
-      t && this.tokens.push(t);
+      const e = this.scanToken();
+      e && this.tokens.push(e);
     }
     return this.tokens;
   }
@@ -210,42 +222,46 @@ class g {
   scanToken() {
     if (this.isWhitespace(this.peek()))
       return this.scanWhitespace();
-    const t = this.position, n = this.line, i = this.column, e = this.advance();
-    switch (e) {
+    const e = this.position, n = this.line, i = this.column, t = this.advance();
+    if ((t === "&" || t === "|") && this.peek() === t)
+      return this.advance(), this.makeToken("logicalOp", t + t, e, n, i);
+    switch (t) {
       case "(":
       case ")":
-        return this.makeToken("paren", e, t, n, i);
+        return this.makeToken("paren", t, e, n, i);
       case "[":
       case "]":
-        return this.makeToken("bracket", e, t, n, i);
+        return this.makeToken("bracket", t, e, n, i);
       case ",":
-        return this.makeToken("comma", e, t, n, i);
+        return this.makeToken("comma", t, e, n, i);
       case "|":
-        return this.makeToken("pipe", e, t, n, i);
+        return this.makeToken("pipe", t, e, n, i);
     }
-    return e === "=" && this.peek() === ">" ? (this.advance(), this.makeToken("arrow", "=>", t, n, i)) : e === ":" && this.peek() === ":" ? (this.advance(), this.makeToken("doubleColon", "::", t, n, i)) : e === '"' || e === "'" ? this.scanString(e, t, n, i) : this.isDigit(e) || e === "-" && this.isDigit(this.peek()) ? this.scanNumber(t, n, i) : this.isOperatorChar(e) ? this.scanSymbolOperator(t, n, i) : this.isIdentifierStart(e) ? this.scanIdentifier(t, n, i) : this.makeToken("unknown", e, t, n, i);
+    return t === "=" && this.peek() === ">" ? (this.advance(), this.makeToken("arrow", "=>", e, n, i)) : t === ":" && this.peek() === ":" ? (this.advance(), this.makeToken("doubleColon", "::", e, n, i)) : t === '"' || t === "'" ? this.scanString(t, e, n, i) : this.isDigit(t) || t === "-" && this.isDigit(this.peek()) ? this.scanNumber(e, n, i) : this.isOperatorChar(t) ? this.scanSymbolOperator(e, n, i) : this.isIdentifierStart(t) ? this.scanIdentifier(e, n, i) : this.makeToken("unknown", t, e, n, i);
   }
   /**
    * Scan whitespace characters
    */
   scanWhitespace() {
-    const t = this.position, n = this.line, i = this.column;
-    let e = "";
+    const e = this.position, n = this.line, i = this.column;
+    let t = "";
     for (; !this.isAtEnd() && this.isWhitespace(this.peek()); ) {
       const s = this.advance();
-      e += s;
+      t += s;
     }
-    return this.makeToken("whitespace", e, t, n, i);
+    return this.makeToken("whitespace", t, e, n, i);
   }
   /**
    * Scan a string literal (single or double quoted)
    */
-  scanString(t, n, i, e) {
+  scanString(e, n, i, t) {
     let s = "";
-    const r = t;
-    for (; !this.isAtEnd() && this.peek() !== t; )
-      if (this.peek() === "\\") {
-        if (this.advance(), !this.isAtEnd()) {
+    const r = e;
+    for (; !this.isAtEnd() && this.peek() !== e; )
+      if (this.peek() === "\\")
+        if (this.advance(), this.isAtEnd())
+          s += "\\";
+        else {
           const a = this.advance();
           switch (a) {
             case "n":
@@ -268,10 +284,10 @@ class g {
               s += "'";
               break;
             default:
-              s += a;
+              s += "\\" + a;
           }
         }
-      } else
+      else
         s += this.advance();
     return this.isAtEnd() ? {
       type: "error",
@@ -279,7 +295,7 @@ class g {
       start: n,
       end: this.position,
       line: i,
-      column: e,
+      column: t,
       raw: r + s
     } : (this.advance(), {
       type: "string",
@@ -287,88 +303,88 @@ class g {
       start: n,
       end: this.position,
       line: i,
-      column: e,
-      raw: t + s + t
+      column: t,
+      raw: e + s + e
     });
   }
   /**
    * Scan a numeric literal
    */
-  scanNumber(t, n, i) {
-    this.position = t, this.column = i;
-    let e = "";
-    for (this.peek() === "-" && (e += this.advance()); !this.isAtEnd() && this.isDigit(this.peek()); )
-      e += this.advance();
+  scanNumber(e, n, i) {
+    this.position = e, this.column = i;
+    let t = "";
+    for (this.peek() === "-" && (t += this.advance()); !this.isAtEnd() && this.isDigit(this.peek()); )
+      t += this.advance();
     if (this.peek() === "." && this.isDigit(this.peekNext()))
-      for (e += this.advance(); !this.isAtEnd() && this.isDigit(this.peek()); )
-        e += this.advance();
+      for (t += this.advance(); !this.isAtEnd() && this.isDigit(this.peek()); )
+        t += this.advance();
     if (this.peek() === "e" || this.peek() === "E")
-      for (e += this.advance(), (this.peek() === "+" || this.peek() === "-") && (e += this.advance()); !this.isAtEnd() && this.isDigit(this.peek()); )
-        e += this.advance();
-    return this.makeToken("number", e, t, n, i);
+      for (t += this.advance(), (this.peek() === "+" || this.peek() === "-") && (t += this.advance()); !this.isAtEnd() && this.isDigit(this.peek()); )
+        t += this.advance();
+    return this.makeToken("number", t, e, n, i);
   }
   /**
    * Scan symbol-based operators (==, !=, >, >=, <, <=, !)
    */
-  scanSymbolOperator(t, n, i) {
-    this.position = t, this.column = i;
-    let e = this.advance();
+  scanSymbolOperator(e, n, i) {
+    this.position = e, this.column = i;
+    let t = this.advance();
     if (!this.isAtEnd()) {
-      const s = e + this.peek();
+      const s = t + this.peek();
       if (s === "=>")
-        return this.advance(), this.makeToken("arrow", "=>", t, n, i);
-      (s in h || s === "==" || s === "!=") && (e = s, this.advance());
+        return this.advance(), this.makeToken("arrow", "=>", e, n, i);
+      (s in h || s === "==" || s === "!=") && (t = s, this.advance());
     }
-    if (e === "!") {
+    if (t === "!") {
       const s = this.position;
       let r = "";
       for (; !this.isAtEnd() && this.isIdentifierChar(this.peek()); )
         r += this.advance();
       if (r) {
         if ("!" + r in u)
-          return this.makeToken("operator", "!" + r, t, n, i);
+          return this.makeToken("operator", "!" + r, e, n, i);
         this.position = s, this.column = i + 1;
       }
     }
-    return e in h || e === "==" || e === "=" || e === "!=" || e === ">" || e === ">=" || e === "<" || e === "<=" ? this.makeToken("operator", e, t, n, i) : this.makeToken("unknown", e, t, n, i);
+    return t in h || t === "==" || t === "=" || t === "!=" || t === ">" || t === ">=" || t === "<" || t === "<=" ? this.makeToken("operator", t, e, n, i) : t === "!" ? this.makeToken("logicalOp", t, e, n, i) : this.makeToken("unknown", t, e, n, i);
   }
   /**
    * Scan an identifier (field name, operator keyword, etc.)
    */
-  scanIdentifier(t, n, i) {
-    this.position = t, this.column = i;
-    let e = "";
+  scanIdentifier(e, n, i) {
+    this.position = e, this.column = i;
+    let t = "";
     const s = this.advance();
-    if (e += s, s === "@" && this.peek() === "@")
-      return this.makeToken("unknown", e, t, n, i);
+    if (t += s, s === "@" && this.peek() === "@")
+      return this.makeToken("unknown", t, e, n, i);
     let r = s;
     for (; !this.isAtEnd() && this.isIdentifierChar(this.peek()); ) {
       const c = this.advance();
       if (c === "." && r === ".")
-        return this.position--, this.column--, e = e.slice(0, -1), this.makeToken("unknown", e, t, n, i);
-      e += c, r = c;
+        return this.position--, this.column--, t = t.slice(0, -1), this.makeToken("unknown", t, e, n, i);
+      t += c, r = c;
     }
-    e.endsWith(".") && (this.position--, this.column--, e = e.slice(0, -1));
-    const a = this.classifyIdentifier(e);
-    return this.makeToken(a, e, t, n, i);
+    t.endsWith(".") && (this.position--, this.column--, t = t.slice(0, -1));
+    const a = this.classifyIdentifier(t);
+    return this.makeToken(a, t, e, n, i);
   }
   /**
    * Classify an identifier into the appropriate token type
    */
-  classifyIdentifier(t) {
-    const n = t.toUpperCase(), i = t.toLowerCase();
-    return d.includes(n) ? "logicalOp" : p.includes(n) ? "collectionOp" : i === "true" || i === "false" ? "boolean" : i === "null" ? "null" : i === "stats" ? "keyword" : l.includes(i) ? "operator" : _.includes(i) ? "aggregation" : k.includes(i) ? "mutator" : f.includes(i) ? "typeHint" : m.includes(i) ? "visualization" : w.includes(i) ? "keyword" : "field";
+  classifyIdentifier(e) {
+    const n = e.toUpperCase(), i = e.toLowerCase();
+    return p.includes(n) ? "logicalOp" : d.includes(n) ? "collectionOp" : i === "true" || i === "false" ? "boolean" : i === "null" ? "null" : i === "stats" ? "keyword" : l.includes(i) ? "operator" : f.includes(i) ? "aggregation" : k.includes(i) ? "mutator" : m.includes(i) ? "typeHint" : T.includes(i) ? "visualization" : g.includes(i) ? "keyword" : "field";
   }
   // ============================================================================
   // Helper Methods
   // ============================================================================
-  makeToken(t, n, i, e, s) {
+  makeToken(e, n, i, t, s) {
     return {
-      type: t,
+      type: e,
       value: n,
       start: i,
       end: this.position,
-      line: e,
+      line: t,
       column: s
     };
   }
@@ -382,81 +398,84 @@ class g {
     return this.position + 1 >= this.input.length ? "\0" : this.input[this.position + 1];
   }
   advance() {
-    const t = this.input[this.position];
-    return this.position++, t === `
-` ? (this.line++, this.column = 1) : this.column++, t;
+    const e = this.input[this.position];
+    return this.position++, e === `
+` ? (this.line++, this.column = 1) : this.column++, e;
   }
-  isWhitespace(t) {
-    return t === " " || t === "	" || t === `
-` || t === "\r";
+  isWhitespace(e) {
+    return e === " " || e === "	" || e === `
+` || e === "\r";
   }
-  isDigit(t) {
-    return t >= "0" && t <= "9";
+  isDigit(e) {
+    return e >= "0" && e <= "9";
   }
-  isIdentifierStart(t) {
-    return t >= "a" && t <= "z" || t >= "A" && t <= "Z" || t === "_" || t === "@";
+  isIdentifierStart(e) {
+    return e >= "a" && e <= "z" || e >= "A" && e <= "Z" || e === "_" || e === "@";
   }
   /**
    * Check if char can continue an identifier (NOT including @ which is only valid at start)
    */
-  isIdentifierChar(t) {
-    return t >= "a" && t <= "z" || t >= "A" && t <= "Z" || t === "_" || this.isDigit(t) || t === "." || // For nested field access
-    t === "-";
+  isIdentifierChar(e) {
+    return e >= "a" && e <= "z" || e >= "A" && e <= "Z" || e === "_" || this.isDigit(e) || e === "." || // For nested field access
+    e === "-";
   }
-  isOperatorChar(t) {
-    return t === "=" || t === "!" || t === ">" || t === "<";
+  isOperatorChar(e) {
+    return e === "=" || e === "!" || e === ">" || e === "<";
   }
 }
-function T(o) {
-  return new g(o).tokenize();
+function O(o) {
+  return new w(o).tokenize();
 }
-function b(o) {
-  return T(o).filter((t) => t.type !== "whitespace");
+function v(o) {
+  return O(o).filter((e) => e.type !== "whitespace");
 }
-function v(o, t) {
+function E(o, e) {
   for (const n of o)
-    if (t >= n.start && t < n.end)
+    if (e >= n.start && e < n.end)
       return n;
   return null;
 }
-function O(o, t, n) {
-  return o.filter((i) => i.start < n && i.end > t);
+function S(o, e, n) {
+  return o.filter((i) => i.start < n && i.end > e);
 }
-function A(o, t) {
+function I(o, e) {
   let n = null;
   for (const i of o)
-    if (i.end <= t)
+    if (i.end <= e)
       n = i;
     else
       break;
   return n;
 }
-function E(o, t, n = !0) {
+function N(o, e, n = !0) {
   const i = n ? o.filter((s) => s.type !== "whitespace") : o;
-  let e = null;
+  let t = null;
   for (const s of i)
-    if (s.end <= t)
-      e = s;
+    if (s.end <= e)
+      t = s;
     else
       break;
-  return e;
+  return t;
 }
 export {
-  _ as AGGREGATION_FUNCTIONS,
-  p as COLLECTION_OPERATORS,
+  f as AGGREGATION_FUNCTIONS,
+  _ as BOOLEAN_PREDICATE_MUTATORS,
+  A as BOOLEAN_PREDICATE_MUTATOR_SET,
+  d as COLLECTION_OPERATORS,
   l as COMPARISON_OPERATORS,
-  w as KEYWORDS,
-  d as LOGICAL_OPERATORS,
+  g as KEYWORDS,
+  p as LOGICAL_OPERATORS,
   k as MUTATORS,
   u as NEGATION_SYMBOL_OPERATORS,
+  b as SYMBOL_LOGICAL_OPERATORS,
   h as SYMBOL_OPERATORS,
-  f as TYPE_HINTS,
-  g as TqlTokenizer,
-  m as VISUALIZATION_TYPES,
-  E as findPreviousToken,
-  v as findTokenAtPosition,
-  A as findTokenBefore,
-  O as findTokensInRange,
-  T as tokenizeTql,
-  b as tokenizeTqlNoWhitespace
+  m as TYPE_HINTS,
+  w as TqlTokenizer,
+  T as VISUALIZATION_TYPES,
+  N as findPreviousToken,
+  E as findTokenAtPosition,
+  I as findTokenBefore,
+  S as findTokensInRange,
+  O as tokenizeTql,
+  v as tokenizeTqlNoWhitespace
 };

package/dist/src/types.d.ts

@@ -38,9 +38,25 @@ export interface TqlComparisonExpression {
     start: number;
     end: number;
 }
+/**
+ * `field ANY value` and its relatives — a comparison applied across the ELEMENTS of an
+ * array-valued field rather than to the field as a whole.
+ *
+ * This type shipped for a long time with no parse path that could produce it: the tokenizer
+ * emitted `collectionOp` for `any` / `all` / `none`, the parser had no arm for that token
+ * type, and every collection query in the editor came back as
+ * "Expected operator after field". The type and `COLLECTION_OPERATORS` were exported the
+ * whole time, so the surface looked supported. `tests/collectionParity.spec.ts` now pins the
+ * accepted forms against both engine grammars.
+ *
+ * `negated` carries the `not any` / `!any` / `not_any` spellings, which both engines accept
+ * and which are otherwise indistinguishable from the positive form once `operator` has been
+ * normalised to its canonical upper-case name.
+ */
 export interface TqlCollectionExpression {
     type: "collection";
     operator: "ANY" | "ALL" | "NONE";
+    negated: boolean;
     field: TqlFieldReference;
     condition: TqlExpression;
     start: number;
@@ -88,21 +104,52 @@ export interface TqlLiteral {
     start: number;
     end: number;
 }
+/**
+ * One argument inside a parameterised mutator call: `split(delimiter=",")`.
+ *
+ * Both engines accept named (`delimiter=","`), positional (`","`) and bare-identifier
+ * (`old=a`) arguments; neither accepts a list literal. See `mutator_arg` in
+ * tql/src/parser/grammar.pest and `_setup_mutators` in
+ * src/tql/parser_components/grammar.py.
+ */
+export interface TqlMutatorArgument {
+    /** Present for `name=value` form; absent for a positional argument. */
+    name?: string;
+    valueType: "string" | "number" | "boolean" | "null" | "identifier";
+    value: string | number | boolean | null;
+    start: number;
+    end: number;
+}
+/**
+ * One link in a mutator chain, with the arguments it was called with.
+ *
+ * `TqlFieldReference.mutators` remains the flat list of names (unchanged for existing
+ * consumers); `mutatorCalls` carries the same chain with argument detail attached.
+ */
+export interface TqlMutatorCall {
+    name: string;
+    args: TqlMutatorArgument[];
+    /** True when the call carried an explicit `(...)` list, even an empty one. */
+    parenthesized: boolean;
+    start: number;
+    end: number;
+}
 export interface TqlFieldReference {
     type: "field";
     name: string;
     path: string[];
     mutators?: string[];
+    mutatorCalls?: TqlMutatorCall[];
     typeHint?: TqlTypeHint;
     start: number;
     end: number;
 }
-export type TqlComparisonOperator = "eq" | "ne" | "=" | "!=" | "==" | "eq_ci" | "gt" | "gte" | "lt" | "lte" | ">" | ">=" | "<" | "<=" | "contains" | "not_contains" | "!contains" | "startswith" | "not_startswith" | "!startswith" | "endswith" | "not_endswith" | "!endswith" | "contains_cs" | "not_contains_cs" | "!contains_cs" | "startswith_cs" | "not_startswith_cs" | "!startswith_cs" | "endswith_cs" | "not_endswith_cs" | "!endswith_cs" | "regexp" | "regex" | "not_regexp" | "not_regex" | "!regexp" | "!regex" | "matches" | "not_matches" | "!matches" | "between" | "not_between" | "!between" | "in" | "not_in" | "!in" | "in_cs" | "not_in_cs" | "!in_cs" | "exists" | "not_exists" | "!exists" | "is" | "is_not" | "!is" | "cidr" | "not_cidr" | "!cidr" | "any" | "all" | "none" | "not_any" | "not_all" | "not_none" | "!any" | "!all" | "!none";
+export type TqlComparisonOperator = "eq" | "ne" | "=" | "!=" | "eq_ci" | "gt" | "gte" | "lt" | "lte" | ">" | ">=" | "<" | "<=" | "contains" | "not_contains" | "!contains" | "startswith" | "not_startswith" | "!startswith" | "endswith" | "not_endswith" | "!endswith" | "contains_cs" | "not_contains_cs" | "!contains_cs" | "startswith_cs" | "not_startswith_cs" | "!startswith_cs" | "endswith_cs" | "not_endswith_cs" | "!endswith_cs" | "regexp" | "regex" | "not_regexp" | "not_regex" | "!regexp" | "!regex" | "matches" | "not_matches" | "!matches" | "between" | "not_between" | "!between" | "in" | "not_in" | "!in" | "in_cs" | "not_in_cs" | "!in_cs" | "exists" | "not_exists" | "!exists" | "is" | "is_not" | "!is" | "cidr" | "not_cidr" | "!cidr" | "any" | "all" | "none" | "not_any" | "not_all" | "not_none" | "!any" | "!all" | "!none";
 export type TqlLogicalOperator = "AND" | "OR" | "NOT";
 export type TqlCollectionOperator = "ANY" | "ALL" | "NONE";
 export type TqlMutator = "lowercase" | "uppercase" | "trim" | "split" | "length" | "replace" | "b64encode" | "b64decode" | "urldecode" | "hexencode" | "hexdecode" | "md5" | "sha256" | "refang" | "defang" | "is_private" | "is_global" | "is_multicast" | "is_loopback" | "is_link_local" | "nslookup" | "geoip_lookup" | "geoip" | "geo" | "any" | "all" | "avg" | "average" | "sum" | "min" | "max";
 export type TqlAggregationFunction = "count" | "sum" | "avg" | "average" | "mean" | "median" | "med" | "min" | "max" | "percentile" | "percentiles" | "p" | "pct" | "percentile_rank" | "percentile_ranks" | "pct_rank" | "pct_ranks" | "std" | "standard_deviation" | "unique_count" | "cardinality" | "values" | "unique" | "distinct";
-export type TqlTypeHint = "string" | "str" | "number" | "int" | "integer" | "float" | "double" | "decimal" | "date" | "bool" | "boolean" | "array" | "list" | "object" | "geo";
+export type TqlTypeHint = "string" | "str" | "number" | "int" | "integer" | "float" | "double" | "decimal" | "date" | "bool" | "boolean" | "array" | "list" | "object" | "geo" | "ip";
 export type TqlVisualizationType = "bar" | "barchart" | "horizontal_bar" | "line" | "area" | "stacked_area" | "pie" | "donut" | "scatter" | "heatmap" | "treemap" | "sunburst" | "table" | "number" | "gauge" | "map" | "grouped_bar" | "stacked_bar" | "nested_pie" | "nested_donut" | "chord" | "auto";
 /**
  * Visualization parameters (e.g., title="Events", stacked=true).
@@ -153,8 +200,43 @@ export interface TqlParseWarning {
     code: TqlWarningCode;
     suggestion?: string;
 }
-export type TqlErrorCode = "UNEXPECTED_TOKEN" | "UNEXPECTED_END" | "UNBALANCED_PARENS" | "UNBALANCED_BRACKETS" | "UNTERMINATED_STRING" | "INVALID_OPERATOR" | "INVALID_MUTATOR" | "INVALID_VALUE" | "MISSING_OPERAND" | "MISSING_OPERATOR" | "MISSING_VALUE" | "MISSING_FIELD" | "MISSING_MUTATOR" | "INVALID_SYNTAX" | "MAX_DEPTH_EXCEEDED" | "TYPE_MISMATCH";
-export type TqlWarningCode = "UNKNOWN_FIELD" | "TYPE_MISMATCH" | "DEPRECATED_OPERATOR" | "REDUNDANT_PARENS";
+export type TqlErrorCode = "UNEXPECTED_TOKEN" | "UNEXPECTED_END" | "UNBALANCED_PARENS" | "UNBALANCED_BRACKETS" | "UNTERMINATED_STRING" | "INVALID_OPERATOR" | "INVALID_MUTATOR" | "INVALID_VALUE" | "MISSING_OPERAND" | "MISSING_OPERATOR" | "MISSING_VALUE" | "MISSING_FIELD" | "MISSING_MUTATOR" | "INVALID_SYNTAX" | "MAX_DEPTH_EXCEEDED" | "TYPE_MISMATCH"
+/**
+ * `f::int | trim::str` — a type hint on BOTH sides of the mutator chain.
+ *
+ * Both engines accept the hint in either position and refuse it in both, structurally: each
+ * grammar is an ordered choice whose first alternative consumes `f::int | trim` and strands
+ * `::str`. There is no defensible answer for which hint would win.
+ */
+ | "DUPLICATE_TYPE_HINT"
+/**
+ * `::` with a token after it that can never be a type name (`f::| trim`, `f:: eq 'a'`,
+ * `f | trim:: eq 'a'`, `f::lowercase`). All four are parse errors in both engines.
+ *
+ * `f::` at END of input is NOT this — that is a hint being typed, and stays a warning.
+ */
+ | "MISSING_TYPE_HINT"
+/**
+ * A malformed `top N` / `bottom N` modifier on a stats aggregation.
+ *
+ * Reserved for the shapes BOTH engines refuse: the modifier given twice on one aggregation
+ * (`sum(x, top 10) top 5`), a modifier with no count (`sum(x) top by y`), and the in-parens
+ * form on `count(*)` / `count()` (`count(*, top 2)`). A spelling only one engine refuses is
+ * an ENGINE_DIVERGENCE warning instead — never this.
+ */
+ | "INVALID_STATS_MODIFIER";
+export type TqlWarningCode = "UNKNOWN_FIELD" | "TYPE_MISMATCH" | "DEPRECATED_OPERATOR" | "REDUNDANT_PARENS"
+/**
+ * The query parses, but only ONE of the two engines accepts it.
+ *
+ * Reserved for measured, currently-live divergences between `tql/src/parser/grammar.pest`
+ * and `src/tql/parser_components/grammar.py` — not for anything this package merely
+ * dislikes. The editor stays permissive (a red squiggle over syntax an engine accepts is
+ * the defect this parser keeps being fixed for) while still naming the engine that will
+ * refuse the query, because silently accepting it is the worse half of the same failure:
+ * the user finds out at execution instead of at the keystroke.
+ */
+ | "ENGINE_DIVERGENCE";
 export interface TqlValidationResult {
     valid: boolean;
     errors: TqlParseError[];