tw-framework 0.2.3__py3-none-any.whl

tw_framework/render_css.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+
+def _legacy():
+    from . import compiler
+
+    return compiler
+
+
+def parse_stylesheet(text: str):
+    compiler = _legacy()
+    return compiler.build_tss_ast_from_text(text)
+
+
+def render_stylesheet(text: str, context=None, minify: bool = False) -> str:
+    compiler = _legacy()
+    sheet = parse_stylesheet(text)
+    css = compiler.render_css(sheet, context=context or {})
+    return compiler.minify_css_content(css) if minify else css
+
+
+__all__ = ["parse_stylesheet", "render_stylesheet"]

tw_framework/render_html.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import html
+import logging
+import os
+from typing import Dict, Generator, Iterable, List, Optional
+
+from .ir import IRComponent, IRElement, IRFor, IRIf, IRLet, IRProgram, IRScript, IRText
+from .runtime_values import RuntimeEnvironment
+from .signature import build_signature_banner, build_signature_meta_tag, compute_tw_signature
+from .hydration import wrap_interactive_nodes
+from .streaming import render_program_streaming
+
+logger = logging.getLogger(__name__)
+
+
+def _legacy():
+    from . import compiler
+
+    return compiler
+
+
+VOID_TAGS = {"br", "hr", "img", "input", "meta", "link"}
+
+_COMPONENT_PROGRAM_CACHE: Dict[str, IRProgram] = {}
+
+
+def _interpolate(value, context):
+    compiler = _legacy()
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        return value
+    return compiler.interpolate(value, context)
+
+
+def _evaluate(expr: str, context):
+    compiler = _legacy()
+    return compiler.evaluate_expression(expr, context)
+
+
+def build_runtime_context(program, context: Optional[Dict] = None) -> Dict:
+    compiler = _legacy()
+    runtime_context: Dict = {}
+    runtime_context.update(dict(program.lets))
+    runtime_context.update(dict(program.state))
+    if getattr(program, "legacy_page", None) is not None and getattr(program, "source_path", ""):
+        try:
+            base_context = compiler.create_base_context(program.legacy_page, program.source_path)
+            runtime_context.update(base_context)
+        except Exception:
+            logger.exception("Failed to create base runtime context for %s", getattr(program, "source_path", ""))
+    runtime_context.update(dict(context or {}))
+    return runtime_context
+
+
+def _render_attrs(attrs: Iterable[Dict], env: RuntimeEnvironment) -> str:
+    parts: List[str] = []
+    context = env.to_context()
+    for attr in attrs:
+        value = _interpolate(attr["value"], context)
+        if value is True:
+            parts.append(attr["name"])
+            continue
+        if value in {False, None}:
+            continue
+        parts.append(f'{attr["name"]}="{html.escape(str(value), quote=True)}"')
+    return f" {' '.join(parts)}" if parts else ""
+
+
+def _render_style(styles: Iterable[Dict], env: RuntimeEnvironment) -> str:
+    resolved = []
+    context = env.to_context()
+    for item in styles:
+        value = _interpolate(item["value"], context)
+        resolved.append(f'{item["name"]}: {value}')
+    return f' style="{html.escape("; ".join(resolved), quote=True)}"' if resolved else ""
+
+
+def _load_component_ir(name: str) -> Optional[IRProgram]:
+    compiler = _legacy()
+    try:
+        path = compiler.resolve_component_path(name)
+    except Exception:
+        logger.exception("Failed to resolve component path for `%s`", name)
+        return None
+
+    if not path or not os.path.exists(path):
+        return None
+
+    cached = _COMPONENT_PROGRAM_CACHE.get(path)
+    if cached is not None:
+        return cached
+
+    from .lowering import lower_program
+    from .parser import parse_file
+
+    try:
+        program = parse_file(path)
+        ir_program = lower_program(program)
+    except Exception:
+        logger.exception("Failed to parse/lower component `%s` at %s", name, path)
+        return None
+
+    _COMPONENT_PROGRAM_CACHE[path] = ir_program
+    return ir_program
+
+
+def render_node(node, env: RuntimeEnvironment) -> str:
+    context = env.to_context()
+    if isinstance(node, IRText):
+        return html.escape(str(_interpolate(node.value, context)))
+    if isinstance(node, IRLet):
+        env.set(node.name, _interpolate(node.value, context))
+        return ""
+    if isinstance(node, IRIf):
+        branch = node.children if _evaluate(node.condition, context) else node.else_children
+        return "".join(render_node(child, env.child()) for child in branch)
+    if isinstance(node, IRFor):
+        rendered = []
+        items = _evaluate(node.iterable, context)
+        for item in items or []:
+            loop_env = env.child({node.var_name: item})
+            rendered.append("".join(render_node(child, loop_env) for child in node.children))
+        return "".join(rendered)
+    if isinstance(node, IRScript):
+        return f"<script>{node.raw_js}</script>"
+    if isinstance(node, IRComponent):
+        props = {prop["name"]: _interpolate(prop["value"], context) for prop in node.props}
+
+        stack = context.get("__tw_component_stack__", ())
+        if node.name in stack:
+            chain = " -> ".join(stack + (node.name,))
+            logger.error("Circular component reference detected: %s", chain)
+            return (
+                f'<div data-tw-component-error="circular" data-tw-component="{html.escape(node.name, quote=True)}">'
+                f"Circular component reference: {html.escape(chain)}"
+                f"</div>"
+            )
+
+        component_ir = _load_component_ir(node.name)
+        if component_ir is None:
+            children_html = "".join(render_node(child, env.child()) for child in node.children)
+            props_html = "".join(
+                f'<li><strong>{html.escape(str(key))}</strong>: {html.escape(str(value))}</li>'
+                for key, value in props.items()
+            )
+            logger.warning("Component `%s` could not be resolved; rendering placeholder.", node.name)
+            return (
+                f'<div data-tw-component-error="not-found" data-tw-component="{html.escape(node.name, quote=True)}">'
+                f"<div>Component not found: {html.escape(node.name)}</div>"
+                f"<ul>{props_html}</ul>{children_html}</div>"
+            )
+
+        component_env = RuntimeEnvironment(
+            values={
+                **dict(component_ir.lets),
+                **dict(component_ir.state),
+                **props,
+                "__tw_component_stack__": stack + (node.name,),
+            }
+        )
+        return "".join(render_node(child, component_env) for child in component_ir.body)
+    if isinstance(node, IRElement):
+        attrs = _render_attrs(node.attrs, env)
+        style_attr = _render_style(node.styles, env)
+        event_attrs = _render_attrs(node.events, env)
+        text = html.escape(str(_interpolate(node.text, context))) if node.text is not None else ""
+        children = "".join(render_node(child, env.child()) for child in node.children)
+        if node.tag in VOID_TAGS:
+            return f"<{node.tag}{attrs}{style_attr}{event_attrs}>"
+        return f"<{node.tag}{attrs}{style_attr}{event_attrs}>{text}{children}</{node.tag}>"
+    return ""
+
+
+def render_program(program: IRProgram, context: Optional[Dict] = None) -> str:
+    env = RuntimeEnvironment(values={**dict(program.lets), **dict(program.state), **dict(context or {})})
+    body = "".join(render_node(node, env) for node in program.body)
+    title = html.escape(str(program.meta.get("title") or "TW Program"))
+
+    signature = compute_tw_signature(program)
+    banner = build_signature_banner(signature, title=title)
+    meta_tags = build_signature_meta_tag(signature)
+
+    html_output = (
+        "<!DOCTYPE html>"
+        f"{banner}"
+        "<html>"
+        "<head>"
+        f"<title>{title}</title>"
+        f"{meta_tags}"
+        "</head>"
+        f"<body>{body}</body>"
+        "</html>"
+    )
+
+    # Apply hydration markers for interactive components
+    html_output = wrap_interactive_nodes(html_output, program, context=context)
+    return html_output
+
+
+def _inject_tw_signature(html_doc: str, banner: str, meta_tag: str) -> str:
+    """
+    Legacy renderer सीधे HTML string return करता है, IR tree नहीं, इसलिए
+    यहां हम एक best-effort post-processing करते हैं: document के सबसे ऊपर
+    एक comment banner डालते हैं, और अगर `<head>` tag मिल जाए तो उसके ठीक
+    बाद <meta> tags भी डाल देते हैं। अगर `<head>` न मिले, तो signature फिर
+    भी silently गायब नहीं होगी — banner के बाद meta tags जोड़ दी जाती हैं।
+    """
+    lowered = html_doc.lower()
+    head_idx = lowered.find("<head>")
+    if head_idx != -1:
+        insert_at = head_idx + len("<head>")
+        html_doc = html_doc[:insert_at] + "\n" + meta_tag + html_doc[insert_at:]
+        return banner + "\n" + html_doc
+    return banner + "\n" + meta_tag + "\n" + html_doc
+
+
+def render_streaming(ir_program: IRProgram, *, page_program=None, context: Optional[Dict] = None, css_href: Optional[str] = None) -> Generator[str, None, None]:
+    """Yield HTML chunks for streaming SSR."""
+    from .streaming import render_program_streaming
+    yield from render_program_streaming(ir_program, context=context)
+
+
+def render_program_document(ir_program: IRProgram, *, page_program=None, context: Optional[Dict] = None, css_href: Optional[str] = None, debug: bool = False) -> str:
+    compiler = _legacy()
+    merged_context = build_runtime_context(page_program, context=context) if page_program is not None else dict(context or {})
+
+    # Check if streaming is enabled via config
+    config = merged_context.get("config", {})
+    use_streaming = bool(config.get("streaming", False))
+
+    if use_streaming:
+        chunks = list(render_program_streaming(ir_program, context=merged_context))
+        html_output = "".join(chunks)
+        # Apply hydration markers
+        html_output = wrap_interactive_nodes(html_output, ir_program, context=merged_context)
+        return html_output
+
+    if page_program is not None and getattr(page_program, "legacy_page", None) is not None:
+        resolved_css = css_href
+        if resolved_css is None:
+            try:
+                resolved_css, _ = compiler.read_global_stylesheet()
+            except Exception:
+                logger.exception("Failed to read global stylesheet")
+                resolved_css = ""
+        raw_html = compiler.render_html(page_program.legacy_page, merged_context, resolved_css or "")
+
+        signature = compute_tw_signature(page_program)
+        title = str(getattr(page_program.meta, "title", "") or "")
+        banner = build_signature_banner(signature, title=title)
+        meta_tag = build_signature_meta_tag(signature)
+        return _inject_tw_signature(raw_html, banner, meta_tag)
+
+    return render_program(ir_program, context=merged_context)
+
+
+__all__ = ["build_runtime_context", "render_node", "render_program", "render_program_document"]

