Skip to content

Commit cb1b688

Browse files
committed
Merge origin/main into claude/project-thread-i8f8j5
Claude-Session: https://claude.ai/code/session_01L6bhgW82YGUW8s8X4Dgiqc Co-authored-by: Claude <noreply@anthropic.com>
2 parents e757894 + 6892888 commit cb1b688

16 files changed

Lines changed: 424 additions & 10 deletions
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
'@objectstack/lint': minor
3+
'@objectstack/spec': minor
4+
---
5+
6+
feat(lint)!: `dashboard-filter-binding-unknown` refuses a widget `filterBindings` key that names no filter the dashboard declares, naming the widget, the key and the declared filters
7+
8+
Clause-②: no (narrowing) — `os validate`, `os build`, `os lint` and the metadata publish door (`422 INVALID_METADATA`) refuse a dashboard whose widget `filterBindings` carries a key that names no declared filter (`{ regoin: false }` beside a `region` filter, or a `dateRange` key on a dashboard that declares no `dateRange`), which they accepted before. A draft still saves, and its `_diagnostics` read reports the same verdict. No accept set is widened; one rule id and its exported constant `DASHBOARD_FILTER_BINDING_UNKNOWN` are added.
9+
Metadata-protocol: narrowed
10+
11+
<!-- adr-0087: registered ui-dashboard-filter-binding-unknown-refused -->
12+
13+
**BREAKING** accept-set narrowing at every authoring door for `dashboard`.
14+
15+
- **Before.** `PUT /api/v1/meta/dashboard/<name>?mode=draft` and the publish that followed both answered `200` for a widget binding `filterBindings: { no_such_filter: 'status' }`. The runtime reads a binding by looking up each declared filter's name, so the key was never read: a misspelled opt-out left the widget scoped by the filter it was meant to ignore, and a misspelled re-target left the filter on its default field.
16+
- **Now.** The rule reports the key at `widgets[i].filterBindings.<key>` at `error`, naming the widget, the key and the declared filters, with the nearest declared name as a "Did you mean". A key is valid when it names a `globalFilters` entry (by its `name`, or its `field` when it has no `name`) or is `dateRange` on a dashboard that declares `dateRange`. It is not suppressible.
17+
- **Who sees it.** A dashboard with a misspelled or stale binding key, for example one left behind after its filter was renamed or removed. No dashboard in this repository's examples or platform objects, and none in the public HotCRM app, binds an undeclared key.
18+
- **Stored rows.** A `sys_metadata` dashboard written before this release with such a key still loads and renders as before: the rule judges the authoring path, not the load path. Its next save or publish is refused until the key is fixed.
19+
20+
**The remedy.** Rename the key to one of the declared filter names the finding lists, declare the filter on the dashboard, or delete the entry.
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
fix(skills): four objectstack-platform eval cases agree with their own `must_not_contain` assertions
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
- **Before.** In `skills/objectstack-platform/evals/config-plugins-ops.json`, four cases refused a string their own `expected_output` spelled: eval 1 `tableName`, eval 2 `data:beforeInsert` and `onInstall`, eval 4 `@objectstack/adapter-`, eval 7 `role:` and `admin_full_access`. Graded against those assertions, the reference answer itself scored wrong, so the eval could not tell a good configuration, plugin or operations answer from a bad one.
11+
- **Now.** Judged per case from the skill text. Eval 1 narrows its assertion to the key spelling `tableName:` (the skill's own warning, "never set `tableName`", names the bare word; the wrong form is the key beside `workflows:` / `approvals:`). Eval 2 says "a `data:*` kernel hook registers and never fires" and "no install / enable / disable hooks" instead of spelling the phantom hook and method. Eval 4 says "no `adapter-*` packages exist". Eval 7 names the refused alias as `role` (the key spelling `role:` stays refused) and says "no platform set" (the skill's term for a set such as the refused platform-admin one). No assertion is deleted, no case added or removed; the file shrinks by 13 tokens under its unchanged ceiling.
12+
- No schema, key or behaviour changes.

‎content/docs/deployment/validating-metadata.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,13 @@ dashboard, widget, filter, field, and object. Opt a widget out with
5757
`filterBindings: { <name>: false }`, or re-target the filter to one of that
5858
object's own fields.
5959

