Merge remote-tracking branch 'origin/main' into claude/issue-5330-empty-combinator-lint

Author: claude

.changeset/cel-classify-error-by-code.md

@@ -0,0 +1,57 @@
+---
+'@objectstack/formula': patch
+---
+
+fix(formula): `classifyError` grades a CEL fault by error class + code, never by the message (#6223)
+
+`EvalResult.error.kind` is author-facing — `@objectstack/objectql`'s `cel-fault`
+puts it in front of the author as `` `${kind}: ${first line}` `` and
+`packages/rest` re-emits it as the HTTP body's `reason`. cel-js embeds the
+author's own **source line** in `message` (`formatErrorWithHighlight`), so a
+classifier that regex-matches that text is matching text the author writes.
+PR #6202 closed the `ParseError` arm this way and left `type` / `runtime` on the
+keyword table pending a per-code audit. This is that audit, and its verdict is
+that the table goes entirely.
+
+Measured on cel-js 8.0.0 — one `no such overload` **evaluation** fault, four
+field names, three wrong answers:
+
+```text
+record.status        > 1  ->  runtime   (right)
+record.parse_status  > 1  ->  parse     (wrong)
+record.syntax_mode   > 1  ->  parse     (wrong)
+record.type_code     > 1  ->  type      (wrong)
+```
+
+`parse` is the inverse of the #6133 misdirection: the expression is
+syntactically perfect and failed on the data, and the author was told to go fix
+an expression that has nothing wrong with it.
+
+`classifyError` now reads only structured contract:
+
+- `ParseError` -> `bounds` when `code === 'limit_exceeded'`, else `parse`
+  (unchanged, from #6202);
+- `EvaluationError` -> `type` for the one declaration-class code
+  (`unknown_variable`, the root identifier is not bound in this scope at all),
+  else `runtime`;
+- anything that is not a cel-js error -> `runtime`.
+
+Two findings from the audit worth recording. First, the residual keyword arm was
+**not** dormant: `matches()` is an ObjectStack stdlib binding over `new
+RegExp(...)`, so an uncompilable pattern escapes as a native `SyntaxError` whose
+message echoes the pattern — and the pattern can come off the row, not just out
+of the source. `matches(record.name, record.re)` with `re = "type("` was
+graded `type`; with `"Exceeded maxAstNodes("` it was graded `bounds`. A data
+value was picking the error kind. Second, there is deliberately no `TypeError`
+arm: cel-js raises that class only from its non-evaluating `TypeChecker`, which
+runs only inside `Environment#check`, and that method catches it and *returns*
+`{ valid: false, error }`. The check-time `TypeError -> type` mapping already
+lives in `celEngine.compile`, which reads that object.
+
+Six evaluate-time codes change verdict from `type` to `runtime`
+(`int_conversion_error`, `uint_conversion_error`, `double_conversion_error`,
+`invalid_index_type`, `heterogeneous_list_element`,
+`invalid_comprehension_range`). Each is a fault decided against the row; every
+one of them was graded `type` only because cel-js happens to use the word "type"
+in its prose (`int() type error: cannot convert to int`). Every evaluate-time
+code the engine can reach now has a fixture pinning its `kind`.

.changeset/filter-token-brace-intent.md

@@ -0,0 +1,57 @@
+---
+"@objectstack/spec": patch
+"@objectstack/core": patch
+"@objectstack/lint": patch
+---
+
+fix(spec,core): a filter placeholder is recognised by INTENT — `{TODAY()}` refuses loudly instead of comparing as a literal (#5586)
+
+`UnknownFilterTokenError` had a hole exactly where authors fall in. Recognition
+used the token-NAME grammar `/^\$?\{([a-zA-Z0-9_]+)\}$/`, so any placeholder
+carrying a **non-word character** classified as "not a placeholder at all" and
+was handed to the driver verbatim, to be compared as a literal string — the
+silent-wrong-result failure the diagnostic exists to abolish.
+
+The failure was inverted against the author. Measured on 17.0.0-rc.2 against a
+four-row fixture:
+
+| filter value | before | |
+|---|---|---|
+| `due_date < '{today}'` | 2 rows | correct — the two overdue rows |
+| `due_date < '{TODAY}'` | throws `UnknownFilterTokenError` | diagnostic working |
+| `due_date < '{TODAY()}'` | **4 rows** | diagnostic bypassed — literal string compare, and `'2026-…' < '{'` in lexicographic order swallowed a row due a week later |
+
+So misspelling `{today}` as `{TODAY}` was reported by name, while misspelling it
+as `{TODAY()}` returned the wrong rows in silence — and the parenthesised,
+kebab-case, natural-language and dotted spellings (`{TODAY()}`,
+`{current-user-id}`, `{30 days ago}`, `{user.id}`) are precisely what an author
+migrating from another system's macro syntax writes first.
+
+**Both directions of the behaviour change:**
+
+- **Previously silent, now refuses loudly** — a filter value that is entirely
+  brace-wrapped and outside the vocabulary now throws `UnknownFilterTokenError`
+  (`code: FILTER_TOKEN_UNKNOWN`, `status: 400`) on the ObjectQL read and write
+  paths and the analytics dataset executor, and is reported as
+  `filter-token-unknown` by `objectstack build` / `validate` / `lint`. Before,
+  it reached the data engine and compared as text.
+- **Unchanged** — `{today}` / `{current_user_id}` still resolve; `{TODAY}` still
+  refuses with the same identity; a value that merely *contains* braces
+  (`'acme {x} deal'`), or is not ONE pair around the whole value (`{a}{b}`,
+  `{{x}}`, `{}`), is still an ordinary literal and still reaches the driver
+  untouched.
+
+Recognition and vocabulary are now two named grammars rather than one:
+`FILTER_TOKEN_WRAPPED_RE` (`/^\$?\{([^{}]+)\}$/`) answers "did the author mean a
+placeholder", and `isContextToken` / `isDateMacroToken` answer "is it in the
+vocabulary". Wide in, strict out. No escape hatch for a literal `{…}` comparand
+ships with this: a repo-wide measurement across structured metadata, examples,
+seed data and fixtures found zero legitimate consumers comparing a
+brace-wrapped literal, and an escape syntax is a public micro-contract that can
+be added the day one shows up.
+
+Flow templates are unaffected. `interpolateFilter` in
+`@objectstack/service-automation` already recognised the same wide shape and
+resolves `{record.id}` / `{TODAY() + 30}` from flow variables **before** the
+filter reaches ObjectQL; its hand-off to the engine is keyed on the token
+vocabulary (`isKnownFilterToken`), which this change does not touch.

packages/core/src/utils/filter-tokens.test.ts

@@ -232,6 +232,83 @@ describe('resolveFilterTokens — tree walk', () => {
   });
 });
 
+/**
+ * #5586 — a placeholder carrying a NON-WORD character used to bypass the
+ * diagnostic entirely.
+ *
+ * Recognition was the token-NAME grammar, so `{TODAY()}` classified as "not a
+ * placeholder", was handed to the driver verbatim and compared as a literal
+ * string. Measured on 17.0.0-rc.2 against a four-row fixture: `due_date <
+ * '{today}'` returned the 2 genuinely overdue rows, `due_date < '{TODAY()}'`
+ * returned all 4 — lexicographic string order puts every `'2026-…'` before
+ * `'{'`, so the window silently swallowed a row due a week later.
+ *
+ * The refusal is asserted on the ADR-0112 envelope (`code` + `status`) plus the
+ * offending token, never on the bare fact of a throw: the resolver already
+ * throws for other reasons, so a throw-only assertion cannot tell "refused with
+ * the right identity" from "blew up somewhere else".
+ */
+describe('resolveFilterTokens — non-word placeholder shapes refuse loudly (#5586)', () => {
+  const ctx = { now: NOW, userId: 'usr_1', orgId: 'org_9' };
+
+  const shapes: Array<[label: string, value: string, token: string]> = [
+    ['call syntax (Salesforce/Excel migrants)', '{TODAY()}', 'TODAY()'],
+    ['kebab-case', '{current-user-id}', 'current-user-id'],
+    ['natural language', '{30 days ago}', '30 days ago'],
+    ['dotted path', '{user.id}', 'user.id'],
+    ['the `${…}` prefix variant', '${TODAY()}', 'TODAY()'],
+  ];
+
+  it.each(shapes)('%s — %s refuses with the full error identity', (_label, value, token) => {
+    let err: unknown;
+    try {
+      resolveFilterTokens({ due_date: { $lt: value } }, ctx);
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(UnknownFilterTokenError);
+    const e = err as UnknownFilterTokenError;
+    expect(e.name).toBe('UnknownFilterTokenError');
+    // ADR-0112 envelope: the caller's filter is malformed, the server is fine.
+    expect(e.code).toBe('FILTER_TOKEN_UNKNOWN');
+    expect(e.status).toBe(400);
+    // The author has to see what THEY wrote, not a normalised paraphrase.
+    expect(e.token).toBe(token);
+    expect(e.message).toContain(`{${token}}`);
+  });
+
+  it('still resolves the canonical spelling — the widening did not eat `{today}`', () => {
+    expect(resolveFilterTokens({ due_date: { $lt: '{today}' } }, ctx))
+      .toEqual({ due_date: { $lt: '2026-07-15' } });
+  });
+
+  it('still refuses the word-character near miss `{TODAY}`', () => {
+    // The shape that ALREADY worked. It is the control: if this ever goes
+    // quiet, the widening has replaced the diagnostic instead of extending it.
+    let err: unknown;
+    try {
+      resolveFilterTokens({ due_date: { $lt: '{TODAY}' } }, ctx);
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(UnknownFilterTokenError);
+    expect((err as UnknownFilterTokenError).token).toBe('TODAY');
+    expect((err as UnknownFilterTokenError).code).toBe('FILTER_TOKEN_UNKNOWN');
+  });
+
+  // Decided, not emergent: recognition is ONE brace pair around the WHOLE
+  // value. Anything else is ordinary text and reaches the driver untouched —
+  // that is what keeps `titleFormat`-style strings and human prose out of the
+  // rule, and it is the property that holds false positives at zero.
+  it.each(['acme {x} deal', '{a}{b}', '{{x}}', '{}', '{a}b', 'x{a}'])(
+    '%s is a literal and passes through unchanged',
+    (value) => {
+      const filter = { title: value };
+      expect(resolveFilterTokens(filter, ctx)).toBe(filter);
+    },
+  );
+});
+
 describe('filterTokenContextFrom', () => {
   it('maps ExecutionContext onto the resolver inputs', () => {
     expect(

packages/core/src/utils/filter-tokens.ts

@@ -48,6 +48,18 @@
  * through is precisely the silent-zero bug this module exists to end, so it is
  * a hard error carrying the near-miss suggestion (`{current_user}` →
  * `{current_user_id}`). Values that merely CONTAIN braces are left untouched.
+ *
+ * "Entirely `{something}`" means ANY character between the braces (#5586).
+ * Until then the recognition grammar was the token-NAME grammar
+ * (`[a-zA-Z0-9_]+`), so a placeholder carrying a non-word character —
+ * `{TODAY()}`, `{current-user-id}`, `{30 days ago}`, `{user.id}` — was not
+ * recognised as a token at all and fell straight through to the literal
+ * comparison this module exists to abolish. The failure was inverted against
+ * the author: `{TODAY}` threw (diagnostic working), `{TODAY()}` returned rows
+ * (diagnostic bypassed) — and the parenthesised, kebab-case and
+ * natural-language spellings are exactly what an author migrating from another
+ * system's macro syntax reaches for first. See `FILTER_TOKEN_WRAPPED_RE` in
+ * `@objectstack/spec`.
  */
 
 import {