Skip to content

Commit bda38ab

Browse files
docs(skills): type-check more objectstack-formula examples with os:check (#31746)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} --> _Requested by **Steedos** · [project thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9Ubb9N2bXVZjKY6oCBfL3iTddq)_ Refs #31112 (slice 4 of a per-skill split: item 4, objectstack-formula; the card stays open) Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:objectstack-formula 技能包的 SKILL.md 又有 5 段 TypeScript 示例接入了示例编译检查(9 段中由 1 段变为 6 段),涉及文本公式、除数保护、动态种子值和两段 `previous` 状态转换条件;没有发现写错的示例。 - 为什么改:AI 编写公式、条件和种子值时最先照抄这些示例;接入检查后,规范一旦改名或收紧,示例会在 CI 里立刻变红,而不是悄悄教错。 - 风险与回滚:只改发布技能包的文档文字,不动任何运行时代码;token 上限未抬高(5956 → 5973 / 5997),新增字节靠同文件删减三处重复说明支付(每处删减的规则都在同文件另有出处)。回滚即 revert 本 PR。 - 先看:`skills/objectstack-formula/SKILL.md` 的「Mandatory patterns for AI emission」一节(5 处新标记与新增的 import 行)。 - 两分钟验证:`pnpm --filter @objectstack/spec check:skill-examples`,预期最后一行为 337 段示例全部通过类型检查。 - 需要你做的:作为受管面审批人审阅并批准本 PR(skills/** 属 Tier H)。 ## What changes `skills/objectstack-formula` had 1 of its 9 fenced `ts` blocks under `check:skill-examples` (measured on `main` 4013e30; every block sits in `SKILL.md`; `references/_index.md` is generator-owned and holds none; `evals/` excluded). It now has 6. Each new mark is the os:check marker on the line above the fence plus one import line; the seed block also gains `const seed = ` and `;` on its existing line. | File | marked before → after / blocks | tokens before → after / ceiling | lines before → after | |:--|:--|:--|:--| | `SKILL.md` | 1 → 6 / 9 | 5956 → 5973 / 5997 | 487 → 494 | Skills bundle reading: the sum of every published `SKILL.md` moves by +7 lines (this file only). - §1 coalesced text formula and §2 guarded divisor: `import { F } from '@objectstack/spec';`. - §4 dynamic seed values: `import { cel } from '@objectstack/spec';` and `const seed = { … };` (a bare `{ a: x, b: y }` statement is a block with labels and does not parse). - §5 `previous`/`record` transition and the bulk-write transition predicate: `import { P } from '@objectstack/spec';`. - Unmarked: the three ❌ blocks (string concatenation on nullable operands, Salesforce-flavor strings, `new Date()` seeds). They are wrong on purpose, and the file now says so once, under the section heading. ## Why #31112 item 4 (ruling B of #22059): published examples are guarded by the opt-in type check. This slice brings objectstack-formula's self-contained examples under it. ### Example fixes None. Every marked block compiled as written once its import was added. ### Trims that paid the marks (each cut and where its rule survives) - Intro: "This skill is the canonical reference for AI authors emitting formula / condition / predicate / dynamic-seed metadata." cut; the frontmatter `description` says what the skill covers and who loads it. - §5: "ISCHANGED-style logic does not exist as a function; use explicit `previous` comparison." cut; survives in the Mechanical translation table row `ISCHANGED(x)` → `previous.x != record.x` and in §5's own "Comparing against `previous` is the only way to say 'just became'". - §3: "For field-level conditional rules, emit the canonical field properties: `visibleWhen`, `readonlyWhen`, and `requiredWhen`." folded into "Never emit `conditionalRequired` (use `requiredWhen`) — …"; the three keys survive in the Surfaces table's `Field` row and the frontmatter `description`. ## Tests <details><summary>check:skill-examples, before and after, and the reverse check</summary> - Before (`main` 4013e30): `✅ 332 prose examples type-check across 3 surface(s)`. - After (commit b484a20; head b372dba adds only a merge of `main` touching no `skills/**` or `packages/spec` path): `pnpm --filter @objectstack/spec check:skill-examples` exited 0 with `✅ 337 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them`. - Reverse check, after the commit: planted a wrong import (`import { F, Field }`, `SKILL.md:240`) and an unknown member on the seed's `cel` envelope (`.bogusKey`, `SKILL.md:296`). The checker exited 1 with TS2305 and TS2339 at exactly those lines. Restored with `git checkout HEAD --`; `git status --porcelain` was empty after. </details> <details><summary>Derived gate sweep (commit b484a20)</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 46 commands. 45 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: 46 derived, 45 run, 1 NOT-MEASURED, 0 unrun. Re-run on the merged head b372dba: `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. - No ceiling was raised or lowered; the ratchet printed no lowering instruction (headroom 24 left). - 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 337 examples green; `node scripts/check-skills-token-ratchet.mjs` exits 0. ## Human Minimum A governed approver reviews and approves (Tier H). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01QsR2jR79xaiCrky8EZ18Up Co-authored-by: Claude <noreply@anthropic.com>
1 parent 6dfc7fa commit bda38ab

2 files changed

Lines changed: 26 additions & 9 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): more of objectstack-formula's self-contained examples are type-checked by `check:skill-examples`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Five more fenced TypeScript blocks in `skills/objectstack-formula/SKILL.md` carry the opt-in check marker, so 6 of its 9 are now compiled against the spec: the coalesced text formula and the guarded divisor gain `import { F }`, the dynamic seed values gain `import { cel }` and a `const`, and both `previous`-transition predicates gain `import { P }`, all from `@objectstack/spec`. No example was wrong. The three ❌ blocks stay unmarked on purpose, and the file now says so once. The marks are paid inside the file by removing restatements: the intro's "canonical reference" sentence (the frontmatter description says it), the ISCHANGED sentence (the translation table's `ISCHANGED(x)` row says it), and the list of field rule keys before `conditionalRequired` (the Surfaces table's `Field` row lists them). No rule's teaching changes.

