tw-framework 0.2.3__py3-none-any.whl

tw_framework/partial_rebuild.py

@@ -0,0 +1,24 @@
+"""
+Partial rebuild support for TW Framework.
+
+When only one page changes, rebuild only affected pages using the dependency graph.
+"""
+
+import logging
+from typing import List, Set
+
+from . import compiler
+from .dependency_graph import DependencyGraph
+
+logger = logging.getLogger(__name__)
+
+
+def get_pages_to_rebuild(project_root: str, changed_files: Set[str]) -> List[dict]:
+    """Return the list of pages that need to be rebuilt given the changed files."""
+    graph = DependencyGraph(project_root)
+    affected = graph.get_affected_nodes(changed_files)
+    pages = compiler.discover_pages()
+    return [p for p in pages if p["path"] in affected]
+
+
+__all__ = ["get_pages_to_rebuild"]

tw_framework/performance_analyzer.py

@@ -0,0 +1,37 @@
+"""
+Runtime performance analyzer for TW Framework.
+
+Measures render time, SSR time, middleware time, and API execution time.
+"""
+
+import logging
+import time
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class PerformanceAnalyzer:
+    """Collects runtime performance metrics."""
+
+    def __init__(self):
+        self.metrics: Dict[str, float] = {}
+
+    def measure(self, name: str, func, *args, **kwargs) -> Any:
+        start = time.perf_counter()
+        try:
+            result = func(*args, **kwargs)
+            return result
+        finally:
+            elapsed = time.perf_counter() - start
+            self.metrics[name] = elapsed
+            logger.debug("Performance: %s took %.4f seconds", name, elapsed)
+
+    def get_report(self) -> Dict[str, float]:
+        return dict(self.metrics)
+
+    def reset(self):
+        self.metrics.clear()
+
+
+__all__ = ["PerformanceAnalyzer"]

tw_framework/plugin_runtime.py

