chore(repo): Typedoc: Handle <code> injection in function signatures #7010
Conversation
🦋 Changeset detectedLatest commit: bdd332e The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds an internal Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Renderer as Theme Renderer
participant Context as ClerkMarkdownThemeContext
participant Partial as reflectionType / other partials
participant Output as HTML
Renderer->>Context: render signatureTitle(...)
Note right of Context #E8F6FF: Context sets\n_insideFunctionSignature=true\nwhen rendering params/types
Context->>Partial: render type model
alt flag = true (inside signature)
Partial->>Partial: strip backticks & remove <code>
Partial-->>Context: unwrapped type string
else flag = false (outside signature)
Partial->>Partial: strip backticks & ensure single <code> wrapper
Partial-->>Context: wrapped `<code>` type string
end
Context-->>Renderer: composed signature HTML
Renderer->>Output: emit final HTML
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
alexisintech
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
.typedoc/custom-theme.mjs(5 hunks)packages/backend/src/tokens/verify.ts(0 hunks)
💤 Files with no reviewable changes (1)
- packages/backend/src/tokens/verify.ts
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/elements
@clerk/clerk-expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/clerk-react
@clerk/react-router
@clerk/remix
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/themes
@clerk/types
@clerk/upgrade
@clerk/vue
commit: |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
.typedoc/custom-theme.mjs (3)
47-48: Consider adding JSDoc documentation for the internal flag.The
_insideFunctionSignatureflag is central to preventing<code>injection, but lacks documentation explaining its purpose and usage pattern.Consider adding a comment like:
+ /** + * Internal flag to track when rendering types inside a function signature context. + * When true, type partials should return unwrapped output to avoid nested code blocks. + * @private + */ this._insideFunctionSignature = false;
148-158: The save/restore pattern correctly addresses the past review concern.The implementation now saves and restores
_insideFunctionSignaturearound bothsignatureParametersandsomeTypecalls, which correctly handles nested function signatures (e.g., callbacks or higher-order returns).Optional improvements:
- For robustness, consider try-finally to ensure flag restoration even if an error occurs:
const prevInsideParams = this._insideFunctionSignature; - this._insideFunctionSignature = true; - md.push(this.partials.signatureParameters(model.parameters || [])); - this._insideFunctionSignature = prevInsideParams; + try { + this._insideFunctionSignature = true; + md.push(this.partials.signatureParameters(model.parameters || [])); + } finally { + this._insideFunctionSignature = prevInsideParams; + }
- Minor nitpick:
prevInsideParamsandprevInsideTypeboth save the same flag in a non-overlapping sequence. A consistent name likeprevmight be clearer.
148-158: Coverage is complete for all overridden partials.The custom theme overrides exactly 5 type partials that wrap types in
<code>tags:declarationType,unionType,functionType,arrayType, andreflectionType. All 5 have the guard pattern, plus 2 additional occurrences insignatureTitle, for a total of 7 guards. Other type partials likeintersectionType,tupleType,typeOperatorType, etc., are not overridden, so they use the default typedoc-plugin-markdown implementations and don't need guards in this theme.The code duplication concern remains valid—the save/restore pattern appears 7 times across the file. The suggested helper extraction would improve maintainability and reduce duplication.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.typedoc/custom-theme.mjs(6 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Build Packages
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (3)
.typedoc/custom-theme.mjs (3)
355-359: LGTM! Conditional wrapping prevents double code blocks.The guard correctly returns unwrapped output when inside a function signature, preventing the
<code>injection issue.
378-382: LGTM! Consistent guard pattern across all modified type partials.The conditional wrapping is correctly applied to
unionType,functionType, andarrayType, maintaining consistency with the fix.Also applies to: 406-410, 509-515
516-536: LGTM! NewreflectionTypepartial correctly handles wrapped types likeSimplify.This addition directly addresses the issue from PR #6993 where
Simplify<VerifyTokenOptions>was causing<code>injection. The implementation correctly follows the established pattern.
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.changeset/silly-jars-shave.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
.changeset/**
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Automated releases must use Changesets.
Files:
.changeset/silly-jars-shave.md
🪛 LanguageTool
.changeset/silly-jars-shave.md
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: --- ---
(QB_NEW_DE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: Analyze (javascript-typescript)
| --- | ||
| --- |
There was a problem hiding this comment.
Changeset file is incomplete and missing required content.
The changeset file contains only the frontmatter delimiters (---) but lacks the package bump entries and change summary. This will fail Changesets processing.
According to the Changesets format, the file should contain:
- Inside the frontmatter: one or more package entries with their bump types (e.g.,
"@clerk/backend": patch) - After the frontmatter: a human-readable summary of the changes
Expected format:
---
"@clerk/backend": patch
---
Fix Typedoc rendering of <code> tags in function signatures
Please update the changeset file with the appropriate package name(s) and bump type based on which packages were modified in this PR.
🧰 Tools
🪛 LanguageTool
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: --- ---
(QB_NEW_DE)
🤖 Prompt for AI Agents
In .changeset/silly-jars-shave.md around lines 1 to 2 the file only contains
frontmatter delimiters and is missing required package bump entries and a
human-readable summary; update the file by adding one or more package entries
with their bump types inside the frontmatter (e.g., "@clerk/backend": patch) and
then add a short summary of the change after the closing --- delimiter, choosing
the correct package names and bump levels that correspond to the packages
modified in this PR.
Description
In this PR, the
Simplifytype was introduced to wrap the type forVerifyTokenOptions, causing the docs for theverifyToken()to changeBefore that PR:
Screen.Recording.2025-10-16.at.14.52.55.mov
After that PR:
Screen.Recording.2025-10-16.at.14.59.10.mov
The function signature incorrectly had
<code>in the codeblock.This PR updates our typedoc theme to disallow the injection of a
<code>in function signatures, as function signatures are already output into codeblocks.Changes regarding this PR:
Screen.Recording.2025-10-16.at.14.51.33.mov
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit