@tellaro/tql 1.5.0 → 3.0.0

package/dist/src/parser.js

@@ -1,6 +1,31 @@
-import { tokenizeTql as u, COMPARISON_OPERATORS as c } from "./tokenizer.js";
-const p = 50, d = /* @__PURE__ */ new Set(["logicalOp", "paren"]);
-class v {
+import { tokenizeTql as T, TYPE_HINTS as f, BOOLEAN_PREDICATE_MUTATOR_SET as N, COMPARISON_OPERATORS as k, NEGATION_SYMBOL_OPERATORS as g, MUTATORS as w, SYMBOL_LOGICAL_OPERATORS as E } from "./tokenizer.js";
+const L = 50, O = /* @__PURE__ */ new Set(["logicalOp", "paren"]), v = /* @__PURE__ */ new Map([
+  ["any", { op: "ANY", negated: !1 }],
+  ["all", { op: "ALL", negated: !1 }],
+  ["none", { op: "NONE", negated: !1 }],
+  ["not_any", { op: "ANY", negated: !0 }],
+  ["not_all", { op: "ALL", negated: !0 }],
+  ["not_none", { op: "NONE", negated: !0 }],
+  ["!any", { op: "ANY", negated: !0 }],
+  ["!all", { op: "ALL", negated: !0 }],
+  ["!none", { op: "NONE", negated: !0 }]
+]);
+function S(o, e) {
+  for (const [t, s] of v)
+    if (s.op === o && s.negated === e && /^[a-z_]+$/.test(t))
+      return t;
+  throw new Error(`no word spelling for collection operator ${o} (negated=${e})`);
+}
+const y = "Collection syntax accepted by the Rust engine only; the Python query API rejects it", _ = "Aggregation modifier on '*' accepted by the Rust engine only; the Python query API rejects it", A = /* @__PURE__ */ new Set([
+  "field",
+  "mutator",
+  "typeHint",
+  "aggregation",
+  "keyword",
+  "visualization",
+  "collectionOp"
+]);
+class I {
   tokens;
   allTokens;
   // Including whitespace for highlighting
@@ -9,7 +34,7 @@ class v {
   warnings;
   depth;
   constructor(e) {
-    this.allTokens = u(e), this.tokens = this.allTokens.filter((t) => t.type !== "whitespace"), this.current = 0, this.errors = [], this.warnings = [], this.depth = 0;
+    this.allTokens = T(e), this.tokens = this.allTokens.filter((t) => t.type !== "whitespace"), this.current = 0, this.errors = [], this.warnings = [], this.depth = 0;
   }
   /**
    * Parse the input and return the result
@@ -24,13 +49,13 @@ class v {
         success: !0
       };
     if (this.isStatsQuery())
-      return {
+      return this.checkStatsModifiers(), {
         ast: null,
         // Stats AST is produced by the Python/Rust parser
         tokens: this.allTokens,
-        errors: [],
-        warnings: [],
-        success: !0
+        errors: this.errors,
+        warnings: this.warnings,
+        success: this.errors.length === 0
       };
     try {
       const e = this.parseExpression();
@@ -67,7 +92,7 @@ class v {
    * Parse a full expression (lowest precedence)
    */
   parseExpression() {
-    if (this.depth++, this.depth > p)
+    if (this.depth++, this.depth > L)
       throw new Error("Maximum query depth exceeded");
     try {
       return this.parseOr();
@@ -89,14 +114,14 @@ class v {
           "MISSING_OPERAND",
           "Add a condition after 'OR'"
         ), e;
-      const r = this.parseAnd();
+      const s = this.parseAnd();
       e = {
         type: "binary",
         operator: "OR",
         left: e,
-        right: r,
+        right: s,
         start: e.start,
-        end: r.end
+        end: s.end
       };
     }
     return e;
@@ -115,14 +140,14 @@ class v {
           "MISSING_OPERAND",
           "Add a condition after 'AND'"
         ), e;
-      const r = this.parseUnary();
+      const s = this.parseUnary();
       e = {
         type: "binary",
         operator: "AND",
         left: e,
-        right: r,
+        right: s,
         start: e.start,
-        end: r.end
+        end: s.end
       };
     }
     return e;
@@ -149,6 +174,8 @@ class v {
   parsePrimary() {
     if (this.check("paren") && this.peek().value === "(")
       return this.parseGroup();
+    if (this.check("collectionOp") && v.has(this.peek().value.toLowerCase()))
+      return this.parseCollectionFirst();
     if (this.check("field") || this.check("aggregation") || this.check("mutator") || this.check("typeHint"))
       return this.parseComparison();
     const e = this.peek();
@@ -185,53 +212,222 @@ class v {
    * - Optional mutator chain: field | lowercase | trim eq "value"
    */
   parseComparison() {
-    const e = this.advance();
+    const e = this.advance(), t = this.parseFieldTail(e), s = this.tryParseCollectionTail(t);
+    return s !== null ? s : this.parseComparisonTail(e, t);
+  }
+  /**
+   * The part of a field reference after its name token: `::type` and `| mutator` chains.
+   *
+   * Split out of `parseComparison` so the operator-first collection form
+   * (`ANY field::string | lowercase eq "x"`) reads the same field grammar rather than a
+   * reduced copy of it. A second copy is how `field::geo` came to be accepted in one place
+   * and rejected in another.
+   */
+  parseFieldTail(e) {
     let t = this.createFieldReference(e);
-    if (this.check("doubleColon"))
-      if (this.advance(), this.check("typeHint") || this.check("field")) {
-        const s = this.advance();
-        t = {
-          ...t,
-          typeHint: s.value.toLowerCase(),
-          end: s.end
-        };
-      } else {
-        const s = this.isAtEnd() ? this.previous() : this.peek();
-        this.addWarning(
-          "Expected type hint after '::'",
-          s,
-          "Valid types: string, int, float, date, bool, array"
-        );
-      }
-    const r = [];
+    const s = this.readTypeHintSlot(t);
+    t = s.field;
+    const n = [], i = [];
     for (; this.check("pipe"); )
-      if (this.advance(), this.check("mutator")) {
-        const s = this.advance();
-        r.push(s.value.toLowerCase());
+      if (this.advance(), this.check("mutator") || this.isCatalogMutatorToken()) {
+        const r = this.advance();
+        n.push(r.value.toLowerCase()), i.push(this.parseMutatorCall(r));
       } else if (this.check("field")) {
-        const s = this.advance();
-        r.push(s.value.toLowerCase()), this.addWarning(`Unknown mutator '${s.value}'`, s, "Check the mutator name spelling");
+        const r = this.advance();
+        n.push(r.value.toLowerCase()), this.addWarning(`Unknown mutator '${r.value}'`, r, "Check the mutator name spelling"), i.push(this.parseMutatorCall(r));
       } else {
-        const s = this.isAtEnd() ? this.previous() : this.peek();
+        const r = this.isAtEnd() ? this.previous() : this.peek();
         this.addError(
           "Expected mutator name after '|'",
-          s,
+          r,
           "MISSING_MUTATOR",
           "Add a mutator like 'lowercase', 'uppercase', 'trim', etc."
         );
         break;
       }
-    if (r.length > 0 && (t = {
+    if (n.length > 0 && (t = {
       ...t,
-      mutators: r,
+      mutators: n,
+      mutatorCalls: i,
       end: this.previous().end
-    }), !this.check("operator")) {
-      const s = this.isAtEnd() ? this.previous() : this.peek(), o = r.length > 0 ? `'${e.value}' with mutator` : `'${e.value}'`;
+    }), this.check("doubleColon"))
+      if (s.filled) {
+        const r = this.advance();
+        this.addError(
+          "A field may carry only one type hint",
+          r,
+          "DUPLICATE_TYPE_HINT",
+          `Write the hint once — either '${e.value}::${t.typeHint ?? "type"} | mutator' or '${e.value} | mutator::type'`
+        ), (this.check("field") || this.check("typeHint") || this.check("mutator")) && this.advance();
+      } else
+        t = this.readTypeHintSlot(t).field;
+    return t;
+  }
+  /**
+   * Read one `::type` slot, if the current token opens one. Returns the field with the hint
+   * applied and whether a hint name was actually consumed.
+   *
+   * Called from BOTH sides of the mutator chain so the two spellings share one definition of
+   * what may follow `::`.
+   *
+   * Match on the token's VALUE, not its type. `classifyIdentifier` tests the mutator catalog
+   * before the type-hint catalog, so a name in both — `geo` is the live case, exported by
+   * TYPE_HINTS and by MUTATORS — arrives here typed "mutator" and was rejected. The package
+   * exported `geo` as a valid type hint while its own parser refused `field::geo`. After
+   * `::` the only thing a token can be is a type name, so the catalog is the right authority
+   * and the lexical class is noise.
+   */
+  readTypeHintSlot(e) {
+    if (!this.check("doubleColon")) return { field: e, filled: !1 };
+    this.advance();
+    const t = this.isAtEnd() ? void 0 : this.peek();
+    if (t !== void 0 && f.includes(t.value.toLowerCase())) {
+      const s = this.advance();
+      return {
+        field: { ...e, typeHint: s.value.toLowerCase(), end: s.end },
+        filled: !0
+      };
+    }
+    if (this.check("field")) {
+      const s = this.advance();
+      return {
+        field: { ...e, typeHint: s.value.toLowerCase(), end: s.end },
+        filled: !0
+      };
+    }
+    return this.isAtEnd() ? (this.addWarning(
+      "Expected type hint after '::'",
+      this.previous(),
+      // Derived from the catalog rather than a hand-written excerpt, which had drifted
+      // to six of the fifteen names and omitted the very one being rejected.
+      `Valid types: ${f.join(", ")}`
+    ), { field: e, filled: !1 }) : (this.addError(
+      "Expected type hint after '::'",
+      this.peek(),
+      "MISSING_TYPE_HINT",
+      // Catalog-derived for the same reason as the warning arm, so the two cannot drift.
+      `Name a type (${f.join(", ")}), or remove the '::'`
+    ), { field: e, filled: !1 });
+  }
+  /**
+   * `ANY field [op] value` — the operator-first collection forms.
+   *
+   * `grammar.pest:226-231` gives `collection_comparison` four alternatives; this is the two
+   * that lead with the operator. The Python parser accepts NEITHER — probed, not inferred:
+   * `ANY f eq 'x'` and `ANY f 'x'` both raise `TQLSyntaxError at position 4`. They are
+   * therefore parsed AND flagged: see `RUST_ONLY_COLLECTION_MESSAGE`.
+   *
+   * The current token is the collection operator.
+   */
+  parseCollectionFirst() {
+    const e = this.advance(), t = v.get(e.value.toLowerCase());
+    if (t === void 0)
+      return this.createPlaceholderExpression(e);
+    if (this.addWarning(
+      y,
+      e,
+      `Write it field-first instead: field ${e.value.toLowerCase()} value`,
+      "ENGINE_DIVERGENCE"
+    ), !(this.check("field") || this.check("aggregation") || this.check("mutator") || this.check("typeHint"))) {
+      const n = this.isAtEnd() ? this.previous() : this.peek();
       return this.addError(
-        `Expected operator after field ${o}`,
-        s,
+        `Expected a field name after '${e.value}'`,
+        n,
+        "MISSING_FIELD",
+        `Use: ${e.value} field eq "value"`
+      ), this.createPlaceholderExpression(e);
+    }
+    const s = this.parseFieldTail(this.advance());
+    return this.finishCollection(e, t.op, t.negated, s, e.start);
+  }
+  /**
+   * `field [not] ANY [op] value`, or null when the token after the field is not a
+   * collection operator at all.
+   *
+   * Only `field ANY value` — no inner comparison operator — is accepted by both engines.
+   * `field ANY eq value` is `grammar.pest`'s third alternative and Python rejects it
+   * (`f any eq 'x'` -> `TQLSyntaxError at position 9`), so it parses with the divergence
+   * warning rather than being silently accepted or silently refused.
+   */
+  tryParseCollectionTail(e) {
+    const t = this.check("logicalOp") && this.logicalWord(this.peek()) === "NOT", s = t ? 1 : 0, n = this.peekAt(s);
+    if (n === void 0 || n.type !== "collectionOp" && n.type !== "operator") return null;
+    const i = v.get(n.value.toLowerCase());
+    if (i === void 0 || t && i.negated) return null;
+    t && this.advance();
+    const r = this.advance();
+    return this.finishCollection(
+      r,
+      i.op,
+      i.negated || t,
+      e,
+      e.start
+    );
+  }
+  /**
+   * The shared tail of both collection forms: an OPTIONAL inner comparison operator
+   * (defaulting to `eq`, as both grammars do) followed by a value or a value list.
+   */
+  finishCollection(e, t, s, n, i) {
+    let r = "eq";
+    if (this.check("operator")) {
+      const h = this.advance();
+      r = this.normalizeOperator(h.value), this.addWarning(
+        y,
+        h,
+        `Drop the '${h.value}': the Python parser accepts only field ${e.value.toLowerCase()} value`,
+        "ENGINE_DIVERGENCE"
+      );
+    }
+    const u = this.check("bracket") && this.peek().value === "[" ? this.parseValueList() : this.parseValue(), a = this.previous().end;
+    return {
+      type: "collection",
+      operator: t,
+      negated: s,
+      field: n,
+      condition: {
+        type: "comparison",
+        field: n,
+        operator: r,
+        value: u,
+        start: n.start,
+        end: a
+      },
+      start: i,
+      end: a
+    };
+  }
+  /**
+   * `<field> <comparison-op> <value>` — everything after the field reference.
+   *
+   * `fieldToken` is threaded through only for the error messages, which name the field the
+   * user typed rather than the normalised reference.
+   */
+  parseComparisonTail(e, t) {
+    const s = t.mutators ?? [], n = this.consumeNegationPrefix();
+    if (!this.check("operator")) {
+      const a = s.length > 0 ? s[s.length - 1] : null;
+      if (n === null && a !== null && N.has(a))
+        return {
+          type: "comparison",
+          field: t,
+          operator: "eq",
+          value: {
+            type: "literal",
+            valueType: "boolean",
+            value: !0,
+            start: t.end,
+            end: t.end
+          },
+          start: t.start,
+          end: t.end
+        };
+      const h = this.isAtEnd() ? this.previous() : this.peek(), p = s.length > 0 ? `'${e.value}' with mutator` : `'${e.value}'`;
+      return this.addError(
+        `Expected operator after field ${p}`,
+        h,
         "MISSING_OPERATOR",
-        "Add an operator like 'eq', 'contains', '==', etc."
+        "Add an operator like 'eq', 'contains', '=', etc."
       ), {
         type: "comparison",
         field: t,
@@ -247,96 +443,128 @@ class v {
         end: t.end
       };
     }
-    const a = this.advance(), n = this.normalizeOperator(a.value);
-    if (n === "exists" || n === "not_exists")
+    const i = this.advance();
+    i.value === "==" && this.addError(
+      "Invalid operator '=='",
+      i,
+      "INVALID_OPERATOR",
+      "Use '=' or 'eq' for equality"
+    );
+    let r = this.normalizeOperator(i.value);
+    if (n !== null) {
+      const a = this.negateOperator(r);
+      a === null ? this.addError(
+        `'${n.value} ${i.value}' is not a TQL operator`,
+        n,
+        "INVALID_OPERATOR",
+        `'${r}' has no negated form; use 'ne' or negate the whole expression: not (field ${r} value)`
+      ) : r = a;
+    }
+    if (r === "is" && this.check("logicalOp") && this.logicalWord(this.peek()) === "NOT" && (this.advance(), r = "is_not"), r === "exists" || r === "not_exists")
       return {
         type: "comparison",
         field: t,
-        operator: n,
+        operator: r,
         value: {
           type: "literal",
           valueType: "boolean",
           value: !0,
-          start: a.end,
-          end: a.end
+          start: i.end,
+          end: i.end
         },
         start: t.start,
-        end: a.end
+        end: i.end
       };
-    if ((n === "is" || n === "is_not") && this.check("null")) {
-      const s = this.advance();
+    if ((r === "is" || r === "is_not") && this.check("null")) {
+      const a = this.advance();
       return {
         type: "comparison",
         field: t,
-        operator: n,
+        operator: r,
         value: {
           type: "literal",
           valueType: "null",
           value: null,
-          start: s.start,
-          end: s.end
+          start: a.start,
+          end: a.end
         },
         start: t.start,
-        end: s.end
+        end: a.end
       };
     }
-    if (n === "in" || n === "not_in") {
-      const s = this.parseValueList();
+    if (/^(not_)?in(_cs)?$/.test(r)) {
+      const a = this.parseValueList();
       return {
         type: "comparison",
         field: t,
-        operator: n,
-        value: s,
+        operator: r,
+        value: a,
         start: t.start,
         end: this.previous().end
       };
     }
-    if (n === "between" || n === "not_between") {
-      const s = this.parseValue();
-      this.matchLogical("AND") || this.addError(
+    if (r === "between" || r === "not_between") {
+      if (this.check("bracket") && this.peek().value === "[") {
+        const p = this.peek(), c = this.parseValueList();
+        return c.length !== 2 && this.addError(
+          `'${r}' needs exactly 2 values, got ${c.length}`,
+          p,
+          "INVALID_VALUE",
+          `Use: field ${r} [low, high]  or  field ${r} low AND high`
+        ), {
+          type: "comparison",
+          field: t,
+          operator: r,
+          value: c,
+          start: t.start,
+          end: this.previous().end
+        };
+      }
+      const a = this.parseValue();
+      this.matchLogicalWord("AND") || this.addError(
         "Expected 'AND' between values in 'between' operator",
         this.isAtEnd() ? this.previous() : this.peek(),
         "INVALID_SYNTAX",
         "Use format: field between value1 AND value2"
       );
-      const o = this.parseValue();
+      const h = this.parseValue();
       return {
         type: "comparison",
         field: t,
-        operator: n,
-        value: [s, o],
+        operator: r,
+        value: [a, h],
         start: t.start,
-        end: o.end
+        end: h.end
       };
     }
     if (this.isAtEnd())
       return this.addError(
-        `Expected a value after operator '${n}'`,
-        a,
+        `Expected a value after operator '${r}'`,
+        i,
         "MISSING_VALUE",
         'Add a value like "text", 123, or true'
       ), {
         type: "comparison",
         field: t,
-        operator: n,
+        operator: r,
         value: {
           type: "literal",
           valueType: "string",
           value: "",
-          start: a.end,
-          end: a.end
+          start: i.end,
+          end: i.end
         },
         start: t.start,
-        end: a.end
+        end: i.end
       };
-    const h = this.parseValue();
+    const u = this.parseValue();
     return {
       type: "comparison",
       field: t,
-      operator: n,
-      value: h,
+      operator: r,
+      value: u,
       start: t.start,
-      end: h.end
+      end: u.end
     };
   }
   /**
@@ -407,12 +635,122 @@ class v {
    */
   parseValueList() {
     const e = [];
-    this.check("bracket") && this.peek().value === "[" ? this.advance() : this.check("paren") && this.peek().value === "(" && this.advance();
+    let t = null;
+    this.check("bracket") && this.peek().value === "[" ? t = this.advance() : this.check("paren") && this.peek().value === "(" && (t = this.advance());
     do {
       if (this.check("bracket") && this.peek().value === "]" || this.check("paren") && this.peek().value === ")") break;
       e.push(this.parseValue());
     } while (this.match("comma"));
-    return this.check("bracket") && this.peek().value === "]" ? this.advance() : this.check("paren") && this.peek().value === ")" && this.advance(), e;
+    if (this.check("bracket") && this.peek().value === "]")
+      this.advance();
+    else if (this.check("paren") && this.peek().value === ")")
+      this.advance();
+    else if (t !== null) {
+      const s = t.value === "[" ? "]" : ")";
+      this.addError(
+        `Missing closing '${s}' in value list`,
+        this.isAtEnd() ? this.previous() : this.peek(),
+        "UNBALANCED_BRACKETS",
+        `Close the list: ${t.value}...${s}`
+      );
+    }
+    return t !== null && e.length === 0 && this.addError(
+      "Empty value list",
+      t,
+      "INVALID_VALUE",
+      "A list needs at least one value. Every TQL engine rejects an empty list, so this query will not run in the editor, in the backend, or in the agent."
+    ), e;
+  }
+  /**
+   * Parse the optional argument list of a mutator call.
+   *
+   * `field | split(delimiter=",") eq "bob"` is valid TQL that both engines accept
+   * (`mutator = { "|" ~ !^"stats" ~ mutator_name ~ ("(" ~ mutator_args? ~ ")")? }` in
+   * tql/src/parser/grammar.pest; `mutator_with_params` in
+   * src/tql/parser_components/grammar.py). The JS parser used to stop at the mutator
+   * NAME, so the '(' fell through to the top-level "Unexpected token" arm and the editor
+   * red-squiggled a query the backend runs happily -- while this package's own completion
+   * documentation advertised that exact call form.
+   *
+   * The name token has already been consumed by the caller.
+   */
+  parseMutatorCall(e) {
+    const t = e.value.toLowerCase(), s = [];
+    if (!(this.check("paren") && this.peek().value === "("))
+      return { name: t, args: s, parenthesized: !1, start: e.start, end: e.end };
+    if (this.advance(), !(this.check("paren") && this.peek().value === ")"))
+      for (; ; ) {
+        const n = this.parseMutatorArgument(t);
+        if (n === null) break;
+        if (s.push(n), this.check("comma")) {
+          this.advance();
+          continue;
+        }
+        break;
+      }
+    return this.check("paren") && this.peek().value === ")" ? this.advance() : this.addError(
+      `Missing closing parenthesis ')' after arguments to '${t}'`,
+      this.isAtEnd() ? this.previous() : this.peek(),
+      "UNBALANCED_PARENS",
+      `Close the argument list: ${t}(...)`
+    ), { name: t, args: s, parenthesized: !0, start: e.start, end: this.previous().end };
+  }
+  /**
+   * Parse one mutator argument: `value`, or `name=value`.
+   *
+   * Returns null (after recording an error) when the current token cannot start an
+   * argument, so the caller stops rather than spinning.
+   */
+  parseMutatorArgument(e) {
+    const t = this.isAtEnd() ? this.previous() : this.peek();
+    if (A.has(t.type) && this.peekAt(1)?.type === "operator" && this.peekAt(1)?.value === "=") {
+      const n = this.advance();
+      this.advance();
+      const i = this.parseMutatorArgumentValue(e);
+      return i === null ? null : { name: n.value, ...i, start: n.start, end: i.end };
+    }
+    const s = this.parseMutatorArgumentValue(e);
+    return s === null ? null : s;
+  }
+  /**
+   * Parse the value half of a mutator argument.
+   *
+   * Neither engine's grammar admits a list literal here, so `[...]` is an error rather
+   * than a silently-accepted superset.
+   */
+  parseMutatorArgumentValue(e) {
+    const t = this.isAtEnd() ? this.previous() : this.peek();
+    if (this.check("string")) {
+      const s = this.advance();
+      return { valueType: "string", value: s.value, start: s.start, end: s.end };
+    }
+    if (this.check("number")) {
+      const s = this.advance();
+      return { valueType: "number", value: parseFloat(s.value), start: s.start, end: s.end };
+    }
+    if (this.check("boolean")) {
+      const s = this.advance();
+      return { valueType: "boolean", value: s.value.toLowerCase() === "true", start: s.start, end: s.end };
+    }
+    if (this.check("null")) {
+      const s = this.advance();
+      return { valueType: "null", value: null, start: s.start, end: s.end };
+    }
+    if (A.has(t.type) && !this.isAtEnd()) {
+      const s = this.advance();
+      return { valueType: "identifier", value: s.value, start: s.start, end: s.end };
+    }
+    return this.check("bracket") ? (this.addError(
+      `List arguments are not supported by '${e}'`,
+      t,
+      "INVALID_VALUE",
+      "Pass a string, number, boolean or bare identifier"
+    ), null) : (this.addError(
+      `Expected an argument value in '${e}(...)'`,
+      t,
+      "MISSING_VALUE",
+      `Write it as ${e}(name="value") or ${e}("value")`
+    ), null);
   }
   // ============================================================================
   // Helper Methods
@@ -426,9 +764,52 @@ class v {
       end: e.end
     };
   }
+  /**
+   * Consume a `not` / `!` sitting between a field and its operator, if one is there.
+   *
+   * The two-token spelling is the PRIMARY form in both grammars, not an alias: fourteen
+   * rules in `tql/src/parser/grammar.pest` are declared as
+   * `not_X_op = { neg_prefix ~ X_op | not_X_word }`, and Python builds the same shape with
+   * `(CaselessKeyword("not") | "!") + CaselessKeyword("X")`. `field not contains "x"` is
+   * how the documentation and the UI examples spell it.
+   *
+   * This package accepted only the underscore form (`not_contains`) and the glued symbol
+   * (`!contains`). Every two-token negation -- `not exists`, `not in`, `not between`,
+   * `not startswith`, `not cidr`, ten more -- was reported as
+   * `Expected operator after field 'f'`, a false red on the most readable spelling of a
+   * third of the operator surface.
+   *
+   * Only consumed when a comparison operator actually follows. Without that lookahead this
+   * would swallow the `not` in `a eq 1 and b not (c eq 2)`, where it belongs to the unary
+   * arm; leaving it in place lets the existing error recovery report on it as before.
+   */
+  consumeNegationPrefix() {
+    if (!(this.check("logicalOp") && this.logicalWord(this.peek()) === "NOT"))
+      return null;
+    const e = this.peekAt(1);
+    return e === void 0 || e.type !== "operator" ? null : this.advance();
+  }
+  /**
+   * The negated form of an operator, or null when it has none.
+   *
+   * DERIVED from `COMPARISON_OPERATORS`, not transcribed: `not X` is a TQL operator exactly
+   * when `not_X` is. That catalog is itself derived from both engine grammars and pinned by
+   * `tests/catalogParity.spec.ts`, so this rule cannot drift from the grammars without that
+   * test going red first -- and `tests/negatedOperatorForms.spec.ts` re-derives the
+   * `neg_prefix ~ X_op` rules straight out of `grammar.pest` and asserts this parser accepts
+   * exactly them.
+   *
+   * Returning null rather than fabricating `not_eq` matters. Neither engine has a
+   * `neg_prefix ~ eq_op` rule, so `f not eq 1` is a syntax error in both, and inventing an
+   * operator no evaluator dispatches on would turn a parse error into an unknown-operator
+   * failure at execution -- later, and further from the user.
+   */
+  negateOperator(e) {
+    const t = `not_${e}`;
+    return k.includes(t) ? t : null;
+  }
   normalizeOperator(e) {
-    const t = e.toLowerCase(), r = {
-      "==": "eq",
+    const t = e.toLowerCase(), s = {
       "=": "eq",
       "!=": "ne",
       ">": "gt",
@@ -436,32 +817,16 @@ class v {
       "<": "lt",
       "<=": "lte"
     };
-    if (e in r)
-      return r[e];
-    const a = {
-      "!in": "not_in",
-      "!contains": "not_contains",
-      "!startswith": "not_startswith",
-      "!endswith": "not_endswith",
-      "!regexp": "not_regexp",
-      "!regex": "not_regex",
-      "!matches": "not_matches",
-      "!between": "not_between",
-      "!exists": "not_exists",
-      "!is": "is_not",
-      "!cidr": "not_cidr",
-      "!any": "not_any",
-      "!all": "not_all",
-      "!none": "not_none"
-    };
-    if (t in a)
-      return a[t];
+    if (e in s)
+      return s[e];
+    if (t in g)
+      return g[t];
     const n = {
       regex: "regexp",
       starts_with: "startswith",
       ends_with: "endswith"
     };
-    return t in n ? n[t] : (c.includes(t), t);
+    return t in n ? n[t] : (k.includes(t), t);
   }
   isAtEnd() {
     return this.current >= this.tokens.length;
@@ -469,6 +834,10 @@ class v {
   peek() {
     return this.tokens[this.current];
   }
+  /** Lookahead by `offset` tokens without consuming; undefined past the end. */
+  peekAt(e) {
+    return this.tokens[this.current + e];
+  }
   previous() {
     return this.tokens[this.current - 1];
   }
@@ -478,6 +847,19 @@ class v {
   check(e) {
     return this.isAtEnd() ? !1 : this.peek().type === e;
   }
+  /**
+   * True when the current token names a mutator in `MUTATORS` but was lexed as something
+   * else because an earlier catalog claimed the name first.
+   *
+   * Deliberately consults the catalog rather than listing the seven affected names: a list
+   * would be an eighth transcription of a set this package already maintains, and it would
+   * go stale the moment a mutator is added that collides with an aggregation.
+   */
+  isCatalogMutatorToken() {
+    if (this.isAtEnd()) return !1;
+    const e = this.peek();
+    return e.type !== "collectionOp" && e.type !== "aggregation" ? !1 : w.includes(e.value.toLowerCase());
+  }
   match(...e) {
     for (const t of e)
       if (this.check(t))
@@ -485,9 +867,31 @@ class v {
     return !1;
   }
   matchLogical(e) {
-    return this.check("logicalOp") && this.peek().value.toUpperCase() === e ? (this.advance(), !0) : !1;
+    return this.check("logicalOp") && this.logicalWord(this.peek()) === e ? (this.advance(), !0) : !1;
+  }
+  /**
+   * The canonical word a `logicalOp` token spells: `AND`, `OR` or `NOT`.
+   *
+   * `&&`, `||` and `!` are the symbolic halves of the same three grammar rules as `and`,
+   * `or` and `not` (see SYMBOL_LOGICAL_OPERATORS), so every consumer must see one name.
+   * Normalising HERE rather than in the tokenizer keeps the token's `value` equal to the
+   * source text, which the highlighting and completion surfaces read.
+   */
+  logicalWord(e) {
+    return E[e.value] ?? e.value.toUpperCase();
   }
-  addError(e, t, r, a) {
+  /**
+   * Match the WORD spelling of a logical operator only, never the symbol.
+   *
+   * Used for the `and` inside `field between low AND high`. Both engines spell that one
+   * literally -- `value ~ ^"and" ~ value` in `grammar.pest`, `CaselessKeyword("and")` in
+   * `between_comparison_natural` -- and neither accepts `between 1 && 5`. Accepting it here
+   * would make this package the only one of the three that does.
+   */
+  matchLogicalWord(e) {
+    return this.check("logicalOp") && this.peek().value.toUpperCase() === e && !(this.peek().value in E) ? (this.advance(), !0) : !1;
+  }
+  addError(e, t, s, n) {
     this.errors.push({
       message: e,
       start: t.start,
@@ -495,11 +899,11 @@ class v {
       line: t.line,
       column: t.column,
       severity: "error",
-      code: r,
-      suggestion: a
+      code: s,
+      suggestion: n
     });
   }
-  addWarning(e, t, r) {
+  addWarning(e, t, s, n = "TYPE_MISMATCH") {
     this.warnings.push({
       message: e,
       start: t.start,
@@ -507,8 +911,8 @@ class v {
       line: t.line,
       column: t.column,
       severity: "warning",
-      code: "TYPE_MISMATCH",
-      suggestion: r
+      code: n,
+      suggestion: s
     });
   }
   /**
@@ -517,7 +921,7 @@ class v {
    */
   synchronize() {
     for (this.advance(); !this.isAtEnd(); ) {
-      if (d.has(this.peek().type) || this.peek().type === "paren" && this.peek().value === ")")
+      if (O.has(this.peek().type) || this.peek().type === "paren" && this.peek().value === ")")
         return;
       this.advance();
     }
@@ -548,6 +952,88 @@ class v {
       end: e.end
     };
   }
+  /**
+   * Flag the malformed `top N` / `bottom N` spellings on a stats aggregation.
+   *
+   * ## Why this is a scan and not a stats parser
+   *
+   * This package deliberately does not build a stats AST — the engines do. But "we do not
+   * parse it" had silently become "we accept anything after `stats`": measured at HEAD, every
+   * one of `sum(x, top 10) top 5`, `sum(x) top by y` and `count(*, top 2)` is a parse error in
+   * BOTH engines and was reported valid here.
+   *
+   * A full stats parser would have to take a side on five spellings the engines currently
+   * DISAGREE about (`count(*) top 2`, `sum(x|trim) top 3`, `sum(x::number) top 3`,
+   * `sum(x|trim, top 3)`, `by y|trim top 3` — Rust accepts all five, Python refuses all five).
+   * Resolving those is an engine question. So this fires ONLY on shapes both engines refuse,
+   * and is silent everywhere else — it can never squiggle a query an engine accepts, which is
+   * the failure mode this parser keeps being repaired for.
+   *
+   * ## Why the group-by region is excluded
+   *
+   * `top` and `bottom` are ordinary identifiers, and `| stats sum(x) by top` is valid in BOTH
+   * engines — a group-by on a field named `top`. So "a `top` not followed by a number" is only
+   * unambiguous in the two AGGREGATION modifier positions: directly after the aggregation's
+   * `)`, or after a comma at the aggregation's own paren depth. `by y top` (no count) is
+   * refused by both engines and is deliberately NOT flagged here, because distinguishing it
+   * from `by top` needs the grammar this method is declining to reimplement.
+   */
+  checkStatsModifiers() {
+    const e = (s) => s !== void 0 && s.type === "keyword" && (s.value.toLowerCase() === "top" || s.value.toLowerCase() === "bottom");
+    let t = this.tokens.length;
+    for (let s = 0; s < this.tokens.length; s++) {
+      const n = this.tokens[s];
+      if (n.type === "keyword" && n.value.toLowerCase() === "by" || n.value === "=>") {
+        t = s;
+        break;
+      }
+    }
+    for (let s = 0; s < t; s++) {
+      if (this.tokens[s].type !== "aggregation") continue;
+      const n = s + 1;
+      if (n >= t || this.tokens[n].value !== "(") continue;
+      let i = 0, r = -1, u = -1, a;
+      for (let l = n; l < t; l++) {
+        const d = this.tokens[l];
+        if (d.value === "(") i++;
+        else if (d.value === ")") {
+          if (i--, i === 0) {
+            r = l;
+            break;
+          }
+        } else i === 1 && d.type === "comma" && (u === -1 && (u = l), e(this.tokens[l + 1]) && (a = this.tokens[l + 1]));
+      }
+      if (r === -1) continue;
+      const h = this.tokens.slice(n + 1, u === -1 ? r : u), p = h.length === 0 || h.length === 1 && h[0].value === "*", c = e(this.tokens[r + 1]) ? this.tokens[r + 1] : void 0;
+      a !== void 0 && c !== void 0 && this.addError(
+        "The 'top'/'bottom' modifier is given twice on one aggregation",
+        c,
+        "INVALID_STATS_MODIFIER",
+        "Write it once — either 'sum(x, top 10)' or 'sum(x) top 10'"
+      );
+      for (const l of [a, c]) {
+        if (l === void 0) continue;
+        const d = this.tokens.indexOf(l);
+        this.tokens[d + 1]?.type !== "number" && this.addError(
+          `Expected a count after '${l.value}'`,
+          l,
+          "INVALID_STATS_MODIFIER",
+          `Give the modifier a number, like '${l.value.toLowerCase()} 10'`
+        );
+      }
+      a !== void 0 && p && this.addError(
+        "'*' cannot take an in-parens 'top'/'bottom' modifier",
+        a,
+        "INVALID_STATS_MODIFIER",
+        "Name a field, or move the modifier outside the parentheses"
+      ), c !== void 0 && p && a === void 0 && this.addWarning(
+        _,
+        c,
+        "Name a field instead of '*', which both engines accept",
+        "ENGINE_DIVERGENCE"
+      );
+    }
+  }
   /**
    * Check if the token stream represents a stats query.
    * Handles: "| stats ...", "stats ...", or starts with a filter before "| stats".
@@ -572,23 +1058,24 @@ class v {
     return t >= this.tokens.length ? !1 : this.tokens[t].type === "keyword" && this.tokens[t].value.toLowerCase() === "stats";
   }
 }
-function l(i) {
-  return i ? new v(i).parse() : { ast: null, errors: [], warnings: [], tokens: [], success: !0 };
+function m(o) {
+  return o ? new I(o).parse() : { ast: null, errors: [], warnings: [], tokens: [], success: !0 };
 }
-function f(i) {
-  return l(i).success;
+function b(o) {
+  return m(o).success;
 }
-function y(i) {
-  return l(i).errors;
+function x(o) {
+  return m(o).errors;
 }
-function g(i) {
-  let e = `Error at line ${i.line}, column ${i.column}: ${i.message}`;
-  return i.suggestion && (e += ` (${i.suggestion})`), e;
+function M(o) {
+  let e = `Error at line ${o.line}, column ${o.column}: ${o.message}`;
+  return o.suggestion && (e += ` (${o.suggestion})`), e;
 }
 export {
-  v as TqlParser,
-  g as formatParseError,
-  y as getTqlErrors,
-  f as isValidTql,
-  l as parseTql
+  I as TqlParser,
+  S as collectionOperatorSpelling,
+  M as formatParseError,
+  x as getTqlErrors,
+  b as isValidTql,
+  m as parseTql
 };