@ox-content/vite-plugin 2.33.0 → 2.34.0

package/dist/index.cjs

@@ -817,7 +817,8 @@ async function extractDocs(srcDirs, options) {
 		return extractDocsFromEntryPoints(options.entryPoints, {
 			root: process.cwd(),
 			private: options.private,
-			internal: options.internal
+			internal: options.internal,
+			typeParameters: options.typeParameters
 		}).map((doc) => ({
 			file: doc.file,
 			entries: doc.entries
@@ -825,7 +826,7 @@ async function extractDocs(srcDirs, options) {
 	}
 	const extractDocsFromDirectories = napi.extractDocsFromDirectories;
 	if (!extractDocsFromDirectories) throw new Error("[ox-content] extractDocsFromDirectories is not available from @ox-content/napi.");
-	return extractDocsFromDirectories(srcDirs, options.include, options.exclude, options.private, options.internal).map((doc) => ({
+	return extractDocsFromDirectories(srcDirs, options.include, options.exclude, options.private, options.internal, options.typeParameters).map((doc) => ({
 		file: doc.file,
 		entries: doc.entries
 	}));
@@ -906,6 +907,7 @@ function resolveDocsOptions(options) {
 		basePath: opts.basePath,
 		pathStrategy: opts.pathStrategy ?? "flat",
 		renderStyle: opts.renderStyle ?? "html",
+		typeParameters: opts.typeParameters ?? false,
 		generateNav: opts.generateNav ?? true
 	};
 }
@@ -2986,6 +2988,337 @@ function generateI18nModule(options, root) {
 	throw new Error("[ox-content:i18n] @ox-content/napi does not expose generateI18nModule. Please rebuild the NAPI package.");
 }
 //#endregion
+//#region src/docs-tests.ts
+var DocsTestRunError = class extends Error {
+	result;
+	constructor(result) {
+		const command = [result.command, ...result.args].join(" ");
+		super(`[ox-content] Docs tests failed with exit code ${result.exitCode}: ${command}`);
+		this.name = "DocsTestRunError";
+		this.result = result;
+	}
+};
+async function collectDocsTests(options) {
+	const cwd = node_path.resolve(options.cwd ?? process.cwd());
+	if ((options.source ?? "markdown") === "jsdoc") return collectJsdocDocsTests(options, cwd);
+	return collectMarkdownDocsTests(options, cwd);
+}
+async function collectMarkdownDocsTests(options, cwd) {
+	const include = toArray(options.include);
+	const ignore = toArray(options.ignore);
+	const files = /* @__PURE__ */ new Map();
+	if (include.length === 0) throw new Error("[ox-content] Docs test include patterns are required for markdown sources.");
+	for (const pattern of include) {
+		const matches = await (0, glob.glob)(pattern, {
+			absolute: true,
+			cwd,
+			ignore,
+			nodir: true
+		});
+		for (const filePath of matches) {
+			const absolutePath = node_path.resolve(filePath);
+			files.set(absolutePath, normalizePath$1(node_path.relative(cwd, absolutePath)));
+		}
+	}
+	const blocks = [];
+	let index = 0;
+	for (const [sourcePath, relativePath] of [...files.entries()].sort((left, right) => left[0].localeCompare(right[0]))) {
+		const extracted = await extractDocsTests(await node_fs_promises.readFile(sourcePath, "utf-8"), {
+			languages: options.languages,
+			requireMeta: options.requireMeta
+		});
+		for (const block of extracted) {
+			blocks.push({
+				...block,
+				sourcePath,
+				relativePath,
+				index
+			});
+			index += 1;
+		}
+	}
+	return blocks;
+}
+async function collectJsdocDocsTests(options, cwd) {
+	const docsOptions = resolveJsdocDocsOptions(options, cwd);
+	const docs = await extractDocs(docsOptions.src, docsOptions);
+	const blocks = [];
+	let index = 0;
+	for (const doc of sortDocs(docs)) for (const entry of sortEntries(doc.entries)) for (const example of entry.examples ?? []) {
+		const extracted = await extractDocsTests(example, {
+			languages: options.languages,
+			requireMeta: options.requireMeta
+		});
+		const sourcePath = resolveEntrySourcePath(entry, doc, cwd);
+		const relativePath = relativeSourcePath(cwd, sourcePath);
+		for (const block of extracted) {
+			blocks.push({
+				...block,
+				sourcePath,
+				relativePath,
+				startLine: entry.line,
+				endLine: entry.endLine,
+				index
+			});
+			index += 1;
+		}
+	}
+	return blocks;
+}
+function resolveJsdocDocsOptions(options, cwd) {
+	const docsOptions = { ...options.docs };
+	if (options.src !== void 0) docsOptions.src = toArray(options.src);
+	if (options.include !== void 0) docsOptions.include = toArray(options.include);
+	if (options.ignore !== void 0) docsOptions.exclude = toArray(options.ignore);
+	const resolved = resolveDocsOptions(docsOptions);
+	return {
+		...resolved,
+		src: resolved.src.map((sourceDir) => node_path.resolve(cwd, sourceDir)),
+		entryPoints: resolved.entryPoints?.map((entryPoint) => ({
+			...entryPoint,
+			path: node_path.resolve(cwd, entryPoint.path)
+		}))
+	};
+}
+function sortDocs(docs) {
+	return [...docs].sort((left, right) => left.file.localeCompare(right.file));
+}
+function sortEntries(entries) {
+	return [...entries].sort((left, right) => {
+		const byFile = left.file.localeCompare(right.file);
+		if (byFile !== 0) return byFile;
+		const byLine = left.line - right.line;
+		if (byLine !== 0) return byLine;
+		return left.name.localeCompare(right.name);
+	});
+}
+function resolveEntrySourcePath(entry, doc, cwd) {
+	const sourcePath = entry.file || doc.file;
+	return node_path.isAbsolute(sourcePath) ? node_path.resolve(sourcePath) : node_path.resolve(cwd, sourcePath);
+}
+function relativeSourcePath(cwd, sourcePath) {
+	const relativePath = node_path.relative(cwd, sourcePath);
+	if (!relativePath.startsWith("..") && !node_path.isAbsolute(relativePath)) return normalizePath$1(relativePath);
+	return normalizePath$1(sourcePath);
+}
+async function writeDocsTestFiles(options) {
+	const cwd = node_path.resolve(options.cwd ?? process.cwd());
+	const generatedDir = node_path.resolve(cwd, options.generatedDir ?? ".cache/ox-content-docs-tests");
+	const clean = options.clean ?? true;
+	const blocks = await collectDocsTests({
+		...options,
+		cwd
+	});
+	if (clean) await node_fs_promises.rm(generatedDir, {
+		recursive: true,
+		force: true
+	});
+	await node_fs_promises.mkdir(generatedDir, { recursive: true });
+	return {
+		cwd,
+		generatedDir,
+		blocks,
+		files: await Promise.all(blocks.map(async (block) => {
+			const filePath = node_path.join(generatedDir, docsTestFileName(block));
+			await node_fs_promises.writeFile(filePath, renderDocsTestFile(block, options), "utf-8");
+			return {
+				filePath,
+				sourcePath: block.sourcePath,
+				relativePath: block.relativePath,
+				startLine: block.startLine,
+				endLine: block.endLine,
+				language: block.language
+			};
+		}))
+	};
+}
+async function runDocsTests(options) {
+	const writeResult = await writeDocsTestFiles(options);
+	const command = options.vitestCommand ?? "vitest";
+	const leadingArgs = options.vitestArgs ?? ["run"];
+	const fileArgs = writeResult.files.map((file) => file.filePath);
+	const args = [...leadingArgs, ...fileArgs];
+	if (fileArgs.length === 0) {
+		if (options.allowEmpty) return {
+			...writeResult,
+			command,
+			args,
+			exitCode: 0,
+			stdout: "",
+			stderr: ""
+		};
+		throw new Error("[ox-content] No runnable docs test blocks were found.");
+	}
+	const result = await runCommand(command, args, {
+		cwd: writeResult.cwd,
+		env: mergeEnv(options.env)
+	});
+	const runResult = {
+		...writeResult,
+		command,
+		args,
+		...result
+	};
+	if (runResult.exitCode !== 0) throw new DocsTestRunError(runResult);
+	return runResult;
+}
+function renderDocsTestFile(block, options) {
+	const parts = [
+		"// Generated by @ox-content/vite-plugin docs test harness.",
+		`// Source: ${block.relativePath}:${block.startLine}-${block.endLine}`,
+		""
+	];
+	const setupCode = options.setupCode?.trimEnd();
+	const code = rewriteImports(block.code.trimEnd(), options.importRewrites);
+	if (setupCode) parts.push(setupCode, "");
+	if ((options.executionMode ?? "test") === "module") {
+		parts.push(code, "");
+		return parts.join("\n");
+	}
+	const { imports, body } = partitionImports(code);
+	parts.push(`import { test } from ${JSON.stringify(rewriteSpecifier(options.testImport ?? "vitest", options.importRewrites))};`);
+	if (imports.length > 0) parts.push(...imports);
+	parts.push("", `test(${JSON.stringify(`${block.relativePath}:${block.startLine}`)}, async () => {`);
+	if (body.trim().length > 0) parts.push(indentCode(body.trimEnd()));
+	parts.push("});", "");
+	return parts.join("\n");
+}
+function partitionImports(source) {
+	const imports = [];
+	const body = [];
+	const lines = source.split(/\r?\n/);
+	let currentImport;
+	for (const line of lines) {
+		if (currentImport) {
+			currentImport.push(line);
+			if (endsImportDeclaration(line)) {
+				imports.push(currentImport.join("\n"));
+				currentImport = void 0;
+			}
+			continue;
+		}
+		if (startsStaticImport(line)) {
+			if (endsImportDeclaration(line)) imports.push(line);
+			else currentImport = [line];
+			continue;
+		}
+		body.push(line);
+	}
+	if (currentImport) body.push(...currentImport);
+	return {
+		imports,
+		body: body.join("\n")
+	};
+}
+function startsStaticImport(line) {
+	const trimmed = line.trimStart();
+	return trimmed.startsWith("import ") && !trimmed.startsWith("import(");
+}
+function endsImportDeclaration(line) {
+	const trimmed = line.trim();
+	return trimmed.endsWith(";") || /^import\s+["'][^"']+["']$/.test(trimmed) || /\sfrom\s+["'][^"']+["']$/.test(trimmed);
+}
+function indentCode(source) {
+	return source.split("\n").map((line) => line.length > 0 ? `  ${line}` : line).join("\n");
+}
+function rewriteImports(source, rewrites) {
+	if (!rewrites) return source;
+	let result = source;
+	for (const [from, to] of Object.entries(rewrites)) {
+		const escaped = escapeRegExp(from);
+		result = result.replace(new RegExp(`(from\\s+["'])${escaped}(["'])`, "g"), `$1${to}$2`).replace(new RegExp(`(import\\s+["'])${escaped}(["'])`, "g"), `$1${to}$2`).replace(new RegExp(`(import\\(\\s*["'])${escaped}(["']\\s*\\))`, "g"), `$1${to}$2`);
+	}
+	return result;
+}
+/**
+* Applies the same import rewrite table to harness-owned imports.
+*
+* @internal
+* @example
+* ```ts docs-test
+* import { expect } from "vitest";
+* import { extractDocsTests } from "../../src/code-blocks";
+*
+* const markdown = [
+*   "```ts docs-test",
+*   "expect(1 + 1).toBe(2);",
+*   "```",
+* ].join("\n");
+*
+* const blocks = await extractDocsTests(markdown);
+*
+* expect(blocks).toHaveLength(1);
+* expect(blocks[0]?.code).toContain("1 + 1");
+* ```
+*/
+function rewriteSpecifier(specifier, rewrites) {
+	return rewrites?.[specifier] ?? specifier;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function docsTestFileName(block) {
+	return `${block.relativePath.replace(/^\.\//, "").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "docs-test"}-L${block.startLine}-${block.index + 1}.test.${extensionForLanguage(block.language)}`;
+}
+function extensionForLanguage(language) {
+	switch (language.toLowerCase()) {
+		case "jsx": return "jsx";
+		case "tsx": return "tsx";
+		case "mjs": return "mjs";
+		case "mts": return "mts";
+		case "js": return "js";
+		default: return "ts";
+	}
+}
+function toArray(value) {
+	if (!value) return [];
+	return Array.isArray(value) ? value : [value];
+}
+function normalizePath$1(value) {
+	return value.split(node_path.sep).join("/");
+}
+function mergeEnv(overrides) {
+	const env = { ...process.env };
+	for (const [key, value] of Object.entries(overrides ?? {})) if (value === void 0) delete env[key];
+	else env[key] = value;
+	return env;
+}
+function runCommand(command, args, options) {
+	return new Promise((resolve, reject) => {
+		const child = (0, node_child_process.spawn)(command, args, {
+			cwd: options.cwd,
+			env: options.env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		if (child.stdout) {
+			child.stdout.setEncoding("utf-8");
+			child.stdout.on("data", (chunk) => {
+				stdout += chunk;
+			});
+		}
+		if (child.stderr) {
+			child.stderr.setEncoding("utf-8");
+			child.stderr.on("data", (chunk) => {
+				stderr += chunk;
+			});
+		}
+		child.on("error", reject);
+		child.on("close", (exitCode) => {
+			resolve({
+				exitCode: exitCode ?? 1,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+//#endregion
 //#region src/lint.ts
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 const SUPPORTED_MARKDOWN_LINT_LANGUAGES = [
@@ -4405,10 +4738,12 @@ function normalizeRuntimeBase(base) {
 exports.DEFAULT_HTML_TEMPLATE = DEFAULT_HTML_TEMPLATE;
 exports.DEFAULT_MARKDOWN_EXTENSIONS = DEFAULT_MARKDOWN_EXTENSIONS;
 exports.DefaultTheme = DefaultTheme;
+exports.DocsTestRunError = DocsTestRunError;
 exports.Fragment = Fragment;
 exports.buildSearchIndex = buildSearchIndex;
 exports.buildSsg = buildSsg;
 exports.clearRenderContext = clearRenderContext;
+exports.collectDocsTests = collectDocsTests;
 exports.collectGitHubRepos = require_github.collectGitHubRepos;
 exports.collectGitHubSources = require_github.collectGitHubSources;
 exports.collectOgpUrls = require_ogp.collectOgpUrls;
@@ -4468,6 +4803,7 @@ exports.resolveOgImageOptions = resolveOgImageOptions;
 exports.resolveSearchOptions = resolveSearchOptions;
 exports.resolveSsgOptions = resolveSsgOptions;
 exports.resolveTheme = require_vitepress.resolveTheme;
+exports.runDocsTests = runDocsTests;
 exports.setRenderContext = setRenderContext;
 exports.shouldLintMarkdownFile = shouldLintMarkdownFile;
 exports.stripMarkdownExtension = stripMarkdownExtension;
@@ -4487,6 +4823,7 @@ exports.useRenderContext = useRenderContext;
 exports.useSiteConfig = useSiteConfig;
 exports.when = when;
 exports.writeDocs = writeDocs;
+exports.writeDocsTestFiles = writeDocsTestFiles;
 exports.writeSearchIndex = writeSearchIndex;
 
 //# sourceMappingURL=index.cjs.map