eslint-plugin-ts-data-forge 0.8.5 → 0.9.0

package/src/rules/prefer-arr-uniq.mts

@@ -1,16 +1,21 @@
 import {
   AST_NODE_TYPES,
+  ASTUtils,
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import { Arr } from 'ts-data-forge';
-import * as ts from 'typescript';
-import { skipTypeWrappers, typeWrapperLayers } from './ast-utils.mjs';
 import {
-  buildImportFixes,
+  buildNamedImportFix,
+  getArgumentText,
+  getImportDeclarations,
   getImportedLocalName,
-  getTsDataForgeImport,
-} from './import-utils.mjs';
+  skipTypeWrappers,
+  typeWrapperLayers,
+} from 'eslint-rule-forge';
+import { Arr } from 'ts-data-forge';
+import * as ts from 'typescript';
+import { primitiveTypeFlags, TS_DATA_FORGE_MODULE } from './constants.mjs';
+import { needsMutableResult } from './mutable-result.mjs';
 
 type Options = readonly [];
 
@@ -47,7 +52,10 @@ export const preferArrUniq: TSESLint.RuleModule<MessageIds, Options> = {
 
     const program = sourceCode.ast;
 
-    const tsDataForgeImport = getTsDataForgeImport(program);
+    const tsDataForgeImports = getImportDeclarations(
+      program,
+      TS_DATA_FORGE_MODULE,
+    );
 
     const services = sourceCode.parserServices;
 
@@ -150,7 +158,7 @@ export const preferArrUniq: TSESLint.RuleModule<MessageIds, Options> = {
         check(node, element.argument);
       },
       'Program:exit': () => {
-        const arrLocalName = getImportedLocalName(tsDataForgeImport, 'Arr');
+        const arrLocalName = getImportedLocalName(tsDataForgeImports, 'Arr');
 
         const arrName = arrLocalName ?? 'Arr';
 
@@ -162,16 +170,18 @@ export const preferArrUniq: TSESLint.RuleModule<MessageIds, Options> = {
         for (const match of mut_matches) {
           const arrayText = sourceCode.getText(match.arrayExpression);
 
-          const argumentText =
-            match.arrayExpression.type === AST_NODE_TYPES.SequenceExpression
-              ? `(${arrayText})`
-              : arrayText;
+          const argumentText = getArgumentText(
+            sourceCode,
+            match.arrayExpression,
+          );
 
           const buildFix =
             (withImport: boolean): TSESLint.ReportFixFunction =>
             (fixer) => [
               ...(withImport && arrLocalName === undefined
-                ? buildImportFixes(fixer, program, tsDataForgeImport, ['Arr'])
+                ? buildNamedImportFix(fixer, program, TS_DATA_FORGE_MODULE, [
+                    'Arr',
+                  ])
                 : []),
               fixer.replaceText(match.node, `${arrName}.uniq(${argumentText})`),
             ];
@@ -206,19 +216,6 @@ export const preferArrUniq: TSESLint.RuleModule<MessageIds, Options> = {
   defaultOptions: [],
 } as const;
 
-/** Methods that `ReadonlyArray` lacks and that mutate the receiver. */
-const mutatingMethods: ReadonlySet<string> = new Set([
-  'copyWithin',
-  'fill',
-  'pop',
-  'push',
-  'reverse',
-  'shift',
-  'sort',
-  'splice',
-  'unshift',
-]);
-
 /**
  * Returns `xs` for `new Set(xs)`, and `undefined` for anything else — including
  * `new Set()`, `new Set<T>(xs)` (whose element type may be wider than `xs`'s)
@@ -254,23 +251,10 @@ const isGlobal = (
   node: TSESTree.Node,
   name: string,
 ): boolean => {
-  const variable = findVariable(sourceCode.getScope(node), name);
+  const variable = ASTUtils.findVariable(sourceCode.getScope(node), name);
 
   // Globals from the TypeScript lib are implicit variables with no definition.
-  return variable === undefined || variable.defs.length === 0;
-};
-
-const findVariable = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  scope: TSESLint.Scope.Scope,
-  name: string,
-): TSESLint.Scope.Variable | undefined => {
-  const variable = scope.set.get(name);
-
-  return (
-    variable ??
-    (scope.upper === null ? undefined : findVariable(scope.upper, name))
-  );
+  return variable === null || variable.defs.length === 0;
 };
 
 /**
@@ -321,15 +305,6 @@ const isPrimitiveType = (
     : (resolved.flags & primitiveTypeFlags) !== 0;
 };
 
-const primitiveTypeFlags =
-  ts.TypeFlags.StringLike |
-  ts.TypeFlags.NumberLike |
-  ts.TypeFlags.BigIntLike |
-  ts.TypeFlags.BooleanLike |
-  ts.TypeFlags.ESSymbolLike |
-  ts.TypeFlags.Null |
-  ts.TypeFlags.Undefined;
-
 const resolveConstraint = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   checker: ts.TypeChecker,
@@ -339,187 +314,3 @@ const resolveConstraint = (
   (type.flags & ts.TypeFlags.TypeParameter) !== 0
     ? (checker.getBaseConstraintOfType(type) ?? type)
     : type;
-
-/**
- * Whether the code around `node` visibly relies on the result being a mutable
- * array, so that swapping in the readonly array `Arr.uniq` returns would not
- * compile. Looks at `node` itself and, when it initializes a variable without a
- * type annotation, at every read of that variable.
- */
-const needsMutableResult = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  sourceCode: TSESLint.SourceCode,
-  // 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 outer = outermostTypePreservingWrapper(node);
-
-  if (isUsedAsMutable(checker, getTsNode, outer)) {
-    return true;
-  }
-
-  const parent = outer.parent;
-
-  if (
-    parent?.type !== AST_NODE_TYPES.VariableDeclarator ||
-    parent.init !== outer ||
-    parent.id.type !== AST_NODE_TYPES.Identifier ||
-    parent.id.typeAnnotation !== undefined
-  ) {
-    return false;
-  }
-
-  const [variable] = sourceCode.getDeclaredVariables(parent);
-
-  return (
-    variable?.references.some(
-      (reference) =>
-        reference.init !== true &&
-        isUsedAsMutable(
-          checker,
-          getTsNode,
-          outermostTypePreservingWrapper(reference.identifier),
-        ),
-    ) ?? false
-  );
-};
-
-/**
- * `node`, or the outermost `!` / `satisfies` around it. Neither changes the
- * type the value is used at, so `Array.from(new Set(xs))!.push(4)` and
- * `ys!.push(4)` still need a mutable array. An `as` does change it, and a
- * readonly array may be cast to a mutable one, so the walk stops there.
- */
-const outermostTypePreservingWrapper = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: TSESTree.Node,
-): TSESTree.Node => {
-  const { parent } = node;
-
-  return parent !== undefined &&
-    (parent.type === AST_NODE_TYPES.TSNonNullExpression ||
-      parent.type === AST_NODE_TYPES.TSSatisfiesExpression) &&
-    parent.expression === node
-    ? outermostTypePreservingWrapper(parent)
-    : 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
- * argument — `Arr.toSorted(Array.from(set), cmp)` has `Ar` inferred as
- * `string[]` — so it would read as "a mutable array is required" for any
- * generic parameter. The declared type (`Ar extends readonly unknown[]`) is
- * what the rewritten argument actually has to satisfy.
- */
-const getDeclaredParameterType = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  checker: ts.TypeChecker,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  argument: ts.Expression,
-): ts.Type | undefined => {
-  const call = argument.parent;
-
-  if (!ts.isCallExpression(call) && !ts.isNewExpression(call)) {
-    return undefined;
-  }
-
-  const index = call.arguments?.indexOf(argument) ?? -1;
-
-  if (index === -1) {
-    return undefined;
-  }
-
-  const declaration = checker.getResolvedSignature(call)?.getDeclaration();
-
-  const parameter = declaration?.parameters[index];
-
-  // A rest parameter's declared type is the array of arguments, not the type of
-  // one; the contextual type is the better answer there.
-  return parameter === undefined || parameter.dotDotDotToken !== undefined
-    ? undefined
-    : checker.getTypeAtLocation(parameter);
-};
-
-/**
- * Whether a readonly array cannot be assigned to `type`: it is a mutable array,
- * or a union of mutable arrays and primitives. (A tuple accepted no array to
- * begin with, so it does not matter here.)
- */
-const isMutableArrayOnly = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  checker: ts.TypeChecker,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  type: ts.Type,
-): boolean => {
-  const members = type.isUnion() ? type.types : ([type] as const);
-
-  return (
-    members.every(
-      (t) =>
-        // `null`, `undefined` and other primitives accept no array at all.
-        (t.flags & primitiveTypeFlags) !== 0 ||
-        (checker.isArrayType(t) && t.getSymbol()?.getName() === 'Array'),
-    ) && members.some((t) => (t.flags & primitiveTypeFlags) === 0)
-  );
-};

package/src/rules/prefer-as-int.mts

@@ -3,14 +3,15 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import type { DeepReadonly } from 'ts-type-forge';
-import { toArgumentText } from './ast-utils.mjs';
-import { brandedNumberTypeNameToFunctionName } from './branded-number-types.mjs';
 import {
-  buildImportFixes,
+  buildNamedImportFix,
+  getArgumentText,
+  getImportDeclarations,
   getNamedImports,
-  getTsDataForgeImport,
-} from './import-utils.mjs';
+} from 'eslint-rule-forge';
+import type { DeepReadonly } from 'ts-type-forge';
+import { brandedNumberTypeNameToFunctionName } from './branded-number-types.mjs';
+import { TS_DATA_FORGE_MODULE } from './constants.mjs';
 
 type Options = readonly [];
 
