@devp0nt/doc0 0.0.0 → 0.1.0

package/dist/parsers/code.js

@@ -0,0 +1,73 @@
+import { asStringArray, defaultIdFromFile, parseRelated } from "../utils.js";
+import { buildDoc } from "../normalize.js";
+import { parse } from "comment-parser";
+//#region src/parsers/code.ts
+const DOC0_TAGS = new Set([
+	"id",
+	"title",
+	"description",
+	"tags",
+	"category",
+	"related",
+	"doc"
+]);
+/** Find the identifier declared on the first meaningful line after a comment block. */
+const nextSymbol = (lines, afterLine) => {
+	for (let i = afterLine + 1; i < lines.length; i++) {
+		const line = lines[i]?.trim() ?? "";
+		if (!line) continue;
+		const declared = line.match(/(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:const|let|var|function|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/);
+		const assigned = line.match(/^([A-Za-z_$][\w$]*)\s*[:=(]/);
+		return (declared ?? assigned)?.[1];
+	}
+};
+const parse$1 = ({ file, content }) => {
+	const blocks = parse(content, { spacing: "preserve" });
+	const lines = content.split("\n");
+	const docs = [];
+	for (const block of blocks) {
+		if (!block.tags.some((tag) => DOC0_TAGS.has(tag.tag))) continue;
+		const value = (name) => {
+			const tag = block.tags.find((candidate) => candidate.tag === name);
+			if (!tag) return;
+			const text = [tag.name, tag.description].filter(Boolean).join(" ").trim();
+			return text.length > 0 ? text : void 0;
+		};
+		const startLine = (block.source[0]?.number ?? 0) + 1;
+		const endLine = (block.source.at(-1)?.number ?? 0) + 1;
+		const body = block.description.trim();
+		docs.push(buildDoc({
+			source: {
+				file,
+				type: "jsdoc",
+				lineStart: startLine,
+				lineEnd: endLine
+			},
+			id: value("id") ?? nextSymbol(lines, endLine - 1) ?? defaultIdFromFile(file),
+			title: value("title"),
+			description: value("description"),
+			tags: asStringArray(value("tags")),
+			category: asStringArray(value("category")),
+			related: parseRelated(value("related")),
+			content: body
+		}));
+	}
+	return docs;
+};
+/** Parses JSDoc in code (`.ts`, `.tsx`, `.js`, …); a block is a doc iff it has a doc0 directive. */
+const codeParser = {
+	name: "code",
+	extensions: [
+		"ts",
+		"tsx",
+		"mts",
+		"cts",
+		"js",
+		"jsx",
+		"mjs",
+		"cjs"
+	],
+	parse: parse$1
+};
+//#endregion
+export { codeParser };

package/dist/parsers/index.d.ts

@@ -0,0 +1,11 @@
+import { Doc, Parser, ParserInput } from "../types.js";
+import { codeParser } from "./code.js";
+import { markdownParser } from "./markdown.js";
+
+//#region src/parsers/index.d.ts
+/** The parsers used when `Doc0.create` is given no `parsers`. */
+declare const defaultParsers: Parser[];
+/** Run the first parser that claims the file's extension. No match → no docs. */
+declare const parseFile: (input: ParserInput, parsers: Parser[]) => Doc[] | Promise<Doc[]>;
+//#endregion
+export { codeParser, defaultParsers, markdownParser, parseFile };

package/dist/parsers/index.js

@@ -0,0 +1,15 @@
+import { codeParser } from "./code.js";
+import { markdownParser } from "./markdown.js";
+import { extname } from "node:path";
+//#region src/parsers/index.ts
+/** The parsers used when `Doc0.create` is given no `parsers`. */
+const defaultParsers = [markdownParser, codeParser];
+/** Run the first parser that claims the file's extension. No match → no docs. */
+const parseFile = (input, parsers) => {
+	const ext = extname(input.file).slice(1).toLowerCase();
+	const parser = parsers.find((candidate) => candidate.extensions.includes(ext));
+	if (!parser) return [];
+	return parser.parse(input);
+};
+//#endregion
+export { codeParser, defaultParsers, markdownParser, parseFile };

package/dist/parsers/markdown.d.ts

@@ -0,0 +1,7 @@
+import { Parser } from "../types.js";
+
+//#region src/parsers/markdown.d.ts
+/** Parses Markdown (`.md`, `.mdx`, `.mdc`): frontmatter → fields, body → content. */
+declare const markdownParser: Parser;
+//#endregion
+export { markdownParser };

package/dist/parsers/markdown.js

@@ -0,0 +1,36 @@
+import { asString, asStringArray, parseRelated } from "../utils.js";
+import { buildDoc } from "../normalize.js";
+import matter from "gray-matter";
+//#region src/parsers/markdown.ts
+const parse = ({ file, content }) => {
+	const parsed = matter(content);
+	const data = parsed.data;
+	if (data.doc === false) return [];
+	return [buildDoc({
+		source: {
+			file,
+			type: "md",
+			lineStart: 1,
+			lineEnd: content.split("\n").length
+		},
+		id: asString(data.id),
+		title: asString(data.title),
+		description: asString(data.description),
+		tags: asStringArray(data.tags),
+		category: asStringArray(data.category),
+		related: parseRelated(data.related),
+		content: parsed.content.trim()
+	})];
+};
+/** Parses Markdown (`.md`, `.mdx`, `.mdc`): frontmatter → fields, body → content. */
+const markdownParser = {
+	name: "markdown",
+	extensions: [
+		"md",
+		"mdx",
+		"mdc"
+	],
+	parse
+};
+//#endregion
+export { markdownParser };

package/dist/search/embedder.d.ts

@@ -0,0 +1,12 @@
+//#region src/search/embedder.d.ts
+/** Small, fast sentence-embedding model: 384-dim, ~23MB, runs locally with no API key. */
+declare const EMBED_MODEL = "Xenova/all-MiniLM-L6-v2";
+declare const EMBED_DIM = 384;
+type Embed = (text: string) => Promise<number[]>;
+/**
+ * The default embedder. The model is downloaded once into the shared Hugging Face cache (`~/.cache/huggingface`) and
+ * reused across projects.
+ */
+declare const createEmbedder: (model?: string) => Embed;
+//#endregion
+export { EMBED_DIM, EMBED_MODEL, Embed, createEmbedder };

package/dist/search/embedder.js

@@ -0,0 +1,30 @@
+//#region src/search/embedder.ts
+/** Small, fast sentence-embedding model: 384-dim, ~23MB, runs locally with no API key. */
+const EMBED_MODEL = "Xenova/all-MiniLM-L6-v2";
+const EMBED_DIM = 384;
+const extractors = /* @__PURE__ */ new Map();
+const getExtractor = async (model) => {
+	let extractor = extractors.get(model);
+	if (!extractor) {
+		extractor = (await import("@huggingface/transformers").catch(() => {
+			throw new Error("doc0: semantic search needs the optional \"@huggingface/transformers\" package. Install it (e.g. `bun add -d @huggingface/transformers`), or use the default keyword search.");
+		})).pipeline("feature-extraction", model);
+		extractors.set(model, extractor);
+	}
+	return extractor;
+};
+/**
+* The default embedder. The model is downloaded once into the shared Hugging Face cache (`~/.cache/huggingface`) and
+* reused across projects.
+*/
+const createEmbedder = (model = EMBED_MODEL) => {
+	return async (text) => {
+		const output = await (await getExtractor(model))(text, {
+			pooling: "mean",
+			normalize: true
+		});
+		return Array.from(output.data, Number);
+	};
+};
+//#endregion
+export { EMBED_DIM, EMBED_MODEL, createEmbedder };

package/dist/search/index.d.ts

@@ -0,0 +1,23 @@
+import { Cache, SearchEngine } from "../types.js";
+import { EMBED_DIM, EMBED_MODEL, Embed, createEmbedder } from "./embedder.js";
+
+//#region src/search/index.d.ts
+type OramaSearchOptions = {
+  /**
+   * Turn on semantic (hybrid keyword + vector) search via local-model embeddings. Lazy-loads
+   * `@huggingface/transformers` on first use. Default `false` — keyword/BM25 only, zero extra install. Passing `embed`
+   * implies `true`.
+   */
+  embeddings?: boolean; /** Custom embedder (e.g. an API provider, or a stub in tests). Implies `embeddings: true`. */
+  embed?: Embed; /** Embedding model id (default `Xenova/all-MiniLM-L6-v2`). */
+  model?: string; /** Where to cache computed vectors (default `node_modules/.cache/doc0`). */
+  cache?: Cache;
+};
+/**
+ * An orama-backed search engine. Keyword/BM25 by default — this is the engine `doc0` uses out of the box. Set
+ * `embeddings: true` (or pass `embed`) to upgrade to hybrid keyword + semantic search with local-model vectors cached
+ * by content hash. Plug a custom config in via `Doc0.create({ search })`.
+ */
+declare const oramaSearch: (options?: OramaSearchOptions) => SearchEngine;
+//#endregion
+export { EMBED_DIM, EMBED_MODEL, type Embed, OramaSearchOptions, createEmbedder, oramaSearch };

package/dist/search/index.js

@@ -0,0 +1,80 @@
+import { fileCache, hash } from "../cache.js";
+import { EMBED_DIM, EMBED_MODEL, createEmbedder } from "./embedder.js";
+import { create, insertMultiple, search } from "@orama/orama";
+//#region src/search/index.ts
+const BASE_SCHEMA = {
+	docId: "string",
+	title: "string",
+	description: "string",
+	content: "string",
+	tags: "string[]"
+};
+/**
+* An orama-backed search engine. Keyword/BM25 by default — this is the engine `doc0` uses out of the box. Set
+* `embeddings: true` (or pass `embed`) to upgrade to hybrid keyword + semantic search with local-model vectors cached
+* by content hash. Plug a custom config in via `Doc0.create({ search })`.
+*/
+const oramaSearch = (options = {}) => {
+	const useEmbeddings = options.embeddings === true || options.embed !== void 0;
+	const model = options.model ?? "Xenova/all-MiniLM-L6-v2";
+	const cache = options.cache ?? fileCache();
+	const embed = useEmbeddings ? options.embed ?? createEmbedder(model) : void 0;
+	const embedCached = async (content) => {
+		const key = `embed:${model}:${hash(content)}`;
+		const cached = await cache.get(key);
+		if (cached) return cached;
+		const vector = await embed(content);
+		await cache.set(key, vector);
+		return vector;
+	};
+	const makeDb = () => create({ schema: useEmbeddings ? {
+		...BASE_SCHEMA,
+		embedding: "vector[384]"
+	} : BASE_SCHEMA });
+	let db;
+	const byId = /* @__PURE__ */ new Map();
+	return {
+		index: async (docs) => {
+			db = makeDb();
+			byId.clear();
+			const records = [];
+			for (const doc of docs) {
+				byId.set(doc.id, doc);
+				const record = {
+					docId: doc.id,
+					title: doc.title,
+					description: doc.description,
+					content: doc.content,
+					tags: doc.tags
+				};
+				if (useEmbeddings) record.embedding = await embedCached(`${doc.title}\n${doc.description}\n${doc.content}`);
+				records.push(record);
+			}
+			await insertMultiple(db, records);
+		},
+		search: async (query, searchOptions) => {
+			if (!db) return [];
+			const limit = searchOptions?.limit ?? 10;
+			const results = useEmbeddings && embed ? await search(db, {
+				mode: "hybrid",
+				term: query,
+				vector: {
+					value: await embed(query),
+					property: "embedding"
+				},
+				limit
+			}) : await search(db, {
+				term: query,
+				limit
+			});
+			const hits = [];
+			for (const hit of results.hits) {
+				const doc = byId.get(hit.document.docId);
+				if (doc) hits.push(doc);
+			}
+			return hits;
+		}
+	};
+};
+//#endregion
+export { EMBED_DIM, EMBED_MODEL, createEmbedder, oramaSearch };

package/dist/select.d.ts

@@ -0,0 +1,19 @@
+import { Doc, RelatedRef } from "./types.js";
+
+//#region src/select.d.ts
+/** A selectable field on a {@link Doc}. `source` carries the file path + line span. */
+type DocField = 'id' | 'title' | 'description' | 'tags' | 'category' | 'related' | 'content' | 'source';
+/**
+ * A projected doc for output (MCP/CLI/web): a subset of {@link Doc} fields, with `related` upgraded from stored links to
+ * enriched {@link RelatedRef}s (target title/description resolved). This is what the tool helpers return.
+ */
+type DocView = Omit<Partial<Doc>, 'related'> & {
+  related?: RelatedRef[];
+};
+declare const ALL_FIELDS: readonly DocField[];
+/** Pick a subset of a doc's fields — keeps MCP/CLI responses lean and lets callers ask for `source`. */
+declare const selectFields: (doc: Doc, fields: readonly DocField[]) => Partial<Doc>;
+/** Parse a comma list / array of field names, keeping only valid {@link DocField}s (else undefined). */
+declare const parseFields: (input?: string | readonly string[]) => DocField[] | undefined;
+//#endregion
+export { ALL_FIELDS, DocField, DocView, parseFields, selectFields };

package/dist/select.js

@@ -0,0 +1,25 @@
+//#region src/select.ts
+const ALL_FIELDS = [
+	"id",
+	"title",
+	"description",
+	"tags",
+	"category",
+	"related",
+	"content",
+	"source"
+];
+/** Pick a subset of a doc's fields — keeps MCP/CLI responses lean and lets callers ask for `source`. */
+const selectFields = (doc, fields) => {
+	const result = {};
+	for (const field of fields) result[field] = doc[field];
+	return result;
+};
+/** Parse a comma list / array of field names, keeping only valid {@link DocField}s (else undefined). */
+const parseFields = (input) => {
+	if (!input) return;
+	const valid = (Array.isArray(input) ? input : String(input).split(",")).map((name) => name.trim()).filter((name) => ALL_FIELDS.includes(name));
+	return valid.length > 0 ? valid : void 0;
+};
+//#endregion
+export { ALL_FIELDS, parseFields, selectFields };

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/types.d.ts
+/** Which parser produced the doc — by parser kind, not file extension. `md` covers .md/.mdx/.mdc. */
+type DocSourceType = 'md' | 'jsdoc';
+/** Where a parsed doc lives — file, the parser that produced it, and line span. */
+type DocSource = {
+  file: string;
+  type: DocSourceType;
+  lineStart: number;
+  lineEnd: number;
+};
+/**
+ * A normalized link to another doc, as stored on a {@link Doc}. Authored loosely — a bare id, an `id!` shorthand for
+ * must-read, or an object — and always normalized to this object form at parse time (the trailing `!` becomes
+ * `required: true`). So `related` is never a raw string on a collected doc.
+ *
+ * @example
+ *   '@related entity-payloads' // → { id: 'entity-payloads' }
+ *   '@related entity-payloads!' // → { id: 'entity-payloads', required: true }
+ *   { id: 'postgres', reason: 'shares the schema' } // kept as-is
+ */
+type DocRelated = {
+  id: string;
+  reason?: string;
+  required?: boolean;
+};
+/**
+ * A {@link DocRelated} link enriched for output: the link's own `reason`/`required` plus the target doc's `title` and
+ * `description`, resolved at output time (not stored on the link) so a reader can tell what's behind the link before
+ * fetching it. This is the shape of a doc's `related` field on output and what the web "Related" section renders.
+ */
+type RelatedRef = DocRelated & {
+  title: string;
+  description: string;
+};
+/**
+ * One normalized doc — the unit doc0 collects, links, and serves. `TExtra` carries any custom fields a
+ * `transform`/`schema` adds.
+ */
+type Doc<TExtra = unknown> = {
+  source: DocSource; /** Explicit, else the symbol name / file basename / dir name. */
+  id: string; /** Explicit, else the first heading, else a humanized `id`. */
+  title: string; /** Explicit, else the first content line. */
+  description: string; /** The most-used directive; a superset of `category`. */
+  tags: string[]; /** The grouping tag(s) — drive generated folder structure. */
+  category: string[];
+  related: DocRelated[]; /** The doc body, with frontmatter / JSDoc directives stripped. */
+  content: string;
+} & TExtra;
+/** A file to write — `generate`/`finalGenerate` return these. */
+type Output = {
+  path: string;
+  content: string;
+};
+type OneOrMany<T> = T | T[];
+/**
+ * Shared cache: `collect()` stores parse results here, extensions store derived data (e.g. embeddings). Keys are
+ * content-addressed by the caller.
+ */
+type Cache = {
+  get: <T>(key: string) => Promise<T | undefined>;
+  set: <T>(key: string, value: T) => Promise<void>;
+};
+/** What a parser receives for one matched file. */
+type ParserInput = {
+  file: string;
+  content: string;
+};
+/**
+ * A doc-carrier parser: claims file extensions and turns one file into zero or more docs (a source can split into
+ * several via the parser or `transform`).
+ */
+type Parser = {
+  name: string;
+  extensions: string[];
+  parse: (input: ParserInput) => Doc[] | Promise<Doc[]>;
+};
+type SearchOptions = {
+  limit?: number;
+};
+/**
+ * A pluggable search engine. By default `Doc0` uses orama keyword/BM25 (`oramaSearch()`, loaded lazily); pass
+ * `oramaSearch({ embeddings: true })` for hybrid keyword + semantic search, or any engine implementing this shape.
+ */
+type SearchEngine = {
+  index: (docs: readonly Doc[]) => void | Promise<void>;
+  search: (query: string, options?: SearchOptions) => Doc[] | Promise<Doc[]>;
+};
+/** The queryable collection returned by `doc0.collect()`. */
+type Docs<TExtra = unknown> = {
+  all: () => Doc<TExtra>[];
+  get: (id: string) => Doc<TExtra> | undefined;
+  search: (query: string, options?: SearchOptions) => Promise<Doc<TExtra>[]>;
+  /**
+   * Graph neighbours via `@related` as enriched links (id + reason/required + target title/description); must-read
+   * first.
+   */
+  related: (id: string, options?: {
+    required?: boolean;
+  }) => RelatedRef[];
+  byTag: (tag: string) => Doc<TExtra>[];
+  byCategory: (category: string) => Doc<TExtra>[];
+  toJSON: () => string;
+};
+/**
+ * Config for `Doc0.create`. `TExtra` is the shape of any custom fields your `transform`/`schema` adds to each `Doc`.
+ */
+type Doc0Options<TExtra = unknown> = {
+  /** Include + `!`-exclude globs. For md/mdx/mdc this is the inclusion gate. */glob: string[]; /** Defaults to the built-in markdown + code parsers. */
+  parsers?: Parser[]; /** Validate and type each doc after transform. */
+  schema?: StandardSchemaV1<unknown, Doc<TExtra>>; /** One source doc → one or many output docs. */
+  transform?: (doc: Doc) => Doc<TExtra> | Doc<TExtra>[]; /** Map a category id to a human-readable title. */
+  category?: Record<string, string>; /** Pluggable search engine; default is orama keyword/BM25. Use `oramaSearch({ embeddings: true })` for semantic. */
+  search?: SearchEngine; /** Run for each doc after collect. */
+  callback?: OneOrMany<(doc: Doc<TExtra>) => void | Promise<void>>; /** Per-doc output; written only when the content differs (idempotent). */
+  generate?: (doc: Doc<TExtra>) => Output | undefined; /** Whole-collection output. */
+  finalGenerate?: (docs: Docs<TExtra>) => OneOrMany<Output>; /** Run once over the whole collection after collect. */
+  finalCallback?: (docs: Docs<TExtra>) => void | Promise<void>;
+  /**
+   * `true` → `node_modules/.cache/doc0` (default), a path to a cache dir, a custom backend, or `false` to disable.
+   */
+  cache?: boolean | string | Cache; /** Bypass scanning — feed docs directly. */
+  data?: Doc<TExtra>[];
+};
+/**
+ * The engine: parse config + actions. Created with `Doc0.create(options)`; the implementing class is named `Doc0`.
+ */
+type Doc0Instance<TExtra = unknown> = {
+  readonly options: Doc0Options<TExtra>;
+  readonly cache: Cache; /** Scan + parse + build the graph. Self-revalidating by mtime, so always fresh; cache-backed. */
+  collect: () => Promise<Docs<TExtra>>; /** collect + run callbacks + write generate/finalGenerate outputs (diff-only). */
+  sync: () => Promise<void>;
+  /**
+   * Watch the globs and call `onChange` (debounced) on change — for push reactions like regenerating. Idempotent: at
+   * most one watcher per `Doc0`. Returns a stop function.
+   */
+  watch: (onChange: () => void | Promise<void>) => () => void;
+};
+/** A `Doc0` instance, or a path to a module that exports one (`doc0` or default). */
+type Doc0Source<TExtra = unknown> = Doc0Instance<TExtra> | string;
+/** Options for `serveWeb` (`@devp0nt/doc0/web`). The served data stays fresh via `collect()`. */
+type ServeWebOptions = {
+  port?: number;
+};
+//#endregion
+export { Cache, Doc, Doc0Instance, Doc0Options, Doc0Source, DocRelated, DocSource, DocSourceType, Docs, OneOrMany, Output, Parser, ParserInput, RelatedRef, SearchEngine, SearchOptions, ServeWebOptions };

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,27 @@
+import { DocRelated } from "./types.js";
+
+//#region src/utils.d.ts
+/** Wrap a single value or an array into an array. */
+declare const toArray: <T>(value: T | T[]) => T[];
+/** Coerce an unknown frontmatter value to a trimmed string, or undefined. */
+declare const asString: (value: unknown) => string | undefined;
+/** Coerce an unknown value to a string array — accepts a string, a comma list, or an array. */
+declare const asStringArray: (value: unknown) => string[];
+/** Humanize an id/slug to Title Case: `entity-payloads` → `Entity Payloads`. */
+declare const humanize: (id: string) => string;
+/** Default id from a file path: the basename without extension, or the dir name for index/README. */
+declare const defaultIdFromFile: (file: string) => string;
+/** The first Markdown heading's text, if any. */
+declare const firstHeading: (content: string) => string | undefined;
+/** Drop a leading top-level heading — callers that render the `title` separately would otherwise duplicate it. */
+declare const stripLeadingHeading: (content: string) => string;
+/** The first non-empty, non-heading line, trimmed. */
+declare const firstLine: (content: string) => string | undefined;
+/**
+ * Parse a frontmatter/JSDoc `related` value into normalized {@link DocRelated} links. Always returns the object form:
+ * the `id!` string shorthand becomes `{ id, required: true }`, and object entries are cleaned (trimmed `id`, optional
+ * `reason`/`required`). Unknown/empty entries are dropped.
+ */
+declare const parseRelated: (value: unknown) => DocRelated[];
+//#endregion
+export { asString, asStringArray, defaultIdFromFile, firstHeading, firstLine, humanize, parseRelated, stripLeadingHeading, toArray };

package/dist/utils.js

@@ -0,0 +1,74 @@
+//#region src/utils.ts
+/** Wrap a single value or an array into an array. */
+const toArray = (value) => Array.isArray(value) ? value : [value];
+/** Coerce an unknown frontmatter value to a trimmed string, or undefined. */
+const asString = (value) => {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : void 0;
+	}
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+};
+/** Coerce an unknown value to a string array — accepts a string, a comma list, or an array. */
+const asStringArray = (value) => {
+	if (Array.isArray(value)) return value.flatMap(asStringArray);
+	const str = asString(value);
+	if (!str) return [];
+	return str.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+};
+/** Humanize an id/slug to Title Case: `entity-payloads` → `Entity Payloads`. */
+const humanize = (id) => id.replace(/[-_]+/g, " ").replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim().replace(/\b\w/g, (char) => char.toUpperCase());
+/** Default id from a file path: the basename without extension, or the dir name for index/README. */
+const defaultIdFromFile = (file) => {
+	const parts = file.split("/");
+	const name = (parts.at(-1) ?? file).replace(/\.[^.]+$/, "");
+	const lower = name.toLowerCase();
+	if (lower === "index" || lower === "readme") return parts.at(-2) ?? name;
+	return name;
+};
+/** The first Markdown heading's text, if any. */
+const firstHeading = (content) => {
+	return content.match(/^#{1,6}\s+(.+)$/m)?.[1]?.trim();
+};
+/** Drop a leading top-level heading — callers that render the `title` separately would otherwise duplicate it. */
+const stripLeadingHeading = (content) => content.replace(/^\s*#{1,6}[^\n]*\n+/, "");
+/** The first non-empty, non-heading line, trimmed. */
+const firstLine = (content) => {
+	for (const raw of content.split("\n")) {
+		const line = raw.trim();
+		if (line.length > 0 && !line.startsWith("#")) return line;
+	}
+};
+/**
+* Parse a frontmatter/JSDoc `related` value into normalized {@link DocRelated} links. Always returns the object form:
+* the `id!` string shorthand becomes `{ id, required: true }`, and object entries are cleaned (trimmed `id`, optional
+* `reason`/`required`). Unknown/empty entries are dropped.
+*/
+const parseRelated = (value) => {
+	if (value === null || value === void 0) return [];
+	return (Array.isArray(value) ? value : asStringArray(value)).flatMap((item) => {
+		if (typeof item === "string") {
+			const trimmed = item.trim();
+			const required = trimmed.endsWith("!");
+			const id = (required ? trimmed.slice(0, -1) : trimmed).trim();
+			if (!id) return [];
+			return [required ? {
+				id,
+				required: true
+			} : { id }];
+		}
+		if (typeof item === "object" && item !== null && "id" in item) {
+			const source = item;
+			const id = asString(source.id);
+			if (!id) return [];
+			const link = { id };
+			const reason = asString(source.reason);
+			if (reason) link.reason = reason;
+			if (source.required === true) link.required = true;
+			return [link];
+		}
+		return [];
+	});
+};
+//#endregion
+export { asString, asStringArray, defaultIdFromFile, firstHeading, firstLine, humanize, parseRelated, stripLeadingHeading, toArray };