feat(linter/plugins): support selectors DSL

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--) {