@clarify-labs/cli 0.10.2 → 0.10.3

package/output/{engine-CSSL_gGd.js → engine-CyFtr8Pz.js}

@@ -22,6 +22,24 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import SwaggerParser from "@apidevtools/swagger-parser";
 import { tmpdir } from "node:os";
 import { createRequire } from "node:module";
+//#region source/parsers/content/diagnostic.ts
+function displayPath(filePath, projectRoot) {
+	if (!filePath) return void 0;
+	if (!projectRoot) return filePath.replace(/^[A-Za-z]:\//, "").replace(/^\/+/, "");
+	const normalized = relative(projectRoot, filePath);
+	return normalized && !normalized.startsWith("..") && !isAbsolute(normalized) ? normalized : filePath.replace(/^[A-Za-z]:\//, "").replace(/^\/+/, "");
+}
+function createContentDiagnostic(options) {
+	const { error } = options;
+	return {
+		kind: options.kind,
+		title: options.title,
+		message: options.message,
+		filePath: displayPath(options.filePath, options.projectRoot),
+		details: error instanceof Error ? options.includeStack ? error.stack ?? error.message : error.message : String(error)
+	};
+}
+//#endregion
 //#region source/parsers/markdown/mdx.ts
 function getLanguage(className) {
 	return (Array.isArray(className) ? className : typeof className === "string" ? className.split(/\s+/) : []).find((item) => typeof item === "string" && item.startsWith("language-"))?.replace(/^language-/, "") || "txt";
@@ -57,9 +75,18 @@ var rehypePlugins = [
 		parseMetaString: parseCodeMeta
 	}]
 ];
-function formatMdxDiagnostic(error) {
-	if (error instanceof Error) return error.message;
-	return String(error);
+function createContentCompileDiagnostic(options) {
+	const { format, phase, error, filePath, projectRoot } = options;
+	const label = format === "mdx" ? "MDX" : "Markdown";
+	return createContentDiagnostic({
+		kind: format,
+		title: `${label} ${phase} error`,
+		message: phase === "syntax" ? "This page could not be compiled. Fix the MDX syntax or component usage above, then reload the route." : `This page could not be compiled. Fix the ${label} syntax or plugin error below, then reload the route.`,
+		error,
+		filePath,
+		projectRoot,
+		includeStack: phase === "compilation"
+	});
 }
 /**
 * Validate MDX content for diagnostics WITHOUT running the build-time rehype
@@ -90,13 +117,13 @@ async function compileMdxContent(content, filePath, projectRoot) {
 	} catch (error) {
 		return {
 			ok: false,
-			diagnostic: {
-				kind: "mdx",
-				title: "MDX syntax error",
-				message: "This page could not be compiled. Fix the MDX syntax or component usage above, then reload the route.",
-				filePath: filePath && projectRoot ? filePath.replace(projectRoot + "/", "").replace(/^\/+/, "") : filePath ? filePath.replace(/^[A-Za-z]:\//, "").replace(/^\/+/, "") : void 0,
-				details: formatMdxDiagnostic(error)
-			}
+			diagnostic: createContentCompileDiagnostic({
+				format: "mdx",
+				phase: "syntax",
+				error,
+				filePath,
+				projectRoot
+			})
 		};
 	}
 }
@@ -452,6 +479,7 @@ function routeIntentFromPagesItem(item) {
 		kind: "page",
 		ref: item
 	};
+	if ("group" in item) throw new Error("Navigation groups do not resolve to route intents");
 	if ("openapi" in item) return {
 		kind: "openapi",
 		ref: item.openapi,
@@ -479,15 +507,19 @@ function firstNavigationPath(nodes) {
 }
 function collectExplicitPagePathIntents(tabs) {
 	const intents = [];
-	for (const tab of tabs ?? []) {
-		if (!tab.pages || tab.pages === "FileTree") continue;
-		for (const group of tab.pages) for (const item of group.pages) if (typeof item !== "string" && "page" in item && item.path) {
+	const collectItems = (items) => {
+		for (const item of items) if (typeof item !== "string" && "group" in item) collectItems(item.pages);
+		else if (typeof item !== "string" && "page" in item && item.path) {
 			const intent = routeIntentFromPagesItem(item);
 			if (intent.kind === "page" && intent.path) intents.push({
 				...intent,
 				path: intent.path
 			});
 		}
+	};
+	for (const tab of tabs ?? []) {
+		if (!tab.pages || tab.pages === "FileTree") continue;
+		for (const group of tab.pages) collectItems(group.pages);
 	}
 	return intents;
 }
@@ -538,28 +570,38 @@ function buildNavigationFromTabsConfig(routes, tabs) {
 }
 function buildNavigationFromConfig(routes, config) {
 	const routeMap = new Map(routes.map((r) => [r.path, r]));
-	return config.map((group) => {
-		const children = group.pages.map((item) => {
-			const intent = routeIntentFromPagesItem(item);
-			if (intent.kind === "openapi") {
-				const path = openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path);
-				const route = routeMap.get(path);
-				return {
-					path,
-					title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
-					icon: intent.icon,
-					sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
-				};
-			}
-			const path = routePathFromRef(intent.ref, intent.path);
+	const buildItem = (item) => {
+		if (typeof item !== "string" && "group" in item) {
+			const children = item.pages.map(buildItem);
+			return {
+				path: firstNavigationPath(children),
+				title: resolveLocalizedText(item.group, "", "") ?? "",
+				icon: item.icon,
+				children
+			};
+		}
+		const intent = routeIntentFromPagesItem(item);
+		if (intent.kind === "openapi") {
+			const path = openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path);
 			const route = routeMap.get(path);
 			return {
-				path: intent.redirect ? normalizePath(intent.redirect) : path,
+				path,
 				title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
 				icon: intent.icon,
 				sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
 			};
-		});
+		}
+		const path = routePathFromRef(intent.ref, intent.path);
+		const route = routeMap.get(path);
+		return {
+			path: intent.redirect ? normalizePath(intent.redirect) : path,
+			title: resolveLocalizedText(intent.title, "", "") ?? route?.meta.title ?? kebabToTitle(path.split("/").pop() ?? intent.ref),
+			icon: intent.icon,
+			sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
+		};
+	};
+	return config.map((group) => {
+		const children = group.pages.map(buildItem);
 		return {
 			path: children[0]?.path ?? "/",
 			title: resolveLocalizedText(group.group, "", "") ?? "",
@@ -581,19 +623,29 @@ function buildLocalizedNavigationForLocale(routes, config, locale, i18n) {
 		path: route.basePath ?? route.path
 	}))), locale, i18n);
 	const routeMap = new Map(routes.map((route) => [route.basePath ?? route.path, route]));
-	return config.map((group) => {
-		const children = group.pages.map((item) => {
-			const intent = routeIntentFromPagesItem(item);
-			const basePath = intent.kind === "openapi" ? openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path) : routePathFromRef(intent.ref, intent.path);
-			const route = routeMap.get(basePath);
-			const path = route?.path ?? localizedRoutePath(basePath, locale, i18n);
+	const buildItem = (item) => {
+		if (typeof item !== "string" && "group" in item) {
+			const children = item.pages.map(buildItem);
 			return {
-				path: (intent.kind === "page" && intent.redirect ? localizedRoutePath(routePathFromRef(intent.redirect), locale, i18n) : void 0) ?? path,
-				title: resolveLocalizedText(intent.title, locale, i18n.defaultLocale) ?? route?.meta.title ?? kebabToTitle(basePath.split("/").pop() ?? intent.ref),
-				icon: intent.icon,
-				sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
+				path: firstNavigationPath(children),
+				title: resolveLocalizedText(item.group, locale, i18n.defaultLocale) ?? "",
+				icon: item.icon,
+				children
 			};
-		});
+		}
+		const intent = routeIntentFromPagesItem(item);
+		const basePath = intent.kind === "openapi" ? openAPIPagePathFromRef(intent.ref, intent.tagFilter, intent.path) : routePathFromRef(intent.ref, intent.path);
+		const route = routeMap.get(basePath);
+		const path = route?.path ?? localizedRoutePath(basePath, locale, i18n);
+		return {
+			path: (intent.kind === "page" && intent.redirect ? localizedRoutePath(routePathFromRef(intent.redirect), locale, i18n) : void 0) ?? path,
+			title: resolveLocalizedText(intent.title, locale, i18n.defaultLocale) ?? route?.meta.title ?? kebabToTitle(basePath.split("/").pop() ?? intent.ref),
+			icon: intent.icon,
+			sections: route?.meta.sections ? navigationSections(route.meta.sections) : void 0
+		};
+	};
+	return config.map((group) => {
+		const children = group.pages.map(buildItem);
 		return {
 			path: children[0]?.path ?? localizedRoutePath("/", locale, i18n),
 			title: resolveLocalizedText(group.group, locale, i18n.defaultLocale) ?? "",
@@ -838,8 +890,9 @@ var clarifySourceConfigSchema = z.object({
 	branch: z.string().optional(),
 	directory: z.string().optional()
 });
-var clarifyPagesItemSchema = z.union([
+var clarifyPagesItemSchema = z.lazy(() => z.union([
 	z.string(),
+	clarifyPagesGroupSchema,
 	z.object({
 		page: z.string(),
 		path: z.string().optional(),
@@ -854,12 +907,12 @@ var clarifyPagesItemSchema = z.union([
 		title: clarifyLocalizedTextSchema.optional(),
 		filter: z.object({ tags: z.array(z.string()).optional() }).optional()
 	})
-]);
-var clarifyPagesGroupSchema = z.object({
+]));
+var clarifyPagesGroupSchema = z.lazy(() => z.object({
 	group: clarifyLocalizedTextSchema,
 	icon: z.string().optional(),
 	pages: z.array(clarifyPagesItemSchema)
-});
+}));
 var clarifyPagesConfigSchema = z.union([z.array(clarifyPagesGroupSchema), z.literal("FileTree")]);
 var clarifyTabItemSchema = z.object({
 	tab: clarifyLocalizedTextSchema,
@@ -1207,16 +1260,10 @@ function createRuntimeSlotsModule(plugins = [], root = process.cwd()) {
 	}
 	return `export const runtimeSlots = {\n${[...grouped.entries()].map(([name, list]) => `  ${JSON.stringify(name)}: [\n    ${list.join(",\n    ")}\n  ]`).join(",\n")}\n};\n`;
 }
-function generateMdxErrorModule(diagnostic) {
+function generateContentDiagnosticModule(diagnostic) {
 	return `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';
 
-export const contentDiagnostic = ${JSON.stringify({
-		kind: diagnostic.kind ?? "mdx",
-		title: diagnostic.title,
-		message: diagnostic.message,
-		filePath: diagnostic.filePath,
-		details: diagnostic.details
-	})};
+export const contentDiagnostic = ${JSON.stringify(diagnostic)};
 
 export default createContentDiagnosticComponent(contentDiagnostic);
 `;
@@ -1234,7 +1281,7 @@ function buildVirtualModules(args) {
 	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
 	modules.set(RESOLVED_CLIENT_ENTRY, clientEntryModule);
 	for (const route of args.routes) {
-		const moduleContent = route.diagnostic ? generateMdxErrorModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.source.filePath)};`;
+		const moduleContent = route.diagnostic ? generateContentDiagnosticModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.source.filePath)};`;
 		modules.set(route.module.virtualModuleId, moduleContent);
 	}
 	return modules;
@@ -1285,26 +1332,42 @@ function createNormalizedContentPlugin(engine) {
 		}
 	};
 }
-function createMdxPlugin() {
-	return mdxPlugin({
-		include: ["**/*.mdx"],
-		format: "mdx",
-		jsxImportSource: "react",
-		providerImportSource: "@clarify-labs/renderer",
-		remarkPlugins,
-		rehypePlugins
-	});
+function createContentCompileTransform(transform, format, projectRoot, errorPolicy = () => "diagnostic") {
+	return async function contentCompileTransform(code, id) {
+		try {
+			return await transform.call(this, code, id);
+		} catch (error) {
+			if (errorPolicy() === "throw") throw error;
+			return {
+				code: generateContentDiagnosticModule(createContentCompileDiagnostic({
+					format,
+					phase: "compilation",
+					error,
+					filePath: id.replace(/\?.*$/, ""),
+					projectRoot
+				})),
+				map: null
+			};
+		}
+	};
 }
