@blumintinc/eslint-plugin-blumint 1.20.136 → 1.20.137

package/lib/index.js

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

package/lib/rules/logical-top-to-bottom-grouping.js

@@ -828,12 +828,31 @@ function truncateWithEllipsis(text, max = 60) {
  * handlers with contradictory targets, so the first handler to claim it wins and
  * the handler call order in `detectViolations` is the tie-break.
  */
-function record(sink, statement, messageId, data, fromIndex, toIndex) {
+function record(sink, statement, messageId, data, fromIndex, toIndex, relocatable = true) {
     if (sink.flagged.has(statement)) {
         return;
     }
     sink.flagged.add(statement);
-    sink.violations.push({ statement, messageId, data, fromIndex, toIndex });
+    sink.violations.push({
+        statement,
+        messageId,
+        data,
+        fromIndex,
+        toIndex,
+        relocatable,
+    });
+}
+/**
+ * The violations the reordering search is allowed to expand into moves, and the
+ * only ones its zero-violation goal test answers about.
+ *
+ * Screening here rather than at detection is what keeps the fix path identical to
+ * one that never saw an unrelocatable violation: the search's candidate moves, its
+ * budget and the order it certifies clean are all computed as if the report were
+ * absent, so adding a report can never redirect, weaken or block a fix.
+ */
+function relocatableViolations(violations) {
+    return violations.filter((violation) => violation.relocatable);
 }
 function isGuardIfStatement(statement) {
     if (statement.type !== utils_1.AST_NODE_TYPES.IfStatement || statement.alternate) {
@@ -1058,23 +1077,58 @@ function unwrappedInitOf(declarator) {
  *
  * The classification runs on the unwrapped initializer: an assertion is erased
  * before the code runs, so `1 as const` is exactly the movable literal `1` is.
+ *
+ * Every declarator must qualify, because the statement is diagnosed — and moved —
+ * as a whole. A sibling binding does not disqualify the statement: how many
+ * bindings a declaration introduces decides whether the fix may relocate it, not
+ * whether the declaration is far from the first use of what it declares (#1889).
  */
-function lateDeclarationCandidateOf(statement) {
+function lateDeclarationDeclaratorsOf(statement) {
     const declaration = variableDeclarationOf(statement);
-    if (!declaration || declaration.declarations.length !== 1) {
+    if (!declaration || declaration.declarations.length === 0) {
         return null;
     }
-    const [declarator] = declaration.declarations;
-    if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
-        return null;
+    const declarators = [];
+    for (const declarator of declaration.declarations) {
+        if (declarator.id.type !== utils_1.AST_NODE_TYPES.Identifier) {
+            return null;
+        }
+        const init = unwrappedInitOf(declarator);
+        if (init &&
+            init.type !== utils_1.AST_NODE_TYPES.Identifier &&
+            init.type !== utils_1.AST_NODE_TYPES.Literal) {
+            return null;
+        }
+        declarators.push(declarator);
     }
-    const init = unwrappedInitOf(declarator);
-    if (init &&
-        init.type !== utils_1.AST_NODE_TYPES.Identifier &&
-        init.type !== utils_1.AST_NODE_TYPES.Literal) {
-        return null;
+    return declarators;
+}
+/**
+ * Whether the reordering fix may relocate this statement to satisfy a
+ * late-declaration report.
+ *
+ * The fix moves whole statements, so relocating `const x = 1, y = 2;` carries `y`
+ * along — past its own first use in the general case, and always further than the
+ * report asked for. Splitting the declaration is the developer's call, so a
+ * declaration with sibling bindings is reported and left where it stands.
+ */
+function isRelocatableLateDeclaration(statement) {
+    return lateDeclarationDeclaratorsOf(statement)?.length === 1;
+}
+/**
+ * The binding the report names: the one whose own first use is the group's.
+ *
+ * A statement's bindings share its position, so the declaration is late relative to
+ * whichever of them is read first; naming a sibling read later would point the
+ * reader at the wrong line.
+ */
+function earliestUsedDeclarator(declarators, body, afterIndex, usageIndex) {
+    if (declarators.length === 1) {
+        return declarators[0];
     }
-    return declarator;
+    const earliest = declarators.find((declarator) => findFirstUsageIndex(body, new Set([declarator.id.name]), afterIndex) ===
+        usageIndex);
+    return earliest ?? declarators[0];
 }
 const LOOP_TYPES = new Set([
     utils_1.AST_NODE_TYPES.ForStatement,
@@ -1110,17 +1164,18 @@ function isMutatedInLoop(body, usageIndex, nameSet) {
 }
 function handleLateDeclarations(sink, body) {
     body.forEach((statement, index) => {
-        const declarator = lateDeclarationCandidateOf(statement);
-        if (!declarator) {
+        const declarators = lateDeclarationDeclaratorsOf(statement);
+        if (!declarators) {
             return;
         }
-        const name = declarator.id.name;
         const dependencies = new Set();
-        const init = unwrappedInitOf(declarator);
-        if (init && init.type === utils_1.AST_NODE_TYPES.Identifier) {
-            dependencies.add(init.name);
-        }
-        const nameSet = new Set([name]);
+        declarators.forEach((declarator) => {
+            const init = unwrappedInitOf(declarator);
+            if (init && init.type === utils_1.AST_NODE_TYPES.Identifier) {
+                dependencies.add(init.name);
+            }
+        });
+        const nameSet = new Set(declarators.map((declarator) => declarator.id.name));
         const usageIndex = findFirstUsageIndex(body, nameSet, index + 1);
         if (usageIndex === -1 || usageIndex <= index + 1) {
             return;
@@ -1140,7 +1195,9 @@ function handleLateDeclarations(sink, body) {
             // Do not hop over another declaration that is used at the same index or earlier
             // if it is also a candidate for being moved.
             // This prevents circular swapping of related declarations (like resolve/reject pairs).
-            if (lateDeclarationCandidateOf(stmt)) {
+            // The test asks about *relocation*, so a declaration the fix will never move
+            // is not one of the two ends of such a swap and does not block the hop.
+            if (isRelocatableLateDeclaration(stmt)) {
                 const declaredNames = getDeclaredNames(stmt);
                 const firstUsageOfIntervening = findFirstUsageIndex(body, declaredNames, index + 1 + i + 1);
                 if (firstUsageOfIntervening !== -1 &&
@@ -1163,7 +1220,11 @@ function handleLateDeclarations(sink, body) {
         if (crossesImpureOrTracked) {
             return;
         }
-        record(sink, statement, 'moveDeclarationCloser', { name }, index, usageIndex);
+        const subject = earliestUsedDeclarator(declarators, body, index + 1, usageIndex);
+        // The same test `isRelocatableLateDeclaration` applies to an intervening
+        // statement, read off the declarators already in hand.
+        const relocatable = declarators.length === 1;
+        record(sink, statement, 'moveDeclarationCloser', { name: subject.id.name }, index, usageIndex, relocatable);
     });
 }
 /**
@@ -1655,8 +1716,12 @@ function orderKey(order, indices) {
     return order.map((statement) => indices.get(statement)).join(',');
 }
 /**
- * Shortest sequence of moves reaching an order with **zero** violations, or null when
- * the search bounds contain no such order.
+ * Shortest sequence of moves reaching an order with **zero** relocatable violations,
+ * or null when the search bounds contain no such order.
+ *
+ * `violations` is pre-screened by `relocatableViolations`, and so is every detection
+ * the search performs: a violation whose statement the fix may not move is neither a
+ * candidate move nor a reason to reject an order, since no reordering can answer it.
  *
  * Breadth-first for two reasons: the emitted fix is then the smallest reordering that
  * satisfies every constraint, and a block whose single named move already suffices
@@ -1706,7 +1771,7 @@ function findResolvingMoves(sourceCode, body, violations, maxMoves) {
             }
             seen.add(key);
             budget -= 1;
-            const next = detectViolations(sourceCode, order);
+            const next = relocatableViolations(detectViolations(sourceCode, order));
             const moves = [...node.moves, { fromIndex, toIndex }];
             if (next.length === 0) {
                 return moves;
@@ -1765,10 +1830,15 @@ function buildReorderFix(body, moves, parent, sourceCode, fixer) {
     return fixer.replaceTextRange([bounds[first], bounds[last + 1]], reordered.slice(first, last + 1).join(''));
 }
 /**
- * A fix is emitted only for a reordering the detector scores at zero violations, and
- * the whole reordering ships as a single fix. Relocating one statement per report
- * satisfies its own adjacency constraint while breaking another's, which under
- * `--fix` oscillates or exhausts the pass budget (#1405).
+ * A fix is emitted only for a reordering the detector scores at zero relocatable
+ * violations, and the whole reordering ships as a single fix. Relocating one
+ * statement per report satisfies its own adjacency constraint while breaking
+ * another's, which under `--fix` oscillates or exhausts the pass budget (#1405).
+ *
+ * A violation no reordering may answer — a declaration whose sibling bindings the
+ * fix would drag along — is reported and otherwise invisible here: it does not
+ * carry the fix, does not veto one, and cannot keep the block from settling, since
+ * the fixed text scores it exactly as the input did.
  *
  * Convergence is structural rather than argued: the emitted order is verified clean
  * by the same detector that produced the reports, and detection depends only on
@@ -1786,13 +1856,14 @@ function handleBlock(ruleContext, node) {
     if (violations.length === 0) {
         return;
     }
-    const moves = findResolvingMoves(sourceCode, body, violations, searchDepthFor(violations.length, body.length));
-    violations.forEach((violation, index) => {
+    const relocatable = relocatableViolations(violations);
+    const moves = findResolvingMoves(sourceCode, body, relocatable, searchDepthFor(relocatable.length, body.length));
+    violations.forEach((violation) => {
         context.report({
             node: violation.statement,
             messageId: violation.messageId,
             data: violation.data,
-            fix: moves && index === 0
+            fix: moves && violation === relocatable[0]
                 ? (fixer) => buildReorderFix(body, moves, node, sourceCode, fixer)
                 : null,
         });

package/lib/rules/no-unused-props.js

@@ -84,14 +84,14 @@ exports.noUnusedProps = (0, createRule_1.createRule)({
         const spreadTypeToPropNames = new Map();
         const processingTypeAliases = new Set();
         const componentsToCheck = [];
-        let currentComponent = null;
+        let currentComponents = null;
         const clearState = () => {
             propsTypes.clear();
             componentToReferencedSpreadTypeNames.clear();
             spreadTypeToPropNames.clear();
             processingTypeAliases.clear();
             componentsToCheck.length = 0;
-            currentComponent = null;
+            currentComponents = null;
         };
         const isGenericTypeSpread = (prop) => prop.startsWith('...') && prop.length === 4 && /^\.\.\.[A-Z]$/.test(prop);
         const hasRestSpreadUsage = (used, restUsed) => {
@@ -412,6 +412,63 @@ exports.noUnusedProps = (0, createRule_1.createRule)({
                 }
             });
         };
+        /**
+         * The props usage of a single declarator, or `null` when the declarator is
+         * not a props-typed arrow component. Each declarator answers on its own:
+         * this rule reports a member of a props type and rewrites nothing, so a
+         * sibling binding in the same statement has no bearing on the verdict
+         * (#1890).
+         */
+        const componentUsageOfDeclarator = (declaration) => {
+            if (declaration.init?.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
+                return null;
+            }
+            const fn = declaration.init;
+            const param = fn.params[0];
+            if (param?.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
+                // Resolve through generic wrappers (e.g. `Readonly<FooProps>`) as well
+                // as the plain `FooProps` annotation; an unannotated pattern under an
+                // FC-annotated declarator resolves from the annotation's argument.
+                const typeName = resolvePropsTypeName(param.typeAnnotation?.typeAnnotation ??
+                    propsArgumentOfFcAnnotation(declaration.id));
+                if (!typeName) {
+                    return null;
+                }
+                const used = new Set();
+                const restUsed = collectUsedFromObjectPattern(param, typeName, used);
+                return { typeName, used, restUsed };
+            }
+            if (param?.type === utils_1.AST_NODE_TYPES.Identifier) {
+                // Identifier param (`props: FooProps`): the destructuring happens in
+                // the body. Resolve the Props type (unwrapping generic wrappers) and
+                // scan the body for `const { ... } = props`.
+                const typeName = resolvePropsTypeName(param.typeAnnotation?.typeAnnotation ??
+                    propsArgumentOfFcAnnotation(declaration.id));
+                if (!typeName) {
+                    return null;
+                }
+                const used = new Set();
+                const { destructureCount, restUsed, hasOpaqueUsage } = collectBodyDestructuring(fn.body, param.name, typeName, used);
+                // Only check when the body destructures the param at least once.
+                // Member access (`props.x`), spread (`{...props}`), passing `props`
+                // whole, or never referencing it (e.g. `_props`) is left to prior
+                // behavior (no report) — those usages can't be enumerated reliably.
+                if (destructureCount === 0) {
+                    return null;
+                }
+                // Mixed usage (some destructure + opaque consumption) forwards the
+                // remaining props, so treat every prop as used to avoid false reports.
+                if (hasOpaqueUsage) {
+                    const propsType = propsTypes.get(typeName);
+                    if (propsType) {
+                        Object.keys(propsType).forEach((key) => used.add(key));
+                    }
+                    return { typeName, used, restUsed: true };
+                }
+                return { typeName, used, restUsed };
+            }
+            return null;
+        };
         return {
             TSTypeAliasDeclaration(node) {
                 if (!node.id.name.endsWith('Props')) {
@@ -796,64 +853,19 @@ exports.noUnusedProps = (0, createRule_1.createRule)({
                 }
             },
             VariableDeclaration(node) {
-                if (node.declarations.length !== 1) {
-                    return;
-                }
-                const declaration = node.declarations[0];
-                if (declaration.init?.type !== utils_1.AST_NODE_TYPES.ArrowFunctionExpression) {
-                    return;
-                }
-                const fn = declaration.init;
-                const param = fn.params[0];
-                if (param?.type === utils_1.AST_NODE_TYPES.ObjectPattern) {
-                    // Resolve through generic wrappers (e.g. `Readonly<FooProps>`) as well
-                    // as the plain `FooProps` annotation; an unannotated pattern under an
-                    // FC-annotated declarator resolves from the annotation's argument.
-                    const typeName = resolvePropsTypeName(param.typeAnnotation?.typeAnnotation ??
-                        propsArgumentOfFcAnnotation(declaration.id));
-                    if (typeName) {
-                        const used = new Set();
-                        const restUsed = collectUsedFromObjectPattern(param, typeName, used);
-                        currentComponent = { node, typeName, used, restUsed };
-                    }
-                    return;
-                }
-                if (param?.type === utils_1.AST_NODE_TYPES.Identifier) {
-                    // Identifier param (`props: FooProps`): the destructuring happens in
-                    // the body. Resolve the Props type (unwrapping generic wrappers) and
-                    // scan the body for `const { ... } = props`.
-                    const typeName = resolvePropsTypeName(param.typeAnnotation?.typeAnnotation ??
-                        propsArgumentOfFcAnnotation(declaration.id));
-                    if (!typeName) {
-                        return;
-                    }
-                    const used = new Set();
-                    const { destructureCount, restUsed, hasOpaqueUsage } = collectBodyDestructuring(fn.body, param.name, typeName, used);
-                    // Only check when the body destructures the param at least once.
-                    // Member access (`props.x`), spread (`{...props}`), passing `props`
-                    // whole, or never referencing it (e.g. `_props`) is left to prior
-                    // behavior (no report) — those usages can't be enumerated reliably.
-                    if (destructureCount === 0) {
-                        return;
-                    }
-                    // Mixed usage (some destructure + opaque consumption) forwards the
-                    // remaining props, so treat every prop as used to avoid false reports.
-                    if (hasOpaqueUsage) {
-                        const propsType = propsTypes.get(typeName);
-                        if (propsType) {
-                            Object.keys(propsType).forEach((key) => used.add(key));
-                        }
-                        currentComponent = { node, typeName, used, restUsed: true };
-                        return;
-                    }
-                    currentComponent = { node, typeName, used, restUsed };
+                const components = node.declarations
+                    .map((declaration) => componentUsageOfDeclarator(declaration))
+                    .filter((component) => component !== null);
+                // A declaration holding no component leaves any pending one untouched,
+                // so an inner non-component declaration cannot drop its enclosing one.
+                if (components.length > 0) {
+                    currentComponents = { node, components };
                 }
             },
             'VariableDeclaration:exit'(node) {
-                if (currentComponent?.node === node) {
-                    const { typeName, used, restUsed } = currentComponent;
-                    componentsToCheck.push({ typeName, used, restUsed });
-                    currentComponent = null;
+                if (currentComponents?.node === node) {
+                    componentsToCheck.push(...currentComponents.components);
+                    currentComponents = null;
                 }
             },
             JSXElement() {

package/lib/rules/vertically-group-related-functions.js

@@ -95,16 +95,32 @@ function isFunctionExpressionLike(node) {
             node.type === 'FunctionExpression' ||
             node.type === 'FunctionDeclaration'));
 }
+// Find the function a declaration contributes to the ordering inventory.
+//
+// A sibling declarator is a FIX-safety question, not a detection one: bailing
+// out of the extractor drops the statement from the inventory entirely, so the
+// ordering violation goes unreported instead of merely unfixed (#1891).
+//
+// At most ONE binding per statement is surfaced — the first function-like
+// declarator — because every downstream structure is keyed on statement
+// identity: the expected-order slots, the comment-inclusive statement ranges,
+// and the fixer's per-statement edits. A second entry sharing a statement would
+// emit two edits over one range and duplicate that statement's text. A later
+// function-like sibling therefore stays invisible, which under-constrains the
+// order rather than misstating it, and no ordering instruction is ever emitted
+// for two functions that cannot move independently of each other.
 function extractFunctionFromVariableDeclaration(statement) {
-    if (statement.declarations.length !== 1) {
-        return null;
-    }
-    const declarator = statement.declarations[0];
-    if (declarator.id.type !== 'Identifier' ||
-        !isFunctionExpressionLike(declarator.init)) {
-        return null;
+    for (const declarator of statement.declarations) {
+        if (declarator.id.type === 'Identifier' &&
+            isFunctionExpressionLike(declarator.init)) {
+            return {
+                name: declarator.id.name,
+                fnNode: declarator.init,
+                hasSiblingDeclarators: statement.declarations.length > 1,
+            };
+        }
     }
-    return { name: declarator.id.name, fnNode: declarator.init };
+    return null;
 }
 function collectFunctions(programBody, eventHandlerRegex, utilityRegex) {
     const functions = [];
@@ -124,6 +140,7 @@ function collectFunctions(programBody, eventHandlerRegex, utilityRegex) {
                 isUtility: utilityRegex.test(name),
                 dependencies: [],
                 originalIndex: index,
+                hasSiblingDeclarators: false,
             });
             return;
         }
@@ -142,13 +159,14 @@ function collectFunctions(programBody, eventHandlerRegex, utilityRegex) {
                     isUtility: utilityRegex.test(name),
                     dependencies: [],
                     originalIndex: index,
+                    hasSiblingDeclarators: false,
                 });
                 return;
             }
             if (statement.declaration.type === 'VariableDeclaration') {
                 const extracted = extractFunctionFromVariableDeclaration(statement.declaration);
                 if (extracted) {
-                    const { name, fnNode } = extracted;
+                    const { name, fnNode, hasSiblingDeclarators } = extracted;
                     functions.push({
                         name,
                         fnNode,
@@ -158,6 +176,7 @@ function collectFunctions(programBody, eventHandlerRegex, utilityRegex) {
                         isUtility: utilityRegex.test(name),
                         dependencies: [],
                         originalIndex: index,
+                        hasSiblingDeclarators,
                     });
                 }
             }
@@ -177,13 +196,14 @@ function collectFunctions(programBody, eventHandlerRegex, utilityRegex) {
                 isUtility: utilityRegex.test(name),
                 dependencies: [],
                 originalIndex: index,
+                hasSiblingDeclarators: false,
             });
             return;
         }
         if (statement.type === 'VariableDeclaration') {
             const extracted = extractFunctionFromVariableDeclaration(statement);
             if (extracted) {
-                const { name, fnNode } = extracted;
+                const { name, fnNode, hasSiblingDeclarators } = extracted;
                 const isExported = ASTHelpers_1.ASTHelpers.isNodeExported(statement);
                 functions.push({
                     name,
@@ -194,6 +214,7 @@ function collectFunctions(programBody, eventHandlerRegex, utilityRegex) {
                     isUtility: utilityRegex.test(name),
                     dependencies: [],
                     originalIndex: index,
+                    hasSiblingDeclarators,
                 });
             }
         }
@@ -686,6 +707,16 @@ exports.verticallyGroupRelatedFunctions = (0, createRule_1.createRule)({
                             firstFunctionIndex > lastFunctionIndex) {
                             return null;
                         }
+                        // Both reorder paths rewrite whole statements, so moving a function
+                        // that shares its declaration with other bindings would carry those
+                        // siblings with it — or, split apart, would leave the sibling's
+                        // initializer evaluating somewhere it was never written to. Neither
+                        // is a rewrite this rule is entitled to make on the reader's behalf.
+                        // The misorderedFunction report still fires; only the rewrite of the
+                        // region containing such a declaration is withheld.
+                        if (functions.some((fn) => fn.hasSiblingDeclarators)) {
+                            return null;
+                        }
                         const slice = node.body.slice(firstFunctionIndex, lastFunctionIndex + 1);
                         const blockContainsOnlyFunctions = slice.every((statement) => functionStatements.has(statement));
                         // Decline a reorder that would hoist a function above an interleaved

package/package.json

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

package/release-manifest.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "1.20.137",
+    "date": "2026-08-08T22:49:24.968Z",
+    "rules": [
+      {
+        "name": "logical-top-to-bottom-grouping",
+        "changeType": "fix",
+        "issues": [
+          1889
+        ],
+        "summary": "report a late declaration that carries a sibling binding (closes #1889)"
+      },
+      {
+        "name": "no-unused-props",
+        "changeType": "fix",
+        "issues": [
+          1890
+        ],
+        "summary": "analyse every declarator, not just the first (closes #1890)"
+      },
+      {
+        "name": "vertically-group-related-functions",
+        "changeType": "fix",
+        "issues": [
+          1891
+        ],
+        "summary": "report a misordered function that carries a sibling binding (closes #1891)"
+      }
+    ]
+  },
   {
     "version": "1.20.136",
     "date": "2026-08-08T14:34:06.547Z",