ts-codemod-lib 3.5.0 → 4.0.0

package/src/functions/ast-transformers/convert-to-readonly.mts

@@ -2,6 +2,7 @@ import {
   Arr,
   expectType,
   ISet,
+  isRecord,
   isString,
   mapNullable,
   match,
@@ -14,6 +15,10 @@ import type {
   StrictExclude,
   StrictExtract,
 } from 'ts-type-forge';
+import {
+  DEFAULT_MUTABLE_PREFIXES,
+  DEFAULT_MUTABLE_TYPE_PREFIXES,
+} from '../constants/index.mjs';
 import {
   hasCallOrConstructSignature,
   hasDisableNextLineComment,
@@ -59,9 +64,17 @@ export const convertToReadonlyTransformer = (
   const DeepReadonlyTypeName =
     options?.DeepReadonly?.typeName ?? 'DeepReadonly';
 
-  const ignorePrefixes = ISet.create(
-    options?.ignorePrefixes ?? ['mut_', '#mut_', '_mut_', 'draft'],
-  );
+  // Removed in 4.0.0; a caller without types would otherwise lose it silently.
+  const untypedOptions: unknown = options;
+
+  if (
+    isRecord(untypedOptions) &&
+    untypedOptions['ignorePrefixes'] !== undefined
+  ) {
+    throw new Error(
+      `The "ignorePrefixes" option of ${TRANSFORMER_NAME} was replaced by "mutableVariablePrefixes", "mutableTypePrefixes" and "mutablePropertyPrefixes".`,
+    );
+  }
 
   const optionsInternal: ReadonlyTransformerOptionsInternal = {
     DeepReadonly: {
@@ -69,7 +82,15 @@ export const convertToReadonlyTransformer = (
       applyLevel: 'keep',
     },
     ignoreEmptyObjectTypes: options?.ignoreEmptyObjectTypes ?? true,
-    ignoredPrefixes: ignorePrefixes,
+    mutableVariablePrefixes: ISet.create(
+      options?.mutableVariablePrefixes ?? DEFAULT_MUTABLE_PREFIXES,
+    ),
+    mutableTypePrefixes: ISet.create(
+      options?.mutableTypePrefixes ?? DEFAULT_MUTABLE_TYPE_PREFIXES,
+    ),
+    mutablePropertyPrefixes: ISet.create(
+      options?.mutablePropertyPrefixes ?? DEFAULT_MUTABLE_PREFIXES,
+    ),
     recordStyle: options?.recordStyle ?? 'ReadonlyRecord',
     debugPrint: options?.debug === true ? console.debug : () => {},
     replaceNode:
@@ -135,13 +156,44 @@ export type ReadonlyTransformerOptions = DeepReadonly<{
   ignoreEmptyObjectTypes?: boolean;
 
   /**
-   * A mute keywords to ignore the readonly conversion.
+   * Prefixes of the names of variables, parameters (but for a constructor
+   * parameter property, which `mutablePropertyPrefixes` decides) and
+   * functions that are left mutable: their types are not made readonly.
+   *
+   * @default ['mut_']
+   */
+  mutableVariablePrefixes?: string[];
+
+  /**
+   * Prefixes of the names of type aliases, interfaces, class declarations and
+   * named class expressions that are left mutable: their declarations are not
+   * made readonly.
    *
-   * (e.g. `"mut_"`)
+   * @default ['Mutable', 'mut_']
+   */
+  mutableTypePrefixes?: string[];
+
+  /**
+   * Prefixes of the names of properties, methods and accessors (of type
+   * literals, interfaces and classes, constructor parameter properties
+   * included) that are left mutable: they get no `readonly`, and their types
+   * are not made readonly. A private name is matched with or after its `#`, so
+   * both `mut_` and `#mut_` cover `#mut_x`. Of a named tuple member with such a prefix, only the type
+   * is kept; the tuple is still made `readonly`.
+   *
+   * A type literal with a property, a method or an accessor of such a prefix
+   * is not wrapped with `Readonly<...>`, which would make that member readonly
+   * too; its other members are marked `readonly` one by one instead, and a
+   * `Readonly<...>` written around it is taken off. It is wrapped as before
+   * when it also has a member that cannot be marked `readonly` by itself (a
+   * method signature or an accessor without such a prefix, or a property or
+   * index signature not yet `readonly` that an ignore comment skips), or when
+   * it is a member of a `Readonly<...>` intersection beside a type that may be
+   * an array.
    *
-   * @default ['mut_', '#mut_', '_mut_', 'draft']
+   * @default ['mut_']
    */
-  ignorePrefixes?: string[];
+  mutablePropertyPrefixes?: string[];
 
   /**
    * The output style used when making `Record<K, V>` readonly.
@@ -176,7 +228,11 @@ type ReadonlyTransformerOptionsInternal = Readonly<{
 
   ignoreEmptyObjectTypes: boolean;
 
-  ignoredPrefixes: ISet<string>;
+  mutableVariablePrefixes: ISet<string>;
+
+  mutableTypePrefixes: ISet<string>;
+
+  mutablePropertyPrefixes: ISet<string>;
 
   recordStyle: 'Readonly<Record>' | 'ReadonlyRecord';
 
@@ -216,24 +272,26 @@ const transformNode = (
     return;
   }
 
-  // check for ignorePrefix
+  // check for mutableVariablePrefixes
   if (node.isKind(tsm.SyntaxKind.VariableDeclaration)) {
     const nodeName = node.getName();
 
-    if (options.ignoredPrefixes.some((p) => nodeName.startsWith(p))) {
+    if (options.mutableVariablePrefixes.some((p) => nodeName.startsWith(p))) {
       // Skip conversion for variable declarations with ignored prefixes
       // Example: const mut_foo: string[] = []; -> remains as is, without appending `as const`
-      options.debugPrint('skipped variable declaration by ignorePrefixes');
+      options.debugPrint(
+        'skipped variable declaration by mutableVariablePrefixes',
+      );
 
       return;
     }
 
-    // TODO: Support ignoredPrefixes in ArrayBindingPattern
+    // TODO: Support mutableVariablePrefixes in ArrayBindingPattern
     // if (ts.isArrayBindingPattern(nodeName)) {
     //   // for (const [i, el] of nodeName.elements.entries())
     // }
 
-    // TODO: Support ignoredPrefixes in ObjectBindingPattern
+    // TODO: Support mutableVariablePrefixes in ObjectBindingPattern
     // if (ts.isObjectBindingPattern(nodeName)) {
     //   // for (const [i, el] of nodeName.elements.entries())
     // }
@@ -244,7 +302,9 @@ const transformNode = (
   if (
     (node.isKind(tsm.SyntaxKind.FunctionDeclaration) ||
       node.isKind(tsm.SyntaxKind.FunctionExpression)) &&
-    options.ignoredPrefixes.some((p) => node.getName()?.startsWith(p) === true)
+    options.mutableVariablePrefixes.some(
+      (p) => node.getName()?.startsWith(p) === true,
+    )
   ) {
     return;
   }
@@ -252,26 +312,30 @@ const transformNode = (
   if (node.isKind(tsm.SyntaxKind.Parameter)) {
     const nodeName = node.getName();
 
-    if (options.ignoredPrefixes.some((p) => nodeName.startsWith(p))) {
-      // Skip readonly conversion for variable declarations with ignored prefixes
-      // Example: const mut_foo: string[] = []; -> remains as is, without readonly conversion
+    if (
+      mutablePrefixesOfParameter(node, options).some((p) =>
+        nodeName.startsWith(p),
+      )
+    ) {
+      // Skip readonly conversion for parameters with mutable prefixes
+      // Example: (mut_foo: string[]) => {} -> remains as is, without readonly conversion
       return;
     }
 
-    // TODO: Support ignoredPrefixes in ArrayBindingPattern
+    // TODO: Support mutableVariablePrefixes in ArrayBindingPattern
     // if (ts.isArrayBindingPattern(nodeName)) {
     // }
 
-    // TODO: Support ignoredPrefixes in ObjectBindingPattern
+    // TODO: Support mutableVariablePrefixes in ObjectBindingPattern
     // if (ts.isObjectBindingPattern(nodeName)) {
     // }
   }
 
   // Skip readonly conversion for type alias declarations with ignored prefixes
-  // Example: type mut_Foo = number[]; -> remains as number[] without readonly
+  // Example: type MutableFoo = number[]; -> remains as number[] without readonly
   if (
     node.isKind(tsm.SyntaxKind.TypeAliasDeclaration) &&
-    options.ignoredPrefixes.some((p) => node.getName().startsWith(p))
+    hasMutableTypeName(node.getName(), options)
   ) {
     return;
   }
@@ -350,8 +414,8 @@ const transformNode = (
 
   if (node.isKind(tsm.SyntaxKind.InterfaceDeclaration)) {
     // Skip readonly conversion for interface declarations with ignored prefixes
-    // Example: interface mut_Interface {...} -> properties remain without readonly
-    if (options.ignoredPrefixes.some((p) => node.getName().startsWith(p))) {
+    // Example: interface MutableInterface {...} -> properties remain without readonly
+    if (hasMutableTypeName(node.getName(), options)) {
       return;
     }
 
@@ -360,14 +424,18 @@ const transformNode = (
     return;
   }
 
+  // Example: const C = class MutableClass {...} -> properties remain without readonly
+  if (
+    node.isKind(tsm.SyntaxKind.ClassExpression) &&
+    hasMutableTypeName(node.getName(), options)
+  ) {
+    return;
+  }
+
   if (node.isKind(tsm.SyntaxKind.ClassDeclaration)) {
     // Skip readonly conversion for class declarations with ignored prefixes
-    // Example: class mut_Class {...} -> properties remain without readonly
-    if (
-      options.ignoredPrefixes.some(
-        (p) => node.getName()?.startsWith(p) === true,
-      )
-    ) {
+    // Example: class MutableClass {...} -> properties remain without readonly
+    if (hasMutableTypeName(node.getName(), options)) {
       return;
     }
 
@@ -421,6 +489,8 @@ const transformNode = (
  * - `tr(Readonly<Readonly<E>>) |-> Readonly<tr(E)>`
  * - `tr(DeepReadonly<Readonly<E>>) |-> DeepReadonly<tr(E)>`
  * - `tr(Readonly<number>) |-> number`
+ * - `tr(Readonly<{ mut_x: X; y: Y }>) |-> { mut_x: X; readonly y: tr(Y) }` (see
+ *   `isLeftUnwrapped`)
  * - `tr(Readonly<E[]>) |-> readonly tr(E)[]`
  * - `tr(Readonly<[E1, E2, E3]>) |-> readonly [tr(E1), tr(E2), tr(E3)]`
  * - `tr(Readonly<readonly E[]>) |-> readonly tr(E)[]`
@@ -647,14 +717,29 @@ const transformTypeReferenceNode = (
       );
     }
 
+    // Read before the recursion, which may replace the node.
+    const typeArgumentBefore = removeParentheses(typeArguments[0]);
+
+    // Readonly<{ mut_x: X; y: Y }> -> { mut_x: X; readonly y: Y }
+    // `Readonly` would make the property of an ignored prefix readonly too, so
+    // it is taken off, and the literal is transformed where nothing wraps it,
+    // which marks its other members readonly in place. See `takesOffReadonly`.
+    const takesOffWrapper =
+      readonlyContext.type !== 'DeepReadonly' &&
+      readonlyContext.indexedAccessDepth === 0 &&
+      typeArgumentBefore.isKind(tsm.SyntaxKind.TypeLiteral) &&
+      takesOffReadonly(typeArgumentBefore, options);
+
     // Recursive processing
     transformNode(
       typeArguments[0],
-      nextReadonlyContext({
-        currentReadonlyContext: readonlyContext,
-        nextReadonlyContextType: 'Readonly',
-        indexedAccessDepthChange: 'keep',
-      }),
+      takesOffWrapper
+        ? initialReadonlyContext
+        : nextReadonlyContext({
+            currentReadonlyContext: readonlyContext,
+            nextReadonlyContextType: 'Readonly',
+            indexedAccessDepthChange: 'keep',
+          }),
       options,
     );
 
@@ -695,6 +780,29 @@ const transformTypeReferenceNode = (
       return;
     }
 
+    // Readonly<Readonly<{ mut_x: X }>> -> { mut_x: X } as well: the inner
+    // `Readonly` has already been taken off the literal.
+    if (
+      takesOffWrapper ||
+      (T.isKind(tsm.SyntaxKind.TypeLiteral) && takesOffReadonly(T, options))
+    ) {
+      // The comments after the literal, which nothing else carries over, go
+      // in front of it: a line comment after it would end the type with a
+      // line break, which a following `[]` cannot be parsed across.
+      const commentsAfterT = commentsBetween(
+        node.getSourceFile(),
+        T.getEnd(),
+        node.getEnd(),
+      );
+
+      options.replaceNode(
+        node,
+        `${commentsInFrontOfT}${commentsAfterT}${T.getText()}`,
+      );
+
+      return;
+    }
+
     // Readonly<Readonly<T>> -> Readonly<T>
     if (isReadonlyTypeReferenceNode(T)) {
       options.replaceNode(node, TText);
@@ -948,7 +1056,11 @@ const transformTupleTypeNode = (
 
     for (const el of node.getElements()) {
       if (el.isKind(tsm.SyntaxKind.NamedTupleMember)) {
-        if (options.ignoredPrefixes.every((p) => !el.getName().startsWith(p))) {
+        if (
+          options.mutablePropertyPrefixes.every(
+            (p) => !el.getName().startsWith(p),
+          )
+        ) {
           transformNode(el.getTypeNode(), nextReadonlyContextValue, options);
         }
       } else {
@@ -1085,10 +1197,13 @@ const transformTypeLiteralNode = (
   const wrappingApplies =
     readonlyContext.type === 'none' && readonlyContext.indexedAccessDepth === 0;
 
-  // A call or construct signature does not survive `Readonly<T>`, so a literal
-  // carrying one is left unwrapped and marked readonly member by member
-  // instead. See `hasCallOrConstructSignature`.
-  const skipWrapping = wrappingApplies && hasCallOrConstructSignature(node);
+  // A call or construct signature does not survive `Readonly<T>`, and a
+  // property of an ignored prefix (`mut_`) must stay mutable, so a literal
+  // carrying either is left unwrapped and marked readonly member by member
+  // instead. See `hasCallOrConstructSignature` and `isLeftUnwrapped`.
+  const skipWrapping =
+    wrappingApplies &&
+    (hasCallOrConstructSignature(node) || isLeftUnwrapped(node, options));
 
   // Recursive processing
   transformMembers(
@@ -1305,7 +1420,9 @@ const transformConstructorParameter = (
 
   const name = param.getName();
 
-  if (options.ignoredPrefixes.some((p) => name.startsWith(p))) {
+  if (
+    mutablePrefixesOfParameter(param, options).some((p) => name.startsWith(p))
+  ) {
     return;
   }
 
@@ -1393,16 +1510,25 @@ const transformUnionOrIntersectionTypeNodeImpl = (
     memberText: string,
   ): string => `${leadingCommentsOfMember(node, member)}${memberText}` as const;
 
+  // Whether a type literal member is wrapped at all; under `DeepReadonly` or an
+  // indexed access none is.
+  const wrapsTypeLiterals =
+    nextReadonlyContextValue.type !== 'DeepReadonly' &&
+    nextReadonlyContextValue.indexedAccessDepth === 0;
+
+  // `Readonly<A & { b: B }>`: `A` stays under the `Readonly`, which the
+  // handler of `Readonly` then takes off as redundant.
+  const underReadonly =
+    readonlyContext.type === 'Readonly' &&
+    readonlyContext.indexedAccessDepth === 0 &&
+    isTypeArgumentOfReadonly(node);
+
   const { primitives, arraysAndTuples, typeLiterals, others } =
     groupUnionIntersectionTypes(newTypes, {
       operator,
-      // `Readonly<A & { b: B }>`: `A` stays under the `Readonly`, which the
-      // handler of `Readonly` then takes off as redundant.
-      underReadonly:
-        readonlyContext.type === 'Readonly' &&
-        readonlyContext.indexedAccessDepth === 0 &&
-        isTypeArgumentOfReadonly(node),
+      underReadonly,
       deepReadonlyTypeName: options.DeepReadonly.typeName,
+      keptUnwrapped: (t) => wrapsTypeLiterals && takesOffReadonly(t, options),
     });
 
   options.debugPrint({ primitives, arraysAndTuples, typeLiterals, others });
@@ -1445,9 +1571,7 @@ const transformUnionOrIntersectionTypeNodeImpl = (
               ),
             ),
             op: operator,
-            wrapWithReadonly:
-              nextReadonlyContextValue.type !== 'DeepReadonly' &&
-              nextReadonlyContextValue.indexedAccessDepth === 0,
+            wrapWithReadonly: wrapsTypeLiterals,
           }),
         ] as const);
 
@@ -1909,6 +2033,17 @@ const transformMembers = (
       continue;
     }
 
+    // A method or an accessor of an ignored prefix is left as written, as in a
+    // class.
+    if (
+      (mb.isKind(tsm.SyntaxKind.MethodSignature) ||
+        mb.isKind(tsm.SyntaxKind.GetAccessor) ||
+        mb.isKind(tsm.SyntaxKind.SetAccessor)) &&
+      checkIfPropertyNameShouldBeIgnored(mb.getNameNode(), options)
+    ) {
+      continue;
+    }
+
     if (mb.isKind(tsm.SyntaxKind.IndexSignature)) {
       transformIndexSignatureDeclaration(
         mb,
@@ -2022,28 +2157,138 @@ const checkIfPropertyNameShouldBeIgnored = (
     // mut_x: number[]
     (nameNode.isKind(tsm.SyntaxKind.Identifier) &&
       pipe(nameNode.getText()).map((nm) =>
-        options.ignoredPrefixes.some((p) => nm.startsWith(p)),
+        options.mutablePropertyPrefixes.some((p) => nm.startsWith(p)),
       ).value) ||
     // "mut_x": number[]
     (nameNode.isKind(tsm.SyntaxKind.StringLiteral) &&
       pipe(nameNode.getLiteralValue()).map((nm) =>
-        options.ignoredPrefixes.some((p) => nm.startsWith(p)),
+        options.mutablePropertyPrefixes.some((p) => nm.startsWith(p)),
       ).value) ||
-    //  #memberName: number[] (class only)
+    //  #memberName: number[] (class only), matched with or after its `#`
     (nameNode.isKind(tsm.SyntaxKind.PrivateIdentifier) &&
       pipe(nameNode.getText()).map((nm) =>
-        options.ignoredPrefixes.some((p) => nm.startsWith(`#${p}`)),
+        options.mutablePropertyPrefixes.some(
+          (p) => nm.startsWith(p) || nm.startsWith(`#${p}`),
+        ),
       ).value) ||
-    // [`mut_x`]: number[]
+    // ['mut_x']: number[], [`mut_x`]: number[]
     (nameNode.isKind(tsm.SyntaxKind.ComputedPropertyName) &&
       pipe(nameNode.getExpression()).map((exp) => {
-        if (exp.isKind(tsm.SyntaxKind.StringLiteral)) {
+        if (
+          exp.isKind(tsm.SyntaxKind.StringLiteral) ||
+          exp.isKind(tsm.SyntaxKind.NoSubstitutionTemplateLiteral)
+        ) {
           const nm = exp.getLiteralValue();
 
-          return options.ignoredPrefixes.some((p) => nm.startsWith(p));
+          return options.mutablePropertyPrefixes.some((p) => nm.startsWith(p));
         }
 
         return false;
       }).value)
   );
 };
+
+/**
+ * Whether a type literal is left without `Readonly<...>` and marked readonly
+ * member by member, because it has a property, a method or an accessor of an
+ * ignored prefix (`{ mut_x: X[] }`), which `transformMembers` leaves mutable
+ * and `Readonly<T>` would not.
+ *
+ * It keeps its `Readonly<...>` when that would leave another member mutable,
+ * since only a property or index signature can be marked `readonly` itself:
+ *
+ * - a method signature or an accessor, which `Readonly<T>` makes readonly too,
+ *   unless its name has an ignored prefix as well;
+ * - a property or index signature the ignore comment skips (as
+ *   `transformMembers` does), which gets no `readonly` of its own, unless it
+ *   is `readonly` already.
+ */
+const isLeftUnwrapped = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: tsm.TypeLiteralNode,
+  options: ReadonlyTransformerOptionsInternal,
+): boolean => {
+  const members = node.getMembers();
+
+  const isMethodOrAccessor = (
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    mb: tsm.TypeElementTypes,
+  ): mb is
+    | tsm.MethodSignature
+    | tsm.GetAccessorDeclaration
+    | tsm.SetAccessorDeclaration =>
+    mb.isKind(tsm.SyntaxKind.MethodSignature) ||
+    mb.isKind(tsm.SyntaxKind.GetAccessor) ||
+    mb.isKind(tsm.SyntaxKind.SetAccessor);
+
+  const isIgnoredMember = (
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    mb: tsm.TypeElementTypes,
+  ): boolean =>
+    (mb.isKind(tsm.SyntaxKind.PropertySignature) || isMethodOrAccessor(mb)) &&
+    checkIfPropertyNameShouldBeIgnored(mb.getNameNode(), options);
+
+  const needsReadonlyWrapper = (
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    mb: tsm.TypeElementTypes,
+  ): boolean =>
+    !isIgnoredMember(mb) &&
+    (isMethodOrAccessor(mb) ||
+      ((mb.isKind(tsm.SyntaxKind.PropertySignature) ||
+        mb.isKind(tsm.SyntaxKind.IndexSignature)) &&
+        !mb.hasModifier(tsm.SyntaxKind.ReadonlyKeyword) &&
+        hasDisableNextLineComment(mb)));
+
+  return members.some(isIgnoredMember) && !members.some(needsReadonlyWrapper);
+};
+
+/** Whether `node`, or a parenthesized type around it, carries the ignore comment. */
+const hasDisableNextLineCommentAround = (node: tsm.Node): boolean => {
+  if (hasDisableNextLineComment(node, TRANSFORMER_NAME)) {
+    return true;
+  }
+
+  const parent = node.getParent();
+
+  return (
+    parent?.isKind(tsm.SyntaxKind.ParenthesizedType) === true &&
+    hasDisableNextLineCommentAround(parent)
+  );
+};
+
+/**
+ * Whether a type literal that is already wrapped, or would be merged into the
+ * `Readonly<...>` of a union or intersection, is taken out of it. See
+ * `isLeftUnwrapped`; in addition, the ignore comment leaves the literal where
+ * it is, and taking `Readonly` off one with a call or construct signature
+ * would bring back the signature it dropped.
+ */
+const takesOffReadonly = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: tsm.TypeLiteralNode,
+  options: ReadonlyTransformerOptionsInternal,
+): boolean =>
+  isLeftUnwrapped(node, options) &&
+  !hasCallOrConstructSignature(node) &&
+  !hasDisableNextLineCommentAround(node);
+
+/** Whether a type alias, interface or class name starts with a `mutableTypePrefixes` entry. */
+const hasMutableTypeName = (
+  name: string | undefined,
+  options: ReadonlyTransformerOptionsInternal,
+): boolean =>
+  name !== undefined &&
+  options.mutableTypePrefixes.some((p) => name.startsWith(p));
+
+/**
+ * A parameter property is a property of the class, as a `PropertyDeclaration`
+ * is; any other parameter is a variable.
+ */
+const mutablePrefixesOfParameter = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  param: tsm.ParameterDeclaration,
+  options: ReadonlyTransformerOptionsInternal,
+): ISet<string> =>
+  param.isParameterProperty()
+    ? options.mutablePropertyPrefixes
+    : options.mutableVariablePrefixes;