@objectstack/formula 9.6.0 → 9.8.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/formula@9.6.0 build /home/runner/work/framework/framework/packages/formula
+> @objectstack/formula@9.8.0 build /home/runner/work/framework/framework/packages/formula
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     23.36 KB
-ESM dist/index.mjs.map 61.55 KB
-ESM ⚡️ Build success in 78ms
-CJS dist/index.js     25.07 KB
-CJS dist/index.js.map 62.92 KB
-CJS ⚡️ Build success in 76ms
+CJS dist/index.js     29.77 KB
+CJS dist/index.js.map 78.89 KB
+CJS ⚡️ Build success in 123ms
+ESM dist/index.mjs     28.04 KB
+ESM dist/index.mjs.map 77.53 KB
+ESM ⚡️ Build success in 124ms
 DTS Build start
-DTS ⚡️ Build success in 4187ms
-DTS dist/index.d.mts 14.02 KB
-DTS dist/index.d.ts  14.02 KB
+DTS ⚡️ Build success in 4371ms
+DTS dist/index.d.mts 15.71 KB
+DTS dist/index.d.ts  15.71 KB

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @objectstack/formula
 
+## 9.8.0
+
+### Minor Changes
+
+- c17d2c8: feat(formula): register the CEL functions the authoring catalog advertises (daysBetween, abs, round, min, max, upper, lower, contains, startsWith, endsWith, matches, len, isEmpty, date, datetime)
+
+  `introspectScope` / `CEL_STDLIB_FUNCTIONS` advertised 25 functions to authors
+  (incl. AI), but only 8 were registered — 14 faulted at runtime (`daysBetween`,
+  `abs`, `round`, `min`, `max`, `upper`, `lower`, `len`, `isEmpty`, `contains`,
+  `startsWith`, `endsWith`, `matches`, plus `date`/`datetime`). Authors were told
+  to call functions that don't exist (e.g. `daysBetween` for "days remaining").
+
+  Register the genuinely-useful set in `registerStdLib` with dyn-lenient signatures
+  (so a `Field.date` arriving as a string still works) and internal coercion, and
+  reconcile the catalog so every advertised entry resolves — guarded by a test that
+  evaluates every `CEL_STDLIB_FUNCTIONS` entry. Pure additions; no behavior change
+  to existing expressions.
+
+### Patch Changes
+
+- Updated dependencies [97c55b3]
+- Updated dependencies [1b1f490]
+  - @objectstack/spec@9.8.0
+
+## 9.7.0
+
+### Minor Changes
+
+- ff0a87a: feat(validate): flag bare field references in record-scoped CEL sites at build time
+
+  > **Heads-up for downstream:** this adds a NEW build-time error. A `Field.formula`
+  > or validation predicate that references a field bare (`amount` instead of
+  > `record.amount`) now fails `objectstack compile`. These expressions were already
+  > silently broken at runtime (they evaluated to `null` / never fired), so this is a
+  > fix that surfaces a latent bug — but a stack carrying one will go from
+  > "builds, silently wrong" to "fails the build" on upgrade. The error message
+  > states the exact correction (`write record.<field>`).
+
+  A `Field.formula` and an object validation predicate evaluate against the
+  `record` namespace only — there is no field flattening — so a bare top-level
+  identifier (`amount`, `status`) resolves to nothing and the expression silently
+  evaluates to `null` / never fires. This is the silent-at-runtime class behind
+  the broken example-crm formulas (#1927) and is exactly what AI authors get wrong.
+
+  `validateExpression` now takes an evaluation `scope` and, for `scope: 'record'`,
+  reports a bare reference with the corrective form (`write record.<field>`). The
+  check is schema-free and acts only on cel-js's `Unknown variable` fault, so it
+  cannot false-positive on arithmetic/comparison/null-guard type overloads. Flow
+  and automation conditions keep the default `scope: 'flattened'` — the record's
+  fields ARE spread to top-level there (alongside flow variables), so bare refs
+  are correct and are NOT flagged. `objectstack compile` wires `record` scope for
+  field formulas and validation predicates; flow conditions stay flattened.
+
+### Patch Changes
+
+- 82c7438: fix(formula): register mixed `double <op> int` arithmetic overloads so number-field formulas compute
+
+  cel-js types a record field number as `double` and a bare integer literal as
+  `int`, and ships overloads only for matching numeric pairs. So an everyday
+  formula like `record.amount / 100` or `record.price * 2` faulted at runtime
+  (`no such overload: dyn<double> / int`); the engine caught the fault and the
+  formula silently evaluated to `null` — passing build, empty at runtime (#1928).
+
+  The CEL engine now registers the missing `double <op> int` / `int <op> double`
+  overloads for `+ - * / %`, computing the result as a `double` (CEL's mixed-numeric
+  promotion). Pure `int op int` is untouched, so integer division (`7 / 2 == 3`)
+  keeps its semantics — the overloads fire only when the operands are genuinely a
+  `double` and an `int`. Authors no longer need the `/ 100.0` float-literal workaround.
+
+- 417b6ac: feat(validate): advisory did-you-mean warnings for likely field typos in flow conditions
+
+  Adds a non-blocking warning channel to build-time expression validation (#1928
+  tier 3). Flow / automation conditions flatten the record's fields to top-level,
+  so a bare `status` is correct — but a bare NON-field identifier is either a flow
+  variable or a typo. When it is a near-miss of a known field (edit distance), the
+  build now emits a `did you mean \`status\`?`warning instead of staying silent,
+WITHOUT failing the build (a genuine flow variable won't be close to a field
+name, so it stays quiet).`ExprValidationResult`gains a`warnings`array and`ExprIssue`a`severity`; `objectstack compile` prints warnings and only fails on
+  errors. This closes the silent-skip gap for misspelled trigger-condition fields
+  (the #1877 family) without the false-positive risk of a hard gate.
+
+  - @objectstack/spec@9.7.0
+
 ## 9.6.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -310,6 +310,23 @@ 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';
 }
 interface ExprValidationError {
     /** Self-correcting message: what is wrong + the correct form. */
@@ -320,6 +337,13 @@ interface ExprValidationError {
 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[];
 }
 /** The dialect a field role expects (Decision 2). */
 declare function expectedDialect(role: FieldRole): 'cel' | 'template';
@@ -340,7 +364,12 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
     roots: string[];
     functions: string[];
 };
-/** 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).
+ */
 declare const CEL_STDLIB_FUNCTIONS: string[];
 
 export { CEL_STDLIB_FUNCTIONS, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, cronEngine, expectedDialect, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.d.ts

@@ -310,6 +310,23 @@ 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';
 }
 interface ExprValidationError {
     /** Self-correcting message: what is wrong + the correct form. */
@@ -320,6 +337,13 @@ interface ExprValidationError {
 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[];
 }
 /** The dialect a field role expects (Decision 2). */
 declare function expectedDialect(role: FieldRole): 'cel' | 'template';
@@ -340,7 +364,12 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
     roots: string[];
     functions: string[];
 };
-/** 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).
+ */
 declare const CEL_STDLIB_FUNCTIONS: string[];
 
 export { CEL_STDLIB_FUNCTIONS, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, cronEngine, expectedDialect, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.js

@@ -51,6 +51,12 @@ function startOfDayUtc(d) {
   out.setUTCHours(0, 0, 0, 0);
   return out;
 }
+function toDate(v) {
+  if (v instanceof Date) return v;
+  if (typeof v === "number" || typeof v === "bigint") return new Date(Number(v));
+  return new Date(String(v));
+}
+var MS_PER_DAY = 864e5;
 function addDaysUtc(d, n) {
   const out = new Date(d.getTime());
   out.setUTCDate(out.getUTCDate() + n);
@@ -96,8 +102,35 @@ function registerStdLib(env, now) {
       }
       return parts.join(separator);
     }
+  ).registerFunction(
+    "daysBetween(dyn, dyn): int",
+    (a, b) => BigInt(Math.round((toDate(b).getTime() - toDate(a).getTime()) / MS_PER_DAY))
+  ).registerFunction("date(dyn): google.protobuf.Timestamp", (s) => toDate(s)).registerFunction("datetime(dyn): google.protobuf.Timestamp", (s) => toDate(s)).registerFunction("abs(dyn): double", (x) => Math.abs(Number(x))).registerFunction("round(dyn): int", (x) => BigInt(Math.round(Number(x)))).registerFunction("min(dyn, dyn): dyn", (a, b) => Number(a) <= Number(b) ? a : b).registerFunction("max(dyn, dyn): dyn", (a, b) => Number(a) >= Number(b) ? a : b).registerFunction("upper(dyn): string", (s) => String(s ?? "").toUpperCase()).registerFunction("lower(dyn): string", (s) => String(s ?? "").toLowerCase()).registerFunction("contains(dyn, dyn): bool", (s, sub) => String(s ?? "").includes(String(sub ?? ""))).registerFunction("startsWith(dyn, dyn): bool", (s, p) => String(s ?? "").startsWith(String(p ?? ""))).registerFunction("endsWith(dyn, dyn): bool", (s, p) => String(s ?? "").endsWith(String(p ?? ""))).registerFunction("matches(dyn, dyn): bool", (s, re) => new RegExp(String(re ?? "")).test(String(s ?? ""))).registerFunction("len(dyn): int", (v) => BigInt(lengthOf(v))).registerFunction(
+    "isEmpty(dyn): bool",
+    (v) => v === null || v === void 0 || lengthOf(v) === 0
   );
 }
+function lengthOf(v) {
+  if (v === null || v === void 0) return 0;
+  if (typeof v === "string" || Array.isArray(v)) return v.length;
+  if (typeof v === "object") return Object.keys(v).length;
+  return 0;
+}
+function registerNumericCoercions(env) {
+  const ops = {
+    "+": (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, b) => fn(Number(a), Number(b));
+    env.registerOperator(`double ${op} int`, impl);
+    env.registerOperator(`int ${op} double`, impl);
+  }
+  return env;
+}
 function buildScope(ctx) {
   const scope = {};
   if (ctx.record !== void 0) scope.record = ctx.record;
@@ -126,7 +159,66 @@ function buildEnv(now) {
     enableOptionalTypes: true,
     limits: DEFAULT_LIMITS
   });
-  return registerStdLib(env, now);
+  return registerNumericCoercions(registerStdLib(env, now));
+}
+var SCOPE_ROOTS = [
+  "record",
+  "previous",
+  "input",
+  "output",
+  "os",
+  "vars",
+  "variables",
+  "automation",
+  "context",
+  "args",
+  "item",
+  "env",
+  "user",
+  "step",
+  "result",
+  "trigger",
+  "event",
+  "payload",
+  "data",
+  "params",
+  "config",
+  "settings"
+];
+function buildScopedEnv(knownFields) {
+  const env = new import_cel_js.Environment({
+    unlistedVariablesAreDyn: false,
+    enableOptionalTypes: true,
+    limits: DEFAULT_LIMITS
+  });
+  registerStdLib(env, () => /* @__PURE__ */ new Date(0));
+  for (const root of SCOPE_ROOTS) {
+    try {
+      env.registerVariable(root, "map");
+    } catch {
+    }
+  }
+  for (const field of knownFields) {
+    try {
+      env.registerVariable(field, "dyn");
+    } catch {
+    }
+  }
+  return env;
+}
+var recordScopeEnv;
+function firstUndeclaredReference(source, knownFields = []) {
+  if (typeof source !== "string" || !source.trim()) return null;
+  try {
+    const env = knownFields.length === 0 ? recordScopeEnv ?? (recordScopeEnv = buildScopedEnv([])) : buildScopedEnv(knownFields);
+    const result = env.parse(source).check?.();
+    if (result && result.valid === false) {
+      const m = /Unknown variable:\s*([A-Za-z_$][\w$]*)/.exec(result.error?.message ?? "");
+      if (m) return m[1];
+    }
+  } catch {
+  }
+  return null;
 }
 function coerce(value) {
   if (typeof value === "bigint") {
@@ -715,11 +807,12 @@ function levenshtein(a, b) {
 function validateExpression(role, input, schema) {
   const { dialect, source } = toSource(input);
   const errors = [];
-  if (!source.trim()) return { ok: true, errors };
+  const warnings = [];
+  if (!source.trim()) return { ok: true, errors, warnings };
   if (role === "template") {
     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 compiled2 = templateEngine.compile(source);
     if (!compiled2.ok) {
@@ -727,11 +820,11 @@ function validateExpression(role, input, schema) {
     }
     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 };
   }
   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) {
@@ -742,8 +835,28 @@ function validateExpression(role, input, schema) {
     });
   } else {
     checkFieldExistence(source, schema, errors);
+    if (schema?.scope === "record") {
+      const bare = firstUndeclaredReference(source);
+      if (bare) {
+        errors.push({
+          source,
+          message: `bare reference \`${bare}\` \u2014 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) {
+      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"}\` \u2014 did you mean \`${suggestion}\`? (flow conditions reference fields bare, e.g. \`${suggestion} == \u2026\`). 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) {
   const m = SINGLE_BRACE_RE.exec(source);
@@ -759,22 +872,20 @@ function introspectScope(role, schema) {
   };
 }
 var CEL_STDLIB_FUNCTIONS = [
+  // Dates (registered stdlib)
   "now",
   "today",
   "daysFromNow",
+  "daysAgo",
   "daysBetween",
   "date",
   "datetime",
-  "timestamp",
-  "isBlank",
-  "isEmpty",
-  "coalesce",
-  "len",
-  "size",
-  "int",
-  "float",
-  "string",
-  "bool",
+  // Numbers (registered stdlib)
+  "abs",
+  "round",
+  "min",
+  "max",
+  // Strings (registered stdlib)
   "upper",
   "lower",
   "trim",
@@ -782,11 +893,21 @@ var CEL_STDLIB_FUNCTIONS = [
   "startsWith",
   "endsWith",
   "matches",
+  "joinNonEmpty",
+  // Collections / null-ish (registered stdlib)
+  "isBlank",
+  "isEmpty",
+  "coalesce",
+  "len",
+  // cel-js built-ins (verified to resolve)
+  "size",
   "has",
-  "min",
-  "max",
-  "abs",
-  "round"
+  "int",
+  "string",
+  "bool",
+  "double",
+  "timestamp",
+  "duration"
 ];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {