ts-codemod-lib 2.1.5 → 2.1.6

package/README.md

@@ -314,6 +314,8 @@ const transformedCode = transformSourceCode(originalCode, isTsx, [
 ]);
 
 const expected = dedent`
+  import { type UnknownRecord } from "ts-type-forge";
+
   export type A = Readonly< {
     name?: string;
     point: (readonly  [x: number, y: number, z?: number]);
@@ -341,7 +343,7 @@ const expected = dedent`
 
 if (import.meta.vitest !== undefined) {
     test('transformSourceCode', () => {
-        assert.isTrue(transformedCode === expected);
+        assert.strictEqual(transformedCode, expected);
     });
 }
 ```

package/dist/cmd/append-as-const.mjs

@@ -10,7 +10,7 @@ import { runTransformerCLI } from './run-transformer-cli.mjs';
 const transformer = appendAsConstTransformer();
 const cmdDef = cmd.command({
     name: transformer.name,
-    version: '2.1.5',
+    version: '2.1.6',
     args: {
         baseDir: cmd.positional({
             type: cmd.string,

package/dist/cmd/convert-interface-to-type.mjs

@@ -10,7 +10,7 @@ import { runTransformerCLI } from './run-transformer-cli.mjs';
 const transformer = convertInterfaceToTypeTransformer();
 const cmdDef = cmd.command({
     name: transformer.name,
-    version: '2.1.5',
+    version: '2.1.6',
     args: {
         baseDir: cmd.positional({
             type: cmd.string,

package/dist/cmd/convert-to-readonly.mjs

@@ -10,7 +10,7 @@ import { runTransformerCLI } from './run-transformer-cli.mjs';
 const transformer = convertToReadonlyTransformer();
 const cmdDef = cmd.command({
     name: transformer.name,
-    version: '2.1.5',
+    version: '2.1.6',
     args: {
         baseDir: cmd.positional({
             type: cmd.string,

package/dist/cmd/replace-any-with-unknown.mjs

@@ -10,7 +10,7 @@ import { runTransformerCLI } from './run-transformer-cli.mjs';
 const transformer = replaceAnyWithUnknownTransformer();
 const cmdDef = cmd.command({
     name: transformer.name,
-    version: '2.1.5',
+    version: '2.1.6',
     args: {
         baseDir: cmd.positional({
             type: cmd.string,

package/dist/cmd/replace-record-with-unknown-record.mjs

@@ -10,7 +10,7 @@ import { runTransformerCLI } from './run-transformer-cli.mjs';
 const transformer = replaceRecordWithUnknownRecordTransformer();
 const cmdDef = cmd.command({
     name: transformer.name,
-    version: '2.1.5',
+    version: '2.1.6',
     args: {
         baseDir: cmd.positional({
             type: cmd.string,

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

@@ -1,7 +1,11 @@
 import { type TsMorphTransformer } from './types.mjs';
 /**
  * Replaces `Readonly<Record<string, unknown>>`, `Record<string, unknown>`,
- * and index signatures `[k: string]: unknown` with `UnknownRecord`
+ * 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
+ * source file (or merges into an existing import from `'ts-type-forge'`).
  */
 export declare const replaceRecordWithUnknownRecordTransformer: () => TsMorphTransformer;
 //# sourceMappingURL=replace-record-with-unknown-record.d.mts.map

package/dist/functions/ast-transformers/replace-record-with-unknown-record.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-record-with-unknown-record.d.mts","sourceRoot":"","sources":["../../../src/functions/ast-transformers/replace-record-with-unknown-record.mts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItD;;;GAGG;AACH,eAAO,MAAM,yCAAyC,QAChD,kBAcS,CAAC"}
+{"version":3,"file":"replace-record-with-unknown-record.d.mts","sourceRoot":"","sources":["../../../src/functions/ast-transformers/replace-record-with-unknown-record.mts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAQtD;;;;;;;GAOG;AACH,eAAO,MAAM,yCAAyC,QAChD,kBAeS,CAAC"}

package/dist/functions/ast-transformers/replace-record-with-unknown-record.mjs

@@ -5,64 +5,81 @@ import '../functions/is-atomic-type-node.mjs';
 
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- ts-morph uses mutable types */
 const TRANSFORMER_NAME = 'replace-record-with-unknown-record';
+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`
+ * 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
+ * source file (or merges into an existing import from `'ts-type-forge'`).
  */
 const replaceRecordWithUnknownRecordTransformer = () => ({
     name: TRANSFORMER_NAME,
     transform: (sourceAst) => {
-        // Process top-level declarations
-        processDeclarations(sourceAst);
-        // Process declarations inside namespaces/modules
-        const namespaces = sourceAst.getModules();
-        for (const namespace of namespaces) {
-            processDeclarations(namespace);
+        const containerModifications = [
+            processDeclarations(sourceAst),
+            ...sourceAst
+                .getModules()
+                .map((namespace) => processDeclarations(namespace)),
+        ];
+        if (containerModifications.includes(true)) {
+            ensureUnknownRecordImport(sourceAst);
         }
     },
 });
 const processDeclarations = (container) => {
-    const typeAliases = container.getTypeAliases();
-    for (const typeAlias of typeAliases) {
+    const typeAliasModifications = container.getTypeAliases().map((typeAlias) => {
         if (hasDisableNextLineComment(typeAlias, TRANSFORMER_NAME)) {
-            continue;
+            return false;
         }
         const typeNode = typeAlias.getTypeNode();
         if (typeNode === undefined)
-            continue;
-        visitTypeNode(typeNode);
+            return false;
+        return visitTypeNode(typeNode);
+    });
+    const interfaceModifications = container
+        .getInterfaces()
+        .map((interfaceDecl) => processInterfaceDeclaration(interfaceDecl));
+    return [...typeAliasModifications, ...interfaceModifications].includes(true);
+};
+const processInterfaceDeclaration = (interfaceDecl) => {
+    if (hasDisableNextLineComment(interfaceDecl, TRANSFORMER_NAME)) {
+        return false;
     }
-    const interfaces = container.getInterfaces();
-    for (const interfaceDecl of interfaces) {
-        if (hasDisableNextLineComment(interfaceDecl, TRANSFORMER_NAME)) {
-            continue;
-        }
-        // 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
-        if (hasStringUnknownSignature) {
-            const properties = interfaceDecl.getProperties();
-            if (Arr.isArrayOfLength(properties, 0) &&
-                Arr.isArrayOfLength(indexSignatures, 1)) {
-                // Replace interface with type alias
-                const interfaceName = interfaceDecl.getName();
-                interfaceDecl.replaceWithText(`export type ${interfaceName} = UnknownRecord;`);
-                continue;
-            }
-        }
-        // Otherwise, check properties for Record types
-        for (const property of interfaceDecl.getProperties()) {
-            const typeNode = property.getTypeNode();
-            if (typeNode === undefined)
-                continue;
-            visitTypeNode(typeNode);
-        }
+    // 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.isArrayOfLength(interfaceDecl.getProperties(), 0) &&
+        Arr.isArrayOfLength(indexSignatures, 1) &&
+        Arr.isArrayOfLength(interfaceDecl.getTypeParameters(), 0) &&
+        Arr.isArrayOfLength(interfaceDecl.getExtends(), 0) &&
+        !interfaceDecl.hasDeclareKeyword() &&
+        !interfaceDecl.hasDefaultKeyword()) {
+        const exportPrefix = interfaceDecl.hasExportKeyword() ? 'export ' : '';
+        const interfaceName = interfaceDecl.getName();
+        interfaceDecl.replaceWithText(`${exportPrefix}type ${interfaceName} = UnknownRecord;`);
+        return true;
     }
+    // Otherwise, check properties for Record types
+    return interfaceDecl
+        .getProperties()
+        .map((property) => {
+        const typeNode = property.getTypeNode();
+        if (typeNode === undefined)
+            return false;
+        return visitTypeNode(typeNode);
+    })
+        .includes(true);
 };
 const visitTypeNode = (node) => {
     if (tsm.Node.isTypeReference(node)) {
@@ -79,15 +96,14 @@ const visitTypeNode = (node) => {
                         Arr.isArrayOfLength(indexSigs, 1) &&
                         isStringUnknownIndexSignature(indexSigs[0])) {
                         node.replaceWithText('UnknownRecord');
-                        return;
+                        return true;
                     }
                     // Otherwise, recurse into the type literal to visit its properties
-                    visitTypeNode(typeArg);
-                    return;
+                    return visitTypeNode(typeArg);
                 }
             }
         }
-        replaceIfRecordUnknown(node);
+        return replaceIfRecordUnknown(node);
     }
     // Check for type literal { [k: string]: unknown }
     if (tsm.Node.isTypeLiteral(node)) {
@@ -98,47 +114,52 @@ const visitTypeNode = (node) => {
             Arr.isArrayOfLength(indexSigs, 1) &&
             isStringUnknownIndexSignature(indexSigs[0])) {
             node.replaceWithText('UnknownRecord');
-            return;
+            return true;
         }
+        return members
+            .map((member) => {
+            if (tsm.Node.isPropertySignature(member)) {
+                const typeNode = member.getTypeNode();
+                return typeNode === undefined ? false : visitTypeNode(typeNode);
+            }
+            if (tsm.Node.isIndexSignatureDeclaration(member)) {
+                const typeNode = member.getReturnTypeNode();
+                return typeNode === undefined ? false : visitTypeNode(typeNode);
+            }
+            return false;
+        })
+            .includes(true);
     }
     // Recursively visit child type nodes