60+
The keys of `filterBindings` are checked too. Each must name a filter the
61+
dashboard declares (a `globalFilters[]` entry's `name`, or its `field` when it
62+
has none, and `dateRange` only when the dashboard declares one). A key naming
63+
anything else is never read at runtime, so a misspelled opt-out leaves the
64+
widget filtered after all; `os validate` refuses it as
65+
`dashboard-filter-binding-unknown`, listing the declared filters.
66+
6067
This is no longer only a CLI verdict. Since #7529 the same rule also runs at the
6168
**runtime publish door** for `dashboard` writes, so a board published from
6269
Studio, `PUT /api/v1/meta/*` or an MCP/AI author is refused there too — the same

‎content/docs/references/ui/dashboard.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ const result = DashboardSchema.parse(data);
7676
| **values** | `string[]` | ✅ | Measure names — Y (at least one; exactly one on the metric/kpi/gauge/solid-gauge/bullet family and on the single-series pie/donut/funnel/treemap/sankey; with no dimensions, two or more only on table/pivot/bar/column/horizontal-bar/line/area/combo) |
7777
| **layout** | `{ x: number; y: number; w: number; h: number }` | optional | Grid layout position (auto-flowed when omitted) |
7878
| **options** | `{ dateGranularity?: Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; sortBy?: string; sortOrder?: Enum<'asc' \| 'desc'>; limit?: integer; … } & Record<string, any>` | optional | Widget specific configuration |
79-
| **filterBindings** | `Record<string, string \| false>` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out |
79+
| **filterBindings** | `Record<string, string \| false>` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out. Each key must name a filter the dashboard declares (dateRange only when declared); lint rule dashboard-filter-binding-unknown refuses any other |
8080
| **suppressWarnings** | `string[]` | optional | Build diagnostic rule ids suppressed on this widget |
8181

8282
### Nested Shape: `Dashboard.dateRange`
@@ -176,7 +176,7 @@ Dashboard header action
176176
| **values** | `string[]` | ✅ | Measure names — Y (at least one; exactly one on the metric/kpi/gauge/solid-gauge/bullet family and on the single-series pie/donut/funnel/treemap/sankey; with no dimensions, two or more only on table/pivot/bar/column/horizontal-bar/line/area/combo) |
177177
| **layout** | `{ x: number; y: number; w: number; h: number }` | optional | Grid layout position (auto-flowed when omitted) |
178178
| **options** | `{ dateGranularity?: Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; sortBy?: string; sortOrder?: Enum<'asc' \| 'desc'>; limit?: integer; … } & Record<string, any>` | optional | Widget specific configuration |
179-
| **filterBindings** | `Record<string, string \| false>` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out |
179+
| **filterBindings** | `Record<string, string \| false>` | optional | Per-widget dashboard-filter bindings: filter name → this widget's field, or false to opt out. Each key must name a filter the dashboard declares (dateRange only when declared); lint rule dashboard-filter-binding-unknown refuses any other |
180180
| **suppressWarnings** | `string[]` | optional | Build diagnostic rule ids suppressed on this widget |
181181

182182
### Allowed Values: `DashboardWidget.type`

‎content/docs/ui/dashboards.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,7 @@ They are two different namespaces:
466466
| :--- | :--- | :--- |
467467
| `globalFilters[].field` (after any `filterBindings` re-target) | The bound widget's `dataset.object` — a bare name against that object's own fields, a dotted `relationship.field` path hop by hop with its prefix declared in the dataset's `include` | `dashboard-filter-field-unknown`, severity **error** |
468468
| `widgets[].dimensions[]` | The dataset's declared `dimensions`, by name | `widget-dimension-unknown`, severity **error** |
469+
| `widgets[].filterBindings` keys | The dashboard's declared filters, by name: each `globalFilters[].name` (its `field` when unnamed), and `dateRange` only when the dashboard declares `dateRange` | `dashboard-filter-binding-unknown`, severity **error** |
469470

470471
Two consequences follow, and their asymmetry is the part that surprises authors:
471472

