react-cheminfo 0.4.1 → 0.6.0

package/src/seo/core/pageMeta.ts

@@ -4,18 +4,23 @@
  * Googlebot renders JavaScript, but Bing, a Slack unfurl, an LMS preview and
  * every academic indexer read the HTML that came off the wire — so the title,
  * the description and the canonical of a page must already be in it. A site
- * with a server rewrites them per request; a static one writes one file per
+ * with a server writes them per request; a static one writes one file per
  * address at build time. Both call this, which is pure string work: no
  * `window`, no `node:fs`.
+ *
+ * The page it is given is the template, which declares where its head goes and
+ * carries none of its own, so this only ever writes — see `./template.ts`.
  */
 
-import { siteById, siteDisplayName } from '../../ecosystem/core/lookup.ts';
+import { siteDisplayName } from '../../ecosystem/core/lookup.ts';
 import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
 import { escapeAttribute, escapeText } from '../../share/core/escape.ts';
 
 import type { DocumentMeta } from './documentMeta.ts';
 import type { RouteMeta } from './routes.ts';
-import { pageMetaFor, trimTrailingSlash } from './routes.ts';
+import { pageMetaFor } from './routes.ts';
+import { mountPathOf, originOf, resolveSite } from './siteFiles.ts';
+import { PAGE_HEAD_MARKER, fill } from './template.ts';
 
 /** Which site is being served, and what it answers. */
 export interface PageMetaOptions {
@@ -23,11 +28,18 @@ export interface PageMetaOptions {
   site: EcosystemSite | SiteId;
   /** Every address it answers, each with its title and description. */
   routes: readonly RouteMeta[];
-  /** The address being written, query string included. */
+  /**
+   * The address being written, query string included: a path, or the absolute
+   * address an app reads off the page it is on.
+   */
   url: string;
   /**
-   * Origin every absolute address is built on. A server passes the one the
-   * request arrived on; a build leaves it out and the site's own host is used.
+   * Where the site is served, mount path included, e.g.
+   * `https://learn.cheminfo.org/surge`. A server passes the one the request
+   * arrived on; a build leaves it out and the site's own host is used. Every
+   * address written here is composed on it, so the mount is carried by the
+   * origin rather than applied a second time. It is an absolute address, or it
+   * is refused.
    * @default `https://<the site's host>`
    */
   origin?: string;
@@ -41,33 +53,44 @@ export interface PageMetaOptions {
 /**
  * Give a page the title, the description and the canonical address of the route
  * it answers, plus the card a link to it unfurls into.
- * @param html - The built page.
+ * @param html - The built template.
  * @param options - Which site, which address, and where it is served from.
- * @returns The page, with its head rewritten for that route.
+ * @returns The page, with its head written for that route.
+ * @throws {Error} When the page carries no `<!--cheminfo:head-->`, when the
+ * site answers no route, or when it names an origin that is not an absolute
+ * address.
  */
 export function injectPageMeta(html: string, options: PageMetaOptions): string {
-  const site = resolveSite(options.site);
-  const meta = pageMetaFor(options.routes, options.url);
-  const name = siteDisplayName(site);
-  const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+  return fill(html, PAGE_HEAD_MARKER, pageHeadTags(options));
+}
+
+/**
+ * The head a route is indexed and shared under, for a caller writing more into
+ * the same place — a structured-data block, a tracking snippet.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The tags, one per line.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export function pageHeadTags(options: PageMetaOptions): string {
+  const name = siteDisplayName(resolveSite(options.site));
+  const description = routeMetaOf(options).description;
+  const origin = originOf(options);
   const { title, canonical } = pageDocumentMeta(options);
   const image = absolute(options.image ?? '/og.png', origin);
 
-  const head = [
+  return [
+    `<title>${escapeText(title)}</title>`,
+    `<meta name="description" content="${escapeAttribute(description)}" />`,
     `<link rel="canonical" href="${escapeAttribute(canonical)}" />`,
     '<meta property="og:type" content="website" />',
     `<meta property="og:site_name" content="${escapeAttribute(name)}" />`,
     `<meta property="og:title" content="${escapeAttribute(title)}" />`,
-    `<meta property="og:description" content="${escapeAttribute(meta.description)}" />`,
+    `<meta property="og:description" content="${escapeAttribute(description)}" />`,
     `<meta property="og:url" content="${escapeAttribute(canonical)}" />`,
     `<meta property="og:image" content="${escapeAttribute(image)}" />`,
     '<meta name="twitter:card" content="summary_large_image" />',
   ].join('\n');
-
-  return insertBeforeHeadEnd(
-    replaceDescription(replaceTitle(html, title), meta.description),
-    head,
-  );
 }
 
 /**
@@ -78,50 +101,28 @@ export function injectPageMeta(html: string, options: PageMetaOptions): string {
  * click that changes the page cannot disagree with the page a crawler fetched.
  * @param options - Which site, which address, and where it is served from.
  * @returns The title, the description and the canonical of that address.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
  */
-export function pageDocumentMeta(options: PageMetaOptions): Required<DocumentMeta> {
+export function pageDocumentMeta(
+  options: PageMetaOptions,
+): Required<DocumentMeta> {
   const site = resolveSite(options.site);
-  const meta = pageMetaFor(options.routes, options.url);
-  const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+  const meta = routeMetaOf(options);
   return {
     title: `${meta.title} — ${siteDisplayName(site)}`,
     description: meta.description,
-    canonical: `${origin}${meta.path}`,
+    canonical: `${originOf(options)}${meta.path}`,
   };
 }
 
-/**
- * Put an addition at the end of the head, where a tracking snippet and a
- * structured-data block both belong.
- * @param html - The page.
- * @param addition - The markup to add, taken as written.
- * @returns The page, with the addition before `</head>`.
- */
-export function insertBeforeHeadEnd(html: string, addition: string): string {
-  const head = html.lastIndexOf('</head>');
-  if (head === -1) return `${html}\n${addition}\n`;
-  return `${html.slice(0, head)}${addition}\n${html.slice(head)}`;
-}
-
-function resolveSite(site: EcosystemSite | SiteId): EcosystemSite {
-  return typeof site === 'string' ? siteById(site) : site;
+// A server behind a mount is handed the address the browser asked for, and the
+// route table is written from the site's own root, so the mount the origin
+// carries is taken off it before the table is read.
+function routeMetaOf(options: PageMetaOptions): RouteMeta {
+  return pageMetaFor(options.routes, options.url, mountPathOf(options));
 }
 
 function absolute(target: string, origin: string): string {
   return target.startsWith('/') ? `${origin}${target}` : target;
 }
-
-function replaceTitle(html: string, title: string): string {
-  const replacement = `<title>${escapeText(title)}</title>`;
-  return html.includes('<title>')
-    ? html.replace(/<title>[\s\S]*?<\/title>/, replacement)
-    : insertBeforeHeadEnd(html, replacement);
-}
-
-function replaceDescription(html: string, description: string): string {
-  const replacement = `<meta name="description" content="${escapeAttribute(description)}" />`;
-  const existing = /<meta[^>]*name="description"[^>]*>/;
-  return existing.test(html)
-    ? html.replace(existing, replacement)
-    : insertBeforeHeadEnd(html, replacement);
-}

package/src/seo/core/robots.ts

@@ -0,0 +1,114 @@
+/**
+ * The crawl policy.
+ *
+ * Our tools are meant to be found, so only the endpoints are kept out of the
+ * index — an API prefix and its documentation are not pages — and each one may
+ * say in a comment why, because a policy nobody can read is a policy nobody
+ * maintains.
+ *
+ * Every line of this file is a directive, so nothing an author writes may
+ * become one they did not: a path is a single line that says something, and
+ * carries no fragment, or it is refused; and a comment is folded onto the one
+ * line it is written as.
+ */
+
+import { joinBasePath } from '../../router/core/basePath.ts';
+
+import type { SiteFilesOptions } from './siteFiles.ts';
+import { mountPathOf, originOf } from './siteFiles.ts';
+
+/** One address kept out of the index, and why. */
+export interface RobotsDisallow {
+  /**
+   * The address prefix, from the site's own root, e.g. `/v1/`. It is a path,
+   * on one line, saying something, carrying no `#`, and padded by nothing: a
+   * blank one would read as `Disallow: /` and keep the whole site out of the
+   * index — RFC 9309 eats the trailing whitespace of a line, so `"   "` is read
+   * as nothing at all — one carrying a line break would write whatever follows
+   * it as a directive of its own, everything from a `#` onwards is read as a
+   * comment, which truncates the path silently, and a padded one is not the
+   * address it looks like: `" /v1/"` does not start at the site root, so it is
+   * written `Disallow: / /v1/` and matches no address at all, leaving the
+   * endpoint crawled by the very line meant to keep it out.
+   */
+  path: string;
+  /**
+   * One sentence written as a `#` line above the directive. The `#` is added
+   * when it is not already there, every run of whitespace is folded to a single
+   * space so the sentence stays on its own line, and a blank one is written as
+   * no line at all.
+   * @default undefined — the directive is written on its own
+   */
+  comment?: string;
+}
+
+const NEWLINE = /[\n\r]/;
+
+const WHITESPACE = /\s+/g;
+
+/**
+ * The crawl policy of the address the site is served at.
+ *
+ * Every path is written under the mount, so a build published as one tool among
+ * several on a shared host allows what it actually answers rather than claiming
+ * the whole host. The sitemap is named only because this module also writes it:
+ * a `Sitemap:` line pointing at a 404 is reported as an error on every fetch.
+ * @param options - The site, its routes, and where it is served.
+ * @param disallow - Addresses to keep out of the index, each optionally with
+ * the sentence saying why.
+ * @returns The `robots.txt` document.
+ * @throws {Error} When a disallowed address is blank, spans more than one line,
+ * carries a `#` or is padded with whitespace, or when the deployment named an
+ * origin that is not an absolute address.
+ */
+export function robotsTxt(
+  options: SiteFilesOptions,
+  disallow: ReadonlyArray<string | RobotsDisallow> = [],
+): string {
+  const mount = mountPathOf(options);
+  const lines = ['User-agent: *', `Allow: ${joinBasePath(mount, '/')}`];
+
+  for (const entry of disallow) {
+    const rule = typeof entry === 'string' ? { path: entry } : entry;
+    const comment =
+      rule.comment === undefined ? undefined : commentLine(rule.comment);
+    if (comment !== undefined) lines.push(comment);
+    lines.push(`Disallow: ${joinBasePath(mount, disallowPath(rule.path))}`);
+  }
+
+  lines.push('', `Sitemap: ${originOf(options)}/sitemap.xml`, '');
+  return lines.join('\n');
+}
+
+function disallowPath(path: string): string {
+  if (path === '') {
+    throw new Error('a disallowed address is a path, never the empty string');
+  }
+  if (path.trim() === '') {
+    throw new Error(
+      `a disallowed address is a path, never blank: ${JSON.stringify(path)}`,
+    );
+  }
+  if (NEWLINE.test(path)) {
+    throw new Error(
+      `a disallowed address is written on one line: ${JSON.stringify(path)}`,
+    );
+  }
+  if (path.includes('#')) {
+    throw new Error(
+      `a disallowed address carries no fragment: ${JSON.stringify(path)}`,
+    );
+  }
+  if (path !== path.trim()) {
+    throw new Error(
+      `a disallowed address is written without padding: ${JSON.stringify(path)}`,
+    );
+  }
+  return path;
+}
+
+function commentLine(comment: string): string | undefined {
+  const text = comment.replaceAll(WHITESPACE, ' ').trim();
+  if (text === '') return undefined;
+  return text.startsWith('#') ? text : `# ${text}`;
+}

package/src/seo/core/routes.ts

@@ -8,6 +8,17 @@
  * the table is a page a search engine only ever sees as the home page.
  */
 
+import { stripBasePath } from '../../router/core/basePath.ts';
+
+const QUERY_OR_FRAGMENT = /[?#]/;
+
+const TRAILING_SLASHES = /\/+$/;
+
+// A scheme and an authority: what `location.href` hands out, and the one shape
+// that cannot be confused with a path. `//host/path` is left as a path, because
+// a route table is free to name one.
+const ABSOLUTE_URL = /^[a-z][\d+.a-z-]*:\/\//i;
+
 /** A page, as a crawler and a shared card see it. */
 export interface RouteMeta {
   /** Absolute path, without a trailing slash and without a query string. */
@@ -16,10 +27,34 @@ export interface RouteMeta {
   title: string;
   /** One sentence, in the words someone would search for. */
   description: string;
+  /**
+   * The label the page is linked under where a title written for a search
+   * result is too long to read as a menu entry — the `noscript` index.
+   * @default the route's own title
+   */
+  short?: string;
+  /**
+   * What the page is for, written after an em dash next to its link in the
+   * `noscript` index.
+   * @default undefined — the link stands on its own
+   */
+  note?: string;
+  /**
+   * Whether the route also answers every address beneath it, so a section
+   * carrying more pages than a table can hold — an entry per structure, per
+   * ligand, per identifier — is indexed under the section rather than under the
+   * home page. Those addresses are canonical to the section itself.
+   * @default false
+   */
+  prefix?: boolean;
 }
 
 /**
  * The route an address names.
+ *
+ * An address a route claims exactly always wins over one that claims it as a
+ * subtree, and between two subtrees the longer claim wins, so `/molecules/HEM`
+ * is a molecule rather than whatever `/` answers.
  * @param routes - Every address the site answers.
  * @param path - Absolute path, without a query string.
  * @returns Its entry, or `undefined` when the site does not know the address.
@@ -28,11 +63,7 @@ export function routeFor(
   routes: readonly RouteMeta[],
   path: string,
 ): RouteMeta | undefined {
-  const wanted = trimTrailingSlash(path) || '/';
-  for (const route of routes) {
-    if (trimTrailingSlash(route.path) === wanted) return route;
-  }
-  return undefined;
+  return exactRoute(routes, path) ?? prefixRoute(routes, path);
 }
 
 /**
@@ -41,20 +72,51 @@ export function routeFor(
  * An address the site does not know is described as the home page rather than
  * invented on the fly, which is what the router does with it too. The query
  * string never reaches the answer: the structure being drawn and the
- * configuration a shared link carries are not pages of their own.
+ * configuration a shared link carries are not pages of their own. An absolute
+ * address is read for its path, so an app handing over `location.href` after an
+ * in-app move is answered rather than silently described as the home page.
+ *
+ * The route table is written from the site's own root, and a server behind a
+ * mount is handed the address the browser asked for — `/surge/exercises` for a
+ * table that names `/exercises`. So the address is read at the site's own root
+ * first, and the four lookups run in this order:
+ *
+ * 1. the mount taken off, claimed exactly;
+ * 2. the address as written, claimed exactly;
+ * 3. the mount taken off, claimed as a subtree;
+ * 4. the address as written, claimed as a subtree.
+ *
+ * Exact before subtree, or a `prefix` route — a home page answering everything
+ * beneath it above all — would claim every mounted address and the mount would
+ * never come off. Stripped before as-written, or the mount itself would open
+ * whichever page happens to carry the mount's own name rather than the site's
+ * front page. Taking the address as written second is what leaves an unmounted
+ * caller answering exactly as before, and lets a table whose own paths start
+ * with the mount's name still be read.
  * @param routes - Every address the site answers.
- * @param url - The address, query string and fragment included.
+ * @param url - The address, query string and fragment included, either as a
+ * path or as an absolute `scheme://host/path` address.
+ * @param basePath - The path the site is mounted at, when the address carries
+ * it, written `surge`, `/surge` or `/surge/`.
+ * @default '' — the address is already written from the site's own root
  * @returns The route it is indexed as.
  * @throws {Error} When the table is empty, so there is no page to fall back to.
  */
 export function pageMetaFor(
   routes: readonly RouteMeta[],
   url: string,
+  basePath = '',
 ): RouteMeta {
   const home = homeRoute(routes);
-  const cut = url.search(/[?#]/);
-  const path = cut === -1 ? url : url.slice(0, cut);
-  return routeFor(routes, path) ?? home;
+  const path = pathOf(url);
+  const own = stripBasePath(basePath, path);
+  return (
+    exactRoute(routes, own) ??
+    exactRoute(routes, path) ??
+    prefixRoute(routes, own) ??
+    prefixRoute(routes, path) ??
+    home
+  );
 }
 
 /**
@@ -66,14 +128,119 @@ export function pageMetaFor(
 export function homeRoute(routes: readonly RouteMeta[]): RouteMeta {
   const first = routes[0];
   if (first === undefined) throw new Error('a site answers at least one route');
-  return routeFor(routes, '/') ?? first;
+  return exactRoute(routes, '/') ?? first;
 }
 
 /**
- * Drop a trailing slash, so `/about/` and `/about` are one page.
+ * Check a route table before a build reads it as a set of file names.
+ *
+ * An address written twice ships two sitemap entries and two links to a page
+ * only the first entry describes, and one carrying a `..` segment writes its
+ * file outside the build output — a real build asked for `/../escaped` and got
+ * a sibling of `dist`. Two addresses that differ only in an empty segment or in
+ * case are the same defect wearing a disguise: `//x` and `/x` both write
+ * `dist/x/index.html`, and so do `/About` and `/about` on the case-insensitive
+ * filesystem macOS and Windows ship by default — one file, two sitemap entries,
+ * and only one of the two descriptions survives. All of it is author
+ * configuration read at build time, so it is refused where it is written rather
+ * than repaired where it lands.
+ * @param routes - Every address the site answers.
+ * @throws {Error} When the table is empty, names one address twice — under any
+ * of those spellings — or carries a path that is not one.
+ */
+export function assertRoutes(routes: readonly RouteMeta[]): void {
+  if (routes.length === 0) throw new Error('a site answers at least one route');
+
+  const claimed = new Set<string>();
+  const folded = new Map<string, string>();
+  for (const route of routes) {
+    const written = JSON.stringify(route.path);
+    assertPath(route.path, written);
+    const address = trimTrailingSlash(route.path) || '/';
+    if (address.includes('//')) {
+      throw new Error(`a route path names no empty segment: ${written}`);
+    }
+    if (claimed.has(address)) {
+      throw new Error(`a route path is written once: ${written}`);
+    }
+    const first = folded.get(address.toLowerCase());
+    if (first !== undefined) {
+      throw new Error(
+        `two route paths name one file on a case-insensitive disk: ${first} and ${written}`,
+      );
+    }
+    claimed.add(address);
+    folded.set(address.toLowerCase(), written);
+  }
+}
+
+/**
+ * Drop the trailing slashes, so `/about/` and `/about` are one page and an
+ * origin written `https://host/surge//` composes one address rather than one
+ * with an empty segment in it.
  * @param value - A path or an origin.
- * @returns It, without the trailing slash `/` itself keeps.
+ * @returns It, without the trailing slashes `/` itself keeps.
  */
 export function trimTrailingSlash(value: string): string {
-  return value.length > 1 && value.endsWith('/') ? value.slice(0, -1) : value;
+  const trimmed = value.replace(TRAILING_SLASHES, '');
+  return trimmed === '' && value !== '' ? '/' : trimmed;
+}
+
+function assertPath(path: string, written: string): void {
+  if (!path.startsWith('/')) {
+    throw new Error(`a route path starts at the site root: ${written}`);
+  }
+  if (QUERY_OR_FRAGMENT.test(path)) {
+    throw new Error(
+      `a route path carries no query string and no fragment: ${written}`,
+    );
+  }
+  if (path.split('/').includes('..')) {
+    throw new Error(`a route path stays inside the site: ${written}`);
+  }
+}
+
+// The path half of whatever the caller had at hand: an absolute address, or a
+// path already, with the query string and the fragment cut off either way.
+function pathOf(url: string): string {
+  if (ABSOLUTE_URL.test(url) && URL.canParse(url)) return new URL(url).pathname;
+  const cut = url.search(QUERY_OR_FRAGMENT);
+  return cut === -1 ? url : url.slice(0, cut);
+}
+
+function exactRoute(
+  routes: readonly RouteMeta[],
+  path: string,
+): RouteMeta | undefined {
+  const wanted = trimTrailingSlash(path) || '/';
+  for (const route of routes) {
+    if ((trimTrailingSlash(route.path) || '/') === wanted) return route;
+  }
+  return undefined;
+}
+
+function prefixRoute(
+  routes: readonly RouteMeta[],
+  path: string,
+): RouteMeta | undefined {
+  const wanted = trimTrailingSlash(path) || '/';
+  let claimed: RouteMeta | undefined;
+  let claimedLength = -1;
+
+  for (const route of routes) {
+    if (route.prefix !== true) continue;
+    const routePath = trimTrailingSlash(route.path) || '/';
+    if (!isUnder(routePath, wanted)) continue;
+    if (routePath.length > claimedLength) {
+      claimed = route;
+      claimedLength = routePath.length;
+    }
+  }
+  return claimed;
+}
+
+function isUnder(routePath: string, path: string): boolean {
+  // `/surgeon` is not a page of `/surge`, so a claim only holds when what
+  // follows it is a path of its own.
+  return routePath === '/' || path.startsWith(`${routePath}/`);
 }