@elliots/typical 0.1.8 → 0.1.10

package/src/transformer.ts

@@ -1,26 +1,303 @@
 import ts from "typescript";
 import fs from "fs";
 import path from "path";
-import { loadConfig, TypicalConfig, DOM_TYPES_TO_IGNORE } from "./config.js";
+import { loadConfig, validateConfig, TypicalConfig, getCompiledIgnorePatterns, CompiledIgnorePatterns } from "./config.js";
 import { shouldTransformFile } from "./file-filter.js";
 import { hoistRegexConstructors } from "./regex-hoister.js";
+import {
+  TransformResult,
+  composeSourceMaps,
+} from "./source-map.js";
+import type { EncodedSourceMap } from '@ampproject/remapping';
 
 import { transform as typiaTransform } from "typia/lib/transform.js";
 import { setupTsProgram } from "./setup.js";
 
+// Re-export TransformResult for consumers
+export type { TransformResult } from "./source-map.js";
+
 // Flags for typeToTypeNode to prefer type aliases over import() syntax
 const TYPE_NODE_FLAGS = ts.NodeBuilderFlags.NoTruncation | ts.NodeBuilderFlags.UseAliasDefinedOutsideCurrentScope;
 
+// Source map markers:
+// - @T:line:col - Type annotation marker (maps generated code to source type annotation)
+// - @L:line - Line marker (identity mapping - maps output line to source line)
+//
+// Lines with @T markers map to the specified type annotation position
+// Lines with @L markers establish identity mapping (output line N maps to source line N)
+// Lines without markers inherit from the most recent marker above
+//
+// Match single-line comment markers: //@T:line:col or //@L:line
+const TYPE_MARKER_REGEX = /\/\/@T:(\d+):(\d+)/g;
+const LINE_MARKER_REGEX = /\/\/@L:(\d+)/g;
+// Strip all markers
+const ALL_MARKERS_REGEX = /\/\/@[TL]:\d+(?::\d+)?\n?/g;
+
+/**
+ * Add a type annotation marker comment to a node.
+ * The marker encodes the original line:column position of the type annotation
+ * so validation errors can be traced back to the source.
+ *
+ * Uses a single-line comment (//) which forces a newline after it,
+ * ensuring each marked statement is on its own line for accurate source maps.
+ */
+function addSourceMapMarker<T extends ts.Node>(
+  node: T,
+  sourceFile: ts.SourceFile,
+  originalNode: ts.Node
+): T {
+  const pos = originalNode.getStart(sourceFile);
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(pos);
+  // Use 1-based line numbers for source maps
+  // Single-line comment forces a newline after it
+  const marker = `@T:${line + 1}:${character}`;
+  if (process.env.DEBUG) {
+    console.log(`TYPICAL: Adding source map marker //${marker}`);
+  }
+  const result = ts.addSyntheticLeadingComment(
+    node,
+    ts.SyntaxKind.SingleLineCommentTrivia,
+    marker,
+    true // trailing newline
+  );
+  if (process.env.DEBUG) {
+    const comments = ts.getSyntheticLeadingComments(result);
+    console.log(`TYPICAL: Synthetic comments after addSourceMapMarker:`, comments?.length);
+  }
+  return result;
+}
+
+/**
+ * Add a line marker comment to a node for identity mapping.
+ * The marker encodes the original line number so the output line maps to itself.
+ *
+ * Uses a single-line comment (//) which forces a newline after it.
+ */
+function addLineMarker<T extends ts.Node>(
+  node: T,
+  sourceFile: ts.SourceFile,
+  originalNode: ts.Node
+): T {
+  const pos = originalNode.getStart(sourceFile);
+  const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+  // Use 1-based line numbers for source maps
+  const marker = `@L:${line + 1}`;
+  if (process.env.DEBUG) {
+    console.log(`TYPICAL: Adding line marker //${marker}`);
+  }
+  return ts.addSyntheticLeadingComment(
+    node,
+    ts.SyntaxKind.SingleLineCommentTrivia,
+    marker,
+    true // trailing newline
+  );
+}
+
+/**
+ * Parse source map markers from code and build a source map.
+ * Markers are single-line comments on their own line:
+ * - //@T:line:col - Type annotation marker (maps to specific source position)
+ * - //@L:line - Line marker (identity mapping to source line, col 0)
+ *
+ * The marker applies to the NEXT line (the actual code statement).
+ * Lines without markers inherit from the most recent marker above.
+ * Returns the code with markers stripped and the generated source map.
+ */
+function parseMarkersAndBuildSourceMap(
+  code: string,
+  fileName: string,
+  originalSource: string,
+  includeContent: boolean
+): { code: string; map: EncodedSourceMap } {
+  const lines = code.split('\n');
+
+  // Current mapping position (inherited by unmarked lines)
+  let currentOrigLine = 1;
+  let currentOrigCol = 0;
+  let pendingMarker: { line: number; col: number } | null = null;
+
+  const mappings: Array<{ generatedLine: number; generatedCol: number; originalLine: number; originalCol: number }> = [];
+  let outputLineNum = 0; // 0-indexed output line counter (after stripping markers)
+
+  for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+    const line = lines[lineIdx];
+
+    // Check for type annotation marker (@T:line:col)
+    TYPE_MARKER_REGEX.lastIndex = 0;
+    const typeMatch = TYPE_MARKER_REGEX.exec(line);
+
+    if (typeMatch) {
+      // This is a @T marker line - store the position for the next line
+      pendingMarker = {
+        line: parseInt(typeMatch[1], 10),
+        col: parseInt(typeMatch[2], 10),
+      };
+      // Don't output this line or create a mapping for it
+      continue;
+    }
+
+    // Check for line marker (@L:line)
+    LINE_MARKER_REGEX.lastIndex = 0;
+    const lineMatch = LINE_MARKER_REGEX.exec(line);
+
+    if (lineMatch) {
+      // This is a @L marker line - identity mapping (col 0)
+      pendingMarker = {
+        line: parseInt(lineMatch[1], 10),
+        col: 0,
+      };
+      // Don't output this line or create a mapping for it
+      continue;
+    }
+
+    // This is a code line - apply pending marker if any
+    if (pendingMarker) {
+      currentOrigLine = pendingMarker.line;
+      currentOrigCol = pendingMarker.col;
+      pendingMarker = null;
+    }
+
+    outputLineNum++;
+
+    // Create mapping for this line
+    mappings.push({
+      generatedLine: outputLineNum,
+      generatedCol: 0,
+      originalLine: currentOrigLine,
+      originalCol: currentOrigCol,
+    });
+  }
+
+  // Strip all markers from the code
+  const cleanCode = code.replace(ALL_MARKERS_REGEX, '');
+
+  // Build VLQ-encoded source map
+  const map = buildSourceMapFromMappings(mappings, fileName, originalSource, includeContent);
+
+  return { code: cleanCode, map };
+}
+
+/**
+ * Build a source map from a list of position mappings.
+ */
+function buildSourceMapFromMappings(
+  mappings: Array<{ generatedLine: number; generatedCol: number; originalLine: number; originalCol: number }>,
+  fileName: string,
+  originalSource: string,
+  includeContent: boolean
+): EncodedSourceMap {
+  // Group mappings by generated line
+  const lineMap = new Map<number, Array<{ generatedCol: number; originalLine: number; originalCol: number }>>();
+  for (const m of mappings) {
+    if (!lineMap.has(m.generatedLine)) {
+      lineMap.set(m.generatedLine, []);
+    }
+    lineMap.get(m.generatedLine)!.push({
+      generatedCol: m.generatedCol,
+      originalLine: m.originalLine,
+      originalCol: m.originalCol,
+    });
+  }
+
+  // Build VLQ-encoded mappings string
+  const maxLine = Math.max(...mappings.map(m => m.generatedLine), 0);
+  const mappingLines: string[] = [];
+
+  let prevGenCol = 0;
+  let prevOrigLine = 0;
+  let prevOrigCol = 0;
+
+  for (let line = 1; line <= maxLine; line++) {
+    const lineMappings = lineMap.get(line);
+    if (!lineMappings || lineMappings.length === 0) {
+      mappingLines.push('');
+      continue;
+    }
+
+    // Sort by generated column
+    lineMappings.sort((a, b) => a.generatedCol - b.generatedCol);
+
+    const segments: string[] = [];
+    prevGenCol = 0; // Reset for each line
+
+    for (const m of lineMappings) {
+      // VLQ encode: [genCol, sourceIdx=0, origLine, origCol]
+      const segment = vlqEncode([
+        m.generatedCol - prevGenCol,
+        0, // source index (we only have one source)
+        (m.originalLine - 1) - prevOrigLine, // 0-based, relative
+        m.originalCol - prevOrigCol,
+      ]);
+      segments.push(segment);
+
+      prevGenCol = m.generatedCol;
+      prevOrigLine = m.originalLine - 1;
+      prevOrigCol = m.originalCol;
+    }
+
+    mappingLines.push(segments.join(','));
+  }
+
+  const map: EncodedSourceMap = {
+    version: 3,
+    file: fileName,
+    sources: [fileName],
+    names: [],
+    mappings: mappingLines.join(';'),
+  };
+
+  if (includeContent) {
+    map.sourcesContent = [originalSource];
+  }
+
+  return map;
+}
+
+// VLQ encoding for source maps
+const VLQ_BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const VLQ_BASE = 32;
+const VLQ_CONTINUATION_BIT = 32;
+
+function vlqEncode(values: number[]): string {
+  return values.map(vlqEncodeInteger).join('');
+}
+
+function vlqEncodeInteger(value: number): string {
+  let result = '';
+  let vlq = value < 0 ? ((-value) << 1) | 1 : value << 1;
+
+  do {
+    let digit = vlq & 31;
+    vlq >>>= 5;
+    if (vlq > 0) {
+      digit |= VLQ_CONTINUATION_BIT;
+    }
+    result += VLQ_BASE64[digit];
+  } while (vlq > 0);
+
+  return result;
+}
+
 export interface TransformContext {
   ts: typeof ts;
   factory: ts.NodeFactory;
   context: ts.TransformationContext;
+  sourceFile: ts.SourceFile;
+}
+
+/**
+ * Internal state for a single file transformation.
+ * Passed between visitor functions to track mutable state.
+ */
+interface FileTransformState {
+  needsTypiaImport: boolean;
 }
 
 export class TypicalTransformer {
   public config: TypicalConfig;
   private program: ts.Program;
   private ts: typeof ts;
+  private compiledPatterns: CompiledIgnorePatterns | null = null;
   private typeValidators = new Map<
     string,
     { name: string; typeNode: ts.TypeNode }
@@ -44,6 +321,144 @@ export class TypicalTransformer {
     this.program = program ?? setupTsProgram(this.ts);
   }
 
+  /**
+   * Create a new TypeScript program with transformed source code.
+   * This is needed so typia can resolve types from our generated typia.createAssert<T>() calls.
+   */
+  private createTypiaProgram(
+    fileName: string,
+    transformedCode: string,
+    languageVersion: ts.ScriptTarget = this.ts.ScriptTarget.ES2020
+  ): { newProgram: ts.Program; boundSourceFile: ts.SourceFile } {
+    // Create a new source file from the transformed code
+    const newSourceFile = this.ts.createSourceFile(
+      fileName,
+      transformedCode,
+      languageVersion,
+      true
+    );
+
+    // Build map of all source files, replacing the transformed one
+    const compilerOptions = this.program.getCompilerOptions();
+    const originalSourceFiles = new Map<string, ts.SourceFile>();
+    for (const sf of this.program.getSourceFiles()) {
+      originalSourceFiles.set(sf.fileName, sf);
+    }
+    originalSourceFiles.set(fileName, newSourceFile);
+
+    // Create custom compiler host that serves our transformed file
+    const customHost: ts.CompilerHost = {
+      getSourceFile: (hostFileName, langVersion) => {
+        if (originalSourceFiles.has(hostFileName)) {
+          return originalSourceFiles.get(hostFileName);
+        }
+        return this.ts.createSourceFile(
+          hostFileName,
+          this.ts.sys.readFile(hostFileName) || "",
+          langVersion,
+          true
+        );
+      },
+      getDefaultLibFileName: (opts) => this.ts.getDefaultLibFilePath(opts),
+      writeFile: () => {},
+      getCurrentDirectory: () => this.ts.sys.getCurrentDirectory(),
+      getCanonicalFileName: (fn) =>
+        this.ts.sys.useCaseSensitiveFileNames ? fn : fn.toLowerCase(),
+      useCaseSensitiveFileNames: () => this.ts.sys.useCaseSensitiveFileNames,
+      getNewLine: () => this.ts.sys.newLine,
+      fileExists: (fn) => originalSourceFiles.has(fn) || this.ts.sys.fileExists(fn),
+      readFile: (fn) => this.ts.sys.readFile(fn),
+    };
+
+    // Create new program, passing oldProgram to reuse dependency context
+    const newProgram = this.ts.createProgram(
+      Array.from(originalSourceFiles.keys()),
+      compilerOptions,
+      customHost,
+      this.program
+    );
+
+    // Get the bound source file from the new program (has proper symbol tables)
+    const boundSourceFile = newProgram.getSourceFile(fileName);
+    if (!boundSourceFile) {
+      throw new Error(`Failed to get bound source file: ${fileName}`);
+    }
+
+    return { newProgram, boundSourceFile };
+  }
+
+  /**
+   * Write intermediate file for debugging purposes.
+   * Creates a .typical.ts file showing the code after typical's transformations
+   * but before typia processes it.
+   */
+  private writeIntermediateFile(fileName: string, code: string): void {
+    if (!this.config.debug?.writeIntermediateFiles) {
+      return;
+    }
+
+    const compilerOptions = this.program.getCompilerOptions();
+    const outDir = compilerOptions.outDir || ".";
+    const rootDir = compilerOptions.rootDir || ".";
+
+    const relativePath = path.relative(rootDir, fileName);
+    const intermediateFileName = relativePath.replace(/\.(tsx?)$/, ".typical.$1");
+    const intermediateFilePath = path.join(outDir, intermediateFileName);
+
+    const dir = path.dirname(intermediateFilePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(intermediateFilePath, code);
+    console.log(`TYPICAL: Wrote intermediate file: ${intermediateFilePath}`);
+  }
+
+  /**
+   * Format typia diagnostic errors into readable error messages.
+   */
+  private formatTypiaErrors(errors: ts.Diagnostic[]): string[] {
+    return errors.map(d => {
+      const fullMessage = typeof d.messageText === 'string' ? d.messageText : d.messageText.messageText;
+
+      if (d.file && d.start !== undefined && d.length !== undefined) {
+        const { line, character } = d.file.getLineAndCharacterOfPosition(d.start);
+        // Extract the actual source code that caused the error
+        const sourceSnippet = d.file.text.substring(d.start, d.start + d.length);
+        // Truncate long snippets
+        const snippet = sourceSnippet.length > 100
+          ? sourceSnippet.substring(0, 100) + '...'
+          : sourceSnippet;
+
+        // Format the error message - extract type issues from typia's verbose output
+        const formattedIssues = this.formatTypiaError(fullMessage);
+
+        return `${d.file.fileName}:${line + 1}:${character + 1}\n` +
+          `  Code: ${snippet}\n` +
+          formattedIssues;
+      }
+      return this.formatTypiaError(fullMessage);
+    });
+  }
+
+  /**
+   * Check for untransformed typia calls and throw an error if found.
+   * This is a fallback in case typia silently fails without reporting a diagnostic.
+   */
+  private checkUntransformedTypiaCalls(code: string, fileName: string): void {
+    const untransformedCalls = this.findUntransformedTypiaCalls(code);
+    if (untransformedCalls.length > 0) {
+      const failedTypes = untransformedCalls.map(c => c.type).filter((v, i, a) => a.indexOf(v) === i);
+      throw new Error(
+        `TYPICAL: Failed to transform the following types (typia cannot process them):\n` +
+        failedTypes.map(t => `  - ${t}`).join('\n') +
+        `\n\nTo skip validation for these types, add to ignoreTypes in typical.json:\n` +
+        `  "ignoreTypes": [${failedTypes.map(t => `"${t}"`).join(', ')}]` +
+        `\n\nFile: ${fileName}`
+      );
+    }
+  }
+
   public createSourceFile(fileName: string, content: string): ts.SourceFile {
     return this.ts.createSourceFile(
       fileName,
@@ -53,11 +468,19 @@ export class TypicalTransformer {
     );
   }
 
+  /**
+   * Transform options for controlling source map generation.
+   */
   public transform(
     sourceFile: ts.SourceFile | string,
     mode: "basic" | "typia" | "js",
-    skippedTypes: Set<string> = new Set()
-  ): string {
+    options: {
+      sourceMap?: boolean;
+      skippedTypes?: Set<string>;
+    } = {}
+  ): TransformResult {
+    const { sourceMap = false, skippedTypes = new Set() } = options;
+
     if (typeof sourceFile === "string") {
       const file = this.program.getSourceFile(sourceFile);
       if (!file) {
@@ -66,128 +489,164 @@ export class TypicalTransformer {
       sourceFile = file;
     }
 
+    const fileName = sourceFile.fileName;
+    const originalSource = sourceFile.getFullText();
     const printer = this.ts.createPrinter();
+    const includeContent = this.config.sourceMap?.includeContent ?? true;
 
-    // Phase 1: typical's own transformations only (no typia)
+    // Phase 1: typical's own transformations (adds source map markers as comments)
     const typicalTransformer = this.getTypicalOnlyTransformer(skippedTypes);
     const phase1Result = this.ts.transform(sourceFile, [typicalTransformer]);
     let transformedCode = printer.printFile(phase1Result.transformed[0]);
+    if (process.env.DEBUG) {
+      console.log("TYPICAL: After phase1 print (first 500):", transformedCode.substring(0, 500));
+      console.log("TYPICAL: Contains //@T:", transformedCode.includes("//@T:"));
+    }
     phase1Result.dispose();
 
     if (mode === "basic") {
-      return transformedCode;
+      // For basic mode, parse markers and build source map, then strip markers
+      if (sourceMap) {
+        const { code, map } = parseMarkersAndBuildSourceMap(
+          transformedCode,
+          fileName,
+          originalSource,
+          includeContent
+        );
+        return { code, map };
+      }
+      // No source map requested - just strip markers
+      return {
+        code: transformedCode.replace(ALL_MARKERS_REGEX, ''),
+        map: null,
+      };
     }
 
     // Phase 2: if code has typia calls, run typia transformer in its own context
+    // The markers survive through typia since they're comments
     if (transformedCode.includes("typia.")) {
       const result = this.applyTypiaTransform(sourceFile.fileName, transformedCode, printer);
-      if (typeof result === 'object' && result.retry) {
+      if (typeof result === 'object' && 'retry' in result && result.retry) {
         // Typia failed on a type - add to skipped and retry the whole transform
         skippedTypes.add(result.failedType);
         // Clear validator caches since we're retrying
         this.typeValidators.clear();
         this.typeStringifiers.clear();
         this.typeParsers.clear();
-        return this.transform(sourceFile, mode, skippedTypes);
+        return this.transform(sourceFile, mode, { sourceMap, skippedTypes });
       }
-      transformedCode = result as string;
+      transformedCode = (result as { code: string }).code;
     }
 
     if (mode === "typia") {
-      return transformedCode;
+      // For typia mode, parse markers and build source map, then strip markers
+      if (sourceMap) {
+        const { code, map } = parseMarkersAndBuildSourceMap(
+          transformedCode,
+          fileName,
+          originalSource,
+          includeContent
+        );
+        return { code, map };
+      }
+      // No source map requested - just strip markers
+      return {
+        code: transformedCode.replace(ALL_MARKERS_REGEX, ''),
+        map: null,
+      };
     }
 
-    // Mode "js" - transpile to JavaScript
+    // Mode "js" - first parse markers to build our source map, then transpile
+    let typicalMap: EncodedSourceMap | null = null;
+    if (sourceMap) {
+      const parsed = parseMarkersAndBuildSourceMap(
+        transformedCode,
+        fileName,
+        originalSource,
+        includeContent
+      );
+      transformedCode = parsed.code;
+      typicalMap = parsed.map;
+    } else {
+      // Strip markers even without source map
+      transformedCode = transformedCode.replace(ALL_MARKERS_REGEX, '');
+    }
+
+    // Transpile to JavaScript with source map support
+    const compilerOptions = {
+      ...this.program.getCompilerOptions(),
+      sourceMap: sourceMap,
+      inlineSourceMap: false,
+      inlineSources: false,
+    };
+
     const compileResult = ts.transpileModule(transformedCode, {
-      compilerOptions: this.program.getCompilerOptions(),
+      compilerOptions,
+      fileName,
     });
 
-    return compileResult.outputText;
+    // Compose the two source maps: typical -> original AND js -> typical
+    if (sourceMap && typicalMap) {
+      let jsMap: EncodedSourceMap | null = null;
+      if (compileResult.sourceMapText) {
+        try {
+          jsMap = JSON.parse(compileResult.sourceMapText) as EncodedSourceMap;
+          jsMap.sources = [fileName];
+        } catch {
+          // Failed to parse, continue without
+        }
+      }
+
+      // Compose maps: jsMap traces JS->TS, typicalMap traces TS->original
+      // Result traces JS->original
+      const composedMap = composeSourceMaps([typicalMap, jsMap], fileName);
+      if (composedMap && includeContent) {
+        composedMap.sourcesContent = [originalSource];
+      }
+
+      return {
+        code: compileResult.outputText,
+        map: composedMap,
+      };
+    }
+
+    return {
+      code: compileResult.outputText,
+      map: null,
+    };
+  }
+
+  /**
+   * Legacy transform method that returns just the code string.
+   * @deprecated Use transform() with options.sourceMap instead
+   */
+  public transformCode(
+    sourceFile: ts.SourceFile | string,
+    mode: "basic" | "typia" | "js",
+    skippedTypes: Set<string> = new Set()
+  ): string {
+    return this.transform(sourceFile, mode, { skippedTypes }).code;
   }
 
   /**
    * Apply typia transformation in a separate ts.transform() context.
    * This avoids mixing program contexts and eliminates the need for import recreation.
-   * Returns either the transformed code string, or a retry signal with the failed type.
+   * Returns either the transformed code, or a retry signal with the failed type.
+   * Source map markers in the code are preserved through the typia transformation.
    */
-  private applyTypiaTransform(fileName: string, code: string, printer: ts.Printer): string | { retry: true; failedType: string } {
-    // 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 || ".";
-
-      const relativePath = path.relative(rootDir, fileName);
-      const intermediateFileName = relativePath.replace(/\.(tsx?)$/, ".typical.$1");
-      const intermediateFilePath = path.join(outDir, intermediateFileName);
-
-      const dir = path.dirname(intermediateFilePath);
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-      }
-
-      fs.writeFileSync(intermediateFilePath, code);
-      console.log(`TYPICAL: Wrote intermediate file: ${intermediateFilePath}`);
-    }
+  private applyTypiaTransform(
+    fileName: string,
+    code: string,
+    printer: ts.Printer
+  ): { code: string } | { retry: true; failedType: string } {
+    this.writeIntermediateFile(fileName, code);
 
     if (process.env.DEBUG) {
       console.log("TYPICAL: Before typia transform (first 500 chars):", code.substring(0, 500));
     }
 
-    // Create a new source file from the transformed code
-    const newSourceFile = this.ts.createSourceFile(
-      fileName,
-      code,
-      this.ts.ScriptTarget.ES2020,
-      true
-    );
-
-    // Create a new program with the transformed source file so typia can resolve types.
-    // Pass oldProgram to reuse parsed/bound data from unchanged dependency files.
-    const compilerOptions = this.program.getCompilerOptions();
-    const originalSourceFiles = new Map<string, ts.SourceFile>();
-    for (const sf of this.program.getSourceFiles()) {
-      originalSourceFiles.set(sf.fileName, sf);
-    }
-    // Replace the original source file with our transformed one
-    originalSourceFiles.set(fileName, newSourceFile);
-
-    const customHost: ts.CompilerHost = {
-      getSourceFile: (hostFileName, languageVersion) => {
-        if (originalSourceFiles.has(hostFileName)) {
-          return originalSourceFiles.get(hostFileName);
-        }
-        return this.ts.createSourceFile(
-          hostFileName,
-          this.ts.sys.readFile(hostFileName) || "",
-          languageVersion,
-          true
-        );
-      },
-      getDefaultLibFileName: (opts) => this.ts.getDefaultLibFilePath(opts),
-      writeFile: () => {},
-      getCurrentDirectory: () => this.ts.sys.getCurrentDirectory(),
-      getCanonicalFileName: (fn) =>
-        this.ts.sys.useCaseSensitiveFileNames ? fn : fn.toLowerCase(),
-      useCaseSensitiveFileNames: () => this.ts.sys.useCaseSensitiveFileNames,
-      getNewLine: () => this.ts.sys.newLine,
-      fileExists: (fn) => originalSourceFiles.has(fn) || this.ts.sys.fileExists(fn),
-      readFile: (fn) => this.ts.sys.readFile(fn),
-    };
-
-    // Create new program, passing oldProgram to reuse dependency context
-    const newProgram = this.ts.createProgram(
-      Array.from(originalSourceFiles.keys()),
-      compilerOptions,
-      customHost,
-      this.program // Reuse old program's structure for unchanged files
-    );
-
-    // Get the bound source file from the new program (has proper symbol tables)
-    const boundSourceFile = newProgram.getSourceFile(fileName);
-    if (!boundSourceFile) {
-      throw new Error(`Failed to get bound source file: ${fileName}`);
-    }
+    // Create a new program with the transformed source file so typia can resolve types
+    const { newProgram, boundSourceFile } = this.createTypiaProgram(fileName, code);
 
     // Collect typia diagnostics to detect transformation failures
     const diagnostics: ts.Diagnostic[] = [];
@@ -242,27 +701,7 @@ export class TypicalTransformer {
       }
 
       // No retryable errors, throw the original error
-      const errorMessages = errors.map(d => {
-        const fullMessage = typeof d.messageText === 'string' ? d.messageText : d.messageText.messageText;
-
-        if (d.file && d.start !== undefined && d.length !== undefined) {
-          const { line, character } = d.file.getLineAndCharacterOfPosition(d.start);
-          // Extract the actual source code that caused the error
-          const sourceSnippet = d.file.text.substring(d.start, d.start + d.length);
-          // Truncate long snippets
-          const snippet = sourceSnippet.length > 100
-            ? sourceSnippet.substring(0, 100) + '...'
-            : sourceSnippet;
-
-          // Format the error message - extract type issues from typia's verbose output
-          const formattedIssues = this.formatTypiaError(fullMessage);
-
-          return `${d.file.fileName}:${line + 1}:${character + 1}\n` +
-            `  Code: ${snippet}\n` +
-            formattedIssues;
-        }
-        return this.formatTypiaError(fullMessage);
-      });
+      const errorMessages = this.formatTypiaErrors(errors);
       throw new Error(
         `TYPICAL: Typia transformation failed:\n\n${errorMessages.join('\n\n')}`
       );
@@ -280,21 +719,12 @@ export class TypicalTransformer {
 
     const finalCode = printer.printFile(typiaTransformed);
 
-    // Also check for untransformed typia calls as a fallback
-    // (in case typia silently fails without reporting a diagnostic)
-    const untransformedCalls = this.findUntransformedTypiaCalls(finalCode);
-    if (untransformedCalls.length > 0) {
-      const failedTypes = untransformedCalls.map(c => c.type).filter((v, i, a) => a.indexOf(v) === i);
-      throw new Error(
-        `TYPICAL: Failed to transform the following types (typia cannot process them):\n` +
-        failedTypes.map(t => `  - ${t}`).join('\n') +
-        `\n\nTo skip validation for these types, add to ignoreTypes in typical.json:\n` +
-        `  "ignoreTypes": [${failedTypes.map(t => `"${t}"`).join(', ')}]` +
-        `\n\nFile: ${fileName}`
-      );
-    }
+    // Check for untransformed typia calls as a fallback
+    this.checkUntransformedTypiaCalls(finalCode, fileName);
 
-    return finalCode;
+    // Source map markers (@T:line:col) are preserved through typia transformation
+    // and will be parsed later in the transform() method
+    return { code: finalCode };
   }
 
   /**
@@ -305,11 +735,6 @@ export class TypicalTransformer {
     return (context: ts.TransformationContext) => {
       const factory = context.factory;
       const typeChecker = this.program.getTypeChecker();
-      const transformContext: TransformContext = {
-        ts: this.ts,
-        factory,
-        context,
-      };
 
       return (sourceFile: ts.SourceFile) => {
         // Check if this file should be transformed based on include/exclude patterns
@@ -321,6 +746,13 @@ export class TypicalTransformer {
           console.log("TYPICAL: processing ", sourceFile.fileName);
         }
 
+        const transformContext: TransformContext = {
+          ts: this.ts,
+          factory,
+          context,
+          sourceFile,
+        };
+
         return this.transformSourceFile(sourceFile, transformContext, typeChecker, skippedTypes);
       };
     };
@@ -337,11 +769,6 @@ export class TypicalTransformer {
     return (context: ts.TransformationContext) => {
       const factory = context.factory;
       const typeChecker = this.program.getTypeChecker();
-      const transformContext: TransformContext = {
-        ts: this.ts,
-        factory,
-        context,
-      };
 
       return (sourceFile: ts.SourceFile) => {
         // Check if this file should be transformed based on include/exclude patterns
@@ -353,6 +780,13 @@ export class TypicalTransformer {
           console.log("TYPICAL: processing ", sourceFile.fileName);
         }
 
+        const transformContext: TransformContext = {
+          ts: this.ts,
+          factory,
+          context,
+          sourceFile,
+        };
+
         // Apply typical's transformations
         let transformedSourceFile = this.transformSourceFile(
           sourceFile,
@@ -372,81 +806,19 @@ export class TypicalTransformer {
           return transformedSourceFile;
         }
 
-        // 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 || ".";
-          const relativePath = path.relative(rootDir, sourceFile.fileName);
-          const intermediateFileName = relativePath.replace(/\.(tsx?)$/, ".typical.$1");
-          const intermediateFilePath = path.join(outDir, intermediateFileName);
-          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}`);
-        }
+        this.writeIntermediateFile(sourceFile.fileName, transformedCode);
 
         if (process.env.DEBUG) {
           console.log("TYPICAL: Before typia transform (first 500 chars):", transformedCode.substring(0, 500));
         }
 
-        // Create a new source file from the transformed code
-        const newSourceFile = this.ts.createSourceFile(
+        // Create a new program with the transformed source file so typia can resolve types
+        const { newProgram, boundSourceFile } = this.createTypiaProgram(
           sourceFile.fileName,
           transformedCode,
-          sourceFile.languageVersion,
-          true
-        );
-
-        // Create a new program with the transformed source file so typia can resolve types.
-        // Pass oldProgram to reuse parsed/bound data from unchanged dependency files.
-        const compilerOptions = this.program.getCompilerOptions();
-        const originalSourceFiles = new Map<string, ts.SourceFile>();
-        for (const sf of this.program.getSourceFiles()) {
-          originalSourceFiles.set(sf.fileName, sf);
-        }
-        // Replace the original source file with our transformed one
-        originalSourceFiles.set(sourceFile.fileName, newSourceFile);
-
-        const customHost: ts.CompilerHost = {
-          getSourceFile: (hostFileName, languageVersion) => {
-            if (originalSourceFiles.has(hostFileName)) {
-              return originalSourceFiles.get(hostFileName);
-            }
-            return this.ts.createSourceFile(
-              hostFileName,
-              this.ts.sys.readFile(hostFileName) || "",
-              languageVersion,
-              true
-            );
-          },
-          getDefaultLibFileName: (opts) => this.ts.getDefaultLibFilePath(opts),
-          writeFile: () => {},
-          getCurrentDirectory: () => this.ts.sys.getCurrentDirectory(),
-          getCanonicalFileName: (fn) =>
-            this.ts.sys.useCaseSensitiveFileNames ? fn : fn.toLowerCase(),
-          useCaseSensitiveFileNames: () => this.ts.sys.useCaseSensitiveFileNames,
-          getNewLine: () => this.ts.sys.newLine,
-          fileExists: (fn) => originalSourceFiles.has(fn) || this.ts.sys.fileExists(fn),
-          readFile: (fn) => this.ts.sys.readFile(fn),
-        };
-
-        // Create new program, passing oldProgram to reuse dependency context
-        const newProgram = this.ts.createProgram(
-          Array.from(originalSourceFiles.keys()),
-          compilerOptions,
-          customHost,
-          this.program // Reuse old program's structure for unchanged files
+          sourceFile.languageVersion
         );
 
-        // Get the bound source file from the new program (has proper symbol tables)
-        const boundSourceFile = newProgram.getSourceFile(sourceFile.fileName);
-        if (!boundSourceFile) {
-          throw new Error(`Failed to get bound source file: ${sourceFile.fileName}`);
-        }
-
         // Collect typia diagnostics to detect transformation failures
         const diagnostics: ts.Diagnostic[] = [];
 
@@ -477,27 +849,7 @@ export class TypicalTransformer {
         // Check for typia errors via diagnostics
         const errors = diagnostics.filter(d => d.category === this.ts.DiagnosticCategory.Error);
         if (errors.length > 0) {
-          const errorMessages = errors.map(d => {
-            const fullMessage = typeof d.messageText === 'string' ? d.messageText : d.messageText.messageText;
-
-            if (d.file && d.start !== undefined && d.length !== undefined) {
-              const { line, character } = d.file.getLineAndCharacterOfPosition(d.start);
-              // Extract the actual source code that caused the error
-              const sourceSnippet = d.file.text.substring(d.start, d.start + d.length);
-              // Truncate long snippets
-              const snippet = sourceSnippet.length > 100
-                ? sourceSnippet.substring(0, 100) + '...'
-                : sourceSnippet;
-
-              // Format the error message - extract type issues from typia's verbose output
-              const formattedIssues = this.formatTypiaError(fullMessage);
-
-              return `${d.file.fileName}:${line + 1}:${character + 1}\n` +
-                `  Code: ${snippet}\n` +
-                formattedIssues;
-            }
-            return this.formatTypiaError(fullMessage);
-          });
+          const errorMessages = this.formatTypiaErrors(errors);
           throw new Error(
             `TYPICAL: Typia transformation failed:\n\n${errorMessages.join('\n\n')}`
           );
@@ -512,19 +864,9 @@ export class TypicalTransformer {
           );
         }
 
-        // Also check for untransformed typia calls as a fallback
+        // Check for untransformed typia calls as a fallback
         const finalCode = printer.printFile(transformedSourceFile);
-        const untransformedCalls = this.findUntransformedTypiaCalls(finalCode);
-        if (untransformedCalls.length > 0) {
-          const failedTypes = untransformedCalls.map(c => c.type).filter((v, i, a) => a.indexOf(v) === i);
-          throw new Error(
-            `TYPICAL: Failed to transform the following types (typia cannot process them):\n` +
-            failedTypes.map(t => `  - ${t}`).join('\n') +
-            `\n\nTo skip validation for these types, add to ignoreTypes in typical.json:\n` +
-            `  "ignoreTypes": [${failedTypes.map(t => `"${t}"`).join(', ')}]` +
-            `\n\nFile: ${sourceFile.fileName}`
-          );
-        }
+        this.checkUntransformedTypiaCalls(finalCode, sourceFile.fileName);
 
         return transformedSourceFile;
       };
@@ -532,48 +874,183 @@ export class TypicalTransformer {
   }
 
   /**
-   * Transform a single source file with TypeScript AST
+   * Transform JSON.stringify or JSON.parse calls to use typia's validated versions.
+   * Returns the transformed node if applicable, or undefined to indicate no transformation.
    */
-  private transformSourceFile(
-    sourceFile: ts.SourceFile,
+  private transformJSONCall(
+    node: ts.CallExpression,
     ctx: TransformContext,
     typeChecker: ts.TypeChecker,
-    skippedTypes: Set<string> = new Set()
-  ): ts.SourceFile {
-    const { ts } = ctx;
+    shouldSkipType: (typeText: string) => boolean
+  ): ts.Node | undefined {
+    const { ts, factory } = ctx;
+    const propertyAccess = node.expression as ts.PropertyAccessExpression;
+
+    if (propertyAccess.name.text === "stringify") {
+      // For stringify, we need to infer the type from the argument
+      // First check if the argument type is 'any' - if so, skip transformation
+      if (node.arguments.length > 0) {
+        const arg = node.arguments[0];
+        const argType = typeChecker.getTypeAtLocation(arg);
+        if (this.isAnyOrUnknownTypeFlags(argType)) {
+          return undefined; // Don't transform JSON.stringify for any/unknown types
+        }
+      }
+
+      if (this.config.reusableValidators) {
+        // Infer type from argument
+        const arg = node.arguments[0];
+        const { typeText, typeNode } = this.inferStringifyType(arg, typeChecker, ctx);
+
+        const stringifierName = this.getOrCreateStringifier(typeText, typeNode);
+        return factory.createCallExpression(
+          factory.createIdentifier(stringifierName),
+          undefined,
+          node.arguments
+        );
+      } else {
+        // Use inline typia.json.stringify
+        return factory.updateCallExpression(
+          node,
+          factory.createPropertyAccessExpression(
+            factory.createPropertyAccessExpression(
+              factory.createIdentifier("typia"),
+              "json"
+            ),
+            "stringify"
+          ),
+          node.typeArguments,
+          node.arguments
+        );
+      }
+    } else if (propertyAccess.name.text === "parse") {
+      // For JSON.parse, we need to infer the expected type from context
+      // Check if this is part of a variable declaration or type assertion
+      let targetType: ts.TypeNode | undefined;
+
+      // Look for type annotations in parent nodes
+      let parent = node.parent;
+      while (parent) {
+        if (ts.isVariableDeclaration(parent) && parent.type) {
+          targetType = parent.type;
+          break;
+        } else if (ts.isAsExpression(parent)) {
+          targetType = parent.type;
+          break;
+        } else if (ts.isReturnStatement(parent)) {
+          // Look for function return type
+          let funcParent = parent.parent;
+          while (funcParent) {
+            if (
+              (ts.isFunctionDeclaration(funcParent) ||
+                ts.isArrowFunction(funcParent) ||
+                ts.isMethodDeclaration(funcParent)) &&
+              funcParent.type
+            ) {
+              targetType = funcParent.type;
+              break;
+            }
+            funcParent = funcParent.parent;
+          }
+          break;
+        } else if (ts.isArrowFunction(parent) && parent.type) {
+          // Arrow function with expression body (not block)
+          // e.g., (s: string): User => JSON.parse(s)
+          targetType = parent.type;
+          break;
+        }
+        parent = parent.parent;
+      }
 
-    // Helper to check if a type should be skipped (failed in typia on previous attempt)
-    const shouldSkipType = (typeText: string): boolean => {
-      if (skippedTypes.size === 0) return false;
-      // Normalize: remove all whitespace and semicolons for comparison
-      const normalize = (s: string) => s.replace(/[\s;]+/g, '').toLowerCase();
-      const normalized = normalize(typeText);
-      for (const skipped of skippedTypes) {
-        const skippedNormalized = normalize(skipped);
-        if (normalized === skippedNormalized || normalized.includes(skippedNormalized) || skippedNormalized.includes(normalized)) {
+      if (targetType && this.isAnyOrUnknownType(targetType)) {
+        // Don't transform JSON.parse for any/unknown types
+        return undefined;
+      }
+
+      // If we can't determine the target type and there's no explicit type argument,
+      // don't transform - we can't validate against an unknown type
+      if (!targetType && !node.typeArguments) {
+        return undefined;
+      }
+
+      if (this.config.reusableValidators && targetType) {
+        // Use reusable parser - use typeNode text to preserve local aliases
+        const typeText = this.getTypeKey(targetType, typeChecker);
+
+        // Skip types that failed in typia (retry mechanism)
+        if (shouldSkipType(typeText)) {
           if (process.env.DEBUG) {
-            console.log(`TYPICAL: Matched skipped type: "${typeText.substring(0, 50)}..." matches "${skipped.substring(0, 50)}..."`);
+            console.log(`TYPICAL: Skipping previously failed type for JSON.parse: ${typeText}`);
           }
-          return true;
+          return undefined;
         }
+
+        const parserName = this.getOrCreateParser(typeText, targetType);
+
+        return factory.createCallExpression(
+          factory.createIdentifier(parserName),
+          undefined,
+          node.arguments
+        );
+      } else {
+        // Use inline typia.json.assertParse
+        const typeArguments = targetType
+          ? [targetType]
+          : node.typeArguments;
+
+        return factory.updateCallExpression(
+          node,
+          factory.createPropertyAccessExpression(
+            factory.createPropertyAccessExpression(
+              factory.createIdentifier("typia"),
+              "json"
+            ),
+            "assertParse"
+          ),
+          typeArguments,
+          node.arguments
+        );
       }
-      return false;
-    };
+    }
 
-    if (!sourceFile.fileName.includes('transformer.test.ts')) {  
-      // Check if this file has already been transformed by us
-      const sourceText = sourceFile.getFullText();
-      if (sourceText.includes('__typical_' + 'assert_') || sourceText.includes('__typical_' + 'stringify_') || sourceText.includes('__typical_' + 'parse_')) {
-        throw new Error(`File ${sourceFile.fileName} has already been transformed by Typical! Double transformation detected.`);
+    return undefined;
+  }
+
+  /**
+   * Check if a type should be skipped (failed in typia on previous attempt).
+   */
+  private shouldSkipType(typeText: string, skippedTypes: Set<string>): boolean {
+    if (skippedTypes.size === 0) return false;
+    // Normalize: remove all whitespace and semicolons for comparison
+    const normalize = (s: string) => s.replace(/[\s;]+/g, '').toLowerCase();
+    const normalized = normalize(typeText);
+    for (const skipped of skippedTypes) {
+      const skippedNormalized = normalize(skipped);
+      if (normalized === skippedNormalized || normalized.includes(skippedNormalized) || skippedNormalized.includes(normalized)) {
+        if (process.env.DEBUG) {
+          console.log(`TYPICAL: Matched skipped type: "${typeText.substring(0, 50)}..." matches "${skipped.substring(0, 50)}..."`);
+        }
+        return true;
       }
     }
+    return false;
+  }
 
-    // Reset caches for each file
-    this.typeValidators.clear();
-    this.typeStringifiers.clear();
-    this.typeParsers.clear();
+  /**
+   * Create an AST visitor function for transforming a source file.
+   * The visitor handles JSON calls, type casts, and function declarations.
+   */
+  private createVisitor(
+    ctx: TransformContext,
+    typeChecker: ts.TypeChecker,
+    skippedTypes: Set<string>,
+    state: FileTransformState
+  ): (node: ts.Node) => ts.Node {
+    const { ts } = ctx;
+    const shouldSkipType = (typeText: string) => this.shouldSkipType(typeText, skippedTypes);
 
-    let needsTypiaImport = false;
+    // Forward declaration for mutual recursion
+    let transformFunction: (func: ts.FunctionDeclaration | ts.ArrowFunction | ts.MethodDeclaration) => ts.Node;
 
     const visit = (node: ts.Node): ts.Node => {
       // Transform JSON calls first (before they get wrapped in functions)
@@ -586,127 +1063,12 @@ export class TypicalTransformer {
           ts.isIdentifier(propertyAccess.expression) &&
           propertyAccess.expression.text === "JSON"
         ) {
-          needsTypiaImport = true;
-
-          if (propertyAccess.name.text === "stringify") {
-            // For stringify, we need to infer the type from the argument
-            // First check if the argument type is 'any' - if so, skip transformation
-            if (node.arguments.length > 0) {
-              const arg = node.arguments[0];
-              const argType = typeChecker.getTypeAtLocation(arg);
-              if (this.isAnyOrUnknownTypeFlags(argType)) {
-                return node; // Don't transform JSON.stringify for any/unknown types
-              }
-            }
-
-            if (this.config.reusableValidators) {
-              // Infer type from argument
-              const arg = node.arguments[0];
-              const { typeText, typeNode } = this.inferStringifyType(arg, typeChecker, ctx);
-
-              const stringifierName = this.getOrCreateStringifier(typeText, typeNode);
-              return ctx.factory.createCallExpression(
-                ctx.factory.createIdentifier(stringifierName),
-                undefined,
-                node.arguments
-              );
-            } else {
-              // Use inline typia.json.stringify
-              return ctx.factory.updateCallExpression(
-                node,
-                ctx.factory.createPropertyAccessExpression(
-                  ctx.factory.createPropertyAccessExpression(
-                    ctx.factory.createIdentifier("typia"),
-                    "json"
-                  ),
-                  "stringify"
-                ),
-                node.typeArguments,
-                node.arguments
-              );
-            }
-          } else if (propertyAccess.name.text === "parse") {
-            // For JSON.parse, we need to infer the expected type from context
-            // Check if this is part of a variable declaration or type assertion
-            let targetType: ts.TypeNode | undefined;
-
-            // Look for type annotations in parent nodes
-            let parent = node.parent;
-            while (parent) {
-              if (ts.isVariableDeclaration(parent) && parent.type) {
-                targetType = parent.type;
-                break;
-              } else if (ts.isAsExpression(parent)) {
-                targetType = parent.type;
-                break;
-              } else if (ts.isReturnStatement(parent)) {
-                // Look for function return type
-                let funcParent = parent.parent;
-                while (funcParent) {
-                  if (
-                    (ts.isFunctionDeclaration(funcParent) ||
-                      ts.isArrowFunction(funcParent) ||
-                      ts.isMethodDeclaration(funcParent)) &&
-                    funcParent.type
-                  ) {
-                    targetType = funcParent.type;
-                    break;
-                  }
-                  funcParent = funcParent.parent;
-                }
-                break;
-              } else if (ts.isArrowFunction(parent) && parent.type) {
-                // Arrow function with expression body (not block)
-                // e.g., (s: string): User => JSON.parse(s)
-                targetType = parent.type;
-                break;
-              }
-              parent = parent.parent;
-            }
-
-            if (targetType && this.isAnyOrUnknownType(targetType)) {
-              // Don't transform JSON.parse for any/unknown types
-              return node;
-            }
-
-            // If we can't determine the target type and there's no explicit type argument,
-            // don't transform - we can't validate against an unknown type
-            if (!targetType && !node.typeArguments) {
-              return node;
-            }
-
-            if (this.config.reusableValidators && targetType) {
-              // 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(
-                ctx.factory.createIdentifier(parserName),
-                undefined,
-                node.arguments
-              );
-
-              return newCall;
-            } else {
-              // Use inline typia.json.assertParse
-              const typeArguments = targetType
-                ? [targetType]
-                : node.typeArguments;
-
-              return ctx.factory.updateCallExpression(
-                node,
-                ctx.factory.createPropertyAccessExpression(
-                  ctx.factory.createPropertyAccessExpression(
-                    ctx.factory.createIdentifier("typia"),
-                    "json"
-                  ),
-                  "assertParse"
-                ),
-                typeArguments,
-                node.arguments
-              );
-            }
+          const transformed = this.transformJSONCall(node, ctx, typeChecker, shouldSkipType);
+          if (transformed) {
+            state.needsTypiaImport = true;
+            return transformed;
           }
+          return node;
         }
       }
 
@@ -745,7 +1107,7 @@ export class TypicalTransformer {
           return ctx.ts.visitEachChild(node, visit, ctx.context);
         }
 
-        needsTypiaImport = true;
+        state.needsTypiaImport = true;
 
         // Visit the expression first to transform any nested casts
         const visitedExpression = ctx.ts.visitNode(node.expression, visit) as ts.Expression;
@@ -776,26 +1138,26 @@ export class TypicalTransformer {
 
       // Transform function declarations
       if (ts.isFunctionDeclaration(node)) {
-        needsTypiaImport = true;
+        state.needsTypiaImport = true;
         return transformFunction(node);
       }
 
       // Transform arrow functions
       if (ts.isArrowFunction(node)) {
-        needsTypiaImport = true;
+        state.needsTypiaImport = true;
         return transformFunction(node);
       }
 
       // Transform method declarations
       if (ts.isMethodDeclaration(node)) {
-        needsTypiaImport = true;
+        state.needsTypiaImport = true;
         return transformFunction(node);
       }
 
       return ctx.ts.visitEachChild(node, visit, ctx.context);
     };
 
-    const transformFunction = (
+    transformFunction = (
       func: ts.FunctionDeclaration | ts.ArrowFunction | ts.MethodDeclaration
     ): ts.Node => {
       const body = func.body;
@@ -859,7 +1221,7 @@ export class TypicalTransformer {
                     : null;
 
                   if (validatorName) {
-                    needsTypiaImport = true;
+                    state.needsTypiaImport = true;
                     visitedBody = ctx.factory.createCallExpression(
                       ctx.factory.createPropertyAccessExpression(
                         visitedBody,
@@ -957,9 +1319,12 @@ export class TypicalTransformer {
               undefined,
               [paramIdentifier]
             );
-            const assertCall =
+            let assertCall: ts.Statement =
               ctx.factory.createExpressionStatement(validatorCall);
 
+            // Add source map marker pointing to the parameter's type annotation
+            assertCall = addSourceMapMarker(assertCall, ctx.sourceFile, param.type!);
+
             validationStatements.push(assertCall);
           } else {
             // Use inline typia.assert calls
@@ -974,9 +1339,12 @@ export class TypicalTransformer {
               [param.type],
               [paramIdentifier]
             );
-            const assertCall =
+            let assertCall: ts.Statement =
               ctx.factory.createExpressionStatement(callExpression);
 
+            // Add source map marker pointing to the parameter's type annotation
+            assertCall = addSourceMapMarker(assertCall, ctx.sourceFile, param.type!);
+
             validationStatements.push(assertCall);
           }
         }
@@ -1169,7 +1537,12 @@ export class TypicalTransformer {
                 [validatorExpr]
               );
 
-              return ctx.factory.updateReturnStatement(node, thenCall);
+              let updatedReturn = ctx.factory.updateReturnStatement(node, thenCall);
+              // Add source map marker pointing to the return type annotation
+              if (returnType && returnType.pos >= 0) {
+                updatedReturn = addSourceMapMarker(updatedReturn, ctx.sourceFile, returnType);
+              }
+              return updatedReturn;
             }
 
             // For async functions, we need to await the expression before validating
@@ -1201,7 +1574,12 @@ export class TypicalTransformer {
                 [expressionToValidate]
               );
 
-              return ctx.factory.updateReturnStatement(node, validatorCall);
+              let updatedReturn = ctx.factory.updateReturnStatement(node, validatorCall);
+              // Add source map marker pointing to the return type annotation
+              if (returnType && returnType.pos >= 0) {
+                updatedReturn = addSourceMapMarker(updatedReturn, ctx.sourceFile, returnType);
+              }
+              return updatedReturn;
             } else {
               // Use inline typia.assert calls
               const typiaIdentifier = ctx.factory.createIdentifier("typia");
@@ -1216,7 +1594,12 @@ export class TypicalTransformer {
                 [expressionToValidate]
               );
 
-              return ctx.factory.updateReturnStatement(node, callExpression);
+              let updatedReturn = ctx.factory.updateReturnStatement(node, callExpression);
+              // Add source map marker pointing to the return type annotation
+              if (returnType && returnType.pos >= 0) {
+                updatedReturn = addSourceMapMarker(updatedReturn, ctx.sourceFile, returnType);
+              }
+              return updatedReturn;
             }
           }
           return ctx.ts.visitEachChild(node, returnTransformer, ctx.context);
@@ -1273,13 +1656,43 @@ export class TypicalTransformer {
       return func;
     };
 
+    return visit;
+  }
+
+  /**
+   * Transform a single source file with TypeScript AST
+   */
+  private transformSourceFile(
+    sourceFile: ts.SourceFile,
+    ctx: TransformContext,
+    typeChecker: ts.TypeChecker,
+    skippedTypes: Set<string> = new Set()
+  ): ts.SourceFile {
+    if (!sourceFile.fileName.includes('transformer.test.ts')) {
+      // Check if this file has already been transformed by us
+      const sourceText = sourceFile.getFullText();
+      if (sourceText.includes('__typical_' + 'assert_') || sourceText.includes('__typical_' + 'stringify_') || sourceText.includes('__typical_' + 'parse_')) {
+        throw new Error(`File ${sourceFile.fileName} has already been transformed by Typical! Double transformation detected.`);
+      }
+    }
+
+    // Reset caches for each file
+    this.typeValidators.clear();
+    this.typeStringifiers.clear();
+    this.typeParsers.clear();
+
+    // Create state object to track mutable state across visitor calls
+    const state: FileTransformState = { needsTypiaImport: false };
+
+    // Create visitor and transform the source file
+    const visit = this.createVisitor(ctx, typeChecker, skippedTypes, state);
     let transformedSourceFile = ctx.ts.visitNode(
       sourceFile,
       visit
     ) as ts.SourceFile;
 
     // Add typia import and validator statements if needed
-    if (needsTypiaImport) {
+    if (state.needsTypiaImport) {
       transformedSourceFile = this.addTypiaImport(transformedSourceFile, ctx);
 
       // Add validator statements after imports (only if using reusable validators)
@@ -1308,13 +1721,213 @@ export class TypicalTransformer {
       }
     }
 
+    // Add line markers to original statements for source map identity mappings.
+    // This ensures original source lines map to themselves rather than inheriting
+    // from previous @T markers.
+    transformedSourceFile = this.addLineMarkersToStatements(transformedSourceFile, ctx, sourceFile);
+
     return transformedSourceFile;
   }
 
+  /**
+   * Add @L line markers to nodes that have original source positions.
+   * This preserves identity mappings for original code, so lines from the source
+   * file map back to themselves rather than inheriting from generated code markers.
+   *
+   * We need to add markers to every node that will be printed on its own line,
+   * including nested members of interfaces, classes, etc.
+   */
+  private addLineMarkersToStatements(
+    transformedFile: ts.SourceFile,
+    ctx: TransformContext,
+    originalSourceFile: ts.SourceFile
+  ): ts.SourceFile {
+    const { ts, factory } = ctx;
+
+    // Check if a node already has a marker comment
+    const hasMarker = (node: ts.Node): boolean => {
+      const existingComments = ts.getSyntheticLeadingComments(node);
+      return existingComments?.some(c =>
+        c.text.startsWith('@T:') || c.text.startsWith('@L:')
+      ) ?? false;
+    };
+
+    // Check if node has valid original position
+    const hasOriginalPosition = (node: ts.Node): boolean => {
+      return node.pos >= 0 && node.end > node.pos;
+    };
+
+    // Recursively process a node and its children to add line markers
+    const addMarkersToNode = <T extends ts.Node>(node: T): T => {
+      // Handle interface declarations - add markers to members
+      if (ts.isInterfaceDeclaration(node)) {
+        const markedMembers = node.members.map(member => {
+          if (!hasMarker(member) && hasOriginalPosition(member)) {
+            return addLineMarker(member, originalSourceFile, member);
+          }
+          return member;
+        });
+        const updatedNode = factory.updateInterfaceDeclaration(
+          node,
+          node.modifiers,
+          node.name,
+          node.typeParameters,
+          node.heritageClauses,
+          markedMembers
+        );
+        // Also mark the interface itself
+        if (!hasMarker(updatedNode) && hasOriginalPosition(node)) {
+          return addLineMarker(updatedNode, originalSourceFile, node) as unknown as T;
+        }
+        return updatedNode as unknown as T;
+      }
+
+      // Handle type alias declarations
+      if (ts.isTypeAliasDeclaration(node)) {
+        if (!hasMarker(node) && hasOriginalPosition(node)) {
+          return addLineMarker(node, originalSourceFile, node);
+        }
+        return node;
+      }
+
+      // Handle class declarations - add markers to members
+      if (ts.isClassDeclaration(node)) {
+        const markedMembers = node.members.map(member => {
+          // Recursively process method bodies
+          let processedMember = member;
+          if (ts.isMethodDeclaration(member) && member.body) {
+            const markedBody = addMarkersToBlock(member.body);
+            if (markedBody !== member.body) {
+              processedMember = factory.updateMethodDeclaration(
+                member,
+                member.modifiers,
+                member.asteriskToken,
+                member.name,
+                member.questionToken,
+                member.typeParameters,
+                member.parameters,
+                member.type,
+                markedBody
+              );
+            }
+          }
+          if (!hasMarker(processedMember) && hasOriginalPosition(member)) {
+            return addLineMarker(processedMember, originalSourceFile, member);
+          }
+          return processedMember;
+        });
+        const updatedNode = factory.updateClassDeclaration(
+          node,
+          node.modifiers,
+          node.name,
+          node.typeParameters,
+          node.heritageClauses,
+          markedMembers
+        );
+        if (!hasMarker(updatedNode) && hasOriginalPosition(node)) {
+          return addLineMarker(updatedNode, originalSourceFile, node) as unknown as T;
+        }
+        return updatedNode as unknown as T;
+      }
+
+      // Handle function declarations - add markers to body statements
+      if (ts.isFunctionDeclaration(node) && node.body) {
+        const markedBody = addMarkersToBlock(node.body);
+        const updatedNode = factory.updateFunctionDeclaration(
+          node,
+          node.modifiers,
+          node.asteriskToken,
+          node.name,
+          node.typeParameters,
+          node.parameters,
+          node.type,
+          markedBody
+        );
+        if (!hasMarker(updatedNode) && hasOriginalPosition(node)) {
+          return addLineMarker(updatedNode, originalSourceFile, node) as unknown as T;
+        }
+        return updatedNode as unknown as T;
+      }
+
+      // Handle variable statements
+      if (ts.isVariableStatement(node)) {
+        if (!hasMarker(node) && hasOriginalPosition(node)) {
+          return addLineMarker(node, originalSourceFile, node);
+        }
+        return node;
+      }
+
+      // Handle expression statements
+      if (ts.isExpressionStatement(node)) {
+        if (!hasMarker(node) && hasOriginalPosition(node)) {
+          return addLineMarker(node, originalSourceFile, node);
+        }
+        return node;
+      }
+
+      // Handle return statements
+      if (ts.isReturnStatement(node)) {
+        if (!hasMarker(node) && hasOriginalPosition(node)) {
+          return addLineMarker(node, originalSourceFile, node);
+        }
+        return node;
+      }
+
+      // Handle if statements
+      if (ts.isIfStatement(node)) {
+        let thenStmt = node.thenStatement;
+        let elseStmt = node.elseStatement;
+
+        if (ts.isBlock(thenStmt)) {
+          thenStmt = addMarkersToBlock(thenStmt);
+        }
+        if (elseStmt && ts.isBlock(elseStmt)) {
+          elseStmt = addMarkersToBlock(elseStmt);
+        }
+
+        const updatedNode = factory.updateIfStatement(node, node.expression, thenStmt, elseStmt);
+        if (!hasMarker(updatedNode) && hasOriginalPosition(node)) {
+          return addLineMarker(updatedNode, originalSourceFile, node) as unknown as T;
+        }
+        return updatedNode as unknown as T;
+      }
+
+      // Default: just mark the node if it has original position
+      if (!hasMarker(node) && hasOriginalPosition(node)) {
+        return addLineMarker(node, originalSourceFile, node);
+      }
+
+      return node;
+    };
+
+    // Add markers to statements in a block
+    const addMarkersToBlock = (block: ts.Block): ts.Block => {
+      const markedStatements = block.statements.map(stmt => addMarkersToNode(stmt));
+      return factory.updateBlock(block, markedStatements);
+    };
+
+    // Process all top-level statements
+    const newStatements = factory.createNodeArray(
+      transformedFile.statements.map(stmt => addMarkersToNode(stmt))
+    );
+
+    return factory.updateSourceFile(transformedFile, newStatements);
+  }
+
   public shouldTransformFile(fileName: string): boolean {
     return shouldTransformFile(fileName, this.config);
   }
 
+  /**
+   * Get pre-compiled ignore patterns, caching them for performance.
+   */
+  private getCompiledPatterns(): CompiledIgnorePatterns {
+    if (!this.compiledPatterns) {
+      this.compiledPatterns = getCompiledIgnorePatterns(this.config);
+    }
+    return this.compiledPatterns;
+  }
+
   /**
    * Check if a TypeNode represents a type that shouldn't be validated.
    * This includes:
@@ -1405,12 +2018,8 @@ export class TypicalTransformer {
    * Also handles union types: "Document | Element" is ignored if "Document" or "Element" is in ignoreTypes.
    */
   private isIgnoredType(typeName: string, typeChecker?: ts.TypeChecker, type?: ts.Type): boolean {
-    // Combine user patterns with DOM types if ignoreDOMTypes is enabled (default: true)
-    const userPatterns = this.config.ignoreTypes ?? [];
-    const domPatterns = this.config.ignoreDOMTypes !== false ? DOM_TYPES_TO_IGNORE : [];
-    const patterns = [...userPatterns, ...domPatterns];
-
-    if (patterns.length === 0) return false;
+    const compiled = this.getCompiledPatterns();
+    if (compiled.allPatterns.length === 0) return false;
 
     // For union types, check each constituent
     if (type && type.isUnion()) {
@@ -1419,12 +2028,12 @@ export class TypicalTransformer {
       );
       if (nonNullTypes.length === 0) return false;
       // All non-null types must be ignored
-      return nonNullTypes.every(t => this.isIgnoredSingleType(t, patterns, typeChecker));
+      return nonNullTypes.every(t => this.isIgnoredSingleType(t, compiled.allPatterns, typeChecker));
     }
 
     // For non-union types, check directly
     if (type && typeChecker) {
-      return this.isIgnoredSingleType(type, patterns, typeChecker);
+      return this.isIgnoredSingleType(type, compiled.allPatterns, typeChecker);
     }
 
     // Fallback: string-based matching for union types like "Document | Element | null"
@@ -1432,25 +2041,42 @@ export class TypicalTransformer {
     const nonNullParts = typeParts.filter(t => t !== 'null' && t !== 'undefined');
     if (nonNullParts.length === 0) return false;
 
-    return nonNullParts.every(part => this.matchesIgnorePattern(part, patterns));
+    return nonNullParts.every(part => this.matchesIgnorePatternCompiled(part, compiled.allPatterns));
   }
 
   /**
    * Check if a single type (not a union) should be ignored.
    * Checks both the type name and its base classes.
+   * Uses Set-based cycle detection to handle recursive type hierarchies.
+   * @param patterns Pre-compiled RegExp patterns
+   * @param visited Set of type IDs already visited (for cycle detection)
    */
-  private isIgnoredSingleType(type: ts.Type, patterns: string[], typeChecker?: ts.TypeChecker, depth = 0): boolean {
-    // Prevent infinite recursion
-    if (depth > 20) return false;
+  private isIgnoredSingleType(
+    type: ts.Type,
+    patterns: RegExp[],
+    typeChecker?: ts.TypeChecker,
+    visited: Set<number> = new Set()
+  ): boolean {
+    // Use type ID for cycle detection (more precise than depth counter)
+    const typeId = (type as { id?: number }).id;
+    if (typeId !== undefined) {
+      if (visited.has(typeId)) {
+        if (process.env.DEBUG) {
+          console.log(`TYPICAL: Cycle detected for type "${type.symbol?.name || '?'}" (id: ${typeId}), skipping`);
+        }
+        return false; // Already visited this type, not ignored
+      }
+      visited.add(typeId);
+    }
 
     const typeName = type.symbol?.name || '';
 
     if (process.env.DEBUG) {
-      console.log(`TYPICAL: isIgnoredSingleType checking type: "${typeName}" (depth: ${depth})`);
+      console.log(`TYPICAL: isIgnoredSingleType checking type: "${typeName}" (visited: ${visited.size})`);
     }
 
     // Check direct name match
-    if (this.matchesIgnorePattern(typeName, patterns)) {
+    if (this.matchesIgnorePatternCompiled(typeName, patterns)) {
       if (process.env.DEBUG) {
         console.log(`TYPICAL: Type "${typeName}" matched ignore pattern directly`);
       }
@@ -1464,7 +2090,7 @@ export class TypicalTransformer {
       console.log(`TYPICAL: Type "${typeName}" has ${baseTypes.length} base types: ${baseTypes.map(t => t.symbol?.name || '?').join(', ')}`);
     }
     for (const baseType of baseTypes) {
-      if (this.isIgnoredSingleType(baseType, patterns, typeChecker, depth + 1)) {
+      if (this.isIgnoredSingleType(baseType, patterns, typeChecker, visited)) {
         if (process.env.DEBUG) {
           console.log(`TYPICAL: Type "${typeName}" ignored because base type "${baseType.symbol?.name}" is ignored`);
         }
@@ -1484,7 +2110,7 @@ export class TypicalTransformer {
                 if (process.env.DEBUG) {
                   console.log(`TYPICAL: Type "${typeName}" extends "${baseTypeName}" (from heritage clause)`);
                 }
-                if (this.matchesIgnorePattern(baseTypeName, patterns)) {
+                if (this.matchesIgnorePatternCompiled(baseTypeName, patterns)) {
                   if (process.env.DEBUG) {
                     console.log(`TYPICAL: Type "${typeName}" ignored because it extends "${baseTypeName}"`);
                   }
@@ -1493,7 +2119,7 @@ export class TypicalTransformer {
                 // Recursively check the heritage type
                 if (typeChecker) {
                   const heritageTypeObj = typeChecker.getTypeAtLocation(heritageType);
-                  if (this.isIgnoredSingleType(heritageTypeObj, patterns, typeChecker, depth + 1)) {
+                  if (this.isIgnoredSingleType(heritageTypeObj, patterns, typeChecker, visited)) {
                     return true;
                   }
 
@@ -1506,7 +2132,7 @@ export class TypicalTransformer {
                       if (process.env.DEBUG) {
                         console.log(`TYPICAL: Type "${typeName}" mixin arg: "${argType.symbol?.name}" (from call expression)`);
                       }
-                      if (this.isIgnoredSingleType(argType, patterns, typeChecker, depth + 1)) {
+                      if (this.isIgnoredSingleType(argType, patterns, typeChecker, visited)) {
                         if (process.env.DEBUG) {
                           console.log(`TYPICAL: Type "${typeName}" ignored because mixin argument "${argType.symbol?.name}" is ignored`);
                         }
@@ -1526,16 +2152,11 @@ export class TypicalTransformer {
   }
 
   /**
-   * Check if a single type name matches any ignore pattern.
+   * Check if a single type name matches any pre-compiled ignore pattern.
+   * @param patterns Pre-compiled RegExp patterns
    */
-  private matchesIgnorePattern(typeName: string, patterns: string[]): boolean {
-    return patterns.some(pattern => {
-      // Convert glob pattern to regex: "React.*" -> /^React\..*$/
-      const regexStr = '^' + pattern
-        .replace(/[.+^${}()|[\]\\]/g, '\\$&')  // Escape special regex chars except *
-        .replace(/\*/g, '.*') + '$';
-      return new RegExp(regexStr).test(typeName);
-    });
+  private matchesIgnorePatternCompiled(typeName: string, patterns: RegExp[]): boolean {
+    return patterns.some(pattern => pattern.test(typeName));
   }
 
   /**
@@ -1979,13 +2600,20 @@ export class TypicalTransformer {
           []
         );
 
-        const declaration = factory.createVariableStatement(
+        let declaration: ts.Statement = factory.createVariableStatement(
           undefined,
           factory.createVariableDeclarationList(
             [factory.createVariableDeclaration(name, undefined, undefined, createCall)],
             ctx.ts.NodeFlags.Const
           )
         );
+
+        // Add source map marker pointing to the type node that triggered this validator
+        // This ensures all the expanded typia validation code maps back to the original type
+        if (typeNode.pos >= 0) {
+          declaration = addSourceMapMarker(declaration, ctx.sourceFile, typeNode);
+        }
+
         statements.push(declaration);
       }
     }