refactor(repo): Inline extract-methods + tighten parameter rendering#8637
Draft
alexisintech wants to merge 7 commits into
Draft
refactor(repo): Inline extract-methods + tighten parameter rendering#8637alexisintech wants to merge 7 commits into
alexisintech wants to merge 7 commits into
Conversation
Folds extract-methods.mjs into a MarkdownPageEvent.END listener that queues a preWriteAsyncJob, removing the second TypeDoc convert pass and its prepare-markdown-renderer.mjs workaround. Output is byte-identical to the prior two-pass flow (verified by full `diff -r`, 695/695 files); adds 10 file-snapshot tests to lock that contract for future refactors. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces three unwrap-optional helpers + a while-loop with a single
`unwrapOptional(t, { deep })`. Extracts the two `toKebabCase` flavors into
`.typedoc/slug.mjs` — `toFileSlug` (method filenames) and `toUrlSlug` (page URLs)
intentionally differ on acronyms, so the module exports both rather than unifying.
Also adds the snapshot dir to `.prettierignore`: lint-staged was silently
transforming the committed snapshots after `vitest run` passed, leaving them out of
sync with the raw output `extract-methods.mjs` writes. Regenerates them.
Output is byte-identical to the pre-refactor baseline (`diff -r`, 695/695 files).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
`clerkParametersTable` now joins flattened parent.child names with `?.` when the parent is optional and `.` when required, mirroring how the property would be accessed at runtime. `nestedParameterRowsFromDocumentedProperties` applies the same rule. With the theme correct, the regex post-process in `formatMethodParametersTable` (reorder + blanket `.` → `?.` rename) is no longer needed — removed (-116 LOC), along with `appendMarkdownTableRows`. Fixes 8 files where the old blanket rule was wrong in one direction or the other: - `shared/clerk/methods/handle-email-link-verification.mdx`: parent `params` is required, children now render as `params.foo` (was `params?.foo`). - `backend/get-auth-fn.mdx`, `backend/get-auth-fn-no-request.mdx`, `nextjs/current-user.mdx`, `shared/api-keys-namespace.mdx`, `shared/custom-navigation.mdx`, `shared/get-memberships.mdx`, `shared/on-event-listener.mdx`: parent is optional, children now render as `parent?.foo` (was `parent.foo`). Adds a snapshot for `handle-email-link-verification.mdx` to lock in the required-parent rendering. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
alexisintech
changed the title
`custom-theme.mjs` and `extract-methods.mjs` were reaching into `node_modules/typedoc-plugin-markdown/dist/libs/...` for `backTicks`, `heading`, `htmlTable`, `table`, `removeLineBreaks`, and the `TypeDeclarationVisibility` enum — none of which the plugin exports publicly. That coupling breaks on any dependency update. Inlines the five utilities (plus the `escapeChars` / `formatTableCell` helpers they call) into `.typedoc/markdown-helpers.mjs`, and replaces the enum check with the underlying string literal (`'compact'`). Generated output is byte-identical to the upstream behavior (`diff -r` shows zero deltas beyond the unrelated step-4 changes; 16 snapshot tests pass). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Stacked on top of #8276 — review that one first.
Four independent refactors of
.typedoc/(each its own commit) plus snapshot tests to lock the contract for future changes.Summary
extract-methodsinside the markdown render pass — foldsextract-methods.mjsinto aMarkdownPageEvent.ENDlistener that queues apreWriteAsyncJob. Removes the secondApplication.bootstrapWithPlugins+convert()and theprepare-markdown-renderer.mjsworkaround it required.unwrapOptional(t, { deep }). The twotoKebabCaseflavors (one for method filenames, one for page URLs) move into.typedoc/slug.mjs— they intentionally differ on acronyms, so the module exports both rather than unifying.clerkParametersTable.flattenParamsnow joinsparent.childwith?.when the parent is optional and.when required. Lets us deleteformatMethodParametersTable(the regex post-process that did a blanket.→?.rename plus a no-longer-needed reorder).node_modulesimports —custom-theme.mjsandextract-methods.mjswere reaching intonode_modules/typedoc-plugin-markdown/dist/libs/...forbackTicks,heading,htmlTable,table,removeLineBreaks, and theTypeDeclarationVisibilityenum — none of which the plugin exports publicly, so that coupling broke on any dependency update. The five utilities (plus theirescapeChars/formatTableCelldependencies) are now inlined in.typedoc/markdown-helpers.mjs, and the enum check is replaced with the underlying string literal ('compact').Also adds the snapshot dir to
.prettierignore: lint-staged was silently transforming the committed snapshots aftervitest runpassed, leaving them out of sync with the raw output thatextract-methods.mjswrites.Output changes
Output is byte-identical to the pre-refactor baseline (
diff -r, 695/695 files) for the first two and fourth commits. The third commit deliberately changes 8 files to fix a latent inconsistency:shared/clerk/methods/handle-email-link-verification.mdx: parentparamsis required, children now render asparams.foo(wasparams?.foo).backend/get-auth-fn.mdx,backend/get-auth-fn-no-request.mdx,nextjs/current-user.mdx,shared/api-keys-namespace.mdx,shared/custom-navigation.mdx,shared/get-memberships.mdx,shared/on-event-listener.mdx: parent is optional, children now render asparent?.foo(wasparent.foo).All eight match the rule "separator reflects how the property would be accessed at runtime."
Test plan
pnpm typedoc:generatesucceeds with no errors.cd .typedoc && vitest runpasses (11 new file-snapshot tests + the existing file-structure tests, 16 total).🤖 Generated with Claude Code