@blumintinc/eslint-plugin-blumint 1.20.195 → 1.20.197

package/lib/index.js

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

package/lib/rules/no-entire-object-hook-deps.js

@@ -1310,6 +1310,46 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
             dependencyEntryIdentifiers = entries;
             return entries;
         }
+        /**
+         * Whether a parameter's binding comes out of a DESTRUCTURING pattern - a
+         * destructured prop rather than a positional parameter.
+         *
+         * why: this is the line `noUnusedParameters` draws, measured against the
+         * consumer's own compiler. It reports a destructured property wherever it
+         * sits, including a rest sibling and including an `_`-prefixed one; a
+         * positional parameter it reports only when the name does not start with
+         * `_`. Keying on the pattern rather than on the name is therefore the
+         * accurate test for the destructured case, and `_`-prefixing must NOT be
+         * read as an opt-out there - tsc ignores the name inside a pattern, so
+         * honouring it would readmit the strand on a binding that merely looks
+         * deliberate.
+         *
+         * The AssignmentPattern step is carried but not reachable from the report
+         * path: measured, the rule emits nothing at all for a DEFAULTED
+         * destructured prop (`({ label, revision = 0 })`), so the fixer never gets
+         * to judge one. It stays because dropping it would classify such a prop as
+         * positional the moment that reporting gap is closed, which is the strand
+         * this function exists to prevent - not because a fixture exercises it.
+         */
+        function isDestructuredParameter(name) {
+            if (name.type !== utils_1.AST_NODE_TYPES.Identifier)
+                return false;
+            let node = name.parent;
+            while (node) {
+                if (node.type === utils_1.AST_NODE_TYPES.ObjectPattern ||
+                    node.type === utils_1.AST_NODE_TYPES.ArrayPattern) {
+                    return true;
+                }
+                if (node.type === utils_1.AST_NODE_TYPES.Property ||
+                    node.type === utils_1.AST_NODE_TYPES.RestElement ||
+                    node.type === utils_1.AST_NODE_TYPES.AssignmentPattern) {
+                    node = node.parent;
+                    continue;
+                }
+                return false;
+            }
+            return false;
+        }
         /**
          * Whether removing `element`'s binding from every dependency array that
          * lists it would leave the binding with no reader in the file.
@@ -1336,11 +1376,35 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
          * inference is safe in the conservative direction — if a sibling report is
          * suppressed the cost is a withheld fix, never a dangling reference.
          *
-         * Parameters are deliberately exempt. An unread parameter is not an unused
-         * BINDING to either instrument — `no-unused-vars` runs with `args: 'none'`
-         * and `noUnusedLocals` does not cover parameters — so declining there would
-         * withhold a fix without preventing any breakage, and it would silently
-         * settle the reporting question #1621 defers.
+         * A DESTRUCTURED parameter is not exempt; a positional one still is.
+         *
+         * why: the instrument that covers a parameter is `noUnusedParameters`, not
+         * `noUnusedLocals`, and the consumer sets `noUnusedParameters: true` while
+         * setting `noUnusedLocals: false` — so a blanket parameter exemption reads
+         * the one flag the consumer has turned OFF and misses the one it has turned
+         * ON. It also cites `no-unused-vars` with `args: 'none'`, which is not the
+         * consumer's setting either. Stranding a destructured prop is therefore a
+         * red build there, from a `tsc --noEmit` gate, and `no-unused-props` cannot
+         * clean up after this fixer because that rule is report-only.
+         *
+         * Nearly every dependency entry in a React component is a destructured
+         * prop, so this is the common case rather than an edge: 21 composed
+         * findings over 13 distinct fixture shapes, every one of them a
+         * destructured prop this fixer stranded (#2236).
+         *
+         * The POSITIONAL parameter stays exempt, and deliberately so. tsc reports
+         * one too, so this IS a residue — but the composed sweep over 23,785
+         * fixtures reached zero of them on its own, and declining there would
+         * settle the reporting question #1621 defers on unmeasured ground while
+         * withholding fixes the corpus shows to be safe, including the #2208
+         * margin-comment arm whose subject is a positional parameter. The residue
+         * is carried deliberately and it is WITNESSED: the control fixture added
+         * with this fix is now the sweep's only surviving stranded parameter, so
+         * the cost of the exemption is visible in that guard's dump rather than
+         * asserted here and forgotten.
+         *
+         * The report stands either way. Only the rewrite is withheld, which is the
+         * conservative direction the rest of this function already takes.
          */
         function wouldStrandBinding(element) {
             const identifier = unwrapExpression(element);
@@ -1349,7 +1413,9 @@ exports.noEntireObjectHookDeps = (0, createRule_1.createRule)({
             const variable = resolveBinding(identifier);
             if (!variable || variable.defs.length === 0)
                 return false;
-            if (variable.defs.some((def) => def.type === 'Parameter')) {
+            const parameterDefs = variable.defs.filter((def) => def.type === 'Parameter');
+            if (parameterDefs.length === variable.defs.length &&
+                !parameterDefs.some((def) => isDestructuredParameter(def.name))) {
                 return false;
             }
             const entries = collectDependencyEntryIdentifiers();

package/lib/rules/no-unused-usestate.d.ts

@@ -5,4 +5,5 @@ import { TSESLint, TSESTree } from '@typescript-eslint/utils';
  */
 export declare const noUnusedUseState: TSESLint.RuleModule<"unusedUseState", never[], {
     VariableDeclarator(node: TSESTree.VariableDeclarator): void;
+    'Program:exit'(): void;
 }>;

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

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.noUnusedUseState = void 0;
 const utils_1 = require("@typescript-eslint/utils");
+const disableDirectives_1 = require("../utils/disableDirectives");
+const importRemoval_1 = require("../utils/importRemoval");
 const createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com/BluMintInc/eslint-custom-rules/blob/main/docs/rules/${name}.md`);
 /**
  * A destructuring binding counts as live when anything other than its own
@@ -11,6 +13,49 @@ const createRule = utils_1.ESLintUtils.RuleCreator((name) => `https://github.com
 const isBindingReferenced = (variable) => {
     return variable.references.some((reference) => !reference.init);
 };
+const isWithinAny = (range, ranges) => ranges.some(([start, end]) => range[0] >= start && range[1] <= end);
+const rangesOverlap = (left, right) => left[0] < right[1] && right[0] < left[1];
+/**
+ * The slice a fix deletes to retire `node`, separators included, or `null` when
+ * the declaration sits somewhere this rule does not rewrite.
+ *
+ * The sole declarator of a statement takes the statement with it, up to the next
+ * token or comment so the line it occupied does not survive as blank space. One
+ * declarator among several takes exactly one separator: the comma after it, plus
+ * the whitespace up to the next declarator so no double space is left behind —
+ * or the comma before it when it ends the list. A comment stops the removal so
+ * it survives the fix.
+ */
+const declarationRemovalRange = (sourceCode, node) => {
+    const parentStatement = node.parent;
+    if (!parentStatement ||
+        parentStatement.type !== utils_1.TSESTree.AST_NODE_TYPES.VariableDeclaration) {
+        return null;
+    }
+    if (parentStatement.declarations.length === 1) {
+        const nextToken = sourceCode.getTokenAfter(parentStatement, {
+            includeComments: true,
+        });
+        return nextToken
+            ? [parentStatement.range[0], nextToken.range[0]]
+            : [parentStatement.range[0], parentStatement.range[1]];
+    }
+    const tokenAfter = sourceCode.getTokenAfter(node);
+    if (tokenAfter && tokenAfter.value === ',') {
+        const tokenAfterComma = sourceCode.getTokenAfter(tokenAfter, {
+            includeComments: true,
+        });
+        return [
+            node.range[0],
+            tokenAfterComma ? tokenAfterComma.range[0] : tokenAfter.range[1],
+        ];
+    }
+    const tokenBefore = sourceCode.getTokenBefore(node);
+    if (tokenBefore && tokenBefore.value === ',') {
+        return [tokenBefore.range[0], node.range[1]];
+    }
+    return [node.range[0], node.range[1]];
+};
 /**
  * Rule to detect and remove unused useState hooks in React components
  * This rule identifies cases where the state variable from useState is ignored (e.g., replaced with _)
@@ -31,6 +76,66 @@ exports.noUnusedUseState = createRule({
     },
     defaultOptions: [],
     create(context) {
+        const sourceCode = context.sourceCode;
+        /**
+         * Every discarded pair the rule finds, in traversal order.
+         *
+         * Reporting waits for `Program:exit` because the `useState` import is left
+         * unreferenced only once NO surviving call mentions it. Judged one
+         * declaration at a time, a file with two dead pairs never sees either as the
+         * import's last use, and the pass that deletes both resolves every report —
+         * so nothing ever revisits the stranded import.
+         */
+        const violations = [];
+        /**
+         * A suppressed report is discarded together with its fix, so its removal
+         * never happens: counting it toward the batch would unbind an import the
+         * surviving text still calls.
+         */
+        const isReportSuppressed = (0, disableDirectives_1.createSuppressionChecker)(context);
+        /**
+         * The extra deletions that keep `removed` from stranding a binding.
+         *
+         * Deleting a `useState` declaration strands two kinds of binding. The
+         * import is unbound by dropping its specifier, which the shared helper
+         * plans. The pattern's own `_` and setter are unbound by the very deletion
+         * being planned — their declarations sit inside `removed`, so they need
+         * nothing further and the unbinder claims them with an empty plan. Anything
+         * else the deletion leaves unreferenced (a `const` read only by the
+         * discarded initializer) declines the whole fix: leaving the report standing
+         * costs less than trading it for an unused-variable error the fixer resolved
+         * out of view.
+         */
+        const planRemoval = (removed) => (0, importRemoval_1.planOrphanedBindingRemoval)(sourceCode, removed, (variables, ranges) => variables.every((variable) => variable.identifiers.every((identifier) => isWithinAny(identifier.range, ranges)))
+            ? []
+            : null);
+        /**
+         * The removals that ship, in traversal order.
+         *
+         * Each is screened alone before joining the batch: a deletion that strands
+         * something unbindable would otherwise withhold every other removal in the
+         * file. Overlapping deletions are dropped because ESLint rejects a fix whose
+         * own edits collide — two dead declarators of one statement overlap on the
+         * separator between them, and the later one is deleted on a following pass.
+         */
+        const planViolations = () => {
+            const planned = [];
+            const claimed = [];
+            for (const violation of violations) {
+                const { removal } = violation;
+                if (!removal)
+                    continue;
+                if (isReportSuppressed(violation.node))
+                    continue;
+                if (planRemoval([removal]) === null)
+                    continue;
+                if (claimed.some((taken) => rangesOverlap(removal, taken)))
+                    continue;
+                claimed.push(removal);
+                planned.push({ violation, removal });
+            }
+            return planned;
+        };
         return {
             // Look for variable declarations that destructure from useState
             VariableDeclarator(node) {
@@ -60,72 +165,56 @@ exports.noUnusedUseState = createRule({
                             // Every other binding of the pattern (the setter, and any nested
                             // or rest binding) must be dead before the declaration can be
                             // deleted. Removing it while the setter is still called strands
-                            // the call sites and breaks the component.
+                            // the call sites and breaks the component. A live setter therefore
+                            // yields a report without a fix.
                             const hasLiveSiblingBinding = declaredVariables.some((variable) => variable !== stateVariable && isBindingReferenced(variable));
-                            context.report({
+                            violations.push({
                                 node,
-                                messageId: 'unusedUseState',
-                                data: {
-                                    stateName: stateIdentifier.name,
-                                },
-                                fix: (fixer) => {
-                                    // A live setter still needs its declaration, so report the
-                                    // discarded value without offering a destructive fix.
-                                    if (hasLiveSiblingBinding) {
-                                        return null;
-                                    }
-                                    // Remove the entire useState declaration
-                                    const sourceCode = context.sourceCode;
-                                    const parentStatement = node.parent;
-                                    if (parentStatement &&
-                                        parentStatement.type ===
-                                            utils_1.TSESTree.AST_NODE_TYPES.VariableDeclaration) {
-                                        // If this is the only declarator, remove the entire statement and any extra whitespace
-                                        if (parentStatement.declarations.length === 1) {
-                                            // Get the next token after the statement to handle whitespace properly
-                                            const nextToken = sourceCode.getTokenAfter(parentStatement, { includeComments: true });
-                                            if (nextToken) {
-                                                // Remove the statement and any whitespace up to the next token
-                                                return fixer.removeRange([
-                                                    parentStatement.range[0],
-                                                    nextToken.range[0],
-                                                ]);
-                                            }
-                                            return fixer.remove(parentStatement);
-                                        }
-                                        // Otherwise, just remove this declarator and any trailing comma
-                                        const declaratorRange = node.range;
-                                        // Check if there's a comma after this declarator
-                                        const tokenAfter = sourceCode.getTokenAfter(node);
-                                        if (tokenAfter && tokenAfter.value === ',') {
-                                            // Consume the separator plus the whitespace before the
-                                            // surviving declarator so no double space is left behind.
-                                            // Comments stop the removal so they survive the fix.
-                                            const tokenAfterComma = sourceCode.getTokenAfter(tokenAfter, { includeComments: true });
-                                            return fixer.removeRange([
-                                                declaratorRange[0],
-                                                tokenAfterComma
-                                                    ? tokenAfterComma.range[0]
-                                                    : tokenAfter.range[1],
-                                            ]);
-                                        }
-                                        // Check if there's a comma before this declarator
-                                        const tokenBefore = sourceCode.getTokenBefore(node);
-                                        if (tokenBefore && tokenBefore.value === ',') {
-                                            return fixer.removeRange([
-                                                tokenBefore.range[0],
-                                                declaratorRange[1],
-                                            ]);
-                                        }
-                                        return fixer.remove(node);
-                                    }
-                                    return null;
-                                },
+                                stateName: stateIdentifier.name,
+                                removal: hasLiveSiblingBinding
+                                    ? null
+                                    : declarationRemovalRange(sourceCode, node),
                             });
                         }
                     }
                 }
             },
+            'Program:exit'() {
+                if (violations.length === 0)
+                    return;
+                const planned = planViolations();
+                // One plan over every surviving removal: the `useState` binding is left
+                // unreferenced by their union even when no single deletion strips its
+                // last call, and the pass that applies them all resolves every report —
+                // so this is the only moment the stranded import is visible.
+                const orphanRemoval = planned.length > 0
+                    ? planRemoval(planned.map((entry) => entry.removal))
+                    : null;
+                // The whole batch ships as one fix, so no deletion lands without the
+                // others the import's orphanhood was judged against, and no unbinding
+                // lands without the deletion it was claimed on. The other violations
+                // report without a fixer; the carrier's pass already resolves them.
+                //
+                // No plan at all means some binding would be left unreferenced yet
+                // cannot be unbound safely, so every deletion stays behind: reports
+                // without a fixer are the lesser damage.
+                const carrier = orphanRemoval ? planned[0] : undefined;
+                const removals = orphanRemoval
+                    ? [...orphanRemoval, ...planned.map((entry) => entry.removal)]
+                    : [];
+                for (const violation of violations) {
+                    context.report({
+                        node: violation.node,
+                        messageId: 'unusedUseState',
+                        data: {
+                            stateName: violation.stateName,
+                        },
+                        fix: violation === carrier?.violation
+                            ? (fixer) => removals.map((range) => fixer.removeRange([range[0], range[1]]))
+                            : undefined,
+                    });
+                }
+            },
         };
     },
 });