eslint-plugin-ts-data-forge 0.8.6 → 0.10.0

package/src/rule-types.mts

@@ -72,6 +72,21 @@ namespace PreferCanonicalLengthCast {
   export type RuleEntry = Linter.StringSeverity;
 }
 
+/**
+ * @description Replace the filter-and-map idiom `xs.flatMap((x) => (cond ? [f(x)] : []))` with a loop in `Arr.generate` from ts-data-forge.
+ *
+ *  ```md
+ *  | key        | value      |
+ *  | :--------- | :--------- |
+ *  | type       | suggestion |
+ *  | deprecated | false      |
+ *  | fixable    | code       |
+ *  ```
+ */
+namespace PreferArrGenerate {
+  export type RuleEntry = Linter.StringSeverity;
+}
+
 /**
  * @description Replace `Array.isArray` with `Arr.isArray` from ts-data-forge.
  *
@@ -148,7 +163,7 @@ namespace PreferAsInt {
 }
 
 /**
- * @description Replace `typeof u === "object" && u !== null` with `isNonNullObject(u)` from ts-data-forge.
+ * @description Replace `typeof u === "object" && u !== null`, in either order and anywhere in an `&&` chain, with `isNonNullObject(u)` from ts-data-forge.
  *
  *  ```md
  *  | key        | value      |
@@ -310,10 +325,26 @@ namespace PreferObjOverEntriesRoundTrip {
   export type RuleEntry = Linter.StringSeverity;
 }
 
+/**
+ * @description Replace `pipe(x).map(mapNullable(fn))` with `pipe(x).mapNullable(fn)`.
+ *
+ *  ```md
+ *  | key        | value      |
+ *  | :--------- | :--------- |
+ *  | type       | suggestion |
+ *  | deprecated | false      |
+ *  | fixable    | code       |
+ *  ```
+ */
+namespace PreferPipeMapNullable {
+  export type RuleEntry = Linter.StringSeverity;
+}
+
 export type EslintTsDataForgeRules = Readonly<{
   'ts-data-forge/prefer-canonical-array-slicing': PreferCanonicalArraySlicing.RuleEntry;
   'ts-data-forge/prefer-canonical-length-guard': PreferCanonicalLengthGuard.RuleEntry;
   'ts-data-forge/prefer-canonical-length-cast': PreferCanonicalLengthCast.RuleEntry;
+  'ts-data-forge/prefer-arr-generate': PreferArrGenerate.RuleEntry;
   'ts-data-forge/prefer-arr-is-array': PreferArrIsArray.RuleEntry;
   'ts-data-forge/prefer-arr-scan': PreferArrScan.RuleEntry;
   'ts-data-forge/prefer-arr-sum': PreferArrSum.RuleEntry;
@@ -328,6 +359,7 @@ export type EslintTsDataForgeRules = Readonly<{
   'ts-data-forge/no-unnecessary-type-guard': NoUnnecessaryTypeGuard.RuleEntry;
   'ts-data-forge/prefer-comparison-over-nullish-guard': PreferComparisonOverNullishGuard.RuleEntry;
   'ts-data-forge/prefer-obj-over-entries-round-trip': PreferObjOverEntriesRoundTrip.RuleEntry;
+  'ts-data-forge/prefer-pipe-map-nullable': PreferPipeMapNullable.RuleEntry;
 }>;
 
 export type EslintTsDataForgeRulesOption = Readonly<{

package/src/rules/ast-utils.mts

@@ -10,6 +10,7 @@ import {
   typeWrapperLayers,
 } from 'eslint-rule-forge';
 import type { DeepReadonly } from 'ts-type-forge';
+import type * as ts from 'typescript';
 
 const isIntegerLiteral = (node: DeepReadonly<TSESTree.Expression>): boolean =>
   node.type === AST_NODE_TYPES.Literal &&
@@ -144,7 +145,8 @@ 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. The length and the bound are read through type wrappers; the
+ * anything else. The comparison, 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.
  *
@@ -153,10 +155,12 @@ type LengthComparison = Readonly<{
  */
 export const parseLengthComparison = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: TSESTree.Expression,
+  wrapped: TSESTree.Expression,
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   sourceCode: TSESLint.SourceCode,
 ): LengthComparison | undefined => {
+  const node = skipTypeWrappers(wrapped);
+
   if (
     node.type !== AST_NODE_TYPES.BinaryExpression ||
     (node.operator !== '>=' && node.operator !== '<=')
@@ -201,6 +205,8 @@ export const parseLengthComparison = (
  * together form the `Arr.isBoundedLengthArray` pattern handled by
  * `prefer-arr-is-bounded-length-array`. The single-bound rules skip such
  * operands so the bounded rule rewrites the whole `&&` instead of the parts.
+ * A comparison wrapped as a whole (`(xs.length >= 1 satisfies boolean) && …`)
+ * is still the operand.
  */
 export const isPartOfBoundedLengthCheck = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -208,10 +214,12 @@ export const isPartOfBoundedLengthCheck = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   sourceCode: TSESLint.SourceCode,
 ): boolean => {
-  const { parent } = node;
+  const operand = outermostTypeWrapper(node);
+
+  const { parent } = operand;
 
   if (
-    parent.type !== AST_NODE_TYPES.LogicalExpression ||
+    parent?.type !== AST_NODE_TYPES.LogicalExpression ||
     parent.operator !== '&&'
   ) {
     return false;
@@ -223,7 +231,7 @@ export const isPartOfBoundedLengthCheck = (
     return false;
   }
 
-  const sibling = parent.left === node ? parent.right : parent.left;
+  const sibling = parent.left === operand ? parent.right : parent.left;
 
   const other = parseLengthComparison(sibling, sourceCode);
 
@@ -237,6 +245,15 @@ export const isPartOfBoundedLengthCheck = (
   );
 };
 
+/** The outermost of the type wrappers around `node`, or `node` itself. */
+const outermostTypeWrapper = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Node,
+): TSESTree.Node =>
+  node.parent !== undefined && isTypeWrapper(node.parent)
+    ? outermostTypeWrapper(node.parent)
+    : node;
+
 type VariableDefinition = Readonly<{
   type: string;
   parent: TSESTree.VariableDeclaration;
@@ -248,3 +265,53 @@ const isVariableDefinition = (
   def: TSESLint.Scope.Definition,
 ): def is TSESLint.Scope.Definition & VariableDefinition =>
   (def.type as string) === 'Variable';
+
+/**
+ * Whether `node`, read through its type wrappers, is the identifier `name`:
+ * `Number`, `(Number as NumberConstructor)` and `Number!` are the same object.
+ */
+export const isIdentifierNamed = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Node,
+  name: string,
+): boolean => {
+  const unwrapped = skipTypeWrappers(node);
+
+  return (
+    unwrapped.type === AST_NODE_TYPES.Identifier && unwrapped.name === name
+  );
+};
+
+/**
+ * Whether `holds` is true of the type of every layer of type wrappers around
+ * `node` (see {@link typeWrapperLayers}), outermost to innermost; `false`
+ * without type information. A widening cast (`s as string | number`) is the
+ * author saying the value may be more than it is, and is respected; a
+ * narrowing one (`s!`, `v as unknown as string`) cannot vouch for what the
+ * value's own type does not, and the fix, which keeps the wrapper, has to
+ * type-check at every layer too.
+ */
+export const typeHoldsAtEveryLayer = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceCode: TSESLint.SourceCode,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: TSESTree.Node,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  holds: (type: ts.Type, typeChecker: ts.TypeChecker) => boolean,
+): boolean => {
+  const services = sourceCode.parserServices;
+
+  const checker = services?.program?.getTypeChecker();
+
+  if (checker === undefined) {
+    return false;
+  }
+
+  return typeWrapperLayers(node).every((layer) => {
+    const tsNode = services?.esTreeNodeToTSNodeMap?.get(layer);
+
+    return (
+      tsNode !== undefined && holds(checker.getTypeAtLocation(tsNode), checker)
+    );
+  });
+};

package/src/rules/constants.mts

@@ -1 +1,13 @@
+import * as ts from 'typescript';
+
 export const TS_DATA_FORGE_MODULE = 'ts-data-forge';
+
+/** The type flags of every primitive type but `void`. */
+export const primitiveTypeFlags =
+  ts.TypeFlags.StringLike |
+  ts.TypeFlags.NumberLike |
+  ts.TypeFlags.BigIntLike |
+  ts.TypeFlags.BooleanLike |
+  ts.TypeFlags.ESSymbolLike |
+  ts.TypeFlags.Null |
+  ts.TypeFlags.Undefined;

package/src/rules/mutable-result.mts

@@ -0,0 +1,204 @@
+import {
+  AST_NODE_TYPES,
+  type TSESLint,
+  type TSESTree,
+} from '@typescript-eslint/utils';
+import * as ts from 'typescript';
+import { primitiveTypeFlags } from './constants.mjs';
+
+/**
+ * Whether the code around `node` visibly relies on the result being a mutable
+ * array, so that swapping in the readonly array `Arr.uniq` or `Arr.generate`
+ * returns would not compile. Looks at `node` itself and, when it initializes a variable without a
+ * type annotation, at every read of that variable.
+ */
+export 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)
+  );
+};
+
+/** Methods that `ReadonlyArray` lacks and that mutate the receiver. */
+const mutatingMethods: ReadonlySet<string> = new Set([
+  'copyWithin',
+  'fill',
+  'pop',
+  'push',
+  'reverse',
+  'shift',
+  'sort',
+  'splice',
+  'unshift',
+]);