feat(cli): lint date-equality vs time values in flow query filters (#1874)

Extends the flow anti-pattern lint from trigger CONDITIONS to query FILTERS.
A scheduled flow whose get_record filter binds a field directly / via $eq / $in
to a time-function value (daysFromNow/today/now/...) silently matches nothing,
because a Field.date stores a time component and an exact match against a
re-computed timestamp never holds — the bug the templates discrete-tier alerts
hit. Range ops ($gte/$lt day windows) are the correct shape and are exempt.

New rule flow-date-equality-filter; advisory warning, never fails the build.
10 tests incl. false-positive guards (windows, $or, plain ranges, non-time eq).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

.changeset/lint-date-equality-filter.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/cli": minor
+---
+
+feat(cli): lint date-EQUALITY against time values in flow query filters (#1874)
+
+The flow anti-pattern lint already flagged a record-change trigger CONDITION
+using date equality (`end_date == daysFromNow(60)`). It now also scans
+get_record/query node FILTERS for the same footgun: a field bound directly, or
+via `$eq` / `$in`, to a time-function value (`daysFromNow`/`today`/`now`/…).
+A `Field.date` is stored with a time component, so an exact match against a
+re-computed timestamp silently returns nothing — the failure the templates
+discrete-tier alerts hit. Range operators (`$gte`/`$lt` day windows) are the
+correct shape and are never flagged. Advisory warning; never fails the build.

packages/cli/src/utils/lint-flow-patterns.test.ts

@@ -4,10 +4,24 @@ import { describe, it, expect } from 'vitest';
 import {
   lintFlowPatterns,
   FLOW_TIME_RELATIVE_ANTIPATTERN,
+  FLOW_DATE_EQUALITY_FILTER,
   FLOW_DOUBLE_BRACE_INTERP,
   FLOW_BARE_DOLLAR_REF,
 } from './lint-flow-patterns.js';
 
+const CEL = (source: string) => ({ dialect: 'cel', source });
+/** A scheduled flow with a get_record node carrying `filter`. */
+const filterFlow = (filter: unknown) => ({
+  flows: [{
+    name: 'expiry_alert',
+    nodes: [
+      { id: 'start', type: 'start', config: { triggerType: 'schedule', schedule: 'cron:0 9 * * *' } },
+      { id: 'query', type: 'get_record', config: { objectName: 'contract', filter } },
+    ],
+    edges: [],
+  }],
+});
+
 const flow = (condition: unknown, triggerType = 'record-after-update') => ({
   flows: [{
     name: 'renewal_alert',
@@ -50,6 +64,52 @@ describe('lintFlowPatterns — time-relative anti-pattern (#1874)', () => {
   });
 });
 
+describe('lintFlowPatterns — date-equality in query filter (#1874)', () => {
+  it('flags a field bound directly to a time value (implicit equality)', () => {
+    const fnds = lintFlowPatterns(filterFlow({ expires_at: CEL('daysFromNow(30)') }));
+    expect(fnds).toHaveLength(1);
+    expect(fnds[0].rule).toBe(FLOW_DATE_EQUALITY_FILTER);
+    expect(fnds[0].hint).toMatch(/\$gte.*daysFromNow\(N\).*\$lt/);
+  });
+
+  it('flags `$in` against time values (the original renewal_alert bug)', () => {
+    const fnds = lintFlowPatterns(filterFlow({
+      status: 'active',
+      end_date: { $in: [CEL('daysFromNow(60)'), CEL('daysFromNow(30)'), CEL('daysFromNow(7)')] },
+    }));
+    expect(fnds).toHaveLength(1);
+    expect(fnds[0].rule).toBe(FLOW_DATE_EQUALITY_FILTER);
+  });
+
+  it('flags `$eq` against a time value', () => {
+    expect(lintFlowPatterns(filterFlow({ d: { $eq: CEL('today()') } }))).toHaveLength(1);
+  });
+
+  describe('does NOT flag (false-positive guards)', () => {
+    it('a one-day window (the correct fix)', () => {
+      expect(lintFlowPatterns(filterFlow({
+        end_date: { $gte: CEL('daysFromNow(7)'), $lt: CEL('daysFromNow(8)') },
+      }))).toHaveLength(0);
+    });
+    it('multi-tier windows wrapped in $or', () => {
+      expect(lintFlowPatterns(filterFlow({
+        status: 'active',
+        $or: [
+          { end_date: { $gte: CEL('daysFromNow(7)'), $lt: CEL('daysFromNow(8)') } },
+          { end_date: { $gte: CEL('daysFromNow(30)'), $lt: CEL('daysFromNow(31)') } },
+        ],
+      }))).toHaveLength(0);
+    });
+    it('a plain range like `due_date < today()` (overdue query)', () => {
+      expect(lintFlowPatterns(filterFlow({ status: 'open', due_date: { $lt: CEL('today()') } }))).toHaveLength(0);
+    });
+    it('equality against a non-time value (status, interpolated id)', () => {
+      expect(lintFlowPatterns(filterFlow({ status: 'active', id: '{record.id}' }))).toHaveLength(0);
+      expect(lintFlowPatterns(filterFlow({ amount: { $eq: CEL('record.threshold') } }))).toHaveLength(0);
+    });
+  });
+});
+
 /** A flow with a create_record node carrying `config`. */
 const nodeFlow = (config: Record<string, unknown>) => ({
   flows: [{

packages/cli/src/utils/lint-flow-patterns.ts

@@ -38,16 +38,82 @@ function conditionSource(raw: unknown): string {
 }
 
 const TIME_FNS = 'daysFromNow|daysAgo|today|now|date|datetime';
+const TIME_FN_RE = new RegExp(`\\b(?:${TIME_FNS})\\s*\\(`);
 // A time function adjacent to an equality operator, either side:
 //   `end_date == daysFromNow(60)`  /  `today() != record.start`
 const DATE_EQ = new RegExp(
   `(?:(?:${TIME_FNS})\\s*\\([^)]*\\)\\s*(?:==|!=))|(?:(?:==|!=)\\s*(?:${TIME_FNS})\\s*\\()`,
 );
 
 export const FLOW_TIME_RELATIVE_ANTIPATTERN = 'flow-time-relative-antipattern';
+export const FLOW_DATE_EQUALITY_FILTER = 'flow-date-equality-filter';
 export const FLOW_DOUBLE_BRACE_INTERP = 'flow-double-brace-interpolation';
 export const FLOW_BARE_DOLLAR_REF = 'flow-bare-dollar-reference';
 
+/** If `v` is a CEL expression whose source calls a time function, return that source. */
+function celTimeSource(v: unknown): string | null {
+  if (v && typeof v === 'object' && (v as AnyRec).dialect === 'cel') {
+    const src = (v as AnyRec).source;
+    if (typeof src === 'string' && TIME_FN_RE.test(src)) return src;
+  }
+  return null;
+}
+
+/** Range operators — the building block of the CORRECT time-window pattern, never flagged. */
+const RANGE_OPS = new Set(['$gte', '$gt', '$lte', '$lt', '$ne']);
+
+/**
+ * Walk a get_record/query `filter` for the date-EQUALITY footgun: a field bound
+ * directly (`field: daysFromNow(N)`) or via `$eq` / `$in` to a time-function value.
+ * A `Field.date` is stored with a time component, so two independently-computed
+ * timestamps never compare equal — the query silently returns nothing (#1928 /
+ * templates #1874). Range operators (`$gte`/`$lt` day windows) are the correct
+ * shape and are never flagged.
+ */
+function scanFilterForDateEquality(
+  filter: unknown,
+  where: string,
+  findings: FlowLintFinding[],
+): void {
+  if (!filter || typeof filter !== 'object' || Array.isArray(filter)) return;
+  for (const [key, val] of Object.entries(filter as AnyRec)) {
+    if (key === '$or' || key === '$and') {
+      if (Array.isArray(val)) for (const sub of val) scanFilterForDateEquality(sub, where, findings);
+      continue;
+    }
+    // `key` is a field name; `val` is its constraint.
+    const direct = celTimeSource(val); // `field: daysFromNow(N)` → implicit equality
+    let hit: { op: string; src: string } | null = direct ? { op: '==', src: direct } : null;
+    if (!hit && val && typeof val === 'object' && (val as AnyRec).dialect !== 'cel') {
+      for (const [op, operand] of Object.entries(val as AnyRec)) {
+        if (RANGE_OPS.has(op)) continue; // correct pattern — leave it
+        if (op === '$eq') {
+          const s = celTimeSource(operand);
+          if (s) { hit = { op: '$eq', src: s }; break; }
+        } else if (op === '$in' && Array.isArray(operand)) {
+          for (const item of operand) {
+            const s = celTimeSource(item);
+            if (s) { hit = { op: '$in', src: s }; break; }
+          }
+          if (hit) break;
+        }
+      }
+    }
+    if (hit) {
+      findings.push({
+        where,
+        message:
+          `filter matches \`${key}\` by ${hit.op} against a time value (\`${hit.src}\`) — a date field carries a ` +
+          `time component, so exact equality against \`${hit.src}\` (re-computed each run) silently matches nothing.`,
+        hint:
+          `Use a one-day window instead: \`${key}: { $gte: daysFromNow(N), $lt: daysFromNow(N+1) }\` ` +
+          `(wrap multiple tiers in \`$or\`). The abutting windows tile the timeline so each row matches exactly once. (#1874)`,
+        rule: FLOW_DATE_EQUALITY_FILTER,
+      });
+    }
+  }
+}
+
 // Flow node VALUES interpolate with SINGLE braces (`{var}` / `{rec.field}` /
 // `{$User.Id}`). Two wrong-syntax mistakes AI/human authors carry over from the
 // *formula* template dialect (`{{ path }}`) or other platforms:
@@ -106,9 +172,16 @@ export function lintFlowPatterns(stack: AnyRec): FlowLintFinding[] {
     //     node values use SINGLE braces; double-brace `{{ }}` and bare `$ref.x`
     //     are carried over from the formula template dialect / other platforms.
     for (const node of nodes) {
+      const nodeWhere = `flow '${flowName}' · node '${node.id}' (${node.type})`;
+
+      // (a2) #1874 — date-EQUALITY (`==`/`$eq`/`$in`) against a time value in a
+      //      query filter. A scheduled flow that filters this way silently matches
+      //      nothing; the robust shape is a `$gte`/`$lt` day window.
+      const cfg = (node.config ?? {}) as AnyRec;
+      if (cfg.filter) scanFilterForDateEquality(cfg.filter, `${nodeWhere} filter`, findings);
+
       const strings: string[] = [];
       collectTemplateStrings(node.config, undefined, strings);
-      const nodeWhere = `flow '${flowName}' · node '${node.id}' (${node.type})`;
       for (const str of strings) {
         if (DOUBLE_BRACE.test(str)) {
           findings.push({