@blumintinc/eslint-plugin-blumint 1.19.8 → 1.19.10

package/lib/index.js

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

package/lib/rules/global-const-style.d.ts

@@ -1,3 +1,4 @@
+import { TSESLint } from '@typescript-eslint/utils';
 type MessageIds = 'upperSnakeCase' | 'asConst';
-declare const _default: import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleModule<MessageIds, [], import("@typescript-eslint/utils/dist/ts-eslint/Rule").RuleListener>;
+declare const _default: TSESLint.RuleModule<MessageIds, [], TSESLint.RuleListener>;
 export default _default;

package/lib/rules/global-const-style.js

@@ -3,6 +3,86 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const isUpperSnakeCase = (str) => /^[A-Z][A-Z0-9_]*$/.test(str);
+// Jest mock handles produced by an `as` cast to a `jest.Mock*` type are
+// stateful test doubles that are reassigned/mutated through
+// `.mockImplementation()`, `.mockReturnValue()`, etc. They are not immutable
+// module configuration, and the `mockedX` camelCase spelling is the established
+// idiom, so they are exempt from the UPPER_SNAKE_CASE rename requirement.
+const JEST_MOCK_TYPE_NAMES = new Set([
+    'Mock',
+    'MockedFunction',
+    'Mocked',
+    'MockedClass',
+]);
+// Match `expr as jest.Mock<...>` / `jest.MockedFunction<...>` /
+// `jest.Mocked<...>` / `jest.MockedClass<...>`. The match is kept deliberately
+// narrow — a qualified `jest.<MockType>` type reference — so unrelated `as`
+// casts keep triggering the rename check.
+const isJestMockCast = (node) => {
+    if (node.type !== utils_1.AST_NODE_TYPES.TSAsExpression) {
+        return false;
+    }
+    const typeAnnotation = node.typeAnnotation;
+    if (typeAnnotation.type !== utils_1.AST_NODE_TYPES.TSTypeReference) {
+        return false;
+    }
+    const { typeName } = typeAnnotation;
+    return (typeName.type === utils_1.AST_NODE_TYPES.TSQualifiedName &&
+        typeName.left.type === utils_1.AST_NODE_TYPES.Identifier &&
+        typeName.left.name === 'jest' &&
+        typeName.right.type === utils_1.AST_NODE_TYPES.Identifier &&
+        JEST_MOCK_TYPE_NAMES.has(typeName.right.name));
+};
+/**
+ * Walks the scope chain upward from `scope` (inclusive) and reports whether
+ * `targetName` is bound anywhere between `scope` and `stopScope` (inclusive).
+ * Mirrors how the engine resolves an identifier at a use site: the first scope
+ * on the chain that declares the name wins. Used to detect whether a rewritten
+ * reference would be captured by a binding sitting between it and the
+ * declaration it currently resolves to.
+ */
+const isNameBoundInChain = (scope, stopScope, targetName) => {
+    let current = scope;
+    while (current) {
+        if (current.set.has(targetName)) {
+            return true;
+        }
+        if (current === stopScope) {
+            break;
+        }
+        current = current.upper;
+    }
+    return false;
+};
+/**
+ * Returns true when renaming `variable` to `newName` would collide with an
+ * existing binding in any scope the rename touches, making the autofix
+ * semantics-changing (and thus unsafe). The rename fixer rewrites the
+ * declaration plus every in-file reference to `newName`; if `newName` already
+ * resolves to a different binding the rewrite would either redeclare a name
+ * already bound in the declaration scope or capture a reference onto an
+ * intervening binding. In every such case the fix is suppressed (report-only).
+ */
+const renameWouldCollide = (variable, newName) => {
+    const declarationScope = variable.scope;
+    // (1) Declaration site: `newName` already bound in the scope that holds the
+    //     declaration would make the rename a redeclaration/shadow. The declared
+    //     variable itself carries the old name, so any entry for `newName` is a
+    //     distinct, colliding binding.
+    if (declarationScope.set.has(newName)) {
+        return true;
+    }
+    // (2) Reference sites: a binding of `newName` sitting between a reference and
+    //     the declaration scope would swallow the rewritten identifier — the
+    //     reference would resolve to that binding instead of the constant.
+    for (const ref of variable.references) {
+        const referenceScope = ref.from ?? declarationScope;
+        if (isNameBoundInChain(referenceScope, declarationScope, newName)) {
+            return true;
+        }
+    }
+    return false;
+};
 // Next.js recognizes these export names by their literal identifier, so
 // renaming them to UPPER_SNAKE_CASE silently breaks the framework contract
 // (e.g. `export const config` controls the API-route body parser / runtime).
