@devp0nt/doc0 0.0.0 → 0.1.0

package/dist/export.js

@@ -0,0 +1,76 @@
+import { selectFields } from "./select.js";
+import { resolveRelated } from "./docs.js";
+import { humanize, stripLeadingHeading } from "./utils.js";
+//#region src/export.ts
+const anchor = (id) => `doc-${id}`;
+const filterDocs = (docs, tag, category) => {
+	const items = tag ? docs.byTag(tag) : docs.all();
+	return category ? items.filter((doc) => doc.category.includes(category)) : items;
+};
+/** Group docs by their first `category`, preserving encounter order; uncategorized docs fall into one bucket. */
+const groupByCategory = (items) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const doc of items) {
+		const key = doc.category[0] ?? "uncategorized";
+		const list = groups.get(key);
+		if (list) list.push(doc);
+		else groups.set(key, [doc]);
+	}
+	return groups;
+};
+const metaLine = (doc, all) => {
+	const parts = [`\`${doc.id}\``];
+	if (doc.tags.length > 0) parts.push(doc.tags.join(", "));
+	parts.push(`\`${doc.source.file}:${doc.source.lineStart}-${doc.source.lineEnd}\``);
+	let line = parts.join(" · ");
+	const refs = resolveRelated(all, doc.related);
+	if (refs.length > 0) {
+		const links = refs.map((ref) => `[${ref.title}](#${anchor(ref.id)})${ref.required ? " (must-read)" : ""}`);
+		line += `\n\n**Related:** ${links.join(", ")}`;
+	}
+	return line;
+};
+/** The built-in JSON formatter: the raw docs (or a `fields` projection), pretty-printed. */
+const formatJson = (docs, _all, options) => JSON.stringify(options.fields ? docs.map((doc) => selectFields(doc, options.fields ?? [])) : docs, null, 2);
+/**
+* The built-in Markdown formatter: a title, a table of contents, then each doc with its metadata and body. Docs are
+* grouped under their `category`; when no doc has a category, it degrades to a clean flat list (no empty buckets).
+*/
+const formatMarkdown = (docs, all, options) => {
+	const groups = groupByCategory(docs);
+	const grouped = !(groups.size === 1 && groups.has("uncategorized"));
+	const docHeading = grouped ? "###" : "##";
+	const out = [
+		`# ${options.title ?? "Documentation"}`,
+		"",
+		`> ${docs.length} ${docs.length === 1 ? "doc" : "docs"}`,
+		"",
+		"## Contents",
+		""
+	];
+	for (const [category, inCat] of groups) {
+		if (grouped) out.push(`- **${humanize(category)}**`);
+		for (const doc of inCat) out.push(`${grouped ? "  " : ""}- [${doc.title}](#${anchor(doc.id)})`);
+	}
+	for (const [category, inCat] of groups) {
+		out.push("", "---");
+		if (grouped) out.push("", `## ${humanize(category)}`);
+		for (const doc of inCat) out.push("", `<a id="${anchor(doc.id)}"></a>`, "", `${docHeading} ${doc.title}`, "", metaLine(doc, all), "", stripLeadingHeading(doc.content).trim());
+	}
+	return `${out.join("\n").replace(/\n{3,}/g, "\n\n").trim()}\n`;
+};
+const BUILTIN = {
+	json: formatJson,
+	md: formatMarkdown
+};
+/**
+* Export a collection to one serialized document — `json` or a rich `md` bundle (or a custom {@link Formatter}),
+* optionally filtered by `tag`/`category`. Powers `doc0 export`, and is reusable from a config's `finalGenerate`.
+*/
+const exportDocs = (docs, options = {}) => {
+	const { format = "md", tag, category } = options;
+	const items = filterDocs(docs, tag, category);
+	return (typeof format === "function" ? format : BUILTIN[format])(items, docs, options);
+};
+//#endregion
+export { exportDocs, formatJson, formatMarkdown };

