ts-codemod-lib 3.5.0 → 4.0.0

package/dist/functions/constants/mutable-prefixes.d.mts

@@ -0,0 +1,23 @@
+/**
+ * The default `mutableVariablePrefixes` and `mutablePropertyPrefixes` of the
+ * transformers: a name that starts with one of these is left mutable. A
+ * private name (`#mut_x`) is matched with or after its `#`.
+ *
+ * The ESLint counterpart is `ignoredMutablePattern` in
+ * `libs/eslint-config-typed/src/rules/eslint-functional-rules.mts` (and, for a
+ * property, the `ignoreAccessorPattern` of `functional/immutable-data` there);
+ * `libs/eslint-config-typed/src/rules/eslint-functional-rules.test.mts` fails
+ * when the two differ; it reads this package's `dist/`, so build first.
+ */
+export declare const DEFAULT_MUTABLE_PREFIXES: readonly string[];
+/**
+ * The default `mutableTypePrefixes` of the transformers: a type alias, an
+ * interface or a class whose name starts with one of these is left mutable,
+ * and `append-as-const` adds no `as const` where the value has to be
+ * assignable to it (an annotated variable, `satisfies`, an arrow's return).
+ * `Mutable` suits the PascalCase of type names; `mut_` is accepted as for
+ * variables. No ESLint rule reads type names, so there is no counterpart to
+ * keep in step.
+ */
+export declare const DEFAULT_MUTABLE_TYPE_PREFIXES: readonly string[];
+//# sourceMappingURL=mutable-prefixes.d.mts.map

package/dist/functions/constants/mutable-prefixes.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutable-prefixes.d.mts","sourceRoot":"","sources":["../../../src/functions/constants/mutable-prefixes.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAEpD,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAGzD,CAAC"}

package/dist/functions/constants/mutable-prefixes.mjs

@@ -0,0 +1,28 @@
+
+
+
+
+
+
+
+
+
+
+
+export const DEFAULT_MUTABLE_PREFIXES = Object.freeze([
+    'mut_',
+]);
+
+
+
+
+
+
+
+
+
+export const DEFAULT_MUTABLE_TYPE_PREFIXES = Object.freeze([
+    'Mutable',
+    'mut_',
+]);
+//# sourceMappingURL=mutable-prefixes.mjs.map

