@rathnasgala2/template 2.0.0

package/src/core/internal/provenance.js

@@ -0,0 +1,49 @@
+/**
+ * Shared validation for the caller-supplied `options.provenance` bundle
+ * (see `src/core/manifest.js` module documentation for what it is and why
+ * `build-input` alone cannot supply it).
+ *
+ * This check must run from `renderPublication`'s `assertOptions` before any
+ * directory is created or Eleventy ever runs, so an incomplete provenance
+ * bundle fails closed exactly like an invalid `build-input` does — nothing
+ * is written. `src/core/manifest.js` also calls it directly as a defensive
+ * second check at the point it actually consumes `provenance`, since it is
+ * cheap and it is the module that most directly depends on the invariant.
+ */
+
+import { RenderOptionsError } from '../errors.js';
+
+/**
+ * Validate the caller-supplied provenance bundle is structurally present.
+ * This is a shallow presence check, not schema validation: the assembled
+ * manifest is itself schema-validated by `renderPublication` before being
+ * returned, which is the authoritative check on the values' final shape.
+ *
+ * @param {import('../../../types/index.d.ts').RenderProvenance} provenance
+ *   caller-supplied provenance bundle
+ * @returns {void}
+ */
+export function assertProvenance(provenance) {
+  if (!provenance || typeof provenance !== 'object') {
+    throw new RenderOptionsError('options.provenance is required');
+  }
+  const required = /** @type {const} */ ([
+    'builder',
+    'repositoryCoordinate',
+    'workflowIdentity',
+    'buildToolVersions',
+  ]);
+  for (const field of required) {
+    if (provenance[field] === undefined) {
+      throw new RenderOptionsError(`options.provenance.${field} is required`);
+    }
+  }
+  if (
+    !Array.isArray(provenance.buildToolVersions) ||
+    provenance.buildToolVersions.length < 9
+  ) {
+    throw new RenderOptionsError(
+      'options.provenance.buildToolVersions must have at least 9 entries (build-tool-identity:2.0.0)',
+    );
+  }
+}

package/src/core/internal/render-policy-content.js

