@objectstack/formula 9.6.0 → 9.8.0

package/src/cel-engine.ts

@@ -16,7 +16,7 @@
 import { Environment } from '@marcbachmann/cel-js';
 import type { Expression } from '@objectstack/spec';
 
-import { buildScope, registerStdLib } from './stdlib';
+import { buildScope, registerNumericCoercions, registerStdLib } from './stdlib';
 import type { DialectEngine, EvalContext, EvalResult } from './types';
 
 /**
@@ -38,7 +38,91 @@ function buildEnv(now: () => Date): Environment {
     enableOptionalTypes: true,
     limits: DEFAULT_LIMITS,
   });
-  return registerStdLib(env, now);
+  return registerNumericCoercions(registerStdLib(env, now));
+}
+
+/**
+ * Namespace roots that a `record`-scoped CEL site may legitimately reference.
+ * Declared as `map` (dyn values) so member access (`record.foo`) and any
+ * arithmetic/comparison on it defers to runtime — the strict env faults ONLY on
+ * an *undeclared* top-level identifier, i.e. a bare field reference. Generous on
+ * purpose: an unknown root is a missed catch, a missing root is a false positive
+ * that would break the build, so we err toward declaring more.
+ */
+const SCOPE_ROOTS = [
+  'record', 'previous', 'input', 'output', 'os', 'vars', 'variables',
+  'automation', 'context', 'args', 'item', 'env', 'user', 'step', 'result',
+  'trigger', 'event', 'payload', 'data', 'params', 'config', 'settings',
+] as const;
+
+/**
+ * A `record`-scoped environment (`unlistedVariablesAreDyn: false`) for detecting
+ * bare field references. It reuses the real stdlib so function calls don't fault;
+ * only undeclared *variables* do. Built once — `parse`/`check` do not mutate it.
+ */
+function buildScopedEnv(knownFields: readonly string[]): Environment {
+  const env = new Environment({
+    unlistedVariablesAreDyn: false,
+    enableOptionalTypes: true,
+    limits: DEFAULT_LIMITS,
+  });
+  registerStdLib(env, () => new Date(0));
+  for (const root of SCOPE_ROOTS) {
+    try { env.registerVariable(root, 'map'); } catch { /* duplicate — ignore */ }
+  }
+  // `knownFields` are declared as `dyn` so they (and member/arith/compare on
+  // them) never fault — only a genuinely-undeclared top-level identifier does.
+  // Empty for a record-scope site (any bare field is a bug); the trigger
+  // object's fields for a flattened flow condition (only a NON-field bare ref —
+  // a typo or flow variable — is then interesting).
+  for (const field of knownFields) {
+    try { env.registerVariable(field, 'dyn'); } catch { /* duplicate / reserved — ignore */ }
+  }
+  return env;
+}
+
+// Roots-only env reused for the common record-scope check (no per-call rebuild).
+let recordScopeEnv: Environment | undefined;
+
+/**
+ * In a `record`-scoped CEL site — a `Field.formula` or an object validation
+ * predicate — the evaluation scope binds only the `record`/`previous`/… *namespaces*
+ * (no field flattening). A bare top-level identifier like `amount` or `status`
+ * therefore resolves to nothing and the expression silently evaluates to `null`
+ * / never fires (#1928, the class behind #1927's broken formulas). Returns the
+ * first such bare reference, or `null`.
+ *
+ * Acts ONLY on cel-js's `Unknown variable: X` fault, so it cannot false-positive
+ * on arithmetic/comparison overloads — and it must NOT be applied to flow /
+ * automation conditions, where the record's fields ARE flattened to top-level
+ * and bare references are correct.
+ */
+export function firstUndeclaredReference(
+  source: string,
+  knownFields: readonly string[] = [],
+): string | null {
+  if (typeof source !== 'string' || !source.trim()) return null;
+  try {
+    const env = knownFields.length === 0
+      ? (recordScopeEnv ??= buildScopedEnv([]))
+      : buildScopedEnv(knownFields);
+    const result = env.parse(source).check?.() as
+      | { valid: boolean; error?: { message?: string } }
+      | undefined;
+    if (result && result.valid === false) {
+      const m = /Unknown variable:\s*([A-Za-z_$][\w$]*)/.exec(result.error?.message ?? '');
+      if (m) return m[1];
+    }
+  } catch {
+    // Parse/other faults are the syntax checker's job (celEngine.compile); this
+    // helper only reports the undeclared-variable case.
+  }
+  return null;
+}
+
+/** @deprecated use {@link firstUndeclaredReference} with no fields. */
+export function detectBareReference(source: string): string | null {
+  return firstUndeclaredReference(source);
 }
 
 /** Coerce cel-js's BigInt-flavored return into spec-friendly JS values. */

