feat: Move getDeclaredVariables and getAncestors to SourceCode

[nzakas]

Prerequisites checklist

• I have read the contributing guidelines.

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

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[x] 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)

This copies getDeclaredVariables() and getAncestors() to the SourceCode class as a continuation of the work for the language plugins. I updated all existing rules to use the new methods.

I also updated getAncestors() to cache its results. It's a little bit surprising that we weren't already doing caching here and just continued to calculate ancestry on every call. I also made the logic a little more efficient by removing the unnecessary call to .reverse().

Refs #16999

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

Did I miss any references?

[netlify]

✅ Deploy Preview for docs-eslint canceled.

Name	Link
🔨 Latest commit	4e0c4df
🔍 Latest deploy log	https://app.netlify.com/sites/docs-eslint/deploys/642f043414670400084b2542

[mdjermanovic]

Suggested change

	* Gets all of the declared variables in the scope represented
	* by `node`. This is a convenience method that passes through
	* Gets all of the variables declared by `node`.
	* This is a convenience method that passes through

I think "in the scope represented by node" would be confusing. For example, for function declarations, this returns variables for the function name and function parameters. The function name variable is not in the scope represented by node but in the parent scope. Also, variables declared at the top level of the function's body are directly in the scope represented by node, but this doesn't return them.

[nzakas]

While that is true, that seems like an edge case and otherwise the statement is accurate. I don't think "declared by node" is accurate, as the node isn't doing any declaring. We use the node to look up the scope, and then look for variables in that scope. So, the scope associated with the node is where we look. Maybe I'll just replace "represented" with "associated"?

[mdjermanovic]

We use the node to look up the scope, and then look for variables in that scope. So, the scope associated with the node is where we look.

I still think the description would be confusing as it suggests that this returns all variables from the scope, but this returns only those that the given node creates.

For example:

{ // `blockStatement` node
    let a, b; // `variableDeclaration1` node
    let c, d; // `variableDeclaration2` node
}

This is a block scope associated with the blockStatement node, variables a b c d are declared in that block scope, but getDeclaredVariables(blockStatement) returns an empty array. getDeclaredVariables(variableDeclaration1) returns [a, b] (Variable objects for a and b), getDeclaredVariables(variableDeclaration2) returns [c, d].

description in eslint-scope also uses wording "declared by the node".

[snitin315]

How about this:

/**
 * Gets variables declared directly by the provided node.
 * This method looks up the scope associated with the node and returns only variables declared within that scope by the node itself.
 * This may not include variables declared in parent or child scopes. If the node declares nothing, this method returns an empty array.
 * @param {ASTNode} node - The node to use for scope lookup.
 * @returns {Array<Variable>} - An array of variable nodes representing declared variables directly within the scope associated with the provided node.
 */
   getDeclaredVariables(node) {
        return this.scopeManager.getDeclaredVariables(node);
    }

[mdjermanovic]

Technically, it doesn't look up the scope but gets the variables from the cache by that particular node. When traversing a node that creates variables, eslint-scope creates variable objects, caches them for that node, and inserts them into appropriate scope(s). For FunctionDeclaration, named FunctionExpression and ClassDeclaration nodes, getDeclaredVariables() returns variables from multiple scopes.

[nzakas]

@mdjermanovic Keep in mind that eslint-scope was not written by a native English speaker, so I'm not sure that's really what we should be using as the source of truth in this case.

I'm not sure it's actually worth debating this given how few people will actually ever read these comments. Maybe let's just leave it as-is so we can merge the functionality?

[mdjermanovic]

Agreed, we can discuss this in a follow-up. My concern is that someone reading these descriptions might think that sourceCode.getDeclaredVariables(node) is the same as sourceCode.getScope(node).variables, which isn't true.

[mdjermanovic]

Suggested change

	* @returns {Array<Variable>} An array of variable nodes representing
	* the declared variables in the scope.
	* @returns {Array<Variable>} An array of variables declared by `node`.

Same as above.

[mdjermanovic]

LGTM, thanks!