pulse-framework 0.1.62__py3-none-any.whl

pulse/transpiler/imports.py

@@ -0,0 +1,341 @@
+"""Import with auto-registration for transpiler."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from pathlib import Path
+from typing import (
+	Any,
+	ParamSpec,
+	TypeAlias,
+	TypeVar,
+	override,
+)
+from typing import Literal as Lit
+
+from pulse.cli.packages import pick_more_specific
+from pulse.transpiler.assets import LocalAsset, register_local_asset
+from pulse.transpiler.errors import TranspileError
+from pulse.transpiler.id import next_id
+from pulse.transpiler.nodes import Call, Expr, to_js_identifier
+from pulse.transpiler.vdom import VDOMExpr
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+ImportKind: TypeAlias = Lit["named", "default", "namespace", "side_effect"]
+
+# JS-like extensions to try when resolving imports without extension (ESM convention)
+_JS_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".mts")
+
+
+def caller_file(depth: int = 2) -> Path:
+	"""Get the file path of the caller."""
+	frame = inspect.currentframe()
+	try:
+		for _ in range(depth):
+			if frame is None:
+				raise RuntimeError("Could not determine caller file")
+			frame = frame.f_back
+		if frame is None:
+			raise RuntimeError("Could not determine caller file")
+		return Path(frame.f_code.co_filename)
+	finally:
+		del frame
+
+
+def is_relative_path(path: str) -> bool:
+	"""Check if path is a relative import (starts with ./ or ../)."""
+	return path.startswith("./") or path.startswith("../")
+
+
+def is_absolute_path(path: str) -> bool:
+	"""Check if path is an absolute filesystem path."""
+	return path.startswith("/")
+
+
+def is_local_path(path: str) -> bool:
+	"""Check if path is a local file path (relative or absolute)."""
+	return is_relative_path(path) or is_absolute_path(path)
+
+
+def resolve_js_file(base_path: Path) -> Path | None:
+	"""Resolve a JS-like import path to an actual file.
+
+	Follows ESM resolution order:
+	1. Exact path (if has extension)
+	2. Try JS extensions: .ts, .tsx, .js, .jsx, .mjs, .mts
+	3. Try /index with each extension
+
+	Returns None if no file is found.
+	"""
+	# If path already has an extension that exists, use it
+	if base_path.suffix and base_path.exists():
+		return base_path
+
+	# If no extension, try JS-like extensions
+	if not base_path.suffix:
+		for ext in _JS_EXTENSIONS:
+			candidate = base_path.with_suffix(ext)
+			if candidate.exists():
+				return candidate
+
+		# Try /index with each extension
+		for ext in _JS_EXTENSIONS:
+			candidate = base_path / f"index{ext}"
+			if candidate.exists():
+				return candidate
+
+	return None
+
+
+def resolve_local_path(path: str, caller: Path | None = None) -> Path | None:
+	"""Resolve a local import path to an actual file.
+
+	For relative paths, resolves relative to caller.
+	For absolute paths, uses the path directly.
+
+	For paths without extensions, tries JS-like resolution.
+	Falls back to the raw resolved path if the file doesn't exist
+	(might be a generated file or future file).
+
+	Returns None only for non-local paths or relative paths without a caller.
+	"""
+	if is_relative_path(path):
+		if caller is None:
+			return None
+		base_path = (caller.parent / Path(path)).resolve()
+	elif is_absolute_path(path):
+		base_path = Path(path).resolve()
+	else:
+		return None
+
+	# If the path has an extension, return it (even if it doesn't exist)
+	if base_path.suffix:
+		return base_path
+
+	# Try JS-like resolution for existing files
+	resolved = resolve_js_file(base_path)
+	if resolved is not None:
+		return resolved
+
+	# Fallback: return the base path even if the file doesn't exist
+	return base_path
+
+
+# Registry key depends on kind and lazy:
+# - named: (name, src, "named", lazy)
+# - default/namespace/side_effect: ("", src, kind, lazy) - only one per src
+_ImportKey: TypeAlias = tuple[str, str, str, bool]
+_IMPORT_REGISTRY: dict[_ImportKey, "Import"] = {}
+
+
+def get_registered_imports() -> list["Import"]:
+	"""Get all registered imports."""
+	return list(_IMPORT_REGISTRY.values())
+
+
+def clear_import_registry() -> None:
+	"""Clear the import registry."""
+	_IMPORT_REGISTRY.clear()
+
+
+@dataclass(slots=True, init=False)
+class Import(Expr):
+	"""JS import that auto-registers and dedupes.
+
+	An Expr that emits as its unique identifier (e.g., useState_1).
+	Overrides transpile_call for JSX component behavior and transpile_getattr for
+	member access.
+
+	Examples:
+		# Named import: import { useState } from "react"
+		useState = Import("useState", "react")
+
+		# Default import: import React from "react"
+		React = Import("react")
+
+		# Namespace import: import * as React from "react"
+		React = Import("*", "react")
+
+		# Side-effect import: import "./styles.css"
+		Import("./styles.css", side_effect=True)
+
+		# Type-only import: import type { Props } from "./types"
+		Props = Import("Props", "./types", is_type=True)
+
+		# JSX component import - wrap in Jsx() to create elements
+		Button = Jsx(Import("Button", "@mantine/core"))
+		# Button("Click me", disabled=True) -> <Button_1 disabled={true}>Click me</Button_1>
+
+		# Local file imports (relative or absolute paths)
+		Import("./styles.css", side_effect=True)  # Local CSS
+		utils = Import("*", "./utils")  # Local JS namespace (resolves extension)
+		config = Import("/absolute/path/config")  # Absolute path default import
+
+		# Lazy import (generates factory for code-splitting)
+		Chart = Import("./Chart", lazy=True)
+		# Generates: const Chart_1 = () => import("./Chart")
+	"""
+
+	name: str
+	src: str
+	kind: ImportKind
+	is_type: bool
+	lazy: bool
+	before: tuple[str, ...]
+	id: str
+	version: str | None = None
+	asset: LocalAsset | None = (
+		None  # Registered local asset (for copying during codegen)
+	)
+
+	def __init__(
+		self,
+		name: str,
+		src: str | None = None,
+		*,
+		side_effect: bool = False,
+		is_type: bool = False,
+		lazy: bool = False,
+		version: str | None = None,
+		before: tuple[str, ...] | list[str] = (),
+		_caller_depth: int = 2,
+	) -> None:
+		if src is None:
+			if name == "*":
+				raise TypeError("Import('*') requires a source")
+			src = name
+			if side_effect:
+				name = ""
+				kind: ImportKind = "side_effect"
+			else:
+				kind = "default"
+		else:
+			if side_effect:
+				raise TypeError("side_effect imports cannot specify a name")
+			if name == "*":
+				name = src
+				kind = "namespace"
+			else:
+				if not name:
+					raise TypeError("Import(name, src) requires a non-empty name")
+				kind = "named"
+
+		# Validate: lazy imports cannot be type-only
+		if lazy and is_type:
+			raise TranspileError("Import cannot be both lazy and type-only")
+
+		# Auto-resolve local paths (relative or absolute) to actual files
+		asset: LocalAsset | None = None
+		import_src = src
+
+		if is_local_path(src):
+			# Resolve to actual file (handles JS extension resolution)
+			caller = caller_file(depth=_caller_depth) if is_relative_path(src) else None
+			resolved = resolve_local_path(src, caller)
+			if resolved is not None:
+				# Register with unified asset registry
+				asset = register_local_asset(resolved)
+				import_src = str(resolved)
+
+		self.name = name
+		self.src = import_src
+		self.kind = kind
+		self.version = version
+		self.lazy = lazy
+		self.asset = asset
+
+		before_tuple = tuple(before) if isinstance(before, list) else before
+
+		# Dedupe key: includes lazy flag to keep lazy and eager imports separate
+		if kind == "named":
+			key: _ImportKey = (name, import_src, "named", lazy)
+		else:
+			key = ("", import_src, kind, lazy)
+
+		if key in _IMPORT_REGISTRY:
+			existing = _IMPORT_REGISTRY[key]
+
+			# Merge: type-only + regular = regular
+			if existing.is_type and not is_type:
+				existing.is_type = False
+
+			# Merge: union of before constraints
+			if before_tuple:
+				merged_before = set(existing.before) | set(before_tuple)
+				existing.before = tuple(sorted(merged_before))
+
+			# Merge: version
+			existing.version = pick_more_specific(existing.version, version)
+
+			# Reuse ID and merged values
+			self.id = existing.id
+			self.is_type = existing.is_type
+			self.before = existing.before
+			self.version = existing.version
+		else:
+			# New import
+			self.id = next_id()
+			self.is_type = is_type
+			self.before = before_tuple
+			_IMPORT_REGISTRY[key] = self
+
+	@property
+	def js_name(self) -> str:
+		"""Unique JS identifier for this import."""
+		return f"{to_js_identifier(self.name)}_{self.id}"
+
+	@property
+	def is_local(self) -> bool:
+		"""Check if this is a local file import (has registered asset)."""
+		return self.asset is not None
+
+	@property
+	def is_lazy(self) -> bool:
+		"""Check if this is a lazy import."""
+		return self.lazy
+
+	# Convenience properties for kind checks
+	@property
+	def is_default(self) -> bool:
+		return self.kind == "default"
+
+	@property
+	def is_namespace(self) -> bool:
+		return self.kind == "namespace"
+
+	@property
+	def is_side_effect(self) -> bool:
+		return self.kind == "side_effect"
+
+	# -------------------------------------------------------------------------
+	# Expr.emit: outputs the unique identifier
+	# -------------------------------------------------------------------------
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		"""Emit this import as its unique JS identifier."""
+		out.append(self.js_name)
+
+	@override
+	def render(self) -> VDOMExpr:
+		"""Render as a registry reference."""
+		return {"t": "ref", "key": self.id}
+
+	# -------------------------------------------------------------------------
+	# Python dunder methods: allow natural syntax in @javascript functions
+	# -------------------------------------------------------------------------
+
+	# Overloads for __call__:
+	# 1. Decorator usage: @Import(...) def fn(...) -> returns fn's type
+	# 2. Expression usage: Import(...)(...) -> returns Call
+
+	@override
+	def __call__(self, *args: Any, **kwargs: Any) -> "Call":
+		"""Allow calling Import objects in Python code.
+
+		Returns a Call expression.
+		"""
+		return Expr.__call__(self, *args, **kwargs)

pulse/transpiler/js_module.py

@@ -0,0 +1,336 @@
+"""Core infrastructure for JavaScript module bindings in transpiler.
+
+JS modules are Python modules that map to JavaScript modules/builtins.
+Registration is done by calling register_js_module() from within the module itself.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import sys
+from dataclasses import dataclass, field
+from typing import Any, Literal, override
+
+from pulse.code_analysis import is_stub_function
+from pulse.transpiler.errors import TranspileError
+from pulse.transpiler.imports import Import
+from pulse.transpiler.nodes import (
+	Expr,
+	Identifier,
+	Jsx,
+	Member,
+	New,
+)
+from pulse.transpiler.transpiler import Transpiler
+
+_MODULE_DUNDERS = frozenset(
+	{
+		"__name__",
+		"__file__",
+		"__doc__",
+		"__package__",
+		"__path__",
+		"__cached__",
+		"__loader__",
+		"__spec__",
+		"__builtins__",
+		"__annotations__",
+	}
+)
+
+
+@dataclass(slots=True)
+class Class(Expr):
+	"""Expr wrapper that emits calls as `new ...(...)`.
+
+	Must also behave like the wrapped expression for attribute access,
+	so patterns like `Promise.resolve(...)` work even if `Promise(...)` emits
+	as `new Promise(...)`.
+	"""
+
+	ctor: Expr
+	name: str = ""
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		self.ctor.emit(out)
+
+	@override
+	def render(self):
+		return self.ctor.render()
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		keywords: list[ast.keyword],
+		ctx: Transpiler,
+	) -> Expr:
+		if keywords:
+			raise TranspileError("Keyword arguments not supported in constructor call")
+		return New(self.ctor, [ctx.emit_expr(a) for a in args])
+
+	@override
+	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
+		# Convention: trailing underscore escapes Python keywords (e.g. from_ -> from, is_ -> is)
+		js_attr = attr[:-1] if attr.endswith("_") else attr
+		return Member(self.ctor, js_attr)
+
+
+@dataclass(frozen=True)
+class JsModule(Expr):
+	"""Expr representing a JavaScript module binding.
+
+	Attributes:
+		name: The JavaScript identifier for the module binding (e.g., "Math", "React"),
+			or None for "global identifier" modules with no module expression.
+		py_name: Python module name for error messages (e.g., "pulse.js.math")
+		src: Import source path. None for builtins.
+		kind: Import kind - "default" or "namespace"
+		values: How attribute access is expressed:
+			- "member": Access as property (e.g., React.useState)
+			- "named_import": Each attribute is a named import (e.g., import { useState } from "react")
+		constructors: Set of names that are constructors (emit with 'new')
+		components: Set of names that are components (wrapped with Jsx)
+	"""
+
+	name: str | None
+	py_name: str = ""
+	src: str | None = None
+	kind: Literal["default", "namespace"] = "namespace"
+	values: Literal["member", "named_import"] = "named_import"
+	constructors: frozenset[str] = field(default_factory=frozenset)
+	components: frozenset[str] = field(default_factory=frozenset)
+
+	@override
+	def emit(self, out: list[str]) -> None:
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be emitted directly - access an attribute")
+
+	@override
+	def render(self):
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be rendered directly - access an attribute")
+
+	@override
+	def transpile_call(
+		self,
+		args: list[ast.expr],
+		keywords: list[ast.keyword],
+		ctx: Transpiler,
+	) -> Expr:
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be called directly - access an attribute")
+
+	@override
+	def transpile_getattr(self, attr: str, ctx: Transpiler) -> Expr:
+		return self.get_value(attr)
+
+	@override
+	def transpile_subscript(self, key: ast.expr, ctx: Transpiler) -> Expr:
+		label = self.py_name or self.name or "JsModule"
+		raise TypeError(f"{label} cannot be subscripted")
+
+	@property
+	def is_builtin(self) -> bool:
+		return self.src is None
+
+	def to_expr(self) -> Identifier | Import:
+		"""Generate the appropriate Expr for this module.
+
+		Returns Identifier for builtins, Import for external modules.
+
+		Raises TranspileError if name is None (module imports are disallowed).
+		"""
+		if self.name is None:
+			label = self.py_name or "JS global module"
+			# If a module has no JS module expression, importing it as a module value is meaningless.
+			# Users should import members from the Python module instead.
+			if self.py_name:
+				msg = (
+					f"Cannot import module '{label}' directly. "
+					+ f"Use 'from {self.py_name} import ...' instead."
+				)
+			else:
+				msg = f"Cannot import module '{label}' directly."
+			raise TranspileError(msg)
+
+		if self.src is None:
+			return Identifier(self.name)
+
+		if self.kind == "default":
+			return Import(self.src)
+		return Import("*", self.src)
+
+	def get_value(self, name: str) -> Member | Class | Jsx | Identifier | Import:
+		"""Get a member of this module as an expression.
+
+		For global-identifier modules (name=None): returns Identifier directly (e.g., Set -> Set)
+			These are "virtual" Python modules exposing JS globals - no actual JS module exists.
+		For builtin namespaces (src=None): returns Member (e.g., Math.floor)
+		For external modules with "member" style: returns Member (e.g., React.useState)
+		For external modules with "named_import" style: returns a named Import
+
+		If name is in constructors, returns a Class that emits `new ...(...)`.
+		If name is in components, returns a Jsx-wrapped expression.
+		"""
+		# Convention: trailing underscore escapes Python keywords (e.g. from_ -> from, is_ -> is).
+		# We keep the original `name` for constructor detection, but emit the JS name.
+		js_name = name[:-1] if name.endswith("_") else name
+
+		expr: Member | Identifier | Import
+		if self.name is None:
+			# Virtual module exposing JS globals - members are just identifiers
+			expr = Identifier(js_name)
+		elif self.src is None:
+			# Builtin namespace (Math, console, etc.) - members accessed as properties
+			expr = Member(Identifier(self.name), js_name)
+		elif self.values == "named_import":
+			expr = Import(js_name, self.src)
+		else:
+			expr = Member(self.to_expr(), js_name)
+
+		if name in self.constructors:
+			return Class(expr, name=name)
+		if name in self.components:
+			return Jsx(expr)
+		return expr
+
+	@override
+	@staticmethod
+	def register(  # pyright: ignore[reportIncompatibleMethodOverride]
+		*,
+		name: str | None,
+		src: str | None = None,
+		kind: Literal["default", "namespace"] = "namespace",
+		values: Literal["member", "named_import"] = "named_import",
+	) -> None:
+		"""Register the calling Python module as a JavaScript module binding.
+
+			Must be called from within the module being registered. The module is
+			automatically detected from the call stack.
+
+			This function sets up __getattr__ on the module for dynamic attribute access,
+			and registers the module object in EXPR_REGISTRY so it can be used as a
+			dependency (e.g., `import pulse.js.math as Math`) during transpilation.
+
+			Args:
+				name: The JavaScript identifier for the module binding (e.g., "Math"), or None
+					for modules that expose only global identifiers and cannot be imported as a whole.
+				src: Import source path. None for builtins.
+				kind: Import kind - "default" or "namespace"
+				values: How attribute access works:
+					- "member": Access as property (e.g., Math.sin, React.useState)
+					- "named_import": Each attribute is a named import
+
+		Example (inside pulse/js/math.py):
+			JsModule.register(name="Math")  # builtin
+
+		Example (inside pulse/js/react.py):
+			JsModule.register(name="React", src="react")  # namespace + named imports
+
+		Example (inside pulse/js/set.py):
+			JsModule.register(name=None)  # global identifier builtin (no module binding)
+		"""
+		from pulse.component import Component  # Import here to avoid cycles
+
+		# Get the calling module from the stack frame
+		frame = inspect.currentframe()
+		assert frame is not None and frame.f_back is not None
+		module_name = frame.f_back.f_globals["__name__"]
+		module = sys.modules[module_name]
+
+		# Collect locally defined names and clean up module namespace.
+		# Priority order for categorization:
+		#   1. Overrides: real functions (with body), Exprs, real @components → returned directly
+		#   2. Components: stub @component functions → wrapped as Jsx(Import(...))
+		#   3. Constructors: classes → emitted with 'new' keyword
+		#   4. Regular imports: stub functions → standard named imports
+		constructors: set[str] = set()
+		components: set[str] = set()
+		local_names: set[str] = set()
+		overrides: dict[str, Any] = {}
+
+		for attr_name in list(vars(module)):
+			if attr_name in _MODULE_DUNDERS or attr_name.startswith("_"):
+				continue
+
+			obj = getattr(module, attr_name)
+
+			# Component-wrapped function - check the raw function's module
+			if isinstance(obj, Component):
+				raw_fn = obj._raw_fn  # pyright: ignore[reportPrivateUsage]
+				fn_module = getattr(raw_fn, "__module__", None)
+				if fn_module != module_name:
+					delattr(module, attr_name)
+					continue
+				if is_stub_function(raw_fn):
+					# Stub component → becomes Jsx(Import(...))
+					components.add(attr_name)
+					local_names.add(attr_name)
+				else:
+					# Real component → preserve as override
+					overrides[attr_name] = obj
+				delattr(module, attr_name)
+				continue
+
+			is_local = not hasattr(obj, "__module__") or obj.__module__ == module_name
+			if not is_local:
+				delattr(module, attr_name)
+				continue
+
+			# Existing Expr (e.g., manually created Jsx)
+			if isinstance(obj, Expr):
+				overrides[attr_name] = obj
+				delattr(module, attr_name)
+				continue
+
+			# Real function with body → preserve as override
+			if inspect.isfunction(obj) and not is_stub_function(obj):
+				overrides[attr_name] = obj
+				delattr(module, attr_name)
+				continue
+
+			# Class → constructor (existing behavior)
+			if inspect.isclass(obj):
+				constructors.add(attr_name)
+				local_names.add(attr_name)
+				delattr(module, attr_name)
+				continue
+
+			# Stub function → regular import (existing behavior)
+			local_names.add(attr_name)
+			delattr(module, attr_name)
+
+		# Add annotated constants to local_names
+		if hasattr(module, "__annotations__"):
+			for ann_name in module.__annotations__:
+				if not ann_name.startswith("_"):
+					local_names.add(ann_name)
+			module.__annotations__.clear()
+
+		# Invariants: a module without a JS module binding cannot be imported from a JS source.
+		if name is None and src is not None:
+			raise ValueError("name=None is only supported for builtins (src=None)")
+
+		js_module = JsModule(
+			name=name,
+			py_name=module.__name__,
+			src=src,
+			kind=kind,
+			values=values,
+			constructors=frozenset(constructors),
+			components=frozenset(components),
+		)
+		# Register the module object itself so `import pulse.js.math as Math` resolves via EXPR_REGISTRY.
+		Expr.register(module, js_module)
+
+		def __getattr__(name: str) -> Member | Class | Jsx | Identifier | Import | Any:
+			if name in overrides:
+				return overrides[name]
+			if name.startswith("_") or name not in local_names:
+				raise AttributeError(name)
+			return js_module.get_value(name)
+
+		module.__getattr__ = __getattr__  # type: ignore[method-assign]