tw_framework/route_optimizer.py

@@ -0,0 +1,40 @@
+"""
+Automatic route optimization for TW Framework.
+
+Detects duplicate routes, unreachable routes, route conflicts, and shadowed routes.
+"""
+
+import logging
+from typing import Dict, List
+
+from . import compiler
+
+logger = logging.getLogger(__name__)
+
+
+def optimize_routes(project_root: str) -> Dict[str, List[str]]:
+    """Analyze routes and return optimization suggestions."""
+    issues = {
+        "duplicate_routes": [],
+        "unreachable_routes": [],
+        "route_conflicts": [],
+        "shadowed_routes": [],
+    }
+
+    pages = compiler.discover_pages()
+    route_map: Dict[str, List[str]] = {}
+    for page in pages:
+        route = compiler.route_path_from_page_info(page)
+        if route not in route_map:
+            route_map[route] = []
+        route_map[route].append(page["path"])
+
+    for route, paths in route_map.items():
+        if len(paths) > 1:
+            issues["duplicate_routes"].append({"route": route, "paths": paths})
+
+    # TODO: Add unreachable, conflict, and shadow detection
+    return issues
+
+
+__all__ = ["optimize_routes"]

tw_framework/router.py

@@ -0,0 +1,7 @@
+from .framework import (  # noqa: F401
+    RouteMatch,
+    normalize_url_path,
+    route_from_dynamic_page,
+    route_from_static_page,
+    strip_trailing_slash,
+)

