@clarify-labs/cli 0.10.2 → 0.10.3

package/output/core/config/config-schema.d.ts

@@ -53,104 +53,18 @@ export declare const clarifySourceConfigSchema: z.ZodObject<{
     branch: z.ZodOptional<z.ZodString>;
     directory: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare const clarifyPagesItemSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-    page: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-    icon: z.ZodOptional<z.ZodString>;
-    redirect: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    openapi: z.ZodString;
-    path: z.ZodOptional<z.ZodString>;
-    icon: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-    filter: z.ZodOptional<z.ZodObject<{
-        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>]>;
-export declare const clarifyPagesGroupSchema: z.ZodObject<{
-    group: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
-    icon: z.ZodOptional<z.ZodString>;
-    pages: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        page: z.ZodString;
-        path: z.ZodOptional<z.ZodString>;
-        title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-        icon: z.ZodOptional<z.ZodString>;
-        redirect: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        openapi: z.ZodString;
-        path: z.ZodOptional<z.ZodString>;
-        icon: z.ZodOptional<z.ZodString>;
-        title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-        filter: z.ZodOptional<z.ZodObject<{
-            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>]>>;
-}, z.core.$strip>;
-export declare const clarifyPagesConfigSchema: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
-    group: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
-    icon: z.ZodOptional<z.ZodString>;
-    pages: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-        page: z.ZodString;
-        path: z.ZodOptional<z.ZodString>;
-        title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-        icon: z.ZodOptional<z.ZodString>;
-        redirect: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>, z.ZodObject<{
-        openapi: z.ZodString;
-        path: z.ZodOptional<z.ZodString>;
-        icon: z.ZodOptional<z.ZodString>;
-        title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-        filter: z.ZodOptional<z.ZodObject<{
-            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>]>>;
-}, z.core.$strip>>, z.ZodLiteral<"FileTree">]>;
+export declare const clarifyPagesItemSchema: z.ZodType<import('../../types.js').ClarifyPagesItem, import('../../types.js').ClarifyPagesItem>;
+export declare const clarifyPagesGroupSchema: z.ZodType<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup>;
+export declare const clarifyPagesConfigSchema: z.ZodUnion<readonly [z.ZodArray<z.ZodType<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup, z.core.$ZodTypeInternals<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup>>>, z.ZodLiteral<"FileTree">]>;
 export declare const clarifyTabItemSchema: z.ZodObject<{
     tab: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
     icon: z.ZodOptional<z.ZodString>;
-    pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
-        group: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
-        icon: z.ZodOptional<z.ZodString>;
-        pages: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-            page: z.ZodString;
-            path: z.ZodOptional<z.ZodString>;
-            title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-            icon: z.ZodOptional<z.ZodString>;
-            redirect: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            openapi: z.ZodString;
-            path: z.ZodOptional<z.ZodString>;
-            icon: z.ZodOptional<z.ZodString>;
-            title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-            filter: z.ZodOptional<z.ZodObject<{
-                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>]>>;
-    }, z.core.$strip>>, z.ZodLiteral<"FileTree">]>>;
+    pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodType<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup, z.core.$ZodTypeInternals<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup>>>, z.ZodLiteral<"FileTree">]>>;
 }, z.core.$strip>;
 export declare const clarifyTabsConfigSchema: z.ZodArray<z.ZodObject<{
     tab: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
     icon: z.ZodOptional<z.ZodString>;
-    pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
-        group: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
-        icon: z.ZodOptional<z.ZodString>;
-        pages: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-            page: z.ZodString;
-            path: z.ZodOptional<z.ZodString>;
-            title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-            icon: z.ZodOptional<z.ZodString>;
-            redirect: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>, z.ZodObject<{
-            openapi: z.ZodString;
-            path: z.ZodOptional<z.ZodString>;
-            icon: z.ZodOptional<z.ZodString>;
-            title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-            filter: z.ZodOptional<z.ZodObject<{
-                tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strip>>;
-        }, z.core.$strip>]>>;
-    }, z.core.$strip>>, z.ZodLiteral<"FileTree">]>>;
+    pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodType<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup, z.core.$ZodTypeInternals<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup>>>, z.ZodLiteral<"FileTree">]>>;
 }, z.core.$strip>>;
 export declare const clarifyThemePresetSchema: z.ZodEnum<{
     default: "default";
@@ -411,25 +325,7 @@ export declare const clarifyProjectConfigSchema: z.ZodObject<{
     tabs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         tab: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
         icon: z.ZodOptional<z.ZodString>;
-        pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
-            group: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
-            icon: z.ZodOptional<z.ZodString>;
-            pages: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-                page: z.ZodString;
-                path: z.ZodOptional<z.ZodString>;
-                title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-                icon: z.ZodOptional<z.ZodString>;
-                redirect: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>, z.ZodObject<{
-                openapi: z.ZodString;
-                path: z.ZodOptional<z.ZodString>;
-                icon: z.ZodOptional<z.ZodString>;
-                title: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
-                filter: z.ZodOptional<z.ZodObject<{
-                    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                }, z.core.$strip>>;
-            }, z.core.$strip>]>>;
-        }, z.core.$strip>>, z.ZodLiteral<"FileTree">]>>;
+        pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodType<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup, z.core.$ZodTypeInternals<import('../../types.js').ClarifyPagesGroup, import('../../types.js').ClarifyPagesGroup>>>, z.ZodLiteral<"FileTree">]>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ClarifyProjectConfigInput = z.input<typeof clarifyProjectConfigSchema>;

