ts-codemod-lib 4.0.0 → 4.0.1

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

@@ -157,8 +157,8 @@ export type ReadonlyTransformerOptions = DeepReadonly<{
 
   /**
    * 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.
+   * parameter property, which `mutablePropertyPrefixes` decides) and functions
+   * that are left mutable: their types are not made readonly.
    *
    * @default ['mut_']
    */
@@ -181,8 +181,8 @@ export type ReadonlyTransformerOptions = DeepReadonly<{
    * 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
+   * 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
@@ -245,6 +245,27 @@ const initialReadonlyContext: ReadonlyContext = {
   indexedAccessDepth: 0,
 } as const;
 
+/** 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;
+
 const transformNode = (
   node: tsm.Node,
   readonlyContext: ReadonlyContext,
@@ -484,6 +505,220 @@ const transformNode = (
 // Transformer implementation for each node type
 //
 
+/** Renders a readonly `Record<K, V>` in the configured record style. */
+const readonlyRecordText = (
+  keyText: string,
+  valueText: string,
+  options: ReadonlyTransformerOptionsInternal,
+): string =>
+  options.recordStyle === 'ReadonlyRecord'
+    ? (`ReadonlyRecord<${keyText}, ${valueText}>` as const)
+    : (`Readonly<Record<${keyText}, ${valueText}>>` as const);
+
+/**
+ * The comments in `[from, to)` of a source file, each followed by what keeps
+ * the next token off it, and nothing else in that range — no whitespace, and no
+ * token such as a separator or a parenthesis.
+ */
+const commentsBetween = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  sourceFile: tsm.SourceFile,
+  from: number,
+  to: number,
+): string => {
+  if (to <= from) {
+    return '';
+  }
+
+  const scanner = tsm.ts.createScanner(
+    tsm.ts.ScriptTarget.Latest,
+    false,
+    tsm.ts.LanguageVariant.Standard,
+    sourceFile.getFullText(),
+    undefined,
+    from,
+    to - from,
+  );
+
+  const mut_comments: string[] = [];
+
+  while (scanner.scan() !== tsm.ts.SyntaxKind.EndOfFileToken) {
+    const token = scanner.getToken();
+
+    // A line comment runs to the end of the line, so it takes one along.
+    const separator =
+      token === tsm.ts.SyntaxKind.SingleLineCommentTrivia
+        ? '\n'
+        : token === tsm.ts.SyntaxKind.MultiLineCommentTrivia
+          ? ' '
+          : undefined;
+
+    if (separator !== undefined) {
+      mut_comments.push(`${scanner.getTokenText()}${separator}`);
+    }
+  }
+
+  return mut_comments.join('');
+};
+
+/** `DeepReadonly<T>` |-> `T`, anything else |-> `undefined` */
+const getDeepReadonlyTypeArg = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  node: tsm.TypeNode,
+  deepReadonlyTypeName: string,
+): tsm.TypeNode | undefined => {
+  if (!node.isKind(tsm.SyntaxKind.TypeReference)) {
+    return undefined;
+  }
+
+  const typeName = node.getTypeName();
+
+  const typeArguments = node.getTypeArguments();
+
+  return typeName.isKind(tsm.SyntaxKind.Identifier) &&
+    typeName.getText() === deepReadonlyTypeName &&
+    Arr.isFixedLengthArray(1, typeArguments)
+    ? typeArguments[0]
+    : undefined;
+};
+
+const checkIfPropertyNameShouldBeIgnored = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  nameNode: tsm.PropertyName,
+  options: ReadonlyTransformerOptionsInternal,
+): boolean => {
+  expectType<typeof nameNode, tsm.PropertyName>('=');
+
+  expectType<
+    tsm.PropertyName,
+    | tsm.NumericLiteral
+    | tsm.BigIntLiteral
+    | tsm.NoSubstitutionTemplateLiteral
+    | tsm.Identifier
+    | tsm.StringLiteral
+    | tsm.PrivateIdentifier
+    | tsm.ComputedPropertyName // [`mut_x`]: number[]
+  >('=');
+
+  return (
+    // mut_x: number[]
+    (nameNode.isKind(tsm.SyntaxKind.Identifier) &&
+      pipe(nameNode.getText()).map((nm) =>
+        options.mutablePropertyPrefixes.some((p) => nm.startsWith(p)),
+      ).value) ||
+    // "mut_x": number[]
+    (nameNode.isKind(tsm.SyntaxKind.StringLiteral) &&
+      pipe(nameNode.getLiteralValue()).map((nm) =>
+        options.mutablePropertyPrefixes.some((p) => nm.startsWith(p)),
+      ).value) ||
+    //  #memberName: number[] (class only), matched with or after its `#`
+    (nameNode.isKind(tsm.SyntaxKind.PrivateIdentifier) &&
+      pipe(nameNode.getText()).map((nm) =>
+        options.mutablePropertyPrefixes.some(
+          (p) => nm.startsWith(p) || nm.startsWith(`#${p}`),
+        ),
+      ).value) ||
+    // ['mut_x']: number[], [`mut_x`]: number[]
+    (nameNode.isKind(tsm.SyntaxKind.ComputedPropertyName) &&
+      pipe(nameNode.getExpression()).map((exp) => {
+        if (
+          exp.isKind(tsm.SyntaxKind.StringLiteral) ||
+          exp.isKind(tsm.SyntaxKind.NoSubstitutionTemplateLiteral)
+        ) {
+          const nm = exp.getLiteralValue();
+
+          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);
+
 /**
  * - `tr(ReadonlyArray<E>) |-> readonly tr(E)[]`
  * - `tr(Readonly<Readonly<E>>) |-> Readonly<tr(E)>`
@@ -786,9 +1021,9 @@ const transformTypeReferenceNode = (
       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.
+      // 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(),
@@ -985,16 +1220,6 @@ const transformTypeReferenceNode = (
   }
 };
 
-/** Renders a readonly `Record<K, V>` in the configured record style. */
-const readonlyRecordText = (
-  keyText: string,
-  valueText: string,
-  options: ReadonlyTransformerOptionsInternal,
-): string =>
-  options.recordStyle === 'ReadonlyRecord'
-    ? (`ReadonlyRecord<${keyText}, ${valueText}>` as const)
-    : (`Readonly<Record<${keyText}, ${valueText}>>` as const);
-
 /** `tr(E[]) |-> tr(E)[]` */
 const transformArrayTypeNode = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -1481,185 +1706,58 @@ const transformUnionTypeNode = (
   transformUnionOrIntersectionTypeNodeImpl(node, readonlyContext, options, '|');
 };
 
-const transformUnionOrIntersectionTypeNodeImpl = (
+/**
+ * The text of `inner`, a type `removeParentheses` took out of `outer`, with the
+ * comments in `outer`'s full text in front of it — before the parentheses and
+ * inside them — and without the parentheses.
+ *
+ * `inner.getFullText()` would drop those before the parentheses, which are as
+ * much a part of `outer` as the rest of it.
+ */
+const textWithoutParentheses = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: tsm.IntersectionTypeNode | tsm.UnionTypeNode,
-  readonlyContext: StrictExclude<
-    ReadonlyContext,
-    Readonly<{ type: 'readonly'; indexedAccessDepth: SafeUintWithSmallInt }>
-  >,
-  options: ReadonlyTransformerOptionsInternal,
-  operator: '&' | '|',
-): void => {
-  const nextReadonlyContextValue = nextReadonlyContext({
-    currentReadonlyContext: readonlyContext,
-    nextReadonlyContextType: 'none',
-    indexedAccessDepthChange: 'keep',
-  });
-
-  // Recursive processing
-  for (const n of node.getTypeNodes() /* = [A, B] */) {
-    transformNode(n, nextReadonlyContextValue, options);
-  }
-
-  const newTypes = node.getTypeNodes();
-
-  const withLeadingComments = (
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    member: tsm.TypeNode,
-    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,
-      underReadonly,
-      deepReadonlyTypeName: options.DeepReadonly.typeName,
-      keptUnwrapped: (t) => wrapsTypeLiterals && takesOffReadonly(t, options),
-    });
-
-  options.debugPrint({ primitives, arraysAndTuples, typeLiterals, others });
-
-  // Separate empty type literals from non-empty ones when ignoreEmptyObjectTypes is true
-  const isEmptyTypeLiteral = (
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    n: tsm.TypeNode,
-  ): boolean =>
-    n.isKind(tsm.SyntaxKind.TypeLiteral) && Arr.isEmpty(n.getMembers());
-
-  const nonEmptyTypeLiterals =
-    typeLiterals === undefined
-      ? undefined
-      : options.ignoreEmptyObjectTypes
-        ? typeLiterals.nodes.filter((n) => !isEmptyTypeLiteral(n))
-        : typeLiterals.nodes;
-
-  const emptyTypeLiterals =
-    typeLiterals === undefined || !options.ignoreEmptyObjectTypes
-      ? undefined
-      : typeLiterals.nodes.filter(isEmptyTypeLiteral);
-
-  const typeLiteralsWrappedWithReadonly: readonly [] | readonly [string] =
-    nonEmptyTypeLiterals === undefined || Arr.isEmpty(nonEmptyTypeLiterals)
-      ? ([] as const)
-      : ([
-          unionToString({
-            types: nonEmptyTypeLiterals.map((n) =>
-              withLeadingComments(
-                n,
-                isMergeableReadonlyTypeReferenceNode(n, operator)
-                  ? // NOTE: Readonly<A & B> -> (A & B) (spliced into `|`)
-                    // NOTE: Readonly<A | B> -> A | B (spliced into `|`)
-                    readonlyTypeArgTextSplicedInto(n, operator)
-                  : n.isKind(tsm.SyntaxKind.TypeLiteral)
-                    ? n.getText()
-                    : // A member kept under `Readonly`; see `underReadonly`
-                      wrapWithParentheses(n.getText()),
-              ),
-            ),
-            op: operator,
-            wrapWithReadonly: wrapsTypeLiterals,
-          }),
-        ] as const);
-
-  // Sort by first occurrence (preserving the original union order as much as possible)
-  const sorted: readonly string[] = [
-    mapNullable(
-      primitives,
-      (a) =>
-        [
-          a.nodes.map((n) => withLeadingComments(n, n.getText())),
-          a.firstPosition,
-        ] as const,
-    ),
-    mapNullable(
-      arraysAndTuples,
-      (a) =>
-        [
-          a.nodes.map((n) => withLeadingComments(n, n.getText())),
-          a.firstPosition,
-        ] as const,
-    ),
-    nonEmptyTypeLiterals !== undefined && Arr.isNonEmpty(nonEmptyTypeLiterals)
-      ? mapNullable(
-          typeLiterals,
-          (a) => [typeLiteralsWrappedWithReadonly, a.firstPosition] as const,
-        )
-      : undefined,
-    emptyTypeLiterals !== undefined && Arr.isNonEmpty(emptyTypeLiterals)
-      ? mapNullable(
-          typeLiterals,
-          (a) =>
-            [
-              emptyTypeLiterals.map((n) => withLeadingComments(n, n.getText())),
-              // Use a position after non-empty type literals if they exist
-              a.firstPosition +
-                (nonEmptyTypeLiterals !== undefined &&
-                Arr.isNonEmpty(nonEmptyTypeLiterals)
-                  ? 0.5
-                  : 0),
-            ] as const,
-        )
-      : undefined,
-    mapNullable(
-      others,
-      (a) =>
-        [
-          // `&` is deliberately not merged, unlike `Readonly<A> & Readonly<B>`
-          // above. See `mergeDeepReadonlyUnionMembers` for why.
-          operator === '|'
-            ? mergeDeepReadonlyUnionMembers(
-                a.nodes,
-                options.DeepReadonly.typeName,
-                withLeadingComments,
-              )
-            : a.nodes.map((n) =>
-                withLeadingComments(n, wrapWithParentheses(n.getText())),
-              ),
-          a.firstPosition,
-        ] as const,
-    ),
-  ]
-    .filter((x) => x !== undefined)
-    .toSorted((a, b) => a[1] - b[1])
-    .flatMap((a) => a[0]);
+  outer: tsm.TypeNode,
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  inner: tsm.TypeNode,
+): string =>
+  `${commentsBetween(outer.getSourceFile(), outer.getPos(), inner.getStart())}${inner.getText()}` as const;
 
-  // Readonly<number & { x: X } & { y: Y } & readonly E[]>
-  // -> number & readonly E[] & Readonly<{ x: X } & { y: Y }>
+const unionToStringImpl = ({
+  types,
+  op,
+  wrapWithReadonly,
+}: Readonly<{
+  types: readonly string[];
+  op: '&' | '|';
+  wrapWithReadonly: boolean | string;
+}>): string =>
+  Arr.isEmpty(types)
+    ? 'never'
+    : Arr.isFixedLengthArray(1, types)
+      ? wrapWithReadonly === false
+        ? wrapWithParentheses(types[0])
+        : (`${isString(wrapWithReadonly) ? wrapWithReadonly : 'Readonly'}<${types[0]}>` as const)
+      : wrapWithReadonly === false
+        ? wrapWithParentheses(types.join(` ${op} `))
+        : (`${isString(wrapWithReadonly) ? wrapWithReadonly : 'Readonly'}<${types.join(` ${op} `)}>` as const);
 
-  // Readonly<number | { x: X } | { y: Y } | readonly E[]>
-  // -> number | readonly E[] | Readonly<{ x: X } | { y: Y }>
-  // Readonly<number & { x: X } & { y: Y } & readonly E[]>
-  // -> number & readonly E[] & Readonly<{ x: X } & { y: Y }>
+const unionToString = ({
+  types: typesRaw,
+  op,
+  wrapWithReadonly,
+}: Readonly<{
+  types: readonly string[];
+  op: '&' | '|';
+  wrapWithReadonly: boolean | string;
+}>): string => {
+  // The members are joined with a separator that supplies its own space, so
+  // whitespace left at a member's edge would accumulate: every run of the
+  // transformer would add one more space before every member but the first, and
+  // a file would never reach a fixed point. Trimming keeps the comments in
+  // front of a member, which are not whitespace.
+  const types = typesRaw.map((s) => s.trim());
 
-  // Readonly<number | { x: X } | { y: Y } | readonly E[]>
-  // -> number | readonly E[] | Readonly<{ x: X } | { y: Y }>
-  //
-  // NOTE: The result is wrapped in parentheses (via `unionToString`). This is
-  // intentional and required for precedence safety: without it, a member such
-  // as a function type (`() => T`), or a mix of `&` and `|`, or a `readonly`
-  // operator would produce invalid syntax when this node is spliced back in.
-  // Idempotency is guaranteed by `transformParenthesizedTypeNode`, which
-  // collapses the redundant nesting (`((X))` -> `(X)`) this wrapping can create
-  // — see the note there. That prevents the parentheses from growing without
-  // bound when a union/intersection sits inside a `ParenthesizedType`.
-  options.replaceNode(
-    node,
-    unionToString({ types: sorted, op: operator, wrapWithReadonly: false }),
-  );
+  return unionToStringImpl({ types, op, wrapWithReadonly });
 };
 
 /**
@@ -1775,10 +1873,10 @@ const isTypeArgumentOfReadonly = (
  * `replaceWithText` overwrites a node from its `getStart()`, so whatever lies
  * in front of that stays in the file by itself. With no leading `|` / `&`, the
  * first member starts there too, and its comments are the type's: repeating
- * them in the replacement would copy them once per run. Every other member
- * has a separator in front of it, and a comment before the separator belongs
- * to no member's full text, so it is gone once the separator is rewritten. It
- * goes with the member after it, like the comments after the separator.
+ * them in the replacement would copy them once per run. Every other member has
+ * a separator in front of it, and a comment before the separator belongs to no
+ * member's full text, so it is gone once the separator is rewritten. It goes
+ * with the member after it, like the comments after the separator.
  *
  * `member` may be the type inside a member's parentheses; the comments inside
  * them are collected too, and the parentheses are not.
@@ -1802,9 +1900,9 @@ const leadingCommentsOfMember = (
  * `Readonly<T>` |-> the text of `T`, to be spliced into a union (`|`) or an
  * intersection (`&`) of the members it is merged with.
  *
- * `T` is wrapped in parentheses for precedence safety (a function type
- * argument needs them), unless it is a union spliced into a union or an
- * intersection spliced into an intersection, which needs none.
+ * `T` is wrapped in parentheses for precedence safety (a function type argument
+ * needs them), unless it is a union spliced into a union or an intersection
+ * spliced into an intersection, which needs none.
  */
 const readonlyTypeArgTextSplicedInto = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -1824,127 +1922,187 @@ const readonlyTypeArgTextSplicedInto = (
     : unwrapReadonlyTypeArgText(node);
 };
 
-/**
- * The text of `inner`, a type `removeParentheses` took out of `outer`, with
- * the comments in `outer`'s full text in front of it — before the parentheses
- * and inside them — and without the parentheses.
- *
- * `inner.getFullText()` would drop those before the parentheses, which are
- * as much a part of `outer` as the rest of it.
- */
-const textWithoutParentheses = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  outer: tsm.TypeNode,
+const transformUnionOrIntersectionTypeNodeImpl = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  inner: tsm.TypeNode,
-): string =>
-  `${commentsBetween(outer.getSourceFile(), outer.getPos(), inner.getStart())}${inner.getText()}` as const;
+  node: tsm.IntersectionTypeNode | tsm.UnionTypeNode,
+  readonlyContext: StrictExclude<
+    ReadonlyContext,
+    Readonly<{ type: 'readonly'; indexedAccessDepth: SafeUintWithSmallInt }>
+  >,
+  options: ReadonlyTransformerOptionsInternal,
+  operator: '&' | '|',
+): void => {
+  const nextReadonlyContextValue = nextReadonlyContext({
+    currentReadonlyContext: readonlyContext,
+    nextReadonlyContextType: 'none',
+    indexedAccessDepthChange: 'keep',
+  });
 
-/**
- * The comments in `[from, to)` of a source file, each followed by what keeps
- * the next token off it, and nothing else in that range — no whitespace, and
- * no token such as a separator or a parenthesis.
- */
-const commentsBetween = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  sourceFile: tsm.SourceFile,
-  from: number,
-  to: number,
-): string => {
-  if (to <= from) {
-    return '';
+  // Recursive processing
+  for (const n of node.getTypeNodes() /* = [A, B] */) {
+    transformNode(n, nextReadonlyContextValue, options);
   }
 
-  const scanner = tsm.ts.createScanner(
-    tsm.ts.ScriptTarget.Latest,
-    false,
-    tsm.ts.LanguageVariant.Standard,
-    sourceFile.getFullText(),
-    undefined,
-    from,
-    to - from,
-  );
+  const newTypes = node.getTypeNodes();
 
-  const mut_comments: string[] = [];
+  const withLeadingComments = (
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    member: tsm.TypeNode,
+    memberText: string,
+  ): string => `${leadingCommentsOfMember(node, member)}${memberText}` as const;
 
-  while (scanner.scan() !== tsm.ts.SyntaxKind.EndOfFileToken) {
-    const token = scanner.getToken();
+  // 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;
 
-    // A line comment runs to the end of the line, so it takes one along.
-    const separator =
-      token === tsm.ts.SyntaxKind.SingleLineCommentTrivia
-        ? '\n'
-        : token === tsm.ts.SyntaxKind.MultiLineCommentTrivia
-          ? ' '
-          : undefined;
+  // `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);
 
-    if (separator !== undefined) {
-      mut_comments.push(`${scanner.getTokenText()}${separator}`);
-    }
-  }
+  const { primitives, arraysAndTuples, typeLiterals, others } =
+    groupUnionIntersectionTypes(newTypes, {
+      operator,
+      underReadonly,
+      deepReadonlyTypeName: options.DeepReadonly.typeName,
+      keptUnwrapped: (t) => wrapsTypeLiterals && takesOffReadonly(t, options),
+    });
 
-  return mut_comments.join('');
-};
+  options.debugPrint({ primitives, arraysAndTuples, typeLiterals, others });
 
-/** `DeepReadonly<T>` |-> `T`, anything else |-> `undefined` */
-const getDeepReadonlyTypeArg = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  node: tsm.TypeNode,
-  deepReadonlyTypeName: string,
-): tsm.TypeNode | undefined => {
-  if (!node.isKind(tsm.SyntaxKind.TypeReference)) {
-    return undefined;
-  }
+  // Separate empty type literals from non-empty ones when ignoreEmptyObjectTypes is true
+  const isEmptyTypeLiteral = (
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    n: tsm.TypeNode,
+  ): boolean =>
+    n.isKind(tsm.SyntaxKind.TypeLiteral) && Arr.isEmpty(n.getMembers());
 
-  const typeName = node.getTypeName();
+  const nonEmptyTypeLiterals =
+    typeLiterals === undefined
+      ? undefined
+      : options.ignoreEmptyObjectTypes
+        ? typeLiterals.nodes.filter((n) => !isEmptyTypeLiteral(n))
+        : typeLiterals.nodes;
 
-  const typeArguments = node.getTypeArguments();
+  const emptyTypeLiterals =
+    typeLiterals === undefined || !options.ignoreEmptyObjectTypes
+      ? undefined
+      : typeLiterals.nodes.filter(isEmptyTypeLiteral);
+
+  const typeLiteralsWrappedWithReadonly: readonly [] | readonly [string] =
+    nonEmptyTypeLiterals === undefined || Arr.isEmpty(nonEmptyTypeLiterals)
+      ? ([] as const)
+      : ([
+          unionToString({
+            types: nonEmptyTypeLiterals.map((n) =>
+              withLeadingComments(
+                n,
+                isMergeableReadonlyTypeReferenceNode(n, operator)
+                  ? // NOTE: Readonly<A & B> -> (A & B) (spliced into `|`)
+                    // NOTE: Readonly<A | B> -> A | B (spliced into `|`)
+                    readonlyTypeArgTextSplicedInto(n, operator)
+                  : n.isKind(tsm.SyntaxKind.TypeLiteral)
+                    ? n.getText()
+                    : // A member kept under `Readonly`; see `underReadonly`
+                      wrapWithParentheses(n.getText()),
+              ),
+            ),
+            op: operator,
+            wrapWithReadonly: wrapsTypeLiterals,
+          }),
+        ] as const);
+
+  // Sort by first occurrence (preserving the original union order as much as possible)
+  const sorted: readonly string[] = [
+    mapNullable(
+      primitives,
+      (a) =>
+        [
+          a.nodes.map((n) => withLeadingComments(n, n.getText())),
+          a.firstPosition,
+        ] as const,
+    ),
+    mapNullable(
+      arraysAndTuples,
+      (a) =>
+        [
+          a.nodes.map((n) => withLeadingComments(n, n.getText())),
+          a.firstPosition,
+        ] as const,
+    ),
+    nonEmptyTypeLiterals !== undefined && Arr.isNonEmpty(nonEmptyTypeLiterals)
+      ? mapNullable(
+          typeLiterals,
+          (a) => [typeLiteralsWrappedWithReadonly, a.firstPosition] as const,
+        )
+      : undefined,
+    emptyTypeLiterals !== undefined && Arr.isNonEmpty(emptyTypeLiterals)
+      ? mapNullable(
+          typeLiterals,
+          (a) =>
+            [
+              emptyTypeLiterals.map((n) => withLeadingComments(n, n.getText())),
+              // Use a position after non-empty type literals if they exist
+              a.firstPosition +
+                (nonEmptyTypeLiterals !== undefined &&
+                Arr.isNonEmpty(nonEmptyTypeLiterals)
+                  ? 0.5
+                  : 0),
+            ] as const,
+        )
+      : undefined,
+    mapNullable(
+      others,
+      (a) =>
+        [
+          // `&` is deliberately not merged, unlike `Readonly<A> & Readonly<B>`
+          // above. See `mergeDeepReadonlyUnionMembers` for why.
+          operator === '|'
+            ? mergeDeepReadonlyUnionMembers(
+                a.nodes,
+                options.DeepReadonly.typeName,
+                withLeadingComments,
+              )
+            : a.nodes.map((n) =>
+                withLeadingComments(n, wrapWithParentheses(n.getText())),
+              ),
+          a.firstPosition,
+        ] as const,
+    ),
+  ]
+    .filter((x) => x !== undefined)
+    .toSorted((a, b) => a[1] - b[1])
+    .flatMap((a) => a[0]);
 
-  return typeName.isKind(tsm.SyntaxKind.Identifier) &&
-    typeName.getText() === deepReadonlyTypeName &&
-    Arr.isFixedLengthArray(1, typeArguments)
-    ? typeArguments[0]
-    : undefined;
-};
+  // Readonly<number & { x: X } & { y: Y } & readonly E[]>
+  // -> number & readonly E[] & Readonly<{ x: X } & { y: Y }>
 
-const unionToString = ({
-  types: typesRaw,
-  op,
-  wrapWithReadonly,
-}: Readonly<{
-  types: readonly string[];
-  op: '&' | '|';
-  wrapWithReadonly: boolean | string;
-}>): string => {
-  // The members are joined with a separator that supplies its own space, so
-  // whitespace left at a member's edge would accumulate: every run of the
-  // transformer would add one more space before every member but the first,
-  // and a file would never reach a fixed point. Trimming keeps the comments in
-  // front of a member, which are not whitespace.
-  const types = typesRaw.map((s) => s.trim());
+  // Readonly<number | { x: X } | { y: Y } | readonly E[]>
+  // -> number | readonly E[] | Readonly<{ x: X } | { y: Y }>
+  // Readonly<number & { x: X } & { y: Y } & readonly E[]>
+  // -> number & readonly E[] & Readonly<{ x: X } & { y: Y }>
 
-  return unionToStringImpl({ types, op, wrapWithReadonly });
+  // Readonly<number | { x: X } | { y: Y } | readonly E[]>
+  // -> number | readonly E[] | Readonly<{ x: X } | { y: Y }>
+  //
+  // NOTE: The result is wrapped in parentheses (via `unionToString`). This is
+  // intentional and required for precedence safety: without it, a member such
+  // as a function type (`() => T`), or a mix of `&` and `|`, or a `readonly`
+  // operator would produce invalid syntax when this node is spliced back in.
+  // Idempotency is guaranteed by `transformParenthesizedTypeNode`, which
+  // collapses the redundant nesting (`((X))` -> `(X)`) this wrapping can create
+  // — see the note there. That prevents the parentheses from growing without
+  // bound when a union/intersection sits inside a `ParenthesizedType`.
+  options.replaceNode(
+    node,
+    unionToString({ types: sorted, op: operator, wrapWithReadonly: false }),
+  );
 };
 
-const unionToStringImpl = ({
-  types,
-  op,
-  wrapWithReadonly,
-}: Readonly<{
-  types: readonly string[];
-  op: '&' | '|';
-  wrapWithReadonly: boolean | string;
-}>): string =>
-  Arr.isEmpty(types)
-    ? 'never'
-    : Arr.isFixedLengthArray(1, types)
-      ? wrapWithReadonly === false
-        ? wrapWithParentheses(types[0])
-        : (`${isString(wrapWithReadonly) ? wrapWithReadonly : 'Readonly'}<${types[0]}>` as const)
-      : wrapWithReadonly === false
-        ? wrapWithParentheses(types.join(` ${op} `))
-        : (`${isString(wrapWithReadonly) ? wrapWithReadonly : 'Readonly'}<${types.join(` ${op} `)}>` as const);
-
 /** Convert ((T)) -> (T) recursively */
 const transformParenthesizedTypeNode = (
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -1964,20 +2122,16 @@ const transformParenthesizedTypeNode = (
   const T = node.getTypeNode();
 
   if (
-    // remove () if T is TypeReferenceNode
-    // e.g. `(Readonly<A>) |-> Readonly<A>`
+    // remove () if T is TypeReferenceNode e.g. `(Readonly<A>) |-> Readonly<A>`
     T.isKind(tsm.SyntaxKind.TypeReference) ||
-    // remove () if T is ArrayTypeNode
-    // e.g. `(A[]) |-> A[]`
+    // remove () if T is ArrayTypeNode e.g. `(A[]) |-> A[]`
     T.isKind(tsm.SyntaxKind.ArrayType) ||
-    // remove () if T is TupleTypeNode
-    // e.g. `([A]) |-> [A]`
+    // remove () if T is TupleTypeNode e.g. `([A]) |-> [A]`
     T.isKind(tsm.SyntaxKind.TupleType) ||
-    // remove () if T is PrimitiveTypeNode
-    // e.g. `(number) |-> number`
+    // remove () if T is PrimitiveTypeNode e.g. `(number) |-> number`
     isAtomicTypeNode(T) ||
-    // remove () if T is TypeLiteralNode
-    // e.g. `({ member: V }) |-> { member: V }`
+    // remove () if T is TypeLiteralNode e.g.
+    // `({ member: V }) |-> { member: V }`
     T.isKind(tsm.SyntaxKind.TypeLiteral) ||
     // collapse redundant nested parentheses if T is itself a ParenthesizedType
     // e.g. `((X)) |-> (X)`
@@ -2134,161 +2288,3 @@ const transformIndexSignatureDeclaration = (
     }
   }
 };
-
-const checkIfPropertyNameShouldBeIgnored = (
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  nameNode: tsm.PropertyName,
-  options: ReadonlyTransformerOptionsInternal,
-): boolean => {
-  expectType<typeof nameNode, tsm.PropertyName>('=');
-
-  expectType<
-    tsm.PropertyName,
-    | tsm.NumericLiteral
-    | tsm.BigIntLiteral
-    | tsm.NoSubstitutionTemplateLiteral
-    | tsm.Identifier
-    | tsm.StringLiteral
-    | tsm.PrivateIdentifier
-    | tsm.ComputedPropertyName // [`mut_x`]: number[]
-  >('=');
-
-  return (
-    // mut_x: number[]
-    (nameNode.isKind(tsm.SyntaxKind.Identifier) &&
-      pipe(nameNode.getText()).map((nm) =>
-        options.mutablePropertyPrefixes.some((p) => nm.startsWith(p)),
-      ).value) ||
-    // "mut_x": number[]
-    (nameNode.isKind(tsm.SyntaxKind.StringLiteral) &&
-      pipe(nameNode.getLiteralValue()).map((nm) =>
-        options.mutablePropertyPrefixes.some((p) => nm.startsWith(p)),
-      ).value) ||
-    //  #memberName: number[] (class only), matched with or after its `#`
-    (nameNode.isKind(tsm.SyntaxKind.PrivateIdentifier) &&
-      pipe(nameNode.getText()).map((nm) =>
-        options.mutablePropertyPrefixes.some(
-          (p) => nm.startsWith(p) || nm.startsWith(`#${p}`),
-        ),
-      ).value) ||
-    // ['mut_x']: number[], [`mut_x`]: number[]
-    (nameNode.isKind(tsm.SyntaxKind.ComputedPropertyName) &&
-      pipe(nameNode.getExpression()).map((exp) => {
-        if (
-          exp.isKind(tsm.SyntaxKind.StringLiteral) ||
-          exp.isKind(tsm.SyntaxKind.NoSubstitutionTemplateLiteral)
-        ) {
-          const nm = exp.getLiteralValue();
-
-          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;