package/dist/generate.d.ts

@@ -0,0 +1,7 @@
+import { Output } from "./types.js";
+
+//#region src/generate.d.ts
+/** Write the file only when its content differs from what's on disk. Returns true if written. */
+declare const writeIfChanged: (output: Output) => Promise<boolean>;
+//#endregion
+export { writeIfChanged };

package/dist/generate.js

@@ -0,0 +1,12 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+//#region src/generate.ts
+/** Write the file only when its content differs from what's on disk. Returns true if written. */
+const writeIfChanged = async (output) => {
+	if (await readFile(output.path, "utf8").catch(() => void 0) === output.content) return false;
+	await mkdir(dirname(output.path), { recursive: true });
+	await writeFile(output.path, output.content, "utf8");
+	return true;
+};
+//#endregion
+export { writeIfChanged };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { Cache, Doc, Doc0Instance, Doc0Options, Doc0Source, DocRelated, DocSource, DocSourceType, Docs, OneOrMany, Output, Parser, ParserInput, RelatedRef, SearchEngine, SearchOptions, ServeWebOptions } from "./types.js";
+import { fileCache, hash, memoryCache, resolveCache } from "./cache.js";
+import { DocsCollection, EngineSource, resolveRelated } from "./docs.js";
+import { ALL_FIELDS, DocField, DocView, parseFields, selectFields } from "./select.js";
+import { ExportFormat, ExportOptions, Formatter, exportDocs, formatJson, formatMarkdown } from "./export.js";
+import { writeIfChanged } from "./generate.js";
+import { codeParser } from "./parsers/code.js";
+import { markdownParser } from "./parsers/markdown.js";
+import { defaultParsers, parseFile } from "./parsers/index.js";
+import { buildDoc } from "./normalize.js";
+import { loadDoc0 } from "./load.js";
+import { asString, asStringArray, defaultIdFromFile, firstHeading, firstLine, humanize, parseRelated, stripLeadingHeading, toArray } from "./utils.js";
+
+//#region src/index.d.ts
+/**
+ * The engine — parse config plus actions. Create one with `Doc0.create(options)` and export it from a config module
+ * (`docs/index.ts`); runners (the CLI, `serveMcp`, …) load it and decide what to run.
+ */
+declare class Doc0<TExtra = unknown> implements Doc0Instance<TExtra> {
+  readonly options: Doc0Options<TExtra>;
+  readonly cache: Cache;
+  private readonly fingerprint;
+  private collected;
+  private signature;
+  private watcher;
+  private readonly listeners;
+  private constructor();
+  static create<TExtra = unknown>(options: Doc0Options<TExtra>): Doc0<TExtra>;
+  private get engineSource();
+  collect(): Promise<Docs<TExtra>>;
+  sync(): Promise<void>;
+  /**
+   * Start watching the globs and call `onChange` (debounced) when a file changes — for push-based reactions like
+   * regenerating outputs. Idempotent: at most one underlying watcher exists per `Doc0`, no matter how many times
+   * `watch()` is called; each call's stop function removes its own listener and closes the watcher once the last one
+   * leaves. Freshness does NOT depend on this — `collect()` revalidates itself.
+   */
+  watch(onChange: () => void | Promise<void>): () => void;
+  private startWatcher;
+  private globFiles;
+  private signatureOf;
+  private scan;
+  private validate;
+}
+//#endregion
+export { ALL_FIELDS, type Cache, type Doc, Doc0, type Doc0Instance, type Doc0Options, type Doc0Source, type DocField, type DocRelated, type DocSource, type DocSourceType, type DocView, type Docs, DocsCollection, type EngineSource, type ExportFormat, type ExportOptions, type Formatter, type OneOrMany, type Output, type Parser, type ParserInput, type RelatedRef, type SearchEngine, type SearchOptions, type ServeWebOptions, asString, asStringArray, buildDoc, codeParser, defaultIdFromFile, defaultParsers, exportDocs, fileCache, firstHeading, firstLine, formatJson, formatMarkdown, hash, humanize, loadDoc0, markdownParser, memoryCache, parseFields, parseFile, parseRelated, resolveCache, resolveRelated, selectFields, stripLeadingHeading, toArray, writeIfChanged };

