@blumintinc/eslint-plugin-blumint 1.20.19 → 1.20.21

package/lib/index.js

@@ -223,7 +223,7 @@ function noFrontendImportsFromFunctionsPatterns(pattern) {
 module.exports = {
     meta: {
         name: '@blumintinc/eslint-plugin-blumint',
-        version: '1.20.19',
+        version: '1.20.21',
     },
     parseOptions: {
         ecmaVersion: 2020,

package/lib/rules/enforce-querykey-ts.js

@@ -1,14 +1,62 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceQueryKeyTs = void 0;
+const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+// The module's path below the project root doubles as the bare specifier,
+// which is precisely why the root tsconfig `paths` and the Jest mapper resolve
+// it.
+const QUERY_KEYS_MODULE = 'src/util/routing/queryKeys';
+const QUERY_KEYS_SUFFIX = 'util/routing/queryKeys';
+const SRC_TIER_SEGMENT = '/src/';
 /**
- * The canonical queryKeys module. The rule takes no options and already hard-codes
- * this path as what makes a key valid, so the fixer writes the very same path
- * instead of guessing one when a file has no queryKeys import to copy from.
+ * An `@/`-aliased specifier resolves under none of tsc, webpack or Jest, so it
+ * is never emitted; it stays recognized because a consumer that does declare
+ * the alias must still have its existing imports understood.
  */
-const DEFAULT_QUERY_KEYS_SOURCE = '@/util/routing/queryKeys';
+const ALIASED_QUERY_KEYS_MODULE = '@/util/routing/queryKeys';
+const toPosixPath = (filePath) => filePath.replace(/\\/g, '/');
+const ensureRelativeSpecifier = (specifier) => specifier.startsWith('.') ? specifier : `./${specifier}`;
+const isWindowsDrivePath = (filePath) => /^[A-Za-z]:[\\/]/.test(filePath);
+const isValidRelativePath = (relativePath) => relativePath !== '' &&
+    !path_1.default.isAbsolute(relativePath) &&
+    !isWindowsDrivePath(relativePath);
+const toAbsoluteFilename = (sourceFilePath, cwd) => toPosixPath(path_1.default.isAbsolute(sourceFilePath)
+    ? sourceFilePath
+    : path_1.default.join(cwd, sourceFilePath));
+/**
+ * `queryKeys.ts` lives at `src/util/routing/queryKeys.ts` and is reachable by
+ * exactly two forms: a relative path, and the bare `src/…` specifier that the
+ * root tsconfig `paths` and the Jest `moduleNameMapper` both resolve. A
+ * hardcoded `@/`-aliased specifier therefore turns every fix into a broken
+ * import (#1391).
+ *
+ * Files under a `src/` segment take the relative form, which dominates the
+ * codebase and stays correct even where `paths` are unavailable; the `../`
+ * count comes from the file's own depth below the root that owns its `src/`
+ * segment. Returns null when no correct specifier exists, which makes the
+ * caller decline the fix rather than write an import that cannot resolve.
+ */
+function buildQueryKeysSpecifier(sourceFilePath, cwd) {
+    const absoluteFilename = toAbsoluteFilename(sourceFilePath, cwd);
+    const tierIndex = absoluteFilename.indexOf(SRC_TIER_SEGMENT);
+    if (tierIndex === -1) {
+        return QUERY_KEYS_MODULE;
+    }
+    // The project root is everything up to and including the separator that
+    // precedes the file's own `src/` segment.
+    const projectRoot = absoluteFilename.slice(0, tierIndex + 1);
+    const targetPath = path_1.default.join(projectRoot, QUERY_KEYS_MODULE);
+    const relativePath = path_1.default.relative(path_1.default.dirname(absoluteFilename), targetPath);
+    if (!isValidRelativePath(relativePath)) {
+        return null;
+    }
+    return ensureRelativeSpecifier(toPosixPath(relativePath));
+}
 /**
  * Rule to enforce the use of centralized router state key constants imported from
  * `src/util/routing/queryKeys.ts` instead of arbitrary string literals when calling
@@ -25,18 +73,21 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            enforceQueryKeyImport: 'Router state key must come from queryKeys.ts (e.g., "@/util/routing/queryKeys", "src/util/routing/queryKeys", or a relative path ending in "/util/routing/queryKeys"). Use a QUERY_KEY_* constant instead of string literals.',
+            enforceQueryKeyImport: 'Router state key must come from queryKeys.ts (e.g., "src/util/routing/queryKeys" or a relative path to that module). Use a QUERY_KEY_* constant instead of string literals.',
             enforceQueryKeyConstant: 'Router state key must use a QUERY_KEY_* constant from queryKeys.ts. Variable "{{variableName}}" is not imported from the correct source.',
         },
     },
     defaultOptions: [],
     create(context) {
+        const cwd = typeof context.getCwd === 'function' ? context.getCwd() : process.cwd();
+        const absoluteFilename = toAbsoluteFilename(context.getFilename(), cwd);
+        const queryKeysSpecifier = buildQueryKeysSpecifier(context.getFilename(), cwd);
         // Track imports from queryKeys.ts
         const queryKeyImports = new Map();
         const localUseRouterStateNames = new Set(['useRouterState']);
         const validQueryKeySources = new Set([
-            DEFAULT_QUERY_KEYS_SOURCE,
-            'src/util/routing/queryKeys',
+            ALIASED_QUERY_KEYS_MODULE,
+            QUERY_KEYS_MODULE,
         ]);
         const allowedQueryKeyFactories = new Set(['makeQueryKey', 'getQueryKey']);
         const sourceCode = context.getSourceCode();
@@ -60,8 +111,21 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
          * Check if a source path refers to queryKeys.ts
          */
         function isQueryKeysSource(source) {
-            return (validQueryKeySources.has(source) ||
-                source.endsWith('/util/routing/queryKeys'));
+            if (validQueryKeySources.has(source) ||
+                source.endsWith(`/${QUERY_KEYS_SUFFIX}`)) {
+                return true;
+            }
+            // A relative specifier can name the module without spelling out
+            // `util/routing`: a sibling reaches it as `./queryKeys`, and a file two
+            // directories below `src/util` as `../../routing/queryKeys`. Resolving
+            // against the linted file recognizes those, which also keeps the fix's own
+            // relative output recognized on the next pass so a second violation
+            // extends that import instead of duplicating it.
+            if (!source.startsWith('.')) {
+                return false;
+            }
+            const resolved = toPosixPath(path_1.default.resolve(path_1.default.dirname(absoluteFilename), source));
+            return resolved.endsWith(`/${QUERY_KEYS_SUFFIX}`);
         }
         function importDeclarationsOf() {
             return sourceCode.ast.body.filter((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration &&
@@ -120,13 +184,41 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
             }
             return 'bound';
         }
+        /**
+         * A parameter binding holds a different value on every call, so no single
+         * `QUERY_KEY_*` constant can stand in for it: a hook that iterates a
+         * constant array of keys hands each one to a callback parameter by design
+         * (#1393). Reporting such an identifier demands a substitution that does not
+         * exist, and the enclosing function is where the caller — not this file —
+         * decides which key is passed.
+         */
+        function isParameterBinding(identifier) {
+            const variable = utils_1.ASTUtils.findVariable(scopeOf(identifier), identifier);
+            const definition = variable?.defs[0];
+            return definition?.type === utils_1.TSESLint.Scope.DefinitionType.Parameter;
+        }
+        function queryKeysDeclarationsOf() {
+            return importDeclarationsOf().filter((declaration) => isQueryKeysSource(String(declaration.source.value)));
+        }
+        /**
+         * The path by which this file reaches queryKeys.ts. An existing declaration
+         * is proof of a path that resolves here — including an `@/` one, in a
+         * consumer that declares that alias — so it wins over anything derived.
+         * Null means the module is unreachable by any specifier this rule can write.
+         */
+        function importSourceOf() {
+            const [declaration] = queryKeysDeclarationsOf();
+            return declaration
+                ? String(declaration.source.value)
+                : queryKeysSpecifier;
+        }
         /**
          * Make the substituted constants resolve: extend the file's queryKeys import
          * when there is one to extend, otherwise add a fresh import statement.
          */
         function buildImportFix(fixer, constants) {
             const importDeclarations = importDeclarationsOf();
-            const queryKeysDeclarations = importDeclarations.filter((declaration) => isQueryKeysSource(String(declaration.source.value)));
+            const queryKeysDeclarations = queryKeysDeclarationsOf();
             const reusable = queryKeysDeclarations.find((declaration) => declaration.importKind !== 'type' &&
                 declaration.specifiers.some(isValueImportSpecifier));
             if (reusable) {
@@ -136,9 +228,10 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
             }
             // A namespace or type-only queryKeys import cannot take named value
             // specifiers, but its path is proof of how this file reaches the module.
-            const source = queryKeysDeclarations.length
-                ? String(queryKeysDeclarations[0].source.value)
-                : DEFAULT_QUERY_KEYS_SOURCE;
+            const source = importSourceOf();
+            if (source === null) {
+                return null;
+            }
             const importText = `import { ${constants.join(', ')} } from '${source}';\n`;
             const [firstImport] = importDeclarations;
             if (firstImport) {
@@ -152,6 +245,7 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
         function flushReports() {
             const resolutions = new Map();
             const missingConstants = [];
+            const canImport = importSourceOf() !== null;
             for (const report of pendingReports) {
                 if (!report.substitution) {
                     continue;
@@ -159,6 +253,12 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
                 const { constant, scope } = report.substitution;
                 const name = localNameOf(constant);
                 const state = resolveBinding(scope, name);
+                // Substituting a constant whose import cannot be written would leave
+                // the file referencing an undefined identifier, which is worse than the
+                // literal it replaced; leaving the report unresolved declines its fix.
+                if (state === 'missing' && !canImport) {
+                    continue;
+                }
                 resolutions.set(report, { name, state });
                 if (state === 'missing' && !missingConstants.includes(name)) {
                     missingConstants.push(name);
@@ -188,7 +288,11 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
                             fixer.replaceText(substitution.keyNode, resolution.name),
                         ];
                         if (report === importCarrier && missingConstants.length > 0) {
-                            fixes.unshift(buildImportFix(fixer, missingConstants));
+                            const importFix = buildImportFix(fixer, missingConstants);
+                            if (!importFix) {
+                                return null;
+                            }
+                            fixes.unshift(importFix);
                         }
                         return fixes;
                     },
@@ -403,7 +507,8 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
                                                 : undefined,
                                         });
                                     }
-                                    else if (keyValue.type === utils_1.AST_NODE_TYPES.Identifier) {
+                                    else if (keyValue.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                        !isParameterBinding(keyValue)) {
                                         // Report variables that aren't from the correct source
                                         pendingReports.push({
                                             node: keyValue,

package/lib/rules/prefer-global-router-state-key.js

@@ -1,8 +1,56 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferGlobalRouterStateKey = void 0;
+const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+// The module's path below the project root doubles as the bare specifier,
+// which is precisely why the root tsconfig `paths` and the Jest mapper resolve
+// it.
+const QUERY_KEYS_MODULE = 'src/util/routing/queryKeys';
+const QUERY_KEYS_SUFFIX = 'util/routing/queryKeys';
+const SRC_TIER_SEGMENT = '/src/';
+const toPosixPath = (filePath) => filePath.replace(/\\/g, '/');
+const ensureRelativeSpecifier = (specifier) => specifier.startsWith('.') ? specifier : `./${specifier}`;
+const isWindowsDrivePath = (filePath) => /^[A-Za-z]:[\\/]/.test(filePath);
+const isValidRelativePath = (relativePath) => relativePath !== '' &&
+    !path_1.default.isAbsolute(relativePath) &&
+    !isWindowsDrivePath(relativePath);
+const toAbsoluteFilename = (sourceFilePath, cwd) => toPosixPath(path_1.default.isAbsolute(sourceFilePath)
+    ? sourceFilePath
+    : path_1.default.join(cwd, sourceFilePath));
+/**
+ * `queryKeys.ts` lives at `src/util/routing/queryKeys.ts` and is reachable by
+ * exactly two forms: a relative path, and the bare `src/…` specifier that the
+ * root tsconfig `paths` and the Jest `moduleNameMapper` both resolve. An
+ * `@/`-aliased specifier resolves under none of tsc, webpack or Jest, so a
+ * hardcoded one turns every fix into a broken import (#1390).
+ *
+ * Files under a `src/` segment take the relative form, which dominates the
+ * codebase and stays correct even where `paths` are unavailable; the `../`
+ * count comes from the file's own depth below the root that owns its `src/`
+ * segment. Returns null when no correct specifier exists, which makes the
+ * caller decline the fix rather than write an import that cannot resolve.
+ */
+function buildQueryKeysSpecifier(sourceFilePath, cwd) {
+    const absoluteFilename = toAbsoluteFilename(sourceFilePath, cwd);
+    const tierIndex = absoluteFilename.indexOf(SRC_TIER_SEGMENT);
+    if (tierIndex === -1) {
+        return QUERY_KEYS_MODULE;
+    }
+    // The project root is everything up to and including the separator that
+    // precedes the file's own `src/` segment.
+    const projectRoot = absoluteFilename.slice(0, tierIndex + 1);
+    const targetPath = path_1.default.join(projectRoot, QUERY_KEYS_MODULE);
+    const relativePath = path_1.default.relative(path_1.default.dirname(absoluteFilename), targetPath);
+    if (!isValidRelativePath(relativePath)) {
+        return null;
+    }
+    return ensureRelativeSpecifier(toPosixPath(relativePath));
+}
 /**
  * Rule to enforce the use of centralized router state key constants imported from
  * `src/util/routing/queryKeys.ts` instead of arbitrary string literals when calling
@@ -19,13 +67,16 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
         fixable: 'code',
         schema: [],
         messages: {
-            preferGlobalRouterStateKey: 'Router state key {{keyValue}} is a string literal. String literals bypass the shared queryKeys.ts QUERY_KEY_* constants, which leads to duplicate router cache entries and makes allowed keys hard to discover. Import the corresponding QUERY_KEY_* constant from "@/util/routing/queryKeys" (or its approved re-export) and pass that to useRouterState instead.',
-            invalidQueryKeySource: 'Router state key variable "{{variableName}}" is not sourced from queryKeys.ts. useRouterState keys must come from QUERY_KEY_* exports so routing cache keys stay stable and traceable. Import the matching constant from "@/util/routing/queryKeys" (or its approved re-export) and use that value here instead of {{variableName}}.',
+            preferGlobalRouterStateKey: 'Router state key {{keyValue}} is a string literal. String literals bypass the shared queryKeys.ts QUERY_KEY_* constants, which leads to duplicate router cache entries and makes allowed keys hard to discover. Import the corresponding QUERY_KEY_* constant from "src/util/routing/queryKeys" (a relative path to that module, or an approved re-export) and pass that to useRouterState instead.',
+            invalidQueryKeySource: 'Router state key variable "{{variableName}}" is not sourced from queryKeys.ts. useRouterState keys must come from QUERY_KEY_* exports so routing cache keys stay stable and traceable. Import the matching constant from "src/util/routing/queryKeys" (a relative path to that module, or an approved re-export) and use that value here instead of {{variableName}}.',
         },
     },
     defaultOptions: [],
     create(context) {
         const sourceCode = context.sourceCode;
+        const cwd = typeof context.getCwd === 'function' ? context.getCwd() : process.cwd();
+        const absoluteFilename = toAbsoluteFilename(context.getFilename(), cwd);
+        const queryKeysSpecifier = buildQueryKeysSpecifier(context.getFilename(), cwd);
         // Prevent duplicate import insertions when multiple fixes target the same query key constant.
         const scheduledQueryKeyNamedImports = new Set();
         // Track imports from queryKeys.ts
@@ -48,8 +99,21 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
             const normalized = source
                 .replace(/^@\/|^src\//, '')
                 .replace(/^(\.\/|\.\.\/)+/, '');
-            return (validQueryKeySources.has(normalized) ||
-                normalized.endsWith('util/routing/queryKeys'));
+            if (validQueryKeySources.has(normalized) ||
+                normalized.endsWith(QUERY_KEYS_SUFFIX)) {
+                return true;
+            }
+            // A relative specifier can name the module without spelling out
+            // `util/routing`: a sibling reaches it as `./queryKeys`, and a file two
+            // directories below `src/util` as `../../routing/queryKeys`. Resolving
+            // against the linted file recognizes those, which also keeps the fix's own
+            // relative output recognized on the next pass so a second violation
+            // extends that import instead of duplicating it.
+            if (!source.startsWith('.')) {
+                return false;
+            }
+            const resolved = toPosixPath(path_1.default.resolve(path_1.default.dirname(absoluteFilename), source));
+            return resolved.endsWith(`/${QUERY_KEYS_SUFFIX}`);
         }
         /**
          * Check if an identifier is a valid QUERY_KEY constant
@@ -57,6 +121,28 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
         function isValidQueryKeyConstant(name) {
             return name.startsWith('QUERY_KEY_');
         }
+        /**
+         * `SourceCode#getScope` supersedes the deprecated `context.getScope`; the
+         * fallback keeps the rule working on ESLint versions that predate it.
+         */
+        function scopeOf(node) {
+            const scoped = sourceCode;
+            return typeof scoped.getScope === 'function'
+                ? scoped.getScope(node)
+                : context.getScope();
+        }
+        /**
+         * A parameter binding holds a different value on every call, so no single
+         * `QUERY_KEY_*` constant can stand in for it: a hook that iterates a
+         * constant array of keys hands each one to a callback parameter by design
+         * (#1394). Reporting such an identifier demands a substitution that does not
+         * exist, and the caller — not this file — decides which key is passed.
+         */
+        function isParameterBinding(identifier) {
+            const variable = utils_1.ASTUtils.findVariable(scopeOf(identifier), identifier);
+            const definition = variable?.defs[0];
+            return definition?.type === utils_1.TSESLint.Scope.DefinitionType.Parameter;
+        }
         /**
          * Check if a node represents a valid query key usage
          */
@@ -284,7 +370,9 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
                                                             if (scheduledQueryKeyNamedImports.has(suggestedConstant)) {
                                                                 return fixes;
                                                             }
-                                                            const importText = `import { ${suggestedConstant} } from '@/util/routing/queryKeys';\n`;
+                                                            const importText = queryKeysSpecifier === null
+                                                                ? null
+                                                                : `import { ${suggestedConstant} } from '${queryKeysSpecifier}';\n`;
                                                             const queryKeysNamedImport = sourceCode.ast.body.find((n) => n.type ===
                                                                 utils_1.AST_NODE_TYPES.ImportDeclaration &&
                                                                 n.importKind !== 'type' &&
@@ -304,6 +392,13 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
                                                                 const lastSpecifier = importSpecifiers[importSpecifiers.length - 1];
                                                                 fixes.push(fixer.insertTextAfter(lastSpecifier, `, ${suggestedConstant}`));
                                                             }
+                                                            else if (importText === null) {
+                                                                // Extending an existing named import needs no
+                                                                // specifier of its own, so only a freshly
+                                                                // written import statement depends on one being
+                                                                // derivable.
+                                                                return null;
+                                                            }
                                                             else if (sideEffectImport) {
                                                                 fixes.push(fixer.replaceText(sideEffectImport, importText.trimEnd()));
                                                             }
@@ -335,7 +430,8 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
                                             },
                                         });
                                     }
-                                    else if (keyValue.type === utils_1.AST_NODE_TYPES.Identifier) {
+                                    else if (keyValue.type === utils_1.AST_NODE_TYPES.Identifier &&
+                                        !isParameterBinding(keyValue)) {
                                         context.report({
                                             node: keyValue,
                                             messageId: 'invalidQueryKeySource',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blumintinc/eslint-plugin-blumint",
-  "version": "1.20.19",
+  "version": "1.20.21",
   "description": "Custom eslint rules for use within BluMint",
   "author": {
     "name": "Brodie McGuire",

package/release-manifest.json

@@ -1,4 +1,48 @@
 [
+  {
+    "version": "1.20.21",
+    "date": "2026-07-29T23:50:58.620Z",
+    "rules": [
+      {
+        "name": "enforce-querykey-ts",
+        "changeType": "fix",
+        "issues": [
+          1393
+        ],
+        "summary": "exempt parameter bindings from the constant requirement (closes #1393)"
+      },
+      {
+        "name": "prefer-global-router-state-key",
+        "changeType": "fix",
+        "issues": [
+          1394
+        ],
+        "summary": "exempt parameter bindings from the constant requirement (closes #1394)"
+      }
+    ]
+  },
+  {
+    "version": "1.20.20",
+    "date": "2026-07-29T19:25:11.467Z",
+    "rules": [
+      {
+        "name": "enforce-querykey-ts",
+        "changeType": "fix",
+        "issues": [
+          1391
+        ],
+        "summary": "derive the inserted queryKeys import specifier (closes #1391)"
+      },
+      {
+        "name": "prefer-global-router-state-key",
+        "changeType": "fix",
+        "issues": [
+          1390
+        ],
+        "summary": "derive queryKeys import specifier from file path (closes #1390)"
+      }
+    ]
+  },
   {
     "version": "1.20.19",
     "date": "2026-07-29T18:36:35.802Z",