package/src/stdlib.ts

@@ -22,6 +22,16 @@ function startOfDayUtc(d: Date): Date {
   return out;
 }
 
+/** Coerce a CEL value (Date | ISO string | epoch number) to a Date. */
+function toDate(v: unknown): Date {
+  if (v instanceof Date) return v;
+  if (typeof v === 'number' || typeof v === 'bigint') return new Date(Number(v));
+  return new Date(String(v));
+}
+
+/** One UTC day in milliseconds. */
+const MS_PER_DAY = 86_400_000;
+
 /** Add `n` days to a Date in UTC; returns a new Date. */
 function addDaysUtc(d: Date, n: number): Date {
   const out = new Date(d.getTime());
@@ -101,9 +111,90 @@ export function registerStdLib(
         }
         return parts.join(separator);
       },
+    )
+    // ── Dates ────────────────────────────────────────────────────────────
+    // Whole days from `a` to `b` (negative if `b` is before `a`). The common
+    // shape is `daysBetween(today(), record.due)` for "days remaining". Args are
+    // coerced (Date | ISO string | epoch) so a `Field.date` that arrives as a
+    // string still works without the caller hydrating it.
+    .registerFunction(
+      'daysBetween(dyn, dyn): int',
+      (a: unknown, b: unknown) =>
+        BigInt(Math.round((toDate(b).getTime() - toDate(a).getTime()) / MS_PER_DAY)),
+    )
+    // Parse an ISO date / date-time string to a Timestamp. `date` and `datetime`
+    // are aliases — both accept either form (the field's own type decides the
+    // intent); kept distinct because authors reach for whichever reads clearer.
+    .registerFunction('date(dyn): google.protobuf.Timestamp', (s: unknown) => toDate(s))
+    .registerFunction('datetime(dyn): google.protobuf.Timestamp', (s: unknown) => toDate(s))
+    // ── Numbers ──────────────────────────────────────────────────────────
+    .registerFunction('abs(dyn): double', (x: unknown) => Math.abs(Number(x)))
+    .registerFunction('round(dyn): int', (x: unknown) => BigInt(Math.round(Number(x))))
+    // min/max return the smaller/larger operand verbatim (type preserved) rather
+    // than a coerced copy, so `min(record.a, record.b)` keeps int-ness when both
+    // are ints. Comparison is numeric.
+    .registerFunction('min(dyn, dyn): dyn', (a: unknown, b: unknown) => (Number(a) <= Number(b) ? a : b))
+    .registerFunction('max(dyn, dyn): dyn', (a: unknown, b: unknown) => (Number(a) >= Number(b) ? a : b))
+    // ── Strings ──────────────────────────────────────────────────────────
+    // Free-function forms of the common string ops. CEL also exposes some as
+    // receiver methods (`s.contains(x)`), but the authoring catalog advertises
+    // the bare-call form, so register it to match what authors are told to use.
+    .registerFunction('upper(dyn): string', (s: unknown) => String(s ?? '').toUpperCase())
+    .registerFunction('lower(dyn): string', (s: unknown) => String(s ?? '').toLowerCase())
+    .registerFunction('contains(dyn, dyn): bool', (s: unknown, sub: unknown) => String(s ?? '').includes(String(sub ?? '')))
+    .registerFunction('startsWith(dyn, dyn): bool', (s: unknown, p: unknown) => String(s ?? '').startsWith(String(p ?? '')))
+    .registerFunction('endsWith(dyn, dyn): bool', (s: unknown, p: unknown) => String(s ?? '').endsWith(String(p ?? '')))
+    .registerFunction('matches(dyn, dyn): bool', (s: unknown, re: unknown) => new RegExp(String(re ?? '')).test(String(s ?? '')))
+    // ── Collections ──────────────────────────────────────────────────────
+    // `len` mirrors CEL's built-in `size()` for strings/lists/maps; `isEmpty` is
+    // the inverse-of-non-empty companion to `isBlank` (true for null, '', []).
+    .registerFunction('len(dyn): int', (v: unknown) => BigInt(lengthOf(v)))
+    .registerFunction(
+      'isEmpty(dyn): bool',
+      (v: unknown) => v === null || v === undefined || lengthOf(v) === 0,
     );
 }
 