package/dist/index.js

@@ -0,0 +1,160 @@
+import { fileCache, hash, memoryCache, resolveCache } from "./cache.js";
+import { loadDoc0 } from "./load.js";
+import { ALL_FIELDS, parseFields, selectFields } from "./select.js";
+import { DocsCollection, resolveRelated } from "./docs.js";
+import { asString, asStringArray, defaultIdFromFile, firstHeading, firstLine, humanize, parseRelated, stripLeadingHeading, toArray } from "./utils.js";
+import { exportDocs, formatJson, formatMarkdown } from "./export.js";
+import { writeIfChanged } from "./generate.js";
+import { buildDoc } from "./normalize.js";
+import { codeParser } from "./parsers/code.js";
+import { markdownParser } from "./parsers/markdown.js";
+import { defaultParsers, parseFile } from "./parsers/index.js";
+import { readFile, stat } from "node:fs/promises";
+import { watch } from "chokidar";
+import { glob } from "tinyglobby";
+//#region src/index.ts
+/**
+* Bump when the shape of a parsed/cached `Doc` changes (e.g. `related` normalization), so an upgrade invalidates stale
+* on-disk parse entries instead of serving the old shape. Part of the cache fingerprint.
+*/
+const CACHE_VERSION = 2;
+/**
+* Lazily build the default search engine (orama keyword/BM25). Imported only on the first `search()`, never on
+* `collect()`/`export`.
+*/
+const defaultEngine = () => import("./search/index.js").then((module) => module.oramaSearch());
+const isNegative = (pattern) => pattern.startsWith("!");
+/** The non-glob prefix of a pattern — used as a watch root (chokidar 4+ has no glob support). */
+const globBase = (pattern) => {
+	const base = [];
+	for (const segment of pattern.split("/")) {
+		if (/[*?{}[\]!]/.test(segment)) break;
+		base.push(segment);
+	}
+	return base.join("/") || ".";
+};
+/**
+* The engine — parse config plus actions. Create one with `Doc0.create(options)` and export it from a config module
+* (`docs/index.ts`); runners (the CLI, `serveMcp`, …) load it and decide what to run.
+*/
+var Doc0 = class Doc0 {
+	options;
+	cache;
+	fingerprint;
+	collected;
+	signature;
+	watcher;
+	listeners = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.options = options;
+		this.cache = resolveCache(options.cache);
+		this.fingerprint = hash(JSON.stringify({
+			version: CACHE_VERSION,
+			transform: options.transform?.toString() ?? null,
+			category: options.category ?? null,
+			parsers: (options.parsers ?? defaultParsers).map((parser) => parser.name)
+		}));
+	}
+	static create(options) {
+		return new Doc0(options);
+	}
+	get engineSource() {
+		return this.options.search ?? defaultEngine;
+	}
+	async collect() {
+		if (this.options.data) {
+			this.collected ??= new DocsCollection([...this.options.data], this.engineSource);
+			return this.collected;
+		}
+		const files = await this.globFiles();
+		const signature = await this.signatureOf(files);
+		if (this.collected && signature === this.signature) return this.collected;
+		this.collected = new DocsCollection(await this.scan(files), this.engineSource);
+		this.signature = signature;
+		return this.collected;
+	}
+	async sync() {
+		const docs = await this.collect();
+		const { callback, generate, finalGenerate, finalCallback } = this.options;
+		if (callback) for (const cb of toArray(callback)) for (const doc of docs.all()) await cb(doc);
+		const outputs = [];
+		if (generate) for (const doc of docs.all()) {
+			const output = generate(doc);
+			if (output) outputs.push(output);
+		}
+		if (finalGenerate) outputs.push(...toArray(finalGenerate(docs)));
+		for (const output of outputs) await writeIfChanged(output);
+		if (finalCallback) await finalCallback(docs);
+	}
+	/**
+	* Start watching the globs and call `onChange` (debounced) when a file changes — for push-based reactions like
+	* regenerating outputs. Idempotent: at most one underlying watcher exists per `Doc0`, no matter how many times
+	* `watch()` is called; each call's stop function removes its own listener and closes the watcher once the last one
+	* leaves. Freshness does NOT depend on this — `collect()` revalidates itself.
+	*/
+	watch(onChange) {
+		this.listeners.add(onChange);
+		this.watcher ??= this.startWatcher();
+		return () => {
+			this.listeners.delete(onChange);
+			if (this.listeners.size === 0) {
+				this.watcher?.close();
+				this.watcher = void 0;
+			}
+		};
+	}
+	startWatcher() {
+		const watcher = watch([...new Set(this.options.glob.filter((pattern) => !isNegative(pattern)).map(globBase))], { ignoreInitial: true });
+		let timer;
+		const fire = () => {
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				for (const listener of this.listeners) listener();
+			}, 100);
+		};
+		watcher.on("add", fire).on("change", fire).on("unlink", fire);
+		return watcher;
+	}
+	async globFiles() {
+		return (await glob(this.options.glob.filter((pattern) => !isNegative(pattern)), {
+			ignore: this.options.glob.filter(isNegative).map((pattern) => pattern.slice(1)),
+			dot: false
+		})).sort();
+	}
+	async signatureOf(files) {
+		return hash((await Promise.all(files.map(async (file) => {
+			const info = await stat(file);
+			return `${file}:${info.mtimeMs}:${info.size}`;
+		}))).join("\n"));
+	}
+	async scan(files) {
+		const parsers = this.options.parsers ?? defaultParsers;
+		const all = [];
+		for (const file of files) {
+			const content = await readFile(file, "utf8");
+			const key = `parse:${this.fingerprint}:${hash(content)}:${file}`;
+			let parsed = await this.cache.get(key);
+			if (!parsed) {
+				parsed = await parseFile({
+					file,
+					content
+				}, parsers);
+				await this.cache.set(key, parsed);
+			}
+			for (const base of parsed) {
+				const produced = this.options.transform ? toArray(this.options.transform(base)) : [base];
+				for (const doc of produced) all.push(await this.validate(doc));
+			}
+		}
+		return all;
+	}
+	async validate(doc) {
+		const schema = this.options.schema;
+		if (!schema) return doc;
+		const result = await schema["~standard"].validate(doc);
+		if (result.issues) throw new Error(`doc0: schema validation failed for "${doc.id}"`);
+		return result.value;
+	}
+};
+//#endregion
+export { ALL_FIELDS, Doc0, DocsCollection, asString, asStringArray, buildDoc, codeParser, defaultIdFromFile, defaultParsers, exportDocs, fileCache, firstHeading, firstLine, formatJson, formatMarkdown, hash, humanize, loadDoc0, markdownParser, memoryCache, parseFields, parseFile, parseRelated, resolveCache, resolveRelated, selectFields, stripLeadingHeading, toArray, writeIfChanged };

