docs(repo): Fix broken typedoc links#8420
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
📝 WalkthroughWalkthroughThe TypeDoc MDX link-rewriting plugin configuration is extended with seven new mappings. These additions enable the plugin to rewrite relative or embedded links targeting various enterprise and billing entities ( Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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. Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.typedoc/custom-plugin.mjs (1)
77-99:⚠️ Potential issue | 🟡 MinorThe new mappings follow established patterns, but the unescaped
fileNamein the RegExp is brittle—consider escaping it or validating at build time.The plugin constructs RegExp patterns by directly interpolating
fileNameon line 128 without escaping. While current mapping names (hyphenated slugs) are safe, future entries containing regex metacharacters will silently fail to match. Consider either:
- Escaping
fileNamewith a helper function (e.g.,fileName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))- Adding a build-time validation that confirms each mapping's source file actually exists in the generated typedoc output
Additionally, these mappings cannot be verified in the source repository (typedoc generates the
.mdxfiles at build time). After running the docs build, spot-check one of these new type links in the rendered output to ensure the rewritten absolute paths are correct.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.typedoc/custom-plugin.mjs around lines 77 - 99, The RegExp built from the unescaped fileName (used where the plugin constructs a RegExp around fileName) is brittle; fix it by escaping fileName before interpolation (use a helper that escapes regex metacharacters) or add a build-time validation step that verifies each mapping's source file exists in the generated typedoc output; update the code path that creates the RegExp (the spot referencing fileName / new RegExp(...) in the plugin) to call the escape helper, and/or add a validation routine that iterates the mapping array and checks the generated .mdx files to fail early if a mapping doesn't resolve.
🧹 Nitpick comments (2)
.typedoc/custom-plugin.mjs (2)
124-133: EscapefileNamebefore embedding it intoRegExp(brittleness/security hardening).
getRelativeLinkReplacements()buildsnew RegExp(... ${fileName}\\.mdx ...)without escapingfileName. Your current slugs (hyphens) are regex-safe, but this is brittle for future mappings—anyfileNamecontaining regex metacharacters (e.g.+,.,(,)) would break the pattern or match unexpectedly.Consider a small
escapeRegExp()helper and use it when building the regex.Patch suggestion
function getRelativeLinkReplacements() { return LINK_REPLACEMENTS.map(([fileName, newPath]) => { + const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') return { // Match both path and optional anchor - pattern: new RegExp(`\\((?:(?:\\.{1,2}\\/)+[^()]*?|)${fileName}\\.mdx(#[^)]+)?\\)`, 'g'), + pattern: new RegExp( + `\\((?:(?:\\.{1,2}\\/)+[^()]*?|)${escapeRegExp(fileName)}\\.mdx(#[^)]+)?\\)`, + 'g' + ), // Preserve the anchor in replacement if it exists replace: (/** `@type` {string} */ _match, anchor = '') => `(${newPath}${anchor})`, }; }); }You can validate this locally with a small Node snippet that demonstrates the regex still matches the same inputs for the current slugs.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.typedoc/custom-plugin.mjs around lines 124 - 133, getRelativeLinkReplacements currently interpolates raw fileName into a RegExp which is brittle and can break if fileName contains regex metacharacters; add an escapeRegExp helper (e.g., escapeRegExp(name): string) and use it to sanitize the fileName from LINK_REPLACEMENTS before building the RegExp in getRelativeLinkReplacements so the pattern uses escapedFileName instead of fileName; update the pattern construction and verify replace behavior remains the same.
264-273: Avoid recomputinggetRelativeLinkReplacements()for every page (minor perf).
load(app)callsgetRelativeLinkReplacements()inside theMarkdownPageEvent.ENDhandler, meaning you rebuild the replacement regex list once per page. Docs generation can involve many pages; this is minor, but easy to improve by precomputing once outside the event callback.Precompute
const linkReplacements = getRelativeLinkReplacements()once at module scope (or once perload(app)call) and reuse it.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.typedoc/custom-plugin.mjs around lines 264 - 273, The code currently calls getRelativeLinkReplacements() inside the MarkdownPageEvent.END handler, causing the replacement list to be rebuilt for every page; move the call to compute linkReplacements once (either at module scope or at the start of load(app)) and reuse that const inside the app.renderer.on(MarkdownPageEvent.END, ...) callback so you iterate over the precomputed linkReplacements and update output.contents (and still use output.url as before) without recomputing the regex list per page.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In @.typedoc/custom-plugin.mjs:
- Around line 77-99: The RegExp built from the unescaped fileName (used where
the plugin constructs a RegExp around fileName) is brittle; fix it by escaping
fileName before interpolation (use a helper that escapes regex metacharacters)
or add a build-time validation step that verifies each mapping's source file
exists in the generated typedoc output; update the code path that creates the
RegExp (the spot referencing fileName / new RegExp(...) in the plugin) to call
the escape helper, and/or add a validation routine that iterates the mapping
array and checks the generated .mdx files to fail early if a mapping doesn't
resolve.
---
Nitpick comments:
In @.typedoc/custom-plugin.mjs:
- Around line 124-133: getRelativeLinkReplacements currently interpolates raw
fileName into a RegExp which is brittle and can break if fileName contains regex
metacharacters; add an escapeRegExp helper (e.g., escapeRegExp(name): string)
and use it to sanitize the fileName from LINK_REPLACEMENTS before building the
RegExp in getRelativeLinkReplacements so the pattern uses escapedFileName
instead of fileName; update the pattern construction and verify replace behavior
remains the same.
- Around line 264-273: The code currently calls getRelativeLinkReplacements()
inside the MarkdownPageEvent.END handler, causing the replacement list to be
rebuilt for every page; move the call to compute linkReplacements once (either
at module scope or at the start of load(app)) and reuse that const inside the
app.renderer.on(MarkdownPageEvent.END, ...) callback so you iterate over the
precomputed linkReplacements and update output.contents (and still use
output.url as before) without recomputing the regex list per page.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: b590224d-631a-4d17-88b3-5b5567cbb502
📒 Files selected for processing (1)
.typedoc/custom-plugin.mjs
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
2 participants
Description
This PR fixes typedoc links to be used in docs.
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change