feat(lint): error (not warn) when a legacy dashboard widget binds no data source (#1878/#1894)

Escalation of the legacy-analytics-shape rule for the case that is an outright
bug rather than deprecated-but-working: a widget that uses the removed
pre-ADR-0021 inline keys (categoryField/rowField/valueField/…) as its ONLY
data wiring — no `dataset`, no `object`, no inline `data`. The renderer reads
only the dataset path, so such a widget has no data at all and renders
nothing.

New rule `widget-legacy-analytics-unrenderable` (severity error) fires for
exactly that case; the existing `widget-legacy-analytics-shape` stays a
suppressible warning when a data source IS present (the widget still renders,
the legacy keys are just ignored noise).

Rationale (AI-writes / human-reviews): a silently-blank widget is precisely
what a human reviewer misses. Because validateWidgetBindings runs only in the
CLI author path (`objectstack compile`/`validate`/`doctor`/`lint`, never in
Studio's runtime authoring), this fails the AI/code build in CI without
touching Studio. It only fails builds that are already broken (the widget
renders nothing regardless), so it surfaces an existing defect rather than
introducing a new gate. Errors are not suppressible.

Framework examples/fixtures carry no legacy-key dashboards, so nothing
regresses. Tests: 3 new cases (unrenderable→error, object-bound→warning,
error-not-suppressible); full suite 40 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

@@ -9,6 +9,7 @@ import {
   CHART_CONFIG_MISSING,
   MEASURE_AGGREGATE_INCOHERENT,
   WIDGET_LEGACY_ANALYTICS_SHAPE,
+  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
 } from './validate-widget-bindings.js';
 
 /** The downstream repro from issue #1719 — dataset with a count AND a sum
@@ -431,4 +432,54 @@ describe('validateWidgetBindings — legacy analytics shape (#1878/#1894)', () =
     })));
     expect(findings).toHaveLength(0);
   });
+
+  // ── error escalation (②): legacy keys as the ONLY data wiring ──
+
+  const legacyOnly = (findings: ReturnType<typeof validateWidgetBindings>) =>
+    findings.filter((f) => f.rule === WIDGET_LEGACY_ANALYTICS_UNRENDERABLE);
+
+  it('ERRORS on a legacy chart with no dataset/object/data — it renders nothing', () => {
+    const stack = {
+      dashboards: [{
+        name: 'broken_dash',
+        label: 'Broken',
+        widgets: [{
+          id: 'orphan_chart',
+          type: 'bar',
+          categoryField: 'status',
+          valueField: 'amount',
+          aggregate: 'sum',
+          layout: { x: 0, y: 0, w: 6, h: 4 },
+        }],
+      }],
+    };
+    const findings = legacyOnly(validateWidgetBindings(stack));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].severity).toBe('error');
+    expect(findings[0].message).toMatch(/renders nothing/i);
+  });
+
+  it('does NOT error when an object binding is present (legacy path still renders) — warns instead', () => {
+    const stack = {
+      dashboards: [{
+        name: 'legacy_dash', label: 'Legacy',
+        widgets: [{ id: 'obj_pivot', type: 'pivot', object: 'task', rowField: 'status', columnField: 'priority', valueField: 'id', aggregation: 'count', layout: { x: 0, y: 0, w: 6, h: 4 } }],
+      }],
+    };
+    const findings = validateWidgetBindings(stack);
+    expect(findings.filter((f) => f.rule === WIDGET_LEGACY_ANALYTICS_UNRENDERABLE)).toHaveLength(0);
+    expect(findings.filter((f) => f.rule === WIDGET_LEGACY_ANALYTICS_SHAPE)).toHaveLength(1);
+    expect(findings.find((f) => f.rule === WIDGET_LEGACY_ANALYTICS_SHAPE)!.severity).toBe('warning');
+  });
+
+  it('the unrenderable error is NOT suppressible', () => {
+    const stack = {
+      dashboards: [{
+        name: 'broken_dash', label: 'Broken',
+        widgets: [{ id: 'orphan', type: 'pie', categoryField: 'status', suppressWarnings: [WIDGET_LEGACY_ANALYTICS_UNRENDERABLE], layout: { x: 0, y: 0, w: 6, h: 4 } }],
+      }],
+    };
+    // errors ignore suppressWarnings — a blank widget must not be silenceable
+    expect(legacyOnly(validateWidgetBindings(stack))).toHaveLength(1);
+  });
 });

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

@@ -27,6 +27,13 @@ import { isIncoherentAggregate } from '@objectstack/spec/data';
  *   (`values`). Post-cutover (ADR-0021) the result rows are keyed by
  *   measure NAME (e.g. `sum_amount`), not the base column (`amount`) — a
  *   stale base-column reference renders the axis but an empty series.
+ * - `widget-legacy-analytics-unrenderable` (#1878/#1894) — a widget uses the
+ *   removed pre-ADR-0021 inline-analytics shape (`categoryField`/`rowField`/…)
+ *   as its ONLY data wiring: no `dataset`, no `object`, no inline `data`. The
+ *   renderer reads only the dataset path, so the widget has no data at all and
+ *   renders nothing. Errored (not warned) so this class of authoring mistake —
+ *   very often an AI emitting a removed shape — fails the build instead of
+ *   shipping a blank widget past human review.
  *
  * Advisory rules — severity `warning`, build stays green:
  *
@@ -64,6 +71,7 @@ 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';
+export const WIDGET_LEGACY_ANALYTICS_UNRENDERABLE = 'widget-legacy-analytics-unrenderable';
 
 /**
  * Pre-ADR-0021 inline-analytics keys. The single-form cutover replaced them
@@ -250,28 +258,53 @@ export function validateWidgetBindings(stack: AnyRec): WidgetBindingFinding[] {
         findings.push({ ...f, where, path });
       };
 
-      // ── (a0) legacy pre-ADR-0021 analytics shape → advisory ──
+      // ── (a0) legacy pre-ADR-0021 analytics shape ──
       // 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.
+      // the semantic-layer `dataset`+`dimensions`+`values`. The renderer reads
+      // ONLY the dataset path, so these keys are dead. Two severities:
+      //   • ERROR   — the legacy keys are the widget's only (dead) data wiring
+      //               (no dataset / object / inline data): it renders nothing.
+      //   • warning — a data source is present, so the widget still renders and
+      //               the legacy keys are merely ignored noise (suppressible).
       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.`,
-        });
+        const optionsData =
+          typeof w.options === 'object' && w.options !== null &&
+          (w.options as AnyRec).data !== undefined;
+        const hasDataSource =
+          w.dataset !== undefined || w.object !== undefined ||
+          w.data !== undefined || optionsData;
+        const keyList = legacyUsed.map((k) => `\`${k}\``).join(', ');
+        const plural = legacyUsed.length > 1;
+        const datasetHint =
+          `Bind a semantic dataset and select fields BY NAME: ` +
+          `\`dataset: '<name>', dimensions: [...], values: [...]\`. ` +
+          `Dataset-bound widgets render through DatasetWidget (pivot rows/cols come from ` +
+          `\`dimensions\`, cell values from \`values\`).`;
+        if (!hasDataSource) {
+          push({
+            severity: 'error',
+            rule: WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
+            message:
+              `sets legacy analytics key${plural ? 's' : ''} ${keyList} ` +
+              `(removed by the ADR-0021 single-form cutover) and binds no data source ` +
+              `(no \`dataset\`, \`object\`, or inline \`data\`) — it renders nothing.`,
+            hint:
+              `${datasetHint} The renderer ignores the legacy keys, so without a data ` +
+              `source this widget has no data at all.`,
+          });
+        } else {
+          push({
+            severity: 'warning',
+            rule: WIDGET_LEGACY_ANALYTICS_SHAPE,
+            message:
+              `sets legacy analytics key${plural ? 's' : ''} ${keyList} that the ADR-0021 ` +
+              `single-form cutover removed — the dashboard renderer ignores ${plural ? 'them' : 'it'}.`,
+            hint:
+              `${datasetHint} These inline keys are a no-op. ` +
+              `Suppress with suppressWarnings: ['${WIDGET_LEGACY_ANALYTICS_SHAPE}'] if intentional.`,
+          });
+        }
       }
 
       // ── (a) dataset reference resolves ──