♻️ Consume @deno/doc v2 natively + fix source-link off-by-one#1208
Closed
taras wants to merge 4 commits into
Closed
♻️ Consume @deno/doc v2 natively + fix source-link off-by-one#1208taras wants to merge 4 commits into
taras wants to merge 4 commits into
Conversation
…odel Bumps `@deno/doc` 0.188.0 -> 0.199.0 and `@deno/graph` 0.89.0 -> 0.100.1, and aligns the www CI job to Deno v2.9.1 (the only workflow still on 2.6.1; matches #1202). `@deno/doc` >= 0.195.0 replaced the flat v1 `DocNode[]` model with a v2 `Document`/`Symbol`/`Declaration` model, so the docs-rendering pipeline is migrated accordingly: - `doc()` now returns `Record<url, Document>`; `Document.symbols` group declarations by name. `DocNode` is redefined locally as `Declaration & { name }` in `use-deno-doc.tsx`, and `useDocPages` iterates `document.symbols` instead of `Object.groupBy`. - `.def` replaces the per-kind def fields (`functionDef`/`classDef`/…); `ClassMethodDef.def`; every `TsType*Def` payload is renamed to `.value`; `NamespaceDef.elements` is now `Symbol[]`. - `kind === "import"` checks dropped ("import" is no longer a `DocNodeKind`). - `blog-image-route.ts`: cast for the newer `Uint8Array` lib type. Note: `@deno/doc` 0.200.0-0.202.0 ship broken wasm bindings that fail to instantiate under Deno (`__wbindgen_placeholder__`), so 0.199.0 is the newest usable v2 release.
commit: |
Surface symbols exported from the package's `./experimental` entrypoint in the API Reference section: - `/api` index lists a stable release's experimental symbols inline with an "experimental" badge (none for 4.0.3 today; appears when a stable release exports `./experimental`). The prerelease's experimental APIs are reached via the "next" toggle / its symbol pages. - Experimental symbol pages live at `/api/:series/experimental/:symbol` with an "Experimental" banner; the sidebar lists stable + experimental symbols with badges, resolving each link to the correct (flat vs namespaced) URL. - Version toggle gains a "next" entry for the prerelease when it's newer than its stable parent and documents the current symbol; the active entry is derived from the page's own series. The "experimental" signal is entrypoint membership (`DocPage.experimental`, set in `package.ts`). Stable pages, older series, and search are unaffected.
Removes the `DocNode = Declaration & { name }` compatibility adapter and the
`{ ...declaration, name }` re-attachment introduced during the v2 upgrade. The
renderer now consumes v2's model directly: a `DocPageSection` holds a raw
`Declaration`, and the render helpers receive the owning symbol's identity via
`type SymbolInfo = Omit<Symbol, "declarations">` — sourced from the real
`Symbol` at build time and from `{ name: page.name }` at render time.
- `extract(declaration, symbol)`, `Type({ declaration, symbol })`,
`exportHash(declaration, symbol, i)`; `DocPageSection.node` → `declaration`.
- Namespace members recurse over `NamespaceDef.elements` (real member Symbols)
instead of synthesizing flat nodes.
- `DocPage.name` is kept (many call sites read it); `SymbolInfo` flows only
through the render helpers.
- Both docs paths updated (`package.ts` and the `/x` `package/node.ts`).
No rendered-output change (verified: API pages, experimental pages, and `/x`
contrib pages render identically).
taras
force-pushed
the
tm/1200-experimental-badge
branch
from
6c10c4a to
14ed918
Compare
taras
force-pushed
the
tm/deno-doc-native-v2
branch
from
fc7cfe5 to
d028e36
Compare
taras
force-pushed
the
tm/1200-experimental-badge
branch
from
14ed918 to
42b8fb1
Compare
Member
Author
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.
Motivation
Third in a stack — on top of #1205 (which is on #1204). Review/merge those first.
The
@deno/docupgrade (#1204) kept the old flat-node shape alive with a compatibility adapter —type DocNode = Declaration & { name }plus a per-declaration name re-attachment — so the renderer never actually spoke v2'sSymbol/Declarationmodel. This PR removes that shim and consumes v2 natively.It also fixes a latent bug the upgrade introduced:
@deno/docv2 (≥0.195.0) changedLocation.linefrom 1-indexed to 0-indexed (deno_doc #150/#777), but the "View code" links feed it straight into GitHub's 1-indexed#L<n>anchor — so every source link pointed one line above the symbol's declaration.Approach
Two commits.
🐛 Fix off-by-one in "View code" source links — add
+ 1where the GitHub#Lanchor is built, inpackage.tsandpackage/node.ts. Verified:runis declared on source line 32 and the link now points to#L32(was#L31, landing on the*/above it).♻️ Drop the
DocNodecompatibility shim — consume v2'sSymbol/Declarationdirectly:DocPageSection.node: DocNode→declaration: Declaration.type SymbolInfo = Omit<Symbol, "declarations">(a fullSymbolis structurally assignable, so build-time code passes the realSymbol; render-time passes{ name: page.name }). Signatures becomeextract(declaration, symbol),Type({ declaration, symbol }),exportHash(declaration, symbol, i).NamespaceDef.elements(real memberSymbols) instead of synthesizing flat nodes.DocPage.nameis intentionally kept (many call sites read it);SymbolInfoflows only through the three render helpers.package.ts(API routes) andpackage/node.ts(the/xcontrib packages).No rendered-output change beyond the line-link fix — this is a structural refactor.
Validation
Ran the site locally:
/api/v4/run,/api/v4/call,/api/v4-next/experimental/createApi(banner + 2 badges intact), and/api/v3/spawnrender with full content;/x/websocket(3 source links) and/x/stream-helpers(25) exercise thepackage/node.tspath; therunsource link verified at the correct line.deno fmt --check,deno lint, anddeno check main.tsxpass.