ts-codemod-lib 4.0.0 → 4.1.0

package/src/functions/ast-transformers/enable-no-unchecked-indexed-access.test.mts

@@ -34,6 +34,29 @@ const preamble = dedent`
   declare const k: string;
 `;
 
+/**
+ * Runs the transformer over `code` in {@link project}, and returns what it made
+ * of it.
+ */
+const transformInProject = (
+  code: string,
+  options?: Parameters<typeof enableNoUncheckedIndexedAccessTransformer>[0],
+): string => {
+  const sourceAst = project.createSourceFile('source.ts', code, {
+    overwrite: true,
+  });
+
+  enableNoUncheckedIndexedAccessTransformer(options).transform(sourceAst);
+
+  return sourceAst.getFullText();
+};
+
+const formatter = (code: string): Promise<string> =>
+  prettier.format(code, {
+    parser: 'typescript',
+    plugins: [prettierPluginTypeScript, prettierPluginEstree],
+  });
+
 const testFn = async ({
   source,
   expected,
@@ -59,23 +82,6 @@ const testFn = async ({
   expect(transformed).toBe(expectedFormatted);
 };
 
-/**
- * Runs the transformer over `code` in {@link project}, and returns what it
- * made of it.
- */
-const transformInProject = (
-  code: string,
-  options?: Parameters<typeof enableNoUncheckedIndexedAccessTransformer>[0],
-): string => {
-  const sourceAst = project.createSourceFile('source.ts', code, {
-    overwrite: true,
-  });
-
-  enableNoUncheckedIndexedAccessTransformer(options).transform(sourceAst);
-
-  return sourceAst.getFullText();
-};
-
 /**
  * The one project every case is checked in, rather than one project per case.
  *
@@ -87,14 +93,14 @@ const transformInProject = (
  * fraction of a millisecond. Sixty of those took `check:test:cov` past Vitest's
  * timeout on CI.
  *
- * Reusing the project is half of the answer and the smaller half — measured,
- * it takes a case from ~300 ms to ~260 ms, because what an edit invalidates is
- * the program, not the parsed library behind it. Naming the libraries the
- * cases actually need is the rest: together they bring a case to ~25 ms.
+ * Reusing the project is half of the answer and the smaller half — measured, it
+ * takes a case from ~300 ms to ~260 ms, because what an edit invalidates is the
+ * program, not the parsed library behind it. Naming the libraries the cases
+ * actually need is the rest: together they bring a case to ~25 ms.
  *
  * What that leaves out — `transformSourceCode` itself, and the transformer
- * against the full library — is what the tests at the bottom of this file
- * still cover.
+ * against the full library — is what the tests at the bottom of this file still
+ * cover.
  */
 const project = new tsm.Project({
   useInMemoryFileSystem: true,
@@ -107,12 +113,6 @@ const project = new tsm.Project({
   },
 });
 
-const formatter = (code: string): Promise<string> =>
-  prettier.format(code, {
-    parser: 'typescript',
-    plugins: [prettierPluginTypeScript, prettierPluginEstree],
-  });
-
 describe(enableNoUncheckedIndexedAccessTransformer, () => {
   describe('accesses the option widens with undefined', () => {
     test.each([

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

@@ -7,6 +7,12 @@ import * as prettier from 'prettier/standalone';
 import { replaceAnyWithUnknownTransformer } from './replace-any-with-unknown.mjs';
 import { transformSourceCode } from './transform-source-code.mjs';
 
+const formatter = (code: string): Promise<string> =>
+  prettier.format(code, {
+    parser: 'typescript',
+    plugins: [prettierPluginTypeScript, prettierPluginEstree],
+  });
+
 const testFn = async ({
   source,
   expected,
@@ -33,12 +39,6 @@ const testFn = async ({
   expect(transformed).toBe(expectedFormatted);
 };
 
-const formatter = (code: string): Promise<string> =>
-  prettier.format(code, {
-    parser: 'typescript',
-    plugins: [prettierPluginTypeScript, prettierPluginEstree],
-  });
-
 describe(replaceAnyWithUnknownTransformer, () => {
   test.each([
     {

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

@@ -12,8 +12,8 @@ const UNKNOWN_RECORD_MODULE = 'ts-type-forge';
 const UNKNOWN_RECORD_NAME = 'UnknownRecord';
 
 /**
- * Replaces `Readonly<Record<string, unknown>>`, `Record<string, unknown>`,
- * and index signatures `[k: string]: unknown` with `UnknownRecord`.
+ * Replaces `Readonly<Record<string, unknown>>`, `Record<string, unknown>`, and
+ * index signatures `[k: string]: unknown` with `UnknownRecord`.
  *
  * When a replacement occurs, also inserts
  * `import { type UnknownRecord } from 'ts-type-forge';` at the top of the
@@ -35,77 +35,14 @@ export const replaceRecordWithUnknownRecordTransformer =
       },
     }) as const;
 
-const processDeclarations = (
-  container: tsm.SourceFile | tsm.ModuleDeclaration,
-): boolean => {
-  const typeAliasModifications = container.getTypeAliases().map((typeAlias) => {
-    if (hasDisableNextLineComment(typeAlias, TRANSFORMER_NAME)) {
-      return false;
-    }
-
-    const typeNode = typeAlias.getTypeNode();
-
-    return typeNode !== undefined && visitTypeNode(typeNode);
-  });
-
-  const interfaceModifications = container
-    .getInterfaces()
-    .map(processInterfaceDeclaration);
-
-  return [...typeAliasModifications, ...interfaceModifications].includes(true);
-};
-
-const processInterfaceDeclaration = (
-  interfaceDecl: tsm.InterfaceDeclaration,
+const isStringUnknownIndexSignature = (
+  sig: tsm.IndexSignatureDeclaration,
 ): boolean => {
-  if (hasDisableNextLineComment(interfaceDecl, TRANSFORMER_NAME)) {
-    return false;
-  }
-
-  // Check if interface has index signature [k: string]: unknown
-  const indexSignatures = interfaceDecl.getIndexSignatures();
-
-  const hasStringUnknownSignature = indexSignatures.some((sig) => {
-    const keyType = sig.getKeyType();
-
-    const returnType = sig.getReturnType();
-
-    return keyType.getText() === 'string' && returnType.getText() === 'unknown';
-  });
-
-  // If it has the signature and no other members, replace entire interface with type alias.
-  // Skip when the interface carries semantics that a plain type alias would lose
-  // (type parameters, extends clauses, declare modifier, default export).
-  if (
-    hasStringUnknownSignature &&
-    Arr.isEmpty(interfaceDecl.getProperties()) &&
-    Arr.isFixedLengthArray(1, indexSignatures) &&
-    Arr.isEmpty(interfaceDecl.getTypeParameters()) &&
-    Arr.isEmpty(interfaceDecl.getExtends()) &&
-    !interfaceDecl.hasDeclareKeyword() &&
-    !interfaceDecl.hasDefaultKeyword()
-  ) {
-    const exportPrefix = interfaceDecl.hasExportKeyword() ? 'export ' : '';
-
-    const interfaceName = interfaceDecl.getName();
-
-    replaceNodeWithText(
-      interfaceDecl,
-      `${exportPrefix}type ${interfaceName} = UnknownRecord;`,
-    );
-
-    return true;
-  }
+  const keyType = sig.getKeyTypeNode();
 
-  // Otherwise, check properties for Record types
-  return interfaceDecl
-    .getProperties()
-    .map((property) => {
-      const typeNode = property.getTypeNode();
+  const returnType = sig.getReturnTypeNode();
 
-      return typeNode !== undefined && visitTypeNode(typeNode);
-    })
-    .includes(true);
+  return keyType.getText() === 'string' && returnType?.getText() === 'unknown';
 };
 
 const visitTypeNode = (node: tsm.TypeNode): boolean => {
@@ -208,14 +145,77 @@ const visitTypeNode = (node: tsm.TypeNode): boolean => {
   );
 };
 
-const isStringUnknownIndexSignature = (
-  sig: tsm.IndexSignatureDeclaration,
+const processInterfaceDeclaration = (
+  interfaceDecl: tsm.InterfaceDeclaration,
 ): boolean => {
-  const keyType = sig.getKeyTypeNode();
+  if (hasDisableNextLineComment(interfaceDecl, TRANSFORMER_NAME)) {
+    return false;
+  }
 
-  const returnType = sig.getReturnTypeNode();
+  // Check if interface has index signature [k: string]: unknown
+  const indexSignatures = interfaceDecl.getIndexSignatures();
 
-  return keyType.getText() === 'string' && returnType?.getText() === 'unknown';
+  const hasStringUnknownSignature = indexSignatures.some((sig) => {
+    const keyType = sig.getKeyType();
+
+    const returnType = sig.getReturnType();
+
+    return keyType.getText() === 'string' && returnType.getText() === 'unknown';
+  });
+
+  // If it has the signature and no other members, replace entire interface with type alias.
+  // Skip when the interface carries semantics that a plain type alias would lose
+  // (type parameters, extends clauses, declare modifier, default export).
+  if (
+    hasStringUnknownSignature &&
+    Arr.isEmpty(interfaceDecl.getProperties()) &&
+    Arr.isFixedLengthArray(1, indexSignatures) &&
+    Arr.isEmpty(interfaceDecl.getTypeParameters()) &&
+    Arr.isEmpty(interfaceDecl.getExtends()) &&
+    !interfaceDecl.hasDeclareKeyword() &&
+    !interfaceDecl.hasDefaultKeyword()
+  ) {
+    const exportPrefix = interfaceDecl.hasExportKeyword() ? 'export ' : '';
+
+    const interfaceName = interfaceDecl.getName();
+
+    replaceNodeWithText(
+      interfaceDecl,
+      `${exportPrefix}type ${interfaceName} = UnknownRecord;`,
+    );
+
+    return true;
+  }
+
+  // Otherwise, check properties for Record types
+  return interfaceDecl
+    .getProperties()
+    .map((property) => {
+      const typeNode = property.getTypeNode();
+
+      return typeNode !== undefined && visitTypeNode(typeNode);
+    })
+    .includes(true);
+};
+
+const processDeclarations = (
+  container: tsm.SourceFile | tsm.ModuleDeclaration,
+): boolean => {
+  const typeAliasModifications = container.getTypeAliases().map((typeAlias) => {
+    if (hasDisableNextLineComment(typeAlias, TRANSFORMER_NAME)) {
+      return false;
+    }
+
+    const typeNode = typeAlias.getTypeNode();
+
+    return typeNode !== undefined && visitTypeNode(typeNode);
+  });
+
+  const interfaceModifications = container
+    .getInterfaces()
+    .map(processInterfaceDeclaration);
+
+  return [...typeAliasModifications, ...interfaceModifications].includes(true);
 };
 
 const replaceIfRecordUnknown = (node: tsm.TypeReferenceNode): boolean => {

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

@@ -7,6 +7,12 @@ import * as prettier from 'prettier/standalone';
 import { replaceRecordWithUnknownRecordTransformer } from './replace-record-with-unknown-record.mjs';
 import { transformSourceCode } from './transform-source-code.mjs';
 
+const formatter = (code: string): Promise<string> =>
+  prettier.format(code, {
+    parser: 'typescript',
+    plugins: [prettierPluginTypeScript, prettierPluginEstree],
+  });
+
 const testFn = async ({
   source,
   expected,
@@ -25,12 +31,6 @@ const testFn = async ({
   expect(transformed).toBe(expectedFormatted);
 };
 
-const formatter = (code: string): Promise<string> =>
-  prettier.format(code, {
-    parser: 'typescript',
-    plugins: [prettierPluginTypeScript, prettierPluginEstree],
-  });
-
 describe(replaceRecordWithUnknownRecordTransformer, () => {
   test.each([
     {

package/src/functions/ast-transformers/transform-source-code.mts

@@ -9,94 +9,47 @@ const fileIgnorePrefixes = [
   'transform-ignore',
 ] as const;
 
-/**
- * Finds the file-level ignore comment `/* <prefix> name, name *\/` and returns
- * the transformer names it lists (empty for all transformers), or `undefined`
- * when the file has none. Whitespace, line breaks included, may surround the
- * prefix and the names, but the names themselves must stay on one line. The
- * prefixes are tried in order, each against the whole file.
- *
- * The scan runs in time linear in the length of `code`, whatever it contains.
- */
-const findFileIgnoreTransformers = (
+export const transformSourceCode = (
   code: string,
-): readonly string[] | undefined => {
-  for (const prefix of fileIgnorePrefixes) {
-    const names = findFileIgnoreComment(code, prefix);
-
-    if (names !== undefined) {
-      return names;
-    }
-  }
-
-  return undefined;
-};
+  isTsx: boolean,
+  transformers: readonly TsMorphTransformer[],
+  debug: boolean = false,
+): string => {
+  const project = new tsm.Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: {
+      jsx: isTsx ? tsm.ts.JsxEmit.React : undefined,
+      target: tsm.ts.ScriptTarget.ESNext,
+      module: tsm.ts.ModuleKind.ESNext,
+    },
+  });
 
-const findFileIgnoreComment = (
-  code: string,
-  prefix: string,
-): readonly string[] | undefined => {
-  // Queries into these searches only move forward, so each part of `code` is
-  // scanned a bounded number of times.
-  const findCommentEnd = createForwardSearch((from) =>
-    code.indexOf('*/', from),
+  const sourceAst = project.createSourceFile(
+    `source.${isTsx ? 'tsx' : 'ts'}`,
+    code,
   );
 
-  const findLineTerminator = createForwardSearch((from) =>
-    indexOfLineTerminator(code, from),
-  );
+  const ignoredTransformers = findFileIgnoreTransformers(code);
 
-  const trimEndBefore = createLastValueCache((commentEnd: number) =>
-    skipWhitespaceBackward(code, commentEnd),
-  );
+  for (const transformer of transformers) {
+    const transformerName = transformer.name;
 
-  for (
-    let mut_open = code.indexOf('/*');
-    mut_open !== -1;
-    mut_open = code.indexOf('/*', mut_open + 2)
-  ) {
-    const prefixStart = skipWhitespace(code, mut_open + 2);
+    if (shouldSkipFile(ignoredTransformers, transformerName)) {
+      if (debug) {
+        console.debug(
+          `skipped by ignore-file comment for transformer: ${transformerName}`,
+        );
+      }
 
-    if (!code.startsWith(prefix, prefixStart)) {
       continue;
     }
 
-    const namesStart = skipWhitespace(code, prefixStart + prefix.length);
-
-    const commentEnd = findCommentEnd(namesStart);
-
-    // Nothing after this point is closed, so no later comment can match.
-    if (commentEnd === -1) {
-      return undefined;
-    }
-
-    const namesEnd = Math.max(namesStart, trimEndBefore(commentEnd));
-
-    const lineTerminator = findLineTerminator(namesStart);
-
-    if (lineTerminator === -1 || lineTerminator >= namesEnd) {
-      const names = code.slice(namesStart, namesEnd);
-
-      // Empty means ignore all transformers; otherwise parse comma-separated
-      // transformer names
-      return names === '' ? [] : names.split(',').map((name) => name.trim());
-    }
+    transformer.transform(sourceAst);
   }
 
-  return undefined;
+  return sourceAst.getFullText();
 };
 
-const shouldSkipFile = (
-  ignoredTransformers: readonly string[] | undefined,
-  transformerName: string,
-): boolean =>
-  ignoredTransformers !== undefined &&
-  // Empty array means ignore all transformers (file-level ignore without
-  // specific transformers); otherwise check if the transformer is in the
-  // ignore list
-  (Arr.isEmpty(ignoredTransformers) ||
-    ignoredTransformers.includes(transformerName));
-
 /**
  * Wraps a search returning the first index at or after `from` (or -1), reusing
  * the previous answer while it still holds for a later `from`.
@@ -137,6 +90,10 @@ const createLastValueCache = (
   };
 };
 
+// Same set as `\s` and `String.prototype.trim`
+const isWhitespace = (char: string | undefined): boolean =>
+  char !== undefined && /^\s$/u.test(char);
+
 const skipWhitespace = (code: string, from: number): number => {
   let mut_index = from;
 
@@ -157,6 +114,10 @@ const skipWhitespaceBackward = (code: string, end: number): number => {
   return mut_index;
 };
 
+// The characters `.` does not match
+const isLineTerminator = (char: string | undefined): boolean =>
+  char !== undefined && /^[\n\r\u{2028}\u{2029}]$/u.test(char);
+
 const indexOfLineTerminator = (code: string, from: number): number => {
   let mut_index = from;
 
@@ -167,51 +128,90 @@ const indexOfLineTerminator = (code: string, from: number): number => {
   return mut_index < code.length ? mut_index : -1;
 };
 
-// Same set as `\s` and `String.prototype.trim`
-const isWhitespace = (char: string | undefined): boolean =>
-  char !== undefined && /^\s$/u.test(char);
-
-// The characters `.` does not match
-const isLineTerminator = (char: string | undefined): boolean =>
-  char !== undefined && /^[\n\r\u{2028}\u{2029}]$/u.test(char);
-
-export const transformSourceCode = (
+const findFileIgnoreComment = (
   code: string,
-  isTsx: boolean,
-  transformers: readonly TsMorphTransformer[],
-  debug: boolean = false,
-): string => {
-  const project = new tsm.Project({
-    useInMemoryFileSystem: true,
-    compilerOptions: {
-      jsx: isTsx ? tsm.ts.JsxEmit.React : undefined,
-      target: tsm.ts.ScriptTarget.ESNext,
-      module: tsm.ts.ModuleKind.ESNext,
-    },
-  });
-
-  const sourceAst = project.createSourceFile(
-    `source.${isTsx ? 'tsx' : 'ts'}`,
-    code,
+  prefix: string,
+): readonly string[] | undefined => {
+  // Queries into these searches only move forward, so each part of `code` is
+  // scanned a bounded number of times.
+  const findCommentEnd = createForwardSearch((from) =>
+    code.indexOf('*/', from),
   );
 
-  const ignoredTransformers = findFileIgnoreTransformers(code);
+  const findLineTerminator = createForwardSearch((from) =>
+    indexOfLineTerminator(code, from),
+  );
 
-  for (const transformer of transformers) {
-    const transformerName = transformer.name;
+  const trimEndBefore = createLastValueCache((commentEnd: number) =>
+    skipWhitespaceBackward(code, commentEnd),
+  );
 
-    if (shouldSkipFile(ignoredTransformers, transformerName)) {
-      if (debug) {
-        console.debug(
-          `skipped by ignore-file comment for transformer: ${transformerName}`,
-        );
-      }
+  for (
+    let mut_open = code.indexOf('/*');
+    mut_open !== -1;
+    mut_open = code.indexOf('/*', mut_open + 2)
+  ) {
+    const prefixStart = skipWhitespace(code, mut_open + 2);
 
+    if (!code.startsWith(prefix, prefixStart)) {
       continue;
     }
 
-    transformer.transform(sourceAst);
+    const namesStart = skipWhitespace(code, prefixStart + prefix.length);
+
+    const commentEnd = findCommentEnd(namesStart);
+
+    // Nothing after this point is closed, so no later comment can match.
+    if (commentEnd === -1) {
+      return undefined;
+    }
+
+    const namesEnd = Math.max(namesStart, trimEndBefore(commentEnd));
+
+    const lineTerminator = findLineTerminator(namesStart);
+
+    if (lineTerminator === -1 || lineTerminator >= namesEnd) {
+      const names = code.slice(namesStart, namesEnd);
+
+      // Empty means ignore all transformers; otherwise parse comma-separated
+      // transformer names
+      return names === '' ? [] : names.split(',').map((name) => name.trim());
+    }
   }
 
-  return sourceAst.getFullText();
+  return undefined;
+};
+
+/**
+ * Finds the file-level ignore comment `/* <prefix> name, name *\/` and returns
+ * the transformer names it lists (empty for all transformers), or `undefined`
+ * when the file has none. Whitespace, line breaks included, may surround the
+ * prefix and the names, but the names themselves must stay on one line. The
+ * prefixes are tried in order, each against the whole file.
+ *
+ * The scan runs in time linear in the length of `code`, whatever it contains.
+ */
+const findFileIgnoreTransformers = (
+  code: string,
+): readonly string[] | undefined => {
+  for (const prefix of fileIgnorePrefixes) {
+    const names = findFileIgnoreComment(code, prefix);
+
+    if (names !== undefined) {
+      return names;
+    }
+  }
+
+  return undefined;
 };
+
+const shouldSkipFile = (
+  ignoredTransformers: readonly string[] | undefined,
+  transformerName: string,
+): boolean =>
+  ignoredTransformers !== undefined &&
+  // Empty array means ignore all transformers (file-level ignore without
+  // specific transformers); otherwise check if the transformer is in the ignore
+  // list
+  (Arr.isEmpty(ignoredTransformers) ||
+    ignoredTransformers.includes(transformerName));

package/src/functions/ast-transformers/transformer-specific-ignore.test.mts

@@ -9,6 +9,12 @@ import { convertToReadonlyTransformer } from './convert-to-readonly.mjs';
 import { replaceAnyWithUnknownTransformer } from './replace-any-with-unknown.mjs';
 import { transformSourceCode } from './transform-source-code.mjs';
 
+const formatter = (code: string): Promise<string> =>
+  prettier.format(code, {
+    parser: 'typescript',
+    plugins: [prettierPluginTypeScript, prettierPluginEstree],
+  });
+
 const testFn = async ({
   source,
   expected,
@@ -39,12 +45,6 @@ const testFn = async ({
   expect(transformed).toBe(expectedFormatted);
 };
 
-const formatter = (code: string): Promise<string> =>
-  prettier.format(code, {
-    parser: 'typescript',
-    plugins: [prettierPluginTypeScript, prettierPluginEstree],
-  });
-
 describe('Transformer-specific ignore comments (Integration)', () => {
   test.each([
     {

package/src/functions/constants/mutable-prefixes.mts

@@ -1,11 +1,11 @@
 /**
  * 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 `#`.
+ * 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);
+ * The ESLint counterpart is `mutablePrefix` in
+ * `libs/eslint-config-typed/src/constants/mutable-prefix.mts`, from which
+ * `eslint-functional-rules.mts` there builds its name and property patterns;
  * `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.
  */
@@ -15,9 +15,9 @@ export const DEFAULT_MUTABLE_PREFIXES: readonly string[] = Object.freeze([
 
 /**
  * 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).
+ * 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.