docs(spec): ApiEndpointSchema.path 的 .describe() 换成 ADR-0121 carve-out 形状的示例 (#5310) - #6064
Merged
qq9340100 merged 3 commits intoAug 7, 2026
Merged
Conversation
…e-out 形状的示例 (#5310) 这段文案原本是 `URL Path (e.g. /api/v1/customers)`。ADR-0121 D1 把声明路径收紧为 `<运行前缀>/apps/<命名空间>/<子路径>`,publish 门 `namespaceGate` 对 carve-out 之外的 路径直接拒绝 —— 词表自己举的例子,publish 会当场拒。 #5271 让 `api` 成为注册元数据类型之后,这段 `.describe()` 成为 metadata-admin 端点表单 里 `path` 字段的说明文字,并进入生成的 JSON Schema,是作者(常为 AI 作者,ADR-0033) 照抄的第一手提示。 新文案给出 carve-out 形状、一个具体示例 `/api/v1/apps/crm/leads`,并说明命名空间段派生 自 `manifest.namespace`(ADR-0121 D2)。措辞复用 `endpoint-publish-gate.ts` 中 `namespaceGate` 的拒绝文案,未新发明判据。 只改文案:schema 结构、`/^\//` 正则、门逻辑一律未动。 新增断言把 `.describe()` 的文本读回来再喂给门:文案里的每个具体示例路径都必须在它自己 命名的命名空间下通过 `validateApiEndpointDeclarations`。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
`.describe()` 文案变化会落到生成的参考文档表格里。按 os-regen 纪律用 `check:generated` 判定失效面(仅 `content/docs/references/**` 一项),再用 `--fix` 只重生成被证实失效的那一项,随后补跑 `gen:openapi`(#5371,无门)。 未手改任何生成物。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
size/m
documentation
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
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
2 participants
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.
Fixes #5310
前提复核(先证再改)
在
origin/main(efedd28)上逐条核对,问题描述的两个事实都成立:packages/spec/src/api/endpoint.zod.ts:59仍然一字未改:path: z.string().regex(/^\//).describe('URL Path (e.g. /api/v1/customers)')packages/spec/src/api/endpoint-publish-gate.ts:87的appEndpointMountPrefix(namespace)返回`${DEFAULT_RUNTIME_PREFIX}/${APP_ENDPOINT_SEGMENT}/${namespace}/`,即/api/v1/apps/[namespace]/。/api/v1/customers不以该挂载前缀开头,namespaceGate走的是拒绝分支 —— 词表自己举的例子,publish 会当场拒。为什么现在才要紧
#5271 之前
api没有注册 schema,/meta/types不为它出 JSON Schema,Studio 只能给一个 raw-JSON 文本框,这段.describe()没有渲染面。#5271 之后它成为 metadata-admin 端点表单里path字段的说明文字,并进入生成的 JSON Schema —— 于是一段会被拒绝的示例,变成了作者(按 ADR-0033,常常是 AI 作者)照抄的第一手提示。改了什么
ApiEndpointSchema.path的.describe()换成 carve-out 形状:/api/v1/apps/[manifest.namespace]/[subpath],并点明子路径必须非空(ADR-0121 D1);/api/v1/apps/crm/leads,并说明它对应manifest.namespace为crm的栈;manifest.namespace(ADR-0121 D2),不是作者的自由字段;措辞直接复用
endpoint-publish-gate.ts里namespaceGate的拒绝文案(must be ... with a non-empty subpath、Only the subpath is yours to name、would parse today and match NOTHING at runtime),没有新发明判据 —— 作者在表单里读到的规则,和被拒时读到的规则,是同一条。只动文案。 schema 结构、
/^\//正则、门逻辑一律未动,endpoint-publish-gate.ts一个字节没改。path仍然只是一个以斜杠开头的字符串,carve-out 仍然只由 publish 门(和运行期匹配器)判定,所以这不是破坏性变更:今天能发布的声明明天照样能发布。ApiMappingSchema的.describe()— 逐条复核结果问题里点名要一并复核,复核完的处置是三条都保持原样,理由逐条不同:
sourcetargettransformmappingGate整键拒绝。但它不是「举例失实」,而是「冻结词表里的被拒键,该不该在表单里自陈」——另一类问题,且这段文案被packages/runtime/src/api-mapping.ts的词表小节逐字引用为规范来源(改它要连带动packages/runtime)。按 Prime Directive #10 另行归档,不在本 PR 修inputMapping/outputMapping的两条(Map Request Body to Internal Params / Map Internal Result to Response Body)与运行期实现一致,也不改。测试
新增的断言不复述文案,而是把
.describe()的文本从 schema 里读回来再喂给门 —— 这样断言不可能和作者真正看到的字符串漂移:三条:
/api/v1/apps/[namespace]/[subpath]形状,并在它自己命名的那个命名空间下通过validateApiEndpointDeclarations(carve-out 由 D2 派生,示例只有配上能声明它的 manifest 才算诚实);/api/v1/customers仍然被拒 —— 把缺陷本身钉住。反向验证(方向在跑之前就先定好:红)
预测:把旧文案换回去,新断言应当因为「示例不是 carve-out 形状」而失败。实测正是这个方向、这个原因:
恢复改动后:
既有的 5 条拒绝例(carve-out 外、别人的命名空间、空子路径、
showcasex近似前缀、无manifest.namespace)全部保留且仍然拒。全量
生成物
按 os-regen 纪律,不手改、不整包扫射:
check:generated先判定失效面,只有content/docs/references/**一项失效,--fix只重生成这一项,随后补跑gen:openapi(#5371,该生成器无门)。复跑后✓ All 10 generated artifacts are up to date.问题描述里预计会动
authorable-surface.json/json-schema.manifest.json,实测没有动:前者不收录.describe()文本,后者只是 schema 名字的棘轮清单。实际落点只有content/docs/references/api/endpoint.mdx一行表格。变更集
.changeset/endpoint-path-describe-carveout.md,@objectstack/spec: patch——.describe()是发布面文案(进 JSON Schema、进参考文档、进 Studio 表单),不是代码注释。Generated by Claude Code