pulse-framework 0.1.46__py3-none-any.whl → 0.1.48__py3-none-any.whl

pulse/transpiler/constants.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from typing import ClassVar, TypeAlias, override
+
+from pulse.transpiler.context import is_interpreted_mode
+from pulse.transpiler.errors import JSCompilationError
+from pulse.transpiler.ids import generate_id
+from pulse.transpiler.nodes import (
+	JSArray,
+	JSBoolean,
+	JSExpr,
+	JSIdentifier,
+	JSNew,
+	JSNumber,
+	JSString,
+)
+
+JsPrimitive: TypeAlias = bool | int | float | str | None
+JsValue: TypeAlias = "JsPrimitive | list[JsValue] | tuple[JsValue, ...] | set[JsValue] | frozenset[JsValue] | dict[str, JsValue]"
+JsVar: TypeAlias = "JsValue | JSExpr"
+
+# Global cache for deduplication across all transpiled functions
+CONSTANTS_CACHE: dict[int, "JsConstant"] = {}  # id(value) -> JsConstant
+
+
+class JsConstant(JSExpr):
+	"""Wrapper for constant values used in transpiled JS functions."""
+
+	is_primary: ClassVar[bool] = True
+
+	value: object
+	expr: JSExpr
+	id: str
+	name: str  # Original Python variable name (set by codegen)
+
+	def __init__(self, value: object, expr: JSExpr, name: str = "") -> None:
+		self.value = value
+		self.expr = expr
+		self.id = generate_id()
+		self.name = name
+
+	@property
+	def js_name(self) -> str:
+		"""Unique JS identifier for this constant."""
+		return f"{self.name}_{self.id}" if self.name else f"_const_{self.id}"
+
+	@override
+	def emit(self) -> str:
+		"""Emit JS code for this constant.
+
+		In normal mode: returns the unique JS name (e.g., "CONSTANT_1")
+		In interpreted mode: returns a get_object call (e.g., "get_object('CONSTANT_1')")
+		"""
+		base = self.js_name
+		if is_interpreted_mode():
+			return f"get_object('{base}')"
+		return base
+
+
+def _value_to_expr(value: JsValue) -> JSExpr:
+	"""Convert a Python value to a JSExpr (no caching)."""
+	if value is None:
+		return JSIdentifier("undefined")
+	elif isinstance(value, bool):
+		return JSBoolean(value)
+	elif isinstance(value, (int, float)):
+		return JSNumber(value)
+	elif isinstance(value, str):
+		return JSString(value)
+	elif isinstance(value, (list, tuple)):
+		return JSArray([_value_to_expr(v) for v in value])
+	elif isinstance(value, (set, frozenset)):
+		return JSNew(
+			JSIdentifier("Set"),
+			[JSArray([_value_to_expr(v) for v in value])],
+		)
+	elif isinstance(value, dict):
+		entries: list[JSExpr] = []
+		for k, v in value.items():
+			if not isinstance(k, str):
+				raise JSCompilationError("Only string keys supported in constant dicts")
+			entries.append(JSArray([JSString(k), _value_to_expr(v)]))
+		return JSNew(JSIdentifier("Map"), [JSArray(entries)])
+	else:
+		raise JSCompilationError(
+			f"Unsupported global constant: {type(value).__name__} (value: {value!r})"
+		)
+
+
+def const_to_js(value: JsValue, name: str = "") -> JsConstant:
+	"""Convert a Python value to a JsConstant (cached by identity)."""
+	value_id = id(value)
+	if value_id in CONSTANTS_CACHE:
+		return CONSTANTS_CACHE[value_id]
+
+	expr = _value_to_expr(value)
+	result = JsConstant(value, expr, name)
+	CONSTANTS_CACHE[value_id] = result
+	return result
+
+
+def jsify(value: JsVar) -> JSExpr:
+	if not isinstance(value, JSExpr):
+		return const_to_js(value).expr
+	return value
+
+
+def registered_constants() -> list[JsConstant]:
+	"""Get all registered JS constants."""
+	return list(CONSTANTS_CACHE.values())

pulse/transpiler/context.py

@@ -0,0 +1,26 @@
+"""Context for JSExpr emit mode."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+# When True, JSExpr.emit() returns code suitable for client-side interpretation
+# (e.g., "get_object('Button_1')" instead of "Button_1")
+_interpreted_mode: ContextVar[bool] = ContextVar(
+	"jsexpr_interpreted_mode", default=False
+)
+
+
+def is_interpreted_mode() -> bool:
+	"""Check if we're in interpreted mode."""
+	return _interpreted_mode.get()
+
+
+@contextmanager
+def interpreted_mode() -> Iterator[None]:
+	"""Context manager to enable interpreted mode for JSExpr.emit()."""
+	token = _interpreted_mode.set(True)
+	try:
+		yield
+	finally:
+		_interpreted_mode.reset(token)