‎skills/objectstack-formula/SKILL.md‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,7 @@ metadata:
2222

2323
ObjectStack has **one** expression language across every domain that needs
2424
computation or boolean predicates: **CEL** (Google Common Expression
25-
Language). This skill is the canonical reference for AI authors emitting
26-
formula / condition / predicate / dynamic-seed metadata.
25+
Language).
2726

2827
> **Predicates / formulas are bare CEL — never wrap field references in `{…}`
2928
> braces.** The #1 authoring mistake is a condition like
@@ -230,11 +229,15 @@ If you need a helper that doesn't exist, prefer adding it to the stdlib
230229

231230
## Mandatory patterns for AI emission
232231

232+
The ❌ blocks are wrong on purpose, so `check:skill-examples` skips them.
233+
233234
### 1. Computed text formula — always coalesce nullable operands
234235

235236
✅ **Correct**
236237

238+
<!-- os:check -->
237239
```ts
240+
import { F } from '@objectstack/spec';
238241
F`coalesce(record.salutation, '') + ' '
239242
+ coalesce(record.first_name, '') + ' '
240243
+ coalesce(record.last_name, '')`
@@ -250,7 +253,9 @@ F`record.salutation + ' ' + record.first_name + ' ' + record.last_name`
250253

251254
✅
252255

256+
<!-- os:check -->
253257
```ts
258+
import { F } from '@objectstack/spec';
254259
F`coalesce(record.cost, 0) > 0
255260
? ((coalesce(record.revenue, 0) - record.cost) * 100) / record.cost
256261
: 0.0`
@@ -269,9 +274,8 @@ P`record.amount != null && record.amount > 10000 && record.region in ['us', 'eu'
269274
P`!isBlank(record.po_number)`;
270275
```
271276

272-
For field-level conditional rules, emit the canonical field properties:
273-
`visibleWhen`, `readonlyWhen`, and `requiredWhen`. Never emit
274-
`conditionalRequired` — it was REMOVED in protocol 17 and is a parse error.
277+
Never emit `conditionalRequired` (use `requiredWhen`) — it was REMOVED in
278+
protocol 17 and is a parse error.
275279

276280
❌ Salesforce-flavor — **fails CEL compile**: `os build` errors with a
277281
located message, and the flow engine throws if it ever reaches runtime:
@@ -286,8 +290,10 @@ located message, and the flow engine throws if it ever reaches runtime:
286290

287291
✅
288292

293+
<!-- os:check -->
289294
```ts
290-
{ close_date: cel`daysFromNow(45)`, created_at: cel`now()` }
295+
import { cel } from '@objectstack/spec';
296+
const seed = { close_date: cel`daysFromNow(45)`, created_at: cel`now()` };
291297
```
292298

293299
❌ Compile-time evaluation — every customer gets the package author's clock:
@@ -306,13 +312,12 @@ so they are safe inside one.
306312

307313
✅
308314

315+
<!-- os:check -->
309316
```ts
317+
import { P } from '@objectstack/spec';
310318
P`previous.status != 'escalated' && record.status == 'escalated'`
311319
```
312320

313-
ISCHANGED-style logic does not exist as a function; use explicit `previous`
314-
comparison.
315-
316321
`record` is the record's **state**, not this write's diff: stored row ⊕
317322
payload, so `record.status == 'escalated'` is true on *every* update of an
318323
already-escalated record. Comparing against `previous` is the only way to say
@@ -342,7 +347,9 @@ the condition is evaluated before any handler runs).
342347
Write it once, on a `before*` or an `after*` event, and it means the same thing
343348
whether the write carries an id or a predicate:
344349

350+
<!-- os:check -->
345351
```ts
352+
import { P } from '@objectstack/spec';
346353
// Fires once per row that ACTUALLY transitioned — on `update(id)` and on
347354
// `update({multi: true})` alike.
348355
P`previous.status != 'done' && record.status == 'done'`

0 commit comments

Comments
 (0)