+/** Length of a string / list / map (0 for scalars and null). */
+function lengthOf(v: unknown): number {
+  if (v === null || v === undefined) return 0;
+  if (typeof v === 'string' || Array.isArray(v)) return v.length;
+  if (typeof v === 'object') return Object.keys(v as Record<string, unknown>).length;
+  return 0;
+}
+
+/**
+ * Register mixed `double <op> int` / `int <op> double` arithmetic overloads.
+ *
+ * cel-js types a record field number as `double` and a bare integer literal as
+ * `int`, and ships overloads only for matching pairs (`double op double`,
+ * `int op int`). So a formula as ordinary as `record.amount / 100` or
+ * `record.price * 2` faults at runtime (`no such overload: dyn<double> / int`);
+ * the engine catches the fault and the formula silently evaluates to `null`
+ * (#1928). Authors then have to know the cel-js quirk and write `/ 100.0`.
+ *
+ * We close the gap by registering the missing mixed overloads. The result is
+ * always computed as a JS `double`, matching CEL's promotion rule for mixed
+ * numeric arithmetic. Pure `int op int` is untouched, so integer division
+ * (`7 / 2 == 3`) keeps its semantics — these overloads only fire when the two
+ * operands are genuinely a `double` and an `int`.
+ */
+export function registerNumericCoercions(env: Environment): Environment {
+  const ops: Record<string, (a: number, b: number) => number> = {
+    '+': (a, b) => a + b,
+    '-': (a, b) => a - b,
+    '*': (a, b) => a * b,
+    '/': (a, b) => a / b,
+    '%': (a, b) => a % b,
+  };
+  for (const [op, fn] of Object.entries(ops)) {
+    const impl = (a: unknown, b: unknown) => fn(Number(a), Number(b));
+    env.registerOperator(`double ${op} int`, impl);
+    env.registerOperator(`int ${op} double`, impl);
+  }
+  return env;
+}
+
 /**
  * Build the variable scope for a single evaluation. Absent fields are simply
  * not bound — CEL macros (`has(record.foo)`) handle missing-key safely.

package/src/validate.test.ts

@@ -80,6 +80,79 @@ describe('validateExpression (ADR-0032)', () => {
     });
   });
 
+  // #1928 — a bare top-level identifier is a silent bug in a `record`-scoped
+  // site (formula field / validation predicate) but correct in a `flattened`
+  // flow/automation condition. The validator must distinguish by `scope`.
+  describe('bare-reference detection by scope (#1928)', () => {
+    it('flags a bare field reference in a record-scoped predicate', () => {
+      const r = validateExpression('predicate', 'lead_score != null && lead_score > 100', { scope: 'record' });
+      expect(r.ok).toBe(false);
+      expect(r.errors[0].message).toMatch(/bare reference `lead_score`/);
+      expect(r.errors[0].message).toMatch(/record\.lead_score/);
+    });
+
+    it('flags a bare reference in a record-scoped value (formula) expression', () => {
+      const r = validateExpression('value', '(budget == null ? 0 : budget) - (spent == null ? 0 : spent)', { scope: 'record' });
+      expect(r.ok).toBe(false);
+      expect(r.errors[0].message).toMatch(/bare reference `(budget|spent)`/);
+    });
+
+    it('accepts the record-qualified form in a record-scoped site', () => {
+      const r = validateExpression('value', '(record.budget == null ? 0 : record.budget) - (record.spent == null ? 0 : record.spent)', { scope: 'record' });
+      expect(r.ok).toBe(true);
+    });
+
+    it('does NOT flag bare references in a flattened (flow) condition', () => {
+      // The record's fields are flattened to top-level for flow conditions, and
+      // flow variables share that namespace, so bare refs are correct here.
+      expect(validateExpression('predicate', 'status == "done" && previous.status != "done"', { scope: 'flattened' }).ok).toBe(true);
+      expect(validateExpression('predicate', 'budget > 100000', { scope: 'flattened' }).ok).toBe(true);
+      expect(validateExpression('predicate', 'expiring_deals.length > 0', { scope: 'flattened' }).ok).toBe(true);
+    });
+
+    it('defaults to flattened scope (no bare-ref flag) when scope is unset', () => {
+      expect(validateExpression('predicate', 'status == "done"').ok).toBe(true);
+    });
+
+    it('does not flag a null-guard on a record-qualified field (no type false-positive)', () => {
+      expect(validateExpression('predicate', 'record.lead_score != null && record.lead_score > 100', { scope: 'record' }).ok).toBe(true);
+    });
+  });
+
+  // #1928 tier 3 — flattened flow conditions reference fields bare, so a bare
+  // ref is not an error. A bare NON-field that is a near-miss of a known field
+  // is a likely typo → non-blocking warning (ok stays true).
+  describe('flow-condition typo warnings (#1928 tier 3)', () => {
+    const fields = ['stage', 'amount', 'status'] as const;
+
+    it('warns (does not error) on a likely field typo in a flattened condition', () => {
+      const r = validateExpression('predicate', 'stagee == "closed_won"', { objectName: 'crm_opportunity', fields, scope: 'flattened' });
+      expect(r.ok).toBe(true);
+      expect(r.errors).toHaveLength(0);
+      expect(r.warnings).toHaveLength(1);
+      expect(r.warnings[0].message).toMatch(/`stagee` is not a field/);
+      expect(r.warnings[0].message).toMatch(/did you mean `stage`/);
+    });
+
+    it('does not warn on a correct bare field reference', () => {
+      const r = validateExpression('predicate', 'stage == "closed_won" && previous.stage != "closed_won"', { objectName: 'crm_opportunity', fields, scope: 'flattened' });
+      expect(r.ok).toBe(true);
+      expect(r.warnings).toHaveLength(0);
+    });
+
+    it('does not warn on a flow variable that is far from any field name', () => {
+      const r = validateExpression('predicate', 'expiring_deals.length > 0', { objectName: 'crm_opportunity', fields, scope: 'flattened' });
+      expect(r.ok).toBe(true);
+      expect(r.warnings).toHaveLength(0);
+    });
+
+    it('emits no warnings without a field list (nothing to compare against)', () => {
+      const r = validateExpression('predicate', 'stagee == "x"', { scope: 'flattened' });
+      expect(r.ok).toBe(true);
+      expect(r.warnings).toHaveLength(0);
+    });
+  });
+
   describe('introspection', () => {
     it('reports the dialect + scope for a field role', () => {
       expect(expectedDialect('predicate')).toBe('cel');

package/src/validate.ts

@@ -17,7 +17,7 @@
  * This validator detects that specific mistake and returns the exact fix.
  */
 