@@ -0,0 +1,196 @@
+import importlib.util
+import logging
+import os
+import traceback
+from dataclasses import dataclass
+
+from .common import content_hash
+
+logger = logging.getLogger(__name__)
+
+
+HOOK_ALIASES = {
+    "before_build": "beforeBuild",
+    "after_build": "afterBuild",
+    "before_route": "beforeRoute",
+    "after_route": "afterRoute",
+}
+
+
+@dataclass
+class LoadedExtension:
+    name: str
+    path: str
+    module: object
+
+
+class PluginAPI:
+    def __init__(self, manager, extension_name):
+        self.manager = manager
+        self.extension_name = extension_name
+
+    def register_hook(self, event_name, handler):
+        self.manager.register_hook(event_name, handler, self.extension_name)
+
+    def hook(self, event_name, handler):
+        self.register_hook(event_name, handler)
+
+    def get_config(self):
+        return dict(self.manager.config or {})
+
+    def get_env(self):
+        return dict(self.manager.env or {})
+
+    def get_project_root(self):
+        return self.manager.project_root
+
+
+class ExtensionManager:
+    def __init__(self, project_root, config=None, env=None):
+        self.project_root = os.path.abspath(project_root)
+        self.config = dict(config or {})
+        self.env = dict(env or {})
+        self.extensions = []
+        self.hooks = {}
+        self.errors = []
+
+    def refresh(self, config=None, env=None):
+        self.config = dict(config or self.config or {})
+        self.env = dict(env or self.env or {})
+        self.extensions = []
+        self.hooks = {}
+        self.errors = []
+        extension_paths = self.discover_extension_paths()
+        self._warn_extension_execution(extension_paths)
+        for path in extension_paths:
+            self._load_extension(path)
+        return self
+
+    def discover_extension_paths(self):
+        paths = []
+        for folder in self._extension_roots():
+            if not os.path.isdir(folder):
+                continue
+            for dirpath, _, filenames in os.walk(folder):
+                for filename in sorted(filenames):
+                    if not filename.endswith(".py") or filename.startswith("_"):
+                        continue
+                    paths.append(os.path.join(dirpath, filename))
+        normalized = sorted(set(os.path.abspath(path) for path in paths))
+        return self._apply_allowlist(normalized)
+
+    def dependency_paths(self):
+        return self.discover_extension_paths()
+
+    def emit(self, event_name, **payload):
+        canonical = self._normalize_event_name(event_name)
+        event_payload = dict(payload)
+        event_payload.setdefault("event", canonical)
+        event_payload.setdefault("project_root", self.project_root)
+        event_payload.setdefault("config", dict(self.config))
+        event_payload.setdefault("env", dict(self.env))
+        for hook in self.hooks.get(canonical, []):
+            try:
+                result = hook["handler"](event_payload)
+                if isinstance(result, dict):
+                    event_payload.update(result)
+            except Exception as err:
+                tb = traceback.format_exc()
+                logger.exception("Extension hook failed: %s::%s", hook.get("extension"), canonical)
+                self.errors.append(f"{hook['extension']}::{canonical}: {err}\n{tb}")
+        return event_payload
+
+    def register_hook(self, event_name, handler, extension_name):
+        canonical = self._normalize_event_name(event_name)
+        if not callable(handler):
+            raise TypeError(f"Hook `{canonical}` from `{extension_name}` must be callable")
+        self.hooks.setdefault(canonical, []).append({
+            "extension": extension_name,
+            "handler": handler,
+        })
+
+    def _extension_roots(self):
+        home_dir = os.path.join(self.project_root, "[home]")
+        return [
+            os.path.join(home_dir, "plugins"),
+            os.path.join(home_dir, "hooks"),
+        ]
+
+    def _normalize_event_name(self, event_name):
+        raw = str(event_name or "").strip()
+        return HOOK_ALIASES.get(raw, raw)
+
+    def _configured_allowlist(self):
+        raw = (
+            self.config.get("plugin_allowlist")
+            or self.config.get("plugins_allowlist")
+            or self.config.get("extension_allowlist")
+            or self.config.get("extensions_allowlist")
+            or []
+        )
+        if isinstance(raw, str):
+            raw = [raw]
+        if not isinstance(raw, (list, tuple, set)):
+            return set()
+        return {
+            str(item).strip().replace("\\", "/")
+            for item in raw
+            if str(item).strip()
+        }
+
+    def _apply_allowlist(self, paths):
+        allowlist = self._configured_allowlist()
+        if not allowlist:
+            return paths
+        allowed = []
+        blocked = []
+        for path in paths:
+            rel = os.path.relpath(path, self.project_root).replace("\\", "/")
+            base = os.path.basename(path)
+            if rel in allowlist or base in allowlist:
+                allowed.append(path)
+            else:
+                blocked.append(rel)
+        if blocked:
+            logger.warning(
+                "Skipping non-allowlisted extensions: %s",
+                ", ".join(sorted(blocked)),
+            )
+        return allowed
+
+    def _warn_extension_execution(self, paths):
+        if not paths:
+            return
+        rendered = ", ".join(
+            sorted(os.path.relpath(path, self.project_root).replace("\\", "/") for path in paths)
+        )
+        if self._configured_allowlist():
+            logger.warning("Executing allowlisted TW extensions: %s", rendered)
+        else:
+            logger.warning(
+                "Executing TW extensions from project code: %s. Review these files carefully or configure `plugin_allowlist` in `tw.config`.",
+                rendered,
+            )
+
+    def _load_extension(self, path):
+        name = os.path.splitext(os.path.basename(path))[0]
+        module_name = f"tw_ext_{name}_{content_hash(path, length=10)}"
+        spec = importlib.util.spec_from_file_location(module_name, path)
+        if spec is None or spec.loader is None:
+            self.errors.append(f"{path}: failed to create import spec")
+            return
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+            api = PluginAPI(self, name)
+            if hasattr(module, "register") and callable(module.register):
+                module.register(api)
+            hooks = getattr(module, "hooks", None)
+            if isinstance(hooks, dict):
+                for event_name, handler in hooks.items():
+                    api.register_hook(event_name, handler)
+            self.extensions.append(LoadedExtension(name=name, path=path, module=module))
+        except Exception as err:
+            tb = traceback.format_exc()
+            logger.exception("Failed to load extension: %s", path)
+            self.errors.append(f"{path}: {err}\n{tb}")

