ourui 0.1.0__py3-none-any.whl

ourui/__init__.py

@@ -0,0 +1,6 @@
+"""OurUI authoring surface and compiler package."""
+
+from ourui.ui import Component, State, component, server, ui
+
+__all__ = ["ui", "server", "State", "Component", "component"]
+__version__ = "0.1.0"

ourui/analysis/__init__.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ourui.analysis.components import (
+    collect_components,
+    component_call_name,
+    expand_component_call,
+)
+from ourui.node import THEME_ATTR_KEYS, Node
+from ourui.parse import call_kind, literal_value, parse_file, span_for
+from ourui.theme import apply_theme_overrides, default_tokens, theme_kwargs_to_overrides
+
+
+@dataclass
+class SemanticGraph:
+    nodes: dict[str, Node] = field(default_factory=dict)
+    roots: list[str] = field(default_factory=list)
+    edges: list[dict[str, str]] = field(default_factory=list)
+    handlers: dict[str, dict[str, Any]] = field(default_factory=dict)
+    states: dict[str, dict[str, Any]] = field(default_factory=dict)
+    components: dict[str, dict[str, Any]] = field(default_factory=dict)
+    routes: dict[str, str] = field(default_factory=dict)
+    tokens: dict[str, dict[str, str]] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "nodes": {nid: n.to_dict() for nid, n in sorted(self.nodes.items())},
+            "roots": list(self.roots),
+            "routes": {k: self.routes[k] for k in sorted(self.routes)},
+            "edges": sorted(self.edges, key=lambda e: (e["from"], e["to"], e["kind"])),
+            "handlers": {k: self.handlers[k] for k in sorted(self.handlers)},
+            "states": {k: self.states[k] for k in sorted(self.states)},
+            "components": {k: self.components[k] for k in sorted(self.components)},
+            "tokens": {
+                "light": {k: self.tokens.get("light", {})[k] for k in sorted(self.tokens.get("light", {}))},
+                "dark": {k: self.tokens.get("dark", {})[k] for k in sorted(self.tokens.get("dark", {}))},
+            },
+        }
+
+
+@dataclass
+class DependencyGraph:
+    edges: list[dict[str, str]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "edges": sorted(self.edges, key=lambda e: (e["from"], e["to"], e["kind"])),
+        }
+
+
+def _is_server_decorator(dec: ast.AST) -> bool:
+    if isinstance(dec, ast.Name) and dec.id == "server":
+        return True
+    if isinstance(dec, ast.Attribute) and dec.attr == "server":
+        return True
+    return False
+
+
+def _is_state_call(call: ast.Call) -> bool:
+    if isinstance(call.func, ast.Name) and call.func.id == "State":
+        return True
+    if isinstance(call.func, ast.Attribute) and call.func.attr == "State":
+        return True
+    return False
+
+
+def _is_theme_call(call: ast.Call) -> bool:
+    if isinstance(call.func, ast.Attribute) and call.func.attr == "Theme":
+        if isinstance(call.func.value, ast.Name) and call.func.value.id == "ui":
+            return True
+    if isinstance(call.func, ast.Name) and call.func.id == "Theme":
+        return True
+    return False
+
+
+class _GraphBuilder:
+    def __init__(self, path: str, components: dict) -> None:
+        self.path = path
+        self.counter = 0
+        self.graph = SemanticGraph(tokens=default_tokens())
+        self.dep = DependencyGraph()
+        self._theme_nodes: dict[str, str] = {}
+        self._page_route_by_node: dict[str, str] = {}
+        self.components = components
+        for name, cdef in components.items():
+            self.graph.components[name] = {
+                "name": name,
+                "style": cdef.style,
+                "params": list(cdef.params),
+                "line": cdef.span_line,
+            }
+
+    def next_id(self, prefix: str = "n") -> str:
+        self.counter += 1
+        return f"{prefix}{self.counter:04d}"
+
+    def theme_node(self, token: str, at: ast.AST) -> str:
+        if token in self._theme_nodes:
+            return self._theme_nodes[token]
+        nid = self.next_id("theme")
+        node = Node(
+            id=nid,
+            kind="ThemeToken",
+            span=span_for(self.path, at),
+            attributes={"token": token},
+            provenance=["analyze:theme_token"],
+        ).with_hash()
+        self.graph.nodes[nid] = node
+        self._theme_nodes[token] = nid
+        return nid
+
+    def register_handler(self, name: str, *, kind: str, at: ast.AST) -> None:
+        self.graph.handlers[name] = {
+            "name": name,
+            "kind": kind,
+            "span": span_for(self.path, at).to_dict(),
+        }
+
+    def register_state(self, name: str, call: ast.Call) -> None:
+        initial: Any = None
+        if call.args:
+            initial = literal_value(call.args[0])
+        self.graph.states[name] = {
+            "name": name,
+            "initial": initial,
+            "span": span_for(self.path, call).to_dict(),
+        }
+
+    def register_theme(self, call: ast.Call) -> None:
+        attrs: dict[str, Any] = {}
+        for kw in call.keywords:
+            if kw.arg is None:
+                continue
+            attrs[kw.arg] = literal_value(kw.value)
+        light, dark = theme_kwargs_to_overrides(attrs)
+        self.graph.tokens = apply_theme_overrides(self.graph.tokens, light=light, dark=dark)
+
+    def _maybe_state_ref(self, node: ast.AST) -> dict[str, str] | None:
+        if isinstance(node, ast.Name) and node.id in self.graph.states:
+            return {"__state__": node.id}
+        return None
+
+    def _resolve_call(self, call: ast.Call, trail: list[str]) -> tuple[ast.Call, list[str]]:
+        """Expand user components until a ui.* call remains."""
+        while component_call_name(call, self.components):
+            name = component_call_name(call, self.components)
+            assert name is not None
+            expanded = expand_component_call(call, self.components)
+            if expanded is None:
+                break
+            trail = [*trail, name]
+            call = expanded
+        return call, trail
+
+    def build_call(
+        self,
+        call: ast.Call,
+        parent_id: str | None = None,
+        expansion_trail: list[str] | None = None,
+    ) -> str | None:
+        trail = list(expansion_trail or [])
+        call, trail = self._resolve_call(call, trail)
+
+        kind = call_kind(call)
+        if kind is None:
+            return None
+
+        nid = self.next_id()
+        attrs: dict[str, Any] = {}
+        child_ids: list[str] = []
+
+        for arg in call.args:
+            if isinstance(arg, ast.Call):
+                cid = self.build_call(arg, parent_id=nid, expansion_trail=trail)
+                if cid:
+                    child_ids.append(cid)
+                    continue
+            if isinstance(arg, ast.List):
+                for elt in arg.elts:
+                    if isinstance(elt, ast.Call):
+                        cid = self.build_call(elt, parent_id=nid, expansion_trail=trail)
+                        if cid:
+                            child_ids.append(cid)
+                continue
+            state_ref = self._maybe_state_ref(arg)
+            if state_ref and kind in {"Button", "Text", "Card"} and "text" not in attrs:
+                attrs["text"] = state_ref
+                continue
+            val = literal_value(arg)
+            if isinstance(val, str):
+                if kind in {"Button", "Text", "Card"} and "text" not in attrs:
+                    attrs["text"] = val
+                elif "title" not in attrs:
+                    attrs["title"] = val
+                else:
+                    attrs.setdefault("_args", []).append(val)
+            else:
+                attrs.setdefault("_args", []).append(val)
+
+        for kw in call.keywords:
+            if kw.arg is None:
+                continue
+            if kw.arg == "children":
+                val_node = kw.value
+                if isinstance(val_node, (ast.List, ast.Tuple)):
+                    for elt in val_node.elts:
+                        if isinstance(elt, ast.Call):
+                            cid = self.build_call(elt, parent_id=nid, expansion_trail=trail)
+                            if cid:
+                                child_ids.append(cid)
+                elif isinstance(val_node, ast.Call):
+                    cid = self.build_call(val_node, parent_id=nid, expansion_trail=trail)
+                    if cid:
+                        child_ids.append(cid)
+                continue
+            if kw.arg == "route" and kind == "Page":
+                route_val = literal_value(kw.value)
+                if isinstance(route_val, str):
+                    self._page_route_by_node[nid] = route_val
+                continue
+            if kw.arg == "on_click":
+                if isinstance(kw.value, ast.Name):
+                    attrs["on_click"] = {"__handler__": kw.value.id}
+                elif isinstance(kw.value, ast.Constant) and isinstance(kw.value.value, str):
+                    attrs["on_click"] = {"__handler__": kw.value.value}
+                else:
+                    attrs["on_click"] = literal_value(kw.value)
+                continue
+            if kw.arg in {"text", "title", "subtitle", "bind"}:
+                state_ref = self._maybe_state_ref(kw.value)
+                if state_ref:
+                    if kw.arg == "bind":
+                        attrs["text"] = state_ref
+                    else:
+                        attrs[kw.arg] = state_ref
+                    continue
+            if isinstance(kw.value, ast.Call):
+                cid = self.build_call(kw.value, parent_id=nid, expansion_trail=trail)
+                if cid:
+                    attrs[kw.arg] = {"__node__": cid}
+                    child_ids.append(cid)
+                    continue
+            attrs[kw.arg] = literal_value(kw.value)
+
+        provenance = ["parse:ui_call", "analyze:semantic_graph", *[f"expand:{n}" for n in trail]]
+        node = Node(
+            id=nid,
+            kind=kind,
+            span=span_for(self.path, call),
+            attributes=attrs,
+            children=child_ids,
+            provenance=provenance,
+            metadata={"expanded_from": list(trail)} if trail else {},
+        ).with_hash()
+        self.graph.nodes[nid] = node
+
+        if parent_id:
+            self.graph.edges.append({"from": parent_id, "to": nid, "kind": "contains"})
+        else:
+            self.graph.roots.append(nid)
+            if kind == "Page" and nid in self._page_route_by_node:
+                route_path = self._page_route_by_node[nid]
+                if route_path in self.graph.routes:
+                    raise ValueError(f"Duplicate route: {route_path!r}")
+                self.graph.routes[route_path] = nid
+
+        for key, value in attrs.items():
+            if key in THEME_ATTR_KEYS and isinstance(value, str):
+                tid = self.theme_node(value, call)
+                self.dep.edges.append({"from": nid, "to": tid, "kind": "uses_theme"})
+                self.graph.edges.append({"from": nid, "to": tid, "kind": "uses_theme"})
+            if key == "on_click" and isinstance(value, dict) and "__handler__" in value:
+                handler = value["__handler__"]
+                self.dep.edges.append({"from": nid, "to": handler, "kind": "on_click"})
+                self.graph.edges.append({"from": nid, "to": handler, "kind": "calls_handler"})
+            if isinstance(value, dict) and "__state__" in value:
+                state_name = value["__state__"]
+                self.dep.edges.append({"from": nid, "to": state_name, "kind": "reads_state"})
+                self.graph.edges.append({"from": nid, "to": state_name, "kind": "reads_state"})
+
+        return nid
+
+    def visit_module(self, module: ast.Module) -> None:
+        for stmt in module.body:
+            if isinstance(stmt, ast.FunctionDef):
+                if any(_is_server_decorator(d) for d in stmt.decorator_list):
+                    self.register_handler(stmt.name, kind="server", at=stmt)
+                elif stmt.name not in self.components:
+                    self.register_handler(stmt.name, kind="client", at=stmt)
+            elif isinstance(stmt, ast.Assign):
+                if isinstance(stmt.value, ast.Call) and _is_state_call(stmt.value):
+                    for target in stmt.targets:
+                        if isinstance(target, ast.Name):
+                            self.register_state(target.id, stmt.value)
+                elif isinstance(stmt.value, ast.Call) and _is_theme_call(stmt.value):
+                    self.register_theme(stmt.value)
+                elif isinstance(stmt.value, ast.Call):
+                    self.build_call(stmt.value)
+            elif isinstance(stmt, ast.Expr) and isinstance(stmt.value, ast.Call):
+                if _is_theme_call(stmt.value):
+                    self.register_theme(stmt.value)
+                else:
+                    self.build_call(stmt.value)
+        self._finalize_routes()
+
+    def _finalize_routes(self) -> None:
+        page_roots = [nid for nid in self.graph.roots if self.graph.nodes[nid].kind == "Page"]
+        unrouted = [nid for nid in page_roots if nid not in self._page_route_by_node]
+        if len(page_roots) == 1 and not self.graph.routes:
+            self.graph.routes["/"] = page_roots[0]
+        elif unrouted:
+            raise ValueError(
+                "Multiple ui.Page definitions require route= on each page "
+                f"(missing route on {len(unrouted)} page(s))"
+            )
+
+
+def _display_path(path: Path) -> str:
+    path = path.resolve()
+    try:
+        return path.relative_to(Path.cwd().resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def build_semantic_graph(path: str | Path) -> tuple[SemanticGraph, DependencyGraph]:
+    path = Path(path)
+    module = parse_file(path)
+    components = collect_components(module)
+    builder = _GraphBuilder(_display_path(path), components)
+    builder.visit_module(module)
+    builder.graph.roots = sorted(set(builder.graph.roots))
+    return builder.graph, builder.dep

ourui/analysis/components.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import ast
+import copy
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ComponentDef:
+    name: str
+    params: list[str]
+    template: ast.Call
+    style: str  # "function" | "class"
+    span_line: int = 0
+
+
+def _is_ui_call(call: ast.Call) -> bool:
+    func = call.func
+    if isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+        return func.value.id == "ui"
+    return False
+
+
+def _inherits_component(bases: list[ast.expr]) -> bool:
+    for base in bases:
+        if isinstance(base, ast.Name) and base.id == "Component":
+            return True
+        if isinstance(base, ast.Attribute) and base.attr == "Component":
+            return True
+    return False
+
+
+def _return_call(fn: ast.FunctionDef) -> ast.Call | None:
+    body = [s for s in fn.body if not isinstance(s, (ast.Pass, ast.Expr))]
+    # allow docstring Expr as first
+    stmts = list(fn.body)
+    if stmts and isinstance(stmts[0], ast.Expr) and isinstance(stmts[0].value, ast.Constant):
+        stmts = stmts[1:]
+    if len(stmts) != 1 or not isinstance(stmts[0], ast.Return):
+        return None
+    value = stmts[0].value
+    if isinstance(value, ast.Call):
+        return value
+    return None
+
+
+def collect_components(module: ast.Module) -> dict[str, ComponentDef]:
+    components: dict[str, ComponentDef] = {}
+
+    for stmt in module.body:
+        if isinstance(stmt, ast.FunctionDef):
+            # skip @server handlers
+            if any(
+                (isinstance(d, ast.Name) and d.id == "server")
+                or (isinstance(d, ast.Attribute) and d.attr == "server")
+                for d in stmt.decorator_list
+            ):
+                continue
+            ret = _return_call(stmt)
+            if ret is None:
+                continue
+            # Must be ui.* or another component name (resolved later)
+            params = [a.arg for a in stmt.args.args]
+            components[stmt.name] = ComponentDef(
+                name=stmt.name,
+                params=params,
+                template=ret,
+                style="function",
+                span_line=stmt.lineno,
+            )
+        elif isinstance(stmt, ast.ClassDef) and _inherits_component(stmt.bases):
+            init_params: list[str] = []
+            build_fn: ast.FunctionDef | None = None
+            for item in stmt.body:
+                if isinstance(item, ast.FunctionDef) and item.name == "__init__":
+                    # skip self
+                    init_params = [a.arg for a in item.args.args[1:]]
+                if isinstance(item, ast.FunctionDef) and item.name == "build":
+                    build_fn = item
+            if build_fn is None:
+                continue
+            ret = _return_call(build_fn)
+            if ret is None:
+                continue
+            # Prefer __init__ params; else build params without self
+            params = init_params or [a.arg for a in build_fn.args.args[1:]]
+            components[stmt.name] = ComponentDef(
+                name=stmt.name,
+                params=params,
+                template=ret,
+                style="class",
+                span_line=stmt.lineno,
+            )
+
+    return components
+
+
+class _Subst(ast.NodeTransformer):
+    def __init__(self, mapping: dict[str, ast.AST], *, class_style: bool) -> None:
+        self.mapping = mapping
+        self.class_style = class_style
+
+    def visit_Name(self, node: ast.Name) -> ast.AST:
+        if node.id in self.mapping:
+            return copy.deepcopy(self.mapping[node.id])
+        return node
+
+    def visit_Attribute(self, node: ast.Attribute) -> ast.AST:
+        self.generic_visit(node)
+        if (
+            self.class_style
+            and isinstance(node.value, ast.Name)
+            and node.value.id == "self"
+            and node.attr in self.mapping
+        ):
+            return copy.deepcopy(self.mapping[node.attr])
+        return node
+
+
+def bind_call_args(call: ast.Call, params: list[str]) -> dict[str, ast.AST]:
+    mapping: dict[str, ast.AST] = {}
+    for i, arg in enumerate(call.args):
+        if i < len(params):
+            mapping[params[i]] = arg
+    for kw in call.keywords:
+        if kw.arg and kw.arg in params:
+            mapping[kw.arg] = kw.value
+    return mapping
+
+
+def expand_component_call(
+    call: ast.Call,
+    components: dict[str, ComponentDef],
+    *,
+    depth: int = 0,
+) -> ast.Call | None:
+    """If call is a user component, return expanded ui.* Call (fully expanded)."""
+    if depth > 16:
+        raise RecursionError("component expansion exceeded depth limit")
+    if not isinstance(call.func, ast.Name):
+        return None
+    name = call.func.id
+    if name not in components:
+        return None
+    cdef = components[name]
+    mapping = bind_call_args(call, cdef.params)
+    template = copy.deepcopy(cdef.template)
+    substituted = _Subst(mapping, class_style=cdef.style == "class").visit(template)
+    ast.fix_missing_locations(substituted)
+    if not isinstance(substituted, ast.Call):
+        return None
+    # Recurse if still a component
+    while isinstance(substituted.func, ast.Name) and substituted.func.id in components:
+        nested = expand_component_call(substituted, components, depth=depth + 1)
+        if nested is None:
+            break
+        substituted = nested
+    return substituted
+
+
+def component_call_name(call: ast.Call, components: dict[str, ComponentDef]) -> str | None:
+    if isinstance(call.func, ast.Name) and call.func.id in components:
+        return call.func.id
+    return None

ourui/cli.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ourui.lsp.server import run_stdio_server
+from ourui.pipeline import dump_json, emit_html
+from ourui.runtime import serve
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="ourui", description="OurUI compiler CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    dump_p = sub.add_parser(
+        "dump",
+        help="Dump Semantic Graph, Dependency Graph, IIR, LTR, and RTR as JSON",
+    )
+    dump_p.add_argument("source", type=Path, help="Path to a Python OurUI module")
+    dump_p.add_argument("-o", "--output", type=Path, default=None, help="Write JSON to file instead of stdout")
+
+    emit_p = sub.add_parser(
+        "emit",
+        help="Emit HTML from HostNode RTR (does not consume Python AST in emitter)",
+    )
+    emit_p.add_argument("source", type=Path, help="Path to a Python OurUI module")
+    emit_p.add_argument("-o", "--output", type=Path, default=None, help="Write HTML to file instead of stdout")
+    emit_p.add_argument("--title", default=None, help="HTML document title")
+
+    serve_p = sub.add_parser(
+        "serve",
+        help="Serve app: GET / emits HTML; POST /__ourui/call/<handler> runs @server fns",
+    )
+    serve_p.add_argument("source", type=Path, help="Path to a Python OurUI module")
+    serve_p.add_argument("--host", default="127.0.0.1")
+    serve_p.add_argument("--port", type=int, default=8765)
+    serve_p.add_argument("--title", default=None)
+    serve_p.add_argument(
+        "--prod",
+        action="store_true",
+        help="Production mode: no HMR, session State, safe errors, /__ourui/health",
+    )
+    serve_p.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        help="Worker processes (requires --prod; uses file session store when >1)",
+    )
+    serve_p.add_argument(
+        "--session-dir",
+        type=Path,
+        default=None,
+        help="Directory for file-backed sessions (or set OURUI_SESSION_DIR)",
+    )
+
+    sub.add_parser(
+        "lsp",
+        help="Start the OurUI Language Server (stdio JSON-RPC for editors)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "dump":
+        if not args.source.exists():
+            print(f"error: file not found: {args.source}", file=sys.stderr)
+            return 1
+        text = dump_json(args.source)
+        if args.output:
+            args.output.write_text(text, encoding="utf-8")
+        else:
+            sys.stdout.write(text)
+        return 0
+
+    if args.command == "emit":
+        if not args.source.exists():
+            print(f"error: file not found: {args.source}", file=sys.stderr)
+            return 1
+        text = emit_html(args.source, title=args.title)
+        if args.output:
+            args.output.write_text(text, encoding="utf-8")
+        else:
+            sys.stdout.write(text)
+        return 0
+
+    if args.command == "serve":
+        if not args.source.exists():
+            print(f"error: file not found: {args.source}", file=sys.stderr)
+            return 1
+        serve(
+            args.source,
+            host=args.host,
+            port=args.port,
+            title=args.title,
+            prod=args.prod,
+            workers=args.workers,
+            session_dir=args.session_dir,
+        )
+        return 0
+
+    if args.command == "lsp":
+        run_stdio_server()
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ourui/emit/__init__.py

@@ -0,0 +1,4 @@
+from ourui.emit.html import emit_bundle, emit_css, emit_html_document
+from ourui.emit.js import emit_js
+
+__all__ = ["emit_bundle", "emit_css", "emit_html_document", "emit_js"]