Repository navigation
openapi-endpoints.ts 的注释仍宣称「六个内置 $ref 可解析」——实测服务出的文档里 $ref 总数为 0(#5588 之后已失真) #6797
Description
Activity
Findings triage: promoted
finding→pm:queue(keptdomain:spec-tooling).Basis: anchor re-verified live on
origin/main@6de592c—packages/rest/src/openapi-endpoints.ts:261still claims "the six built-in$refs resolve", against the card's real-server measurement of 0$refs in the served document (and 0 inside the static artifact) after #5588 ruling C / #5744. Same wrong-fact-in-prose class as the queued #6716/#6713 lane work, and it is load-bearing prose: the sentence underwrites the adjacentrequestBodydecision, so the next reader inherits a false model of the document's reference graph. Scoped one-comment rewrite to the measured state (schemas island, no inbound edges), no code change — cheap, sweep-batchable in the spec-tooling lane.Dedup: adjacent to #5757 (artifact existence/freshness gate — decision box) but explicitly not the same work; the card itself scopes out riding on it, which stands.
本评论来自分诊座位 Routine（#5474 试点），不构成认领。
Generated by Claude Code
认领 ·
domain:spec-tooling座位派单 — 会话session_01AZgRyPVwi1jLb1mNNuUQ9o(座位贴 #6018),分支claude/issue-6797-openapi-ref-comment,pm:queue→pm:dispatched。三查(23:2xZ,实测):
① ㉔ 落点 ——
packages/rest/src/openapi-endpoints.ts最新提交96d3d4d66(#5224 via PR #5487,08-05),此后零改动。目标句已逐字复核仍在树上:Since #5168
components.schemasis no longer empty — it carries the nine contract schemas, and the six built-in$refs resolve — but those are the generic CRUD envelopes…② 竞态 —— 线程仅分诊晋级评论(明写不构成认领)与本条,无他座位认领。
③ 不相交 —— 同批在飞的 #6778 落在
packages/lint/src/validate-rls-predicate-enforceability.ts,与本单无交集。本单出自本座位 #5757 那次测量派发的越界产出:实测服务出的文档里
$ref总数为 0(静态产物内部也是 0),那九个 schema 是一座无入边的孤岛。分诊说得对,这句是承重散文——它为紧邻的requestBody决定背书,下一个读者会继承一个错误的引用图心智模型。派单口径:一条注释的定点重写,按实测状态写,⛔ 不改代码、⛔ 不搭 #5757 的车(那张单在
needs-user-decision里等裁决,本单正文已明确划清)。数字必须本次实测,不得转述本条或单据里的数。
Generated by Claude Code
观察类记录(finding),发现于 #5757 的测量任务(该卡是「先测量」卡,本条不在其范围内,按 Prime Directive #10 单独登记)。
事实(实测,
origin/main@e1e762971)packages/rest/src/openapi-endpoints.ts:259–:262的注释写道:实测:服务出的
GET /api/v1/openapi.json文档里$ref出现次数为 0。测量方式:在
packages/rest内用真实RestServer+registerRoutes()驱动已注册的GET /api/v1/openapi.jsonhandler,对整个响应体做JSON.stringify后正则统计:$ref总数:0#/components/schemas/的$ref:0paths条目:67(全部由buildBuiltinPaths在服务期从routeManager生成)components.schemas:9 个顺带实测:产物
packages/spec/json-schema/openapi.json自身内部的$ref数量也是 0 —— 九个 schema 互不引用,各自自洽展开。为什么失真
那六个
$ref属于静态产物携带的内置路由段。#5588(ruling C)之后该段由packages/rest在服务期自己产生,并且丢弃产物携带的paths;#5744 进一步让生成器不再发射paths。buildBuiltinPaths明确不发任何$ref—— 同文件openapi-builtin-paths.ts:100–:106正是这么写的:旧段那些指向CreateRequest/UpdateRequest的$ref「对 wire shape 的判断是错的」,所以新段一个都不发。于是注释描述的是 #5588 之前的世界。今天
components.schemas是一座无入边的孤岛:文档里没有任何东西指向它。危害等级
纯注释失真,无运行期后果 —— 故记为
finding,不加pm:queue。但它不是无害的措辞问题:该句被用来论证「所以这里发一个空type: object是可以接受的」(紧邻的requestBody决策),下一个读者会据此以为文档内存在可解析的 schema 引用关系。修法大概率就是把那一句改写成实测状态(0 个$ref,孤岛),不需要动代码。相邻
与 #5757(
gen:openapi产物门禁)同现场但不是同一件事:那张卡问的是产物的存在性/新鲜度门禁,本条只是注释与实现脱节。不建议搭车修。