@blumintinc/eslint-plugin-blumint 1.20.129 → 1.20.130

package/lib/index.js

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

package/lib/rules/enforce-dynamic-file-naming.js

@@ -5,19 +5,82 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DYNAMIC_RULES_LABEL = exports.REQUIRE_DYNAMIC_FIREBASE_IMPORTS_RULE = exports.RULE_NAME = void 0;
 const path_1 = __importDefault(require("path"));
+const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 exports.RULE_NAME = 'enforce-dynamic-file-naming';
 const ENFORCE_DYNAMIC_IMPORTS_RULE = '@blumintinc/blumint/enforce-dynamic-imports';
 exports.REQUIRE_DYNAMIC_FIREBASE_IMPORTS_RULE = '@blumintinc/blumint/require-dynamic-firebase-imports';
 exports.DYNAMIC_RULES_LABEL = `${ENFORCE_DYNAMIC_IMPORTS_RULE} or ${exports.REQUIRE_DYNAMIC_FIREBASE_IMPORTS_RULE}`;
-const SHORTHAND_DISABLE_NEXT_LINE = /\bednl\b/;
-const SHORTHAND_DISABLE_LINE = /\bedl\b/;
 const DISABLE_NEXT_LINE_TOKEN = 'eslint-disable-next-line';
 const DISABLE_LINE_TOKEN = 'eslint-disable-line';
