@blumintinc/eslint-plugin-blumint 1.20.86 → 1.20.87

package/lib/rules/no-explicit-return-type.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.noExplicitReturnType = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
+const importRemoval_1 = require("../utils/importRemoval");
 const defaultOptions = {
     allowRecursiveFunctions: true,
     allowOverloadedFunctions: true,
@@ -725,16 +726,45 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
             return (Boolean(mergedOptions.allowVoidReturnTypes) &&
                 declaresVoidResult(returnType));
         }
-        function fixReturnType(fixer, node) {
-            // Some nodes expose returnType directly while others nest it under value.
-            const returnType = 'returnType' in node
-                ? node.returnType
-                : 'value' in node
-                    ? node.value.returnType
-                    : null;
-            if (!returnType)
-                return null;
-            return fixer.remove(returnType);
+        /**
+         * Reports an annotation, taking with it any import it was the only
+         * consumer of. The two are one fix: applying either half alone leaves the
+         * file worse than applying neither.
+         *
+         * Orphanhood is judged against this annotation's own removal and the file
+         * as it stands, never against what the rest of the `--fix` run might also
+         * delete. A sibling annotation naming the same type may be
+         * `eslint-disable`d — which a rule cannot see, since suppression is
+         * applied to reports after they are emitted — so an edit that assumes its
+         * sibling will also go deletes an import the surviving annotation still
+         * references, trading an unused import for a dangling type. Judging one
+         * edit at a time is suppression-safe by construction: a suppressed
+         * report's fix never applies, so it can never have been depended on.
+         *
+         * The cost is that a type shared by several strippable annotations is not
+         * unbound in a single pass; each pass removes the annotations it can see,
+         * and only a pass that leaves the binding with no reference at all
+         * removes the import.
+         */
+        function reportAnnotation(node, returnType, strippable) {
+            const importRanges = strippable
+                ? (0, importRemoval_1.planOrphanedImportRemoval)(sourceCode, [returnType.range])
+                : null;
+            context.report({
+                node: returnType,
+                messageId: strippable
+                    ? 'noExplicitReturnTypeInferable'
+                    : 'noExplicitReturnTypeNonInferable',
+                data: { functionKind: describeFunctionKind(node) },
+                ...(importRanges
+                    ? {
+                        fix: (fixer) => [
+                            fixer.remove(returnType),
+                            ...importRanges.map((range) => fixer.removeRange([range[0], range[1]])),
+                        ],
+                    }
+                    : {}),
+            });
         }
         return {
             FunctionDeclaration(node) {
@@ -749,17 +779,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
-                const isInferable = Boolean(node.body);
-                context.report({
-                    node: returnType,
-                    messageId: isInferable
-                        ? 'noExplicitReturnTypeInferable'
-                        : 'noExplicitReturnTypeNonInferable',
-                    data: { functionKind: describeFunctionKind(node) },
-                    ...(isInferable
-                        ? { fix: (fixer) => fixReturnType(fixer, node) }
-                        : {}),
-                });
+                reportAnnotation(node, returnType, Boolean(node.body));
             },
             FunctionExpression(node) {
                 const returnType = node.returnType;
@@ -776,12 +796,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
-                context.report({
-                    node: returnType,
-                    messageId: 'noExplicitReturnTypeInferable',
-                    data: { functionKind: describeFunctionKind(node) },
-                    fix: (fixer) => fixReturnType(fixer, node),
-                });
+                reportAnnotation(node, returnType, true);
             },
             ArrowFunctionExpression(node) {
                 const returnType = node.returnType;
@@ -793,12 +808,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
-                context.report({
-                    node: returnType,
-                    messageId: 'noExplicitReturnTypeInferable',
-                    data: { functionKind: describeFunctionKind(node) },
-                    fix: (fixer) => fixReturnType(fixer, node),
-                });
+                reportAnnotation(node, returnType, true);
             },
             TSMethodSignature(node) {
                 const returnType = node.returnType;
@@ -811,11 +821,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isOverloadedFunction(node)) {
                     return;
                 }
-                context.report({
-                    node: returnType,
-                    messageId: 'noExplicitReturnTypeNonInferable',
-                    data: { functionKind: describeFunctionKind(node) },
-                });
+                reportAnnotation(node, returnType, false);
             },
             MethodDefinition(node) {
                 const returnType = node.value.returnType;
@@ -829,17 +835,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isReturnTypeRequiredByRecursion(node)) {
                     return;
                 }
-                const isInferable = Boolean(node.value.body);
-                context.report({
-                    node: returnType,
-                    messageId: isInferable
-                        ? 'noExplicitReturnTypeInferable'
-                        : 'noExplicitReturnTypeNonInferable',
-                    data: { functionKind: describeFunctionKind(node) },
-                    ...(isInferable
-                        ? { fix: (fixer) => fixReturnType(fixer, node) }
-                        : {}),
-                });
+                reportAnnotation(node, returnType, Boolean(node.value.body));
             },
             TSAbstractMethodDefinition(node) {
                 const returnType = node.value.returnType;
@@ -852,11 +848,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                 }
                 // Abstract methods never have bodies; they are always non-inferable and
                 // intentionally have no fixer.
