@waveso/docs 0.4.0 → 0.6.0

package/dist/render.js

@@ -1,13 +1,16 @@
+import { collectAnchorIds, splitAnchor } from "./anchors.js";
 import { docsError } from "./docs-error.js";
 import { DEFAULT_DOCS_THEMES, createDocsHighlighter } from "./highlighter.js";
+import { describeSuggestion } from "./link-suggestion.js";
 import { rehypeCaptureToc } from "./plugins/rehype-capture-toc.js";
 import { rehypeCodeFrame } from "./plugins/rehype-code-frame.js";
 import { rehypeNormalizeCodeLanguage, rehypeRestoreExcludedCode } from "./plugins/rehype-code-language.js";
 import { rehypeFallbackHeadingIds } from "./plugins/rehype-fallback-heading-ids.js";
 import { rehypeFlattenRoots } from "./plugins/rehype-flatten-roots.js";
-import { foldSegments, remarkDocLinks, resolveMarkdownLink } from "./plugins/remark-doc-links.js";
+import { foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref } from "./plugins/remark-doc-links.js";
 import { remarkUnwrapImages } from "./plugins/remark-unwrap-images.js";
 import { remarkYouTube } from "./plugins/remark-youtube.js";
+import { visit } from "unist-util-visit";
 import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
 import { rehypeGithubAlerts } from "rehype-github-alerts";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
