jaclang 0.8.8__py3-none-any.whl → 0.8.10__py3-none-any.whl

jaclang/runtimelib/archetype.py

@@ -69,13 +69,13 @@ class AnchorReport:
     context: dict[str, Any]
 
 
-DataSpatialFilter: TypeAlias = (
+ObjectSpatialFilter: TypeAlias = (
     Callable[["Archetype"], bool] | "Archetype" | list["Archetype"] | None
 )
 
 
 @dataclass(eq=False, repr=False)
-class DataSpatialDestination:
+class ObjectSpatialDestination:
     """Object-Spatial Destination."""
 
     direction: EdgeDir
@@ -92,18 +92,18 @@ class DataSpatialDestination:
 
 
 @dataclass(eq=False, repr=False)
-class DataSpatialPath:
+class ObjectSpatialPath:
     """Object-Spatial Path."""
 
     origin: list[NodeArchetype]
-    destinations: list[DataSpatialDestination]
+    destinations: list[ObjectSpatialDestination]
     edge_only: bool
     from_visit: bool
 
     def __init__(
         self,
         origin: NodeArchetype | list[NodeArchetype],
-        destinations: list[DataSpatialDestination] | None = None,
+        destinations: list[ObjectSpatialDestination] | None = None,
     ) -> None:
         """Override Init."""
         if not isinstance(origin, list):
@@ -115,7 +115,7 @@ class DataSpatialPath:
 
     def convert(
         self,
-        filter: DataSpatialFilter,
+        filter: ObjectSpatialFilter,
     ) -> Callable[["Archetype"], bool] | None:
         """Convert filter."""
         if not filter:
@@ -129,44 +129,44 @@ class DataSpatialPath:
     def append(
         self,
         direction: EdgeDir,
-        edge: DataSpatialFilter,
-        node: DataSpatialFilter,
-    ) -> DataSpatialPath:
+        edge: ObjectSpatialFilter,
+        node: ObjectSpatialFilter,
+    ) -> ObjectSpatialPath:
         """Append destination."""
         self.destinations.append(
-            DataSpatialDestination(direction, self.convert(edge), self.convert(node))
+            ObjectSpatialDestination(direction, self.convert(edge), self.convert(node))
         )
         return self
 
-    def _out(
-        self, edge: DataSpatialFilter = None, node: DataSpatialFilter = None
-    ) -> DataSpatialPath:
+    def edge_out(
+        self, edge: ObjectSpatialFilter = None, node: ObjectSpatialFilter = None
+    ) -> ObjectSpatialPath:
         """Override greater than function."""
         return self.append(EdgeDir.OUT, edge, node)
 
-    def _in(
-        self, edge: DataSpatialFilter = None, node: DataSpatialFilter = None
-    ) -> DataSpatialPath:
+    def edge_in(
+        self, edge: ObjectSpatialFilter = None, node: ObjectSpatialFilter = None
+    ) -> ObjectSpatialPath:
         """Override greater than function."""
         return self.append(EdgeDir.IN, edge, node)
 
-    def _any(
-        self, edge: DataSpatialFilter = None, node: DataSpatialFilter = None
-    ) -> DataSpatialPath:
+    def edge_any(
+        self, edge: ObjectSpatialFilter = None, node: ObjectSpatialFilter = None
+    ) -> ObjectSpatialPath:
         """Override greater than function."""
         return self.append(EdgeDir.ANY, edge, node)
 
-    def edge(self) -> DataSpatialPath:
+    def edge(self) -> ObjectSpatialPath:
         """Set edge only."""
         self.edge_only = True
         return self
 
-    def visit(self) -> DataSpatialPath:
+    def visit(self) -> ObjectSpatialPath:
         """Set from visit."""
         self.from_visit = True
         return self
 
-    def repr_builder(self, repr: str, dest: DataSpatialDestination, mark: str) -> str:
+    def repr_builder(self, repr: str, dest: ObjectSpatialDestination, mark: str) -> str:
         """Repr builder."""
         repr += mark
         repr += f' (edge{" filter" if dest.edge else ""}) '
@@ -361,8 +361,8 @@ class ObjectAnchor(Anchor):
 class Archetype:
     """Archetype Protocol."""
 
-    _jac_entry_funcs_: ClassVar[list[DataSpatialFunction]] = []
-    _jac_exit_funcs_: ClassVar[list[DataSpatialFunction]] = []
+    _jac_entry_funcs_: ClassVar[list[ObjectSpatialFunction]] = []
+    _jac_exit_funcs_: ClassVar[list[ObjectSpatialFunction]] = []
 
     @cached_property
     def __jac__(self) -> Anchor:
@@ -454,7 +454,7 @@ class Root(NodeArchetype):
 
 
 @dataclass(eq=False)
-class DataSpatialFunction:
+class ObjectSpatialFunction:
     """Object-Spatial Function."""
 
     name: str

jaclang/runtimelib/client_bundle.py

