feat(spec): 补上 defineHook() 作者侧工厂,并修正 object.zod.ts 两处错误处方 (#4269) - #4273
Merged
Conversation
…#4269) Follows the defineDatasource template: input-shape config in, HookSchema.parse, resolved shape out. Exported from the package root and @objectstack/spec/data. Closes the convention-scan authoring path's zero-validation gap (the #4207 alias/guidance errors now fire at import, not bind) and converges both authoring paths on the z.output artifact shape. Also rewords the two UNKNOWN_KEY_GUIDANCE prescriptions (workflows/hooks) in object.zod.ts that referred authors to a defineHook() that did not exist — they now name a real function plus its import path — and switches the schema.mdx lifecycle-hook example to the factory with a factory-over-bare-literal note. Drift guard in hook.test.ts: factory output === HookSchema.parse output, defaults/CEL materialization, function-handler passthrough by reference, bind-time re-parse idempotence, authoring-time hard-fail with the schema's own guidance. Closes #4269 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/m
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…tory-zod-fix-007ec4
os-zhuang
added a commit
that referenced
this pull request
Jul 31, 2026
* docs(skills): hook examples author with defineHook(), not bare `: Hook` literals (#4274) #4273 shipped defineHook() and pointed docs + error prescriptions at it, but skills/objectstack-data — the first thing an AI author reads — still taught the bare-literal form in 18 places across SKILL.md, rules/hooks.md, rules/validation.md, and references/data-hooks.md. Mechanical rewrite: `const x: Hook = {…}` → `const x = defineHook({…})` (imports switched to the value import), plus the factory-over-bare-literal note in rules/hooks.md and references/data-hooks.md, phrased identically to the schema.mdx note from #4273. Every rewritten block was scanned for unknown top-level keys — HookSchema is strict, so a stray key inside a defineHook() example would teach a crash — none found; the os:check gate covers the tagged blocks (198 examples green). Closes #4274 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * chore: empty changeset — docs-only PR, releases nothing Same convention as #4279: the changeset gate wants an explicit statement of release intent, and skills/ ships in no npm package. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4269。从 #4001/#4207 延伸:hook 的约定扫描作者路径此前零运行时校验,且
object.zod.ts的错误处方引用了不存在的defineHook()—— 作者照处方 import 会再失败一次。改动
1.
defineHook()工厂(packages/spec/src/data/hook.zod.ts)照
defineDatasource模板(datasource.zod.ts:538):纯HookSchema.parse,Hook(z.input)进、ResolvedHook(z.output)出;包根与@objectstack/spec/data子路径均导出。v1 不含任何劝导逻辑 —— handler 弃用告警留在 binder(bindHooksToEngine的warnLegacyHandler选项),单处维护。2. 两处错误处方修正(
object.zod.tsUNKNOWN_KEY_GUIDANCE的workflows/hooks)"registered via `defineHook()`" → "wrapped in `defineHook()` from `@objectstack/spec/data`":随工厂落地处方成真;措辞复核把「registered」改准确(工厂做校验,注册靠扫描/defineStack),并补上 import 路径让 AI 作者零猜测照做。既有测试钉子(lifecycle hook / record_change / #1535)全部保留。
3. drift-guard 测试(
hook.test.ts,+5)enabled→ 「hook 没有开关键」)4. 文档一处注记(
content/docs/protocol/objectql/schema.mdx)Lifecycle Hooks 示例裸字面量 →
export default defineHook({...})+ 「工厂优先于裸字面量」注记(defineDatasource 同款规则);os:check片段对构建后 dist 类型检查通过。5. changeset(
@objectstack/specminor,新公共 API)+ api-surface 基线重生成(root 与 data 两个入口各 +defineHook)。有意的行为变化
parse-at-import:坏 hook 从「绑定期 skip + warning」变为作者期硬失败(#4001 姿态:静默失效制造虚假完成)。存量裸字面量不受影响,工厂是可选入口,迁移纯增量。
验证
pnpm build全仓绿check:api-surface/check:docs/check:skill-examples(198 例,含本次改的片段)/check:strictness-ledger/check:exported-any/check:authorable-surface全绿check:generated本地红是 main 既有问题(check:generatedfails on main:check:strictness-ledger(#4232) was never classified in its ledger #4265/check:generated 的双向对账从不在 CI 上执行——#4203 关闭次日即被 #4232 原样复现，main 的本地 wrapper 又红了 #4255:check:strictness-ledger未分类),与本 PR 无关后续(不扩大本 PR 范围)
skills/objectstack-data的 hook 示例仍教裸: Hook字面量(SKILL.md:399 等)—— 已另开 issue 跟进。🤖 Generated with Claude Code