@tanstack/eslint-plugin-query 5.94.4 → 5.95.0

package/src/rules/exhaustive-deps/exhaustive-deps.utils.ts

@@ -14,7 +14,7 @@ export const ExhaustiveDepsUtils = {
     const component = ASTUtils.getFunctionAncestor(sourceCode, node)
     const queryFnScope = scopeManager.acquire(node)
 
-    if (queryFnScope === null) {
+    if (queryFnScope === null || reference.isValueReference === false) {
       return false
     }
 
@@ -59,24 +59,88 @@ export const ExhaustiveDepsUtils = {
       !ExhaustiveDepsUtils.isInstanceOfKind(reference.identifier.parent)
     )
   },
-  isInstanceOfKind(node: TSESTree.Node) {
-    return (
-      node.type === AST_NODE_TYPES.BinaryExpression &&
-      node.operator === 'instanceof'
-    )
+
+  /**
+   * Given required refs and existing queryKey entries, compute missing dependency paths
+   * respecting allowlisted variables and types.
+   */
+  computeFilteredMissingPaths(params: {
+    requiredRefs: Array<{
+      path: string
+      root: string
+      allowlistedByType: boolean
+    }>
+    allowlistedVariables: Set<string>
+    existingRootIdentifiers: Set<string>
+    existingFullPaths: Set<string>
+  }): Array<string> {
+    const {
+      requiredRefs,
+      allowlistedVariables,
+      existingRootIdentifiers,
+      existingFullPaths,
+    } = params
+
+    const missingPaths = new Set<string>()
+
+    for (const { root, path, allowlistedByType } of requiredRefs) {
+      // If root itself is present in the key, it covers all members
+      if (existingRootIdentifiers.has(root)) continue
+      if (allowlistedVariables.has(root)) continue
+      if (existingFullPaths.has(path)) continue
+      if (allowlistedByType) continue
+
+      missingPaths.add(path)
+    }
+
+    // Collapse descendants: if a root is already missing, drop deeper paths
+    for (const path of missingPaths) {
+      const root = path.split('.')[0]
+      if (root !== path && root !== undefined && missingPaths.has(root)) {
+        missingPaths.delete(path)
+      }
+    }
+
+    return Array.from(missingPaths)
   },
 
+  /**
+   * Extract existing queryKey deps as root identifiers and full member paths.
+   */
   collectQueryKeyDeps(params: {
     sourceCode: Readonly<TSESLint.SourceCode>
     scopeManager: TSESLint.Scope.ScopeManager
     queryKeyNode: TSESTree.Node
-  }): Set<string> {
+  }): { roots: Set<string>; paths: Set<string> } {
     const { sourceCode, scopeManager, queryKeyNode } = params
-    const deps = new Set<string>()
+    const roots = new Set<string>()
+    const paths = new Set<string>()
     const visitorKeys = sourceCode.visitorKeys
 
-    function add(identifier: TSESTree.Identifier) {
-      deps.add(ASTUtils.mapKeyNodeToBaseText(identifier, sourceCode))
+    function addRoot(name: string) {
+      const cleaned = ExhaustiveDepsUtils.normalizeChain(name)
+      roots.add(cleaned)
+      paths.add(cleaned)
+    }
+    function addFull(text: string) {
+      const cleaned = ExhaustiveDepsUtils.normalizeChain(text)
+      paths.add(cleaned)
+    }
+    function addRefPath(
+      refPath: {
+        path: string
+        root: string
+        coversRootMembers: boolean
+      } | null,
+    ) {
+      if (!refPath) return
+
+      if (refPath.coversRootMembers) {
+        addRoot(refPath.root)
+        return
+      }
+
+      addFull(refPath.path)
     }
 
     function visitChildren(node: TSESTree.Node): void {
@@ -106,9 +170,15 @@ export const ExhaustiveDepsUtils = {
       if (!node) return
 
       switch (node.type) {
-        case AST_NODE_TYPES.Identifier:
-          add(node)
+        case AST_NODE_TYPES.Identifier: {
+          addRefPath(
+            ExhaustiveDepsUtils.computeRefPath({
+              identifier: node,
+              sourceCode: sourceCode,
+            }),
+          )
           return
+        }
         case AST_NODE_TYPES.ArrowFunctionExpression:
         case AST_NODE_TYPES.FunctionExpression:
           for (const reference of ExhaustiveDepsUtils.collectExternalRefsInFunction(
@@ -117,9 +187,16 @@ export const ExhaustiveDepsUtils = {
               scopeManager: scopeManager,
             },
           )) {
-            if (reference.identifier.type === AST_NODE_TYPES.Identifier) {
-              add(reference.identifier)
+            if (reference.identifier.type !== AST_NODE_TYPES.Identifier) {
+              continue
             }
+
+            addRefPath(
+              ExhaustiveDepsUtils.computeRefPath({
+                identifier: reference.identifier,
+                sourceCode: sourceCode,
+              }),
+            )
           }
           return
         case AST_NODE_TYPES.Property:
@@ -131,19 +208,20 @@ export const ExhaustiveDepsUtils = {
             node.parent.callee === node &&
             node.object.type === AST_NODE_TYPES.Identifier
           ) {
-            deps.add(node.object.name)
+            addRoot(node.object.name)
           } else {
             visit(node.object)
           }
           return
         case AST_NODE_TYPES.CallExpression:
           node.arguments.forEach((argument) => visit(argument))
-          if (
-            node.callee.type === AST_NODE_TYPES.MemberExpression ||
-            node.callee.type === AST_NODE_TYPES.ChainExpression ||
-            node.callee.type === AST_NODE_TYPES.TSNonNullExpression
-          ) {
-            visit(node.callee)
+          switch (node.callee.type) {
+            case AST_NODE_TYPES.Identifier:
+            case AST_NODE_TYPES.MemberExpression:
+            case AST_NODE_TYPES.ChainExpression:
+            case AST_NODE_TYPES.TSNonNullExpression:
+              visit(node.callee)
+              break
           }
           return
       }
@@ -153,7 +231,7 @@ export const ExhaustiveDepsUtils = {
 
     visit(queryKeyNode)
 
-    return deps
+    return { roots, paths }
   },
 
   isNode(value: unknown): value is TSESTree.Node {
@@ -165,6 +243,97 @@ export const ExhaustiveDepsUtils = {
     )
   },
 
+  /**
+   * Checks whether the resolved variable is allowlisted by its type annotation
+   */
+  variableIsAllowlistedByType(params: {
+    allowlistedTypes: Set<string>
+    variable: TSESLint.Scope.Variable | null
+  }): boolean {
+    const { allowlistedTypes, variable } = params
+    if (allowlistedTypes.size === 0) return false
+    if (!variable) return false
+
+    for (const id of variable.identifiers) {
+      if (id.typeAnnotation) {
+        const typeIdentifiers = new Set<string>()
+        ExhaustiveDepsUtils.collectTypeIdentifiers(
+          id.typeAnnotation.typeAnnotation,
+          typeIdentifiers,
+        )
+        for (const typeIdentifier of typeIdentifiers) {
+          if (allowlistedTypes.has(typeIdentifier)) return true
+        }
+      }
+    }
+
+    return false
+  },
+  isInstanceOfKind(node: TSESTree.Node) {
+    return (
+      node.type === AST_NODE_TYPES.BinaryExpression &&
+      node.operator === 'instanceof'
+    )
+  },
+
+  /**
+   * Normalizes a chain by removing optional chaining operators
+   *
+   * Example: `a?.b.c!` -> `a.b.c`
+   */
+  normalizeChain(text: string): string {
+    return text.replace(/(?:\?(\.)|!)/g, '$1')
+  },
+
+  /**
+   * Computes the reference path for an identifier
+   *
+   * Example: `a.b.c!` -> `{ path: 'a.b.c', root: 'a' }`
+   */
+  computeRefPath(params: {
+    identifier: TSESTree.Identifier
+    sourceCode: Readonly<TSESLint.SourceCode>
+  }): { path: string; root: string; coversRootMembers: boolean } | null {
+    const { identifier, sourceCode } = params
+
+    const fullChainNode = ASTUtils.traverseUpOnly(identifier, [
+      AST_NODE_TYPES.MemberExpression,
+      AST_NODE_TYPES.TSNonNullExpression,
+      AST_NODE_TYPES.Identifier,
+    ])
+
+    const fullText = ExhaustiveDepsUtils.normalizeChain(
+      sourceCode.getText(fullChainNode),
+    )
+
+    const parent = fullChainNode.parent
+    let dependencyPath = fullText
+    let coversRootMembers = fullText === identifier.name
+
+    if (
+      parent &&
+      parent.type === AST_NODE_TYPES.CallExpression &&
+      parent.callee === fullChainNode
+    ) {
+      const segments = fullText.split('.')
+      if (segments.length > 1) {
+        dependencyPath = segments.slice(0, -1).join('.')
+      }
+
+      coversRootMembers = false
+    }
+
+    dependencyPath =
+      dependencyPath.split('.')[0] === '' ? identifier.name : dependencyPath
+    const root = dependencyPath.split('.')[0]
+
+    return {
+      path: dependencyPath,
+      root: root ?? identifier.name,
+      coversRootMembers: coversRootMembers && dependencyPath === root,
+    }
+  },
+
   collectExternalRefsInFunction(params: {
     functionNode: TSESTree.ArrowFunctionExpression | TSESTree.FunctionExpression
     scopeManager: TSESLint.Scope.ScopeManager
@@ -210,4 +379,61 @@ export const ExhaustiveDepsUtils = {
 
     return externalRefs
   },
+
+  /**
+   * Recursively collects type identifiers from a type annotation
+   */
+  collectTypeIdentifiers(typeNode: TSESTree.TypeNode, out: Set<string>): void {
+    switch (typeNode.type) {
+      case AST_NODE_TYPES.TSTypeReference: {
+        if (typeNode.typeName.type === AST_NODE_TYPES.Identifier) {
+          out.add(typeNode.typeName.name)
+        }
+        break
+      }
+      case AST_NODE_TYPES.TSUnionType:
+      case AST_NODE_TYPES.TSIntersectionType: {
+        typeNode.types.forEach((t) =>
+          ExhaustiveDepsUtils.collectTypeIdentifiers(t, out),
+        )
+        break
+      }
+      case AST_NODE_TYPES.TSArrayType: {
+        ExhaustiveDepsUtils.collectTypeIdentifiers(typeNode.elementType, out)
+        break
+      }
+      case AST_NODE_TYPES.TSTupleType: {
+        typeNode.elementTypes.forEach((et) =>
+          ExhaustiveDepsUtils.collectTypeIdentifiers(et, out),
+        )
+        break
+      }
+    }
+  },
+
+  /**
+   * Gets the function expression nodes from a queryFn property, handling conditional expressions.
+   * When neither branch is skipToken, returns both branches so all deps are scanned.
+   */
+  getQueryFnNodes(queryFn: TSESTree.Property): Array<TSESTree.Node> {
+    if (queryFn.value.type !== AST_NODE_TYPES.ConditionalExpression) {
+      return [queryFn.value]
+    }
+
+    if (
+      queryFn.value.consequent.type === AST_NODE_TYPES.Identifier &&
+      queryFn.value.consequent.name === 'skipToken'
+    ) {
+      return [queryFn.value.alternate]
+    }
+
+    if (
+      queryFn.value.alternate.type === AST_NODE_TYPES.Identifier &&
+      queryFn.value.alternate.name === 'skipToken'
+    ) {
+      return [queryFn.value.consequent]
+    }
+
+    return [queryFn.value.consequent, queryFn.value.alternate]
+  },
 }

package/src/utils/ast-utils.ts

@@ -42,10 +42,9 @@ export const ASTUtils = {
     properties: Array<TSESTree.ObjectLiteralElement>,
     key: string,
   ): TSESTree.Property | undefined {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
-    return properties.find((x) =>
+    return properties.find((x): x is TSESTree.Property =>
       ASTUtils.isPropertyWithIdentifierKey(x, key),
-    ) as TSESTree.Property | undefined
+    )
   },
   getNestedIdentifiers(node: TSESTree.Node): Array<TSESTree.Identifier> {
     const identifiers: Array<TSESTree.Identifier> = []
@@ -132,28 +131,6 @@ export const ASTUtils = {
 
     return identifiers
   },
-  isAncestorIsCallee(identifier: TSESTree.Node) {
-    let previousNode = identifier
-    let currentNode = identifier.parent
-
-    while (currentNode !== undefined) {
-      if (
-        currentNode.type === AST_NODE_TYPES.CallExpression &&
-        currentNode.callee === previousNode
-      ) {
-        return true
-      }
-
-      if (currentNode.type !== AST_NODE_TYPES.MemberExpression) {
-        return false
-      }
-
-      previousNode = currentNode
-      currentNode = currentNode.parent
-    }
-
-    return false
-  },
   traverseUpOnly(
     identifier: TSESTree.Node,
     allowedNodeTypes: Array<AST_NODE_TYPES>,