@kontourai/corpus 0.0.0-bootstrap.0 → 0.8.0

package/src/hub.mjs

@@ -0,0 +1,198 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { UsageError } from './errors.mjs';
+import { validateProducts } from './manifest.mjs';
+import { BASE_CSS, escapeHtml } from './site-template.mjs';
+
+const HUB_CSS = `${BASE_CSS}
+main { max-width: 1100px; margin: 0 auto; padding: 2rem 1.5rem 3rem; }
+h1 { font-size: 2.1rem; line-height: 1.2; margin: 0 0 .5rem; }
+.lede { color: var(--muted); font-size: 1.1rem; max-width: 70ch; margin: 0 0 1.5rem; }
+.legend { display: flex; flex-wrap: wrap; gap: .5rem 1.25rem; padding: 0; margin: 0 0 1.5rem; list-style: none; color: var(--muted); font-size: .9rem; }
+.products { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); padding: 0; margin: 0; list-style: none; }
+.product { border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); padding: 1rem 1.1rem; display: flex; flex-direction: column; gap: .4rem; }
+.product h2 { font-size: 1.15rem; margin: 0; display: flex; align-items: center; gap: .6rem; flex-wrap: wrap; }
+.product h2 a { color: var(--fg); text-decoration: none; }
+.product h2 a:hover { text-decoration: underline; }
+.product .tagline { margin: 0; color: var(--muted); font-size: .95rem; }
+.product .meta { margin: 0; color: var(--muted); font-size: .85rem; }
+.product .links { margin: auto 0 0; font-size: .9rem; display: flex; gap: 1rem; }
+.state { display: inline-block; font-size: .75rem; font-weight: 700; letter-spacing: .03em; text-transform: uppercase; padding: .1rem .5rem; border-radius: 999px; border: 1px solid currentColor; }
+.state-current { color: var(--ok); }
+.state-behind { color: var(--warn); }
+.state-thin { color: var(--info); }
+.state-unpublished { color: var(--bad); }
+.state-unknown, .state-checking { color: var(--muted); }
+section.install { margin-top: 2.5rem; max-width: 80ch; }
+section.install h2 { margin-bottom: .5rem; }
+`;
+
+/**
+ * Client-side status: the bundle comes from the same origin (the hub must be
+ * served at the origin root, e.g. https://kontourai.github.io/), and the
+ * default-branch HEAD from the GitHub API, cached in localStorage for 10
+ * minutes to stay under the anonymous rate limit. Precedence: unpublished, behind, thin, current; "unknown" when the
+ * main commit could not be read and nothing else applies.
+ */
+const HUB_SCRIPT = `
+(function () {
+  var products = JSON.parse(document.getElementById('products-data').textContent);
+  var TTL = 10 * 60 * 1000;
+  function ago(iso) {
+    var then = Date.parse(iso);
+    if (!isFinite(then)) return 'at an unknown time';
+    var s = Math.max(0, (Date.now() - then) / 1000);
+    var units = [['year', 31536000], ['month', 2592000], ['day', 86400], ['hour', 3600], ['minute', 60]];
+    for (var i = 0; i < units.length; i++) {
+      var n = Math.floor(s / units[i][1]);
+      if (n >= 1) return n + ' ' + units[i][0] + (n === 1 ? '' : 's') + ' ago';
+    }
+    return 'just now';
+  }
+  function getJson(url, init) {
+    return fetch(url, init).then(function (r) {
+      if (!r.ok) throw new Error('HTTP ' + r.status);
+      return r.json();
+    });
+  }
+  function mainCommit(repo) {
+    var key = 'docs-kit-hub:head:' + repo;
+    try {
+      var hit = JSON.parse(localStorage.getItem(key) || 'null');
+      if (hit && Date.now() - hit.at < TTL) return Promise.resolve(hit.value);
+    } catch (e) {}
+    return getJson('https://api.github.com/repos/' + repo + '/commits/HEAD', { headers: { Accept: 'application/vnd.github+json' } }).then(function (c) {
+      var value = { sha: c.sha, date: c.commit && c.commit.committer ? c.commit.committer.date : null };
+      try { localStorage.setItem(key, JSON.stringify({ at: Date.now(), value: value })); } catch (e) {}
+      return value;
+    });
+  }
+  function settle(p) {
+    return p.then(function (v) { return { ok: true, value: v }; }, function (e) { return { ok: false, error: e }; });
+  }
+  function text(el, value) { el.textContent = value; }
+  products.forEach(function (p) {
+    var card = document.getElementById('product-' + p.product);
+    var badge = card.querySelector('.state');
+    var tagline = card.querySelector('.tagline');
+    var meta = card.querySelector('.meta');
+    Promise.all([
+      settle(getJson('/' + p.product + '/docs-bundle.json', { cache: 'no-cache' })),
+      settle(mainCommit(p.repo))
+    ]).then(function (r) {
+      var bundle = r[0].ok && r[0].value && [1, 2].includes(r[0].value.schemaVersion) ? r[0].value : null;
+      var main = r[1].ok ? r[1].value : null;
+      var state, detail;
+      if (!bundle) {
+        state = 'unpublished';
+        detail = 'No docs bundle is published at /' + p.product + '/docs-bundle.json.';
+      } else {
+        var docs = (bundle.documents || []).filter(function (d) { return !d.landing; }).length, topics = (bundle.topics || []).length;
+        var counts = docs + ' doc' + (docs === 1 ? '' : 's') + ', ' + topics + ' topic' + (topics === 1 ? '' : 's');
+        var built = 'built ' + ago(bundle.builtAt) + ' from ' + String(bundle.sha || '').slice(0, 7);
+        if (bundle.tagline) text(tagline, bundle.tagline);
+        if (main && main.sha && bundle.sha !== main.sha) {
+          state = 'behind';
+          detail = counts + '; ' + built + '; HEAD is ' + main.sha.slice(0, 7) + (main.date ? ', committed ' + ago(main.date) : '') + '.';
+        } else if (docs < 3) {
+          state = 'thin';
+          detail = counts + '; ' + built + '. Fewer than 3 documents.';
+        } else if (main && main.sha) {
+          state = 'current';
+          detail = counts + '; ' + built + ', matching HEAD.';
+        } else {
+          state = 'unknown';
+          detail = counts + '; ' + built + '. Could not read the default branch from GitHub to compare.';
+        }
+      }
+      badge.className = 'state state-' + state;
+      text(badge, state);
+      text(meta, detail);
+      card.setAttribute('data-state', state);
+    });
+  });
+})();
+`;
+
+function productCard({ product, repo }) {
+  return `<li class="product" id="product-${escapeHtml(product)}" data-state="checking">
+  <h2><a href="/${escapeHtml(product)}/">${escapeHtml(product)}</a> <span class="state state-checking">checking</span></h2>
+  <p class="tagline"></p>
+  <p class="meta" aria-live="polite">Loading the published docs bundle…</p>
+  <p class="links"><a href="/${escapeHtml(product)}/">Docs site</a><a href="https://github.com/${escapeHtml(repo)}">${escapeHtml(repo)}</a></p>
+</li>`;
+}
+
+export function renderHub(products) {
+  // `<` is escaped so product data can never close the script element.
+  const data = JSON.stringify(products).replace(/</g, '\\u003c');
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Kontour documentation</title>
+<meta name="description" content="Documentation for every Kontour building block, and one MCP server that serves all of it to agents.">
+<meta name="generator" content="@kontourai/corpus">
+<style>${HUB_CSS}</style>
+</head>
+<body>
+<a class="skip-link" href="#main">Skip to content</a>
+<header class="site-header">
+  <a class="brand" href="./">Kontour docs</a>
+  <nav aria-label="Site"><a href="https://github.com/kontourai">GitHub</a><a href="#install">MCP server</a></nav>
+</header>
+<main id="main">
+  <h1>Kontour documentation</h1>
+  <p class="lede">Every Kontour building block publishes its docs here from its own repository. Status compares each published bundle with the HEAD of the repository's default branch.</p>
+  <ul class="legend" aria-label="Status legend">
+    <li><span class="state state-current">current</span> built from the default branch HEAD</li>
+    <li><span class="state state-behind">behind</span> the default branch has moved since the build</li>
+    <li><span class="state state-thin">thin</span> fewer than 3 documents</li>
+    <li><span class="state state-unpublished">unpublished</span> no bundle found</li>
+    <li><span class="state state-unknown">unknown</span> GitHub could not be reached to compare</li>
+  </ul>
+  <ul class="products">
+${products.map(productCard).join('\n')}
+  </ul>
+  <section class="install" id="install" aria-labelledby="install-heading">
+    <h2 id="install-heading">Ask an agent about any building block</h2>
+    <p>The Corpus MCP server reads every published bundle listed here and answers <code>list_products</code>, <code>list_topics</code>, <code>get_topic</code>, <code>get_document</code>, and <code>search</code>. Replace <code>&lt;sha&gt;</code> with a commit of <a href="https://github.com/kontourai/corpus">kontourai/corpus</a>.</p>
+    <pre><code>npx -y github:kontourai/corpus#&lt;sha&gt; corpus mcp</code></pre>
+    <p>Claude Code:</p>
+    <pre><code>claude mcp add kontour-docs -- npx -y github:kontourai/corpus#&lt;sha&gt; corpus mcp</code></pre>
+    <p>Codex (<code>~/.codex/config.toml</code>):</p>
+    <pre><code>[mcp_servers.kontour-docs]
+command = "npx"
+args = ["-y", "github:kontourai/corpus#&lt;sha&gt;", "corpus", "mcp"]</code></pre>
+  </section>
+</main>
+<footer class="site-footer">Generated by <a href="https://github.com/kontourai/corpus">Corpus</a> from <a href="products.json">products.json</a>.</footer>
+<script type="application/json" id="products-data">${data}</script>
+<script>${HUB_SCRIPT}</script>
+</body>
+</html>
+`;
+}
+
+/** `docs-kit hub`: validate products.json strictly, write index.html and a copy of products.json. */
+export function runHub({ products: productsFile, out }) {
+  let text;
+  try {
+    text = readFileSync(productsFile, 'utf8');
+  } catch (error) {
+    throw new UsageError(`cannot read ${productsFile}: ${error.code === 'ENOENT' ? 'file not found' : error.message}`);
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new UsageError(`${productsFile} is not valid JSON: ${error.message}`);
+  }
+  const { products, errors } = validateProducts(raw);
+  if (errors.length > 0) throw new UsageError(`${productsFile} is invalid:\n${errors.map((error) => `  - ${error}`).join('\n')}`);
+  mkdirSync(out, { recursive: true });
+  writeFileSync(path.join(out, 'index.html'), renderHub(products));
+  writeFileSync(path.join(out, 'products.json'), text);
+  return `docs-kit hub: ${products.length} products -> ${out}`;
+}

package/src/index.mjs

@@ -0,0 +1,12 @@
+// Library entry. The CLI (bin/docs-kit.mjs) is the supported interface; these
+// exports exist for tests and for tools that embed docs-kit.
+export { runChecks, runDecisionChecks, formatCheckReport } from './check.mjs';
+export { parseDecisionRecord, validateDecisionRecord, validateDecisions, renderDecisionIndex, DECISION_STATUSES, EVIDENCE_KINDS } from './decisions.mjs';
+export { runBuild, checkGeneratedSite } from './build.mjs';
+export { assembleBundle, bundleDigest, bundleFromCheckout } from './bundle.mjs';
+export { validateManifest, validateProducts, loadManifest } from './manifest.mjs';
+export { analyzeMarkdown, githubSlug, extractSection } from './markdown.mjs';
+export { createDocsServer, hubSource, repoSource, workspaceSource, staticSource, bundleFileSource, bundleShapeError, searchBundles } from './mcp.mjs';
+export { renderHub } from './hub.mjs';
+export { EXIT_OK, EXIT_GATE, EXIT_USAGE } from './errors.mjs';
+export { readContentManifest, contentImpact, checkContentReviews } from './content.mjs';

package/src/init.mjs

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { UsageError } from './errors.mjs';
+import { originRepo } from './git.mjs';
+import { DEFAULT_LANDING, INIT_PURPOSE_PLACEHOLDER, manifestFile } from './manifest.mjs';
+import { isRepoFile, listMarkdownFiles } from './paths.mjs';
+
+function titleCase(value) {
+  return value
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\p{L}/gu, (letter) => letter.toUpperCase());
+}
+
+/** Section guess: the first directory under docs/, or "Documentation" for docs/*.md. */
+export function guessSection(source) {
+  const parts = source.split('/');
+  return parts.length > 2 ? titleCase(parts[1]) : 'Documentation';
+}
+
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-._]+|[-._]+$/g, '') || 'product';
+}
+
+/**
+ * `corpus init`: write a starter v2 corpus.json. Never overwrites one, and
+ * refuses while a retired docs-kit.json is present (manifestFile throws).
+ */
+export function runInit({ root }) {
+  const target = path.join(root, manifestFile(root));
+  if (existsSync(target)) throw new UsageError(`${target} already exists; refusing to overwrite it`);
+
+  const repo = originRepo(root) ?? `kontourai/${slugify(path.basename(path.resolve(root)))}`;
+  const product = repo.split('/')[1];
+  let tagline = '';
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (typeof pkg.description === 'string') tagline = pkg.description.trim();
+  } catch {
+    // No package.json, or not JSON: leave the tagline for the author.
+  }
+
+  const manifest = {
+    schemaVersion: 2,
+    product,
+    title: titleCase(product),
+    tagline,
+    repo,
+    purpose: INIT_PURPOSE_PLACEHOLDER,
+    builtOn: [],
+    landing: DEFAULT_LANDING,
+    documents: listMarkdownFiles(root, 'docs').map((source) => ({ source, section: guessSection(source) })),
+    topics: [],
+    exclude: [],
+  };
+  writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`);
+  const notes = [`corpus init: wrote ${target} with ${manifest.documents.length} documents`];
+  if (!isRepoFile(root, DEFAULT_LANDING)) notes.push(`  note: ${DEFAULT_LANDING} does not exist; create it or set "landing"`);
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(product)) notes.push(`  note: product "${product}" is not a lowercase slug; adjust product and repo`);
+  notes.push('  next: replace the "purpose" placeholder, list the Kontour products you build on in "builtOn" (or leave it empty), review sections and order, move unpublished docs to "exclude", add "topics" and "covers", then run corpus check');
+  return notes.join('\n');
+}

