Fix infinite recursion in example generation for circular type references

[musicpulpite]

Fix infinite recursion in example generation for circular type references

Summary

This PR adds cycle detection to prevent infinite recursion when generating examples for types with circular references in both Python and TypeScript SDK generators.

Problem: When types have circular references (e.g., type A references type B, which references type A), the example generators would recurse infinitely, causing stack overflow errors as seen in VapiAI/docs PR #795.

Solution:

• Created RecursionGuard utility classes for both Python and TypeScript that track visited types and enforce a maximum recursion depth (default: 5)
• Threaded the recursion guard through all example generation code paths
• When a cycle is detected (type already visited on current stack) or max depth is reached, return None/undefined which gets filtered out by existing code

Python changes:

• New RecursionGuard class in generators/python/src/fern_python/snippet/recursion_guard.py
• Updated SnippetWriter and all snippet generator implementations to accept and pass through recursion_guard parameter
• Updated FernTypedDict helper methods to support recursion guard

TypeScript changes:

• New RecursionGuard interface and RecursionGuardImpl class in generators/typescript/model/type-reference-example-generator/src/RecursionGuard.ts
• Updated GeneratedTypeReferenceExampleImpl.buildExample() to check for cycles before recursing into named types
• Updated BaseGeneratedType interface and all concrete implementations to accept optional recursionGuard parameter

Review & Testing Checklist for Human

⚠️ CRITICAL - This PR has NOT been tested against the actual failing examples

• Test with VapiAI/docs examples: Clone the VapiAI/docs repo, check out PR remove IDs #795, and verify that SDK generation no longer causes infinite recursion with this fix
• Verify TypeScript compilation: Run pnpm build or equivalent in the TypeScript generators to ensure no compilation errors were introduced
• Check maxDepth appropriateness: The default maxDepth is set to 5. Verify this doesn't break legitimate deeply nested examples and is sufficient to catch cycles early
• Validate return values: Confirm that returning None/undefined on cycle detection is correct and doesn't break example generation for valid cases
• Performance testing: Test with deeply nested (but non-circular) structures to ensure the recursion guard doesn't cause performance issues

Test Plan

1. Set up a test API definition with circular type references (e.g., type A { b: B }, type B { a: A })
2. Generate Python and TypeScript SDKs with examples enabled
3. Verify generation completes without stack overflow
4. Verify generated examples are valid (or omitted for circular fields)
5. Test with the actual VapiAI/docs configuration that was failing

Notes

• The recursion guard uses a copy-on-write approach for the visited set to avoid shared mutable state
• The withDepthIncrement() method is used for container types (lists, maps) to track depth without marking types as visited
• No unit tests were added in this PR - these should be added as follow-up work
• Session: https://app.devin.ai/sessions/e43b93483cc145b58c6b14ea1407a3f1
• Requested by: William McAdams (@musicpulpite, [email protected])

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring