refactor: parallelize docs rendering and Shiki setup

[trivikr]

🔗 Linked issue

N/A

🧭 Context

Docs generation was doing more sequential work than necessary in the API renderer. We were awaiting kind sections one at a time, then symbols one at a time within each section, and each symbol also awaited syntax highlighting and markdown rendering serially.

For packages with large API surfaces, that made total render time closer to the sum of all individual steps instead of allowing independent work to overlap.

📚 Description

This PR parallelizes the independent async work in the docs rendering pipeline while preserving stable output order.

Changes:

• render kind sections concurrently in renderDocNodes
• render symbols concurrently within each kind section
• run per-symbol signature highlighting, description markdown rendering, and JSDoc tag rendering in parallel
• parallelize fenced code block highlighting in markdown rendering
• cache the in-flight Shiki highlighter initialization promise so concurrent highlighting does not trigger redundant startup work

The rendered HTML order is unchanged:

• kind sections still follow KIND_DISPLAY_ORDER
• symbols still render in their original section order

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
npmx.dev	Ready	Preview, Comment	Apr 5, 2026 3:04pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ignored	Preview	Apr 5, 2026 3:04pm
npmx-lunaria	Ignored		Apr 5, 2026 3:04pm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: aeec8486-7cdc-46d5-b426-13cf8f8ce229

📥 Commits

Reviewing files that changed from the base of the PR and between 80295fb and 92d69f3.

📒 Files selected for processing (1)

• server/utils/docs/text.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• server/utils/docs/text.ts

---

📝 Walkthrough

Walkthrough

The PR parallelises documentation rendering: render.ts now builds kind sections and symbol/signature/description/tag blocks using concurrent promises instead of sequential awaits. text.ts (renderMarkdown) highlights fenced code blocks with Promise.all and restores placeholders by index. shiki.ts (getShikiHighlighter) caches an in‑flight initialisation promise to prevent concurrent startup races and stores the resolved highlighter. Tests add createFunctionSymbol/createInterfaceSymbol helpers and a new ordering test verifying stable section and symbol render order.

🚥 Pre-merge checks | ✅ 1

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description check	✅ Passed	The pull request description clearly explains the context, motivation, and specific changes made to parallelise docs rendering while preserving output order.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

server/utils/docs/text.ts (1)

138-141: Consider using forEach for type-safe iteration.

The non-null assertion highlightedCodeBlocks[i]! bypasses TypeScript's type checking. While the loop bounds guarantee valid indices, a forEach callback would be strictly type-safe without the assertion.

♻️ Suggested refactor

-  for (let i = 0; i < highlightedCodeBlocks.length; i++) {
-    const highlighted = highlightedCodeBlocks[i]!
-    result = result.replace(`__CODE_BLOCK_${i}__`, highlighted)
-  }
+  highlightedCodeBlocks.forEach((highlighted, i) => {
+    result = result.replace(`__CODE_BLOCK_${i}__`, highlighted)
+  })

As per coding guidelines: "Ensure you write strictly type-safe code, for example by ensuring you always check when accessing an array value by index".

server/utils/docs/render.ts (1)

138-161: Destructured array elements may be null despite conditional guards.

The variables highlightedSignature, renderedDescription, and renderedJsDocTags are typed as string | null. The conditionals at lines 144, 154, and 159 mirror the conditions used to create the promises, but TypeScript cannot correlate these checks.

The runtime behaviour is correct, but for stricter type safety, consider using truthiness checks directly on the resolved values (which you already do at lines 154 and 159) or adding explicit null checks.

♻️ Minor type-safe adjustment for line 145

   if (signatures.length > 0) {
-    lines.push(`<div class="docs-signature">${highlightedSignature}</div>`)
+    lines.push(`<div class="docs-signature">${highlightedSignature ?? ''}</div>`)

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b64ac82b-b369-41a2-b097-ee16c3a7f693

📥 Commits

Reviewing files that changed from the base of the PR and between eb4d862 and ed78b73.

📒 Files selected for processing (4)

• server/utils/docs/render.ts
• server/utils/docs/text.ts
• server/utils/shiki.ts
• test/unit/server/utils/docs/render.spec.ts

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd79fef8-b292-4e38-9c0d-e632936bf7fc

📥 Commits

Reviewing files that changed from the base of the PR and between ed78b73 and e2de6db.

📒 Files selected for processing (2)

• server/utils/docs/render.ts
• server/utils/docs/text.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• server/utils/docs/render.ts