tw_framework/runtime_model.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class CompilerArtifacts:
+    source_path: str = ""
+    tokens: List[Dict[str, Any]] = field(default_factory=list)
+    ast: Optional[Dict[str, Any]] = None
+    diagnostics: List[Dict[str, Any]] = field(default_factory=list)
+    ir: Optional[Dict[str, Any]] = None
+    html: Optional[str] = None
+    program: Any = None
+    runtime_context: Dict[str, Any] = field(default_factory=dict)
+    dependencies: List[str] = field(default_factory=list)
+    route_path: str = "/"
+    pipeline: str = "modular"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+__all__ = ["CompilerArtifacts"]

tw_framework/runtime_values.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class RuntimeEnvironment:
+    values: Dict[str, Any] = field(default_factory=dict)
+    parent: Optional["RuntimeEnvironment"] = None
+
+    def get(self, name: str, default=None):
+        if name in self.values:
+            return self.values[name]
+        if self.parent is not None:
+            return self.parent.get(name, default)
+        return default
+
+    def set(self, name: str, value: Any):
+        self.values[name] = value
+
+    def to_context(self) -> Dict[str, Any]:
+        data = self.parent.to_context() if self.parent is not None else {}
+        data.update(self.values)
+        return data
+
+    def child(self, extra: Optional[Dict[str, Any]] = None) -> "RuntimeEnvironment":
+        return RuntimeEnvironment(values=dict(extra or {}), parent=self)
+
+
+__all__ = ["RuntimeEnvironment"]

