@tanstack/eslint-plugin-query 5.94.5 → 5.95.1

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

@@ -1,7 +1,6 @@
 import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
 import { ASTUtils } from '../../utils/ast-utils'
 import { getDocsUrl } from '../../utils/get-docs-url'
-import { uniqueBy } from '../../utils/unique-by'
 import { detectTanstackQueryImports } from '../../utils/detect-react-query-imports'
 import { ExhaustiveDepsUtils } from './exhaustive-deps.utils'
 import type { TSESLint, TSESTree } from '@typescript-eslint/utils'
@@ -14,6 +13,13 @@ export const name = 'exhaustive-deps'
 
 const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
 
+type RuleOption = {
+  allowlist?: {
+    variables?: Array<string>
+    types?: Array<string>
+  }
+}
+
 export const rule = createRule({
   name,
   meta: {
@@ -28,27 +34,36 @@ export const rule = createRule({
     },
     hasSuggestions: true,
     fixable: 'code',
-    schema: [],
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowlist: {
+            type: 'object',
+            properties: {
+              variables: { type: 'array', items: { type: 'string' } },
+              types: { type: 'array', items: { type: 'string' } },
+            },
+            additionalProperties: false,
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
   },
   defaultOptions: [],
 
   create: detectTanstackQueryImports((context) => {
     return {
-      Property: (node) => {
-        if (
-          !ASTUtils.isObjectExpression(node.parent) ||
-          !ASTUtils.isIdentifierWithName(node.key, QUERY_KEY)
-        ) {
-          return
-        }
-
+      ObjectExpression: (node: TSESTree.ObjectExpression) => {
         const scopeManager = context.sourceCode.scopeManager
+
         const queryKey = ASTUtils.findPropertyWithIdentifierKey(
-          node.parent.properties,
+          node.properties,
           QUERY_KEY,
         )
         const queryFn = ASTUtils.findPropertyWithIdentifierKey(
-          node.parent.properties,
+          node.properties,
           QUERY_FN,
         )
 
@@ -70,103 +85,134 @@ export const rule = createRule({
           context,
         )
 
-        const externalRefs = ASTUtils.getExternalRefs({
-          scopeManager,
-          sourceCode: context.sourceCode,
-          node: getQueryFnRelevantNode(queryFn),
-        })
+        const queryFnNodes = ExhaustiveDepsUtils.getQueryFnNodes(queryFn)
 
-        const relevantRefs = externalRefs.filter((reference) =>
-          ExhaustiveDepsUtils.isRelevantReference({
-            sourceCode: context.sourceCode,
-            reference,
+        const externalRefs = queryFnNodes.flatMap((fnNode) =>
+          ASTUtils.getExternalRefs({
             scopeManager,
-            node: getQueryFnRelevantNode(queryFn),
-            filename: context.filename,
+            sourceCode: context.sourceCode,
+            node: fnNode,
           }),
         )
 
+        const relevantRefs = externalRefs.filter((reference) =>
+          queryFnNodes.some((fnNode) =>
+            ExhaustiveDepsUtils.isRelevantReference({
+              sourceCode: context.sourceCode,
+              reference,
+              scopeManager,
+              node: fnNode,
+              filename: context.filename,
+            }),
+          ),
+        )
+
+        const ruleOptions = context.options.at(0) as RuleOption | undefined
+        const allowlistedVariables = new Set(
+          ruleOptions?.allowlist?.variables ?? [],
+        )
+        const allowlistedTypes = new Set(ruleOptions?.allowlist?.types ?? [])
+
+        const requiredRefs = relevantRefs.flatMap((ref) => {
+          if (ref.identifier.type !== AST_NODE_TYPES.Identifier) return []
+
+          const refPath = ExhaustiveDepsUtils.computeRefPath({
+            identifier: ref.identifier,
+            sourceCode: context.sourceCode,
+          })
+
+          if (refPath === null) return []
+
+          return [
+            {
+              ...refPath,
+              allowlistedByType:
+                ExhaustiveDepsUtils.variableIsAllowlistedByType({
+                  allowlistedTypes,
+                  variable: ref.resolved ?? null,
+                }),
+            },
+          ]
+        })
+
+        if (requiredRefs.length === 0) return
+
         const queryKeyDeps = ExhaustiveDepsUtils.collectQueryKeyDeps({
           sourceCode: context.sourceCode,
-          scopeManager,
+          scopeManager: scopeManager,
+          queryKeyNode: queryKeyNode,
+        })
+
+        const missingPaths = ExhaustiveDepsUtils.computeFilteredMissingPaths({
+          requiredRefs: requiredRefs,
+          allowlistedVariables: allowlistedVariables,
+          existingRootIdentifiers: queryKeyDeps.roots,
+          existingFullPaths: queryKeyDeps.paths,
+        })
+
+        if (missingPaths.length === 0) return
+
+        const missingAsText = missingPaths.join(', ')
+        const suggestions = buildSuggestions({
           queryKeyNode,
+          missingPaths,
+          missingAsText,
+          sourceCode: context.sourceCode,
         })
 
-        const missingRefs = relevantRefs
-          .map((ref) => ({
-            ref: ref,
-            text: ASTUtils.isAncestorIsCallee(ref.identifier)
-              ? ref.identifier.name
-              : ASTUtils.mapKeyNodeToBaseText(
-                  ref.identifier,
-                  context.sourceCode,
-                ),
-          }))
-          .filter(({ ref, text }) => {
-            return (
-              !ref.isTypeReference &&
-              !queryKeyDeps.has(text) &&
-              !queryKeyDeps.has(text.split(/[?.]/)[0] ?? '')
-            )
-          })
-          .map(({ ref, text }) => ({
-            identifier: ref.identifier,
-            text: text,
-          }))
-
-        const uniqueMissingRefs = uniqueBy(missingRefs, (x) => x.text)
-
-        if (uniqueMissingRefs.length > 0) {
-          const missingAsText = uniqueMissingRefs
-            .map((ref) => ref.text)
-            .join(', ')
-
-          const queryKeyValue = context.sourceCode.getText(queryKeyNode)
-
-          const existingWithMissing =
-            queryKeyValue === '[]'
-              ? `[${missingAsText}]`
-              : queryKeyValue.replace(/\]$/, `, ${missingAsText}]`)
-
-          const suggestions: TSESLint.ReportSuggestionArray<string> = []
-
-          if (queryKeyNode.type === AST_NODE_TYPES.ArrayExpression) {
-            suggestions.push({
-              messageId: 'fixTo',
-              data: { result: existingWithMissing },
-              fix(fixer) {
-                return fixer.replaceText(queryKeyNode, existingWithMissing)
-              },
-            })
-          }
-
-          context.report({
-            node: node,
-            messageId: 'missingDeps',
-            data: {
-              deps: uniqueMissingRefs.map((ref) => ref.text).join(', '),
-            },
-            suggest: suggestions,
-          })
-        }
+        context.report({
+          node,
+          messageId: 'missingDeps',
+          data: { deps: missingAsText },
+          suggest: suggestions,
+        })
       },
     }
   }),
 })
 
-function getQueryFnRelevantNode(queryFn: TSESTree.Property) {
-  if (queryFn.value.type !== AST_NODE_TYPES.ConditionalExpression) {
-    return queryFn.value
+function buildSuggestions(params: {
+  queryKeyNode: TSESTree.Node
+  missingPaths: Array<string>
+  missingAsText: string
+  sourceCode: Readonly<TSESLint.SourceCode>
+}): TSESLint.ReportSuggestionArray<string> {
+  const { queryKeyNode, missingPaths, missingAsText, sourceCode } = params
+
+  if (queryKeyNode.type !== AST_NODE_TYPES.ArrayExpression) {
+    return []
   }
 
-  if (
-    queryFn.value.consequent.type === AST_NODE_TYPES.Identifier &&
-    queryFn.value.consequent.name === 'skipToken'
-  ) {
-    return queryFn.value.alternate
+  const closingBracket = sourceCode.getLastToken(queryKeyNode)
+  if (!closingBracket) return []
+
+  const existingElements = queryKeyNode.elements
+    .filter((el): el is NonNullable<typeof el> => el !== null)
+    .map((el) => sourceCode.getText(el))
+
+  const resultText = `[${[...existingElements, ...missingPaths].join(', ')}]`
+
+  if (queryKeyNode.elements.length === 0) {
+    return [
+      {
+        messageId: 'fixTo',
+        data: { result: resultText },
+        fix: (fixer) => fixer.replaceText(queryKeyNode, resultText),
+      },
+    ]
   }
 
-  return queryFn.value.consequent
+  const tokenBefore = sourceCode.getTokenBefore(closingBracket)
+  const separator = tokenBefore?.value === ',' ? ' ' : ', '
+
+  return [
+    {
+      messageId: 'fixTo',
+      data: { result: resultText },
+      fix: (fixer) =>
+        fixer.insertTextBefore(closingBracket, `${separator}${missingAsText}`),
+    },
+  ]
 }
 
 function dereferenceVariablesAndTypeAssertions(

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>,