tywrap 0.8.0 → 0.9.0

package/src/tywrap.ts

@@ -16,13 +16,15 @@ import type {
   Parameter,
   PythonType,
   PythonModuleConfig,
+  IrContract,
 } from './types/index.js';
 import { fsUtils, pathUtils, processUtils, isWindows } from './utils/runtime.js';
 import { globalCache } from './utils/cache.js';
 import { resolvePythonExecutable } from './utils/python.js';
 import { computeIrCacheFilename } from './utils/ir-cache.js';
+import { logger } from './utils/logger.js';
 
-const TYWRAP_IR_VERSION = '0.3.0';
+const TYWRAP_IR_VERSION = '0.4.0';
 
 // Collect unknown typing constructs encountered during annotation parsing (per-generate run)
 let unknownTypeNamesCollector: Map<string, number> = new Map();
@@ -34,7 +36,7 @@ function recordUnknown(name: string): void {
 /**
  * Main tywrap function
  */
-export interface TywrapInstance {
+interface TywrapInstance {
   mapper: TypeMapper;
   generator: CodeGenerator;
   options: Partial<TywrapOptions>;
@@ -42,7 +44,9 @@ export interface TywrapInstance {
 
 export async function tywrap(options: Partial<TywrapOptions> = {}): Promise<TywrapInstance> {
   const mapper = new TypeMapper({ presets: options.types?.presets });
-  const generator = new CodeGenerator(mapper);
+  const generator = new CodeGenerator(mapper, {
+    onTypeDegrade: typeName => recordUnknown(`unresolvable generated type ${typeName}`),
+  });
 
   globalCache.setDebug(options.debug ?? false);
 
@@ -63,7 +67,7 @@ export interface GenerateRunOptions {
 
 export interface GenerateFailure {
   module: string;
-  code: 'ir-unavailable';
+  code: 'ir-unavailable' | 'ir-version-mismatch' | 'contract-invalid';
   message: string;
 }
 
@@ -83,6 +87,68 @@ function normalizeForComparison(text: string): string {
   return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
 }
 
+function stableJson(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stableJson);
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, child]) => [key, stableJson(child)])
+    );
+  }
+  return value;
+}
+
+function serializeContract(ir: IrContract): string {
+  const contract = { ...ir };
+  delete contract.metadata;
+  return `${JSON.stringify(stableJson(contract), null, 2)}\n`;
+}
+
+function validateIrVersion(
+  ir: unknown,
+  source: string
+): { ir: IrContract | null; error?: string; code?: GenerateFailure['code'] } {
+  if (ir === null || typeof ir !== 'object' || Array.isArray(ir)) {
+    return { ir: null, code: 'contract-invalid', error: `${source} is not a JSON IR object.` };
+  }
+  const contract = ir as IrContract;
+  if (typeof contract.ir_version !== 'string') {
+    return {
+      ir: null,
+      code: 'contract-invalid',
+      error: `${source} is missing its string ir_version.`,
+    };
+  }
+  if (contract.ir_version !== TYWRAP_IR_VERSION) {
+    return {
+      ir: null,
+      code: 'ir-version-mismatch',
+      error: `IR version mismatch: TypeScript expects ${TYWRAP_IR_VERSION}, but ${source} declares ${contract.ir_version}. Regenerate the contract with a matching tywrap_ir.`,
+    };
+  }
+  if (typeof contract.module !== 'string' || contract.module.length === 0) {
+    return { ir: null, code: 'contract-invalid', error: `${source} is missing its module name.` };
+  }
+  const requiredArrays: ReadonlyArray<readonly [string, unknown]> = [
+    ['functions', contract.functions],
+    ['classes', contract.classes],
+    ['type_aliases', contract.type_aliases],
+  ];
+  for (const [field, value] of requiredArrays) {
+    if (!Array.isArray(value)) {
+      return {
+        ir: null,
+        code: 'contract-invalid',
+        error: `${source} is missing required array field ${field}.`,
+      };
+    }
+  }
+  return { ir: contract };
+}
+
 async function safeReadFile(path: string): Promise<string | null> {
   try {
     return await fsUtils.readFile(path);
@@ -106,13 +172,17 @@ async function fetchAndCacheIr(
   cacheKey: string,
   caching: boolean,
   checkMode: boolean
-): Promise<{ ir: unknown | null; error?: string }> {
+): Promise<{ ir: IrContract | null; error?: string; code?: GenerateFailure['code'] }> {
   let ir: unknown | null = null;
   let irError: string | undefined;
   if (caching && fsUtils.isAvailable() && !checkMode) {
     try {
       const cached = await fsUtils.readFile(pathUtils.join(CACHE_DIR, cacheKey));
-      ir = JSON.parse(cached);
+      const cachedValidation = validateIrVersion(
+        JSON.parse(cached),
+        `Cached Python IR for ${moduleKey}`
+      );
+      ir = cachedValidation.ir;
     } catch {
       ir = null;
     }
@@ -124,13 +194,60 @@ async function fetchAndCacheIr(
     });
     ir = fetchResult.ir;
     irError = fetchResult.error;
-    if (ir && caching && fsUtils.isAvailable() && !checkMode) {
-      try {
-        await fsUtils.writeFile(pathUtils.join(CACHE_DIR, cacheKey), JSON.stringify(ir));
-      } catch {}
+  }
+  if (!ir) {
+    return { ir: null, error: irError, code: 'ir-unavailable' };
+  }
+  const validated = validateIrVersion(ir, `Python IR for ${moduleKey}`);
+  if (!validated.ir) {
+    return {
+      ir: null,
+      error: irError ?? validated.error,
+      code: validated.code ?? 'ir-unavailable',
+    };
+  }
+  if (caching && fsUtils.isAvailable() && !checkMode) {
+    try {
+      await fsUtils.writeFile(pathUtils.join(CACHE_DIR, cacheKey), JSON.stringify(validated.ir));
+    } catch {}
+  }
+  return { ir: validated.ir };
+}
+
+async function readContractInput(
+  moduleKey: string,
+  contractInput: TywrapOptions['contractInput']
+): Promise<{ ir: IrContract | null; error?: string; code?: GenerateFailure['code'] }> {
+  const inputPath = typeof contractInput === 'string' ? contractInput : contractInput?.[moduleKey];
+  if (!inputPath) {
+    return {
+      ir: null,
+      code: 'contract-invalid',
+      error: `No contractInput path configured for module ${moduleKey}.`,
+    };
+  }
+  try {
+    const parsed = JSON.parse(await fsUtils.readFile(inputPath)) as unknown;
+    const validated = validateIrVersion(parsed, `Contract ${inputPath}`);
+    if (!validated.ir) {
+      return { ir: null, error: validated.error, code: validated.code };
     }
+    if (validated.ir.module !== moduleKey) {
+      return {
+        ir: null,
+        code: 'contract-invalid',
+        error: `Contract ${inputPath} is for module ${validated.ir.module}, not ${moduleKey}.`,
+      };
+    }
+    return { ir: validated.ir };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ir: null,
+      code: 'contract-invalid',
+      error: `Failed to read contract ${inputPath}: ${message}`,
+    };
   }
-  return { ir, error: irError };
 }
 
 /**
@@ -320,25 +437,39 @@ export async function generate(
     unknownTypeNamesCollector = new Map();
     // Resolve module IR via the Python extractor (with optional cache)
     const cacheKey = await computeCacheKey(moduleKey, resolvedOptions);
-    const { ir, error: irError } = await fetchAndCacheIr(
-      moduleKey,
-      resolvedOptions,
-      pythonPath,
-      cacheKey,
-      caching,
-      checkMode
-    );
+    const irResult = resolvedOptions.contractInput
+      ? await readContractInput(moduleKey, resolvedOptions.contractInput)
+      : await fetchAndCacheIr(moduleKey, resolvedOptions, pythonPath, cacheKey, caching, checkMode);
+    const { ir, error: irError } = irResult;
     if (!ir) {
       const message = `No IR produced for module ${moduleKey}${irError ? `: ${irError}` : ''}`;
       warnings.push(message);
       failures.push({
         module: moduleKey,
-        code: 'ir-unavailable',
+        code: irResult.code ?? 'ir-unavailable',
         message,
       });
       continue;
     }
 
+    const irWarnings = Array.isArray((ir as Record<string, unknown>).warnings)
+      ? ((ir as Record<string, unknown>).warnings as unknown[])
+      : [];
+    for (const warning of irWarnings) {
+      if (typeof warning !== 'string') {
+        continue;
+      }
+      // Only type-honesty degrades feed --fail-on-warn. Environment capability
+      // notices (e.g. typing.get_overloads missing on Python < 3.11) describe
+      // the analyzing interpreter, not the generated types, and must not fail
+      // an otherwise clean build.
+      if (warning.startsWith('Return annotation for ')) {
+        recordUnknown(`Python IR warning: ${warning}`);
+      } else {
+        logger.info(`Python IR notice: ${warning}`, { component: 'Generate' });
+      }
+    }
+
     const moduleModel = transformIrToTsModel(ir);
 
     // Apply module-level export filtering (functions/classes + excludes).
@@ -351,6 +482,10 @@ export async function generate(
     const baseName = moduleModel.name || 'module';
     const filesToEmit: Array<{ path: string; content: string }> = [
       { path: pathUtils.join(outputDir, `${baseName}.generated.ts`), content: gen.typescript },
+      {
+        path: pathUtils.join(outputDir, `${baseName}.contract.json`),
+        content: serializeContract(ir),
+      },
     ];
 
     // Optional .d.ts emission (header-only declarations mirroring exports)
@@ -441,7 +576,7 @@ async function fetchPythonIr(
   try {
     const primary = await execAndParseIr(
       pythonPath,
-      ['-m', 'tywrap_ir', '--module', moduleName, '--ir-version', TYWRAP_IR_VERSION, '--no-pretty'],
+      ['-m', 'tywrap_ir', '--module', moduleName, '--no-pretty'],
       execOptions,
       'tywrap_ir output'
     );
@@ -476,7 +611,7 @@ async function fetchPythonIr(
 
     const fallback = await execAndParseIr(
       pythonPath,
-      [localMain, '--module', moduleName, '--ir-version', TYWRAP_IR_VERSION, '--no-pretty'],
+      [localMain, '--module', moduleName, '--no-pretty'],
       execOptions,
       'tywrap_ir fallback output'
     );

package/src/utils/cache.ts

@@ -12,7 +12,7 @@ import { getComponentLogger } from './logger.js';
 
 const log = getComponentLogger('Cache');
 
-export interface CacheEntry<T = unknown> {
+interface CacheEntry<T = unknown> {
   key: string;
   data: T;
   timestamp: number;
@@ -27,7 +27,7 @@ export interface CacheEntry<T = unknown> {
   };
 }
 
-export interface CacheStats {
+interface CacheStats {
   totalEntries: number;
   totalSize: number;
   hitRate: number;
@@ -36,7 +36,7 @@ export interface CacheStats {
   memoryUsage: number;
 }
 
-export interface CacheConfig {
+interface CacheConfig {
   baseDir: string;
   maxSize: number; // Maximum cache size in bytes
   maxAge: number; // Maximum age in milliseconds

package/src/utils/codec.ts

@@ -9,6 +9,8 @@
  * Sklearn estimators: { "__tywrap__": "sklearn.estimator", "encoding": "json", ... }
  */
 
+import { tagDecodedShape } from '../runtime/validators.js';
+
 // Avoid hard dependency on apache-arrow types at compile time to keep install optional.
 export type ArrowTable = { readonly numCols?: number; readonly numRows?: number } & Record<
   string,
@@ -68,6 +70,7 @@ export type ValueEnvelope =
       readonly b64?: string; // when encoding=arrow
       readonly data?: unknown; // when encoding=json
       readonly shape?: readonly number[];
+      readonly dtype?: string | null;
     }
   | {
       readonly __tywrap__: 'scipy.sparse';
@@ -442,13 +445,16 @@ function decodeArrowOrJsonEnvelope<T>(
       throw new Error(`Invalid ${typeTag} envelope: missing b64`);
     }
     const bytes = fromBase64(b64);
-    return decodeArrow(bytes);
+    const decoded = decodeArrow(bytes);
+    return isPromiseLike(decoded)
+      ? decoded.then(item => tagDecodedShape(item, { marker: typeTag as 'dataframe' | 'series' }))
+      : tagDecodedShape(decoded, { marker: typeTag as 'dataframe' | 'series' });
   }
   if (encoding === 'json') {
     if (!('data' in value)) {
       throw new Error(`Invalid ${typeTag} envelope: missing data`);
     }
-    return value.data;
+    return tagDecodedShape(value.data, { marker: typeTag as 'dataframe' | 'series' });
   }
   throw new Error(`Invalid ${typeTag} envelope: unsupported encoding ${String(encoding)}`);
 }
