quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/component_composer.py

@@ -0,0 +1,133 @@
+"""
+Quantum Component Composer — <Component prop="…">slot content</Component>.
+
+COMP-1..4 (SPEC.md). What this used to get wrong, found by building the admin
+layout on it:
+
+  - the component was searched in ./components relative to the process's
+    working directory — paths.components from quantum.config.yaml and the
+    `from=` of q:import were ignored;
+  - a component that was not found, or failed, became an HTML comment and the
+    page answered 200 with the section missing;
+  - the child ran as ComponentRuntime() with no configuration, so a q:query
+    or q:invoke service= inside a child component had no datasources/services;
+  - slot content was grafted into the child's AST and evaluated in the
+    CHILD's scope: a q:loop over the page's rows inside a layout saw nothing.
+    Worse, the graft mutated the child AST held in the resolver cache, so the
+    first request's slot content replaced the q:slot for every later request;
+  - props used get_variable only (no expressions) and fell back to the
+    placeholder text on failure.
+"""
+
+import re
+from typing import Any, Dict, List
+
+from quantum.core.ast_nodes import ComponentCallNode, ComponentNode, HTMLNode, QuantumNode, SlotNode
+from quantum.core.expressions import ExpressionError
+from quantum.runtime.component import ComponentRuntime
+from quantum.runtime.component_resolver import ComponentNotFoundError, ComponentResolver
+
+
+class ComponentCompositionError(Exception):
+    """A component call could not be composed; the message names the component."""
+
+
+class RenderedHTML(QuantumNode):
+    """Markup the parent already rendered (slot content), inserted as-is."""
+
+    def __init__(self, html: str):
+        self.html = html
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": "rendered_html", "length": len(self.html)}
+
+    def validate(self) -> List[str]:
+        return []
+
+
+class ComponentComposer:
+    def __init__(self, resolver: ComponentResolver):
+        self.resolver = resolver
+
+    def compose(self, call: ComponentCallNode, parent) -> str:
+        """Render `call` as a child of the HTMLRenderer `parent`."""
+        from quantum.runtime.renderer import HTMLRenderer
+
+        nome, origem = parent.imports.get(call.component_name, (call.component_name, None))
+        try:
+            child = self.resolver.resolve(nome, origem).ast
+        except ComponentNotFoundError as exc:
+            raise ComponentCompositionError(f"<{call.component_name}>: {exc}") from exc
+
+        props = self._props(child, call, parent)
+        # COMP-4: the same configuration and the same session, application and
+        # request scopes as the page — a layout showing {session.userName}
+        # used to see an empty session.
+        props.update(_session_scope=parent.context.session_vars,
+                     _application_scope=parent.context.application_vars,
+                     _request_scope=parent.context.request_vars)
+        runtime = ComponentRuntime(config=parent.config)
+        runtime.execute_component(child, props)
+
+        # COMP-3: slot content belongs to the page — rendered here, with the
+        # page's variables, before the child sees it.
+        slot = RenderedHTML(parent.render_all(call.children)) if call.children else None
+        preenchido = ComponentNode(name=child.name, component_type=child.component_type)
+        preenchido.statements = self._com_slot(child.statements, slot)
+        preenchido.params, preenchido.returns, preenchido.functions = child.params, child.returns, child.functions
+
+        renderer = HTMLRenderer(runtime.execution_context, components_dir=parent.components_dir,
+                                function_resolver=runtime._resolve_expression_function, config=parent.config)
+        return renderer.render(preenchido)
+
+    def _props(self, child: ComponentNode, call: ComponentCallNode, parent) -> Dict[str, Any]:
+        props = {}
+        for definicao in child.params:
+            if definicao.name in call.props:
+                props[definicao.name] = self._avaliar(call.props[definicao.name], definicao.name, call, parent)
+            elif definicao.default is not None:
+                props[definicao.name] = definicao.default
+            elif definicao.required:
+                raise ComponentCompositionError(
+                    f"<{call.component_name}> requires the prop {definicao.name!r}")
+        return props
+
+    @staticmethod
+    def _avaliar(valor, prop, call, parent):
+        """COMP-2: a prop is an attribute of a tag — an expression that fails is an error."""
+        if not isinstance(valor, str) or "{" not in valor:
+            return valor
+        variaveis = parent.context.get_all_variables()
+        try:
+            inteira = re.fullmatch(r"\s*\{([^{}]*)\}\s*", valor)
+            if inteira:
+                return parent._expressions.evaluate(inteira.group(1), variaveis)
+            return re.sub(r"\{([^{}]*)\}",
+                          lambda m: str(parent._expressions.evaluate(m.group(1), variaveis)), valor)
+        except ExpressionError as exc:
+            raise ComponentCompositionError(
+                f"<{call.component_name} {prop}=\"{valor}\">: {exc}") from exc
+
+    def _com_slot(self, nodes: List[QuantumNode], slot) -> List[QuantumNode]:
+        """Copy of `nodes` with each q:slot replaced — the cached child AST is never touched."""
+        resultado = []
+        for node in nodes:
+            if isinstance(node, SlotNode):
+                # Only the default slot receives the call's children; named
+                # slots keep their default content (named slots are not
+                # implemented, as before).
+                if slot is not None and (node.name or "default") == "default":
+                    resultado.append(slot)
+                else:
+                    resultado.extend(node.default_content or [])
+            elif isinstance(node, HTMLNode) and self._tem_slot(node.children):
+                copia = HTMLNode(tag=node.tag, attributes=dict(node.attributes),
+                                 children=self._com_slot(node.children, slot), self_closing=node.self_closing)
+                resultado.append(copia)
+            else:
+                resultado.append(node)
+        return resultado
+
+    def _tem_slot(self, nodes) -> bool:
+        return any(isinstance(n, SlotNode) or (isinstance(n, HTMLNode) and self._tem_slot(n.children))
+                   for n in nodes)

