@clarify-labs/cli 0.8.0 → 0.8.2

package/output/{plugin-CcD5HeTN.js → plugin-D5EF3pYl.js}

@@ -9,12 +9,12 @@ import shiki from "shiki";
 import { visit } from "unist-util-visit";
 import { markdownRemarkPlugins, themeBootstrapScript, themePresets } from "@clarify-labs/renderer";
 import { stringify } from "yaml";
-import { remark } from "remark";
 import matter from "gray-matter";
+import { remark } from "remark";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import SwaggerParser from "@apidevtools/swagger-parser";
 import { tmpdir } from "node:os";
 import { z } from "zod";
-import { pathToFileURL } from "node:url";
 import { build, loadConfigFromFile } from "vite";
 import { createRequire } from "node:module";
 //#region source/core/utils.ts
@@ -140,23 +140,76 @@ function readRouteArtifactContent(route) {
 	const content = readRouteContent(route);
 	return shouldUseUtf8Signature(route) ? withUtf8Signature(content) : content;
 }
+function isLlmsTxtRoute(route) {
+	return !route.path.split("/").includes("404");
+}
+function llmsTxtDescription(route) {
+	if (route.description) return route.description;
+	const sections = route.sections?.filter((section) => section.level === 2).slice(0, 3).map((section) => section.title);
+	if (sections?.length) return `Covers ${sections.join(", ")}.`;
+	if (route.keywords?.length) return `Related topics: ${route.keywords.join(", ")}.`;
+	if (route.kind === "openapi") return "OpenAPI artifact for machine-readable API reference data.";
+}
+function llmsTxtListItem(route, basePath) {
+	if (!route.contentArtifactUrl) return void 0;
+	const description = llmsTxtDescription(route);
+	return description ? `- [${route.title}](${basePath}${route.contentArtifactUrl}): ${description}` : `- [${route.title}](${basePath}${route.contentArtifactUrl})`;
+}
+function llmsTxtLocaleLabel(locale, projectConfig) {
+	return projectConfig.i18n?.locales.find((item) => item.code === locale)?.label ?? locale;
+}
+function groupRoutesByLocale(routes) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const key = route.locale ?? "default";
+		groups.set(key, [...groups.get(key) ?? [], route]);
+	}
+	return groups;
+}
+function groupLlmsTxtRoutesByLocale(routes, projectConfig) {
+	const routesBySource = /* @__PURE__ */ new Map();
+	const defaultLocale = projectConfig.i18n?.defaultLocale;
+	for (const route of routes) {
+		const sourceKey = `${route.locale ?? defaultLocale ?? "default"}:${route.basePath ?? route.contentArtifactUrl ?? route.path}`;
+		const previousRoute = routesBySource.get(sourceKey);
+		if (!previousRoute || previousRoute.locale && !route.locale) routesBySource.set(sourceKey, route);
+	}
+	return groupRoutesByLocale([...routesBySource.values()].map((route) => ({
+		...route,
+		locale: route.locale ?? defaultLocale
+	})));
+}
+function llmsTxtDocsSectionTitle(locale, groupCount, projectConfig) {
+	if (groupCount <= 1) return "Docs";
+	return `Docs - ${locale === "default" ? "Default" : llmsTxtLocaleLabel(locale, projectConfig)}`;
+}
 function createLlmsTxt(routes, projectConfig) {
 	const basePath = normalizeBasePath(projectConfig.routePrefix);
 	const lines = [`# ${projectConfig.title}`, ""];
 	if (projectConfig.description) lines.push(`> ${projectConfig.description}`, "");
-	lines.push("## Docs");
-	for (const route of routes.filter((route) => route.kind === "mdx")) {
-		if (!route.contentArtifactUrl) continue;
-		lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
+	lines.push("This file lists the source-ready Markdown and OpenAPI artifacts for this documentation site.", "");
+	const mdxRoutes = routes.filter((route) => route.kind === "mdx" && isLlmsTxtRoute(route));
+	if (mdxRoutes.length > 0) {
+		const localizedGroups = groupLlmsTxtRoutesByLocale(mdxRoutes, projectConfig);
+		for (const [locale, localeRoutes] of localizedGroups) {
+			lines.push(`## ${llmsTxtDocsSectionTitle(locale, localizedGroups.size, projectConfig)}`);
+			for (const route of localeRoutes) {
+				const item = llmsTxtListItem(route, basePath);
+				if (item) lines.push(item);
+			}
+			lines.push("");
+		}
 	}
-	const openApiRoutes = routes.filter((route) => route.kind === "openapi");
+	const openApiRoutes = routes.filter((route) => route.kind === "openapi" && isLlmsTxtRoute(route));
 	if (openApiRoutes.length > 0) {
-		lines.push("", "## OpenAPI");
+		if (lines.at(-1) !== "") lines.push("");
+		lines.push("## OpenAPI");
 		for (const route of openApiRoutes) {
-			if (!route.contentArtifactUrl) continue;
-			lines.push(`- [${route.title}](${basePath}${route.contentArtifactUrl})`);
+			const item = llmsTxtListItem(route, basePath);
+			if (item) lines.push(item);
 		}
 	}
+	while (lines.at(-1) === "") lines.pop();
 	return `${lines.join("\n")}\n`;
 }
 function createLlmsTxtArtifact(routes, projectConfig) {
@@ -316,6 +369,101 @@ function parseFrontmatter(content) {
 	};
 }
 //#endregion
+//#region source/parsers/content.ts
+async function transformContent(transform, input) {
+	return transform ? await transform(input) : input;
+}
+function createContentProcessor(transform) {
+	return {
+		async processMdx(source, filePath) {
+			const { frontmatter, content } = parseFrontmatter(source);
+			const transformed = await transformContent(transform, {
+				kind: "mdx",
+				source,
+				filePath,
+				frontmatter,
+				content
+			});
+			return {
+				frontmatter: transformed.frontmatter,
+				content: transformed.content
+			};
+		},
+		async processText(source, kind, filePath) {
+			return (await transformContent(transform, {
+				kind,
+				source,
+				filePath,
+				frontmatter: {},
+				content: source
+			})).content;
+		}
+	};
+}
+//#endregion
+//#region source/core/hooks.ts
+async function runHooks(plugins, hookName, input, ctx) {
+	let result = input;
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.[hookName];
+		if (!hook) continue;
+		try {
+			result = await hook(result, ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
+		}
+	}
+	return result;
+}
+async function runDevConfigureServerHooks(plugins, server, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["dev:configureServer"];
+		if (!hook) continue;
+		try {
+			await hook(server, ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "dev:configureServer" failed: ${err}`, { cause: err });
+		}
+	}
+}
+async function runBuildAssetsHooks(plugins, ctx) {
+	const assets = [];
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["build:assets"];
+		if (!hook) continue;
+		try {
+			const pluginAssets = await hook(ctx);
+			assets.push(...pluginAssets);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:assets" failed: ${err}`, { cause: err });
+		}
+	}
+	return assets;
+}
+async function runBuildDoneHooks(plugins, ctx) {
+	for (const plugin of plugins) {
+		const hook = plugin.hooks?.["build:done"];
+		if (!hook) continue;
+		try {
+			await hook(ctx);
+		} catch (err) {
+			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:done" failed: ${err}`, { cause: err });
+		}
+	}
+}
+//#endregion
+//#region source/core/content.ts
+var contentProcessors = /* @__PURE__ */ new WeakMap();
+function createProjectContentProcessor(plugins, ctx) {
+	return createContentProcessor((input) => runHooks(plugins, "content:transform", input, ctx));
+}
+function setProjectContentProcessor(ctx, processor) {
+	contentProcessors.set(ctx, processor);
+}
+function getProjectContentProcessor(ctx) {
+	return contentProcessors.get(ctx);
+}
+//#endregion
 //#region source/parsers/routes.ts
 function kebabToTitle(str) {
 	return str.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
@@ -392,18 +540,19 @@ function resolveLocalizedText(text, locale, fallbackLocale) {
 	if (text === void 0) return void 0;
 	return text[locale] ?? (fallbackLocale ? text[fallbackLocale] : void 0) ?? Object.values(text)[0];
 }
-function findContentRoutes(dir, base = dir) {
+async function findContentRoutes(dir, base = dir, options = {}) {
 	const routes = [];
 	if (!existsSync(dir)) return routes;
 	const entries = readdirSync(dir, { withFileTypes: true });
 	for (const entry of entries) {
 		const fullPath = join(dir, entry.name);
-		if (entry.isDirectory()) routes.push(...findContentRoutes(fullPath, base));
+		if (entry.isDirectory()) routes.push(...await findContentRoutes(fullPath, base, options));
 		else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
 			const relativePath = relative(base, fullPath);
 			const pathParts = relativePath.replace(/\.mdx?$/, "").split("/");
 			const cleanPath = ("/" + pathParts.map((p) => p === "index" ? "" : p).filter(Boolean).join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
-			const { frontmatter, content } = parseFrontmatter(readFileSync(fullPath, "utf-8"));
+			const source = readFileSync(fullPath, "utf-8");
+			const { frontmatter, content } = await (options.contentProcessor ?? createContentProcessor()).processMdx(source, fullPath);
 			let title = typeof frontmatter.title === "string" ? frontmatter.title : "";
 			if (!title) {
 				const lastPart = pathParts[pathParts.length - 1] ?? "";
@@ -660,6 +809,13 @@ var OPENAPI_HTTP_METHODS = [
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+function isSameOpenAPIFile(url, filePath) {
+	try {
+		return resolve(fileURLToPath(url)) === resolve(filePath);
+	} catch {
+		return resolve(url) === resolve(filePath);
+	}
+}
 function findOpenAPIRoutes(dir, base = dir) {
 	const routes = [];
 	if (!existsSync(dir)) return routes;
@@ -723,12 +879,26 @@ function extractOpenAPISections(spec, filterTags) {
 	}
 	return sections;
 }
-async function readOpenAPISpec(filePath) {
+async function readOpenAPISpec(filePath, contentProcessor) {
 	try {
-		return {
+		if (!contentProcessor) return {
 			ok: true,
 			spec: await SwaggerParser.dereference(filePath)
 		};
+		const source = readFileSync(filePath, "utf-8");
+		const transformedSource = await contentProcessor.processText(source, "openapi", filePath);
+		if (transformedSource === source) return {
+			ok: true,
+			spec: await SwaggerParser.dereference(filePath)
+		};
+		return {
+			ok: true,
+			spec: await SwaggerParser.dereference(filePath, { resolve: { transformedOpenAPISource: {
+				order: 1,
+				canRead: (file) => isSameOpenAPIFile(file.url, filePath),
+				read: () => transformedSource
+			} } })
+		};
 	} catch (error) {
 		return {
 			ok: false,
@@ -989,7 +1159,7 @@ function createOpenAPIPlugin() {
 					const result = specFromCache ? {
 						ok: true,
 						spec: specFromCache
-					} : await readOpenAPISpec(route.filePath);
+					} : await readOpenAPISpec(route.filePath, getProjectContentProcessor(ctx));
 					if (!result.ok) {
 						route.diagnostic = result.diagnostic;
 						route.title = route.title || "OpenAPI parse error";
@@ -1306,9 +1476,51 @@ function createSourceLinksPlugin() {
 	};
 }
 //#endregion
+//#region source/parsers/variables.ts
+var variablePattern = /{{\s*([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)\s*}}/g;
+function getVariableValue(variables, path) {
+	let current = variables;
+	for (const segment of path.split(".")) {
+		if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+function stringifyVariableValue(variables, path, stack) {
+	if (stack.includes(path)) throw new Error(`[clarify] variable "${path}" contains a circular reference: ${[...stack, path].join(" -> ")}`);
+	const value = getVariableValue(variables, path);
+	if (value === void 0 || typeof value === "object") return void 0;
+	if (typeof value !== "string") return String(value);
+	return value.replace(variablePattern, (match, nestedPath) => stringifyVariableValue(variables, nestedPath, [...stack, path]) ?? match);
+}
+function applyVariables(content, variables = {}) {
+	return content.replace(variablePattern, (match, path) => stringifyVariableValue(variables, path, []) ?? match);
+}
+//#endregion
+//#region source/plugins/variables/index.ts
+function applyVariablesToFrontmatter(frontmatter, variables) {
+	const nextFrontmatter = { ...frontmatter };
+	for (const key of ["title", "description"]) {
+		if (typeof nextFrontmatter[key] !== "string") continue;
+		nextFrontmatter[key] = applyVariables(nextFrontmatter[key], variables);
+	}
+	return nextFrontmatter;
+}
+function createVariablesPlugin() {
+	return {
+		name: "clarify:variables",
+		hooks: { "content:transform": (input, ctx) => ({
+			...input,
+			frontmatter: applyVariablesToFrontmatter(input.frontmatter, ctx.projectConfig.variables),
+			content: applyVariables(input.content, ctx.projectConfig.variables)
+		}) }
+	};
+}
+//#endregion
 //#region source/core/builtin.ts
 function createBuiltinPlugins(options = {}) {
 	const plugins = [
+		createVariablesPlugin(),
 		createOpenAPIPlugin(),
 		createSourceLinksPlugin(),
 		createContentArtifactsPlugin(),
@@ -1377,6 +1589,13 @@ var clarifyFooterConfigSchema = z.object({
 	socials: z.record(z.string(), z.string()).optional(),
 	copyright: clarifyLocalizedTextSchema.optional()
 }).strict();
+var clarifyVariableValueSchema = z.lazy(() => z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	z.record(z.string(), clarifyVariableValueSchema)
+]));
+var clarifyVariablesConfigSchema = z.record(z.string(), clarifyVariableValueSchema);
 var clarifySourceConfigSchema = z.object({
 	repository: z.string(),
 	branch: z.string().optional(),
@@ -1454,9 +1673,11 @@ var clarifyProjectConfigSchema = z.object({
 	favicon: clarifyFaviconConfigSchema.optional(),
 	theme: clarifyThemeConfigSchema.optional(),
 	routePrefix: z.string().optional(),
+	assetPrefix: z.string().optional(),
 	navbar: z.object({ links: z.array(clarifyNavbarLinkSchema).optional() }).optional(),
 	banner: clarifyBannerConfigSchema.optional(),
 	footer: clarifyFooterConfigSchema.optional(),
+	variables: clarifyVariablesConfigSchema.optional(),
 	i18n: clarifyI18nConfigSchema.optional(),
 	tabs: clarifyTabsConfigSchema.optional()
 });
@@ -1516,7 +1737,22 @@ function resolveI18nConfig(i18n) {
 		locales: i18n.locales
 	};
 }
+function resolveRoutePrefix(routePrefix) {
+	const trimmed = routePrefix?.trim();
+	if (!trimmed || trimmed === "/") return "/";
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
+function resolveAssetPrefix(assetPrefix, routePrefix) {
+	const trimmed = assetPrefix?.trim();
+	if (trimmed === void 0) return routePrefix;
+	if (trimmed === "./" || trimmed === "") return trimmed || "/";
+	if (!trimmed || trimmed === "/") return "/";
+	if (/^[a-z][a-z\d+.-]*:\/\//i.test(trimmed)) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+	if (trimmed.startsWith("./") || trimmed.startsWith("../")) return trimmed.endsWith("/") ? trimmed : `${trimmed}/`;
+	return `/${trimmed.replace(/^\/+|\/+$/g, "")}/`;
+}
 function resolveProjectConfig(config = {}) {
+	const routePrefix = resolveRoutePrefix(config.routePrefix);
 	return {
 		title: config.title ?? "Clarify Docs",
 		description: config.description ?? "",
@@ -1525,11 +1761,13 @@ function resolveProjectConfig(config = {}) {
 		logo: config.logo,
 		homeUrl: config.homeUrl,
 		favicon: config.favicon,
-		routePrefix: config.routePrefix ?? "/",
+		routePrefix,
+		assetPrefix: resolveAssetPrefix(config.assetPrefix, routePrefix),
 		theme: resolveThemeConfig(config.theme),
 		navbar: config.navbar,
 		banner: config.banner,
 		footer: config.footer,
+		variables: config.variables ?? {},
 		i18n: resolveI18nConfig(config.i18n),
 		tabs: config.tabs
 	};
@@ -1583,57 +1821,6 @@ function writeClarifyEnvDts(projectRoot, plugins) {
 	writeFileSync(filePath, next, "utf-8");
 }
 //#endregion
-//#region source/core/hooks.ts
-async function runHooks(plugins, hookName, input, ctx) {
-	let result = input;
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.[hookName];
-		if (!hook) continue;
-		try {
-			result = await hook(result, ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "${hookName}" failed: ${err}`, { cause: err });
-		}
-	}
-	return result;
-}
-async function runDevConfigureServerHooks(plugins, server, ctx) {
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.["dev:configureServer"];
-		if (!hook) continue;
-		try {
-			await hook(server, ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "dev:configureServer" failed: ${err}`, { cause: err });
-		}
-	}
-}
-async function runBuildAssetsHooks(plugins, ctx) {
-	const assets = [];
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.["build:assets"];
-		if (!hook) continue;
-		try {
-			const pluginAssets = await hook(ctx);
-			assets.push(...pluginAssets);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:assets" failed: ${err}`, { cause: err });
-		}
-	}
-	return assets;
-}
-async function runBuildDoneHooks(plugins, ctx) {
-	for (const plugin of plugins) {
-		const hook = plugin.hooks?.["build:done"];
-		if (!hook) continue;
-		try {
-			await hook(ctx);
-		} catch (err) {
-			throw new Error(`[clarify] plugin "${plugin.name}" hook "build:done" failed: ${err}`, { cause: err });
-		}
-	}
-}
-//#endregion
 //#region source/core/options.ts
 function resolveBuildOptions(options = {}) {
 	return {
@@ -1649,7 +1836,7 @@ async function discoverRoutesForRoot(routeRoot, locale, plugins, ctx) {
 	return (await runHooks(plugins, "routes:discover", {
 		contentRoot: routeRoot,
 		locale,
-		routes: findContentRoutes(routeRoot)
+		routes: await findContentRoutes(routeRoot, routeRoot, { contentProcessor: getProjectContentProcessor(ctx) })
 	}, ctx)).routes;
 }
 async function discoverRoutes(root, contentRoot, plugins, ctx) {
@@ -1714,6 +1901,7 @@ async function resolveClarifySite(options = {}, resolveOptions = {}) {
 		routes: [],
 		navigation: []
 	};
+	setProjectContentProcessor(ctx, createProjectContentProcessor(plugins, ctx));
 	let routes = await discoverRoutes(root, contentRoot, plugins, ctx);
 	routes = await runHooks(plugins, "routes:discovered", routes, ctx);
 	routes = applyConfiguredPageRoutePaths(routes, projectConfig.tabs, projectConfig.i18n);
@@ -2042,7 +2230,7 @@ function clarifyPlugin(options = {}) {
 			async config() {
 				await resolveRoutesAndSpecs();
 				return {
-					base: projectConfig.routePrefix,
+					base: projectConfig.assetPrefix,
 					build: {
 						...generateOptions.outputDirectory ? { outDir: generateOptions.outputDirectory } : {},
 						manifest: true
@@ -2182,4 +2370,4 @@ function clarifyPlugin(options = {}) {
 //#endregion
 export { resolveClarifySite as a, createClarifyRuntimeAliases as i, defineConfig as n, createClarifyTempDir as o, loadClarifyConfig as r, clarifyPlugin as t };
 
-//# sourceMappingURL=plugin-CcD5HeTN.js.map
+//# sourceMappingURL=plugin-D5EF3pYl.js.map