@eslint-react/ast 5.17.3 → 5.18.0

package/dist/index.d.ts

@@ -1,53 +1,87 @@
 import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/types";
 //#region src/types.d.ts
+/** Union of function-like node types. */
 type TSESTreeFunction = TSESTree.ArrowFunctionExpression | TSESTree.FunctionDeclaration | TSESTree.FunctionExpression;
+/** Union of class-like node types. */
 type TSESTreeClass = TSESTree.ClassDeclaration | TSESTree.ClassExpression;
+/** Union of method and property definition node types. */
 type TSESTreeMethodOrPropertyDefinition = TSESTree.PropertyDefinition | TSESTree.MethodDefinition;
+/** Union of all JSX-related node types. */
 type TSESTreeJSX = TSESTree.JSXAttribute | TSESTree.JSXClosingElement | TSESTree.JSXClosingFragment | TSESTree.JSXElement | TSESTree.JSXEmptyExpression | TSESTree.JSXExpressionContainer | TSESTree.JSXFragment | TSESTree.JSXIdentifier | TSESTree.JSXMemberExpression | TSESTree.JSXNamespacedName | TSESTree.JSXOpeningElement | TSESTree.JSXOpeningFragment | TSESTree.JSXSpreadAttribute | TSESTree.JSXSpreadChild | TSESTree.JSXText;
+/** Union of JSX element-like node types (element or fragment). */
 type TSESTreeJSXElementLike = TSESTree.JSXElement | TSESTree.JSXFragment;
+/** Union of JSX attribute-like node types (attribute or spread attribute). */
 type TSESTreeJSXAttributeLike = TSESTree.JSXAttribute | TSESTree.JSXSpreadAttribute;
+/** An expression statement that is a directive (ex: `"use strict"`). */
 type TSESTreeDirective = TSESTree.ExpressionStatement & {
   directive: string;
   expression: TSESTree.StringLiteral;
 };
+/** Union of TypeScript type expression node types. */
 type TSESTreeTypeExpression = TSESTree.TSAsExpression | TSESTree.TSTypeAssertion | TSESTree.TSNonNullExpression | TSESTree.TSSatisfiesExpression | TSESTree.TSInstantiationExpression;
 declare namespace check_d_exports {
   export { is, isClass, isConditional, isDirective, isExpression, isFunction, isIdentifier, isJSX, isJSXElement, isJSXElementOrFragment, isJSXFragment, isJSXTagNameExpression, isOneOf, isProperty, isPropertyOrMethod, isTypeAssertionExpression, isTypeExpression };
 }
+/** Check if a node is of the given type. */
 declare const is: <NodeType extends AST_NODE_TYPES>(nodeType: NodeType) => (node: TSESTree.Node | null | undefined) => node is Extract<TSESTree.Node, {
   type: NodeType;
 }>;
+/** Check if a node is one of the given types. */
 declare const isOneOf: <NodeTypes extends readonly AST_NODE_TYPES[]>(nodeTypes: NodeTypes) => (node: TSESTree.Node | null | undefined) => node is Extract<TSESTree.Node, {
   type: NodeTypes[number];
 }>;
+/**
+ * Check if a node is a directive statement (ex: `"use client"`), optionally matching a specific directive name.
+ * @param node The node to check.
+ * @param name The directive name to match. When omitted, any directive matches.
+ * @returns `true` if the node is a matching directive statement.
+ */
 declare function isDirective(node: TSESTree.Node, name?: string): node is TSESTreeDirective;
+/**
+ * Check if a node is an identifier, optionally matching a specific name.
+ * @param node The node to check.
+ * @param name The identifier name to match. When omitted, any identifier matches.
+ * @returns `true` if the node is a matching identifier.
+ */
 declare function isIdentifier(node: TSESTree.Node, name?: string): node is TSESTree.Identifier;
+/** Check if a node is a class declaration or class expression. */
 declare const isClass: (node: TSESTree.Node | null | undefined) => node is TSESTree.ClassDeclarationWithName | TSESTree.ClassDeclarationWithOptionalName | TSESTree.ClassExpression;