quantum/runtime/component_resolver.py

@@ -0,0 +1,174 @@
+"""
+Quantum Component Resolver
+
+Phase 2: Component Composition
+Responsible for finding, loading, and caching imported components.
+"""
+
+import sys
+from pathlib import Path
+from typing import Dict, Optional, List
+from dataclasses import dataclass
+
+# Fix imports
+
+from quantum.core.parser import QuantumParser, QuantumParseError
+from quantum.core.ast_nodes import ComponentNode, ImportNode
+
+
+@dataclass
+class ComponentMetadata:
+    """Metadata about a resolved component"""
+    name: str
+    path: Path
+    ast: ComponentNode
+    imports: List[ImportNode]
+
+
+class ComponentResolver:
+    """
+    Resolves and loads Quantum components.
+
+    Phase 2: Component Composition
+
+    Responsibilities:
+    - Find component .q files by name
+    - Load and parse components
+    - Cache parsed components
+    - Resolve component dependencies
+    """
+
+    def __init__(self, components_dir: str = "./components"):
+        self.components_dir = Path(components_dir)
+        self.parser = QuantumParser()
+
+        # Component cache: {name: ComponentMetadata}
+        self.cache: Dict[str, ComponentMetadata] = {}
+
+    def resolve(self, component_name: str, from_path: Optional[str] = None) -> ComponentMetadata:
+        """
+        Resolve component by name.
+
+        Args:
+            component_name: Name of component (e.g., "Header", "Button")
+            from_path: Optional relative path (e.g., "./ui", "../shared")
+
+        Returns:
+            ComponentMetadata with AST and metadata
+
+        Raises:
+            ComponentNotFoundError: If component file doesn't exist
+        """
+
+        # Check cache first
+        cache_key = f"{from_path or 'default'}:{component_name}"
+        if cache_key in self.cache:
+            return self.cache[cache_key]
+
+        # Find component file
+        component_path = self._find_component_file(component_name, from_path)
+
+        if not component_path.exists():
+            raise ComponentNotFoundError(
+                f"Component '{component_name}' not found. "
+                f"Searched: {component_path}"
+            )
+
+        # Parse component
+        try:
+            ast = self.parser.parse_file(str(component_path))
+
+            if not isinstance(ast, ComponentNode):
+                raise ComponentNotFoundError(
+                    f"File '{component_path}' is not a component "
+                    f"(got {type(ast).__name__})"
+                )
+
+            # Extract imports from component
+            imports = [stmt for stmt in ast.statements if isinstance(stmt, ImportNode)]
+
+            # Create metadata
+            metadata = ComponentMetadata(
+                name=component_name,
+                path=component_path,
+                ast=ast,
+                imports=imports
+            )
+
+            # Cache it
+            self.cache[cache_key] = metadata
+
+            return metadata
+
+        except QuantumParseError as e:
+            raise ComponentNotFoundError(
+                f"Failed to parse component '{component_name}': {e}"
+            )
+
+    def _find_component_file(self, component_name: str, from_path: Optional[str] = None) -> Path:
+        """
+        Find component .q file.
+
+        Resolution order:
+        1. If from_path provided: {from_path}/{ComponentName}.q
+        2. Default: {components_dir}/{ComponentName}.q
+        3. Try lowercase: {components_dir}/{componentname}.q
+        4. Try snake_case: {components_dir}/{component_name}.q
+        """
+
+        # Try from_path first if provided
+        if from_path:
+            from_dir = self.components_dir / from_path.lstrip('./')
+            path = from_dir / f"{component_name}.q"
+            if path.exists():
+                return path
+
+        # Try exact name
+        path = self.components_dir / f"{component_name}.q"
+        if path.exists():
+            return path
+
+        # Try lowercase
+        path = self.components_dir / f"{component_name.lower()}.q"
+        if path.exists():
+            return path
+
+        # Try snake_case conversion
+        snake_case_name = self._to_snake_case(component_name)
+        path = self.components_dir / f"{snake_case_name}.q"
+        if path.exists():
+            return path
+
+        # Return original path (will trigger not found error)
+        return self.components_dir / f"{component_name}.q"
+
+    def _to_snake_case(self, name: str) -> str:
+        """
+        Convert PascalCase to snake_case.
+
+        Examples:
+          ProductCard → product_card
+          AdminLayout → admin_layout
+          UserProfileHeader → user_profile_header
+        """
+        import re
+        # Insert underscore before uppercase letters
+        result = re.sub(r'(?<!^)(?=[A-Z])', '_', name)
+        return result.lower()
+
+    def clear_cache(self):
+        """Clear component cache (useful for development hot-reload)"""
+        self.cache.clear()
+
+    def preload(self, component_names: List[str]):
+        """Preload components into cache"""
+        for name in component_names:
+            try:
+                self.resolve(name)
+            except ComponentNotFoundError:
+                pass  # Skip missing components
+
+
+class ComponentNotFoundError(Exception):
+    """Component file not found or invalid"""
+    pass

