@transclude/core 0.1.0

package/src/rewrite.js

@@ -0,0 +1,281 @@
+// Making a foreign document safe to put in a page, and making its links work.
+//
+// Two jobs over one tree. Sanitizing decides what is allowed to survive the
+// trip. Rewriting turns every relative URL into one that still points at the
+// source, since the markup is about to be read on a different origin.
+//
+// Both run over the whole document once, before it is indexed, so several
+// fragments from one page pay for it once.
+
+import { parse } from 'parse5';
+
+/** Removed outright. Their content goes with them. */
+const STRIP = new Set(['script', 'iframe', 'object', 'embed', 'base', 'link', 'style']);
+
+/** Attributes holding a URL, and what a URL there is allowed to be. */
+const NAVIGATIONAL = new Set(['href', 'action', 'formaction', 'ping', 'longdesc', 'cite']);
+const FETCHABLE = new Set(['src', 'poster', 'data', 'background']);
+const SRCSET = new Set(['srcset', 'imagesrcset']);
+
+/** Schemes an attribute may name. Anything else is dropped. */
+const SAFE_SCHEME = /^(https?:|mailto:|tel:|ftp:)/i;
+
+/**
+ * `<meta http-equiv="refresh">` navigates the page it lands in. Nothing about a
+ * transcluded fragment should be able to do that.
+ */
+const isRefresh = (node) =>
+  node.tagName === 'meta' &&
+  node.attrs?.some((a) => a.name === 'http-equiv' && /^refresh$/i.test(a.value));
+
+const kidsOf = (node) => node.childNodes ?? [];
+const isElement = (node) => typeof node.tagName === 'string';
+
+function remove(node) {
+  const siblings = node.parentNode?.childNodes;
+  if (!siblings) return;
+  const at = siblings.indexOf(node);
+  if (at !== -1) siblings.splice(at, 1);
+}
+
+/**
+ * Strip what must not travel.
+ *
+ * `<base>` is on the list for a reason that is easy to miss: it does not affect
+ * the fragment, it retargets every relative URL in the document the fragment is
+ * inserted into. `<link>` and `<style>` go because their rules are not scoped to
+ * the fragment: both restyle the whole page the fragment lands in, one by
+ * pulling a stylesheet from anywhere and one by carrying it. `<base>` and
+ * `<link>` are read for their own purposes before this runs.
+ *
+ * A `style` attribute is the other kind. It paints the element it sits on and
+ * nothing else, so it is kept unless `styles` says otherwise. Dropping them by
+ * default would flatten the source's own meaning: a highlighted code block
+ * carries its colors that way.
+ *
+ * @param {object} root a parse5 tree, modified in place
+ * @param {{ styles?: 'keep'|'strip' }} [options]
+ * @returns {string[]} what was taken out, for a caller that wants to report it
+ */
+export function sanitize(root, { styles = 'keep' } = {}) {
+  const removed = [];
+
+  const visit = (node) => {
+    // A copy, because the walk removes from the live list.
+    for (const child of [...kidsOf(node)]) {
+      if (!isElement(child)) continue;
+
+      if (STRIP.has(child.tagName) || isRefresh(child)) {
+        removed.push(child.tagName);
+        remove(child);
+        continue;
+      }
+
+      child.attrs = (child.attrs ?? []).filter((attr) => {
+        // Every event handler, whatever it is called.
+        if (/^on/i.test(attr.name)) {
+          removed.push(`@${attr.name}`);
+          return false;
+        }
+        if (styles === 'strip' && attr.name === 'style') {
+          removed.push('@style');
+          return false;
+        }
+        return true;
+      });
+
+      for (const attr of child.attrs) {
+        if (!allowedUrl(child, attr)) {
+          removed.push(`@${attr.name}`);
+          attr.value = '';
+        }
+      }
+
+      visit(child);
+    }
+  };
+
+  visit(root);
+  return removed;
+}
+
+/**
+ * Whether a URL-bearing attribute may keep its value.
+ *
+ * `javascript:` is refused everywhere. `data:` is refused everywhere except an
+ * image source, where it is ordinary and cannot navigate anything.
+ */
+function allowedUrl(element, attr) {
+  const holdsUrl =
+    NAVIGATIONAL.has(attr.name) || FETCHABLE.has(attr.name) || isXlink(attr.name);
+  if (!holdsUrl) return true;
+
+  const value = attr.value.trim();
+  if (!value) return true;
+
+  const scheme = value.match(/^([a-z][a-z0-9+.-]*):/i)?.[1]?.toLowerCase();
+  if (!scheme) return true; // relative, resolved later
+
+  if (scheme === 'data') {
+    return element.tagName === 'img' && attr.name === 'src' && /^data:image\//i.test(value);
+  }
+  return SAFE_SCHEME.test(value);
+}
+
+const isXlink = (name) => name === 'xlink:href' || name === 'href';
+
+// ---- absolute URLs ---------------------------------------------------------
+
+/**
+ * The document's own idea of where it is.
+ *
+ * A `<base href>` wins over the URL the response came from, because that is
+ * what the source document's own relative links were written against.
+ *
+ * @param {string} html
+ * @param {string} responseUrl the URL after every redirect
+ * @returns {string} what relative URLs resolve against
+ */
+export function baseOf(html, responseUrl) {
+  const found = parse(html);
+  let href = null;
+
+  const visit = (node) => {
+    for (const child of kidsOf(node)) {
+      if (!isElement(child)) continue;
+      if (child.tagName === 'base' && !href) {
+        href = child.attrs?.find((a) => a.name === 'href')?.value ?? null;
+      }
+      visit(child);
+    }
+  };
+  visit(found);
+
+  if (!href) return responseUrl;
+  try {
+    return new URL(href, responseUrl).href;
+  } catch {
+    return responseUrl;
+  }
+}
+
+const absolute = (value, base) => {
+  try {
+    return new URL(value, base).href;
+  } catch {
+    return value;
+  }
+};
+
+/**
+ * A `srcset`, as a list of candidates.
+ *
+ * It cannot be split on commas: a URL may contain one, and plenty do. A
+ * candidate's URL ends at whitespace, or at a comma that is part of the URL
+ * token itself, which is the rule the HTML parser uses.
+ *
+ * @param {string} value
+ * @returns {Array<{ url: string, descriptor: string }>} split on the commas that separate
+ *   candidates rather than the ones inside a URL
+ */
+export function parseSrcset(value) {
+  const out = [];
+  const ws = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f';
+  let i = 0;
+
+  while (i < value.length) {
+    while (i < value.length && (ws(value[i]) || value[i] === ',')) i += 1;
+    if (i >= value.length) break;
+
+    const from = i;
+    while (i < value.length && !ws(value[i])) i += 1;
+    let url = value.slice(from, i);
+    let descriptor = '';
+
+    if (url.endsWith(',')) {
+      url = url.replace(/,+$/, '');
+    } else {
+      while (i < value.length && ws(value[i])) i += 1;
+      const at = i;
+      while (i < value.length && value[i] !== ',') i += 1;
+      descriptor = value.slice(at, i).trim();
+      if (value[i] === ',') i += 1;
+    }
+
+    if (url) out.push({ url, descriptor });
+  }
+  return out;
+}
+
+const CSS_URL = /url\(\s*(['"]?)([^'")]*)\1\s*\)/gi;
+
+/**
+ * `url()` references inside a style attribute or a `<style>` block.
+ *
+ * @param {string} css
+ * @param {string} base
+ * @returns {string}
+ */
+export function rewriteCss(css, base) {
+  return css.replace(CSS_URL, (whole, quote, url) => {
+    const value = url.trim();
+    if (!value || /^(data|blob):/i.test(value)) return whole;
+    return `url(${quote}${absolute(value, base)}${quote})`;
+  });
+}
+
+/**
+ * Every relative URL made absolute against the source.
+ *
+ * A hash-only href is included on purpose. Left alone it would point at the
+ * page the fragment was inserted into, which is a different document that
+ * probably has no such id.
+ *
+ * @param {object} root modified in place
+ * @param {string} base
+ * @returns {object} the same root
+ */
+export function absolutize(root, base) {
+  const visit = (node) => {
+    for (const child of kidsOf(node)) {
+      if (!isElement(child)) continue;
+
+      for (const attr of child.attrs ?? []) {
+        if (SRCSET.has(attr.name)) {
+          attr.value = parseSrcset(attr.value)
+            .map(({ url, descriptor }) =>
+              descriptor ? `${absolute(url, base)} ${descriptor}` : absolute(url, base),
+            )
+            .join(', ');
+          continue;
+        }
+
+        if (attr.name === 'style') {
+          attr.value = rewriteCss(attr.value, base);
+          continue;
+        }
+
+        const holdsUrl =
+          NAVIGATIONAL.has(attr.name) || FETCHABLE.has(attr.name) || isXlink(attr.name);
+        if (!holdsUrl || !attr.value.trim()) continue;
+        if (/^(data|blob|mailto:|tel:|javascript:)/i.test(attr.value.trim())) continue;
+
+        attr.value =
+          attr.name === 'ping'
+            ? attr.value.split(/\s+/).filter(Boolean).map((u) => absolute(u, base)).join(' ')
+            : absolute(attr.value, base);
+      }
+
+      if (child.tagName === 'style') {
+        for (const text of kidsOf(child)) {
+          if (text.nodeName === '#text') text.value = rewriteCss(text.value, base);
+        }
+      }
+
+      visit(child);
+    }
+  };
+
+  visit(root);
+  return root;
+}

package/src/routes.js

@@ -0,0 +1,199 @@
+// File-based routing. The directory tree is the route table; Hono does the
+// matching. Pure functions only. The plugin and the server both scan, and they
+// must not be able to disagree.
+//
+//   routes/index.html            ->  /
+//   routes/about.html            ->  /about
+//   routes/blog/index.html       ->  /blog
+//   routes/blog/[slug].html      ->  /blog/:slug
+//   routes/docs/[...path].html   ->  /docs/:path{.+}
+//   routes/api/people.js         ->  /api/people, an endpoint rather than a page
+//   routes/404.html              ->  the not-found handler, not a route
+//   routes/500.html              ->  the error page, not a route
+//   routes/_partial.html         ->  ignored, as is anything under an _ directory
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const EXT = '.html';
+/**
+ * A `.js` file in the routes tree is an endpoint: a route with no template, no
+ * layout and no regions, which answers with a `Response` of its own. Same
+ * filename rules as a page, so `[param]`, `[...rest]` and `index` all work,
+ * because it is the same route table.
+ */
+const ENDPOINT_EXT = '.js';
+const NOT_FOUND = '404';
+/**
+ * Not a route either: nothing links to `/500`, and a request for it is not what
+ * makes it render. An unhandled throw is. Prerendered like the not-found page,
+ * because a page that renders when something is already broken should not need a
+ * loader, a database, or anything else that can also be broken.
+ */
+const ERROR = '500';
+
+/**
+ * @param {string} dir
+ * @returns {{ routes: object[], endpoints: object[], notFound: object|null,
+ *   error: object|null }} the pages, the endpoints, and the two pages that are
+ *   reached for rather than routed to
+ */
+export function scanRoutes(dir) {
+  const routes = [];
+  const endpoints = [];
+  let notFound = null;
+  let error = null;
+
+  const seen = new Map();
+  for (const rel of walk(dir)) {
+    const route = toRoute(rel, path.join(dir, rel));
+
+    if (route.kind === 'page' && route.id === NOT_FOUND) {
+      notFound = route;
+      continue;
+    }
+    if (route.kind === 'page' && route.id === ERROR) {
+      error = route;
+      continue;
+    }
+    // One pattern, one answer. A page and an endpoint claiming the same URL is
+    // the same mistake as two pages claiming it.
+    const clash = seen.get(route.pattern) ?? seen.get(route.id);
+    if (clash) {
+      throw new Error(
+        `[transclude] ${rel} and ${clash} collide (${route.pattern}, id ${route.id}). Rename one`,
+      );
+    }
+    seen.set(route.pattern, rel);
+    seen.set(route.id, rel);
+    (route.kind === 'page' ? routes : endpoints).push(route);
+  }
+
+  routes.sort(bySpecificity);
+  endpoints.sort(bySpecificity);
+  return { routes, endpoints, notFound, error };
+}
+
+/**
+ * @param {string} rel the path under the routes directory
+ * @param {string} file
+ * @returns {object} its id, URL pattern, params and kind
+ */
+export function toRoute(rel, file) {
+  const kind = rel.endsWith(ENDPOINT_EXT) ? 'endpoint' : 'page';
+  const ext = kind === 'endpoint' ? ENDPOINT_EXT : EXT;
+  const parts = rel.slice(0, -ext.length).split(path.sep);
+
+  // `blog/index.html` and `blog.html` both mean /blog; the trailing `index`
+  // is addressing, not a path segment.
+  const named = parts.at(-1) === 'index' ? parts.slice(0, -1) : parts;
+  const segments = named.map(parseSegment);
+
+  return {
+    kind,
+    id: idOf(parts),
+    file,
+    rel,
+    segments,
+    pattern: patternOf(segments),
+    params: segments.filter((s) => s.kind !== 'static').map((s) => s.name),
+    hasRest: segments.some((s) => s.kind === 'rest'),
+  };
+}
+
+function parseSegment(name) {
+  const rest = /^\[\.\.\.(.+)\]$/.exec(name);
+  if (rest) return { kind: 'rest', name: rest[1] };
+
+  const param = /^\[(.+)\]$/.exec(name);
+  if (param) return { kind: 'param', name: param[1] };
+
+  return { kind: 'static', name };
+}
+
+function patternOf(segments) {
+  if (!segments.length) return '/';
+  return (
+    '/' +
+    segments
+      .map((s) => {
+        if (s.kind === 'static') return s.name;
+        // Hono's `*` wildcard is not a named param; a regex param is.
+        return s.kind === 'rest' ? `:${s.name}{.+}` : `:${s.name}`;
+      })
+      .join('/')
+  );
+}
+
+/**
+ * A URL-safe, stable key for the virtual module ids. Brackets would have to
+ * survive a round trip through `/@id/...` and they are reserved characters.
+ *
+ * The separator must not be a dot. Vite decides whether to run a request
+ * through its transform pipeline partly by extension, and `people._name` parses
+ * as the extension `._name`, so dotted ids fall straight past the dev server and
+ * get answered by the app as a 404 page. Silent, and only on nested routes.
+ */
+function idOf(parts) {
+  return parts
+    .map((part) =>
+      part
+        .replace(/^\[\.\.\.(.+)\]$/, '_$1_rest')
+        .replace(/^\[(.+)\]$/, '_$1'),
+    )
+    .join('-');
+}
+
+// Static beats dynamic, dynamic beats catch-all, and among equals the longer
+// path wins. Registration order then makes Hono's behaviour deterministic
+// rather than something to reason about per-router.
+function bySpecificity(a, b) {
+  if (a.hasRest !== b.hasRest) return a.hasRest ? 1 : -1;
+  if (a.params.length !== b.params.length) return a.params.length - b.params.length;
+  if (a.segments.length !== b.segments.length) return b.segments.length - a.segments.length;
+  return a.pattern.localeCompare(b.pattern);
+}
+
+function walk(dir, base = dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    // `_` marks something that is not a route: helpers and drafts.
+    if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, base, out);
+    else if (entry.name.endsWith(EXT) || entry.name.endsWith(ENDPOINT_EXT)) {
+      out.push(path.relative(base, full));
+    }
+  }
+  return out;
+}
+
+/**
+ * The routes directory, or a migration error.
+ *
+ * It was `pages/` until it started holding `.js` endpoints as well as `.html`
+ * pages, at which point the name was no longer true. A missing directory otherwise
+ * produces an empty route table and a site of 404s, which is a confusing way to
+ * learn about a rename.
+ *
+ * @param {string} app the app directory
+ * @param {string} routesDir from the config
+ * @returns {string}
+ * @throws when the old `pages/` name is still there
+ */
+export function resolveRoutesDir(app, routesDir) {
+  const dir = path.resolve(app, routesDir);
+  if (fs.existsSync(dir)) return dir;
+
+  const legacy = path.resolve(app, 'pages');
+  if (fs.existsSync(legacy)) {
+    throw new Error(
+      `[transclude] ${path.relative(app, legacy)}/ is now ${routesDir}/. It holds .js ` +
+        `endpoints as well as .html pages. Rename the directory, or set ` +
+        `\`routesDir\` in transclude.config.js.`,
+    );
+  }
+  return dir;
+}