@@ -463,6 +469,8 @@ const decodeNdarrayEnvelope: EnvelopeHandler = (value, decodeArrow) => {
   const encoding = value.encoding;
   const shapeValue = value.shape;
   const shape = isNumberArray(shapeValue) ? shapeValue : undefined;
+  const dtype = typeof value.dtype === 'string' ? value.dtype : undefined;
+  const metadata = { marker: 'ndarray' as const, dims: shape?.length, dtype };
 
   if (encoding === 'arrow') {
     const b64 = value.b64;
@@ -480,30 +488,30 @@ const decodeNdarrayEnvelope: EnvelopeHandler = (value, decodeArrow) => {
       return decoded.then(data => {
         const values = extractArrowValues(data);
         if (!values) {
-          return data; // Fallback: return raw data if extraction fails
+          return tagDecodedShape(data, metadata); // Fallback: keep provenance on raw data.
         }
         // Reshape scalars and multi-dimensional arrays, but not 1D
-        if (shape && shape.length !== 1) {
-          return reshapeArray(values, shape);
-        }
-        return values;
+        return tagDecodedShape(
+          shape && shape.length !== 1 ? reshapeArray(values, shape) : values,
+          metadata
+        );
       });
     }
     const values = extractArrowValues(decoded);
     if (!values) {
-      return decoded; // Fallback: return raw data if extraction fails
+      return tagDecodedShape(decoded, metadata); // Fallback: keep provenance on raw data.
     }
     // Reshape scalars and multi-dimensional arrays, but not 1D
-    if (shape && shape.length !== 1) {
-      return reshapeArray(values, shape);
-    }
-    return values;
+    return tagDecodedShape(
+      shape && shape.length !== 1 ? reshapeArray(values, shape) : values,
+      metadata
+    );
   }
   if (encoding === 'json') {
     if (!('data' in value)) {
       throw new Error('Invalid ndarray envelope: missing data');
     }
-    return value.data;
+    return tagDecodedShape(value.data, metadata);
   }
   throw new Error(`Invalid ndarray envelope: unsupported encoding ${String(encoding)}`);
 };

