feat(linter/plugins): support selectors DSL (#14435)

Implement support for selectors DSL in Oxlint JS plugins.

The implementation is based on ESLint's implementation. Like ESLint, it uses [esquery](https://www.npmjs.com/package/esquery) as the underlying selector parser and matcher.

One detail is not implemented. ESLint ensures that visit functions are called in order of their "specificity" with the most specific called first. This implementation just calls them in the order they're defined. This is a shortcoming and will need to be fixed in future, but I imagine that in practice visitation order makes no difference for the vast majority of rules.

I've made what I hope are some optimizations versus ESLint's version. Notably:

1. Making simple selectors which unconditionally visit a subset of nodes (e.g. `:matches(FunctionDeclaration, FunctionExpression)` bypass the selector match process - as it'd always return `true` anyway.
2. Faster implementations of union and intersection.

Author: overlookmotel

apps/oxlint/package.json

@@ -36,7 +36,10 @@
     "dist"
   ],
   "devDependencies": {
+    "@types/esquery": "^1.5.4",
+    "@types/estree": "^1.0.8",
     "eslint": "^9.36.0",
+    "esquery": "^1.6.0",
     "execa": "^9.6.0",
     "jiti": "^2.6.0",
     "tsdown": "^0.15.5",

apps/oxlint/src-js/generated/type_ids.ts

@@ -174,3 +174,4 @@ export const NODE_TYPE_IDS_MAP = new Map([
 
 export const NODE_TYPES_COUNT = 165;
 export const LEAF_NODE_TYPES_COUNT = 27;
+export const FUNCTION_NODE_TYPE_IDS = [30, 55, 56];

apps/oxlint/src-js/generated/visitor.d.ts

@@ -380,4 +380,5 @@ export interface VisitorObject {
   'TSTypeReference:exit'?: (node: ESTree.TSTypeReference) => void;
   TSUnionType?: (node: ESTree.TSUnionType) => void;
   'TSUnionType:exit'?: (node: ESTree.TSUnionType) => void;
+  [key: string]: (node: ESTree.Node) => void;
 }

apps/oxlint/src-js/plugins/selector.ts

@@ -0,0 +1,203 @@
+import esquery from 'esquery';
+import visitorKeys from '../generated/keys.js';
+import { FUNCTION_NODE_TYPE_IDS, NODE_TYPE_IDS_MAP } from '../generated/type_ids.js';
+// @ts-expect-error we need to generate `.d.ts` file for this module
+import { ancestors } from '../generated/walk.js';
+
+import type { ESQueryOptions, Selector as EsquerySelector } from 'esquery';
+import type { Node as EsqueryNode } from 'estree';
+import type { Node, VisitFn } from './types.ts';
+
+const ObjectKeys = Object.keys;
+
+const { matches: esqueryMatches, parse: esqueryParse } = esquery;
+
+type NodeTypeId = number;
+
+// Options to call `esquery.matches` with.
+const ESQUERY_OPTIONS: ESQueryOptions = {
+  nodeTypeKey: 'type',
+  visitorKeys,
+  fallback: (node: EsqueryNode) => ObjectKeys(node).filter(filterKey),
+  matchClass: (_className: unknown, _node: EsqueryNode, _ancestors: EsqueryNode[]) => false, // TODO: Is this right?
+};
+const filterKey = (key: string) => key !== 'parent' && key !== 'range' && key !== 'loc';
+
+// Parsed selector.
+interface Selector {
+  // Array of IDs of types this selector matches, or `null` if selector matches all types.
+  typeIds: NodeTypeId[] | null;
+  // `esquery` selector object for this selector.
+  esquerySelector: EsquerySelector;
+  // `true` if selector applies matching beyond just filtering on node type.
+  // * `FunctionExpression > Identifier` is complex.
+  // * `:matches(FunctionExpression, FunctionDeclaration)` is not complex.
+  // Primarily this exists to make simple `:matches` faster.
+  isComplex: boolean;
+  // Number of attributes in selector. Used for calculating selector's specificity.
+  attributeCount: number;
+  // Number of identifiers in selector. Used for calculating selector's specificity.
+  identifierCount: number;
+}
+
+// Cache of parsed `Selector`s.
+const cache: Map<string, Selector> = new Map([]);
+
+const EMPTY_TYPE_IDS_ARRAY: NodeTypeId[] = [];
+
+/**
+ * Parse a selector string and return a `Selector` object which represents it.
+ *
+ * @param key - Selector string e.g. `Program > VariableDeclaration`
+ * @returns `Selector` object
+ */
+export function parseSelector(key: string): Selector {
+  // Used cached object if we've parsed this key before
+  let selector = cache.get(key);
+  if (selector !== void 0) return selector;
+
+  // Parse with `esquery` and analyse
+  const esquerySelector = esqueryParse(key);
+
+  selector = {
+    typeIds: null,
+    esquerySelector,
+    isComplex: false,
+    attributeCount: 0,
+    identifierCount: 0,
+  };
+  selector.typeIds = analyzeSelector(esquerySelector, selector);
+
+  // Store in cache for next time
+  cache.set(key, selector);
+
+  return selector;
+}
+
+/**
+ * Analyse an `EsquerySelector` to determine:
+ *
+ * 1. What node types it matches on.
+ * 2. Whether it is "simple" or "complex" - "simple" matches a subset of node types without further conditions.
+ * 3. It's specificity (number of identifiers and attributes).
+ *
+ * This function traverses the `EsquerySelector` and calls itself recursively.
+ * It returns an array of node type IDs which the selector may match.
+ *
+ * @param esquerySelector - `EsquerySelector` to analyse.
+ * @param selector - `Selector` which has its `isSimple`, `attributeCount`, and `identifierCount` updated.
+ * @returns Array of node type IDs the selector matches, or `null` if it matches all nodes.
+ */
+function analyzeSelector(esquerySelector: EsquerySelector, selector: Selector): NodeTypeId[] | null {
+  switch (esquerySelector.type) {
+    case 'identifier': {
+      selector.identifierCount++;
+
+      const typeId = NODE_TYPE_IDS_MAP.get(esquerySelector.value);
+      // If the type is invalid, just treat this selector as not matching any types.
+      // But still increment `identifierCount`.
+      // This matches ESLint's behavior.
+      return typeId === void 0 ? EMPTY_TYPE_IDS_ARRAY : [typeId];
+    }
+
+    case 'not':
+      for (let i = 0, childSelectors = esquerySelector.selectors, len = childSelectors.length; i < len; i++) {
+        analyzeSelector(childSelectors[i], selector);
+      }
+      selector.isComplex = true;
+      return null;
+
+    case 'matches': {
+      // OR matcher. Matches a node if any of child selectors matches it.
+      let nodeTypes: NodeTypeId[] | null = [];
+      for (let i = 0, childSelectors = esquerySelector.selectors, len = childSelectors.length; i < len; i++) {
+        const childNodeTypes = analyzeSelector(childSelectors[i], selector);
+        if (childNodeTypes === null) {
+          nodeTypes = null;
+        } else if (nodeTypes !== null) {
+          nodeTypes.push(...childNodeTypes);
+        }
+      }
+      if (nodeTypes === null) return null;
+      // De-duplicate
+      // TODO: Faster way to do this? Sort and then dedupe manually?
+      return [...new Set(nodeTypes)];
+    }
+
+    case 'compound': {
+      // AND matcher. Only matches a node if all child selectors match it.
+      const childSelectors = esquerySelector.selectors,
+        len = childSelectors.length;
+      // TODO: Can `childSelectors` have 0 length?
+      if (len === 0) return [];
+
+      let nodeTypes: NodeTypeId[] | null = null;
+      for (let i = 0; i < len; i++) {
+        const childNodeTypes = analyzeSelector(childSelectors[i], selector);
+
+        // If child selector matches all types, does not narrow the types the selector matches
+        if (childNodeTypes === null) continue;
+
+        if (nodeTypes === null) {
+          // First child selector which matches specific types
+          nodeTypes = childNodeTypes;
+        } else {
+          // Selector only matches intersection of all child selectors.
+          // TODO: Could make this faster if `analyzeSelector` always returned an ordered array.
+          nodeTypes = childNodeTypes.filter(nodeType => nodeTypes.includes(nodeType));
+        }
+      }
+      return nodeTypes;
+    }
+
+    case 'attribute':
+    case 'field':
+    case 'nth-child':
+    case 'nth-last-child':
+      selector.isComplex = true;
+      selector.attributeCount++;
+      return null;
+
+    case 'child':
+    case 'descendant':
+    case 'sibling':
+    case 'adjacent':
+      selector.isComplex = true;
+      analyzeSelector(esquerySelector.left, selector);
+      return analyzeSelector(esquerySelector.right, selector);
+
+    case 'class':
+      // TODO: Should TS function types be included in `FUNCTION_NODE_TYPE_IDS`?
+      // This TODO comment is from ESLint's implementation. Not sure what it means!
+      // TODO: Abstract into JSLanguage somehow.
+      if (esquerySelector.name === 'function') return FUNCTION_NODE_TYPE_IDS;
+      selector.isComplex = true;
+      return null;
+
+    case 'wildcard':
+      return null;
+
+    default:
+      selector.isComplex = true;
+      return null;
+  }
+}
+
+/**
+ * Wrap a visit function so it's only called if the provided `EsquerySelector` matches the AST node.
+ *
+ * IMPORTANT: Selector matching will only be correct if `ancestors` from `generated/walk.js`
+ * contains the ancestors of the AST node passed to the returned visit function.
+ * Therefore, the returned visit function can only be called during AST traversal.
+ *
+ * @params visitFn - Visit function to wrap
+ * @params esquerySelector - `EsquerySelector` object
+ * @returns Wrapped visit function
+ */
+export function wrapVisitFnWithSelectorMatch(visitFn: VisitFn, esquerySelector: EsquerySelector): VisitFn {
+  return (node: Node) => {
+    if (esqueryMatches(node as unknown as EsqueryNode, esquerySelector, ancestors, ESQUERY_OPTIONS)) {
+      visitFn(node);
+    }
+  };
+}

apps/oxlint/src-js/plugins/visitor.ts

@@ -73,6 +73,7 @@
 // it will avoid full GC runs, which should greatly improve performance.
 
 import { LEAF_NODE_TYPES_COUNT, NODE_TYPE_IDS_MAP, NODE_TYPES_COUNT } from '../generated/type_ids.js';
+import { parseSelector, wrapVisitFnWithSelectorMatch } from './selector.js';
 
 import type { CompiledVisitorEntry, EnterExit, Node, VisitFn, Visitor } from './types.ts';
 
@@ -212,17 +213,49 @@ export function addVisitorToCompiled(visitor: Visitor): void {
   for (let i = 0; i < keysLen; i++) {
     let name = keys[i];
 
-    const visitFn = (visitor as { [key: string]: VisitFn })[name];
+    let visitFn = visitor[name];
     if (typeof visitFn !== 'function') {
       throw new TypeError(`'${name}' property of visitor object is not a function`);
     }
 
     const isExit = name.endsWith(':exit');
     if (isExit) name = name.slice(0, -5);
 
-    const typeId = NODE_TYPE_IDS_MAP.get(name);
-    if (typeId === void 0) throw new Error(`Unknown node type '${name}' in visitor object`);
-    addVisitFn(typeId, isExit, visitFn);
+    // TODO: Combine the two hashmaps `NODE_TYPE_IDS_MAP` and selectors cache into one `Map`
+    // to avoid 2 hashmap lookups for selectors?
+    let typeId = NODE_TYPE_IDS_MAP.get(name);
+    if (typeId !== void 0) {
+      // Single type visit function e.g. `Program`
+      addVisitFn(typeId, isExit, visitFn);
+      continue;
+    }
+
+    // `*` matches any node without any filtering, so no need to wrap it
+    if (name !== '*') {
+      // Selector.
+      // Parse selector.
+      // Wrap `visitFn` so it only executes if the selector matches.
+      // If selector is simple (unconditionally matches certain types e.g. `:matches(X, Y)`), skip wrapping.
+      const selector = parseSelector(name);
+      if (selector.isComplex) visitFn = wrapVisitFnWithSelectorMatch(visitFn, selector.esquerySelector);
+
+      const { typeIds } = selector;
+      if (typeIds !== null) {
+        // Selector matches a specific set of node types
+        for (let i = 0, len = typeIds.length; i < len; i++) {
+          addVisitFn(typeIds[i], isExit, visitFn);
+        }
+        continue;
+      }
+    }
+
+    // `*` selector or some other selector that matches all node types
+    for (typeId = 0; typeId < LEAF_NODE_TYPES_COUNT; typeId++) {
+      addLeafVisitFn(typeId, isExit, visitFn);
+    }
+    for (; typeId < NODE_TYPES_COUNT; typeId++) {
+      addNonLeafVisitFn(typeId, isExit, visitFn);
+    }
   }
 }
 
@@ -326,6 +359,8 @@ function addNonLeafVisitFn(typeId: number, isExit: boolean, visitFn: VisitFn): v
 export function finalizeCompiledVisitor() {
   if (hasActiveVisitors === false) return false;
 
+  // TODO: Visit functions need to be ordered by specificity of their selectors, with most specific first
+
   // Merge visit functions for node types which have multiple visitors from different rules,
   // or enter+exit functions for leaf nodes
   for (let i = mergedLeafVisitorTypeIds.length - 1; i >= 0; i--) {