@ape-egg/vibe-compiler 3.0.0

package/src/compiler/spa.rs

@@ -0,0 +1,612 @@
+// 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);
+    // The 404 convention: a `404.html` in the pages tree compiles to the
+    // declared '*' fallback — no-match deep links mount it instead of a
+    // permanently blank outlet. The runtime resolves it with
+    // name: 'not-found' and it never claims a click.
+    if no_ext == "404" || no_ext.ends_with("/404") {
+        return "*".to_string();
+    }
+    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,
+    })
+}
+
+/// Scan a page body for the hoistable-layout shape: ignoring whitespace,
+/// comments and top-level <script> blocks, the body must be EXACTLY ONE
+/// `<component src="…">` element. Returns (open_tag, src, inner_html).
+/// In-body scripts stay page code (they ride the fragment prelude), so they
+/// don't break the shape.
+pub fn detect_layout_root(raw_source: &str) -> Option<(String, String, String)> {
+    let body_re = Regex::new(r"(?is)<body[^>]*>(.*)</body>").unwrap();
+    let body_caps = body_re.captures(raw_source)?;
+    let body_match = body_caps.get(1)?;
+    let body_inner = body_match.as_str();
+
+    let comment_re = Regex::new(r"(?s)<!--.*?-->").unwrap();
+    let cleaned = comment_re.replace_all(body_inner, "");
+    let script_re = Regex::new(r"(?is)<script\b[^>]*>.*?</script>").unwrap();
+    // Top-level <style> blocks are page assets that ride the fragment, same
+    // as scripts — the page-styles-at-body-bottom convention must not break
+    // the "layout + slot content" shape.
+    let page_style_re = Regex::new(r"(?is)<style\b[^>]*>.*?</style>").unwrap();
+    let cleaned = script_re.replace_all(&cleaned, "");
+    let cleaned = page_style_re.replace_all(&cleaned, "");
+    let trimmed = cleaned.trim();
+
+    let open_re = Regex::new(r#"(?is)^<component\b((?:"[^"]*"|'[^']*'|[^>"'])*)>"#).unwrap();
+    let caps = open_re.captures(trimmed)?;
+    let open_tag = caps.get(0).unwrap().as_str().to_string();
+    let attrs = caps.get(1).unwrap().as_str();
+    let src_re = Regex::new(r#"(?i)src\s*=\s*"([^"]+)""#).unwrap();
+    let src = src_re.captures(attrs)?.get(1).unwrap().as_str().to_string();
+
+    // Find the matching </component> by depth over a MASKED copy of the body:
+    // comments, scripts and styles are space-filled at identical byte offsets,
+    // so a textual '<component' mention inside them can't corrupt the count —
+    // while every index still slices the ORIGINAL body (the slot content keeps
+    // its scripts/comments verbatim in the splices below).
+    let mask = |mut masked: String, re: &Regex| {
+        let spans: Vec<(usize, usize)> =
+            re.find_iter(&masked).map(|m| (m.start(), m.end())).collect();
+        for (s, e) in spans {
+            masked.replace_range(s..e, &" ".repeat(e - s));
+        }
+        masked
+    };
+    let masked_body = mask(
+        mask(mask(body_inner.to_string(), &comment_re), &script_re),
+        &page_style_re,
+    );
+    let start = masked_body.find(open_tag.as_str())?;
+    let after_open = start + open_tag.len();
+    let tag_re = Regex::new(r"(?i)<component\b|</component\s*>").unwrap();
+    let mut depth = 1usize;
+    let mut inner_end = None;
+    for m in tag_re.find_iter(&masked_body[after_open..]) {
+        if m.as_str().starts_with("</") {
+            depth -= 1;
+            if depth == 0 {
+                inner_end = Some(after_open + m.start());
+                break;
+            }
+        } else {
+            depth += 1;
+        }
+    }
+    let inner_end = inner_end?;
+    let close_end = body_inner[inner_end..].find('>').map(|i| inner_end + i + 1)?;
+
+    // Everything outside the root element must be only whitespace, comments
+    // or scripts — a second top-level sibling means the page isn't "layout +
+    // slot content" and the app falls back to whole-page fragments.
+    let outside = format!("{}{}", &body_inner[..start], &body_inner[close_end..]);
+    let outside = comment_re.replace_all(&outside, "");
+    let outside = script_re.replace_all(&outside, "");
+    let outside = page_style_re.replace_all(&outside, "");
+    if !outside.trim().is_empty() {
+        return None;
+    }
+
+    let reduced_body = format!(
+        "{}{}{}",
+        &body_inner[..start],
+        &body_inner[after_open..inner_end],
+        &body_inner[close_end..]
+    );
+    let reduced_source = format!(
+        "{}{}{}",
+        &raw_source[..body_match.start()],
+        reduced_body,
+        &raw_source[body_match.end()..]
+    );
+
+    Some((open_tag, src, reduced_source))
+}
+
+/// The hoist decision: every page must present the SAME root component —
+/// identical src and identical open tag (attributes parameterize a layout
+/// instance; divergence means the pages don't share one). Returns the shared
+/// (open_tag, src) when hoisting applies.
+pub fn hoistable_layout(candidates: &[Option<(String, String, String)>]) -> Option<(String, String)> {
+    let first = candidates.first()?.as_ref()?;
+    for candidate in candidates {
+        let c = candidate.as_ref()?;
+        if c.0 != first.0 || c.1 != first.1 {
+            return None;
+        }
+    }
+    Some((first.0.clone(), first.1.clone()))
+}
+
+/// 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],
+    hoisted_layout: Option<&(String, String)>,
+) -> 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.
+    // With a hoisted layout the outlet nests inside the layout's slot: the
+    // layout mounts ONCE in the shell (build-inlined like any page chrome)
+    // and navigation swaps only the slot content — layout DOM, component
+    // state and timers persist, matching what a hand-written SPA shell does.
+    match hoisted_layout {
+        Some((open_tag, _src)) => {
+            html.push_str("    ");
+            html.push_str(open_tag);
+            html.push('\n');
+            html.push_str("      <component src=\"@[page.src]\" key=\"@[page.path]\"></component>\n");
+            html.push_str("    </component>\n");
+        }
+        None => {
+            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("404.html"), "*");
+        assert_eq!(route_for("errors/404.html"), "*");
+        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);
+    }
+}