feat(cli): dashboard widget reference integrity check (dataset → dimensions/measures + chartConfig fields)

[os-zhuang]

Closes #1721.

What

Extends the #1719 semantic widget-binding pass (validateWidgetBindings) into the full dashboard widget reference integrity check the issue proposes, and surfaces it in all four build-time tools:

Rule	Severity	Issue item
widget-dataset-unknown	error	(a) dataset resolves to a declared Dataset
widget-dimension-unknown	error	(b) every dimensions[] entry is a real dataset dimension
widget-measure-unknown	error	(c) every values[] entry is a real dataset measure
chart-field-unknown	error	(d) chartConfig.xAxis.field resolves to a dataset dimension; yAxis[].field / series[].name resolve to a measure selected in values
chart-config-missing	warning	(d) chart-type widget with no chartConfig at all
table-count-only	warning	(e) — already landed in #1719, unchanged

• validate — semantic pass after safeParse succeeds; errors fail with located, corrective messages (and in --json); warnings print non-blocking (--strict makes them fatal).
• build/compile — same: errors fail the build where the cutover damage actually occurred (CI).
• lint — findings pass their real severity through (was hardcoded warning).
• doctor — new "Dashboard integrity — All widgets resolve datasets, dimensions, and measures" section mirroring the orphan-view pass.

Messages list the declared names and carry a did-you-mean suggestion with containment checked before edit distance, so the cutover's canonical drift (amount → sum_amount) is suggested:

✗ Dashboard widget integrity failed (1 issue)
• dashboard "pipeline_dashboard" › widget "pipeline_trend_90d": chartConfig.yAxis[0].field "amount"
  does not resolve to a measure of dataset "opportunity_metrics" (declared measures: opp_count,
  total_amount, avg_amount).
    Post-cutover data is keyed by the dataset's measure NAME, not the base column.
    rule: chart-field-unknown  at dashboards[0].widgets[3]

Design notes

• Errors are not suppressible — they describe a binding the analytics service cannot satisfy; suppressWarnings: ['<rule-id>'] keeps working for the two advisory rules.
• A chartConfig field that names an already-invalid values/dimensions entry is not double-reported — rules (b)/(c) own that error.
• A widget whose dataset doesn't resolve reports once and skips the name checks (nothing to resolve against).
• Per the issue, the check lives in the CLI (where multi-package config is assembled), not the spec schema — a widget in one package can resolve a dataset in another.
• A measure that is declared on the dataset but not selected in the widget's values gets a targeted message ("the query result will not contain it") instead of the generic one.

Example apps

chart-config-missing flagged 19 chart widgets across the three example apps — all authored without chartConfig. They now carry the explicit mapping (xAxis.field = dimension, yAxis[].field = measure name), the authoring shape templates#30 standardized on after browser-verifying it fixes the blank charts. Note the tension: objectui HEAD's DatasetWidget (since 92449ef99) derives series from values and ignores chartConfig, so at HEAD the warning is advisory rather than a real breakage — but published renderers consume it, and the explicit form is compatible both ways. If values-derived rendering becomes the contract everywhere, chart-config-missing can be dropped without touching the error rules.

app-todo's two count-only record-listing tables (overdue_tasks_table, due_today) still warn under table-count-only — re-modeling them as object-bound ListViews (ADR-0017) is #1719's failure class, left as a follow-up.

Verification

• 28 unit tests on the validator (incl. both issue repros: the validate/doctor: add Dashboard widget reference integrity check (dataset → dimensions/measures + chartConfig fields) #1721 sum_amount/amount chart and the 构建期告警：table/pivot dashboard widget 绑定到「count-only」数据集（很可能是应做成 ListView 的记录列表） #1719 count-only table); full CLI suite 254 passed; tsc clean.
• All three example apps: validate passes, dashboards typecheck (remaining showcase page-type errors are pre-existing drift in untouched files).
• Negative path exercised end-to-end: a stale yAxis.field makes both validate and build exit 1 with the message above; doctor prints the new integrity section.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 11, 2026 10:28am