package/output/core/engine/engine.d.ts

@@ -6,6 +6,7 @@ import { VirtualModules } from '../runtime/virtual-modules.js';
 import { ClarifyContext } from './context.js';
 import { ClarifyEngineRuntime, PrepareOptions } from './types.js';
 export type { ClarifyEngineMode, ClarifyEngineRuntime, PrepareOptions } from './types.js';
+export declare function assertNoContentDiagnostics(routes: ContentRoute[]): void;
 export declare class ClarifyEngine {
     readonly options: ClarifyBuildOptions;
     readonly root: string;

package/output/core/runtime/virtual-modules.d.ts

@@ -47,6 +47,6 @@ export declare function createClientEntryModule(options?: CreateClientEntryModul
  * type — no runtime validation is needed.
  */
 export declare function createRuntimeSlotsModule(plugins?: ClarifyPlugin[], root?: string): string;
-export declare function generateMdxErrorModule(diagnostic: ContentDiagnostic): string;
+export declare function generateContentDiagnosticModule(diagnostic: ContentDiagnostic): string;
 export declare function buildVirtualModules(args: BuildVirtualModulesArgs): VirtualModules;
 export {};

package/output/{engine-qafLfnXQ.cjs → engine-BDdPszs2.cjs}

@@ -53,6 +53,24 @@ let _apidevtools_swagger_parser = require("@apidevtools/swagger-parser");
 _apidevtools_swagger_parser = __toESM(_apidevtools_swagger_parser, 1);
 let node_os = require("node:os");
 let node_module = require("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 = (0, node_path.relative)(projectRoot, filePath);
+	return normalized && !normalized.startsWith("..") && !(0, node_path.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";
@@ -88,9 +106,18 @@ var rehypePlugins = [
 		parseMetaString: _clarify_labs_renderer.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
@@ -121,13 +148,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
+			})
 		};
 	}
 }
@@ -483,6 +510,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,
@@ -510,15 +538,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;
 }
@@ -569,28 +601,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, "", "") ?? "",
@@ -612,19 +654,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) ?? "",
@@ -869,8 +921,9 @@ var clarifySourceConfigSchema = zod.z.object({
 	branch: zod.z.string().optional(),
 	directory: zod.z.string().optional()
 });
