feat: add support for `:scope` selector

[petebacondarwin]

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 estools/esquery#61

[petebacondarwin]

Of course since tsquery uses esquery to parse the query strings, it will be tricky to fix this until esquery supports it too...

[phenomnomnominal]

Yeah that's a great idea, and their implementation looks solid. I'll give the ESQuery team a little while to see if they respond to the comments, but then will definitely look at moving the parser into TSQuery (hopefully temporarily)

[petebacondarwin]

Great! Happy to create PR(s) as necessary. Just give me the nod.

[phenomnomnominal]

I had a go at adding unit tests to the PR in ESQuery, but other tests were failing and I don't have time to dig into them right now 😕

@petebacondarwin do you reckon it's worth fixing it up their side, or should we try to do it directly in TSQuery?

[run1t]

It would be very helpful to be able to use the :scope selector.
Any news about this ?

[run1t]

I added some very basic unit tests to the PR in ESQuery, where should I do the pull requests ?
Do I have to create another one on https://github.com/estools/esquery or do I have to pull request directly in this one: https://github.com/jupenur/esquery ?

If you have anothers tests in mind I'll be glad to add them.
You can see my branch here: https://github.com/run1t/esquery/tree/scope-root-tests

[phenomnomnominal]

Thank you so much for your work on this! I'm not really sure how the PR should work, you could just do it against esquery and see what happens? Might be more direct that way. I guess they'll tell you if it doesn't work right.

I'd probably suggest adding another test for the use case mentioned in the original issue here as well, just to make sure we're solving the original request?

[run1t]

I'll add the test for the use case described above and I'll create a new pull request against esquery directly 😃

[run1t]

If the pull request is accepted and a new version is published, what would be the next steps (beside updating the ESquery version in package.json)?

[phenomnomnominal]

Just updating the version and then publishing it 😊

[run1t]

Unfortunately it does not seem so easy 😢

• I published the branch on npm : https://www.npmjs.com/package/esquery-scope
• I updated the package.json on tsquery

but I have this error when I run the tests:

tsquery: › tsquery - :has: › should find any nodes with multiple attributes

    Unknown selector type: scope

      33 |     }
      34 |
    > 35 |     throw new Error(`Unknown selector type: ${selector.type}`);
         |           ^
      36 | }
      37 |

The tests below are failing with the same error:

• tsquery: › tsquery - :has: › should find any nodes with multiple attributes
• tsquery: › tsquery - :has: › should find any nodes with one of multiple attributes
• tsquery: › tsquery - :has: › should handle chained :has selectors
• tsquery: › tsquery - :has: › should handle nested :has selectors

Do you have any ideas on why it's failing ?

[run1t]

It's seems that a new matcher is needed in this file:

tsquery/src/matchers/index.ts

Lines 1 to 34 in 07baf37

	// Dependencies:
	import { TSQueryMatchers } from '../tsquery-types';
	// Matches:
	import { attribute } from './attribute';
	import { child } from './child';
	import { classs } from './class';
	import { descendant } from './descendant';
	import { field } from './field';
	import { has } from './has';
	import { identifier } from './identifier';
	import { matches } from './matches';
	import { not } from './not';
	import { nthChild, nthLastChild } from './nth-child';
	import { adjacent, sibling } from './sibling';
	import { wildcard } from './wildcard';
	export const MATCHERS: TSQueryMatchers = {
	adjacent,
	attribute,
	child,
	compound: matches('every'),
	'class': classs,
	descendant,
	field,
	'nth-child': nthChild,
	'nth-last-child': nthLastChild,
	has,
	identifier,
	matches: matches('some'),
	not,
	sibling,
	wildcard
	};

[phenomnomnominal]

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