@objectstack/formula 9.6.0 → 9.7.0

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 {