feat(lint): warn on legacy pre-ADR-0021 dashboard analytics keys (#1878/#1894)

An author — very often an AI — can still write the removed inline-analytics
shape (categoryField/valueField/xAxisField/yAxisFields/aggregate/aggregation/
rowField/columnField) on a dashboard widget. Post-ADR-0021 the renderer routes
dataset-bound widgets through DatasetWidget and never reads these keys, so
authoring one is a silent no-op — exactly the "AI writes a dead property"
failure the liveness audit targets, but on the authoring side.

Add a `widget-legacy-analytics-shape` advisory rule to validateWidgetBindings
(already wired into `objectstack compile`): when a widget carries any legacy
key, emit a warning steering the author to `dataset` + `dimensions` + `values`,
with the fix spelled out. Fires whether or not a dataset is also present (the
keys are dead either way) and closes the gap where a dataset-less legacy
widget was skipped silently. Warning-only, per-widget suppressible via
`suppressWarnings`; never fails the build.

Tests: 4 new cases (dataset-bound legacy key, dataset-less legacy pivot,
clean dataset widget, suppression); full validate-widget-bindings suite green
(37 passed).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LddW4NaQBdf5FTEnBPpnUJ

Author: claude

packages/lint/src/validate-widget-bindings.test.ts

@@ -8,6 +8,7 @@ import {
   CHART_FIELD_UNKNOWN,
   CHART_CONFIG_MISSING,
   MEASURE_AGGREGATE_INCOHERENT,
+  WIDGET_LEGACY_ANALYTICS_SHAPE,
 } from './validate-widget-bindings.js';
 
 /** The downstream repro from issue #1719 — dataset with a count AND a sum
@@ -380,3 +381,54 @@ describe('validateWidgetBindings (measure-aggregate-incoherent — rate aggregat
     expect(validateWidgetBindings(stack)).toHaveLength(0);
   });
 });
+
+describe('validateWidgetBindings — legacy analytics shape (#1878/#1894)', () => {
+  const only = (findings: ReturnType<typeof validateWidgetBindings>) =>
+    findings.filter((f) => f.rule === WIDGET_LEGACY_ANALYTICS_SHAPE);
+
+  it('warns (not errors) when a dataset-bound widget also carries a legacy key', () => {
+    // valueField is dead once the widget is dataset-bound; steer the author off it.
+    const findings = only(validateWidgetBindings(reproStack({ valueField: 'total_amount' })));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].severity).toBe('warning');
+    expect(findings[0].message).toContain('`valueField`');
+    expect(findings[0].hint).toMatch(/dataset.*dimensions.*values/is);
+  });
+
+  it('warns on a legacy pivot widget that has NO dataset (previously skipped silently)', () => {
+    const stack = {
+      dashboards: [{
+        name: 'legacy_dash',
+        label: 'Legacy',
+        widgets: [{
+          id: 'legacy_pivot',
+          type: 'pivot',
+          object: 'task',
+          rowField: 'status',
+          columnField: 'priority',
+          valueField: 'id',
+          aggregation: 'count',
+          layout: { x: 0, y: 0, w: 6, h: 4 },
+        }],
+      }],
+    };
+    const findings = only(validateWidgetBindings(stack));
+    expect(findings).toHaveLength(1);
+    // all legacy keys reported in one finding
+    expect(findings[0].message).toContain('`rowField`');
+    expect(findings[0].message).toContain('`columnField`');
+    expect(findings[0].message).toContain('`aggregation`');
+  });
+
+  it('does NOT warn on a clean dataset-shaped widget', () => {
+    expect(only(validateWidgetBindings(reproStack()))).toHaveLength(0);
+  });
+
+  it('is suppressible per widget via suppressWarnings', () => {
+    const findings = only(validateWidgetBindings(reproStack({
+      categoryField: 'cost_center',
+      suppressWarnings: [WIDGET_LEGACY_ANALYTICS_SHAPE],
+    })));
+    expect(findings).toHaveLength(0);
+  });
+});

packages/lint/src/validate-widget-bindings.ts

@@ -44,6 +44,12 @@ import { isIncoherentAggregate } from '@objectstack/spec/data';
  *   `count_distinct`) of a `percent`/rate field, whose total routinely
  *   exceeds 100%. Rates must AVG. Checked once per dataset (independent of
  *   any widget) when the bound object's field types are known.
+ * - `widget-legacy-analytics-shape` (#1878/#1894) — a widget sets a
+ *   pre-ADR-0021 inline key (`categoryField`/`valueField`/`xAxisField`/
+ *   `yAxisFields`/`aggregate`/`aggregation`/`rowField`/`columnField`) that the
+ *   single-form cutover removed. The dashboard renderer routes dataset-bound
+ *   widgets through `DatasetWidget` and never reads these, so they are a
+ *   silent no-op. Steers the author onto `dataset`+`dimensions`+`values`.
  *
  * Warnings can be deliberately suppressed per widget via
  * `suppressWarnings: ['<rule-id>']`; errors cannot — they describe a
@@ -57,6 +63,21 @@ export const CHART_FIELD_UNKNOWN = 'chart-field-unknown';
 export const CHART_CONFIG_MISSING = 'chart-config-missing';
 export const TABLE_COUNT_ONLY = 'table-count-only';
 export const MEASURE_AGGREGATE_INCOHERENT = 'measure-aggregate-incoherent';
+export const WIDGET_LEGACY_ANALYTICS_SHAPE = 'widget-legacy-analytics-shape';
+
+/**
+ * Pre-ADR-0021 inline-analytics keys. The single-form cutover replaced them
+ * with the semantic-layer shape (`dataset` + `dimensions` + `values`); the
+ * dashboard renderer routes dataset-bound widgets through `DatasetWidget` and
+ * never reads these, so authoring one today is a silent no-op. Warned (not
+ * errored) because they still parse and a legacy object-bound widget keeps
+ * rendering — the author is just being steered to the governed shape.
+ * (liveness audit #1878 / #1894).
+ */
+const LEGACY_ANALYTICS_KEYS = [
+  'categoryField', 'valueField', 'xAxisField', 'yAxisFields',
+  'aggregate', 'aggregation', 'rowField', 'columnField',
+] as const;
 
 export type WidgetBindingSeverity = 'error' | 'warning';
 
@@ -229,6 +250,30 @@ export function validateWidgetBindings(stack: AnyRec): WidgetBindingFinding[] {
         findings.push({ ...f, where, path });
       };
 
+      // ── (a0) legacy pre-ADR-0021 analytics shape → advisory ──
+      // Steer authors (very often an AI) off the removed inline shape and onto
+      // the semantic-layer `dataset`+`dimensions`+`values`. Fires whether or
+      // not a dataset is also present, because the renderer ignores these keys
+      // either way — a dataset-bound widget carrying `categoryField` silently
+      // drops it. Suppressible per widget; never fails the build.
+      const legacyUsed = LEGACY_ANALYTICS_KEYS.filter((k) => w[k] !== undefined);
+      if (legacyUsed.length > 0) {
+        push({
+          severity: 'warning',
+          rule: WIDGET_LEGACY_ANALYTICS_SHAPE,
+          message:
+            `sets legacy analytics key${legacyUsed.length > 1 ? 's' : ''} ` +
+            `${legacyUsed.map((k) => `\`${k}\``).join(', ')} that the ADR-0021 ` +
+            `single-form cutover removed — the dashboard renderer ignores ${legacyUsed.length > 1 ? 'them' : 'it'}.`,
+          hint:
+            `Bind a semantic dataset and select fields BY NAME instead: ` +
+            `\`dataset: '<name>', dimensions: [...], values: [...]\`. ` +
+            `Dataset-bound widgets render through DatasetWidget (pivot rows/cols come from ` +
+            `\`dimensions\`, cell values from \`values\`); these inline keys are a no-op. ` +
+            `Suppress with suppressWarnings: ['${WIDGET_LEGACY_ANALYTICS_SHAPE}'] if intentional.`,
+        });
+      }
+
       // ── (a) dataset reference resolves ──
       const dsName = typeof w.dataset === 'string' ? w.dataset : undefined;
       const dataset = dsName ? datasets.get(dsName) : undefined;