tw_framework/semantic.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import logging
+from typing import Dict, Optional
+
+from .ast_nodes import ComponentNode, ElementNode, ForNode, IfNode, LetNode, Program
+from .diagnostics import Diagnostic, DiagnosticBag
+
+logger = logging.getLogger(__name__)
+
+
+def _legacy():
+    from . import compiler
+
+    return compiler
+
+
+class SemanticAnalyzer:
+    def _check_expression(self, expr, scope, diagnostics: DiagnosticBag, source_path: str, label: str):
+        compiler = _legacy()
+        try:
+            names = compiler.collect_expression_names(expr)
+        except Exception:
+            logger.exception("Failed to collect expression names (%s) in %s: %r", source_path, label, expr)
+            names = set()
+        for name in sorted(names):
+            if name not in scope:
+                diagnostics.add(
+                    Diagnostic(
+                        severity="error",
+                        code="TW2101",
+                        message=f"Unknown name `{name}` in {label}.",
+                        file_path=source_path,
+                    )
+                )
+
+    def _check_interpolations(self, text, scope, diagnostics: DiagnosticBag, source_path: str, label: str):
+        compiler = _legacy()
+        if not isinstance(text, str):
+            return
+        for expr in compiler.extract_placeholder_expressions(text):
+            self._check_expression(expr, scope, diagnostics, source_path, label)
+
+    def _walk_nodes(self, nodes, scope, diagnostics: DiagnosticBag, source_path: str):
+        next_scope = dict(scope)
+        for node in nodes:
+            if isinstance(node, LetNode):
+                next_scope[node.name] = node.value
+                self._check_interpolations(node.value, next_scope, diagnostics, source_path, f"`let {node.name}`")
+                continue
+            if isinstance(node, IfNode):
+                self._check_expression(node.condition, next_scope, diagnostics, source_path, "`if` condition")
+                self._walk_nodes(node.children, dict(next_scope), diagnostics, source_path)
+                self._walk_nodes(node.else_children, dict(next_scope), diagnostics, source_path)
+                continue
+            if isinstance(node, ForNode):
+                self._check_expression(node.iterable, next_scope, diagnostics, source_path, "`for` iterable")
+                child_scope = dict(next_scope)
+                child_scope[node.var_name] = True
+                self._walk_nodes(node.children, child_scope, diagnostics, source_path)
+                continue
+            if isinstance(node, ElementNode):
+                self._check_interpolations(node.text, next_scope, diagnostics, source_path, f"`{node.tag}` text")
+                for attr in node.attrs + node.styles + node.events:
+                    self._check_interpolations(attr.value, next_scope, diagnostics, source_path, f"`{node.tag}` `{attr.name}`")
+                for value in node.router.values():
+                    self._check_interpolations(value, next_scope, diagnostics, source_path, f"`{node.tag}` router")
+                self._walk_nodes(node.children, dict(next_scope), diagnostics, source_path)
+                continue
+            if isinstance(node, ComponentNode):
+                for prop in node.props:
+                    self._check_interpolations(prop.value, next_scope, diagnostics, source_path, f"`{node.name}` prop `{prop.name}`")
+                self._walk_nodes(node.children, dict(next_scope), diagnostics, source_path)
+
+    def _check_page_meta(self, program: Program, diagnostics: DiagnosticBag, source_path: str):
+        meta = program.meta
+
+        valid_render_modes = {"static", "server", "edge"}
+        if meta.render_mode not in valid_render_modes:
+            diagnostics.add(
+                Diagnostic(
+                    severity="error",
+                    code="TW2201",
+                    message=f'Invalid `render` mode "{meta.render_mode}". Use one of: static, server, edge.',
+                    file_path=source_path,
+                )
+            )
+
+        if meta.render_mode == "static" and meta.revalidate is not None:
+            diagnostics.add(
+                Diagnostic(
+                    severity="warning",
+                    code="TW2202",
+                    message="`revalidate` has no effect on `render static` pages. "
+                            "Use `render server` or `render edge` for ISR-style revalidation.",
+                    file_path=source_path,
+                )
+            )
+
+        if meta.revalidate is not None and meta.revalidate < 0:
+            diagnostics.add(
+                Diagnostic(
+                    severity="error",
+                    code="TW2203",
+                    message=f"`revalidate` must be a non-negative number, got {meta.revalidate}.",
+                    file_path=source_path,
+                )
+            )
+
+        if meta.redirect_to and meta.rewrite_to:
+            diagnostics.add(
+                Diagnostic(
+                    severity="error",
+                    code="TW2204",
+                    message="A page cannot define both `redirect` and `rewrite` at the same time.",
+                    file_path=source_path,
+                )
+            )
+
+    def analyze(self, program: Program, context: Optional[Dict] = None) -> DiagnosticBag:
+        diagnostics = DiagnosticBag()
+        compiler = _legacy()
+
+        if program.legacy_page and program.source_path:
+            try:
+                analysis_context = context or compiler.create_base_context(program.legacy_page, program.source_path)
+            except Exception:
+                logger.exception("Failed to create base context for %s", program.source_path)
+                analysis_context = context or {}
+            legacy_items = compiler.analyze_page_semantics(
+                program.legacy_page,
+                analysis_context,
+                program.source_path,
+            )
+            diagnostics.extend(Diagnostic.from_legacy(item) for item in legacy_items)
+
+        if not program.meta.title:
+            diagnostics.add(
+                Diagnostic(
+                    severity="warning",
+                    code="TW2001",
+                    message='Page title is empty. Consider setting `page { title "..." }`.',
+                    file_path=program.source_path,
+                )
+            )
+
+        self._check_page_meta(program, diagnostics, program.source_path)
+
+        scope = {}
+        scope.update(program.lets)
+        scope.update(program.state)
+        scope.update(context or {})
+        self._walk_nodes(program.body, scope, diagnostics, program.source_path)
+
+        return diagnostics
+
+
+def analyze_program(program: Program, context: Optional[Dict] = None) -> DiagnosticBag:
+    return SemanticAnalyzer().analyze(program, context=context)
+
+
+__all__ = ["SemanticAnalyzer", "analyze_program"]