package/dist/load.d.ts

@@ -0,0 +1,10 @@
+import { Doc0Instance, Doc0Source } from "./types.js";
+
+//#region src/load.d.ts
+/**
+ * Resolve a {@link Doc0Source} to an engine: pass an instance through, or import a module by path and grab its `doc0`
+ * (named) or `default` export.
+ */
+declare const loadDoc0: (src: Doc0Source) => Promise<Doc0Instance>;
+//#endregion
+export { loadDoc0 };

package/dist/load.js

@@ -0,0 +1,17 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/load.ts
+const isDoc0 = (value) => typeof value === "object" && value !== null && typeof value.collect === "function";
+/**
+* Resolve a {@link Doc0Source} to an engine: pass an instance through, or import a module by path and grab its `doc0`
+* (named) or `default` export.
+*/
+const loadDoc0 = async (src) => {
+	if (typeof src !== "string") return src;
+	const mod = await import(pathToFileURL(resolve(src)).href);
+	const candidate = mod.doc0 ?? mod.default;
+	if (!isDoc0(candidate)) throw new Error(`doc0: no \`doc0\` (or default) export found in "${src}"`);
+	return candidate;
+};
+//#endregion
+export { loadDoc0 };

package/dist/mcp/index.d.ts

@@ -0,0 +1,13 @@
+import { Doc0Source } from "../types.js";
+import { DocsPage, ListOptions, SearchToolOptions, getDoc, listDocs, searchDocs } from "./tools.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/mcp/index.d.ts
+/**
+ * Serve a doc0 collection over MCP with three universal tools (`list_docs` [paged], `search_docs`, `get_doc`). Pass a
+ * `Doc0` instance or a path to a config module. Tool handlers call `collect()`, which self-revalidates — so the served
+ * data is always fresh without a watcher.
+ */
+declare const serveMcp: (src: Doc0Source) => Promise<McpServer>;
+//#endregion
+export { type DocsPage, type ListOptions, type SearchToolOptions, getDoc, listDocs, searchDocs, serveMcp };