@@ -207,12 +287,16 @@ exports.default = (0, createRule_1.createRule)({
                     if (isExported && NEXTJS_RESERVED_EXPORTS.has(name)) {
                         return;
                     }
-                    // Check for UPPER_SNAKE_CASE
-                    if (!isUpperSnakeCase(name)) {
+                    // Check for UPPER_SNAKE_CASE. Jest mock handles (`x as jest.Mock<…>`)
+                    // are exempt: they are mutable test doubles, not immutable config, so
+                    // the `mockedX` idiom is intentional. The exemption gates only this
+                    // rename check — the `as const` logic above is untouched.
+                    if (!isUpperSnakeCase(name) && !isJestMockCast(init)) {
                         const newName = name
                             .replace(/([A-Z])/g, '_$1')
                             .toUpperCase()
                             .replace(/^_/, '');
+                        const idNode = declaration.id;
                         context.report({
                             node: declaration,
                             messageId: 'upperSnakeCase',
@@ -221,12 +305,50 @@ exports.default = (0, createRule_1.createRule)({
                                 suggestedName: newName,
                             },
                             fix(fixer) {
-                                if (typeAnnotation) {
-                                    return fixer.replaceText(declaration, `${newName}${typeText} = ${initText}`);
+                                // Resolve the declared variable so the rename can rewrite the
+                                // declaration AND every reference together. Renaming only the
+                                // declaration id (the previous behavior) left every use site
+                                // bound to a now-undefined name — `--fix` exited 0 while
+                                // silently corrupting working code (Issue #1313, same defect
+                                // class as #1256).
+                                const declaredVariable = context
+                                    .getDeclaredVariables(declaration)
+                                    .find((variable) => variable.name === name) ?? null;
+                                // Cannot resolve the variable — never emit a partial rename.
+                                if (!declaredVariable) {
+                                    return null;
+                                }
+                                // Exported symbols with in-file use sites are cross-file
+                                // contracts whose importers a single-file fixer cannot reach;
+                                // rewriting the local sites alone would still leave the export
+                                // renamed and importers broken. Report-only. (A bare exported
+                                // declaration with no extra references keeps the historical
+                                // rename behavior — nothing to orphan in-file.)
+                                const hasExtraReferences = declaredVariable.references.some((ref) => ref.identifier !== idNode);
+                                if (isExported && hasExtraReferences) {
+                                    return null;
+                                }
+                                // Suppress the fix when `newName` already binds something in a
+                                // scope the rename would touch — a rename fixer must never
+                                // change program semantics or shadow an existing binding.
+                                if (renameWouldCollide(declaredVariable, newName)) {
+                                    return null;
                                 }
-                                else {
-                                    return fixer.replaceText(declaration.id, newName);
+                                // Rewrite the declaration id (preserving any type annotation,
+                                // whose range is part of the id node) plus every reference.
+                                const fixes = [
+                                    fixer.replaceText(idNode, typeAnnotation ? `${newName}${typeText}` : newName),
+                                ];
+                                for (const ref of declaredVariable.references) {
+                                    // The declaration write reference is the id node itself and
+                                    // is already handled above. Skipping it also avoids emitting
+                                    // overlapping fix ranges, which ESLint rejects.
+                                    if (ref.identifier === idNode) {
+                                        continue;
+                                    }
+                                    fixes.push(fixer.replaceText(ref.identifier, newName));
                                 }
+                                return fixes;
                             },
                         });
                     }

package/lib/rules/no-harness-coupled-disables.js

@@ -43,6 +43,29 @@ const SESSION_MATCHER = {
 function isDirectiveComment(comment) {
     return DIRECTIVE_PREFIX.test(comment.value.trim());
 }
+/**
+ * Pointer phrasing by which a directive DEFERS its rationale to an adjacent
+ * comment: "see above", "per the note below", "as noted in the comment".
+ * Up to two intervening words ("the note", "the preceding") are tolerated so
+ * natural phrasings still register as deferrals.
+ */
+const DEFERRAL_PATTERN = /\b(?:see|per|as)\s+(?:\w+\s+){0,2}(?:above|below|note|comment|preceding)\b/i;
+/**
+ * A directive defers to its preceding comment only when its own `--` text is a
+ * mere pointer to that comment ("see above") or carries no substantive words at
+ * all (a bare "^" gesture). This is the discriminating signal for #1296's
+ * split-justification support: a directive that already states a substantive,
+ * self-contained reason owns its rationale outright, so an unrelated docblock or
+ * line comment that merely sits above it — documenting the declaration, not the
+ * suppression — must never contribute its incidental harness keywords (#1312).
+ */
+function defersToPreceding(justification) {
+    const text = justification.trim();
+    if (DEFERRAL_PATTERN.test(text)) {
+        return true;
+    }
+    return text.replace(/[^a-z]/gi, '') === '';
+}
 /**
  * Isolates the justification text of a directive comment: everything after the
  * first `--` separator, spanning every line of a multi-line block body. The
@@ -109,12 +132,16 @@ exports.noHarnessCoupledDisables = (0, createRule_1.createRule)({
                     }
                     // Split-justification style: an immediately-adjacent preceding
                     // non-directive comment (no intervening blank line or code) is part
-                    // of the directive's rationale when the directive defers to it.
+                    // of the directive's rationale ONLY when the directive defers to it.
+                    // Without the deferral gate, an unrelated docblock above the
+                    // declaration bleeds its incidental harness words into a directive
+                    // that already carries a self-contained code-level reason (#1312).
                     let scanned = justification;
                     const previous = comments[index - 1];
                     if (previous &&
                         !isDirectiveComment(previous) &&
-                        comment.loc.start.line - previous.loc.end.line <= 1) {
+                        comment.loc.start.line - previous.loc.end.line <= 1 &&
+                        defersToPreceding(justification)) {
                         scanned = `${previous.value}\n${scanned}`;
                     }
                     const matchedTerm = findHarnessTerm(scanned);

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,32 @@
 [
+  {
+    "version": "1.19.10",
+    "date": "2026-07-17T10:33:03.696Z",
+    "rules": [
+      {
+        "name": "global-const-style",
+        "changeType": "fix",
+        "issues": [
+          1313
+        ],
+        "summary": "scope-aware upperSnakeCase autofix + exempt jest mock handles (closes #1313)"
+      }
+    ]
+  },
+  {
+    "version": "1.19.9",
+    "date": "2026-07-17T01:27:12.035Z",
+    "rules": [
+      {
+        "name": "no-harness-coupled-disables",
+        "changeType": "fix",
+        "issues": [
+          1312
+        ],
+        "summary": "only merge preceding comment when directive defers to it (closes #1312)"
+      }
+    ]
+  },
   {
     "version": "1.19.8",
     "date": "2026-07-17T00:25:07.461Z",