@waveso/docs 0.4.0 → 0.5.0

package/dist/react/youtube.d.ts

@@ -3,11 +3,32 @@ import { ReactNode } from "react";
 interface YouTubeProps {
   /** The 11-character video id, e.g. `dQw4w9WgXcQ`. */
   id?: string | undefined;
+  /**
+   * Seconds to start at, from the link's `t` or `start`.
+   *
+   * ⚠️ IT USED TO BE DROPPED, AND THE FACADE AUTOPLAYS. `https://youtu.be/x?t=754`
+   * is a link to one moment in a two-hour talk — most of why anyone deep-links a
+   * video at all — and it opened at zero and started playing there, leaving the
+   * reader to work out that the author had meant somewhere else.
+   */
+  start?: number | undefined;
+  /** Playlist the video was linked inside, from the link's `list`. */
+  list?: string | undefined;
   /**
    * Accessible name for the player. Markdown carries no video title, so the
    * fallback is generic — pass a real one where you have it.
    */
   title?: string | undefined;
+  /**
+   * The closed facade's control. Default `'Play video: {title}'`.
+   *
+   * `{title}` is replaced with {@link YouTubeProps.title}. A placeholder rather
+   * than concatenation because a translator has to be able to move the name
+   * within the sentence — several languages put it first.
+   */
+  playLabel?: string | undefined;
+  /** The open facade's control. Default `'Hide video: {title}'`. */
+  hideLabel?: string | undefined;
   className?: string | undefined;
 }
 /**
@@ -48,6 +69,6 @@ interface YouTubeProps {
  * `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
  * exist for uploads below 1280×720 and 404s to a broken image with no fallback.
  */
-declare function YouTube({ id, title, className }: YouTubeProps): ReactNode;
+declare function YouTube({ id, start, list, title, playLabel, hideLabel, className }: YouTubeProps): ReactNode;
 //#endregion
 export { YouTube, YouTubeProps };

package/dist/react/youtube.js

@@ -1,6 +1,24 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/react/youtube.tsx
+/**
+* The embed URL, with whatever the author's link carried.
+*
+* `URLSearchParams` rather than string concatenation: `list` comes out of a
+* document and goes into a URL, and building this by hand is how a crafted
+* "playlist id" adds parameters of its own. `start` is already a number.
+*/
+function embedUrl(id, start, list) {
+	const params = new URLSearchParams({
+		rel: "0",
+		autoplay: "1"
+	});
+	if (start !== void 0 && Number.isFinite(start) && start > 0) params.set("start", String(Math.floor(start)));
+	if (list !== void 0 && list !== "") params.set("list", list);
+	return `https://www.youtube-nocookie.com/embed/${id}?${params.toString()}`;
+}
 const DEFAULT_TITLE = "YouTube video player";
+const DEFAULT_PLAY_LABEL = "Play video: {title}";
+const DEFAULT_HIDE_LABEL = "Hide video: {title}";
 /**
 * Click-to-load YouTube embed, with **no client JavaScript at all**.
 *
@@ -39,7 +57,7 @@ const DEFAULT_TITLE = "YouTube video player";
 * `hqdefault.jpg` rather than `maxresdefault.jpg` deliberately: maxres does not
 * exist for uploads below 1280×720 and 404s to a broken image with no fallback.
 */
-function YouTube({ id, title, className }) {
+function YouTube({ id, start, list, title, playLabel, hideLabel, className }) {
 	if (!id) return null;
 	const safeId = encodeURIComponent(id);
 	const label = title?.trim() || DEFAULT_TITLE;
@@ -78,17 +96,17 @@ function YouTube({ id, title, className }) {
 				}),
 				/* @__PURE__ */ jsx("span", {
 					className: "wave-docs-sr-only wave-docs-youtube__label-play",
-					children: `Play video: ${label}`
+					children: (playLabel ?? DEFAULT_PLAY_LABEL).replace("{title}", label)
 				}),
 				/* @__PURE__ */ jsx("span", {
 					className: "wave-docs-youtube__label-hide",
-					children: `Hide video: ${label}`
+					children: (hideLabel ?? DEFAULT_HIDE_LABEL).replace("{title}", label)
 				})
 			]
 		}), /* @__PURE__ */ jsx("iframe", {
 			className: "wave-docs-youtube__frame",
 			loading: "lazy",
-			src: `https://www.youtube-nocookie.com/embed/${safeId}?rel=0&autoplay=1`,
+			src: embedUrl(safeId, start, list),
 			title: label,
 			allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
 			allowFullScreen: true

package/dist/render.d.ts

@@ -1,5 +1,6 @@
 import { DocFile, DocFrontmatter, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsThemes } from "./highlighter.js";
+import { RehypeCodeFrameOptions } from "./plugins/rehype-code-frame.js";
 import { resolveMarkdownLink } from "./plugins/remark-doc-links.js";
 import { PluggableList } from "unified";
 //#region src/render.d.ts
@@ -115,6 +116,16 @@ interface DocsRendererOptions {
    * than a monochrome block of DSL.
    */
   excludeLangs?: readonly string[] | undefined;
+  /**
+   * Accessible names for the copy button, for a site that is not in English.
+   *
+   * ⚠️ `rehypeCodeFrame` HAS TAKEN A `copyLabel` SINCE IT WAS WRITTEN AND
+   * NOTHING EVER PASSED ONE. The plugin is private, so the option was
+   * unreachable from every entry point — the README said the label was
+   * configurable and it was not. Baked into the HTML at build time, so
+   * overriding it costs no client bytes.
+   */
+  codeLabels?: RehypeCodeFrameOptions | undefined;
 }
 /**
  * Renders {@link DocFile}s. Build one per process and reuse it.

package/dist/render.js

@@ -5,7 +5,7 @@ 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 rehypeShikiFromHighlighter from "@shikijs/rehype/core";
@@ -96,9 +96,29 @@ 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. */
 function toRouteKey(href) {
@@ -238,7 +258,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 +314,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,16 +328,16 @@ 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;
 		}));
@@ -336,8 +362,9 @@ function createDocsRenderer(options) {
 	}
 	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 = {

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 };