package/dist/mcp/index.js

@@ -0,0 +1,82 @@
+import { loadDoc0 } from "../load.js";
+import { ALL_FIELDS, parseFields } from "../select.js";
+import { getDoc, listDocs, searchDocs } from "./tools.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+//#region src/mcp/index.ts
+/** Default page size for `list_docs` — keeps the agent's context lean; page further with `offset`. */
+const LIST_LIMIT = 50;
+/** Default number of `search_docs` hits when the caller doesn't say. */
+const SEARCH_LIMIT = 10;
+const FIELDS_DESC = `Optional subset of fields to return. Any of: ${ALL_FIELDS.join(", ")}. "source" gives the file path and line span so you can open the implementation.`;
+const json = (value) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify(value, null, 2)
+	}],
+	structuredContent: value
+});
+/**
+* Serve a doc0 collection over MCP with three universal tools (`list_docs` [paged], `search_docs`, `get_doc`). Pass a
+* `Doc0` instance or a path to a config module. Tool handlers call `collect()`, which self-revalidates — so the served
+* data is always fresh without a watcher.
+*/
+const serveMcp = async (src) => {
+	const doc0 = await loadDoc0(src);
+	const server = new McpServer({
+		name: "doc0",
+		version: "0.0.0"
+	}, { capabilities: { tools: {} } });
+	server.registerTool("list_docs", {
+		title: "List docs",
+		description: "List documentation entries (paged). Call this first; for project rules, filter by tag \"rule\" and follow any whose description fits your task. The response includes `total` — if it exceeds the page, fetch more with `offset`.",
+		inputSchema: {
+			tag: z.string().optional(),
+			category: z.string().optional(),
+			fields: z.array(z.string()).optional().describe(FIELDS_DESC),
+			limit: z.number().int().positive().optional().describe(`Max docs to return (default ${LIST_LIMIT}).`),
+			offset: z.number().int().nonnegative().optional().describe("Skip this many docs — page through `total`.")
+		}
+	}, async ({ tag, category, fields, limit, offset }) => json(listDocs(await doc0.collect(), {
+		tag,
+		category,
+		fields: parseFields(fields),
+		limit: limit ?? LIST_LIMIT,
+		offset
+	})));
+	server.registerTool("search_docs", {
+		title: "Search docs",
+		description: "Hybrid keyword + semantic search across all docs. Returns the top matching docs with snippets.",
+		inputSchema: {
+			query: z.string(),
+			limit: z.number().int().positive().optional().describe(`Max hits (default ${SEARCH_LIMIT}).`),
+			fields: z.array(z.string()).optional().describe(FIELDS_DESC)
+		}
+	}, async ({ query, limit, fields }) => json({ hits: await searchDocs(await doc0.collect(), query, {
+		limit: limit ?? SEARCH_LIMIT,
+		fields: parseFields(fields)
+	}) }));
+	server.registerTool("get_doc", {
+		title: "Get doc",
+		description: "Get one doc by id (full content and source by default). Its `related` field lists linked docs with their title and description — open those by id with get_doc, no separate call needed.",
+		inputSchema: {
+			id: z.string(),
+			fields: z.array(z.string()).optional().describe(FIELDS_DESC)
+		}
+	}, async ({ id, fields }) => {
+		const doc = getDoc(await doc0.collect(), id, parseFields(fields));
+		if (!doc) return {
+			content: [{
+				type: "text",
+				text: `No doc with id "${id}".`
+			}],
+			isError: true
+		};
+		return json(doc);
+	});
+	await server.connect(new StdioServerTransport());
+	return server;
+};
+//#endregion
+export { getDoc, listDocs, searchDocs, serveMcp };

