tywrap 0.2.1 → 0.4.0

package/src/tywrap.ts

@@ -4,19 +4,25 @@
 
 import { CodeGenerator } from './core/generator.js';
 import { TypeMapper } from './core/mapper.js';
+import { parseAnnotationToPythonType } from './core/annotation-parser.js';
 import { createConfig } from './config/index.js';
 import type {
   TywrapOptions,
+  PythonGenericParameter,
   PythonFunction,
   PythonModule as TSPythonModule,
   PythonClass,
+  PythonTypeAlias,
   Parameter,
   PythonType,
 } from './types/index.js';
-import { fsUtils, pathUtils, processUtils, hashUtils } from './utils/runtime.js';
+import { fsUtils, pathUtils, processUtils, isWindows } from './utils/runtime.js';
 import { globalCache } from './utils/cache.js';
 import { globalParallelProcessor } from './utils/parallel-processor.js';
 import { resolvePythonExecutable } from './utils/python.js';
+import { computeIrCacheFilename } from './utils/ir-cache.js';
+
+const TYWRAP_IR_VERSION = '0.2.0';
 
 // Collect unknown typing constructs encountered during annotation parsing (per-generate run)
 let unknownTypeNamesCollector: Map<string, number> = new Map();
@@ -80,9 +86,16 @@ export interface GenerateRunOptions {
   check?: boolean;
 }
 