@@ -0,0 +1,169 @@
+"""Client bundle generation utilities for Jac web front-ends."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any, Iterable, Sequence
+
+from jaclang.compiler.program import JacProgram
+
+
+class ClientBundleError(RuntimeError):
+    """Raised when the client bundle cannot be generated."""
+
+
+@dataclass(slots=True)
+class ClientBundle:
+    """Container for a compiled client bundle."""
+
+    module_name: str
+    code: str
+    client_functions: list[str]
+    client_globals: list[str]
+    hash: str
+
+
+@dataclass(slots=True)
+class _CachedBundle:
+    signature: str
+    bundle: ClientBundle
+
+
+class ClientBundleBuilder:
+    """Compile Jac modules and runtime support into a browser-ready bundle."""
+
+    def __init__(self, runtime_path: Path | None = None) -> None:
+        """Initialise the builder with an optional override for the runtime path."""
+        self.runtime_path = runtime_path or Path(__file__).with_name(
+            "client_runtime.jac"
+        )
+        self._cache: dict[str, _CachedBundle] = {}
+
+    def build(self, module: ModuleType, force: bool = False) -> ClientBundle:
+        """Build (or reuse) a client bundle for the supplied module."""
+        # Derive source path from module __file__ (replace .py with .jac)
+        if not hasattr(module, "__file__") or not module.__file__:
+            raise ClientBundleError(
+                f"Module '{module.__name__}' has no __file__ attribute"
+            )
+        module_path = module.__file__.replace(".py", ".jac")
+
+        source_path = Path(module_path).resolve()
+        runtime_path = self.runtime_path.resolve()
+        signature = self._signature([source_path, runtime_path])
+
+        cached = self._cache.get(module.__name__)
+        if not force and cached and cached.signature == signature:
+            return cached.bundle
+
+        bundle = self._compile_bundle(module, source_path, runtime_path)
+        self._cache[module.__name__] = _CachedBundle(signature=signature, bundle=bundle)
+        return bundle
+
+    def _compile_bundle(
+        self,
+        module: ModuleType,
+        module_path: Path,
+        runtime_path: Path,
+    ) -> ClientBundle:
+        """Compile bundle pieces and stitch them together."""
+        runtime_js = self._compile_to_js(runtime_path)
+
+        # Get manifest from JacProgram
+        from jaclang.runtimelib.machine import JacMachine as Jac
+
+        mod = Jac.program.mod.hub.get(str(module_path))
+        manifest = mod.gen.client_manifest if mod else None
+
+        module_js = self._compile_to_js(module_path)
+
+        client_exports = sorted(dict.fromkeys(manifest.exports)) if manifest else []
+
+        client_globals_map: dict[str, Any] = {}
+        if manifest:
+            for name in manifest.globals:
+                if name in manifest.globals_values:
+                    client_globals_map[name] = manifest.globals_values[name]
+                elif hasattr(module, name):
+                    client_globals_map[name] = getattr(module, name)
+                else:
+                    client_globals_map[name] = None
+        client_globals_map = {
+            key: client_globals_map[key] for key in sorted(client_globals_map)
+        }
+
+        registration_js = self._generate_registration_js(
+            module.__name__, client_exports, client_globals_map
+        )
+
+        bundle_pieces = [
+            "// Jac client runtime",
+            runtime_js,
+            "",
+            f"// Client module: {module.__name__}",
+            module_js,
+            "",
+            registration_js,
+        ]
+        bundle_code = "\n".join(piece for piece in bundle_pieces if piece is not None)
+        bundle_hash = hashlib.sha256(bundle_code.encode("utf-8")).hexdigest()
+
+        return ClientBundle(
+            module_name=module.__name__,
+            code=bundle_code,
+            client_functions=client_exports,
+            client_globals=list(client_globals_map.keys()),
+            hash=bundle_hash,
+        )
+
+    def _compile_to_js(self, source_path: Path) -> str:
+        """Compile the provided Jac file into JavaScript."""
+        program = JacProgram()
+        mod = program.compile(str(source_path))
+        if program.errors_had:
+            formatted = "\n".join(str(err) for err in program.errors_had)
+            raise ClientBundleError(
+                f"Failed to compile '{source_path}' for client bundle:\n{formatted}"
+            )
+        return mod.gen.js or ""
+
+    @staticmethod
+    def _signature(paths: Iterable[Path]) -> str:
+        """Compute a cache signature based on file modification times."""
+        parts: list[str] = []
+        for path in paths:
+            try:
+                stat = path.stat()
+                parts.append(f"{path}:{stat.st_mtime_ns}")
+            except FileNotFoundError:
+                parts.append(f"{path}:missing")
+        return hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _generate_registration_js(
+        module_name: str,
+        client_functions: Sequence[str],
+        client_globals: dict[str, Any],
+    ) -> str:
+        """Generate registration code that exposes client symbols globally."""
+        globals_entries: list[str] = []
+        for name, value in client_globals.items():
+            identifier = json.dumps(name)
+            try:
+                value_literal = json.dumps(value)
+            except TypeError:
+                value_literal = "null"
+            globals_entries.append(f"{identifier}: {value_literal}")
+
+        globals_literal = (
+            "{ " + ", ".join(globals_entries) + " }" if globals_entries else "{}"
+        )
+        functions_literal = json.dumps(list(client_functions))
+        module_literal = json.dumps(module_name)
+
+        # Use the registration function from client_runtime.jac
+        return f"__jacRegisterClientModule({module_literal}, {functions_literal}, {globals_literal});"