-const DISABLE_BLOCK_PATTERN = /\beslint-disable\b(?!-)/;
-const disabledRuleNameFrom = (commentText) => {
-    const mentionsEnforceDynamicImports = commentText.includes(ENFORCE_DYNAMIC_IMPORTS_RULE);
-    const mentionsRequireDynamicFirebaseImports = commentText.includes(exports.REQUIRE_DYNAMIC_FIREBASE_IMPORTS_RULE);
+const DISABLE_TOKEN = 'eslint-disable';
+/**
+ * ESLint splits a directive comment on ` -- ` and treats the tail as a human
+ * justification, never as part of the rule list. A rule named only in the tail
+ * is prose, so it must not read as a bypass.
+ */
+const JUSTIFICATION_SEPARATOR = /\s-{2,}\s/;
+/**
+ * Mirrors ESLint's own `directivesPattern`: the directive has to be the FIRST
+ * token of the comment, followed by whitespace or the end of the comment.
+ * `// see eslint-disable-next-line <rule>` is prose to ESLint and suppresses
+ * nothing, so it cannot count as an acknowledged exception here either.
+ *
+ * The alternatives are ordered longest-first because `eslint-disable` would
+ * otherwise shadow the two suffixed spellings.
+ */
+const DIRECTIVE_PATTERN = new RegExp(`^(${DISABLE_NEXT_LINE_TOKEN}|${DISABLE_LINE_TOKEN}|${DISABLE_TOKEN})(?:\\s|$)`);
+/**
+ * The only two directives ESLint honors inside a `//` comment. A bare
+ * `// eslint-disable <rule>` is inert — ESLint parses `eslint-disable` only out
+ * of a block comment — so blessing it would hand a reviewer a documented
+ * exception while the sibling rule keeps failing CI.
+ */
+const LINE_COMMENT_DIRECTIVES = new Set([
+    DISABLE_NEXT_LINE_TOKEN,
+    DISABLE_LINE_TOKEN,
+]);
+/**
+ * The rule names a comment actually disables, or `null` when ESLint would not
+ * read the comment as a disable directive at all.
+ */
+const disabledRuleNamesFrom = (comment) => {
+    const justification = JUSTIFICATION_SEPARATOR.exec(comment.value);
+    const directivePart = (justification ? comment.value.slice(0, justification.index) : comment.value).trim();
+    const match = DIRECTIVE_PATTERN.exec(directivePart);
+    if (!match) {
+        return null;
+    }
+    const directiveText = match[1];
+    if (comment.type !== utils_1.AST_TOKEN_TYPES.Block &&
+        !LINE_COMMENT_DIRECTIVES.has(directiveText)) {
+        return null;
+    }
+    // ESLint rejects a multi-line `eslint-disable-line` outright and reports the
+    // comment as a problem instead of applying it.
+    if (directiveText === DISABLE_LINE_TOKEN &&
+        comment.loc.start.line !== comment.loc.end.line) {
+        return null;
+    }
+    return directivePart
+        .slice(directiveText.length)
+        .split(',')
+        .map((ruleName) => ruleName.trim().replace(/^(['"])(.*)\1$/s, '$2'))
+        .filter((ruleName) => ruleName.length > 0);
+};
+/**
+ * The rule has to be named explicitly. An unnamed blanket disable is not a
+ * counter-example: it silences this rule too, so no report is observable on
+ * such a file either way.
+ */
+const disabledRuleNameFrom = (comment) => {
+    const disabledRuleNames = disabledRuleNamesFrom(comment);
+    if (disabledRuleNames === null) {
+        return null;
+    }
+    const disabled = new Set(disabledRuleNames);
+    const mentionsEnforceDynamicImports = disabled.has(ENFORCE_DYNAMIC_IMPORTS_RULE);
+    const mentionsRequireDynamicFirebaseImports = disabled.has(exports.REQUIRE_DYNAMIC_FIREBASE_IMPORTS_RULE);
     if (mentionsEnforceDynamicImports && mentionsRequireDynamicFirebaseImports) {
         return exports.DYNAMIC_RULES_LABEL;
     }
@@ -59,16 +122,8 @@ exports.default = (0, createRule_1.createRule)({
                 const sourceCode = context.getSourceCode();
                 const comments = sourceCode.getAllComments();
                 for (const comment of comments) {
-                    const commentText = comment.value.trim();
-                    const disabledRuleNameForComment = disabledRuleNameFrom(commentText);
-                    const disablesTargetRule = disabledRuleNameForComment !== null;
-                    const inlineDisable = (commentText.includes(DISABLE_NEXT_LINE_TOKEN) ||
-                        commentText.includes(DISABLE_LINE_TOKEN) ||
-                        SHORTHAND_DISABLE_NEXT_LINE.test(commentText) ||
-                        SHORTHAND_DISABLE_LINE.test(commentText)) &&
-                        disablesTargetRule;
-                    const blockDisable = DISABLE_BLOCK_PATTERN.test(commentText) && disablesTargetRule;
-                    if (inlineDisable || blockDisable) {
+                    const disabledRuleNameForComment = disabledRuleNameFrom(comment);
+                    if (disabledRuleNameForComment !== null) {
                         foundDisableDirective = true;
                         disabledRuleName = disabledRuleNameForComment;
                         break;

package/lib/rules/enforce-global-constants.d.ts

@@ -1,4 +1,4 @@
 import { TSESLint } from '@typescript-eslint/utils';
-type MessageIds = 'useGlobalConstant' | 'extractDefaultToGlobalConstant';
+type MessageIds = 'useGlobalConstant' | 'extractDefaultToGlobalConstant' | 'declareMemoDependency';
 export declare const enforceGlobalConstants: TSESLint.RuleModule<MessageIds, [], TSESLint.RuleListener>;
 export {};

package/lib/rules/enforce-global-constants.js

@@ -5,6 +5,86 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const shebang_1 = require("../utils/shebang");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+/**
+ * Scope kinds whose bindings are established once per module evaluation:
+ * globals, imports and module-level declarations. A literal reading one of those
+ * can still be hoisted verbatim, because the name it reads is in scope at module
+ * level too.
+ */
+const MODULE_LEVEL_SCOPE_TYPES = new Set(['global', 'module']);
+/**
+ * True when `inner` lies entirely inside `outer`'s source range.
+ */
+function isRangeWithin(inner, outer) {
+    return inner[0] >= outer[0] && inner[1] <= outer[1];
+}
+/**
+ * True when a reference appears purely in type position (an annotation, or the
+ * target of an `as`/`satisfies`). Types erase at compile time, so such a name
+ * neither blocks hoisting nor belongs in a dependency array. The flags are read
+ * defensively: an analyzer that omits them leaves the reference classified as a
+ * value, which keeps the conservative answer.
+ */
+function isTypeOnlyReference(reference) {
+    const flags = reference;
+    return flags.isTypeReference === true && flags.isValueReference === false;
+}
+/**
+ * True when a reference names a value that can differ between renders, i.e. one
+ * bound INSIDE the module and OUTSIDE the memo callback: a prop, a local, a
+ * destructured value, another hook's result.
+ *
+ * Everything else leaves hoisting available. An unresolved name is an ambient
+ * global. A module- or global-scoped binding is fixed for the module's lifetime
+ * and is equally visible from module scope. A binding whose own scope sits
+ * inside the callback — the callback's parameters, its locals, a nested
+ * function's locals — is created by the callback rather than closed over.
+ */
+function isRenderScopeReference(reference, callbackRange) {
+    const variable = reference.resolved;
+    if (!variable) {
+        return false;
+    }
+    if (MODULE_LEVEL_SCOPE_TYPES.has(variable.scope.type)) {
+        return false;
+    }
+    return !isRangeWithin(variable.scope.block.range, callbackRange);
+}
+/**
+ * The first render-scope value a memo callback reads, in source order, or null
+ * when it reads none.
+ *
+ * Answered from RESOLVED scope references rather than identifier names, so
+ * shadowing, destructuring and imports are accounted for exactly as the scope
+ * analyzer sees them. The whole callback is the unit of analysis, not just the
+ * returned literal: `const debounce = delay * 2; return { debounce };` closes
+ * over `delay` just as `return { debounce: delay }` does, and naming the
+ * callback-local `debounce` would prescribe a dependency that does not exist
+ * outside the callback.
+ */
+function findRenderScopeDependency(callbackScope, callbackRange) {
+    let earliest = null;
+    const pending = [callbackScope];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        for (const reference of current.references) {
+            if (isTypeOnlyReference(reference)) {
+                continue;
+            }
+            if (!isRenderScopeReference(reference, callbackRange)) {
+                continue;
+            }
+            // Source order rather than traversal order, so the reported name does not
+            // depend on how the scope tree happens to be walked.
+            if (!earliest ||
+                reference.identifier.range[0] < earliest.identifier.range[0]) {
+                earliest = reference;
+            }
+        }
+        pending.push(...current.childScopes);
+    }
+    return earliest ? earliest.identifier.name : null;
+}
 exports.enforceGlobalConstants = (0, createRule_1.createRule)({
     name: 'enforce-global-constants',
     meta: {
@@ -18,6 +98,7 @@ exports.enforceGlobalConstants = (0, createRule_1.createRule)({
         messages: {
             useGlobalConstant: 'Object literal returned from useMemo with empty dependencies creates a new reference every render without providing memoization benefits → this wastes memory and misleads readers into thinking the value is computed → move the object to a module-level constant (e.g., const OPTIONS = { ... } as const;).',
             extractDefaultToGlobalConstant: 'Inline default value in destructuring creates a new reference on every render → this causes unnecessary re-renders in child components due to unstable identity → extract the default to a module-level constant (e.g., const DEFAULT_OPTIONS = { ... } as const;).',
+            declareMemoDependency: 'Object literal returned from useMemo reads "{{name}}" from the surrounding render scope while declaring an empty dependency array → the memo keeps the "{{name}}" captured on the first render and never recomputes, so the object silently goes stale, and it cannot be hoisted to a module-level constant because "{{name}}" exists only during a render → declare "{{name}}" (and every other render-scope value the callback reads) in the dependency array, or drop the useMemo if the object is meant to be constant.',
         },
     },
     defaultOptions: [],
@@ -169,6 +250,19 @@ exports.enforceGlobalConstants = (0, createRule_1.createRule)({
             }
             return { kind: 'free' };
         }
+        /**
+         * The first render-scope value the memo callback reads, or null when it
+         * reads none and the literal is therefore hoistable as written.
+         */
+        function getRenderScopeDependency(callback) {
+            const callbackScope = sourceCode.scopeManager?.acquire(callback);
+            if (!callbackScope) {
+                // Without scope analysis nothing can be shown to be closed over, so the
+                // literal keeps the hoisting report the rule has always emitted.
+                return null;
+            }
+            return findRenderScopeDependency(callbackScope, callback.range);
+        }
         function buildInitializerText(initText) {
             const needsAsConst = /^(?:true|false|-?\d|\[|\{|[`'"])/.test(initText) &&
                 !/\bas const\b/.test(initText);
@@ -331,15 +425,31 @@ exports.enforceGlobalConstants = (0, createRule_1.createRule)({
                 if (returnValue.type === utils_1.AST_NODE_TYPES.TSAsExpression) {
                     actualReturnValue = returnValue.expression;
                 }
-                if (actualReturnValue.type === utils_1.AST_NODE_TYPES.ObjectExpression ||
-                    (actualReturnValue.type === utils_1.AST_NODE_TYPES.ArrayExpression &&
+                if (actualReturnValue.type !== utils_1.AST_NODE_TYPES.ObjectExpression &&
+                    !(actualReturnValue.type === utils_1.AST_NODE_TYPES.ArrayExpression &&
                         actualReturnValue.elements.some((element) => element !== null &&
                             element.type === utils_1.AST_NODE_TYPES.ObjectExpression))) {
+                    return;
+                }
+                // An empty dependency array means the author DECLARED no dependencies,
+                // not that there are none. When the callback closes over a render-scope
+                // value, hoisting the literal to module scope does not compile — the
+                // name it reads exists only during a render — so prescribing a global
+                // constant is advice that cannot be followed. The reachable remedy is
+                // the omitted dependency, which is what the split below names.
+                const renderScopeDependency = getRenderScopeDependency(callback);
+                if (renderScopeDependency !== null) {
                     context.report({
                         node,
-                        messageId: 'useGlobalConstant',
+                        messageId: 'declareMemoDependency',
+                        data: { name: renderScopeDependency },
                     });
+                    return;
                 }
+                context.report({
+                    node,
+                    messageId: 'useGlobalConstant',
+                });
             },
             VariableDeclaration(node) {
                 const relevantDeclarators = node.declarations.filter((d) => d.id.type === utils_1.AST_NODE_TYPES.ObjectPattern ||

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

@@ -39,6 +39,18 @@ const APPROVED_REEXPORT_SOURCES = new Set(['constants', 'constants/index']);
  * is.
  */
 const normalizeSpecifier = (source) => source.replace(/^@\/|^src\//, '').replace(/^(\.\/|\.\.\/)+/, '');
+const ASSERTION_NODE_TYPES = new Set([
+    utils_1.AST_NODE_TYPES.TSAsExpression,
+    utils_1.AST_NODE_TYPES.TSSatisfiesExpression,
+    utils_1.AST_NODE_TYPES.TSNonNullExpression,
+    utils_1.AST_NODE_TYPES.TSTypeAssertion,
+]);
+const isTypeAssertion = (node) => ASSERTION_NODE_TYPES.has(node.type);
+/**
+ * The expression an assertion — or a stack of them, since they compose — is
+ * written onto.
+ */
+const unwrapTypeAssertions = (node) => isTypeAssertion(node) ? unwrapTypeAssertions(node.expression) : node;
 const toPosixPath = (filePath) => filePath.replace(/\\/g, '/');
 const ensureRelativeSpecifier = (specifier) => specifier.startsWith('.') ? specifier : `./${specifier}`;
 const isWindowsDrivePath = (filePath) => /^[A-Za-z]:[\\/]/.test(filePath);
@@ -387,6 +399,17 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
             if (node.type === utils_1.AST_NODE_TYPES.ChainExpression) {
                 return isValidQueryKeyUsage(node.expression);
             }
+            // The same argument, and it holds more strongly for an assertion: `as
+            // const`, `satisfies string`, `!` and `<string>KEY` are erased before
+            // anything runs, so what they evaluate to is the very key they wrap.
+            // Naming none of these types made an asserted key fall through to
+            // `return false`, and an alias records its initializer exactly as
+            // written — so a type spelled onto an alias of an approved constant
+            // withdrew the carve-out that same alias has without one, reporting a key
+            // `prefer-global-router-state-key` accepts (#1840).
+            if (isTypeAssertion(node)) {
+                return isValidQueryKeyUsage(node.expression);
+            }
             if (node.type === utils_1.AST_NODE_TYPES.Identifier) {
                 const importInfo = queryKeyImports.get(node.name);
                 if (importInfo && isQueryKeysSource(importInfo.source)) {
@@ -452,6 +475,15 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
          * Check if a node contains string literals that should be reported
          */
         function containsInvalidStringLiteral(node) {
+            // A type says nothing about where a key came from, and a literal under
+            // one came from nowhere just the same. Answering on the assertion node
+            // instead of what it wraps let `'key' as const` — and an asserted operand
+            // of a concatenation or a ternary — pass for something other than a
+            // string literal, so the only bare-key detector this rule has never ran
+            // on it (#1842).
+            if (isTypeAssertion(node)) {
+                return containsInvalidStringLiteral(node.expression);
+            }
             // Direct string literal
             if (node.type === utils_1.AST_NODE_TYPES.Literal &&
                 typeof node.value === 'string') {
@@ -517,6 +549,31 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
             }
             return null;
         }
+        /**
+         * The span a substituted constant is written over: the literal together
+         * with every assertion written onto it.
+         *
+         * The assertion is dropped rather than kept because it exists to shape the
+         * literal, and the literal is what leaves. `as const` is illegal on a
+         * reference (TS1355), so writing the constant *inside* the assertion would
+         * trade a report for a file that no longer compiles; the other notations
+         * survive that but only to restate a type the constant already has, since
+         * `queryKeys.ts` exports it narrowed. Replacing the whole span is therefore
+         * both the only uniformly compiling choice and the smaller edit to read.
+         *
+         * Null where a comment sits in the span the constant would cover: no
+         * rewrite can know what a comment beside a key meant, and deleting it is
+         * text this fixer does not own. The report then stands unfixed, which
+         * leaves the author holding both the key and the comment.
+         */
+        function substitutionSpanOf(keyExpression, staticKeyNode) {
+            if (keyExpression === staticKeyNode) {
+                return keyExpression;
+            }
+            return sourceCode.getCommentsInside(keyExpression).length === 0
+                ? keyExpression
+                : null;
+        }
         /**
          * The `QUERY_KEY_*` constant a key value names, or null when it names none.
          *
@@ -599,7 +656,18 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
                                 prop.key.name === 'key');
                             // If key property exists, check its value
                             if (keyProperty && keyProperty.value) {
-                                const keyValue = keyProperty.value;
+                                const keyExpression = keyProperty.value;
+                                // A type written onto the key is erased before anything runs,
+                                // so what the arms below have to judge is the key underneath
+                                // it. Dispatching on the node as written asked about the
+                                // assertion — a node type neither arm names — so an invalid key
+                                // escaped the rule altogether merely by carrying one, while the
+                                // resolver behind `isValidQueryKeyUsage` had long since seen
+                                // through it: detecting and resolving are separate paths, and
+                                // widening one leaves the other exactly as it was (#1842).
+                                // Reporting the unwrapped node puts the report on the same key
+                                // the unasserted spelling reports.
+                                const keyValue = unwrapTypeAssertions(keyExpression);
                                 // Check if it's a valid query key usage
                                 if (!isValidQueryKeyUsage(keyValue)) {
                                     // Check if it contains invalid string literals
@@ -609,12 +677,15 @@ exports.enforceQueryKeyTs = (0, createRule_1.createRule)({
                                         const suggestedConstant = staticKey
                                             ? generateAutoFix(staticKey.text)
                                             : null;
+                                        const span = staticKey
+                                            ? substitutionSpanOf(keyExpression, staticKey.node)
+                                            : null;
                                         pendingReports.push({
                                             node: keyValue,
                                             messageId: 'enforceQueryKeyImport',
-                                            substitution: staticKey && suggestedConstant
+                                            substitution: span && suggestedConstant
                                                 ? {
-                                                    keyNode: staticKey.node,
+                                                    keyNode: span,
                                                     constant: suggestedConstant,
                                                     scope: scopeOf(keyValue),
                                                 }

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,35 @@
 [
+  {
+    "version": "1.20.130",
+    "date": "2026-08-07T08:38:15.008Z",
+    "rules": [
+      {
+        "name": "enforce-dynamic-file-naming",
+        "changeType": "fix",
+        "issues": [
+          1843
+        ],
+        "summary": "honor only the disable directives ESLint itself honors (closes #1843)"
+      },
+      {
+        "name": "enforce-global-constants",
+        "changeType": "fix",
+        "issues": [
+          1841
+        ],
+        "summary": "name the reachable remedy when a memo literal closes over render scope (closes #1841)"
+      },
+      {
+        "name": "enforce-querykey-ts",
+        "changeType": "fix",
+        "issues": [
+          1840,
+          1842
+        ],
+        "summary": "see through a type assertion at the report site (closes #1842); resolve an aliased key through a type assertion (closes #1840)"
+      }
+    ]
+  },
   {
     "version": "1.20.129",
     "date": "2026-08-07T06:47:26.731Z",