feat(metadata): support advanced generics using recursion

[moshams272]

Description

This PR uses the Recursive approach instead of using Regex that just covered the basic generic and can't handle:

• Nested Generics Transformer<T, Awaitable<U>>
• Function Signature (str: MyType) => Promise<T>
• Complex Union and Intersection string & number | boolean
• Depth

The new implementation uses a top-down Recursive approach, breaking down types layer by layer starting from the weakest operators to the strongest.

Validation

• Added comprehensive test cases in transformers.test.mjs
• Run node --run test and verified that all test cases (old and new) passed successfully.

Related Issues

This PR acts as an extension to #666. While #666 solved the basic mapping, this implementation introduces a recursive parser to handle more complex nested types.

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run node --run test and all tests passed.
• I have check code formatting with node --run format & node --run lint.
• I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Apr 13, 2026 4:31pm

[cursor]

PR Summary

Medium Risk
Replaces the existing regex/split-based type-linking logic with a new recursive parser, which could change how many API type strings render across generated docs. Risk is moderate because it affects a core formatting utility but is covered by expanded unit tests.

Overview
transformTypeToReferenceLink now delegates type rendering to a new recursive parseType implementation, replacing the previous regex-driven generic parsing logic.

The new parser supports nested generics, function return types, and more complex union/intersection combinations (including precedence handling and parenthesis stripping), and adds targeted unit tests to lock in these behaviors. It also removes the unused TYPE_GENERIC_REGEX constant.

^{Reviewed by Cursor Bugbot for commit bb43bc8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 82.14286% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.32%. Comparing base (3d00fa8) to head (bb43bc8).

Files with missing lines	Patch %	Lines
src/generators/metadata/utils/typeParser.mjs	79.41%	30 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #763      +/-   ##
==========================================
- Coverage   78.43%   78.32%   -0.12%     
==========================================
  Files         157      158       +1     
  Lines       13962    14047      +85     
  Branches     1152     1169      +17     
==========================================
+ Hits        10951    11002      +51     
- Misses       3006     3035      +29     
- Partials        5       10       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bb43bc8. Configure here.}

[cursor]

Arrow function checked first causes wrong operator precedence

Medium Severity

The => handler runs before | and &, giving => the lowest precedence in this top-down recursive parser. For a type like Promise<string> | (err: Error) => void, splitByOuterSeparator splits on => at depth 0, producing params Promise<string> | (err: Error) and return void — treating the whole expression as a single function type. The correct parse is a union of Promise<string> and (err: Error) => void. Any union or intersection appearing before a function arrow at the same nesting level will be swallowed into the parameter side.

Additional Locations (1)

• src/generators/metadata/utils/typeParser.mjs#L109-L120

 

^{Reviewed by Cursor Bugbot for commit bb43bc8. Configure here.}