@ape-egg/vibe 2.1.21 → 2.3.0

package/compiler/src/compiler/spa.rs

@@ -0,0 +1,477 @@
+// SPA mode (fetched): compiles the MPA pages tree into page-component
+// fragments under /components/vibe-spa/, a generated route table, and a
+// composed index.html shell that boots @ape-egg/vibe/spa with a reactive
+// `<component src="@[page.src]">` outlet. The composed shell is plain tier-2
+// runtime-Vibe code — the invariant that compiled output is always runtime
+// Vibe code holds.
+//
+// Everything is per-page on purpose: future per-page SPA selection becomes a
+// filter over pages, not a rework.
+
+use regex::Regex;
+
+/// One page of the pages tree, dissected for SPA output.
+pub struct SpaPage {
+    /// Pages-relative source path, e.g. "brawlers/$index.html"
+    pub rel_path: String,
+    /// Route template, e.g. "/brawlers/:index"
+    pub route: String,
+    /// Fragment URL, e.g. "/components/vibe-spa/brawlers/$index.html"
+    pub src: String,
+    /// Harvested <title> text
+    pub title: Option<String>,
+    /// Fragment markup: page styles + rewritten page scripts + body content
+    pub fragment: String,
+    /// Head resources for shell composition (styles/scripts/title excluded)
+    pub head_items: Vec<HeadItem>,
+    /// Body attributes in authored order: (name, Some(value) | None)
+    pub body_attrs: Vec<(String, Option<String>)>,
+    /// The page's vibe import specifier, pre-rewrite (shell import harvest)
+    pub vibe_import: Option<String>,
+    /// First side-effect API found without an `$.on('unmount'` teardown
+    pub hygiene_offender: Option<&'static str>,
+}
+
+#[derive(Clone, PartialEq)]
+pub enum HeadKind {
+    Meta,
+    Other,
+}
+
+#[derive(Clone)]
+pub struct HeadItem {
+    pub kind: HeadKind,
+    /// Whitespace-collapsed form — both the dedup key and the emitted markup
+    pub normalized: String,
+}
+
+pub struct ShellComposition {
+    pub html: String,
+    /// Verbose-mode notes: dropped page-specific meta, body attr divergence
+    pub notes: Vec<String>,
+}
+
+/// Map a pages-relative file path to its route template. Grammar shared with
+/// the runtime route scanners: `$param` captures one segment, a terminal
+/// `$$name` file is an optional catch-all (`:name*`), a literal terminal
+/// `index` serves its directory path.
+pub fn route_for(rel_path: &str) -> String {
+    let no_ext = rel_path.strip_suffix(".html").unwrap_or(rel_path);
+    let mut segments: Vec<&str> = no_ext.split('/').filter(|s| !s.is_empty()).collect();
+    if segments.last() == Some(&"index") {
+        segments.pop();
+    }
+    let catch_all = segments
+        .last()
+        .map_or(false, |s| s.starts_with("$$"));
+    let tail = if catch_all { segments.pop() } else { None };
+    let mut parts: Vec<String> = segments
+        .iter()
+        .map(|s| match s.strip_prefix('$') {
+            Some(param) => format!(":{}", param),
+            None => s.to_string(),
+        })
+        .collect();
+    if let Some(tail) = tail {
+        parts.push(format!(":{}*", &tail[2..]));
+    }
+    format!("/{}", parts.join("/"))
+}
+
+/// Route-table order, most-specific-first for a first-match-wins resolver:
+/// non-catch-alls before catch-alls, deeper before shallower, statics before
+/// params, then lexicographic for determinism. (game-stack's scanRoutes sorts
+/// deepest-first over dynamic routes only; a full table additionally needs
+/// the exact-beats-param and everything-beats-catch-all rules.) Returns
+/// indices so `pages` keeps its stable path order for shell composition.
+pub fn route_order(pages: &[SpaPage]) -> Vec<usize> {
+    let depth = |route: &str| route.split('/').filter(|s| !s.is_empty()).count();
+    let params = |route: &str| route.split('/').filter(|s| s.starts_with(':')).count();
+    let mut order: Vec<usize> = (0..pages.len()).collect();
+    order.sort_by(|&x, &y| {
+        let a = &pages[x].route;
+        let b = &pages[y].route;
+        a.ends_with('*')
+            .cmp(&b.ends_with('*'))
+            .then(depth(b).cmp(&depth(a)))
+            .then(params(a).cmp(&params(b)))
+            .then(a.cmp(b))
+    });
+    order
+}
+
+/// The specifier a page uses to import vibe — the shell reuses the project's
+/// own working import style instead of inventing one. Fragment scripts are
+/// carried byte-identical: vibe() itself applies defaults semantics once
+/// booted (state is app-lifetime; re-mounts seed missing keys only), so no
+/// import rewrite is needed.
+pub fn harvest_vibe_import(script: &str) -> Option<String> {
+    Regex::new(r#"from\s*['"]([^'"]*@ape-egg/vibe(?:/index\.js)?)['"]"#)
+        .unwrap()
+        .captures(script)
+        .map(|caps| caps[1].to_string())
+}
+
+/// Derive the @ape-egg/vibe/spa specifier from the harvested vibe specifier.
+pub fn spa_import_for(vibe_spec: &str) -> String {
+    match vibe_spec.strip_suffix("/index.js") {
+        Some(base) => format!("{}/spa.js", base),
+        None => format!("{}/spa", vibe_spec),
+    }
+}
+
+/// Grep-level unmount hygiene (a teaching aid, not a guarantee): a page
+/// script that starts side effects and never references `$.on('unmount'`
+/// will leak them across SPA navigations.
+pub fn hygiene_offender(script: &str) -> Option<&'static str> {
+    if script.contains("$.on('unmount'") || script.contains("$.on(\"unmount\"") {
+        return None;
+    }
+    ["setInterval", "setTimeout", "addEventListener", "new WebSocket"]
+        .iter()
+        .find(|api| script.contains(*api))
+        .copied()
+}
+
+fn collapse_whitespace(html: &str) -> String {
+    let mut out = String::with_capacity(html.len());
+    let mut in_space = false;
+    for ch in html.trim().chars() {
+        if ch.is_whitespace() {
+            if !in_space {
+                out.push(' ');
+                in_space = true;
+            }
+        } else {
+            out.push(ch);
+            in_space = false;
+        }
+    }
+    out
+}
+
+/// Dissect a compiled page into its SPA parts. `html` is the page AFTER the
+/// normal compile transforms (component handling, element transform) so the
+/// fragment is exactly what the MPA output would have carried.
+pub fn dissect_page(rel_path: &str, html: &str) -> Result<SpaPage, String> {
+    let head_re = Regex::new(r"(?is)<head[^>]*>(.*?)</head>").unwrap();
+    let body_re = Regex::new(r"(?is)<body([^>]*)>(.*)</body>").unwrap();
+
+    let head = head_re
+        .captures(html)
+        .map(|caps| caps[1].to_string())
+        .unwrap_or_default();
+    let body_caps = body_re
+        .captures(html)
+        .ok_or_else(|| format!("pages/{} has no <body> — SPA pages need one", rel_path))?;
+    let body_attrs_raw = body_caps[1].to_string();
+    let body_inner = body_caps[2].trim_matches('\n').to_string();
+
+    // Comments never travel to the shell head.
+    let head = Regex::new(r"(?s)<!--.*?-->").unwrap().replace_all(&head, "");
+
+    let style_re = Regex::new(r"(?is)<style[^>]*>.*?</style>").unwrap();
+    let styles: Vec<String> = style_re
+        .find_iter(&head)
+        .map(|m| m.as_str().trim().to_string())
+        .collect();
+    let head = style_re.replace_all(&head, "");
+
+    let script_re = Regex::new(r#"(?is)<script[^>]*type=["']module["'][^>]*>.*?</script>"#).unwrap();
+    let scripts: Vec<String> = script_re
+        .find_iter(&head)
+        .map(|m| m.as_str().trim().to_string())
+        .collect();
+    let head = script_re.replace_all(&head, "");
+
+    let title_re = Regex::new(r"(?is)<title[^>]*>(.*?)</title>").unwrap();
+    let title = title_re
+        .captures(&head)
+        .map(|caps| collapse_whitespace(&caps[1]))
+        .filter(|t| !t.is_empty());
+    let head = title_re.replace_all(&head, "");
+
+    let item_re = Regex::new(
+        r"(?is)<(?:meta|link|base)\b[^>]*/?>|<script\b[^>]*>.*?</script>|<noscript\b[^>]*>.*?</noscript>",
+    )
+    .unwrap();
+    let head_items: Vec<HeadItem> = item_re
+        .find_iter(&head)
+        .map(|m| {
+            let normalized = collapse_whitespace(m.as_str());
+            let kind = if normalized.to_lowercase().starts_with("<meta") {
+                HeadKind::Meta
+            } else {
+                HeadKind::Other
+            };
+            HeadItem { kind, normalized }
+        })
+        .collect();
+
+    let attr_re = Regex::new(r#"([^\s"'=]+)(?:="([^"]*)")?"#).unwrap();
+    let body_attrs: Vec<(String, Option<String>)> = attr_re
+        .captures_iter(&body_attrs_raw)
+        .map(|caps| (caps[1].to_string(), caps.get(2).map(|v| v.as_str().to_string())))
+        .collect();
+
+    let vibe_import = scripts.iter().find_map(|s| harvest_vibe_import(s));
+    let offender = scripts.iter().find_map(|s| hygiene_offender(s));
+
+    let mut fragment = String::new();
+    for style in &styles {
+        fragment.push_str(style);
+        fragment.push('\n');
+    }
+    if !styles.is_empty() && !scripts.is_empty() {
+        fragment.push('\n');
+    }
+    for script in &scripts {
+        fragment.push_str(script);
+        fragment.push('\n');
+    }
+    if !(styles.is_empty() && scripts.is_empty()) {
+        fragment.push('\n');
+    }
+    fragment.push_str(&body_inner);
+    if !fragment.ends_with('\n') {
+        fragment.push('\n');
+    }
+
+    Ok(SpaPage {
+        rel_path: rel_path.to_string(),
+        route: route_for(rel_path),
+        src: format!("/components/vibe-spa/{}", rel_path),
+        title,
+        fragment,
+        head_items,
+        body_attrs,
+        vibe_import,
+        hygiene_offender: offender,
+    })
+}
+
+/// Compose the shell: deduped head union + '/' route's title, union body
+/// attrs minus vibe-fouc, one generated boot script, the route outlet. Meta tags
+/// keep only the set common to every page (per-route meta is future work);
+/// links and shared scripts stack as a deduped union.
+pub fn compose_shell(pages: &[SpaPage], route_order: &[usize]) -> ShellComposition {
+    let mut notes = Vec::new();
+
+    let vibe_spec = pages
+        .iter()
+        .enumerate()
+        .find(|(_, p)| p.route == "/")
+        .and_then(|(_, p)| p.vibe_import.clone())
+        .or_else(|| pages.iter().find_map(|p| p.vibe_import.clone()))
+        // Nothing harvestable (vibe imported only transitively through the
+        // project's own bundled modules): fall back to the conventional
+        // browser-resolvable path — a bare specifier would need an import map.
+        .unwrap_or_else(|| "/node_modules/@ape-egg/vibe/index.js".to_string());
+    let spa_spec = spa_import_for(&vibe_spec);
+
+    let title = pages
+        .iter()
+        .find(|p| p.route == "/")
+        .and_then(|p| p.title.clone())
+        .or_else(|| pages.iter().find_map(|p| p.title.clone()));
+
+    // Meta intersection: normalized form present in every page survives.
+    let meta_kept: Vec<String> = pages
+        .first()
+        .map(|first| {
+            first
+                .head_items
+                .iter()
+                .filter(|item| item.kind == HeadKind::Meta)
+                .filter(|item| {
+                    pages.iter().all(|p| {
+                        p.head_items
+                            .iter()
+                            .any(|other| other.normalized == item.normalized)
+                    })
+                })
+                .map(|item| item.normalized.clone())
+                .collect()
+        })
+        .unwrap_or_default();
+
+    for page in pages {
+        for item in &page.head_items {
+            if item.kind == HeadKind::Meta && !meta_kept.contains(&item.normalized) {
+                notes.push(format!(
+                    "pages/{}: page-specific {} dropped from the shell head (per-route meta is future work)",
+                    page.rel_path, item.normalized
+                ));
+            }
+        }
+    }
+
+    // Union of everything else, deduped, first-seen order (metas keep their
+    // intersection set, also first-seen).
+    let mut head_lines: Vec<String> = Vec::new();
+    for page in pages {
+        for item in &page.head_items {
+            let keep = match item.kind {
+                HeadKind::Meta => meta_kept.contains(&item.normalized),
+                HeadKind::Other => true,
+            };
+            if keep && !head_lines.contains(&item.normalized) {
+                head_lines.push(item.normalized.clone());
+            }
+        }
+    }
+
+    // Body attribute union, first-seen order and value; disagreements noted.
+    let mut body_attrs: Vec<(String, Option<String>)> = Vec::new();
+    for page in pages {
+        for (name, value) in &page.body_attrs {
+            match body_attrs.iter().find(|(n, _)| n == name) {
+                None => body_attrs.push((name.clone(), value.clone())),
+                Some((_, kept)) if kept != value => notes.push(format!(
+                    "body attribute \"{}\" differs across pages — shell keeps the first-seen value",
+                    name
+                )),
+                Some(_) => {}
+            }
+        }
+    }
+    for page in pages {
+        for (name, _) in &page.body_attrs {
+            if !pages.iter().all(|p| p.body_attrs.iter().any(|(n, _)| n == name)) {
+                let note = format!(
+                    "body attribute \"{}\" is not on every page (e.g. pages/{}) — shell uses the union",
+                    name, page.rel_path
+                );
+                if !notes.contains(&note) {
+                    notes.push(note);
+                }
+            }
+        }
+    }
+    // vibe-fouc absence is the compiled-mode marker (the runtime gates
+    // hyperspeed manifest loading on it). The shell is compiled output:
+    // strip the attribute from the union — there is nothing to flash, the
+    // outlet is empty and fragments hydrate off-DOM before insertion.
+    body_attrs.retain(|(n, _)| n != "vibe-fouc");
+
+    let body_attr_str = body_attrs
+        .iter()
+        .map(|(name, value)| match value {
+            Some(value) => format!("{}=\"{}\"", name, value),
+            None => name.clone(),
+        })
+        .collect::<Vec<_>>()
+        .join(" ");
+
+    let mut routes_js = String::new();
+    for &i in route_order {
+        let page = &pages[i];
+        routes_js.push_str("        { \"route\": ");
+        routes_js.push_str(&serde_json::to_string(&page.route).unwrap());
+        routes_js.push_str(", \"src\": ");
+        routes_js.push_str(&serde_json::to_string(&page.src).unwrap());
+        if let Some(title) = &page.title {
+            routes_js.push_str(", \"title\": ");
+            routes_js.push_str(&serde_json::to_string(title).unwrap());
+        }
+        routes_js.push_str(" },\n");
+    }
+
+    let mut html = String::from("<!DOCTYPE html>\n<html>\n  <head>\n");
+    if let Some(title) = &title {
+        html.push_str("    <title>");
+        html.push_str(title);
+        html.push_str("</title>\n");
+    }
+    for line in &head_lines {
+        html.push_str("    ");
+        html.push_str(line);
+        html.push('\n');
+    }
+    html.push_str("\n    <script type=\"module\">\n");
+    html.push_str(&format!("      import vibe from \"{}\";\n", vibe_spec));
+    html.push_str(&format!(
+        "      import {{ setupSpa, resolve }} from \"{}\";\n\n",
+        spa_spec
+    ));
+    html.push_str("      const routes = [\n");
+    html.push_str(&routes_js);
+    html.push_str("      ];\n\n");
+    html.push_str("      window.$ = vibe({ page: resolve(location, routes) ?? {} });\n");
+    html.push_str("      setupSpa({ routes });\n");
+    html.push_str("    </script>\n  </head>\n\n");
+    html.push_str(&format!("  <body {}>\n", body_attr_str));
+    // Keyed outlet: a key (page.path) change remounts even when the src is
+    // unchanged, so param→param navigation on the same route mounts fresh.
+    html.push_str("    <component src=\"@[page.src]\" key=\"@[page.path]\"></component>\n");
+    html.push_str("  </body>\n</html>\n");
+
+    ShellComposition { html, notes }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn route_grammar_matches_the_scanners() {
+        assert_eq!(route_for("index.html"), "/");
+        assert_eq!(route_for("about.html"), "/about");
+        assert_eq!(route_for("docs/index.html"), "/docs");
+        assert_eq!(route_for("brawlers/$index.html"), "/brawlers/:index");
+        assert_eq!(route_for("docs/$$rest.html"), "/docs/:rest*");
+        assert_eq!(route_for("$$rest.html"), "/:rest*");
+        assert_eq!(route_for("shop/$id/cart.html"), "/shop/:id/cart");
+    }
+
+    fn page(route: &str) -> SpaPage {
+        SpaPage {
+            rel_path: String::new(),
+            route: route.to_string(),
+            src: String::new(),
+            title: None,
+            fragment: String::new(),
+            head_items: vec![],
+            body_attrs: vec![],
+            vibe_import: None,
+            hygiene_offender: None,
+        }
+    }
+
+    #[test]
+    fn orders_most_specific_first() {
+        let pages = vec![
+            page("/"),
+            page("/:all*"),
+            page("/brawlers/:index"),
+            page("/brawlers/new"),
+            page("/docs/:rest*"),
+            page("/about"),
+        ];
+        let routes: Vec<&str> = route_order(&pages)
+            .into_iter()
+            .map(|i| pages[i].route.as_str())
+            .collect();
+        assert_eq!(
+            routes,
+            vec!["/brawlers/new", "/brawlers/:index", "/about", "/", "/docs/:rest*", "/:all*"]
+        );
+    }
+
+    #[test]
+    fn harvests_and_derives_shell_imports() {
+        assert_eq!(
+            harvest_vibe_import("import vibe from '/nodemodules/@ape-egg/vibe/index.js';"),
+            Some("/nodemodules/@ape-egg/vibe/index.js".to_string())
+        );
+        assert_eq!(spa_import_for("/nodemodules/@ape-egg/vibe/index.js"), "/nodemodules/@ape-egg/vibe/spa.js");
+        assert_eq!(spa_import_for("@ape-egg/vibe"), "@ape-egg/vibe/spa");
+    }
+
+    #[test]
+    fn hygiene_flags_side_effects_without_teardown() {
+        assert_eq!(hygiene_offender("setInterval(() => {}, 100)"), Some("setInterval"));
+        assert_eq!(hygiene_offender("setInterval(x); $.on('unmount', stop)"), None);
+        assert_eq!(hygiene_offender("const x = 1;"), None);
+    }
+}