ts-codemod-lib 2.2.0 → 2.2.2

package/src/cmd/convert-to-readonly.mts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import * as cmd from 'cmd-ts';
-import { Result } from 'ts-data-forge';
+import { Arr, Result } from 'ts-data-forge';
 import { convertToReadonlyTransformer } from '../functions/index.mjs';
 import { runTransformerCLI } from './run-transformer-cli.mjs';
 
@@ -9,7 +9,7 @@ const transformer = convertToReadonlyTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.2.0',
+  version: '2.2.2',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,
@@ -64,4 +64,4 @@ const cmdDef = cmd.command({
   },
 });
 
-await cmd.run(cmdDef, process.argv.slice(2));
+await cmd.run(cmdDef, Arr.skip(process.argv, 2));

package/src/cmd/replace-any-with-unknown.mts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import * as cmd from 'cmd-ts';
-import { Result } from 'ts-data-forge';
+import { Arr, Result } from 'ts-data-forge';
 import { replaceAnyWithUnknownTransformer } from '../functions/index.mjs';
 import { runTransformerCLI } from './run-transformer-cli.mjs';
 
@@ -9,7 +9,7 @@ const transformer = replaceAnyWithUnknownTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.2.0',
+  version: '2.2.2',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,
@@ -64,4 +64,4 @@ const cmdDef = cmd.command({
   },
 });
 
-await cmd.run(cmdDef, process.argv.slice(2));
+await cmd.run(cmdDef, Arr.skip(process.argv, 2));

package/src/cmd/replace-record-with-unknown-record.mts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import * as cmd from 'cmd-ts';
-import { Result } from 'ts-data-forge';
+import { Arr, Result } from 'ts-data-forge';
 import { replaceRecordWithUnknownRecordTransformer } from '../functions/index.mjs';
 import { runTransformerCLI } from './run-transformer-cli.mjs';
 
@@ -9,7 +9,7 @@ const transformer = replaceRecordWithUnknownRecordTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.2.0',
+  version: '2.2.2',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,
@@ -64,4 +64,4 @@ const cmdDef = cmd.command({
   },
 });
 
-await cmd.run(cmdDef, process.argv.slice(2));
+await cmd.run(cmdDef, Arr.skip(process.argv, 2));

package/src/cmd/run-transformer-cli.mts

@@ -3,7 +3,7 @@
 import dedent from 'dedent';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { Arr, Result, unknownToString } from 'ts-data-forge';
