@tellaro/tql 1.4.3 → 2.0.0

package/dist/src/validator.d.ts

@@ -1,4 +1,52 @@
-import { TqlParseError, TqlParseWarning, TqlValidationOptions, TqlValidationResult } from './types';
+import { TqlFieldType, TqlParseError, TqlParseWarning, TqlValidationOptions, TqlValidationResult } from './types';
+/**
+ * Maximum regex pattern length TQL will compile, in characters (code points).
+ *
+ * A pattern longer than this is refused by every TQL runtime. It is flagged here
+ * -- in the editor, as the user types -- because the alternative is discovering
+ * it after the rule has been saved and deployed: before tql#185 the Python
+ * evaluator answered "no match" for an over-long pattern while the query parsed
+ * cleanly and reported health green, so a detection rule carrying one never
+ * fired and nothing anywhere said so.
+ *
+ * Mirrored by `MAX_REGEX_PATTERN_LENGTH` in `src/tql/regex_guard.py` and
+ * `tql/src/comparator.rs`. Changing it in one place only re-creates the
+ * divergence.
+ */
+export declare const MAX_REGEX_PATTERN_LENGTH = 1000;
+/**
+ * Every field type in the `TqlFieldType` union.
+ *
+ * Declared once so an operator that genuinely applies to everything says so by NAME rather
+ * than by a transcribed twelve-element list — and so a new field type cannot be added to the
+ * union while silently falling out of the operators it belongs to.
+ * `tests/collectionOperatorTypes.spec.ts` reads the union out of `src/types.ts` and asserts
+ * this array is exactly it, so a divergence is a red rather than a quiet narrowing.
+ */
+export declare const ALL_FIELD_TYPES: TqlFieldType[];
+/**
+ * Every numeric field type in the union — all nine widths, not the five that get typed out.
+ */
+export declare const NUMERIC_FIELD_TYPES: TqlFieldType[];
+/**
+ * The types an ORDERED comparison (`gt`/`gte`/`lt`/`lte`) is defined over.
+ *
+ * Numeric and date, plus `keyword`: both evaluators fall back to a lexicographic string
+ * comparison when neither side reads as a number, and Python's own validator lists all four
+ * operators in its `keyword_ops`. `text` is excluded on that same source's reasoning — a
+ * range over an analyzed field compares tokens, not the value the user typed.
+ */
+export declare const ORDERED_FIELD_TYPES: TqlFieldType[];
+/**
+ * The types `between` / `not_between` are defined over.
+ *
+ * `ORDERED_FIELD_TYPES` minus `keyword`. The four ordered operators and `between` are NOT
+ * the same set, and the difference is Python's, not this package's: `keyword_ops` in
+ * `_validate_simple_type_compatibility` lists `gt`/`gte`/`lt`/`lte` and excludes `between`.
+ * `tests/collectionAndNullSemantics.spec.ts` pins that exclusion against the Python source,
+ * so this constant self-retires if Python ever adds it.
+ */
+export declare const BETWEEN_FIELD_TYPES: TqlFieldType[];
 export declare class TqlValidator {
     private options;
     private errors;
@@ -12,6 +60,58 @@ export declare class TqlValidator {
      * Validate an expression recursively
      */
     private validateExpression;
+    /**
+     * `f any ['a','b']` is ill-typed. Say so, and name `in`.
+     *
+     * ## The rule, as both engines implement it
+     *
+     * `any` / `none` apply a comparison to each ELEMENT of an array-valued field. The operand
+     * is therefore a SCALAR: `f any 'admin'` asks whether some element equals `'admin'`. A
+     * LIST operand asks whether some single element equals the whole two-element list, which
+     * no scalar element can. `in` is already the membership operator, and is what the author
+     * meant.
+     *
+     * Both engines now refuse it -- `ab55587` in `tql/src/opensearch/query_builder.rs`
+     * (`build_collection_op`) and `_refuse_list_operand` in
+     * `src/tql/opensearch_components/query_converter.py` -- raising a type error whose
+     * `valid_operators` are `in` / `not in`. Before that it emitted `{"term": {"f": [..]}}`,
+     * which OpenSearch answers with HTTP 400 `[term] query does not support array of values`,
+     * failing the WHOLE search including every unrelated clause; the intermediate fix emitted
+     * `match_none`, which executed cleanly and excluded nothing, silently.
+     *
+     * ## Three arities, and only the middle one is new
+     *
+     * The engines do NOT test `is_array`. They unwrap a single-element list FIRST
+     * (`unwrap_single` in Rust, `len(value) == 1` in Python) and refuse only what is still a
+     * list. Measured against the live Python translator at `ab55587`:
+     *
+     * | Query              | Python translator                                    |
+     * |--------------------|------------------------------------------------------|
+     * | `f any 'admin'`    | `{"term": {"f": "admin"}}`                            |
+     * | `f any ['a']`      | `{"term": {"f": "a"}}` -- unwrapped, NOT refused      |
+     * | `f any ['a','b']`  | `TQLTypeError`, valid operators `in`, `not in`        |
+     *
+     * A naive `Array.isArray(value)` check would flag `f any ['a']`, which both engines
+     * translate perfectly well -- a red squiggle over a working query, which is the defect
+     * this parser keeps being fixed for. Hence `length >= 2`, and hence the two arities are
+     * tested separately in `tests/collectionListOperand.spec.ts`.
+     *
+     * The empty list is not handled here: `f any []` is already an `INVALID_VALUE` error from
+     * the parser (`tests/emptyValueList.spec.ts`), and Python does not even parse it
+     * (`TQLSyntaxError`). Reporting it twice would be noise.
+     *
+     * ## Why `ALL` is excluded, and why that is not an oversight
+     *
+     * `all` / `not_all` are answered by a Painless script that compares each element to
+     * `params.value`. A list operand there emits valid DSL that matches nothing -- which is
+     * what both in-memory evaluators also answer -- so both engines dispatch `all` BEFORE the
+     * refusal and leave it untouched. `f all ['a','b']` translating cleanly is a pinned
+     * negative case here, not a gap.
+     *
+     * Negation is irrelevant: in both engines the array check precedes the quantifier wrapper,
+     * so `not any` / `not none` refuse on the same footing as the positive spellings.
+     */
+    private validateCollectionOperand;
     /**
      * Validate a comparison expression
      */