-    if (tsm.Node.isUnionTypeNode(node)) {
-        for (const typeNode of node.getTypeNodes()) {
-            visitTypeNode(typeNode);
-        }
+    if (tsm.Node.isUnionTypeNode(node) || tsm.Node.isIntersectionTypeNode(node)) {
+        return node
+            .getTypeNodes()
+            .map((typeNode) => visitTypeNode(typeNode))
+            .includes(true);
     }
-    else if (tsm.Node.isIntersectionTypeNode(node)) {
-        for (const typeNode of node.getTypeNodes()) {
-            visitTypeNode(typeNode);
-        }
+    if (tsm.Node.isArrayTypeNode(node)) {
+        return visitTypeNode(node.getElementTypeNode());
     }
-    else if (tsm.Node.isArrayTypeNode(node)) {
-        visitTypeNode(node.getElementTypeNode());
+    if (tsm.Node.isTupleTypeNode(node)) {
+        return node
+            .getElements()
+            .map((element) => visitTypeNode(element))
+            .includes(true);
     }
-    else if (tsm.Node.isTupleTypeNode(node)) {
-        for (const element of node.getElements()) {
-            visitTypeNode(element);
-        }
+    if (tsm.Node.isParenthesizedTypeNode(node)) {
+        return visitTypeNode(node.getTypeNode());
     }
-    else if (tsm.Node.isParenthesizedTypeNode(node)) {
-        visitTypeNode(node.getTypeNode());
+    // Handles `readonly T[]`, `readonly [...]`, `keyof T`
+    if (tsm.Node.isTypeOperatorTypeNode(node)) {
+        return visitTypeNode(node.getTypeNode());
     }
-    else if (tsm.Node.isTypeLiteral(node)) {
-        for (const member of node.getMembers()) {
-            if (tsm.Node.isPropertySignature(member)) {
-                const typeNode = member.getTypeNode();
-                if (typeNode !== undefined) {
-                    visitTypeNode(typeNode);
-                }
-            }
-            else if (tsm.Node.isIndexSignatureDeclaration(member)) {
-                const typeNode = member.getReturnTypeNode();
-                if (typeNode !== undefined) {
-                    visitTypeNode(typeNode);
-                }
-            }
-        }
+    if (tsm.Node.isRestTypeNode(node)) {
+        return visitTypeNode(node.getTypeNode());
     }
+    if (tsm.Node.isNamedTupleMember(node)) {
+        return visitTypeNode(node.getTypeNode());
+    }
+    return false;
 };
 const isStringUnknownIndexSignature = (sig) => {
     const keyType = sig.getKeyTypeNode();
@@ -155,8 +176,10 @@ const replaceIfRecordUnknown = (node) => {
                 typeArgs[0].getText() === 'string' &&
                 typeArgs[1].getText() === 'unknown') {
                 node.replaceWithText('UnknownRecord');
+                return true;
             }
-            break;
+            // Recurse into type arguments (e.g. Record<string, Record<string, unknown>>)
+            return typeArgs.map((typeArg) => visitTypeNode(typeArg)).includes(true);
         }
         case 'Readonly': {
             // Check if it's Readonly<Record<string, unknown>>
@@ -171,14 +194,45 @@ const replaceIfRecordUnknown = (node) => {
                             innerTypeArgs[0].getText() === 'string' &&
                             innerTypeArgs[1].getText() === 'unknown') {
                             node.replaceWithText('UnknownRecord');
+                            return true;
                         }
                     }
                 }
+                // Otherwise, recurse into the type argument
+                return visitTypeNode(innerType);
             }
-            break;
+            return false;
+        }
+        default: {
+            // Recurse into type arguments for any other generic type
+            return node
+                .getTypeArguments()
+                .map((typeArg) => visitTypeNode(typeArg))
+                .includes(true);
         }
     }
 };
