You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 32907ae
Browse filesBrowse the repository at this point in the historyBrowse files
fix(spec): check:variant-docs reads a z.enum discriminator arm's members into the union key (#29531)
<!-- claude-projects-attribution: {"github_login":"os-warren"} -->
_Requested by **Warren** · [project
thread](https://claude.ai/code/project/chan_01U5RdnAAmkSQmZbqh6FtqZ8?thread=cmsg_01U5RdnAAmkSQmZbqh6FtqZ898KToLEMsyis22XxZA8ZTu)_Fixes#29412
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:`check:variant-docs` 现在把 `z.enum` 判别臂的全部成员读进联合的台账键;唯一受影响的条目从
`kind:nav` 改键为 `kind:field|flow|nav`,并在 `api/metadata-api.mdx` 补一句点名
`field` / `flow` 两个 kind。
- 为什么改:旧的遍历只读字面量臂,枚举臂整个不进键,枚举增删成员时键不动,门禁就不会把作者送回文档。
- 风险与回滚:只动门禁脚本、它的台账和一句文档,不发布任何包;回滚即 revert 本 PR。
- 先看:`packages/spec/scripts/check-variant-docs.mts` 的 `armVariants()`;再看
`packages/spec/scripts/check-variant-docs.test.ts`;最后
`packages/spec/variant-docs.json` 的改键。
- 两分钟验证:`pnpm --filter @objectstack/spec check:variant-docs`,预期打印 24
个联合全部通过;`--list` 里 contributions 的键是 `kind:field|flow|nav`。
- 需要你做的:无,席位落地。
## What changes
- `packages/spec/scripts/check-variant-docs.mts`: a new exported
`armVariants()` reads the values one arm's discriminator matches. A
literal keeps them in the def's `values`; a zod 4 `z.enum` keeps its
members in `entries`, and the walker never read that field, so an enum
arm was left out of the key entirely. `armVariants()` now reads zod's
own parse set (`_zod.values`, which drops a numeric TypeScript enum's
reverse-mapping keys) and falls back to the entries' values. The
per-union key building moved into an exported `unionKey()`. The sweep
moved into `main()` and runs only when the file is invoked as a script,
so the test can import the two helpers without sweeping `src/` or
setting `OS_EAGER_SCHEMAS` in its worker.
- `packages/spec/variant-docs.json`: re-keyed the one entry this moves,
`kind:nav` to `kind:field|flow|nav`
(GetPackageCustomizationsResponseSchema `contributions`). Its note is
kept, with the sentence saying the walker cannot read the enum arm
replaced by one saying it now does.
- `content/docs/api/metadata-api.mdx` (bounded in-place fix, file
surface amended in Claim amendment 6582783172): once re-keyed, the gate
found that the bound doc never mentions `field`, and that `flow` passed
only through an unrelated row (the `type` column at line 33). That is
the doc owing a re-read, which this change is what surfaces. One
sentence now names the kinds: "the fields (kind `field`) and flows (kind
`flow`) other installed packages contribute to `hotcrm`'s objects".
- `packages/spec/scripts/check-variant-docs.test.ts` (new): pins a
fixture union with one enum arm and one literal arm, keyed on all three
members; adding a member to the enum arm moves the key; a literal-only
control keys as before; non-discriminated schemas answer null; an
object-built enum reads its values, not its keys.
## Why
A discriminated union's ledger key exists so that adding or dropping a
variant changes the key and sends the author back to the bound doc. An
enum arm's members were never in the key, so a `page` kind added to the
`field` / `flow` enum would have left the key at `kind:nav` and the gate
green.
## Tests
- `check:variant-docs --list` on `origin/main` 94d3e25 vs this head: 24
discriminated unions both times; exactly one key differs (`kind:nav`
became `kind:field|flow|nav`). Measured, not assumed: no other union in
`src/` has an enum arm.
- New `scripts/check-variant-docs.test.ts`: 7/7 pass.
- `pnpm --filter @objectstack/spec test` (local project) at 314f4b3:
Test Files 793 passed (793), Tests 23526 passed, 1 todo.
- `pnpm --filter @objectstack/spec typecheck` at 314f4b3 (tsc,
`check:scripts-typecheck`, `check:test-typecheck`): exit 0.
- No ablation: the diff changes a gate script, which os-dev does not
ablate. The before/after `--list` reading above is the evidence that the
reading changed.
## Acceptance notes
- No changeset, `skip-changeset`: `@objectstack/spec`'s `files[]` ships
`dist`, `json-schema`, `src/**/*.zod.ts` and others, not `scripts/` or
`variant-docs.json`; `content/docs/` is no package.
- No `packages/spec/src/**/*.zod.ts` file and no strictness-ledger file
is touched.
- The match for a variant in a doc stays as loose as before; the gate
still proves only that the page says the word.
## Verification
<details><summary>dispatch-gates at 314f4b3: 86 derived, 86 run, all
exit 0</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 86 families. 76 exited 0 on the
first run; 10 exited 3 (PREREQUISITE NOT MET) on the fresh worktree, the
one `check:docs` exit 1 being the missing `json-schema` tree, a
prerequisite and not a finding. After `git fetch origin 621a487` and
`turbo run build --filter='@objectstack/lint...'
--filter=@objectstack/objectql --filter=@objectstack/formula
--filter='@objectstack/client-react...' --filter=@objectstack/spec`, all
ten re-ran to exit 0, `check:variant-docs` among them on the first run.
Reconciliation: "dispatch-gates --ran: 86 derived famil(ies) accounted
for — 86 run, 0 NOT-MEASURED".
</details>
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes (eslint on the two changed
scripts files: exit 0; the repo-wide run is CI's).
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset (nothing publishes
here).
- [x] 6. `packages/spec` touched: no generated artifact moves
(`check:docs` green).
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
Dispatched by `domain:spec#3 · os-warren ·
session_01JQwxbahe4v7GBD94QeSnir`; dev = card thread
`session_01JQwxbZYuv4NM4LDCUNP3cK`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01JQwxbZYuv4NM4LDCUNP3cK
---
_Generated by [Claude
Code](https://claude.ai/code/session_01JQwxbZYuv4NM4LDCUNP3cK)_
Co-authored-by: Claude <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: packages/spec/variant-docs.json
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -196,12 +196,12 @@
196
196
"reason": "Wire response of GET /auth/me/permissions (#28508): the server answers the anonymous or the authenticated body from the session, and nobody writes either into metadata. content/docs/references/api/auth.mdx is generated from MePermissionsResponseSchema."
"note": "The per-kind entry of GET /packages/:id/customizations `contributions` (#27928, ruling 6566915346 letter E). Not authored (the server answers it), but GOVERNED rather than exempt, as the flow registration verdict is: Studio draws each kind differently, and api/metadata-api.mdx names the list and its `nav` kind. The key holds only `nav` because the `field` / `flow` arm discriminates by a `z.enum`, which this walker does not read as variants."
204
+
"note": "The per-kind entry of GET /packages/:id/customizations `contributions` (#27928, ruling 6566915346 letter E). Not authored (the server answers it), but GOVERNED rather than exempt, as the flow registration verdict is: Studio draws each kind differently, and api/metadata-api.mdx names the list and its `nav` kind. The `field` / `flow` arm discriminates by a `z.enum`; the walker reads its members into the key, so adding or dropping a kind there moves the key and sends the author back to that doc."
0 commit comments