pulse/transpiler/errors.py

@@ -0,0 +1,2 @@
+class JSCompilationError(Exception):
+	pass

pulse/transpiler/function.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+import types as pytypes
+from typing import (
+	Any,
+	Callable,
+	ClassVar,
+	Generic,
+	TypeAlias,
+	TypeVar,
+	TypeVarTuple,
+	override,
+)
+
+# Import module registrations to ensure they're available for dependency analysis
+import pulse.transpiler.modules  # noqa: F401
+from pulse.helpers import getsourcecode
+from pulse.transpiler.builtins import BUILTINS
+from pulse.transpiler.constants import JsConstant, const_to_js
+from pulse.transpiler.context import is_interpreted_mode
+from pulse.transpiler.errors import JSCompilationError
+from pulse.transpiler.ids import generate_id
+from pulse.transpiler.imports import Import
+from pulse.transpiler.js_module import JS_MODULES
+from pulse.transpiler.nodes import JSEXPR_REGISTRY, JSExpr, JSTransformer
+from pulse.transpiler.py_module import (
+	PY_MODULES,
+	PyModuleExpr,
+)
+from pulse.transpiler.transpiler import JsTranspiler
+
+Args = TypeVarTuple("Args")
+R = TypeVar("R")
+
+
+AnyJsFunction: TypeAlias = "JsFunction[*tuple[Any, ...], Any]"
+
+# Global cache for deduplication across all transpiled functions
+# Registered BEFORE analyzing deps to handle mutual recursion
+FUNCTION_CACHE: dict[Callable[..., object], AnyJsFunction] = {}
+
+
+class JsFunction(JSExpr, Generic[*Args, R]):
+	is_primary: ClassVar[bool] = True
+
+	fn: Callable[[*Args], R]
+	id: str
+	deps: dict[str, JSExpr]
+
+	def __init__(self, fn: Callable[[*Args], R]) -> None:
+		self.fn = fn
+		self.id = generate_id()
+
+		# Register self in cache BEFORE analyzing deps (handles cycles)
+		FUNCTION_CACHE[fn] = self
+
+		# Analyze code object and resolve globals + closure vars
+		effective_globals, all_names = analyze_code_object(fn)
+
+		# Build dependencies dictionary - all values are JSExpr
+		deps: dict[str, JSExpr] = {}
+
+		for name in all_names:
+			value = effective_globals.get(name)
+
+			if value is None:
+				# Not in globals - check builtins (allows user to shadow builtins)
+				# Note: co_names includes both global names AND attribute names (e.g., 'input'
+				# from 'tags.input'). We only add supported builtins; unsupported ones are
+				# skipped since they might be attribute accesses handled during transpilation.
+				if name in BUILTINS:
+					deps[name] = BUILTINS[name]
+				continue
+
+			# Already a JSExpr (JsFunction, JsConstant, Import, JSMember, etc.)
+			if isinstance(value, JSExpr):
+				deps[name] = value
+			elif inspect.ismodule(value):
+				if value in JS_MODULES:
+					# import pulse.js.math as Math -> JSIdentifier or Import
+					deps[name] = JS_MODULES[value].to_js_expr()
+				elif value in PY_MODULES:
+					deps[name] = PyModuleExpr(PY_MODULES[value])
+				else:
+					raise JSCompilationError(
+						f"Could not resolve JavaScript module import for '{name}' (value: {value!r}). "
+						+ "Neither a registered Python module nor a known JS wrapper. "
+						+ "Check your import statement and module configuration."
+					)
+
+			elif id(value) in JSEXPR_REGISTRY:
+				# JSEXPR_REGISTRY always contains JSExpr (wrapping happens in JSExpr.register)
+				deps[name] = JSEXPR_REGISTRY[id(value)]
+			elif inspect.isfunction(value):
+				deps[name] = javascript(value)
+			elif callable(value):
+				raise JSCompilationError(
+					f"Callable object '{name}' (type: {type(value).__name__}) is not supported. "
+					+ "Only functions can be transpiled."
+				)
+			else:
+				deps[name] = const_to_js(value, name)
+
+		self.deps = deps
+
+	@property
+	def js_name(self) -> str:
+		"""Unique JS identifier for this function."""
+		return f"{self.fn.__name__}_{self.id}"
+
+	@override
+	def emit(self) -> str:
+		"""Emit JS code for this function reference.
+
+		In normal mode: returns the unique JS name (e.g., "myFunc_1")
+		In interpreted mode: returns a get_object call (e.g., "get_object('myFunc_1')")
+		"""
+		base = self.js_name
+		if is_interpreted_mode():
+			return f"get_object('{base}')"
+		return base
+
+	def imports(self) -> dict[str, Import]:
+		"""Get all Import dependencies."""
+		return {k: v for k, v in self.deps.items() if isinstance(v, Import)}
+
+	def functions(self) -> dict[str, AnyJsFunction]:
+		"""Get all JsFunction dependencies."""
+		return {k: v for k, v in self.deps.items() if isinstance(v, JsFunction)}
+
+	def constants(self) -> dict[str, JsConstant]:
+		"""Get all JsConstant dependencies."""
+		return {k: v for k, v in self.deps.items() if isinstance(v, JsConstant)}
+
+	def modules(self) -> dict[str, PyModuleExpr]:
+		"""Get all PyModuleExpr dependencies."""
+		return {k: v for k, v in self.deps.items() if isinstance(v, PyModuleExpr)}
+
+	def module_functions(self) -> dict[str, JSTransformer]:
+		"""Get all module function JSTransformer dependencies (named imports from modules)."""
+		from pulse.transpiler.builtins import BUILTINS
+
+		return {
+			k: v
+			for k, v in self.deps.items()
+			if isinstance(v, JSTransformer) and v.name not in BUILTINS
+		}
+
+	def transpile(self) -> str:
+		"""Transpile this JsFunction to JavaScript code.
+
+		Returns the complete JavaScript function code.
+		"""
+
+		# Get source code
+		src = getsourcecode(self.fn)
+		src = textwrap.dedent(src)
+
+		# Parse to AST
+		module = ast.parse(src)
+		fndefs = [
+			n
+			for n in module.body
+			if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
+		]
+		if not fndefs:
+			raise JSCompilationError("No function definition found in source")
+		fndef = fndefs[-1]
+
+		# Get argument names
+		arg_names = [arg.arg for arg in fndef.args.args]
+
+		# Transpile - pass deps directly, transpiler handles dispatch
+		visitor = JsTranspiler(fndef, args=arg_names, deps=self.deps)
+		js_fn = visitor.transpile(name=self.js_name)
+		return js_fn.emit()
+
+
+def analyze_code_object(
+	fn: Callable[..., object],
+) -> tuple[dict[str, Any], set[str]]:
+	"""Analyze code object and resolve globals + closure variables.
+
+	Returns a tuple of:
+	    - effective_globals: dict mapping names to their values (includes closure vars)
+	    - all_names: set of all names referenced in the code (including nested functions)
+	"""
+	code = fn.__code__
+
+	# Collect all names from code object and nested functions in one pass
+	seen_codes: set[int] = set()
+	all_names: set[str] = set()
+
+	def walk_code(c: pytypes.CodeType) -> None:
+		if id(c) in seen_codes:
+			return
+		seen_codes.add(id(c))
+		all_names.update(c.co_names)
+		all_names.update(c.co_freevars)  # Include closure variables
+		for const in c.co_consts:
+			if isinstance(const, pytypes.CodeType):
+				walk_code(const)
+
+	walk_code(code)
+
+	# Build effective globals dict: start with function's globals, then add closure values
+	effective_globals = dict(fn.__globals__)
+
+	# Resolve closure variables from closure cells
+	if code.co_freevars and fn.__closure__:
+		closure = fn.__closure__
+		for i, freevar_name in enumerate(code.co_freevars):
+			if i < len(closure):
+				cell = closure[i]
+				# Get the value from the closure cell
+				try:
+					effective_globals[freevar_name] = cell.cell_contents
+				except ValueError:
+					# Cell is empty (unbound), skip it
+					pass
+
+	return effective_globals, all_names
+
+
+def javascript(fn: Callable[[*Args], R]) -> JsFunction[*Args, R]:
+	"""Decorator to convert a function into a JsFunction.
+
+	Usage:
+	    @javascript
+	    def my_func(x: int) -> int:
+	        return x + 1
+
+	    # my_func is now a JsFunction instance
+	"""
+	result = FUNCTION_CACHE.get(fn)
+	if not result:
+		result = JsFunction(fn)
+		FUNCTION_CACHE[fn] = result
+	return result  # pyright: ignore[reportReturnType]
+
+
+def registered_functions() -> list[AnyJsFunction]:
+	"""Get all registered JS functions."""
+	return list(FUNCTION_CACHE.values())
+
+
+X = JsFunction[int]

pulse/transpiler/ids.py

@@ -0,0 +1,16 @@
+"""Unique ID generator for JavaScript codegen."""
+
+from itertools import count
+
+_counter = count(1)
+
+
+def generate_id() -> str:
+	"""Generate unique hex ID like '1', '2', 'a', 'ff', etc."""
+	return f"{next(_counter):x}"
+
+
+def reset_id_counter() -> None:
+	"""Reset counter (for testing)."""
+	global _counter
+	_counter = count(1)