eslint-plugin-ts-data-forge 0.10.4 → 0.10.6

package/src/rules/mutable-result.mts

@@ -74,62 +74,6 @@ const outermostTypePreservingWrapper = (
     : node;
 };
 
-const isUsedAsMutable = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  checker: ts.TypeChecker,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  getTsNode: (esNode: TSESTree.Node) => ts.Node | undefined,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: TSESTree.Node,
-): boolean => {
-  const parent = node.parent;
-
-  if (
-    parent?.type === AST_NODE_TYPES.MemberExpression &&
-    parent.object === node
-  ) {
-    // xs.push(...), xs.sort(), ...
-    if (
-      !parent.computed &&
-      parent.property.type === AST_NODE_TYPES.Identifier &&
-      mutatingMethods.has(parent.property.name)
-    ) {
-      return true;
-    }
-
-    // xs[0] = ..., xs.length = ..., xs[0]++, delete xs[0]
-    const grandParent = parent.parent;
-
-    return (
-      (grandParent.type === AST_NODE_TYPES.AssignmentExpression &&
-        grandParent.left === parent) ||
-      grandParent.type === AST_NODE_TYPES.UpdateExpression ||
-      (grandParent.type === AST_NODE_TYPES.UnaryExpression &&
-        grandParent.operator === 'delete')
-    );
-  }
-
-  // Passed to a parameter, assigned to a variable, or returned from a function
-  // whose declared type is a mutable array.
-  const tsNode = getTsNode(node);
-
-  if (tsNode === undefined) {
-    return false;
-  }
-
-  if (!ts.isExpression(tsNode)) {
-    return false;
-  }
-
-  const expectedType =
-    getDeclaredParameterType(checker, tsNode) ??
-    checker.getContextualType(tsNode);
-
-  return (
-    expectedType !== undefined && isMutableArrayOnly(checker, expectedType)
-  );
-};
-
 /**
  * The declared type of the parameter `argument` is passed to. The contextual
  * type of an argument to a generic function is instantiated from that very
@@ -190,6 +134,62 @@ const isMutableArrayOnly = (
   );
 };
 
+const isUsedAsMutable = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  checker: ts.TypeChecker,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  getTsNode: (esNode: TSESTree.Node) => ts.Node | undefined,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Node,
+): boolean => {
+  const parent = node.parent;
+
+  if (
+    parent?.type === AST_NODE_TYPES.MemberExpression &&
+    parent.object === node
+  ) {
+    // xs.push(...), xs.sort(), ...
+    if (
+      !parent.computed &&
+      parent.property.type === AST_NODE_TYPES.Identifier &&
+      mutatingMethods.has(parent.property.name)
+    ) {
+      return true;
+    }
+
+    // xs[0] = ..., xs.length = ..., xs[0]++, delete xs[0]
+    const grandParent = parent.parent;
+
+    return (
+      (grandParent.type === AST_NODE_TYPES.AssignmentExpression &&
+        grandParent.left === parent) ||
+      grandParent.type === AST_NODE_TYPES.UpdateExpression ||
+      (grandParent.type === AST_NODE_TYPES.UnaryExpression &&
+        grandParent.operator === 'delete')
+    );
+  }
+
+  // Passed to a parameter, assigned to a variable, or returned from a function
+  // whose declared type is a mutable array.
+  const tsNode = getTsNode(node);
+
+  if (tsNode === undefined) {
+    return false;
+  }
+
+  if (!ts.isExpression(tsNode)) {
+    return false;
+  }
+
+  const expectedType =
+    getDeclaredParameterType(checker, tsNode) ??
+    checker.getContextualType(tsNode);
+
+  return (
+    expectedType !== undefined && isMutableArrayOnly(checker, expectedType)
+  );
+};
+
 /** Methods that `ReadonlyArray` lacks and that mutate the receiver. */
 const mutatingMethods: ReadonlySet<string> = new Set<string>([
   'copyWithin',

package/src/rules/no-unnecessary-type-guard.mts

@@ -6,14 +6,13 @@ import {
 } from '@typescript-eslint/utils';
 import {
   buildCalleeResolver,
-  buildNamedImportFix,
   getImportDeclarations,
-  getImportedLocalName,
   typeWrapperLayers,
 } from 'eslint-rule-forge';
 import type { DeepReadonly, ReadonlyRecord } from 'ts-type-forge';
 import * as ts from 'typescript';
 import { TS_DATA_FORGE_MODULE } from './constants.mjs';
+import { tsDataForgeValueAtByName } from './import-binding.mjs';
 
 type Options = readonly [
   Readonly<{
@@ -178,39 +177,32 @@ export const noUnnecessaryTypeGuard: TSESLint.RuleModule<MessageIds, Options> =
 
       const resolveGuard = buildCalleeResolver(tsDataForgeImports);
 
-      const buildReplaceFix =
-        (
-          isNamespace: boolean,
-          // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-          propertyNode: TSESTree.Node,
-          replacement: string,
-        ): TSESLint.ReportFixFunction =>
-        (fixer) => {
-          // A namespace member access (`tf.isX`) exposes every export, so the
-          // canonical name is always in scope.
-          if (isNamespace) {
-            return [fixer.replaceText(propertyNode, replacement)];
-          }
-
-          // If the replacement guard is already imported (possibly under an
-          // alias), rename to its in-scope local name. Otherwise add a new
-          // import and rename to the canonical name.
-          const localName = getImportedLocalName(
-            tsDataForgeImports,
-            replacement,
-          );
+      // One binding per replacement guard, however many reports use it.
+      const guardAt = tsDataForgeValueAtByName(sourceCode);
 
-          if (localName !== undefined) {
-            return [fixer.replaceText(propertyNode, localName)];
-          }
-
-          return [
-            ...buildNamedImportFix(fixer, program, TS_DATA_FORGE_MODULE, [
-              replacement,
-            ]),
-            fixer.replaceText(propertyNode, replacement),
-          ];
-        };
+      const buildReplaceFix = (
+        isNamespace: boolean,
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        propertyNode: TSESTree.Node,
+        replacement: string,
+      ): TSESLint.ReportFixFunction | null => {
+        // A namespace member access (`tf.isX`) exposes every export, so the
+        // canonical name is always in scope.
+        if (isNamespace) {
+          return (fixer) => [fixer.replaceText(propertyNode, replacement)];
+        }
+
+        // The replacement guard's local name, added to the imports when the
+        // file does not import it; no fix when it cannot be bound there.
+        const guard = guardAt(replacement)(propertyNode);
+
+        return guard === undefined
+          ? null
+          : (fixer) => [
+              ...guard.edits(fixer),
+              fixer.replaceText(propertyNode, guard.localName),
+            ];
+      };
 
       const reportConstant = (
         node: DeepReadonly<TSESTree.CallExpression>,
@@ -250,7 +242,11 @@ export const noUnnecessaryTypeGuard: TSESLint.RuleModule<MessageIds, Options> =
           // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           node: node as TSESTree.Node,
           messageId: 'replaceTypeGuard',
-          data: { from, to },
+          // The name the fix writes: an aliased import's local name.
+          data: {
+            from,
+            to: isNamespace ? to : (guardAt(to)(propertyNode)?.localName ?? to),
+          },
           fix: buildReplaceFix(isNamespace, propertyNode, to),
         });
       };
@@ -335,6 +331,174 @@ type Verdict = DeepReadonly<
   | { kind: 'replace'; replacement: string }
 >;
 
+const replacementVerdict = (
+  replacement: string | undefined,
+): Verdict | undefined =>
+  replacement === undefined
+    ? undefined
+    : ({ kind: 'replace', replacement } as const);
+
+/**
+ * Decomposes a type into its union members. Returns `undefined` when any member
+ * is opaque (`any` / `unknown` / `never`) or deferred (type parameter, indexed
+ * access, …), signalling that the rule should not draw conclusions.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+const collectUnionParts = (type: ts.Type): readonly ts.Type[] | undefined => {
+  const parts = type.isUnion() ? type.types : ([type] as const);
+
+  for (const part of parts) {
+    if ((part.flags & DEFERRED_OR_OPAQUE_FLAGS) !== 0) {
+      return undefined;
+    }
+  }
+
+  return parts;
+};
+
+const isCallableType = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  type: ts.Type,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  checker: ts.TypeChecker,
+): boolean =>
+  checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0 ||
+  checker.getSignaturesOfType(type, ts.SignatureKind.Construct).length > 0;
+
+/**
+ * Whether `isRecord` is guaranteed to accept this (non-union) type.
+ *
+ * `isRecord` narrows to `UnknownRecord` (`ReadonlyRecord<string, unknown>`), so
+ * a string index signature is exactly what it asks for and its value type is
+ * `unknown`, which anything satisfies. Arrays and callables are excluded even
+ * when they carry one, because `isRecord` rejects them at runtime
+ * (`Array.isArray` is true; `typeof fn === 'object'` is false).
+ *
+ * Deliberately conservative: an object type without an index signature of its
+ * own is reported as neither guaranteed-accepted nor guaranteed-rejected, even
+ * where TypeScript would accept it through an implicit index signature.
+ */
+const isGuaranteedRecord = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  type: ts.Type,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  checker: ts.TypeChecker,
+): boolean =>
+  checker.getIndexInfoOfType(type, ts.IndexKind.String) !== undefined &&
+  !isCallableType(type, checker) &&
+  !checker.isArrayType(type) &&
+  !checker.isTupleType(type);
+
+/** Classifies a single (non-union) type into a primitive {@link Atom}. */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+const classifyAtom = (type: ts.Type): Atom => {
+  const { flags } = type;
+
+  if ((flags & ts.TypeFlags.Undefined) !== 0) {
+    return 'undefined';
+  }
+
+  if ((flags & ts.TypeFlags.Null) !== 0) {
+    return 'null';
+  }
+
+  if ((flags & ts.TypeFlags.BooleanLike) !== 0) {
+    return 'boolean';
+  }
+
+  if ((flags & ts.TypeFlags.NumberLike) !== 0) {
+    return 'number';
+  }
+
+  if ((flags & ts.TypeFlags.StringLike) !== 0) {
+    return 'string';
+  }
+
+  if ((flags & ts.TypeFlags.BigIntLike) !== 0) {
+    return 'bigint';
+  }
+
+  if ((flags & ts.TypeFlags.ESSymbolLike) !== 0) {
+    return 'symbol';
+  }
+
+  // Branded primitives (e.g. `NonEmptyString = string & {...}`) are
+  // intersections; classify them by their underlying primitive constituent.
+  if (type.isIntersection()) {
+    for (const constituent of type.types) {
+      const atom = classifyAtom(constituent);
+
+      if (atom !== 'other') {
+        return atom;
+      }
+    }
+  }
+
+  return 'other';
+};
+
+/**
+ * Whether `isRecord` is guaranteed to reject this (non-union) type: every
+ * primitive (`null` included), every array or tuple, and every callable fails
+ * its `typeof x === 'object' && x !== null && !Array.isArray(x)` check.
+ */
+const isGuaranteedNotRecord = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  type: ts.Type,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  checker: ts.TypeChecker,
+): boolean =>
+  classifyAtom(type) !== 'other' ||
+  checker.isArrayType(type) ||
+  checker.isTupleType(type) ||
+  isCallableType(type, checker);
+
+/** A stable key for a set of atoms, used to look up replacement guards. */
+const joinAtoms = (atoms: readonly AtomKey[]): string =>
+  ATOM_ORDER.filter((atom) => atoms.includes(atom)).join('|');
+
+/**
+ * Returns `true` when the type is guaranteed to be a non-empty string: either a
+ * non-empty string literal or a value branded as `NonEmptyString`
+ * (`MinLengthString<N>` with `N >= 1`).
+ */
+const isGuaranteedNonEmptyString = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  type: ts.Type,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  checker: ts.TypeChecker,
+): boolean => {
+  if (type.isStringLiteral()) {
+    return type.value !== '';
+  }
+
+  if (type.getProperty(BRAND_MARKER_PROPERTY) === undefined) {
+    return false;
+  }
+
+  const minLengthSymbol = type.getProperty(MIN_LENGTH_BRAND_KEY);
+
+  if (minLengthSymbol === undefined) {
+    return false;
+  }
+
+  // The `MinLength` brand value is `MinLengthTuple<N, 0>`; it has a required
+  // first element (`'0'`) exactly when `N >= 1`, i.e. the string is non-empty.
+  // `MinLengthString<0>` brands with a plain array and has no such element.
+  return (
+    checker.getTypeOfSymbol(minLengthSymbol).getProperty('0') !== undefined
+  );
+};
+
+/**
+ * Returns `true` when the type can possibly be a non-empty string (a general
+ * `string`, a branded string, or a non-empty string literal). The empty string
+ * literal and non-string types cannot.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+const couldBeNonEmptyString = (type: ts.Type): boolean =>
+  type.isStringLiteral() ? type.value !== '' : classifyAtom(type) === 'string';
+
 /**
  * What a guard with `spec` does on an argument of `type`: always the same
  * boolean, the same as a narrower guard, or nothing the rule can say.
@@ -435,13 +599,6 @@ const verdictOf = (
   }
 };
 
-const replacementVerdict = (
-  replacement: string | undefined,
-): Verdict | undefined =>
-  replacement === undefined
-    ? undefined
-    : ({ kind: 'replace', replacement } as const);
-
 /**
  * Whether `verdict`, drawn from one layer's type, also holds for `type`. A
  * constant has to come out the same. A replacement holds where the rule would
@@ -481,121 +638,6 @@ const holdsOn = (
   );
 };
 
-/**
- * Decomposes a type into its union members. Returns `undefined` when any member
- * is opaque (`any` / `unknown` / `never`) or deferred (type parameter, indexed
- * access, …), signalling that the rule should not draw conclusions.
- */
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-const collectUnionParts = (type: ts.Type): readonly ts.Type[] | undefined => {
-  const parts = type.isUnion() ? type.types : ([type] as const);
-
-  for (const part of parts) {
-    if ((part.flags & DEFERRED_OR_OPAQUE_FLAGS) !== 0) {
-      return undefined;
-    }
-  }
-
-  return parts;
-};
-
-/**
- * Whether `isRecord` is guaranteed to accept this (non-union) type.
- *
- * `isRecord` narrows to `UnknownRecord` (`ReadonlyRecord<string, unknown>`), so
- * a string index signature is exactly what it asks for and its value type is
- * `unknown`, which anything satisfies. Arrays and callables are excluded even
- * when they carry one, because `isRecord` rejects them at runtime
- * (`Array.isArray` is true; `typeof fn === 'object'` is false).
- *
- * Deliberately conservative: an object type without an index signature of its
- * own is reported as neither guaranteed-accepted nor guaranteed-rejected, even
- * where TypeScript would accept it through an implicit index signature.
- */
-const isGuaranteedRecord = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  type: ts.Type,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  checker: ts.TypeChecker,
-): boolean =>
-  checker.getIndexInfoOfType(type, ts.IndexKind.String) !== undefined &&
-  !isCallableType(type, checker) &&
-  !checker.isArrayType(type) &&
-  !checker.isTupleType(type);
-
-/**
- * Whether `isRecord` is guaranteed to reject this (non-union) type: every
- * primitive (`null` included), every array or tuple, and every callable fails
- * its `typeof x === 'object' && x !== null && !Array.isArray(x)` check.
- */
-const isGuaranteedNotRecord = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  type: ts.Type,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  checker: ts.TypeChecker,
-): boolean =>
-  classifyAtom(type) !== 'other' ||
-  checker.isArrayType(type) ||
-  checker.isTupleType(type) ||
-  isCallableType(type, checker);
-
-const isCallableType = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  type: ts.Type,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  checker: ts.TypeChecker,
-): boolean =>
-  checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0 ||
-  checker.getSignaturesOfType(type, ts.SignatureKind.Construct).length > 0;
-
-/** Classifies a single (non-union) type into a primitive {@link Atom}. */
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-const classifyAtom = (type: ts.Type): Atom => {
-  const { flags } = type;
-
-  if ((flags & ts.TypeFlags.Undefined) !== 0) {
-    return 'undefined';
-  }
-
-  if ((flags & ts.TypeFlags.Null) !== 0) {
-    return 'null';
-  }
-
-  if ((flags & ts.TypeFlags.BooleanLike) !== 0) {
-    return 'boolean';
-  }
-
-  if ((flags & ts.TypeFlags.NumberLike) !== 0) {
-    return 'number';
-  }
-
-  if ((flags & ts.TypeFlags.StringLike) !== 0) {
-    return 'string';
-  }
-
-  if ((flags & ts.TypeFlags.BigIntLike) !== 0) {
-    return 'bigint';
-  }
-
-  if ((flags & ts.TypeFlags.ESSymbolLike) !== 0) {
-    return 'symbol';
-  }
-
-  // Branded primitives (e.g. `NonEmptyString = string & {...}`) are
-  // intersections; classify them by their underlying primitive constituent.
-  if (type.isIntersection()) {
-    for (const constituent of type.types) {
-      const atom = classifyAtom(constituent);
-
-      if (atom !== 'other') {
-        return atom;
-      }
-    }
-  }
-
-  return 'other';
-};
-
 const ATOM_ORDER: readonly AtomKey[] = [
   'undefined',
   'null',
@@ -606,52 +648,6 @@ const ATOM_ORDER: readonly AtomKey[] = [
   'symbol',
 ] as const;
 
-/** A stable key for a set of atoms, used to look up replacement guards. */
-const joinAtoms = (atoms: readonly AtomKey[]): string =>
-  ATOM_ORDER.filter((atom) => atoms.includes(atom)).join('|');
-
-/**
- * Returns `true` when the type is guaranteed to be a non-empty string: either a
- * non-empty string literal or a value branded as `NonEmptyString`
- * (`MinLengthString<N>` with `N >= 1`).
- */
-const isGuaranteedNonEmptyString = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  type: ts.Type,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  checker: ts.TypeChecker,
-): boolean => {
-  if (type.isStringLiteral()) {
-    return type.value !== '';
-  }
-
-  if (type.getProperty(BRAND_MARKER_PROPERTY) === undefined) {
-    return false;
-  }
-
-  const minLengthSymbol = type.getProperty(MIN_LENGTH_BRAND_KEY);
-
-  if (minLengthSymbol === undefined) {
-    return false;
-  }
-
-  // The `MinLength` brand value is `MinLengthTuple<N, 0>`; it has a required
-  // first element (`'0'`) exactly when `N >= 1`, i.e. the string is non-empty.
-  // `MinLengthString<0>` brands with a plain array and has no such element.
-  return (
-    checker.getTypeOfSymbol(minLengthSymbol).getProperty('0') !== undefined
-  );
-};
-
-/**
- * Returns `true` when the type can possibly be a non-empty string (a general
- * `string`, a branded string, or a non-empty string literal). The empty string
- * literal and non-string types cannot.
- */
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-const couldBeNonEmptyString = (type: ts.Type): boolean =>
-  type.isStringLiteral() ? type.value !== '' : classifyAtom(type) === 'string';
-
 /**
  * Returns `true` when evaluating the expression cannot have observable side
  * effects, so replacing the surrounding call with a literal is safe. Limited to

package/src/rules/no-unnecessary-type-guard.test.mts

@@ -406,13 +406,73 @@ describe('no-unnecessary-type-guard', () => {
           const y = isNonNullish(x);
         `,
         output: dedent`
-          import { isNotNull } from 'ts-data-forge';
-          import { isNonNullish } from 'ts-data-forge';
+          import { isNonNullish, isNotNull } from 'ts-data-forge';
           declare const x: string | null;
           const y = isNotNull(x);
         `,
         errors: [{ messageId: 'replaceTypeGuard' }],
       },
+      {
+        name: 'the message names an aliased replacement guard by its local name',
+        code: dedent`
+          import { isNonNullish, isNotNull as inn } from 'ts-data-forge';
+          declare const x: string | null;
+          const y = isNonNullish(x);
+        `,
+        output: dedent`
+          import { isNonNullish, isNotNull as inn } from 'ts-data-forge';
+          declare const x: string | null;
+          const y = inn(x);
+        `,
+        errors: [
+          {
+            messageId: 'replaceTypeGuard',
+            data: { from: 'isNonNullish', to: 'inn' },
+          },
+        ],
+      },
+      {
+        name: 'several reports bind each replacement guard they write',
+        code: dedent`
+          import { isNonNullish } from 'ts-data-forge';
+          declare const x: string | null;
+          declare const z: string | undefined;
+          const a = isNonNullish(x);
+          const b = isNonNullish(x);
+          const c = isNonNullish(z);
+        `,
+        output: [
+          dedent`
+            import { isNonNullish, isNotNull } from 'ts-data-forge';
+            declare const x: string | null;
+            declare const z: string | undefined;
+            const a = isNotNull(x);
+            const b = isNonNullish(x);
+            const c = isNonNullish(z);
+          `,
+          dedent`
+            import { isNonNullish, isNotNull, isNotUndefined } from 'ts-data-forge';
+            declare const x: string | null;
+            declare const z: string | undefined;
+            const a = isNotNull(x);
+            const b = isNonNullish(x);
+            const c = isNotUndefined(z);
+          `,
+          dedent`
+            import { isNonNullish, isNotNull, isNotUndefined } from 'ts-data-forge';
+            declare const x: string | null;
+            declare const z: string | undefined;
+            const a = isNotNull(x);
+            const b = isNotNull(x);
+            const c = isNotUndefined(z);
+          `,
+        ],
+        errors: [
+          { messageId: 'replaceTypeGuard' },
+          { messageId: 'replaceTypeGuard' },
+          { messageId: 'replaceTypeGuard' },
+        ],
+      },
       {
         name: 'isNullish that only matches undefined -> isUndefined',
         code: dedent`