/// import { isString } from "@local/eff"; import { parseForESLint } from "@typescript-eslint/parser"; import { AST_NODE_TYPES as AST, type TSESTree } from "@typescript-eslint/types"; import { simpleTraverse } from "@typescript-eslint/typescript-estree"; import { isFunction } from "@typescript-eslint/utils/ast-utils"; import path from "node:path"; import { getFixturesRootDir } from "./fixtures"; export interface ParseCodeOptions { /** * Anchor file path used for parser inference (a `.tsx` path enables JSX). * Defaults to the `estree.tsx` fixture. */ filePath?: string; /** * Passed through to the parser; when omitted, JSX support is inferred from `filePath`. */ jsx?: boolean; sourceType?: "commonjs" | "module" | "script"; } export function parseCode(code: string, options: ParseCodeOptions = {}): ReturnType { const { filePath = path.join(getFixturesRootDir(), "estree.tsx"), jsx, sourceType } = options; const parsed = parseForESLint(code, { disallowAutomaticSingleRunInference: true, ecmaVersion: "latest", filePath, sourceType: "module", tokens: true, ...(jsx == null ? {} : { jsx }), ...(sourceType == null ? {} : { sourceType }), }); // Attach parent pointers so parsed ASTs behave like the ones ESLint hands to rules simpleTraverse(parsed.ast, { enter() {} }, true); return parsed; } /** * Collects every node of the given `type` under `input`. * When `input` is a string it is parsed with `parseCode` (`options` apply); * when it is a node its subtree is traversed as-is (`options` are ignored) * and existing parent pointers are left untouched. * @param input Source code or an AST node to search. * @param type The node type to collect. * @param options Parser options, only used when `input` is a string. * @returns The matching nodes in traversal order. */ export function collectNodes(input: string | TSESTree.Node, type: T["type"], options: ParseCodeOptions = {}): T[] { const nodes: T[] = []; const isTarget = (node: TSESTree.Node): node is T => node.type === type; const root = isString(input) ? parseCode(input, options).ast : input; simpleTraverse( root, { enter(node) { if (isTarget(node)) { nodes.push(node); } }, }, ); return nodes; } /** * Returns the first node of the given `type` under `input`. * @param input Source code or an AST node to search. * @param type The node type to find. * @param options Parser options, only used when `input` is a string. * @returns The first matching node in traversal order. */ export function getFirstNodeOfType(input: string | TSESTree.Node, type: T["type"], options: ParseCodeOptions = {}): T { const [node] = collectNodes(input, type, options); if (node == null) { const hint = isString(input) ? ` in: ${input}` : " in the given subtree"; throw new Error(`No ${type} found${hint}`); } return node; } /** * Finds every Identifier named `name` that is a reference rather than a * declaration. Excluded declaration sites are: variable declarator ids, * function/class declaration ids, import specifier bindings, enum/member/ * module/type-alias declaration ids, function parameters, and non-computed * property keys. Requires parent pointers (as attached by `parseCode`) when * `input` is a node. * @param input Source code or an AST node to search. * @param name The identifier name to look for. * @param options Parser options, only used when `input` is a string. * @returns The referencing Identifier nodes in traversal order. */ export function findIdentifierReferences(input: string | TSESTree.Node, name: string, options: ParseCodeOptions = {}): TSESTree.Identifier[] { const refs: TSESTree.Identifier[] = []; const root = isString(input) ? parseCode(input, options).ast : input; simpleTraverse(root, { enter(node) { if (node.type !== AST.Identifier || node.name !== name) return; const parent: TSESTree.Node | undefined = node.parent; if (parent.type === AST.ClassDeclaration && parent.id === node) return; if (parent.type === AST.FunctionDeclaration && parent.id === node) return; if (parent.type === AST.ImportDefaultSpecifier) return; if (parent.type === AST.ImportSpecifier) return; if (parent.type === AST.Property && parent.key === node && !parent.computed) return; if (parent.type === AST.TSEnumDeclaration && parent.id === node) return; if (parent.type === AST.TSEnumMember && parent.id === node) return; if (parent.type === AST.TSModuleDeclaration && parent.id === node) return; if (parent.type === AST.TSTypeAliasDeclaration && parent.id === node) return; if (parent.type === AST.VariableDeclarator && parent.id === node) return; if (isFunction(parent) && parent.params.some((p) => p === node)) return; refs.push(node); }, }); return refs; } /** * Parses `code` and returns the expression of the first top-level * ExpressionStatement. * @param code Source code whose first statement is an expression statement. * @param options Parser options passed to `parseCode`. * @returns The expression of the first top-level ExpressionStatement. */ export function getFirstExpression(code: string, options: ParseCodeOptions = {}): TSESTree.Expression { const stmt = parseCode(code, options).ast.body[0]; if (stmt?.type !== AST.ExpressionStatement) { throw new Error(`Expected an expression statement, got: ${code}`); } return stmt.expression; } /** * Parses `code` and returns the expression of the last top-level * ExpressionStatement. * @param code Source code whose last statement is an expression statement. * @param options Parser options passed to `parseCode`. * @returns The expression of the last top-level ExpressionStatement. */ export function getLastExpression(code: string, options: ParseCodeOptions = {}): TSESTree.Expression { const stmt = parseCode(code, options).ast.body.at(-1); if (stmt?.type !== AST.ExpressionStatement) { throw new Error(`Expected last statement to be an ExpressionStatement, got ${stmt?.type ?? "unknown"}`); } return stmt.expression; } /** * Returns the source text covered by `node`'s range. * @param code The source text `node` was parsed from. * @param node The node whose text to read. * @returns The slice of `code` covered by `node`. */ export function getTextOf(code: string, node: TSESTree.Node): string { return code.slice(node.range[0], node.range[1]); }