+export interface GenerateFailure {
+  module: string;
+  code: 'ir-unavailable';
+  message: string;
+}
+
 export interface GenerateResult {
   written: string[];
   warnings: string[];
+  failures: GenerateFailure[];
   /**
    * Only set when `GenerateRunOptions.check === true`.
    * Lists files that are missing or differ from what would be generated.
@@ -117,6 +130,7 @@ export async function generate(
   const written: string[] = [];
   const outOfDate: string[] = [];
   const warnings: string[] = [];
+  const failures: GenerateFailure[] = [];
   const outputDir = resolvedOptions.output.dir;
   const caching = resolvedOptions.performance.caching;
   const cacheDir = '.tywrap/cache';
@@ -138,13 +152,14 @@ export async function generate(
   const modules = resolvedOptions.pythonModules ?? {};
   for (const entry of Object.entries(modules)) {
     const moduleKey = entry[0];
+    const moduleConfig = entry[1];
     // reset collector for each module
     unknownTypeNamesCollector = new Map();
     // Prefer Python IR extractor over TS analyzer with optional cache
-    const cacheKey = await computeCacheKey(moduleKey, options);
+    const cacheKey = await computeCacheKey(moduleKey, resolvedOptions);
     let ir: unknown | null = null;
     let irError: string | undefined;
-    if (caching && fsUtils.isAvailable()) {
+    if (caching && fsUtils.isAvailable() && !checkMode) {
       try {
         const cached = await fsUtils.readFile(pathUtils.join(cacheDir, cacheKey));
         ir = JSON.parse(cached);
@@ -153,7 +168,10 @@ export async function generate(
       }
     }
     if (!ir) {
-      const fetchResult = await fetchPythonIr(moduleKey, pythonPath);
+      const fetchResult = await fetchPythonIr(moduleKey, pythonPath, {
+        timeoutMs: resolvedOptions.runtime?.node?.timeout,
+        pythonImportPath: resolvedOptions.pythonImportPath,
+      });
       ir = fetchResult.ir;
       irError = fetchResult.error;
       if (ir && caching && fsUtils.isAvailable() && !checkMode) {
@@ -163,12 +181,90 @@ export async function generate(
       }
     }
     if (!ir) {
-      warnings.push(`No IR produced for module ${moduleKey}${irError ? `: ${irError}` : ''}`);
+      const message = `No IR produced for module ${moduleKey}${irError ? `: ${irError}` : ''}`;
+      warnings.push(message);
+      failures.push({
+        module: moduleKey,
+        code: 'ir-unavailable',
+        message,
+      });
       continue;
     }
 
     const moduleModel = transformIrToTsModel(ir);
 
+    // Apply module-level export filtering (functions/classes + excludes).
+    {
+      const builtInDefaultExcludes = new Set([
+        'dataclass',
+        'property',
+        'staticmethod',
+        'classmethod',
+        'abstractmethod',
+        'cached_property',
+      ]);
+
+      const excludeExact = new Set((moduleConfig.exclude ?? []).map(String));
+      const excludeRegexes: RegExp[] = [];
+      for (const pattern of moduleConfig.excludePatterns ?? []) {
+        try {
+          excludeRegexes.push(new RegExp(String(pattern)));
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          warnings.push(
+            `Module ${moduleKey}: invalid excludePatterns regex "${String(pattern)}": ${message}`
+          );
+        }
+      }
+
+      const shouldExclude = (name: string, applyBuiltInDefaults: boolean): boolean => {
+        if (excludeExact.has(name)) {
+          return true;
+        }
+        if (excludeRegexes.some(r => r.test(name))) {
+          return true;
+        }
+        if (applyBuiltInDefaults && builtInDefaultExcludes.has(name)) {
+          return true;
+        }
+        return false;
+      };
+
+      if (Array.isArray(moduleConfig.functions)) {
+        const allow = new Set(moduleConfig.functions.map(String));
+        for (const requested of allow) {
+          if (!moduleModel.functions.some(f => f.name === requested)) {
+            warnings.push(
+              `Module ${moduleKey}: configured function "${requested}" not found in IR`
+            );
+          }
+        }
+        moduleModel.functions = moduleModel.functions.filter(
+          f => allow.has(f.name) && !shouldExclude(f.name, false)
+        );
+      } else {
+        moduleModel.functions = moduleModel.functions.filter(f => !shouldExclude(f.name, true));
+      }
+
+      if (Array.isArray(moduleConfig.classes)) {
+        const allow = new Set(moduleConfig.classes.map(String));
+        for (const requested of allow) {
+          if (!moduleModel.classes.some(c => c.name === requested)) {
+            warnings.push(`Module ${moduleKey}: configured class "${requested}" not found in IR`);
+          }
+        }
+        moduleModel.classes = moduleModel.classes.filter(
+          c => allow.has(c.name) && !shouldExclude(c.name, false)
+        );
+      } else {
+        moduleModel.classes = moduleModel.classes.filter(c => !shouldExclude(c.name, true));
+      }
+
+      moduleModel.typeAliases = (moduleModel.typeAliases ?? []).filter(
+        alias => !shouldExclude(alias.name, false)
+      );
+    }
+
     // Generate module code
     const annotatedJSDoc = Boolean(resolvedOptions.output?.annotatedJSDoc);
     const gen = instance.generator.generateModuleDefinition(moduleModel, annotatedJSDoc);
@@ -182,7 +278,7 @@ export async function generate(
     if (resolvedOptions.output?.declaration) {
       filesToEmit.push({
         path: pathUtils.join(outputDir, `${baseName}.generated.d.ts`),
-        content: renderDts(gen.typescript),
+        content: gen.declaration,
       });
     }
 
@@ -242,10 +338,10 @@ export async function generate(
   }
 
   if (checkMode) {
-    return { written: [], warnings, outOfDate };
+    return { written: [], warnings, failures, outOfDate };
   }
 
-  return { written, warnings };
+  return { written, warnings, failures };
 }
 
 /**
@@ -253,19 +349,28 @@ export async function generate(
  */
 async function fetchPythonIr(
   moduleName: string,
-  pythonPath: string
+  pythonPath: string,
+  options: { timeoutMs?: number; pythonImportPath?: string[] } = {}
 ): Promise<{ ir: unknown | null; error?: string }> {
   if (!processUtils.isAvailable()) {
     return { ir: null, error: 'Subprocess operations not available in this runtime' };
   }
+  const delimiter = isWindows() ? ';' : ':';
+  const extraPaths = (options.pythonImportPath ?? []).filter(Boolean);
+  const existingPyPath =
+    typeof process !== 'undefined' && typeof process.env === 'object' && process.env
+      ? process.env.PYTHONPATH
+      : undefined;
+  const mergedPyPath = [...extraPaths, ...(existingPyPath ? [existingPyPath] : [])]
+    .filter(Boolean)
+    .join(delimiter);
+  const env = mergedPyPath ? { PYTHONPATH: mergedPyPath } : undefined;
   try {
-    const result = await processUtils.exec(pythonPath, [
-      '-m',
-      'tywrap_ir',
-      '--module',
-      moduleName,
-      '--no-pretty',
-    ]);
+    const result = await processUtils.exec(
+      pythonPath,
+      ['-m', 'tywrap_ir', '--module', moduleName, '--ir-version', TYWRAP_IR_VERSION, '--no-pretty'],
+      { timeoutMs: options.timeoutMs, env }
+    );
     if (result.code === 0) {
       try {
         return { ir: JSON.parse(result.stdout) };
@@ -277,18 +382,40 @@ async function fetchPythonIr(
       }
     }
 
-    // Fallback to invoking local __main__.py
+    const stderrText = result.stderr.trim();
+    const isTywrapIrMissing =
+      stderrText.includes('No module named') && stderrText.includes('tywrap_ir');
+    if (!isTywrapIrMissing) {
+      return { ir: null, error: `tywrap_ir failed. stderr: ${stderrText || 'empty'}` };
+    }
+
+    // Fallback to invoking local __main__.py (useful when running from the repo).
     const localMain = pathUtils.join(process.cwd(), 'tywrap_ir', 'tywrap_ir', '__main__.py');
-    const fallback = await processUtils.exec(pythonPath, [
-      localMain,
-      '--module',
-      moduleName,
-      '--no-pretty',
-    ]);
+    let localMainExists = false;
+    if (fsUtils.isAvailable()) {
+      try {
+        await fsUtils.readFile(localMain);
+        localMainExists = true;
+      } catch {
+        localMainExists = false;
+      }
+    }
+    if (!localMainExists) {
+      return {
+        ir: null,
+        error: `tywrap_ir not found on PYTHONPATH. stderr: ${stderrText || 'empty'}`,
+      };
+    }
+
+    const fallback = await processUtils.exec(
+      pythonPath,
+      [localMain, '--module', moduleName, '--ir-version', TYWRAP_IR_VERSION, '--no-pretty'],
+      { timeoutMs: options.timeoutMs, env }
+    );
     if (fallback.code !== 0) {
       return {
         ir: null,
-        error: `tywrap_ir failed. stderr: ${fallback.stderr.trim() || result.stderr.trim() || 'empty'}`,
+        error: `tywrap_ir failed. stderr: ${fallback.stderr.trim() || stderrText || 'empty'}`,
       };
     }
     try {
@@ -307,73 +434,161 @@ async function fetchPythonIr(
 /**
  * Convert JSON IR from Python into the internal TypeScript model used by the generator.
  */
+function collectModuleTypeVarNames(obj: Record<string, unknown>): Set<string> {
+  const names = new Set<string>();
+  const constants = Array.isArray(obj.constants) ? (obj.constants as unknown[]) : [];
+
+  for (const constant of constants) {
+    const entry = constant as Record<string, unknown>;
+    const name = typeof entry.name === 'string' ? entry.name.trim() : '';
+    if (!name) {
+      continue;
+    }
+
+    const valueRepr = typeof entry.value_repr === 'string' ? entry.value_repr.trim() : '';
+    if (/^~?[A-Za-z_][A-Za-z0-9_]*$/.test(valueRepr) && valueRepr.replace(/^~/, '') === name) {
+      names.add(name);
+      continue;
+    }
+
+    const annotation = typeof entry.annotation === 'string' ? entry.annotation.trim() : '';
+    if (/(^|\.)(TypeVar|ParamSpec|TypeVarTuple)(\[|\(|$)/.test(annotation)) {
+      names.add(name);
+    }
+  }
+
+  return names;
+}
+
 function transformIrToTsModel(ir: unknown): TSPythonModule {
   const obj: Record<string, unknown> =
     typeof ir === 'object' && ir !== null ? (ir as Record<string, unknown>) : {};
   const functions = (obj.functions as unknown[]) ?? [];
   const classes = (obj.classes as unknown[]) ?? [];
-  const mapParam = (p: Record<string, unknown>): Parameter => ({
+  const aliases = (obj.type_aliases as unknown[]) ?? [];
+  const moduleTypeVarNames = collectModuleTypeVarNames(obj);
+  const parseType = (
+    annotation: unknown,
+    typeParameters: readonly PythonGenericParameter[] = []
+  ): PythonType =>
+    parseAnnotationToPythonType(annotation, {
+      onUnknownTypeName: recordUnknown,
+      knownTypeVarNames: moduleTypeVarNames,
+      typeParameters,
+    });
+  const mapTypeParameters = (value: Record<string, unknown>): PythonGenericParameter[] =>
+    Array.isArray(value.type_params)
+      ? (value.type_params as unknown[]).map(v => {
+          const param = (v ?? {}) as Record<string, unknown>;
+          return {
+            name: String(param.name ?? ''),
+            kind: String(param.kind ?? 'typevar') as PythonGenericParameter['kind'],
+            bound: param.bound ? parseType(param.bound) : undefined,
+            constraints: Array.isArray(param.constraints)
+              ? (param.constraints as unknown[]).map(item => parseType(item))
+              : undefined,
+            variance:
+              param.variance === 'covariant' ||
+              param.variance === 'contravariant' ||
+              param.variance === 'invariant'
+                ? param.variance
+                : undefined,
+          } satisfies PythonGenericParameter;
+        })
+      : [];
+  const mapParam = (
+    p: Record<string, unknown>,
+    typeParameters: readonly PythonGenericParameter[] = []
+  ): Parameter => ({
     name: String(p.name ?? ''),
-    type: parseAnnotationToPythonType(p.annotation),
+    type: parseType(p.annotation, typeParameters),
     optional: Boolean(p.default),
     varArgs: p.kind === 'VAR_POSITIONAL',
     kwArgs: p.kind === 'VAR_KEYWORD',
+    positionalOnly: p.kind === 'POSITIONAL_ONLY',
+    keywordOnly: p.kind === 'KEYWORD_ONLY',
   });
 
-  const mapFunc = (f: Record<string, unknown>): PythonFunction => ({
-    name: String(f.name ?? ''),
-    signature: {
-      parameters: Array.isArray(f.parameters)
-        ? (f.parameters as unknown[]).map(v => mapParam((v ?? {}) as Record<string, unknown>))
-        : [],
-      returnType: parseAnnotationToPythonType(f.returns),
+  const mapFunc = (
+    f: Record<string, unknown>,
+    inheritedTypeParameters: readonly PythonGenericParameter[] = []
+  ): PythonFunction => {
+    const localTypeParameters = mapTypeParameters(f);
+    const annotationTypeParameters = [...inheritedTypeParameters, ...localTypeParameters];
+    return {
+      name: String(f.name ?? ''),
+      signature: {
+        parameters: Array.isArray(f.parameters)
+          ? (f.parameters as unknown[]).map(v =>
+              mapParam((v ?? {}) as Record<string, unknown>, annotationTypeParameters)
+            )
+          : [],
+        returnType: parseType(f.returns, annotationTypeParameters),
+        isAsync: Boolean(f.is_async),
+        isGenerator: Boolean(f.is_generator),
+      },
+      docstring: (f.docstring as string | undefined) ?? undefined,
+      decorators: [],
       isAsync: Boolean(f.is_async),
       isGenerator: Boolean(f.is_generator),
-    },
-    docstring: (f.docstring as string | undefined) ?? undefined,
-    decorators: [],
-    isAsync: Boolean(f.is_async),
-    isGenerator: Boolean(f.is_generator),
-    returnType: parseAnnotationToPythonType(f.returns),
-    parameters: Array.isArray(f.parameters)
-      ? (f.parameters as unknown[]).map(v => mapParam((v ?? {}) as Record<string, unknown>))
-      : [],
-  });
+      typeParameters: [...localTypeParameters],
+      returnType: parseType(f.returns, annotationTypeParameters),
+      parameters: Array.isArray(f.parameters)
+        ? (f.parameters as unknown[]).map(v =>
+            mapParam((v ?? {}) as Record<string, unknown>, annotationTypeParameters)
+          )
+        : [],
+    };
+  };
 
-  const mapClass = (c: Record<string, unknown>): PythonClass => ({
-    name: String(c.name ?? ''),
-    bases: Array.isArray(c.bases) ? (c.bases as string[]) : [],
-    methods: Array.isArray(c.methods)
-      ? (c.methods as unknown[]).map(v => mapFunc((v ?? {}) as Record<string, unknown>))
-      : [],
-    properties: Array.isArray(c.fields)
-      ? ((c.fields as unknown[]).map(v => {
-          const p = (v ?? {}) as Record<string, unknown>;
-          const optional = Boolean(p.default);
-          return {
-            name: String(p.name ?? ''),
-            type: parseAnnotationToPythonType(p.annotation),
-            readonly: false,
-            setter: false,
-            getter: true,
-            optional,
-          } as unknown as never;
-        }) as unknown as PythonClass['properties'])
-      : [],
-    docstring: (c.docstring as string | undefined) ?? undefined,
-    decorators: (c.typed_dict as boolean) ? ['__typed_dict__'] : [],
-    kind: (c.typed_dict as boolean)
-      ? 'typed_dict'
-      : (c.is_protocol as boolean)
-        ? 'protocol'
-        : (c.is_namedtuple as boolean)
-          ? 'namedtuple'
-          : (c.is_dataclass as boolean)
-            ? 'dataclass'
-            : (c.is_pydantic as boolean)
-              ? 'pydantic'
-              : 'class',
-  });
+  const mapClass = (c: Record<string, unknown>): PythonClass => {
+    const classTypeParameters = mapTypeParameters(c);
+    return {
+      name: String(c.name ?? ''),
+      bases: Array.isArray(c.bases) ? (c.bases as string[]) : [],
+      methods: Array.isArray(c.methods)
+        ? (c.methods as unknown[]).map(v =>
+            mapFunc((v ?? {}) as Record<string, unknown>, classTypeParameters)
+          )
+        : [],
+      properties: Array.isArray(c.fields)
+        ? (c.fields as unknown[]).map(v => {
+            const p = (v ?? {}) as Record<string, unknown>;
+            return {
+              name: String(p.name ?? ''),
+              type: parseType(p.annotation, classTypeParameters),
+              readonly: false,
+              setter: false,
+              getter: true,
+              optional: Boolean(p.default),
+            };
+          })
+        : [],
+      docstring: (c.docstring as string | undefined) ?? undefined,
+      decorators: (c.typed_dict as boolean) ? ['__typed_dict__'] : [],
+      kind: (c.typed_dict as boolean)
+        ? 'typed_dict'
+        : (c.is_protocol as boolean)
+          ? 'protocol'
+          : (c.is_namedtuple as boolean)
+            ? 'namedtuple'
+            : (c.is_dataclass as boolean)
+              ? 'dataclass'
+              : (c.is_pydantic as boolean)
+                ? 'pydantic'
+                : 'class',
+      typeParameters: classTypeParameters,
+    };
+  };
+
+  const mapTypeAlias = (alias: Record<string, unknown>): PythonTypeAlias => {
+    const typeParameters = mapTypeParameters(alias);
+    return {
+      name: String(alias.name ?? ''),
+      type: parseType(alias.definition, typeParameters),
+      typeParameters,
+    };
+  };
 
   const moduleModel: TSPythonModule = {
     name: (obj.module as string) ?? 'module',
@@ -384,255 +599,13 @@ function transformIrToTsModel(ir: unknown): TSPythonModule {
         : undefined,
     functions: functions.map(v => mapFunc((v ?? {}) as Record<string, unknown>)),
     classes: classes.map(v => mapClass((v ?? {}) as Record<string, unknown>)),
+    typeAliases: aliases.map(v => mapTypeAlias((v ?? {}) as Record<string, unknown>)),
     imports: [],
     exports: [],
   };
   return moduleModel;
 }
 
-function unknownType(): PythonType {
-  return { kind: 'custom', name: 'Any', module: 'typing' };
-}
-
-// Parse Python IR annotation string -> PythonType
-function parseAnnotationToPythonType(annotation: unknown, depth = 0): PythonType {
-  if (annotation === null || annotation === undefined) {
-    return unknownType();
-  }
-  if (depth > 100) {
-    return unknownType();
-  }
-  const raw = String(annotation).trim();
-
-  // Handle built-in class repr: <class 'int'>
-  const classMatch = raw.match(/^<class ['"][^'"]+['"]>$/);
-  if (classMatch) {
-    const inner = (raw.match(/^<class ['"]([^'"]+)['"]>$/) ?? [])[1] ?? '';
-    const name = (inner.split('.').pop() ?? '').toString();
-    return mapSimpleName(name);
-  }
-
-  // PEP 604 unions: int | str | None
-  if (raw.includes(' | ')) {
-    const parts = splitTopLevel(raw, '|');
-    const types = parts.map(p => parseAnnotationToPythonType(p.trim(), depth + 1));
-    return { kind: 'union', types };
-  }
-
-  // typing.Union[...]
-  if (raw.startsWith('typing.Union[') || raw.startsWith('Union[')) {
-    const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-    const parts = splitTopLevel(inner, ',');
-    const types = parts.map(p => parseAnnotationToPythonType(p.trim(), depth + 1));
-    return { kind: 'union', types };
-  }
-
-  // Optional[T]
-  if (raw.startsWith('typing.Optional[') || raw.startsWith('Optional[')) {
-    const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-    const base = parseAnnotationToPythonType(inner, depth + 1);
-    return { kind: 'optional', type: base };
-  }
-
-  // Literal[...] -> literal values union
-  if (raw.startsWith('typing.Literal[') || raw.startsWith('Literal[')) {
-    const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-    const parts = splitTopLevel(inner, ',');
-    if (parts.length === 1) {
-      return mapLiteral(String(parts[0] ?? '').trim());
-    }
-    return { kind: 'union', types: parts.map(p => mapLiteral(String(p).trim())) } as PythonType;
-  }
-
-  // typing_extensions wrappers: ClassVar[T], Final[T], Required[T], NotRequired[T]
-  const extMatch = raw.match(
-    /^(typing\.|typing_extensions\.)?(ClassVar|Final|Required|NotRequired)\[(.*)\]$/
-  );
-  if (extMatch) {
-    const inner = extMatch[3] ?? '';
-    const base = parseAnnotationToPythonType(inner, depth + 1);
-    return base;
-  }
-
-  // LiteralString
-  if (raw === 'typing.LiteralString' || raw === 'LiteralString') {
-    return { kind: 'primitive', name: 'str' } as PythonType;
-  }
-
-  // Callable[[...], R]
-  if (raw.startsWith('typing.Callable[') || raw.startsWith('Callable[')) {
-    const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-    const parts = splitTopLevel(inner, ',');
-    if (parts.length >= 2) {
-      const paramsPart = (parts[0] ?? '').trim();
-      const returnPart = parts.slice(1).join(',').trim();
-      const paramInner =
-        paramsPart.startsWith('[') && paramsPart.endsWith(']') ? paramsPart.slice(1, -1) : '';
-      const paramTypes = ((): PythonType[] => {
-        const trimmed = paramInner.trim();
-        if (trimmed === '...' || trimmed === 'Ellipsis') {
-          return [{ kind: 'custom', name: '...' } as PythonType];
-        }
-        return trimmed
-          ? splitTopLevel(trimmed, ',').map(p => parseAnnotationToPythonType(p.trim(), depth + 1))
-          : [];
-      })();
-      const returnType = parseAnnotationToPythonType(returnPart, depth + 1);
-      return { kind: 'callable', parameters: paramTypes, returnType } as PythonType;
-    }
-  }
-
-  // Mapping[K, V] / Dict[K, V] normalization
-  if (raw.startsWith('typing.Mapping[') || raw.startsWith('Mapping[')) {
-    const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-    const parts = splitTopLevel(inner, ',');
-    const itemTypes = parts.map(p => parseAnnotationToPythonType(p.trim(), depth + 1));
-    return { kind: 'collection', name: 'dict', itemTypes } as PythonType;
-  }
-
-  // Annotated[T, ...] -> annotated node with base and metadata
-  if (raw.startsWith('typing.Annotated[') || raw.startsWith('Annotated[')) {
-    const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-    const parts = splitTopLevel(inner, ',');
-    if (parts.length > 0) {
-      const base = parseAnnotationToPythonType((parts[0] ?? '').trim(), depth + 1);
-      const metaParts = parts.slice(1).map(p => String(p).trim());
-      return { kind: 'annotated', base, metadata: metaParts } as PythonType;
-    }
-  }
-
-  // Collections: list[T], dict[K,V], tuple[...], set[T]
-  const coll = normalizeCollectionName(raw);
-  if (coll) {
-    const { name, inner } = coll;
-    const itemParts =
-      name === 'dict' ? splitTopLevel(inner ?? '', ',') : splitTopLevel(inner ?? '', ',');
-    const itemTypes = (inner ? itemParts : []).map(p =>
-      parseAnnotationToPythonType(p.trim(), depth + 1)
-    );
-    return { kind: 'collection', name, itemTypes };
-  }
-
-  // typing.Callable[...] unlikely for now - treat as custom
-
-  // Bare names like int, str, float, bool, bytes, None
-  return mapSimpleName(raw);
-}
-
-function mapSimpleName(name: string): PythonType {
-  const n = name.replace(/^typing\./, '').trim();
-  if (n === 'int' || n === 'float' || n === 'str' || n === 'bool' || n === 'bytes') {
-    // cast to the specific union type without using any
-    return { kind: 'primitive', name: n };
-  }
-  // Track unknown typing-ish names for diagnostics
-  if (
-    n === 'Any' ||
-    n === 'Never' ||
-    n === 'LiteralString' ||
-    n === 'ClassVar' ||
-    n === 'Final' ||
-    n === 'TypeAlias' ||
-    n === 'Required' ||
-    n === 'NotRequired'
-  ) {
-    try {
-      recordUnknown(n);
-    } catch {}
-  }
-  if (n === 'None' || n.toLowerCase() === 'nonetype') {
-    return { kind: 'primitive', name: 'None' };
-  }
-  if (n === 'list' || n === 'List') {
-    return { kind: 'collection', name: 'list', itemTypes: [] };
-  }
-  if (n === 'dict' || n === 'Dict') {
-    return { kind: 'collection', name: 'dict', itemTypes: [] };
-  }
-  if (n === 'tuple' || n === 'Tuple') {
-    return { kind: 'collection', name: 'tuple', itemTypes: [] };
-  }
-  if (n === 'set' || n === 'Set') {
-    return { kind: 'collection', name: 'set', itemTypes: [] };
-  }
-  return { kind: 'custom', name: n };
-}
-
-function normalizeCollectionName(
-  raw: string
-): { name: 'list' | 'dict' | 'tuple' | 'set' | 'frozenset'; inner?: string } | null {
-  const m = raw.match(/^(typing\.)?(List|Dict|Tuple|Set|list|dict|tuple|set)\[(.*)\]$/);
-  if (!m) {
-    return null;
-  }
-  const nameRaw = String(m[2] ?? '');
-  const name =
-    nameRaw.toLowerCase() === 'list'
-      ? 'list'
-      : nameRaw.toLowerCase() === 'dict'
-        ? 'dict'
-        : nameRaw.toLowerCase() === 'tuple'
-          ? 'tuple'
-          : 'set';
-  return { name, inner: String(m[3] ?? '') };
-}
-
-function splitTopLevel(input: string, sep: '|' | ','): string[] {
-  const results: string[] = [];
-  let level = 0;
-  let cur = '';
-  let guard = 0;
-  for (let i = 0; i < input.length; i++) {
-    // Depth/length guard to avoid pathological recursion/loops
-    guard++;
-    if (guard > 20000) {
-      // Bail out safely; push remaining and break
-      if (cur.trim()) {
-        results.push(cur.trim());
-      }
-      break;
-    }
-    const ch = input.charAt(i);
-    if (ch === '[' || ch === '(') {
-      level++;
-    }
-    if (ch === ']' || ch === ')') {
-      level = Math.max(0, level - 1);
-    }
-    if (level === 0 && input.slice(i, i + sep.length) === sep) {
-      results.push(cur.trim());
-      cur = '';
-      i += sep.length - 1;
-      continue;
-    }
-    cur += ch;
-  }
-  if (cur.trim()) {
-    results.push(cur.trim());
-  }
-  return results;
-}
-
-function mapLiteral(text: string): PythonType {
-  // strip quotes if present
-  const t = text.trim();
-  if ((t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'))) {
-    return { kind: 'literal', value: t.slice(1, -1) } as PythonType;
-  }
-  if (t === 'True' || t === 'False') {
-    return { kind: 'literal', value: t === 'True' } as PythonType;
-  }
-  if (t === 'None') {
-    return { kind: 'literal', value: null } as PythonType;
-  }
-  const num = Number(t);
-  if (!Number.isNaN(num)) {
-    return { kind: 'literal', value: num } as PythonType;
-  }
-  // fallback
-  return { kind: 'custom', name: t } as PythonType;
-}
-
 /**
  * Compute a stable cache key filename for a module and options
  */
@@ -650,6 +623,8 @@ async function computeCacheKey(
   const keyObject = {
     module: moduleName,
     moduleVersion: moduleConfig?.version ?? null,
+    irVersion: TYWRAP_IR_VERSION,
+    pythonImportPath: options.pythonImportPath ?? [],
     runtime: {
       pythonPath: runtimePython,
       virtualEnv: options.runtime?.node?.virtualEnv ?? null,
@@ -665,47 +640,7 @@ async function computeCacheKey(
     },
     typeHints: moduleConfig?.typeHints ?? 'strict',
   } as const;
-  const normalized = JSON.stringify(keyObject);
-  const digest = await hashUtils.sha256Hex(normalized);
-  return `ir_${moduleName}_${digest.slice(0, 16)}.json`;
-}
-
-/**
- * Very lightweight .d.ts emitter derived from generated TS wrappers
- * This is intentionally minimal and stable for our wrappers shape.
- */
-function renderDts(generatedTs: string): string {
-  const header = `// Generated by tywrap\n// Type Declarations\n// DO NOT EDIT MANUALLY\n\n`;
-  const lines: string[] = [header];
-  // Extract function exports
-  const funcRegex = /export\s+async\s+function\s+(\w+)\s*\(([^)]*)\)\s*:\s*Promise<([^>]+)>/g;
-  let m: RegExpExecArray | null;
-  while ((m = funcRegex.exec(generatedTs)) !== null) {
-    const name = m[1];
-    const params = m[2];
-    const ret = m[3];
-    lines.push(`export function ${name}(${params}): Promise<${ret}>;`);
-  }
-  // Extract class exports and methods
-  const classRegex = /export\s+class\s+(\w+)\s*\{([\s\S]*?)\n\}/g;
-  while ((m = classRegex.exec(generatedTs)) !== null) {
-    const className = String(m[1] ?? '');
-    const body = String(m[2] ?? '');
-    // Constructor is always variadic unknown[] in current generator
-    const methods: string[] = [];
-    const methodRegex = /\n\s+async\s+(\w+)\s*\(([^)]*)\)\s*:\s*Promise<([^>]+)>/g;
-    let mm: RegExpExecArray | null;
-    while ((mm = methodRegex.exec(body)) !== null) {
-      methods.push(`  ${mm[1]}(${mm[2]}): Promise<${mm[3]}>;`);
-    }
-    lines.push(`export class ${className} {`);
-    lines.push(`  constructor(...args: unknown[]);`);
-    if (methods.length > 0) {
-      lines.push(methods.join('\n'));
-    }
-    lines.push('}');
-  }
-  return `${lines.join('\n')}\n`;
+  return await computeIrCacheFilename(keyObject);
 }
 
 /**