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

package/dist/index.d.mts

@@ -1,141 +1,123 @@
 import { z } from "zod";
-import { Guide, Wiki, WikiPage } from "@topik/schema";
+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<{
   id: z.ZodString;
   title: z.ZodString;
-  tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-  id: string;
-  title: string;
-  tags?: string[] | undefined;
-}, {
-  id: string;
-  title: string;
-  tags?: string[] | undefined;
-}>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
 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;
-  navigation: z.ZodOptional<z.ZodArray<z.ZodType<WikiNavNode, z.ZodTypeDef, unknown>, "many">>;
+  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<{
       primary: z.ZodString;
       light: z.ZodOptional<z.ZodString>;
       dark: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-      primary: string;
-      light?: string | undefined;
-      dark?: string | undefined;
-    }, {
-      primary: string;
-      light?: string | undefined;
-      dark?: string | undefined;
-    }>>;
+    }, z.core.$strip>>;
     appearance: z.ZodOptional<z.ZodObject<{
-      default: z.ZodOptional<z.ZodEnum<["light", "dark", "system"]>>;
-    }, "strip", z.ZodTypeAny, {
-      default?: "dark" | "light" | "system" | undefined;
-    }, {
-      default?: "dark" | "light" | "system" | undefined;
-    }>>;
-  }, "strip", z.ZodTypeAny, {
-    colors?: {
-      primary: string;
-      light?: string | undefined;
-      dark?: string | undefined;
-    } | undefined;
-    appearance?: {
-      default?: "dark" | "light" | "system" | undefined;
-    } | undefined;
-  }, {
-    colors?: {
-      primary: string;
-      light?: string | undefined;
-      dark?: string | undefined;
-    } | undefined;
-    appearance?: {
-      default?: "dark" | "light" | "system" | undefined;
-    } | undefined;
-  }>>;
-}, "strip", z.ZodTypeAny, {
-  id: string;
-  title: string;
-  navigation?: WikiNavNode[] | undefined;
-  theme?: {
-    colors?: {
-      primary: string;
-      light?: string | undefined;
-      dark?: string | undefined;
-    } | undefined;
-    appearance?: {
-      default?: "dark" | "light" | "system" | undefined;
-    } | undefined;
-  } | undefined;
-}, {
-  id: string;
-  title: string;
-  navigation?: unknown[] | undefined;
-  theme?: {
-    colors?: {
-      primary: string;
-      light?: string | undefined;
-      dark?: string | undefined;
-    } | undefined;
-    appearance?: {
-      default?: "dark" | "light" | "system" | undefined;
-    } | undefined;
-  } | undefined;
-}>;
+      default: z.ZodOptional<z.ZodEnum<{
+        dark: "dark";
+        light: "light";
+        system: "system";
+      }>>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
 type WikiConfig = z.infer<typeof wikiConfigSchema>;
 declare function parseWikiConfig(raw: unknown): WikiConfig;
 //#endregion
 //#region src/resource.d.ts