package/dist/mcp/tools.d.ts

@@ -0,0 +1,39 @@
+import { Docs } from "../types.js";
+import { DocField, DocView } from "../select.js";
+
+//#region src/mcp/tools.d.ts
+type ListOptions = {
+  tag?: string;
+  category?: string;
+  fields?: DocField[]; /** Max docs to return; omit for all. Pair with `offset` to page a large project. */
+  limit?: number; /** Skip this many docs before the page (default 0). */
+  offset?: number;
+};
+type SearchToolOptions = {
+  limit?: number;
+  fields?: DocField[];
+};
+/** A page of listed docs plus the unpaged `total`, so a caller knows whether to fetch more. */
+type DocsPage = {
+  docs: DocView[];
+  total: number;
+  offset: number;
+  limit?: number;
+};
+/**
+ * Table of contents — optionally filtered by tag/category, with selectable fields and `limit`/`offset` paging. Returns
+ * the page plus `total` (the full filtered count) so callers can page through a large project without flooding
+ * context.
+ */
+declare const listDocs: (docs: Docs, options?: ListOptions) => DocsPage;
+/** Hybrid search; each hit carries the selected fields plus a content snippet. */
+declare const searchDocs: (docs: Docs, query: string, options?: SearchToolOptions) => Promise<(DocView & {
+  snippet: string;
+})[]>;
+/**
+ * One doc by id (all fields by default — `content` and `source` included), or undefined. The `related` field comes back
+ * enriched (each link carries the target's `title`/`description`), so a separate "get related" call isn't needed.
+ */
+declare const getDoc: (docs: Docs, id: string, fields?: DocField[]) => DocView | undefined;
+//#endregion
+export { DocsPage, ListOptions, SearchToolOptions, getDoc, listDocs, searchDocs };

package/dist/mcp/tools.js

