refactor(transformer): modularize into handler modules

Extract transformer code from monolithic index.ts (7352 lines) into
focused handler modules for better maintainability:

- handlers/classes.ts: Class, dataclass, enum, TypedDict, Protocol, NamedTuple
- handlers/functions.ts: Functions, lambda, async/await, yield
- handlers/comprehensions.ts: List/dict/set comprehensions, generators
- handlers/imports.ts: Import statement handling
- handlers/assignments.ts: Assignments, destructuring
- handlers/exceptions.ts: Try/except/finally, raise
- handlers/control-flow.ts: If/while/for/match statements
- handlers/docstrings.ts: Docstring parsing, JSDoc generation
- handlers/literals.ts: Numbers, strings, f-strings, booleans
- handlers/expressions.ts: Binary/unary operators, conditionals
- builtins/call-handlers.ts: Builtin function registry
- types.ts: Shared type definitions
- context.ts: Transform context and scope management

Result: index.ts reduced from 7352 to 2589 lines (65% reduction)
All 2297 tests passing, ESLint clean.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: swernerx

packages/python2ts/src/transformer/builtins/call-handlers.ts

@@ -0,0 +1,203 @@
+import type { SyntaxNode } from "@lezer/common"
+import { getChildren } from "../../parser/index.js"
+import type { TransformContext, NodeTransformer } from "../types.js"
+
+/**
+ * Handler configuration for builtin functions.
+ * Simple handlers just need runtime and output pattern.
+ */
+interface SimpleHandler {
+  runtime: string
+  output: string // Use {args} as placeholder
+  isAsync?: boolean
+  needsNew?: boolean
+}
+
+/**
+ * Simple builtin handlers that follow the pattern:
+ * ctx.usesRuntime.add(runtime); return output.replace("{args}", args)
+ */
+const SIMPLE_BUILTINS: Record<string, SimpleHandler> = {
+  // Core builtins
+  len: { runtime: "len", output: "len({args})" },
+  range: { runtime: "range", output: "range({args})" },
+  int: { runtime: "int", output: "int({args})" },
+  float: { runtime: "float", output: "float({args})" },
+  str: { runtime: "str", output: "str({args})" },
+  bool: { runtime: "bool", output: "bool({args})" },
+  abs: { runtime: "abs", output: "abs({args})" },
+  min: { runtime: "min", output: "min({args})" },
+  max: { runtime: "max", output: "max({args})" },
+  sum: { runtime: "sum", output: "sum({args})" },
+  list: { runtime: "list", output: "list({args})" },
+  dict: { runtime: "dict", output: "dict({args})" },
+  set: { runtime: "set", output: "set({args})" },
+  tuple: { runtime: "tuple", output: "tuple({args})" },
+  enumerate: { runtime: "enumerate", output: "enumerate({args})" },
+  zip: { runtime: "zip", output: "zip({args})" },
+  sorted: { runtime: "sorted", output: "sorted({args})" },
+  reversed: { runtime: "reversed", output: "reversed({args})" },
+  type: { runtime: "type", output: "type({args})" },
+  input: { runtime: "input", output: "input({args})" },
+  ord: { runtime: "ord", output: "ord({args})" },
+  chr: { runtime: "chr", output: "chr({args})" },
+  all: { runtime: "all", output: "all({args})" },
+  any: { runtime: "any", output: "any({args})" },
+  map: { runtime: "map", output: "map({args})" },
+  filter: { runtime: "filter", output: "filter({args})" },
+  repr: { runtime: "repr", output: "repr({args})" },
+  round: { runtime: "round", output: "round({args})" },
+  divmod: { runtime: "divmod", output: "divmod({args})" },
+  hex: { runtime: "hex", output: "hex({args})" },
+  oct: { runtime: "oct", output: "oct({args})" },
+  bin: { runtime: "bin", output: "bin({args})" },
+  getattr: { runtime: "getattr", output: "getattr({args})" },
+  hasattr: { runtime: "hasattr", output: "hasattr({args})" },
+  setattr: { runtime: "setattr", output: "setattr({args})" },
+
+  // itertools
+  chain: { runtime: "itertools/chain", output: "chain({args})" },
+  combinations: { runtime: "itertools/combinations", output: "combinations({args})" },
+  permutations: { runtime: "itertools/permutations", output: "permutations({args})" },
+  product: { runtime: "itertools/product", output: "product({args})" },
+  cycle: { runtime: "itertools/cycle", output: "cycle({args})" },
+  repeat: { runtime: "itertools/repeat", output: "repeat({args})" },
+  islice: { runtime: "itertools/islice", output: "islice({args})" },
+  takewhile: { runtime: "itertools/takeWhile", output: "takeWhile({args})" },
+  dropwhile: { runtime: "itertools/dropWhile", output: "dropWhile({args})" },
+  zip_longest: { runtime: "itertools/zipLongest", output: "zipLongest({args})" },
+  compress: { runtime: "itertools/compress", output: "compress({args})" },
+  filterfalse: { runtime: "itertools/filterFalse", output: "filterFalse({args})" },
+  accumulate: { runtime: "itertools/accumulate", output: "accumulate({args})" },
+  groupby: { runtime: "itertools/groupby", output: "groupby({args})" },
+  count: { runtime: "itertools/count", output: "count({args})" },
+  tee: { runtime: "itertools/tee", output: "tee({args})" },
+  pairwise: { runtime: "itertools/pairwise", output: "pairwise({args})" },
+  combinations_with_replacement: {
+    runtime: "itertools/combinationsWithReplacement",
+    output: "combinationsWithReplacement({args})"
+  },
+
+  // collections
+  Counter: { runtime: "collections/Counter", output: "new Counter({args})", needsNew: true },
+  defaultdict: { runtime: "collections/defaultdict", output: "defaultdict({args})" },
+  deque: { runtime: "collections/deque", output: "new deque({args})", needsNew: true },
+
+  // functools
+  partial: { runtime: "functools/partial", output: "partial({args})" },
+  reduce: { runtime: "functools/reduce", output: "reduce({args})" },
+  lru_cache: { runtime: "functools/lruCache", output: "lruCache({args})" },
+  cache: { runtime: "functools/cache", output: "cache({args})" },
+  wraps: { runtime: "functools/wraps", output: "wraps({args})" },
+  cmp_to_key: { runtime: "functools/cmpToKey", output: "cmpToKey({args})" },
+  total_ordering: { runtime: "functools/totalOrdering", output: "totalOrdering({args})" },
+
+  // json
+  dumps: { runtime: "json/dumps", output: "dumps({args})" },
+  loads: { runtime: "json/loads", output: "loads({args})" },
+  dump: { runtime: "json/dump", output: "dump({args})" },
+  load: { runtime: "json/load", output: "load({args})" },
+
+  // datetime
+  datetime: { runtime: "datetime/datetime", output: "new datetime({args})", needsNew: true },
+  date: { runtime: "datetime/date", output: "new date({args})", needsNew: true },
+  time: { runtime: "datetime/time", output: "new time({args})", needsNew: true },
+  timedelta: { runtime: "datetime/timedelta", output: "new timedelta({args})", needsNew: true },
+
+  // string module
+  Template: { runtime: "string/Template", output: "new Template({args})", needsNew: true },
+  capwords: { runtime: "string/capWords", output: "capWords({args})" },
+
+  // glob module - async
+  glob: { runtime: "glob/glob", output: "await glob({args})", isAsync: true },
+  iglob: { runtime: "glob/iglob", output: "await iglob({args})", isAsync: true },
+  rglob: { runtime: "glob/rglob", output: "await rglob({args})", isAsync: true },
+
+  // shutil module - async
+  copy: { runtime: "shutil/copy", output: "await copy({args})", isAsync: true },
+  copy2: { runtime: "shutil/copy2", output: "await copy2({args})", isAsync: true },
+  copytree: { runtime: "shutil/copytree", output: "await copytree({args})", isAsync: true },
+  move: { runtime: "shutil/move", output: "await move({args})", isAsync: true },
+  rmtree: { runtime: "shutil/rmtree", output: "await rmtree({args})", isAsync: true },
+  which: { runtime: "shutil/which", output: "await which({args})", isAsync: true },
+
+  // tempfile module - async
+  mkstemp: { runtime: "tempfile/mkstemp", output: "await mkstemp({args})", isAsync: true },
+  mkdtemp: { runtime: "tempfile/mkdtemp", output: "await mkdtemp({args})", isAsync: true },
+  NamedTemporaryFile: {
+    runtime: "tempfile/NamedTemporaryFile",
+    output: "await NamedTemporaryFile.create({args})",
+    isAsync: true
+  },
+  TemporaryDirectory: {
+    runtime: "tempfile/TemporaryDirectory",
+    output: "await TemporaryDirectory.create({args})",
+    isAsync: true
+  },
+
+  // pathlib
+  Path: { runtime: "pathlib/Path", output: "new Path({args})", needsNew: true }
+}
+
+/**
+ * Handle isinstance() call with special tuple-to-array conversion
+ */
+function handleIsinstance(
+  args: string,
+  argList: SyntaxNode | undefined,
+  ctx: TransformContext,
+  transformNode: NodeTransformer
+): string {
+  ctx.usesRuntime.add("isinstance")
+
+  // Special handling: if second arg is a tuple, convert to array for multiple type check
+  if (argList) {
+    const argChildren = getChildren(argList).filter(
+      (c) => c.name !== "(" && c.name !== ")" && c.name !== ","
+    )
+    if (argChildren.length >= 2) {
+      const firstArg = argChildren[0]
+      const secondArg = argChildren[1]
+      if (firstArg && secondArg?.name === "TupleExpression") {
+        // Convert tuple to array literal
+        const tupleChildren = getChildren(secondArg).filter(
+          (c) => c.name !== "(" && c.name !== ")" && c.name !== ","
+        )
+        const typesCodes = tupleChildren.map((el) => transformNode(el, ctx))
+        return `isinstance(${transformNode(firstArg, ctx)}, [${typesCodes.join(", ")}])`
+      }
+    }
+  }
+  return `isinstance(${args})`
+}
+
+/**
+ * Handle builtin function call.
+ * Returns the transformed code, or null if not a builtin.
+ */
+export function handleBuiltinCall(
+  calleeName: string,
+  args: string,
+  argList: SyntaxNode | undefined,
+  ctx: TransformContext,
+  transformNode: NodeTransformer
+): string | null {
+  // Special case: print -> console.log (no runtime needed)
+  if (calleeName === "print") {
+    return `console.log(${args})`
+  }
+
+  // Special case: isinstance needs complex handling
+  if (calleeName === "isinstance") {
+    return handleIsinstance(args, argList, ctx, transformNode)
+  }
+
+  // Check simple builtins registry
+  const handler = SIMPLE_BUILTINS[calleeName]
+  if (handler) {
+    ctx.usesRuntime.add(handler.runtime)
+    return handler.output.replace("{args}", args)
+  }
+
+  return null
+}

