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

package/src/rules/prefer-canonical-array-slicing.mts

@@ -4,8 +4,9 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type ReadonlyRecord } from 'ts-type-forge';
+import type { ReadonlyRecord } from 'ts-type-forge';
 import * as ts from 'typescript';
+import { skipTypeWrappers, typeWrapperLayers } from './ast-utils.mjs';
 import {
   buildImportFixes,
   getImportedLocalName,
@@ -48,19 +49,24 @@ const normalizeCountedOp = (
         : ({ fn, count } as const);
 
 const asNonNegativeIntegerLiteral = (
-  node: TSESTree.Node,
-): number | undefined =>
-  node.type === AST_NODE_TYPES.Literal &&
-  typeof node.value === 'number' &&
-  Number.isInteger(node.value) &&
-  node.value >= 0
+  wrapped: TSESTree.Node,
+): number | undefined => {
+  const node = skipTypeWrappers(wrapped);
+
+  return node.type === AST_NODE_TYPES.Literal &&
+    typeof node.value === 'number' &&
+    Number.isInteger(node.value) &&
+    node.value >= 0
     ? node.value
     : undefined;
+};
 
 /** Matches `-N` (unary minus of a positive integer literal) and returns `N`. */
 const asNegatedPositiveIntegerLiteral = (
-  node: TSESTree.Node,
+  wrapped: TSESTree.Node,
 ): number | undefined => {
+  const node = skipTypeWrappers(wrapped);
+
   if (
     node.type !== AST_NODE_TYPES.UnaryExpression ||
     node.operator !== '-' ||
@@ -238,6 +244,18 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
     const getTypeOf = (node: TSESTree.Node): ts.Type =>
       checker.getTypeAtLocation(parserServices.esTreeNodeToTSNodeMap.get(node));
 
+    /**
+     * Whether `predicate` holds for the type of every layer of type wrappers
+     * around `node` (see typeWrapperLayers): a cast neither makes a `Set` an
+     * array nor stops an array from being flattened by `concat`, and the fix,
+     * which keeps the wrapper, has to type-check as well.
+     */
+    const holdsThroughWrappers = (
+      node: TSESTree.Node,
+      predicate: (type: ts.Type) => boolean,
+    ): boolean =>
+      typeWrapperLayers(node).every((layer) => predicate(getTypeOf(layer)));
+
     /**
      * `true` only when the type can never be an array in any branch, so
      * `xs.concat(v)` is guaranteed to append `v` as one element rather than
@@ -395,9 +413,14 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
       // eslint-disable-next-line total-functions/no-unsafe-type-assertion
       const rawOperator = body.operator as ComparisonOperator;
 
-      const isIndex = (side: TSESTree.Node): boolean =>
-        side.type === AST_NODE_TYPES.Identifier &&
-        side.name === indexParam.name;
+      const isIndex = (wrapped: TSESTree.Node): boolean => {
+        const side = skipTypeWrappers(wrapped);
+
+        return (
+          side.type === AST_NODE_TYPES.Identifier &&
+          side.name === indexParam.name
+        );
+      };
 
       const [op, other] = isIndex(body.left)
         ? ([rawOperator, body.right] as const)
@@ -644,7 +667,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
             element.type !== AST_NODE_TYPES.SpreadElement &&
             node.arguments.length === 1 &&
             arg.type !== AST_NODE_TYPES.SpreadElement &&
-            isArrayOrTupleType(getTypeOf(arg))
+            holdsThroughWrappers(arg, isArrayOrTupleType)
           ) {
             report(
               node,
@@ -667,7 +690,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
 
         // The receiver must be an array or tuple (not a string / typed array
         // / other object that happens to share the method name).
-        if (!isArrayOrTupleType(getTypeOf(receiver))) {
+        if (!holdsThroughWrappers(receiver, isArrayOrTupleType)) {
           return;
         }
 
@@ -747,7 +770,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
 
             // `xs.concat(item)` appends only when `item` can never be an
             // array (otherwise `concat` would flatten it).
-            if (isDefinitelyNotArrayType(getTypeOf(arg))) {
+            if (holdsThroughWrappers(arg, isDefinitelyNotArrayType)) {
               report(
                 node,
                 { fn: 'toPushed', itemText: toArgText(arg) },
@@ -794,7 +817,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
 
         // Spreading a non-array iterable (`[v, ...someSet]`) is a genuine
         // conversion, not an element addition to an array.
-        if (!isArrayOrTupleType(getTypeOf(spread.argument))) {
+        if (!holdsThroughWrappers(spread.argument, isArrayOrTupleType)) {
           return;
         }
 

package/src/rules/prefer-canonical-array-slicing.test.mts

@@ -586,3 +586,95 @@ describe('prefer-canonical-array-slicing', () => {
     ],
   });
 });
+
+describe('prefer-canonical-array-slicing through type wrappers', () => {
+  tester.run('prefer-canonical-array-slicing', preferCanonicalArraySlicing, {
+    valid: [
+      {
+        name: 'a concat argument cast away from an array may still be flattened',
+        code: dedent`
+          declare const xs: readonly number[];
+          declare const v: number | readonly number[];
+          const ys = xs.concat(v as number);
+        `,
+      },
+      {
+        name: 'a spread Set cast to an array is still a conversion',
+        code: dedent`
+          declare const s: ReadonlySet<number>;
+          const ys = [...(s as unknown as readonly number[]), 1];
+        `,
+      },
+      {
+        name: 'a receiver cast to an array is still not one',
+        code: dedent`
+          declare const s: string;
+          const ys = (s as unknown as readonly string[]).slice(1);
+        `,
+      },
+      {
+        name: 'a concat argument cast to an array is still not one',
+        code: dedent`
+          declare const s: ReadonlySet<number>;
+          const ys = [1].concat(s as unknown as readonly number[]);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'a count wrapped in `as` or `satisfies`',
+        code: dedent`
+          declare const xs: readonly number[];
+          const a = xs.slice(1 as number);
+          const b = xs.slice(0 satisfies number, -1 as number);
+          const c = xs.toSpliced(2 satisfies number);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          declare const xs: readonly number[];
+          const a = Arr.tail(xs);
+          const b = Arr.butLast(xs);
+          const c = Arr.take(xs, 2);
+        `,
+        errors: [
+          { messageId: 'preferCanonicalArraySlicing' },
+          { messageId: 'preferCanonicalArraySlicing' },
+          { messageId: 'preferCanonicalArraySlicing' },
+        ],
+      },
+      {
+        name: 'a filter comparison on a wrapped index',
+        code: dedent`
+          declare const xs: readonly number[];
+          const ys = xs.filter((_, i) => (i satisfies number) >= 1);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          declare const xs: readonly number[];
+          const ys = Arr.tail(xs);
+        `,
+        errors: [{ messageId: 'preferCanonicalArraySlicing' }],
+      },
+      {
+        name: 'a wrapped receiver and item keep their wrappers',
+        code: dedent`
+          declare const xs: readonly number[];
+          declare const v: number | undefined;
+          const ys = (xs satisfies readonly number[]).slice(1);
+          const zs = [...xs!, v!];
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          declare const xs: readonly number[];
+          declare const v: number | undefined;
+          const ys = Arr.tail(xs satisfies readonly number[]);
+          const zs = Arr.toPushed(xs!, v!);
+        `,
+        errors: [
+          { messageId: 'preferCanonicalArraySlicing' },
+          { messageId: 'preferCanonicalArraySlicing' },
+        ],
+      },
+    ],
+  });
+});

package/src/rules/prefer-canonical-length-cast.mts

@@ -1,8 +1,10 @@
 import {
   AST_NODE_TYPES,
+  ASTUtils,
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
+import { skipTypeWrappers } from './ast-utils.mjs';
 import { getImportedLocalName, getTsDataForgeImport } from './import-utils.mjs';
 
 type Options = readonly [];
@@ -185,7 +187,7 @@ export const preferCanonicalLengthCast: TSESLint.RuleModule<
               node.callee,
               `${arrLocalName}.${rewrite.replacement}`,
             ),
-            ...dropBoundsFix(fixer, node, rewrite),
+            ...dropBoundsFix(fixer, sourceCode, node, rewrite),
           ],
         });
       },
@@ -263,11 +265,16 @@ const matchesBounds = (
 
 /**
  * Removes the length arguments the rewrite drops. Each removal runs from the
- * dropped argument up to the start of the next one, so the comma, whitespace
- * and any comments in between go with it; the ranges never overlap.
+ * first token after the delimiter before the dropped argument (the call's `(`
+ * or the previous comma) up to the first token after the comma that follows
+ * it. Parentheses the source put around the dropped argument, the comma,
+ * whitespace and any comments in between go with it; parentheses around the
+ * next argument stay. The ranges never overlap.
  */
 const dropBoundsFix = (
   fixer: TSESLint.RuleFixer,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
   // 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,
@@ -283,23 +290,46 @@ const dropBoundsFix = (
     // "not of this type".
     const dropped = node.arguments[index];
 
-    const next = node.arguments[index + 1];
+    const previous = node.arguments[index - 1];
+
+    if (dropped === undefined || rewrite.keep.includes(index)) {
+      return [];
+    }
+
+    const delimiterBefore =
+      previous === undefined
+        ? sourceCode.getTokenAfter(node.callee, ASTUtils.isOpeningParenToken)
+        : sourceCode.getTokenAfter(previous, ASTUtils.isCommaToken);
+
+    const start =
+      delimiterBefore === null
+        ? null
+        : sourceCode.getTokenAfter(delimiterBefore);
 
-    return dropped === undefined ||
-      next === undefined ||
-      rewrite.keep.includes(index)
+    const commaAfter = sourceCode.getTokenAfter(dropped, ASTUtils.isCommaToken);
+
+    const end =
+      commaAfter === null ? null : sourceCode.getTokenAfter(commaAfter);
+
+    return start === null || end === null
       ? []
-      : [fixer.removeRange([dropped.range[0], next.range[0]])];
+      : [fixer.removeRange([start.range[0], end.range[0]])];
   });
 
-/** A non-negative integer literal's value, or `undefined` for anything else. */
+/**
+ * A non-negative integer literal's value, or `undefined` for anything else.
+ * Read through type wrappers: `1 as const` is still the bound `1`.
+ */
 const getLengthLiteral = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: TSESTree.Node,
-): number | undefined =>
-  node.type === AST_NODE_TYPES.Literal &&
-  typeof node.value === 'number' &&
-  Number.isSafeInteger(node.value) &&
-  node.value >= 0
+  wrapped: TSESTree.Node,
+): number | undefined => {
+  const node = skipTypeWrappers(wrapped);
+
+  return node.type === AST_NODE_TYPES.Literal &&
+    typeof node.value === 'number' &&
+    Number.isSafeInteger(node.value) &&
+    node.value >= 0
     ? node.value
     : undefined;
+};

package/src/rules/prefer-canonical-length-cast.test.mts

@@ -303,3 +303,114 @@ describe('prefer-canonical-length-cast', () => {
     ],
   });
 });
