Implement core disposal logic for explicit resource management

[abhinavs1920]

This Pull Request implements part of #4445 and fixes/closes #5314.

Make using actually dispose and SuppressedError builtin ( continued work )

Follow-up to my last PR (#4649) that added parsing.

Now when a block ends, resources get cleaned up properly.

• New bytecodes: AddDisposableResource + DisposeResources + PushDisposalScope

• VM now has a disposal stack + scope tracking

• Bytecompiler adds resources after each using and cleans up at end of blocks

• Add SuppressedError builtin following AggregateError pattern

• Add .error and .suppressed properties to `SuppressedError

• Update tests to expect TypeError for non-disposable values

Works like:

{
  using file = openFile();
} // ← auto disposed here

{
  using a = one();
  using b = two();
} // disposes b then a

{
  using outer = ...;
  { using inner = ...; } // inner first
} // then outer

using x = null; // just skips, no crash

[github-actions]

Test262 conformance changes

Test result	main count	PR count	difference
Total	52,963	52,963	0
Passed	50,073	50,073	0
Ignored	2,072	2,072	0
Failed	818	818	0
Panics	0	0	0
Conformance	94.54%	94.54%	0.00%

Tested main commit: 50f0103d9188d33862efbc38397a81e497973632
Tested PR commit: a684036e5e486d0e3a29ab0ac5f19a58dba664b2
Compare commits: 50f0103...a684036

[codecov]

Codecov Report

❌ Patch coverage is 88.58447% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.94%. Comparing base (6ddc2b4) to head (17abdf8).
⚠️ Report is 951 commits behind head on main.

Files with missing lines	Patch %	Lines
core/engine/src/builtins/error/suppressed.rs	84.61%	8 Missing ⚠️
core/engine/src/vm/flowgraph/mod.rs	0.00%	6 Missing ⚠️
core/engine/src/bytecompiler/mod.rs	16.66%	5 Missing ⚠️
...engine/src/vm/opcode/disposal/dispose_resources.rs	86.95%	3 Missing ⚠️
core/engine/src/vm/code_block.rs	0.00%	2 Missing ⚠️
core/engine/src/error/mod.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #5079       +/-   ##
===========================================
+ Coverage   47.24%   59.94%   +12.69%     
===========================================
  Files         476      593      +117     
  Lines       46892    63912    +17020     
===========================================
+ Hits        22154    38309    +16155     
- Misses      24738    25603      +865     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jedel1043]

Looks great, I really like the staged approach you're doing to implement the feature.

One thing though is that we need to gate everything behind the experimental feature while the proposal is not in stage 4. The parser can stay as it is since that usually doesn't get gated, but the bytecompiler should throw an error instruction instead of pushing a resource to the resources stack if the feature is not enabled.

[abhinavs1920]

Done, pushed the fix. Makes sense to keep unfinished proposals gated, I should've caught that myself looking at how import.defer was handled :)

Quick question while I'm here: for the next PR I'm planning to wire up disposal into the exception handling path (try-finally integration + SuppressedError). Is there anything specific about how the current handler/finally mechanism works that I should be aware of before diving in, or is the existing try.rs in the bytecompiler a good enough starting point?

[jedel1043]

Yes, try.rs is half of the solution but the other half lives in https://github.com/boa-dev/boa/blob/main/core/engine/src/bytecompiler/jump_control.rs, which is our jump handler tracking code that ensures finally statements are always executed even when returning from functions or breaking from loops.

I imagine you can reuse the code that we have for try-finally to integrate using statements, since those are very similar in concept

[abhinavs1920]

Just went through both files. The picture is clearer now, jump_control.rs is basically the glue that makes sure any break, continue, or return inside a try block doesn't just jump past the finally. It does this by collecting JumpRecords and routing them through a JumpTable at the end of the finally block so each one ends up at the right destination after disposal runs.

For using, I think the approach would be: push a JumpControlInfo with TRY_WITH_FINALLY semantics when entering a block that has using declarations, wrap the block body in a handler (like push_handler does for try), and on exit emit DisposeResources in the same spot compile_finally_stmt runs today. That way breaks/returns/exceptions all naturally route through disposal before leaving the scope.

Does that sound like the right direction, or is there a cleaner way you had in mind :)

[github-actions]

Test262 conformance changes

Test result	main count	PR count	difference
Total	53,125	53,125	0
Passed	51,049	51,049	0
Ignored	1,482	1,482	0
Failed	594	594	0
Panics	0	0	0
Conformance	96.09%	96.09%	0.00%

Tested main commit: 3cec5e6bc4454077cb8d65b537d368d633137e0e
Tested PR commit: 17abdf8c0cbe1d76ced026f252047655c52f27f2
Compare commits: 3cec5e6...17abdf8

[jedel1043]

Yep, sounds like the correct approach

[abhinavs1920]

Heyyy @jedel1043, can you have a quick look when you're available? 👀

[jedel1043]

It might be better to start integrating the try-finally semantics in this PR instead of postponing it to a separate phase, because a lot of the new code here will have to be adjusted (or even removed) when integrating that.

[abhinavs1920]

Heyyy,

I was thinking more about this and I feel like the current approach with static counting + emitting DisposeResources at block exit isn’t going to hold up once we integrate try/finally.

Since disposal needs to run on all exits (exceptions, early returns, etc.), it seems like we’ll need to move closer to the jump-control / handler-based approach anyway.

What I’m considering is:

• removing the using_count logic from block.rs
• instead pushing a JumpControlInfo when entering a block that has using declarations (similar to how try works)
• wrapping the block body with a handler
• and routing all exits (return, break, continue, throw) through disposal via the jump table

Would push a update soon!! :)

[abhinavs1920]

Quick update: everything looks good on my side, try/finally is working and all tests pass (including the new exception cases).

I did notice one issue though. Using inside function bodies works fine in tests (via eval), but it panics when run through the CLI. The panic points to mod.rs:90, and it looks like a binding index mismatch.

Since all tests pass, I’m guessing this is due to a difference between how eval and top-level code are compiled.

Let me know you thoughts on this...