@@ -0,0 +1,295 @@
+/**
+ * The single source of truth for `contracts/render-policy.jcs`'s content
+ * (brief S2 section 3 "Markdown, sanitizer, highlighter" and "Per-artifact
+ * CSP baseline"; DEC-097 section 5 `renderPolicyIdentity`).
+ *
+ * `scripts/generate-contracts.mjs` emits this exact document as compact JCS
+ * to `contracts/render-policy.jcs`; `src/core/internal/content-security.js`
+ * consumes the same constants to build the actual markdown-it, sanitize-html
+ * and highlighter configuration this renderer runs, and to compute the
+ * `renderPolicyIdentity` every `renderableBody.renderPolicy` in a
+ * `build-input:2.0.0` instance must byte-equal. Keeping both in one module
+ * makes drift between "the policy we publish" and "the policy we enforce"
+ * structurally impossible.
+ */
+
+/** @type {string} */
+export const RENDER_POLICY_NAME = 'gala-render-policy';
+
+/**
+ * Byte-equal to the template lock's `contractVersion` (DEC-097 section 5),
+ * which every S2 `build-input:2.0.0` fixture carries as the literal string
+ * `"2.0.0"` (matches `manifest.js`'s `buildInputContractVersion`).
+ *
+ * @type {string}
+ */
+export const RENDER_POLICY_VERSION = '2.0.0';
+
+/** @type {string} */
+export const MARKDOWN_IT_PACKAGE = 'markdown-it';
+/** @type {string} */
+export const MARKDOWN_IT_VERSION = '14.3.1';
+
+/**
+ * The exact markdown-it construction options brief S2 section 3 requires.
+ *
+ * @type {{html: false, linkify: false, typographer: false}}
+ */
+export const MARKDOWN_IT_OPTIONS = Object.freeze({
+  html: false,
+  linkify: false,
+  typographer: false,
+});
+
+/** @type {string} */
+export const SANITIZER_PACKAGE = 'sanitize-html';
+/** @type {string} */
+export const SANITIZER_VERSION = '2.17.7';
+
+/**
+ * URL schemes admitted for `a[href]`. Same-document fragments and
+ * repository-relative paths carry no scheme and are handled separately.
+ *
+ * @type {readonly string[]}
+ */
+export const ALLOWED_URL_SCHEMES = Object.freeze(['https', 'http', 'mailto']);
+
+/**
+ * The closed allowlist of tags this renderer ever emits from author
+ * markdown: "semantic text and content tags" only (brief S2 section 3).
+ * No form, frame, SVG, MathML, script, style, object or template element is
+ * ever admitted.
+ *
+ * @type {readonly string[]}
+ */
+export const ALLOWED_TAGS = Object.freeze([
+  'p',
+  'br',
+  'hr',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'ul',
+  'ol',
+  'li',
+  'blockquote',
+  'pre',
+  'code',
+  'strong',
+  'em',
+  'b',
+  'i',
+  'u',
+  's',
+  'del',
+  'ins',
+  'sub',
+  'sup',
+  'mark',
+  'small',
+  'wbr',
+  'a',
+  'img',
+  'table',
+  'thead',
+  'tbody',
+  'tr',
+  'th',
+  'td',
+  'dl',
+  'dt',
+  'dd',
+  'figure',
+  'figcaption',
+  'span',
+]);
+
+/**
+ * The closed per-tag attribute allowlist. `id` is admitted only on headings
+ * (this renderer's own generated heading IDs); `style`, every `on*` handler,
+ * `srcdoc` and every other undeclared attribute is always stripped (brief S2
+ * section 3).
+ *
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const ALLOWED_ATTRIBUTES_BY_TAG = Object.freeze({
+  h1: Object.freeze(['id']),
+  h2: Object.freeze(['id']),
+  h3: Object.freeze(['id']),
+  h4: Object.freeze(['id']),
+  h5: Object.freeze(['id']),
+  h6: Object.freeze(['id']),
+  a: Object.freeze(['href', 'rel']),
+  img: Object.freeze(['src', 'alt']),
+  ol: Object.freeze(['start']),
+  pre: Object.freeze(['class']),
+  code: Object.freeze(['class']),
+  span: Object.freeze(['class']),
+});
+
+/** @type {string} */
+export const HIGHLIGHTER_PACKAGE = '@11ty/eleventy-plugin-syntaxhighlight';
+/** @type {string} */
+export const HIGHLIGHTER_VERSION = '5.0.2';
+
+/**
+ * The closed grammar-name catalog the owned highlighter accepts. A fence
+ * language outside this list always falls back to escaped, unhighlighted
+ * code (brief S2 section 3).
+ *
+ * @type {readonly string[]}
+ */
+export const HIGHLIGHT_GRAMMARS = Object.freeze(
+  [
+    'bash',
+    'css',
+    'diff',
+    'java',
+    'javascript',
+    'json',
+    'jsx',
+    'markdown',
+    'markup',
+    'python',
+    'sql',
+    'tsx',
+    'typescript',
+    'yaml',
+  ].sort(),
+);
+
+/**
+ * The closed `span.class` token-class catalog admitted on highlighted code,
+ * grounded in the actual Prism.js token classes {@link HIGHLIGHT_GRAMMARS}
+ * can produce (Prism's documented generic token set plus this
+ * repository's own empirical sample across every admitted grammar). `token`
+ * itself is always the base class; every other admitted value is a
+ * secondary token-class (brief S2 section 3: "`span` elements carrying
+ * `token` and admitted token-class values").
+ *
+ * @type {readonly string[]}
+ */
+export const ADMITTED_TOKEN_CLASSES = Object.freeze(
+  [
+    'token',
+    'atrule',
+    'attr-equals',
+    'attr-name',
+    'attr-value',
+    'bold',
+    'boolean',
+    'builtin',
+    'cdata',
+    'char',
+    'class-name',
+    'comment',
+    'constant',
+    'content',
+    'coord',
+    'deleted',
+    'deleted-sign',
+    'doctype',
+    'entity',
+    'for-or-select',
+    'function',
+    'function-variable',
+    'important',
+    'inserted',
+    'inserted-sign',
+    'interpolation',
+    'interpolation-punctuation',
+    'italic',
+    'key',
+    'keyword',
+    'namespace',
+    'null',
+    'number',
+    'operator',
+    'prefix',
+    'prolog',
+    'property',
+    'punctuation',
+    'regex',
+    'rule',
+    'selector',
+    'shebang',
+    'string',
+    'symbol',
+    'tag',
+    'template-punctuation',
+    'template-string',
+    'title',
+    'url',
+    'variable',
+  ].sort(),
+);
+
+/**
+ * The closed `pre.class`/`code.class` catalog for highlighted fences: one
+ * `language-<grammar>` value per {@link HIGHLIGHT_GRAMMARS} entry. An
+ * unknown fence language's own `language-<arbitrary>` class (emitted by
+ * markdown-it's own escaped fallback renderer) is not in this list and is
+ * stripped by the sanitizer, matching the "escaped fallback" contract.
+ *
+ * @type {readonly string[]}
+ */
+export const ADMITTED_LANGUAGE_CLASSES = Object.freeze(
+  HIGHLIGHT_GRAMMARS.map((grammar) => `language-${grammar}`),
+);
+
+/**
+ * The exact per-artifact CSP baseline (brief S2 section 3). Directive order
+ * is byte-exact as written in the brief; every directive's value list is
+ * already sorted bytewise and duplicate-free because S2 materializes no
+ * module package, configuration, output or runtime, so this string is
+ * byte-identical on every route.
+ *
+ * @type {string}
+ */
+export const CONTENT_SECURITY_POLICY_BASELINE =
+  "default-src 'none'; base-uri 'none'; object-src 'none'; " +
+  "frame-ancestors 'none'; form-action 'none'; script-src 'self'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; " +
+  "media-src 'self'; manifest-src 'self'; worker-src 'none'";
+
+/**
+ * Build the exact plain-object document `contracts/render-policy.jcs`
+ * publishes: `name`, `version` byte-equal to the template lock's
+ * `contractVersion`, a closed sanitizer/parser catalog, and no self-digest
+ * (DEC-097 section 5).
+ *
+ * @returns {Record<string, unknown>} the render-policy document
+ */
+export function renderPolicyDocument() {
+  return {
+    name: RENDER_POLICY_NAME,
+    version: RENDER_POLICY_VERSION,
+    contentSecurityPolicy: CONTENT_SECURITY_POLICY_BASELINE,
+    markdownIt: {
+      package: MARKDOWN_IT_PACKAGE,
+      version: MARKDOWN_IT_VERSION,
+      options: { ...MARKDOWN_IT_OPTIONS },
+    },
+    sanitizer: {
+      package: SANITIZER_PACKAGE,
+      version: SANITIZER_VERSION,
+      allowedTags: [...ALLOWED_TAGS],
+      allowedAttributes: Object.fromEntries(
+        Object.entries(ALLOWED_ATTRIBUTES_BY_TAG).map(([tag, attrs]) => [
+          tag,
+          [...attrs],
+        ]),
+      ),
+      allowedUrlSchemes: [...ALLOWED_URL_SCHEMES],
+    },
+    highlighter: {
+      package: HIGHLIGHTER_PACKAGE,
+      version: HIGHLIGHTER_VERSION,
+      grammars: [...HIGHLIGHT_GRAMMARS],
+      tokenClasses: [...ADMITTED_TOKEN_CLASSES],
+    },
+  };
+}

