@blumintinc/eslint-plugin-blumint 1.20.85 → 1.20.87

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

package/lib/utils/importRemoval.d.ts

@@ -0,0 +1,57 @@
+import { TSESLint, TSESTree } from '@typescript-eslint/utils';
+/** A half-open `[start, end)` slice of the source text. */
+export type TextRange = readonly [number, number];
+/** An import clause that introduces exactly one local binding. */
+export type ImportBindingSpecifier = TSESTree.ImportSpecifier | TSESTree.ImportDefaultSpecifier | TSESTree.ImportNamespaceSpecifier;
+/**
+ * The source a rule needs to unbind an import. Narrower than
+ * `TSESLint.SourceCode` so tests can drive the helper without a full linter
+ * run.
+ */
+export type ImportRemovalSource = Pick<TSESLint.SourceCode, 'text' | 'ast' | 'scopeManager' | 'getTokenBefore' | 'getTokenAfter' | 'getCommentsBefore' | 'getCommentsInside'>;
+/**
+ * The text ranges that unbind `specifiers` from their shared declaration, or
+ * `null` when no removal is provably safe. All specifiers of the declaration
+ * being listed collapses the declaration itself rather than leaving
+ * `import {} from './User';` behind, and losing every *named* specifier next to
+ * a surviving default takes the braces with it.
+ *
+ * Any comment inside the declaration declines the removal outright: the ranges
+ * computed here span separators, so a comment nested among the specifiers
+ * would be swallowed or stranded depending on where it sits.
+ */
+export declare function planImportBindingRemoval(source: ImportRemovalSource, specifiers: readonly ImportBindingSpecifier[]): TextRange[] | null;
+/**
+ * Fixes unbinding `specifiers`, or `null` when the removal is not provably
+ * safe. A caller that gets `null` must drop its whole fix: a rewrite that
+ * strips a binding's last use while leaving the binding behind trades its own
+ * report for an unused-variable one.
+ */
+export declare function removeImportBindingFixes(source: ImportRemovalSource, fixer: TSESLint.RuleFixer, specifiers: readonly ImportBindingSpecifier[]): TSESLint.RuleFix[] | null;
+/**
+ * The specifier that binds `variable`, when the variable is a named/default/
+ * namespace import. `import X = require('y')` binds through a declaration of
+ * its own rather than a specifier and is left alone.
+ */
+export declare function importBindingSpecifierOf(variable: TSESLint.Scope.Variable): ImportBindingSpecifier | undefined;
+/**
+ * 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
+ * unbound safely — an import behind a directive comment, a type alias or a type
+ * parameter, all of which this helper refuses to guess at.
+ *
+ * `null` is a demand, not a suggestion: the caller declines its whole fix. The
+ * alternative — deleting the last use and keeping the declaration — converts a
+ * file that lints clean into one that fails `no-unused-vars`, and since the
+ * original report is resolved by the fix, nothing re-reports the debt.
+ *
+ * `removed` is one fix's own deletion, judged against the file as it stands.
+ * Widening it to "everything this `--fix` run will delete" looks like it would
+ * catch a binding two edits share, but it is unsound: a rule cannot see
+ * `eslint-disable` comments, because suppression is applied to reports after the
+ * rule emits them. A suppressed sibling edit never happens, so the widened view
+ * deletes an import that a surviving reference still needs — trading an unused
+ * import for a dangling type reference, a lint warning for a compile error.
+ * There is deliberately no way to ask this helper that question.
+ */
+export declare function planOrphanedImportRemoval(source: ImportRemovalSource, removed: readonly TextRange[]): TextRange[] | null;