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 0:54am

[cursor]

PR Summary

Medium Risk
Updates the type-linking logic to a new recursive parser, which can change how generated API docs render and link types for many signatures. Risk is moderate due to new parsing/precedence handling across unions, intersections, generics, and function types.

Overview
Replaces the regex-based generic type handling in transformTypeToReferenceLink with a dedicated recursive parser (typeParser.mjs) that supports nested generics, union/intersection precedence, and function return types when generating reference links.

Removes the old TYPE_GENERIC_REGEX constant and adds/expands unit tests to cover advanced combinations (functions returning generics, operator precedence, and deeply nested mixes of generics/unions/intersections).

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

[codecov]

Codecov Report

❌ Patch coverage is 93.87755% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.43%. Comparing base (3d00fa8) to head (00d8c39).

Files with missing lines	Patch %	Lines
src/generators/metadata/utils/typeParser.mjs	92.56%	6 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #763      +/-   ##
==========================================
- Coverage   78.43%   78.43%   -0.01%     
==========================================
  Files         157      158       +1     
  Lines       13962    13998      +36     
  Branches     1152     1165      +13     
==========================================
+ Hits        10951    10979      +28     
- 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 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 00d8c39. Configure here.}

[cursor]

Function arrow operator precedence is incorrect in parser

High Severity

The => (function arrow) handling is checked after | and &, but in TypeScript type syntax => is the weakest-binding operator — its return type extends to the right consuming unions and intersections. For input like (err: Error) => string | null, the parser first finds | at the outer level (depth 0), splits into (err: Error) => string and null, and incorrectly produces a union instead of a function returning string | null. The => check needs to come before the | and & checks so the return type is kept whole and recursively parsed.

 

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

[moshams272]

WIP