# What This PR Does
Enhance's `oxc_semantic`'s integration tests with a regression test suite that ensures semantic's contract guarantees hold over all test cases in typescript-eslint's scope snapshot tests. Each test case checks a separate assumption and runs independently from other test cases.
This PR sets up the code infrastructure for this test suite and adds two test cases to start us off:
1. Reflexivity tests for `IdentifierReference` and `Reference`
2. Symbol declaration reflexivity tests between declarations in `SymbolTable` and their corresponding node in the AST.
Please refer to the doc comments for each of these tests for an in-depth explanation.
## Aren't our existing tests sufficient?
`oxc_semantic` is currently tested directly via
1. scope snapshot tests, ported from `typescript-eslint`
2. Hand-written tests using `SemanticTester` in `tests/integration`
And indirectly via
3. Conformance test suite over Test262/TypeScript/Babel
4. Linter snapshot tests
Shouldn't this be sufficient? I argue not, for two reasons:
## 1. Clarify Contract Ambiguity
When using `Semantic`, I often find myself asking these questions?
* Does `semantic.symbols().get_declaration(id)` point to a `BindingIdentifer`/`BindingPattern` or the declaration that holds an identifier/pattern?
* Will a `Reference`'s `node_id` point me to an `IdentifierReference` or the expression/statement that is holding an `IdentifierReference`?
* When will `BindingIdentifier`'s `symbol_id` get populated? can we guarantee that after semantic analysis it will never be `None`?
* What actually _is_ the node covered by `semantic.symbols().get_span(id)`? This one really messed me up, and resulted in me creating #4739.
* What scope does `Function::scope_id` point to? The one where the function is declared? The one created by its body? The one created by the type annotations but before the function body? Or something else entirely?
**These test cases are meant to answer such questions and guarnatee those answers as test cases**. No other existing testing solution currently upholds such promises: they only tell us if code expecting one answer or another produces an unexpected result. However, those parts of the codebase could always be adjusted to conform to new `Semantic` behavior, meaning no contract guarantees are actually upheld.
## 2. Existing Tests Do Not Test The Same Behavior
I'll cover each above listed test case one-by-one:
1. For starters, these tests only cover scopes. Additionally, they only tell us **how behavior has changed**, not that **behavior is now incorrect**.
2. These _do_ generally cover the same behaviors, but **are not comprehensive and are difficult to maintain**. These are unit tests that should be used hand-in-hand with this new test suite.
3. The most relevant tests here are for the parser. However, these tests **only tell us if a syntax/parse error was produced**, and tell us nothing about the validity of `Semantic`.
4. Relying on lint rule's output is a a mediiocre proxy of `Semantic`'s behavior at best. They can tell us if changes to `Semantic` break assumptions made by lint rules, but they do not tell us if **those assumptions are the ones we want to uphold to external crates consuming `Semantic`.
`SymbolFlags::ArrowFunction` is an oddity, as whether a symbol is an arrow function is not statically knowable. In the following cases, `f` symbol did not have `ArrowFunction` flag set:
```js
const {f} = {f: () => {}};
```
```js
let f = 123;
f = () => {};
```
`SymbolFlags::ArrowFunction` is therefore not particularly useful, and possibly misleading. Having it complicates the transformer, and it's not used anywhere in Oxc.
This PR removes it.
Realized we can get the source type from the AST.
The next PR will introduce `unambiguous` to `SourceType` and directly set `Program::source_type` to either `script` or `module`.
So far, the `ReferenceFlags::TSTypeQuery` only used indicates it is referenced by `TSTypeQuery` that we can confirm the reference should be regarded as a type reference, namely `ReferenceFlags::Type`.
This PR adds a `ReferenceFlags::ValueAsType` instead of `ReferenceFlags::TSTypeQuery`. The new flag has the same behavior as the previous one. But it looks more general and is not only used in `TSTypeQuery`. But now it is a temporary flag. We use it to resolve the symbol correctly and replace `ReferenceFlags::ValueAsTyoe` with `ReferenceFlags::Type` after resolved.
Also, this change eliminates the inconsistency in behavior between the `Reference::is_type` and `ReferenceFlags::is_type` methods.
close: #5435
The behavior of `IdentifierReference` in `TSPropertySignature` is the same as in `TSTypeQuery`, both allow only reference value bindings and type-only import bindings.
I still use `ReferenceFlags::TSTypeQuery` here because I want to avoid producing many changes unrelated to the bug in this PR. I will refactor it in the follow-up PR soon
Closes#5177
While making this, I noticed an uncaught parse error for accessors: accessors cannot be optional. I'll add a fix for this in an up-stack PR.
Previously `ScopeTree::get_child_ids` and `ScopeTree::get_child_ids_mut` returned an `Option`. Instead return the unwrapped value, in line with other methods e.g. `get_flags`.
There are many cases in lint rules where we want to see if a symbol is a
function by checking its SymbolFlags. This is currently not fully possible,
since variables assigned to arrow functions are not distinguished from any other
kind of variable. This PR adds `SymbolFlags::ArrowFunction` for variables that
are initialized to arrow functions. Symbols that are re-assigned to arrow
functions will not have this flag, but this is acceptable for lint rules.
> Re-creation of #4427 due to rebasing issues. Original attempt: #642
-----
Third time's the charm?
Each time I attempt this rule, I find a bunch of bugs in `Semantic`, and I expect this attempt to be no different. Expect sidecar issues+PRs stemming from this PR here.
## Not Supported
These are cases supported in the original eslint rule, but that I'm intentionally deciding not to support
- export comments in scripts
```js
/* exported a */ var a;
```
- global comments
```js
/* global a */ var a;
```
## Behavior Changes
These are intentional deviations from the original rule's behavior:
- logical re-assignments are not considered usages
```js
// passes in eslint/no-unused-vars, fails in this implementation
let a = 0; a ||= 1;
let b = 0; b &&= 2;
let c = undefined; c ??= []
```
## Known Limitations
- Lint rules do not have babel or tsconfig information, meaning we can't determine if `React` imports are being used or not. The relevant tsconfig settings here are `jsx`, `jsxPragma`, and `jsxFragmentName`. To accommodate this, all imports to symbols named `React` or `h` are ignored in JSX files.
- References to symbols used in JSDoc `{@link}` tags are not created, so symbols that are only used in doc comments will be reported as unused. See: #4443
- `.vue` files are skipped completely, since variables can be used in templates in ways we cannot detect
> note: `.d.ts` files are skipped as well.
## Todo
- [x] Skip unused TS enum members on used enums
- [x] Skip unused parameters followed by used variables in object/array spreads
- [x] Re-assignments to array/object spreads do not respect `destructuredArrayIgnorePattern` (related to: https://github.com/oxc-project/oxc/issues/4435)
- [x] #4493
- [x] References inside a nested scope are not considered usages (#4447)
- [x] Port over typescript-eslint test cases _(wip, they've been copied and I'm slowly enabling them)_
- [x] Handle constructor properties
```ts
class Foo {
constructor(public a) {} // `a` should be allowed
}
```
- [x] Read references in sequence expressions (that are not in the last position) should not count as a usage
```js
let a = 0; let b = (a++, 0); console.log(b)
```
> Honestly, is anyone even writing code like this?
- [x] function overload signatures should not be reported
- [x] Named functions returned from other functions get incorrectly reported as unused (found by @camc314)
```js
function foo() {
return function bar() { }
}
Foo()()
```
- [x] false positive for TS modules within ambient modules
```ts
declare global {
// incorrectly marked as unused
namespace jest { }
}
```
## Blockers
- https://github.com/oxc-project/oxc/issues/4436
- https://github.com/oxc-project/oxc/issues/4437
- #4446
- #4447
- #4494
- #4495
## Non-Blocking Issues
- #4443
- #4475 (prevents checks on exported symbols from namespaces)
```ts
type T = 0;
export { T }
^ ReferenceFlags::Type | ReferenceFlags::Read
```
The export `T` only referenced type binding. We should remove `ReferenceFlags::Read` for it.
The code changes in `builder.rs` optimize the export flag check in the `SemanticBuilder` implementation. Instead of setting the export flag to `true` for all cases except `ExportDefaultDeclarationKind::ClassDeclaration(ref class)`, the flag is now set to `true` only for `ExportDefaultDeclarationKind::ClassDeclaration` and `false` for all other cases. This change improves the efficiency of the export flag check.
> Part of #4445
Fixes a bug where non-exported functions and variables inside of
exported TS namespaces were being flagged with `SymbolFlags::Export`
```ts
export namespace Foo {
// incorrectly flagged as exported
function foo() { }
}
```
