@eslint-react/var 5.20.4 → 5.20.6

package/dist/index.d.ts

@@ -36,6 +36,8 @@ export interface ImportEntry {
  * time, and results preserve source order.
  */
 export interface ImportLookup {
+  /** Return every import entry, in source order. */
+  all(): readonly ImportEntry[];
   /**
    * Look up the import entry a local name is bound to.
    *
@@ -50,8 +52,6 @@ export interface ImportLookup {
    * @returns The matching entries in source order, possibly empty.
    */
   bindingsOf(name: string): readonly ImportEntry[];
-  /** Return every import entry, in source order. */
-  all(): readonly ImportEntry[];
   /**
    * Check whether a local name is bound to a specific imported export.
    *
@@ -69,6 +69,11 @@ export interface ImportLookup {
 }
 /** Options for {@link createImportLookup}. */
 export interface ImportLookupOptions {
+  /**
+   * Local names to pre-register as namespace bindings without an import
+   * statement, e.g. a `ReactDOM` global provided by the environment.
+   */
+  builtinNamespaces?: readonly string[];
   /**
    * The base import source to track, e.g. `"react-dom"`.
    *
@@ -76,11 +81,6 @@ export interface ImportLookupOptions {
    * matches a source of `"react-dom"`.
    */
   source: string;
-  /**
-   * Local names to pre-register as namespace bindings without an import
-   * statement, e.g. a `ReactDOM` global provided by the environment.
-   */
-  builtinNamespaces?: readonly string[];
 }
 /**
  * Create a lookup of local import bindings from a source by scanning the
@@ -171,17 +171,17 @@ export declare function isValueEqual(context: RuleContext, a: TSESTree.Node, b:
  *
  * | Definition type          | `def.node`                                   | Returns                            |
  * |--------------------------|----------------------------------------------|------------------------------------|
- * | `Variable`               | `VariableDeclarator`                         | `def.node.init` (or `null`)        |
- * | `FunctionName`           | `FunctionDeclaration` / `FunctionExpression` | `def.node`                         |
+ * | `CatchClause`            | `CatchClause`                                | `null`                             |
  * | `ClassName`              | `ClassDeclaration` / `ClassExpression`       | `def.node`                         |
- * | `Parameter`              | containing function node                     | `def.node` (if a real function)    |
- * | `TSEnumName`             | `TSEnumDeclaration`                          | `def.node`                         |
- * | `TSEnumMember`           | `TSEnumMember`                               | `def.node.initializer` (or `null`) |
+ * | `FunctionName`           | `FunctionDeclaration` / `FunctionExpression` | `def.node`                         |
+ * | `ImplicitGlobalVariable` | any node                                     | `null`                             |
  * | `ImportBinding`          | import specifier                             | `null`                             |
- * | `CatchClause`            | `CatchClause`                                | `null`                             |
+ * | `Parameter`              | containing function node                     | `null` (the value is supplied by the caller) |
+ * | `TSEnumMember`           | `TSEnumMember`                               | `def.node.initializer` (or `null`) |
+ * | `TSEnumName`             | `TSEnumDeclaration`                          | `def.node`                         |
  * | `TSModuleName`           | `TSModuleDeclaration`                        | `null`                             |
  * | `Type`                   | type alias node                              | `null`                             |
- * | `ImplicitGlobalVariable` | any node                                     | `null`                             |
+ * | `Variable`               | `VariableDeclarator`                         | `def.node.init` for a plain identifier binding; `null` for destructured bindings or missing init |
  *
  * @param context The ESLint rule context.
  * @param node The identifier to resolve.
@@ -192,6 +192,9 @@ export declare function isValueEqual(context: RuleContext, a: TSESTree.Node, b:
  *   scope chain upward via `findVariable` so that references to outer-scope bindings are resolved
  *   correctly.
  * @returns The resolved node, or `null` if the identifier cannot be resolved to a value node.
+ *
+ * For origin/pedigree tracking that maps destructured bindings to the declarator's
+ * initializer, see {@link resolveOrigin}.
  */
 export declare function resolve(context: RuleContext, node: TSESTree.Identifier, options?: Partial<{
   at: number;
@@ -255,4 +258,51 @@ export type ObjectType = {
  * @returns The object type of the node, or `null` when it cannot be resolved.
  */
 export declare function resolveObjectType(context: RuleContext, node: TSESTree.Node | null): ObjectType | null;
+//#endregion
+//#region src/resolve-origin.d.ts
+/**
+ * Resolve an identifier to the AST node its value **originates from**,
+ * suitable for origin/pedigree tracking in ESLint rule analysis.
+ *
+ * The resolution follows these rules per definition type:
+ *
+ * | Definition type          | `def.node`                                   | Returns                            |
+ * |--------------------------|----------------------------------------------|------------------------------------|
+ * | `CatchClause`            | `CatchClause`                                | `null`                             |
+ * | `ClassName`              | `ClassDeclaration` / `ClassExpression`       | `def.node`                         |
+ * | `FunctionName`           | `FunctionDeclaration` / `FunctionExpression` | `def.node`                         |
+ * | `ImplicitGlobalVariable` | any node                                     | `null`                             |
+ * | `ImportBinding`          | import specifier                             | `def.node` (the import specifier)  |
+ * | `Parameter`              | containing function node                     | `def.node` (if a real function)    |
+ * | `TSEnumMember`           | `TSEnumMember`                               | `def.node.initializer` (or `null`) |
+ * | `TSEnumName`             | `TSEnumDeclaration`                          | `def.node`                         |
+ * | `TSModuleName`           | `TSModuleDeclaration`                        | `null`                             |
+ * | `Type`                   | type alias node                              | `null`                             |
+ * | `Variable`               | `VariableDeclarator`                         | `def.node.init` (or `null`), including for destructured bindings |
+ *
+ * Unlike {@link resolve}, a binding declared through a destructuring
+ * pattern (e.g. `setState` in `const [state, setState] = useState()`) resolves to the
+ * declarator's initializer (the `useState()` call), i.e. the source expression the
+ * binding derives from rather than the binding's own value; and a parameter resolves
+ * to the containing function node (the binding's declaration site) instead of `null`;
+ * and an import binding resolves to its import specifier (whose parent
+ * `ImportDeclaration` carries the module source) instead of `null`.
+ *
+ * Use this for origin/pedigree tracking ("what produced this value?"); use
+ * {@link resolve} when the precise value of the binding is needed.
+ *
+ * @param context The ESLint rule context.
+ * @param node The identifier to resolve.
+ * @param options Optional settings:
+ * - `at`: Index of the definition to resolve (default: `0` for the first definition).
+ * - `localOnly`: If `true`, only consider variables declared in the same scope as the identifier
+ *   (this will miss variables declared in an outer scope). When `false` (default), traverse the
+ *   scope chain upward via `findVariable` so that references to outer-scope bindings are resolved
+ *   correctly.
+ * @returns The resolved origin node, or `null` if the identifier cannot be resolved.
+ */
+export declare function resolveOrigin(context: RuleContext, node: TSESTree.Identifier, options?: Partial<{
+  at: number;
+  localOnly: boolean;
+}>): TSESTree.Node | null;
 //#endregion

package/dist/index.js

@@ -512,7 +512,7 @@ const takeWhile = dual(2, (xs, pred) => {
 * ```
 */
 function createImportLookup(program, options) {
-	const { source, builtinNamespaces = [] } = options;
+	const { builtinNamespaces = [], source } = options;
 	const entries = [];
 	const byLocal = /* @__PURE__ */ new Map();
 	const byName = /* @__PURE__ */ new Map();
@@ -563,15 +563,15 @@ function createImportLookup(program, options) {
 		}
 	}
 	return {
+		all() {
+			return entries;
+		},
 		binding(local) {
 			return byLocal.get(local);
 		},
 		bindingsOf(name) {
 			return byName.get(name) ?? [];
 		},
-		all() {
-			return entries;
-		},
 		has(local, name) {
 			return byLocal.get(local)?.name === name;
 		},
@@ -602,26 +602,37 @@ function getRequireExpressionArguments(node) {
 }
 
 //#endregion
-//#region src/resolve.ts
+//#region src/resolve-origin.ts
 /**
-* Resolve an identifier to the AST node that represents its value,
-* suitable for use in ESLint rule analysis.
+* Resolve an identifier to the AST node its value **originates from**,
+* suitable for origin/pedigree tracking in ESLint rule analysis.
 *
 * The resolution follows these rules per definition type:
 *
 * | Definition type          | `def.node`                                   | Returns                            |
 * |--------------------------|----------------------------------------------|------------------------------------|
-* | `Variable`               | `VariableDeclarator`                         | `def.node.init` (or `null`)        |
-* | `FunctionName`           | `FunctionDeclaration` / `FunctionExpression` | `def.node`                         |
+* | `CatchClause`            | `CatchClause`                                | `null`                             |
 * | `ClassName`              | `ClassDeclaration` / `ClassExpression`       | `def.node`                         |
+* | `FunctionName`           | `FunctionDeclaration` / `FunctionExpression` | `def.node`                         |
+* | `ImplicitGlobalVariable` | any node                                     | `null`                             |
+* | `ImportBinding`          | import specifier                             | `def.node` (the import specifier)  |
 * | `Parameter`              | containing function node                     | `def.node` (if a real function)    |
-* | `TSEnumName`             | `TSEnumDeclaration`                          | `def.node`                         |
 * | `TSEnumMember`           | `TSEnumMember`                               | `def.node.initializer` (or `null`) |
-* | `ImportBinding`          | import specifier                             | `null`                             |
-* | `CatchClause`            | `CatchClause`                                | `null`                             |
+* | `TSEnumName`             | `TSEnumDeclaration`                          | `def.node`                         |
 * | `TSModuleName`           | `TSModuleDeclaration`                        | `null`                             |
 * | `Type`                   | type alias node                              | `null`                             |
-* | `ImplicitGlobalVariable` | any node                                     | `null`                             |
+* | `Variable`               | `VariableDeclarator`                         | `def.node.init` (or `null`), including for destructured bindings |
+*
+* Unlike {@link resolve}, a binding declared through a destructuring
+* pattern (e.g. `setState` in `const [state, setState] = useState()`) resolves to the
+* declarator's initializer (the `useState()` call), i.e. the source expression the
+* binding derives from rather than the binding's own value; and a parameter resolves
+* to the containing function node (the binding's declaration site) instead of `null`;
+* and an import binding resolves to its import specifier (whose parent
+* `ImportDeclaration` carries the module source) instead of `null`.
+*
+* Use this for origin/pedigree tracking ("what produced this value?"); use
+* {@link resolve} when the precise value of the binding is needed.
 *
 * @param context The ESLint rule context.
 * @param node The identifier to resolve.
@@ -631,9 +642,9 @@ function getRequireExpressionArguments(node) {
 *   (this will miss variables declared in an outer scope). When `false` (default), traverse the
 *   scope chain upward via `findVariable` so that references to outer-scope bindings are resolved
 *   correctly.
-* @returns The resolved node, or `null` if the identifier cannot be resolved to a value node.
+* @returns The resolved origin node, or `null` if the identifier cannot be resolved.
 */
-function resolve(context, node, options) {
+function resolveOrigin(context, node, options) {
 	const { at = 0, localOnly = false } = options ?? {};
 	const scope = context.sourceCode.getScope(node);
 	const variable = localOnly ? scope.set.get(node.name) : findVariable(scope, node);
@@ -652,7 +663,7 @@ function resolve(context, node, options) {
 		case DefinitionType.Parameter: return Check.isFunction(def.node) ? def.node : null;
 		case DefinitionType.TSEnumName: return def.node;
 		case DefinitionType.TSEnumMember: return def.node.initializer ?? null;
-		case DefinitionType.ImportBinding: return null;
+		case DefinitionType.ImportBinding: return def.node;
 		case DefinitionType.CatchClause: return null;
 		case DefinitionType.TSModuleName: return null;
 		case DefinitionType.Type: return null;
@@ -685,8 +696,8 @@ function isValueEqual(context, a, b) {
 		case a.type === AST_NODE_TYPES.Literal && b.type === AST_NODE_TYPES.Literal: return a.value === b.value;
 		case a.type === AST_NODE_TYPES.TemplateElement && b.type === AST_NODE_TYPES.TemplateElement: return a.value.cooked === b.value.cooked;
 		case Check.isIdentifier(a) && Check.isIdentifier(b): {
-			const aDefNode = resolve(context, a);
-			const bDefNode = resolve(context, b);
+			const aDefNode = resolveOrigin(context, a);
+			const bDefNode = resolveOrigin(context, b);
 			const aDefNodeParent = aDefNode?.parent;
 			const bDefNodeParent = bDefNode?.parent;
 			const aVar = findVariable(aScope, a);
@@ -805,6 +816,70 @@ function isInitializedFromReactNative(name, initialScope, importSource = "react-
 	].includes(name.toLowerCase()) || Boolean(resolveImportSource(name, initialScope)?.startsWith(importSource));
 }
 
+//#endregion
+//#region src/resolve.ts
+/**
+* Resolve an identifier to the AST node that represents its value,
+* suitable for use in ESLint rule analysis.
+*
+* The resolution follows these rules per definition type:
+*
+* | Definition type          | `def.node`                                   | Returns                            |
+* |--------------------------|----------------------------------------------|------------------------------------|
+* | `CatchClause`            | `CatchClause`                                | `null`                             |
+* | `ClassName`              | `ClassDeclaration` / `ClassExpression`       | `def.node`                         |
+* | `FunctionName`           | `FunctionDeclaration` / `FunctionExpression` | `def.node`                         |
+* | `ImplicitGlobalVariable` | any node                                     | `null`                             |
+* | `ImportBinding`          | import specifier                             | `null`                             |
+* | `Parameter`              | containing function node                     | `null` (the value is supplied by the caller) |
+* | `TSEnumMember`           | `TSEnumMember`                               | `def.node.initializer` (or `null`) |
+* | `TSEnumName`             | `TSEnumDeclaration`                          | `def.node`                         |
+* | `TSModuleName`           | `TSModuleDeclaration`                        | `null`                             |
+* | `Type`                   | type alias node                              | `null`                             |
+* | `Variable`               | `VariableDeclarator`                         | `def.node.init` for a plain identifier binding; `null` for destructured bindings or missing init |
+*
+* @param context The ESLint rule context.
+* @param node The identifier to resolve.
+* @param options Optional settings:
+* - `at`: Index of the definition to resolve (default: `0` for the first definition).
+* - `localOnly`: If `true`, only consider variables declared in the same scope as the identifier
+*   (this will miss variables declared in an outer scope). When `false` (default), traverse the
+*   scope chain upward via `findVariable` so that references to outer-scope bindings are resolved
+*   correctly.
+* @returns The resolved node, or `null` if the identifier cannot be resolved to a value node.
+*
+* For origin/pedigree tracking that maps destructured bindings to the declarator's
+* initializer, see {@link resolveOrigin}.
+*/
+function resolve(context, node, options) {
+	const { at = 0, localOnly = false } = options ?? {};
+	const scope = context.sourceCode.getScope(node);
+	const variable = localOnly ? scope.set.get(node.name) : findVariable(scope, node);
+	if (variable == null) return null;
+	const def = variable.defs.at(at);
+	if (def == null) return null;
+	switch (def.type) {
+		case DefinitionType.FunctionName: return def.node;
+		case DefinitionType.ClassName: return def.node;
+		case DefinitionType.Variable: {
+			const { id, init } = def.node;
+			if (id !== def.name) return null;
+			if (init == null) return null;
+			if ("declarations" in init) return null;
+			return init;
+		}
+		case DefinitionType.Parameter: return null;
+		case DefinitionType.TSEnumName: return def.node;
+		case DefinitionType.TSEnumMember: return def.node.initializer ?? null;
+		case DefinitionType.ImportBinding: return null;
+		case DefinitionType.CatchClause: return null;
+		case DefinitionType.TSModuleName: return null;
+		case DefinitionType.Type: return null;
+		case DefinitionType.ImplicitGlobalVariable: return null;
+		default: return null;
+	}
+}
+
 //#endregion
 //#region src/resolve-enclosing-assignment-target.ts
 /**
@@ -934,4 +1009,4 @@ function resolveObjectType(context, node) {
 }
 
 //#endregion
-export { createImportLookup, getRequireExpressionArguments, isAssignmentTargetEqual, isInitializedFromReact, isInitializedFromReactNative, isValueEqual, resolve, resolveEnclosingAssignmentTarget, resolveImportSource, resolveObjectType };
+export { createImportLookup, getRequireExpressionArguments, isAssignmentTargetEqual, isInitializedFromReact, isInitializedFromReactNative, isValueEqual, resolve, resolveEnclosingAssignmentTarget, resolveImportSource, resolveObjectType, resolveOrigin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eslint-react/var",
-  "version": "5.20.4",
+  "version": "5.20.6",
   "description": "ESLint React's TSESTree AST utility module for static analysis of variables.",
   "homepage": "https://github.com/Rel1cx/eslint-react",
   "bugs": {
@@ -29,8 +29,8 @@
     "dist"
   ],
   "dependencies": {
-    "@eslint-react/ast": "5.20.4",
-    "@eslint-react/eslint": "5.20.4",
+    "@eslint-react/ast": "5.20.6",
+    "@eslint-react/eslint": "5.20.6",
     "@typescript-eslint/scope-manager": "^8.70.0",
     "@typescript-eslint/types": "^8.70.0",
     "@typescript-eslint/utils": "^8.70.0",