@ox-content/vite-plugin 2.89.0 → 2.90.0

package/dist/index.cjs

@@ -109,6 +109,119 @@ function createMarkdownEnvironment(options) {
 	};
 }
 //#endregion
+//#region src/highlight-native.ts
+/**
+* Extract text content from a hast node.
+*/
+function getTextContent(node) {
+	let text = "";
+	if ("children" in node) {
+		for (const child of node.children) if (child.type === "text") text += child.value;
+		else if (child.type === "element") text += getTextContent(child);
+	}
+	return text;
+}
+function normalizeClassName(className) {
+	if (Array.isArray(className)) return className.filter((value) => typeof value === "string");
+	if (typeof className === "string" && className) return className.split(/\s+/).filter(Boolean);
+	return [];
+}
+/**
+* Highlights with the native tree-sitter engine, or `null` when it has no
+* grammar for `lang`.
+*
+* Parsing once and walking the tree is roughly eight times faster than
+* matching TextMate patterns line by line — 10.5 ms against 81.5 ms over the
+* documentation corpus's code blocks — and it emits the same
+* `--octc-shiki-*` markup, so themes are unaffected.
+*/
+function highlightNatively(code, lang) {
+	try {
+		return require_vitepress.importNapiModuleSync().highlightCodeBlock(code, lang);
+	} catch {
+		return null;
+	}
+}
+/** Whether the native engine claims `lang`. */
+function nativeSupports(lang) {
+	try {
+		return require_vitepress.importNapiModuleSync().supportsHighlightLanguage(lang);
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether any block in this tree still needs Shiki.
+*
+* Creating a Shiki highlighter parses two dozen TextMate grammars, about
+* 190 ms, so a document whose languages are all covered natively must not
+* touch it at all.
+*/
+function treeNeedsShiki(tree, nativeThemeApplies) {
+	if (!nativeThemeApplies) return true;
+	let needed = false;
+	const walk = (node) => {
+		if (needed || !("children" in node)) return;
+		for (const child of node.children) {
+			if (child.type !== "element") continue;
+			if (child.tagName === "code") {
+				const lang = languageOf(child);
+				if (lang !== null && !nativeSupports(lang)) {
+					needed = true;
+					return;
+				}
+			}
+			walk(child);
+		}
+	};
+	walk(tree);
+	return needed;
+}
+/** The `language-*` class on a `<code>` element, if it carries one. */
+function languageOf(codeElement) {
+	const className = normalizeClassName(codeElement.properties?.className).find((value) => value.startsWith("language-"));
+	return className ? className.slice(9) : null;
+}
+/**
+* Highlights every code block in a rendered document in one native call.
+*
+* Returns the rewritten HTML and the languages it declined, so the caller
+* knows whether Shiki still has to run over the result. Returns `null` when
+* the native module is unavailable.
+*
+* This exists because the plumbing dwarfed the work: walking each page
+* through an HTML parser and serializer to find `<pre>` elements cost 139 ms
+* over the documentation corpus, and re-parsing each highlighted block to
+* splice it back cost another 38 ms, against 14 ms of actual highlighting.
+*
+* It runs off the main thread. The synchronous binding held the event loop
+* for the whole pass, so a build asking for several pages at once still got
+* them one at a time — `Promise.all` over the corpus measured the same as
+* awaiting each page in turn.
+*/
+async function highlightDocumentNatively(html) {
+	try {
+		return await require_vitepress.importNapiModuleSync().highlightHtmlCodeBlocksAsync(html);
+	} catch {
+		return null;
+	}
+}
+/**
+* Splices `replacements` back over the blocks the native pass left pending.
+*
+* Entry `i` is the highlighted `<pre>` for pending block `i`, or an empty
+* string to leave that block alone. This keeps a page that needs one exotic
+* grammar — a Vue SFC, a Mermaid diagram — off the HTML round trip, rather
+* than surrendering the whole document for it.
+*/
+function applyPendingHighlights(html, replacements) {
+	try {
+		return require_vitepress.importNapiModuleSync().applyPendingHighlights(html, replacements);
+	} catch {
+		return html;
+	}
+}
+//#endregion
 //#region src/shiki-theme.ts
 /**
 * Name callers pass as `highlightTheme` to render syntax colors as CSS custom
@@ -233,17 +346,19 @@ function rehypeShikiHighlight(options) {
 	const { theme, langs } = options;
 	return async (tree) => {
 		const { themeName } = normalizeThemeInput(theme);
-		const highlighter = await getHighlighter(theme, langs);
+		const nativeThemeApplies = themeName === CSS_VARIABLES_THEME;
+		const highlighter = treeNeedsShiki(tree, nativeThemeApplies) ? await getHighlighter(theme, langs) : void 0;
 		const highlightBlockCode = (codeElement) => {
 			let lang = "text";
 			const langClass = normalizeClassName(codeElement.properties?.className).find((value) => value.startsWith("language-"));
 			if (langClass) lang = langClass.replace("language-", "");
 			const codeText = getTextContent(codeElement);
 			try {
-				const highlighted = highlighter.codeToHtml(codeText, {
+				const highlighted = (nativeThemeApplies ? highlightNatively(codeText, lang) : null) ?? highlighter?.codeToHtml(codeText, {
 					lang,
 					theme: themeName
 				});
+				if (highlighted === void 0) return null;
 				const parsed = (0, unified.unified)().use(rehypeParse$3, { fragment: true }).parse(highlighted);
 				if (parsed.children[0]?.type === "element") {
 					const highlightedPre = parsed.children[0];
@@ -262,10 +377,11 @@ function rehypeShikiHighlight(options) {
 			lang = langClass.replace("language-", "");
 			const codeText = getTextContent(codeElement);
 			try {
-				const highlighted = highlighter.codeToHtml(codeText, {
+				const highlighted = (nativeThemeApplies ? highlightNatively(codeText, lang) : null) ?? highlighter?.codeToHtml(codeText, {
 					lang,
 					theme: themeName
 				});
+				if (highlighted === void 0) return null;
 				const parsed = (0, unified.unified)().use(rehypeParse$3, { fragment: true }).parse(highlighted);
 				if (parsed.children[0]?.type === "element") {
 					const highlightedCode = parsed.children[0].children.find((child) => child.type === "element" && child.tagName === "code");
@@ -289,7 +405,8 @@ function rehypeShikiHighlight(options) {
 				const child = node.children[i];
 				if (child.type === "element" && child.tagName === "pre") {
 					const codeElement = child.children.find((c) => c.type === "element" && c.tagName === "code");
-					if (codeElement) {
+					const alreadyHighlighted = normalizeClassName(child.properties?.className).includes("shiki");
+					if (codeElement && !alreadyHighlighted) {
 						const highlightedPre = highlightBlockCode(codeElement);
 						if (highlightedPre) node.children[i] = highlightedPre;
 					}
@@ -303,22 +420,6 @@ function rehypeShikiHighlight(options) {
 	};
 }
 /**
-* Extract text content from a hast node.
-*/
-function getTextContent(node) {
-	let text = "";
-	if ("children" in node) {
-		for (const child of node.children) if (child.type === "text") text += child.value;
-		else if (child.type === "element") text += getTextContent(child);
-	}
-	return text;
-}
-function normalizeClassName(className) {
-	if (Array.isArray(className)) return className.filter((value) => typeof value === "string");
-	if (typeof className === "string" && className) return className.split(/\s+/).filter(Boolean);
-	return [];
-}
-/**
 * Apply syntax highlighting to HTML using Shiki.
 */
 async function highlightCode(html, theme = CSS_VARIABLES_THEME, langs = []) {
@@ -329,6 +430,83 @@ async function highlightCode(html, theme = CSS_VARIABLES_THEME, langs = []) {
 	return String(result);
 }
 //#endregion
+//#region src/highlight-pending.ts
+/**
+* Highlighting the blocks the native pass could not claim.
+*
+* These arrive already named — the native pass reports each one's language —
+* which lets this load exactly the grammars a page needs instead of the whole
+* bundled set, and splice each result back without an HTML parser.
+*/
+/**
+* A highlighter that starts with no grammars and gains them on demand.
+*
+* `getHighlighter` loads all two dozen `BUILTIN_LANGS` up front, because the
+* tree walk it serves discovers a page's languages only while rewriting it.
+* The pending list does not have that problem — it names every language it
+* needs — and paying for two dozen TextMate grammars to highlight one Vue
+* block is most of what a page with an exotic block costs.
+*/
+const lazyHighlighterCache = /* @__PURE__ */ new Map();
+const loadedLangs = /* @__PURE__ */ new WeakMap();
+async function getLazyHighlighter(theme, customLangs, wanted) {
+	const { themeInput } = normalizeThemeInput(theme);
+	const cacheKey = JSON.stringify({
+		theme: themeInput,
+		langs: customLangs
+	});
+	let highlighterPromise = lazyHighlighterCache.get(cacheKey);
+	if (!highlighterPromise) {
+		highlighterPromise = (0, shiki.createHighlighter)({
+			themes: [themeInput],
+			langs: customLangs
+		});
+		lazyHighlighterCache.set(cacheKey, highlighterPromise);
+	}
+	const highlighter = await highlighterPromise;
+	let loaded = loadedLangs.get(highlighter);
+	if (!loaded) {
+		loaded = /* @__PURE__ */ new Set();
+		loadedLangs.set(highlighter, loaded);
+	}
+	const missing = [...new Set(wanted.filter((lang) => !loaded.has(lang) && BUILTIN_LANGS.includes(lang)))];
+	if (missing.length > 0) await Promise.all(missing.map(async (lang) => {
+		try {
+			await highlighter.loadLanguage(lang);
+			loaded.add(lang);
+		} catch {}
+	}));
+	return highlighter;
+}
+/**
+* Highlight the blocks the native pass left pending, in order.
+*
+* Entry `i` of the result is the `<pre>` for block `i`, or an empty string
+* when Shiki has no grammar for it either — in which case the block is left
+* exactly as it arrived, the same outcome the tree walk reached by keeping the
+* original element.
+*
+* This is the whole point of the pending list: a page whose only unsupported
+* block is a Mermaid diagram used to be handed to the tree walk in full, which
+* re-highlighted every one of its other blocks and paid for a parse and a
+* serialize of the page to do it.
+*/
+async function highlightPendingBlocks(blocks, theme = CSS_VARIABLES_THEME, langs = []) {
+	if (blocks.length === 0) return [];
+	const { themeName } = normalizeThemeInput(theme);
+	const highlighter = await getLazyHighlighter(theme, langs, blocks.map((block) => block.language));
+	return blocks.map((block) => {
+		try {
+			return highlighter.codeToHtml(block.source, {
+				lang: block.language,
+				theme: themeName
+			});
+		} catch {
+			return "";
+		}
+	});
+}
+//#endregion
 //#region src/plugins/mermaid.ts
 /**
 * Mermaid Plugin - Native Rust renderer via NAPI
@@ -342,21 +520,21 @@ var mermaid_exports = /* @__PURE__ */ require_vitepress.__exportAll({
 	transformMermaidStatic: () => transformMermaidStatic
 });
 /** Cached NAPI bindings */
-let napiBindings$1 = null;
-let napiLoadAttempted$1 = false;
+let napiBindings = null;
+let napiLoadAttempted = false;
 async function loadNapi() {
-	if (napiLoadAttempted$1) return napiBindings$1;
-	napiLoadAttempted$1 = true;
+	if (napiLoadAttempted) return napiBindings;
+	napiLoadAttempted = true;
 	try {
 		const binding = await require_vitepress.importNapiModule();
 		if (typeof binding.transformMermaid !== "function") {
-			napiBindings$1 = null;
+			napiBindings = null;
 			return null;
 		}
-		napiBindings$1 = binding;
+		napiBindings = binding;
 		return binding;
 	} catch {
-		napiBindings$1 = null;
+		napiBindings = null;
 		return null;
 	}
 }
@@ -1947,24 +2125,25 @@ function normalizeDiagnostic(diagnostic) {
 //#endregion
 //#region src/transform.ts
 /**
-* Cached NAPI bindings instance.
-* Loaded on first use and reused for subsequent transformations.
+* The NAPI load, cached as the promise rather than as its result.
+*
+* The load yields, and a caller arriving during that yield has to wait for it
+* rather than read a result that is not there yet. Holding the promise is what
+* makes every caller wait for the same load; holding an "already attempted"
+* flag beside an unset result meant the first page to arrive loaded the module
+* and every page behind it concluded there were no bindings at all.
+*
 * @internal
 */
-let napiBindings;
-/**
-* Flag to prevent repeated NAPI loading attempts.
-* Set to true after first load attempt (success or failure).
-* @internal
-*/
-let napiLoadAttempted = false;
+let napiLoad;
 /**
 * Lazily loads and caches NAPI bindings.
 *
 * This function uses lazy loading to defer the import of NAPI bindings
 * until they're actually needed. The bindings are loaded only once and
-* cached for subsequent uses. If loading fails (e.g., bindings not built),
-* the failure is cached to avoid repeated load attempts.
+* cached for subsequent uses, including by callers that ask for them while
+* that first load is still in flight. If loading fails (e.g., bindings not
+* built), the failure is cached to avoid repeated load attempts.
 *
 * ## Performance Considerations
 *
@@ -1995,18 +2174,12 @@ let napiLoadAttempted = false;
 *
 * @internal
 */
-async function loadNapiBindings() {
-	if (napiLoadAttempted) return napiBindings ?? null;
-	napiLoadAttempted = true;
-	try {
-		const mod = await require_vitepress.importNapiModule();
-		napiBindings = mod;
-		return mod;
-	} catch (error) {
+function loadNapiBindings() {
+	napiLoad ??= require_vitepress.importNapiModule().catch((error) => {
 		if (process.env.DEBUG) console.debug("[ox-content] NAPI bindings load failed:", error);
-		napiBindings = null;
 		return null;
-	}
+	});
+	return napiLoad;
 }
 async function transformMarkdown(source, filePath, options, ssgOptions) {
 	const napi = await loadNapiBindings();
@@ -2061,9 +2234,18 @@ async function transformMarkdown(source, filePath, options, ssgOptions) {
 	const { html: protectedHtml, svgs } = protectMermaidSvgs(html);
 	html = protectedHtml;
 	if (options.highlight) {
-		const originalHtml = html;
-		const highlightedHtml = await highlightCode(html, options.highlightTheme, options.highlightLangs);
-		html = napi.mergeHighlightedCodeBlocks(originalHtml, highlightedHtml);
+		const native = options.highlightTheme === void 0 || options.highlightTheme === "css-variables" ? await highlightDocumentNatively(html) : null;
+		if (native && native.skipped.length === 0) {
+			html = native.html;
+			if (native.pending.length > 0) {
+				const replacements = await highlightPendingBlocks(native.pending, options.highlightTheme, options.highlightLangs);
+				html = applyPendingHighlights(html, replacements);
+			}
+		} else {
+			const originalHtml = html;
+			const highlightedHtml = await highlightCode(html, options.highlightTheme, options.highlightLangs);
+			html = napi.mergeHighlightedCodeBlocks(originalHtml, highlightedHtml);
+		}
 	}
 	html = await transformBuiltinEmbeds(html, options.embeds ?? {
 		github: {},
@@ -2177,6 +2359,56 @@ if (import.meta.hot) {
 }
 //#endregion
 //#region src/docs.ts
+/**
+* Source Documentation Extraction and Generation
+*
+* This module provides comprehensive tools for extracting JSDoc/TSDoc comments
+* from TypeScript/JavaScript source files and automatically generating Markdown
+* documentation.
+*
+* ## Features
+*
+* - **Automatic Extraction**: Parses JSDoc comments from functions, classes, interfaces, and types
+* - **Flexible Filtering**: Include/exclude patterns for selective documentation
+* - **Markdown Generation**: Converts extracted docs to organized Markdown files
+* - **Navigation Generation**: Auto-generates sidebar navigation metadata
+* - **GitHub Links**: Includes clickable links to source code on GitHub
+*
+* ## Supported JSDoc Tags
+*
+* - `@param {type} name - description` - Function parameter documentation
+* - `@returns {type} description` - Return value documentation
+* - `@example` - Code examples (multi-line blocks)
+* - `@private` - Mark item as private (excluded from docs if private=false)
+* - `@default value` - Default parameter value
+* - Custom tags are preserved in the `tags` field
+*
+* ## Usage Flow
+*
+* 1. Call `extractDocs()` to parse source files
+* 2. Call `generateMarkdown()` to create Markdown content
+* 3. Call `writeDocs()` to write files to output directory
+* 4. Generated nav.ts can be imported for sidebar navigation
+*
+* @example
+* ```typescript
+* import { extractDocs, generateMarkdown, writeDocs } from './docs';
+*
+* const docsOptions = {
+*   enabled: true,
+*   src: ['./src'],
+*   out: './docs/api',
+*   include: ['**\/*.ts'],
+*   exclude: ['**\/*.test.ts'],
+*   groupBy: 'file',
+*   githubUrl: 'https://github.com/user/project',
+* };
+*
+* const extracted = await extractDocs(['./src'], docsOptions);
+* const markdown = generateMarkdown(extracted, docsOptions);
+* await writeDocs(markdown, './docs/api', extracted, docsOptions);
+* ```
+*/
 const DEFAULT_DOCS_INCLUDE = [
 	"**/*.ts",
 	"**/*.tsx",
@@ -2317,7 +2549,7 @@ async function writeDocs(docs, outDir, extractedDocs, options) {
 	napi.writeGeneratedDocs(docs, outDir, extractedDocs ? toRustDocsModules(extractedDocs) : void 0, {
 		generateNav: options?.generateNav ?? false,
 		groupBy: options?.groupBy ?? "file",
-		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		generatedAt: existingGeneratedAt(outDir) ?? (/* @__PURE__ */ new Date()).toISOString(),
 		basePath: options?.basePath,
 		pathStrategy: options?.pathStrategy,
 		groupOrder: options?.groupOrder,
@@ -2327,6 +2559,15 @@ async function writeDocs(docs, outDir, extractedDocs, options) {
 		singleEntryRoot: options?.singleEntryRoot
 	});
 }
+/** Keep `docs.json`'s timestamp stable across regenerations of the same tree. */
+function existingGeneratedAt(outDir) {
+	try {
+		const parsed = JSON.parse((0, node_fs.readFileSync)(node_path.join(outDir, "docs.json"), "utf8"));
+		return typeof parsed.generatedAt === "string" && parsed.generatedAt.length > 0 ? parsed.generatedAt : void 0;
+	} catch {
+		return;
+	}
+}
 function toRustDocsModules(docs) {
 	return docs.map((doc) => ({
 		file: doc.file,