tywrap 0.1.0

package/src/cli.ts

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import yargs, { type Argv, type ArgumentsCamelCase } from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import { resolveConfig, type ResolveConfigOptions } from './config/index.js';
+import type { RuntimeStrategy, TywrapOptions } from './types/index.js';
+import { getComponentLogger } from './utils/logger.js';
+
+const log = getComponentLogger('CLI');
+
+const DEFAULT_CONFIG_FILES = [
+  'tywrap.config.ts',
+  'tywrap.config.mts',
+  'tywrap.config.js',
+  'tywrap.config.mjs',
+  'tywrap.config.cjs',
+  'tywrap.config.json',
+];
+
+function resolveConfigPath(explicitPath?: string): { configPath?: string; explicit: boolean } {
+  const cwd = process.cwd();
+  if (explicitPath) {
+    const resolved = resolve(cwd, explicitPath);
+    return { configPath: resolved, explicit: true };
+  }
+  for (const name of DEFAULT_CONFIG_FILES) {
+    const candidate = resolve(cwd, name);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- config discovery uses user-controlled paths
+    if (existsSync(candidate)) {
+      return { configPath: candidate, explicit: false };
+    }
+  }
+  return { configPath: undefined, explicit: false };
+}
+
+function parseModules(modulesList?: string): string[] {
+  if (!modulesList) {
+    return [];
+  }
+  return modulesList
+    .split(',')
+    .map(m => m.trim())
+    .filter(Boolean);
+}
+
+function buildModulesConfig(
+  modules: string[],
+  runtime: RuntimeStrategy
+): TywrapOptions['pythonModules'] {
+  return Object.fromEntries(modules.map(name => [name, { runtime, typeHints: 'strict' }]));
+}
+
+function renderConfigTemplate(options: {
+  format: 'ts' | 'json';
+  modules: string[];
+  runtime: RuntimeStrategy;
+  outputDir: string;
+}): string {
+  const modules = options.modules.length > 0 ? options.modules : ['math'];
+  if (options.format === 'json') {
+    const config = {
+      pythonModules: buildModulesConfig(modules, options.runtime),
+      output: { dir: options.outputDir, format: 'esm', declaration: false, sourceMap: false },
+      runtime: { node: { pythonPath: 'python3' } },
+      types: { presets: ['stdlib'] },
+    };
+    return `${JSON.stringify(config, null, 2)}\n`;
+  }
+
+  const moduleLines = modules
+    .map(
+      name => `    ${JSON.stringify(name)}: { runtime: '${options.runtime}', typeHints: 'strict' },`
+    )
+    .join('\n');
+  return `import { defineConfig } from 'tywrap';
+
+export default defineConfig({
+  pythonModules: {
+${moduleLines}
+  },
+  output: {
+    dir: '${options.outputDir}',
+    format: 'esm',
+    declaration: false,
+    sourceMap: false
+  },
+  runtime: {
+    node: {
+      pythonPath: 'python3'
+    }
+  },
+  types: {
+    presets: ['stdlib']
+  }
+});
+`;
+}
+
+async function main(): Promise<void> {
+  await yargs(hideBin(process.argv))
+    .scriptName('tywrap')
+    .command(
+      'generate',
+      'Generate TypeScript wrappers',
+      (y: Argv) =>
+        y
+          .option('config', {
+            alias: 'c',
+            type: 'string',
+            describe: 'Path to config file (defaults to tywrap.config.* if present)',
+          })
+          .option('modules', {
+            type: 'string',
+            describe: 'Comma-separated list of Python modules to wrap',
+          })
+          .option('runtime', {
+            type: 'string',
+            choices: ['node', 'pyodide', 'http', 'auto'],
+            default: 'node',
+            describe: 'Runtime to use when --modules is provided',
+          })
+          .option('python', {
+            type: 'string',
+            describe: 'Path to Python executable',
+          })
+          .option('output-dir', {
+            type: 'string',
+            describe: 'Directory for generated wrappers',
+          })
+          .option('format', {
+            type: 'string',
+            choices: ['esm', 'cjs', 'both'],
+            describe: 'Output module format',
+          })
+          .option('declaration', {
+            type: 'boolean',
+            describe: 'Emit TypeScript declaration files',
+          })
+          .option('source-map', {
+            type: 'boolean',
+            describe: 'Emit source maps for generated files',
+          })
+          .option('use-cache', {
+            alias: 'cache',
+            type: 'boolean',
+            describe: 'Enable on-disk caching (use --no-cache to disable)',
+          })
+          .option('debug', {
+            type: 'boolean',
+            describe: 'Enable debug logging',
+          })
+          .option('fail-on-warn', {
+            type: 'boolean',
+            default: false,
+            describe: 'Exit with code 2 if generation emits warnings',
+          })
+          .strict(),
+      async (
+        argv: ArgumentsCamelCase<{
+          config?: string;
+          modules?: string;
+          runtime: RuntimeStrategy;
+          python?: string;
+          outputDir?: string;
+          format?: 'esm' | 'cjs' | 'both';
+          declaration?: boolean;
+          sourceMap?: boolean;
+          useCache?: boolean;
+          debug?: boolean;
+          failOnWarn: boolean;
+        }>
+      ) => {
+        const { configPath, explicit } = resolveConfigPath(argv.config);
+        const modules = parseModules(argv.modules);
+
+        const overrides: NonNullable<ResolveConfigOptions['overrides']> = {};
+        if (modules.length > 0) {
+          overrides.pythonModules = buildModulesConfig(modules, argv.runtime);
+        }
+
+        if (
+          argv.outputDir ||
+          argv.format ||
+          typeof argv.declaration === 'boolean' ||
+          typeof argv.sourceMap === 'boolean'
+        ) {
+          overrides.output = {
+            ...(argv.outputDir ? { dir: argv.outputDir } : {}),
+            ...(argv.format ? { format: argv.format } : {}),
+            ...(typeof argv.declaration === 'boolean' ? { declaration: argv.declaration } : {}),
+            ...(typeof argv.sourceMap === 'boolean' ? { sourceMap: argv.sourceMap } : {}),
+          };
+        }
+
+        if (typeof argv.useCache === 'boolean') {
+          overrides.performance = {
+            caching: argv.useCache,
+          };
+        }
+
+        if (argv.python) {
+          overrides.runtime = {
+            node: { pythonPath: argv.python },
+          };
+        }
+
+        if (typeof argv.debug === 'boolean') {
+          overrides.debug = argv.debug;
+        }
+
+        if (!configPath && modules.length === 0) {
+          log.error('No config file found and no modules provided. Create a config with `tywrap init` or pass --modules.');
+          process.exit(1);
+        }
+
+        const { generate } = await import('./tywrap.js');
+
+        try {
+          const options = await resolveConfig({
+            configFile: configPath,
+            overrides,
+            requireConfig: explicit,
+          });
+
+          if (!options.pythonModules || Object.keys(options.pythonModules).length === 0) {
+            log.error('No pythonModules configured. Use --modules or update your config.');
+            process.exit(1);
+          }
+
+          const res = await generate(options);
+          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.`);
+            process.exit(2);
+          }
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          log.error('Generation failed', { error: message });
+          process.exit(1);
+        }
+      }
+    )
+    .command(
+      'init',
+      'Create a starter tywrap.config file',
+      (y: Argv) =>
+        y
+          .option('config', {
+            alias: 'c',
+            type: 'string',
+            describe: 'Path for the new config file',
+          })
+          .option('format', {
+            type: 'string',
+            choices: ['ts', 'json'],
+            default: 'ts',
+            describe: 'Config file format',
+          })
+          .option('modules', {
+            type: 'string',
+            describe: 'Comma-separated list of Python modules to wrap',
+          })
+          .option('runtime', {
+            type: 'string',
+            choices: ['node', 'pyodide', 'http', 'auto'],
+            default: 'node',
+            describe: 'Runtime for generated module entries',
+          })
+          .option('output-dir', {
+            type: 'string',
+            default: './generated',
+            describe: 'Output directory for generated wrappers',
+          })
+          .option('force', {
+            type: 'boolean',
+            default: false,
+            describe: 'Overwrite existing config file',
+          })
+          .strict(),
+      async (
+        argv: ArgumentsCamelCase<{
+          config?: string;
+          format: 'ts' | 'json';
+          modules?: string;
+          runtime: RuntimeStrategy;
+          outputDir: string;
+          force: boolean;
+        }>
+      ) => {
+        const modules = parseModules(argv.modules);
+        const defaultName = argv.format === 'json' ? 'tywrap.config.json' : 'tywrap.config.ts';
+        const targetPath = resolve(process.cwd(), argv.config ?? defaultName);
+
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- config path is user-controlled
+        if (!argv.force && existsSync(targetPath)) {
+          log.error('Config file already exists. Use --force to overwrite.', { path: targetPath });
+          process.exit(1);
+        }
+
+        const content = renderConfigTemplate({
+          format: argv.format,
+          modules,
+          runtime: argv.runtime,
+          outputDir: argv.outputDir,
+        });
+
+        try {
+          // 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`);
+        } catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err);
+          log.error('Failed to write config', { error: message });
+          process.exit(1);
+        }
+      }
+    )
+    .demandCommand(1, 'Please specify a command')
+    .strict()
+    .help()
+    .version()
+    .parse();
+}
+
+main().catch(err => {
+  log.error('Unexpected error', { error: err instanceof Error ? err.message : String(err) });
+  process.exit(1);
+});

