feat(cli): add phantom-aggregation flow lint (#1870)

A node-config key naming a capability the automation engine lacks
(aggregations/aggregate/groupBy/rollup/having) is silently ignored at runtime —
the node runs and computes nothing (templates publication_rollup). Flag it and
point the author to the data-layer equivalent: Field.summary for a cross-object
rollup, Field.formula for a per-record computed value.

New rule flow-phantom-aggregation; advisory warning. 3 tests.

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

Author: os-zhuang

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

@@ -2,13 +2,16 @@
 "@objectstack/cli": minor
 ---
 
-feat(cli): lint date-EQUALITY against time values in flow query filters (#1874)
+feat(cli): two new flow authoring anti-pattern lints — date-equality filters (#1874) and phantom aggregation (#1870)
 
-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.
+Extends the build-time flow anti-pattern lint (advisory warnings, never fail the build):
+
+- **flow-date-equality-filter (#1874)**: a get_record/query filter that binds a
+  field directly, or via `$eq`/`$in`, to a time-function value
+  (`daysFromNow`/`today`/`now`/…). A `Field.date` stores a time component, so an
+  exact match against a re-computed timestamp silently returns nothing. Range
+  operators (`$gte`/`$lt` day windows) are the correct shape and are exempt.
+- **flow-phantom-aggregation (#1870)**: a node config key naming a capability the
+  automation engine does not have (`aggregations`/`aggregate`/`groupBy`/`rollup`/
+  `having`). There is no aggregate node, so the key is silently ignored and the
+  node computes nothing. Points the author to `Field.summary` / `Field.formula`.

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

@@ -5,6 +5,7 @@ import {
   lintFlowPatterns,
   FLOW_TIME_RELATIVE_ANTIPATTERN,
   FLOW_DATE_EQUALITY_FILTER,
+  FLOW_PHANTOM_AGGREGATION,
   FLOW_DOUBLE_BRACE_INTERP,
   FLOW_BARE_DOLLAR_REF,
 } from './lint-flow-patterns.js';
@@ -110,6 +111,36 @@ describe('lintFlowPatterns — date-equality in query filter (#1874)', () => {
   });
 });
 
+describe('lintFlowPatterns — phantom aggregation capability (#1870)', () => {
+  const scriptNode = (config: Record<string, unknown>) => ({
+    flows: [{
+      name: 'rollup',
+      nodes: [
+        { id: 'start', type: 'start', config: {} },
+        { id: 'sum', type: 'script', config },
+      ],
+      edges: [],
+    }],
+  });
+
+  it('flags `aggregations` on a script node (publication_rollup bug)', () => {
+    const fnds = lintFlowPatterns(scriptNode({ aggregations: { total: { sum: 'amount' } } }));
+    expect(fnds).toHaveLength(1);
+    expect(fnds[0].rule).toBe(FLOW_PHANTOM_AGGREGATION);
+    expect(fnds[0].hint).toMatch(/Field\.summary/);
+  });
+
+  it('flags groupBy / rollup / aggregate / having too', () => {
+    for (const key of ['groupBy', 'rollup', 'aggregate', 'having']) {
+      expect(lintFlowPatterns(scriptNode({ [key]: {} })).map((f) => f.rule)).toContain(FLOW_PHANTOM_AGGREGATION);
+    }
+  });
+
+  it('does NOT flag an ordinary script/function node', () => {
+    expect(lintFlowPatterns(scriptNode({ function: 'helpdesk.triage', inputs: { x: 1 } }))).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

@@ -47,9 +47,18 @@ const DATE_EQ = new RegExp(
 
 export const FLOW_TIME_RELATIVE_ANTIPATTERN = 'flow-time-relative-antipattern';
 export const FLOW_DATE_EQUALITY_FILTER = 'flow-date-equality-filter';
+export const FLOW_PHANTOM_AGGREGATION = 'flow-phantom-aggregation';
 export const FLOW_DOUBLE_BRACE_INTERP = 'flow-double-brace-interpolation';
 export const FLOW_BARE_DOLLAR_REF = 'flow-bare-dollar-reference';
 
+/**
+ * Node-config keys that name a capability the automation engine does NOT have.
+ * There is no aggregate node, so a `script`/`loop`/… node carrying these keys is
+ * silently ignored — the node runs and computes nothing (templates #1870,
+ * `publication_rollup`). Aggregation belongs in the data layer, not a flow.
+ */
+const PHANTOM_AGG_KEYS = new Set(['aggregations', 'aggregate', 'groupBy', 'rollup', 'having']);
+
 /** 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') {
@@ -180,6 +189,24 @@ export function lintFlowPatterns(stack: AnyRec): FlowLintFinding[] {
       const cfg = (node.config ?? {}) as AnyRec;
       if (cfg.filter) scanFilterForDateEquality(cfg.filter, `${nodeWhere} filter`, findings);
 
+      // (a3) #1870 — a node-config key naming a non-existent capability (there is
+      //      no aggregate node) is silently ignored at runtime, so the node
+      //      computes nothing. Point the author at the data-layer equivalent.
+      for (const key of Object.keys(cfg)) {
+        if (PHANTOM_AGG_KEYS.has(key)) {
+          findings.push({
+            where: nodeWhere,
+            message:
+              `node config has \`${key}\` — the automation engine has no aggregate node, so \`${key}\` is ` +
+              `silently ignored and this node computes nothing at runtime.`,
+            hint:
+              `Aggregation belongs in the data layer: use \`Field.summary\` for a cross-object rollup ` +
+              `(sum/count of children), or \`Field.formula\` for a per-record computed value. (#1870)`,
+            rule: FLOW_PHANTOM_AGGREGATION,
+          });
+        }
+      }
+
       const strings: string[] = [];
       collectTemplateStrings(node.config, undefined, strings);
       for (const str of strings) {