package/src/utils/ir-cache.ts

@@ -1,6 +1,6 @@
 import { hashUtils } from './runtime.js';
 
-export interface IrCacheKeyObject {
+interface IrCacheKeyObject {
   module: string;
   moduleVersion: string | null;
   irVersion: string;

package/src/utils/runtime.ts

@@ -23,13 +23,16 @@ interface RuntimeCapabilities {
 
 // Cache for runtime detection to avoid repeated environment checks
 let runtimeCache: RuntimeInfo | null = null;
-
-/**
- * Clear runtime cache (for testing purposes only)
- * @internal
- */
-export function clearRuntimeCache(): void {
-  runtimeCache = null;
+let runtimeCacheSignature: string | undefined;
+
+function currentRuntimeSignature(): string {
+  return [
+    typeof Deno !== 'undefined' && Deno !== null,
+    typeof Bun !== 'undefined' && Bun !== null,
+    typeof process !== 'undefined' && process.versions?.node,
+    typeof window !== 'undefined' ? window.isSecureContext : undefined,
+    typeof self !== 'undefined' ? self.isSecureContext : undefined,
+  ].join('|');
 }
 
 /**
@@ -37,7 +40,8 @@ export function clearRuntimeCache(): void {
  * Results are cached and frozen to prevent external mutation
  */
 export function detectRuntime(): RuntimeInfo {
-  if (runtimeCache) {
+  const signature = currentRuntimeSignature();
+  if (runtimeCache && runtimeCacheSignature === signature) {
     return runtimeCache;
   }
   // Deno detection (must come before Node.js check)
@@ -56,6 +60,7 @@ export function detectRuntime(): RuntimeInfo {
       capabilities: Object.freeze(capabilities),
     };
     runtimeCache = Object.freeze(result) as RuntimeInfo;
+    runtimeCacheSignature = signature;
     return runtimeCache;
   }
 
@@ -75,6 +80,7 @@ export function detectRuntime(): RuntimeInfo {
       capabilities: Object.freeze(capabilities),
     };
     runtimeCache = Object.freeze(result) as RuntimeInfo;
+    runtimeCacheSignature = signature;
     return runtimeCache;
   }
 
@@ -94,6 +100,7 @@ export function detectRuntime(): RuntimeInfo {
       capabilities: Object.freeze(capabilities),
     };
     runtimeCache = Object.freeze(result) as RuntimeInfo;
+    runtimeCacheSignature = signature;
     return runtimeCache;
   }
 
@@ -119,6 +126,7 @@ export function detectRuntime(): RuntimeInfo {
       capabilities: Object.freeze(capabilities),
     };
     runtimeCache = Object.freeze(result) as RuntimeInfo;
+    runtimeCacheSignature = signature;
     return runtimeCache;
   }
 
@@ -137,6 +145,7 @@ export function detectRuntime(): RuntimeInfo {
 
   // Cache and freeze the result to prevent external mutation
   runtimeCache = Object.freeze(result) as RuntimeInfo;
+  runtimeCacheSignature = signature;
   return runtimeCache;
 }
 
@@ -183,52 +192,6 @@ export function hasCapability(capability: keyof RuntimeCapabilities): boolean {
   return getRuntimeCapabilities()[capability];
 }
 
-/**
- * Get the best runtime strategy for Python execution
- */
-export function getBestPythonRuntime(): 'node' | 'pyodide' | 'http' {
-  const runtime = detectRuntime();
-
-  if (runtime.name === 'browser') {
-    return 'pyodide';
-  }
-
-  if (runtime.capabilities.subprocess) {
-    return 'node'; // Works for Node.js, Deno, and Bun
-  }
-
-  // Fallback to HTTP bridge
-  return 'http';
-}
-
-type PathModule = typeof import('node:path');
-
-// Cache for lazy-loaded path module
-let pathModule: PathModule | null = null;
-
-/**
- * Lazy load Node.js path module on demand
- */
-async function loadPathModule(): Promise<PathModule | null> {
-  if (pathModule) {
-    return pathModule;
-  }
-
-  const runtime = detectRuntime();
-  if (runtime.name === 'node') {
-    try {
-      pathModule = await import('node:path');
-      return pathModule;
-    } catch {
-      // Fallback for older Node.js versions
-      pathModule = await import('path');
-      return pathModule;
-    }
-  }
-
-  return null;
-}
-
 /**
  * Apply a single path segment to the accumulated normalized segments,
  * resolving '..' and dropping '.'/empty segments in place.
@@ -283,30 +246,6 @@ export const pathUtils = {
     return normalizePath(joined);
   },
 
-  /**
-   * Join paths asynchronously with enhanced Node.js support
-   */
-  async joinAsync(...segments: string[]): Promise<string> {
-    const runtime = detectRuntime();
-
-    // For Node.js, use the real path module when available
-    if (runtime.name === 'node') {
-      const pathMod = await loadPathModule();
-      if (pathMod?.posix) {
-        return pathMod.posix.join(...segments);
-      }
-    }
-
-    // Fallback implementation with normalization
-    const joined = segments
-      .filter(Boolean)
-      .join('/')
-      .replace(/\/+/g, '/') // Replace multiple slashes with single slash
-      .replace(/\\/g, '/'); // Normalize backslashes to forward slashes
-
-    return normalizePath(joined);
-  },
-
   /**
    * Resolve absolute path in a cross-runtime way (synchronous)
    */
@@ -329,27 +268,6 @@ export const pathUtils = {
     // Fallback: normalize and return as-is for relative paths
     return normalizePath(path);
   },
-
-  /**
-   * Resolve absolute path in a cross-runtime way (asynchronous)
-   */
-  async resolveAsync(path: string): Promise<string> {
-    const runtime = detectRuntime();
-
-    if (runtime.name === 'node') {
-      const pathMod = await loadPathModule();
-      if (pathMod) {
-        return pathMod.resolve(path);
-      }
-    }
-
-    if (runtime.name === 'browser') {
-      return new URL(path, location.href).href;
-    }
-
-    // Fallback: normalize and return as-is
-    return normalizePath(path);
-  },
 };
 
 /**
@@ -642,28 +560,6 @@ export function isWindows(): boolean {
   return deno?.build?.os === 'windows';
 }
 
-/**
- * Check if running on macOS
- */
-export function isMacOS(): boolean {
-  if (typeof process !== 'undefined' && process.platform) {
-    return process.platform === 'darwin';
-  }
-  const deno = (globalThis as unknown as { Deno?: { build?: { os?: string } } }).Deno;
-  return deno?.build?.os === 'darwin';
-}
-
-/**
- * Check if running on Linux
- */
-export function isLinux(): boolean {
-  if (typeof process !== 'undefined' && process.platform) {
-    return process.platform === 'linux';
-  }
-  const deno = (globalThis as unknown as { Deno?: { build?: { os?: string } } }).Deno;
-  return deno?.build?.os === 'linux';
-}
-
 /**
  * Check if a path is absolute
  */
@@ -676,13 +572,6 @@ export function isAbsolutePath(path: string): boolean {
   return /^[A-Za-z]:[\\/]/.test(path);
 }
 
-/**
- * Get the path separator for the current platform
- */
-export function getPathSeparator(): string {
-  return isWindows() ? '\\' : '/';
-}
-
 /**
  * Get the default Python executable name for the current platform
  */

package/src/version.ts

@@ -9,4 +9,4 @@
  * Regenerate with: node scripts/generate-version.mjs
  */
 
-export const VERSION: string = "0.8.0";
+export const VERSION: string = "0.9.0";