docspack 0.3.0 → 1.0.0

package/src/coverage.ts

@@ -0,0 +1,96 @@
+import { readFile } from "node:fs/promises";
+import { resolvePackageDir } from "./discovery.js";
+import { formatDocumentedLibrary, type PackageManifest, resolveChunkFile } from "./spec.js";
+import { readPublicSurface } from "./surface.js";
+import { documentedLibraries } from "./verify.js";
+
+/** How much of one library's public surface the documentation mentions. */
+export interface LibraryCoverage {
+  readonly library: string;
+  /** Exported names long enough to search prose for. */
+  readonly names: number;
+  /** Those the documentation mentions at least once, anywhere. */
+  readonly documented: number;
+  /** A sample of what it does not mention, for an author to act on. */
+  readonly uncovered: readonly string[];
+}
+
+export interface CoverageReport {
+  readonly libraries: readonly LibraryCoverage[];
+  /** Libraries the package documents whose declarations could not be read. */
+  readonly unreadable: readonly string[];
+}
+
+/**
+ * A name shorter than this is too generic to look for in prose, and its absence would say
+ * nothing: `Env`, `z`, `app`.
+ */
+const MIN_NAME = 4;
+
+/** How many uncovered names are named in the report. */
+const SAMPLE = 12;
+
+export interface CoverageOptions {
+  readonly packageDir: string;
+  readonly llmsDir: string;
+  readonly manifest: PackageManifest;
+  /** Project the library is resolved from when the docs package does not depend on it itself. */
+  readonly cwd: string;
+}
+
+/**
+ * Compares what a documentation package says against what the library it documents exports.
+ *
+ * A documentation site is written page by page around tasks and an API grows name by name, so
+ * the two drift apart with nobody noticing — measured across two well-documented projects, half
+ * of the exported surface is mentioned nowhere. This is the number that makes that visible, and
+ * it is mechanical: two files, no model, no judgement.
+ */
+export async function measureCoverage(options: CoverageOptions): Promise<CoverageReport> {
+  const libraries = await documentedLibraries(options.packageDir, options.manifest);
+  if (libraries.length === 0) return { libraries: [], unreadable: [] };
+
+  const text = await readCorpus(options);
+  const mentioned = identifiers(text);
+  const covered: LibraryCoverage[] = [];
+  const unreadable: string[] = [];
+
+  for (const library of libraries) {
+    const dir =
+      (await resolvePackageDir(library.name, options.packageDir)) ??
+      (await resolvePackageDir(library.name, options.cwd));
+    const surface = dir === undefined ? undefined : await readPublicSurface(dir);
+    if (surface === undefined) {
+      unreadable.push(formatDocumentedLibrary(library));
+      continue;
+    }
+
+    const names = [...surface.symbols.keys()].filter((name) => name.length >= MIN_NAME);
+    const uncovered = names.filter((name) => !mentioned.has(name));
+    covered.push({
+      library: formatDocumentedLibrary(library),
+      names: names.length,
+      documented: names.length - uncovered.length,
+      uncovered: uncovered.slice(0, SAMPLE),
+    });
+  }
+
+  return { libraries: covered, unreadable };
+}
+
+/** Splits text into the identifier-shaped tokens an exact mention would produce. */
+export function identifiers(text: string): Set<string> {
+  return new Set(text.split(/[^A-Za-z0-9_$]+/).filter((token) => token.length > 0));
+}
+
+async function readCorpus(options: CoverageOptions): Promise<string> {
+  const parts: string[] = [];
+  for (const chunk of options.manifest.chunks) {
+    try {
+      parts.push(await readFile(resolveChunkFile(options.llmsDir, chunk.file), "utf8"));
+    } catch {
+      // A chunk that cannot be read is doctor's finding to report, not coverage's.
+    }
+  }
+  return parts.join("\n");
+}

package/src/db.ts

@@ -8,13 +8,29 @@ import { STOPWORDS } from "./stopwords.js";
 
 const require = createRequire(import.meta.url);
 
+/**
+ * Where a package's text came from. `docs` is written by a human and published as a docs
+ * package; `artifact` is derived from an installed library's own type declarations. The
+ * distinction is not cosmetic — a signature is a fact about the build, prose is a claim by its
+ * author — so it is stored rather than inferred from the name.
+ */
+export type PackageKind = "docs" | "artifact";
+
 export interface IndexedPackage {
   readonly id: string;
   readonly name: string;
   readonly version: string;
+  readonly kind?: PackageKind;
   readonly indexedAt?: string;
 }
 