package/dist/functions/constants/mutable-prefixes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutable-prefixes.mjs","sourceRoot":"","sources":["../../../src/functions/constants/mutable-prefixes.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACvE,MAAM;CACP,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC5E,SAAS;IACT,MAAM;CACP,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-codemod-lib",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "private": false,
   "keywords": [
     "typescript",
@@ -38,27 +38,27 @@
     "LICENSE"
   ],
   "dependencies": {
-    "ts-data-forge": "^14.8.0",
+    "ts-data-forge": "^14.10.0",
     "ts-morph": "^28.0.0",
     "ts-type-forge": "^9.2.2"
   },
   "devDependencies": {
-    "@types/node": "26.6.4",
-    "@vitest/browser-playwright": "5.0.3",
-    "@vitest/coverage-v8": "5.0.3",
-    "@vitest/ui": "5.0.3",
-    "cspell": "10.3.6",
+    "@types/node": "26.6.5",
+    "@vitest/browser-playwright": "5.0.5",
+    "@vitest/coverage-v8": "5.0.5",
+    "@vitest/ui": "5.0.5",
+    "cspell": "10.4.0",
     "dedent": "1.7.2",
     "esbuild": "0.28.2",
-    "eslint": "10.12.0",
-    "eslint-config-typed": "5.19.0",
-    "eslint-plugin-ts-data-forge": "0.9.0",
-    "eslint-plugin-ts-fortress": "1.3.4",
-    "eslint-plugin-ts-type-forge": "0.8.9",
+    "eslint": "10.13.0",
+    "eslint-config-typed": "6.0.0",
+    "eslint-plugin-ts-data-forge": "0.10.4",
+    "eslint-plugin-ts-fortress": "1.3.9",
+    "eslint-plugin-ts-type-forge": "0.8.14",
     "jiti": "2.7.0",
-    "npm-run-all2": "9.0.3",
-    "playwright": "1.64.0",
-    "prettier": "3.9.9",
+    "npm-run-all2": "9.0.4",
+    "playwright": "1.64.1",
+    "prettier": "3.9.10",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
     "ts-repo-utils": "10.7.1",
@@ -67,15 +67,15 @@
     "typedoc-github-theme": "0.4.0",
     "typescript": "6.0.3",
     "typescript-native": "npm:typescript@7.0.2",
-    "vite": "8.3.3",
-    "vitest": "5.0.3"
+    "vite": "8.3.5",
+    "vitest": "5.0.5"
   },
   "engines": {
-    "node": ">=22.22.2",
+    "node": ">=22.23.4",
     "pnpm": ">=9.0.0"
   },
   "volta": {
-    "node": "26.12.0"
+    "node": "26.12.1"
   },
   "publishConfig": {
     "access": "public",

package/src/functions/ast-transformers/append-as-const.mts

@@ -1,6 +1,10 @@
-import { Arr, ISet } from 'ts-data-forge';
+import { Arr, ISet, isRecord } from 'ts-data-forge';
 import * as tsm from 'ts-morph';
 import type { DeepReadonly } from 'ts-type-forge';
+import {
+  DEFAULT_MUTABLE_PREFIXES,
+  DEFAULT_MUTABLE_TYPE_PREFIXES,
+} from '../constants/index.mjs';
 import {
   hasDisableNextLineComment,
   isAsConstNode,
@@ -16,13 +20,26 @@ const TRANSFORMER_NAME = 'append-as-const';
 export const appendAsConstTransformer = (
   options?: AppendAsConstTransformerOptions,
 ): TsMorphTransformer => {
-  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 renamed to "mutableVariablePrefixes".`,
+    );
+  }
 
   const optionsInternal: AppendAsConstTransformerOptionsInternal = {
     applyLevel: options?.applyLevel ?? 'avoidInFunctionArgs',
-    ignoredPrefixes: ignorePrefixes,
+    mutableVariablePrefixes: ISet.create(
+      options?.mutableVariablePrefixes ?? DEFAULT_MUTABLE_PREFIXES,
+    ),
+    mutableTypePrefixes: ISet.create(
+      options?.mutableTypePrefixes ?? DEFAULT_MUTABLE_TYPE_PREFIXES,
+    ),
     removeAsConstForConstTypeParameters:
       options?.removeAsConstForConstTypeParameters ?? true,
 
@@ -63,13 +80,23 @@ export type AppendAsConstTransformerOptions = DeepReadonly<{
   applyLevel?: 'all' | 'avoidInFunctionArgs';
 
   /**
-   * A mute keywords to ignore the readonly conversion.
+   * Prefixes of the names of variables that are left mutable: their
+   * initializers get no `as const`, nor does a value annotated with their type
+   * (`typeof mut_x`).
    *
-   * (e.g. `"mut_"`)
+   * @default ['mut_']
+   */
+  mutableVariablePrefixes?: string[];
+
+  /**
+   * Prefixes of the names of mutable types (see `convert-to-readonly`): a
+   * variable whose type annotation names such a type, an expression that
+   * `satisfies` one and an arrow function body returning one get no
+   * `as const`, which would make them unassignable to it.
    *
-   * @default ['mut_', '#mut_', '_mut_', 'draft']
+   * @default ['Mutable', 'mut_']
    */
-  ignorePrefixes?: string[];
+  mutableTypePrefixes?: string[];
 
   /**
    * Whether to remove redundant `as const` assertions from call arguments
@@ -93,7 +120,8 @@ export type AppendAsConstTransformerOptions = DeepReadonly<{
 
 type AppendAsConstTransformerOptionsInternal = DeepReadonly<{
   applyLevel: 'all' | 'avoidInFunctionArgs';
-  ignoredPrefixes: ISet<string>;
+  mutableVariablePrefixes: ISet<string>;
+  mutableTypePrefixes: ISet<string>;
   removeAsConstForConstTypeParameters: boolean;
 
   debugPrint: (...args: readonly unknown[]) => void;
@@ -143,11 +171,13 @@ const transformNode = (
   if (node.isKind(tsm.SyntaxKind.VariableDeclaration)) {
     const nodeName = node.getName();
 
-    // check for ignorePrefix
-    if (options.ignoredPrefixes.some((p) => nodeName.startsWith(p))) {
+    // check for mutableVariablePrefixes
+    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;
     }
@@ -167,6 +197,18 @@ const transformNode = (
       return;
     }
 
+    // Example: const foo: MutableFoo = { a: [] }; -> remains as is, because
+    // `as const` would make the initializer unassignable to `MutableFoo`
+    const typeNode = node.getTypeNode();
+
+    if (refersToMutableType(typeNode, options)) {
+      options.debugPrint(
+        'skipped variable declaration annotated with a mutable type',
+      );
+
+      return;
+    }
+
     const declarationKindKeywords = node
       .getVariableStatement()
       ?.getDeclarationKindKeywords()
@@ -189,13 +231,13 @@ const transformNode = (
     }
 
     // const [a, b] = ...;
-    // TODO: Support ignoredPrefixes in ArrayBindingPattern
+    // TODO: Support mutableVariablePrefixes in ArrayBindingPattern
     // if (ts.isArrayBindingPattern(nodeName)) {
     //   // for (const [i, el] of nodeName.elements.entries())
     // }
 
     // const { x, y } = ...;
-    // TODO: Support ignoredPrefixes in ObjectBindingPattern
+    // TODO: Support mutableVariablePrefixes in ObjectBindingPattern
     // if (ts.isObjectBindingPattern(nodeName)) {
     //   // for (const [i, el] of nodeName.elements.entries())
     // }
@@ -218,6 +260,14 @@ const transformNode = (
 
   // pass by ([X satisfies ...] -> X)
   if (tsm.Node.isSatisfiesExpression(node)) {
+    // Example: { a: [] } satisfies MutableFoo -> remains as is, because
+    // `as const` would make it fail to satisfy `MutableFoo`
+    if (refersToMutableType(node.getTypeNode(), options)) {
+      options.debugPrint('skipped satisfies expression with a mutable type');
+
+      return;
+    }
+
     transformNode(node.getExpression(), context, options);
 
     return;
@@ -236,6 +286,14 @@ const transformNode = (
 
   // pass by arrow function body ([() => X] -> X)
   if (tsm.Node.isArrowFunction(node)) {
+    // Example: (): MutableFoo => ({ a: [] }) -> remains as is, because
+    // `as const` would make the body unassignable to `MutableFoo`
+    if (refersToMutableType(node.getReturnTypeNode(), options)) {
+      options.debugPrint('skipped arrow function with a mutable return type');
+
+      return;
+    }
+
     const body = node.getBody();
 
     transformNode(body, context, options);
@@ -682,3 +740,82 @@ const isBareConstTypeParameterReference = (
     constTypeParameterNames.has(typeName.getText())
   );
 };
+
+/** `ns.MutableFoo` -> `MutableFoo` */
+const lastNameOf = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  entityName: tsm.EntityName,
+): string =>
+  (tsm.Node.isQualifiedName(entityName)
+    ? entityName.getRight()
+    : entityName
+  ).getText();
+
+/** `mut_x.items` -> `mut_x` */
+const firstNameOf = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  entityName: tsm.EntityName,
+): string =>
+  tsm.Node.isQualifiedName(entityName)
+    ? firstNameOf(entityName.getLeft())
+    : entityName.getText();
+
+const startsWithAny = (prefixes: ISet<string>, name: string): boolean =>
+  prefixes.some((p) => name.startsWith(p));
+
+/**
+ * The name a `typeof` starts from: a variable (`mut_x`) or a class, which
+ * `convert-to-readonly` leaves mutable by its type prefix (`MutableStore`).
+ */
+const isMutableValueName = (
+  name: string,
+  options: AppendAsConstTransformerOptionsInternal,
+): boolean =>
+  startsWithAny(options.mutableVariablePrefixes, name) ||
+  startsWithAny(options.mutableTypePrefixes, name);
+
+/**
+ * Whether `typeNode` names a type of a `mutableTypePrefixes` prefix anywhere
+ * in it (`MutableFoo`, `ns.MutableFoo[]`, `import('./m').MutableFoo | X`), or
+ * the type of a variable of a `mutableVariablePrefixes` prefix or a class of
+ * a `mutableTypePrefixes` one (`typeof mut_x`, `typeof MutableStore`). It reads names only, so an alias of another name for such
+ * a type is missed.
+ */
+const refersToMutableType = (
+  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+  typeNode: tsm.TypeNode | undefined,
+  options: AppendAsConstTransformerOptionsInternal,
+): boolean => {
+  if (typeNode === undefined) {
+    return false;
+  }
+
+  const refers = (n: tsm.Node): boolean => {
+    if (n.isKind(tsm.SyntaxKind.TypeReference)) {
+      return startsWithAny(
+        options.mutableTypePrefixes,
+        lastNameOf(n.getTypeName()),
+      );
+    }
+
+    if (n.isKind(tsm.SyntaxKind.ImportType)) {
+      const qualifier = n.getQualifier();
+
+      return (
+        qualifier !== undefined &&
+        // typeof import('./m').mut_x names a value
+        (n.compilerNode.isTypeOf
+          ? isMutableValueName(firstNameOf(qualifier), options)
+          : startsWithAny(options.mutableTypePrefixes, lastNameOf(qualifier)))
+      );
+    }
+
+    // typeof mut_x, typeof mut_x.items, typeof MutableClass
+    return (
+      n.isKind(tsm.SyntaxKind.TypeQuery) &&
+      isMutableValueName(firstNameOf(n.getExprName()), options)
+    );
+  };
+
+  return refers(typeNode) || typeNode.getFirstDescendant(refers) !== undefined;
+};

package/src/functions/ast-transformers/append-as-const.test.mts

@@ -1013,7 +1013,25 @@ describe(appendAsConstTransformer, () => {
     ])('$name', testFn);
   });
 
-  describe('ignorePrefixes option (mut_ prefix)', () => {
+  describe('mutableVariablePrefixes option (mut_ prefix)', () => {
+    test('the removed ignorePrefixes option is refused', () => {
+      expect(() =>
+        appendAsConstTransformer(
+          // @ts-expect-error removed in 4.0.0
+          { ignorePrefixes: ['mut_'] },
+        ),
+      ).toThrow('mutableVariablePrefixes');
+    });
+
+    test('an unset ignorePrefixes option is accepted', () => {
+      expect(() =>
+        appendAsConstTransformer(
+          // @ts-expect-error removed in 4.0.0
+          { ignorePrefixes: undefined },
+        ),
+      ).not.toThrow();
+    });
+
     test.each([
       {
         name: 'single variable with mut_ prefix',
@@ -1025,6 +1043,66 @@ describe(appendAsConstTransformer, () => {
         source: 'const mut_a = [1, 2], mut_b = { c: 3 };',
         expected: 'const mut_a = [1, 2], mut_b = { c: 3 };',
       },
+      {
+        name: '"draft" and "_mut_" are not default prefixes',
+        source: 'const draft = { a: [1] }, _mut_b = [2];',
+        expected: 'const draft = { a: [1] } as const, _mut_b = [2] as const;',
+      },
+      {
+        name: 'a variable annotated with a mutable type gets no as const',
+        source: dedent`
+          const a: MutableFoo = { b: [1] };
+          const c: ns.MutableFoo | undefined = { b: [1] };
+          const d: readonly MutableFoo[] = [{ b: [1] }];
+          const f: mut_Foo = { b: [1] };
+          const g: import('./m').MutableFoo = { b: [1] };
+          const h = { b: [1] } satisfies MutableFoo;
+          const i = (): MutableFoo => ({ b: [1] });
+          const j: typeof mut_x = [1];
+          const k: typeof mut_y.items = [1];
+          const l: typeof import('./m').mut_z = [1];
+          const m: InstanceType<typeof MutableStore> = { items: [] };
+          const n: InstanceType<typeof import('./m').MutableStore> = { items: [] };
+          const o = ((): MutableFoo => ({ b: [1] }));
+          const p = cond ? ({ b: [1] } satisfies MutableFoo) : q;
+          const e: Foo = { b: [1] };
+        `,
+        expected: dedent`
+          const a: MutableFoo = { b: [1] };
+          const c: ns.MutableFoo | undefined = { b: [1] };
+          const d: readonly MutableFoo[] = [{ b: [1] }];
+          const f: mut_Foo = { b: [1] };
+          const g: import('./m').MutableFoo = { b: [1] };
+          const h = { b: [1] } satisfies MutableFoo;
+          const i = (): MutableFoo => ({ b: [1] });
+          const j: typeof mut_x = [1];
+          const k: typeof mut_y.items = [1];
+          const l: typeof import('./m').mut_z = [1];
+          const m: InstanceType<typeof MutableStore> = { items: [] };
+          const n: InstanceType<typeof import('./m').MutableStore> = { items: [] };
+          const o = ((): MutableFoo => ({ b: [1] }));
+          const p = cond ? ({ b: [1] } satisfies MutableFoo) : q;
+          const e: Foo = { b: [1] } as const;
+        `,
+      },
+      {
+        name: 'mutableTypePrefixes replaces the default',
+        source: dedent`
+          const a: MutableFoo = { b: [1] };
+          const c: MyFoo = { b: [1] };
+        `,
+        expected: dedent`
+          const a: MutableFoo = { b: [1] } as const;
+          const c: MyFoo = { b: [1] };
+        `,
+        options: { mutableTypePrefixes: ['My'] },
+      },
+      {
+        name: 'the prefixes named in the option replace the default',
+        source: 'const draft = { a: [1] }, mut_b = [2];',
+        expected: 'const draft = { a: [1] }, mut_b = [2] as const;',
+        options: { mutableVariablePrefixes: ['draft'] },
+      },
     ])('$name', testFn);
   });