tw_framework/production_optimizer.py

@@ -0,0 +1,82 @@
+"""
+Production optimization for TW Framework.
+
+Generates production output with minified HTML, CSS, JS, compressed assets,
+and hashed filenames.
+"""
+
+import gzip
+import hashlib
+import logging
+import os
+import shutil
+from typing import List, Optional
+
+from . import compiler
+
+logger = logging.getLogger(__name__)
+
+
+def optimize_for_production(output_dir: str):
+    """Apply production optimizations to the output directory."""
+    # Minify HTML files
+    for root, _, files in os.walk(output_dir):
+        for fname in files:
+            if fname.endswith(".html"):
+                path = os.path.join(root, fname)
+                with open(path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                minified = compiler.minify_html_content(content)
+                with open(path, "w", encoding="utf-8") as f:
+                    f.write(minified)
+
+    # Minify CSS files
+    for root, _, files in os.walk(output_dir):
+        for fname in files:
+            if fname.endswith(".css"):
+                path = os.path.join(root, fname)
+                with open(path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                minified = compiler.minify_css_content(content)
+                with open(path, "w", encoding="utf-8") as f:
+                    f.write(minified)
+
+    # Minify JS files
+    for root, _, files in os.walk(output_dir):
+        for fname in files:
+            if fname.endswith(".js"):
+                path = os.path.join(root, fname)
+                with open(path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                minified = compiler.minify_js_content(content)
+                with open(path, "w", encoding="utf-8") as f:
+                    f.write(minified)
+
+    # Gzip compress files
+    for root, _, files in os.walk(output_dir):
+        for fname in files:
+            if fname.endswith((".html", ".css", ".js", ".json", ".xml", ".txt", ".svg")):
+                path = os.path.join(root, fname)
+                with open(path, "rb") as f:
+                    data = f.read()
+                with gzip.open(path + ".gz", "wb", compresslevel=9) as gz:
+                    gz.write(data)
+
+    # Hash filenames for cache busting
+    for root, _, files in os.walk(output_dir):
+        for fname in files:
+            if fname.endswith((".css", ".js")):
+                path = os.path.join(root, fname)
+                with open(path, "rb") as f:
+                    data = f.read()
+                digest = hashlib.sha256(data).hexdigest()[:12]
+                name, ext = os.path.splitext(fname)
+                hashed_name = f"{name}.{digest}{ext}"
+                hashed_path = os.path.join(root, hashed_name)
+                if not os.path.exists(hashed_path):
+                    shutil.copy2(path, hashed_path)
+                # Remove original file
+                os.remove(path)
+
+
+__all__ = ["optimize_for_production"]

tw_framework/reactivity.py

@@ -0,0 +1,349 @@
+"""
+TW Client Reactivity System
+Generates a lightweight JS runtime injected into pages that use:
+  - state { ... }       -> reactive variables
+  - bind:value          -> two-way input binding
+  - on:click / on:input -> event handlers
+  - show:condition      -> conditional display
+  - tw-for / tw-each    -> client-side list rendering (from JSON endpoint or inline array)
+  - tw-ref              -> DOM refs
+
+This module:
+1. Parses .tw page/component nodes and detects reactivity usage
+2. Emits a minimal vanilla-JS runtime (~2KB gzipped) per page
+3. Hooks into the compiler's render pipeline via page-level `script {}` injection
+
+No framework deps. No virtual DOM. Direct DOM updates.
+"""
+
+import json
+import re
+
+# ─── Runtime JS (injected once per page that uses reactivity) ─────────────────
+
+_TW_REACTIVE_RUNTIME = r"""
+(function() {
+'use strict';
+
+// ── State store ──────────────────────────────────────────────────────────────
+var __twState = {};
+var __twWatchers = {};
+var __twRefs = {};
+
+function __twDefineState(initialState) {
+  Object.keys(initialState).forEach(function(key) {
+    __twState[key] = initialState[key];
+  });
+  __twSync();
+}
+
+function __twSet(key, value) {
+  if (__twState[key] === value) return;
+  __twState[key] = value;
+  (__twWatchers[key] || []).forEach(function(fn) { try { fn(value); } catch(e){} });
+  __twSync();
+}
+
+function __twGet(key) {
+  return __twState[key];
+}
+
+function __twWatch(key, fn) {
+  if (!__twWatchers[key]) __twWatchers[key] = [];
+  __twWatchers[key].push(fn);
+}
+
+// ── DOM sync ──────────────────────────────────────────────────────────────────
+function __twSync() {
+  // bind:value — sync input values
+  document.querySelectorAll('[data-tw-bind]').forEach(function(el) {
+    var key = el.getAttribute('data-tw-bind');
+    if (el !== document.activeElement && key in __twState) {
+      if (el.type === 'checkbox') {
+        el.checked = !!__twState[key];
+      } else {
+        el.value = __twState[key] !== null && __twState[key] !== undefined ? __twState[key] : '';
+      }
+    }
+  });
+
+  // show: — toggle visibility
+  document.querySelectorAll('[data-tw-show]').forEach(function(el) {
+    var expr = el.getAttribute('data-tw-show');
+    var val = __twEval(expr);
+    el.style.display = val ? '' : 'none';
+  });
+
+  // tw-text — update text content
+  document.querySelectorAll('[data-tw-text]').forEach(function(el) {
+    var expr = el.getAttribute('data-tw-text');
+    var val = __twEval(expr);
+    el.textContent = val !== null && val !== undefined ? String(val) : '';
+  });
+
+  // tw-html — update inner HTML (escaped)
+  document.querySelectorAll('[data-tw-html]').forEach(function(el) {
+    var expr = el.getAttribute('data-tw-html');
+    var val = __twEval(expr);
+    el.innerHTML = val !== null && val !== undefined ? String(val) : '';
+  });
+
+  // class: — conditional class
+  document.querySelectorAll('[data-tw-class]').forEach(function(el) {
+    try {
+      var pairs = JSON.parse(el.getAttribute('data-tw-class'));
+      Object.keys(pairs).forEach(function(cls) {
+        el.classList.toggle(cls, !!__twEval(pairs[cls]));
+      });
+    } catch(e) {}
+  });
+
+  // tw-for — client-side list rendering
+  document.querySelectorAll('[data-tw-for]').forEach(function(container) {
+    var expr = container.getAttribute('data-tw-for');
+    var tmpl = container.querySelector('[data-tw-for-template]');
+    if (!tmpl) return;
+    var items = __twEval(expr);
+    if (!Array.isArray(items)) return;
+    var existing = container.querySelectorAll('[data-tw-for-item]');
+    existing.forEach(function(el) { el.remove(); });
+    items.forEach(function(item, idx) {
+      var clone = tmpl.cloneNode(true);
+      clone.removeAttribute('data-tw-for-template');
+      clone.setAttribute('data-tw-for-item', idx);
+      clone.style.display = '';
+      // Interpolate {item.*} / {item} in text nodes and attributes
+      __twInterpolateNode(clone, { item: item, index: idx });
+      container.appendChild(clone);
+    });
+  });
+}
+
+// ── Safe expression evaluator ────────────────────────────────────────────────
+function __twEval(expr) {
+  try {
+    var fn = new Function(
+      Object.keys(__twState).join(','),
+      'try { return (' + expr + '); } catch(e) { return undefined; }'
+    );
+    return fn.apply(null, Object.keys(__twState).map(function(k) { return __twState[k]; }));
+  } catch(e) {
+    return undefined;
+  }
+}
+
+// ── Text interpolation for tw-for clones ─────────────────────────────────────
+function __twInterpolateNode(root, ctx) {
+  var walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null, false);
+  var node;
+  while ((node = walker.nextNode())) {
+    node.textContent = node.textContent.replace(/\{([^{}]+)\}/g, function(_, expr) {
+      try {
+        var fn = new Function(Object.keys(ctx).join(','), 'try{return('+expr+');}catch(e){return "";}');
+        var v = fn.apply(null, Object.keys(ctx).map(function(k){return ctx[k];}));
+        return v !== null && v !== undefined ? v : '';
+      } catch(e) { return ''; }
+    });
+  }
+  root.querySelectorAll('*').forEach(function(el) {
+    Array.from(el.attributes).forEach(function(attr) {
+      if (attr.name.startsWith('data-tw-')) return;
+      attr.value = attr.value.replace(/\{([^{}]+)\}/g, function(_, expr) {
+        try {
+          var fn = new Function(Object.keys(ctx).join(','), 'try{return('+expr+');}catch(e){return "";}');
+          var v = fn.apply(null, Object.keys(ctx).map(function(k){return ctx[k];}));
+          return v !== null && v !== undefined ? v : '';
+        } catch(e) { return ''; }
+      });
+    });
+  });
+}
+
+// ── Event binding ─────────────────────────────────────────────────────────────
+function __twBindEvents() {
+  // bind:value -> two-way binding
+  document.querySelectorAll('[data-tw-bind]').forEach(function(el) {
+    if (el.__twBound) return;
+    el.__twBound = true;
+    var key = el.getAttribute('data-tw-bind');
+    var eventName = (el.type === 'checkbox' || el.tagName === 'SELECT') ? 'change' : 'input';
+    el.addEventListener(eventName, function() {
+      var val = el.type === 'checkbox' ? el.checked : el.value;
+      __twSet(key, val);
+    });
+  });
+
+  // on:* -> event handlers
+  document.querySelectorAll('[data-tw-on]').forEach(function(el) {
+    if (el.__twOnBound) return;
+    el.__twOnBound = true;
+    try {
+      var handlers = JSON.parse(el.getAttribute('data-tw-on'));
+      Object.keys(handlers).forEach(function(eventName) {
+        el.addEventListener(eventName, function(event) {
+          var expr = handlers[eventName];
+          try {
+            var fn = new Function(
+              Object.keys(__twState).concat(['event', '__twSet', '__twGet']).join(','),
+              expr
+            );
+            fn.apply(null, Object.keys(__twState).map(function(k) { return __twState[k]; }).concat([event, __twSet, __twGet]));
+          } catch(e) { console.error('TW event error:', e); }
+          __twSync();
+        });
+      });
+    } catch(e) {}
+  });
+
+  // tw-ref
+  document.querySelectorAll('[data-tw-ref]').forEach(function(el) {
+    __twRefs[el.getAttribute('data-tw-ref')] = el;
+  });
+}
+
+// ── Fetch helper for API calls ───────────────────────────────────────────────
+window.__twFetch = async function(url, options) {
+  options = options || {};
+  var method = (options.method || 'GET').toUpperCase();
+  var headers = Object.assign({ 'Content-Type': 'application/json' }, options.headers || {});
+  var body = options.body !== undefined ? JSON.stringify(options.body) : undefined;
+  try {
+    var res = await fetch(url, { method: method, headers: headers, body: body });
+    var ct = res.headers.get('content-type') || '';
+    var data = ct.includes('application/json') ? await res.json() : await res.text();
+    return { ok: res.ok, status: res.status, data: data };
+  } catch(e) {
+    return { ok: false, status: 0, data: null, error: e.message };
+  }
+};
+
+// ── Public API ────────────────────────────────────────────────────────────────
+window.__tw = {
+  state: __twState,
+  set: __twSet,
+  get: __twGet,
+  watch: __twWatch,
+  sync: __twSync,
+  refs: __twRefs,
+  eval: __twEval,
+  fetch: __twFetch,
+};
+
+// ── Init on DOM ready ─────────────────────────────────────────────────────────
+function __twInit() {
+  __twBindEvents();
+  __twSync();
+  // Re-bind after dynamic DOM changes (tw-for, etc.)
+  var observer = new MutationObserver(function() {
+    __twBindEvents();
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', __twInit);
+} else {
+  __twInit();
+}
+
+})();
+"""
+
+# ─── Compiler directive parsers ───────────────────────────────────────────────
+
+_STATE_BLOCK_RE = re.compile(r'\bstate\s*\{([^}]*)\}', re.DOTALL)
+_STATE_KV_RE = re.compile(r'(\w+)\s+(.+?)(?=\n\s*\w|\Z)', re.DOTALL)
+
+
+def parse_state_block(source: str) -> dict:
+    """
+    Parse:
+        state {
+            count 0
+            name "hello"
+            items []
+        }
+    Returns {"count": 0, "name": "hello", "items": []}
+    """
+    state = {}
+    for block_match in _STATE_BLOCK_RE.finditer(source):
+        body = block_match.group(1)
+        for kv in _STATE_KV_RE.finditer(body.strip()):
+            key = kv.group(1).strip()
+            raw = kv.group(2).strip()
+            from . import compiler as _c
+            val = _c.parse_literal_value(raw)
+            # Strip outer quotes from string values
+            if isinstance(val, str) and len(val) >= 2 and val[0] == val[-1] and val[0] in ('"', "'"):
+                val = val[1:-1]
+            state[key] = val
+    return state
+
+
+def has_reactivity(source: str) -> bool:
+    """Quick check: does this .tw file use any reactive features?"""
+    patterns = [
+        r'\bstate\s*\{',
+        r'\bbind:',
+        r'\bon:',
+        r'\bshow:',
+        r'\btw-for\b',
+        r'\btw-text\b',
+        r'\btw-ref\b',
+    ]
+    return any(re.search(p, source) for p in patterns)
+
+
+def build_state_init_script(state: dict) -> str:
+    """Generates the inline script that seeds __twDefineState."""
+    if not state:
+        return ""
+    return f"__twDefineState({json.dumps(state, ensure_ascii=False)});"
+
+
+def get_reactivity_runtime_js() -> str:
+    return _TW_REACTIVE_RUNTIME
+
+
+# ─── HTML attribute transformer ───────────────────────────────────────────────
+# These convert .tw reactive directives to data-tw-* HTML attributes
+# so the runtime JS can pick them up.
+
+def transform_reactive_attrs(attrs: list) -> list:
+    """
+    Convert:
+        bind:value "count"   -> data-tw-bind="count"
+        show:visible "count > 0" -> data-tw-show="count > 0"
+        on:click "count++"   -> data-tw-on='{"click":"count++"}'
+        tw-ref "myInput"     -> data-tw-ref="myInput"
+        tw-text "count"      -> data-tw-text="count"
+    """
+    out = []
+    on_handlers = {}
+    for name, value in attrs:
+        nl = name.lower()
+        if nl.startswith("bind:"):
+            out.append(("data-tw-bind", value))
+        elif nl.startswith("show:"):
+            out.append(("data-tw-show", value))
+        elif nl.startswith("on:"):
+            event = nl[3:]
+            on_handlers[event] = value
+        elif nl in {"tw-ref", "tw:ref"}:
+            out.append(("data-tw-ref", value))
+        elif nl in {"tw-text", "tw:text"}:
+            out.append(("data-tw-text", value))
+        elif nl in {"tw-html", "tw:html"}:
+            out.append(("data-tw-html", value))
+        elif nl in {"tw-for", "tw:for"}:
+            out.append(("data-tw-for", value))
+        elif nl in {"tw-class", "tw:class"}:
+            # Expect JSON string: '{"active": "isActive", "hidden": "!show"}'
+            out.append(("data-tw-class", value))
+        else:
+            out.append((name, value))
+
+    if on_handlers:
+        out.append(("data-tw-on", json.dumps(on_handlers)))
+
+    return out