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 12, 2026 9:44am

[cursor]

PR Summary

Medium Risk
Replaces the type-linking parser with new recursive splitting/precedence logic for unions, intersections, functions, and nested generics, which could subtly change how types are rendered in generated docs. Covered by added unit tests, but still impacts core metadata generation output.

Overview
transformTypeToReferenceLink now uses a recursive type parser (parseAdvancedType) instead of the previous regex-based generic handling, enabling correct linking/formatting for nested generics, function return types (=>), and mixed union/intersection precedence.

The generic-regex constant (TYPE_GENERIC_REGEX) is removed, the outer-splitting helper is generalized to support multiple separators and parentheses depth, and new tests validate complex combinations (functions + generics + unions/intersections).

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

[codecov]

Codecov Report

❌ Patch coverage is 93.16239% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.43%. Comparing base (3d00fa8) to head (c69122a).

Files with missing lines	Patch %	Lines
src/generators/metadata/utils/transformers.mjs	91.48%	5 Missing and 3 partials ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #763   +/-   ##
=======================================
  Coverage   78.43%   78.43%           
=======================================
  Files         157      157           
  Lines       13962    14000   +38     
  Branches     1152     1164   +12     
=======================================
+ Hits        10951    10981   +30     
- Misses       3006     3011    +5     
- Partials        5        8    +3     

☔ 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 2 potential issues.

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

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

[avivkeller]

Suggested change

	// Kick off the recursive parser on the cleaned input
	const markdownLinks = parseAdvancedType(typeInput, transformType);
	const markdownLinks = parseType(typeInput);

Let's call this parseType, and, since it's getting very complex, let's put it in it's own file.

[avivkeller]

MyType should be handled, no?