-var clarifyPagesItemSchema = zod.z.union([
+var clarifyPagesItemSchema = zod.z.lazy(() => zod.z.union([
 	zod.z.string(),
+	clarifyPagesGroupSchema,
 	zod.z.object({
 		page: zod.z.string(),
 		path: zod.z.string().optional(),
@@ -885,12 +938,12 @@ var clarifyPagesItemSchema = zod.z.union([
 		title: clarifyLocalizedTextSchema.optional(),
 		filter: zod.z.object({ tags: zod.z.array(zod.z.string()).optional() }).optional()
 	})
-]);
-var clarifyPagesGroupSchema = zod.z.object({
+]));
+var clarifyPagesGroupSchema = zod.z.lazy(() => zod.z.object({
 	group: clarifyLocalizedTextSchema,
 	icon: zod.z.string().optional(),
 	pages: zod.z.array(clarifyPagesItemSchema)
-});
+}));
 var clarifyPagesConfigSchema = zod.z.union([zod.z.array(clarifyPagesGroupSchema), zod.z.literal("FileTree")]);
 var clarifyTabItemSchema = zod.z.object({
 	tab: clarifyLocalizedTextSchema,
@@ -1238,16 +1291,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);
 `;
@@ -1265,7 +1312,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;
@@ -1316,26 +1363,42 @@ function createNormalizedContentPlugin(engine) {
 		}
 	};
 }
-function createMdxPlugin() {
-	return (0, _mdx_js_rollup.default)({
-		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 (0, _mdx_js_rollup.default)({
-		include: ["**/*.md"],
-		format: "md",
+function createContentCompilerPlugin(format, projectRoot, errorPolicy) {
+	const markdown = format === "markdown";
+	const plugin = (0, _mdx_js_rollup.default)({
+		include: [markdown ? "**/*.md" : "**/*.mdx"],
+		format: markdown ? "md" : "mdx",
 		jsxImportSource: "react",
 		providerImportSource: "@clarify-labs/renderer",
 		remarkPlugins,
-		remarkRehypeOptions: { allowDangerousHtml: true },
-		rehypePlugins: [rehype_raw.default, ...rehypePlugins]
+		...markdown ? { remarkRehypeOptions: { allowDangerousHtml: true } } : {},
+		rehypePlugins: markdown ? [rehype_raw.default, ...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;
@@ -1457,13 +1520,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 = (0, _tailwindcss_vite.default)();
 	return [
 		...(0, _vitejs_plugin_react.default)(),
 		...Array.isArray(tailwind) ? tailwind : [tailwind],
+		compilePolicyPlugin,
 		normalizedContentPlugin,
 		createClarifyViteCorePlugin(engine, normalizedContentPlugin, markdown, mdx),
 		markdown,
@@ -1472,7 +1544,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: {
@@ -1825,9 +1897,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 (0, node_path.resolve)((0, node_url.fileURLToPath)(url)) === (0, node_path.resolve)(filePath);
@@ -1942,7 +2011,7 @@ function extractOpenAPISections(spec, filterTags) {
 	}
 	return sections;
 }
-async function readOpenAPISpec(filePath, contentProcessor) {
+async function readOpenAPISpec(filePath, contentProcessor, projectRoot) {
 	try {
 		if (!contentProcessor) return {
 			ok: true,
@@ -1965,13 +2034,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
+			})
 		};
 	}
 }
@@ -2002,31 +2072,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;
 }
@@ -2172,7 +2235,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";
@@ -2219,7 +2282,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;
@@ -3051,6 +3114,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;
@@ -3275,6 +3344,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 = (0, node_path.join)(outputDir, ".ssr");
@@ -3382,4 +3452,4 @@ Object.defineProperty(exports, "defineConfig", {
 	}
 });
 
-//# sourceMappingURL=engine-qafLfnXQ.cjs.map
+//# sourceMappingURL=engine-BDdPszs2.cjs.map