Merge pull request #255 from bbopen/refactor/0.6.1

0.6.1: maintenance — decompose complexity hotspots, dedup dispatch, drop dead exports

Author: bbopen

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.6.1](https://github.com/bbopen/tywrap/compare/v0.6.0...v0.6.1) (2026-05-31)
+
+A maintenance release. Nothing you call changes — no API, behavior, or wire-protocol changes.
+
+Internal cleanup only: removed two dead exports, broke the eleven worst complexity hotspots into smaller helpers with their output unchanged (cache-key generation, type-hint validation, the dev watch/reload paths, the subprocess write queue, module discovery, path and interpreter resolution, and an annotation-parser helper), and factored the duplicated request/response dispatch in the codec and RPC client into one path. The static-analysis actionable-complexity count dropped from 14 to 3 — the remaining three are deferred to 0.7.0 or left as-is on purpose.
+
 ## [0.6.0](https://github.com/bbopen/tywrap/compare/v0.5.1...v0.6.0) (2026-05-31)
 
 A cleanup release. There are no new features — this is one breaking pass that renames much of the runtime vocabulary, trims the public API, and tightens a couple of defaults, so the churn happens once instead of dribbling across several releases. If you only use the high-level `tywrap()`, `generate()`, and `defineConfig()` API, most of this won't touch you. The wire protocol is unchanged, so a 0.5.x client and a 0.6.0 bridge still talk to each other.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tywrap",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Generate type-safe TypeScript wrappers for any Python library — Node.js, Deno, Bun, and browsers via Pyodide.",
   "type": "module",
   "main": "dist/index.js",

src/core/annotation-parser.ts

@@ -118,30 +118,35 @@ export function parseAnnotationToPythonType(
     return { kind: 'custom', name: n };
   };
 
+  // Extracts the leading quoted string from the body of a `Name(...)` factory call
+  // (the `inner` already stripped of the outer `Name(` and trailing `)`). Returns
+  // the unquoted name, or null when the body is not a well-formed quoted argument.
+  const extractQuotedFactoryArg = (inner: string): string | null => {
+    if (inner.length < 2) {
+      return null;
+    }
+
+    const quote = inner[0];
+    if ((quote !== "'" && quote !== '"') || inner[inner.length - 1] !== quote) {
+      return null;
+    }
+
+    const commaIndex = inner.indexOf(',');
+    const quoted = commaIndex === -1 ? inner : inner.slice(0, commaIndex).trimEnd();
+    if (quoted.length < 2 || quoted[quoted.length - 1] !== quote) {
+      return null;
+    }
+
+    return quoted.slice(1, -1);
+  };
+
   const parseTypingFactoryName = (text: string, name: string): string | null => {
     for (const prefix of modulePrefixes) {
       const start = `${prefix}${name}(`;
       if (!text.startsWith(start) || !text.endsWith(')')) {
         continue;
       }
-
-      const inner = text.slice(start.length, -1).trim();
-      if (inner.length < 2) {
-        return null;
-      }
-
-      const quote = inner[0];
-      if ((quote !== "'" && quote !== '"') || inner[inner.length - 1] !== quote) {
-        return null;
-      }
-
-      const commaIndex = inner.indexOf(',');
-      const quoted = commaIndex === -1 ? inner : inner.slice(0, commaIndex).trimEnd();
-      if (quoted.length < 2 || quoted[quoted.length - 1] !== quote) {
-        return null;
-      }
-
-      return quoted.slice(1, -1);
+      return extractQuotedFactoryArg(text.slice(start.length, -1).trim());
     }
 
     return null;

src/core/discovery.ts

@@ -122,38 +122,61 @@ export class ModuleDiscovery {
       return cached.path;
     }
 
-    // Try to resolve using Python's module finder
-    if (processUtils.isAvailable()) {
-      try {
-        const pythonPath = await this.getPythonExecutable();
-        const result = await processUtils.exec(
-          pythonPath,
-          [
-            '-c',
-            `import ${moduleName}; print(${moduleName}.__file__ if hasattr(${moduleName}, '__file__') else '${moduleName}.__path__[0]' if hasattr(${moduleName}, '__path__') else 'builtin')`,
-          ],
-          { timeoutMs: this.options.timeoutMs }
-        );
+    // Try to resolve using Python's module finder, then fall back to a
+    // filesystem search across the known Python paths.
+    return (
+      (await this.resolveViaInterpreter(moduleName)) ??
+      (await this.resolveViaSearchPaths(moduleName))
+    );
+  }
+
+  /**
+   * Resolve a module path by asking the Python interpreter for `__file__`.
+   * Caches and returns the resolved path, or `null` when the interpreter is
+   * unavailable, reports a builtin, or fails.
+   */
+  private async resolveViaInterpreter(moduleName: string): Promise<string | null> {
+    if (!processUtils.isAvailable()) {
+      return null;
+    }
 
-        if (result.code === 0 && result.stdout.trim() !== 'builtin') {
-          const modulePath = result.stdout.trim();
+    try {
+      const pythonPath = await this.getPythonExecutable();
+      const result = await processUtils.exec(
+        pythonPath,
+        [
+          '-c',
+          `import ${moduleName}; print(${moduleName}.__file__ if hasattr(${moduleName}, '__file__') else '${moduleName}.__path__[0]' if hasattr(${moduleName}, '__path__') else 'builtin')`,
+        ],
+        { timeoutMs: this.options.timeoutMs }
+      );
 
-          // Cache the result
-          this.moduleCache.set(moduleName, {
-            name: moduleName,
-            path: modulePath,
-            isPackage: modulePath.endsWith('__init__.py'),
-            dependencies: [],
-          });
+      if (result.code === 0 && result.stdout.trim() !== 'builtin') {
+        const modulePath = result.stdout.trim();
 
-          return modulePath;
-        }
-      } catch (error) {
-        log.warn('Failed to resolve module', { moduleName, error: String(error) });
+        // Cache the result
+        this.moduleCache.set(moduleName, {
+          name: moduleName,
+          path: modulePath,
+          isPackage: modulePath.endsWith('__init__.py'),
+          dependencies: [],
+        });
+
+        return modulePath;
       }
+    } catch (error) {
+      log.warn('Failed to resolve module', { moduleName, error: String(error) });
     }
 
-    // Fallback: search in known Python paths
+    return null;
+  }
+
+  /**
+   * Fallback resolution: probe `<path>/<module>.py` and
+   * `<path>/<module>/__init__.py` across the known Python search paths.
+   * Returns the first existing candidate, or `null`.
+   */
+  private async resolveViaSearchPaths(moduleName: string): Promise<string | null> {
     const searchPaths = await this.getPythonSearchPaths();
 
     for (const searchPath of searchPaths) {
@@ -237,40 +260,33 @@ export class ModuleDiscovery {
    */
   parseDependenciesFromSource(source: string): string[] {
     const dependencies: string[] = [];
-    const lines = source.split('\n');
 
-    for (const line of lines) {
-      const trimmed = line.trim();
-
-      // Skip comments and empty lines
-      if (trimmed.startsWith('#') || trimmed === '') {
-        continue;
+    for (const line of source.split('\n')) {
+      const moduleName = this.extractImportedModule(line.trim());
+      if (moduleName) {
+        dependencies.push(moduleName);
       }
+    }
 
-      // Match import statements
-      const importMatch = trimmed.match(/^import\s+([a-zA-Z_][a-zA-Z0-9_\.]*)/);
-      if (importMatch?.[1]) {
-        const fullModuleName = importMatch[1];
-        const moduleName = fullModuleName.split('.')[0]; // Get top-level module
-        if (moduleName) {
-          dependencies.push(moduleName);
-        }
-        continue;
-      }
+    return [...new Set(dependencies)]; // Remove duplicates
+  }
 
-      // Match from ... import statements
-      const fromMatch = trimmed.match(/^from\s+([a-zA-Z_][a-zA-Z0-9_\.]*)\s+import/);
-      if (fromMatch?.[1]) {
-        const fullModuleName = fromMatch[1];
-        const moduleName = fullModuleName.split('.')[0]; // Get top-level module
-        if (moduleName) {
-          dependencies.push(moduleName);
-        }
-        continue;
-      }
+  /**
+   * Extract the top-level module name imported by a single (trimmed) source
+   * line, or `null` when the line is a comment, blank, or not an import.
+   */
+  private extractImportedModule(trimmed: string): string | null {
+    // Skip comments and empty lines
+    if (trimmed.startsWith('#') || trimmed === '') {
+      return null;
     }
 
-    return [...new Set(dependencies)]; // Remove duplicates
+    // Match `import x.y.z` and `from x.y.z import ...` statements.
+    const match =
+      trimmed.match(/^import\s+([a-zA-Z_][a-zA-Z0-9_\.]*)/) ??
+      trimmed.match(/^from\s+([a-zA-Z_][a-zA-Z0-9_\.]*)\s+import/);
+
+    return match?.[1]?.split('.')[0] ?? null; // Get top-level module
   }
 
   /**

src/core/validation.ts

@@ -195,60 +195,96 @@ export class ValidationEngine {
     errors: AnalysisError[],
     warnings: AnalysisWarning[]
   ): void {
-    // Check return type (skip __init__ methods as they conventionally don't need return type annotations)
-    if (this.isEmptyType(func.returnType) && func.name !== '__init__') {
-      if (this.config.allowMissingTypeHints) {
-        warnings.push({
-          type: 'missing-type',
-          message: `Function '${func.name}' is missing return type annotation`,
-        });
-      } else if (this.config.strictTypeChecking) {
-        // In strict mode without allowMissingTypeHints, we warn first then error
-        warnings.push({
-          type: 'missing-type',
-          message: `Function '${func.name}' is missing return type annotation`,
-        });
-        errors.push({
-          type: 'type',
-          message: `Function '${func.name}' requires return type annotation`,
-        });
-      }
-    }
+    this.checkReturnTypeHint(func, errors, warnings);
 
     // Check parameter types (skip 'self' and 'cls' parameters)
     for (const param of func.parameters) {
-      if (this.isEmptyType(param.type) && param.name !== 'self' && param.name !== 'cls') {
-        if (this.config.allowMissingTypeHints) {
-          warnings.push({
-            type: 'missing-type',
-            message: `Parameter '${param.name}' in function '${func.name}' is missing type annotation`,
-          });
-        } else if (this.config.strictTypeChecking) {
-          // In strict mode without allowMissingTypeHints, we warn first then error
-          warnings.push({
-            type: 'missing-type',
-            message: `Parameter '${param.name}' in function '${func.name}' is missing type annotation`,
-          });
-          errors.push({
-            type: 'type',
-            message: `Parameter '${param.name}' in function '${func.name}' requires type annotation`,
-          });
-        }
-      }
+      this.checkParameterTypeHint(func, param, errors, warnings);
+      this.checkParameterTypeStructure(param, errors);
+    }
 
-      // Validate type structure only in strict mode (skip 'self' and 'cls' parameters)
-      if (
-        this.config.strictTypeChecking &&
-        !this.config.allowMissingTypeHints &&
-        param.name !== 'self' &&
-        param.name !== 'cls'
-      ) {
-        const typeErrors = this.validateTypeAnnotation(param.type, `parameter '${param.name}'`);
-        errors.push(...typeErrors);
-      }
+    this.checkReturnTypeStructure(func, errors);
+  }
+
+  /**
+   * Emit a missing-type warning, and—in strict mode—an accompanying error.
+   * In strict mode without allowMissingTypeHints, we warn first then error.
+   */
+  private reportMissingType(
+    warningMessage: string,
+    errorMessage: string,
+    warnings: AnalysisWarning[],
+    errors: AnalysisError[]
+  ): void {
+    if (this.config.allowMissingTypeHints) {
+      warnings.push({ type: 'missing-type', message: warningMessage });
+    } else if (this.config.strictTypeChecking) {
+      warnings.push({ type: 'missing-type', message: warningMessage });
+      errors.push({ type: 'type', message: errorMessage });
     }
+  }
 
-    // Validate return type structure only in strict mode
+  /**
+   * Check the function return type annotation (skip __init__ methods as they
+   * conventionally don't need return type annotations).
+   */
+  private checkReturnTypeHint(
+    func: PythonFunction,
+    errors: AnalysisError[],
+    warnings: AnalysisWarning[]
+  ): void {
+    if (this.isEmptyType(func.returnType) && func.name !== '__init__') {
+      this.reportMissingType(
+        `Function '${func.name}' is missing return type annotation`,
+        `Function '${func.name}' requires return type annotation`,
+        warnings,
+        errors
+      );
+    }
+  }
+
+  /**
+   * Check a single parameter's type annotation (skip 'self' and 'cls').
+   */
+  private checkParameterTypeHint(
+    func: PythonFunction,
+    param: PythonFunction['parameters'][number],
+    errors: AnalysisError[],
+    warnings: AnalysisWarning[]
+  ): void {
+    if (this.isEmptyType(param.type) && param.name !== 'self' && param.name !== 'cls') {
+      this.reportMissingType(
+        `Parameter '${param.name}' in function '${func.name}' is missing type annotation`,
+        `Parameter '${param.name}' in function '${func.name}' requires type annotation`,
+        warnings,
+        errors
+      );
+    }
+  }
+
+  /**
+   * Validate a single parameter's type structure only in strict mode
+   * (skip 'self' and 'cls' parameters).
+   */
+  private checkParameterTypeStructure(
+    param: PythonFunction['parameters'][number],
+    errors: AnalysisError[]
+  ): void {
+    if (
+      this.config.strictTypeChecking &&
+      !this.config.allowMissingTypeHints &&
+      param.name !== 'self' &&
+      param.name !== 'cls'
+    ) {
+      const typeErrors = this.validateTypeAnnotation(param.type, `parameter '${param.name}'`);
+      errors.push(...typeErrors);
+    }
+  }
+
+  /**
+   * Validate the return type structure only in strict mode.
+   */
+  private checkReturnTypeStructure(func: PythonFunction, errors: AnalysisError[]): void {
     if (this.config.strictTypeChecking && !this.config.allowMissingTypeHints) {
       const returnTypeErrors = this.validateTypeAnnotation(func.returnType, 'return type');
       errors.push(...returnTypeErrors);