Repository navigation
Commit 5d8e559
docs(skills): type-check more objectstack-ui examples with os:check (#31706)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} -->
_Requested by **Steedos** · [project
thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9UbbMte2M4pEgfqrXNwg6KKjWH)_
Refs #31112 (slice 3 of a per-skill split: item 4, objectstack-ui; the
card stays open)
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:objectstack-ui 技能包里又有 10 段 TypeScript 示例接入了示例编译检查(33 段中由 15 段变为
25 段),涉及动作、页面、仪表盘和看板/甘特视图的示例;没有发现写错的示例。
- 为什么改:AI 编写界面元数据时最先照抄这些示例;接入检查后,规范一旦改名或收紧,示例会在 CI 里立刻变红,而不是悄悄教错。
- 风险与回滚:只改发布技能包的文档文字,不动任何运行时代码;四个文件的 token
上限都未抬高,新增字节靠同文件删减重复说明支付(每处删减的规则都在同文件另有出处)。回滚即 revert 本 PR。
- 先看:`skills/objectstack-ui/rules/dashboards.md`(4
段新接入、删减最多)、`skills/objectstack-ui/rules/list-views.md`(看板与甘特示例改为带类型的
`ListView`)、`skills/objectstack-ui/rules/pages.md`(3 段新接入)。
- 两分钟验证:`pnpm --filter @objectstack/spec check:skill-examples`,预期最后一行为
332 段示例全部通过类型检查。
- 需要你做的:作为受管面审批人审阅并批准本 PR(skills/** 属 Tier H)。
## What changes
`skills/objectstack-ui` had 15 of its 33 fenced `ts`/`typescript` blocks
under `check:skill-examples` (measured on `main` 8210894, all `*.md`
outside `evals/`; `references/_index.md` and the generator-owned
`references/react-blocks.md`, which holds no ts block, excluded). It now
has 25. Every new mark is the os:check marker on the line above the
fence; each wrapper is one import line plus a typed `const` on the
existing first line (and, for the two arrays, one opening and one
closing line), never more than three lines.
| File | marked before → after / blocks | tokens before → after /
ceiling | lines before → after |
|:--|:--|:--|:--|
| `rules/actions.md` | 4 → 5 / 5 | 2258 → 2257 / 2259 | 181 → 184 |
| `rules/dashboards.md` | 4 → 8 / 9 | 6232 → 6231 / 6232 | 462 → 473 |
| `rules/list-views.md` | 3 → 5 / 11 | 3451 → 3446 / 3451 | 329 → 334 |
| `rules/pages.md` | 1 → 4 / 4 | 5648 → 5668 / 5669 | 426 → 432 |
| untouched: `SKILL.md`, `navigation.md`, `record-page.md` | 0/1, 2/2,
1/1 | headroom 0, 0, 0 | unchanged |
Skills bundle reading: no `SKILL.md` changed, so the sum of every
published `SKILL.md` stays 4592 lines.
- **`rules/actions.md`**: the `opensInNewTab` + `newTabUrl` action gains
its `defineAction` import and is marked.
- **`rules/pages.md`**: the `kind: 'html'` page gains its `definePage`
import; the styled pricing card becomes `const card: PageComponent = { …
};` and the doc navigation item `const navigation: NavigationItem[] = [
… ];`. The orphan-looking marker above the master/detail block is over a
`tsx` fence and was already counted by the gate, not by this ts tally.
- **`rules/dashboards.md`**: the dataset-bound widget becomes `const
widget: DashboardWidget`; the two `filterBindings` widgets and the two
`compareTo` widgets become `const widgets: DashboardWidget[] = [ … ];`
(the second pair gains the comma between its two objects); the `options`
line becomes `const options: DashboardWidget['options']`. The two bare
`compareTo:` lines stay a fragment and the file says so once.
- **`rules/list-views.md`**: the kanban and gantt examples become `const
board: ListView` and `const timeline: ListView`, so a top-level
`groupBy` or a missing `gantt.startDateField` now fails the gate. The
bare-key blocks (`data`, `columns`, `filter`, `userFilters`, `sort`,
`grouping`) stay fragments and the file says so once.
## Why
#31112 item 4 (ruling B of #22059): published examples are guarded by
the opt-in type check, and every defect the P0 text-fix card found sat
in an unmarked block. This slice brings objectstack-ui's self-contained
examples under it.
### Example fixes
None. Every candidate block was probed in isolation with its wrapper (TS
API, syntactic then semantic pass, with a planted unknown key per file
as the control leg) and compiled as written.
### Trims that paid the marks (each cut and where its rule survives)
- `rules/actions.md` §Action body context: "— the blessed name (same
axes and `undefined` cases as hooks, objectstack-data)" became "(as in
hooks, objectstack-data)". The blessed-name rule survives at
`skills/objectstack-data/references/data-hooks.md:584` ("the single
blessed name") and the same read at `:619`.
- `rules/actions.md` new-tab warning: "builds and draws a checkbox in
the dialog" became "draws a checkbox"; the rule (never express new-tab
via `params`) is unchanged.
- `rules/pages.md` `kind:'html'`: "; use `kind:'react'` for those" cut;
survives in the tier table's `react` row (hooks, `onClick`,
expressions).
- `rules/pages.md` styling block: its comment "every block carries
responsiveStyles + tokens" cut; survives in the Rules list above it
(stable `id` on every styled node, values as design tokens).
- `rules/pages.md` routing: "; that gives one doc many addresses and
breaks cross-references" cut; survives as "so a doc has exactly one URL"
in the same paragraph.
- `rules/pages.md` live instances: "(one source, never a stale copy)"
cut; survives at "Write business concepts" ("has no producer and drifts;
the self-describing metadata is the one source").
- `rules/dashboards.md` §compareTo: "The renderer derives the comparison
automatically; no second `filter` is required." cut; survives at
**Requirements** ("The shifted query reuses the original `filter` shape
and replaces only the date-bound clauses"). ", so what a widget declares
is exactly what runs" cut; the same-shape statement it followed stays.
- `rules/dashboards.md` KPI example comments: the metric's "renderer
fetches the prior quarter and surfaces a secondary value + delta arrow"
survives at **Metric widgets** ("a delta arrow plus a trend label"); the
chart's "(M2). The renderer issues a second query … overlays it as a
muted/dashed series" survives at the §compareTo opening and at
**Cartesian charts** (dashed, reduced opacity).
- `rules/dashboards.md`: the metric comment "(binds the crm_task_metrics
dataset; filter = runtimeFilter)" survives in the block's own `dataset:`
key and at §Dataset-Bound Widgets ("presentation-scope `filter` flows
into the query as the runtime filter"); "for this widget only" in the
options comment survives in the `dateGranularity` table row ("for this
widget only"); the pie/donut rationale clause cut, the rule
("`compareTo` is silently ignored") stays.
- `rules/list-views.md`: "Every view lives under `list` / `form` /
`listViews` / `formViews`, as above." survives in §The `defineView`
container's first sentence; the `lanes` comment "option VALUES to draw,
in this order" survives in the note under the block ("`lanes` chooses
the lanes and their order … not one of the field's inline options"); "—
past the right edge of a narrow screen —" survives in hand-over item (a)
("scroll right"); "; declare `searchableFields` to choose the set"
survives in the table row "declares `searchableFields` | that list,
verbatim"; ": nothing ever drew it", "(the block above)" and "(CRUD,
live updates, filtering, pagination)" carried no rule.
## Tests
<details><summary>check:skill-examples, before and after, and the
reverse check</summary>
- Before (`main` 8210894): `✅ 322 prose examples type-check across 3
surface(s)`.
- After (head 3bc338e; 0de24c0 adds only a merge of `main` touching no
`skills/**` or `packages/spec` path): `pnpm --filter @objectstack/spec
check:skill-examples` exited 0 with `✅ 332 prose examples type-check
across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC
pass on all of them` (skills + docs surface 288 → 298).
- Reverse check, after the commit: planted one wrong key per touched
file: `newTabTarget` (`rules/actions.md:165`), `docName` on the doc nav
item (`rules/pages.md:365`), the retired widget `position`
(`rules/dashboards.md:52`) and a top-level kanban `groupBy`
(`rules/list-views.md:264`). The checker exited 1 with TS2353 at exactly
those four lines. Restored with `git checkout HEAD --
skills/objectstack-ui`; `git diff HEAD` and `git status --porcelain`
were empty after.
</details>
<details><summary>Derived gate sweep (head 3bc338e)</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 44 commands. 43 exited 0. `pnpm
check:dual-build-cjs-loads` exited 3 (PREREQUISITE NOT MET: needs every
package's dist; CI runs it). `dispatch-gates --ran` exited 0: 44
derived, 43 run, 1 NOT-MEASURED, 0 unrun. Re-run on the merged head
0de24c0: `check-skills-token-ratchet`, `check-changeset-no-major --base
origin/main`, `check:skill-links`, `check-empty-changeset --base
origin/main`, all exit 0.
</details>
## Acceptance notes
- `check:skill-examples` is not in the derived gate list for a
`skills/**` diff, so it was run by hand.
- Unmarked, and why: `SKILL.md`'s `subforms` block is indented three
spaces inside a numbered list item, and the gate's fence pattern only
reads a fence at column 0, so a marker there would be an orphan; moving
it out of the list would break the list and costs bytes `SKILL.md` does
not have (headroom 0). In `rules/list-views.md`, `filter`, `sort` and
`grouping` would compile with a three-line wrapper (probed green), but
each costs about 100 bytes and the file has 5 tokens left after the
kanban and gantt marks; `data` (a `[...]` placeholder), `columns` (two
statements) and `userFilters` + `appearance` are true fragments. In
`rules/dashboards.md` the two bare `compareTo:` lines are a fragment.
- No ceiling was raised or lowered; the ratchet printed no lowering
instruction.
- This build ran on the default tier: `dispatch-gates --tier` mandates
Fable for `skills/**`, and the claim records the no-Fable-build exit;
the contract review is the seat's, on the lane's isolated reviewer.
## Verification
`pnpm --filter @objectstack/spec check:skill-examples` (needs
`@objectstack/spec` and `@objectstack/client-react` built) prints 332
examples green; `node scripts/check-skills-token-ratchet.mjs` exits 0
with every `skills/objectstack-ui` file within its ceiling.
## Human Minimum
A governed approver reviews and approves (Tier H).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---
_Generated by [Claude
Code](https://claude.ai/code/session_01QsR2jUzyjnwuhUWHpExHXT)_
Co-authored-by: Claude <noreply@anthropic.com>1 parent 2a32bd4 commit 5d8e559
5 files changed
Lines changed: 81 additions & 46 deletions
File tree
- .changeset
- skills/objectstack-ui/rules
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
114 | 114 | | |
115 | 115 | | |
116 | 116 | | |
117 | | - | |
| 117 | + | |
118 | 118 | | |
119 | 119 | | |
120 | 120 | | |
| |||
150 | 150 | | |
151 | 151 | | |
152 | 152 | | |
| 153 | + | |
153 | 154 | | |
| 155 | + | |
| 156 | + | |
154 | 157 | | |
155 | 158 | | |
156 | 159 | | |
| |||
166 | 169 | | |
167 | 170 | | |
168 | 171 | | |
169 | | - | |
170 | | - | |
| 172 | + | |
| 173 | + | |
171 | 174 | | |
172 | 175 | | |
173 | 176 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
43 | 43 | | |
44 | 44 | | |
45 | 45 | | |
| 46 | + | |
46 | 47 | | |
47 | | - | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
48 | 51 | | |
49 | 52 | | |
50 | 53 | | |
51 | 54 | | |
52 | 55 | | |
53 | 56 | | |
54 | 57 | | |
55 | | - | |
| 58 | + | |
56 | 59 | | |
57 | 60 | | |
58 | 61 | | |
| |||
175 | 178 | | |
176 | 179 | | |
177 | 180 | | |
178 | | - | |
179 | | - | |
180 | 181 | | |
181 | 182 | | |
182 | 183 | | |
183 | | - | |
184 | | - | |
185 | | - | |
| 184 | + | |
186 | 185 | | |
187 | 186 | | |
188 | 187 | | |
| |||
212 | 211 | | |
213 | 212 | | |
214 | 213 | | |
| 214 | + | |
215 | 215 | | |
| 216 | + | |
| 217 | + | |
216 | 218 | | |
| 219 | + | |
217 | 220 | | |
218 | 221 | | |
219 | 222 | | |
220 | 223 | | |
| 224 | + | |
221 | 225 | | |
222 | 226 | | |
223 | 227 | | |
224 | 228 | | |
225 | 229 | | |
226 | | - | |
227 | | - | |
| 230 | + | |
228 | 231 | | |
229 | 232 | | |
230 | | - | |
231 | | - | |
| 233 | + | |
232 | 234 | | |
233 | 235 | | |
234 | 236 | | |
235 | 237 | | |
236 | 238 | | |
237 | 239 | | |
238 | 240 | | |
| 241 | + | |
| 242 | + | |
239 | 243 | | |
240 | 244 | | |
241 | 245 | | |
| |||
250 | 254 | | |
251 | 255 | | |
252 | 256 | | |
253 | | - | |
254 | | - | |
| 257 | + | |
255 | 258 | | |
256 | 259 | | |
257 | 260 | | |
258 | 261 | | |
259 | 262 | | |
260 | 263 | | |
| 264 | + | |
261 | 265 | | |
262 | | - | |
| 266 | + | |
| 267 | + | |
| 268 | + | |
| 269 | + | |
263 | 270 | | |
264 | 271 | | |
265 | 272 | | |
266 | | - | |
| 273 | + | |
267 | 274 | | |
268 | 275 | | |
269 | 276 | | |
270 | 277 | | |
271 | 278 | | |
272 | | - | |
| 279 | + | |
| 280 | + | |
273 | 281 | | |
274 | 282 | | |
275 | 283 | | |
| |||
342 | 350 | | |
343 | 351 | | |
344 | 352 | | |
| 353 | + | |
345 | 354 | | |
346 | | - | |
347 | | - | |
| 355 | + | |
| 356 | + | |
| 357 | + | |
| 358 | + | |
348 | 359 | | |
349 | 360 | | |
350 | 361 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
34 | | - | |
35 | | - | |
| 34 | + | |
36 | 35 | | |
37 | 36 | | |
38 | 37 | | |
39 | | - | |
| 38 | + | |
| 39 | + | |
40 | 40 | | |
41 | 41 | | |
42 | 42 | | |
43 | 43 | | |
44 | 44 | | |
45 | 45 | | |
46 | | - | |
47 | | - | |
| 46 | + | |
48 | 47 | | |
49 | 48 | | |
50 | 49 | | |
| |||
137 | 136 | | |
138 | 137 | | |
139 | 138 | | |
140 | | - | |
| 139 | + | |
141 | 140 | | |
142 | 141 | | |
143 | 142 | | |
144 | 143 | | |
145 | 144 | | |
146 | 145 | | |
147 | 146 | | |
148 | | - | |
| 147 | + | |
149 | 148 | | |
150 | 149 | | |
151 | 150 | | |
| |||
183 | 182 | | |
184 | 183 | | |
185 | 184 | | |
186 | | - | |
| 185 | + | |
187 | 186 | | |
188 | 187 | | |
189 | 188 | | |
| |||
256 | 255 | | |
257 | 256 | | |
258 | 257 | | |
| 258 | + | |
259 | 259 | | |
260 | | - | |
| 260 | + | |
| 261 | + | |
| 262 | + | |
261 | 263 | | |
262 | 264 | | |
263 | 265 | | |
264 | 266 | | |
265 | 267 | | |
266 | | - | |
| 268 | + | |
267 | 269 | | |
268 | 270 | | |
269 | 271 | | |
270 | 272 | | |
271 | | - | |
| 273 | + | |
272 | 274 | | |
273 | 275 | | |
274 | 276 | | |
| |||
290 | 292 | | |
291 | 293 | | |
292 | 294 | | |
293 | | - | |
294 | | - | |
| 295 | + | |
| 296 | + | |
295 | 297 | | |
296 | 298 | | |
297 | 299 | | |
| |||
309 | 311 | | |
310 | 312 | | |
311 | 313 | | |
| 314 | + | |
312 | 315 | | |
313 | | - | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
314 | 319 | | |
315 | 320 | | |
316 | 321 | | |
| |||
322 | 327 | | |
323 | 328 | | |
324 | 329 | | |
325 | | - | |
| 330 | + | |
326 | 331 | | |
327 | 332 | | |
328 | 333 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
143 | 143 | | |
144 | 144 | | |
145 | 145 | | |
146 | | - | |
| 146 | + | |
147 | 147 | | |
148 | 148 | | |
149 | 149 | | |
| 150 | + | |
150 | 151 | | |
| 152 | + | |
| 153 | + | |
151 | 154 | | |
152 | 155 | | |
153 | 156 | | |
| |||
254 | 257 | | |
255 | 258 | | |
256 | 259 | | |
| 260 | + | |
257 | 261 | | |
258 | | - | |
259 | | - | |
| 262 | + | |
| 263 | + | |
| 264 | + | |
260 | 265 | | |
261 | 266 | | |
262 | 267 | | |
| |||
277 | 282 | | |
278 | 283 | | |
279 | 284 | | |
280 | | - | |
| 285 | + | |
281 | 286 | | |
282 | 287 | | |
283 | 288 | | |
| |||
344 | 349 | | |
345 | 350 | | |
346 | 351 | | |
347 | | - | |
348 | | - | |
| 352 | + | |
349 | 353 | | |
350 | 354 | | |
351 | 355 | | |
352 | 356 | | |
353 | 357 | | |
354 | 358 | | |
355 | 359 | | |
| 360 | + | |
356 | 361 | | |
357 | | - | |
| 362 | + | |
| 363 | + | |
| 364 | + | |
358 | 365 | | |
359 | 366 | | |
360 | | - | |
| 367 | + | |
361 | 368 | | |
362 | 369 | | |
363 | 370 | | |
364 | 371 | | |
365 | | - | |
366 | | - | |
| 372 | + | |
367 | 373 | | |
368 | 374 | | |
369 | 375 | | |
| |||
0 commit comments