-                context.report({
-                    node: returnType,
-                    messageId: 'noExplicitReturnTypeNonInferable',
-                    data: { functionKind: describeFunctionKind(node) },
-                });
+                reportAnnotation(node, returnType, false);
             },
             TSDeclareFunction(node) {
                 const returnType = node.returnType;
@@ -869,11 +861,7 @@ exports.noExplicitReturnType = (0, createRule_1.createRule)({
                     isOverloadedTsDeclareFunction(node)) {
                     return;
                 }
-                context.report({
-                    node: returnType,
-                    messageId: 'noExplicitReturnTypeNonInferable',
-                    data: { functionKind: describeFunctionKind(node) },
-                });
+                reportAnnotation(node, returnType, false);
             },
         };
     },

package/lib/rules/prefer-fragment-component.js

@@ -5,6 +5,7 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const disableDirectives_1 = require("../utils/disableDirectives");
+const importInsertion_1 = require("../utils/importInsertion");
 const REACT_MODULE = 'react';
 const FRAGMENT_NAME = 'Fragment';
 /**
@@ -151,29 +152,6 @@ exports.preferFragmentComponent = (0, createRule_1.createRule)({
             }
             return null;
         }
-        /**
-         * Where a brand-new import statement can be spliced in without changing
-         * what the file's directives govern. A whole-line insertion directly before
-         * the first statement slides in between an `eslint-disable-next-line`
-         * comment and the line it applies to, silently retargeting that directive
-         * at the import. Anchoring above such comments keeps every directive
-         * pointed at the code its author aimed it at.
-         */
-        function findImportAnchor() {
-            const firstStatement = sourceCode.ast.body[0];
-            let anchor = firstStatement;
-            const leadingComments = sourceCode.getCommentsBefore(firstStatement);
-            for (let index = leadingComments.length - 1; index >= 0; index--) {
-                const comment = leadingComments[index];
-                const [directive] = (0, disableDirectives_1.parseDisableDirectives)([comment]);
-                if (directive?.kind !== 'disable-next-line' ||
-                    comment.loc.end.line + 1 !== anchor.loc.start.line) {
-                    break;
-                }
-                anchor = comment;
-            }
-            return anchor;
-        }
         /**
          * Adds Fragment to an existing react import or creates a new one. The
          * emitted shape is a value named specifier, since the rewritten element
@@ -205,10 +183,14 @@ exports.preferFragmentComponent = (0, createRule_1.createRule)({
                     return fixer.insertTextAfter(lastSpecifier, `, { ${FRAGMENT_NAME} }`);
                 }
             }
-            // No React import found, create a new one
-            const importText = `import { ${FRAGMENT_NAME} } from '${REACT_MODULE}';\n`;
-            const indentation = sourceCode.text.match(/^[ \t]*/m)?.[0] || '';
-            return fixer.insertTextBefore(findImportAnchor(), indentation + importText);
+            // No react declaration can host the specifier, so the fix emits its own
+            // declaration. The shared anchor keeps the file's prologue intact: a
+            // `'use client'` directive stays the first statement, a `#!` shebang
+            // stays at character 0, a header comment stays above the code it covers,
+            // and an `eslint-disable-next-line` keeps pointing at the line its author
+            // aimed it at instead of at the inserted import.
+            const anchor = (0, importInsertion_1.importInsertionAnchor)(sourceCode);
+            return (0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, anchor, `import { ${FRAGMENT_NAME} } from '${REACT_MODULE}';\n`);
         }
         return {
             // Find JSX Fragment shorthand (<></>)

package/lib/rules/prefer-global-router-state-key.js

@@ -8,6 +8,7 @@ const path_1 = __importDefault(require("path"));
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const importInsertion_1 = require("../utils/importInsertion");
 // The module's path below the project root doubles as the bare specifier,
 // which is precisely why the root tsconfig `paths` and the Jest mapper resolve
 // it.
@@ -321,23 +322,6 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
         function findImportKey(importMap, predicate) {
             return Array.from(importMap.entries()).find(([, value]) => predicate(value))?.[0];
         }
-        /**
-         * Helper to find the last directive prologue in a statement list
-         */
-        function findLastDirective(body) {
-            let lastDirective;
-            for (const stmt of body) {
-                if (stmt.type === utils_1.AST_NODE_TYPES.ExpressionStatement &&
-                    stmt.expression.type === utils_1.AST_NODE_TYPES.Literal &&
-                    typeof stmt.expression.value === 'string' &&
-                    typeof stmt.directive === 'string') {
-                    lastDirective = stmt;
-                    continue;
-                }
-                break;
-            }
-            return lastDirective;
-        }
         return {
             // Track imports from queryKeys.ts
             ImportDeclaration(node) {
@@ -514,13 +498,23 @@ exports.preferGlobalRouterStateKey = (0, createRule_1.createRule)({
                                                                     fixes.push(fixer.insertTextBefore(firstImport, importText));
                                                                 }
                                                                 else {
-                                                                    const lastDirective = findLastDirective(sourceCode.ast.body);
-                                                                    if (lastDirective) {
-                                                                        fixes.push(fixer.insertTextAfter(lastDirective, `\n${importText}`));
-                                                                    }
-                                                                    else {
-                                                                        fixes.push(fixer.insertTextBeforeRange([0, 0], importText));
-                                                                    }
+                                                                    // A file's first import may cross only the
+                                                                    // whitespace the source opens with. The
+                                                                    // shared anchor is the floor of that climb:
+                                                                    // it clears the directive prologue, but
+                                                                    // also a `#!` shebang or a leading header
+                                                                    // comment, which text spliced at character
+                                                                    // 0 would displace.
+                                                                    const anchor = (0, importInsertion_1.importInsertionAnchor)(sourceCode);
+                                                                    const anchorIndex = anchor.kind === 'before'
+                                                                        ? anchor.target.range[0]
+                                                                        : anchor.index;
+                                                                    const opensFile = sourceCode.text
+                                                                        .slice(0, anchorIndex)
+                                                                        .trim() === '';
+                                                                    fixes.push((0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, opensFile
+                                                                        ? { kind: 'index', index: 0 }
+                                                                        : anchor, importText));
                                                                 }
                                                             }
                                                             scheduledQueryKeyNamedImports.add(suggestedConstant);

package/lib/rules/prefer-use-deep-compare-memo.js

@@ -4,6 +4,7 @@ exports.preferUseDeepCompareMemo = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const importInsertion_1 = require("../utils/importInsertion");
 const DEEP_COMPARE_MODULE = '@blumintinc/use-deep-compare';
 const DEEP_COMPARE_HOOK = 'useDeepCompareMemo';
 // Consider these as memoizing hooks producing stable references
@@ -199,28 +200,23 @@ function bindsHookImport(variable, hookImport) {
         variable.defs.every((def) => def.node === hookImport));
 }
 function ensureDeepCompareImportFixes(context, fixer) {
-    const fixes = [];
     const sourceCode = context.sourceCode;
     const program = sourceCode.ast;
     // If already imported anywhere, skip adding
     if (findDeepCompareMemoImport(program))
-        return fixes;
-    // Determine insertion point and indentation
-    const importDecls = program.body.filter((n) => n.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
-    const fullText = sourceCode.getText();
-    let importText = `import { useDeepCompareMemo } from '@blumintinc/use-deep-compare';\n`;
-    if (importDecls.length === 0) {
-        fixes.push(fixer.insertTextBeforeRange([0, 0], importText));
-    }
-    else {
-        const firstImport = importDecls[0];
-        const before = fullText.slice(0, firstImport.range[0]);
-        const lastNewline = before.lastIndexOf('\n');
-        const indent = lastNewline >= 0 ? before.slice(lastNewline + 1) : '';
-        importText = `${indent}${importText}`;
-        fixes.push(fixer.insertTextBefore(firstImport, importText));
-    }
-    return fixes;
+        return [];
+    // The shared anchor keeps the insertion below whatever opens the file: text
+    // spliced above a `#!` shebang stops the file parsing, and text above a
+    // `'use client'` directive or a header comment strips the prologue of the
+    // meaning it only carries while it leads.
+    const anchor = (0, importInsertion_1.importInsertionAnchor)(sourceCode);
+    const indent = (0, importInsertion_1.importAnchorIndent)(sourceCode, anchor);
+    const importText = `${indent}import { ${DEEP_COMPARE_HOOK} } from '${DEEP_COMPARE_MODULE}';\n`;
+    // Widened to the anchor's line start because the emitted statement carries
+    // its own indentation, leaving the displaced anchor sitting on the original.
+    return [
+        (0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, (0, importInsertion_1.importAnchorLineStart)(sourceCode, anchor), importText),
+    ];
 }
 function findVariableInScope(scope, name) {
     if (!scope)

package/lib/rules/react-memoize-literals.js

@@ -4,6 +4,7 @@ exports.reactMemoizeLiterals = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
+const importInsertion_1 = require("../utils/importInsertion");
 const LITERAL_DESCRIPTOR_BY_TYPE = {
     [utils_1.AST_NODE_TYPES.ObjectExpression]: {
         literalType: 'object literal',
@@ -672,7 +673,8 @@ function bindsReactHook(variable, hookName) {
  * already imports it. Extending an existing declaration is preferred over a new
  * one so a file keeps a single `react` specifier list.
  */
-function buildHookImportFix(fixer, program, hookName) {
+function buildHookImportFix(fixer, sourceCode, hookName) {
+    const program = sourceCode.ast;
     if (importsHook(program, hookName)) {
         return null;
     }
@@ -694,12 +696,11 @@ function buildHookImportFix(fixer, program, hookName) {
     if (defaultSpecifier) {
         return fixer.insertTextAfter(defaultSpecifier, `, { ${hookName} }`);
     }
+    // The shared anchor keeps the declaration below whatever prologue the file
+    // opens with: a `'use client'` directive stops being a directive, and a `#!`
+    // shebang stops parsing, once a statement is spliced above it.
     const statement = `import { ${hookName} } from '${REACT_MODULE}';\n`;
-    const firstImport = program.body.find((node) => node.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
-    const anchor = firstImport ?? program.body[0];
-    return anchor
-        ? fixer.insertTextBefore(anchor, statement)
-        : fixer.insertTextAfterRange([0, 0], statement);
+    return (0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, (0, importInsertion_1.importInsertionAnchor)(sourceCode), statement);
 }
 /**
  * Scope kinds whose bindings are established once per module evaluation:
@@ -834,7 +835,7 @@ function buildMemoSuggestions(node, descriptor, sourceCode, context) {
                 // two disjoint ranges can be applied independently, stranding the
                 // wrapper without its binding.
                 const fixes = [];
-                const importFix = buildHookImportFix(fixer, sourceCode.ast, descriptor.memoHook);
+                const importFix = buildHookImportFix(fixer, sourceCode, descriptor.memoHook);
                 if (importFix) {
                     fixes.push(importFix);
                 }

package/lib/rules/require-memo.js

@@ -6,6 +6,7 @@ exports.requireMemo = void 0;
 const utils_1 = require("@typescript-eslint/utils");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const createRule_1 = require("../utils/createRule");
+const importInsertion_1 = require("../utils/importInsertion");
 const isComponentExplicitlyUnmemoized = (componentName) => componentName.toLowerCase().includes('unmemoized');
 // React's universal convention: only PascalCase-initial identifiers are
 // treated as components. camelCase names are render-prop callbacks or plain
@@ -190,15 +191,17 @@ function checkFunction(context, node) {
                                 // Calculate relative path based on current file location
                                 const currentFilePath = context.getFilename();
                                 const importPath = calculateImportPath(currentFilePath);
-                                // Find the first import statement to insert after
-                                const firstImport = program.body.find((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
-                                // Add new import statement for memo
                                 const importStatement = `import { memo } from '${importPath}';`;
+                                const firstImport = program.body.find((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
+                                // An existing import hosts the helper import directly after
+                                // it, keeping the module's imports contiguous. With none to
+                                // follow, the shared anchor keeps the file's prologue in
+                                // place: a `'use client'` directive only counts as one while
+                                // it is the first statement, and a `#!` shebang only parses
+                                // at character 0.
                                 importFix = firstImport
-                                    ? // Insert after the first import with a single newline
-                                        fixer.insertTextAfter(firstImport, '\n' + importStatement)
-                                    : // Insert at the start of the file
-                                        fixer.insertTextBeforeRange([program.range[0], program.range[0]], importStatement + '\n');
+                                    ? fixer.insertTextAfter(firstImport, `\n${importStatement}`)
+                                    : (0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, (0, importInsertion_1.importInsertionAnchor)(sourceCode), `${importStatement}\n`);
                             }
                         }
                         const functionKeywordRange = [

package/lib/rules/require-memoize-jsx-returners.js

@@ -5,6 +5,7 @@ const utils_1 = require("@typescript-eslint/utils");
 const createRule_1 = require("../utils/createRule");
 const ASTHelpers_1 = require("../utils/ASTHelpers");
 const disableDirectives_1 = require("../utils/disableDirectives");
+const importInsertion_1 = require("../utils/importInsertion");
 const MEMOIZE_PREFERRED_MODULE = '@blumintinc/typescript-memoize';
 const MEMOIZE_MODULES = new Set([
     MEMOIZE_PREFERRED_MODULE,
@@ -407,19 +408,13 @@ function getImportFixes(fixer, sourceCode, hasMemoizeImport, scheduledImportFix)
             return { fixes, scheduledImportFix: true };
         }
     }
-    const firstImport = programBody.find((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration);
-    const anchorNode = (firstImport ?? programBody[0]);
-    if (anchorNode) {
-        const text = sourceCode.text;
-        const anchorStart = anchorNode.range?.[0] ?? 0;
-        const lineStart = text.lastIndexOf('\n', anchorStart - 1) + 1;
-        const leadingWhitespace = text.slice(lineStart, anchorStart).match(/^[ \t]*/)?.[0] ?? '';
-        const importLine = `${leadingWhitespace}import { Memoize } from '${MEMOIZE_PREFERRED_MODULE}';\n`;
-        fixes.push(fixer.insertTextBeforeRange([lineStart, lineStart], importLine));
-    }
-    else {
-        fixes.push(fixer.insertTextBeforeRange([0, 0], `import { Memoize } from '${MEMOIZE_PREFERRED_MODULE}';\n`));
-    }
+    // The anchor sits past the file's prologue, so a `'use client'` directive
+    // keeps its position as the first statement and a `#!` shebang keeps
+    // character 0. Emitting the anchor's own indentation after the import leaves
+    // the displaced statement indented exactly as it was.
+    const anchor = (0, importInsertion_1.importInsertionAnchor)(sourceCode);
+    const indent = (0, importInsertion_1.importAnchorIndent)(sourceCode, anchor);
+    fixes.push((0, importInsertion_1.insertAtImportAnchor)(sourceCode, fixer, anchor, `import { Memoize } from '${MEMOIZE_PREFERRED_MODULE}';\n${indent}`));
     return { fixes, scheduledImportFix: true };
 }
 exports.requireMemoizeJsxReturners = (0, createRule_1.createRule)({

package/lib/utils/importInsertion.d.ts

@@ -0,0 +1,52 @@
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
+/**
+ * Where a brand-new top-of-file import belongs. `before` anchors at a node (or
+ * a comment bound to the node below it); `index` is a raw character offset for
+ * files with nothing to anchor to — a shebang-only, directive-only, or empty
+ * file.
+ */
+export type ImportInsertionAnchor = {
+    kind: 'before';
+    target: TSESTree.Node | TSESTree.Comment;
+} | {
+    kind: 'index';
+    index: number;
+};
+/**
+ * The source a rule needs to place an import. Narrower than
+ * `TSESLint.SourceCode` so tests can drive the helper without a full linter
+ * run.
+ */
+export type ImportInsertionSource = Pick<TSESLint.SourceCode, 'text' | 'ast' | 'getCommentsBefore'>;
+/**
+ * Resolves the position where a fixer may insert a new import declaration
+ * without changing what the file's prologue governs. A `'use client'` /
+ * `'use server'` directive must stay the first statement or it stops being a
+ * directive; a `#!` shebang must stay at character 0 or the file stops
+ * parsing; a leading `// @ts-nocheck` (or any header comment) keeps its
+ * meaning only above the code it covers. The anchor therefore lands on the
+ * first import if one exists, else on the first non-directive statement —
+ * both positions sit past the prologue because comments are excluded from a
+ * node's range — and only degenerate files (no statements at all) fall back
+ * to a computed offset.
+ */
+export declare function importInsertionAnchor(sourceCode: ImportInsertionSource): ImportInsertionAnchor;
+/**
+ * Applies `text` at `anchor`. Callers keep full control of the inserted
+ * statement and its separators; the only adjustment made here is a leading
+ * newline when a raw-offset anchor sits mid-line (after a directive's `;` or
+ * at the unterminated end of a shebang), where splicing text verbatim would
+ * fuse the import onto the prologue's line.
+ */
+export declare function insertAtImportAnchor(sourceCode: ImportInsertionSource, fixer: TSESLint.RuleFixer, anchor: ImportInsertionAnchor, text: string): TSESLint.RuleFix;
+/**
+ * Widens `anchor` to the start of its line, for rules that emit
+ * `${indent}import …\n` so the displaced anchor keeps its own indentation.
+ * Raw-offset anchors pass through: they never sit inside an indented line.
+ */
+export declare function importAnchorLineStart(sourceCode: ImportInsertionSource, anchor: ImportInsertionAnchor): ImportInsertionAnchor;
+/**
+ * The whitespace prefix of the anchor's line, for fixers that replicate the
+ * anchor's indentation on the inserted import.
+ */
+export declare function importAnchorIndent(sourceCode: ImportInsertionSource, anchor: ImportInsertionAnchor): string;

package/lib/utils/importInsertion.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importAnchorIndent = exports.importAnchorLineStart = exports.insertAtImportAnchor = exports.importInsertionAnchor = void 0;
+const utils_1 = require("@typescript-eslint/utils");
+const disableDirectives_1 = require("./disableDirectives");
+/**
+ * A comment that governs the line directly below it. Splicing an import
+ * between such a comment and its subject silently retargets the suppression
+ * at the import, so the anchor must climb above the whole run.
+ */
+function bindsNextLine(comment) {
+    const [directive] = (0, disableDirectives_1.parseDisableDirectives)([comment]);
+    if (directive?.kind === 'disable-next-line') {
+        return true;
+    }
+    const value = comment.value.trim();
+    return value.startsWith('@ts-expect-error') || value.startsWith('@ts-ignore');
+}
+/**
+ * Walks upward from `anchor` over line-binding suppression comments that sit
+ * on consecutive lines, so the eventual insertion lands above them rather
+ * than between a suppression and the line it covers.
+ */
+function climbBoundComments(sourceCode, anchor) {
+    let target = anchor;
+    const comments = sourceCode.getCommentsBefore(anchor);
+    for (let index = comments.length - 1; index >= 0; index--) {
+        const comment = comments[index];
+        if (!bindsNextLine(comment) ||
+            comment.loc.end.line + 1 !== target.loc.start.line) {
+            break;
+        }
+        target = comment;
+    }
+    return target;
+}
+function isDirective(statement) {
+    return (statement.type === utils_1.AST_NODE_TYPES.ExpressionStatement &&
+        typeof statement.directive === 'string');
+}
+/**
+ * Resolves the position where a fixer may insert a new import declaration
+ * without changing what the file's prologue governs. A `'use client'` /
+ * `'use server'` directive must stay the first statement or it stops being a
+ * directive; a `#!` shebang must stay at character 0 or the file stops
+ * parsing; a leading `// @ts-nocheck` (or any header comment) keeps its
+ * meaning only above the code it covers. The anchor therefore lands on the
+ * first import if one exists, else on the first non-directive statement —
+ * both positions sit past the prologue because comments are excluded from a
+ * node's range — and only degenerate files (no statements at all) fall back
+ * to a computed offset.
+ */
+function importInsertionAnchor(sourceCode) {
+    const { body } = sourceCode.ast;
+    const anchorNode = body.find((statement) => statement.type === utils_1.AST_NODE_TYPES.ImportDeclaration) ?? body.find((statement) => !isDirective(statement));
+    if (anchorNode) {
+        return {
+            kind: 'before',
+            target: climbBoundComments(sourceCode, anchorNode),
+        };
+    }
+    const lastDirective = [...body].reverse().find(isDirective);
+    if (lastDirective) {
+        // Start of the line after the directive, so a trailing same-line comment
+        // stays glued to its statement and no blank line is spliced in.
+        const lineEnd = sourceCode.text.indexOf('\n', lastDirective.range[1]);
+        return {
+            kind: 'index',
+            index: lineEnd === -1 ? sourceCode.text.length : lineEnd + 1,
+        };
+    }
+    if (sourceCode.text.startsWith('#!')) {
+        const lineEnd = sourceCode.text.indexOf('\n');
+        return {
+            kind: 'index',
+            index: lineEnd === -1 ? sourceCode.text.length : lineEnd + 1,
+        };
+    }
+    return { kind: 'index', index: 0 };
+}
+exports.importInsertionAnchor = importInsertionAnchor;
+/**
+ * Applies `text` at `anchor`. Callers keep full control of the inserted
+ * statement and its separators; the only adjustment made here is a leading
+ * newline when a raw-offset anchor sits mid-line (after a directive's `;` or
+ * at the unterminated end of a shebang), where splicing text verbatim would
+ * fuse the import onto the prologue's line.
+ */
+function insertAtImportAnchor(sourceCode, fixer, anchor, text) {
+    if (anchor.kind === 'before') {
+        return fixer.insertTextBefore(anchor.target, text);
+    }
+    const needsNewline = anchor.index > 0 && sourceCode.text[anchor.index - 1] !== '\n';
+    return fixer.insertTextBeforeRange([anchor.index, anchor.index], needsNewline ? `\n${text}` : text);
+}
+exports.insertAtImportAnchor = insertAtImportAnchor;
+/**
+ * Widens `anchor` to the start of its line, for rules that emit
+ * `${indent}import …\n` so the displaced anchor keeps its own indentation.
+ * Raw-offset anchors pass through: they never sit inside an indented line.
+ */
+function importAnchorLineStart(sourceCode, anchor) {
+    if (anchor.kind === 'index') {
+        return anchor;
+    }
+    const lineStart = sourceCode.text.lastIndexOf('\n', anchor.target.range[0] - 1) + 1;
+    return { kind: 'index', index: lineStart };
+}
+exports.importAnchorLineStart = importAnchorLineStart;
+/**
+ * The whitespace prefix of the anchor's line, for fixers that replicate the
+ * anchor's indentation on the inserted import.
+ */
+function importAnchorIndent(sourceCode, anchor) {
+    const from = anchor.kind === 'before' ? anchor.target.range[0] : anchor.index;
+    const lineStart = sourceCode.text.lastIndexOf('\n', from - 1) + 1;
+    const match = /^[ \t]*/.exec(sourceCode.text.slice(lineStart, from));
+    return match?.[0] ?? '';
+}
+exports.importAnchorIndent = importAnchorIndent;
+//# sourceMappingURL=importInsertion.js.map