docs(generator): fix reference $ref links and opaque Object types#3126
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 102 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
xuyushun441-sys
force-pushed
the
docs/generator-fixes
branch
3 times, most recently
from
July 17, 2026 12:30
7987387 to
45d0653
Compare
os-zhuang
changed the title
xuyushun441-sys
force-pushed
the
docs/generator-fixes
branch
from
July 17, 2026 12:46
45d0653 to
b8d62dc
Compare
The 243 generated reference pages carried ~92 links to a page that never
existed (`[__schema0](./__schema0)`), 6 self-links to `(./#)`, and every
inline object rendered as an opaque `Object`. Root causes, all in
build-docs.ts:
- `formatType` turned `$ref` into `./<schemaName>`, but pages are named
after the *zod file* — so no `$ref` link could ever resolve. Named refs
now resolve through the schemaCategoryMap/schemaZodFileMap that
scanCategories() already built (dead code until now) to
`/docs/references/<category>/<file>#<schema>`, and fall back to plain
text rather than a 404 when no page exists.
- `__schemaN` refs are Zod-hoisted inline schemas with no page at all;
they are now expanded structurally, with a cycle guard (these schemas
are recursive — a node contains nodes — and naive inlining blows the
stack).
- `$ref: "#"` (self-reference) now links to the section's own anchor.
- Inline objects render their shape one level deep
(`{ label: string; value: string; color?: string; … }`) instead of
`Object`; const variants render their literal, so discriminated unions
read as `'a' | 'b'` rather than `Object | Object`.
- JSDoc `{@link ../automation/sync.zod.ts}` linked to a repo path that
404s on the site; source paths now rewrite to their docs route, and a
bare `@see` renders as "See also:" prose instead of a stray tag.
- Property type cells escape backslashes before pipes, matching the
neighbouring `desc` escaping (and its comment) — CodeQL's
js/incomplete-sanitization on the old order.
Counts after regenerating: __schemaN links 92 → 0, (./#) 6 → 0,
zod.ts links → 0. Passes the new `--check` gate from #3134.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
xuyushun441-sys
force-pushed
the
docs/generator-fixes
branch
from
July 17, 2026 13:03
b8d62dc to
0897ad5
Compare
This was referenced Jul 17, 2026
os-zhuang
added a commit
that referenced
this pull request
Jul 17, 2026
#3138 extracted the emit()/manageDir()/flush() sink to lib/generated-output.ts and moved build-skill-references + build-react-blocks-contract onto it, but left build-docs.ts carrying the inline original — #3126 was rewriting the same file and the migration would have conflicted. #3126 has landed, so collect the debt. Two copies of a check/write sink is the one duplication this design cannot afford: its whole claim is that --check and write are the same code, and that claim is per copy. A fix to one silently leaves the other behind, and the failure mode is a gate that passes on output a real run would not produce. Adds wasEmitted() to the shared sink. build-docs is the first caller whose later output depends on its earlier output — each category index links only the pages that got generated — and that question belongs to the sink, which already owns the emitted map. New export; the other two callers are unaffected. The empty-input guard moves to flush()'s guard hook, same meaning. Pure refactor, verified: byte-identical output across all 258 files; all five drift classes still fail (stale content, missing page, stale leftover, no-schema guard, in-sync green); both existing sink callers regress clean, including #3138's reverse test that a hand-written .md in skills/*/references/ keeps the gate green and survives a write. Net -58 lines. Co-Authored-By: Claude Opus 4.8 <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
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.
背景
文档审计发现 243 个自动生成的 reference 页有系统性缺陷:92 处指向不存在页面的
[__schema0](./__schema0)、6 处(./#)自链、大量Object | Object。根因全在packages/spec/scripts/build-docs.ts。根因与修复
$ref链接其实都是坏的(不只匿名的显眼):formatType把$ref转成./<schemaName>,但页面是按 zod 文件命名的(data/object.mdx),ref 指向的是 schema 名(Field)——两套命名空间从未打通。现在具名 ref 走scanCategories()早就建好、却从未被读取的schemaCategoryMap/schemaZodFileMap解析成站内路由;查不到页面则降级为纯文本而不是吐 404。__schemaN是 Zod 把复用的内联 schema 提升进$defs时合成的名字,根本没有对应页面 → 就地展开结构,并加环路保护(这些 schema 是递归的——节点含节点——朴素内联会爆栈,第一版就爆了)。$ref: "#"自引用 → 链到本节锚点。Object | Object:内联对象展开一层形状({ label: string; value: string; color?: string; … });const 变体渲染字面量,判别式联合读作'a' | 'b'。{@link ../automation/sync.zod.ts}链到仓库路径(站上 404)→ 重写为站内路由;裸@see渲染成 "See also:"。重新生成后:
__schemaN链接 92 → 0,(./#)6 → 0,zod.ts 坏链 → 0。附带:修好 lychee.toml(但不恢复触发)
查"为什么坏链能长期躺在 main 上"时发现:
check-links.yml的触发被注释掉了,而原因很可能是配置本身坏了 ——follow_redirects与 boolean 形式的include_fragments在 lychee ≥0.24 都不是合法键,accept要字符串数组。job 一启动就死。本 PR 修好配置使其可加载,但不恢复触发:试跑后发现还需要
root_dir/fallback_extensions才能解析根相对链接,且站内确有几处真 404 要先清。完整恢复路径与已发现的真坏链清单记录在 #3136。先修闸门再上锁,顺序反了就是每个 PR 都红——那正是它当初被关掉的原因。验证
pnpm --filter @objectstack/spec gen:docs✅ ·pnpm --filter @objectstack/docs build✅ (exit 0)。diff 含 186 个重新生成的 mdx(生成产物)。🤖 Generated with Claude Code