+
+describe('prefer-canonical-length-cast through type wrappers', () => {
+  tester.run('prefer-canonical-length-cast', preferCanonicalLengthCast, {
+    valid: [
+      {
+        name: 'a wrapped bound other than the degenerate one',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asMinLengthArray(2 as const, xs);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'a bound wrapped in `as const`',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asMinLengthArray(1 as const, xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asNonEmptyArray(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalCast' }],
+      },
+      {
+        name: 'bounds wrapped in `satisfies`, the kept one keeping its wrapper',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asBoundedLengthTuple(3 satisfies number, 3 as const, xs!);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asFixedLengthTuple(3 satisfies number, xs!);
+        `,
+        errors: [{ messageId: 'useCanonicalCast' }],
+      },
+    ],
+  });
+});
+
+describe('prefer-canonical-length-cast with parenthesized operands', () => {
+  tester.run('prefer-canonical-length-cast', preferCanonicalLengthCast, {
+    valid: [],
+    invalid: [
+      {
+        name: 'a parenthesized array after the dropped bound',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asMinLengthArray(1, (xs));
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asNonEmptyArray((xs));
+        `,
+        errors: [{ messageId: 'useCanonicalCast' }],
+      },
+      {
+        name: 'a parenthesized dropped bound',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asMinLengthArray((1), xs);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asNonEmptyArray(xs);
+        `,
+        errors: [{ messageId: 'useCanonicalCast' }],
+      },
+      {
+        name: 'a parenthesized second bound of a bounded cast',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asBoundedLengthArray(2, ((2)), xs);
+          const zs = Arr.asBoundedLengthArray((0), (0), (xs));
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ys = Arr.asFixedLengthArray(2, xs);
+          const zs = Arr.asEmptyArray((xs));
+        `,
+        errors: [
+          { messageId: 'useCanonicalCast' },
+          { messageId: 'useCanonicalCast' },
+        ],
+      },
+    ],
+  });
+});

package/src/rules/prefer-canonical-length-guard.mts

@@ -3,7 +3,8 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { type MutableRecord, type ReadonlyRecord } from 'ts-type-forge';
+import type { MutableRecord, ReadonlyRecord } from 'ts-type-forge';
+import { skipTypeWrappers, toArgumentText } from './ast-utils.mjs';
 import { getImportedLocalName, getTsDataForgeImport } from './import-utils.mjs';
 import { preferArrIsBoundedLengthArray } from './prefer-arr-is-bounded-length-array.mjs';
 import { preferArrIsFixedLengthArray } from './prefer-arr-is-fixed-length-array.mjs';
@@ -153,7 +154,7 @@ export const preferCanonicalLengthGuard: TSESLint.RuleModule<
             return;
           }
 
-          const arrayText = sourceCode.getText(array);
+          const arrayText = toArgumentText(array, sourceCode);
 
           context.report({
             node,
@@ -234,7 +235,8 @@ const getGuardName = (
 
 /**
  * Whether the call is `guard(...bounds, array)` with every bound written as the
- * exact numeric literal the rewrite requires.
+ * exact numeric literal the rewrite requires, under any type wrapper
+ * (`0 as const` is still the bound 0).
  *
  * The arity check also excludes the curried form (`guard(...bounds)`): the
  * degenerate guards take only the array, so there is nothing to rewrite it to.
@@ -250,10 +252,14 @@ const matchesBounds = (
     return false;
   }
 
-  return args.every(
-    (arg, index) =>
+  return args.every((arg, index) => {
+    const bound = skipTypeWrappers(arg);
+
+    return (
       arg.type !== AST_NODE_TYPES.SpreadElement &&
       (index === bounds.length ||
-        (arg.type === AST_NODE_TYPES.Literal && arg.value === bounds[index])),
-  );
+        (bound.type === AST_NODE_TYPES.Literal &&
+          bound.value === bounds[index]))
+    );
+  });
 };

package/src/rules/prefer-canonical-length-guard.test.mts

@@ -305,3 +305,102 @@ describe('prefer-canonical-length-guard', () => {
     ],
   });
 });
+
+describe('prefer-canonical-length-guard through type wrappers', () => {
+  tester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [
+      {
+        name: 'a wrapped bound other than the degenerate one',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const ok = Arr.isFixedLengthArray(1 as const, xs);
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'a bound wrapped in `as const` or `satisfies`',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const a = Arr.isFixedLengthArray(0 as const, xs);
+          const b = Arr.isBoundedLengthTuple(0 satisfies number, 0, xs!);
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          const a = Arr.isEmpty(xs);
+          const b = Arr.isEmptyTuple(xs!);
+        `,
+        errors: [
+          { messageId: 'useCanonicalGuard' },
+          { messageId: 'useCanonicalGuard' },
+        ],
+      },
+    ],
+  });
+
+  typedTester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [
+      {
+        name: 'a computed index named `length` is not the length',
+        code: dedent`
+          declare const xs: readonly number[];
+          declare const length: number;
+          const ok = xs[length] > 0;
+        `,
+      },
+    ],
+    invalid: [
+      {
+        name: 'a folded-in comparison on a wrapped length',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+          declare const xs: readonly number[];
+          const a = (xs.length satisfies number) > 0;
+          const b = xs.length >= 1 && (xs as readonly number[]).length <= 3;
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+          declare const xs: readonly number[];
+          const a = Arr.isNonEmpty(xs);
+          const b = Arr.isBoundedLengthArray(1, 3, xs);
+        `,
+        errors: [
+          { messageId: 'useIsNonEmpty' },
+          { messageId: 'useIsBoundedLengthArray' },
+        ],
+      },
+    ],
+  });
+});
+
+describe('prefer-canonical-length-guard with parenthesized operands', () => {
+  tester.run('prefer-canonical-length-guard', preferCanonicalLengthGuard, {
+    valid: [],
+    invalid: [
+      {
+        name: 'a sequence array keeps its parentheses',
+        code: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          declare const log: () => void;
+          const ok = Arr.isFixedLengthArray(0, (log(), xs));
+        `,
+        output: dedent`
+          import { Arr } from 'ts-data-forge';
+
+          declare const xs: readonly number[];
+          declare const log: () => void;
+          const ok = Arr.isEmpty((log(), xs));
+        `,
+        errors: [{ messageId: 'useCanonicalGuard' }],
+      },
+    ],
+  });
+});

package/src/rules/prefer-comparison-over-nullish-guard.mts

@@ -3,7 +3,7 @@ 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 { buildCalleeResolver, getTsDataForgeImport } from './import-utils.mjs';
 
 type Options = readonly [];
@@ -29,7 +29,11 @@ const COMPARISON_GUARDS: ReadonlyRecord<string, ComparisonSpec> = {
 
 /**
  * Argument expression kinds whose precedence is lower than equality, so they
- * must be parenthesized when placed on the left of `===` / `!==`.
+ * must be parenthesized when placed on the left of `===` / `!==`. A node's text
+ * never includes the parentheses the source wrote around it, so this is decided
+ * on the kind alone. `as` / `satisfies` and a nested equality would parse as
+ * intended, but are parenthesized so that the type or the grouping is not read
+ * as part of the comparison.
  */
 const ARG_NEEDS_PARENS: ReadonlySet<string> = new Set([
   AST_NODE_TYPES.LogicalExpression,
@@ -38,11 +42,33 @@ const ARG_NEEDS_PARENS: ReadonlySet<string> = new Set([
   AST_NODE_TYPES.SequenceExpression,
   AST_NODE_TYPES.ArrowFunctionExpression,
   AST_NODE_TYPES.YieldExpression,
+  AST_NODE_TYPES.TSAsExpression,
+  AST_NODE_TYPES.TSSatisfiesExpression,
 ]);
 
+/** Binary operators that bind no tighter than `===` / `!==`. */
+const LOOSE_BINARY_OPERATORS: ReadonlySet<string> = new Set([
+  '|',
+  '^',
+  '&',
+  '==',
+  '!=',
+  '===',
+  '!==',
+]);
+
+const argumentNeedsParens = (
+  argument: DeepReadonly<TSESTree.Expression>,
+): boolean =>
+  ARG_NEEDS_PARENS.has(argument.type) ||
+  (argument.type === AST_NODE_TYPES.BinaryExpression &&
+    LOOSE_BINARY_OPERATORS.has(argument.operator));
+
 /**
  * Returns `true` when the comparison must be wrapped in parentheses to preserve
- * the original grouping given the call expression's parent context.
+ * the original grouping given the call expression's parent context. A type
+ * wrapper around the call is one such context: `x === null satisfies boolean`
+ * would apply the wrapper to `null`.
  */
 const needsWrappingInParent = (
   node: DeepReadonly<TSESTree.CallExpression>,
@@ -56,6 +82,9 @@ const needsWrappingInParent = (
     case AST_NODE_TYPES.AwaitExpression:
     case AST_NODE_TYPES.BinaryExpression:
     case AST_NODE_TYPES.TSNonNullExpression:
+    case AST_NODE_TYPES.TSAsExpression:
+    case AST_NODE_TYPES.TSSatisfiesExpression:
+    case AST_NODE_TYPES.TSTypeAssertion:
       return true;
 
     case AST_NODE_TYPES.MemberExpression:
@@ -124,9 +153,7 @@ export const preferComparisonOverNullishGuard: TSESLint.RuleModule<
 
         const argRaw = sourceCode.getText(argument);
 
-        const argText = ARG_NEEDS_PARENS.has(argument.type)
-          ? `(${argRaw})`
-          : argRaw;
+        const argText = argumentNeedsParens(argument) ? `(${argRaw})` : argRaw;
 
         const comparison = `${argText} ${spec.op} ${spec.literal}`;