-type Resource = Guide | Wiki | WikiPage;
+type Resource = Asset | Guide | Wiki | WikiPage;
 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 {
@@ -168,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,10 +1,12 @@
 import { z } from "zod";
-import { join, resolve } from "node:path";
+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 { analyzeTopikContent, formatTopikContent, parseTopikContent, validateTopikContent } from "@topik/content-schema";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
-import { guideSchema, wikiPageSchema, wikiSchema } from "@topik/schema";
 import { EventEmitter } from "node:events";
 import { watch as watch$1 } from "chokidar";
 //#region src/config/collection.ts
@@ -18,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({
+		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({
+		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({
-		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.union([z.literal("tab"), z.literal("dropdown")]),
+		title,
+		href,
+		icon,
+		hidden: z.boolean().optional()
+	}).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.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({
@@ -52,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);
@@ -91,7 +203,222 @@ async function findConfigFile(dir, candidates) {
 	return null;
 }
 //#endregion
+//#region src/compile/assets.ts
+const MIME_BY_EXT = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".svg": "image/svg+xml",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".ico": "image/x-icon",
+	".bmp": "image/bmp",
+	".mp4": "video/mp4",
+	".webm": "video/webm",
+	".pdf": "application/pdf",
+	".zip": "application/zip",
+	".tar": "application/x-tar",
+	".gz": "application/gzip",
+	".mp3": "audio/mpeg",
+	".wav": "audio/wav",
+	".ogg": "audio/ogg",
+	".m4a": "audio/mp4",
+	".flac": "audio/flac",
+	".csv": "text/csv",
+	".txt": "text/plain",
+	".doc": "application/msword",
+	".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+	".xls": "application/vnd.ms-excel",
+	".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+	".ppt": "application/vnd.ms-powerpoint",
+	".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+};
+const ASSET_TAG_ATTRS = [
+	"src",
+	"darkSrc",
+	"href"
+];
+async function extractAssets(source, options) {
+	const { baseDir, filePath } = options;
+	const ast = parseTopikContent(source);
+	const refs = /* @__PURE__ */ new Map();
+	const slots = /* @__PURE__ */ new Map();
+	const collect = (url, slot, requireKnownExtension) => {
+		if (!isLocalRef(url)) return;
+		if (requireKnownExtension && !hasKnownAssetExtension(url)) return;
+		if (!refs.has(url)) {
+			const absPath = resolveAssetPath(url, {
+				baseDir,
+				filePath
+			});
+			const relFromBase = relative(baseDir, absPath).split(sep).join(posix.sep);
+			refs.set(url, {
+				original: url,
+				absPath,
+				relFromBase
+			});
+		}
+		const list = slots.get(url) ?? [];
+		list.push(slot);
+		slots.set(url, list);
+	};
+	walk(ast, (node) => {
+		if (node.type === "image") {
+			const url = stringAttr(node, "src");
+			if (url) collect(url, {
+				node,
+				attr: "src"
+			}, false);
+		} else if (node.type === "link") {
+			const url = stringAttr(node, "href");
+			if (url) collect(url, {
+				node,
+				attr: "href"
+			}, true);
+		} else if (node.type === "tag") for (const attr of ASSET_TAG_ATTRS) {
+			const url = stringAttr(node, attr);
+			if (url) collect(url, {
+				node,
+				attr
+			}, true);
+		}
+	});
+	if (refs.size === 0) return {
+		content: source,
+		assets: [],
+		manifest: []
+	};
+	const urlToId = /* @__PURE__ */ new Map();
+	const byName = /* @__PURE__ */ new Map();
+	const refList = Array.from(refs.values());
+	const settled = await Promise.allSettled(refList.map((ref) => toAsset(ref)));
+	const failures = [];
+	for (let i = 0; i < settled.length; i++) {
+		const result = settled[i];
+		if (result.status === "fulfilled") {
+			urlToId.set(refList[i].original, result.value.name);
+			byName.set(result.value.name, result.value);
+		} else failures.push(result.reason instanceof Error ? result.reason.message : String(result.reason));
+	}
+	if (failures.length > 0) throw new Error(`Failed to extract ${failures.length} asset(s):\n  - ${failures.join("\n  - ")}`);
+	const manifest = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const ref of refs.values()) {
+		const name = urlToId.get(ref.original);
+		if (name && !seen.has(name)) {
+			manifest.push(name);
+			seen.add(name);
+		}
+	}
+	for (const [url, slotList] of slots.entries()) {
+		const id = urlToId.get(url);
+		if (!id) continue;
+		for (const slot of slotList) slot.node.attributes[slot.attr] = `asset:${id}`;
+	}
+	return {
+		content: formatTopikContent(ast),
+		assets: Array.from(byName.values()),
+		manifest
+	};
+}
+function walk(node, fn) {
+	fn(node);
+	for (const child of node.children) walk(child, fn);
+}
+function stringAttr(node, attr) {
+	const value = node.attributes?.[attr];
+	return typeof value === "string" ? value : void 0;
+}
+function hasKnownAssetExtension(url) {
+	const [path] = splitUrl(url);
+	const decoded = decodeSafe(path);
+	const m = /\.([a-z0-9]+)$/i.exec(decoded);
+	if (!m) return false;
+	return `.${m[1].toLowerCase()}` in MIME_BY_EXT;
+}
+function isLocalRef(url) {
+	if (url.length === 0) return false;
+	if (url.startsWith("#")) return false;
+	if (url.startsWith("mailto:")) return false;
+	if (url.startsWith("tel:")) return false;
+	if (url.startsWith("data:")) return false;
+	if (url.startsWith("//")) return false;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(url)) return false;
+	return true;
+}
+function resolveAssetPath(url, { baseDir, filePath }) {
+	const [pathPart] = splitUrl(url);
+	const decoded = decodeSafe(pathPart);
+	const absolute = resolve(isAbsolute(decoded) || decoded.startsWith("/") ? baseDir : dirname(filePath), decoded.replace(/^\/+/, ""));
+	const rel = relative(baseDir, absolute);
+	if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`Asset reference "${url}" in ${filePath} resolves outside the compilation directory`);
+	return absolute;
+}
+function splitUrl(url) {
+	const hashIdx = url.indexOf("#");
+	const queryIdx = url.indexOf("?");
+	let cut = -1;
+	if (hashIdx >= 0) cut = hashIdx;
+	if (queryIdx >= 0 && (cut < 0 || queryIdx < cut)) cut = queryIdx;
+	if (cut < 0) return [url, ""];
+	return [url.slice(0, cut), url.slice(cut)];
+}
+function decodeSafe(s) {
+	try {
+		return decodeURIComponent(s);
+	} catch {
+		return s;
+	}
+}
+async function toAsset(ref) {
+	let bytes;
+	try {
+		bytes = await readFile(ref.absPath);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Asset "${ref.original}" not found at ${ref.absPath}: ${message}`, { cause: error });
+	}
+	const digest = createHash("sha256").update(bytes).digest();
+	const integrity = `sha256-${digest.toString("base64")}`;
+	const name = digest.toString("hex").slice(0, 16);
+	const extMatch = /\.([a-z0-9]+)(?:[?#].*)?$/i.exec(ref.relFromBase);
+	const ext = extMatch ? `.${extMatch[1].toLowerCase()}` : "";
+	const mediaType = MIME_BY_EXT[ext];
+	return {
+		apiVersion: "v1",
+		type: "Asset",
+		name,
+		spec: {
+			uri: ref.relFromBase,
+			integrity,
+			...mediaType ? { mediaType } : {}
+		}
+	};
+}
+//#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]*)$/);
@@ -121,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`);
@@ -132,58 +464,177 @@ 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 fileContents = await Promise.all(pagePaths.map(async (pagePath) => {
-		return readFile(await resolveFilePath(dir, pagePath), "utf-8");
+	const resolvedFiles = await Promise.all(pagePaths.map(async (pagePath) => {
+		const filePath = await resolveFilePath(dir, pagePath);
+		return {
+			filePath,
+			raw: await readFile(filePath, "utf-8")
+		};
 	}));
 	const resources = [];
+	const diagnostics = [];
+	const pageAnalyses = [];
+	const assetsById = /* @__PURE__ */ new Map();
 	for (let i = 0; i < pagePaths.length; i++) {
 		const pagePath = pagePaths[i];
-		const { frontmatter, content } = parseMarkdownFrontmatter(fileContents[i], pagePath);
-		const name = pagePathToName(pagePath);
-		const title = typeof frontmatter.title === "string" ? frontmatter.title : extractMarkdownTitle(content, name);
+		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(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: content
-				}
+					value: rewritten
+				},
+				...manifest.length > 0 ? { assets: manifest } : {}
 			}
 		};
 		resources.push(pageResource);
 	}
+	for (const asset of assetsById.values()) resources.push(asset);
 	const wikiResource = {
 		apiVersion: "v1",
 		type: "Wiki",
 		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 normalizeWikiPageDescription(description) {
+	return typeof description === "string" ? description.slice(0, 1024) : void 0;
 }
-function collectPagePaths(nodes) {
+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) {
@@ -200,56 +651,124 @@ 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 } : {},
+				...node.hidden ? { hidden: true } : {},
+				children
+			};
+			return {
+				type: "dropdown",
+				title: node.title,
 				...node.slug ? { slug: node.slug } : {},
 				...node.icon ? { icon: node.icon } : {},
-				children: resolveNavigation(node.children, wikiId)
+				...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 { frontmatter, content } = parseMarkdownFrontmatter(await readFile(join(dir, file), "utf-8"), file);
+		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
+		});
+		for (const asset of assets) if (!assetsById.has(asset.name)) assetsById.set(asset.name, asset);
 		const slug = fileToSlug(file);
 		const name = `${config.id}-${slug}`;
-		const title = typeof frontmatter.title === "string" ? frontmatter.title : extractMarkdownTitle(content, slug);
+		const title = typeof frontmatter.title === "string" ? frontmatter.title : extractMarkdownTitle(rewritten, slug);
 		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",
@@ -262,13 +781,18 @@ async function compileGuides(options) {
 				...tags.length > 0 ? { tags } : {},
 				content: {
 					format: "topik",
-					value: content
-				}
+					value: rewritten
+				},
+				...manifest.length > 0 ? { assets: manifest } : {}
 			}
 		};
 		resources.push(guide);
 	}