package/src/core/internal/route-labels.js

@@ -0,0 +1,68 @@
+/**
+ * Deterministic route-segment derivation for generated listing pages (tag,
+ * series, archive) from an authored `plainLabel` (task packet S2-T06:
+ * navigation renderer/page kinds).
+ *
+ * `contentFrontmatterNormalized.tags`/`.series` are `plainLabel` values:
+ * normalized Unicode text, 1..80 graphemes, with no further route-safety
+ * constraint (checked against
+ * `node_modules/@rathnasgala2/schemas/schemas/build-input.schema.json`'s
+ * `plainLabel` `$def` — no ASCII/slug pattern, unlike `contentFrontmatterNormalized.slug`,
+ * which the schema already restricts to `^[a-z0-9]+(?:-[a-z0-9]+)*$`). A tag
+ * or series label can therefore contain spaces, uppercase letters, or any
+ * non-Latin script.
+ *
+ * `route.js` already documents that this renderer's route projection is
+ * deliberately not DEC-097 section 8's full Unicode-17 percent-encoding and
+ * collision-resolution engine (out of scope; it only ever projects
+ * already-schema-validated `canonicalRoute` values, never derives a route
+ * from an arbitrary label). This module makes the same scoped choice for the
+ * one new case S2-T06 introduces — turning an arbitrary label into a route
+ * segment — and closes the collision risk a lossy ASCII-only slug would
+ * otherwise introduce (two distinct Unicode labels both losing all their
+ * characters to filtering) by always appending a short, deterministic content
+ * hash of the exact label. Two distinct labels can therefore never collide on
+ * the same generated route, even when their readable prefixes are identical
+ * or both empty.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * @param {string} label the raw label
+ * @returns {string} its lowercase ASCII-only readable prefix (may be empty)
+ */
+function asciiReadablePrefix(label) {
+  const lower = label.normalize('NFC').toLowerCase();
+  let out = '';
+  let lastWasSeparator = true;
+  for (const character of lower) {
+    if (/[a-z0-9]/u.test(character)) {
+      out += character;
+      lastWasSeparator = false;
+    } else if (!lastWasSeparator) {
+      out += '-';
+      lastWasSeparator = true;
+    }
+  }
+  return out.replace(/-+$/u, '').slice(0, 48);
+}
+
+/**
+ * Derive a deterministic, collision-free, route-safe segment for an
+ * arbitrary authored label (a tag, a series name, or any other `plainLabel`
+ * used to generate a listing page route).
+ *
+ * @param {string} label the raw authored label
+ * @returns {string} a lowercase ASCII route segment: an optional readable
+ *   prefix followed by a 10-character hexadecimal content hash of the exact
+ *   label
+ */
+export function routeSegmentForLabel(label) {
+  const hash = createHash('sha256')
+    .update(label, 'utf8')
+    .digest('hex')
+    .slice(0, 10);
+  const prefix = asciiReadablePrefix(label);
+  return prefix.length > 0 ? `${prefix}-${hash}` : hash;
+}

