@objectstack/formula 9.5.1 → 9.7.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/formula@9.5.1 build /home/runner/work/framework/framework/packages/formula
+> @objectstack/formula@9.7.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
-CJS dist/index.js     25.06 KB
-CJS dist/index.js.map 62.33 KB
-CJS ⚡️ Build success in 111ms
-ESM dist/index.mjs     23.34 KB
-ESM dist/index.mjs.map 60.97 KB
-ESM ⚡️ Build success in 115ms
+CJS dist/index.js     27.85 KB
+CJS dist/index.js.map 73.20 KB
+CJS ⚡️ Build success in 103ms
+ESM dist/index.mjs     26.12 KB
+ESM dist/index.mjs.map 71.83 KB
+ESM ⚡️ Build success in 104ms
 DTS Build start
-DTS ⚡️ Build success in 4438ms
-DTS dist/index.d.mts 14.02 KB
-DTS dist/index.d.ts  14.02 KB
+DTS ⚡️ Build success in 5303ms
+DTS dist/index.d.mts 15.44 KB
+DTS dist/index.d.ts  15.44 KB

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @objectstack/formula
 
+## 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
+
+- bb00a50: fix(formula): catch unknown functions in CEL conditions at build (#1877)
+
+  `compile()` discarded cel-js's type-check verdict because `check()` returns a `TypeCheckResult` object (`{ valid, error }`), not an array — so the `Array.isArray(checkErrors)` guard never matched. A condition calling an unknown function (`PRIOR(status)`, a typo'd `isBlnk(...)`) type-checks as `found no matching overload`, but that result never surfaced, so `objectstack compile`, `registerFlow`, and the `validate_expression` tool all accepted the predicate, which then silently no-op'd the flow at runtime. Now reads the documented `{ valid, error }` shape, closing the gap for flow conditions, validation rules, and field formulas at once.
+
+- Updated dependencies [d1e930a]
+- Updated dependencies [71578f2]
+- Updated dependencies [5e3a301]
+- Updated dependencies [5db2742]
+  - @objectstack/spec@9.6.0
+
 ## 9.5.1
 
 ### 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';

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';

package/dist/index.js

@@ -98,6 +98,21 @@ function registerStdLib(env, now) {
     }
   );
 }
+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 +141,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") {
@@ -185,11 +259,11 @@ var celEngine = {
     try {
       const env = buildEnv(() => /* @__PURE__ */ new Date(0));
       const compiled = env.parse(source);
-      const checkErrors = compiled.check?.();
-      if (checkErrors && Array.isArray(checkErrors) && checkErrors.length > 0) {
+      const checkResult = compiled.check?.();
+      if (checkResult && checkResult.valid === false) {
         return {
           ok: false,
-          error: { kind: "type", message: checkErrors.join("; ") }
+          error: { kind: "type", message: checkResult.error?.message ?? "expression failed type checking" }
         };
       }
       return { ok: true, value: compiled.ast };
@@ -715,11 +789,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 +802,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 +817,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);