+/** Check if a node is a function declaration, function expression, or arrow function expression. */
 declare const isFunction: (node: TSESTree.Node | null | undefined) => node is TSESTree.ArrowFunctionExpressionWithBlockBody | TSESTree.ArrowFunctionExpressionWithExpressionBody | TSESTree.FunctionDeclarationWithName | TSESTree.FunctionDeclarationWithOptionalName | TSESTree.FunctionExpression;
+/** Check if a node is a property-like node (property definition, index signature, parameter property, or property signature). */
 declare const isProperty: (node: TSESTree.Node | null | undefined) => node is TSESTree.PropertyDefinitionComputedName | TSESTree.PropertyDefinitionNonComputedName | TSESTree.TSIndexSignature | TSESTree.TSParameterProperty | TSESTree.TSPropertySignatureComputedName | TSESTree.TSPropertySignatureNonComputedName;
+/** Check if a node is a property or method definition. */
 declare const isPropertyOrMethod: (node: TSESTree.Node | null | undefined) => node is TSESTree.MethodDefinitionComputedName | TSESTree.MethodDefinitionNonComputedName | TSESTree.PropertyDefinitionComputedName | TSESTree.PropertyDefinitionNonComputedName;
+/** Check if a node is a JSX element. */
 declare const isJSXElement: (node: TSESTree.Node | null | undefined) => node is TSESTree.JSXElement;
+/** Check if a node is a JSX fragment. */
 declare const isJSXFragment: (node: TSESTree.Node | null | undefined) => node is TSESTree.JSXFragment;
+/** Check if a node is a JSX element or JSX fragment. */
 declare const isJSXElementOrFragment: (node: TSESTree.Node | null | undefined) => node is TSESTree.JSXElement | TSESTree.JSXFragment;
+/** Check if a node can appear as a JSX tag name. */
 declare const isJSXTagNameExpression: (node: TSESTree.Node | null | undefined) => node is TSESTree.JSXIdentifier | TSESTree.JSXMemberExpression | TSESTree.JSXNamespacedName;
+/** Check if a node is any JSX-related node. */
 declare const isJSX: (node: TSESTree.Node | null | undefined) => node is TSESTree.JSXAttribute | TSESTree.JSXClosingElement | TSESTree.JSXClosingFragment | TSESTree.JSXElement | TSESTree.JSXEmptyExpression | TSESTree.JSXExpressionContainer | TSESTree.JSXFragment | TSESTree.JSXIdentifier | TSESTree.JSXMemberExpression | TSESTree.JSXNamespacedName | TSESTree.JSXOpeningElement | TSESTree.JSXOpeningFragment | TSESTree.JSXSpreadAttribute | TSESTree.JSXSpreadChild | TSESTree.JSXText;
+/** Check if a node is a TypeScript type expression (assertion, non-null, satisfies, or instantiation). */
 declare const isTypeExpression: (node: TSESTree.Node | null | undefined) => node is TSESTree.TSAsExpression | TSESTree.TSInstantiationExpression | TSESTree.TSNonNullExpression | TSESTree.TSSatisfiesExpression | TSESTree.TSTypeAssertion;
+/** Check if a node is a TypeScript type assertion-like expression (as, assertion, non-null, or satisfies). */
 declare const isTypeAssertionExpression: (node: TSESTree.Node | null | undefined) => node is TSESTree.TSAsExpression | TSESTree.TSNonNullExpression | TSESTree.TSSatisfiesExpression | TSESTree.TSTypeAssertion;
