eslint-rule-forge 0.3.1 → 0.4.0

package/src/imports.mts

@@ -140,33 +140,233 @@ export const buildCalleeResolver = (
 
 /**
  * A fix that inserts `import { <specifiers> } from '<moduleName>';` at the top
- * of the file, or no fix when `specifiers` is empty. Each specifier is written
+ * of the file, after its directive prologue (`'use client';` stays a
+ * directive), or no fix when `specifiers` is empty. Each specifier is written
  * as given, so `type T` imports a type.
  *
- * The placement is deliberately naive: an import sorter
- * (prettier-plugin-organize-imports or any equivalent) merges and orders it
- * afterwards. Put every name one report needs into a single call: ESLint
- * merges the fixes of one report into one edit, and two fixes inserting at the
- * start of the file conflict, so that one of them is dropped.
+ * Use it only when the file does not import from `moduleName` by name;
+ * {@link bindValueImports} adds to an existing declaration instead, which
+ * keeps `import-x/no-duplicates` satisfied, and falls back to this. An import
+ * sorter orders the declaration afterwards. Put every name one report needs
+ * into a single call: ESLint merges the fixes of one report into one edit,
+ * and two fixes inserting at the same place conflict, so that one of them is
+ * dropped.
  */
 export const buildNamedImportFix = (
   fixer: TSESLint.RuleFixer,
   program: TSESTree.Program,
   moduleName: string,
   specifiers: readonly string[],
-): readonly TSESLint.RuleFix[] =>
-  specifiers.length === 0
-    ? ([] as const)
-    : ([
-        fixer.insertTextBefore(
-          program,
-          `import { ${specifiers.join(', ')} } from '${moduleName}';\n`,
-        ),
-      ] as const);
-
-const importedNameOf = (
+): readonly TSESLint.RuleFix[] => {
+  if (specifiers.length === 0) {
+    return [] as const;
+  }
+
+  const declaration =
+    `import { ${specifiers.join(', ')} } from '${moduleName}';` as const;
+
+  const lastDirective = program.body
+    .filter(
+      (statement): statement is TSESTree.ExpressionStatement =>
+        statement.type === AST_NODE_TYPES.ExpressionStatement &&
+        statement.directive !== undefined,
+    )
+    .at(-1);
+
+  if (lastDirective === undefined) {
+    return [fixer.insertTextBefore(program, `${declaration}\n`)] as const;
+  }
+
+  // After the comments that start on the directive's last line as well: one
+  // such as `// eslint-disable-line` is about that line.
+  const anchor =
+    (program.comments ?? [])
+      .filter(
+        (comment) =>
+          comment.range[0] >= lastDirective.range[1] &&
+          comment.loc.start.line === lastDirective.loc.end.line,
+      )
+      .at(-1) ?? lastDirective;
+
+  return [fixer.insertTextAfter(anchor, `\n${declaration}`)] as const;
+};
+
+/**
+ * The local names `moduleName`'s exports `exportNames` are bound to as values
+ * once `edits` are made, in the same order, or `undefined` when one of them
+ * cannot be bound.
+ *
+ * - Imported as a value: that local name, and no edit.
+ * - Imported by `import { type x }`: the edit drops `type`, keeping a comment
+ *   after it.
+ * - Not imported: the edit adds it to the first named import from the module
+ *   that has a value specifier, or else to any named import from it that is
+ *   not `import type`. Adding it there rather than in a new declaration keeps
+ *   `import-x/no-duplicates` satisfied. Failing that, it goes into braces
+ *   after a lone default import (`import D, { x }`), and when the module has
+ *   neither, a new declaration goes after the directive prologue
+ *   ({@link buildNamedImportFix}).
+ * - Refused when an import already binds the name to something else
+ *   (`import type { x }`, `import { y as x }`, `import { x } from 'other'`),
+ *   where adding it would be a duplicate binding.
+ *
+ * ESLint's default parser leaves `importKind` out, which counts as a value
+ * import. Every name a fix writes is bound by that fix's own edits rather than
+ * left to another report's: an editor applies one fix at a time, and a fix
+ * that loses a conflict with another in the same pass is dropped. Fixes that
+ * all add a name overlap, so `--fix` applies one per pass, and the rest in the
+ * next, by when the file imports it. Whether something other than an import
+ * binds the name where it is written is the caller's to check
+ * ({@link hasForeignBinding}).
+ */
+export const bindValueImports = (
+  sourceCode: TSESLint.SourceCode,
+  moduleName: string,
+  exportNames: readonly string[],
+): ValueImportBinding | undefined => {
+  const program = sourceCode.ast;
+
+  const allImports = program.body.filter(
+    (node): node is TSESTree.ImportDeclaration =>
+      node.type === AST_NODE_TYPES.ImportDeclaration,
+  );
+
+  const declarations = getImportDeclarations(program, moduleName);
+
+  const named = declarations.flatMap((declaration) =>
+    declaration.specifiers.flatMap((specifier) =>
+      specifier.type === AST_NODE_TYPES.ImportSpecifier
+        ? [{ declaration, specifier }]
+        : [],
+    ),
+  );
+
+  const bindings = exportNames.map((exportName) =>
+    bindingOf(sourceCode, allImports, named, exportName),
+  );
+
+  if (bindings.includes(undefined)) {
+    return undefined;
+  }
+
+  const defined = bindings.filter((b) => b !== undefined);
+
+  const toAdd = defined.flatMap((b) => (b.isAdded ? [b.localName] : []));
+
+  const host = (
+    named.find(isValueImport) ?? named.find(isNotTypeOnly)
+  )?.declaration.specifiers.at(-1);
+
+  // `import D from 'm'` takes `, { x }`: a second declaration beside it would
+  // be a duplicate.
+  const defaultHost = declarations.find(
+    (declaration) =>
+      declaration.importKind !== 'type' &&
+      declaration.specifiers.length === 1 &&
+      declaration.specifiers[0]?.type === AST_NODE_TYPES.ImportDefaultSpecifier,
+  )?.specifiers[0];
+
+  return {
+    localNames: defined.map((b) => b.localName),
+    edits: (fixer) => [
+      ...defined.flatMap((b) => b.edits(fixer)),
+      ...(toAdd.length === 0
+        ? []
+        : host !== undefined
+          ? [fixer.insertTextAfter(host, `, ${toAdd.join(', ')}`)]
+          : defaultHost !== undefined
+            ? [fixer.insertTextAfter(defaultHost, `, { ${toAdd.join(', ')} }`)]
+            : buildNamedImportFix(fixer, program, moduleName, toAdd)),
+    ],
+  };
+};
+
+/** The exported name `specifier` imports: `x` for `import { x as y }`. */
+export const importedNameOf = (
   specifier: DeepReadonly<TSESTree.ImportSpecifier>,
 ): string =>
   specifier.imported.type === AST_NODE_TYPES.Identifier
     ? specifier.imported.name
     : specifier.imported.value;
+
+/** What {@link bindValueImports} gives. */
+export type ValueImportBinding = Readonly<{
+  /** The names to write, in the order of the export names asked for. */
+  localNames: readonly string[];
+
+  /** The edits that bring every one of them into scope. */
+  edits: (fixer: TSESLint.RuleFixer) => readonly TSESLint.RuleFix[];
+}>;
+
+type NamedSpecifier = Readonly<{
+  declaration: TSESTree.ImportDeclaration;
+  specifier: TSESTree.ImportSpecifier;
+}>;
+
+/** Neither `specifier` nor its declaration says `type`. */
+const isValueImport = ({ declaration, specifier }: NamedSpecifier): boolean =>
+  isNotTypeOnly({ declaration, specifier }) && specifier.importKind !== 'type';
+
+/** The declaration is not `import type`. */
+const isNotTypeOnly = ({ declaration }: NamedSpecifier): boolean =>
+  declaration.importKind !== 'type';
+
+const bindingOf = (
+  sourceCode: TSESLint.SourceCode,
+  allImports: readonly TSESTree.ImportDeclaration[],
+  named: readonly NamedSpecifier[],
+  exportName: string,
+):
+  | Readonly<{
+      localName: string;
+      isAdded: boolean;
+      edits: (fixer: TSESLint.RuleFixer) => readonly TSESLint.RuleFix[];
+    }>
+  | undefined => {
+  const matching = named.filter(
+    ({ specifier }) => importedNameOf(specifier) === exportName,
+  );
+
+  const value = matching.find(isValueImport);
+
+  if (value !== undefined) {
+    return {
+      localName: value.specifier.local.name,
+      isAdded: false,
+      edits: () => [],
+    };
+  }
+
+  const inlineType = matching.find(isNotTypeOnly)?.specifier;
+
+  if (inlineType !== undefined) {
+    const typeKeyword = sourceCode.getFirstToken(inlineType);
+
+    // Up to whatever follows `type`, a comment included, so that the comment
+    // stays.
+    const next =
+      typeKeyword === null
+        ? null
+        : sourceCode.getTokenAfter(typeKeyword, { includeComments: true });
+
+    return typeKeyword === null || next === null
+      ? undefined
+      : {
+          localName: inlineType.local.name,
+          isAdded: false,
+          edits: (fixer) => [
+            fixer.removeRange([typeKeyword.range[0], next.range[0]]),
+          ],
+        };
+  }
+
+  const isTaken = allImports.some((declaration) =>
+    declaration.specifiers.some(
+      (specifier) => specifier.local.name === exportName,
+    ),
+  );
+
+  return isTaken
+    ? undefined
+    : { localName: exportName, isAdded: true, edits: () => [] };
+};

package/src/index.mts

@@ -1,4 +1,5 @@
 export * from './bindings.mjs';
+export * from './comments.mjs';
 export * from './imports.mjs';
 export * from './negation.mjs';
 export * from './parentheses.mjs';

package/src/negation.mts

@@ -279,32 +279,34 @@ const precedenceOf = (node: DeepReadonly<TSESTree.Node>): Precedence => {
   return LOOSER_THAN_LOGICAL.has(node.type) ? 'looser' : 'tighter';
 };
 
-const LOOSER_THAN_LOGICAL: ReadonlySet<AST_NODE_TYPES> = new Set([
-  AST_NODE_TYPES.ArrowFunctionExpression,
-  AST_NODE_TYPES.AssignmentExpression,
-  AST_NODE_TYPES.ConditionalExpression,
-  AST_NODE_TYPES.SequenceExpression,
-  AST_NODE_TYPES.YieldExpression,
-]);
+const LOOSER_THAN_LOGICAL: ReadonlySet<AST_NODE_TYPES> =
+  new Set<AST_NODE_TYPES>([
+    AST_NODE_TYPES.ArrowFunctionExpression,
+    AST_NODE_TYPES.AssignmentExpression,
+    AST_NODE_TYPES.ConditionalExpression,
+    AST_NODE_TYPES.SequenceExpression,
+    AST_NODE_TYPES.YieldExpression,
+  ]);
 
 /** Expressions `!` can be put in front of without parentheses. */
-const BINDS_AS_TIGHT_AS_UNARY: ReadonlySet<AST_NODE_TYPES> = new Set([
-  AST_NODE_TYPES.ArrayExpression,
-  AST_NODE_TYPES.AwaitExpression,
-  AST_NODE_TYPES.CallExpression,
-  AST_NODE_TYPES.ChainExpression,
-  AST_NODE_TYPES.Identifier,
-  AST_NODE_TYPES.Literal,
-  AST_NODE_TYPES.MemberExpression,
-  AST_NODE_TYPES.MetaProperty,
-  AST_NODE_TYPES.NewExpression,
-  AST_NODE_TYPES.ObjectExpression,
-  AST_NODE_TYPES.TaggedTemplateExpression,
-  AST_NODE_TYPES.TemplateLiteral,
-  AST_NODE_TYPES.ThisExpression,
-  AST_NODE_TYPES.TSNonNullExpression,
-  AST_NODE_TYPES.UnaryExpression,
-]);
+const BINDS_AS_TIGHT_AS_UNARY: ReadonlySet<AST_NODE_TYPES> =
+  new Set<AST_NODE_TYPES>([
+    AST_NODE_TYPES.ArrayExpression,
+    AST_NODE_TYPES.AwaitExpression,
+    AST_NODE_TYPES.CallExpression,
+    AST_NODE_TYPES.ChainExpression,
+    AST_NODE_TYPES.Identifier,
+    AST_NODE_TYPES.Literal,
+    AST_NODE_TYPES.MemberExpression,
+    AST_NODE_TYPES.MetaProperty,
+    AST_NODE_TYPES.NewExpression,
+    AST_NODE_TYPES.ObjectExpression,
+    AST_NODE_TYPES.TaggedTemplateExpression,
+    AST_NODE_TYPES.TemplateLiteral,
+    AST_NODE_TYPES.ThisExpression,
+    AST_NODE_TYPES.TSNonNullExpression,
+    AST_NODE_TYPES.UnaryExpression,
+  ]);
 
 const RELATIONAL_OPERATORS: ReadonlySet<ComparisonOperator> =
   new Set<ComparisonOperator>(['<', '<=', '>', '>=']);

package/src/rules/no-side-effect-import.mts

@@ -28,6 +28,7 @@ export const createNoSideEffectImport = ({
       fixable: 'code',
       schema: [],
       messages: { removeSideEffectImport: message },
+      defaultOptions: [],
     },
 
     create: (context) => ({
@@ -43,7 +44,6 @@ export const createNoSideEffectImport = ({
         });
       },
     }),
-    defaultOptions: [],
   }) as const;
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */

package/src/rules/prefer-array-is-array.mts

@@ -3,11 +3,8 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import {
-  buildNamedImportFix,
-  getImportDeclarations,
-  getNamedImports,
-} from '../imports.mjs';
+import { hasForeignBinding } from '../bindings.mjs';
+import { bindValueImports } from '../imports.mjs';
 import { getRangeWithParens } from '../parentheses.mjs';
 import { isIdentifierNamed, skipTypeWrappers } from '../type-wrappers.mjs';
 
@@ -38,15 +35,12 @@ export const createPreferArrayIsArray = ({
       fixable: 'code',
       schema: [],
       messages: { useIsArray: text },
+      defaultOptions: [],
     },
 
     create: (context) => {
       const sourceCode = context.sourceCode;
 
-      const program = sourceCode.ast;
-
-      const moduleImports = getImportDeclarations(program, moduleName);
-
       const mut_nodesToFix: TSESTree.CallExpression[] = [];
 
       return {
@@ -58,43 +52,36 @@ export const createPreferArrayIsArray = ({
           mut_nodesToFix.push(node);
         },
         'Program:exit': () => {
-          const hasNamespaceImport =
-            getNamedImports(moduleImports).includes(namespace);
+          const binding = bindValueImports(sourceCode, moduleName, [namespace]);
 
-          // The import fix lives on the first report only:
-          // `insertTextBefore(program, …)` produces overlapping ranges
-          // otherwise and only one of them would survive a pass. A first
-          // report silenced by an `eslint-disable` comment therefore takes
-          // the import with it.
-          for (const [index, node] of mut_nodesToFix.entries()) {
+          const localName = binding?.localNames[0];
+
+          // Every fix brings the namespace into scope itself, so that one
+          // applied alone (an editor's quick fix) is complete.
+          for (const node of mut_nodesToFix) {
             context.report({
               node,
               messageId: 'useIsArray',
-              fix: (fixer) => {
-                const importFixes =
-                  index === 0 && !hasNamespaceImport
-                    ? buildNamedImportFix(fixer, program, moduleName, [
-                        namespace,
-                      ])
-                    : ([] as const);
-
-                // Only the callee is replaced, type wrappers included, along
-                // with the parentheses around it, which its range leaves out;
-                // the arguments stay as written.
-                return [
-                  ...importFixes,
-                  fixer.replaceTextRange(
-                    getRangeWithParens(sourceCode, node.callee),
-                    replacement,
-                  ),
-                ];
-              },
+              fix:
+                binding === undefined ||
+                localName === undefined ||
+                hasForeignBinding(sourceCode, node, localName, moduleName)
+                  ? null
+                  : (fixer) => [
+                      ...binding.edits(fixer),
+                      // Only the callee is replaced, type wrappers included,
+                      // along with the parentheses around it, which its range
+                      // leaves out; the arguments stay as written.
+                      fixer.replaceTextRange(
+                        getRangeWithParens(sourceCode, node.callee),
+                        `${localName}.isArray`,
+                      ),
+                    ],
             });
           }
         },
       };
     },
-    defaultOptions: [],
   } as const;
 };
 

package/src/rules/prefer-is-non-null-object.mts

@@ -3,11 +3,8 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import {
-  buildNamedImportFix,
-  getImportDeclarations,
-  getNamedImports,
-} from '../imports.mjs';
+import { hasForeignBinding } from '../bindings.mjs';
+import { bindValueImports } from '../imports.mjs';
 import { getRangeWithParens, parenthesesDepth } from '../parentheses.mjs';
 import { skipTypeWrappers } from '../type-wrappers.mjs';
 
@@ -33,16 +30,14 @@ export const createPreferIsNonNullObject = ({
       messages: {
         useIsNonNullObject: `Replace the object/null check with \`isNonNullObject()\` from ${moduleName}.`,
       },
+      defaultOptions: [],
     },
 
     create: (context) => {
       const sourceCode = context.sourceCode;
 
-      const program = sourceCode.ast;
-
-      const moduleImports = getImportDeclarations(program, moduleName);
-
-      const mut_pairsToFix: NonNullObjectPair[] = [];
+      const mut_pairsToFix: (NonNullObjectPair &
+        Readonly<{ chain: TSESTree.LogicalExpression }>)[] = [];
 
       return {
         LogicalExpression: (node) => {
@@ -51,48 +46,48 @@ export const createPreferIsNonNullObject = ({
             return;
           }
 
-          mut_pairsToFix.push(...findNonNullObjectPairs(sourceCode, node));
+          mut_pairsToFix.push(
+            ...findNonNullObjectPairs(sourceCode, node).map((pair) => ({
+              ...pair,
+              chain: node,
+            })),
+          );
         },
         'Program:exit': () => {
-          const hasIsNonNullObjectImport =
-            getNamedImports(moduleImports).includes('isNonNullObject');
-
-          // The import fix lives on the first report only:
-          // `insertTextBefore(program, …)` produces overlapping ranges
-          // otherwise and only one of them would survive a pass. A first
-          // report silenced by an `eslint-disable` comment therefore takes
-          // the import with it.
-          for (const [
-            index,
-            { range, identifierName },
-          ] of mut_pairsToFix.entries()) {
+          const binding = bindValueImports(sourceCode, moduleName, [
+            'isNonNullObject',
+          ]);
+
+          const localName = binding?.localNames[0];
+
+          // Every fix brings `isNonNullObject` into scope itself, so that one
+          // applied alone (an editor's quick fix) is complete.
+          for (const { range, identifierName, chain } of mut_pairsToFix) {
+            const loc = {
+              start: sourceCode.getLocFromIndex(range[0]),
+              end: sourceCode.getLocFromIndex(range[1]),
+            } as const;
+
             context.report({
-              loc: {
-                start: sourceCode.getLocFromIndex(range[0]),
-                end: sourceCode.getLocFromIndex(range[1]),
-              },
+              loc,
               messageId: 'useIsNonNullObject',
-              fix: (fixer) => {
-                const replacement = `isNonNullObject(${identifierName})`;
-
-                const importFixes =
-                  index === 0 && !hasIsNonNullObjectImport
-                    ? buildNamedImportFix(fixer, program, moduleName, [
-                        'isNonNullObject',
-                      ])
-                    : [];
-
-                return [
-                  ...importFixes,
-                  fixer.replaceTextRange(range, replacement),
-                ];
-              },
+              fix:
+                binding === undefined ||
+                localName === undefined ||
+                hasForeignBinding(sourceCode, chain, localName, moduleName)
+                  ? null
+                  : (fixer) => [
+                      ...binding.edits(fixer),
+                      fixer.replaceTextRange(
+                        range,
+                        `${localName}(${identifierName})`,
+                      ),
+                    ],
             });
           }
         },
       };
     },
-    defaultOptions: [],
   }) as const;
 
 /**