package/src/locate.mjs

@@ -0,0 +1,341 @@
+import { Lexer } from 'marked';
+import { analyzeMarkdown, blockLines, decodeEntities, plainText } from './markdown.mjs';
+import { encodePath } from './paths.mjs';
+
+/**
+ * Find a quoted passage, typically text selected on a rendered docs page, in
+ * a bundle's Markdown and report where it lives in the source file.
+ *
+ * Both sides are reduced to a comparable form: letters and digits, lowercased
+ * and NFKD-decomposed with combining marks dropped, and every run of
+ * whitespace or punctuation collapsed to one space. Markdown that renders as
+ * nothing is dropped from the document side first: link and image
+ * destinations, HTML tags and comments, fence lines, list and task markers,
+ * and reference definitions. Entities are decoded. Emphasis and code marks
+ * (`*`, `_`, `~`, backticks) and backslashes are dropped on both sides
+ * without leaving a gap, so `**foo**bar` matches the rendered `foobar`. Code
+ * (fenced, indented, and code spans) renders literally, so nothing inside it
+ * is dropped except those marks. Each kept character remembers its offset in
+ * the original Markdown, so a match maps back to exact lines.
+ */
+
+const DROPPED = /[*_~`\\]/;
+const WORD = /[\p{L}\p{N}]/u;
+const MARK = /\p{M}/u;
+const MIN_QUOTE = 3;
+const ANCHOR_WORDS = 4;
+/** Alternatives returned for an ambiguous quote; `matchCount` reports the total. */
+export const MAX_ALTERNATIVES = 10;
+
+/** Line-start offsets, counting CRLF, a lone CR, and LF as one break each, as the Markdown lexer does. */
+function lineIndex(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code === 10 || (code === 13 && text.charCodeAt(i + 1) !== 10)) starts.push(i + 1);
+  }
+  return {
+    starts,
+    /** 1-based line of a character offset. */
+    lineOf(offset) {
+      let low = 0;
+      let high = starts.length - 1;
+      while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (starts[mid] <= offset) low = mid;
+        else high = mid - 1;
+      }
+      return low + 1;
+    },
+  };
+}
+
+const LIST_MARKER = /^(?:[-+*]|\d{1,9}[.)])(?:[ \t]|$)/;
+
+/**
+ * Offsets that are code content (rendered literally): fenced and indented
+ * code lines, and code spans. Fences are found by a line scanner, so ones
+ * nested in lists and blockquotes count too. An opener may follow `>` and
+ * list markers; it may be indented four or more columns only inside a list
+ * (elsewhere that is an indented code line, not a fence). A fence opened in
+ * a blockquote ends with the blockquote.
+ */
+function codeRanges(markdown, index) {
+  const literal = new Uint8Array(markdown.length);
+  const lineSpan = (first, last) => {
+    if (last < first) return;
+    const from = index.starts[first - 1];
+    const to = last < index.starts.length ? index.starts[last] : markdown.length;
+    literal.fill(1, from, to);
+  };
+  const lines = markdown.split(/\r\n|\r|\n/);
+  let open = null;
+  let inList = false;
+  lines.forEach((line, i) => {
+    const quoted = /^[ \t]*>/.test(line);
+    let rest = line.replace(/^(?:[ \t]*>)+/, '');
+    const indent = /^[ \t]*/.exec(rest)[0].replace(/\t/g, '    ').length;
+    rest = rest.trimStart();
+    let marker = false;
+    for (let m = LIST_MARKER.exec(rest); m; m = LIST_MARKER.exec(rest)) {
+      marker = true;
+      rest = rest.slice(m[0].length).trimStart();
+    }
+    if (marker) inList = true;
+    else if (rest !== '' && indent === 0 && !quoted && open === null) inList = false;
+    const fence = /^(`{3,}|~{3,})(.*)$/.exec(rest);
+    if (open !== null) {
+      if (open.quoted && !quoted) {
+        lineSpan(open.first, i); // the blockquote ended, and the fence with it
+        open = null;
+      } else {
+        if (fence && fence[1][0] === open.char && fence[1].length >= open.length && fence[2].trim() === '') {
+          lineSpan(open.first, i);
+          open = null;
+        }
+        return;
+      }
+    }
+    if (!fence || (indent >= 4 && !marker && !inList)) return;
+    // A backtick fence's info string cannot contain a backtick.
+    if (fence[1][0] === '`' && fence[2].includes('`')) return;
+    open = { first: i + 2, char: fence[1][0], length: fence[1].length, quoted };
+  });
+  if (open !== null) lineSpan(open.first, lines.length);
+  // Indented code blocks are top-level code tokens without a fence.
+  for (const { token, start, end } of blockLines(Lexer.lex(markdown, { gfm: true })))
+    if (token.type === 'code' && !/^[ \t]*(?:`{3,}|~{3,})/.test(token.raw)) lineSpan(start, end);
+  // Code spans, per paragraph: a backtick run closes at the next run of the
+  // same length; an unmatched run is literal. Runs are found once, so time
+  // stays linear in the paragraph, whatever its backticks.
+  for (const paragraph of markdown.matchAll(/[^\n]+(?:\n(?![ \t]*\r?$)[^\n]*)*/gm)) {
+    const runs = [...paragraph[0].matchAll(/`+/g)].map((run) => ({ at: paragraph.index + run.index, length: run[0].length }));
+    const next = new Map(); // length -> indexes of runs with that length, in order
+    runs.forEach((run, k) => {
+      if (!next.has(run.length)) next.set(run.length, []);
+      next.get(run.length).push(k);
+    });
+    const cursor = new Map();
+    for (let k = 0; k < runs.length; ) {
+      const { at, length } = runs[k];
+      const same = next.get(length);
+      let c = cursor.get(length) ?? 0;
+      while (c < same.length && same[c] <= k) c++;
+      cursor.set(length, c);
+      if (c >= same.length || literal[at]) {
+        k++;
+        continue;
+      }
+      const close = same[c];
+      literal.fill(1, at + length, runs[close].at);
+      k = close + 1;
+    }
+  }
+  return literal;
+}
+
+const ENTITY = /&(?:#x[\da-f]+|#\d+|[a-z][a-z\d]*);/gi;
+
+/** Character ranges of Markdown that render as nothing, and entities to decode, outside code. */
+function markdownMask(markdown, index) {
+  const literal = codeRanges(markdown, index);
+  const hidden = new Uint8Array(markdown.length);
+  const patterns = [
+    /\]\((?:[^()\s]|\([^()]*\))*(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g, // ](destination "title")
+    /\]\[[^\]\n]*\]/g, // ][reference]
+    /^ {0,3}\[[^\]\n]+\]:.*$/gm, // [reference]: definition
+    /<!--[\s\S]*?-->/g,
+    /<\/?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>]*)?\/?>/g, // tags, but not autolinks such as <https://x>
+    /^[ \t]*(?:`{3,}|~{3,}).*$/gm, // fence lines and their info strings
+    /^[ \t>]*(?:[-+*]|\d{1,9}[.)])[ \t]+(?:\[[ xX]\][ \t]+)?/gm, // list and task markers
+  ];
+  for (const pattern of patterns)
+    for (const match of markdown.matchAll(pattern)) {
+      if (literal[match.index]) continue;
+      // A `](...)` or `][...]` match keeps its `]`; only the destination is hidden.
+      const from = match[0].startsWith('](') || match[0].startsWith('][') ? match.index + 1 : match.index;
+      for (let i = from; i < match.index + match[0].length; i++) if (!literal[i]) hidden[i] = 1;
+    }
+  const entities = new Map();
+  for (const match of markdown.matchAll(ENTITY)) {
+    if (literal[match.index] || hidden[match.index]) continue;
+    const decoded = decodeEntities(match[0]);
+    if (decoded === match[0]) hidden.fill(1, match.index, match.index + match[0].length);
+    else entities.set(match.index, { end: match.index + match[0].length, text: decoded });
+  }
+  return { hidden, entities };
+}
+
+/** The comparable form of `text`, plus each output character's offset in `text`. */
+export function normalizeForMatch(text, { markdown = false, index = null } = {}) {
+  const { hidden, entities } = markdown ? markdownMask(text, index ?? lineIndex(text)) : { hidden: null, entities: new Map() };
+  let normalized = '';
+  const offsets = [];
+  // Tracked here: endsWith on a string built with += flattens it on every call.
+  let open = false;
+  const separator = (offset) => {
+    if (open) {
+      normalized += ' ';
+      offsets.push(offset);
+      open = false;
+    }
+  };
+  const emit = (value, offset) => {
+    const code = value.charCodeAt(0);
+    // ASCII fast path; everything else goes through NFKD.
+    if (value.length === 1 && code < 128) {
+      if ((code >= 48 && code <= 57) || (code >= 97 && code <= 122)) {
+        normalized += value;
+        offsets.push(offset);
+        open = true;
+      } else if (code >= 65 && code <= 90) {
+        normalized += String.fromCharCode(code + 32);
+        offsets.push(offset);
+        open = true;
+      } else if (!DROPPED.test(value)) separator(offset);
+      return;
+    }
+    for (const part of value.normalize('NFKD').toLowerCase()) {
+      if (MARK.test(part) || DROPPED.test(part)) continue;
+      if (WORD.test(part)) {
+        normalized += part;
+        for (let k = 0; k < part.length; k++) offsets.push(offset);
+        open = true;
+      } else separator(offset);
+    }
+  };
+  for (let i = 0; i < text.length; ) {
+    const entity = entities.get(i);
+    if (entity) {
+      emit(entity.text, i);
+      i = entity.end;
+      continue;
+    }
+    const char = String.fromCodePoint(text.codePointAt(i));
+    if (!hidden?.[i]) emit(char, i);
+    i += char.length;
+  }
+  return { normalized, offsets };
+}
+
+/** Every start index of `needle` in `haystack`. */
+function occurrences(haystack, needle) {
+  const found = [];
+  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + 1)) found.push(at);
+  return found;
+}
+
+/**
+ * Top-level blocks with body lines, and the top-level headings with the id
+ * the page gives them (analyzeMarkdown is what the site build slugs with).
+ */
+function documentOutline(markdown) {
+  const blocks = blockLines(analyzeMarkdown(markdown).tokens);
+  const headings = blocks
+    .filter(({ token }) => token.type === 'heading')
+    .map(({ token, start }) => ({ line: start, text: plainText(token.tokens).trim(), anchor: token.slugId }));
+  return { blocks, headings };
+}
+
+const collapse = (text) => text.replace(/\s+/g, ' ');
+
+/**
+ * Locate `quote` in the documents of `bundle` (optionally only `source`).
+ * Returns { best, alternatives, matchCount, confidence, documentsSearched }
+ * (`best` is null when nothing matches), or { error }. Matching counts every
+ * candidate cheaply; only the best and up to MAX_ALTERNATIVES others are
+ * described in full: the source, the 1-based file line range, the enclosing
+ * heading and anchor, the surrounding Markdown blocks, the GitHub blob URL
+ * with #Lstart-Lend, and the page URL.
+ *
+ * Ranking and confidence: verbatim matches (the quote, whitespace collapsed,
+ * appears as written) come first, then normalized ones, each group in
+ * document order. Confidence is 1 for a verbatim best match, 0.9 for a
+ * normalized one, and 0.5 for the head-and-tail fallback (the first and last
+ * four words in order within a nearby window, used only when nothing matches
+ * whole), divided by the number of candidates.
+ */
+export function locateInBundle(bundle, quote, { source } = {}) {
+  const wanted = normalizeForMatch(quote).normalized.trim();
+  if (wanted.replace(/ /g, '').length < MIN_QUOTE) return { error: `quote is too short to locate; it needs at least ${MIN_QUOTE} letters or digits` };
+  const documents = source === undefined ? bundle.documents : bundle.documents.filter((document) => document.source === source);
+  if (documents.length === 0) return { error: `unknown document "${source}"`, availableDocuments: bundle.documents.map((document) => document.source) };
+
+  // The quote as written, split around its first and last letter or digit, for the verbatim check.
+  const written = collapse(quote).trim();
+  const core = written.replace(/^[^\p{L}\p{N}]+/u, '').replace(/[^\p{L}\p{N}]+$/u, '');
+  const lead = written.slice(0, written.indexOf(core));
+  const trail = written.slice(written.indexOf(core) + core.length);
+
+  const spansIn = (normalized) => {
+    const exact = occurrences(normalized, wanted).map((at) => ({ from: at, to: at + wanted.length, exact: true }));
+    if (exact.length > 0) return exact;
+    const words = wanted.split(' ');
+    if (words.length < ANCHOR_WORDS * 2) return [];
+    const head = words.slice(0, ANCHOR_WORDS).join(' ');
+    const tail = words.slice(-ANCHOR_WORDS).join(' ');
+    const spans = [];
+    for (const at of occurrences(normalized, head)) {
+      const end = normalized.indexOf(tail, at + head.length);
+      if (end !== -1 && end + tail.length - at <= wanted.length * 1.5 + 200) spans.push({ from: at, to: end + tail.length, exact: false });
+    }
+    return spans;
+  };
+  let candidates = documents.flatMap((document) => {
+    const index = lineIndex(document.markdown);
+    const { normalized, offsets } = normalizeForMatch(document.markdown, { markdown: true, index });
+    const { markdown } = document;
+    return spansIn(normalized).map(({ from, to, exact }) => {
+      const start = offsets[from];
+      const last = offsets[to - 1];
+      const end = last + (markdown.codePointAt(last) > 0xffff ? 2 : 1);
+      const verbatim =
+        exact &&
+        collapse(markdown.slice(start, end)) === core &&
+        collapse(markdown.slice(Math.max(0, start - lead.length), start)) === lead &&
+        collapse(markdown.slice(end, end + trail.length)) === trail;
+      return { document, index, start, end, exact, verbatim };
+    });
+  });
+  if (candidates.some((candidate) => candidate.exact)) candidates = candidates.filter((candidate) => candidate.exact);
+  if (candidates.length === 0) return { best: null, documentsSearched: documents.length };
+  const ordered = [...candidates.filter((candidate) => candidate.verbatim), ...candidates.filter((candidate) => !candidate.verbatim)];
+  const best = ordered[0];
+  const base = best.verbatim ? 1 : best.exact ? 0.9 : 0.5;
+
+  const outlines = new Map();
+  const describe = ({ document, index, start, end, exact, verbatim }) => {
+    if (!outlines.has(document)) outlines.set(document, { ...documentOutline(document.markdown), lines: document.markdown.split(/\r\n|\r|\n/) });
+    const { blocks, headings, lines } = outlines.get(document);
+    const lineOffset = document.lineOffset ?? 0;
+    const repoPath = document.repoPath ?? document.source;
+    const bodyStart = index.lineOf(start);
+    const bodyEnd = index.lineOf(end - 1);
+    const heading = headings.filter((entry) => entry.line <= bodyStart).at(-1) ?? null;
+    const around = blocks.filter((block) => block.end >= bodyStart && block.start <= bodyEnd);
+    const contextStart = Math.min(bodyStart, ...around.map((block) => block.start));
+    const contextEnd = Math.max(bodyEnd, ...around.map((block) => block.end));
+    const startLine = bodyStart + lineOffset;
+    const endLine = bodyEnd + lineOffset;
+    return {
+      source: document.source,
+      repoPath,
+      startLine,
+      endLine,
+      heading: heading?.text ?? null,
+      anchor: heading?.anchor ?? null,
+      url: heading ? `${document.url}#${encodeURIComponent(heading.anchor)}` : document.url,
+      blobUrl: `https://github.com/${bundle.repo}/blob/${bundle.sha ?? 'HEAD'}/${encodePath(repoPath)}#L${startLine}-L${endLine}`,
+      markdown: `${lines.slice(contextStart - 1, contextEnd).join('\n')}\n`,
+      match: verbatim ? 'verbatim' : exact ? 'normalized' : 'head-and-tail',
+      ...(document.lineOffset === undefined ? { note: 'this bundle predates docs-kit 0.6.0, so line numbers assume the file has no front matter' } : {}),
+    };
+  };
+  return {
+    best: describe(best),
+    alternatives: ordered.slice(1, 1 + MAX_ALTERNATIVES).map(describe),
+    matchCount: ordered.length,
+    confidence: Math.max(0.01, Math.round((base / ordered.length) * 100) / 100),
+    documentsSearched: documents.length,
+  };
+}