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	May 22, 2026 6:41pm

[cursor]

PR Summary

Medium Risk
Replaces regex-based type parsing with a new recursive parser, which could change how type annotations render and link across generated docs for edge-case signatures. Risk is mitigated by expanded unit test coverage but still touches core metadata link generation.

Overview
Improves transformTypeToReferenceLink by replacing the prior regex/split-based generic handling with a new recursive parseType parser that supports nested generics, arrays, arrow-function signatures, and correct | vs & precedence.

Adds TYPE_OPENERS/TYPE_CLOSERS constants for depth-aware parsing, removes the old TYPE_GENERIC_REGEX, and expands unit tests to cover complex nested combinations (functions, destructuring, unions/intersections, and multi-parameter generics).

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

[codecov]

Codecov Report

❌ Patch coverage is 86.61972% with 38 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.80%. Comparing base (3d00fa8) to head (560f5bc).
⚠️ Report is 22 commits behind head on main.

Files with missing lines	Patch %	Lines
src/generators/metadata/utils/typeParser.mjs	83.89%	36 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #763      +/-   ##
==========================================
+ Coverage   78.43%   82.80%   +4.36%     
==========================================
  Files         157      171      +14     
  Lines       13962    14904     +942     
  Branches     1152     1305     +153     
==========================================
+ Hits        10951    12341    +1390     
+ Misses       3006     2555     -451     
- 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.

[avivkeller]

Made a little optimization

[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 560f5bc. Configure here.}

[cursor]

Dead code: arrow branch in splitByOuterSeparator never reached

Low Severity

The isArrow / separator === '=>' branch in splitByOuterSeparator is dead code. All call sites pass single-character separators: ',', ':', '|', or '&'. The '=>' case in parseType uses direct index-based slicing via op.index instead. This adds unnecessary branching logic and an extra return 1 path that are never exercised, making the function harder to understand.

 

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