eslint-rule-forge 0.3.2 → 0.5.0

package/src/imports.mts

@@ -61,8 +61,8 @@ export type ResolvedCallee = Readonly<{
   canonicalName: string;
 
   /**
-   * The identifier to rewrite to change what is called: the callee itself for
-   * a named import, the property for a namespace import.
+   * The identifier to rewrite to change what is called: the callee itself for a
+   * named import, the property for a namespace import.
    */
   propertyNode: TSESTree.Identifier;
 
@@ -140,33 +140,377 @@ 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 braces of the first import from the
+ *   module that has a value specifier, or else of the first other one with
+ *   braces that is not `import type`, empty braces included (`import {}`,
+ *   `import D, {}`).
+ *   Adding it there rather than in a new declaration keeps
+ *   `import-x/no-duplicates` satisfied. Failing that, it goes into new 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 hosts = hostsFor(declarations);
+
+  return {
+    localNames: defined.map((b) => b.localName),
+    edits: (fixer) => [
+      ...defined.flatMap((b) => b.edits(fixer)),
+      ...(toAdd.length === 0
+        ? []
+        : addToFirstHost(fixer, sourceCode, moduleName, hosts, toAdd)),
+    ],
+  };
+};
+
+/**
+ * The edits that import `moduleName`'s types `names` the file does not import
+ * yet: added to an existing `import type { … }` from the module (`, X`), else
+ * as `type X` to another import from it, chosen as {@link bindValueImports}
+ * chooses one, and only failing those as a new
+ * `import { type X } from '<module>'` after the directive prologue. Adding to
+ * an existing declaration keeps `import-x/no-duplicates` satisfied. Whether the
+ * file binds a name to something else is the caller's to check.
+ */
+export const addTypeImports = (
+  fixer: TSESLint.RuleFixer,
+  sourceCode: TSESLint.SourceCode,
+  moduleName: string,
+  names: readonly string[],
+): readonly TSESLint.RuleFix[] => {
+  if (names.length === 0) {
+    return [];
+  }
+
+  const declarations = getImportDeclarations(sourceCode.ast, moduleName);
+
+  const typeOnlyFix = firstFix(
+    declarations.filter(isTypeOnlyDeclaration),
+    (declaration) => addToImportBraces(fixer, sourceCode, declaration, names),
+  );
+
+  return typeOnlyFix !== undefined
+    ? [typeOnlyFix]
+    : addToFirstHost(
+        fixer,
+        sourceCode,
+        moduleName,
+        hostsFor(declarations),
+        names.map((name) => `type ${name}`),
+      );
+};
+
+/**
+ * Adds `specifiers` to the `{ … }` of `declaration`: after its last named
+ * specifier, or inside empty braces (`import d, {} from …`). `undefined` when
+ * the declaration has no braces (a default or namespace import alone) or there
+ * is nothing to add. The braces of import attributes (`with { … }`) are not
+ * taken for them.
+ */
+export const addToImportBraces = (
+  fixer: TSESLint.RuleFixer,
+  sourceCode: TSESLint.SourceCode,
+  declaration: TSESTree.ImportDeclaration,
+  specifiers: readonly string[],
+): TSESLint.RuleFix | undefined => {
+  if (specifiers.length === 0) {
+    return undefined;
+  }
+
+  const lastNamed = declaration.specifiers
+    .filter(
+      (specifier): specifier is TSESTree.ImportSpecifier =>
+        specifier.type === AST_NODE_TYPES.ImportSpecifier,
+    )
+    .at(-1);
+
+  if (lastNamed !== undefined) {
+    return fixer.insertTextAfter(lastNamed, `, ${specifiers.join(', ')}`);
+  }
+
+  const openingBrace = sourceCode.getFirstToken(declaration, {
+    filter: (token) =>
+      token.value === '{' && token.range[1] <= declaration.source.range[0],
+  });
+
+  return openingBrace === null
+    ? undefined
+    : fixer.insertTextAfter(openingBrace, ` ${specifiers.join(', ')} `);
+};
+
+/** 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;
+
+/** The first fix `toFix` gives for `declarations`, trying them in order. */
+const firstFix = (
+  declarations: readonly TSESTree.ImportDeclaration[],
+  toFix: (
+    declaration: TSESTree.ImportDeclaration,
+  ) => TSESLint.RuleFix | undefined,
+): TSESLint.RuleFix | undefined => {
+  for (const declaration of declarations) {
+    const fix = toFix(declaration);
+
+    if (fix !== undefined) {
+      return fix;
+    }
+  }
+
+  return undefined;
+};
+
+/**
+ * Adds `specifiers` to the braces of the first of `hosts` that has them, else
+ * puts braces after a lone default import among them (`import D, { x }`): a
+ * second declaration beside it would be a duplicate. Failing both, a new
+ * declaration importing them from `moduleName`.
+ */
+const addToFirstHost = (
+  fixer: TSESLint.RuleFixer,
+  sourceCode: TSESLint.SourceCode,
+  moduleName: string,
+  hosts: readonly TSESTree.ImportDeclaration[],
+  specifiers: readonly string[],
+): readonly TSESLint.RuleFix[] => {
+  const intoBraces = firstFix(hosts, (declaration) =>
+    addToImportBraces(fixer, sourceCode, declaration, specifiers),
+  );
+
+  if (intoBraces !== undefined) {
+    return [intoBraces];
+  }
+
+  const defaultHost = hosts.find(
+    (declaration) =>
+      declaration.specifiers.length === 1 &&
+      declaration.specifiers[0]?.type === AST_NODE_TYPES.ImportDefaultSpecifier,
+  )?.specifiers[0];
+
+  return defaultHost !== undefined
+    ? [fixer.insertTextAfter(defaultHost, `, { ${specifiers.join(', ')} }`)]
+    : buildNamedImportFix(fixer, sourceCode.ast, moduleName, specifiers);
+};
+
+/** 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;
+}>;
+
+/** `import type …`. */
+const isTypeOnlyDeclaration = (
+  declaration: TSESTree.ImportDeclaration,
+): boolean => declaration.importKind === 'type';
+
+/** The declaration is not `import type`. */
+const isNotTypeOnly = ({ declaration }: NamedSpecifier): boolean =>
+  !isTypeOnlyDeclaration(declaration);
+
+/** Neither `specifier` nor its declaration says `type`. */
+const isValueImport = ({ declaration, specifier }: NamedSpecifier): boolean =>
+  isNotTypeOnly({ declaration, specifier }) && specifier.importKind !== 'type';
+
+/**
+ * The declarations a name can be added to, in the order to try them: those that
+ * are not `import type`, the ones with a value specifier first, since one
+ * holding only `type` specifiers is erased (and flagged by
+ * `no-import-type-side-effects`) unless a value joins it.
+ */
+const hostsFor = (
+  declarations: readonly TSESTree.ImportDeclaration[],
+): readonly TSESTree.ImportDeclaration[] => {
+  const notTypeOnly = declarations.filter(
+    (declaration) => !isTypeOnlyDeclaration(declaration),
+  );
+
+  const hasValueSpecifier = (
+    declaration: TSESTree.ImportDeclaration,
+  ): boolean =>
+    declaration.specifiers.some(
+      (specifier) =>
+        specifier.type === AST_NODE_TYPES.ImportSpecifier &&
+        isValueImport({ declaration, specifier }),
+    );
+
+  return [
+    ...notTypeOnly.filter(hasValueSpecifier),
+    ...notTypeOnly.filter((declaration) => !hasValueSpecifier(declaration)),
+  ];
+};
+
+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,6 +1,8 @@
 export * from './bindings.mjs';
