@blumintinc/eslint-plugin-blumint 1.20.136 → 1.20.138

package/lib/rules/prefer-params-over-parent-id.js

@@ -7,6 +7,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.preferParamsOverParentId = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const disableDirectives_1 = require("../utils/disableDirectives");
+const importRemoval_1 = require("../utils/importRemoval");
+const patternBindingRemoval_1 = require("../utils/patternBindingRemoval");
+function rangesOverlap(a, b) {
+    return a[0] < b[1] && b[0] < a[1];
+}
 const HANDLER_TYPES = new Set([
     'DocumentChangeHandler',
     'DocumentChangeHandlerTransaction',
@@ -220,6 +226,57 @@ exports.preferParamsOverParentId = (0, createRule_1.createRule)({
     defaultOptions: [],
     create(context) {
         const handlerNodes = new Set();
+        const sourceCode = context.sourceCode;
+        /**
+         * Every `ref.parent...id` read the rule reports, in traversal order.
+         *
+         * Reporting waits for `Program:exit` because the binding the read walks from
+         * — `change` in `const { data: change, params } = event` — is left
+         * unreferenced only once NO surviving read mentions it. Judged one read at a
+         * time, a handler with two of them never sees either as the binding's last
+         * use, and the pass that rewrites both resolves every report, so nothing
+         * revisits the stranded binding.
+         */
+        const violations = [];
+        /**
+         * A suppressed report is discarded together with its fix, so its rewrite
+         * never happens: counting it toward the batch would retire a property the
+         * surviving text still reads.
+         */
+        const isReportSuppressed = (0, disableDirectives_1.createSuppressionChecker)(context);
+        /**
+         * The bindings a rewrite strands are destructuring properties rather than
+         * imports, so the import machinery is handed the pattern planner to unbind
+         * them with.
+         */
+        const planRemoval = (removed) => (0, importRemoval_1.planOrphanedBindingRemoval)(sourceCode, removed, (variables, ranges) => (0, patternBindingRemoval_1.planPatternBindingRemoval)(sourceCode, variables, ranges));
+        /**
+         * The rewrites that ship, in traversal order.
+         *
+         * Each is screened alone before joining the batch: a rewrite whose own
+         * deletion strands something that cannot be unbound safely would otherwise
+         * withhold every other rewrite in the file. Overlapping edits are dropped
+         * because ESLint discards every message for a file whose fixes collide.
+         */
+        function planViolations() {
+            const planned = [];
+            const claimed = [];
+            for (const violation of violations) {
+                const { replacement } = violation;
+                if (!replacement)
+                    continue;
+                if (isReportSuppressed(violation.node))
+                    continue;
+                if (planRemoval([violation.node.range]) === null)
+                    continue;
+                if (claimed.some((taken) => rangesOverlap(violation.node.range, taken))) {
+                    continue;
+                }
+                claimed.push(violation.node.range);
+                planned.push({ violation, replacement });
+            }
+            return planned;
+        }
         return {
             // Track Firebase change handler functions
             'FunctionDeclaration, FunctionExpression, ArrowFunctionExpression'(node) {
@@ -230,45 +287,71 @@ exports.preferParamsOverParentId = (0, createRule_1.createRule)({
             // Detect .ref.parent.id patterns
             MemberExpression(node) {
                 const parentAccess = isParentIdAccess(node);
-                if (parentAccess.isMatch) {
-                    const handlerNode = findHandlerFunction(node, handlerNodes);
-                    if (handlerNode) {
-                        const hasOptional = hasOptionalChaining(node);
-                        const paramsInScope = getParamsInScope(handlerNode);
-                        if (!paramsInScope) {
-                            context.report({
-                                node,
-                                messageId: 'preferParams',
-                                data: {
-                                    paramName: getParentParamName(parentAccess.depth),
-                                },
-                            });
-                            return;
-                        }
-                        const paramSuggestion = getParentParamName(parentAccess.depth);
-                        let replacement = null;
-                        if (paramsInScope.identifier) {
-                            replacement = hasOptional
-                                ? `${paramsInScope.identifier}?.${paramSuggestion}`
-                                : `${paramsInScope.identifier}.${paramSuggestion}`;
-                        }
-                        else if (paramsInScope.properties) {
-                            const localName = paramsInScope.properties.get(paramSuggestion);
-                            if (localName) {
-                                replacement = localName;
-                            }
-                        }
-                        context.report({
-                            node,
-                            messageId: 'preferParams',
-                            data: {
-                                paramName: paramSuggestion,
-                            },
-                            fix: replacement
-                                ? (fixer) => fixer.replaceText(node, replacement)
-                                : undefined,
-                        });
-                    }
+                if (!parentAccess.isMatch) {
+                    return;
+                }
+                const handlerNode = findHandlerFunction(node, handlerNodes);
+                if (!handlerNode) {
+                    return;
+                }
+                const paramName = getParentParamName(parentAccess.depth);
+                const paramsInScope = getParamsInScope(handlerNode);
+                if (!paramsInScope) {
+                    violations.push({ node, paramName, replacement: null });
+                    return;
+                }
+                const hasOptional = hasOptionalChaining(node);
+                let replacement = null;
+                if (paramsInScope.identifier) {
+                    replacement = hasOptional
+                        ? `${paramsInScope.identifier}?.${paramName}`
+                        : `${paramsInScope.identifier}.${paramName}`;
+                }
+                else if (paramsInScope.properties) {
+                    replacement = paramsInScope.properties.get(paramName) ?? null;
+                }
+                violations.push({ node, paramName, replacement });
+            },
+            'Program:exit'() {
+                if (violations.length === 0) {
+                    return;
+                }
+                const planned = planViolations();
+                // One plan over every surviving rewrite: a binding read by two of them
+                // is unreferenced only under their union, and the pass that applies
+                // them all resolves every report — so this is the only moment the
+                // stranded binding is visible.
+                const removal = planned.length > 0
+                    ? planRemoval(planned.map((entry) => entry.violation.node.range))
+                    : null;
+                // ESLint throws out every message for a file whose fix ranges overlap,
+                // so a plan that collides with the rewrites it was computed for is
+                // withheld rather than allowed to take the pass down with it.
+                const collides = removal?.some((range) => planned.some((entry) => rangesOverlap(entry.violation.node.range, [range[0], range[1]])));
+                const removalRanges = removal && !collides ? removal : null;
+                // The whole batch ships as one fix, so no rewrite lands without the
+                // others its binding's orphanhood was judged against, and no unbinding
+                // lands without the rewrites it was claimed on. The remaining
+                // violations report without a fixer; the carrier's pass resolves them.
+                //
+                // No plan at all means some binding would be left unreferenced yet
+                // cannot be unbound safely, so every rewrite stays behind: an unfixed
+                // report is the lesser damage.
+                const carrier = removalRanges ? planned[0] : undefined;
+                for (const violation of violations) {
+                    context.report({
+                        node: violation.node,
+                        messageId: 'preferParams',
+                        data: {
+                            paramName: violation.paramName,
+                        },
+                        fix: violation === carrier?.violation
+                            ? (fixer) => [
+                                ...(removalRanges ?? []).map((range) => fixer.removeRange([range[0], range[1]])),
+                                ...planned.map((entry) => fixer.replaceText(entry.violation.node, entry.replacement)),
+                            ]
+                            : undefined,
+                    });
                 }
             },
         };

package/lib/rules/use-latest-callback.js

@@ -4,6 +4,7 @@ exports.useLatestCallback = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const importRemoval_1 = require("../utils/importRemoval");
 /**
  * Matches Prettier's own default. Dropping the dependency array lets the call
  * collapse onto one line, so the fixer decides a line break a formatter owns: a
@@ -774,17 +775,40 @@ exports.useLatestCallback = (0, createRule_1.createRule)({
                         : openBrace.range[0];
                     return [fixer.removeRange([start, closeBrace.range[1]])];
                 };
-                const importFixes = (fixer) => {
+                /**
+                 * The hook's own import, placed at the react import it displaces.
+                 *
+                 * The anchor is nudged to the start of any planned deletion that
+                 * encloses it, because a fix's edits must not overlap: an unbinding
+                 * that swallows the react declaration's whole line starts before the
+                 * declaration whenever that line is indented, and inserting inside
+                 * that span is the one position ESLint rejects outright.
+                 */
+                const insertImportFixes = (fixer, unbindings) => {
+                    if (latestCallbackImport) {
+                        return [];
+                    }
+                    let at = statement.range[0];
+                    for (const [start, end] of unbindings) {
+                        if (start < at && at < end) {
+                            at = start;
+                        }
+                    }
+                    return [fixer.insertTextBeforeRange([at, at], `${importText}\n`)];
+                };
+                const importFixes = (fixer, unbindsReactSpecifiers, unbindings) => {
                     if (!touchesImport) {
                         return [];
                     }
+                    // The orphan plan already unbinds every react specifier the rewrite
+                    // strips, so the only edit left here is the hook's own import.
+                    if (!unbindsReactSpecifiers) {
+                        return insertImportFixes(fixer, unbindings);
+                    }
                     // A surviving reference (or a member-only file) leaves the react
                     // import untouched; only the new import is added when missing.
                     if (hasSurvivingReference || specifiers.length === 0) {
-                        if (latestCallbackImport) {
-                            return [];
-                        }
-                        return [fixer.insertTextBefore(statement, `${importText}\n`)];
+                        return insertImportFixes(fixer, unbindings);
                     }
                     const defaultOrNamespace = statement.specifiers.find((s) => s.type === utils_1.AST_NODE_TYPES.ImportDefaultSpecifier ||
                         s.type === utils_1.AST_NODE_TYPES.ImportNamespaceSpecifier);
@@ -801,10 +825,9 @@ exports.useLatestCallback = (0, createRule_1.createRule)({
                         }
                         return [fixer.remove(statement)];
                     }
-                    const fixes = [];
-                    if (!latestCallbackImport) {
-                        fixes.push(fixer.insertTextBefore(statement, `${importText}\n`));
-                    }
+                    const fixes = [
+                        ...insertImportFixes(fixer, unbindings),
+                    ];
                     if (remainingNamed.length === 0) {
                         fixes.push(...removeNamedGroup(fixer, namedSpecifiers));
                     }
@@ -862,6 +885,55 @@ exports.useLatestCallback = (0, createRule_1.createRule)({
                     conversion.node.range[1],
                 ]);
                 const programScope = ASTHelpers_1.ASTHelpers.getScope(context, program);
+                /**
+                 * The spans the batched rewrite genuinely erases.
+                 *
+                 * Only two parts of a converted call disappear: its callee, which the
+                 * hook's name replaces, and everything past the callback argument — the
+                 * dependency array and any further argument. The callback text and the
+                 * call's type parameters are re-emitted verbatim, so listing them would
+                 * read every binding they mention as unreferenced and unbind imports the
+                 * rewritten call still uses.
+                 *
+                 * `includeIdentifierCallees` selects which oracle owns the react
+                 * `useCallback` specifier. Excluded, the specifier's binding has no
+                 * reference among these spans, so the orphan planner never considers it
+                 * and {@link importFixes} keeps its comment-preserving splice.
+                 */
+                const erasedSpans = (includeIdentifierCallees) => batchedConversions.flatMap((conversion) => {
+                    const { node } = conversion;
+                    const spans = [
+                        [node.arguments[0].range[1], node.range[1]],
+                    ];
+                    // A member callee's object is the only binding it reads, and the
+                    // rule's own import rewrite never touches it.
+                    if (includeIdentifierCallees || !conversion.callee) {
+                        spans.push(node.callee.range);
+                    }
+                    return spans;
+                });
+                /**
+                 * Whether the edits form the single ordered, non-overlapping sequence
+                 * ESLint demands of one fix.
+                 *
+                 * The two import oracles below own disjoint declarations in every shape
+                 * this rule is written for, but "every shape" is a claim about a file
+                 * nobody has seen. A file that breaks it — a dependency array reading
+                 * the same react declaration the specifier splice rewrites — would make
+                 * ESLint throw out of the whole lint rather than report, so the edit set
+                 * is checked and withheld instead.
+                 */
+                const editsAreDisjoint = (fixes) => {
+                    const ordered = [...fixes].sort((left, right) => left.range[0] - right.range[0] || left.range[1] - right.range[1]);
+                    let previousEnd = -1;
+                    for (const fix of ordered) {
+                        if (fix.range[0] < previousEnd) {
+                            return false;
+                        }
+                        previousEnd = fix.range[1];
+                    }
+                    return true;
+                };
                 // Every call-site conversion and the import rewrite ride on ONE fix
                 // from ONE report. ESLint discards a multi-part fix wholesale when any
                 // part conflicts with another rule's fix and retries it on the next
@@ -894,11 +966,37 @@ exports.useLatestCallback = (0, createRule_1.createRule)({
                         if (orphansLocalBinding(programScope, droppedRanges)) {
                             return null;
                         }
+                        // Converting every `React.useCallback` call strips the last read of
+                        // the react default import, and dropping a dependency array strips
+                        // the last read of whatever was computed for it. Either leaves the
+                        // file failing `no-unused-vars` and `noUnusedLocals` on a fix that
+                        // resolved the only report that would have re-raised the debt
+                        // (issue #1898).
+                        //
+                        // Two plans, because the react `useCallback` specifier has two
+                        // possible owners and only one of them may edit it. The wider plan
+                        // decides everything, which is what unbinds a mixed
+                        // `import React, { useCallback }` as a single declaration; when it
+                        // declines — a comment among the specifiers, a name the planner's
+                        // second-opinion scan still finds — the narrower plan hands that
+                        // specifier back to the splice above, which preserves the comments
+                        // the planner refuses to guess at (issue #1446).
+                        //
+                        // A null from BOTH is a demand to withhold: a binding is left
+                        // unreferenced that neither oracle can unbind safely.
+                        const wholePlan = (0, importRemoval_1.planOrphanedImportRemoval)(sourceCode, erasedSpans(true));
+                        const unbindings = wholePlan ??
+                            (0, importRemoval_1.planOrphanedImportRemoval)(sourceCode, erasedSpans(false));
+                        if (!unbindings) {
+                            return null;
+                        }
                         const texts = conversionTexts();
-                        return [
+                        const fixes = [
                             ...batchedConversions.map((conversion) => fixer.replaceText(conversion.node, texts.get(conversion.node))),
-                            ...importFixes(fixer),
+                            ...importFixes(fixer, wholePlan === null, unbindings),
+                            ...unbindings.map((range) => fixer.removeRange([range[0], range[1]])),
                         ];
+                        return editsAreDisjoint(fixes) ? fixes : null;
                     },
                 });
                 for (const conversion of [...followers, ...deferredConversions]) {

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/lib/utils/importRemoval.d.ts

@@ -9,6 +9,27 @@ export type ImportBindingSpecifier = TSESTree.ImportSpecifier | TSESTree.ImportD
  * run.
  */
 export type ImportRemovalSource = Pick<TSESLint.SourceCode, 'text' | 'ast' | 'scopeManager' | 'getTokenBefore' | 'getTokenAfter' | 'getCommentsBefore' | 'getCommentsInside'>;
+/**
+ * The slice to delete for a statement that loses its last binding. The whole
+ * line goes when the statement owns it, trailing same-line comments included:
+ * those describe the declaration that is going away, and a
+ * `// eslint-disable-line` among them would otherwise outlive its subject. A
+ * statement sharing its line with other code gives up only its own characters.
+ */
+export declare function statementRemovalRange(source: ImportRemovalSource, declaration: TSESTree.Node): TextRange | null;
+export type Removable = {
+    range: TextRange;
+    removed: boolean;
+};
+/**
+ * Ranges covering every removed item together with the separators that would
+ * be left dangling. A removed run reaches forward to the next survivor, or
+ * backward from the previous one when it ends the list, so exactly one
+ * separator per removed item disappears. Returns `null` when every item is
+ * removed — that collapse is the caller's to make, since what encloses the
+ * list (braces, the declaration itself) must go too.
+ */
+export declare function removalRuns(items: readonly Removable[]): TextRange[] | null;
 /**
  * The text ranges that unbind `specifiers` from their shared declaration, or
  * `null` when no removal is provably safe. All specifiers of the declaration
@@ -50,6 +71,58 @@ export type ImportBindingUse = {
  * fix may claim that.
  */
 export declare function importBindingReferences(source: ImportRemovalSource): ImportBindingUse[];
+/**
+ * True when the name still occurs in the source outside `ranges` and outside
+ * `binding` — the span or spans that declare it — ignoring the positions where a
+ * name is a module's export name rather than a reference to a local binding.
+ *
+ * Scope analysis already answers "is this binding referenced", and it is what
+ * `no-unused-vars` answers with. This coarser second opinion exists to catch
+ * the cases where the two could disagree — a shadowing binding, a construct the
+ * scope manager does not link — because a removal that turns out to be wrong
+ * deletes working code, while a removal declined in error only leaves the
+ * original report standing.
+ */
+export declare function nameOccursOutside(source: ImportRemovalSource, name: string, ranges: readonly TextRange[], binding: readonly TextRange[]): boolean;
+/** Every binding identifier a destructuring pattern introduces. */
+export declare function patternIdentifiers(pattern: TSESTree.Node | null): TSESTree.Identifier[];
+/**
+ * Every binding that `removed` would leave with nothing referencing it.
+ *
+ * The scan answers only "which bindings does this deletion strand"; what to do
+ * about each is the caller's, since an import is unbound by deleting a specifier
+ * while a destructured property is unbound by deleting a property — and some
+ * bindings must not be touched at all.
+ */
+export declare function orphanedBindings(source: ImportRemovalSource, removed: readonly TextRange[]): TSESLint.Scope.Variable[];
+/** A binding together with the ranges that USE it. */
+export type BindingUse = {
+    variable: TSESLint.Scope.Variable;
+    uses: TextRange[];
+};
+/**
+ * Every binding the file declares, paired with the positions that USE it — the
+ * same set {@link orphanedBindings} judges orphanhood by, a declarator's own
+ * initializer write excluded.
+ *
+ * {@link importBindingReferences} answers the narrower question for import
+ * bindings alone, which suffices only for a caller whose deletions can strand
+ * nothing else. A caller that can also strand a local declaration — a `type`
+ * alias named by the annotations it deletes, a `const` read through `typeof` —
+ * has to partition its edits over every binding, because a binding it never
+ * asks about ends up owned by no fix at all and stays orphaned for good.
+ */
+export declare function bindingUses(source: ImportRemovalSource): BindingUse[];
+/**
+ * How a caller unbinds the orphans this module does not own — a destructured
+ * property, a local declaration, a binding it deliberately leaves alone.
+ *
+ * Every such orphan arrives in ONE call because two of them can share a list
+ * whose separators are only correct when planned together. The result is the
+ * ranges that unbind them, `[]` for orphans the caller accepts as they are, or
+ * `null` to decline — which withholds the caller's whole fix.
+ */
+export type OrphanUnbinder = (variables: readonly TSESLint.Scope.Variable[], removed: readonly TextRange[]) => TextRange[] | null;
 /**
  * The extra ranges a fix must delete so that removing `removed` leaves nothing
  * bound to nothing, or `null` when some binding would be orphaned yet cannot be
@@ -78,3 +151,18 @@ export declare function importBindingReferences(source: ImportRemovalSource): Im
  * to work out which edits belong in the same batch.
  */
 export declare function planOrphanedImportRemoval(source: ImportRemovalSource, removed: readonly TextRange[]): TextRange[] | null;
+/**
+ * {@link planOrphanedImportRemoval} widened by an `unbind` strategy for the
+ * orphans imports do not cover. Without one, an orphan bound by anything other
+ * than an import declines the fix, which is exactly what the import-only entry
+ * point promises.
+ *
+ * Every contract of {@link planOrphanedImportRemoval} carries over unchanged —
+ * `removed` is one fix's own deletion, `null` is a demand — with one addition
+ * the import arm never needed. An import declaration binds names without reading
+ * any, so unbinding one cannot strand a second binding; a declaration `unbind`
+ * deletes usually DOES read something (`const { data } = event` reads `event`),
+ * so its plan is re-examined against the file and declined if it strands
+ * anything the first pass did not already account for.
+ */
+export declare function planOrphanedBindingRemoval(source: ImportRemovalSource, removed: readonly TextRange[], unbind?: OrphanUnbinder): TextRange[] | null;