[generator] Add support for source map backed stack traces for debugging generator output

[nikeokoronkwo]

Fixes #505

This PR adds support for working with the web generator errors better using dart-style stack traces by mapping the stack trace frames from V8/NodeJS to Dart, using the related dart packages.

This makes the error messages much easier to debug and deal with, which improves debugging

Issues

1. There are some issues mapping the frames completely, including but not limited to mapping npm dependency code in the stack frames. The major example here being that the frames occuring from the typescript package are being mapped to other unrelated packages. An example before:

    at getTypeFromTypeReference (~/web/web_generator/lib/src/node_modules/typescript/lib/typescript.js:65071:36)
    at getTypeFromTypeNodeWorker (~/web/web_generator/lib/src/node_modules/typescript/lib/typescript.js:67750:16)
    at getTypeFromTypeNode (~/web/web_generator/lib/src/node_modules/typescript/lib/typescript.js:67712:41)
    at Object.getTypeFromTypeNode (~/web/web_generator/lib/src/node_modules/typescript/lib/typescript.js:51140:21)
    at Transformer._transformType$4$isNullable$parameter$typeArg (~/web/web_generator/lib/src/dart_main.js:8064
    at Transformer._transformType$1 (~/web/web_generator/lib/src/dart_main.js:81095:19)

and after:

../../../../../../.pub-cache/hosted/pub.dev/dart_style-3.1.3/lib/src/front_end/piece_writer.dart 208:23  getTypeFromTypeReference
../../../../../../.pub-cache/hosted/pub.dev/dart_style-3.1.3/lib/src/short/rule/rule.dart 166:5          getTypeFromTypeNode
org-dartlang-sdk:///lib/_internal/js_shared/lib/js_util_patch.dart 149:10                                Transformer._transformType

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the debugging experience for the web_generator by implementing a mechanism to map V8/NodeJS stack traces to their corresponding Dart source locations. This transformation provides more readable and actionable error messages, making it easier to identify and resolve issues within the generated code. Additionally, it includes refactoring of event handling in package:web and updates to the generator's type processing capabilities.

Highlights

• Dart-style Stack Trace Mapping: Implemented a mechanism to map V8/NodeJS stack traces from the web generator to Dart source locations, significantly improving error readability and debugging.
• Raw Stack Trace Option: Introduced a --raw-stack-traces flag in gen_interop_bindings.dart to allow developers to view unmapped JavaScript stack traces if needed.
• Event Provider Refactoring in package:web: Consolidated CustomEventProviders into EventStreamProviders for a cleaner and more consistent event handling API.
• Enhanced Type Transformation in web_generator: Improved the web_generator's ability to correctly transform TypeScript literal types and indexed access types into their Dart equivalents.
• Node.js Requirement Update: Updated the minimum Node.js version requirement for web_generator to v22 or newer.

Changelog

• web/CHANGELOG.md
  • Removed CustomEventProviders and noted their migration to EventStreamProviders.
• web/README.md
  • Documented that document.cookie is now non-nullable and always returns a String in package:web.
• web/lib/src/helpers/events/events.dart
  • Migrated custom event extensions from CustomEventProviders to EventStreamProviders.
• web/lib/src/helpers/events/providers.dart
  • Consolidated CustomEventProviders into EventStreamProviders by moving relevant static members.
• web/lib/src/helpers/events/streams.dart
  • Removed unused Device import and simplified event listener wrapping logic.
• web_generator/README.md
  • Added a requirement for Node.js v22 or newer for web_generator.
• web_generator/bin/gen_interop_bindings.dart
  • Implemented source map-based stack trace mapping for Node.js errors.
  • Added a --raw-stack-traces flag to display unmapped JavaScript stack traces.
• web_generator/lib/src/ast/declarations.dart
  • Refactored conditional list additions for constructors and extendees using if (x != null) x to [?x].
• web_generator/lib/src/ast/merger.dart
  • Refactored conditional list additions for extensions and enums using if (x != null) x to [?x].
• web_generator/lib/src/cli.dart
  • Refactored conditional list additions for supertypes using if (x != null) x to [?x].
• web_generator/lib/src/dart_main.dart
  • Added a TODO comment regarding Dart stack traces in JS.
• web_generator/lib/src/interop_gen/parser.dart
  • Enhanced error reporting for parsing diagnostics, adding ParseError prefix and conditional handleDiagnostics calls.
• web_generator/lib/src/interop_gen/transform/transformer.dart
  • Refactored modifier parsing for class declarations.
  • Simplified name assignment for literal expressions.
  • Introduced helper functions for literal type creation.
  • Added comprehensive logic for transforming IndexedAccessType nodes.
• web_generator/lib/src/js/typescript.dart
  • Exposed typeToString and typeToTypeNode methods from TypeScript's TSTypeChecker for advanced type introspection.
• web_generator/lib/src/js/typescript.types.dart
  • Defined TSTypeFlags.BooleanLiteral and TSSyntaxKind.IndexedAccessType.
  • Added new extension types for TSLiteralType, TSNumberLiteralType, and TSStringLiteralType.
• web_generator/pubspec.yaml
  • Added new dependencies: source_map_stack_trace, source_maps, and stack_trace.
• web_generator/test/integration/interop_gen/indexed_access_test_expected.dart
  • Added expected output for indexed access type transformation tests.
• web_generator/test/integration/interop_gen/indexed_access_test_input.d.ts
  • Added new TypeScript declaration file for indexed access type tests.
• web_generator/test/integration/interop_gen/literal_test_expected.dart
  • Added expected output for literal type transformation tests.
• web_generator/test/integration/interop_gen/literal_test_input.d.ts
  • Added new TypeScript declaration file for literal type tests.

Ignored Files

• Ignored by pattern: .github/workflows/** (4)
  • .github/workflows/js_interop.yaml
  • .github/workflows/no-response.yml
  • .github/workflows/web.yaml
  • .github/workflows/web_generator.yaml

Activity

• The pull request addresses issue [web_generator] Improve debugging of bin scripts with better stack traces #505 by implementing Dart-style stack trace mapping for web generator errors.
• The author has provided example stack traces to demonstrate the improvement in error messages.
• A known issue has been identified regarding difficulties in completely mapping frames from npm dependency code, specifically the typescript package.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the debugging experience for the web generator by adding support for Dart-style stack traces. My review includes a suggestion to make the stack trace parsing more robust and a minor simplification in the IndexedAccessType logic.

[gemini-code-assist]

Assuming HomogenousEnumType is a subtype of UnionType, this else if block is redundant. The logic for UnionType already handles iterating through types and recursively calling collectKeys. Removing this block will simplify the code without changing its behavior.