ts-codemod-lib 3.4.1 → 3.4.2

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

@@ -3034,6 +3034,380 @@ describe(convertToReadonlyTransformer, () => {
     });
   });
 
+  describe('Readonly over a union or intersection', () => {
+    test.each(
+      [
+        // A member whose readonly-ness the codemod cannot see stays under the
+        // `Readonly` it was written under.
+        {
+          name: 'An alias in an intersection under Readonly stays under it',
+          source: dedent`
+            type X<A> = Readonly<A & { b: string[] }>;
+          `,
+          expected: dedent`
+            type X<A> = Readonly<A & { b: readonly string[] }>;
+          `,
+        },
+        {
+          name: 'An alias in a union under Readonly stays under it',
+          source: dedent`
+            type X<A> = Readonly<A | { b: string[] }>;
+          `,
+          expected: dedent`
+            type X<A> = Readonly<A | { b: readonly string[] }>;
+          `,
+        },
+        {
+          name: 'An intersection of aliases under Readonly is left as written',
+          source: dedent`
+            type X<A, B> = Readonly<A & B>;
+          `,
+          expected: dedent`
+            type X<A, B> = Readonly<A & B>;
+          `,
+        },
+        {
+          name: 'A nested union under Readonly stays under it',
+          source: dedent`
+            type X<A, B> = Readonly<(A | B) & { c: string[] }>;
+          `,
+          expected: dedent`
+            type X<A, B> = Readonly<(A | B) & { c: readonly string[] }>;
+          `,
+        },
+        {
+          name: 'Members readonly on their own are still taken out',
+          source: dedent`
+            type X<A> = Readonly<number | string[] | DeepReadonly<A> | Map<string, A> | { b: string }>;
+          `,
+          expected: dedent`
+            type X<A> = number | readonly string[] | DeepReadonly<A> | ReadonlyMap<string, A> | Readonly<{ b: string }>;
+          `,
+        },
+        {
+          // `Readonly` would drop the call signature.
+          name: 'A function type is still taken out',
+          source: dedent`
+            type X = Readonly<(() => void) & { b: string }>;
+          `,
+          expected: dedent`
+            type X = (() => void) & Readonly<{ b: string }>;
+          `,
+        },
+
+        // #2231: what replaces `Readonly<…>` keeps the parentheses its
+        // position needs.
+        {
+          name: 'Readonly of an intersection with an alias as an array element under readonly',
+          source: dedent`
+            type A = Readonly<{ a: string }>;
+            export type X = readonly Readonly<A & { b: string }>[];
+          `,
+          expected: dedent`
+            type A = Readonly<{ a: string }>;
+            export type X = readonly Readonly<A & { b: string }>[];
+          `,
+        },
+        {
+          name: 'Readonly of an intersection with an alias as an array element',
+          source: dedent`
+            type A = Readonly<{ a: string }>;
+            export type X = Readonly<A & { b: string }>[];
+          `,
+          expected: dedent`
+            type A = Readonly<{ a: string }>;
+            export type X = readonly Readonly<A & { b: string }>[];
+          `,
+        },
+        {
+          name: 'Readonly of a union with an alias as an array element',
+          source: dedent`
+            type X<A> = Readonly<A | { b: string }>[];
+          `,
+          expected: dedent`
+            type X<A> = readonly Readonly<A | { b: string }>[];
+          `,
+        },
+        {
+          name: 'Readonly of an intersection with an alias in ReadonlyArray',
+          source: dedent`
+            type X<A> = ReadonlyArray<Readonly<A & { b: string }>>;
+          `,
+          expected: dedent`
+            type X<A> = readonly Readonly<A & { b: string }>[];
+          `,
+        },
+        {
+          name: 'A Readonly that is taken off as an array element',
+          source: dedent`
+            type X = Readonly<number | readonly string[]>[];
+          `,
+          expected: dedent`
+            type X = readonly (number | readonly string[])[];
+          `,
+        },
+        {
+          name: 'A Readonly that is taken off under readonly',
+          source: dedent`
+            type X = readonly Readonly<number & { b: string }>[];
+          `,
+          expected: dedent`
+            type X = readonly (number & Readonly<{ b: string }>)[];
+          `,
+        },
+        {
+          name: 'A Readonly that is taken off as an intersection member',
+          source: dedent`
+            type X = { a: string } & Readonly<number | { b: string }>;
+          `,
+          expected: dedent`
+            type X = Readonly<{ a: string }> & (number | Readonly<{ b: string }>);
+          `,
+        },
+
+        // #2169: `Readonly<A> & Readonly<B>` is merged only when both are
+        // object types, because `Readonly<string[] & X>` leaves the array
+        // mutable.
+        {
+          name: 'An intersection of Readonly aliases is not merged',
+          source: dedent`
+            type X<A, B> = Readonly<A> & Readonly<B>;
+          `,
+          expected: dedent`
+            type X<A, B> = Readonly<A> & Readonly<B>;
+          `,
+        },
+        {
+          name: 'A Readonly alias is not merged with a type literal',
+          source: dedent`
+            type X<A> = Readonly<A> & { b: string[] };
+          `,
+          expected: dedent`
+            type X<A> = Readonly<A> & Readonly<{ b: readonly string[] }>;
+          `,
+        },
+        {
+          name: 'Readonly type literals in an intersection are merged',
+          source: dedent`
+            type X = Readonly<{ a: string } | { c: string }> & Readonly<{ b: string }>;
+          `,
+          expected: dedent`
+            type X = Readonly<({ a: string } | { c: string }) & { b: string }>;
+          `,
+        },
+        {
+          // A mapped type over anything but `keyof T` is an object type.
+          name: 'Mapped types in an intersection under Readonly are merged',
+          source: dedent`
+            type X<S, K extends keyof S> = Readonly<{ [k in K]?: S[k] } & { [k in Exclude<keyof S, K>]: S[k] }>;
+          `,
+          expected: dedent`
+            type X<S, K extends keyof S> = Readonly<{ [k in K]?: S[k] } & { [k in Exclude<keyof S, K>]: S[k] }>;
+          `,
+        },
+        {
+          // `{ [k in keyof T]: T[k] }` maps an array `T` to an array.
+          name: 'A homomorphic mapped type in an intersection is not merged',
+          source: dedent`
+            type X<T> = Readonly<{ [k in keyof T]: T[k] }> & Readonly<{ b: string }>;
+          `,
+          expected: dedent`
+            type X<T> = Readonly<{ [k in keyof T]: T[k] }> & Readonly<{ b: string }>;
+          `,
+        },
+        {
+          name: 'A union of Readonly aliases is still merged',
+          source: dedent`
+            type X<A, B> = Readonly<A> | Readonly<B>;
+          `,
+          expected: dedent`
+            type X<A, B> = Readonly<A | B>;
+          `,
+        },
+      ].flatMap((c) => [
+        c,
+        // The output is a fixed point: running the codemod again keeps it,
+        // readonly-ness included.
+        { ...c, name: `${c.name} (fixed point)`, source: c.expected },
+      ]),
+    )('$name', testFn);
+
+    // What merging `Readonly` members relies on.
+    test('premises of merging Readonly members', () => {
+      type X = { x: number };
+
+      // `Readonly` distributes over `|`, so merging a union is safe.
+      expectType<Readonly<string[] | X>, readonly string[] | Readonly<X>>('=');
+
+      // It does not over `&` with an array member: the merged form leaves the
+      // array mutable.
+      expectType<Readonly<string[] & X>, readonly string[] & Readonly<X>>('<=');
+
+      expectType<Readonly<string[] & X>, readonly string[] & Readonly<X>>('!=');
+    });
+  });
+
+  describe('Comments in front of a member', () => {
+    // `replaceWithText` overwrites a node from `getStart()`, so a comment in
+    // front of it stays where it is. Text built for the replacement must carry
+    // the comments after that point — those in front of each member and those
+    // in front of the `|` / `&` separating them — and none before it.
+    test.each([
+      {
+        name: 'JSDoc on each member of a union with a leading `|`',
+        source: dedent`
+          export type ProbeStore =
+            /** Kept until the browser is closed. */
+            | 'session'
+            /** Kept until it is forgotten. */
+            | 'device';
+        `,
+        // Prettier itself moves the second comment to the end of the line
+        // before it; here it stays in front of its member.
+        expected: dedent`
+          export type ProbeStore =
+            | /** Kept until the browser is closed. */ 'session'
+            | /** Kept until it is forgotten. */ 'device';
+        `,
+      },
+      {
+        name: 'Line comments on each member of a union with a leading `|`',
+        source: dedent`
+          type T =
+            // first
+            | 'a'
+            // second
+            | 'b'
+            // third
+            | 'c';
+        `,
+        expected: dedent`
+          type T =
+            // first
+            | 'a'
+            // second
+            | 'b'
+            // third
+            | 'c';
+        `,
+      },
+      {
+        name: 'Comments on each member of a union without a leading `|`',
+        source: dedent`
+          type T = /** a */ 'a' | /** b */ 'b';
+        `,
+        expected: dedent`
+          type T = /** a */ 'a' | /** b */ 'b';
+        `,
+      },
+      {
+        name: 'A comment after `|` stays with the member after it',
+        source: dedent`
+          type T = 'a' | // about b
+            'b';
+        `,
+        expected: dedent`
+          type T = 'a' | // about b
+            'b';
+        `,
+      },
+      ...toUnionAndIntersectionTestCase({
+        title: (op) => `Comments on members of an ${op} that are converted`,
+        testCase: (op) => ({
+          source: dedent`
+            type T =
+              /** list */
+              ${op} number[]
+              /** object */
+              ${op} { a: number[] };
+          `,
+          // The comment on the object moves inside the `Readonly` around it.
+          expected: dedent`
+            type T =
+              /** list */
+              ${op} readonly number[]
+              ${op} Readonly</** object */ { a: readonly number[] }>;
+          `,
+        }),
+      }),
+      ...toUnionAndIntersectionTestCase({
+        title: (op) =>
+          `Comments on Readonly members of an ${op} that are merged`,
+        testCase: (op) => ({
+          source: dedent`
+            type T = /** a */ Readonly<{ a: number }> ${op} /** b */ Readonly<{ b: number }>;
+          `,
+          expected: dedent`
+            type T = /** a */ Readonly<{ a: number } ${op} /** b */ { b: number }>;
+          `,
+        }),
+      }),
+      {
+        name: 'Comments on DeepReadonly members that are merged',
+        source: dedent`
+          type T = /** a */ DeepReadonly<{ a: number[] }> | /** b */ DeepReadonly<{ b: string[] }>;
+        `,
+        expected: dedent`
+          type T = /** a */ DeepReadonly<{ a: number[] } | /** b */ { b: string[] }>;
+        `,
+      },
+      {
+        name: 'A comment in front of a union inside parentheses',
+        source: dedent`
+          type T = (/** a */ 'a' | 'b')[];
+        `,
+        expected: dedent`
+          type T = /** a */ readonly ('a' | 'b')[];
+        `,
+      },
+      {
+        name: 'Comments around parentheses that Readonly<T> unwraps',
+        source: dedent`
+          type T = Readonly</** a */ (/** b */ number[])>;
+        `,
+        expected: dedent`
+          type T = /** a */ /** b */ readonly number[];
+        `,
+      },
+      {
+        name: 'Comments around parentheses in a rest element',
+        source: dedent`
+          type T = [string, ...(/** a */ readonly number[])];
+        `,
+        expected: dedent`
+          type T = readonly [string, .../** a */ number[]];
+        `,
+      },
+      {
+        name: 'A comment in front of an array type',
+        source: dedent`
+          type T = /** c */ number[];
+        `,
+        expected: dedent`
+          type T = /** c */ readonly number[];
+        `,
+      },
+      {
+        name: 'A comment in front of a tuple type',
+        source: dedent`
+          type T = /** c */ [number, string];
+        `,
+        expected: dedent`
+          type T = /** c */ readonly [number, string];
+        `,
+      },
+      {
+        name: 'A comment in front of a type literal',
+        source: dedent`
+          type T = /** c */ { a: number };
+        `,
+        expected: dedent`
+          type T = /** c */ Readonly<{ a: number }>;
+        `,
+      },
+    ])('$name', testFn);
+  });
+
   describe('Parenthesized types', () => {
     test.each([
       {
@@ -3877,7 +4251,7 @@ describe(convertToReadonlyTransformer, () => {
           type /* Block Comment */ WithComments = Readonly<{
             prop1: readonly string[]; // Trailing comment
             /* Another block */
-            prop2: /* member type comment */ readonly /* member type inner comment */ number[];
+            prop2: /* member type comment */ /* member type inner comment */ readonly number[];
             /* End block */
           }>;
         `,
@@ -4678,11 +5052,10 @@ const toUnionAndIntersectionTestCase = ({
 
 describe('idempotency', () => {
   test('a union whose members carry leading whitespace reaches a fixed point', () => {
-    // The members are read with `getFullText()`, which includes the whitespace
-    // in front of each one, and joined with a separator that adds its own. Left
-    // alone the two compound, and a file with `// prettier-ignore` on a long
-    // union grows by one space per member on every run — nothing downstream
-    // normalizes it back.
+    // Whitespace in front of a member, joined with a separator that adds its
+    // own, compounds when left alone, and a file with `// prettier-ignore` on a
+    // long union grows by one space per member on every run — nothing
+    // downstream normalizes it back.
     const code = [
       '// prettier-ignore',
       'export type P = ',
@@ -4700,4 +5073,45 @@ describe('idempotency', () => {
 
     expect(twice).toBe(once);
   });
+
+  test('comments on union members survive rounds of the codemod and Prettier', async () => {
+    // `fix:codemod` runs the codemod and then Prettier, which takes off the
+    // parentheses the codemod puts around a union, so every run starts again
+    // from the unparenthesized form. A comment lost in one round or copied in
+    // the next shows up only across several of them.
+    const code = dedent`
+      export type ProbeStore =
+        /** Kept until the browser is closed. */
+        | 'session'
+        /** Kept until it is forgotten. */
+        | 'device';
+    `;
+
+    const round = async (src: string): Promise<string> =>
+      prettier.format(
+        transformSourceCode(src, false, [convertToReadonlyTransformer()]),
+        {
+          parser: 'typescript',
+          plugins: [prettierPluginTypeScript, prettierPluginEstree],
+        },
+      );
+
+    const round1 = await round(code);
+
+    const round2 = await round(round1);
+
+    const round3 = await round(round2);
+
+    expect(round1).toBe(
+      `${dedent`
+        export type ProbeStore =
+          /** Kept until the browser is closed. */
+          "session" | /** Kept until it is forgotten. */ "device";
+      `}\n`,
+    );
+
+    expect(round2).toBe(round1);
+
+    expect(round3).toBe(round1);
+  });
 });

package/src/functions/ast-transformers/readonly-transformer-helpers/group-union-types.mts

@@ -11,9 +11,30 @@ import {
   type ReadonlyTypeReferenceNode,
 } from '../../functions/index.mjs';
 
+/**
+ * Sorts the members of a union or intersection into the groups
+ * `convert-to-readonly` writes back separately.
+ *
+ * `typeLiterals` is the group joined and wrapped in a single `Readonly<...>`.
+ * It takes type literals, the `Readonly<...>` members that may be merged (see
+ * `isMergeableReadonlyTypeReferenceNode`), and, when the union or intersection
+ * is itself the argument of a `Readonly<...>` (`underReadonly`), every other
+ * member that `Readonly` still means something to (see `staysOutsideReadonly`):
+ * taking such a member out of the `Readonly` it was written under would drop
+ * its readonly-ness.
+ */
 export const groupUnionIntersectionTypes = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
   types: readonly tsm.TypeNode[],
+  {
+    operator,
+    underReadonly,
+    deepReadonlyTypeName,
+  }: Readonly<{
+    operator: '&' | '|';
+    underReadonly: boolean;
+    deepReadonlyTypeName: string;
+  }>,
 ): Readonly<{
   primitives:
     | Readonly<{
@@ -37,7 +58,7 @@ export const groupUnionIntersectionTypes = (
   typeLiterals:
     | Readonly<{
         firstPosition: number;
-        nodes: readonly (tsm.TypeLiteralNode | ReadonlyTypeReferenceNode)[];
+        nodes: readonly tsm.TypeNode[];
       }>
     | undefined;
 
@@ -71,7 +92,7 @@ export const groupUnionIntersectionTypes = (
     typeLiterals:
       | Readonly<{
           firstPosition: number;
-          nodes: (tsm.TypeLiteralNode | ReadonlyTypeReferenceNode)[];
+          nodes: tsm.TypeNode[];
         }>
       | undefined;
 
@@ -130,7 +151,8 @@ export const groupUnionIntersectionTypes = (
     if (
       (t.isKind(tsm.SyntaxKind.TypeLiteral) &&
         !hasCallOrConstructSignature(t)) ||
-      isReadonlyTypeReferenceNode(t)
+      isMergeableReadonlyTypeReferenceNode(t, operator) ||
+      (underReadonly && !staysOutsideReadonly(t, deepReadonlyTypeName))
     ) {
       if (mut_grouped.typeLiterals === undefined) {
         mut_grouped.typeLiterals = {
@@ -157,3 +179,102 @@ export const groupUnionIntersectionTypes = (
 
   return mut_grouped;
 };
+
+/**
+ * Whether a `Readonly<T>` member of a union or intersection may be merged with
+ * the others into one `Readonly<...>`.
+ *
+ * - In a union, any `T`: `Readonly` distributes over `|`, so `Readonly<A> |
+ *   Readonly<B>` and `Readonly<A | B>` are the same type.
+ * - In an intersection, only a `T` known to be an object type (see
+ *   `isObjectTypeLiteral`). Over object types `Readonly<A> & Readonly<B>` and
+ *   `Readonly<A & B>` agree, but `Readonly` maps an array to a readonly array
+ *   only when its argument _is_ an array, so `Readonly<string[] & X>` leaves the
+ *   array mutable where `Readonly<string[]> & Readonly<X>` does not. A type
+ *   parameter or an alias may be such an array.
+ */
+export const isMergeableReadonlyTypeReferenceNode = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: tsm.TypeNode,
+  operator: '&' | '|',
+): node is ReadonlyTypeReferenceNode =>
+  isReadonlyTypeReferenceNode(node) &&
+  (operator === '|' || isObjectTypeLiteral(node.getTypeArguments()[0]));
+
+/**
+ * A type literal or a mapped type known to be an object type, or a union,
+ * intersection or `Readonly<...>` of them.
+ */
+const isObjectTypeLiteral = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: tsm.TypeNode,
+): boolean => {
+  const t = removeParentheses(node);
+
+  if (t.isKind(tsm.SyntaxKind.TypeLiteral)) {
+    return true;
+  }
+
+  // A mapped type is an object type unless it maps over `keyof T`, which maps
+  // an array `T` to an array.
+  if (t.isKind(tsm.SyntaxKind.MappedType)) {
+    const constraint = t.getTypeParameter().getConstraint();
+
+    return !(
+      constraint?.isKind(tsm.SyntaxKind.TypeOperator) === true &&
+      constraint.getOperator() === tsm.SyntaxKind.KeyOfKeyword
+    );
+  }
+
+  if (isReadonlyTypeReferenceNode(t)) {
+    return isObjectTypeLiteral(t.getTypeArguments()[0]);
+  }
+
+  if (
+    t.isKind(tsm.SyntaxKind.UnionType) ||
+    t.isKind(tsm.SyntaxKind.IntersectionType)
+  ) {
+    return t.getTypeNodes().every(isObjectTypeLiteral);
+  }
+
+  return false;
+};
+
+/**
+ * Whether a member of a union or intersection under `Readonly<...>` may be
+ * taken out of it as it is.
+ *
+ * - A function or constructor type, or a type literal with a call or construct
+ *   signature, loses its signatures under `Readonly`; see
+ *   `hasCallOrConstructSignature`.
+ * - `keyof T` and `unique symbol` are not object types.
+ * - `DeepReadonly<T>`, `ReadonlyMap`, `ReadonlySet` and `ReadonlyRecord` are
+ *   readonly already.
+ */
+const staysOutsideReadonly = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: tsm.TypeNode,
+  deepReadonlyTypeName: string,
+): boolean => {
+  if (
+    node.isKind(tsm.SyntaxKind.FunctionType) ||
+    node.isKind(tsm.SyntaxKind.ConstructorType) ||
+    node.isKind(tsm.SyntaxKind.TypeLiteral) ||
+    node.isKind(tsm.SyntaxKind.TypeOperator)
+  ) {
+    return true;
+  }
+
+  if (node.isKind(tsm.SyntaxKind.TypeReference)) {
+    const typeName = node.getTypeName().getText();
+
+    return (
+      typeName === deepReadonlyTypeName ||
+      typeName === 'ReadonlyMap' ||
+      typeName === 'ReadonlySet' ||
+      typeName === 'ReadonlyRecord'
+    );
+  }
+
+  return false;
+};