@blumintinc/eslint-plugin-blumint 1.20.194 → 1.20.196

package/lib/index.js

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

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,
+                    });
+                }
+            },
         };
     },
 });

package/lib/rules/no-useless-fragment.js

@@ -3,16 +3,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noUselessFragment = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const ASTHelpers_1 = require("../utils/ASTHelpers");
+const reactFragmentBinding_1 = require("../utils/reactFragmentBinding");
+const disableDirectives_1 = require("../utils/disableDirectives");
+const importRemoval_1 = require("../utils/importRemoval");
 /**
  * Normalizes JSX child node types into short descriptors used inside lint messages.
  * Keeps message phrasing consistent regardless of the specific child node shape.
+ * A long-form fragment child (`<Fragment>`, `<React.Fragment>`) is described as
+ * a fragment rather than a JSX element so the message reads the same whichever
+ * spelling the nested fragment uses.
  * @param child - The JSX child node to describe.
+ * @param isFragmentElement - Recognizes the long-form fragment spellings.
  * @returns Human-readable descriptor for the child type used in lint messages.
  */
-const describeChild = (child) => {
+const describeChild = (child, isFragmentElement) => {
     switch (child.type) {
         case 'JSXElement':
-            return 'JSX element';
+            return isFragmentElement(child) ? 'fragment' : 'JSX element';
         case 'JSXFragment':
             return 'fragment';
         case 'JSXText':
@@ -112,44 +120,244 @@ const reindentPromotedChild = (sourceCode, fragment, child) => {
     })
         .join('\n');
 };
+/** The opening and closing tag spans of either fragment spelling. */
+const tagRangesOf = (node) => {
+    if (node.type === 'JSXFragment') {
+        return [node.openingFragment.range, node.closingFragment.range];
+    }
+    return node.closingElement
+        ? [node.openingElement.range, node.closingElement.range]
+        : [node.openingElement.range];
+};
+const contains = (outer, inner) => outer[0] <= inner[0] && inner[1] <= outer[1];
+/**
+ * Partitions violations into the sets whose unwraps have to travel together.
+ *
+ * A `Fragment` import read by two useless `<Fragment>` elements is orphaned only
+ * once BOTH are unwrapped, so neither unwrap may drop the import alone — and a
+ * fix may only count on the other unwrap happening if it performs that unwrap
+ * itself. Fragments that jointly hold a binding alive therefore become one
+ * batch; every other fragment is a batch of one, judged against the file as it
+ * stands. Shorthand `<>` names nothing, so it is never unioned with anything and
+ * keeps fixing independently.
+ *
+ * EVERY binding is asked about, not the imported ones alone, so that a binding
+ * no fix asks about cannot end up owned by none of them.
+ */
+function batchViolations(source, violations) {
+    const parents = violations.map((_violation, index) => index);
+    const find = (index) => {
+        let current = index;
+        while (parents[current] !== current) {
+            parents[current] = parents[parents[current]];
+            current = parents[current];
+        }
+        return current;
+    };
+    const union = (left, right) => {
+        const rootLeft = find(left);
+        const rootRight = find(right);
+        if (rootLeft !== rootRight) {
+            parents[rootRight] = rootLeft;
+        }
+    };
+    const ownerOf = (use) => violations.findIndex(({ tags }) => tags.some((tag) => use[0] >= tag[0] && use[1] <= tag[1]));
+    for (const { uses } of (0, importRemoval_1.bindingUses)(source)) {
+        if (uses.length < 2)
+            continue;
+        const owners = new Set();
+        const escapes = uses.some((use) => {
+            const owner = ownerOf(use);
+            if (owner === -1)
+                return true;
+            owners.add(owner);
+            return false;
+        });
+        // A use outside every unwrap keeps the binding alive whatever these fixes
+        // do, so their fixes owe each other nothing.
+        if (escapes || owners.size < 2)
+            continue;
+        const [first, ...rest] = [...owners];
+        for (const other of rest) {
+            union(first, other);
+        }
+    }
+    const groups = new Map();
+    violations.forEach((violation, index) => {
+        const root = find(index);
+        const group = groups.get(root);
+        if (group) {
+            group.push(violation);
+        }
+        else {
+            groups.set(root, [violation]);
+        }
+    });
+    return [...groups.values()];
+}
+/**
+ * The unwraps `batch` performs plus the import specifiers they leave bound to
+ * nothing. `null` when an orphan cannot be unbound safely — an import behind a
+ * directive comment, say — in which case the caller keeps the report and drops
+ * the fix, because unwrapping while leaving the import behind turns a clean file
+ * into one that fails `no-unused-vars`.
+ */
+function planBatch(source, batch) {
+    const unwraps = batch.map((violation) => ({
+        node: violation.node,
+        // Only fixable violations reach a plan, so the replacement is present.
+        text: violation.replacement,
+    }));
+    const cleanups = (0, importRemoval_1.planOrphanedImportRemoval)(source, batch.flatMap((violation) => violation.tags));
+    return cleanups ? { unwraps, cleanups } : null;
+}
 exports.noUselessFragment = (0, createRule_1.createRule)({
     name: 'no-useless-fragment',
     create(context) {
+        const sourceCode = context.sourceCode;
+        /**
+         * Long-form fragments are recognized through the element's own scope, so a
+         * `Fragment` shadowed by a local component is not mistaken for react's.
+         */
+        const isFragmentElement = (element) => (0, reactFragmentBinding_1.isReactFragmentElement)(element, (node) => ASTHelpers_1.ASTHelpers.getScope(context, node));
+        /**
+         * Fragments held until `Program:exit`. Whether an unwrap strands the import
+         * that names the fragment is a whole-file question, and the answer can only
+         * be given once every fragment reading that import is known.
+         */
+        const violations = [];
+        /**
+         * Whether ESLint will discard a report, resolved the way ESLint resolves it.
+         * A batched fix counts on every unwrap in its batch happening; a suppressed
+         * report never fixes, so its fragment — and the reference its tags hold —
+         * outlives the pass and must not be counted on.
+         */
+        const isSuppressed = (0, disableDirectives_1.createSuppressionChecker)(context);
+        /**
+         * The single decision every fragment spelling shares. `<>`, `<Fragment>`
+         * and `<React.Fragment>` denote the same node, so they are reported and
+         * unwrapped identically; splitting the logic per spelling is what let the
+         * long forms go unexamined in the first place.
+         */
+        const collectWhenUseless = (node) => {
+            const meaningfulChildren = node.children.filter((child) => !isFormattingWhitespace(child));
+            if (meaningfulChildren.length !== 1) {
+                return;
+            }
+            const [child] = meaningfulChildren;
+            /**
+             * A fragment whose only child is an expression container — e.g.
+             * `<>{portal}</>` — is NOT useless. Unwrapping it to a bare
+             * `{portal}` is invalid in statement/return position, and wrapping a
+             * single ReactNode expression in a fragment is the idiomatic way to
+             * render it. (Mirrors the upstream rule's `allowExpressions`.)
+             */
+            if (child.type === 'JSXExpressionContainer') {
+                return;
+            }
+            /**
+             * Unwrapping is only sound when the child is itself standalone JSX.
+             * A text child (`<>hello</>`) would become a bare identifier
+             * reference, and a spread child (`<>{...items}</>`) is not a valid
+             * expression on its own — both are report-only so the developer
+             * chooses how to restructure the surrounding code.
+             */
+            const isFixable = child.type === 'JSXElement' || child.type === 'JSXFragment';
+            violations.push({
+                node,
+                childKind: describeChild(child, isFragmentElement),
+                replacement: isFixable
+                    ? reindentPromotedChild(sourceCode, node, child)
+                    : null,
+                tags: tagRangesOf(node),
+            });
+        };
         return {
             JSXFragment(node) {
-                const meaningfulChildren = node.children.filter((child) => !isFormattingWhitespace(child));
-                if (meaningfulChildren.length !== 1) {
+                collectWhenUseless(node);
+            },
+            JSXElement(node) {
+                if (!isFragmentElement(node)) {
                     return;
                 }
-                const [child] = meaningfulChildren;
                 /**
-                 * A fragment whose only child is an expression container — e.g.
-                 * `<>{portal}</>` — is NOT useless. Unwrapping it to a bare
-                 * `{portal}` is invalid in statement/return position, and wrapping a
-                 * single ReactNode expression in a fragment is the idiomatic way to
-                 * render it. (Mirrors the upstream rule's `allowExpressions`.)
+                 * An attribute is content the shorthand cannot carry: `key` positions
+                 * the fragment in a sibling list, and unwrapping would move it onto
+                 * the promoted child, changing reconciliation. Only the long forms can
+                 * reach this branch, since `<>` admits no attributes at all.
                  */
-                if (child.type === 'JSXExpressionContainer') {
+                if (node.openingElement.attributes.length > 0) {
                     return;
                 }
+                collectWhenUseless(node);
+            },
+            /**
+             * Emits every held report, each carrying the import cleanup its own
+             * unwrap makes necessary.
+             *
+             * Orphanhood is judged against a single fix's own deletions, never
+             * against what sibling reports might also delete: ESLint may discard a
+             * sibling, and the fragment it was going to unwrap then keeps the import
+             * alive.
+             */
+            'Program:exit'() {
+                if (violations.length === 0)
+                    return;
                 /**
-                 * Unwrapping is only sound when the child is itself standalone JSX.
-                 * A text child (`<>hello</>`) would become a bare identifier
-                 * reference, and a spread child (`<>{...items}</>`) is not a valid
-                 * expression on its own — both are report-only so the developer
-                 * chooses how to restructure the surrounding code.
+                 * A fragment nested inside another fragment being unwrapped is left out
+                 * of the batching. Its tags are carried into the outer fragment's
+                 * replacement text verbatim, so its reference SURVIVES that fix — and
+                 * the two replacements would overlap besides. The outer unwrap then
+                 * finds the import still in use and leaves it, and the next `--fix`
+                 * pass unwraps what is by then a lone fragment and takes the import
+                 * with it.
                  */
-                const isFixable = child.type === 'JSXElement' || child.type === 'JSXFragment';
-                context.report({
-                    node,
-                    messageId: 'noUselessFragment',
-                    data: {
-                        childKind: describeChild(child),
-                    },
-                    fix: isFixable
-                        ? (fixer) => fixer.replaceText(node, reindentPromotedChild(context.sourceCode, node, child))
-                        : null,
-                });
+                const unwrapping = violations.filter((violation) => violation.replacement !== null && !isSuppressed(violation.node));
+                const batchable = unwrapping.filter((violation) => !unwrapping.some((other) => other !== violation &&
+                    contains(other.node.range, violation.node.range)));
+                const batchableSet = new Set(batchable);
+                const plans = new Map();
+                for (const batch of batchViolations(sourceCode, batchable)) {
+                    const plan = planBatch(sourceCode, batch);
+                    if (!plan)
+                        continue;
+                    for (const violation of batch) {
+                        plans.set(violation, plan);
+                    }
+                }
+                for (const violation of violations) {
+                    /**
+                     * A fixable fragment the batching left out fixes on its own. It is
+                     * nested inside another fragment being unwrapped — so its tags are
+                     * carried into that fragment's replacement rather than deleted, and
+                     * strand nothing — or it is suppressed, in which case ESLint discards
+                     * the report and the fix never runs. A fragment that WAS batched and
+                     * whose batch declined gets no fix at all, which is the whole point of
+                     * the decline.
+                     */
+                    const own = violation.replacement !== null && !batchableSet.has(violation)
+                        ? {
+                            unwraps: [
+                                { node: violation.node, text: violation.replacement },
+                            ],
+                            cleanups: [],
+                        }
+                        : null;
+                    const applied = plans.get(violation) ?? own;
+                    context.report({
+                        node: violation.node,
+                        messageId: 'noUselessFragment',
+                        data: { childKind: violation.childKind },
+                        ...(applied
+                            ? {
+                                fix: (fixer) => [
+                                    ...applied.unwraps.map((unwrap) => fixer.replaceText(unwrap.node, unwrap.text)),
+                                    ...applied.cleanups.map((range) => fixer.removeRange([range[0], range[1]])),
+                                ],
+                            }
+                            : {}),
+                    });
+                }
             },
         };
     },