@@ -36,7 +37,10 @@ export const preferAsInt: TSESLint.RuleModule<MessageIds, Options> = {
 
     const program = sourceCode.ast;
 
-    const tsDataForgeImport = getTsDataForgeImport(program);
+    const tsDataForgeImports = getImportDeclarations(
+      program,
+      TS_DATA_FORGE_MODULE,
+    );
 
     const mut_nodesToFix: {
       node: TSESTree.TSAsExpression | TSESTree.TSTypeAssertion;
@@ -66,7 +70,7 @@ export const preferAsInt: TSESLint.RuleModule<MessageIds, Options> = {
       TSAsExpression: collect,
       TSTypeAssertion: collect,
       'Program:exit': () => {
-        const namedImports = getNamedImports(tsDataForgeImport);
+        const namedImports = getNamedImports(tsDataForgeImports);
 
         // Group nodes by function name to handle imports efficiently
         const functionNameToNodes = Map.groupBy(
@@ -87,14 +91,17 @@ export const preferAsInt: TSESLint.RuleModule<MessageIds, Options> = {
                 functionName,
               },
               fix: (fixer) => {
-                const replacement = `${functionName}(${toArgumentText(node.expression, sourceCode)})`;
+                const replacement = `${functionName}(${getArgumentText(sourceCode, node.expression)})`;
 
                 // Add import only for the first node of this function and only if not already imported
                 const importFixes =
                   index === 0 && !hasImport
-                    ? buildImportFixes(fixer, program, tsDataForgeImport, [
-                        functionName,
-                      ])
+                    ? buildNamedImportFix(
+                        fixer,
+                        program,
+                        TS_DATA_FORGE_MODULE,
+                        [functionName],
+                      )
                     : [];
 
                 return [...importFixes, fixer.replaceText(node, replacement)];

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

@@ -4,14 +4,16 @@ import {
   type TSESLint,
   type TSESTree,
 } from '@typescript-eslint/utils';
-import type { ReadonlyRecord } from 'ts-type-forge';
-import * as ts from 'typescript';
-import { skipTypeWrappers, typeWrapperLayers } from './ast-utils.mjs';
 import {
-  buildImportFixes,
+  buildNamedImportFix,
+  getImportDeclarations,
   getImportedLocalName,
-  getTsDataForgeImport,
-} from './import-utils.mjs';
+  skipTypeWrappers,
+  typeWrapperLayers,
+} from 'eslint-rule-forge';
+import type { ReadonlyRecord } from 'ts-type-forge';
+import * as ts from 'typescript';
+import { TS_DATA_FORGE_MODULE } from './constants.mjs';
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types */
 
@@ -82,23 +84,32 @@ const asNegatedPositiveIntegerLiteral = (
 
 /**
  * Whether re-reading the expression is free of side effects (a plain variable
- * or a non-computed property chain). Required for patterns that reference the
- * receiver twice, such as `xs.filter((_, i) => i < xs.length - 1)`.
+ * or a non-computed property chain, type wrappers aside). Required for
+ * patterns that reference the receiver twice, such as
+ * `xs.filter((_, i) => i < xs.length - 1)`.
  */
-const isSimpleReference = (node: TSESTree.Node): boolean =>
-  node.type === AST_NODE_TYPES.Identifier ||
-  node.type === AST_NODE_TYPES.ThisExpression ||
-  (node.type === AST_NODE_TYPES.MemberExpression &&
-    !node.computed &&
-    node.property.type === AST_NODE_TYPES.Identifier &&
-    isSimpleReference(node.object));
-
-const rootIdentifierName = (node: TSESTree.Node): string | undefined =>
-  node.type === AST_NODE_TYPES.Identifier
+const isSimpleReference = (wrapped: TSESTree.Node): boolean => {
+  const node = skipTypeWrappers(wrapped);
+
+  return (
+    node.type === AST_NODE_TYPES.Identifier ||
+    node.type === AST_NODE_TYPES.ThisExpression ||
+    (node.type === AST_NODE_TYPES.MemberExpression &&
+      !node.computed &&
+      node.property.type === AST_NODE_TYPES.Identifier &&
+      isSimpleReference(node.object))
+  );
+};
+
+const rootIdentifierName = (wrapped: TSESTree.Node): string | undefined => {
+  const node = skipTypeWrappers(wrapped);
+
+  return node.type === AST_NODE_TYPES.Identifier
     ? node.name
     : node.type === AST_NODE_TYPES.MemberExpression
       ? rootIdentifierName(node.object)
       : undefined;
+};
 
 type ComparisonOperator = '!==' | '<' | '<=' | '>' | '>=';
 
@@ -188,7 +199,10 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
 
     const program = sourceCode.ast;
 
-    const tsDataForgeImport = getTsDataForgeImport(program);
+    const tsDataForgeImports = getImportDeclarations(
+      program,
+      TS_DATA_FORGE_MODULE,
+    );
 
     const parserServices = ESLintUtils.getParserServices(context);
 
@@ -199,11 +213,14 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
      * (possibly aliased), a namespace import member, or the canonical `Arr`
      * (added by the import fix when nothing is imported yet).
      */
-    const arrLocalName = getImportedLocalName(tsDataForgeImport, 'Arr');
+    const arrLocalName = getImportedLocalName(tsDataForgeImports, 'Arr');
 
-    const namespaceLocalName = tsDataForgeImport?.specifiers.find(
-      (specifier) => specifier.type === AST_NODE_TYPES.ImportNamespaceSpecifier,
-    )?.local.name;
+    const namespaceLocalName = tsDataForgeImports
+      .flatMap((declaration) => declaration.specifiers)
+      .find(
+        (specifier) =>
+          specifier.type === AST_NODE_TYPES.ImportNamespaceSpecifier,
+      )?.local.name;
 
     const arrRef =
       arrLocalName ??
@@ -330,26 +347,41 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
       });
     };
 
-    /** Matches `<xsText>.length` (non-computed). */
+    /**
+     * Matches `<receiver>.length` (non-computed), type wrappers aside on the
+     * access, on its object and on the receiver:
+     * `(xs as readonly T[]).length` reads the length of `xs`.
+     */
     const isReceiverLengthAccess = (
-      node: TSESTree.Node,
-      receiverText: string,
-    ): boolean =>
-      node.type === AST_NODE_TYPES.MemberExpression &&
-      !node.computed &&
-      node.property.type === AST_NODE_TYPES.Identifier &&
-      node.property.name === 'length' &&
-      sourceCode.getText(node.object) === receiverText;
+      wrapped: TSESTree.Node,
+      receiver: TSESTree.Expression,
+    ): boolean => {
+      const node = skipTypeWrappers(wrapped);
+
+      return (
+        node.type === AST_NODE_TYPES.MemberExpression &&
+        !node.computed &&
+        node.property.type === AST_NODE_TYPES.Identifier &&
+        node.property.name === 'length' &&
+        sourceCode.getText(skipTypeWrappers(node.object)) ===
+          sourceCode.getText(skipTypeWrappers(receiver))
+      );
+    };
 
-    /** Matches `<xsText>.length - M` (M ≥ 1) and returns `M`. */
+    /**
+     * Matches `<receiver>.length - M` (M ≥ 1), under any type wrapper, and
+     * returns `M`.
+     */
     const matchLengthMinus = (
-      node: TSESTree.Node,
-      receiverText: string,
+      wrapped: TSESTree.Node,
+      receiver: TSESTree.Expression,
     ): number | undefined => {
+      const node = skipTypeWrappers(wrapped);
+
       if (
         node.type !== AST_NODE_TYPES.BinaryExpression ||
         node.operator !== '-' ||
-        !isReceiverLengthAccess(node.left, receiverText)
+        !isReceiverLengthAccess(node.left, receiver)
       ) {
         return undefined;
       }
@@ -367,7 +399,6 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
     const classifyFilterCallback = (
       callback: TSESTree.CallExpressionArgument,
       receiver: TSESTree.Expression,
-      receiverText: string,
     ): CopyOp | undefined => {
       if (
         callback.type !== AST_NODE_TYPES.ArrowFunctionExpression ||
@@ -401,7 +432,8 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
         return undefined;
       }
 
-      const body = callback.body;
+      // `(i >= 1) satisfies boolean` is still the comparison.
+      const body = skipTypeWrappers(callback.body);
 
       if (
         body.type !== AST_NODE_TYPES.BinaryExpression ||
@@ -448,7 +480,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
         return undefined;
       }
 
-      const m = matchLengthMinus(other, receiverText);
+      const m = matchLengthMinus(other, receiver);
 
       return m === undefined ? undefined : classifyLengthComparison(op, m);
     };
@@ -504,7 +536,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
           return undefined;
         }
 
-        const m = matchLengthMinus(end, sourceCode.getText(receiver));
+        const m = matchLengthMinus(end, receiver);
 
         return m === undefined ? undefined : normalizeCountedOp('skipLast', m);
       }
@@ -515,7 +547,6 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
     const classifyToSplicedArgs = (
       args: readonly TSESTree.CallExpressionArgument[],
       receiver: TSESTree.Expression,
-      receiverText: string,
     ): CopyOp | undefined => {
       if (args.length === 1) {
         const [start] = args;
@@ -564,7 +595,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
           return undefined;
         }
 
-        const m = matchLengthMinus(deleteCount, receiverText);
+        const m = matchLengthMinus(deleteCount, receiver);
 
         return m === undefined ? undefined : normalizeCountedOp('takeLast', m);
       }
@@ -590,7 +621,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
         // `xs.toSpliced(xs.length, 0, item)` appends → toPushed.
         if (
           isSimpleReference(receiver) &&
-          isReceiverLengthAccess(start, receiverText)
+          isReceiverLengthAccess(start, receiver)
         ) {
           return { fn: 'toPushed', itemText: toArgText(item) };
         }
@@ -694,8 +725,6 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
           return;
         }
 
-        const receiverText = sourceCode.getText(receiver);
-
         switch (methodName) {
           case 'slice': {
             const op = classifySliceArgs(node.arguments, receiver);
@@ -708,11 +737,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
           }
 
           case 'toSpliced': {
-            const op = classifyToSplicedArgs(
-              node.arguments,
-              receiver,
-              receiverText,
-            );
+            const op = classifyToSplicedArgs(node.arguments, receiver);
 
             if (op !== undefined) {
               report(node, op, toArgText(receiver));
@@ -728,7 +753,7 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
               return;
             }
 
-            const op = classifyFilterCallback(callback, receiver, receiverText);
+            const op = classifyFilterCallback(callback, receiver);
 
             if (op !== undefined) {
               report(node, op, toArgText(receiver));
@@ -837,7 +862,9 @@ export const preferCanonicalArraySlicing: TSESLint.RuleModule<
             fix: (fixer) => {
               const importFixes =
                 index === 0 && needsArrImport
-                  ? buildImportFixes(fixer, program, tsDataForgeImport, ['Arr'])
+                  ? buildNamedImportFix(fixer, program, TS_DATA_FORGE_MODULE, [
+                      'Arr',
+                    ])
                   : [];
 
               return [