docs(spec): give six zod modules a true module-header doc block (#6145) - #6447
Merged
os-project-manager merged 2 commits intoAug 7, 2026
Merged
Conversation
The six modules already carried a genuine module introduction, written glued to the module's first declaration. Under #5059's strict selection rule that block is the SYMBOL's TSDoc — its hover text — so the pages stopped opening with it and printed nothing instead. The prose was never the problem; its attachment was. Each block is promoted VERBATIM to a top-level header that documents no symbol (column 0, header region, followed by the imports rather than by a declaration) — the shape 74 of the 183 sources with a module header already use. `content/docs/references/**` is regenerated through the standard `check:generated --fix` flow: exactly the six listed pages change, 110 insertions and 0 deletions, every other page byte-identical. Fixes #6145 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ffcE95NaMJcL9XJ9VDYgk
|
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
documentation
os-project-manager
marked this pull request as ready for review
August 7, 2026 20:43
os-project-manager
deleted the
claude/issue-6145-module-header-doc-blocks
branch
August 7, 2026 20:58
This was referenced Aug 7, 2026
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 #6145
Background
#5059 / PR #6134 narrowed
getFileDescription()to accept only a module-level doc block that belongs to no symbol (column 0, in the header zone, and not adjacent to a declaration — i.e. TSDoc's own attachment rule read back). The strictness of that rule is its entire value: six reference pages that had been opening with an internal comment were cured by it.The side effect is six other modules whose opening prose genuinely reads as a module introduction but was written glued to the first declaration. Under the new rule that block belongs to the symbol (it is still its hover text), so the pages stopped showing it and now print nothing. The prose was never the problem; its attachment was.
What this PR does
It gives each of those six modules a true module-header block — the existing introduction is promoted verbatim, byte for byte, to a top-level doc block that documents no symbol (column 0, header zone, followed by the imports rather than by a declaration). That is exactly the shape 74 of the 183 sources that carry a module header already use (
api/errors.zod.ts,ai/mcp.zod.ts,cloud/package.zod.ts, …). No new shape was invented, and not one word of new prose was written.data/driver/postgres.zod.tsconst POSTGRES_CONFIG_KEYSdata/driver/mysql.zod.tsconst MYSQL_CONFIG_KEYSdata/driver/sqlite.zod.tsconst SQLITE_CONFIG_KEYScloud/template-manifest.zod.tsexport const TemplateManifestSchemasystem/doc.zod.tsexport const DocSchemaapi/error-code-ledger.zod.tsexport const ERROR_CODE_LEDGER⛔ The lenient fallback the PM explicitly ruled out on the card — 「不得改回「若 doc block 附着于第一个导出的 schema 就照发」这类宽容回退」 — was not adopted.
scripts/build-docs.ts,scripts/lib/file-description.tsand every generator / gate mechanism are untouched, not one byte."Verbatim move" is proved, not asserted
For each file, the multiset of non-blank lines is byte-identical to
origin/main— i.e. textually these six edits are a pure reordering, with no line added or removed:This matters most for
api/error-code-ledger.zod.ts: the "Retiring a code" section PR #6389 added to it earlier today moved up inside the same block, entirely undisturbed.Premise verification (rule 6)
Measured per file against the same-day latest
origin/mainwith the realfindModuleDocBlock(), rather than taken from the card:All six pages did in fact open straight into the
Callout Sourceblock with no introduction. The premise holds in full; none of it had expired. After the change the same probe returns each module's own header for all six.Regenerated reference pages
Produced through the standard
check:generated --fixflow; the output is committed unedited. The blast radius is exactly the six pages the card listed, not one more:110 insertions, 0 deletions — the other 178 pages are preserved byte for byte, and #6134's selection result is untouched everywhere.
Reverse verification (direction predicted before it was run)
Prediction: re-gluing any module header back onto its declaration should turn the new pin test red, and the failure should say that file's opening went back to
null. Revertingsystem/doc.zod.tstoorigin/main:The direction matched the prediction. Restored, 39/39 green again.
That pin deliberately asserts on the six source files and not on the emitted
.mdx:check:docscompares artifact against source, so a re-glued module header would quietly empty the page while the gate stayed green — which is exactly how the original six victim pages survived two rounds onmain.Verification
.github/workflows/lint.yml(not from memory): 30 gates in the ESLint job plus 24 in the TypeScript Type Check job, all green (the 30 ESLint-job gates were re-run after mergingorigin/mainand were still all green).check:authorable-surfacegreen withauthorable-surface.base.jsonunchanged — no authorable key moved, and not one byte of the acceptance surface changed.pnpm --filter @objectstack/spec test: 339 files / 8640 tests passed.pnpm --filter @objectstack/rest test: 64 files / 881 tests passed (the main consumer of the error-code ledger).pnpm --filter @objectstack/spec exec tsc --noEmitgreen;turbo run build70/70 andturbo run typecheck120/120 successful.node scripts/check-nul-bytes.mjsgreen, plus a self-scan beyond the gate's surface over all 14 files this PR touches — no hits.The same-day latest
origin/main(including PR #6279's bare-name flip) is merged in: no conflicts, and after the merge all 10check:generatedartifacts are green with a clean working tree.check:api-surfacedid briefly report "44 breaking" after the merge — that is the stale-disttrap documented in AGENTS.md §9 (the dist was still the pre-merge 19:40 build); it went green on a rebuild and is unrelated to this PR.Refs: #5059 · PR #6134 · PR #6389