tywrap 0.2.1 → 0.4.0

package/src/config/index.ts

@@ -7,7 +7,8 @@
 
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { readFile, rm, writeFile, mkdtemp, symlink } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -16,15 +17,9 @@ import type {
   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>
@@ -33,19 +28,35 @@ type DeepPartial<T> = {
       : T[K];
 };
 
+/**
+ * User-authored configuration shape accepted by defineConfig() and config files.
+ */
+export type TywrapConfig = DeepPartial<TywrapOptions>;
+
+/**
+ * Fully resolved configuration shape returned by createConfig() and resolveConfig().
+ */
+export type ResolvedTywrapConfig = TywrapOptions;
+
 /**
  * Default configuration values used when options are not supplied.
  */
-const DEFAULT_CONFIG: TywrapConfig = {
+const DEFAULT_CONFIG: ResolvedTywrapConfig = {
   pythonModules: {},
+  pythonImportPath: [],
   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,
 };
 
+const LEGACY_DEVELOPMENT_MESSAGE =
+  'Legacy config field "development" is no longer supported. Use createBridgeReloader() or startNodeWatchSession() from "tywrap/dev" instead.';
+
+const LEGACY_MODULE_WATCH_MESSAGE =
+  'Legacy config field "pythonModules.<module>.watch" is no longer supported. Use startNodeWatchSession() from "tywrap/dev" instead.';
+
 /**
  * Recursively merge two configuration objects. Arrays are overwritten by
  * overrides instead of concatenated.
@@ -82,16 +93,38 @@ function safeExists(path: string): boolean {
   return existsSync(path);
 }
 
+function detectLegacyFields(config: TywrapConfig): void {
+  const rawConfig = config as unknown as Record<string, unknown>;
+  if (Object.prototype.hasOwnProperty.call(rawConfig, 'development')) {
+    throw new Error(LEGACY_DEVELOPMENT_MESSAGE);
+  }
+
+  const pythonModules = rawConfig.pythonModules;
+  if (!isPlainObject(pythonModules)) {
+    return;
+  }
+
+  for (const moduleConfig of Object.values(pythonModules)) {
+    if (
+      isPlainObject(moduleConfig) &&
+      Object.prototype.hasOwnProperty.call(moduleConfig, 'watch')
+    ) {
+      throw new Error(LEGACY_MODULE_WATCH_MESSAGE);
+    }
+  }
+}
+
 /**
  * Validate configuration values and throw user-friendly errors when invalid.
  */
-function validateConfig(config: TywrapConfig): void {
+function validateConfig(config: ResolvedTywrapConfig): void {
+  detectLegacyFields(config);
   const allowedTopLevel = new Set([
     'pythonModules',
+    'pythonImportPath',
     'output',
     'runtime',
     'performance',
-    'development',
     'types',
     'debug',
   ]);
@@ -105,6 +138,15 @@ function validateConfig(config: TywrapConfig): void {
   if (typeof out.dir !== 'string') {
     throw new Error('output.dir must be a string');
   }
+
+  if (config.pythonImportPath !== undefined) {
+    if (
+      !Array.isArray(config.pythonImportPath) ||
+      config.pythonImportPath.some(p => typeof p !== 'string')
+    ) {
+      throw new Error('pythonImportPath must be an array of strings');
+    }
+  }
   if (!['esm', 'cjs', 'both'].includes(out.format)) {
     throw new Error('output.format must be one of "esm", "cjs" or "both"');
   }
@@ -136,18 +178,6 @@ function validateConfig(config: TywrapConfig): void {
     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([
@@ -183,7 +213,7 @@ function validateConfig(config: TywrapConfig): void {
  *
  * @param overrides CLI or programmatic overrides
  */
-export function createConfig(overrides: DeepPartial<TywrapOptions> = {}): TywrapConfig {
+export function createConfig(overrides: DeepPartial<TywrapOptions> = {}): ResolvedTywrapConfig {
   const merged = merge(DEFAULT_CONFIG, overrides);
   validateConfig(merged);
   return merged;
@@ -200,7 +230,9 @@ export interface ResolveConfigOptions {
  * Resolve configuration by loading a config file (JSON/JS/TS) and merging
  * defaults with any overrides.
  */
-export async function resolveConfig(options: ResolveConfigOptions = {}): Promise<TywrapConfig> {
+export async function resolveConfig(
+  options: ResolveConfigOptions = {}
+): Promise<ResolvedTywrapConfig> {
   const cwd = options.cwd ?? process.cwd();
   const overrides = options.overrides ?? {};
   const configFile = options.configFile ? resolve(cwd, options.configFile) : undefined;
@@ -272,6 +304,20 @@ export async function loadConfigFile(configFile: string): Promise<Partial<Tywrap
       fileName: resolved,
     });
 
+    let transpiledOutput = output.outputText;
+    if (!emitCommonJs) {
+      try {
+        // Preserve support for `import { defineConfig } from 'tywrap'` when ESM config
+        // is evaluated from an OS temp directory outside the package scope.
+        const tywrapEntryHref = await import.meta.resolve('tywrap');
+        transpiledOutput = transpiledOutput
+          .replaceAll("'tywrap'", `'${tywrapEntryHref}'`)
+          .replaceAll('\"tywrap\"', `\"${tywrapEntryHref}\"`);
+      } catch {
+        // Best-effort: leave source as-is when tywrap cannot be 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
@@ -309,18 +355,31 @@ export async function loadConfigFile(configFile: string): Promise<Partial<Tywrap
       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`);
+    // Why: Node can't import ESM from a string without a custom loader. We write transpiled
+    // output to a temporary `.mjs` file under the OS temp directory (not next to user config),
+    // then clean up both file and temporary directory after loading.
+    const tempDir = await mkdtemp(resolve(tmpdir(), 'tywrap-config-'));
+    const tmpPath = resolve(tempDir, `.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 localNodeModules = resolve(process.cwd(), 'node_modules');
+      if (safeExists(localNodeModules)) {
+        const tempNodeModules = resolve(tempDir, 'node_modules');
+        try {
+          // eslint-disable-next-line security/detect-non-literal-fs-filename -- temp path is derived from OS temp directory
+          await symlink(localNodeModules, tempNodeModules, 'dir');
+        } catch {
+          // Best-effort only; regular resolution may still succeed without a symlink.
+        }
+      }
+
+      // eslint-disable-next-line security/detect-non-literal-fs-filename -- temp path is derived from OS temp directory
+      await writeFile(tmpPath, transpiledOutput, '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 });
+      await rm(tempDir, { recursive: true, force: true });
     }
   }
 
@@ -335,6 +394,6 @@ async function safeReadFileAsync(path: string): Promise<string> {
 /**
  * Type helper for authoring tywrap configs with full type inference.
  */
-export function defineConfig(config: TywrapConfig): TywrapConfig {
+export function defineConfig<T extends TywrapConfig>(config: T): T {
   return config;
 }

package/src/core/analyzer.ts

@@ -26,6 +26,7 @@ import { getComponentLogger } from '../utils/logger.js';
 const log = getComponentLogger('Analyzer');
 
 const UNKNOWN_TYPE: PythonType = { kind: 'custom', name: 'Any', module: 'typing' };
+const PYTHON_LANGUAGE = Python as unknown as Parameters<Parser['setLanguage']>[0];
 
 export class PyAnalyzer {
   private parser: Parser;
@@ -44,7 +45,7 @@ export class PyAnalyzer {
     }
 
     try {
-      await this.parser.setLanguage(Python);
+      await this.parser.setLanguage(PYTHON_LANGUAGE);
       this.initialized = true;
     } catch (error) {
       throw new Error(`Failed to initialize Python parser: ${error}`);
@@ -141,7 +142,7 @@ export class PyAnalyzer {
   async extractFunctions(node: SyntaxNode): Promise<PythonFunction[]> {
     const functions: PythonFunction[] = [];
 
-    const functionNodes = this.findNodesByType(node, 'function_definition');
+    const functionNodes = this.findDirectDefinitions(node, 'function_definition');
 
     for (const funcNode of functionNodes) {
       try {
@@ -161,7 +162,7 @@ export class PyAnalyzer {
   async extractClasses(node: SyntaxNode): Promise<PythonClass[]> {
     const classes: PythonClass[] = [];
 
-    const classNodes = this.findNodesByType(node, 'class_definition');
+    const classNodes = this.findDirectDefinitions(node, 'class_definition');
 
     for (const classNode of classNodes) {
       try {
@@ -238,7 +239,7 @@ export class PyAnalyzer {
     const properties: Property[] = [];
 
     if (bodyNode) {
-      const methodNodes = this.findNodesByType(bodyNode, 'function_definition');
+      const methodNodes = this.findDirectDefinitions(bodyNode, 'function_definition');
       for (const methodNode of methodNodes) {
         try {
           const method = await this.extractFunction(methodNode);
@@ -249,9 +250,18 @@ export class PyAnalyzer {
       }
 
       // Extract properties (assignments with type annotations or @property decorators)
-      const assignmentNodes = this.findNodesByType(bodyNode, 'assignment');
-      for (const assignNode of assignmentNodes) {
-        const prop = this.extractProperty(assignNode);
+      for (const stmt of bodyNode.namedChildren) {
+        // Only consider class-body statements, never descend into method bodies.
+        const assignmentNode =
+          stmt.type === 'assignment'
+            ? stmt
+            : stmt.type === 'expression_statement'
+              ? (stmt.namedChildren.find(c => c.type === 'assignment') ?? null)
+              : null;
+        if (!assignmentNode) {
+          continue;
+        }
+        const prop = this.extractProperty(assignmentNode);
         if (prop) {
           properties.push(prop);
         }
@@ -641,21 +651,45 @@ export class PyAnalyzer {
    */
   private findNodesByType(node: SyntaxNode, type: string): SyntaxNode[] {
     const results: SyntaxNode[] = [];
-
-    const traverse = (n: SyntaxNode): void => {
+    const stack: SyntaxNode[] = [node];
+    while (stack.length > 0) {
+      const n = stack.pop();
+      if (!n) {
+        break;
+      }
       if (n.type === type) {
         results.push(n);
       }
-
-      for (const child of n.children) {
-        traverse(child);
+      for (let i = n.children.length - 1; i >= 0; i--) {
+        const child = n.children[i];
+        if (child) {
+          stack.push(child);
+        }
       }
-    };
-
-    traverse(node);
+    }
     return results;
   }
 
+  private findDirectDefinitions(
+    node: SyntaxNode,
+    type: 'function_definition' | 'class_definition'
+  ): SyntaxNode[] {
+    const out: SyntaxNode[] = [];
+    for (const child of node.namedChildren) {
+      if (child.type === type) {
+        out.push(child);
+        continue;
+      }
+      if (child.type === 'decorated_definition') {
+        const def = child.namedChildren.find(c => c.type === type) ?? null;
+        if (def) {
+          out.push(def);
+        }
+      }
+    }
+    return out;
+  }
+
   private extractModuleName(path?: string): string {
     if (!path) {
       return 'unknown';
@@ -683,6 +717,8 @@ export class PyAnalyzer {
       const expr = firstChild.child(0);
       if (expr?.type === 'string') {
         let docstring = expr.text;
+        // Strip docstring prefixes like r/u/f/b and combos (rf/fr/br/...).
+        docstring = docstring.replace(/^(?:[rRuUbBfF]{1,2})(?=(\"\"\"|'''|\"|'))/, '');
         // Remove outer quotes and any remaining inner quotes
         if (docstring.startsWith('"""') && docstring.endsWith('"""')) {
           docstring = docstring.slice(3, -3);