ipx/site/gen.mts

// The docs pages, into site/dist/docs: the guides in docs.mts, and an API reference for each
// service from api.mts, laid out as docs.rs lays out a crate (#223): a root page listing its
// modules and types, a page a module listing its endpoints, a page an endpoint and a page a type.
// No script: the site's Content-Security-Policy allows none of its own.
//
//   node site/gen.mts        (site/build.sh runs it)
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { ipx, directory, type Api, type ApiType, type Field, type Group, type Item, type Method } from './api.mts';
import { guides } from './docs.mts';

const here = path.dirname(fileURLToPath(import.meta.url));
const dist = path.join(here, 'dist');
const SRC = 'https://git.sdf1.net/rays/ipx/src/branch/main';

const esc = (s: unknown) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');

/// The version a reference documents: its service's last release, from its changelog, not the
/// -dev version between releases.
function released(changelog: string) {
  const m = fs.readFileSync(path.join(here, '..', changelog), 'utf8').match(/^## \[(\d+\.\d+\.\d+)\]/m);
  return m?.[1] ?? '';
}

function write(rel: string, html: string) {
  const file = path.join(dist, rel);
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.writeFileSync(file, html);
}

function shell({ title, description, sidebar, body }: { title: string, description: string, sidebar: string, body: string, current: string }) {
  return `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>${esc(title)}</title>
<meta name="description" content="${esc(description)}">
<meta name="color-scheme" content="light">
<link rel="icon" href="/favicon.png">
<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
<link rel="stylesheet" href="/site.css">
</head>
<body>
<header class="bar">
  <a class="home" href="/"><img src="/logo.svg" alt="" width="36" height="36">iPX</a>
  <nav aria-label="Elsewhere">
    <a href="/docs/" aria-current="true">Docs</a>
    <a href="https://directory.ipxreader.app">Directory</a>
    <a class="src" href="https://git.sdf1.net/rays/ipx" title="Source code on git.sdf1.net"><img src="/gitea.svg" alt="Source code" width="28" height="28"></a>
  </nav>
</header>
<div class="docs">
<aside class="side">${sidebar}</aside>
<main class="doc">${body}</main>
</div>
<footer>
  <p>iPX is free and open source under the MIT licence.</p>
</footer>
</body>
</html>
`;
}

/* ---------------- the guides ---------------- */

const REFS: [Api, string][] = [[ipx, 'ipx'], [directory, 'ipx-directory']];

function guideSidebar(cur: string) {
  const li = (href: string, name: string, on: boolean) => `<li><a href="${href}"${on ? ' aria-current="page"' : ''}>${name}</a></li>`;
  return `<nav aria-label="Docs">
  <h2 class="side-h">Guides</h2>
  <ul>${guides.map(g => li(g.href, g.name, g.href === cur)).join('')}</ul>
  <h2 class="side-h">API reference</h2>
  <ul>${REFS.map(([r, label]) => li(r.root + '/', label, false)).join('')}</ul>
</nav>`;
}

for (const g of guides) {
  write(g.file, shell({ title: g.title, description: g.description, sidebar: guideSidebar(g.href), body: g.body, current: 'docs' }));
}

/* ---------------- the references ---------------- */

const METHOD_CLASS: Record<Method, string> = { GET: 'm-get', POST: 'm-post', PATCH: 'm-patch', PUT: 'm-patch', DELETE: 'm-delete' };

function reference(api: Api) {
  const label = api.label || api.name;
  const version = released(api.changelog);
  const typeNames = new Set(api.types.map(t => t.name));
  const typeHref = (n: string) => `${api.root}/types/${n}`;
  const itemHref = (g: Group, it: Item) => `${api.root}/${g.id}/${it.slug}`;
  const fnName = (it: Item) => it.slug.replace(/-/g, '_');
  // A Rust type, its names that are types of this API linked.
  const ty = (s: string) => esc(s).replace(/\b[A-Z][A-Za-z]+\b/g, n => typeNames.has(n) ? `<a class="t" href="${typeHref(n)}">${n}</a>` : n);
  const isType = (s: string) => /^[A-Z]/.test(s) && /[A-Za-z>]$/.test(s) && !/\s/.test(s.replace(/, /g, ','));
  const access = (it: Item) => it.access || 'signed in';

  // Which endpoints mention each type, for its "Used by", as docs.rs lists where a type turns up.
  // An endpoint, with its module, or a type that has it as a field (its module null).
  const usedBy = new Map<string, ([Group, Item] | [null, ApiType])[]>();
  for (const g of api.groups) for (const it of g.items) {
    for (const s of [it.body, it.query, it.returns].filter((s): s is string => !!s)) {
      for (const n of s.match(/\b[A-Z][A-Za-z]+\b/g) || []) if (typeNames.has(n)) {
        const uses = usedBy.get(n) ?? [];
        usedBy.set(n, uses);
        if (!uses.some(([, x]) => x === it)) uses.push([g, it]);
      }
    }
  }
  // Types inside types: a type used only as a field is reached from the type that holds it.
  for (const t of api.types) for (const [, ft] of t.fields) {
    for (const n of ft.match(/\b[A-Z][A-Za-z]+\b/g) || []) if (typeNames.has(n) && n !== t.name) {
      const uses = usedBy.get(n) ?? [];
      usedBy.set(n, uses);
      if (!uses.some(([, x]) => x === t)) uses.push([null, t]);
    }
  }

  const crumbs = (...parts: [href: string, name: string][]) => `<p class="path"><a href="${api.root}/">${esc(api.name)}</a>${parts.map(([h, n]) => `::<a href="${h}">${n}</a>`).join('')}</p>`;
  const top = `<a class="crate" href="${api.root}/"><img src="/logo.svg" alt="" width="40" height="40"><span><b>${esc(label)}</b>${version ? `<span class="ver">${version}</span>` : ''}</span></a>`;
  const back = `<p class="side-back"><a href="/docs/">All docs</a></p>`;

  function sidebar({ group, item, type }: { group?: Group, item?: Item, type?: ApiType } = {}) {
    let s = top;
    if (group) {
      s += `<h2 class="side-h">Module <a href="${api.root}/${group.id}/">${group.name}</a></h2>
<ul class="items">${group.items.map(it => `<li><a class="${METHOD_CLASS[it.method]}" href="${itemHref(group, it)}" title="${it.method} ${esc(it.path)}"${it === item ? ' aria-current="page"' : ''}><span class="verb">${it.method}</span> ${fnName(it)}</a></li>`).join('')}</ul>`;
    }
    s += `<h2 class="side-h">Modules</h2><ul>${api.groups.map(g => `<li><a href="${api.root}/${g.id}/"${g === group && !item ? ' aria-current="page"' : ''}>${g.name}</a></li>`).join('')}</ul>`;
    s += `<h2 class="side-h">Types</h2><ul class="types">${api.types.map(t => `<li><a class="t" href="${typeHref(t.name)}"${t === type ? ' aria-current="page"' : ''}>${t.name}</a></li>`).join('')}</ul>`;
    return `<nav aria-label="${esc(label)} reference">${s}</nav>${back}`;
  }

  const page = (rel: string, title: string, description: string, side: string, body: string) =>
    write(rel, shell({ title, description, sidebar: side, body, current: 'docs' }));

  // The root: what the crate page shows on docs.rs, its modules and types.
  page(`${api.root.slice(1)}/index.html`, `${label} API`, `The HTTP API of ${label}, endpoint by endpoint.`, sidebar(),
    `<h1 class="item"><span class="kind">API</span> <span class="name">${esc(label)}</span>${version ? ` <span class="ver">${version}</span>` : ''}</h1>
${api.intro}
<h2 id="modules">Modules</h2>
<dl class="list">${api.groups.map(g => `<dt><a href="${api.root}/${g.id}/">${g.name}</a></dt><dd>${g.summary}</dd>`).join('')}</dl>
<h2 id="types">Types</h2>
<dl class="list">${api.types.map(t => `<dt><a class="t" href="${typeHref(t.name)}">${t.name}</a></dt><dd>${t.doc || ''}</dd>`).join('')}</dl>`);

  for (const g of api.groups) {
    page(`${api.root.slice(1)}/${g.id}/index.html`, `${api.name}::${g.name}`, g.title, sidebar({ group: g }),
      `${crumbs()}<h1 class="item"><span class="kind">Module</span> ${esc(api.name)}::<span class="name">${g.name}</span></h1>
<p>${g.summary}</p>
<h2 id="endpoints">Endpoints</h2>
<dl class="list">${g.items.map(it => `<dt><a class="${METHOD_CLASS[it.method]}" href="${itemHref(g, it)}"><span class="verb">${it.method}</span> ${esc(it.path)}</a></dt><dd>${it.summary}</dd>`).join('')}</dl>`);

    for (const it of g.items) {
      const decl = [
        `<span class="verb ${METHOD_CLASS[it.method]}">${it.method}</span> ${esc(it.path)}`,
        it.query && `    query  ${ty(it.query)}`,
        it.body && `    body   ${ty(it.body)}`,
        `    -&gt;     ${isType(it.returns) ? ty(it.returns) : esc(it.returns)}`,
      ].filter(Boolean).join('\n');
      const fieldsOf = (n: string) => api.types.find(t => t.name === n)?.fields || [];
      const rows = (list: Field[]) => `<dl class="fields">${list.map(([n, t, d]) => `<dt id="${it.slug}-${n}"><code>${esc(n)}: ${ty(t)}</code></dt><dd>${d || ''}</dd>`).join('')}</dl>`;
      let body = `${crumbs([`${api.root}/${g.id}/`, g.name])}
<h1 class="item"><span class="kind">Endpoint</span> ${esc(api.name)}::${g.name}::<span class="name fn">${fnName(it)}</span><a class="srclink" href="${SRC}/${api.name === 'ipx' ? 'crates/ipx/src/web.rs' : 'crates/directory/src/lib.rs'}">Source</a></h1>
<pre class="decl"><code>${decl}</code></pre>
<p class="summary">${it.summary}</p>
${it.doc || ''}
<p class="access">Access: <b>${esc(access(it))}</b></p>`;
      if (it.pathParams) body += `<h2>Path parameters</h2>${rows(it.pathParams)}`;
      if (it.query) body += `<h2>Query</h2><p>${ty(it.query)}, as query parameters:</p>${rows(fieldsOf(it.query))}`;
      if (it.body) body += `<h2>Body</h2><p>${ty(it.body)}, as JSON.</p>`;
      body += `<h2>Returns</h2><p>${isType(it.returns) ? `${ty(it.returns)}, as JSON.` : esc(it.returns)}</p>`;
      if (it.errors?.length) body += `<h2>Errors</h2><dl class="fields">${it.errors.map(([c, d]) => `<dt><code>${esc(c)}</code></dt><dd>${d}</dd>`).join('')}</dl>`;
      if (it.example) body += `<h2>Example</h2><pre><code>${esc(it.example)}</code></pre>`;
      page(`${api.root.slice(1)}/${g.id}/${it.slug}.html`, `${it.method} ${it.path} - ${label}`, it.summary.replace(/<[^>]+>/g, ''), sidebar({ group: g, item: it }), body);
    }
  }

  page(`${api.root.slice(1)}/types/index.html`, `${api.name}::types`, `The types ${label}'s API takes and gives.`, sidebar(),
    `${crumbs()}<h1 class="item"><span class="kind">Module</span> ${esc(api.name)}::<span class="name">types</span></h1>
<dl class="list">${api.types.map(t => `<dt><a class="t" href="${typeHref(t.name)}">${t.name}</a></dt><dd>${t.doc || ''}</dd>`).join('')}</dl>`);

  for (const t of api.types) {
    const decl = t.name === 'Event'
      ? `enum Event {\n${t.fields.map(([n, f]) => `    ${n} ${ty(f)},`).join('\n')}\n}`
      : t.fields.length
        ? `struct ${t.name} {\n${t.fields.map(([n, f]) => `    ${n}: ${ty(f)},`).join('\n')}\n}`
        : `enum ${t.name}`;
    const uses = usedBy.get(t.name) || [];
    let body = `${crumbs([`${api.root}/types/`, 'types'])}
<h1 class="item"><span class="kind">${t.name === 'Event' || !t.fields.length ? 'Enum' : 'Struct'}</span> ${esc(api.name)}::types::<span class="name t">${t.name}</span></h1>
<pre class="decl"><code>${decl}</code></pre>
${t.doc ? `<p class="summary">${t.doc}</p>` : ''}`;
    if (t.fields.length) {
      body += `<h2>${t.name === 'Event' ? 'Variants' : 'Fields'}</h2><dl class="fields">${t.fields.map(([n, f, d]) =>
        `<dt id="${n}"><a class="anchor" href="#${n}" aria-label="Link to ${esc(n)}">§</a><code>${esc(n)}${t.name === 'Event' ? ' ' : ': '}${ty(f)}</code></dt><dd>${d || ''}</dd>`).join('')}</dl>`;
    }
    if (uses.length) {
      body += `<h2>Used by</h2><ul class="uses">${uses.map(([g, x]) => g
        ? `<li><a class="${METHOD_CLASS[x.method]}" href="${itemHref(g, x)}"><span class="verb">${x.method}</span> ${esc(x.path)}</a></li>`
        : `<li><a class="t" href="${typeHref(x.name)}">${x.name}</a></li>`).join('')}</ul>`;
    }
    page(`${api.root.slice(1)}/types/${t.name}.html`, `${t.name} - ${label}`, (t.doc || `${t.name} in ${label}'s API`).replace(/<[^>]+>/g, ''), sidebar({ type: t }), body);
  }

  // Every link to a type must name one there is: a misspelt type in api.mts is otherwise a
  // name in plain text, which looks right and leads nowhere.
  for (const g of api.groups) for (const it of g.items) for (const s of [it.body, it.query].filter((s): s is string => !!s)) {
    for (const n of s.match(/\b[A-Z][A-Za-z]+\b/g) ?? []) if (!typeNames.has(n) && !['Vec', 'Option'].includes(n)) throw new Error(`${it.path}: no type ${n}`);
  }
}

reference(ipx);
reference(directory);