eslint-plugin-ts-data-forge 0.8.2 → 0.8.4

package/src/rules/ast-utils.mts

@@ -3,18 +3,125 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type DeepReadonly } from 'ts-type-forge';
+import type { DeepReadonly } from 'ts-type-forge';
+
+/**
+ * `node` with every `as`, `satisfies`, `!` and `<T>` around it taken off: the
+ * expression whose value it is. A wrapper changes no value, so a rule judges
+ * syntax on this — `xs.length > (0 as number)` compares with the literal `0`
+ * — and writes its fix from the original node so the wrapper is kept. A type
+ * is another matter: see {@link typeWrapperLayers}. See
+ * `docs/writing-lint-rules.md` at the repository root. A copy of
+ * `eslint-config-typed`'s `type-wrapper-utils.mts`, since this package is
+ * published on its own.
+ */
+export const skipTypeWrappers = <N extends TSESTree.Node>(
+  node: N,
+): N | TSESTree.Expression =>
+  isTypeWrapper(node) ? skipTypeWrappers(node.expression) : node;
+
+/**
+ * `node` and every expression inside the type wrappers around it, outermost
+ * first: `x as A as B` gives `x as A as B`, `x as A` and `x`.
+ *
+ * A conclusion a rule draws from a type — that a guard always holds, that a
+ * value is an array, that `?? 0` is dead — has to hold for the type of every
+ * layer. An assertion therefore only ever makes a rule more cautious: one
+ * that widens (`x as string | null`) is the author saying the value may be
+ * `null`, and is respected; one that narrows (`x!`, `v as string` on an
+ * `unknown`) is a claim the checker cannot verify, and the value's own type
+ * still decides.
+ */
+export const typeWrapperLayers = <N extends TSESTree.Node>(
+  node: N,
+): readonly (N | TSESTree.Expression)[] =>
+  isTypeWrapper(node)
+    ? ([node, ...typeWrapperLayers(node.expression)] as const)
+    : ([node] as const);
+
+export const isTypeWrapper = (
+  node: DeepReadonly<TSESTree.Node>,
+): node is TypeWrapper => TYPE_WRAPPERS.has(node.type);
+
+export type TypeWrapper =
+  | TSESTree.TSAsExpression
+  | TSESTree.TSNonNullExpression
+  | TSESTree.TSSatisfiesExpression
+  | TSESTree.TSTypeAssertion;
+
+const TYPE_WRAPPERS: ReadonlySet<AST_NODE_TYPES> = new Set([
+  AST_NODE_TYPES.TSAsExpression,
+  AST_NODE_TYPES.TSNonNullExpression,
+  AST_NODE_TYPES.TSSatisfiesExpression,
+  AST_NODE_TYPES.TSTypeAssertion,
+]);
 
 const isIntegerLiteral = (node: DeepReadonly<TSESTree.Expression>): boolean =>
   node.type === AST_NODE_TYPES.Literal &&
   typeof node.value === 'number' &&
   Number.isInteger(node.value);
 
