eslint-rule-forge 0.4.0 → 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;
 
@@ -145,12 +145,11 @@ export const buildCalleeResolver = (
  * as given, so `type T` imports a type.
  *
  * 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.
+ * {@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,
@@ -199,10 +198,12 @@ export const buildNamedImportFix = (
  * - 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
+ * - 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}).
@@ -212,11 +213,11 @@ export const buildNamedImportFix = (
  *
  * 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
+ * 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 = (
@@ -253,18 +254,7 @@ export const bindValueImports = (
 
   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];
+  const hosts = hostsFor(declarations);
 
   return {
     localNames: defined.map((b) => b.localName),
@@ -272,15 +262,86 @@ export const bindValueImports = (
       ...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)),
+        : 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>,
@@ -289,6 +350,56 @@ export const importedNameOf = (
     ? 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. */
@@ -303,13 +414,46 @@ type NamedSpecifier = Readonly<{
   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 declaration is not `import type`. */
-const isNotTypeOnly = ({ declaration }: NamedSpecifier): boolean =>
-  declaration.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,

package/src/index.mts

@@ -4,4 +4,5 @@ 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-is-non-null-object.mts

@@ -115,51 +115,8 @@ const isChainOperand = (
   parenthesesDepth(sourceCode, node) === 0;
 
 /**
- * Every non-overlapping pair in the `&&` chain `node` heads, left to right. The
- * two halves may come in either order, and the pair may have operands before
- * and after it: `a && u !== null && typeof u === 'object' && b`. They have to
- * be next to each other, so that the pair is one range of the source.
- */
-const findNonNullObjectPairs = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  sourceCode: TSESLint.SourceCode,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: TSESTree.LogicalExpression,
-): readonly NonNullObjectPair[] => {
-  const operands = chainOperands(sourceCode, node);
-
-  const pairsFrom = (index: number): readonly NonNullObjectPair[] => {
-    const first = operands[index];
-
-    const second = operands[index + 1];
-
-    if (first === undefined || second === undefined) {
-      return [];
-    }
-
-    const identifierName =
-      pairIdentifierName(first, second) ?? pairIdentifierName(second, first);
-
-    return identifierName === undefined
-      ? pairsFrom(index + 1)
-      : [
-          {
-            range: [
-              getRangeWithParens(sourceCode, first)[0],
-              getRangeWithParens(sourceCode, second)[1],
-            ],
-            identifierName,
-          },
-          ...pairsFrom(index + 2),
-        ];
-  };
-
-  return pairsFrom(0);
-};
-
-/**
- * The operands of the `&&` chain `node`, left to right. A parenthesized `&&`
- * is one operand: its halves cannot be replaced without its parentheses.
+ * The operands of the `&&` chain `node`, left to right. A parenthesized `&&` is
+ * one operand: its halves cannot be replaced without its parentheses.
  */
 const chainOperands = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -178,26 +135,11 @@ const chainOperands = (
 // Every operand below is read through its type wrappers: `typeof (u satisfies
 // unknown) === 'object' && u! !== null` is the same check.
 
-/**
- * The name of `u` when `typeofCheck` is `typeof u === 'object'` and
- * `nullCheck` is `u !== null` for the same `u`.
- */
-const pairIdentifierName = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  typeofCheck: TSESTree.Expression,
+const isLiteralOf = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  nullCheck: TSESTree.Expression,
-): string | undefined => {
-  const identifierName = getTypeofObjectIdentifierName(
-    skipTypeWrappers(typeofCheck),
-  );
-
-  return identifierName !== undefined &&
-    identifierName ===
-      getNonNullCheckIdentifierName(skipTypeWrappers(nullCheck))
-    ? identifierName
-    : undefined;
-};
+  node: TSESTree.Node,
+  value: string | null,
+): boolean => node.type === AST_NODE_TYPES.Literal && node.value === value;
 
 /** `u` of `typeof u === 'object'`, in either operand order. */
 const getTypeofObjectIdentifierName = (
@@ -237,8 +179,8 @@ const getTypeofObjectIdentifierName = (
 
 /**
  * `u` of `u !== null`, in either operand order. `u != null` also excludes
- * `undefined`, which `typeof u === 'object'` has already excluded, so it is
- * the same check here.
+ * `undefined`, which `typeof u === 'object'` has already excluded, so it is the
+ * same check here.
  */
 const getNonNullCheckIdentifierName = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -264,8 +206,66 @@ const getNonNullCheckIdentifierName = (
   return checked?.type === AST_NODE_TYPES.Identifier ? checked.name : undefined;
 };
 
-const isLiteralOf = (
+/**
+ * The name of `u` when `typeofCheck` is `typeof u === 'object'` and `nullCheck`
+ * is `u !== null` for the same `u`.
+ */
+const pairIdentifierName = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: TSESTree.Node,
-  value: string | null,
-): boolean => node.type === AST_NODE_TYPES.Literal && node.value === value;
+  typeofCheck: TSESTree.Expression,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  nullCheck: TSESTree.Expression,
+): string | undefined => {
+  const identifierName = getTypeofObjectIdentifierName(
+    skipTypeWrappers(typeofCheck),
+  );
+
+  return identifierName !== undefined &&
+    identifierName ===
+      getNonNullCheckIdentifierName(skipTypeWrappers(nullCheck))
+    ? identifierName
+    : undefined;
+};
+
+/**
+ * Every non-overlapping pair in the `&&` chain `node` heads, left to right. The
+ * two halves may come in either order, and the pair may have operands before
+ * and after it: `a && u !== null && typeof u === 'object' && b`. They have to
+ * be next to each other, so that the pair is one range of the source.
+ */
+const findNonNullObjectPairs = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.LogicalExpression,
+): readonly NonNullObjectPair[] => {
+  const operands = chainOperands(sourceCode, node);
+
+  const pairsFrom = (index: number): readonly NonNullObjectPair[] => {
+    const first = operands[index];
+
+    const second = operands[index + 1];
+
+    if (first === undefined || second === undefined) {
+      return [];
+    }
+
+    const identifierName =
+      pairIdentifierName(first, second) ?? pairIdentifierName(second, first);
+
+    return identifierName === undefined
+      ? pairsFrom(index + 1)
+      : [
+          {
+            range: [
+              getRangeWithParens(sourceCode, first)[0],
+              getRangeWithParens(sourceCode, second)[1],
+            ],
+            identifierName,
+          },
+          ...pairsFrom(index + 2),
+        ];
+  };
+
+  return pairsFrom(0);
+};

package/src/rules/prefer-is-record-and-has-key.mts

@@ -45,11 +45,11 @@ export const createPreferIsRecordAndHasKey = ({
       /**
        * Whether the `isRecord(...)` half of the rewrite would be dead code
        * because the object already satisfies `hasKey`'s
-       * `R extends UnknownRecord` constraint, at every layer of type
-       * wrappers: an array cast to a record is still rejected by `isRecord`,
-       * and a record widened to one that may be an array is the author saying
-       * it may need the guard. Without type information nothing is known, so
-       * the guard is kept.
+       * `R extends UnknownRecord` constraint, at every layer of type wrappers:
+       * an array cast to a record is still rejected by `isRecord`, and a record
+       * widened to one that may be an array is the author saying it may need
+       * the guard. Without type information nothing is known, so the guard is
+       * kept.
        */
       const isKnownRecord = (
         // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types