Use JSDoc comments in `build.mjs` and related scripts to provide type hints and better intellisense. I was having a hard time knowing what fields are available in different methods, and I found this quite helpful. I'm sure other newcomers to this part of our codegen infrastructure will find it helpful as well.
Revert the changes to `oxc_traverse` made in #5577.
Those changes may well have been good, but...
The soundness of `Traverse` is a finely balanced thing, and the pointer gymnastics are subtle, so I think it's best to be extremely conservative about changes. I last ran Miri on it with the original formulation (`as *mut _` etc) and it passed. Currently it's not possible to usefully run Miri on the transformer because it contains known unsound code (#3483). So until we're able to check soundness with Miri, I think it's best to avoid changes, as it'd be easy to trigger UB unintentionally.
Make the `Ancestor` type used in `oxc_traverse` an owned type. Instead of `TraverseCtx::parent` returning a `&'t Ancestor<'a>`, it now returns an `Ancestor<'a, 't>`.
This allows `Ancestor` to be `Copy`.
The `'t` lifetime plays the same role in both cases - preventing any `Ancestor` from escaping from the `enter_*` / `exit_*` method in which it's obtained.
Same for the `*Without*` types which are `Ancestor` enum's "payloads". Any AST node references obtained from an `Ancestor` are also constrained by same `'t` lifetime - e.g. `&'t Statement<'a>`.
Codegen `ChildScopeCollector`, so that if more types have scopes added, we don't forget to add them (like the problem #5118 fixed).
The methods are in different order in the generated version, but otherwise identical to before this PR.
`visit_finally_clause` has to be added manually, as `oxc_traverse` codegen does not read or understand `#[visit(as)]` attrs.
`Atom`, `SourceType` and `Span` from `oxc_span`, and operators from `oxc_syntax` are now re-exported from `oxc_ast` crate. Remove unnecessary `use` statements by importing them all from `oxc_ast`.
Move generated files in `oxc_traverse` crate into separate folder, to match `ast_tools`.
Also amend the header on generated files to match files generated by `ast_tools`.
Closes#5008.
There are no longer any nodes with conditional scopes. Remove support for `#[scope(if(...))]` attr from `oxc_traverse` codegen - it's no longer needed.
Closes#4200.
Align `Traverse`'s behavior with `Visit` and `VisitMut`. For types with scopes, call `enter_*` before entering scope, and call `exit_*` after exiting scope.
Separate out attributes which communicate info to codegen related to scopes into `#[scope]` attr.
Before:
```rs
#[visited_node(scope(ScopeFlags::empty()))]
pub struct BlockStatement<'a> { /* ... */ }
```
After:
```rs
#[visited_node]
#[scope]
pub struct BlockStatement<'a> { /* ... */ }
```
I think this is clearer.
Improve annotation of AST types for codegen.
Currently:
```rs
#[visited_node(
scope(ScopeFlags::empty()),
enter_scope_before(cases),
)]
pub struct SwitchStatement<'a> {
pub span: Span,
pub discriminant: Expression<'a>,
pub cases: Vec<'a, SwitchCase<'a>>,
pub scope_id: Cell<Option<ScopeId>>,
}
```
After this PR:
```rs
#[visited_node(scope(ScopeFlags::empty()))]
pub struct SwitchStatement<'a> {
pub span: Span,
pub discriminant: Expression<'a>,
#[scope(enter_before)]
pub cases: Vec<'a, SwitchCase<'a>>,
pub scope_id: Cell<Option<ScopeId>>,
}
```
I think this is easier to read.
In order to enable use of `#[scope]` attr, this introduces a dummy `VisitedNode` derive macro. Like the `visited_node` macro, `VisitedNode` derive macro is designed to do very minimal work and have no heavy dependencies, so it should be almost 0 cost in terms of compile time.
Pass `&mut TraverseCtx` to `Traverse::enter_*` and `Traverse::exit_*` visitor methods. Previously was immutable `&TraverseCtx`.
This is a step towards exposing mutable scope tree + symbol table to visitors.
`Traverse` use `Semantic` to construct scopes tree and expose it to visitors via `TraverseCtx`.
Currently scopes tree is immutable. Will expose it as a mutable in a follow-on.
This is extremely inefficient. Semantic does all kinds of stuff (control flow graph etc) which `Traverse` doesn't need, and `Traverse` just throws away all that work after semantic has done it. Intent here is to get a working implementation first, and then to do another pass later on to improve performance.
Add scope flags to `TraverseCtx`.
Closes#3189.
`walk_*` functions build a stack of `ScopeFlags` as AST is traversed, and they can be queried from within visitors with `ctx.scope()`, `ctx.ancestor_scope()` and `ctx.find_scope()`.
The codegen which generates `walk_*` functions gets the info about which AST types have scopes, and how to check for strict mode from the `#[visited_node]` attrs on AST type definitions in `oxc_ast`.
A few notes:
Each scope inherits the strict mode flag from the level before it in the stack, so if you need to know "am I in strict mode context here?", `ctx.scope().is_strict_mode()` will tell you - no need to travel back up the stack to find out.
Scopes do *not* inherit any other flags from level before it. So `ctx.scope()` in a block nested in a function will return `ScopeFlags::empty()` not `ScopeFlags::Function`.
I had to add an extra flag `ScopeFlags::Method`. The reason for this is to deal with when a `Function` is actually a `MethodDefinition`, and to avoid creating 2 scopes in this case. The principle I'm trying to follow is to encode as little logic in the codegen as possible, as it's rather hidden away. Instead the codegen follows a standard logic for every node, guided by attributes which are visible next to the types in `oxc_ast`. This hopefully makes how `Traverse`'s visitors are generated less mysterious, and easier to change.
The case of `Function` within `MethodDefinition` is a weird one and would not be possible to implement without encoding a magic "special case" within the codegen without this extra `ScopeFlags::Method` variant. Its existence does not alter the operation of any other code in Oxc which uses `ScopeFlags`.
In my view `ScopeFlags` might benefit from a little bit of an overhaul anyway. I believe we could pack more information into the bits and make it more useful.
Make the code for `retag_stack` in `walk_*` functions more
comprehensible, by replacing hard-coded enum discriminants as integers
with an `AncestorType` type.
Alternative solution to the problem raised in #3170.
close: #3170
First part of #3152.
This adds a crate `oxc_traverse`, but doesn't connect it up to the
transformer or anything else yet.
I think we could merge this now - as it doesn't affect any code that's
in use - and then iterate on it to add scopes before using it in
transformer. Please see
https://github.com/oxc-project/oxc/pull/3152#issuecomment-2094965406 for
the broader picture.
