Fix SDK API reference parameter labels#2164
Merged
Merged
Conversation
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found across 1 file
Confidence score: 3/5
- There is a concrete behavioral risk in
packages/docs/sdk-api-reference-labels.js: per-mutation subtree debouncing can miss concurrently added subtrees, which may leave label rewriting inconsistent on the page. - Given the moderate severity (5/10) and high confidence (8/10), this is more than a cosmetic uncertainty and introduces a plausible regression in docs rendering behavior.
- Pay close attention to
packages/docs/sdk-api-reference-labels.js- debounce scheduling should cover coalesced mutations with a full-page rewrite to avoid missed rewrites.
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/docs/sdk-api-reference-labels.js">
<violation number="1" location="packages/docs/sdk-api-reference-labels.js:187">
P2: Debouncing rewrites with a per-mutation subtree root can miss other concurrently added subtrees, causing inconsistent label rewriting. Schedule a full-page rewrite here so coalesced mutations are all covered.</violation>
</file>
Architecture diagram
sequenceDiagram
participant Browser as Client Browser
participant Mintlify as Mintlify Renderer
participant Script as SDK Label Rewriter
participant SPA as SPA Router
participant DOM as DOM Tree
Note over Browser,DOM: Page Load Flow
Browser->>Mintlify: Request /v3/api-reference/{language}/...
Mintlify->>Mintlify: Render OpenAPI spec (camelCase labels)
Mintlify->>Browser: Return HTML with SDK code samples
Note over Browser,DOM: SDK Label Rewriter Execution
Browser->>Script: Load sdk-api-reference-labels.js
Script->>Script: scheduleRewrite() on initial load
Script->>DOM: Create TreeWalker to scan text nodes
alt Python or Ruby path (e.g., /v3/api-reference/python/...)
Script->>Script: currentSdkLanguage() returns "python" or "ruby"
Script->>Script: Load SNAKE_CASE_PARAM_LABELS mapping
Script->>DOM: Walk text nodes within content-area, api-section, field
loop For each matching text node
alt Node is inside code, pre, input, script, style, or editable element
Script->>DOM: SKIP - preserve camelCase
else Node is valid label text
Script->>DOM: Replace camelCase → snake_case using RegExp
end
end
else Java/Go/TypeScript path
Script->>Script: currentSdkLanguage() returns unsupported language
Script->>DOM: No rewrite - labels remain camelCase
end
Note over Browser,DOM: SPA Route Change Handling
Browser->>SPA: User navigates to new API reference page
SPA->>Script: pathname changes (polled every 250ms)
Script->>Script: Detect path change via setInterval
Script->>DOM: scheduleRewrite() with document.body
Note over Browser,DOM: Dynamic DOM Updates
DOM->>Script: Trigger MutationObserver on added nodes
Script->>Script: scheduleRewrite() with new subtree
Script->>DOM: Rewrite labels in newly added content only
Note over Browser,DOM: Validation
Browser->>Browser: Verify Python/Ruby labels display snake_case
Browser->>Browser: Verify code blocks remain camelCase
Browser->>Browser: Verify Java page labels unchanged
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
| for (const mutation of mutations) { | ||
| for (const node of mutation.addedNodes) { | ||
| if (node.nodeType === Node.ELEMENT_NODE) { | ||
| scheduleRewrite(node); |
Contributor
There was a problem hiding this comment.
P2: Debouncing rewrites with a per-mutation subtree root can miss other concurrently added subtrees, causing inconsistent label rewriting. Schedule a full-page rewrite here so coalesced mutations are all covered.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/sdk-api-reference-labels.js, line 187:
<comment>Debouncing rewrites with a per-mutation subtree root can miss other concurrently added subtrees, causing inconsistent label rewriting. Schedule a full-page rewrite here so coalesced mutations are all covered.</comment>
<file context>
@@ -0,0 +1,202 @@
+ for (const mutation of mutations) {
+ for (const node of mutation.addedNodes) {
+ if (node.nodeType === Node.ELEMENT_NODE) {
+ scheduleRewrite(node);
+ return;
+ }
</file context>
pirate
approved these changes
May 26, 2026
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
2 participants
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.
Summary
Why
Mintlify renders these language-scoped API reference pages from the Stainless documented OpenAPI spec, so visible schema labels use wire-format camelCase even when the Python and Ruby SDK snippets use snake_case.
Validation
pnpm --dir packages/docs exec prettier --check sdk-api-reference-labels.jsnode --check packages/docs/sdk-api-reference-labels.js/v3/api-reference/{python,ruby,java}/...: Python/Ruby labels rewrote to snake_case, code blocks stayed camelCase, and Java remained unchangedSummary by cubic
Fixes mismatched parameter labels on Python and Ruby SDK API reference pages by rewriting OpenAPI camelCase labels to SDK snake_case. Code samples and inputs remain unchanged; other languages are unaffected.
packages/docs/sdk-api-reference-labels.jsto relabel visible schema fields for Python and Ruby only.code,pre,input,script,style, and editable elements to preserve language-correct snippets.Written for commit ea143a6. Summary will update on new commits. Review in cubic