package/src/core/internal/route.js

@@ -0,0 +1,167 @@
+/**
+ * Route-to-output-path projection and the byte-exact generated redirect
+ * document (brief S2 section 3 "Required generated outputs"; DEC-097
+ * section 6 artifact-manifest redirect subsection).
+ *
+ * This module implements the `directory-index` and `explicit-file` cases of
+ * DEC-097 section 7's `gala-portable-v2` route projection only for routes
+ * that are already valid `canonicalRoute` strings (schema-enforced before
+ * this module ever runs). The full Unicode-17 percent-encoding/collision
+ * engine DEC-097 section 8 describes is out of S2-T03's scope: it governs
+ * arbitrary repository-relative source paths, which this renderer never
+ * derives routes from (every route it projects comes from an
+ * already-schema-validated `canonicalRoute` field in `build-input`).
+ */
+
+/**
+ * @typedef {'directory-index' | 'explicit-file'} RouteNormalizationProfile
+ */
+
+/**
+ * Join a base path and a route into one absolute public route, exactly
+ * once, with no double slash.
+ *
+ * @param {string} basePath the build input's `basePath` (`canonicalRoute`,
+ *   always starts with `/`)
+ * @param {string} route a `canonicalRoute` (always starts with `/`)
+ * @returns {string} the joined absolute route, starting with `/`
+ */
+export function joinBasePathAndRoute(basePath, route) {
+  const baseSegment = basePath.replace(/^\/+|\/+$/g, '');
+  const routeSegment = route.replace(/^\/+|\/+$/g, '');
+  const segments = [baseSegment, routeSegment].filter(
+    (segment) => segment.length > 0,
+  );
+  return `/${segments.join('/')}`;
+}
+
+/**
+ * Project one already-joined absolute route to its candidate-directory-
+ * relative output file path.
+ *
+ * @param {string} joinedRoute the base-path-joined absolute route
+ * @param {RouteNormalizationProfile} profile the selected route
+ *   normalization profile
+ * @returns {string} a repository-relative-style output path with no leading
+ *   slash
+ */
+export function projectRouteToFilePath(joinedRoute, profile) {
+  const trimmed = joinedRoute.replace(/^\/+/, '');
+  if (profile === 'explicit-file') {
+    return trimmed.length === 0 ? 'index.html' : trimmed;
+  }
+  if (trimmed.length === 0) return 'index.html';
+  return `${trimmed.replace(/\/+$/, '')}/index.html`;
+}
+
+/**
+ * Recover the public route an output file path was projected from, the
+ * exact inverse of {@link projectRouteToFilePath} for the `directory-index`
+ * profile. Used only to prove the manifest's redirect
+ * `backingPath`-to-`sourceRoute` equality invariant by construction.
+ *
+ * @param {string} filePath a candidate-directory-relative output path
+ * @param {RouteNormalizationProfile} profile the selected route
+ *   normalization profile
+ * @returns {string} the absolute route that projects to `filePath`
+ */
+export function projectFilePathToRoute(filePath, profile) {
+  if (profile === 'explicit-file') {
+    return filePath === 'index.html' ? '/' : `/${filePath}`;
+  }
+  if (filePath === 'index.html') return '/';
+  const withoutIndex = filePath.replace(/\/index\.html$/, '');
+  return `/${withoutIndex}`;
+}
+
+/**
+ * Project a `basePath` to the one fixed generated error-document output path
+ * DEC-097's Spaces website-configuration subsection defines: `errorDocumentKey`
+ * is exactly `404.html` when `basePath` is `/`; otherwise the base path with
+ * its one leading and terminal slash removed, followed by `/404.html`. This
+ * is deliberately independent of the selected `RouteNormalizationProfile`
+ * (`directory-index` vs `explicit-file`): the generated error document is
+ * always this one literal filename, never route-normalized like an ordinary
+ * content route (brief S2 section 3: "one ordinary generated `404.html` at
+ * the selected base path"; DEC-097's Spaces/Pages/local-directory adapters
+ * all bind their provider error-document configuration to this exact key).
+ *
+ * @param {string} basePath the build input's `basePath` (`canonicalRoute`,
+ *   always starts with `/`)
+ * @returns {string} the candidate-directory-relative error document path,
+ *   with no leading slash
+ */
+export function errorDocumentPath(basePath) {
+  const trimmed = basePath.replace(/^\/+|\/+$/g, '');
+  return trimmed.length === 0 ? '404.html' : `${trimmed}/404.html`;
+}
+
+/**
+ * Project a `basePath` and a fixed-name public asset route (a route that is
+ * always this one literal file, never subject to `directory-index`
+ * normalization: the generated feeds, sitemap and static search index) to
+ * its candidate-directory-relative output path. Equivalent to
+ * {@link projectRouteToFilePath} under the `explicit-file` profile, exposed
+ * under its own name so a call site never has to spell out
+ * `'explicit-file'` to mean "this is a literal file, not a route".
+ *
+ * @param {string} basePath the build input's `basePath`
+ * @param {string} route a `canonicalRoute` ending in a real file extension
+ *   (e.g. `/feed/atom.xml`)
+ * @returns {string} the candidate-directory-relative output path, with no
+ *   leading slash
+ */
+export function projectFixedAssetPath(basePath, route) {
+  return projectRouteToFilePath(
+    joinBasePathAndRoute(basePath, route),
+    'explicit-file',
+  );
+}
+
+const REDIRECT_TARGET_ESCAPES =
+  /** @type {Readonly<Record<string, string>>} */ ({
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+  });
+
+/**
+ * Apply the redirect document's one-pass HTML escape to a target route.
+ *
+ * @param {string} targetRoute the route the redirect points to
+ * @returns {string} the escaped bytes used for every `T` occurrence
+ */
+export function escapeRedirectTarget(targetRoute) {
+  let escaped = '';
+  for (const character of targetRoute) {
+    escaped += REDIRECT_TARGET_ESCAPES[character] ?? character;
+  }
+  return escaped;
+}
+
+/**
+ * Render the exact UTF-8, no-BOM, LF-terminated generated redirect document
+ * DEC-097 section 6 and brief S2 section 3 specify byte-for-byte.
+ *
+ * @param {string} targetRoute the route this redirect document points to
+ * @returns {string} the complete document text
+ */
+export function renderRedirectDocument(targetRoute) {
+  const escapedTarget = escapeRedirectTarget(targetRoute);
+  return (
+    '<!doctype html>\n' +
+    '<html lang="en">\n' +
+    '<head>\n' +
+    '<meta charset="utf-8">\n' +
+    `<meta http-equiv="refresh" content="0;url=${escapedTarget}">\n` +
+    `<link rel="canonical" href="${escapedTarget}">\n` +
+    '<title>Redirecting...</title>\n' +
+    '</head>\n' +
+    '<body>\n' +
+    `<p>This page has moved to <a href="${escapedTarget}">${escapedTarget}</a>.</p>\n` +
+    '</body>\n' +
+    '</html>\n'
+  );
+}