package/src/config/index.ts

@@ -0,0 +1,289 @@
+/**
+ * Configuration system
+ *
+ * Loads configuration from defaults, optional config file and CLI overrides
+ * with basic validation of known options.
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, extname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type {
+  TywrapOptions,
+  OutputConfig,
+  RuntimeConfig,
+  PerformanceConfig,
+  DevelopmentConfig,
+} from '../types/index.js';
+import { getDefaultPythonPath } from '../utils/python.js';
+
+/**
+ * Public configuration type. Currently identical to {@link TywrapOptions}.
+ */
+export type TywrapConfig = TywrapOptions;
+
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends Array<infer U>
+    ? Array<U>
+    : T[K] extends object
+      ? DeepPartial<T[K]>
+      : T[K];
+};
+
+/**
+ * Default configuration values used when options are not supplied.
+ */
+const DEFAULT_CONFIG: TywrapConfig = {
+  pythonModules: {},
+  output: { dir: './generated', format: 'esm', declaration: false, sourceMap: false },
+  runtime: { node: { pythonPath: getDefaultPythonPath(), timeout: 30000 } },
+  performance: { caching: false, batching: false, compression: 'none' },
+  development: { hotReload: false, sourceMap: false, validation: 'none' },
+  types: { presets: [] },
+  debug: false,
+};
+
+/**
+ * Recursively merge two configuration objects. Arrays are overwritten by
+ * overrides instead of concatenated.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function ensureConfigObject(value: unknown, configFile: string): Partial<TywrapOptions> {
+  if (!isPlainObject(value)) {
+    throw new Error(`Configuration file must export an object: ${configFile}`);
+  }
+  return value as Partial<TywrapOptions>;
+}
+
+function merge<T>(base: T, override: DeepPartial<T>): T {
+  const result = new Map<string, unknown>(Object.entries(base as Record<string, unknown>));
+  for (const [key, val] of Object.entries(override)) {
+    if (val === undefined) {
+      continue;
+    }
+    const current = result.get(key);
+    if (isPlainObject(val) && isPlainObject(current)) {
+      result.set(key, merge(current, val));
+    } else {
+      result.set(key, val);
+    }
+  }
+  return Object.fromEntries(result) as T;
+}
+
+function safeExists(path: string): boolean {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename -- config path is user-controlled and resolved
+  return existsSync(path);
+}
+
+/**
+ * Validate configuration values and throw user-friendly errors when invalid.
+ */
+function validateConfig(config: TywrapConfig): void {
+  const allowedTopLevel = new Set([
+    'pythonModules',
+    'output',
+    'runtime',
+    'performance',
+    'development',
+    'types',
+    'debug',
+  ]);
+  for (const key of Object.keys(config)) {
+    if (!allowedTopLevel.has(key)) {
+      throw new Error(`Unknown configuration option \"${key}\"`);
+    }
+  }
+
+  const out: OutputConfig = config.output;
+  if (typeof out.dir !== 'string') {
+    throw new Error('output.dir must be a string');
+  }
+  if (!['esm', 'cjs', 'both'].includes(out.format)) {
+    throw new Error('output.format must be one of "esm", "cjs" or "both"');
+  }
+  if (typeof out.declaration !== 'boolean' || typeof out.sourceMap !== 'boolean') {
+    throw new Error('output.declaration and output.sourceMap must be boolean');
+  }
+
+  const runtime: RuntimeConfig = config.runtime;
+  if (runtime.node) {
+    if (runtime.node.pythonPath !== undefined && typeof runtime.node.pythonPath !== 'string') {
+      throw new Error('runtime.node.pythonPath must be a string');
+    }
+    if (runtime.node.timeout !== undefined) {
+      if (typeof runtime.node.timeout !== 'number' || runtime.node.timeout < 0) {
+        throw new Error('runtime.node.timeout must be a non-negative number');
+      }
+    }
+  }
+
+  const perf: PerformanceConfig = config.performance;
+  if (typeof perf.caching !== 'boolean') {
+    throw new Error('performance.caching must be a boolean');
+  }
+  if (typeof perf.batching !== 'boolean') {
+    throw new Error('performance.batching must be a boolean');
+  }
+  const validCompression = ['auto', 'gzip', 'brotli', 'none'];
+  if (!validCompression.includes(perf.compression)) {
+    throw new Error(`performance.compression must be one of ${validCompression.join(', ')}`);
+  }
+
+  const dev: DevelopmentConfig = config.development;
+  if (typeof dev.hotReload !== 'boolean') {
+    throw new Error('development.hotReload must be a boolean');
+  }
+  if (typeof dev.sourceMap !== 'boolean') {
+    throw new Error('development.sourceMap must be a boolean');
+  }
+  const validValidation = ['runtime', 'compile', 'both', 'none'];
+  if (!validValidation.includes(dev.validation)) {
+    throw new Error(`development.validation must be one of ${validValidation.join(', ')}`);
+  }
+
+  if (config.types) {
+    const presets = config.types.presets;
+    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');
+      }
+      for (const preset of presets) {
+        if (!validPresets.has(preset)) {
+          throw new Error(
+            `types.presets contains invalid value "${preset}". Allowed: ${Array.from(validPresets).join(', ')}`
+          );
+        }
+      }
+    }
+  }
+
+  if (typeof config.debug !== 'boolean') {
+    throw new Error('debug must be a boolean');
+  }
+}
+
+/**
+ * Create a configuration object by merging defaults with overrides.
+ *
+ * @param overrides CLI or programmatic overrides
+ */
+export function createConfig(overrides: DeepPartial<TywrapOptions> = {}): TywrapConfig {
+  const merged = merge(DEFAULT_CONFIG, overrides);
+  validateConfig(merged);
+  return merged;
+}
+
+export interface ResolveConfigOptions {
+  configFile?: string;
+  overrides?: DeepPartial<TywrapOptions>;
+  cwd?: string;
+  requireConfig?: boolean;
+}
+
+/**
+ * Resolve configuration by loading a config file (JSON/JS/TS) and merging
+ * defaults with any overrides.
+ */
+export async function resolveConfig(options: ResolveConfigOptions = {}): Promise<TywrapConfig> {
+  const cwd = options.cwd ?? process.cwd();
+  const overrides = options.overrides ?? {};
+  const configFile = options.configFile ? resolve(cwd, options.configFile) : undefined;
+  let fileConfig: DeepPartial<TywrapOptions> = {};
+
+  if (configFile) {
+    if (!safeExists(configFile)) {
+      if (options.requireConfig) {
+        throw new Error(`Configuration file not found: ${configFile}`);
+      }
+    } else {
+      fileConfig = await loadConfigFile(configFile);
+    }
+  }
+
+  const merged = merge(merge(DEFAULT_CONFIG, fileConfig), overrides);
+  validateConfig(merged);
+  return merged;
+}
+
+/**
+ * Load a tywrap config file. Supports JSON, JS/CJS/ESM, and TS files.
+ */
+export async function loadConfigFile(configFile: string): Promise<Partial<TywrapOptions>> {
+  const ext = extname(configFile).toLowerCase();
+  const resolved = resolve(configFile);
+
+  if (!safeExists(resolved)) {
+    throw new Error(`Configuration file not found: ${resolved}`);
+  }
+
+  if (ext === '.json') {
+    const txt = await safeReadFileAsync(resolved);
+    try {
+      const parsed = JSON.parse(txt) as unknown;
+      return ensureConfigObject(parsed, resolved);
+    } catch (err) {
+      throw new Error(`Failed to parse JSON config ${resolved}: ${(err as Error).message}`);
+    }
+  }
+
+  if (ext === '.cjs') {
+    const require = createRequire(import.meta.url);
+    // eslint-disable-next-line security/detect-non-literal-require -- config path is user-controlled and resolved
+    const mod = require(resolved) as Record<string, unknown>;
+    const loaded = mod.default ?? mod;
+    return ensureConfigObject(loaded ?? {}, resolved);
+  }
+
+  if (ext === '.js' || ext === '.mjs') {
+    const mod = (await import(pathToFileURL(resolved).href)) as Record<string, unknown>;
+    const loaded = mod.default ?? mod;
+    return ensureConfigObject(loaded ?? {}, resolved);
+  }
+
+  if (ext === '.ts' || ext === '.mts' || ext === '.cts') {
+    const ts = await import('typescript');
+    const source = await safeReadFileAsync(resolved);
+    const output = ts.transpileModule(source, {
+      compilerOptions: {
+        module: ts.ModuleKind.CommonJS,
+        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);
+  }
+
+  throw new Error(`Unsupported configuration file extension: ${ext}`);
+}
+
+async function safeReadFileAsync(path: string): Promise<string> {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename -- config path is user-controlled and resolved
+  return readFile(path, 'utf-8');
+}
+
+/**
+ * Type helper for authoring tywrap configs with full type inference.
+ */
+export function defineConfig(config: TywrapConfig): TywrapConfig {
+  return config;
+}