@topik/core 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { Asset, Guide, Wiki, WikiPage } from "@topik/schema";
+import { TopikContentDiagnostic } from "@topik/content-schema";
 
 //#region src/config/collection.d.ts
 declare const collectionConfigSchema: z.ZodObject<{
@@ -11,24 +12,48 @@ type CollectionConfig = z.infer<typeof collectionConfigSchema>;
 declare function parseCollectionConfig(raw: unknown): CollectionConfig;
 //#endregion
 //#region src/config/wiki.d.ts
-type WikiNavNode = string | {
-  group: string;
+type WikiPageNavNode = {
+  type: "page";
+  slug: string;
+  icon?: string;
+  hidden?: boolean;
+};
+type WikiGroupNavNode = {
+  type: "group";
+  title: string;
   slug?: string;
   icon?: string;
+  expanded?: boolean;
+  hidden?: boolean;
   children: WikiNavNode[];
-} | {
-  tab: string;
+};
+type WikiInternalSwitcherNavNode = {
+  type: "tab" | "dropdown";
+  title: string;
   slug?: string;
   icon?: string;
+  hidden?: boolean;
   children: WikiNavNode[];
-} | {
+};
+type WikiExternalSwitcherNavNode = {
+  type: "tab" | "dropdown";
+  title: string;
   href: string;
+  icon?: string;
+  hidden?: boolean;
+};
+type WikiLinkNavNode = {
+  type: "link";
   title: string;
+  href: string;
   icon?: string;
+  hidden?: boolean;
 };
+type WikiNavNode = string | WikiPageNavNode | WikiGroupNavNode | WikiInternalSwitcherNavNode | WikiExternalSwitcherNavNode | WikiLinkNavNode;
 declare const wikiConfigSchema: z.ZodObject<{
   id: z.ZodString;
   title: z.ZodString;
+  description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
   navigation: z.ZodOptional<z.ZodArray<z.ZodType<WikiNavNode, unknown, z.core.$ZodTypeInternals<WikiNavNode, unknown>>>>;
   theme: z.ZodOptional<z.ZodObject<{
     colors: z.ZodOptional<z.ZodObject<{
@@ -54,26 +79,45 @@ type ResourceType = Resource["type"];
 //#endregion
 //#region src/compile/shared.d.ts
 interface CompileResult {
+  diagnostics: TopikContentDiagnostic[];
   resources: Resource[];
 }
+type LinkValidationPolicy = "error" | "warning" | "off";
+interface CompileValidationOptions {
+  /** How unresolved wiki page links and same-page guide fragments are handled. */
+  links?: LinkValidationPolicy;
+}
+declare class CompileError extends Error {
+  readonly diagnostics: TopikContentDiagnostic[];
+  constructor(diagnostics: TopikContentDiagnostic[]);
+}
+declare function isErrorDiagnostic(diagnostic: TopikContentDiagnostic): boolean;
 //#endregion
 //#region src/compile/wiki.d.ts
 interface CompileWikiOptions {
   dir: string;
+  validation?: CompileValidationOptions;
 }
 declare function compileWiki(options: CompileWikiOptions): Promise<CompileResult>;
+declare function pagePathToName(wikiId: string, pagePath: string): string;
 //#endregion
 //#region src/compile/guide.d.ts
 interface CompileGuidesOptions {
   dir: string;
+  validation?: CompileValidationOptions;
 }
 declare function compileGuides(options: CompileGuidesOptions): Promise<CompileResult>;
 //#endregion
 //#region src/compile/index.d.ts
 interface CompileOptions {
   dir: string;
+  validation?: CompileValidationOptions;
 }
 declare function compile(options: CompileOptions): Promise<CompileResult>;
+interface LintResult {
+  diagnostics: CompileResult["diagnostics"];
+}
+declare function lint(options: CompileOptions): Promise<LintResult>;
 //#endregion
 //#region src/validate.d.ts
 interface ValidationError {
@@ -106,4 +150,4 @@ interface Watcher {
 }
 declare function watch(options: WatchOptions): Promise<Watcher>;
 //#endregion
-export { type CollectionConfig, type CompileGuidesOptions, type CompileOptions, type CompileResult, type CompileWikiOptions, type Resource, type ResourceType, type ValidationError, type ValidationResult, type WatchOptions, type Watcher, type WikiConfig, compile, compileGuides, compileWiki, parseCollectionConfig, parseWikiConfig, validateResources, watch };
+export { type CollectionConfig, CompileError, type CompileGuidesOptions, type CompileOptions, type CompileResult, type CompileValidationOptions, type CompileWikiOptions, type LinkValidationPolicy, type LintResult, type Resource, type ResourceType, type ValidationError, type ValidationResult, type WatchOptions, type Watcher, type WikiConfig, compile, compileGuides, compileWiki, isErrorDiagnostic, lint, pagePathToName, parseCollectionConfig, parseWikiConfig, validateResources, watch };

package/dist/index.mjs

@@ -1,12 +1,12 @@
 import { z } from "zod";
+import { WIKI_EXTERNAL_HREF_PATTERN, WIKI_NAV_ICON_PATTERN, assetSchema, guideSchema, joinWikiPath, wikiPageSchema, wikiSchema } from "@topik/schema";
 import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { access, readFile, readdir } from "node:fs/promises";
 import { parse } from "yaml";
 import { createHash } from "node:crypto";
-import Markdoc from "@markdoc/markdoc";
+import { analyzeTopikContent, formatTopikContent, parseTopikContent, validateTopikContent } from "@topik/content-schema";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
-import { assetSchema, guideSchema, wikiPageSchema, wikiSchema } from "@topik/schema";
 import { EventEmitter } from "node:events";
 import { watch as watch$1 } from "chokidar";
 //#region src/config/collection.ts
@@ -20,27 +20,125 @@ function parseCollectionConfig(raw) {
 }
 //#endregion
 //#region src/config/wiki.ts
+const wikiNavIconPattern = new RegExp(WIKI_NAV_ICON_PATTERN);
+const wikiExternalHrefPattern = new RegExp(WIKI_EXTERNAL_HREF_PATTERN);
+const pathSegment = z.string().min(1).max(256).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Slugs must be lowercase DNS-style segments");
 const wikiPagePath = z.string().min(1).max(512).regex(/^(?:[a-z0-9]+(?:-[a-z0-9]+)*)(?:\/(?:[a-z0-9]+(?:-[a-z0-9]+)*))*$/, "Wiki page paths must use lowercase DNS-style segments separated by '/'");
-const navNodeSchema = z.union([
+const title = z.string().min(1).max(256);
+const icon = z.string().min(1).max(256).regex(wikiNavIconPattern, "Icons must be lowercase DNS-style names").optional();
+const href = z.string().max(2048).refine((value) => {
+	if (!wikiExternalHrefPattern.test(value)) return false;
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" || url.protocol === "http:";
+	} catch {
+		return false;
+	}
+}, { message: "href must be a valid http or https URL" });
+const navNodeSchema = z.lazy(() => z.union([
 	wikiPagePath,
 	z.object({
-		group: z.string().min(1).max(256),
-		slug: z.string().min(1).max(256).optional(),
-		icon: z.string().min(1).max(256).optional(),
-		children: z.lazy(() => z.array(navNodeSchema)).default([])
-	}),
+		type: z.literal("page"),
+		slug: wikiPagePath,
+		icon,
+		hidden: z.boolean().optional()
+	}).strict(),
 	z.object({
-		tab: z.string().min(1).max(256),
-		slug: z.string().min(1).max(256).optional(),
-		icon: z.string().min(1).max(256).optional(),
-		children: z.lazy(() => z.array(navNodeSchema)).default([])
-	}),
+		type: z.literal("group"),
+		title,
+		slug: pathSegment.optional(),
+		icon,
+		expanded: z.boolean().optional(),
+		hidden: z.boolean().optional(),
+		children: z.array(navNodeSchema).default([])
+	}).strict(),
 	z.object({
-		href: z.string().max(2048).refine((v) => v.startsWith("https://") || v.startsWith("http://"), { message: "href must be an http or https URL" }),
-		title: z.string().min(1).max(256),
-		icon: z.string().min(1).max(256).optional()
-	})
-]);
+		type: z.union([z.literal("tab"), z.literal("dropdown")]),
+		title,
+		slug: pathSegment.optional(),
+		icon,
+		hidden: z.boolean().optional(),
+		children: z.array(navNodeSchema).default([])
+	}).strict(),
+	z.object({
+		type: z.union([z.literal("tab"), z.literal("dropdown")]),
+		title,
+		href,
+		icon,
+		hidden: z.boolean().optional()
+	}).strict(),
+	z.object({
+		type: z.literal("link"),
+		title,
+		href,
+		icon,
+		hidden: z.boolean().optional()
+	}).strict()
+]));
+function nodeKind(node) {
+	if (typeof node !== "string" && node.type === "tab") return "tab";
+	if (typeof node !== "string" && node.type === "dropdown") return "dropdown";
+	return "sidebar";
+}
+function validateHomogeneousLevel(nodes, allowed, path, context) {
+	const kinds = nodes.map(nodeKind);
+	nodes.forEach((_node, index) => {
+		const kind = kinds[index];
+		if (!allowed.has(kind)) {
+			const nodePath = [...path, index];
+			context.addIssue({
+				code: "custom",
+				path: nodePath,
+				message: `Navigation ${kind} nodes are not allowed at ${formatConfigPath(nodePath)}`
+			});
+		}
+	});
+	const expectedKind = kinds[0];
+	kinds.forEach((kind, index) => {
+		if (kind === expectedKind) return;
+		const nodePath = [...path, index];
+		context.addIssue({
+			code: "custom",
+			path: nodePath,
+			message: `Navigation surfaces cannot be mixed at the same level: expected ${expectedKind}, found ${kind} at ${formatConfigPath(nodePath)}`
+		});
+	});
+	nodes.forEach((node, index) => {
+		if (typeof node === "string" || !("children" in node)) return;
+		const childPath = [
+			...path,
+			index,
+			"children"
+		];
+		if (node.type === "tab") validateHomogeneousLevel(node.children, /* @__PURE__ */ new Set(["dropdown", "sidebar"]), childPath, context);
+		else validateHomogeneousLevel(node.children, /* @__PURE__ */ new Set(["sidebar"]), childPath, context);
+	});
+}
+function validateUniquePageRoutes(nodes, path, context, prefix = "", routes = /* @__PURE__ */ new Map()) {
+	nodes.forEach((node, index) => {
+		const nodePath = [...path, index];
+		if (typeof node === "string" || node.type === "page") {
+			const sourcePath = joinNavigationPath(prefix, typeof node === "string" ? node : node.slug);
+			const route = sourcePath === "index" ? "" : sourcePath.replace(/\/index$/, "");
+			const previousPath = routes.get(route);
+			if (previousPath) context.addIssue({
+				code: "custom",
+				path: nodePath,
+				message: `Navigation contains duplicate page route /${route}: first defined at ${formatConfigPath(previousPath)}, duplicated at ${formatConfigPath(nodePath)}`
+			});
+			else routes.set(route, nodePath);
+			return;
+		}
+		if ("children" in node) validateUniquePageRoutes(node.children, [...nodePath, "children"], context, joinNavigationPath(prefix, node.slug), routes);
+	});
+}
+function formatConfigPath(path) {
+	return path.reduce((formatted, segment) => typeof segment === "number" ? `${formatted}[${segment}]` : formatted ? `${formatted}.${segment}` : segment, "");
+}
+function joinNavigationPath(prefix, path) {
+	if (!path) return prefix;
+	return prefix ? `${prefix}/${path}` : path;
+}
 const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/, "Must be a hex color (e.g. #ff73a8)");
 const themeSchema = z.object({
 	colors: z.object({
@@ -54,11 +152,23 @@ const themeSchema = z.object({
 		"system"
 	]).optional() }).optional()
 });