+export * from './comments.mjs';
 export * from './imports.mjs';
 export * from './negation.mjs';
 export * from './parentheses.mjs';
 export * from './rules/index.mjs';
+export * from './statements.mjs';
 export * from './type-wrappers.mjs';

package/src/negation.mts

@@ -137,10 +137,9 @@ export type NegationContext = Readonly<{
   checker: ts.TypeChecker;
   getLayerTypes: GetLayerTypes;
   /**
-   * Whether `node`'s value is a boolean, so that the negation of `!node` may
-   * be `node` itself. Where only the truthiness of the negation is read — the
-   * test of an `if` — any value will do, and this may answer `true` for every
-   * node.
+   * Whether `node`'s value is a boolean, so that the negation of `!node` may be
+   * `node` itself. Where only the truthiness of the negation is read — the test
+   * of an `if` — any value will do, and this may answer `true` for every node.
    */
   isBoolean: (node: DeepReadonly<TSESTree.Expression>) => boolean;
 }>;
@@ -159,12 +158,12 @@ export type NegationContext = Readonly<{
  * | anything else      | `!a`, `!(a)`      | always                                |
  *
  * `undefined` when the first two rows' condition does not hold: then the only
- * exact negation is `!!a` or `!(a < b)`, and a caller decides whether to
- * write it (with {@link prefixedNegationOf}) or to give up. Inside `&&` and
- * `||`, a side with no short negation is written with `!`.
+ * exact negation is `!!a` or `!(a < b)`, and a caller decides whether to write
+ * it (with {@link prefixedNegationOf}) or to give up. Inside `&&` and `||`, a
+ * side with no short negation is written with `!`.
  *
- * The node is taken as written: a comparison under a type wrapper is not
- * looked into, since inverting it would drop the wrapper.
+ * The node is taken as written: a comparison under a type wrapper is not looked
+ * into, since inverting it would drop the wrapper.
  */
 export const negationOf = (
   node: DeepReadonly<TSESTree.Expression>,
@@ -210,6 +209,34 @@ type Negation = Readonly<{
   precedence: Precedence;
 }>;
 
+const isLooserThan = (precedence: Precedence, operator: '&&' | '||'): boolean =>
+  precedence === 'looser' || (operator === '&&' && precedence === '||');
+
+const asOperand = (
+  negation: Negation,
+  operator: '&&' | '||' | undefined,
+): string =>
+  operator !== undefined && isLooserThan(negation.precedence, operator)
+    ? (`(${negation.text})` as const)
+    : negation.text;
+
+const precedenceOf = (node: DeepReadonly<TSESTree.Node>): Precedence => {
+  if (node.type === AST_NODE_TYPES.LogicalExpression) {
+    // `??` cannot be mixed with `&&` or `||` without parentheses.
+    return node.operator === '??' ? 'looser' : node.operator;
+  }
+
+  return LOOSER_THAN_LOGICAL.has(node.type) ? 'looser' : 'tighter';
+};
+
+/**
+ * The parser's node, which the source code and the token store take as mutable,
+ * for one that this package only reads.
+ */
+const asNode = <T extends TSESTree.Node>(node: DeepReadonly<T>): T =>
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  node as T;
+
 const shortNegationOf = (
   node: DeepReadonly<TSESTree.Expression>,
   context: NegationContext,
@@ -259,26 +286,6 @@ const shortNegationOf = (
   };
 };
 
-const asOperand = (
-  negation: Negation,
-  operator: '&&' | '||' | undefined,
-): string =>
-  operator !== undefined && isLooserThan(negation.precedence, operator)
-    ? (`(${negation.text})` as const)
-    : negation.text;
-
-const isLooserThan = (precedence: Precedence, operator: '&&' | '||'): boolean =>
-  precedence === 'looser' || (operator === '&&' && precedence === '||');
-
-const precedenceOf = (node: DeepReadonly<TSESTree.Node>): Precedence => {
-  if (node.type === AST_NODE_TYPES.LogicalExpression) {
-    // `??` cannot be mixed with `&&` or `||` without parentheses.
-    return node.operator === '??' ? 'looser' : node.operator;
-  }
-
-  return LOOSER_THAN_LOGICAL.has(node.type) ? 'looser' : 'tighter';
-};
-
 const LOOSER_THAN_LOGICAL: ReadonlySet<AST_NODE_TYPES> =
   new Set<AST_NODE_TYPES>([
     AST_NODE_TYPES.ArrowFunctionExpression,
@@ -348,11 +355,3 @@ const isNeverNaN = (type: ts.Type, checker: ts.TypeChecker): boolean => {
     checker.typeToString(brandType) === 'false'
   );
 };
-
-/**
- * The parser's node, which the source code and the token store take as
- * mutable, for one that this package only reads.
- */
-const asNode = <T extends TSESTree.Node>(node: DeepReadonly<T>): T =>
-  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-  node as T;

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';
 
@@ -44,10 +41,6 @@ export const createPreferArrayIsArray = ({
     create: (context) => {
       const sourceCode = context.sourceCode;
 
-      const program = sourceCode.ast;
-
-      const moduleImports = getImportDeclarations(program, moduleName);
-
       const mut_nodesToFix: TSESTree.CallExpression[] = [];
 
       return {
@@ -59,37 +52,31 @@ 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`,
+                      ),
+                    ],
             });
           }
         },