fix(lint): resolve a dashboard widget's own filter keys and options.sortBy at validate/build (#14276)

* wip(lint): widget filter keys + sortBy limbs on the #14105 seam

* test(lint): pin both #14148 limbs; path-precise findings

* test(lint): pin the validate+build acceptance criterion for both limbs

* chore: changeset for #14148

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: baozhoutao

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+  column on the bound dataset's object graph. Reported path-precise at
+  `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+  that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+  not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+  out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+  `values[]` entry of the widget. A name the dataset declares but the widget did not
+  select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
   WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
   DASHBOARD_FILTER_FIELD_UNKNOWN,
   DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+  // [#14148] The widget's OWN two references, at the same site: the keys of its
+  // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+  // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+  // `options.sortBy` against what the widget selects.
+  WIDGET_FILTER_FIELD_UNKNOWN,
+  WIDGET_FILTER_FIELD_NOT_INCLUDED,
+  WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
   indexObjectGraph,
   resolveFieldPath,
   isUnjudgeable,
+  joinablePrefixes,
+  describeFieldPathVerdict,
   nearestName,
   suggestName,
   listNames,
   RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+  ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
   return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+  const prefixes = new Set<string>();
+  if (!Array.isArray(include)) return prefixes;
+  for (const entry of include) {
+    if (typeof entry !== 'string' || !entry) continue;
+    const segments = entry.split('.');
+    for (let i = 1; i <= segments.length; i++) {
+      prefixes.add(segments.slice(0, i).join('.'));
+    }
+  }
+  return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+  /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+  message: string;
+  /** The supporting field list, for the finding's hint. */
+  detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+  verdict: FieldPathVerdict,
+  path: string,
+  subject: string,
+): FieldPathAccount | undefined {
+  switch (verdict.kind) {
+    case 'ok':
+    case 'unknowable':
+    case 'hop-untargeted':
+      return undefined;
+    case 'hop-unknown':
+      return {
+        message:
+          `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+          `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+        detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+      };
+    case 'hop-not-relationship':
+      return {
+        message:
+          `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+          `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+          `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+        detail:
+          `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+          `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+      };
+    case 'field-unknown':
+      return {
+        message:
+          `${subject} "${path}" is not a field on object "${verdict.object}".` +
+          `${suggestName(verdict.field, verdict.candidates)}`,
+        detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+      };
+  }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
   RELATIONSHIP_FIELD_TYPES,
+  describeFieldPathVerdict,
   indexObjectGraph,
   isUnjudgeable,
-  listNames,
+  joinablePrefixes,
   resolveFieldPath,
-  suggestName,
-  type FieldPathVerdict,
   type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
   return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
-  const prefixes = new Set<string>();
-  if (!Array.isArray(include)) return prefixes;
-  for (const entry of include) {
-    if (typeof entry !== 'string' || !entry) continue;
-    const segments = entry.split('.');
-    for (let i = 1; i <= segments.length; i++) {
-      prefixes.add(segments.slice(0, i).join('.'));
-    }
-  }
-  return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
-  verdict: FieldPathVerdict,
-  path: string,
-  subject: string,
-): { message: string; detail: string } | undefined {
-  switch (verdict.kind) {
-    case 'ok':
-    case 'unknowable':
-    case 'hop-untargeted':
-      return undefined;
-    case 'hop-unknown':
-      return {
-        message:
-          `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
-          `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
-        detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
-      };
-    case 'hop-not-relationship':
-      return {
-        message:
-          `${subject} "${path}" traverses "${verdict.segment}", which is a` +
-          `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
-          `"${verdict.object}" and not a relationship — there is nothing to join through.`,
-        detail:
-          `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
-          `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
-      };
-    case 'field-unknown':
-      return {
-        message:
-          `${subject} "${path}" is not a field on object "${verdict.object}".` +
-          `${suggestName(verdict.field, verdict.candidates)}`,
-        detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
-      };
-  }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
   'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
         return;
       }
 
-      const account = existenceMessage(verdict, entry, `include[${ii}]`);
+      const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
       if (!account) return;
       findings.push({
         severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
       const verdict = resolveFieldPath(graph, object, written);
       if (isUnjudgeable(verdict) || !verdict) return;
 
-      const account = existenceMessage(verdict, written, subject);
+      const account = describeFieldPathVerdict(verdict, written, subject);
       if (account) {
         findings.push({
           severity: 'error',