fix(web_generator): resolve infinite recursion for self-referential class types

[wisdomaj]

Summary

Fixes a stack overflow in web_generator's interop_gen transformer when a class member's return type references the class being transformed (e.g. static open(): Promise<Database> inside Database).

Problem

When transforming a class, _transformClassOrInterface builds the declaration object and then iterates over members. When it encounters Promise<Database>, the type resolver calls _searchForDeclRecursive("Database"), which looks in nodeMap. The class hasn't been registered yet (that happens after transformAndReturn completes), so the lookup fails and triggers a new transformAndReturn(Database) call, causing infinite recursion.

Reproducing the issue

1. Create a file input.d.ts:

export declare class Database {
  readonly name: string;
  static open(name: string): Promise<Database>;
  close(): void;
}

2. Run the generator:

dart bin/gen_interop_bindings.dart dts input.d.ts -o output.dart

3. Observe the stack overflow:

RangeError: Maximum call stack size exceeded
    at _SymbolTrackerImpl.trackSymbol (typescript.js:94992)
    at lookupSymbolChain (typescript.js:57448)
    ...

Removing the Promise<Database> return type (or replacing it with Promise<void>) makes the crash go away, confirming the self-referential type is the trigger.

Solution

Uses an in-progress guard map (_pendingTypes).

• _transformClassOrInterface registers the declaration as pending before processing members and removes it after via try/finally
• _searchForDeclRecursive checks _pendingTypes before calling transformAndReturn. If found, it uses the in-progress instance to break the cycle
• The post-loop re-lookup is guarded so it doesn't overwrite a pending match

This approach:

• Avoids duplicating scope registration logic (no changes to _transformNamespace or _searchForDeclRecursive's existing registration paths)
• Does not pollute the global nodeMap with nested declarations
• Works identically for top-level and namespace-nested classes

Test plan

• All 75 existing tests pass
• Add additional self referencing tests

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request introduces a pre-registration step for declarations in the Transformer to prevent infinite recursion when members reference their parent type. While this addresses the immediate issue, feedback highlights that the implementation is incomplete for nested declarations and causes global symbol pollution, which is evident in the updated test expectations where types are resolved to underlying class names instead of intended typedefs. A more robust solution involving proper scope registration is recommended.

[kevmoo]

/gemini review

[gemini-code-assist]

Code Review

This pull request implements a cycle-detection mechanism in the Transformer class to prevent infinite recursion when a class member's type references the class itself. It introduces a _pendingTypes map to track active transformations and updates the declaration lookup logic to utilize these in-progress instances. I have no feedback to provide.

[kevmoo]

@wisdomaj – tests would be nice 😄

[wisdomaj]

@kevmoo Just added all of the test cases I could think of at the moment 😄

[nikeokoronkwo]

This is interesting... something I was currently dealing with concerning infinite recursion is dealing with multiple of the same/similar nodes defined in different files. Sometimes these nodes may be overloaded and the node properties may need to be referenced from another file.

For reference, this issue comes when parsing types from the ES Spec implementations in TS declarations by the TypeScript team.

While I understand the scope of this PR may not be to cover that as well, I wanted to make this comment as a reference so that if that isn't covered here, I'd continue from this to find a longer-term solution.

[kevmoo]

FYI: I'm vibe hacking on bootstrapping the generator on itself and hitting the same issue! I have a fix locally (stacked with a BUNCH of other stuff) that took inspiration from this fix!

[kevmoo]

Looks like we need to rebase on HEAD and fix tests, please!

[wisdomaj]

Apologies for the late response to this PR. I've been crazy busy the last few weeks and haven't had any time to dedicate to this. I did just submit github issue #550 that better explains my motivation for this PR and other work I planned to contribute.

This PR is pretty far behind main now and it looks like from PR #548 that the issues I attempted to address in this PR may have been taken care of already. I can close this PR if you'd like.

[kevmoo]

#549 is the latest that @nikeokoronkwo is going to look at.

If you want to help, I'd love eyes on that HUGE PR. It has many individual commits that should be easier to look through.

Are the tests robust? Are there obvious issues with the implementation?

That would be a HUGE help! 🙏

[wisdomaj]

Awesome! I'll try and take a look later today if time allows.

[kevmoo]

Do you expect the system to keep moving after an exception here?

[wisdomaj]

I was trying to retain the same behavior with how exceptions were handled. I think we would want to fail fast and loud. If we kept moving after an exception I think we would generate bindings that are not complete, compile fine, but cause runtime errors.

Using try/finally are probably not necessary right now since an exception should stop transformation anyways. Using try/finally is more so defensive programming in case exception handling is changed in the future. If someone later adds a higher level catch (e.g. to print a different error message), removing finally would leave the half built type stuck in _pendingTypes, and later types that reference it would pick up that broken version instead of a fully transformed one.