feat: add support for `:scope` selector

See https://developer.mozilla.org/en-US/docs/Web/CSS/:scope

This selector would allow queries to limit the matching to only the direct children of the AST on which the query is run.

For example, in the following code:

const x = function() {
  function y() {
    return 'bar';
  }
  return 'foo';
};

How do you query for just the outer function’s return statement? Currently the query ReturnStatement will return both return statements even if it is run on the Block node that is the body of the outer function.

With the :scope selector you would be able to use :scope > ReturnStatement and then run that on the body of the outer function to only return the outer ReturnStatement.

ESQuery has a PR for adding this already https://github.com/estools/esquery/pull/61

[phenomnomnominal]

Ah yep, too right. Once their PR gets merged and released I can port over the matcher and the tests too.

[cancerberoSgx]

If I’m understanding this correctly, I think:root would be the same as SourceFile?. Example, SourceFile>FunctionDeclaration will select root function declarations while FunctionDeclaration will select all.Or an I missing something ?

About the question, you select the outer ReturnStatement like this: FunctionExpression >Block > * > ReturnStatement. Or more specific: SourceFile>FunctionExpression >Block > * > ReturnStatement.

The ‘*’ would be a SyntaxList but seems is treated specially and you cannot mention it in the query (i.e this works: FunctionExpression >Block > SyntaxList, this won’t work: FunctionExpression >Block > SyntaxList *)

About :scope , IMO, in the context of JavaScript it could be confused with a symbol scope. My two cents