+import { Arr, expectType, Result, unknownToString } from 'ts-data-forge';
 import {
   getDiffFrom,
   getModifiedFiles,
@@ -199,8 +199,16 @@ const getFilesFromGlob = async (
   >
 > => {
   const globResult = await glob(baseDir, {
-    ignore: exclude,
+    // Never transform files inside dependencies. With pnpm,
+    // `packages/*/node_modules/<dep>` are symlinks whose `src/` directory would
+    // otherwise be matched by patterns such as
+    // `packages/**/{src,scripts,samples,test}/**`, so the codemod would rewrite
+    // dependency source files (and could hit pathological types there).
+    ignore: Arr.toPushed(exclude, '**/node_modules/**'),
     absolute: true,
+    // Do not escape the project tree by following symlinks (e.g. the pnpm
+    // `node_modules` symlinks above, or workspace-package links).
+    followSymbolicLinks: false,
   });
 
   if (Result.isErr(globResult)) {
@@ -235,16 +243,12 @@ const transformFiles = async (
     const result = await transformOneFile(filePath, transformers, silent);
 
     if (Result.isOk(result)) {
-      switch (result.value) {
-        case 'transformed':
-          mut_transformedCount += 1;
+      expectType<typeof result.value, 'unchanged' | 'transformed'>('=');
 
-          break;
-
-        case 'unchanged':
-          mut_unchangedCount += 1;
-
-          break;
+      if (result.value === 'transformed') {
+        mut_transformedCount += 1;
+      } else {
+        mut_unchangedCount += 1;
       }
     } else {
       mut_errorFiles.push(path.basename(filePath));
@@ -285,14 +289,14 @@ const transformOneFile = async (
       echoIfNotSilent(`⏭️ ${fileName} - no changes needed`);
 
       return Result.ok('unchanged');
-    } else {
-      // eslint-disable-next-line security/detect-non-literal-fs-filename
-      await fs.writeFile(filePath, transformedCode, 'utf8');
+    }
 
-      echoIfNotSilent(`✅ ${fileName} - transformed`);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(filePath, transformedCode, 'utf8');
 
-      return Result.ok('transformed');
-    }
+    echoIfNotSilent(`✅ ${fileName} - transformed`);
+
+    return Result.ok('transformed');
   } catch (error) {
     const errStr = unknownToString(error);
 

package/src/functions/ast-transformers/convert-interface-to-type.mts

@@ -70,7 +70,7 @@ export const convertInterfaceToTypeTransformer = (): TsMorphTransformer =>
 
           const ownType = buildTypeLiteral(members);
 
-          return [...extendedTypesWithMembers, ownType].join(' & ');
+          return Arr.toPushed(extendedTypesWithMembers, ownType).join(' & ');
         })();
 
         // Get export keyword

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

@@ -12,6 +12,7 @@ import { type DeepReadonly, type SafeUintWithSmallInt } from 'ts-type-forge';
 import {
   hasDisableNextLineComment,
   isAtomicTypeNode,
+  isConditionalTypeDistributionGuard,
   isReadonlyArrayTypeNode,
   isReadonlyTupleOrArrayTypeNode,
   isReadonlyTupleTypeNode,
@@ -705,7 +706,12 @@ const transformArrayTypeNode = (
     // Unnecessary `Readonly` wrapper will be remove in transformTypeReferenceNode
     case 'Readonly':
     case 'none':
-      if (readonlyContext.indexedAccessDepth === 0) {
+      // Skip the `A[] extends B[] ? ...` union-distribution-guard idiom: adding
+      // `readonly` there does not improve immutability and breaks the idiom.
+      if (
+        readonlyContext.indexedAccessDepth === 0 &&
+        !isConditionalTypeDistributionGuard(node)
+      ) {
         const readonlyText = `readonly ${node.getFullText()}` as const;
 
         options.replaceNode(
@@ -752,7 +758,12 @@ const transformTupleTypeNode = (
     // Unnecessary `Readonly` wrapper will be remove in transformTypeReferenceNode
     case 'Readonly':
     case 'none':
-      if (readonlyContext.indexedAccessDepth === 0) {
+      // Skip the `[A] extends [B] ? ...` union-distribution-guard idiom: adding
+      // `readonly` there does not improve immutability and breaks the idiom.
+      if (
+        readonlyContext.indexedAccessDepth === 0 &&
+        !isConditionalTypeDistributionGuard(node)
+      ) {
         const readonlyText = `readonly ${node.getFullText()}` as const;
 
         options.replaceNode(
@@ -1043,50 +1054,54 @@ const transformClassDeclarationNode = (
 
   for (const ctor of node.getConstructors()) {
     for (const param of ctor.getParameters()) {
-      if (hasDisableNextLineComment(param)) {
-        options.debugPrint(
-          'skipped class constructor parameter by disable-next-line comment',
-        );
+      transformConstructorParameter(param, options);
+    }
 
-        continue;
-      }
+    const body = ctor.getBody();
 
-      {
-        const name = (param satisfies tsm.ParameterDeclaration).getName();
+    if (body !== undefined) {
+      transformNode(body, initialReadonlyContext, options);
+    }
+  }
+};
 
-        if (options.ignoredPrefixes.some((p) => name.startsWith(p))) {
-          continue;
-        }
-      }
+const transformConstructorParameter = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  param: tsm.ParameterDeclaration,
+  options: ReadonlyTransformerOptionsInternal,
+): void => {
+  if (hasDisableNextLineComment(param)) {
+    options.debugPrint(
+      'skipped class constructor parameter by disable-next-line comment',
+    );
 
-      // Check if parameter is a property declaration (public/protected/private)
-      const scope = param.getScope();
+    return;
+  }
 
-      // public -> public readonly
-      // protected -> protected readonly
-      // private -> private readonly
-      if (
-        scope === tsm.Scope.Public ||
-        scope === tsm.Scope.Protected ||
-        scope === tsm.Scope.Private
-      ) {
-        param.setIsReadonly(true);
-      }
+  const name = param.getName();
 
-      const type = param.getTypeNode();
+  if (options.ignoredPrefixes.some((p) => name.startsWith(p))) {
+    return;
+  }
 
-      if (type !== undefined) {
-        transformNode(type, initialReadonlyContext, options);
-      }
-    }
+  // Check if parameter is a property declaration (public/protected/private)
+  const scope = param.getScope();
 
-    const body = ctor.getBody();
+  // public -> public readonly
+  // protected -> protected readonly
+  // private -> private readonly
+  if (
+    scope === tsm.Scope.Public ||
+    scope === tsm.Scope.Protected ||
+    scope === tsm.Scope.Private
+  ) {
+    param.setIsReadonly(true);
+  }
 
-    if (body !== undefined) {
-      transformNode(body, initialReadonlyContext, options);
-    }
+  const type = param.getTypeNode();
 
-    continue;
+  if (type !== undefined) {
+    transformNode(type, initialReadonlyContext, options);
   }
 };
 
@@ -1238,6 +1253,20 @@ const transformUnionOrIntersectionTypeNodeImpl = (
 
   // 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 }>
+
+  // 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 }),
@@ -1296,7 +1325,18 @@ const transformParenthesizedTypeNode = (
     isAtomicTypeNode(T) ||
     // remove () if T is TypeLiteralNode
     // e.g. `({ member: V }) |-> { member: V }`
-    T.isKind(tsm.SyntaxKind.TypeLiteral)
+    T.isKind(tsm.SyntaxKind.TypeLiteral) ||
+    // collapse redundant nested parentheses if T is itself a ParenthesizedType
+    // e.g. `((X)) |-> (X)`
+    //
+    // This is what makes the transform terminate on nested parentheses. The
+    // union/intersection handler defensively wraps its result in parentheses
+    // for precedence safety, which turns `(A | B)` into `((A | B))` when the
+    // union already sits inside a `ParenthesizedType`. Collapsing the redundant
+    // outer layer here means each pass removes exactly the layer the wrapping
+    // added, so the parentheses no longer grow without bound (which previously
+    // overflowed the parser stack on inputs like `type T = (('a' | 'b'))`).
+    T.isKind(tsm.SyntaxKind.ParenthesizedType)
   ) {
     options.replaceNode(node, T.getFullText());
   }

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

@@ -59,7 +59,10 @@ const normalizeWhitespaceForComparison = (code: string): string => {
   const placeholder = '___LINE_COMMENT_NEWLINE_PLACEHOLDER___';
 
   // 1. Protect newlines immediately following line comments
-  const protectedCode = code.replaceAll(/(\/\/.*?)\r?\n/gu, `$1${placeholder}`);
+  const protectedCode = code.replaceAll(
+    /(\/\/.*?)\r?\n/gu,
+    (_match, comment: string) => `${comment}${placeholder}`,
+  );
 
   // 2. Collapse multiple whitespace characters (including unprotected newlines) into a single space
   const collapsedCode = protectedCode.replaceAll(/\s+/gu, ' ');
@@ -738,6 +741,56 @@ describe(convertToReadonlyTransformer, () => {
       },
     ])('$name', testFn);
 
+    describe('Conditional type union-distribution-guard idiom', () => {
+      test.each([
+        {
+          name: 'Single-element tuples in check and extends positions are left as-is',
+          source: dedent`
+            type TypeExtends<A, B> = [A] extends [B] ? true : false;
+          `,
+          expected: dedent`
+            type TypeExtends<A, B> = [A] extends [B] ? true : false;
+          `,
+        },
+        {
+          name: 'Multi-element guard tuples are left as-is',
+          source: dedent`
+            type Eq<A, B> = [A, B] extends [B, A] ? true : false;
+          `,
+          expected: dedent`
+            type Eq<A, B> = [A, B] extends [B, A] ? true : false;
+          `,
+        },
+        {
+          name: 'Tuples in true/false branches are still converted',
+          source: dedent`
+            type T<A> = [A] extends [string] ? [A, A] : [number];
+          `,
+          expected: dedent`
+            type T<A> = [A] extends [string] ? readonly [A, A] : readonly [number];
+          `,
+        },
+        {
+          name: 'Arrays in check and extends positions are left as-is',
+          source: dedent`
+            type ArrayExtends<A, B> = A[] extends B[] ? true : false;
+          `,
+          expected: dedent`
+            type ArrayExtends<A, B> = A[] extends B[] ? true : false;
+          `,
+        },
+        {
+          name: 'Arrays in true/false branches are still converted',
+          source: dedent`
+            type T<A> = A[] extends string[] ? A[] : number[];
+          `,
+          expected: dedent`
+            type T<A> = A[] extends string[] ? readonly A[] : readonly number[];
+          `,
+        },
+      ])('$name', testFn);
+    });
+
     describe('Rest types', () => {
       test.each([
         {
@@ -2574,6 +2627,69 @@ describe(convertToReadonlyTransformer, () => {
           type ParenReadonly = Readonly<{ a: number }>
         `,
       },
+      {
+        // Regression: redundant nested parentheses around a union used to make
+        // the transformer re-wrap the union on every pass, growing parentheses
+        // without bound until ts-morph's parser overflowed its stack (hang).
+        name: 'Doubled parentheses around a union (no infinite paren growth)',
+        source: dedent`
+          type DoubleParenUnion = (('a' | 'b'));
+        `,
+        expected: dedent`
+          type DoubleParenUnion = 'a' | 'b';
+        `,
+      },
+      {
+        name: 'Doubled parentheses around an object union (no infinite paren growth)',
+        source: dedent`
+          type DoubleParenObjUnion = (({ a: number[] } | { b: string[] }));
+        `,
+        expected: dedent`
+          type DoubleParenObjUnion = Readonly<
+            { a: readonly number[] } | { b: readonly string[] }
+          >;
+        `,
+      },
+      {
+        name: 'Doubled parentheses around a union in a conditional type (no infinite paren growth)',
+        source: dedent`
+          type DoubleParenCond = true extends true ? (('a' | 'b')) : 'c';
+        `,
+        expected: dedent`
+          type DoubleParenCond = true extends true ? 'a' | 'b' : 'c';
+        `,
+      },
+      {
+        // Precedence guard: the defensive parentheses around a union/intersection
+        // must NOT be dropped. A function type used as a union member is invalid
+        // TypeScript unless parenthesized (`string | () => number` is a syntax
+        // error), so the wrapping has to survive the transform.
+        name: 'Function type in a union stays parenthesized (precedence)',
+        source: dedent`
+          type FnUnion = string | (() => number);
+        `,
+        expected: dedent`
+          type FnUnion = string | (() => number);
+        `,
+      },
+      {
+        name: 'Bare function type in a union is parenthesized (precedence)',
+        source: dedent`
+          type FnUnionBare = string | () => number;
+        `,
+        expected: dedent`
+          type FnUnionBare = string | (() => number);
+        `,
+      },
+      {
+        name: 'Mixed & and | keeps precedence parentheses',
+        source: dedent`
+          type Mixed = number & { a: string } | { b: number };
+        `,
+        expected: dedent`
+          type Mixed = (number & Readonly<{ a: string }>) | Readonly<{ b: number }>;
+        `,
+      },
     ])('$name', testFn);
   });
 

package/src/functions/ast-transformers/readonly-transformer-helpers/readonly-context.mts

@@ -15,12 +15,12 @@ import { type SafeUintWithSmallInt } from 'ts-type-forge';
  * - `"none"`: All other cases
  */
 export type ReadonlyContext = Readonly<
-  { indexedAccessDepth: SafeUintWithSmallInt } & (
+  (
     | { type: 'DeepReadonly' }
     | { type: 'Readonly' }
     | { type: 'readonly' }
     | { type: 'none' }
-  )
+  ) & { indexedAccessDepth: SafeUintWithSmallInt }
 >;
 
 export const nextReadonlyContext = <
@@ -31,9 +31,7 @@ export const nextReadonlyContext = <
   nextReadonlyContextType: next,
   indexedAccessDepthChange = 'infinity',
 }: Readonly<
-  {
-    currentReadonlyContext: Curr;
-  } & (
+  (
     | {
         nextReadonlyContextType: Next;
         indexedAccessDepthChange: 'decr' | 'incr' | 'keep' | 'infinity';
@@ -45,7 +43,9 @@ export const nextReadonlyContext = <
         >;
         indexedAccessDepthChange?: 'infinity';
       }
-  )
+  ) & {
+    currentReadonlyContext: Curr;
+  }
 >): Readonly<{
   type: Extract<ReadonlyContext['type'], 'DeepReadonly'> | Next;
   indexedAccessDepth: SafeUintWithSmallInt;

package/src/functions/ast-transformers/replace-record-with-unknown-record.mts

@@ -23,12 +23,12 @@ export const replaceRecordWithUnknownRecordTransformer =
     ({
       name: TRANSFORMER_NAME,
       transform: (sourceAst) => {
-        const containerModifications = [
-          processDeclarations(sourceAst),
-          ...sourceAst
+        const containerModifications = Arr.toUnshifted(
+          sourceAst
             .getModules()
             .map((namespace) => processDeclarations(namespace)),
-        ];
+          processDeclarations(sourceAst),
+        );
 
         if (containerModifications.includes(true)) {
           ensureUnknownRecordImport(sourceAst);

package/src/functions/functions/has-disable-next-line-comment.mts

@@ -52,17 +52,17 @@ export const hasDisableNextLineComment = (
         );
 
         if (matchedPrefix !== undefined) {
+          // If no transformer name specified, check if comment applies to all transformers
+          if (transformerName === undefined) {
+            return true;
+          }
+
           // Extract the part after the prefix
           const afterPrefix = commentText
             .slice(commentText.indexOf(matchedPrefix))
             .replace(matchedPrefix, '')
             .trim();
 
-          // If no transformer name specified, check if comment applies to all transformers
-          if (transformerName === undefined) {
-            return true;
-          }
-
           // If no specific transformers listed in comment, it applies to all
           if (afterPrefix === '') {
             return true;

package/src/functions/functions/index.mts

@@ -1,6 +1,7 @@
 export * from './has-disable-next-line-comment.mjs';
 export * from './is-as-const-node.mjs';
 export * from './is-atomic-type-node.mjs';
+export * from './is-conditional-type-distribution-guard.mjs';
 export * from './is-readonly-node.mjs';
 export * from './is-spread-parameter-node.mjs';
 export * from './remove-parentheses.mjs';

package/src/functions/functions/is-conditional-type-distribution-guard.mts

@@ -0,0 +1,45 @@
+import * as tsm from 'ts-morph';
+
+/**
+ * Determines whether a type node is an operand (check or extends type) of a
+ * conditional type whose check type is wrapped to suppress union distribution,
+ * i.e. the `X` and `Y` in `X extends Y ? ... : ...` where `X` is itself a tuple
+ * or array.
+ *
+ * Wrapping a naked type parameter so that it is no longer naked is a well-known
+ * type-implementation idiom used to suppress union distribution. Both
+ * `[A] extends [B] ? ...` (tuple wrapping) and `A[] extends B[] ? ...` (array
+ * wrapping) rely on this. Adding a `readonly` modifier to those operands neither
+ * makes the type more immutable in any meaningful way nor preserves the idiom's
+ * intent, so such operands must be left untouched.
+ *
+ * A naked check type such as `T extends string[] ? ...` still distributes, so it
+ * is not a guard; arrays/tuples in its extends position are converted as usual.
+ *
+ * @param node - The type node to check
+ * @returns true if the node is the check or extends type of a distribution-guarded
+ *   conditional type
+ */
+export const isConditionalTypeDistributionGuard = (node: tsm.Node): boolean => {
+  const parent = node.getParent();
+
+  if (parent?.isKind(tsm.SyntaxKind.ConditionalType) !== true) {
+    return false;
+  }
+
+  const checkType = parent.getCheckType();
+
+  // The guard is only in effect when the check type itself is wrapped in a tuple
+  // or array; otherwise (e.g. a naked `T`) the conditional still distributes.
+  if (
+    !checkType.isKind(tsm.SyntaxKind.TupleType) &&
+    !checkType.isKind(tsm.SyntaxKind.ArrayType)
+  ) {
+    return false;
+  }
+
+  return (
+    checkType.compilerNode === node.compilerNode ||
+    parent.getExtendsType().compilerNode === node.compilerNode
+  );
+};

package/src/functions/functions/wrap-with-parentheses.mts

@@ -10,6 +10,19 @@
  */
 import { asUint32, range } from 'ts-data-forge';
 
+const parenDepthDelta = (char: string): number => {
+  switch (char) {
+    case '(':
+      return 1;
+
+    case ')':
+      return -1;
+
+    default:
+      return 0;
+  }
+};
+
 const isWrappedWithParentheses = (str: string): boolean => {
   const trimmed = str.trim();
 
@@ -22,30 +35,11 @@ const isWrappedWithParentheses = (str: string): boolean => {
   let mut_depth = 0;
 
   for (const mut_i of range(0, asUint32(trimmed.length))) {
-    const char: string = trimmed.charAt(mut_i);
-
-    switch (char) {
-      case '(': {
-        mut_depth += 1;
-
-        break;
-      }
-
-      case ')': {
-        mut_depth -= 1;
-
-        // If we reach depth 0 before the end, the outer parentheses don't wrap everything
-        if (mut_depth === 0 && mut_i < trimmed.length - 1) {
-          return false;
-        }
-
-        break;
-      }
+    mut_depth += parenDepthDelta(trimmed.charAt(mut_i));
 
-      default: {
-        // Other characters - no action needed
-        break;
-      }
+    // If we reach depth 0 before the end, the outer parentheses don't wrap everything
+    if (mut_depth === 0 && mut_i < trimmed.length - 1) {
+      return false;
     }
   }