tywrap 0.1.0 → 0.1.2

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs';
-import { writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import yargs, { type Argv, type ArgumentsCamelCase } from 'yargs';
 import { hideBin } from 'yargs/helpers';
@@ -99,6 +99,46 @@ ${moduleLines}
 `;
 }
 
+async function addRecommendedScriptsToPackageJson(cwd: string): Promise<void> {
+  const packageJsonPath = resolve(cwd, 'package.json');
+  // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is derived from cwd
+  if (!existsSync(packageJsonPath)) {
+    return;
+  }
+  try {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is derived from cwd
+    const raw = await readFile(packageJsonPath, 'utf-8');
+    const pkg = JSON.parse(raw) as Record<string, unknown>;
+    const scripts =
+      typeof pkg.scripts === 'object' && pkg.scripts !== null && !Array.isArray(pkg.scripts)
+        ? (pkg.scripts as Record<string, unknown>)
+        : {};
+    const nextScripts: Record<string, unknown> = { ...scripts };
+    let changed = false;
+
+    if (nextScripts['tywrap:generate'] === undefined) {
+      nextScripts['tywrap:generate'] = 'tywrap generate';
+      changed = true;
+    }
+    if (nextScripts['tywrap:check'] === undefined) {
+      nextScripts['tywrap:check'] = 'tywrap generate --check';
+      changed = true;
+    }
+
+    if (!changed) {
+      return;
+    }
+
+    pkg.scripts = nextScripts;
+    const out = `${JSON.stringify(pkg, null, 2)}\n`;
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is derived from cwd
+    await writeFile(packageJsonPath, out, 'utf-8');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.warn('Failed to update package.json scripts', { error: message });
+  }
+}
+
 async function main(): Promise<void> {
   await yargs(hideBin(process.argv))
     .scriptName('tywrap')
@@ -157,6 +197,11 @@ async function main(): Promise<void> {
             default: false,
             describe: 'Exit with code 2 if generation emits warnings',
           })
+          .option('check', {
+            type: 'boolean',
+            default: false,
+            describe: 'Check whether generated wrappers are up to date without writing files',
+          })
           .strict(),
       async (
         argv: ArgumentsCamelCase<{
@@ -171,6 +216,7 @@ async function main(): Promise<void> {
           useCache?: boolean;
           debug?: boolean;
           failOnWarn: boolean;
+          check: boolean;
         }>
       ) => {
         const { configPath, explicit } = resolveConfigPath(argv.config);
@@ -212,7 +258,9 @@ async function main(): Promise<void> {
         }
 
         if (!configPath && modules.length === 0) {
-          log.error('No config file found and no modules provided. Create a config with `tywrap init` or pass --modules.');
+          log.error(
+            'No config file found and no modules provided. Create a config with `tywrap init` or pass --modules.'
+          );
           process.exit(1);
         }
 
@@ -230,10 +278,28 @@ async function main(): Promise<void> {
             process.exit(1);
           }
 
-          const res = await generate(options);
-          process.stdout.write(`Generated: ${res.written.join(', ')}\n`);
+          const res = await generate(options, { check: argv.check });
+          if (argv.check) {
+            const outOfDate = res.outOfDate ?? [];
+            if (outOfDate.length === 0) {
+              process.stdout.write('Generated wrappers are up to date.\n');
+            } else {
+              process.stderr.write('Generated wrappers are out of date:\n');
+              for (const file of outOfDate) {
+                process.stderr.write(`- ${file}\n`);
+              }
+              process.stderr.write('\nRun `tywrap generate` to update.\n');
+              if (!(argv.failOnWarn && res.warnings.length > 0)) {
+                process.exit(3);
+              }
+            }
+          } else {
+            process.stdout.write(`Generated: ${res.written.join(', ')}\n`);
+          }
           if (argv.failOnWarn && res.warnings.length > 0) {
-            log.error(`Warnings encountered (count ${res.warnings.length}). Failing due to --fail-on-warn.`);
+            log.error(
+              `Warnings encountered (count ${res.warnings.length}). Failing due to --fail-on-warn.`
+            );
             process.exit(2);
           }
         } catch (err: unknown) {
@@ -279,6 +345,12 @@ async function main(): Promise<void> {
             default: false,
             describe: 'Overwrite existing config file',
           })
+          .option('scripts', {
+            type: 'boolean',
+            default: true,
+            describe:
+              'Add recommended tywrap scripts to package.json (use --no-scripts to disable)',
+          })
           .strict(),
       async (
         argv: ArgumentsCamelCase<{
@@ -288,6 +360,7 @@ async function main(): Promise<void> {
           runtime: RuntimeStrategy;
           outputDir: string;
           force: boolean;
+          scripts: boolean;
         }>
       ) => {
         const modules = parseModules(argv.modules);
@@ -311,6 +384,9 @@ async function main(): Promise<void> {
           // eslint-disable-next-line security/detect-non-literal-fs-filename -- config path is user-controlled
           await writeFile(targetPath, content, 'utf-8');
           process.stdout.write(`Created ${targetPath}\n`);
+          if (argv.scripts) {
+            await addRecommendedScriptsToPackageJson(process.cwd());
+          }
         } catch (err: unknown) {
           const message = err instanceof Error ? err.message : String(err);
           log.error('Failed to write config', { error: message });

package/src/config/index.ts

@@ -5,8 +5,9 @@
  * with basic validation of known options.
  */
 
+import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { readFile, rm, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -149,7 +150,15 @@ function validateConfig(config: TywrapConfig): void {
 
   if (config.types) {
     const presets = config.types.presets;
-    const validPresets = new Set(['numpy', 'pandas', 'pydantic', 'stdlib', 'scipy', 'torch', 'sklearn']);
+    const validPresets = new Set([
+      'numpy',
+      'pandas',
+      'pydantic',
+      'stdlib',
+      'scipy',
+      'torch',
+      'sklearn',
+    ]);
     if (presets !== undefined) {
       if (!Array.isArray(presets) || presets.some(p => typeof p !== 'string')) {
         throw new Error('types.presets must be an array of strings');
@@ -250,27 +259,69 @@ export async function loadConfigFile(configFile: string): Promise<Partial<Tywrap
   if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
     const ts = await import('typescript');
     const source = await safeReadFileAsync(resolved);
+    // Why: many configs want to `import { defineConfig } from 'tywrap'`. The tywrap package is ESM,
+    // so evaluating a transpiled CommonJS config would try `require('tywrap')` and fail. Treat
+    // `.ts`/`.mts` configs as ESM, and only treat `.cts` as CommonJS to match Node conventions.
+    const emitCommonJs = ext === '.cts';
     const output = ts.transpileModule(source, {
       compilerOptions: {
-        module: ts.ModuleKind.CommonJS,
+        module: emitCommonJs ? ts.ModuleKind.CommonJS : ts.ModuleKind.ES2020,
         target: ts.ScriptTarget.ES2020,
         esModuleInterop: true,
       },
       fileName: resolved,
     });
-    const require = createRequire(import.meta.url);
-    const nodeModule = require('module') as typeof import('module');
-    const moduleCtor = nodeModule.Module as unknown as typeof import('module').Module & {
-      _nodeModulePaths: (path: string) => string[];
-    };
-    const mod = new moduleCtor(resolved) as import('module').Module & {
-      _compile: (code: string, filename: string) => void;
-    };
-    mod.filename = resolved;
-    mod.paths = moduleCtor._nodeModulePaths(dirname(resolved));
-    mod._compile(output.outputText, resolved);
-    const loaded = (mod.exports as Record<string, unknown>).default ?? mod.exports;
-    return ensureConfigObject(loaded ?? {}, resolved);
+
+    if (emitCommonJs) {
+      // Why: `.cts` is explicitly CommonJS. We evaluate the transpiled output in-memory using
+      // Node's Module internals (`Module._compile` / `_nodeModulePaths`) to avoid writing an extra
+      // temp file. These are private Node APIs, so we keep this tooling path scoped and rely on
+      // supported Node versions (see package.json engines).
+      const require = createRequire(import.meta.url);
+      const nodeModule = require('module') as typeof import('module');
+      const moduleCtor = nodeModule.Module as unknown as typeof import('module').Module & {
+        _nodeModulePaths?: (path: string) => string[];
+      };
+      if (typeof moduleCtor !== 'function') {
+        throw new Error(
+          '[tywrap] Unable to evaluate .cts config in-memory (emitCommonJs=true): missing Node Module constructor'
+        );
+      }
+      const nodeModulePaths = moduleCtor._nodeModulePaths;
+      if (typeof nodeModulePaths !== 'function') {
+        throw new Error(
+          '[tywrap] Unable to evaluate .cts config in-memory (emitCommonJs=true): missing Node private API Module._nodeModulePaths'
+        );
+      }
+      const mod = new moduleCtor(resolved) as import('module').Module & {
+        _compile?: (code: string, filename: string) => void;
+      };
+      const compile = mod._compile;
+      if (typeof compile !== 'function') {
+        throw new Error(
+          '[tywrap] Unable to evaluate .cts config in-memory (emitCommonJs=true): missing Node private API Module._compile'
+        );
+      }
+      mod.filename = resolved;
+      mod.paths = nodeModulePaths(dirname(resolved));
+      compile.call(mod, output.outputText, resolved);
+      const loaded = (mod.exports as Record<string, unknown>).default ?? mod.exports;
+      return ensureConfigObject(loaded ?? {}, resolved);
+    }
+
+    // Why: Node can't import ESM from a string without a custom loader. We write the transpiled
+    // output to a temporary `.mjs` file next to the source config so relative imports and Node
+    // resolution behave naturally, then clean it up immediately after loading.
+    const tmpPath = resolve(dirname(resolved), `.tywrap.config.${randomUUID()}.mjs`);
+    try {
+      // eslint-disable-next-line security/detect-non-literal-fs-filename -- temp path is derived from config location
+      await writeFile(tmpPath, output.outputText, 'utf-8');
+      const mod = (await import(pathToFileURL(tmpPath).href)) as Record<string, unknown>;
+      const loaded = mod.default ?? mod;
+      return ensureConfigObject(loaded ?? {}, resolved);
+    } finally {
+      await rm(tmpPath, { force: true });
+    }
   }
 
   throw new Error(`Unsupported configuration file extension: ${ext}`);

package/src/core/generator.ts

@@ -141,12 +141,16 @@ export class CodeGenerator {
     const fname = this.escapeIdentifier(func.name);
     const moduleId = moduleName ?? '__main__';
 
-    // Overloads: generate trailing optional parameter drop variants (exclude *args/**kwargs)
+    // Overloads: generate trailing optional parameter drop variants (exclude *args/**kwargs).
+    // Why: Python APIs frequently have many optional tail params. TypeScript callers expect
+    // `fn(a)`, `fn(a, b)`, ... all to typecheck. We emit a family of overloads that progressively
+    // "drop" optional tail args, but also include the full positional signature (<= length) so a
+    // call that supplies all args still matches an overload.
     const positional = filteredParams.filter(p => !p.varArgs && !p.kwArgs);
     const firstOptionalIndex = positional.findIndex(p => p.optional);
     const overloads: string[] = [];
     if (firstOptionalIndex >= 0) {
-      for (let i = firstOptionalIndex; i < positional.length; i++) {
+      for (let i = firstOptionalIndex; i <= positional.length; i++) {
         const head = positional.slice(0, i);
         const rest = filteredParams.filter(p => p.varArgs || p.kwArgs);
         const sigParams = [...head, ...rest].map(renderParam).join(', ');

package/src/core/mapper.ts

@@ -267,7 +267,8 @@ export class TypeMapper {
     }
 
     // Forward references and user types
-    return { kind: 'custom', name: type.name, module: type.module };
+    const normalized = this.normalizeCustomType(type);
+    return { kind: 'custom', name: normalized.name, module: normalized.module };
   }
 
   mapCallableType(type: {
@@ -348,15 +349,26 @@ export class TypeMapper {
     module?: string;
     rawName: string;
   } {
+    // Why: the Python IR sometimes represents qualified names like "pandas.DataFrame" as a single
+    // `name` string (with dots) instead of splitting into { module, name }. Dots are not valid in
+    // TypeScript identifiers, and we want stable test expectations, so normalize to a leaf `name`
+    // plus a `module` path when possible.
     const rawName = type.name;
     if (type.module) {
       return { name: type.name, module: type.module, rawName };
     }
     if (rawName.includes('.')) {
-      const parts = rawName.split('.');
+      const parts = rawName.split('.').filter(part => part.length > 0);
+      if (parts.length === 0) {
+        return { name: rawName, module: undefined, rawName };
+      }
+      const name = parts[parts.length - 1];
+      if (!name) {
+        return { name: rawName, module: undefined, rawName };
+      }
       return {
-        name: parts[parts.length - 1] ?? rawName,
-        module: parts.slice(0, -1).join('.'),
+        name,
+        module: parts.length > 1 ? parts.slice(0, -1).join('.') : undefined,
         rawName,
       };
     }
@@ -441,9 +453,7 @@ export class TypeMapper {
       const allowModule = !moduleName || moduleName.startsWith('scipy');
       if (allowModule) {
         const baseProps = [prop('shape', numberArray), prop('dtype', stringType, true)];
-        const buildSparse = (
-          format: 'csr' | 'csc' | 'coo'
-        ): TSObjectType => ({
+        const buildSparse = (format: 'csr' | 'csc' | 'coo'): TSObjectType => ({
           kind: 'object',
           properties: [
             prop('format', { kind: 'literal', value: format }),
@@ -464,7 +474,10 @@ export class TypeMapper {
           return buildSparse('coo');
         }
         if (name === 'spmatrix') {
-          return { kind: 'union', types: [buildSparse('csr'), buildSparse('csc'), buildSparse('coo')] };
+          return {
+            kind: 'union',
+            types: [buildSparse('csr'), buildSparse('csc'), buildSparse('coo')],
+          };
         }
       }
     }

package/src/index.ts

@@ -69,12 +69,13 @@ export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runti
 export {
   decodeValue,
   decodeValueAsync,
+  autoRegisterArrowDecoder,
   registerArrowDecoder,
   clearArrowDecoder,
 } from './utils/codec.js';
 
 // Version info
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.2';
 
 /**
  * Quick setup function for getting started