+const nameRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_WIKI_ID_FOR_PAGE_NAMES = 46;
 const wikiConfigSchema = z.object({
-	id: z.string().min(1).max(63).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+	id: z.string().min(1).max(MAX_WIKI_ID_FOR_PAGE_NAMES, `Wiki id must be ${MAX_WIKI_ID_FOR_PAGE_NAMES} characters or fewer`).regex(nameRegex),
 	title: z.string().min(1).max(256),
+	description: z.union([z.string().max(1024), z.null()]).optional(),
 	navigation: z.array(navNodeSchema).optional(),
 	theme: themeSchema.optional()
+}).superRefine((config, context) => {
+	if (config.navigation) {
+		validateHomogeneousLevel(config.navigation, /* @__PURE__ */ new Set([
+			"tab",
+			"dropdown",
+			"sidebar"
+		]), ["navigation"], context);
+		validateUniquePageRoutes(config.navigation, ["navigation"], context);
+	}
 });
 function parseWikiConfig(raw) {
 	return wikiConfigSchema.parse(raw);
@@ -124,10 +234,14 @@ const MIME_BY_EXT = {
 	".ppt": "application/vnd.ms-powerpoint",
 	".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
 };
-const ASSET_TAG_ATTRS = ["src", "href"];
+const ASSET_TAG_ATTRS = [
+	"src",
+	"darkSrc",
+	"href"
+];
 async function extractAssets(source, options) {
 	const { baseDir, filePath } = options;
-	const ast = Markdoc.parse(source);
+	const ast = parseTopikContent(source);
 	const refs = /* @__PURE__ */ new Map();
 	const slots = /* @__PURE__ */ new Map();
 	const collect = (url, slot, requireKnownExtension) => {
@@ -203,7 +317,7 @@ async function extractAssets(source, options) {
 		for (const slot of slotList) slot.node.attributes[slot.attr] = `asset:${id}`;
 	}
 	return {
-		content: Markdoc.format(ast),
+		content: formatTopikContent(ast),
 		assets: Array.from(byName.values()),
 		manifest
 	};
@@ -269,7 +383,8 @@ async function toAsset(ref) {
 	const integrity = `sha256-${digest.toString("base64")}`;
 	const name = digest.toString("hex").slice(0, 16);
 	const extMatch = /\.([a-z0-9]+)(?:[?#].*)?$/i.exec(ref.relFromBase);
-	const mediaType = MIME_BY_EXT[extMatch ? `.${extMatch[1].toLowerCase()}` : ""];
+	const ext = extMatch ? `.${extMatch[1].toLowerCase()}` : "";
+	const mediaType = MIME_BY_EXT[ext];
 	return {
 		apiVersion: "v1",
 		type: "Asset",
@@ -283,6 +398,27 @@ async function toAsset(ref) {
 }
 //#endregion
 //#region src/compile/shared.ts
+var CompileError = class extends Error {
+	diagnostics;
+	constructor(diagnostics) {
+		super(formatContentDiagnostics(diagnostics));
+		this.diagnostics = diagnostics;
+		this.name = "CompileError";
+	}
+};
+function linkValidationPolicy(options) {
+	return options?.links ?? "error";
+}
+function isErrorDiagnostic(diagnostic) {
+	return diagnostic.level === "error" || diagnostic.level === "critical";
+}
+function hasCompileErrors(diagnostics) {
+	return diagnostics.some(isErrorDiagnostic);
+}
+function throwOnCompileErrors(diagnostics) {
+	const errors = diagnostics.filter(isErrorDiagnostic);
+	if (errors.length > 0) throw new CompileError(errors);
+}
 const DNS_LABEL_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function parseMarkdownFrontmatter(raw, filePath) {
 	const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
@@ -312,6 +448,11 @@ function extractMarkdownTitle(content, fallback) {
 	if (match) return match[1].trim();
 	return fallback.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
+function formatContentDiagnostics(diagnostics) {
+	return diagnostics.filter(isErrorDiagnostic).map((diagnostic) => {
+		return `${diagnostic.file ?? "content"}${diagnostic.lines.length > 0 ? `:${diagnostic.lines.join(",")}` : ""} ${diagnostic.level} ${diagnostic.id}: ${diagnostic.message}`;
+	}).join("\n");
+}
 function parseReferenceList(value, fieldName, filePath) {
 	if (value == null) return;
 	if (!Array.isArray(value)) throw new Error(`${fieldName} in ${filePath} must be an array of resource names`);
@@ -323,15 +464,99 @@ function parseReferenceList(value, fieldName, filePath) {
 	return references.length > 0 ? references : void 0;
 }
 //#endregion
+//#region src/compile/links.ts
+const NON_PAGE_SCHEME = /^(?:asset|https?|mailto|tel):/i;
+const LINK_BASE = "https://topik.local";
+function validateWikiLinks(pages, policy) {
+	if (policy === "off") return [];
+	const level = policy === "error" ? "error" : "warning";
+	const pagesBySlug = new Map(pages.map((page) => [page.slug, page]));
+	const diagnostics = [];
+	for (const page of pages) for (const link of page.analysis.links) {
+		if (NON_PAGE_SCHEME.test(link.href)) continue;
+		const target = resolveInternalTarget(link.href, page.sourcePath);
+		if (!target) continue;
+		const targetPage = pagesBySlug.get(target.slug);
+		if (!targetPage) {
+			diagnostics.push(linkDiagnostic("link-page-not-found", level, `Internal link '${link.href}' resolves to missing page '/${target.slug}'.`, link));
+			continue;
+		}
+		if (target.fragment && !targetPage.analysis.headings.some((heading) => heading.id === target.fragment)) diagnostics.push(linkDiagnostic("link-fragment-not-found", level, `Internal link '${link.href}' references missing heading '#${target.fragment}' on '/${target.slug}'.`, link));
+	}
+	return diagnostics;
+}
+function validateLocalFragments(analysis, policy) {
+	if (policy === "off") return [];
+	const level = policy === "error" ? "error" : "warning";
+	const headingIds = new Set(analysis.headings.map((heading) => heading.id));
+	const diagnostics = [];
+	for (const link of analysis.links) {
+		if (!link.href.startsWith("#") || link.href === "#") continue;
+		const fragment = decodeFragment(link.href.slice(1));
+		if (fragment && !headingIds.has(fragment)) diagnostics.push(linkDiagnostic("link-fragment-not-found", level, `Link '${link.href}' references a missing heading in this document.`, link));
+	}
+	return diagnostics;
+}
+function resolveInternalTarget(href, sourcePath) {
+	let url;
+	try {
+		url = new URL(href, `${LINK_BASE}/${sourcePath}`);
+	} catch {
+		return;
+	}
+	if (url.origin !== LINK_BASE) return void 0;
+	return {
+		fragment: decodeFragment(url.hash.slice(1)),
+		slug: decodePath(url.pathname)
+	};
+}
+function decodeFragment(value) {
+	if (!value) return "";
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+function decodePath(pathname) {
+	const normalized = pathname.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean).map((segment) => {
+		try {
+			return decodeURIComponent(segment);
+		} catch {
+			return segment;
+		}
+	}).join("/").replace(/\.(?:mdx?|markdown)$/i, "");
+	if (normalized === "index") return "";
+	return normalized.replace(/\/index$/, "");
+}
+function linkDiagnostic(id, level, message, link) {
+	return {
+		id,
+		type: link.kind,
+		level,
+		message,
+		lines: link.lines,
+		...link.file ? { file: link.file } : {}
+	};
+}
+//#endregion
 //#region src/compile/wiki.ts
 async function compileWiki(options) {
+	const result = await inspectWiki(options);
+	throwOnCompileErrors(result.diagnostics);
+	return result;
+}
+async function inspectWiki(options) {
 	const dir = resolve(options.dir);
 	const raw = await readOptionalConfigFile(dir, [
 		"wiki.yaml",
 		"wiki.yml",
 		"wiki.json"
 	]);
-	if (raw == null) return { resources: [] };
+	if (raw == null) return {
+		diagnostics: [],
+		resources: []
+	};
 	const config = parseWikiConfig(raw);
 	const pagePaths = config.navigation ? [...new Set(collectPagePaths(config.navigation))] : [];
 	const resolvedFiles = await Promise.all(pagePaths.map(async (pagePath) => {
@@ -342,25 +567,39 @@ async function compileWiki(options) {
 		};
 	}));
 	const resources = [];
+	const diagnostics = [];
+	const pageAnalyses = [];
 	const assetsById = /* @__PURE__ */ new Map();
 	for (let i = 0; i < pagePaths.length; i++) {
 		const pagePath = pagePaths[i];
 		const { filePath, raw } = resolvedFiles[i];
 		const { frontmatter, content } = parseMarkdownFrontmatter(raw, pagePath);
+		const validation = validateTopikContent(content, { file: filePath });
+		diagnostics.push(...validation.errors);
+		if (!validation.valid) continue;
 		const { content: rewritten, assets, manifest } = await extractAssets(content, {
 			baseDir: dir,
 			filePath
 		});
 		for (const asset of assets) if (!assetsById.has(asset.name)) assetsById.set(asset.name, asset);
-		const name = pagePathToName(pagePath);
-		const title = typeof frontmatter.title === "string" ? frontmatter.title : extractMarkdownTitle(rewritten, name);
+		const name = pagePathToName(config.id, pagePath);
+		const title = typeof frontmatter.title === "string" ? frontmatter.title : extractMarkdownTitle(rewritten, pagePathToTitleFallback(pagePath));
+		const description = normalizeWikiPageDescription(frontmatter.description);
+		const analysis = analyzeTopikContent(rewritten, { file: filePath });
+		diagnostics.push(...analysis.diagnostics);
+		pageAnalyses.push({
+			analysis,
+			slug: pagePathToSlug(pagePath),
+			sourcePath: pagePath
+		});
 		const pageResource = {
 			apiVersion: "v1",
 			type: "WikiPage",
-			name: `${config.id}-${name}`,
+			name,
 			spec: {
 				wiki: config.id,
 				title,
+				...description != null ? { description } : {},
 				content: {
 					format: "topik",
 					value: rewritten
@@ -377,17 +616,25 @@ async function compileWiki(options) {
 		name: config.id,
 		spec: {
 			title: config.title,
+			...config.description != null ? { description: config.description } : {},
 			...config.navigation ? { navigation: resolveNavigation(config.navigation, config.id) } : {},
 			...config.theme ? { theme: config.theme } : {}
 		}
 	};
 	resources.push(wikiResource);
-	return { resources };
+	if (!hasCompileErrors(diagnostics)) diagnostics.push(...validateWikiLinks(pageAnalyses, linkValidationPolicy(options.validation)));
+	return {
+		diagnostics,
+		resources
+	};
 }
-function collectPagePaths(nodes) {
+function normalizeWikiPageDescription(description) {
+	return typeof description === "string" ? description.slice(0, 1024) : void 0;
+}
+function collectPagePaths(nodes, prefix = "") {
 	const paths = [];
-	for (const node of nodes) if (typeof node === "string") paths.push(node);
-	else if ("group" in node || "tab" in node) paths.push(...collectPagePaths(node.children));
+	for (const node of nodes) if (typeof node === "string" || node.type === "page") paths.push(joinWikiPath(prefix, typeof node === "string" ? node : node.slug));
+	else if ("children" in node) paths.push(...collectPagePaths(node.children, joinWikiPath(prefix, node.slug)));
 	return paths;
 }
 async function resolveFilePath(dir, pagePath) {
@@ -404,52 +651,110 @@ function pagePathToSlug(pagePath) {
 	if (pagePath === "index") return "";
 	return pagePath.replace(/\/index$/, "");
 }
-function pagePathToName(pagePath) {
-	return pagePath.replace(/^\//, "").replaceAll("/", "-");
+function pagePathToName(wikiId, pagePath) {
+	const normalizedPath = normalizePagePath(pagePath);
+	return `${wikiId}-${createHash("sha256").update(normalizedPath).digest("hex").slice(0, 16)}`;
 }
-function resolveNavigation(nodes, wikiId) {
+function resolveNavigation(nodes, wikiId, prefix = "") {
 	return nodes.map((node) => {
-		if (typeof node === "string") return {
-			type: "page",
-			page: `${wikiId}-${pagePathToName(node)}`,
-			slug: pagePathToSlug(node)
-		};
-		if ("group" in node || "tab" in node) {
-			const isTab = "tab" in node;
-			const title = isTab ? node.tab : node.group;
+		if (typeof node === "string" || node.type === "page") {
+			const localPath = typeof node === "string" ? node : node.slug;
+			const pagePath = joinWikiPath(prefix, localPath);
 			return {
-				type: isTab ? "tab" : "group",
-				title,
+				type: "page",
+				page: pagePathToName(wikiId, pagePath),
+				slug: pagePathToSlug(localPath),
+				sourcePath: pagePath,
+				...typeof node !== "string" && node.icon ? { icon: node.icon } : {},
+				...typeof node !== "string" && node.hidden ? { hidden: true } : {}
+			};
+		}
+		if ("children" in node) {
+			const children = resolveNavigation(node.children, wikiId, joinWikiPath(prefix, node.slug));
+			if (node.type === "group") return {
+				type: "group",
+				title: node.title,
+				...node.slug ? { slug: node.slug } : {},
+				...node.icon ? { icon: node.icon } : {},
+				...node.hidden ? { hidden: true } : {},
+				...node.expanded ? { expanded: true } : {},
+				children
+			};
+			if (node.type === "tab") return {
+				type: "tab",
+				title: node.title,
 				...node.slug ? { slug: node.slug } : {},
 				...node.icon ? { icon: node.icon } : {},
-				children: resolveNavigation(node.children, wikiId)
+				...node.hidden ? { hidden: true } : {},
+				children
+			};
+			return {
+				type: "dropdown",
+				title: node.title,
+				...node.slug ? { slug: node.slug } : {},
+				...node.icon ? { icon: node.icon } : {},
+				...node.hidden ? { hidden: true } : {},
+				children
 			};
 		}
+		if (node.type === "tab") return {
+			type: "tab",
+			title: node.title,
+			href: node.href,
+			...node.icon ? { icon: node.icon } : {},
+			...node.hidden ? { hidden: true } : {}
+		};
+		if (node.type === "dropdown") return {
+			type: "dropdown",
+			title: node.title,
+			href: node.href,
+			...node.icon ? { icon: node.icon } : {},
+			...node.hidden ? { hidden: true } : {}
+		};
 		return {
 			type: "link",
 			title: node.title,
 			href: node.href,
-			...node.icon ? { icon: node.icon } : {}
+			...node.icon ? { icon: node.icon } : {},
+			...node.hidden ? { hidden: true } : {}
 		};
 	});
 }
+function normalizePagePath(pagePath) {
+	return pagePath.replace(/^\//, "").replace(/\.(?:mdx?|markdown)$/i, "");
+}
+function pagePathToTitleFallback(pagePath) {
+	return normalizePagePath(pagePath).replaceAll("/", "-");
+}
 //#endregion
 //#region src/compile/guide.ts
 async function compileGuides(options) {
+	const result = await inspectGuides(options);
+	throwOnCompileErrors(result.diagnostics);
+	return result;
+}
+async function inspectGuides(options) {
 	const dir = resolve(options.dir);
 	const raw = await readOptionalConfigFile(dir, [
 		"collection.yaml",
 		"collection.yml",
 		"collection.json"
 	]);
-	if (raw == null) return { resources: [] };
+	if (raw == null) return {
+		diagnostics: [],
+		resources: []
+	};
 	const config = parseCollectionConfig(raw);
 	const markdownFiles = (await readdir(dir)).filter((f) => f.endsWith(".md") || f.endsWith(".mdx")).sort();
 	const resources = [];
+	const diagnostics = [];
 	const assetsById = /* @__PURE__ */ new Map();
 	for (const file of markdownFiles) {
 		const filePath = join(dir, file);
 		const { frontmatter, content } = parseMarkdownFrontmatter(await readFile(filePath, "utf-8"), file);
+		const validation = validateTopikContent(content, { file: filePath });
+		diagnostics.push(...validation.errors);
+		if (!validation.valid) continue;
 		const { content: rewritten, assets, manifest } = await extractAssets(content, {
 			baseDir: dir,
 			filePath
@@ -461,6 +766,9 @@ async function compileGuides(options) {
 		const tags = mergeTags(config.tags, frontmatter.tags);
 		const authors = parseReferenceList(frontmatter.authors, "authors", file);
 		const description = typeof frontmatter.description === "string" ? frontmatter.description : void 0;
+		const analysis = analyzeTopikContent(rewritten, { file: filePath });
+		diagnostics.push(...analysis.diagnostics);
+		diagnostics.push(...validateLocalFragments(analysis, linkValidationPolicy(options.validation)));
 		const guide = {
 			apiVersion: "v1",
 			type: "Guide",
@@ -481,7 +789,10 @@ async function compileGuides(options) {
 		resources.push(guide);
 	}
 	for (const asset of assetsById.values()) resources.push(asset);
-	return { resources };
+	return {
+		diagnostics,
+		resources
+	};
 }
 function fileToSlug(filename) {
 	return filename.replace(/\.(mdx?|md)$/, "");
@@ -509,15 +820,40 @@ const COLLECTION_CONFIG_FILES = [
 async function compile(options) {
 	const dir = resolve(options.dir);
 	const resources = [];
+	const diagnostics = [];
 	if (await findConfigFile(dir, WIKI_CONFIG_FILES)) {
-		const result = await compileWiki({ dir });
+		const result = await compileWiki({
+			dir,
+			validation: options.validation
+		});
 		resources.push(...result.resources);
+		diagnostics.push(...result.diagnostics);
 	}
 	if (await findConfigFile(dir, COLLECTION_CONFIG_FILES)) {
-		const result = await compileGuides({ dir });
+		const result = await compileGuides({
+			dir,
+			validation: options.validation
+		});
 		resources.push(...result.resources);
+		diagnostics.push(...result.diagnostics);
 	}
-	return { resources };
+	return {
+		diagnostics,
+		resources
+	};
+}
+async function lint(options) {
+	const dir = resolve(options.dir);
+	const diagnostics = [];
+	if (await findConfigFile(dir, WIKI_CONFIG_FILES)) diagnostics.push(...(await inspectWiki({
+		dir,
+		validation: options.validation
+	})).diagnostics);
+	if (await findConfigFile(dir, COLLECTION_CONFIG_FILES)) diagnostics.push(...(await inspectGuides({
+		dir,
+		validation: options.validation
+	})).diagnostics);
+	return { diagnostics };
 }
 //#endregion
 //#region src/validate.ts
@@ -641,4 +977,4 @@ async function watch(options) {
 	return watcher;
 }
 //#endregion
-export { compile, compileGuides, compileWiki, parseCollectionConfig, parseWikiConfig, validateResources, watch };
+export { CompileError, compile, compileGuides, compileWiki, isErrorDiagnostic, lint, pagePathToName, parseCollectionConfig, parseWikiConfig, validateResources, watch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topik/core",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "Topik core library",
   "license": "MIT",
   "repository": {
@@ -20,20 +20,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@markdoc/markdoc": "^0.5.7",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "chokidar": "^5.0.0",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6",
-    "@topik/schema": "0.1.0-alpha.3"
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3",
+    "@topik/content-schema": "0.1.0-alpha.4",
+    "@topik/schema": "0.1.0-alpha.4"
   },
   "devDependencies": {
-    "@types/node": "^24",
-    "@typescript/native-preview": "7.0.0-dev.20260427.1",
-    "typescript": "^6",
-    "vite-plus": "^0.1.18",
-    "vitest": "npm:@voidzero-dev/vite-plus-test@latest"
+    "@types/node": "22.20.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "typescript": "^6.0.3",
+    "vite-plus": "0.2.4"
   },
   "scripts": {
     "build": "vp pack",