eslint-plugin-ts-data-forge 0.8.1 → 0.8.3

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

@@ -4,8 +4,9 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type DeepReadonly, type ReadonlyRecord } from 'ts-type-forge';
+import type { DeepReadonly, ReadonlyRecord } from 'ts-type-forge';
 import * as ts from 'typescript';
+import { typeWrapperLayers } from './ast-utils.mjs';
 import {
   buildCalleeResolver,
   buildImportFixes,
@@ -156,7 +157,9 @@ export const noUnnecessaryTypeGuard: TSESLint.RuleModule<MessageIds, Options> =
       const strictNullChecks =
         compilerOptions.strictNullChecks ?? compilerOptions.strict ?? false;
 
-      if (!strictNullChecks) return {};
+      if (!strictNullChecks) {
+        return {};
+      }
 
       const checker = parserServices.program.getTypeChecker();
 
@@ -249,7 +252,9 @@ export const noUnnecessaryTypeGuard: TSESLint.RuleModule<MessageIds, Options> =
 
       return {
         CallExpression: (node) => {
-          if (node.arguments.length !== 1) return;
+          if (node.arguments.length !== 1) {
+            return;
+          }
 
           const argument = node.arguments[0];
 
@@ -262,140 +267,57 @@ export const noUnnecessaryTypeGuard: TSESLint.RuleModule<MessageIds, Options> =
 
           const resolved = resolveGuard(node.callee);
 
-          if (resolved === undefined) return;
+          if (resolved === undefined) {
+            return;
+          }
 
           const { canonicalName, propertyNode, isNamespace } = resolved;
 
-          if (ignored.has(canonicalName)) return;
+          if (ignored.has(canonicalName)) {
+            return;
+          }
 
           const spec = GUARD_SPECS[canonicalName];
 
-          if (spec === undefined) return;
-
-          const argTsNode = parserServices.esTreeNodeToTSNodeMap.get(argument);
-
-          const argType = checker.getTypeAtLocation(argTsNode);
-
-          const parts = collectUnionParts(argType);
-
-          if (parts === undefined) return; // opaque / generic → bail conservatively
-
-          const inputAtoms = new Set(parts.map(classifyAtom));
-
-          const hasMemberOutsideTarget = (
-            atoms: readonly AtomKey[],
-          ): boolean => {
-            const targetSet = new Set<Atom>(atoms);
-
-            return parts.some((p) => !targetSet.has(classifyAtom(p)));
-          };
-
-          switch (spec.kind) {
-            case 'excludeFrom': {
-              const removable = spec.atoms.filter((a) => inputAtoms.has(a));
-
-              if (removable.length === 0) {
-                // Nothing to exclude → the guard always holds.
-                reportConstant(node, canonicalName, true, argument);
-              } else if (!hasMemberOutsideTarget(spec.atoms)) {
-                // Every member is excluded → the guard never holds.
-                reportConstant(node, canonicalName, false, argument);
-              } else if (removable.length < spec.atoms.length) {
-                const replacement = spec.replacements?.[joinAtoms(removable)];
-
-                if (replacement !== undefined) {
-                  reportReplace(
-                    node,
-                    canonicalName,
-                    replacement,
-                    isNamespace,
-                    propertyNode,
-                  );
-                }
-              }
-
-              break;
-            }
-
-            case 'narrowTo': {
-              const present = spec.atoms.filter((a) => inputAtoms.has(a));
-
-              if (present.length === 0) {
-                // No member is in the target set → the guard never holds.
-                reportConstant(node, canonicalName, false, argument);
-              } else if (!hasMemberOutsideTarget(spec.atoms)) {
-                // Input ⊆ target → the guard always holds and narrows nothing.
-                reportConstant(node, canonicalName, true, argument);
-              } else if (present.length < spec.atoms.length) {
-                const replacement = spec.replacements?.[joinAtoms(present)];
-
-                if (replacement !== undefined) {
-                  reportReplace(
-                    node,
-                    canonicalName,
-                    replacement,
-                    isNamespace,
-                    propertyNode,
-                  );
-                }
-              }
-
-              break;
-            }
-
-            case 'record': {
-              if (parts.every((p) => isGuaranteedRecord(p, checker))) {
-                // Every member already satisfies `UnknownRecord`.
-                reportConstant(node, canonicalName, true, argument);
-              } else if (
-                parts.every((p) => isGuaranteedNotRecord(p, checker))
-              ) {
-                // No member can ever be a non-null, non-array object.
-                reportConstant(node, canonicalName, false, argument);
-              }
-
-              break;
-            }
-
-            case 'nonEmptyString': {
-              const hasNullish =
-                inputAtoms.has('undefined') || inputAtoms.has('null');
-
-              const nonNullishParts = parts.filter((p) => {
-                const atom = classifyAtom(p);
-
-                return atom !== 'undefined' && atom !== 'null';
-              });
-
-              if (!nonNullishParts.some(couldBeNonEmptyString)) {
-                // No member can be a non-empty string → the guard never holds.
-                reportConstant(node, canonicalName, false, argument);
-
-                break;
-              }
-
-              if (
-                nonNullishParts.some(
-                  (p) => !isGuaranteedNonEmptyString(p, checker),
-                )
-              ) {
-                break; // still does real string/empty work
-              }
-
-              if (hasNullish) {
-                reportReplace(
-                  node,
-                  canonicalName,
-                  'isNonNullish',
-                  isNamespace,
-                  propertyNode,
-                );
-              } else {
-                reportConstant(node, canonicalName, true, argument);
-              }
-
-              break;
-            }
+          if (spec === undefined) {
+            return;
+          }
+
+          // A conclusion drawn from the argument's type has to hold at every
+          // layer of type wrappers around it (see typeWrapperLayers):
+          // `isNull(x as string | null)` is the author saying `x` may be
+          // `null`, and `isNullish(x as string | undefined)` still sees the
+          // `null` that `x` may hold.
+          const layerTypes = typeWrapperLayers(argument).map((layer) =>
+            checker.getTypeAtLocation(
+              parserServices.esTreeNodeToTSNodeMap.get(layer),
+            ),
+          );
+
+          const verdict = layerTypes
+            .map((type) => verdictOf(spec, type, checker))
+            .find(
+              (candidate): candidate is Verdict =>
+                candidate !== undefined &&
+                layerTypes.every((type) =>
+                  holdsOn(candidate, spec, type, checker),
+                ),
+            );
+
+          if (verdict === undefined) {
+            return;
+          }
+
+          if (verdict.kind === 'constant') {
+            reportConstant(node, canonicalName, verdict.value, argument);
+          } else {
+            reportReplace(
+              node,
+              canonicalName,
+              verdict.replacement,
+              isNamespace,
+              propertyNode,
+            );
           }
         },
       };
@@ -403,6 +325,158 @@ export const noUnnecessaryTypeGuard: TSESLint.RuleModule<MessageIds, Options> =
     defaultOptions: [{}],
   } as const;
 
+/** What the rule concludes about a guard call from one type of its argument. */
+type Verdict = DeepReadonly<
+  | { kind: 'constant'; value: boolean }
+  | { kind: 'replace'; replacement: 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.
+ */
+const verdictOf = (
+  spec: GuardSpec,
+  // 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,
+): Verdict | undefined => {
+  const parts = collectUnionParts(type);
+
+  if (parts === undefined) {
+    return undefined; // opaque / generic → bail conservatively
+  }
+
+  const inputAtoms = new Set(parts.map(classifyAtom));
+
+  const hasMemberOutsideTarget = (atoms: readonly AtomKey[]): boolean => {
+    const targetSet = new Set<Atom>(atoms);
+
+    return parts.some((p) => !targetSet.has(classifyAtom(p)));
+  };
+
+  switch (spec.kind) {
+    case 'excludeFrom': {
+      const removable = spec.atoms.filter((a) => inputAtoms.has(a));
+
+      if (removable.length === 0) {
+        // Nothing to exclude → the guard always holds.
+        return { kind: 'constant', value: true } as const;
+      }
+
+      if (!hasMemberOutsideTarget(spec.atoms)) {
+        // Every member is excluded → the guard never holds.
+        return { kind: 'constant', value: false } as const;
+      }
+
+      return replacementVerdict(
+        removable.length < spec.atoms.length
+          ? spec.replacements?.[joinAtoms(removable)]
+          : undefined,
+      );
+    }
+
+    case 'narrowTo': {
+      const present = spec.atoms.filter((a) => inputAtoms.has(a));
+
+      if (present.length === 0) {
+        // No member is in the target set → the guard never holds.
+        return { kind: 'constant', value: false } as const;
+      }
+
+      if (!hasMemberOutsideTarget(spec.atoms)) {
+        // Input ⊆ target → the guard always holds and narrows nothing.
+        return { kind: 'constant', value: true } as const;
+      }
+
+      return replacementVerdict(
+        present.length < spec.atoms.length
+          ? spec.replacements?.[joinAtoms(present)]
+          : undefined,
+      );
+    }
+
+    case 'record':
+      // Every member already satisfies `UnknownRecord`, or none can ever be
+      // a non-null, non-array object.
+      return parts.every((p) => isGuaranteedRecord(p, checker))
+        ? ({ kind: 'constant', value: true } as const)
+        : parts.every((p) => isGuaranteedNotRecord(p, checker))
+          ? ({ kind: 'constant', value: false } as const)
+          : undefined;
+
+    case 'nonEmptyString': {
+      const nonNullishParts = parts.filter((p) => {
+        const atom = classifyAtom(p);
+
+        return atom !== 'undefined' && atom !== 'null';
+      });
+
+      if (!nonNullishParts.some(couldBeNonEmptyString)) {
+        // No member can be a non-empty string → the guard never holds.
+        return { kind: 'constant', value: false } as const;
+      }
+
+      if (
+        nonNullishParts.some((p) => !isGuaranteedNonEmptyString(p, checker))
+      ) {
+        return undefined; // still does real string/empty work
+      }
+
+      return inputAtoms.has('undefined') || inputAtoms.has('null')
+        ? ({ kind: 'replace', replacement: 'isNonNullish' } as const)
+        : ({ kind: 'constant', value: true } as const);
+    }
+  }
+};
+
+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
+ * suggest the same one, or where the guard and its replacement are the same
+ * constant: under `x!` on a `string | null`, `isNonNullish` and `isNotNull`
+ * are both always `true` on `string`.
+ */
+const holdsOn = (
+  verdict: Verdict,
+  spec: GuardSpec,
+  // 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 => {
+  const onType = verdictOf(spec, type, checker);
+
+  if (verdict.kind === 'constant') {
+    return onType?.kind === 'constant' && onType.value === verdict.value;
+  }
+
+  if (onType?.kind === 'replace') {
+    return onType.replacement === verdict.replacement;
+  }
+
+  const replacementSpec = GUARD_SPECS[verdict.replacement];
+
+  const replacementOnType =
+    replacementSpec === undefined
+      ? undefined
+      : verdictOf(replacementSpec, type, checker);
+
+  return (
+    onType?.kind === 'constant' &&
+    replacementOnType?.kind === 'constant' &&
+    replacementOnType.value === onType.value
+  );
+};
+
 /**
  * Decomposes a type into its union members. Returns `undefined` when any member
  * is opaque (`any` / `unknown` / `never`) or deferred (type parameter, indexed
@@ -413,7 +487,9 @@ 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;
+    if ((part.flags & DEFERRED_OR_OPAQUE_FLAGS) !== 0) {
+      return undefined;
+    }
   }
 
   return parts;
@@ -473,19 +549,33 @@ const isCallableType = (
 const classifyAtom = (type: ts.Type): Atom => {
   const { flags } = type;
 
-  if ((flags & ts.TypeFlags.Undefined) !== 0) return 'undefined';
+  if ((flags & ts.TypeFlags.Undefined) !== 0) {
+    return 'undefined';
+  }
 
-  if ((flags & ts.TypeFlags.Null) !== 0) return 'null';
+  if ((flags & ts.TypeFlags.Null) !== 0) {
+    return 'null';
+  }
 
-  if ((flags & ts.TypeFlags.BooleanLike) !== 0) return 'boolean';
+  if ((flags & ts.TypeFlags.BooleanLike) !== 0) {
+    return 'boolean';
+  }
 
-  if ((flags & ts.TypeFlags.NumberLike) !== 0) return 'number';
+  if ((flags & ts.TypeFlags.NumberLike) !== 0) {
+    return 'number';
+  }
 
-  if ((flags & ts.TypeFlags.StringLike) !== 0) return 'string';
+  if ((flags & ts.TypeFlags.StringLike) !== 0) {
+    return 'string';
+  }
 
-  if ((flags & ts.TypeFlags.BigIntLike) !== 0) return 'bigint';
+  if ((flags & ts.TypeFlags.BigIntLike) !== 0) {
+    return 'bigint';
+  }
 
-  if ((flags & ts.TypeFlags.ESSymbolLike) !== 0) return 'symbol';
+  if ((flags & ts.TypeFlags.ESSymbolLike) !== 0) {
+    return 'symbol';
+  }
 
   // Branded primitives (e.g. `NonEmptyString = string & {...}`) are
   // intersections; classify them by their underlying primitive constituent.
@@ -493,7 +583,9 @@ const classifyAtom = (type: ts.Type): Atom => {
     for (const constituent of type.types) {
       const atom = classifyAtom(constituent);
 
-      if (atom !== 'other') return atom;
+      if (atom !== 'other') {
+        return atom;
+      }
     }
   }
 
@@ -525,13 +617,19 @@ const isGuaranteedNonEmptyString = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   checker: ts.TypeChecker,
 ): boolean => {
-  if (type.isStringLiteral()) return type.value !== '';
+  if (type.isStringLiteral()) {
+    return type.value !== '';
+  }
 
-  if (type.getProperty(BRAND_MARKER_PROPERTY) === undefined) return false;
+  if (type.getProperty(BRAND_MARKER_PROPERTY) === undefined) {
+    return false;
+  }
 
   const minLengthSymbol = type.getProperty(MIN_LENGTH_BRAND_KEY);
 
-  if (minLengthSymbol === undefined) return false;
+  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.
@@ -547,11 +645,8 @@ const isGuaranteedNonEmptyString = (
  * literal and non-string types cannot.
  */
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-const couldBeNonEmptyString = (type: ts.Type): boolean => {
-  if (type.isStringLiteral()) return type.value !== '';
-
-  return classifyAtom(type) === 'string';
-};
+const couldBeNonEmptyString = (type: ts.Type): boolean =>
+  type.isStringLiteral() ? type.value !== '' : classifyAtom(type) === 'string';
 
 /**
  * Returns `true` when evaluating the expression cannot have observable side
@@ -574,6 +669,12 @@ const isSideEffectFreeArg = (node: DeepReadonly<TSESTree.Node>): boolean => {
         (!node.computed || isSideEffectFreeArg(node.property))
       );
 
+    case AST_NODE_TYPES.TSAsExpression:
+    case AST_NODE_TYPES.TSNonNullExpression:
+    case AST_NODE_TYPES.TSSatisfiesExpression:
+    case AST_NODE_TYPES.TSTypeAssertion:
+      return isSideEffectFreeArg(node.expression);
+
     default:
       return false;
   }

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

@@ -460,3 +460,103 @@ describe('no-unnecessary-type-guard', () => {
     ],
   });
 });
+
+describe('no-unnecessary-type-guard through type wrappers', () => {
+  tester.run('no-unnecessary-type-guard', noUnnecessaryTypeGuard, {
+    valid: [
+      {
+        name: 'isNullish on a value cast away from null',
+        code: dedent`
+          import { isNullish } from 'ts-data-forge';
+          declare const x: string | null | undefined;
+          const y = isNullish(x as string | undefined);
+        `,
+      },
+      {
+        name: 'isNonNullish on a value cast away from null',
+        code: dedent`
+          import { isNonNullish } from 'ts-data-forge';
+          declare const x: string | null | undefined;
+          const y = isNonNullish(x as string | undefined);
+        `,
+      },
+      {
+        name: 'isNonEmptyString on a string cast to NonEmptyString',
+        code: dedent`
+          import { type NonEmptyString } from 'ts-type-forge';
+          import { isNonEmptyString } from 'ts-data-forge';
+          declare const x: string | null | undefined;
+          const y = isNonEmptyString(x as NonEmptyString | null | undefined);
+        `,
+      },
+      {
+        name: 'isNull on a value whose `!` does not remove the null',
+        code: dedent`
+          import { isNull } from 'ts-data-forge';
+          declare const x: string | null;
+          const y = isNull(x!);
+        `,
+      },
+      {
+        name: 'isNull on a value widened to include null: the `as` is the author saying it may be null',
+        code: dedent`
+          import { isNull } from 'ts-data-forge';
+          declare const x: string;
+          const y = isNull(x as string | null);
+        `,
+      },
+      {
+        name: 'isNullish on a value widened to include null is not narrowed to isUndefined',
+        code: dedent`
+          import { isNullish } from 'ts-data-forge';
+          declare const x: string | undefined;
+          const y = isNullish(x as string | null | undefined);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'isNonNullish on a value whose `!` does not remove the null',
+        code: dedent`
+          import { isNonNullish, isNotNull } from 'ts-data-forge';
+          declare const x: string | null;
+          const y = isNonNullish(x!);
+        `,
+        output: dedent`
+          import { isNonNullish, isNotNull } from 'ts-data-forge';
+          declare const x: string | null;
+          const y = isNotNull(x!);
+        `,
+        errors: [{ messageId: 'replaceTypeGuard' }],
+      },
+      {
+        name: 'isNull on a value widened to exclude null still, at every layer',
+        code: dedent`
+          import { isNull } from 'ts-data-forge';
+          declare const x: string;
+          const y = isNull(x as string | undefined);
+        `,
+        output: dedent`
+          import { isNull } from 'ts-data-forge';
+          declare const x: string;
+          const y = false;
+        `,
+        errors: [{ messageId: 'alwaysFalse' }],
+      },
+      {
+        name: 'isNullish replaced on the value under `satisfies`, keeping the wrapper',
+        code: dedent`
+          import { isNullish, isUndefined } from 'ts-data-forge';
+          declare const x: string | undefined;
+          const y = isNullish(x satisfies string | null | undefined);
+        `,
+        output: dedent`
+          import { isNullish, isUndefined } from 'ts-data-forge';
+          declare const x: string | undefined;
+          const y = isUndefined(x satisfies string | null | undefined);
+        `,
+        errors: [{ messageId: 'replaceTypeGuard' }],
+      },
+    ],
+  });
+});

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

@@ -3,7 +3,7 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type DeepReadonly } from 'ts-type-forge';
+import { skipTypeWrappers } from './ast-utils.mjs';
 import {
   buildImportFixes,
   getNamedImports,
@@ -40,7 +40,9 @@ export const preferArrIsArray: TSESLint.RuleModule<MessageIds, Options> = {
 
     return {
       CallExpression: (node) => {
-        if (!isArrayIsArrayCall(node)) return;
+        if (!isArrayIsArrayCall(node)) {
+          return;
+        }
 
         mut_nodesToFix.push(node);
       },
@@ -59,17 +61,19 @@ export const preferArrIsArray: TSESLint.RuleModule<MessageIds, Options> = {
             fix: (fixer) => {
               const callee = node.callee;
 
-              if (callee.type !== AST_NODE_TYPES.MemberExpression) return [];
-
-              const replacement = `Arr.isArray${sourceCode.getText(node).slice(sourceCode.getText(callee).length)}`;
+              if (callee.type !== AST_NODE_TYPES.MemberExpression) {
+                return [];
+              }
 
+              // Only the callee is replaced: parentheses the source put around
+              // it are outside its range, and stay balanced.
               // Add import only for the first node and only if not already imported
               const importFixes =
                 index === 0 && !hasArrImport
                   ? buildImportFixes(fixer, program, tsDataForgeImport, ['Arr'])
                   : [];
 
-              return [...importFixes, fixer.replaceText(node, replacement)];
+              return [...importFixes, fixer.replaceText(callee, 'Arr.isArray')];
             },
           });
         }
@@ -80,19 +84,34 @@ export const preferArrIsArray: TSESLint.RuleModule<MessageIds, Options> = {
 } as const;
 
 const isArrayIsArrayCall = (
-  node: DeepReadonly<TSESTree.CallExpression>,
+  // AST nodes hold mutable child arrays, so they are not deeply readonly.
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.CallExpression,
 ): boolean => {
-  if (node.callee.type !== AST_NODE_TYPES.MemberExpression) return false;
+  if (node.callee.type !== AST_NODE_TYPES.MemberExpression) {
+    return false;
+  }
+
+  const { property } = node.callee;
 
-  const { object, property } = node.callee;
+  // `(Array as ArrayConstructor).isArray` is still `Array.isArray`.
+  const object = skipTypeWrappers(node.callee.object);
 
-  if (object.type !== AST_NODE_TYPES.Identifier) return false;
+  if (object.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
 
-  if (object.name !== 'Array') return false;
+  if (object.name !== 'Array') {
+    return false;
+  }
 
-  if (property.type !== AST_NODE_TYPES.Identifier) return false;
+  if (property.type !== AST_NODE_TYPES.Identifier) {
+    return false;
+  }
 
-  if (property.name !== 'isArray') return false;
+  if (property.name !== 'isArray') {
+    return false;
+  }
 
   return true;
 };