pulse/transpiler/modules/__init__.py

@@ -0,0 +1,33 @@
+"""Central registration point for all module transpilers.
+
+This module registers all built-in Python modules for transpilation.
+Import this module to ensure all transpilers are available.
+"""
+
+import asyncio as asyncio_builtin
+import json as json_builtin
+import math as math_builtin
+import typing as typing_builtin
+
+import pulse as pulse_module
+import pulse.dom.tags as pulseTags
+from pulse.transpiler.modules.asyncio import PyAsyncio
+from pulse.transpiler.modules.json import PyJson
+from pulse.transpiler.modules.math import PyMath
+from pulse.transpiler.modules.pulse.tags import PulseTags
+from pulse.transpiler.modules.typing import PyTyping
+from pulse.transpiler.py_module import PyModule
+
+# Register built-in Python modules
+PyModule.register(math_builtin, PyMath)
+PyModule.register(json_builtin, PyJson)
+PyModule.register(asyncio_builtin, PyAsyncio)
+PyModule.register(typing_builtin, PyTyping)
+
+# Register Pulse DOM tags for JSX transpilation
+# This covers `from pulse.dom import tags; tags.div(...)`
+PyModule.register(pulseTags, PulseTags)
+
+# Register main pulse module for transpilation
+# This covers `import pulse as ps; ps.div(...)`
+PyModule.register(pulse_module, PulseTags)