@@ -547,6 +548,12 @@ Binding precedence: an explicit `filterBindings` entry (string override or
547548
`false` opt-out) → the filter's legacy `targetWidgets` allow-list → the
548549
filter's own `field`.
549550

551+
Each key must name a filter the dashboard declares. The dashboard looks a
552+
binding up by the declared filter's name, so a misspelled key (`regoin` for
553+
`region`) is never read and the widget keeps the filter it was meant to drop
554+
or re-target. `os validate` and the publish door refuse such a key with
555+
`dashboard-filter-binding-unknown`, naming the declared filters.
556+
550557
### In the Console
551558

552559
- **The filter bar.** The date range and each global filter render as controls above the

‎packages/lint/src/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,10 @@ export {
4040
// field, now that it is resolved on the object graph rather than skipped
4141
// whenever it was dotted.
4242
DASHBOARD_FILTER_FIELD_NOT_INCLUDED,
43+
// [#27445] A `filterBindings` KEY naming no filter the dashboard declares:
44+
// the runtime reads a binding by the declared filter's name, so the entry is
45+
// never read and the widget keeps the filter it meant to drop or re-target.
46+
DASHBOARD_FILTER_BINDING_UNKNOWN,
4347
// [#14148] The widget's OWN two references, at the same site: the keys of its
4448
// presentation-scope `filter` (resolved on the #14105 object-graph seam, with
4549
// the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and

‎packages/lint/src/rule-explanations.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,25 @@ const DASHBOARD_FILTER_FIELD_UNKNOWN_EXPLANATION: RuleExplanation = {
379379
],
380380
};
381381

382+
const DASHBOARD_FILTER_BINDING_UNKNOWN_EXPLANATION: RuleExplanation = {
383+
rule: 'dashboard-filter-binding-unknown',
384+
covers: 'which keys a widget\'s filterBindings may name',
385+
paragraphs: [
386+
'A widget\'s `filterBindings` maps a dashboard filter\'s NAME to one of the widget\'s own fields ' +
387+
'(re-target) or to `false` (opt out). The names a widget may bind are the ones its dashboard ' +
388+
'declares: each `globalFilters` entry under its `name` (its `field` when `name` is omitted), and ' +
389+
'the reserved name `dateRange` when the dashboard declares `dateRange`.',
390+
'The runtime reads a binding by looking up each declared filter\'s name, so a key that names no ' +
391+
'declared filter is never read. A misspelled opt-out leaves the widget scoped by the filter it ' +
392+
'was meant to ignore, and a misspelled re-target leaves the filter on its default field. Either ' +
393+
'way the widget counts different rows than the author wrote, with nothing on the page to say so, ' +
394+
'which is why the rule is an error and is not suppressible.',
395+
'To fix it, rename the key to a declared filter name (the finding names the nearest one), declare ' +
396+
'the filter on the dashboard, or delete the entry. A `dateRange` key on a dashboard that declares ' +
397+
'no `dateRange` is reported the same way: there is no date range for it to bind.',
398+
],
399+
};
400+
382401
const DASHBOARD_FILTER_FIELD_NOT_INCLUDED_EXPLANATION: RuleExplanation = {
383402
rule: 'dashboard-filter-field-not-included',
384403
covers: 'why a filter\'s relationship prefix must be included',
@@ -5179,6 +5198,7 @@ export const RULE_EXPLANATIONS: Readonly<Record<string, RuleExplanation>> = Obje
51795198
[WIDGET_LEGACY_ANALYTICS_SHAPE_EXPLANATION.rule]: WIDGET_LEGACY_ANALYTICS_SHAPE_EXPLANATION,
51805199
[DASHBOARD_FILTER_FIELD_UNKNOWN_EXPLANATION.rule]: DASHBOARD_FILTER_FIELD_UNKNOWN_EXPLANATION,
51815200
[DASHBOARD_FILTER_FIELD_NOT_INCLUDED_EXPLANATION.rule]: DASHBOARD_FILTER_FIELD_NOT_INCLUDED_EXPLANATION,
5201+
[DASHBOARD_FILTER_BINDING_UNKNOWN_EXPLANATION.rule]: DASHBOARD_FILTER_BINDING_UNKNOWN_EXPLANATION,
51825202
[DASHBOARD_FILTER_FIELD_UNPROVISIONED_EXPLANATION.rule]: DASHBOARD_FILTER_FIELD_UNPROVISIONED_EXPLANATION,
51835203
[WIDGET_FILTER_FIELD_UNKNOWN_EXPLANATION.rule]: WIDGET_FILTER_FIELD_UNKNOWN_EXPLANATION,
51845204
[WIDGET_FILTER_FIELD_NOT_INCLUDED_EXPLANATION.rule]: WIDGET_FILTER_FIELD_NOT_INCLUDED_EXPLANATION,

‎packages/lint/src/runtime-gate.test.ts‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -856,7 +856,7 @@ describe('dashboard widget dataset bindings at the runtime publish gate (#7529)'
856856
expect(dangling.errors).toHaveLength(1);
857857
});
858858