-function createMarkdownPlugin() {
-	return mdxPlugin({
-		include: ["**/*.md"],
-		format: "md",
+function createContentCompilerPlugin(format, projectRoot, errorPolicy) {
+	const markdown = format === "markdown";
+	const plugin = mdxPlugin({
+		include: [markdown ? "**/*.md" : "**/*.mdx"],
+		format: markdown ? "md" : "mdx",
 		jsxImportSource: "react",
 		providerImportSource: "@clarify-labs/renderer",
 		remarkPlugins,
-		remarkRehypeOptions: { allowDangerousHtml: true },
-		rehypePlugins: [rehypeRaw, ...rehypePlugins]
+		...markdown ? { remarkRehypeOptions: { allowDangerousHtml: true } } : {},
+		rehypePlugins: markdown ? [rehypeRaw, ...rehypePlugins] : rehypePlugins
 	});
+	const transform = typeof plugin.transform === "function" ? plugin.transform : plugin.transform?.handler;
+	if (!transform) return plugin;
+	return {
+		...plugin,
+		transform: createContentCompileTransform(transform, format, projectRoot, errorPolicy)
+	};
 }
 function createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown, mdx) {
 	let viteConfig;
@@ -1426,13 +1489,22 @@ function createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown,
 * site itself - it only bridges Vite lifecycle hooks to the engine.
 */
 function createViteAdapter(engine) {
+	let contentCompileErrorPolicy = "diagnostic";
+	const errorPolicy = () => contentCompileErrorPolicy;
 	const normalizedContentPlugin = createNormalizedContentPlugin(engine);
-	const markdown = createMarkdownPlugin();
-	const mdx = createMdxPlugin();
+	const markdown = createContentCompilerPlugin("markdown", engine.root, errorPolicy);
+	const mdx = createContentCompilerPlugin("mdx", engine.root, errorPolicy);
+	const compilePolicyPlugin = {
+		name: "clarify:content-compile-policy",
+		configResolved(config) {
+			contentCompileErrorPolicy = config.command === "build" && engine.generateOptions.ssg.failOnError ? "throw" : "diagnostic";
+		}
+	};
 	const tailwind = tailwindcss();
 	return [
 		...react(),
 		...Array.isArray(tailwind) ? tailwind : [tailwind],
+		compilePolicyPlugin,
 		normalizedContentPlugin,
 		createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown, mdx),
 		markdown,
@@ -1441,7 +1513,7 @@ function createViteAdapter(engine) {
 }
 var cliPackageVersion = {
 	name: "@clarify-labs/cli",
-	version: "0.10.2",
+	version: "0.10.3",
 	license: "AGPL-3.0-only",
 	type: "module",
 	repository: {
@@ -1794,9 +1866,6 @@ var OPENAPI_HTTP_METHODS = [
 	"trace"
 ];
 var CLARIFY_OPENAPI_SECTION_ID_EXTENSION = "x-clarify-section-id";
-function errorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
-}
 function isSameOpenAPIFile(url, filePath) {
 	try {
 		return resolve(fileURLToPath(url)) === resolve(filePath);
@@ -1911,7 +1980,7 @@ function extractOpenAPISections(spec, filterTags) {
 	}
 	return sections;
 }
-async function readOpenAPISpec(filePath, contentProcessor) {
+async function readOpenAPISpec(filePath, contentProcessor, projectRoot) {
 	try {
 		if (!contentProcessor) return {
 			ok: true,
@@ -1934,13 +2003,14 @@ async function readOpenAPISpec(filePath, contentProcessor) {
 	} catch (error) {
 		return {
 			ok: false,
-			diagnostic: {
+			diagnostic: createContentDiagnostic({
 				kind: "openapi",
 				title: "OpenAPI spec parse failed",
-				message: `Clarify could not parse ${filePath}.`,
+				message: "Clarify could not parse this OpenAPI specification.",
+				error,
 				filePath,
-				details: errorMessage(error)
-			}
+				projectRoot
+			})
 		};
 	}
 }
@@ -1971,31 +2041,24 @@ export const routeData = {};
 export default createOpenApiRouteComponent({ ...routeData, spec });
 `;
 }
-function generateOpenAPIErrorModule(diagnostic) {
-	return `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';
-
-export const contentDiagnostic = ${JSON.stringify({
-		kind: diagnostic.kind ?? "openapi",
-		title: diagnostic.title,
-		message: diagnostic.message,
-		filePath: diagnostic.filePath,
-		details: diagnostic.details
-	})};
-
-export default createContentDiagnosticComponent(contentDiagnostic);
-`;
-}
 //#endregion
 //#region source/plugins/openapi/index.ts
 function collectOpenAPIPageIntents(config) {
 	const intents = [];
-	function visitPages(pages) {
-		if (!pages || pages === "FileTree") return;
-		for (const group of pages) for (const item of group.pages) {
+	function visitItems(items) {
+		for (const item of items) {
+			if (typeof item !== "string" && "group" in item) {
+				visitItems(item.pages);
+				continue;
+			}
 			const intent = routeIntentFromPagesItem(item);
 			if (intent.kind === "openapi" && (intent.path || intent.tagFilter?.length)) intents.push(intent);
 		}
 	}
+	function visitPages(pages) {
+		if (!pages || pages === "FileTree") return;
+		for (const group of pages) visitItems(group.pages);
+	}
 	for (const tab of config.tabs ?? []) visitPages(tab.pages);
 	return intents;
 }
@@ -2141,7 +2204,7 @@ function createOpenAPIPlugin() {
 					const result = specFromCache ? {
 						ok: true,
 						spec: specFromCache
-					} : await readOpenAPISpec(route.source.filePath, processor);
+					} : await readOpenAPISpec(route.source.filePath, processor, ctx.generateOptions.projectRoot);
 					if (!result.ok) {
 						route.diagnostic = result.diagnostic;
 						route.meta.title = route.meta.title || "OpenAPI parse error";
@@ -2188,7 +2251,7 @@ function createOpenAPIPlugin() {
 				for (const [routeSpecModuleId, spec] of specModules) modules.set(specVirtualModuleId(routeSpecModuleId), generateOpenAPISpecModule(spec));
 				for (const route of ctx.routes) {
 					if (route.kind !== "openapi") continue;
-					if (route.diagnostic) modules.set(route.module.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
+					if (route.diagnostic) modules.set(route.module.virtualModuleId, generateContentDiagnosticModule(route.diagnostic));
 					else if (route.openapi?.sourceSpecId) {
 						const routeSpecModuleId = route.openapi.routeSpecModuleId ?? route.openapi.sourceSpecId;
 						if (!specModules.has(routeSpecModuleId)) continue;
@@ -3020,6 +3083,12 @@ function loadVirtualModule(id, modules) {
 	const bareId = stripVirtualPrefix(id);
 	return modules.get(bareId) ?? modules.get(id) ?? null;
 }
+function assertNoContentDiagnostics(routes) {
+	const failures = routes.filter((route) => route.diagnostic);
+	if (failures.length === 0) return;
+	const summary = failures.map((route) => `- ${route.path}: ${route.diagnostic?.title ?? "Content error"}${route.diagnostic?.filePath ? ` (${route.diagnostic.filePath})` : ""}`).join("\n");
+	throw new Error(`[clarify] Content diagnostics prevented the build:\n${summary}`);
+}
 var ClarifyEngine = class {
 	options;
 	root;
@@ -3244,6 +3313,7 @@ var ClarifyEngine = class {
 		await runPhase(this.plugins, "ssg", this.ctx, async () => {
 			if (process.env.SKIP_CLARIFY_SSG) return;
 			if (!await runInterceptHooks(this.plugins, "ssg:shouldRun", this.ctx)) return;
+			if (this.generateOptions.ssg.failOnError) assertNoContentDiagnostics(this.routes);
 			const outputDir = this.runtime.outputDirectory ?? this.generateOptions.outputDirectory;
 			if (!outputDir) throw new Error("[clarify] outputDirectory is required before SSG runs");
 			const ssrOutputDir = join(outputDir, ".ssr");
@@ -3304,4 +3374,4 @@ function createClarifyEngine(options = {}) {
 //#endregion
 export { cliPackageVersion as a, defineConfig as c, createClarifyTempDir as i, createClarifyEngine as n, cliPackageVersionWithCaret as o, createClarifyRuntimeAliases as r, createViteAdapter as s, ClarifyEngine as t };
 
-//# sourceMappingURL=engine-CSSL_gGd.js.map
+//# sourceMappingURL=engine-CyFtr8Pz.js.map