+/** An exported name and the chunk carrying its declaration. */
+export interface SymbolHit {
+  readonly name: string;
+  readonly packageId: string;
+  readonly chunkId: string;
+}
+
 export interface IndexedChunk {
   readonly chunkId: string;
   readonly filePath: string;
@@ -39,15 +55,18 @@ export interface SearchOptions {
   readonly limit?: number;
   /** Stop returning chunks once this many tokens have been collected. */
   readonly maxTokens?: number;
+  /** Restrict to packages of these kinds. Defaults to every kind. */
+  readonly kinds?: readonly PackageKind[];
 }
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS packages (
     id TEXT PRIMARY KEY,
     name TEXT NOT NULL,
     version TEXT NOT NULL,
+    kind TEXT NOT NULL DEFAULT 'docs',
     indexed_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 
@@ -61,6 +80,15 @@ CREATE TABLE IF NOT EXISTS chunks (
 
 CREATE INDEX IF NOT EXISTS chunks_by_package ON chunks(package_id);
 
+CREATE TABLE IF NOT EXISTS symbols (
+    package_id TEXT NOT NULL REFERENCES packages(id),
+    name TEXT NOT NULL,
+    chunk_id TEXT NOT NULL,
+    PRIMARY KEY (package_id, name)
+);
+
+CREATE INDEX IF NOT EXISTS symbols_by_name ON symbols(name);
+
 CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
     content,
     tags,
@@ -133,9 +161,22 @@ export class Store {
     this.#db = db;
     this.#db.exec("PRAGMA journal_mode = WAL");
     this.#db.exec(SCHEMA);
+    this.#migrate();
     this.#db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
   }
 
+  /**
+   * Brings a store written by an older version forward. `CREATE TABLE IF NOT EXISTS` covers a
+   * new table, but not a new column on one that already exists, and rebuilding the whole index
+   * to add one would make an upgrade re-read every package on the machine.
+   */
+  #migrate(): void {
+    const columns = this.#db.prepare("PRAGMA table_info(packages)").all() as { name: string }[];
+    if (!columns.some((column) => column.name === "kind")) {
+      this.#db.exec("ALTER TABLE packages ADD COLUMN kind TEXT NOT NULL DEFAULT 'docs'");
+    }
+  }
+
   static open(path: string = defaultStorePath()): Store {
     if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
     try {
@@ -154,16 +195,115 @@ export class Store {
 
   listPackages(): IndexedPackage[] {
     const rows = this.#db
-      .prepare("SELECT id, name, version, indexed_at FROM packages ORDER BY name, version")
-      .all() as { id: string; name: string; version: string; indexed_at: string }[];
+      .prepare("SELECT id, name, version, kind, indexed_at FROM packages ORDER BY name, version")
+      .all() as {
+      id: string;
+      name: string;
+      version: string;
+      kind: string;
+      indexed_at: string;
+    }[];
     return rows.map((row) => ({
       id: row.id,
       name: row.name,
       version: row.version,
+      kind: row.kind === "artifact" ? "artifact" : "docs",
       indexedAt: row.indexed_at,
     }));
   }
 
+  /** Every version of one library in the store, newest indexing first. */
+  versionsOf(name: string): IndexedPackage[] {
+    return this.listPackages().filter((pkg) => pkg.name === name);
+  }
+
+  /**
+   * Chunks declaring an exported name, by exact match rather than by ranking.
+   *
+   * A symbol is a key, not a phrase. Ranking one is the mistake that made `docspack ask` unable
+   * to tell "the documentation does not mention this" from "nothing matched".
+   */
+  lookupSymbol(name: string, packageIds?: readonly string[]): SymbolHit[] {
+    if (packageIds !== undefined && packageIds.length === 0) return [];
+    const scope =
+      packageIds === undefined
+        ? ""
+        : ` AND package_id IN (${packageIds.map(() => "?").join(", ")})`;
+    const rows = this.#db
+      .prepare(
+        // A package that declares the name comes first: an empty chunk id means the name is
+        // exported but its declaration was not readable, which answers less.
+        `SELECT name, package_id AS packageId, chunk_id AS chunkId
+           FROM symbols WHERE name = ?${scope}
+          ORDER BY (chunk_id = '') ASC, package_id`,
+      )
+      .all(name, ...(packageIds ?? [])) as {
+      name: string;
+      packageId: string;
+      chunkId: string;
+    }[];
+    return rows.map((row) => ({ name: row.name, packageId: row.packageId, chunkId: row.chunkId }));
+  }
+
+  /** Every chunk of one package, for a check that has to read the whole corpus. */
+  chunksOf(packageId: string): SearchHit[] {
+    const rows = this.#db
+      .prepare(
+        `SELECT chunk_id AS chunkId, package_id AS packageId, file_path AS filePath,
+                tokens, content
+           FROM chunks WHERE package_id = ?`,
+      )
+      .all(packageId) as {
+      chunkId: string;
+      packageId: string;
+      filePath: string;
+      tokens: number;
+      content: string;
+    }[];
+    return rows.map((row) => ({
+      chunkId: row.chunkId,
+      packageId: row.packageId,
+      filePath: row.filePath,
+      tokens: Number(row.tokens ?? 0),
+      content: row.content,
+    }));
+  }
+
+  /** Every exported name recorded for one package. */
+  symbolsOf(packageId: string): string[] {
+    const rows = this.#db
+      .prepare("SELECT name FROM symbols WHERE package_id = ? ORDER BY name")
+      .all(packageId) as { name: string }[];
+    return rows.map((row) => row.name);
+  }
+
+  /** One chunk by its id, however it was found. */
+  chunk(chunkId: string): SearchHit | undefined {
+    const row = this.#db
+      .prepare(
+        `SELECT chunk_id AS chunkId, package_id AS packageId, file_path AS filePath,
+                tokens, content
+           FROM chunks WHERE chunk_id = ?`,
+      )
+      .get(chunkId) as
+      | {
+          chunkId: string;
+          packageId: string;
+          filePath: string;
+          tokens: number;
+          content: string;
+        }
+      | undefined;
+    if (row === undefined) return undefined;
+    return {
+      chunkId: row.chunkId,
+      packageId: row.packageId,
+      filePath: row.filePath,
+      tokens: Number(row.tokens ?? 0),
+      content: row.content,
+    };
+  }
+
   countChunks(packageId: string): number {
     const row = this.#db
       .prepare("SELECT COUNT(*) AS total FROM chunks WHERE package_id = ?")
@@ -171,10 +311,19 @@ export class Store {
     return row.total;
   }
 
-  /** Replaces a package and all of its chunks in a single transaction. */
-  indexPackage(pkg: IndexedPackage, chunks: readonly IndexedChunk[]): void {
+  /**
+   * Replaces a package, all of its chunks and its symbol table in a single transaction.
+   *
+   * `symbols` maps an exported name to the chunk declaring it, and is how a query about a name
+   * is answered without ranking anything.
+   */
+  indexPackage(
+    pkg: IndexedPackage,
+    chunks: readonly IndexedChunk[],
+    symbols?: ReadonlyMap<string, string>,
+  ): void {
     const insertPackage = this.#db.prepare(
-      "INSERT OR REPLACE INTO packages (id, name, version) VALUES (?, ?, ?)",
+      "INSERT OR REPLACE INTO packages (id, name, version, kind) VALUES (?, ?, ?, ?)",
     );
     const insertChunk = this.#db.prepare(
       "INSERT OR REPLACE INTO chunks (chunk_id, package_id, file_path, tokens, content) VALUES (?, ?, ?, ?, ?)",
@@ -182,15 +331,19 @@ export class Store {
     const insertFts = this.#db.prepare(
       "INSERT INTO chunks_fts (content, tags, package_id, chunk_id) VALUES (?, ?, ?, ?)",
     );
+    const insertSymbol = this.#db.prepare(
+      "INSERT OR REPLACE INTO symbols (package_id, name, chunk_id) VALUES (?, ?, ?)",
+    );
 
     this.#db.exec("BEGIN");
     try {
       this.#deleteChunks(pkg.id);
-      insertPackage.run(pkg.id, pkg.name, pkg.version);
+      insertPackage.run(pkg.id, pkg.name, pkg.version, pkg.kind ?? "docs");
       for (const chunk of chunks) {
         insertChunk.run(chunk.chunkId, pkg.id, chunk.filePath, chunk.tokens, chunk.content);
         insertFts.run(chunk.content, chunk.tags.join(" "), pkg.id, chunk.chunkId);
       }
+      for (const [name, chunk] of symbols ?? []) insertSymbol.run(pkg.id, name, chunk);
       this.#db.exec("COMMIT");
     } catch (error) {
       this.#db.exec("ROLLBACK");
@@ -228,6 +381,13 @@ export class Store {
       conditions.push("f.package_id LIKE ?");
       parameters.push(options.packageFilter);
     }
+    if (options.kinds !== undefined) {
+      if (options.kinds.length === 0) return [];
+      conditions.push(
+        `f.package_id IN (SELECT id FROM packages WHERE kind IN (${options.kinds.map(() => "?").join(", ")}))`,
+      );
+      parameters.push(...options.kinds);
+    }
 
     const rows = this.#db
       .prepare(
@@ -272,5 +432,6 @@ export class Store {
   #deleteChunks(packageId: string): void {
     this.#db.prepare("DELETE FROM chunks_fts WHERE package_id = ?").run(packageId);
     this.#db.prepare("DELETE FROM chunks WHERE package_id = ?").run(packageId);
+    this.#db.prepare("DELETE FROM symbols WHERE package_id = ?").run(packageId);
   }
 }

package/src/discovery.ts

@@ -23,6 +23,14 @@ export interface DiscoveredPackage {
   readonly trusted: boolean;
 }
 
+/** An ordinary dependency: a library this project installed, whatever documents it. */
+export interface DiscoveredLibrary {
+  readonly name: string;
+  readonly version: string;
+  /** Root of the installed package. */
+  readonly dir: string;
+}
+
 export interface Discovery {
   readonly packages: readonly DiscoveredPackage[];
   /** Human-readable problems that did not stop discovery, e.g. a declared but uninstalled package. */
@@ -90,19 +98,48 @@ export async function discoverPackages(cwd: string): Promise<Discovery> {
   return { packages, problems };
 }
 
+/**
+ * Every library this project depends on directly, installed and readable.
+ *
+ * Documentation packages are excluded: those are handled by `discoverPackages`, and a docs
+ * package's own type declarations describe nothing anybody asks about.
+ */
+export async function discoverLibraries(cwd: string): Promise<readonly DiscoveredLibrary[]> {
+  const root = resolve(cwd);
+  const names = (await declaredDependencies(root)).filter((name) => !isDocsPackage(name));
+  const libraries: DiscoveredLibrary[] = [];
+
+  for (const name of names) {
+    const dir = await resolvePackageDir(name, root);
+    if (dir === undefined) continue;
+    try {
+      libraries.push({ name, version: await installedVersion(name, dir), dir });
+    } catch {
+      // A dependency with no version in its manifest is not one to index.
+    }
+  }
+
+  return libraries;
+}
+
 /** Package ids installed in this project, used to scope queries to the versions actually in use. */
 export async function projectPackageIds(cwd: string): Promise<string[]> {
   const { packages } = await discoverPackages(cwd);
   return packages.map((pkg) => pkg.id);
 }
 
+/** Docs packages this project depends on, the input to `discoverPackages`. */
+async function declaredDocsPackages(cwd: string): Promise<string[]> {
+  return (await declaredDependencies(cwd)).filter(isDocsPackage);
+}
+
 /**
- * Every docs package declared by this directory or by an ancestor of it. A workspace declares
+ * Every dependency declared by this directory or by an ancestor of it. A workspace declares
  * shared tooling in the repository root and its members inherit the install, so reading only
  * `cwd/package.json` answers "this project has no documentation" for most monorepos — the same
  * upward walk `resolvePackageDir` already does for the install.
  */
-async function declaredDocsPackages(cwd: string): Promise<string[]> {
+async function declaredDependencies(cwd: string): Promise<string[]> {
   const names = new Set<string>();
   let found = false;
   let dir = cwd;
@@ -131,9 +168,7 @@ async function declaredDocsPackages(cwd: string): Promise<string[]> {
     const manifest = parsed as { dependencies?: unknown; devDependencies?: unknown };
     for (const field of [manifest.dependencies, manifest.devDependencies]) {
       if (typeof field !== "object" || field === null) continue;
-      for (const name of Object.keys(field as Record<string, unknown>)) {
-        if (isDocsPackage(name)) names.add(name);
-      }
+      for (const name of Object.keys(field as Record<string, unknown>)) names.add(name);
     }
 
     const parent = dirname(dir);

package/src/doctor.ts

@@ -2,6 +2,7 @@ import type { Dirent } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { readBuildConfig } from "./config.js";
+import { measureCoverage } from "./coverage.js";
 import { PLACEHOLDER } from "./init/templates.js";
 import {
   estimateTokens,
@@ -48,6 +49,13 @@ export interface DoctorOptions {
   readonly pedantic?: boolean;
 }
 
+/**
+ * Below this share of a library's exported names, a package is documenting a fraction of what
+ * the library publishes. Reported, never gated on: a page listing every export and explaining
+ * none would score full marks, so this is a number for an author to read, not a wall.
+ */
+const THIN_COVERAGE = 0.6;
+
 /** Over this, a chunk crowds out the response budget; under it, a chunk answers nothing. */
 const MAX_CHUNK_TOKENS = 1500;
 const MIN_CHUNK_TOKENS = 30;
@@ -64,12 +72,14 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   const prose: Severity = options.pedantic === true ? "warn" : "info";
 
   const pkg = await readJson(join(options.dir, "package.json"));
-  const manifest = await loadManifest(llmsDir, findings);
-  if (manifest === undefined) {
+  const loaded = await loadManifest(llmsDir, findings);
+  if (loaded === undefined) {
     return { ok: false, findings, chunks: 0, tokens: 0 };
   }
+  const { manifest, raw } = loaded;
 
   checkPackageJson(pkg, manifest, findings);
+  checkUnknownFields(raw, findings);
 
   let tokens = 0;
   let newestSource = 0;
@@ -197,6 +207,8 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
     });
   }
 
+  findings.push(...(await coverageFindings(options.dir, llmsDir, manifest)));
+
   if (manifest.chunks.every((chunk) => chunk.entities.length === 0)) {
     findings.push({
       check: "no-entities",
@@ -233,7 +245,7 @@ function plural(count: number, noun: string): string {
 async function loadManifest(
   llmsDir: string,
   findings: Finding[],
-): Promise<PackageManifest | undefined> {
+): Promise<{ manifest: PackageManifest; raw: unknown } | undefined> {
   let raw: string;
   try {
     raw = await readFile(join(llmsDir, MANIFEST_FILE), "utf8");
@@ -248,7 +260,8 @@ async function loadManifest(
   }
 
   try {
-    return parseManifest(JSON.parse(raw), `${LLMS_DIR}/${MANIFEST_FILE}`);
+    const parsed: unknown = JSON.parse(raw);
+    return { manifest: parseManifest(parsed, `${LLMS_DIR}/${MANIFEST_FILE}`), raw: parsed };
   } catch (error) {
     findings.push({
       check: "manifest-invalid",
@@ -261,6 +274,47 @@ async function loadManifest(
   }
 }
 
+/** Every key the format defines. `additionalProperties` is true, so nothing else is read. */
+const MANIFEST_KEYS = new Set(["$schema", "name", "version", "documents", "chunks"]);
+const CHUNK_KEYS = new Set(["id", "file", "tokens", "tags", "entities", "documents"]);
+
+/**
+ * Reports keys outside the closed set.
+ *
+ * Unknown fields are accepted and ignored, which is the forward-compatibility rule and worth
+ * keeping — but it also means `"tokens"` written as `"token"` validates, publishes, and does
+ * nothing. A publisher is the one party who can still tell a typo from an extension, so the
+ * check belongs here rather than in the reader, at a severity `--strict` fails on.
+ */
+function checkUnknownFields(raw: unknown, findings: Finding[]): void {
+  const root = raw as Record<string, unknown>;
+  const unknown = Object.keys(root).filter((key) => !MANIFEST_KEYS.has(key));
+  if (unknown.length > 0) {
+    findings.push({
+      check: "unknown-field",
+      severity: "warn",
+      message: `the manifest has ${unknown.length === 1 ? "a field" : "fields"} nothing reads: ${unknown.join(", ")}`,
+      where: `${LLMS_DIR}/${MANIFEST_FILE}`,
+      fix: "Remove it, or correct the spelling. Unknown fields are accepted and ignored.",
+    });
+  }
+
+  const chunks = Array.isArray(root.chunks) ? root.chunks : [];
+  for (const entry of chunks) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const chunk = entry as Record<string, unknown>;
+    const extra = Object.keys(chunk).filter((key) => !CHUNK_KEYS.has(key));
+    if (extra.length === 0) continue;
+    findings.push({
+      check: "unknown-field",
+      severity: "warn",
+      message: `chunk "${String(chunk.id)}" has ${extra.length === 1 ? "a field" : "fields"} nothing reads: ${extra.join(", ")}`,
+      where: `${LLMS_DIR}/${MANIFEST_FILE}`,
+      fix: "Remove it, or correct the spelling. Unknown fields are accepted and ignored.",
+    });
+  }
+}
+
 function checkPackageJson(
   pkg: Record<string, unknown> | undefined,
   manifest: PackageManifest,
@@ -341,6 +395,48 @@ async function mtime(path: string): Promise<number> {
   }
 }
 
+/**
+ * How much of the documented library's public surface the package mentions.
+ *
+ * A documentation site is written page by page around tasks and an API grows name by name, so
+ * they drift apart with nobody noticing. This is the check that notices — mechanical, from two
+ * files, with no model and no judgement in it.
+ */
+async function coverageFindings(
+  dir: string,
+  llmsDir: string,
+  manifest: PackageManifest,
+): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  let report: Awaited<ReturnType<typeof measureCoverage>>;
+  try {
+    report = await measureCoverage({ packageDir: dir, llmsDir, manifest, cwd: dir });
+  } catch {
+    // Coverage is a note about the documentation, never a reason a package fails to check.
+    return findings;
+  }
+
+  for (const library of report.libraries) {
+    if (library.names === 0) continue;
+    const share = library.documented / library.names;
+    const percent = Math.round(100 * share);
+    findings.push({
+      check: "coverage",
+      severity: "info",
+      message:
+        `mentions ${library.documented} of ${library.names} names ${library.library} exports (${percent}%)` +
+        (library.uncovered.length === 0 ? "" : `; missing ${library.uncovered.join(", ")}`),
+      ...(share < THIN_COVERAGE
+        ? {
+            fix: "Document the exports nobody has written about, or narrow what the package claims to document.",
+          }
+        : {}),
+    });
+  }
+
+  return findings;
+}
+
 async function readJson(path: string): Promise<Record<string, unknown> | undefined> {
   try {
     const parsed: unknown = JSON.parse(await readFile(path, "utf8"));

package/src/document.ts

@@ -6,6 +6,8 @@ export interface CleanedDocument {
   readonly title?: string;
   /** Keywords taken from front matter, indexed alongside the prose. */
   readonly tags: readonly string[];
+  /** Libraries this document describes, when it describes fewer than the whole package. */
+  readonly documents: readonly string[];
 }
 
 const FRONT_MATTER = /^?---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
@@ -17,23 +19,29 @@ const FRONT_MATTER = /^?---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 export function cleanDocument(raw: string): CleanedDocument {
   const match = FRONT_MATTER.exec(raw);
   const body = stripBoilerplate(match === null ? raw : raw.slice(match[0].length)).trim();
-  if (match?.[1] === undefined) return { text: body, tags: [] };
+  if (match?.[1] === undefined) return { text: body, tags: [], documents: [] };
 
   const meta = parseFrontMatter(match[1]);
   return {
     text: body,
     ...(meta.title === undefined ? {} : { title: meta.title }),
     tags: meta.tags,
+    documents: meta.documents,
   };
 }
 
 /**
- * Reads the two front matter fields worth indexing. This is deliberately not a YAML parser:
+ * Reads the three front matter fields worth reading. This is deliberately not a YAML parser:
  * anything more complex is not metadata a retrieval index can use.
  */
-function parseFrontMatter(block: string): { title?: string; tags: string[] } {
+function parseFrontMatter(block: string): {
+  title?: string;
+  tags: string[];
+  documents: string[];
+} {
   let title: string | undefined;
   const tags: string[] = [];
+  const documents: string[] = [];
 
   for (const line of block.split("\n")) {
     const entry = /^\s*([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line);
@@ -45,9 +53,10 @@ function parseFrontMatter(block: string): { title?: string; tags: string[] } {
     if ((key === "tags" || key === "keywords") && value.startsWith("[")) {
       tags.push(...splitList(value));
     }
+    if (key === "documents" && value.startsWith("[")) documents.push(...splitList(value));
   }
 
-  return { ...(title === undefined ? {} : { title }), tags };
+  return { ...(title === undefined ? {} : { title }), tags, documents };
 }
 
 function splitList(value: string): string[] {