chore(repo): Typedoc: Handle <code> injection in function signatures #7010
Conversation
🦋 Changeset detectedLatest commit: c5989e1 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\nwhile rendering params/types
Context->>Partial: render type model
alt inside signature (_insideFunctionSignature = true)
Partial->>Partial: strip backticks & remove <code>
Partial-->>Context: return unwrapped type string
else outside signature (_insideFunctionSignature = false)
Partial->>Partial: strip backticks & ensure single `<code>` wrapper
Partial-->>Context: return wrapped 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.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
packages/backend/src/tokens/verify.ts (1)
43-43: Excellent documentation enhancement!The extended description effectively guides developers toward the best practice of using environment variables for configuration. The example is clear and actionable, directly demonstrating how to pass
secretKeyfrom an environment variable.Optional readability improvement:
The line is quite long (~400+ characters). Consider breaking it into multiple sentences for improved readability:
-@param options - Options for verifying the token. It is recommended to set these options as [environment variables](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `verifyToken(token, { secretKey: process.env.CLERK_SECRET_KEY })`. +@param options - Options for verifying the token. It is recommended to set these options as [environment variables](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable and pass it like this: `verifyToken(token, { secretKey: process.env.CLERK_SECRET_KEY })`.
📜 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(6 hunks)packages/backend/src/tokens/verify.ts(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- .typedoc/custom-theme.mjs
🧰 Additional context used
📓 Path-based instructions (6)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/backend/src/tokens/verify.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/backend/src/tokens/verify.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/tokens/verify.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/backend/src/tokens/verify.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/backend/src/tokens/verify.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/backend/src/tokens/verify.ts
⏰ 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). (5)
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: Build Packages
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (2)
packages/backend/src/tokens/verify.ts (2)
23-25: Verify@interfacetag usage for type alias.The
@interfaceJSDoc tag is typically used with TypeScriptinterfacedeclarations, but here it's applied to atypealias. While this may be intentional for Typedoc rendering purposes (especially given this PR addresses Typedoc issues), it's technically inconsistent with standard JSDoc conventions.If this is intentional for Typedoc, consider it approved. Otherwise, you may want to remove the
@interfacetag or convert the type to an interface if extensibility is needed.
26-34: LGTM! Type definition is well-structured.The
VerifyTokenOptionstype correctly usesSimplifyto flatten the intersection for better IDE experience. The JSDoc for thejwtKeyproperty appropriately recommends using environment variables, which aligns with security best practices.
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