@jxsuite/compiler 3.0.0 → 4.0.0

package/src/site/base-path.ts

@@ -0,0 +1,175 @@
+/**
+ * Base-path.ts — re-rooting a build's output onto the path the site is deployed under.
+ *
+ * A site at `https://example.pages.dev/m/my-site/` is served from `/m/my-site/`, and every
+ * absolute-path reference the build emits — `/assets/vue-reactivity.js`,
+ * `/components/site-counter.js`, `/images/hero.jpg` — resolves against `example.pages.dev/`
+ * instead, where nothing is. The page renders blank rather than merely wrong, because the runtime
+ * assets 404 first (issue 235).
+ *
+ * **The base is not a new option.** `project.json`'s `url` is the base URI every emitted reference
+ * is resolved against (RFC 3986 §5), and the compiler was resolving against its ORIGIN and
+ * discarding its path. `siteBasePath` in `@jxsuite/schema/asset-paths` reads the path back; a
+ * second `build.base` key would be a second writer on the one fact the canonical links and the
+ * sitemap are already built from, free to disagree with them.
+ *
+ * **The rewrite happens on finished HTML, and that is the point.** The alternative is to thread a
+ * prefix through the twelve emitters that can put a URL on a page — the import map and its
+ * modulepreloads, three page-template tiers that each write their own map, component scripts,
+ * island modules, sidecar and npm bundles, image `srcset`, `$head` entries, and whatever a page
+ * author wrote by hand. That list is exactly the kind that is complete until the next emitter is
+ * added, and #227 was already one emitter's map disagreeing with another's. One pass over the bytes
+ * that ship cannot drift from them.
+ *
+ * Outputs that are not HTML keep their own handling, because each has a syntax and none of them can
+ * be found by looking at a tag: `_headers`, `_redirects`, the service worker's precache list and
+ * scope, `manifest.webmanifest`, and the absolute URLs in `sitemap.xml` and `robots.txt`.
+ *
+ * Everything here is idempotent (see `withBase`), so a value an emitter already prefixed survives
+ * this pass unchanged.
+ *
+ * @docs framework/site/deployment
+ */
+
+import { formatSrcset, parseSrcset, withBase } from "@jxsuite/schema/asset-paths";
+
+/**
+ * Attributes whose value is a single URL.
+ *
+ * `href` and `src` are most of the traffic; the rest are the ones a Jx page can actually emit —
+ * `<form action>`, `<button formaction>`, `<video poster>`, `<object data>`. Anything not listed is
+ * left alone, which is the safe direction: a missed URL 404s visibly on a subpath deployment, while
+ * a rewritten non-URL corrupts a page that was working.
+ */
+const URL_ATTRS = new Set(["href", "src", "poster", "action", "formaction", "data"]);
+
+/** Attributes whose value is a `srcset` candidate list rather than one URL. */
+const SRCSET_ATTRS = new Set(["srcset", "imagesrcset"]);
+
+/**
+ * One HTML tag: the name, then attributes with quoted values consumed whole.
+ *
+ * Consuming quotes matters — a `>` inside an attribute value would otherwise end the tag early and
+ * leave the rest of its attributes as text this pass never looks at.
+ */
+const TAG_RE = /<([a-zA-Z][a-zA-Z0-9-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+
+/** One attribute inside a tag's attribute blob. */
+const ATTR_RE = /([a-zA-Z_:][\w:.-]*)\s*=\s*("([^"]*)"|'([^']*)')/g;
+
+/** `url(...)` inside a CSS value, capturing the optional quote so it can be put back. */
+const CSS_URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+
+/** A JSON string literal holding an absolute-path reference — an import map's keys and values. */
+const JSON_ABS_PATH_RE = /"(\/[^"/][^"]*)"/g;
+
+/** `<script type="importmap">…</script>`, whose body is JSON rather than markup. */
+const IMPORTMAP_RE = /(<script\b[^>]*\btype\s*=\s*["']importmap["'][^>]*>)([\s\S]*?)(<\/script>)/gi;
+
+/** `<style>…</style>`, whose body is CSS rather than markup. */
+const STYLE_BLOCK_RE = /(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi;
+
+/**
+ * `<meta>` names whose `content` is a URL.
+ *
+ * `content` is the one attribute here that usually holds prose, so it is rewritten only when the
+ * same tag says the value is a URL. OpenGraph and Twitter image/player metas are the cases a page
+ * actually produces from an author-written `/hero.jpg`.
+ */
+const URL_META_RE =
+  /\b(?:property|name)\s*=\s*["'](?:og:|twitter:)[\w:.-]*(?:image|url|video|audio|player)[\w:.-]*["']/i;
+
+/**
+ * A quote around a `url()` target that survived attribute escaping.
+ *
+ * In a `style` ATTRIBUTE the quotes inside `url("…")` are escaped, so the target arrives wrapped in
+ * `&quot;` rather than in a character {@link CSS_URL_RE} would have treated as a delimiter. Left
+ * alone the value no longer starts with `/` and is silently skipped — a background image that 404s
+ * on a subpath deployment with nothing to show for it.
+ */
+const ENTITY_QUOTE_RE = /^(&quot;|&#34;|&apos;|&#39;)([\s\S]*)\1$/;
+
+/** Rewrite every `url(...)` in a CSS fragment, in a `<style>` block or a `style` attribute. */
+function rewriteCssUrls(css: string, base: string): string {
+  return css.replaceAll(CSS_URL_RE, (match, quote: string, inner: string) => {
+    const raw = inner.trim();
+    const escaped = ENTITY_QUOTE_RE.exec(raw);
+    const target = escaped ? escaped[2]! : raw;
+    const out = withBase(base, target);
+    if (out === target) {
+      return match;
+    }
+    return `url(${quote}${escaped ? `${escaped[1]}${out}${escaped[1]}` : out}${quote})`;
+  });
+}
+
+/** Rewrite one attribute value, or return it unchanged when the attribute carries no URL. */
+function rewriteAttrValue(tag: string, attrs: string, name: string, value: string, base: string) {
+  const lower = name.toLowerCase();
+  if (URL_ATTRS.has(lower)) {
+    return withBase(base, value);
+  }
+  if (SRCSET_ATTRS.has(lower)) {
+    const candidates = parseSrcset(value);
+    return candidates.length === 0
+      ? value
+      : formatSrcset(
+          candidates.map((c) => ({ descriptor: c.descriptor, url: withBase(base, c.url) })),
+        );
+  }
+  if (lower === "style") {
+    return rewriteCssUrls(value, base);
+  }
+  if (lower === "content" && tag === "meta" && URL_META_RE.test(attrs)) {
+    return withBase(base, value);
+  }
+  return value;
+}
+
+/**
+ * Re-root every site-absolute URL in a page's HTML onto `base`.
+ *
+ * `base` of `""` is a site at an origin root, and the HTML is returned untouched — no allocation
+ * and no risk for the deployment Jx documents.
+ *
+ * @param {string} html - A finished page
+ * @param {string} base - From `siteBasePath`
+ * @returns {string} The page as it should ship
+ */
+export function rewriteHtmlBase(html: string, base: string): string {
+  if (base === "") {
+    return html;
+  }
+
+  let out = html.replaceAll(IMPORTMAP_RE, (_match, open: string, body: string, close: string) => {
+    /* The import map's KEYS are addressable too: a map may name a module by URL rather than by bare
+       specifier, and a key left at the old root would resolve to a file the build did not write. */
+    const rewritten = body.replaceAll(
+      JSON_ABS_PATH_RE,
+      (_literal, path: string) => `"${withBase(base, path)}"`,
+    );
+    return open + rewritten + close;
+  });
+
+  out = out.replaceAll(
+    STYLE_BLOCK_RE,
+    (_m, open: string, css: string, close: string) => open + rewriteCssUrls(css, base) + close,
+  );
+
+  return out.replaceAll(TAG_RE, (match, tagName: string, attrs: string) => {
+    if (attrs === "") {
+      return match;
+    }
+    const tag = tagName.toLowerCase();
+    const rewrittenAttrs = attrs.replaceAll(
+      ATTR_RE,
+      (whole, name: string, _quoted: string, dq: string | undefined, sq: string | undefined) => {
+        const quote = dq === undefined ? "'" : '"';
+        const value = dq ?? sq ?? "";
+        const next = rewriteAttrValue(tag, attrs, name, value, base);
+        return next === value ? whole : `${name}=${quote}${next}${quote}`;
+      },
+    );
+    return rewrittenAttrs === attrs ? match : `<${tagName}${rewrittenAttrs}>`;
+  });
+}

package/src/site/dev-command.ts

@@ -2,8 +2,10 @@
  * Dev command — `jx dev` resolves the project's @jxsuite/server dev entry and spawns it under Bun.
  *
  * The compiler cannot depend on @jxsuite/server (the server already depends on the compiler), and
- * the dev server is Bun-native while the jx bin runs under Node — so the command is pure resolution
- * + spawn: the entry module is resolved from the PROJECT's node_modules and executed with Bun.
+ * the dev server is Bun-native while the jx bin runs under Node — so the command is pure
+ * resolution
+ *
+ * - Spawn: the entry module is resolved from the PROJECT's node_modules and executed with Bun.
  *
  * @module dev-command
  */

package/src/site/format-host.ts

@@ -10,7 +10,7 @@ import { readFileSync } from "node:fs";
 import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
-import { buildExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import { buildExtensionRegistry, EXTENSION_MANIFEST } from "@jxsuite/schema/extension-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatHostIO, FormatRegistry, ProjectBlock } from "@jxsuite/schema/format-registry";
 import type { ProjectConfig } from "@jxsuite/schema/types";
@@ -75,6 +75,59 @@ export function createNodeFormatIO(projectRoot: string): FormatHostIO {
   };
 }
 
+/**
+ * Where an extension package's manifest resolves from — the two answers `createNodeFormatIO`
+ * merges.
+ */
+export interface ExtensionResolution {
+  /** Resolvable from the PROJECT's own node_modules. */
+  project: boolean;
+  /** Resolvable from the HOST's module graph — `createNodeFormatIO`'s fallback branch. */
+  host: boolean;
+  /** The manifest path from whichever probe answered; the project wins, matching resolution order. */
+  manifestPath?: string;
+}
+
+/**
+ * Split `createNodeFormatIO`'s two-branch resolution into its two ANSWERS.
+ *
+ * The IO deliberately collapses them (project first, then host) because a caller loading a class
+ * only needs the file. A catalogue needs them apart: "the project installed this" and "this host
+ * ships it" are different affordances — install-then-enable versus enable — and a surface that
+ * cannot tell them apart offers the wrong one.
+ *
+ * Probes the MANIFEST rather than the package directory, because the manifest is what the registry
+ * resolves (see `loadExtension`): a package present in node_modules whose `exports` map omits
+ * `./jx-extension.json` is one whose enablement would throw, so it must not read as resolvable.
+ *
+ * @param {string} projectRoot - The project whose node_modules is tried first
+ * @param {string} name - Bare package specifier, e.g. "@jxsuite/parser"
+ * @returns {ExtensionResolution}
+ */
+export function probeExtension(projectRoot: string, name: string): ExtensionResolution {
+  const ref = `${name}/${EXTENSION_MANIFEST}`;
+  let manifestPath: string | undefined;
+
+  let project = false;
+  try {
+    manifestPath = createRequire(resolve(projectRoot, "package.json")).resolve(ref);
+    project = true;
+  } catch {
+    // Not installed in the project. The host probe below decides whether it resolves at all.
+  }
+
+  let host = false;
+  try {
+    const fromHost = createRequire(import.meta.url).resolve(ref);
+    host = true;
+    manifestPath ??= fromHost;
+  } catch {
+    // Not shipped by this host either.
+  }
+
+  return { host, project, ...(manifestPath === undefined ? {} : { manifestPath }) };
+}
+
 /** Build the extension registry for a project from its project.json `extensions` array. */
 export async function buildProjectExtensionRegistry(
   projectRoot: string,

package/src/site/headers-emitter.ts

@@ -11,6 +11,7 @@
  * @docs framework/site/deployment
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { buildCspHeaders, normalizeCspConfig } from "./csp.ts";
@@ -181,6 +182,25 @@ export function contentTypeRules(outDir: string): HeaderRule[] {
   return rules;
 }
 
+/**
+ * Re-root every rule's pattern onto the deployment base.
+ *
+ * A `_headers` pattern is matched against the REQUEST path, so on a site served from `/m/my-site/`
+ * a rule for `/assets/*` matches nothing at all — which is silent, because a missing cache header
+ * is a slow site rather than a broken one. The generated patterns and the author's `build.headers`
+ * rules go through together: both describe the same URL space.
+ *
+ * @param {readonly HeaderRule[]} rules
+ * @param {string} base - From `siteBasePath`; `""` returns the rules untouched
+ * @returns {HeaderRule[]}
+ */
+export function rebaseHeaderRules(rules: readonly HeaderRule[], base: string): HeaderRule[] {
+  if (base === "") {
+    return [...rules];
+  }
+  return rules.map((rule) => ({ headers: rule.headers, pattern: withBase(base, rule.pattern) }));
+}
+
 /** Render rules in the Netlify / Cloudflare Pages `_headers` format. */
 export function renderHeaders(rules: readonly HeaderRule[]): string {
   const blocks = rules.map((rule) => {

package/src/site/i18n.ts

@@ -12,6 +12,7 @@
  * @docs framework/site/i18n
  */
 
+import { siteAbsoluteUrl } from "@jxsuite/schema/asset-paths";
 import {
   canonicalizeLocale,
   localeDirection,
@@ -298,13 +299,13 @@ export function localeAlternates(
     let alternates = built.get(members);
     if (alternates === undefined) {
       alternates = members.map((m) => ({
-        href: new URL(m.urlPattern, siteUrl).href,
+        href: siteAbsoluteUrl(m.urlPattern, siteUrl),
         hreflang: m.locale,
       }));
       const fallback = members.find((m) => m.locale === i18n.defaultLocale);
       if (fallback !== undefined) {
         alternates.push({
-          href: new URL(fallback.urlPattern, siteUrl).href,
+          href: siteAbsoluteUrl(fallback.urlPattern, siteUrl),
           hreflang: "x-default",
         });
       }

package/src/site/prototype-resolver.ts

@@ -56,8 +56,9 @@ const RESERVED_KEYS = new Set([
  * to a .class.json path via doc.imports
  *
  * The resolver: - Reads the .class.json from disk - Follows $implementation to import the JS module
+ *
  * - Instantiates the class with the config - Calls .resolve() and replaces the state entry with the
- * result
+ *   result
  *
  * @param {JxMutableNode | JxDocument} doc - The page document (mutated in place)
  * @param {{ sourcePath?: string; _pathParams?: Record<string, string> }} route - Route info

package/src/site/service-worker.ts

@@ -20,6 +20,7 @@
  * @docs framework/site/deployment
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -100,6 +101,7 @@ function configId(config: ServiceWorkerConfig): string {
 export function buildServiceWorker(
   config: ServiceWorkerConfig,
   outDir?: string,
+  base = "",
 ): ServiceWorkerOutput {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -140,15 +142,26 @@ export function buildServiceWorker(
     }
   }
 
+  /*
+   * The worker runs in the browser and every URL in it is a REQUEST path, so on a site served from
+   * `/m/my-site/` the base belongs on all three: a precache entry without it fetches a 404, and
+   * `CACHE_FIRST` without it never matches, so the content-addressed images it exists to serve
+   * from cache go to the network on every view. `outputFileFor` above is deliberately checked
+   * BEFORE this — those URLs are looked up in `outDir`, which has no base.
+   */
+  const cachedPrecache = precache.map((url) => withBase(base, url));
+  const cacheFirst = withBase(base, CACHE_FIRST_PREFIX);
+  const offlineFallback = fallback === undefined ? null : withBase(base, fallback);
+
   const cache = `jx-${configId(config)}`;
   const source = `/*
  * Generated by @jxsuite/compiler — configure via \`serviceWorker\` in project.json.
  * Set \`"serviceWorker": false\` to replace this with a worker that removes itself.
  */
 const CACHE = ${JSON.stringify(cache)};
-const PRECACHE = ${JSON.stringify(precache)};
-const CACHE_FIRST = ${JSON.stringify(CACHE_FIRST_PREFIX)};
-const OFFLINE_FALLBACK = ${JSON.stringify(fallback ?? null)};
+const PRECACHE = ${JSON.stringify(cachedPrecache)};
+const CACHE_FIRST = ${JSON.stringify(cacheFirst)};
+const OFFLINE_FALLBACK = ${JSON.stringify(offlineFallback)};
 
 self.addEventListener("install", (event) => {
   // Take over as soon as possible: a half-updated pair of workers is harder to reason about than
@@ -285,10 +298,14 @@ self.addEventListener("activate", (event) => {
  * @param {string} scope
  * @returns {string}
  */
-export function registrationScript(scope: string): string {
+export function registrationScript(scope: string, base = ""): string {
+  /* Both are request paths. A worker's scope may not exceed its own directory, so a worker served
+     from `/m/my-site/sw.js` with a scope of `/` fails to register outright — the one failure here
+     that is loud rather than silent. */
+  const worker = withBase(base, `/${SERVICE_WORKER_PATH}`);
   return (
     `if('serviceWorker' in navigator){addEventListener('load',function(){` +
-    `navigator.serviceWorker.register('/${SERVICE_WORKER_PATH}',{scope:${JSON.stringify(scope)}})` +
+    `navigator.serviceWorker.register('${worker}',{scope:${JSON.stringify(withBase(base, scope))}})` +
     `.catch(function(){})})}`
   );
 }