feat: Implement SourceCode#markVariableAsUsed()

[nzakas]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[ ] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[x] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Implements SourceCode#markVariableAsUsed() and sets context.markVariableAsUsed() to use it.

Refs #16999

Is there anything you'd like reviewers to focus on?

I'm not sure of how I implemented this method. I started out by passing in an Identifier node because we can use that to get the scope and determine if it's a declared variable. This also seemed like it would be the most developer-friendly.

Based on my feedback from @ljharb, I change it to accept a string and optionally a node. I'd like some more feedback on whether this makes sense.

[netlify]

👷 Deploy Preview for docs-eslint processing.

Name	Link
🔨 Latest commit	6a24d06
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/6438563535794400086d55e2

[netlify]

✅ Deploy Preview for docs-eslint ready!

Name	Link
🔨 Latest commit	12019f8
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/64419aa6d3fa99000723ef7d
😎 Deploy Preview	https://deploy-preview-17086--docs-eslint.netlify.app/extend/custom-rules
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[ljharb]

We're currently doing context.markVariableAsUsed() in 3 places across 2 rules - jsx-uses-react (which only applies to those not using the new React jsx runtime), and jsx-uses-vars (which continues to apply to jsx). All 3 use cases do indeed pass a string - 1 of them has an AST node available, but the other 2 provide a string only, from eslint settings, so I'm not sure what I'd have to do to make that work.

What's the benefit of this change, though? Whether a variable is used or not seems very context-dependent to me, more than just the static source code can know.

[nzakas]

This is part of the work for #16999. In order to allow ESLint to lint other languages, we need to remove anything that is JS-specific from context and move it to SourceCode. So context will become a language-neutral access point for ESLint functionality and anything specific to the code being linted will end up SourceCode. Most functionality is already on SourceCode, we just got a bit lazy with defining where these methods go.

What I'm interested in knowing about eslint-plugin-react's usage is whether or not you have an Identifier node related to the variable you're marking as read? I just don't want to implement something that makes it impossible for you to switch to the new API.

[ljharb]

No, for the cases where it's a string from settings (like "React" or "createElement" or something), we have no nodes at all, and this change would presumably force us to add some visitors to locate the nodes.

[nzakas]

Okay, that's what I needed to know. I'll change the API to be markVariableAsUsed(string, refNode) to better match what we already have.

[mdjermanovic]

This looks like a breaking change because custom scope managers are not required to provide these methods.

In the parseForESLint interface specification, we require parsers to return a ScopeManager object whose interface doesn't mention isGlobalReturn() and lists isModule() as deprecated and not used in ESLint:

eslint/docs/src/extend/scope-manager-interface.md

Lines 43 to 51 in f57eff2

	### Deprecated members
	Those members are defined but not used in ESLint.
	#### isModule()
	* **Parameters:**
	* **Return type:** `boolean`
	* **Description:** `true` if this program is module.

[mdjermanovic]

I think the goal here is just, when the Program node is passed, to return the innermost top-level scope instead of the outermost (global) scope that getScope() returns, so if we want to avoid analyzing configured language options, perhaps we could check the scopes directly:

const initialScope = currentScope.type === "global" && currentScope.childScopes.length > 0 && currentScope.childScopes[0].block === this.ast
            ? currentScope.childScopes[0]
            : currentScope;

or maybe do something like this:

const initialScope = refNode === this.ast
            ? this.scopeManager.acquire(refNode, /* inner = */ true)
            : this.getScope(refNode);

[nzakas]

Ah, that's brilliant. I'll update the logic.

[mdjermanovic]

There's a merge conflict now.

[nzakas]

Yup, updating the docs now.

[mdjermanovic]

LGTM, thanks!