+const ensureUnknownRecordImport = (sourceFile) => {
+    const existingImport = sourceFile
+        .getImportDeclarations()
+        .find((decl) => decl.getModuleSpecifierValue() === UNKNOWN_RECORD_MODULE);
+    if (existingImport === undefined) {
+        sourceFile.insertImportDeclaration(0, {
+            moduleSpecifier: UNKNOWN_RECORD_MODULE,
+            namedImports: [{ name: UNKNOWN_RECORD_NAME, isTypeOnly: true }],
+        });
+        return;
+    }
+    const alreadyImported = existingImport
+        .getNamedImports()
+        .some((ni) => ni.getName() === UNKNOWN_RECORD_NAME);
+    if (alreadyImported)
+        return;
+    existingImport.addNamedImport({
+        name: UNKNOWN_RECORD_NAME,
+        isTypeOnly: true,
+    });
+};
 
 export { replaceRecordWithUnknownRecordTransformer };
 //# sourceMappingURL=replace-record-with-unknown-record.mjs.map

package/dist/functions/ast-transformers/replace-record-with-unknown-record.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"replace-record-with-unknown-record.mjs","sources":["../../../src/functions/ast-transformers/replace-record-with-unknown-record.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAAA;AAMA,MAAM,gBAAgB,GAAG,oCAAoC;AAE7D;;;AAGG;AACI,MAAM,yCAAyC,GACpD,OACG;AACC,IAAA,IAAI,EAAE,gBAAgB;AACtB,IAAA,SAAS,EAAE,CAAC,SAAS,KAAI;;QAEvB,mBAAmB,CAAC,SAAS,CAAC;;AAG9B,QAAA,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,EAAE;AAEzC,QAAA,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;YAClC,mBAAmB,CAAC,SAAS,CAAC;QAChC;IACF,CAAC;AACF,CAAA;AAEL,MAAM,mBAAmB,GAAG,CAC1B,SAAiD,KACzC;AACR,IAAA,MAAM,WAAW,GAAG,SAAS,CAAC,cAAc,EAAE;AAE9C,IAAA,KAAK,MAAM,SAAS,IAAI,WAAW,EAAE;AACnC,QAAA,IAAI,yBAAyB,CAAC,SAAS,EAAE,gBAAgB,CAAC,EAAE;YAC1D;QACF;AAEA,QAAA,MAAM,QAAQ,GAAG,SAAS,CAAC,WAAW,EAAE;QAExC,IAAI,QAAQ,KAAK,SAAS;YAAE;QAE5B,aAAa,CAAC,QAAQ,CAAC;IACzB;AAEA,IAAA,MAAM,UAAU,GAAG,SAAS,CAAC,aAAa,EAAE;AAE5C,IAAA,KAAK,MAAM,aAAa,IAAI,UAAU,EAAE;AACtC,QAAA,IAAI,yBAAyB,CAAC,aAAa,EAAE,gBAAgB,CAAC,EAAE;YAC9D;QACF;;AAGA,QAAA,MAAM,eAAe,GAAG,aAAa,CAAC,kBAAkB,EAAE;QAE1D,MAAM,yBAAyB,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,GAAG,KAAI;AAC7D,YAAA,MAAM,OAAO,GAAG,GAAG,CAAC,UAAU,EAAE;AAEhC,YAAA,MAAM,UAAU,GAAG,GAAG,CAAC,aAAa,EAAE;AAEtC,YAAA,QACE,OAAO,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,UAAU,CAAC,OAAO,EAAE,KAAK,SAAS;AAExE,QAAA,CAAC,CAAC;;QAGF,IAAI,yBAAyB,EAAE;AAC7B,YAAA,MAAM,UAAU,GAAG,aAAa,CAAC,aAAa,EAAE;AAEhD,YAAA,IACE,GAAG,CAAC,eAAe,CAAC,UAAU,EAAE,CAAC,CAAC;gBAClC,GAAG,CAAC,eAAe,CAAC,eAAe,EAAE,CAAC,CAAC,EACvC;;AAEA,gBAAA,MAAM,aAAa,GAAG,aAAa,CAAC,OAAO,EAAE;AAE7C,gBAAA,aAAa,CAAC,eAAe,CAC3B,eAAe,aAAa,CAAA,iBAAA,CAAmB,CAChD;gBAED;YACF;QACF;;QAGA,KAAK,MAAM,QAAQ,IAAI,aAAa,CAAC,aAAa,EAAE,EAAE;AACpD,YAAA,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,EAAE;YAEvC,IAAI,QAAQ,KAAK,SAAS;gBAAE;YAE5B,aAAa,CAAC,QAAQ,CAAC;QACzB;IACF;AACF,CAAC;AAED,MAAM,aAAa,GAAG,CAAC,IAAkB,KAAU;IACjD,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE;;QAElC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,KAAK,UAAU,EAAE;AAC/C,YAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,EAAE;YAExC,IAAI,GAAG,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE;AACpC,gBAAA,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC;gBAE3B,IAAI,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE;AACnC,oBAAA,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE;oBAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KACjC,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC,CAAC,CACxC;;AAGD,oBAAA,IACE,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC;AAC/B,wBAAA,GAAG,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC,CAAC;AACjC,wBAAA,6BAA6B,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAC3C;AACA,wBAAA,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC;wBAErC;oBACF;;oBAGA,aAAa,CAAC,OAAO,CAAC;oBAEtB;gBACF;YACF;QACF;QAEA,sBAAsB,CAAC,IAAI,CAAC;IAC9B;;IAGA,IAAI,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE;AAChC,QAAA,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE;QAEjC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KACjC,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC,CAAC,CACxC;;AAGD,QAAA,IACE,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC;AAC/B,YAAA,GAAG,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC,CAAC;AACjC,YAAA,6BAA6B,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAC3C;AACA,YAAA,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC;YAErC;QACF;IACF;;IAGA,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE;QAClC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE,EAAE;YAC1C,aAAa,CAAC,QAAQ,CAAC;QACzB;IACF;SAAO,IAAI,GAAG,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,EAAE;QAChD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE,EAAE;YAC1C,aAAa,CAAC,QAAQ,CAAC;QACzB;IACF;SAAO,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE;AACzC,QAAA,aAAa,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC1C;SAAO,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE;QACzC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE;YACxC,aAAa,CAAC,OAAO,CAAC;QACxB;IACF;SAAO,IAAI,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,EAAE;AACjD,QAAA,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACnC;SAAO,IAAI,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE;QACvC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE;YACtC,IAAI,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE;AACxC,gBAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE;AAErC,gBAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;oBAC1B,aAAa,CAAC,QAAQ,CAAC;gBACzB;YACF;iBAAO,IAAI,GAAG,CAAC,IAAI,CAAC,2BAA2B,CAAC,MAAM,CAAC,EAAE;AACvD,gBAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,iBAAiB,EAAE;AAE3C,gBAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;oBAC1B,aAAa,CAAC,QAAQ,CAAC;gBACzB;YACF;QACF;IACF;AACF,CAAC;AAED,MAAM,6BAA6B,GAAG,CACpC,GAAkC,KACvB;AACX,IAAA,MAAM,OAAO,GAAG,GAAG,CAAC,cAAc,EAAE;AAEpC,IAAA,MAAM,UAAU,GAAG,GAAG,CAAC,iBAAiB,EAAE;AAE1C,IAAA,OAAO,OAAO,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,UAAU,EAAE,OAAO,EAAE,KAAK,SAAS;AAC9E,CAAC;AAED,MAAM,sBAAsB,GAAG,CAAC,IAA2B,KAAU;IACnE,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE;IAE7C,QAAQ,QAAQ;QACd,KAAK,QAAQ,EAAE;;AAEb,YAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,EAAE;AAExC,YAAA,IACE,GAAG,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC;AAChC,gBAAA,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,QAAQ;gBAClC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,SAAS,EACnC;AACA,gBAAA,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC;YACvC;YAEA;QACF;QACA,KAAK,UAAU,EAAE;;AAEf,YAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,EAAE;YAExC,IAAI,GAAG,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE;AACpC,gBAAA,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC;gBAE7B,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE;oBACvC,MAAM,aAAa,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE;AAEvD,oBAAA,IAAI,aAAa,KAAK,QAAQ,EAAE;AAC9B,wBAAA,MAAM,aAAa,GAAG,SAAS,CAAC,gBAAgB,EAAE;AAElD,wBAAA,IACE,GAAG,CAAC,eAAe,CAAC,aAAa,EAAE,CAAC,CAAC;AACrC,4BAAA,aAAa,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,QAAQ;4BACvC,aAAa,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,SAAS,EACxC;AACA,4BAAA,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC;wBACvC;oBACF;gBACF;YACF;YAEA;QACF;;AAMJ,CAAC;;;;"}
+{"version":3,"file":"replace-record-with-unknown-record.mjs","sources":["../../../src/functions/ast-transformers/replace-record-with-unknown-record.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-codemod-lib",
-  "version": "2.1.5",
+  "version": "2.1.6",
   "private": false,
   "keywords": [
     "typescript",

package/src/cmd/append-as-const.mts

@@ -9,7 +9,7 @@ const transformer = appendAsConstTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.1.5',
+  version: '2.1.6',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,

package/src/cmd/convert-interface-to-type.mts

@@ -9,7 +9,7 @@ const transformer = convertInterfaceToTypeTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.1.5',
+  version: '2.1.6',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,

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

@@ -9,7 +9,7 @@ const transformer = convertToReadonlyTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.1.5',
+  version: '2.1.6',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,

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

@@ -9,7 +9,7 @@ const transformer = replaceAnyWithUnknownTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.1.5',
+  version: '2.1.6',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,

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

@@ -9,7 +9,7 @@ const transformer = replaceRecordWithUnknownRecordTransformer();
 
 const cmdDef = cmd.command({
   name: transformer.name,
-  version: '2.1.5',
+  version: '2.1.6',
   args: {
     baseDir: cmd.positional({
       type: cmd.string,

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

@@ -6,95 +6,113 @@ import { type TsMorphTransformer } from './types.mjs';
 
 const TRANSFORMER_NAME = 'replace-record-with-unknown-record';
 
+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`
+ * 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
+ * source file (or merges into an existing import from `'ts-type-forge'`).
  */
 export const replaceRecordWithUnknownRecordTransformer =
   (): TsMorphTransformer =>
     ({
       name: TRANSFORMER_NAME,
       transform: (sourceAst) => {
-        // Process top-level declarations
-        processDeclarations(sourceAst);
-
-        // Process declarations inside namespaces/modules
-        const namespaces = sourceAst.getModules();
-
-        for (const namespace of namespaces) {
-          processDeclarations(namespace);
+        const containerModifications = [
+          processDeclarations(sourceAst),
+          ...sourceAst
+            .getModules()
+            .map((namespace) => processDeclarations(namespace)),
+        ];
+
+        if (containerModifications.includes(true)) {
+          ensureUnknownRecordImport(sourceAst);
         }
       },
     }) as const;
 
 const processDeclarations = (
   container: tsm.SourceFile | tsm.ModuleDeclaration,
-): void => {
-  const typeAliases = container.getTypeAliases();
-
-  for (const typeAlias of typeAliases) {
+): boolean => {
+  const typeAliasModifications = container.getTypeAliases().map((typeAlias) => {
     if (hasDisableNextLineComment(typeAlias, TRANSFORMER_NAME)) {
-      continue;
+      return false;
     }
 
     const typeNode = typeAlias.getTypeNode();
 
-    if (typeNode === undefined) continue;
+    if (typeNode === undefined) return false;
 
-    visitTypeNode(typeNode);
-  }
+    return visitTypeNode(typeNode);
+  });
 
-  const interfaces = container.getInterfaces();
+  const interfaceModifications = container
+    .getInterfaces()
+    .map((interfaceDecl) => processInterfaceDeclaration(interfaceDecl));
 
-  for (const interfaceDecl of interfaces) {
-    if (hasDisableNextLineComment(interfaceDecl, TRANSFORMER_NAME)) {
-      continue;
-    }
+  return [...typeAliasModifications, ...interfaceModifications].includes(true);
+};
 
-    // Check if interface has index signature [k: string]: unknown
-    const indexSignatures = interfaceDecl.getIndexSignatures();
+const processInterfaceDeclaration = (
+  interfaceDecl: tsm.InterfaceDeclaration,
+): boolean => {
+  if (hasDisableNextLineComment(interfaceDecl, TRANSFORMER_NAME)) {
+    return false;
+  }
 
-    const hasStringUnknownSignature = indexSignatures.some((sig) => {
-      const keyType = sig.getKeyType();
+  // Check if interface has index signature [k: string]: unknown
+  const indexSignatures = interfaceDecl.getIndexSignatures();
 
-      const returnType = sig.getReturnType();
+  const hasStringUnknownSignature = indexSignatures.some((sig) => {
+    const keyType = sig.getKeyType();
 
-      return (
-        keyType.getText() === 'string' && returnType.getText() === 'unknown'
-      );
-    });
+    const returnType = sig.getReturnType();
 
-    // If it has the signature and no other members, replace entire interface with type alias
-    if (hasStringUnknownSignature) {
-      const properties = interfaceDecl.getProperties();
+    return keyType.getText() === 'string' && returnType.getText() === 'unknown';
+  });
 
-      if (
-        Arr.isArrayOfLength(properties, 0) &&
-        Arr.isArrayOfLength(indexSignatures, 1)
-      ) {
-        // Replace interface with type alias
-        const interfaceName = interfaceDecl.getName();
+  // 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.isArrayOfLength(interfaceDecl.getProperties(), 0) &&
+    Arr.isArrayOfLength(indexSignatures, 1) &&
+    Arr.isArrayOfLength(interfaceDecl.getTypeParameters(), 0) &&
+    Arr.isArrayOfLength(interfaceDecl.getExtends(), 0) &&
+    !interfaceDecl.hasDeclareKeyword() &&
+    !interfaceDecl.hasDefaultKeyword()
+  ) {
+    const exportPrefix = interfaceDecl.hasExportKeyword() ? 'export ' : '';
 
-        interfaceDecl.replaceWithText(
-          `export type ${interfaceName} = UnknownRecord;`,
-        );
+    const interfaceName = interfaceDecl.getName();
 
-        continue;
-      }
-    }
+    interfaceDecl.replaceWithText(
+      `${exportPrefix}type ${interfaceName} = UnknownRecord;`,
+    );
+
+    return true;
+  }
 
-    // Otherwise, check properties for Record types
-    for (const property of interfaceDecl.getProperties()) {
+  // Otherwise, check properties for Record types
+  return interfaceDecl
+    .getProperties()
+    .map((property) => {
       const typeNode = property.getTypeNode();
 
-      if (typeNode === undefined) continue;
+      if (typeNode === undefined) return false;
 
-      visitTypeNode(typeNode);
-    }
-  }
+      return visitTypeNode(typeNode);
+    })
+    .includes(true);
 };
 
-const visitTypeNode = (node: tsm.TypeNode): void => {
+const visitTypeNode = (node: tsm.TypeNode): boolean => {
   if (tsm.Node.isTypeReference(node)) {
     // Check if it's Readonly<{ [k: string]: unknown }>
     if (node.getTypeName().getText() === 'Readonly') {
@@ -118,18 +136,16 @@ const visitTypeNode = (node: tsm.TypeNode): void => {
           ) {
             node.replaceWithText('UnknownRecord');
 
-            return;
+            return true;
           }
 
           // Otherwise, recurse into the type literal to visit its properties
-          visitTypeNode(typeArg);
-
-          return;
+          return visitTypeNode(typeArg);
         }
       }
     }
 
-    replaceIfRecordUnknown(node);
+    return replaceIfRecordUnknown(node);
   }
 
   // Check for type literal { [k: string]: unknown }
@@ -148,44 +164,65 @@ const visitTypeNode = (node: tsm.TypeNode): void => {
     ) {
       node.replaceWithText('UnknownRecord');
 
-      return;
+      return true;
     }
-  }
 
-  // Recursively visit child type nodes
-  if (tsm.Node.isUnionTypeNode(node)) {
-    for (const typeNode of node.getTypeNodes()) {
-      visitTypeNode(typeNode);
-    }
-  } else if (tsm.Node.isIntersectionTypeNode(node)) {
-    for (const typeNode of node.getTypeNodes()) {
-      visitTypeNode(typeNode);
-    }
-  } else if (tsm.Node.isArrayTypeNode(node)) {
-    visitTypeNode(node.getElementTypeNode());
-  } else if (tsm.Node.isTupleTypeNode(node)) {
-    for (const element of node.getElements()) {
-      visitTypeNode(element);
-    }
-  } else if (tsm.Node.isParenthesizedTypeNode(node)) {
-    visitTypeNode(node.getTypeNode());
-  } else if (tsm.Node.isTypeLiteral(node)) {
-    for (const member of node.getMembers()) {
-      if (tsm.Node.isPropertySignature(member)) {
-        const typeNode = member.getTypeNode();
-
-        if (typeNode !== undefined) {
-          visitTypeNode(typeNode);
+    return members
+      .map((member) => {
+        if (tsm.Node.isPropertySignature(member)) {
+          const typeNode = member.getTypeNode();
+
+          return typeNode === undefined ? false : visitTypeNode(typeNode);
         }
-      } else if (tsm.Node.isIndexSignatureDeclaration(member)) {
-        const typeNode = member.getReturnTypeNode();
 
-        if (typeNode !== undefined) {
-          visitTypeNode(typeNode);
+        if (tsm.Node.isIndexSignatureDeclaration(member)) {
+          const typeNode = member.getReturnTypeNode();
+
+          return typeNode === undefined ? false : visitTypeNode(typeNode);
         }
-      }
-    }
+
+        return false;
+      })
+      .includes(true);
+  }
+
+  // Recursively visit child type nodes
+  if (tsm.Node.isUnionTypeNode(node) || tsm.Node.isIntersectionTypeNode(node)) {
+    return node
+      .getTypeNodes()
+      .map((typeNode) => visitTypeNode(typeNode))
+      .includes(true);
+  }
+
+  if (tsm.Node.isArrayTypeNode(node)) {
+    return visitTypeNode(node.getElementTypeNode());
+  }
+
+  if (tsm.Node.isTupleTypeNode(node)) {
+    return node
+      .getElements()
+      .map((element) => visitTypeNode(element))
+      .includes(true);
+  }
+
+  if (tsm.Node.isParenthesizedTypeNode(node)) {
+    return visitTypeNode(node.getTypeNode());
+  }
+
+  // Handles `readonly T[]`, `readonly [...]`, `keyof T`
+  if (tsm.Node.isTypeOperatorTypeNode(node)) {
+    return visitTypeNode(node.getTypeNode());
+  }
+
+  if (tsm.Node.isRestTypeNode(node)) {
+    return visitTypeNode(node.getTypeNode());
   }
+
+  if (tsm.Node.isNamedTupleMember(node)) {
+    return visitTypeNode(node.getTypeNode());
+  }
+
+  return false;
 };
 
 const isStringUnknownIndexSignature = (
@@ -198,7 +235,7 @@ const isStringUnknownIndexSignature = (
   return keyType.getText() === 'string' && returnType?.getText() === 'unknown';
 };
 
-const replaceIfRecordUnknown = (node: tsm.TypeReferenceNode): void => {
+const replaceIfRecordUnknown = (node: tsm.TypeReferenceNode): boolean => {
   const typeName = node.getTypeName().getText();
 
   switch (typeName) {
@@ -212,9 +249,12 @@ const replaceIfRecordUnknown = (node: tsm.TypeReferenceNode): void => {
         typeArgs[1].getText() === 'unknown'
       ) {
         node.replaceWithText('UnknownRecord');
+
+        return true;
       }
 
-      break;
+      // Recurse into type arguments (e.g. Record<string, Record<string, unknown>>)
+      return typeArgs.map((typeArg) => visitTypeNode(typeArg)).includes(true);
     }
     case 'Readonly': {
       // Check if it's Readonly<Record<string, unknown>>
@@ -235,16 +275,51 @@ const replaceIfRecordUnknown = (node: tsm.TypeReferenceNode): void => {
               innerTypeArgs[1].getText() === 'unknown'
             ) {
               node.replaceWithText('UnknownRecord');
+
+              return true;
             }
           }
         }
+
+        // Otherwise, recurse into the type argument
+        return visitTypeNode(innerType);
       }
 
-      break;
+      return false;
     }
 
     default: {
-      break;
+      // Recurse into type arguments for any other generic type
+      return node
+        .getTypeArguments()
+        .map((typeArg) => visitTypeNode(typeArg))
+        .includes(true);
     }
   }
 };
+
+const ensureUnknownRecordImport = (sourceFile: tsm.SourceFile): void => {
+  const existingImport = sourceFile
+    .getImportDeclarations()
+    .find((decl) => decl.getModuleSpecifierValue() === UNKNOWN_RECORD_MODULE);
+
+  if (existingImport === undefined) {
+    sourceFile.insertImportDeclaration(0, {
+      moduleSpecifier: UNKNOWN_RECORD_MODULE,
+      namedImports: [{ name: UNKNOWN_RECORD_NAME, isTypeOnly: true }],
+    });
+
+    return;
+  }
+
+  const alreadyImported = existingImport
+    .getNamedImports()
+    .some((ni) => ni.getName() === UNKNOWN_RECORD_NAME);
+
+  if (alreadyImported) return;
+
+  existingImport.addNamedImport({
+    name: UNKNOWN_RECORD_NAME,
+    isTypeOnly: true,
+  });
+};

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

@@ -0,0 +1,312 @@
+/* eslint-disable tree-shakable/import-star */
+/* eslint-disable vitest/expect-expect */
+import dedent from 'dedent';
+import * as prettierPluginEstree from 'prettier/plugins/estree';
+import * as prettierPluginTypeScript from 'prettier/plugins/typescript';
+import * as prettier from 'prettier/standalone';
+import { replaceRecordWithUnknownRecordTransformer } from './replace-record-with-unknown-record.mjs';
+import { transformSourceCode } from './transform-source-code.mjs';
+
+const testFn = async ({
+  source,
+  expected,
+}: Readonly<{
+  source: string;
+  expected: string;
+}>): Promise<void> => {
+  const transformed = await formatter(
+    transformSourceCode(source, false, [
+      replaceRecordWithUnknownRecordTransformer(),
+    ]),
+  );
+
+  const expectedFormatted = await formatter(expected);
+
+  expect(transformed).toBe(expectedFormatted);
+};
+
+const formatter = (code: string): Promise<string> =>
+  prettier.format(code, {
+    parser: 'typescript',
+    plugins: [prettierPluginTypeScript, prettierPluginEstree],
+  });
+
+describe(replaceRecordWithUnknownRecordTransformer, () => {
+  test.each([
+    {
+      name: 'Simple Record<string, unknown> with import added',
+      source: 'type Foo = Record<string, unknown>;',
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Readonly<Record<string, unknown>>',
+      source: 'type Foo = Readonly<Record<string, unknown>>;',
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Type literal { [k: string]: unknown }',
+      source: 'type Foo = { [k: string]: unknown };',
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Readonly type literal Readonly<{ [k: string]: unknown }>',
+      source: 'type Foo = Readonly<{ [k: string]: unknown }>;',
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Exported interface with only [k: string]: unknown',
+      source: dedent`
+        export interface Foo {
+          [k: string]: unknown;
+        }
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        export type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Non-exported interface with only [k: string]: unknown preserves missing export',
+      source: dedent`
+        interface Foo {
+          [k: string]: unknown;
+        }
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Generic interface with [k: string]: unknown is left untouched',
+      source: dedent`
+        export interface Foo<T> {
+          [k: string]: unknown;
+        }
+      `,
+      expected: dedent`
+        export interface Foo<T> {
+          [k: string]: unknown;
+        }
+      `,
+    },
+    {
+      name: 'Interface with extends + [k: string]: unknown is left untouched',
+      source: dedent`
+        interface Bar {
+          a: number;
+        }
+        export interface Foo extends Bar {
+          [k: string]: unknown;
+        }
+      `,
+      expected: dedent`
+        interface Bar {
+          a: number;
+        }
+        export interface Foo extends Bar {
+          [k: string]: unknown;
+        }
+      `,
+    },
+    {
+      name: 'declare interface with [k: string]: unknown is left untouched',
+      source: dedent`
+        declare interface Foo {
+          [k: string]: unknown;
+        }
+      `,
+      expected: dedent`
+        declare interface Foo {
+          [k: string]: unknown;
+        }
+      `,
+    },
+    {
+      name: 'Generic interface still has its property types transformed',
+      source: dedent`
+        export interface Foo<T> {
+          value: Record<string, unknown>;
+          tag: T;
+        }
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        export interface Foo<T> {
+          value: UnknownRecord;
+          tag: T;
+        }
+      `,
+    },
+    {
+      name: 'Record nested under readonly tuple (regression: TypeOperator)',
+      source: dedent`
+        type Foo =
+          | readonly [
+              'always',
+              Readonly<{
+                patternOptions?: Readonly<Record<string, unknown>>;
+              }>,
+            ];
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo =
+          | readonly [
+              'always',
+              Readonly<{
+                patternOptions?: UnknownRecord;
+              }>,
+            ];
+      `,
+    },
+    {
+      name: 'Record nested under readonly array (regression: TypeOperator)',
+      source: dedent`
+        type Foo = Readonly<{
+          forbid?: readonly (string | Record<string, unknown>)[];
+        }>;
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = Readonly<{
+          forbid?: readonly (string | UnknownRecord)[];
+        }>;
+      `,
+    },
+    {
+      name: 'readonly Readonly<Record<...>>[] at type alias root (regression)',
+      source: 'type Foo = readonly Readonly<Record<string, unknown>>[];',
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = readonly UnknownRecord[];
+      `,
+    },
+    {
+      name: 'Record inside namespace',
+      source: dedent`
+        namespace Ns {
+          export type Foo = Record<string, unknown>;
+        }
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        namespace Ns {
+          export type Foo = UnknownRecord;
+        }
+      `,
+    },
+    {
+      name: 'Record nested in union inside namespace',
+      source: dedent`
+        namespace Ns {
+          export type Options = Readonly<{
+            targets:
+              | string
+              | readonly unknown[]
+              | Readonly<Record<string, unknown>>;
+          }>;
+        }
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        namespace Ns {
+          export type Options = Readonly<{
+            targets: string | readonly unknown[] | UnknownRecord;
+          }>;
+        }
+      `,
+    },
+    {
+      name: 'No transformation -> no import added',
+      source: 'type Foo = string;',
+      expected: 'type Foo = string;',
+    },
+    {
+      name: 'Existing UnknownRecord import is not duplicated',
+      source: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = Record<string, unknown>;
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Merged into existing ts-type-forge import with other names',
+      source: dedent`
+        import { type DeepReadonly } from 'ts-type-forge';
+
+        type Foo = Record<string, unknown>;
+      `,
+      expected: dedent`
+        import { type DeepReadonly, type UnknownRecord } from 'ts-type-forge';
+
+        type Foo = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Disable comment skips the type alias and does not add import',
+      source: dedent`
+        // transformer-ignore-next-line
+        type Foo = Record<string, unknown>;
+      `,
+      expected: dedent`
+        // transformer-ignore-next-line
+        type Foo = Record<string, unknown>;
+      `,
+    },
+    {
+      name: 'Transformer-specific disable comment is respected',
+      source: dedent`
+        // transformer-ignore-next-line replace-record-with-unknown-record
+        type A = Record<string, unknown>;
+        type B = Record<string, unknown>;
+      `,
+      expected: dedent`
+        import { type UnknownRecord } from 'ts-type-forge';
+
+        // transformer-ignore-next-line replace-record-with-unknown-record
+        type A = Record<string, unknown>;
+        type B = UnknownRecord;
+      `,
+    },
+    {
+      name: 'Record<string, string> (non-unknown value) is left alone',
+      source: 'type Foo = Record<string, string>;',
+      expected: 'type Foo = Record<string, string>;',
+    },
+    {
+      name: 'Record<number, unknown> (non-string key) is left alone',
+      source: 'type Foo = Record<number, unknown>;',
+      expected: 'type Foo = Record<number, unknown>;',
+    },
+  ])('$name', testFn);
+});