-import { celEngine } from './cel-engine';
+import { celEngine, firstUndeclaredReference } from './cel-engine';
 import { templateEngine } from './template-engine';
 
 export type FieldRole = 'predicate' | 'value' | 'template';
@@ -36,6 +36,23 @@ export interface ExprSchemaHint {
   objectName?: string;
   /** Known top-level field names, so `record.<field>` can be checked. */
   fields?: readonly string[];
+  /**
+   * Evaluation scope of the authoring site — determines whether a bare top-level
+   * identifier is legal (#1928):
+   *  - `'record'`    → the record is bound only as the `record` namespace, with
+   *                    no field flattening (`Field.formula`, object validation
+   *                    predicates). A bare `amount` resolves to nothing and the
+   *                    expression silently evaluates to `null` / never fires, so
+   *                    it MUST be written `record.amount`. We flag bare refs.
+   *  - `'flattened'` → the record's own fields are spread to top-level alongside
+   *                    flow variables (flow / automation conditions), so bare
+   *                    `status` is correct and is NOT an error. Flow variables
+   *                    are not schema-knowable, so a non-field bare identifier
+   *                    can't be soundly told apart from a typo — but when one is
+   *                    a near-miss of a known field we emit a non-blocking
+   *                    did-you-mean *warning*. (Default.)
+   */
+  scope?: 'record' | 'flattened';
 }
 
 export interface ExprValidationError {
@@ -48,6 +65,13 @@ export interface ExprValidationError {
 export interface ExprValidationResult {
   ok: boolean;
   errors: ExprValidationError[];
+  /**
+   * Non-blocking advisories (#1928 tier 3): a likely-typo'd field reference in a
+   * flattened flow condition. Never affects `ok` — callers surface these without
+   * failing the build, since a bare identifier there may legitimately be a flow
+   * variable.
+   */
+  warnings: ExprValidationError[];
 }
 
 /** A bare `{x}` that is NOT part of a `{{x}}` mustache hole. */
@@ -134,14 +158,15 @@ export function validateExpression(
 ): ExprValidationResult {
   const { dialect, source } = toSource(input);
   const errors: ExprValidationError[] = [];
-  if (!source.trim()) return { ok: true, errors };
+  const warnings: ExprValidationError[] = [];
+  if (!source.trim()) return { ok: true, errors, warnings };
 
   if (role === 'template') {
     // Templates must be the `template` dialect (or untyped string). Reject a
     // CEL envelope mistakenly placed in a text field.
     if (dialect && dialect !== 'template') {
       errors.push({ source, message: `expected a text template but got a \`${dialect}\` expression.` });
-      return { ok: false, errors };
+      return { ok: false, errors, warnings };
     }
     const compiled = templateEngine.compile(source);
     if (!compiled.ok) {
@@ -150,13 +175,13 @@ export function validateExpression(
     // A single `{x}` in a template is the legacy/deprecated form (ADR-0032 §3).
     const hint = SINGLE_BRACE_RE.test(source) ? bracesHintForTemplate(source) : null;
     if (hint) errors.push({ source, message: hint });
-    return { ok: errors.length === 0, errors };
+    return { ok: errors.length === 0, errors, warnings };
   }
 
   // predicate | value → CEL
   if (dialect && dialect !== 'cel') {
     errors.push({ source, message: `expected a CEL expression but got a \`${dialect}\` dialect.` });
-    return { ok: false, errors };
+    return { ok: false, errors, warnings };
   }
   const compiled = celEngine.compile(source);
   if (!compiled.ok) {
@@ -169,8 +194,41 @@ export function validateExpression(
     });
   } else {
     checkFieldExistence(source, schema, errors);
+    if (schema?.scope === 'record') {
+      // In a `record`-scoped site a bare top-level identifier is a silent bug —
+      // it must be `record.<field>` (#1928). Hard error.
+      const bare = firstUndeclaredReference(source);
+      if (bare) {
+        errors.push({
+          source,
+          message:
+            `bare reference \`${bare}\` — a formula/validation expression binds the record as the ` +
+            `\`record\` namespace, not at top level, so \`${bare}\` resolves to nothing and the ` +
+            `expression silently evaluates to null. Write \`record.${bare}\`.`,
+        });
+      }
+    } else if (schema?.fields && schema.fields.length > 0) {
+      // Flattened flow/automation condition: the record's fields ARE bound at
+      // top-level, so a bare ref is normally correct. But a *non-field* bare
+      // identifier is either a flow variable or a typo. When it is a near-miss
+      // of a known field, warn (did-you-mean) WITHOUT failing the build —
+      // a genuine flow variable won't be edit-distance-close to a field. (#1928)
+      const unknown = firstUndeclaredReference(source, schema.fields);
+      if (unknown) {
+        const suggestion = nearest(unknown, schema.fields);
+        if (suggestion) {
+          warnings.push({
+            source,
+            message:
+              `\`${unknown}\` is not a field of \`${schema.objectName ?? 'the trigger object'}\` — ` +
+              `did you mean \`${suggestion}\`? (flow conditions reference fields bare, e.g. \`${suggestion} == …\`). ` +
+              `If \`${unknown}\` is a flow variable this is safe to ignore.`,
+          });
+        }
+      }
+    }
   }
-  return { ok: errors.length === 0, errors };
+  return { ok: errors.length === 0, errors, warnings };
 }
 
 function bracesHintForTemplate(source: string): string {
@@ -198,10 +256,21 @@ export function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
   };
 }
 
-/** Public catalog of CEL stdlib functions available in expressions. */
+/**
+ * Public catalog of CEL functions available in expressions — what `introspectScope`
+ * advertises to authors (incl. AI). Every entry MUST actually resolve at runtime:
+ * either registered in `registerStdLib` or a verified cel-js built-in. Drifting this
+ * list ahead of the runtime tells the author to call functions that fault (#1928).
+ */
 export const CEL_STDLIB_FUNCTIONS: string[] = [
-  'now', 'today', 'daysFromNow', 'daysBetween', 'date', 'datetime', 'timestamp',
-  'isBlank', 'isEmpty', 'coalesce', 'len', 'size', 'int', 'float', 'string', 'bool',
-  'upper', 'lower', 'trim', 'contains', 'startsWith', 'endsWith', 'matches',
-  'has', 'min', 'max', 'abs', 'round',
+  // Dates (registered stdlib)
+  'now', 'today', 'daysFromNow', 'daysAgo', 'daysBetween', 'date', 'datetime',
+  // Numbers (registered stdlib)
+  'abs', 'round', 'min', 'max',
+  // Strings (registered stdlib)
+  'upper', 'lower', 'trim', 'contains', 'startsWith', 'endsWith', 'matches', 'joinNonEmpty',
+  // Collections / null-ish (registered stdlib)
+  'isBlank', 'isEmpty', 'coalesce', 'len',
+  // cel-js built-ins (verified to resolve)
+  'size', 'has', 'int', 'string', 'bool', 'double', 'timestamp', 'duration',
 ];