+/**
+ * The source text of `node` for an argument position. A node's text never
+ * includes the parentheses the source wrote around it, so a comma (sequence)
+ * expression gets them back rather than spilling into the next argument.
+ */
+export const toArgumentText = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Node,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+): string => {
+  const text = sourceCode.getText(node);
+
+  return node.type === AST_NODE_TYPES.SequenceExpression ? `(${text})` : text;
+};
+
+/**
+ * Whether `node` is an array or a tuple at every layer of type wrappers (see
+ * {@link typeWrapperLayers}): a cast does not make a string an array, and the
+ * fix, which keeps the wrapper, has to type-check too. `false` without type
+ * information.
+ */
+export const isArrayOrTupleExpression = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  services: TSESLint.SourceCode['parserServices'],
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Expression,
+): boolean => {
+  const checker = services?.program?.getTypeChecker();
+
+  if (checker === undefined) {
+    return false;
+  }
+
+  return typeWrapperLayers(node).every((expression) => {
+    const tsNode = services?.esTreeNodeToTSNodeMap?.get(expression);
+
+    if (tsNode === undefined) {
+      return false;
+    }
+
+    const type = checker.getTypeAtLocation(tsNode);
+
+    return checker.isArrayType(type) || checker.isTupleType(type);
+  });
+};
+
+/**
+ * Whether `node`, under any type wrapper, is an integer literal or a `const`
+ * initialized with one.
+ */
 export const isIntegerLiteralOrConstant = (
   node: DeepReadonly<TSESTree.Expression>,
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   sourceCode: TSESLint.SourceCode,
 ): boolean => {
+  // `(3 as number)`, `3 satisfies number` are still the bound 3.
+  if (isTypeWrapper(node)) {
+    return isIntegerLiteralOrConstant(node.expression, sourceCode);
+  }
+
   // Direct integer literal (e.g., 3)
   if (isIntegerLiteral(node)) {
     return true;
@@ -53,12 +160,40 @@ export const isIntegerLiteralOrConstant = (
   );
 };
 
-export const isLengthAccess = (
-  node: DeepReadonly<TSESTree.Expression>,
-): node is TSESTree.MemberExpression =>
-  node.type === AST_NODE_TYPES.MemberExpression &&
-  node.property.type === AST_NODE_TYPES.Identifier &&
-  node.property.name === 'length';
+/**
+ * `node` as a `<array>.length` read, looked for under any type wrapper
+ * (`(xs.length satisfies number)`, `xs.length!`), or `undefined`. The property
+ * must be written `.length`: `xs[length]` reads whatever index the variable
+ * `length` holds.
+ */
+export const asLengthAccess = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Expression,
+): TSESTree.MemberExpression | undefined => {
+  const inner = skipTypeWrappers(node);
+
+  return inner.type === AST_NODE_TYPES.MemberExpression &&
+    !inner.computed &&
+    inner.property.type === AST_NODE_TYPES.Identifier &&
+    inner.property.name === 'length'
+    ? inner
+    : undefined;
+};
+
+/**
+ * Whether two array expressions are written the same way, type wrappers aside:
+ * `xs.length >= 1 && (xs as readonly T[]).length <= 3` bounds one array.
+ */
+export const isSameArrayText = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  a: TSESTree.Expression,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  b: TSESTree.Expression,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+): boolean =>
+  sourceCode.getText(skipTypeWrappers(a)) ===
+  sourceCode.getText(skipTypeWrappers(b));
 
 type LengthComparison = Readonly<{
   array: TSESTree.Expression;
@@ -70,7 +205,9 @@ type LengthComparison = Readonly<{
  * Parses a `<array>.length <op> <bound>` comparison (in either operand order)
  * into its array expression, integer-literal/`const` `bound`, and whether it is
  * a lower (`min`) or upper (`max`) length bound. Returns `undefined` for
- * anything else.
+ * anything else. The length and the bound are read through type wrappers; the
+ * `bound` returned is the literal or constant underneath, since a wrapper such
+ * as `as number` would only widen the length a guard narrows to.
  *
  * - `xs.length >= n` / `n <= xs.length` → `min`
  * - `xs.length <= n` / `n >= xs.length` → `max`
@@ -90,13 +227,15 @@ export const parseLengthComparison = (
 
   const { left, right, operator } = node;
 
-  const lengthOnLeft = isLengthAccess(left);
+  const leftLength = asLengthAccess(left);
+
+  const lengthOnLeft = leftLength !== undefined;
 
-  const lengthSide = lengthOnLeft ? left : right;
+  const lengthSide = leftLength ?? asLengthAccess(right);
 
   const boundSide = lengthOnLeft ? right : left;
 
-  if (!isLengthAccess(lengthSide)) {
+  if (lengthSide === undefined) {
     return undefined;
   }
 
@@ -110,7 +249,11 @@ export const parseLengthComparison = (
     ? 'min'
     : 'max';
 
-  return { array: lengthSide.object, bound: boundSide, kind };
+  return {
+    array: lengthSide.object,
+    bound: skipTypeWrappers(boundSide),
+    kind,
+  };
 };
 
 /**
@@ -151,7 +294,7 @@ export const isPartOfBoundedLengthCheck = (
 
   return (
     self.kind !== other.kind &&
-    sourceCode.getText(self.array) === sourceCode.getText(other.array)
+    isSameArrayText(self.array, other.array, sourceCode)
   );
 };
 

package/src/rules/import-utils.mts

@@ -3,7 +3,8 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type DeepReadonly } from 'ts-type-forge';
+import type { DeepReadonly } from 'ts-type-forge';
+import { isTypeWrapper } from './ast-utils.mjs';
 import { TS_DATA_FORGE_MODULE } from './constants.mjs';
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
@@ -100,7 +101,16 @@ export const buildCalleeResolver = (
     }),
   );
 
-  return (callee) => {
+  // `(isNull as (u: unknown) => boolean)(x)` and `(tf as typeof tf).isNull(x)`
+  // still call `isNull`: both the callee and a namespace object are read
+  // through type wrappers.
+  const resolve = (
+    callee: DeepReadonly<TSESTree.Expression>,
+  ): ResolvedCallee | undefined => {
+    if (isTypeWrapper(callee)) {
+      return resolve(callee.expression);
+    }
+
     if (callee.type === AST_NODE_TYPES.Identifier) {
       const canonicalName = localToCanonical.get(callee.name);
 
@@ -115,25 +125,35 @@ export const buildCalleeResolver = (
     }
 
     if (
-      namespaceName !== undefined &&
-      callee.type === AST_NODE_TYPES.MemberExpression &&
-      !callee.computed &&
-      callee.object.type === AST_NODE_TYPES.Identifier &&
-      callee.object.name === namespaceName &&
-      callee.property.type === AST_NODE_TYPES.Identifier
+      namespaceName === undefined ||
+      callee.type !== AST_NODE_TYPES.MemberExpression ||
+      callee.computed ||
+      callee.property.type !== AST_NODE_TYPES.Identifier
     ) {
-      return {
-        canonicalName: callee.property.name,
-        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-        propertyNode: callee.property as TSESTree.Node,
-        isNamespace: true,
-      };
+      return undefined;
     }
 
-    return undefined;
+    const object = skipReadonlyTypeWrappers(callee.object);
+
+    return object.type === AST_NODE_TYPES.Identifier &&
+      object.name === namespaceName
+      ? {
+          canonicalName: callee.property.name,
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          propertyNode: callee.property as TSESTree.Node,
+          isNamespace: true,
+        }
+      : undefined;
   };
+
+  return resolve;
 };
 
+const skipReadonlyTypeWrappers = (
+  node: DeepReadonly<TSESTree.Expression>,
+): DeepReadonly<TSESTree.Expression> =>
+  isTypeWrapper(node) ? skipReadonlyTypeWrappers(node.expression) : node;
+
 export const buildImportFixes = (
   fixer: TSESLint.RuleFixer,
   program: TSESTree.Program,

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

@@ -1,4 +1,4 @@
-import { type TSESLint, type TSESTree } from '@typescript-eslint/utils';
+import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
 import { Arr } from 'ts-data-forge';
 import { TS_DATA_FORGE_MODULE } from './constants.mjs';
 

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,
@@ -282,132 +283,41 @@ export const noUnnecessaryTypeGuard: TSESLint.RuleModule<MessageIds, Options> =
             return;
           }
 
-          const argTsNode = parserServices.esTreeNodeToTSNodeMap.get(argument);
-
-          const argType = checker.getTypeAtLocation(argTsNode);
-
-          const parts = collectUnionParts(argType);
+          // 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),
+            ),
+          );
 
-          if (parts === undefined) {
-            return; // opaque / generic → bail conservatively
+          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;
           }
 
-          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 (verdict.kind === 'constant') {
+            reportConstant(node, canonicalName, verdict.value, argument);
+          } else {
+            reportReplace(
+              node,
+              canonicalName,
+              verdict.replacement,
+              isNamespace,
+              propertyNode,
+            );
           }
         },
       };
@@ -415,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
@@ -607,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;
   }