tywrap 0.5.1 → 0.6.0

package/src/core/annotation-parser.ts

@@ -245,6 +245,19 @@ export function parseAnnotationToPythonType(
     return results;
   };
 
+  // Returns the content between the first `[` and the last `]` of a special-form
+  // annotation (e.g. the `int, str` of `Union[int, str]`). Callers gate this on a
+  // prefix check, so the brackets are known to be present.
+  const bracketInner = (raw: string): string => raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
+
+  // True when `raw` opens with one of the supported module prefixes followed by
+  // `name[`. Mirrors the inlined `raw.startsWith('typing.Name[') || ...` checks so
+  // the branch ordering in `parse` is unchanged.
+  const startsWithSpecialForm = (raw: string, name: string): boolean =>
+    raw.startsWith(`typing.${name}[`) ||
+    raw.startsWith(`typing_extensions.${name}[`) ||
+    raw.startsWith(`${name}[`);
+
   const splitGenericInvocation = (raw: string): { name: string; inner: string } | null => {
     if (!raw.endsWith(']')) {
       return null;
@@ -277,6 +290,86 @@ export function parseAnnotationToPythonType(
     };
   };
 
+  // Parses the body of a `Callable[...]` form (the `inner` already stripped of the
+  // outer brackets). `recurse` is the top-level `parse`, threaded in so this stays a
+  // standalone helper. Returns null only when the form has fewer than the required
+  // two comma-separated sections, matching the original guarded branch exactly.
+  const parseCallableInner = (
+    inner: string,
+    depth: number,
+    recurse: (ann: unknown, depth?: number) => PythonType
+  ): PythonType | null => {
+    const parts = splitTopLevel(inner, ',');
+    if (parts.length < 2) {
+      return null;
+    }
+
+    const paramsPart = (parts[0] ?? '').trim();
+    const returnPart = parts.slice(1).join(',').trim();
+    const returnType = recurse(returnPart, depth + 1);
+
+    if (paramsPart === '...' || paramsPart === 'Ellipsis') {
+      return {
+        kind: 'callable',
+        parameters: [{ kind: 'custom', name: '...' }],
+        returnType,
+      };
+    }
+
+    const directParamSpec = recurse(paramsPart, depth + 1);
+    if (directParamSpec.kind === 'paramspec') {
+      return {
+        kind: 'callable',
+        parameters: [],
+        parameterSpec: directParamSpec,
+        returnType,
+      };
+    }
+
+    const paramInner =
+      paramsPart.startsWith('[') && paramsPart.endsWith(']') ? paramsPart.slice(1, -1) : '';
+    const trimmed = paramInner.trim();
+    if (trimmed === '...' || trimmed === 'Ellipsis') {
+      return {
+        kind: 'callable',
+        parameters: [{ kind: 'custom', name: '...' }],
+        returnType,
+      };
+    }
+
+    const parameters = trimmed
+      ? splitTopLevel(trimmed, ',').map(p => recurse(p.trim(), depth + 1))
+      : [];
+    return { kind: 'callable', parameters, returnType };
+  };
+
+  // Handles the `typing.TypeVar('T')` / `ParamSpec('P')` / `TypeVarTuple('Ts')`
+  // factory-call forms. Returns null when `rawText` is none of them, preserving
+  // the original sequential fall-through (TypeVar, then ParamSpec, then TypeVarTuple).
+  const parseTypingFactory = (rawText: string): PythonType | null => {
+    const typeVarName = parseTypingFactoryName(rawText, 'TypeVar');
+    if (typeVarName) {
+      return mapKnownTypeParameter(typeVarName) ?? { kind: 'typevar', name: typeVarName };
+    }
+
+    const paramSpecName = parseTypingFactoryName(rawText, 'ParamSpec');
+    if (paramSpecName) {
+      return mapKnownTypeParameter(paramSpecName) ?? { kind: 'paramspec', name: paramSpecName };
+    }
+
+    const typeVarTupleName = parseTypingFactoryName(rawText, 'TypeVarTuple');
+    if (typeVarTupleName) {
+      return (
+        mapKnownTypeParameter(typeVarTupleName) ?? {
+          kind: 'typevartuple',
+          name: typeVarTupleName,
+        }
+      );
+    }
+
+    return null;
+  };
+
   const parse = (ann: unknown, depth = 0): PythonType => {
     if (ann === null || ann === undefined) {
       return unknownType();
@@ -320,33 +413,18 @@ export function parseAnnotationToPythonType(
       }
     }
 
-    if (
-      raw.startsWith('typing.Union[') ||
-      raw.startsWith('typing_extensions.Union[') ||
-      raw.startsWith('Union[')
-    ) {
-      const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-      const parts = splitTopLevel(inner, ',');
+    if (startsWithSpecialForm(raw, 'Union')) {
+      const parts = splitTopLevel(bracketInner(raw), ',');
       const types = parts.map(p => parse(p.trim(), depth + 1));
       return { kind: 'union', types };
     }
 
-    if (
-      raw.startsWith('typing.Optional[') ||
-      raw.startsWith('typing_extensions.Optional[') ||
-      raw.startsWith('Optional[')
-    ) {
-      const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-      return { kind: 'optional', type: parse(inner, depth + 1) };
+    if (startsWithSpecialForm(raw, 'Optional')) {
+      return { kind: 'optional', type: parse(bracketInner(raw), depth + 1) };
     }
 
-    if (
-      raw.startsWith('typing.Literal[') ||
-      raw.startsWith('typing_extensions.Literal[') ||
-      raw.startsWith('Literal[')
-    ) {
-      const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-      const parts = splitTopLevel(inner, ',');
+    if (startsWithSpecialForm(raw, 'Literal')) {
+      const parts = splitTopLevel(bracketInner(raw), ',');
       if (parts.length === 1) {
         return mapLiteral(String(parts[0] ?? '').trim());
       }
@@ -360,24 +438,9 @@ export function parseAnnotationToPythonType(
       return parse(extMatch[3] ?? '', depth + 1);
     }
 
-    const typeVarName = parseTypingFactoryName(rawText, 'TypeVar');
-    if (typeVarName) {
-      return mapKnownTypeParameter(typeVarName) ?? { kind: 'typevar', name: typeVarName };
-    }
-
-    const paramSpecName = parseTypingFactoryName(rawText, 'ParamSpec');
-    if (paramSpecName) {
-      return mapKnownTypeParameter(paramSpecName) ?? { kind: 'paramspec', name: paramSpecName };
-    }
-
-    const typeVarTupleName = parseTypingFactoryName(rawText, 'TypeVarTuple');
-    if (typeVarTupleName) {
-      return (
-        mapKnownTypeParameter(typeVarTupleName) ?? {
-          kind: 'typevartuple',
-          name: typeVarTupleName,
-        }
-      );
+    const typingFactory = parseTypingFactory(rawText);
+    if (typingFactory) {
+      return typingFactory;
     }
     if (
       raw === 'typing.LiteralString' ||
@@ -387,61 +450,15 @@ export function parseAnnotationToPythonType(
       return { kind: 'primitive', name: 'str' };
     }
 
-    if (
-      raw.startsWith('typing.Callable[') ||
-      raw.startsWith('typing_extensions.Callable[') ||
-      raw.startsWith('Callable[')
-    ) {
-      const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-      const parts = splitTopLevel(inner, ',');
-      if (parts.length >= 2) {
-        const paramsPart = (parts[0] ?? '').trim();
-        const returnPart = parts.slice(1).join(',').trim();
-        const returnType = parse(returnPart, depth + 1);
-
-        if (paramsPart === '...' || paramsPart === 'Ellipsis') {
-          return {
-            kind: 'callable',
-            parameters: [{ kind: 'custom', name: '...' }],
-            returnType,
-          };
-        }
-
-        const directParamSpec = parse(paramsPart, depth + 1);
-        if (directParamSpec.kind === 'paramspec') {
-          return {
-            kind: 'callable',
-            parameters: [],
-            parameterSpec: directParamSpec,
-            returnType,
-          };
-        }
-
-        const paramInner =
-          paramsPart.startsWith('[') && paramsPart.endsWith(']') ? paramsPart.slice(1, -1) : '';
-        const trimmed = paramInner.trim();
-        if (trimmed === '...' || trimmed === 'Ellipsis') {
-          return {
-            kind: 'callable',
-            parameters: [{ kind: 'custom', name: '...' }],
-            returnType,
-          };
-        }
-
-        const parameters = trimmed
-          ? splitTopLevel(trimmed, ',').map(p => parse(p.trim(), depth + 1))
-          : [];
-        return { kind: 'callable', parameters, returnType };
+    if (startsWithSpecialForm(raw, 'Callable')) {
+      const callable = parseCallableInner(bracketInner(raw), depth, parse);
+      if (callable) {
+        return callable;
       }
     }
 
-    if (
-      raw.startsWith('typing.Mapping[') ||
-      raw.startsWith('typing_extensions.Mapping[') ||
-      raw.startsWith('Mapping[')
-    ) {
-      const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-      const parts = splitTopLevel(inner, ',');
+    if (startsWithSpecialForm(raw, 'Mapping')) {
+      const parts = splitTopLevel(bracketInner(raw), ',');
       return {
         kind: 'collection',
         name: 'dict',
@@ -449,13 +466,8 @@ export function parseAnnotationToPythonType(
       };
     }
 
-    if (
-      raw.startsWith('typing.Annotated[') ||
-      raw.startsWith('typing_extensions.Annotated[') ||
-      raw.startsWith('Annotated[')
-    ) {
-      const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-      const parts = splitTopLevel(inner, ',');
+    if (startsWithSpecialForm(raw, 'Annotated')) {
+      const parts = splitTopLevel(bracketInner(raw), ',');
       if (parts.length > 0) {
         return {
           kind: 'annotated',
@@ -465,13 +477,8 @@ export function parseAnnotationToPythonType(
       }
     }
 
-    if (
-      raw.startsWith('typing.Unpack[') ||
-      raw.startsWith('typing_extensions.Unpack[') ||
-      raw.startsWith('Unpack[')
-    ) {
-      const inner = raw.slice(raw.indexOf('[') + 1, raw.lastIndexOf(']'));
-      return { kind: 'unpack', type: parse(inner, depth + 1) };
+    if (startsWithSpecialForm(raw, 'Unpack')) {
+      return { kind: 'unpack', type: parse(bracketInner(raw), depth + 1) };
     }
 
     const coll = normalizeCollectionName(raw);

package/src/core/discovery.ts

@@ -12,6 +12,32 @@ import { getComponentLogger } from '../utils/logger.js';
 
 const log = getComponentLogger('Discovery');
 
+/**
+ * Strict allow-list for Python module names.
+ *
+ * Module names are interpolated into a `python -c` source string, so anything
+ * outside a conservative identifier-plus-dots shape (e.g. quotes, semicolons,
+ * newlines, parentheses, whitespace) could break out of the intended
+ * expression and inject arbitrary code into the interpreter. Reject those
+ * before they ever reach the subprocess argv.
+ */
+const SAFE_MODULE_NAME = /^[A-Za-z_][A-Za-z0-9_.]*$/;
+
+/**
+ * Validate a Python module name against {@link SAFE_MODULE_NAME}.
+ *
+ * @throws {Error} if the name is empty or contains characters that could
+ *   escape the `python -c` expression it is interpolated into.
+ */
+function assertSafeModuleName(moduleName: string): void {
+  if (typeof moduleName !== 'string' || !SAFE_MODULE_NAME.test(moduleName)) {
+    throw new Error(
+      `Unsafe Python module name rejected: ${JSON.stringify(moduleName)}. ` +
+        'Module names must match /^[A-Za-z_][A-Za-z0-9_.]*$/.'
+    );
+  }
+}
+
 export interface ModuleInfo {
   name: string;
   path: string;
@@ -87,6 +113,9 @@ export class ModuleDiscovery {
    * Resolve Python module path from module name
    */
   async resolvePythonPath(moduleName: string): Promise<string | null> {
+    // Reject names that could break out of the `python -c` expression below.
+    assertSafeModuleName(moduleName);
+
     // Check cache first
     const cached = this.moduleCache.get(moduleName);
     if (cached) {
@@ -383,6 +412,9 @@ export class ModuleDiscovery {
    * Get module version information
    */
   async getModuleVersion(moduleName: string): Promise<string | undefined> {
+    // Reject names that could break out of the `python -c` expression below.
+    assertSafeModuleName(moduleName);
+
     if (!processUtils.isAvailable()) {
       return undefined;
     }

package/src/core/emit-call.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared call-emission helpers for the TypeScript wrapper generator.
+ *
+ * The function, method, and constructor wrappers all emit the same runtime
+ * prelude (assemble `__args`, fold a trailing object into `__kwargs`, unpack
+ * `*args`) and the same argument guards (reject positional-only-as-keyword,
+ * require keyword-only arguments). They differ only by indentation, the error
+ * label used in thrown messages, and the terminal RPC verb (which the call
+ * sites still emit themselves).
+ *
+ * The emitted strings MUST stay byte-identical to the previous inline copies.
+ */
+
+import type { Parameter } from '../types/index.js';
+
+/** Describes one call site for prelude/guard emission. */
+export interface CallDescriptor {
+  /** Positional parameters (no *args/**kwargs/keyword-only). */
+  positionalParams: readonly Parameter[];
+  /** The `*args` parameter, if any. */
+  varArgsParam?: Parameter;
+  /** Whether `*args` is modeled as an array param (true when kwargs coexist). */
+  needsVarArgsArray: boolean;
+  /** Whether the wrapper takes a `kwargs` parameter. */
+  hasKwArgs: boolean;
+  /** Whether the callee declares `**kwargs`. */
+  hasVarKwArgs: boolean;
+  /** Names of keyword-only parameters. */
+  keywordOnlyNames: readonly string[];
+  /** Names of required keyword-only parameters. */
+  requiredKwOnlyNames: readonly string[];
+  /** Names of positional-only parameters. */
+  positionalOnlyNames: readonly string[];
+  /** Number of leading required positional parameters. */
+  requiredPosCount: number;
+  /** Base indentation (e.g. '  ' for functions, '    ' for methods/ctors). */
+  indent: string;
+  /** Error label used in thrown messages (function/method name or '__init__'). */
+  errorLabel: string;
+}
+
+/** Helpers wired from the generator instance (they depend on `this`). */
+export interface CallEmitHelpers {
+  escapeIdentifier(name: string): string;
+  renderLooksLikeKwargsExpr(
+    valueExpr: string,
+    options: {
+      keywordOnlyNames: string[];
+      requiredKwOnlyNames: string[];
+      hasVarKwArgs: boolean;
+    }
+  ): string;
+}
+
+/**
+ * Emit the runtime prelude lines that build the `__args` array, fold a trailing
+ * plain object into `__kwargs`, and unpack `*args`.
+ */
+export function emitCallPrelude(desc: CallDescriptor, helpers: CallEmitHelpers): string[] {
+  const {
+    positionalParams,
+    varArgsParam,
+    needsVarArgsArray,
+    hasKwArgs,
+    hasVarKwArgs,
+    keywordOnlyNames,
+    requiredKwOnlyNames,
+    requiredPosCount,
+    indent: i,
+    errorLabel,
+  } = desc;
+  const i2 = `${i}  `;
+  const i3 = `${i2}  `;
+
+  const lines: string[] = [];
+  if (hasKwArgs) {
+    lines.push(`${i}let __kwargs = kwargs;`);
+  }
+  const positionalArgExprs = positionalParams.map(p => helpers.escapeIdentifier(p.name));
+  lines.push(`${i}const __args: unknown[] = [${positionalArgExprs.join(', ')}];`);
+  if (requiredPosCount < positionalParams.length) {
+    lines.push(
+      `${i}while (__args.length > ${requiredPosCount} && __args[__args.length - 1] === undefined) {`
+    );
+    lines.push(`${i2}__args.pop();`);
+    lines.push(`${i}}`);
+  }
+  if (hasKwArgs && requiredPosCount < positionalParams.length) {
+    const looksLikeKwargs = helpers.renderLooksLikeKwargsExpr('__candidate', {
+      keywordOnlyNames: [...keywordOnlyNames],
+      requiredKwOnlyNames: [...requiredKwOnlyNames],
+      hasVarKwArgs,
+    });
+    lines.push(`${i}if (__kwargs === undefined && __args.length > ${requiredPosCount}) {`);
+    lines.push(`${i2}const __candidate = __args[__args.length - 1];`);
+    lines.push(`${i2}if (${looksLikeKwargs}) {`);
+    lines.push(`${i3}__kwargs = __candidate as any;`);
+    lines.push(`${i3}__args.pop();`);
+    lines.push(`${i2}}`);
+    lines.push(`${i}}`);
+  }
+  if (varArgsParam) {
+    const vname = helpers.escapeIdentifier(varArgsParam.name);
+    if (needsVarArgsArray) {
+      const looksLikeKwargs = helpers.renderLooksLikeKwargsExpr(vname, {
+        keywordOnlyNames: [...keywordOnlyNames],
+        requiredKwOnlyNames: [...requiredKwOnlyNames],
+        hasVarKwArgs,
+      });
+      lines.push(`${i}let __varargs: unknown[] = [];`);
+      lines.push(`${i}if (${vname} !== undefined) {`);
+      lines.push(`${i2}if (globalThis.Array.isArray(${vname})) {`);
+      lines.push(`${i3}__varargs = ${vname};`);
+      lines.push(`${i2}} else if (__kwargs === undefined && ${looksLikeKwargs}) {`);
+      lines.push(`${i3}__kwargs = ${vname} as any;`);
+      lines.push(`${i2}} else {`);
+      lines.push(
+        `${i3}throw new Error(\`${errorLabel} expected ${varArgsParam.name} to be an array\`);`
+      );
+      lines.push(`${i2}}`);
+      lines.push(`${i}}`);
+      lines.push(`${i}__args.push(...__varargs);`);
+    } else {
+      lines.push(`${i}__args.push(...${vname});`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Emit the argument guard lines that reject positional-only arguments passed as
+ * keywords and enforce required keyword-only arguments.
+ */
+export function emitArgGuards(desc: CallDescriptor): string[] {
+  const {
+    hasKwArgs,
+    positionalOnlyNames,
+    requiredKwOnlyNames,
+    indent: i,
+    errorLabel,
+  } = desc;
+  const i2 = `${i}  `;
+  const i3 = `${i2}  `;
+
+  const lines: string[] = [];
+  if (hasKwArgs && positionalOnlyNames.length > 0) {
+    lines.push(`${i}const __positionalOnly = ${JSON.stringify(positionalOnlyNames)} as const;`);
+    lines.push(`${i}for (const key of __positionalOnly) {`);
+    lines.push(`${i2}if (__kwargs && Object.prototype.hasOwnProperty.call(__kwargs, key)) {`);
+    lines.push(
+      `${i3}throw new Error(\`${errorLabel} does not accept positional-only argument "\${key}" as a keyword argument\`);`
+    );
+    lines.push(`${i2}}`);
+    lines.push(`${i}}`);
+  }
+  if (hasKwArgs && requiredKwOnlyNames.length > 0) {
+    lines.push(`${i}const __requiredKwOnly = ${JSON.stringify(requiredKwOnlyNames)} as const;`);
+    lines.push(`${i}const __missing: string[] = [];`);
+    lines.push(`${i}for (const key of __requiredKwOnly) {`);
+    lines.push(`${i2}if (!__kwargs || !Object.prototype.hasOwnProperty.call(__kwargs, key)) {`);
+    lines.push(`${i3}__missing.push(key);`);
+    lines.push(`${i2}}`);
+    lines.push(`${i}}`);
+    lines.push(`${i}if (__missing.length > 0) {`);
+    lines.push(
+      `${i2}throw new Error(\`Missing required keyword-only arguments for ${errorLabel}: \${__missing.join(', ')}\`);`
+    );
+    lines.push(`${i}}`);
+  }
+  return lines;
+}