@@ -0,0 +1,72 @@
+import { ALL_FIELDS, selectFields } from "../select.js";
+import { resolveRelated } from "../docs.js";
+//#region src/mcp/tools.ts
+/** Fields returned by default from `list_docs` — a compact summary plus `source`. */
+const SUMMARY_FIELDS = [
+	"id",
+	"title",
+	"description",
+	"tags",
+	"category",
+	"source"
+];
+/** Fields returned by default per `search_docs` hit (the snippet is added on top). */
+const HIT_FIELDS = [
+	"id",
+	"title",
+	"description",
+	"source"
+];
+const snippet = (content, max = 280) => {
+	const text = content.trim().replace(/\s+/g, " ");
+	return text.length > max ? `${text.slice(0, max).trimEnd()}…` : text;
+};
+/** Project a doc to the selected fields, upgrading `related` (when present) to enriched {@link RelatedRef}s. */
+const project = (docs, doc, fields) => {
+	const { related, ...rest } = selectFields(doc, fields);
+	return related ? {
+		...rest,
+		related: resolveRelated(docs, related)
+	} : rest;
+};
+/**
+* Table of contents — optionally filtered by tag/category, with selectable fields and `limit`/`offset` paging. Returns
+* the page plus `total` (the full filtered count) so callers can page through a large project without flooding
+* context.
+*/
+const listDocs = (docs, options = {}) => {
+	const { tag, category, fields = SUMMARY_FIELDS, limit, offset = 0 } = options;
+	let items = tag ? docs.byTag(tag) : docs.all();
+	if (category) items = items.filter((doc) => doc.category.includes(category));
+	const total = items.length;
+	const start = Math.max(0, offset);
+	const projected = (limit === void 0 ? items.slice(start) : items.slice(start, start + Math.max(0, limit))).map((doc) => project(docs, doc, fields));
+	return limit === void 0 ? {
+		docs: projected,
+		total,
+		offset: start
+	} : {
+		docs: projected,
+		total,
+		offset: start,
+		limit
+	};
+};
+/** Hybrid search; each hit carries the selected fields plus a content snippet. */
+const searchDocs = async (docs, query, options = {}) => {
+	const { limit, fields = HIT_FIELDS } = options;
+	return (await docs.search(query, { limit })).map((doc) => ({
+		...project(docs, doc, fields),
+		snippet: snippet(doc.content)
+	}));
+};
+/**
+* One doc by id (all fields by default — `content` and `source` included), or undefined. The `related` field comes back
+* enriched (each link carries the target's `title`/`description`), so a separate "get related" call isn't needed.
+*/
+const getDoc = (docs, id, fields = [...ALL_FIELDS]) => {
+	const doc = docs.get(id);
+	return doc ? project(docs, doc, fields) : void 0;
+};
+//#endregion
+export { getDoc, listDocs, searchDocs };

package/dist/normalize.d.ts

@@ -0,0 +1,21 @@
+import { Doc, DocRelated, DocSource } from "./types.js";
+
+//#region src/normalize.d.ts
+/** A doc as a parser produces it, before defaults are filled in. */
+type RawDoc = {
+  source: DocSource;
+  id?: string;
+  title?: string;
+  description?: string;
+  tags?: string[];
+  category?: string[];
+  related?: DocRelated[];
+  content: string;
+};
+/**
+ * Fill the conventional defaults: `id` from the file, `title` from the first heading, `description` from the first
+ * line, and merge `category` into `tags` (tags is always a superset of category).
+ */
+declare const buildDoc: (raw: RawDoc) => Doc;
+//#endregion
+export { RawDoc, buildDoc };

package/dist/normalize.js

@@ -0,0 +1,25 @@
+import { defaultIdFromFile, firstHeading, firstLine, humanize } from "./utils.js";
+//#region src/normalize.ts
+/**
+* Fill the conventional defaults: `id` from the file, `title` from the first heading, `description` from the first
+* line, and merge `category` into `tags` (tags is always a superset of category).
+*/
+const buildDoc = (raw) => {
+	const id = raw.id ?? defaultIdFromFile(raw.source.file);
+	const title = raw.title ?? firstHeading(raw.content) ?? humanize(id);
+	const description = raw.description ?? firstLine(raw.content) ?? "";
+	const category = raw.category ?? [];
+	const tags = [...new Set([...raw.tags ?? [], ...category])];
+	return {
+		source: raw.source,
+		id,
+		title,
+		description,
+		tags,
+		category,
+		related: raw.related ?? [],
+		content: raw.content
+	};
+};
+//#endregion
+export { buildDoc };

package/dist/parsers/code.d.ts

@@ -0,0 +1,7 @@
+import { Parser } from "../types.js";
+
+//#region src/parsers/code.d.ts
+/** Parses JSDoc in code (`.ts`, `.tsx`, `.js`, …); a block is a doc iff it has a doc0 directive. */
+declare const codeParser: Parser;
+//#endregion
+export { codeParser };