+/** Check if a node is an expression node. */
 declare const isExpression: (node: TSESTree.Node | null | undefined) => node is TSESTree.ArrayExpression | TSESTree.ArrayPattern | TSESTree.ArrowFunctionExpressionWithBlockBody | TSESTree.ArrowFunctionExpressionWithExpressionBody | TSESTree.AssignmentExpression | TSESTree.AwaitExpression | TSESTree.PrivateInExpression | TSESTree.SymmetricBinaryExpression | TSESTree.CallExpression | TSESTree.ChainExpression | TSESTree.ClassExpression | TSESTree.ConditionalExpression | TSESTree.FunctionExpression | TSESTree.Identifier | TSESTree.ImportExpression | TSESTree.JSXElement | TSESTree.JSXFragment | TSESTree.BigIntLiteral | TSESTree.BooleanLiteral | TSESTree.NullLiteral | TSESTree.NumberLiteral | TSESTree.RegExpLiteral | TSESTree.StringLiteral | TSESTree.LogicalExpression | TSESTree.MemberExpressionComputedName | TSESTree.MemberExpressionNonComputedName | TSESTree.MetaProperty | TSESTree.NewExpression | TSESTree.ObjectExpression | TSESTree.ObjectPattern | TSESTree.SequenceExpression | TSESTree.Super | TSESTree.TaggedTemplateExpression | TSESTree.TemplateLiteral | TSESTree.ThisExpression | TSESTree.TSAsExpression | TSESTree.TSInstantiationExpression | TSESTree.TSNonNullExpression | TSESTree.TSSatisfiesExpression | TSESTree.TSTypeAssertion | TSESTree.UnaryExpressionBitwiseNot | TSESTree.UnaryExpressionDelete | TSESTree.UnaryExpressionMinus | TSESTree.UnaryExpressionNot | TSESTree.UnaryExpressionPlus | TSESTree.UnaryExpressionTypeof | TSESTree.UnaryExpressionVoid | TSESTree.UpdateExpression | TSESTree.YieldNoStarExpression | TSESTree.YieldStarExpression;
 /**
- * Check if a node is a conditional expression or control flow statement
- * @param node The node to check
- * @returns True if the node is conditional
+ * Check if a node is a conditional expression or a control flow statement.
+ * @param node The node to check.
+ * @returns `true` if the node is conditional.
  */
 declare const isConditional: (node: TSESTree.Node | null | undefined) => node is TSESTree.ConditionalExpression | TSESTree.DoWhileStatement | TSESTree.ForInStatement | TSESTree.ForOfStatement | TSESTree.ForStatement | TSESTree.IfStatement | TSESTree.LogicalExpression | TSESTree.SwitchStatement | TSESTree.WhileStatement;
 declare namespace compare_d_exports {
   export { isEqual };
 }
 /**
- * Check if two nodes are equal.
- * @param a node to compare.
- * @param b node to compare.
- * @returns `true` if node equal.
+ * Check if two nodes are structurally equal.
+ * @param a The first node to compare.
+ * @param b The second node to compare.
+ * @returns `true` if the nodes are equal.
  * @see https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/util/isNodeEqual.ts
  */
 declare const isEqual: {
@@ -57,17 +91,58 @@ declare const isEqual: {
 declare namespace extract_d_exports {
   export { findProperty, getCalleeName, getFullyQualifiedName, getIdentifierAt, getPropertyName, unwrap };
 }
+/**
+ * Recursively unwrap TypeScript type expressions and chain expressions to get the underlying expression.
+ * @param node The node to unwrap.
+ * @returns The innermost non-type-expression node.
+ */
 declare function unwrap(node: TSESTree.Node): Exclude<TSESTree.Node, TSESTreeTypeExpression>;
+/**
+ * Find a property by name in a list of object literal properties, recursing into spread object expressions.
+ * @param properties The object literal properties to search.
+ * @param name The property name to look for.
+ * @returns The matching `Property` node, or `null` when not found.
+ */
 declare function findProperty(properties: TSESTree.ObjectLiteralElement[], name: string): TSESTree.Property | null;
+/**
+ * Get the name of the callee of a call expression.
+ * @param node The call expression to inspect.
+ * @returns The callee name (ex: `"useState"`), or `null` when it cannot be statically determined.
+ */
 declare function getCalleeName(node: TSESTree.CallExpression): string | null;
+/**
+ * Get the static name of an object property's key.
+ * @param property The property to inspect.
+ * @param effort `"min"` only matches plain identifiers; `"max"` also resolves string literals and simple template literals.
+ * @returns The property name, or `null` when it cannot be statically determined.
+ */
 declare function getPropertyName(property: TSESTree.Property, effort?: "min" | "max"): string | null;
+/**
+ * Get the fully qualified name of a node (ex: `React.useState`), falling back to source text when needed.
+ * @param node The node to inspect.
+ * @param getText A function returning the source text of a node.
+ * @returns The fully qualified name.
+ */
 declare function getFullyQualifiedName(node: TSESTree.Node, getText: (node: TSESTree.Node) => string): string;
+/**
+ * Get the identifier at a given position in a member expression chain (ex: position `0` in `a.b.c` is `a`).
+ * @param node The expression to walk.
+ * @param position The position of the identifier to return.
+ * @returns The identifier at the given position, or `null` when there is none.
+ */
 declare function getIdentifierAt(node: TSESTree.Expression | TSESTree.PrivateIdentifier, position: number): TSESTree.Identifier | null;
 declare namespace traverse_d_exports {
   export { findParent };
 }
 type Predicate<T extends TSESTree.Node> = (node: TSESTree.Node) => node is T;
 type NodePredicate = (node: TSESTree.Node) => boolean;
+/**
+ * Walk up the AST from `node` to find the nearest ancestor matching a predicate.
+ * @param node The starting node for the upward search.
+ * @param test The predicate a candidate ancestor must satisfy.
+ * @param stop An optional predicate that aborts the search when it returns `true`.
+ * @returns The first matching ancestor, or `null` when none is found.
+ */
 declare function findParent<T extends TSESTree.Node>(node: TSESTree.Node | null, test: Predicate<T>, stop?: NodePredicate): T | null;
 declare function findParent(node: TSESTree.Node | null, test: NodePredicate, stop?: NodePredicate): TSESTree.Node | null;
 //#endregion

package/dist/index.js

@@ -22,35 +22,58 @@ var check_exports = /* @__PURE__ */ __exportAll({
 	isTypeAssertionExpression: () => isTypeAssertionExpression,
 	isTypeExpression: () => isTypeExpression
 });
+/** Check if a node is of the given type. */
 const is = ASTUtils.isNodeOfType;
+/** Check if a node is one of the given types. */
 const isOneOf = ASTUtils.isNodeOfTypes;
+/**
+* Check if a node is a directive statement (ex: `"use client"`), optionally matching a specific directive name.
+* @param node The node to check.
+* @param name The directive name to match. When omitted, any directive matches.
+* @returns `true` if the node is a matching directive statement.
+*/
 function isDirective(node, name) {
 	return node.type === AST_NODE_TYPES.ExpressionStatement && (name == null || node.directive === name);
 }
+/**
+* Check if a node is an identifier, optionally matching a specific name.
+* @param node The node to check.
+* @param name The identifier name to match. When omitted, any identifier matches.
+* @returns `true` if the node is a matching identifier.
+*/
 function isIdentifier(node, name) {
 	return node.type === AST_NODE_TYPES.Identifier && (name == null || node.name === name);
 }
+/** Check if a node is a class declaration or class expression. */
 const isClass = isOneOf([AST_NODE_TYPES.ClassDeclaration, AST_NODE_TYPES.ClassExpression]);
+/** Check if a node is a function declaration, function expression, or arrow function expression. */
 const isFunction = isOneOf([
 	AST_NODE_TYPES.ArrowFunctionExpression,
 	AST_NODE_TYPES.FunctionDeclaration,
 	AST_NODE_TYPES.FunctionExpression
 ]);
+/** Check if a node is a property-like node (property definition, index signature, parameter property, or property signature). */
 const isProperty = isOneOf([
 	AST_NODE_TYPES.PropertyDefinition,
 	AST_NODE_TYPES.TSIndexSignature,
 	AST_NODE_TYPES.TSParameterProperty,
 	AST_NODE_TYPES.TSPropertySignature
 ]);
+/** Check if a node is a property or method definition. */
 const isPropertyOrMethod = isOneOf([AST_NODE_TYPES.PropertyDefinition, AST_NODE_TYPES.MethodDefinition]);
+/** Check if a node is a JSX element. */
 const isJSXElement = is(AST_NODE_TYPES.JSXElement);
+/** Check if a node is a JSX fragment. */
 const isJSXFragment = is(AST_NODE_TYPES.JSXFragment);
+/** Check if a node is a JSX element or JSX fragment. */
 const isJSXElementOrFragment = isOneOf([AST_NODE_TYPES.JSXElement, AST_NODE_TYPES.JSXFragment]);
+/** Check if a node can appear as a JSX tag name. */
 const isJSXTagNameExpression = isOneOf([
 	AST_NODE_TYPES.JSXIdentifier,
 	AST_NODE_TYPES.JSXMemberExpression,
 	AST_NODE_TYPES.JSXNamespacedName
 ]);
+/** Check if a node is any JSX-related node. */
 const isJSX = isOneOf([
 	AST_NODE_TYPES.JSXAttribute,
 	AST_NODE_TYPES.JSXClosingElement,
@@ -68,6 +91,7 @@ const isJSX = isOneOf([
 	AST_NODE_TYPES.JSXSpreadChild,
 	AST_NODE_TYPES.JSXText
 ]);
+/** Check if a node is a TypeScript type expression (assertion, non-null, satisfies, or instantiation). */
 const isTypeExpression = isOneOf([
 	AST_NODE_TYPES.TSAsExpression,
 	AST_NODE_TYPES.TSTypeAssertion,
@@ -75,12 +99,14 @@ const isTypeExpression = isOneOf([
 	AST_NODE_TYPES.TSSatisfiesExpression,
 	AST_NODE_TYPES.TSInstantiationExpression
 ]);
+/** Check if a node is a TypeScript type assertion-like expression (as, assertion, non-null, or satisfies). */
 const isTypeAssertionExpression = isOneOf([
 	AST_NODE_TYPES.TSAsExpression,
 	AST_NODE_TYPES.TSTypeAssertion,
 	AST_NODE_TYPES.TSNonNullExpression,
 	AST_NODE_TYPES.TSSatisfiesExpression
 ]);
+/** Check if a node is an expression node. */
 const isExpression = isOneOf([
 	AST_NODE_TYPES.ArrayExpression,
 	AST_NODE_TYPES.ArrayPattern,
@@ -119,9 +145,9 @@ const isExpression = isOneOf([
 	AST_NODE_TYPES.YieldExpression
 ]);
 /**
-* Check if a node is a conditional expression or control flow statement
-* @param node The node to check
-* @returns True if the node is conditional
+* Check if a node is a conditional expression or a control flow statement.
+* @param node The node to check.
+* @returns `true` if the node is conditional.
 */
 const isConditional = isOneOf([
 	AST_NODE_TYPES.DoWhileStatement,
@@ -619,10 +645,21 @@ var extract_exports = /* @__PURE__ */ __exportAll({
 	getPropertyName: () => getPropertyName,
 	unwrap: () => unwrap
 });
+/**
+* Recursively unwrap TypeScript type expressions and chain expressions to get the underlying expression.
+* @param node The node to unwrap.
+* @returns The innermost non-type-expression node.
+*/
 function unwrap(node) {
 	if (isTypeExpression(node) || node.type === AST_NODE_TYPES.ChainExpression) return unwrap(node.expression);
 	return node;
 }
+/**
+* Find a property by name in a list of object literal properties, recursing into spread object expressions.
+* @param properties The object literal properties to search.
+* @param name The property name to look for.
+* @returns The matching `Property` node, or `null` when not found.
+*/
 function findProperty(properties, name) {
 	for (const property of properties) {
 		if (property.type === AST_NODE_TYPES.Property && getPropertyName(property) === name) return property;
@@ -633,12 +670,23 @@ function findProperty(properties, name) {
 	}
 	return null;
 }
+/**
+* Get the name of the callee of a call expression.
+* @param node The call expression to inspect.
+* @returns The callee name (ex: `"useState"`), or `null` when it cannot be statically determined.
+*/
 function getCalleeName(node) {
 	const callee = unwrap(node.callee);
 	if (callee.type === AST_NODE_TYPES.Identifier) return callee.name;
 	if (callee.type === AST_NODE_TYPES.MemberExpression && !callee.computed && callee.property.type === AST_NODE_TYPES.Identifier) return callee.property.name;
 	return null;
 }
+/**
+* Get the static name of an object property's key.
+* @param property The property to inspect.
+* @param effort `"min"` only matches plain identifiers; `"max"` also resolves string literals and simple template literals.
+* @returns The property name, or `null` when it cannot be statically determined.
+*/
 function getPropertyName(property, effort = "min") {
 	const key = unwrap(property.key);
 	if (key.type === AST_NODE_TYPES.Identifier && !property.computed) return key.name;
@@ -647,6 +695,12 @@ function getPropertyName(property, effort = "min") {
 	if (key.type === AST_NODE_TYPES.TemplateLiteral && key.expressions.length === 0) return key.quasis[0]?.value.cooked ?? key.quasis[0]?.value.raw ?? null;
 	return null;
 }
+/**
+* Get the fully qualified name of a node (ex: `React.useState`), falling back to source text when needed.
+* @param node The node to inspect.
+* @param getText A function returning the source text of a node.
+* @returns The fully qualified name.
+*/
 function getFullyQualifiedName(node, getText) {
 	const expr = unwrap(node);
 	switch (expr.type) {
@@ -663,6 +717,12 @@ function getFullyQualifiedName(node, getText) {
 		default: return getText(expr);
 	}
 }
+/**
+* Get the identifier at a given position in a member expression chain (ex: position `0` in `a.b.c` is `a`).
+* @param node The expression to walk.
+* @param position The position of the identifier to return.
+* @returns The identifier at the given position, or `null` when there is none.
+*/
 function getIdentifierAt(node, position) {
 	const identifiers = [];
 	let current = unwrap(node);
@@ -679,10 +739,10 @@ function getIdentifierAt(node, position) {
 //#region src/compare.ts
 var compare_exports = /* @__PURE__ */ __exportAll({ isEqual: () => isEqual });
 /**
-* Check if two nodes are equal.
-* @param a node to compare.
-* @param b node to compare.
-* @returns `true` if node equal.
+* Check if two nodes are structurally equal.
+* @param a The first node to compare.
+* @param b The second node to compare.
+* @returns `true` if the nodes are equal.
 * @see https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/src/util/isNodeEqual.ts
 */
 const isEqual = dual(2, (a, b) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eslint-react/ast",
-  "version": "5.17.3",
+  "version": "5.18.0",
   "description": "ESLint React's TSESTree AST utility module.",
   "homepage": "https://github.com/Rel1cx/eslint-react",
   "bugs": {
@@ -29,19 +29,19 @@
     "dist"
   ],
   "dependencies": {
-    "@typescript-eslint/types": "^8.64.0",
-    "@typescript-eslint/typescript-estree": "^8.64.0",
-    "@typescript-eslint/utils": "^8.64.0",
+    "@typescript-eslint/types": "^8.65.0",
+    "@typescript-eslint/typescript-estree": "^8.65.0",
+    "@typescript-eslint/utils": "^8.65.0",
     "string-ts": "^2.3.1"
   },
   "devDependencies": {
-    "@typescript-eslint/parser": "^8.64.0",
+    "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.7.0",
-    "tsdown": "^0.22.9",
+    "tsdown": "^0.22.13",
     "typescript": "6.0.3",
     "vitest": "^4.1.10",
-    "@local/configs": "0.0.0",
     "@local/eff": "0.0.0",
+    "@local/configs": "0.0.0",
     "@local/testkit": "0.0.0"
   },
   "peerDependencies": {