@elliots/typical 0.1.4 → 0.1.5

package/src/transformer.ts

@@ -1,6 +1,9 @@
 import ts from "typescript";
+import fs from "fs";
+import path from "path";
 import { loadConfig, TypicalConfig } from "./config.js";
 import { shouldTransformFile } from "./file-filter.js";
+import { hoistRegexConstructors } from "./regex-hoister.js";
 
 import { transform as typiaTransform } from "typia/lib/transform.js";
 import { setupTsProgram } from "./setup.js";
@@ -89,6 +92,10 @@ export class TypicalTransformer {
       };
 
       return (sourceFile: ts.SourceFile) => {
+        // Check if this file should be transformed based on include/exclude patterns
+        if (!this.shouldTransformFile(sourceFile.fileName)) {
+          return sourceFile; // Return unchanged for excluded files
+        }
 
         if (process.env.DEBUG) {
           console.log("TYPICAL: processing ", sourceFile.fileName);
@@ -112,6 +119,28 @@ export class TypicalTransformer {
           console.log("TYPICAL: Before typia transform (first 500 chars):", transformedCode.substring(0, 500));
         }
 
+        // Write intermediate file if debug option is enabled
+        if (this.config.debug?.writeIntermediateFiles) {
+          const compilerOptions = this.program.getCompilerOptions();
+          const outDir = compilerOptions.outDir || ".";
+          const rootDir = compilerOptions.rootDir || ".";
+
+          // Calculate the relative path from rootDir
+          const relativePath = path.relative(rootDir, sourceFile.fileName);
+          // Change extension to .typical.ts to indicate intermediate state
+          const intermediateFileName = relativePath.replace(/\.tsx?$/, ".typical.ts");
+          const intermediateFilePath = path.join(outDir, intermediateFileName);
+
+          // Ensure directory exists
+          const dir = path.dirname(intermediateFilePath);
+          if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+          }
+
+          fs.writeFileSync(intermediateFilePath, transformedCode);
+          console.log(`TYPICAL: Wrote intermediate file: ${intermediateFilePath}`);
+        }
+
         if (transformedCode.includes("typia.")) {
           try {
             // Create a new source file from our transformed code
@@ -200,7 +229,10 @@ export class TypicalTransformer {
                 if (stmt.importClause?.isTypeOnly) {
                   continue;
                 }
-                syntheticStatements.push(this.recreateImportDeclaration(stmt, factory));
+                const recreated = this.recreateImportDeclaration(stmt, factory, newProgram.getTypeChecker());
+                if (recreated) {
+                  syntheticStatements.push(recreated);
+                }
               } else {
                 syntheticStatements.push(stmt);
               }
@@ -216,6 +248,15 @@ export class TypicalTransformer {
               typiaTransformed.hasNoDefaultLib,
               typiaTransformed.libReferenceDirectives
             );
+
+            // Hoist RegExp constructors to top-level constants for performance
+            if (this.config.hoistRegex !== false) {
+              transformedSourceFile = hoistRegexConstructors(
+                transformedSourceFile,
+                this.ts,
+                factory
+              );
+            }
           } catch (error) {
             console.warn("Failed to apply typia transformer:", sourceFile.fileName, error);
           }
@@ -233,8 +274,9 @@ export class TypicalTransformer {
    */
   private recreateImportDeclaration(
     importDecl: ts.ImportDeclaration,
-    factory: ts.NodeFactory
-  ): ts.ImportDeclaration {
+    factory: ts.NodeFactory,
+    typeChecker: ts.TypeChecker
+  ): ts.ImportDeclaration | undefined {
     let importClause: ts.ImportClause | undefined;
 
     if (importDecl.importClause) {
@@ -249,20 +291,54 @@ export class TypicalTransformer {
           );
         } else if (this.ts.isNamedImports(clause.namedBindings)) {
           // import { foo, bar } from "baz"
-          const elements = clause.namedBindings.elements.map((el) =>
-            factory.createImportSpecifier(
-              el.isTypeOnly,
-              el.propertyName ? factory.createIdentifier(el.propertyName.text) : undefined,
-              factory.createIdentifier(el.name.text)
-            )
-          );
-          namedBindings = factory.createNamedImports(elements);
+          // Filter out type-only imports (explicit or inferred from symbol)
+          const elements = clause.namedBindings.elements
+            .filter((el) => {
+              // Skip explicit type-only specifiers
+              if (el.isTypeOnly) return false;
+              // Check if the symbol is type-only (interface, type alias, etc.)
+              let symbol = typeChecker.getSymbolAtLocation(el.name);
+              // Follow alias to get the actual exported symbol
+              if (symbol && symbol.flags & this.ts.SymbolFlags.Alias) {
+                symbol = typeChecker.getAliasedSymbol(symbol);
+              }
+              if (symbol) {
+                const declarations = symbol.getDeclarations();
+                if (declarations && declarations.length > 0) {
+                  // If all declarations are type-only, skip this import
+                  const allTypeOnly = declarations.every((decl) =>
+                    this.ts.isInterfaceDeclaration(decl) ||
+                    this.ts.isTypeAliasDeclaration(decl) ||
+                    this.ts.isTypeLiteralNode(decl)
+                  );
+                  if (allTypeOnly) return false;
+                }
+              }
+              return true;
+            })
+            .map((el) =>
+              factory.createImportSpecifier(
+                false,
+                el.propertyName ? factory.createIdentifier(el.propertyName.text) : undefined,
+                factory.createIdentifier(el.name.text)
+              )
+            );
+          // Only create named imports if there are non-type specifiers
+          if (elements.length > 0) {
+            namedBindings = factory.createNamedImports(elements);
+          }
         }
       }
 
+      // Skip import entirely if no default import and no named bindings remain
+      const defaultName = clause.name ? factory.createIdentifier(clause.name.text) : undefined;
+      if (!defaultName && !namedBindings) {
+        return undefined;
+      }
+
       importClause = factory.createImportClause(
         clause.isTypeOnly,
-        clause.name ? factory.createIdentifier(clause.name.text) : undefined,
+        defaultName,
         namedBindings
       );
     }
@@ -289,11 +365,6 @@ export class TypicalTransformer {
   ): ts.SourceFile {
     const { ts } = ctx;
 
-    // Check if this file should be transformed
-    if (!this.shouldTransformFile(sourceFile.fileName)) {
-      return sourceFile; // Return unchanged for excluded files
-    }
-
     if (!sourceFile.fileName.includes('transformer.test.ts')) {  
       // Check if this file has already been transformed by us
       const sourceText = sourceFile.getFullText();
@@ -328,115 +399,22 @@ export class TypicalTransformer {
             if (node.arguments.length > 0) {
               const arg = node.arguments[0];
               const argType = typeChecker.getTypeAtLocation(arg);
-              const typeFlags = argType.flags;
-              // Skip if type is any (1) or unknown (2)
-              if (typeFlags & ts.TypeFlags.Any || typeFlags & ts.TypeFlags.Unknown) {
+              if (this.isAnyOrUnknownTypeFlags(argType)) {
                 return node; // Don't transform JSON.stringify for any/unknown types
               }
             }
 
             if (this.config.reusableValidators) {
-              // For JSON.stringify, try to infer the type from the argument
-              let typeText = "unknown";
-              let typeNodeForCache: ts.TypeNode | undefined;
-
-              if (node.arguments.length > 0) {
-                const arg = node.arguments[0];
-
-                // Check if it's a type assertion
-                if (ts.isAsExpression(arg)) {
-                  // For type assertions, use the asserted type directly
-                  const assertedType = arg.type;
-                  const objectType =
-                    typeChecker.getTypeFromTypeNode(assertedType);
-
-                  const typeNode = assertedType;
-
-                  if (typeNode) {
-                    const typeString = typeChecker.typeToString(objectType);
-                    typeText = `Asserted_${typeString.replace(
-                      /[^a-zA-Z0-9_]/g,
-                      "_"
-                    )}`;
-                    typeNodeForCache = typeNode;
-                  } else {
-                    typeText = "unknown";
-                    typeNodeForCache = ctx.factory.createKeywordTypeNode(
-                      ctx.ts.SyntaxKind.UnknownKeyword
-                    );
-                  }
-                } else if (ts.isObjectLiteralExpression(arg)) {
-                  // For object literals, use the type checker to get the actual type
-                  const objectType = typeChecker.getTypeAtLocation(arg);
-
-                  const typeNode = typeChecker.typeToTypeNode(
-                    objectType,
-                    arg,
-                    ts.NodeBuilderFlags.InTypeAlias
-                  );
-
-                  if (typeNode) {
-                    const propNames = arg.properties
-                      .map((prop) => {
-                        if (ts.isShorthandPropertyAssignment(prop)) {
-                          return prop.name.text;
-                        } else if (
-                          ts.isPropertyAssignment(prop) &&
-                          ts.isIdentifier(prop.name)
-                        ) {
-                          return prop.name.text;
-                        }
-                        return "unknown";
-                      })
-                      .sort()
-                      .join("_");
-
-                    typeText = `ObjectLiteral_${propNames}`;
-                    typeNodeForCache = typeNode;
-                  } else {
-                    // typeText = "unknown";
-                    // typeNodeForCache = ctx.factory.createKeywordTypeNode(
-                    //   ctx.ts.SyntaxKind.UnknownKeyword
-                    // );
-                    throw new Error('unknown type node for object literal: ' + arg.getText());
-                  }
-                } else {
-                  // For other expressions, try to get the type from the type checker
-                  const argType = typeChecker.getTypeAtLocation(arg);
-
-                  const typeNode = typeChecker.typeToTypeNode(
-                    argType,
-                    arg,
-                    ts.NodeBuilderFlags.InTypeAlias
-                  );
-                  if (typeNode) {
-                    const typeString = typeChecker.typeToString(argType);
-                    typeText = `Expression_${typeString.replace(
-                      /[^a-zA-Z0-9_]/g,
-                      "_"
-                    )}`;
-                    typeNodeForCache = typeNode;
-                  } else {
-                    typeText = "unknown";
-                    typeNodeForCache = ctx.factory.createKeywordTypeNode(
-                      ctx.ts.SyntaxKind.UnknownKeyword
-                    )
-                  }
-                }
-              }
-
-              const stringifierName = this.getOrCreateStringifier(
-                typeText,
-                typeNodeForCache!
-              );
+              // Infer type from argument
+              const arg = node.arguments[0];
+              const { typeText, typeNode } = this.inferStringifyType(arg, typeChecker, ctx);
 
-              const newCall = ctx.factory.createCallExpression(
+              const stringifierName = this.getOrCreateStringifier(typeText, typeNode);
+              return ctx.factory.createCallExpression(
                 ctx.factory.createIdentifier(stringifierName),
                 undefined,
                 node.arguments
               );
-
-              return newCall;
             } else {
               // Use inline typia.json.stringify
               return ctx.factory.updateCallExpression(
@@ -491,13 +469,7 @@ export class TypicalTransformer {
               parent = parent.parent;
             }
 
-            // Skip transformation if target type is any or unknown
-            const isAnyOrUnknown = targetType && (
-              targetType.kind === ts.SyntaxKind.AnyKeyword ||
-              targetType.kind === ts.SyntaxKind.UnknownKeyword
-            );
-
-            if (isAnyOrUnknown) {
+            if (targetType && this.isAnyOrUnknownType(targetType)) {
               // Don't transform JSON.parse for any/unknown types
               return node;
             }
@@ -509,9 +481,8 @@ export class TypicalTransformer {
             }
 
             if (this.config.reusableValidators && targetType) {
-              // Use reusable parser - use typeToString
-              const targetTypeObj = typeChecker.getTypeFromTypeNode(targetType);
-              const typeText = typeChecker.typeToString(targetTypeObj);
+              // Use reusable parser - use typeNode text to preserve local aliases
+              const typeText = this.getTypeKey(targetType, typeChecker);
               const parserName = this.getOrCreateParser(typeText, targetType);
 
               const newCall = ctx.factory.createCallExpression(
@@ -544,6 +515,52 @@ export class TypicalTransformer {
         }
       }
 
+      // Transform type assertions (as expressions) when validateCasts is enabled
+      // e.g., `obj as User` becomes `__typical_assert_N(obj)`
+      if (this.config.validateCasts && ts.isAsExpression(node)) {
+        const targetType = node.type;
+
+        // Skip 'as any' and 'as unknown' casts - these are intentional escapes
+        if (this.isAnyOrUnknownType(targetType)) {
+          return ctx.ts.visitEachChild(node, visit, ctx.context);
+        }
+
+        // Skip primitive types - no runtime validation needed
+        if (targetType.kind === ts.SyntaxKind.StringKeyword ||
+            targetType.kind === ts.SyntaxKind.NumberKeyword ||
+            targetType.kind === ts.SyntaxKind.BooleanKeyword) {
+          return ctx.ts.visitEachChild(node, visit, ctx.context);
+        }
+
+        needsTypiaImport = true;
+
+        // Visit the expression first to transform any nested casts
+        const visitedExpression = ctx.ts.visitNode(node.expression, visit) as ts.Expression;
+
+        if (this.config.reusableValidators) {
+          // Use typeNode text to preserve local aliases
+          const typeText = this.getTypeKey(targetType, typeChecker);
+          const validatorName = this.getOrCreateValidator(typeText, targetType);
+
+          // Replace `expr as Type` with `__typical_assert_N(expr)`
+          return ctx.factory.createCallExpression(
+            ctx.factory.createIdentifier(validatorName),
+            undefined,
+            [visitedExpression]
+          );
+        } else {
+          // Inline validator: typia.assert<Type>(expr)
+          return ctx.factory.createCallExpression(
+            ctx.factory.createPropertyAccessExpression(
+              ctx.factory.createIdentifier("typia"),
+              "assert"
+            ),
+            [targetType],
+            [visitedExpression]
+          );
+        }
+      }
+
       // Transform function declarations
       if (ts.isFunctionDeclaration(node)) {
         needsTypiaImport = true;
@@ -565,139 +582,6 @@ export class TypicalTransformer {
       return ctx.ts.visitEachChild(node, visit, ctx.context);
     };
 
-    // Helper functions for flow analysis
-    const getRootIdentifier = (expr: ts.Expression): string | undefined => {
-      if (ts.isIdentifier(expr)) {
-        return expr.text;
-      }
-      if (ts.isPropertyAccessExpression(expr)) {
-        return getRootIdentifier(expr.expression);
-      }
-      return undefined;
-    };
-
-    const containsReference = (expr: ts.Expression, name: string): boolean => {
-      if (ts.isIdentifier(expr) && expr.text === name) {
-        return true;
-      }
-      if (ts.isPropertyAccessExpression(expr)) {
-        return containsReference(expr.expression, name);
-      }
-      if (ts.isElementAccessExpression(expr)) {
-        return containsReference(expr.expression, name) ||
-               containsReference(expr.argumentExpression as ts.Expression, name);
-      }
-      // Check all children
-      let found = false;
-      ts.forEachChild(expr, (child) => {
-        if (ts.isExpression(child) && containsReference(child, name)) {
-          found = true;
-        }
-      });
-      return found;
-    };
-
-    // Check if a validated variable has been tainted in the function body
-    const isTainted = (varName: string, body: ts.Block): boolean => {
-      let tainted = false;
-
-      // First pass: collect aliases (variables that reference properties of varName)
-      // e.g., const addr = user.address; -> addr is an alias
-      const aliases = new Set<string>([varName]);
-
-      const collectAliases = (node: ts.Node): void => {
-        // Look for: const/let x = varName.property or const/let x = varName
-        if (ts.isVariableStatement(node)) {
-          for (const decl of node.declarationList.declarations) {
-            if (ts.isIdentifier(decl.name) && decl.initializer) {
-              // Check if initializer is rooted at our tracked variable or any existing alias
-              const initRoot = getRootIdentifier(decl.initializer);
-              if (initRoot && aliases.has(initRoot)) {
-                aliases.add(decl.name.text);
-              }
-            }
-          }
-        }
-        ts.forEachChild(node, collectAliases);
-      };
-      collectAliases(body);
-
-      // Helper to check if any alias is involved
-      const involvesTrackedVar = (expr: ts.Expression): boolean => {
-        const root = getRootIdentifier(expr);
-        return root !== undefined && aliases.has(root);
-      };
-
-      const checkTainting = (node: ts.Node): void => {
-        if (tainted) return; // Early exit if already tainted
-
-        // Reassignment: trackedVar = ...
-        if (ts.isBinaryExpression(node) &&
-            node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
-            ts.isIdentifier(node.left) &&
-            aliases.has(node.left.text)) {
-          tainted = true;
-          return;
-        }
-
-        // Property assignment: trackedVar.x = ... or alias.x = ...
-        if (ts.isBinaryExpression(node) &&
-            node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
-            ts.isPropertyAccessExpression(node.left) &&
-            involvesTrackedVar(node.left)) {
-          tainted = true;
-          return;
-        }
-
-        // Element assignment: trackedVar[x] = ... or alias[x] = ...
-        if (ts.isBinaryExpression(node) &&
-            node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
-            ts.isElementAccessExpression(node.left) &&
-            involvesTrackedVar(node.left.expression)) {
-          tainted = true;
-          return;
-        }
-
-        // Passed as argument to a function: fn(trackedVar) or fn(alias)
-        if (ts.isCallExpression(node)) {
-          for (const arg of node.arguments) {
-            // Check if any tracked variable or alias appears in the argument
-            let hasTrackedRef = false;
-            const checkRef = (n: ts.Node): void => {
-              if (ts.isIdentifier(n) && aliases.has(n.text)) {
-                hasTrackedRef = true;
-              }
-              ts.forEachChild(n, checkRef);
-            };
-            checkRef(arg);
-            if (hasTrackedRef) {
-              tainted = true;
-              return;
-            }
-          }
-        }
-
-        // Method call on the variable: trackedVar.method() or alias.method()
-        if (ts.isCallExpression(node) &&
-            ts.isPropertyAccessExpression(node.expression) &&
-            involvesTrackedVar(node.expression.expression)) {
-          tainted = true;
-          return;
-        }
-
-        // Await expression (async boundary - external code could run)
-        if (ts.isAwaitExpression(node)) {
-          tainted = true;
-          return;
-        }
-
-        ts.forEachChild(node, checkTainting);
-      };
-
-      checkTainting(body);
-      return tainted;
-    };
-
     const transformFunction = (
       func: ts.FunctionDeclaration | ts.ArrowFunction | ts.MethodDeclaration
     ): ts.Node => {
@@ -732,8 +616,7 @@ export class TypicalTransformer {
       func.parameters.forEach((param) => {
         if (param.type) {
           // Skip 'any' and 'unknown' types - no point validating them
-          if (param.type.kind === ts.SyntaxKind.AnyKeyword ||
-              param.type.kind === ts.SyntaxKind.UnknownKeyword) {
+          if (this.isAnyOrUnknownType(param.type)) {
             return;
           }
 
@@ -747,8 +630,8 @@ export class TypicalTransformer {
           validatedVariables.set(paramName, paramType);
 
           if (this.config.reusableValidators) {
-            // Use reusable validators - use typeToString
-            const typeText = typeChecker.typeToString(paramType);
+            // Use reusable validators - use typeNode text to preserve local aliases
+            const typeText = this.getTypeKey(param.type, typeChecker);
             const validatorName = this.getOrCreateValidator(
               typeText,
               param.type
@@ -796,8 +679,7 @@ export class TypicalTransformer {
             for (const decl of node.declarationList.declarations) {
               if (decl.type && ts.isIdentifier(decl.name)) {
                 // Skip any/unknown types
-                if (decl.type.kind !== ts.SyntaxKind.AnyKeyword &&
-                    decl.type.kind !== ts.SyntaxKind.UnknownKeyword) {
+                if (!this.isAnyOrUnknownType(decl.type)) {
                   const constType = typeChecker.getTypeFromTypeNode(decl.type);
                   validatedVariables.set(decl.name.text, constType);
                 }
@@ -866,12 +748,7 @@ export class TypicalTransformer {
       }
 
       // Skip 'any' and 'unknown' return types - no point validating them
-      const isAnyOrUnknownReturn = returnType && (
-        returnType.kind === ts.SyntaxKind.AnyKeyword ||
-        returnType.kind === ts.SyntaxKind.UnknownKeyword
-      );
-
-      if (returnType && returnTypeForString && !isAnyOrUnknownReturn) {
+      if (returnType && returnTypeForString && !this.isAnyOrUnknownType(returnType)) {
         const returnTransformer = (node: ts.Node): ts.Node => {
           if (ts.isReturnStatement(node) && node.expression) {
             // Skip return validation if the expression already contains a __typical _parse_* call
@@ -891,10 +768,10 @@ export class TypicalTransformer {
 
             // Flow analysis: Skip return validation if returning a validated variable
             // (or property of one) that hasn't been tainted
-            const rootVar = getRootIdentifier(node.expression);
+            const rootVar = this.getRootIdentifier(node.expression);
             if (rootVar && validatedVariables.has(rootVar)) {
               // Check if the variable has been tainted (mutated, passed to function, etc.)
-              if (!isTainted(rootVar, visitedBody)) {
+              if (!this.isTainted(rootVar, visitedBody)) {
                 // Return expression is rooted at a validated, untainted variable
                 // For direct returns (identifier) or property access, we can skip validation
                 if (ts.isIdentifier(node.expression) || ts.isPropertyAccessExpression(node.expression)) {
@@ -918,8 +795,9 @@ export class TypicalTransformer {
             }
 
             if (this.config.reusableValidators) {
-              // Use reusable validators - always use typeToString
-              const returnTypeText = typeChecker.typeToString(returnTypeForString!);
+              // Use reusable validators - use typeNode text to preserve local aliases
+              // Pass returnTypeForString for synthesized nodes (inferred return types)
+              const returnTypeText = this.getTypeKey(returnType, typeChecker, returnTypeForString);
               const validatorName = this.getOrCreateValidator(
                 returnTypeText,
                 returnType
@@ -1045,6 +923,200 @@ export class TypicalTransformer {
     return shouldTransformFile(fileName, this.config);
   }
 
+  /**
+   * Check if a TypeNode represents any or unknown type.
+   * These types are intentional escape hatches and shouldn't be validated.
+   */
+  private isAnyOrUnknownType(typeNode: ts.TypeNode): boolean {
+    return typeNode.kind === this.ts.SyntaxKind.AnyKeyword ||
+           typeNode.kind === this.ts.SyntaxKind.UnknownKeyword;
+  }
+
+  /**
+   * Check if a Type has any or unknown flags.
+   */
+  private isAnyOrUnknownTypeFlags(type: ts.Type): boolean {
+    return (type.flags & this.ts.TypeFlags.Any) !== 0 ||
+           (type.flags & this.ts.TypeFlags.Unknown) !== 0;
+  }
+
+  /**
+   * Infer type information from a JSON.stringify argument for creating a reusable stringifier.
+   */
+  private inferStringifyType(
+    arg: ts.Expression,
+    typeChecker: ts.TypeChecker,
+    ctx: TransformContext
+  ): { typeText: string; typeNode: ts.TypeNode } {
+    const ts = this.ts;
+
+    // Type assertion: use the asserted type directly
+    if (ts.isAsExpression(arg)) {
+      const typeNode = arg.type;
+      const typeString = typeChecker.typeToString(typeChecker.getTypeFromTypeNode(typeNode));
+      return {
+        typeText: `Asserted_${typeString.replace(/[^a-zA-Z0-9_]/g, "_")}`,
+        typeNode,
+      };
+    }
+
+    // Object literal: use property names for the key
+    if (ts.isObjectLiteralExpression(arg)) {
+      const objectType = typeChecker.getTypeAtLocation(arg);
+      const typeNode = typeChecker.typeToTypeNode(objectType, arg, ts.NodeBuilderFlags.InTypeAlias);
+      if (!typeNode) {
+        throw new Error('unknown type node for object literal: ' + arg.getText());
+      }
+      const propNames = arg.properties
+        .map((prop) => {
+          if (ts.isShorthandPropertyAssignment(prop)) return prop.name.text;
+          if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) return prop.name.text;
+          return "unknown";
+        })
+        .sort()
+        .join("_");
+      return { typeText: `ObjectLiteral_${propNames}`, typeNode };
+    }
+
+    // Other expressions: infer from type checker
+    const argType = typeChecker.getTypeAtLocation(arg);
+    const typeNode = typeChecker.typeToTypeNode(argType, arg, ts.NodeBuilderFlags.InTypeAlias);
+    if (typeNode) {
+      const typeString = typeChecker.typeToString(argType);
+      return {
+        typeText: `Expression_${typeString.replace(/[^a-zA-Z0-9_]/g, "_")}`,
+        typeNode,
+      };
+    }
+
+    // Fallback to unknown
+    return {
+      typeText: "unknown",
+      typeNode: ctx.factory.createKeywordTypeNode(ctx.ts.SyntaxKind.UnknownKeyword),
+    };
+  }
+
+  // ============================================
+  // Flow Analysis Helpers
+  // ============================================
+
+  /**
+   * Gets the root identifier from an expression.
+   * e.g., `user.address.city` -> "user"
+   */
+  private getRootIdentifier(expr: ts.Expression): string | undefined {
+    if (this.ts.isIdentifier(expr)) {
+      return expr.text;
+    }
+    if (this.ts.isPropertyAccessExpression(expr)) {
+      return this.getRootIdentifier(expr.expression);
+    }
+    return undefined;
+  }
+
+  /**
+   * Check if a validated variable has been tainted (mutated) in the function body.
+   * A variable is tainted if it's reassigned, has properties modified, is passed
+   * to a function, has methods called on it, or if an await occurs.
+   */
+  private isTainted(varName: string, body: ts.Block): boolean {
+    let tainted = false;
+    const ts = this.ts;
+
+    // Collect aliases (variables that reference properties of varName)
+    // e.g., const addr = user.address; -> addr is an alias
+    const aliases = new Set<string>([varName]);
+
+    const collectAliases = (node: ts.Node): void => {
+      if (ts.isVariableStatement(node)) {
+        for (const decl of node.declarationList.declarations) {
+          if (ts.isIdentifier(decl.name) && decl.initializer) {
+            const initRoot = this.getRootIdentifier(decl.initializer);
+            if (initRoot && aliases.has(initRoot)) {
+              aliases.add(decl.name.text);
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, collectAliases);
+    };
+    collectAliases(body);
+
+    // Helper to check if any alias is involved
+    const involvesTrackedVar = (expr: ts.Expression): boolean => {
+      const root = this.getRootIdentifier(expr);
+      return root !== undefined && aliases.has(root);
+    };
+
+    const checkTainting = (node: ts.Node): void => {
+      if (tainted) return;
+
+      // Reassignment: trackedVar = ...
+      if (ts.isBinaryExpression(node) &&
+          node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+          ts.isIdentifier(node.left) &&
+          aliases.has(node.left.text)) {
+        tainted = true;
+        return;
+      }
+
+      // Property assignment: trackedVar.x = ... or alias.x = ...
+      if (ts.isBinaryExpression(node) &&
+          node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+          ts.isPropertyAccessExpression(node.left) &&
+          involvesTrackedVar(node.left)) {
+        tainted = true;
+        return;
+      }
+
+      // Element assignment: trackedVar[x] = ... or alias[x] = ...
+      if (ts.isBinaryExpression(node) &&
+          node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+          ts.isElementAccessExpression(node.left) &&
+          involvesTrackedVar(node.left.expression)) {
+        tainted = true;
+        return;
+      }
+
+      // Passed as argument to a function: fn(trackedVar) or fn(alias)
+      if (ts.isCallExpression(node)) {
+        for (const arg of node.arguments) {
+          let hasTrackedRef = false;
+          const checkRef = (n: ts.Node): void => {
+            if (ts.isIdentifier(n) && aliases.has(n.text)) {
+              hasTrackedRef = true;
+            }
+            ts.forEachChild(n, checkRef);
+          };
+          checkRef(arg);
+          if (hasTrackedRef) {
+            tainted = true;
+            return;
+          }
+        }
+      }
+
+      // Method call on the variable: trackedVar.method() or alias.method()
+      if (ts.isCallExpression(node) &&
+          ts.isPropertyAccessExpression(node.expression) &&
+          involvesTrackedVar(node.expression.expression)) {
+        tainted = true;
+        return;
+      }
+
+      // Await expression (async boundary - external code could run)
+      if (ts.isAwaitExpression(node)) {
+        tainted = true;
+        return;
+      }
+
+      ts.forEachChild(node, checkTainting);
+    };
+
+    checkTainting(body);
+    return tainted;
+  }
+
   private addTypiaImport(
     sourceFile: ts.SourceFile,
     ctx: TransformContext
@@ -1083,135 +1155,153 @@ export class TypicalTransformer {
     return sourceFile;
   }
 
-  private getOrCreateValidator(
-    typeText: string,
-    typeNode: ts.TypeNode
-  ): string {
-    if (this.typeValidators.has(typeText)) {
-      return this.typeValidators.get(typeText)!.name;
+  /**
+   * Gets type text for use as a validator map key.
+   * Uses getText() to preserve local aliases (e.g., "User1" vs "User2"),
+   * but falls back to typeToString() for synthesized nodes without source positions.
+   *
+   * @param typeNode The TypeNode to get a key for
+   * @param typeChecker The TypeChecker to use
+   * @param typeObj Optional Type object - use this for synthesized nodes since
+   *                getTypeFromTypeNode doesn't work correctly on them
+   */
+  private getTypeKey(typeNode: ts.TypeNode, typeChecker: ts.TypeChecker, typeObj?: ts.Type): string {
+    // Check if node has a real position (not synthesized)
+    if (typeNode.pos >= 0 && typeNode.end > typeNode.pos) {
+      try {
+        return typeNode.getText();
+      } catch {
+        // Fall through to typeToString
+      }
     }
+    // Fallback for synthesized nodes - use the provided Type object if available,
+    // otherwise try to get it from the node (which may not work correctly)
+    const type = typeObj ?? typeChecker.getTypeFromTypeNode(typeNode);
+    return typeChecker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation);
+  }
 
-    const validatorName = `__typical_` + `assert_${this.typeValidators.size}`;
-    this.typeValidators.set(typeText, { name: validatorName, typeNode });
-    return validatorName;
+  /**
+   * Creates a readable name suffix from a type string.
+   * For simple identifiers like "User" or "string", returns the name directly.
+   * For complex types, returns a numeric index.
+   */
+  private getTypeNameSuffix(typeText: string, existingNames: Set<string>, fallbackIndex: number): string {
+    // Strip known prefixes that wrap the actual type name
+    let normalizedTypeText = typeText;
+    if (typeText.startsWith('Expression_')) {
+      normalizedTypeText = typeText.slice('Expression_'.length);
+    } else if (typeText.startsWith('ObjectLiteral_')) {
+      // Object literals use property names, fall back to numeric
+      return String(fallbackIndex);
+    }
+
+    // Check if it's a simple identifier (letters, numbers, underscore, starting with letter/underscore)
+    if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(normalizedTypeText)) {
+      // It's a simple type name like "User", "string", "MyType"
+      let name = normalizedTypeText;
+      // Handle collisions by appending a number
+      if (existingNames.has(name)) {
+        let i = 2;
+        while (existingNames.has(`${normalizedTypeText}${i}`)) {
+          i++;
+        }
+        name = `${normalizedTypeText}${i}`;
+      }
+      return name;
+    }
+    // Complex type - use numeric index
+    return String(fallbackIndex);
   }
 
-  private getOrCreateStringifier(
+  /**
+   * Generic method to get or create a typed function (validator, stringifier, or parser).
+   */
+  private getOrCreateTypedFunction(
+    kind: 'assert' | 'stringify' | 'parse',
     typeText: string,
     typeNode: ts.TypeNode
   ): string {
-    if (this.typeStringifiers.has(typeText)) {
-      return this.typeStringifiers.get(typeText)!.name;
+    const maps = {
+      assert: this.typeValidators,
+      stringify: this.typeStringifiers,
+      parse: this.typeParsers,
+    };
+    const prefixes = {
+      assert: '__typical_assert_',
+      stringify: '__typical_stringify_',
+      parse: '__typical_parse_',
+    };
+
+    const map = maps[kind];
+    const prefix = prefixes[kind];
+
+    if (map.has(typeText)) {
+      return map.get(typeText)!.name;
     }
 
-    const stringifierName = `__typical_` + `stringify_${this.typeStringifiers.size}`;
-    this.typeStringifiers.set(typeText, { name: stringifierName, typeNode });
-    return stringifierName;
+    const existingSuffixes = [...map.values()].map(v => v.name.slice(prefix.length));
+    const existingNames = new Set(existingSuffixes);
+    const numericCount = existingSuffixes.filter(s => /^\d+$/.test(s)).length;
+    const suffix = this.getTypeNameSuffix(typeText, existingNames, numericCount);
+    const name = `${prefix}${suffix}`;
+    map.set(typeText, { name, typeNode });
+    return name;
+  }
+
+  private getOrCreateValidator(typeText: string, typeNode: ts.TypeNode): string {
+    return this.getOrCreateTypedFunction('assert', typeText, typeNode);
+  }
+
+  private getOrCreateStringifier(typeText: string, typeNode: ts.TypeNode): string {
+    return this.getOrCreateTypedFunction('stringify', typeText, typeNode);
   }
 
   private getOrCreateParser(typeText: string, typeNode: ts.TypeNode): string {
-    if (this.typeParsers.has(typeText)) {
-      return this.typeParsers.get(typeText)!.name;
-    }
+    return this.getOrCreateTypedFunction('parse', typeText, typeNode);
+  }
 
-    const parserName = `__typical_` + `parse_${this.typeParsers.size}`;
-    this.typeParsers.set(typeText, { name: parserName, typeNode });
-    return parserName;
+  /**
+   * Creates a nested property access expression from an array of identifiers.
+   * e.g., ['typia', 'json', 'createStringify'] -> typia.json.createStringify
+   */
+  private createPropertyAccessChain(factory: ts.NodeFactory, parts: string[]): ts.Expression {
+    let expr: ts.Expression = factory.createIdentifier(parts[0]);
+    for (let i = 1; i < parts.length; i++) {
+      expr = factory.createPropertyAccessExpression(expr, parts[i]);
+    }
+    return expr;
   }
 
   private createValidatorStatements(ctx: TransformContext): ts.Statement[] {
     const { factory } = ctx;
     const statements: ts.Statement[] = [];
 
-    // Create assert validators
-    for (const [, { name: validatorName, typeNode }] of this.typeValidators) {
-      const createAssertCall = factory.createCallExpression(
-        factory.createPropertyAccessExpression(
-          factory.createIdentifier("typia"),
-          "createAssert"
-        ),
-        [typeNode],
-        []
-      );
-
-      const validatorDeclaration = factory.createVariableStatement(
-        undefined,
-        factory.createVariableDeclarationList(
-          [
-            factory.createVariableDeclaration(
-              validatorName,
-              undefined,
-              undefined,
-              createAssertCall
-            ),
-          ],
-          ctx.ts.NodeFlags.Const
-        )
-      );
-      statements.push(validatorDeclaration);
-    }
-
-    // Create stringifiers
-    for (const [, { name: stringifierName, typeNode }] of this
-      .typeStringifiers) {
-      const createStringifyCall = factory.createCallExpression(
-        factory.createPropertyAccessExpression(
-          factory.createPropertyAccessExpression(
-            factory.createIdentifier("typia"),
-            "json"
-          ),
-          "createStringify"
-        ),
-        [typeNode],
-        []
-      );
-
-      const stringifierDeclaration = factory.createVariableStatement(
-        undefined,
-        factory.createVariableDeclarationList(
-          [
-            factory.createVariableDeclaration(
-              stringifierName,
-              undefined,
-              undefined,
-              createStringifyCall
-            ),
-          ],
-          ctx.ts.NodeFlags.Const
-        )
-      );
-      statements.push(stringifierDeclaration);
-    }
-
-    // Create parsers
-    for (const [, { name: parserName, typeNode }] of this.typeParsers) {
-      const createParseCall = factory.createCallExpression(
-        factory.createPropertyAccessExpression(
-          factory.createPropertyAccessExpression(
-            factory.createIdentifier("typia"),
-            "json"
-          ),
-          "createAssertParse"
-        ),
-        [typeNode],
-        []
-      );
+    const configs: Array<{
+      map: Map<string, { name: string; typeNode: ts.TypeNode }>;
+      methodPath: string[];
+    }> = [
+      { map: this.typeValidators, methodPath: ['typia', 'createAssert'] },
+      { map: this.typeStringifiers, methodPath: ['typia', 'json', 'createStringify'] },
+      { map: this.typeParsers, methodPath: ['typia', 'json', 'createAssertParse'] },
+    ];
+
+    for (const { map, methodPath } of configs) {
+      for (const [, { name, typeNode }] of map) {
+        const createCall = factory.createCallExpression(
+          this.createPropertyAccessChain(factory, methodPath),
+          [typeNode],
+          []
+        );
 
-      const parserDeclaration = factory.createVariableStatement(
-        undefined,
-        factory.createVariableDeclarationList(
-          [
-            factory.createVariableDeclaration(
-              parserName,
-              undefined,
-              undefined,
-              createParseCall
-            ),
-          ],
-          ctx.ts.NodeFlags.Const
-        )
-      );
-      statements.push(parserDeclaration);
+        const declaration = factory.createVariableStatement(
+          undefined,
+          factory.createVariableDeclarationList(
+            [factory.createVariableDeclaration(name, undefined, undefined, createCall)],
+            ctx.ts.NodeFlags.Const
+          )
+        );
+        statements.push(declaration);
+      }
     }
 
     return statements;