-	return { resources };
+	for (const asset of assetsById.values()) resources.push(asset);
+	return {
+		diagnostics,
+		resources
+	};
 }
 function fileToSlug(filename) {
 	return filename.replace(/\.(mdx?|md)$/, "");
@@ -296,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
@@ -314,6 +863,7 @@ const ajv = new Ajv2020({
 });
 addFormats(ajv);
 const validators = {
+	Asset: ajv.compile(assetSchema),
 	Guide: ajv.compile(guideSchema),
 	Wiki: ajv.compile(wikiSchema),
 	WikiPage: ajv.compile(wikiPageSchema)
@@ -427,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,8 +1,13 @@
 {
   "name": "@topik/core",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Topik core library",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/subtopik/topik.git",
+    "directory": "packages/core"
+  },
   "files": [
     "dist"
   ],
@@ -15,19 +20,19 @@
     "access": "public"
   },
   "dependencies": {
-    "ajv": "^8.18.0",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "chokidar": "^4.0.0",
-    "yaml": "^2.7.0",
-    "zod": "^3.25.0",
-    "@topik/schema": "0.1.0-alpha.2"
+    "chokidar": "^5.0.0",
+    "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.20260316.1",
-    "typescript": "^5",
-    "vite-plus": "^0.1.12",
-    "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",