package/src/core/internal/search-index.js

@@ -0,0 +1,119 @@
+/**
+ * Static search index generation (task packet S2-T08; brief S2 section 3
+ * "Required generated outputs": "static search index").
+ *
+ * Scope note (documented, not silently assumed): neither the brief text this
+ * task read nor DEC-097 fixes an exact search-index document shape (checked
+ * with a full-text grep of both for "search" — no hit beyond this brief
+ * phrase). This module therefore documents its own deterministic shape here,
+ * matching this renderer's established style for an unfixed structural
+ * decision (see `internal/route-labels.js`'s route-segment grammar and the
+ * media pipeline scope decisions in the package README): one JSON document,
+ * `{schemaVersion, generatedAt, publication, documents[]}`, sorted by each
+ * document's own absolute URL (UTF-8 byte order, this renderer's one
+ * deterministic ordering convention throughout — see
+ * `internal/source-inventory.js#compareUtf8Bytes`).
+ *
+ * `generatedAt` is `buildInput.buildEpoch` — a build-input *field*, sourced
+ * deterministically from the selected Git commit's own committer timestamp
+ * (DEC-097 section 5), not read from the wall clock at build time — matching
+ * `src/core/manifest.js`'s own `manifest.generatedAt` convention, so two
+ * clean builds of the same `build-input` still produce byte-identical index
+ * bytes.
+ *
+ * No runtime search JavaScript accompanies this document (brief S2 section
+ * 1: "reads completely with JavaScript disabled"; acceptance test C: "the
+ * appearance controller is the only browser bootstrap" — this renderer's one
+ * admitted client-side script in all of S2). This module's only output is
+ * the index document's bytes; nothing wires a `<script>` to it.
+ *
+ * Only actual authored content (`article`/`page` records, `status:
+ * "published"`) is indexed — never a synthetic listing page
+ * (index/tag/series/archive/profile/author), which has no body text to
+ * excerpt and is already reachable through ordinary navigation rather than
+ * full-text search.
+ */
+
+import { joinBasePathAndRoute } from './route.js';
+import { compareUtf8Bytes } from './source-inventory.js';
+import { contentLastModified, contentRoute } from './page-kinds.js';
+
+/** @type {number} the excerpt's maximum character length — bounded for the
+ * same documented reason `plainText`'s own `description` field is bounded
+ * to 500 graphemes elsewhere in this schema family. */
+const EXCERPT_MAX_LENGTH = 300;
+
+/**
+ * Derive a short plain-text excerpt from an already-sanitized HTML body: a
+ * deliberately simple, deterministic tag strip (never a full HTML parser —
+ * this is a search-index summary field, not rendered output), collapsing
+ * whitespace and bounding the result length.
+ *
+ * @param {string} html a `renderableBody.body`-shaped, already
+ *   render-policy-conformant HTML fragment
+ * @returns {string} the bounded plain-text excerpt
+ */
+function plainTextExcerpt(html) {
+  const stripped = html
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return stripped.length > EXCERPT_MAX_LENGTH
+    ? `${stripped.slice(0, EXCERPT_MAX_LENGTH).trimEnd()}…`
+    : stripped;
+}
+
+/**
+ * Build the deterministic static search index document for one validated
+ * `build-input:2.0.0` instance.
+ *
+ * @param {import('../../../types/index.d.ts').NormalizedBuildInput} validatedInput
+ * @returns {string} the exact UTF-8 JSON text, LF-terminated
+ */
+export function buildSearchIndex(validatedInput) {
+  const { publication, content, basePath, baseUrl, buildEpoch } =
+    validatedInput;
+
+  /**
+   * @param {string} route an un-joined route
+   * @returns {string} the absolute `https://` URL
+   */
+  const absoluteUrl = (route) =>
+    new URL(joinBasePathAndRoute(basePath, route), baseUrl).toString();
+
+  const documents = content
+    .filter(
+      (record) =>
+        (record.frontmatter.kind === 'article' ||
+          record.frontmatter.kind === 'page') &&
+        record.frontmatter.status === 'published',
+    )
+    .map((record) => {
+      const { frontmatter } = record;
+      return {
+        id: frontmatter.id,
+        route: absoluteUrl(contentRoute(frontmatter)),
+        kind: frontmatter.kind,
+        title: frontmatter.title,
+        description: frontmatter.description ?? '',
+        excerpt: plainTextExcerpt(record.body),
+        language: frontmatter.language,
+        tags: [...frontmatter.tags].sort(),
+        publishedAt: frontmatter.publishedAt,
+        lastModified: contentLastModified(frontmatter),
+      };
+    })
+    .sort((a, b) => compareUtf8Bytes(a.route, b.route));
+
+  const document = {
+    schemaVersion: '1',
+    generatedAt: buildEpoch,
+    publication: {
+      title: publication.title,
+      canonicalBase: publication.canonicalBase,
+    },
+    documents,
+  };
+
+  return `${JSON.stringify(document)}\n`;
+}