packages/python2ts/src/transformer/context.ts

@@ -0,0 +1,159 @@
+import type { TransformContext } from "./types.js"
+
+/**
+ * JavaScript/TypeScript reserved keywords that cannot be used as variable names.
+ * Python allows these as identifiers, so we need to rename them.
+ */
+export const JS_RESERVED_KEYWORDS = new Set([
+  // ECMAScript reserved words
+  "break",
+  "case",
+  "catch",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "in",
+  "instanceof",
+  "new",
+  "return",
+  "switch",
+  "this",
+  "throw",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  // ECMAScript 6+ reserved words
+  "class",
+  "const",
+  "enum",
+  "export",
+  "extends",
+  "import",
+  // Note: 'super' is intentionally NOT in this list as it's valid in JS class contexts
+  // Strict mode reserved words
+  "implements",
+  "interface",
+  "let",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "static",
+  "yield",
+  // TypeScript reserved words
+  "abstract",
+  "as",
+  "async",
+  "await",
+  "declare",
+  "is",
+  "module",
+  "namespace",
+  "require",
+  "type"
+  // Note: 'get', 'set', 'from', 'of' are contextual keywords and valid as identifiers
+])
+
+/**
+ * Escape a variable name if it's a reserved keyword.
+ * Adds underscore prefix to reserved keywords.
+ */
+export function escapeReservedKeyword(name: string): string {
+  return JS_RESERVED_KEYWORDS.has(name) ? `_${name}` : name
+}
+
+/**
+ * Create a new transform context for processing Python source.
+ */
+export function createContext(source: string): TransformContext {
+  return {
+    source,
+    indentLevel: 0,
+    usesRuntime: new Set(),
+    scopeStack: [new Set()], // Start with one global scope
+    definedClasses: new Set(),
+    insideFunctionBody: 0,
+    insideTryBlock: 0,
+    hoistedImports: []
+  }
+}
+
+/** Push a new scope onto the stack */
+export function pushScope(ctx: TransformContext): void {
+  ctx.scopeStack.push(new Set())
+}
+
+/** Pop the current scope from the stack */
+export function popScope(ctx: TransformContext): void {
+  if (ctx.scopeStack.length > 1) {
+    ctx.scopeStack.pop()
+  }
+}
+
+/** Check if a variable is declared in any accessible scope */
+export function isVariableDeclared(ctx: TransformContext, name: string): boolean {
+  for (const scope of ctx.scopeStack) {
+    if (scope.has(name)) return true
+  }
+  return false
+}
+
+/** Declare a variable in the current (top) scope */
+export function declareVariable(ctx: TransformContext, name: string): void {
+  const currentScope = ctx.scopeStack[ctx.scopeStack.length - 1]
+  if (currentScope) {
+    currentScope.add(name)
+  }
+}
+
+/**
+ * Strip outer parentheses from an expression if they're redundant.
+ * Used to avoid double-parentheses in conditions like `if ((x === y))`.
+ * Does NOT strip if the expression contains an assignment (walrus operator needs double parens).
+ */
+export function stripOuterParens(code: string): string {
+  const trimmed = code.trim()
+  if (trimmed.startsWith("(") && trimmed.endsWith(")")) {
+    // Don't strip if this contains an assignment expression (walrus operator)
+    // Assignment in condition requires double parens: if ((x = getValue()))
+    const inner = trimmed.slice(1, -1)
+    // Check for assignment: = not preceded by !, =, <, > (to avoid ==, !=, <=, >=)
+    if (/(?<![!=<>])=(?!=)/.test(inner)) {
+      return code
+    }
+
+    // Check if the parens are balanced (not just opening and closing separately)
+    let depth = 0
+    for (let i = 0; i < trimmed.length; i++) {
+      if (trimmed[i] === "(") depth++
+      else if (trimmed[i] === ")") depth--
+      // If depth reaches 0 before the end, the outer parens aren't matched
+      if (depth === 0 && i < trimmed.length - 1) return code
+    }
+    // Safe to strip the outer parens
+    return inner
+  }
+  return code
+}
+
+/** Map of Python built-in types to TypeScript types */
+export const PYTHON_TO_TS_TYPES: Record<string, string> = {
+  str: "string",
+  int: "number",
+  float: "number",
+  bool: "boolean",
+  bytes: "Uint8Array",
+  None: "null",
+  Any: "any",
+  object: "object"
+}