@@ -16,7 +19,6 @@ import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { unified } from "unified";
-import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
 //#region src/render.ts
 /**
@@ -96,11 +98,43 @@ function assertResolvedImage(value, src, relativePath) {
 * author means by `![](./diagram.png)` and what the link path has always done.
 */
 function foldImageSrc(src, dirSegments) {
-	if (isPublicImageSrc(src)) return src;
-	const segments = foldSegments(dirSegments, src);
-	return segments === void 0 ? void 0 : segments.join("/");
+	if (isPublicImageSrc(src)) return {
+		path: src,
+		suffix: ""
+	};
+	const { path, query, hash } = splitHref(src);
+	if (path === "") return;
+	const segments = foldSegments(dirSegments, path);
+	return segments === void 0 ? void 0 : {
+		path: segments.join("/"),
+		suffix: `${query}${hash}`
+	};
+}
+/**
+* Put the authored `?query#hash` back, unless the resolver wrote its own.
+*
+* A resolver returning `/img/diagram.a1b2c3.png?w=800` has said something more
+* specific than the author's `?v=2` — and concatenating the two would produce
+* two `?` in one URL, which is not a URL. Same rule the rest of this package
+* uses when a host and a default disagree: the more specific one wins.
+*/
+function withSuffix(src, suffix) {
+	if (suffix === "" || /[?#]/.test(src)) return src;
+	return `${src}${suffix}`;
 }
 /** Route without its `?query` / `#anchor`, for existence checks. */
+/**
+* Does this route belong to the host application rather than the docs?
+*
+* Prefix match on a segment boundary, so `/api` covers `/api/keys` and does not
+* accidentally cover `/apiary`.
+*/
+function isExternalRoute(route, external) {
+	return external.some((prefix) => {
+		const trimmed = prefix.replace(/\/+$/, "");
+		return route === trimmed || route.startsWith(`${trimmed}/`);
+	});
+}
 function toRouteKey(href) {
 	const cut = href.search(/[?#]/);
 	return cut === -1 ? href : href.slice(0, cut);
@@ -238,7 +272,7 @@ async function buildProcessor(options, themes, highlighterPromise) {
 			ariaHidden: "true",
 			tabIndex: -1
 		}
-	}).use(options.rehypePlugins ?? []).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeCodeFrame).use(rehypeShikiFromHighlighter, highlighter, {
+	}).use(options.rehypePlugins ?? []).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeCodeFrame, options.codeLabels ?? {}).use(rehypeShikiFromHighlighter, highlighter, {
 		themes,
 		defaultColor: false,
 		fallbackLanguage: "text",
@@ -294,7 +328,13 @@ function createDocsRenderer(options) {
 		await Promise.all(images.map(async (node) => {
 			const src = node.properties.src;
 			if (typeof src !== "string" || src === "") return;
-			const folded = foldImageSrc(src, context.dirSegments);
+			let folded;
+			try {
+				folded = foldImageSrc(src, context.dirSegments);
+			} catch (error) {
+				if (!(error instanceof URIError)) throw error;
+				throw docsError("invalid-image", `@waveso/docs: image "${src}" in ${file.relativePath} is not valid percent-encoding. Write %25 for a literal percent sign, or name the file as it is on disk.`, { cause: error });
+			}
 			if (folded === void 0) throw docsError("invalid-image", `@waveso/docs: image "${src}" in ${file.relativePath} climbs above the content root.`);
 			if (resolve === void 0) {
 				if (isPublicImageSrc(src)) return;
@@ -302,42 +342,87 @@ function createDocsRenderer(options) {
 			}
 			let resolved;
 			try {
-				resolved = await resolve(folded, context);
+				resolved = await resolve(folded.path, context);
 			} catch (error) {
 				throw docsError("invalid-image", `@waveso/docs: the imageResolver threw on image "${src}" in ${file.relativePath}.`, { cause: error });
 			}
 			if (resolved === void 0) {
-				node.properties.src = folded;
-				return;
+				if (isPublicImageSrc(src)) return;
+				throw docsError("invalid-image", `@waveso/docs: the imageResolver returned nothing for image "${src}" in ${file.relativePath}, which is relative to the markdown file — so nothing can serve it: the browser would resolve it against the page route, and the same markdown would request a different file from every page. Return a src for it, or move the image under \`public/\` and write an absolute one such as "/diagram.png".`);
 			}
 			assertResolvedImage(resolved, src, file.relativePath);
-			node.properties.src = resolved.src;
+			node.properties.src = withSuffix(resolved.src, folded.suffix);
 			if (resolved.width !== void 0) node.properties.width = resolved.width;
 			if (resolved.height !== void 0) node.properties.height = resolved.height;
 		}));
 	}
 	/**
-	* Fail the build on a link that would have 404'd.
+	* Act on a link problem at the severity the site chose.
+	*
+	* ⚠️ `'throw'` IS THE DEFAULT AND SHOULD STAY IT. The link was valid in the
+	* editor and on GitHub, so a warning in a build log is a warning nobody
+	* reads. The setting exists because a migration may knowingly run against an
+	* incomplete corpus for a while and the tool cannot know that — which is the
+	* same reason Docusaurus has one.
+	*/
+	function report(severity, code, message) {
+		if (severity === "ignore") return;
+		if (severity === "throw") throw docsError(code, message);
+		console.warn(docsError(code, message).message);
+	}
+	/**
+	* Anchors that point into the page being rendered.
 	*
-	* Deliberately a throw and not a warning: the link was valid in the editor
-	* and on GitHub, so a warning in a build log is a warning nobody reads.
+	* ⚠️ HERE, NOT IN THE CORPUS PASS, BECAUSE THIS IS WHERE THE LINE NUMBER IS.
+	* The recorded refs carry the source line and the tree still has its
+	* positions; both are gone from a returned `RenderedDoc`. A same-page anchor
+	* is also the one a writer produces most — every "see below" — so it is worth
+	* the better message.
+	*
+	* Cross-page anchors need the other page's ids and are checked by
+	* `renderAll`, which is the first point at which they exist.
 	*/
+	function assertOwnAnchors(file, tree, refs) {
+		if (config.onBrokenAnchors === "ignore") return;
+		let ids;
+		for (const ref of refs) {
+			const anchor = splitAnchor(ref.href ?? ref.raw);
+			if (anchor === void 0) continue;
+			if (anchor.route !== "" && anchor.route !== file.href) continue;
+			ids ??= collectAnchorIds(tree);
+			if (ids.has(anchor.fragment)) continue;
+			report(config.onBrokenAnchors, "broken-anchor", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', and this page has no '#${anchor.fragment}'.${describeSuggestion(anchor.fragment, ids)} Heading ids come from the heading text, so renaming a heading renames its anchor.`);
+		}
+	}
+	/** Check every link a page recorded, and act at the configured severity. */
 	function assertLinks(file, refs) {
 		for (const ref of refs) {
-			if (ref.href === void 0) throw docsError("broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which does not resolve to a documentation page. Use a path relative to this file, or an absolute URL for external links.`);
-			if (knownRoutes === void 0 || ref.asset) continue;
+			if (ref.anchorOnly) continue;
+			if (ref.href === void 0) {
+				report(config.onBrokenLinks, "broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which does not resolve to a documentation page. Use a path relative to this file, or an absolute URL for external links.`);
+				continue;
+			}
+			if (knownRoutes === void 0 || ref.asset || ref.anchorOnly) continue;
 			const route = toRouteKey(ref.href);
+			if (isExternalRoute(route, config.externalRoutes)) continue;
 			if (knownRoutes.has(route)) continue;
-			if (draftRoutes?.has(route)) throw docsError("draft-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — a page marked \`draft: true\`, so it is not published and the link would 404. Publish the page, remove the link, or build with \`includeDrafts\`.`);
+			if (draftRoutes?.has(route)) {
+				report(config.onBrokenLinks, "draft-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — a page marked \`draft: true\`, so it is not published and the link would 404. Publish the page, remove the link, or build with \`includeDrafts\`.`);
+				continue;
+			}
 			const aliasTarget = aliasRoutes?.get(route);
-			if (aliasTarget !== void 0) throw docsError("alias-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — an alias that redirects to '${aliasTarget}'. An alias is not a page: it 404s unless \`createDocsRedirects\` is wired into \`next.config.ts\`, and it is never prerendered. Link to '${aliasTarget}' directly.`);
-			throw docsError("broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — no such page exists. Fix the link, or add an \`aliases\` entry to the page it used to point at.`);
+			if (aliasTarget !== void 0) {
+				report(config.onBrokenLinks, "alias-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — an alias that redirects to '${aliasTarget}'. An alias is not a page: it 404s unless \`createDocsRedirects\` is wired into \`next.config.ts\`, and it is never prerendered. Link to '${aliasTarget}' directly.`);
+				continue;
+			}
+			report(config.onBrokenLinks, "broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — no such page exists.${describeSuggestion(route, knownRoutes)} Fix the link, or add an \`aliases\` entry to the page it used to point at.`);
 		}
 	}
 	return { async render(file) {
 		const processor = await processorPromise;
+		const lead = "\n".repeat(file.frontmatterLines ?? 0);
 		const vfile = new VFile({
-			value: file.content,
+			value: lead + file.content,
 			path: file.filePath
 		});
 		vfile.data.docLinkContext = {
@@ -348,7 +433,8 @@ function createDocsRenderer(options) {
 		const hast = await processor.run(processor.parse(vfile), vfile);
 		if (titleHeading && !hasHeadingOne(hast)) hast.children.unshift(titleHeadingNode(file.frontmatter.title));
 		await resolveImages(hast, file, imageResolver);
-		if (config.assertLinks) assertLinks(file, vfile.data.docLinks ?? []);
+		assertLinks(file, vfile.data.docLinks ?? []);
+		assertOwnAnchors(file, hast, vfile.data.docLinks ?? []);
 		return {
 			frontmatter: file.frontmatter,
 			hast: stripPositions(hast),

package/dist/route-path.js

@@ -1,5 +1,5 @@
 import { docsError } from "./docs-error.js";
-import { foldSegments } from "./plugins/remark-doc-links.js";
+import { decodePath, foldSegments } from "./plugins/remark-doc-links.js";
 //#region src/route-path.ts
 /**
 * Turning route segments into a URL path.
@@ -39,7 +39,12 @@ const ALIAS_PATTERN_CHARS = /[:()+*?{}]/;
 * every rejection below names the markdown file at the moment it is read.
 */
 function toAliasRoute(alias, basePath, sourceLabel) {
-	const trimmed = alias.trim();
+	let trimmed;
+	try {
+		trimmed = decodePath(alias.trim(), alias);
+	} catch (error) {
+		throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} is not valid percent-encoding. Write %25 for a literal percent sign, or write the former URL as its readable form.`, { cause: error });
+	}
 	if (trimmed.split("/").some((part) => part === "." || part === "..")) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} has a '.' or '..' segment. An alias is a former URL relative to the docs base path, not a path on disk: write \`aliases: [legacy/old-name]\`.`);
 	const pattern = ALIAS_PATTERN_CHARS.exec(trimmed);
 	if (pattern !== null) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} contains '${pattern[0]}', which Next compiles as redirect pattern syntax rather than as part of the URL — the redirect then swallows every page whose route the pattern happens to match, or fails the build. Remove the character; an alias is a literal former URL.`);

package/dist/safe-href.d.ts

@@ -0,0 +1,47 @@
+//#region src/safe-href.d.ts
+/**
+ * The one allowlist of schemes this package will put in an `href`.
+ *
+ * Private — deliberately not an entry point.
+ *
+ * ⚠️ IT WAS THE MARKDOWN PATH'S ALONE, AND `meta.json` WENT ROUND IT. A hand
+ * written nav entry — `{ "title": "Status", "href": "javascript:…" }` — reached
+ * `<a href>` through `DocsSidebar` with nothing checking it, while the markdown
+ * beside it was filtered by a comment calling the check load-bearing. Both paths
+ * end at the same anchor, so both need the same rule, and a rule with two copies
+ * is a rule with one that is out of date.
+ *
+ * Node-safe and browser-safe: two regular expressions and two functions, no
+ * imports at all.
+ */
+/**
+ * Strip the characters a browser ignores inside a URL.
+ *
+ * `java\nscript:` and `java&#09;script:` are `javascript:` to a parser and not
+ * to a naive regular expression, so the test has to run on the string the
+ * browser will see rather than on the one that was written.
+ */
+declare function normaliseUrl(href: string): string;
+/**
+ * Would this href navigate somewhere we are willing to send a reader?
+ *
+ * Nothing upstream filters it on the markdown side: `remarkDocLinks` skips every
+ * href with a scheme, so `assertLinks` never sees one either, and `remarkRehype`
+ * runs with `allowDangerousHtml` off but passes a link's own url through
+ * untouched. Verified against React 19: it neutralises `javascript:` in every
+ * obfuscated form, silently — but it lets `vbscript:` and
+ * `data:text/html;base64,…` reach the DOM verbatim. So the allowlist is ours.
+ */
+declare function isSafeHref(href: string): boolean;
+/**
+ * Does following this href leave the site in a new tab?
+ *
+ * ⚠️ NOT "HAS A SCHEME". `meta.json` used that test, so a `mailto:` sidebar
+ * entry was given `target="_blank"` and announced as "(opens in a new tab)" — a
+ * tab that never opens, described to precisely the reader who cannot see that it
+ * did not. Only http(s) and protocol-relative navigate; `mailto:` and `tel:`
+ * hand off to the OS and leave the page where it is.
+ */
+declare function opensInNewTab(href: string): boolean;
+//#endregion
+export { isSafeHref, normaliseUrl, opensInNewTab };

package/dist/safe-href.js

@@ -0,0 +1,73 @@
+//#region src/safe-href.ts
+/**
+* The one allowlist of schemes this package will put in an `href`.
+*
+* Private — deliberately not an entry point.
+*
+* ⚠️ IT WAS THE MARKDOWN PATH'S ALONE, AND `meta.json` WENT ROUND IT. A hand
+* written nav entry — `{ "title": "Status", "href": "javascript:…" }` — reached
+* `<a href>` through `DocsSidebar` with nothing checking it, while the markdown
+* beside it was filtered by a comment calling the check load-bearing. Both paths
+* end at the same anchor, so both need the same rule, and a rule with two copies
+* is a rule with one that is out of date.
+*
+* Node-safe and browser-safe: two regular expressions and two functions, no
+* imports at all.
+*/
+/**
+* Any URL with a scheme, or protocol-relative.
+*/
+const ABSOLUTE_URL = /^([a-z][a-z0-9+.-]*:|\/\/)/i;
+/**
+* The schemes a link may carry.
+*
+* GitHub's own allowlist, which is the bar to match: documentation links to
+* `sms:`, `ftp:` and `irc:` are ordinary, and an allowlist of three silently
+* deleted them. The point of the check is to stop `javascript:`, `data:` and
+* `vbscript:` reaching an `href`, not to have an opinion about protocols.
+*
+* A scheme not listed here — `vscode:`, `obsidian:`, `slack:` — is refused
+* rather than rendered. That is deliberate: an allowlist that grows on request
+* is safe, one that guesses is not.
+*/
+const SAFE_SCHEME = /^(https?|mailto|tel|sms|ftp|ftps|irc|ircs|xmpp|news|nntp|feed|git|matrix):/i;
+/**
+* Strip the characters a browser ignores inside a URL.
+*
+* `java\nscript:` and `java&#09;script:` are `javascript:` to a parser and not
+* to a naive regular expression, so the test has to run on the string the
+* browser will see rather than on the one that was written.
+*/
+function normaliseUrl(href) {
+	return [...href].filter((char) => (char.codePointAt(0) ?? 0) > 32).join("");
+}
+/**
+* Would this href navigate somewhere we are willing to send a reader?
+*
+* Nothing upstream filters it on the markdown side: `remarkDocLinks` skips every
+* href with a scheme, so `assertLinks` never sees one either, and `remarkRehype`
+* runs with `allowDangerousHtml` off but passes a link's own url through
+* untouched. Verified against React 19: it neutralises `javascript:` in every
+* obfuscated form, silently — but it lets `vbscript:` and
+* `data:text/html;base64,…` reach the DOM verbatim. So the allowlist is ours.
+*/
+function isSafeHref(href) {
+	const normalised = normaliseUrl(href);
+	if (!ABSOLUTE_URL.test(normalised)) return true;
+	return normalised.startsWith("//") || SAFE_SCHEME.test(normalised);
+}
+/**
+* Does following this href leave the site in a new tab?
+*
+* ⚠️ NOT "HAS A SCHEME". `meta.json` used that test, so a `mailto:` sidebar
+* entry was given `target="_blank"` and announced as "(opens in a new tab)" — a
+* tab that never opens, described to precisely the reader who cannot see that it
+* did not. Only http(s) and protocol-relative navigate; `mailto:` and `tel:`
+* hand off to the OS and leave the page where it is.
+*/
+function opensInNewTab(href) {
+	const normalised = normaliseUrl(href);
+	return /^https?:\/\//i.test(normalised) || normalised.startsWith("//");
+}
+//#endregion
+export { isSafeHref, normaliseUrl, opensInNewTab };

package/dist/search-index.js

@@ -1,5 +1,5 @@
-import { isFootnotes, isTransparentContainer } from "./section-boundary.js";
 import { mergeSearchOptions } from "./search-options.js";
+import { isFootnotes, isTransparentContainer } from "./section-boundary.js";
 import MiniSearch from "minisearch";
 //#region src/search-index.ts
 /** `<h1>`…`<h6>` to their numeric depth. */

package/dist/search-options.d.ts

@@ -1,5 +1,5 @@
 import { SearchRecord } from "./types.js";
-import { Options } from "minisearch";
+import { Options, SearchOptions } from "minisearch";
 //#region src/search-options.d.ts
 /**
  * Split text into index terms.
@@ -45,5 +45,67 @@ declare const SEARCH_INDEX_OPTIONS: Options<SearchRecord>;
  * OR. Nothing below that merges: a `boost` override replaces the whole map.
  */
 declare function mergeSearchOptions(overrides?: Partial<Options<SearchRecord>>): Options<SearchRecord>;
+/**
+ * {@link SearchOptions} with every function-valued member removed.
+ *
+ * `prefix` and `fuzzy` survive as the boolean and the number they usually are;
+ * their function overloads do not, because a predicate cannot be serialised.
+ */
+type SerializableSearchQueryOptions = Omit<SearchOptions, 'filter' | 'boostTerm' | 'boostDocument' | 'tokenize' | 'processTerm' | 'prefix' | 'fuzzy'> & {
+  prefix?: boolean;
+  fuzzy?: boolean | number;
+};
+/**
+ * MiniSearch overrides that can be handed from a Server Component to a Client
+ * Component — which is to say, the ones with no functions in them.
+ *
+ * React serialises a Client Component's props, and a function is not
+ * serialisable: `docs.Layout` forwarding `{ processTerm }` into `DocsSearch`
+ * fails `next build` outright with *"Functions cannot be passed directly to
+ * Client Components"*. This type is what stops that being expressible.
+ *
+ * ⚠️ THE OMIT LIST IS NOT THE GUARANTEE — {@link findFunctionValuedOptions} IS.
+ * MiniSearch is free to add a function-valued option in a minor, and the day it
+ * does this list is quietly incomplete while still compiling. The runtime walk
+ * has no such failure mode: it finds a function wherever it is, including in
+ * options this package has never heard of. The type is here to fail earlier and
+ * more legibly, not to be the last line of defence.
+ *
+ * The escape hatch for real function tuning is a client boundary of the host's
+ * own, which is the only place the two halves can share a module reference:
+ *
+ * ```tsx
+ * // app/docs/search.tsx
+ * 'use client';
+ * import { DocsSearch } from '@waveso/docs/react/next-search';
+ * import { processTerm } from '@/lib/search-terms';
+ *
+ * export function Search({ indexUrl }: { indexUrl: string }) {
+ *   return <DocsSearch indexUrl={indexUrl} miniSearchOptions={{ processTerm }} />;
+ * }
+ * ```
+ *
+ * That component takes the boundary with it, so the function is a module import
+ * on both sides rather than a prop crossing between them — exactly how
+ * {@link tokenizeSearchText} reaches the client today.
+ */
+type SerializableSearchOptions = Omit<Partial<Options<SearchRecord>>, 'extractField' | 'stringifyField' | 'tokenize' | 'processTerm' | 'logger' | 'searchOptions' | 'autoSuggestOptions'> & {
+  searchOptions?: SerializableSearchQueryOptions;
+  autoSuggestOptions?: SerializableSearchQueryOptions;
+};
+/**
+ * Dotted paths of every function reachable from `options`, in encounter order.
+ *
+ * The load-bearing half of the boundary check, and deliberately structural
+ * rather than a key list: it answers for `processTerm`, for
+ * `searchOptions.filter`, and for whatever MiniSearch adds next, because it
+ * asks what the values *are* rather than what they are called.
+ *
+ * `seen` makes a cyclic options object an empty answer rather than a stack
+ * overflow. Nothing in MiniSearch's surface is cyclic, but a hang during
+ * `next build` is a far worse failure than a wrong one, and the guard is a
+ * line.
+ */
+declare function findFunctionValuedOptions(options: object, prefix?: string, seen?: WeakSet<object>): string[];
 //#endregion
-export { SEARCH_INDEX_OPTIONS, mergeSearchOptions, tokenizeSearchText };
+export { SEARCH_INDEX_OPTIONS, SerializableSearchOptions, SerializableSearchQueryOptions, findFunctionValuedOptions, mergeSearchOptions, tokenizeSearchText };

package/dist/search-options.js

@@ -99,5 +99,29 @@ function mergeSearchOptions(overrides = {}) {
 		}
 	};
 }
+/**
+* Dotted paths of every function reachable from `options`, in encounter order.
+*
+* The load-bearing half of the boundary check, and deliberately structural
+* rather than a key list: it answers for `processTerm`, for
+* `searchOptions.filter`, and for whatever MiniSearch adds next, because it
+* asks what the values *are* rather than what they are called.
+*
+* `seen` makes a cyclic options object an empty answer rather than a stack
+* overflow. Nothing in MiniSearch's surface is cyclic, but a hang during
+* `next build` is a far worse failure than a wrong one, and the guard is a
+* line.
+*/
+function findFunctionValuedOptions(options, prefix = "", seen = /* @__PURE__ */ new WeakSet()) {
+	if (seen.has(options)) return [];
+	seen.add(options);
+	const found = [];
+	for (const [key, value] of Object.entries(options)) {
+		const path = prefix === "" ? key : `${prefix}.${key}`;
+		if (typeof value === "function") found.push(path);
+		else if (typeof value === "object" && value !== null) found.push(...findFunctionValuedOptions(value, path, seen));
+	}
+	return found;
+}
 //#endregion
-export { SEARCH_INDEX_OPTIONS, mergeSearchOptions, tokenizeSearchText };
+export { SEARCH_INDEX_OPTIONS, findFunctionValuedOptions, mergeSearchOptions, tokenizeSearchText };

package/dist/semaphore.d.ts

@@ -0,0 +1,46 @@
+//#region src/semaphore.d.ts
+/**
+ * A counting semaphore, for bounding how much of a process resource is in use.
+ *
+ * Private — deliberately not an entry point in `package.json`.
+ *
+ * {@link mapPooled} bounds a fan-out over a list, which is the easy case: the
+ * list is known, so the pool can pull from it. A recursive tree walk has no
+ * list — `scanDir` calls itself once per subdirectory, so a per-call pool
+ * bounds each directory and multiplies across the depth, which is not a bound
+ * at all. That is what this is for.
+ *
+ * ⚠️ NEVER ACQUIRE A SLOT WHILE HOLDING ONE. Nested acquisition deadlocks the
+ * moment every slot is held by a caller waiting for a slot, and no amount of
+ * timeout rescues it. Guard the leaf operation — the `readFile`, the `readdir`
+ * — and never the recursive call around it. In `source.ts` this is why the
+ * traversal itself is ungated: only the filesystem calls take slots, so the
+ * descriptors are bounded exactly while the walk stays as parallel as it was.
+ */
+/** @see createSemaphore */
+interface Semaphore {
+  /**
+   * Run `fn` once a slot is free, and give the slot back when it settles.
+   *
+   * Rejections propagate untouched, and release the slot on the way out.
+   */
+  run<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * A semaphore admitting `limit` concurrent callers.
+ *
+ * Waiters are woken in arrival order, so a long queue cannot starve its head.
+ *
+ * A limit below one falls back to one, for the same reason {@link mapPooled}
+ * clamps: a caller passing `0` — or a negative, from arithmetic on a config
+ * value — would otherwise admit nobody, and the symptom is a build that hangs
+ * rather than one that fails.
+ *
+ * ⚠️ `Math.max(1, limit)` IS NOT ENOUGH, BECAUSE `Math.max(1, NaN)` IS `NaN`.
+ * With `max` set to `NaN`, `active >= max` is false forever and the semaphore
+ * admits everyone — no hang, no error, and no bound, which is the one outcome
+ * worse than either. Non-finite means one.
+ */
+declare function createSemaphore(limit: number): Semaphore;
+//#endregion
+export { Semaphore, createSemaphore };

package/dist/semaphore.js

@@ -0,0 +1,60 @@
+//#region src/semaphore.ts
+/**
+* A semaphore admitting `limit` concurrent callers.
+*
+* Waiters are woken in arrival order, so a long queue cannot starve its head.
+*
+* A limit below one falls back to one, for the same reason {@link mapPooled}
+* clamps: a caller passing `0` — or a negative, from arithmetic on a config
+* value — would otherwise admit nobody, and the symptom is a build that hangs
+* rather than one that fails.
+*
+* ⚠️ `Math.max(1, limit)` IS NOT ENOUGH, BECAUSE `Math.max(1, NaN)` IS `NaN`.
+* With `max` set to `NaN`, `active >= max` is false forever and the semaphore
+* admits everyone — no hang, no error, and no bound, which is the one outcome
+* worse than either. Non-finite means one.
+*/
+function createSemaphore(limit) {
+	const requested = Math.floor(limit);
+	const max = Number.isFinite(requested) && requested >= 1 ? requested : 1;
+	const waiting = [];
+	let active = 0;
+	/**
+	* Hand the slot to the next waiter rather than releasing and re-taking it.
+	*
+	* The naive form — decrement here, let the woken waiter increment itself — is
+	* *equivalent*, and this was written that way first on the assumption that it
+	* was not. It is equivalent because the decrement and the wake happen in one
+	* synchronous step: no microtask can be interposed between them, and anything
+	* enqueued earlier runs before this function rather than inside it, so there
+	* is no window for a caller to read `active` below the limit. Mutation-tested
+	* — swapping in the naive form fails nothing, which is the honest result.
+	*
+	* It stays this way because that argument is about the scheduler rather than
+	* about this code. One `await` between the decrement and the wake and the
+	* bound is gone, with nothing able to observe it. Handing the slot over makes
+	* `active` a count of owned slots at every point, whoever holds them, so the
+	* invariant is local and needs no argument at all.
+	*/
+	const release = () => {
+		const next = waiting.shift();
+		if (next !== void 0) {
+			next();
+			return;
+		}
+		active -= 1;
+	};
+	return { async run(fn) {
+		if (active >= max) await new Promise((resolve) => {
+			waiting.push(resolve);
+		});
+		else active += 1;
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	} };
+}
+//#endregion
+export { createSemaphore };