859-
it('ALL FIVE error ids are reachable at the door — the class the 2026-08-15 ruling accepted', () => {
859+
it('ALL SIX error ids are reachable at the door — the class the 2026-08-15 ruling accepted', () => {
860860
// `surfaces` is per-rule, so the flip enforces the rule's whole error set,
861861
// not just `widget-dataset-unknown`. The ruling accepted the class as one
862862
// coherent "this board cannot render" set — this test makes that
@@ -897,6 +897,14 @@ describe('dashboard widget dataset bindings at the runtime publish gate (#7529)'
897897
dashboard([cleanWidget()], { dateRange: { field: 'close_date' } }),
898898
['dashboard-filter-field-unknown'],
899899
],
900+
[
901+
// [#27445] The sixth id joins through the same per-rule `surfaces`: a
902+
// binding key the runtime never reads leaves the widget counting rows
903+
// the author scoped out, so it is refused at the door with the five.
904+
'filterBindings key naming no declared dashboard filter',
905+
dashboard([cleanWidget({ filterBindings: { no_such_filter: false } })]),
906+
['dashboard-filter-binding-unknown'],
907+
],
900908
];
901909

902910
const seen = new Set<string>();
@@ -909,9 +917,10 @@ describe('dashboard widget dataset bindings at the runtime publish gate (#7529)'
909917
for (const e of errors) seen.add(e.rule);
910918
}
911919

912-
// Non-vacuous, and the ruling's whole accept-set as #15463 left it:
913-
// exactly the five. `chart-field-unknown` is deliberately absent.
920+
// Non-vacuous, and the ruling's whole accept-set as #15463 left it plus
921+
// #27445's id: exactly the six. `chart-field-unknown` is deliberately absent.
914922
expect([...seen].sort()).toEqual([
923+
'dashboard-filter-binding-unknown',
915924
'dashboard-filter-field-unknown',
916925
'widget-dataset-unknown',
917926
'widget-dimension-unknown',
@@ -921,6 +930,18 @@ describe('dashboard widget dataset bindings at the runtime publish gate (#7529)'
921930
expect(seen.has('chart-field-unknown')).toBe(false);
922931
});
923932

933+
it('[#27445] a binding to a DECLARED filter passes the door; a misspelled key is refused at its path', () => {
934+
const declared = { globalFilters: [{ name: 'region', field: 'region', type: 'select' }] };
935+
const ok = gateDashboard(dashboard([cleanWidget({ filterBindings: { region: false } })], declared));
936+
expect(ok.errors, JSON.stringify(ok.errors)).toEqual([]);
937+
938+
const typo = gateDashboard(dashboard([cleanWidget({ filterBindings: { regoin: false } })], declared));
939+
expect(typo.errors.map((e) => e.rule)).toEqual(['dashboard-filter-binding-unknown']);
940+
expect(typo.errors[0].path).toBe('dashboards[0].widgets[0].filterBindings.regoin');
941+
expect(typo.errors[0].message).toContain('(declared: region)');
942+
expect(typo.errors[0].hint).toContain('Did you mean "region"?');
943+
});
944+
924945
it('the demoted `chart-field-unknown` still RUNS at the door — on the advisory channel (#15463)', () => {
925946
// The other half of the accept-set narrowing: the exact body that used to
926947
// 422 now publishes, and the finding reaches the author on the 2xx response

0 commit comments

Comments
 (0)