quantum/runtime/conditions.py

@@ -0,0 +1,54 @@
+"""The one place a `condition` is evaluated (q:if, q:elseif, guards).
+
+ComponentRuntime (statements) and HTMLRenderer (markup) each had their own
+copy of this function. They drifted: IF-2 (`condition="1"` was false) existed
+in one and not the other. Both call this now.
+"""
+
+import re
+from typing import Any, Dict
+
+from quantum.core.expression_diagnostics import report_unresolved
+from quantum.core.expressions import ExpressionError, ExpressionEvaluator, UndefinedError
+
+_BRACES = re.compile(r'\{([^}]+)\}')
+
+
+def evaluate_condition(evaluator: ExpressionEvaluator, condition: str,
+                       variables: Dict[str, Any], guard: bool = False) -> bool:
+    """True or False for a condition, by the rules of SPEC IF-2, EXPR-5, EXPR-8, AUTH-6.
+
+    The condition is evaluated as an expression with the braces stripped:
+    the variable NAMES stay in place for the evaluator to resolve, so no
+    value is ever parsed as syntax. (It used to interpolate the values into
+    the text and eval() the result — code assembled out of data; a record
+    named "'; __import__(...)" became executable. PUBLIC_RELEASE_PLAN P0.1.)
+    """
+    if not condition:
+        return False
+    stripped = _BRACES.sub(lambda m: m.group(1), condition).strip()
+    try:
+        # EXPR-8: a key a scope does not have (session.userId before login)
+        # is None here, so `not session.authenticated` is true for a visitor.
+        return bool(evaluator.evaluate(stripped, variables or {}, absent_scope_key_is_none=True))
+    except UndefinedError as exc:
+        if guard:
+            # AUTH-6: a guard decides whether the page and its actions run.
+            # Reading a failure as false would let everything through, so in
+            # a guard it is an error: the page fails closed.
+            raise ExpressionError(
+                f"guard condition {condition!r} could not be evaluated: {exc}. A guard "
+                f"must decide; test each part first, e.g. "
+                f"`not session.user or not session.user.is_admin`") from exc
+        # EXPR-5: a condition is a presence test — a missing name, key or
+        # attribute makes it FALSE, never true. Before, the literal
+        # placeholder 'session.user.is_admin' came back as a non-empty string,
+        # read as true: the admin branch rendered for a logged-out visitor.
+        report_unresolved(stripped, ExpressionError(
+            f"condition {condition!r} could not be evaluated; treated as false"))
+        return False
+    except ExpressionError as exc:
+        # A syntax error or a function that does not exist is an error:
+        # reading it as false is how `age >= 18 && ok` took the else branch
+        # for every input.
+        raise ExpressionError(f"condition {condition!r} could not be evaluated: {exc}") from exc