kitfly 0.1.2 → 0.2.0

package/src/shared.ts

@@ -6,7 +6,7 @@
  */
 
 import { readdir, readFile, stat } from "node:fs/promises";
-import { join, resolve, sep } from "node:path";
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ENGINE_SITE_DIR, siteOverridePath } from "./engine.ts";
 
 // ---------------------------------------------------------------------------
@@ -62,10 +62,15 @@ export interface SiteServer {
 	host?: string; // Default dev server host
 }
 
+export type SiteMode = "docs" | "slides";
+export type SlideAspect = "16/9" | "4/3" | "3/2" | "16/10";
+
 export interface SiteConfig {
 	docroot: string;
 	title: string;
 	version?: string;
+	mode?: SiteMode;
+	aspect?: SlideAspect;
 	home?: string;
 	brand: SiteBrand;
 	sections: SiteSection[];
@@ -88,6 +93,22 @@ export interface ContentFile {
 	sectionBase?: string;
 }
 
+export interface SlideSegment {
+	index: number;
+	frontmatter: Record<string, unknown>;
+	body: string;
+	title: string;
+	className?: string;
+}
+
+export interface SlideContent extends SlideSegment {
+	id: string;
+	section: string;
+	sourcePath: string;
+	sourceUrlPath: string;
+	kind: "markdown" | "yaml" | "json";
+}
+
 // ---------------------------------------------------------------------------
 // Environment and CLI helpers
 // ---------------------------------------------------------------------------
@@ -386,14 +407,28 @@ export function parseFrontmatter(content: string): {
 	frontmatter: Record<string, unknown>;
 	body: string;
 } {
-	const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-	if (!match) {
+	const normalized = content.replace(/^\uFEFF/, "").replaceAll("\r\n", "\n");
+	const lines = normalized.split("\n");
+
+	let i = 0;
+	while (i < lines.length && lines[i].trim() === "") i += 1;
+	if (i >= lines.length || lines[i].trim() !== "---") {
 		return { frontmatter: {}, body: content };
 	}
 
+	i += 1;
+	const fmLines: string[] = [];
+	while (i < lines.length && lines[i].trim() !== "---") {
+		fmLines.push(lines[i]);
+		i += 1;
+	}
+	if (i >= lines.length) return { frontmatter: {}, body: content };
+	i += 1; // consume closing ---
+
+	const body = lines.slice(i).join("\n");
+
 	const frontmatter: Record<string, unknown> = {};
-	const lines = match[1].split("\n");
-	for (const line of lines) {
+	for (const line of fmLines) {
 		const colonIndex = line.indexOf(":");
 		if (colonIndex > 0) {
 			const key = line.slice(0, colonIndex).trim();
@@ -409,7 +444,7 @@ export function parseFrontmatter(content: string): {
 		}
 	}
 
-	return { frontmatter, body: match[2] };
+	return { frontmatter, body };
 }
 
 export function slugify(text: string): string {
@@ -421,6 +456,524 @@ export function slugify(text: string): string {
 		.trim();
 }
 
+export type SlidesVisualsFenceDiagnostic = {
+	line: number;
+	message: string;
+	type?: string;
+};
+
+interface FenceState {
+	char: "`" | "~";
+	length: number;
+}
+
+interface FenceMarker extends FenceState {
+	trailer: string;
+}
+
+function parseFenceMarker(trimmed: string): FenceMarker | null {
+	const match = trimmed.match(/^([`~]{3,})(.*)$/);
+	if (!match) return null;
+	const marker = match[1];
+	if (!marker.split("").every((ch) => ch === marker[0])) return null;
+	const char = marker[0] as "`" | "~";
+	return { char, length: marker.length, trailer: match[2] };
+}
+
+function updateFenceState(trimmed: string, fence: FenceState | null): FenceState | null {
+	const marker = parseFenceMarker(trimmed);
+	if (!marker) return fence;
+
+	if (!fence) {
+		return { char: marker.char, length: marker.length };
+	}
+
+	// Markdown closing fences must use the same fence character and at least the same length.
+	if (marker.char === fence.char && marker.length >= fence.length && marker.trailer.trim() === "") {
+		return null;
+	}
+
+	return fence;
+}
+
+const SLIDES_VISUALS_TYPES = new Set([
+	"kpi",
+	"stat-grid",
+	"compare",
+	"quadrant-grid",
+	"scorecard",
+	"comparison-table",
+	"layer-cake",
+	"pyramid",
+	"funnel",
+]);
+
+const SLIDES_VISUALS_RULES: Record<
+	string,
+	{
+		required: string[];
+		scalars: string[];
+		lists: Record<
+			string,
+			{ kind: "strings" } | { kind: "objects"; fields: string[]; optional?: string[] }
+		>;
+	}
+> = {
+	kpi: {
+		required: ["label", "value"],
+		scalars: ["label", "value", "trend"],
+		lists: {},
+	},
+	"stat-grid": {
+		required: ["metrics"],
+		scalars: [],
+		lists: { metrics: { kind: "objects", fields: ["label", "value"], optional: ["trend"] } },
+	},
+	compare: {
+		required: ["left", "right"],
+		scalars: ["left-title", "right-title"],
+		lists: { left: { kind: "strings" }, right: { kind: "strings" } },
+	},
+	"quadrant-grid": {
+		required: ["tl", "tr", "bl", "br"],
+		scalars: ["axis-x", "axis-y", "tl", "tr", "bl", "br"],
+		lists: {},
+	},
+	scorecard: {
+		required: ["metrics"],
+		scalars: [],
+		lists: { metrics: { kind: "objects", fields: ["label", "value"], optional: ["trend"] } },
+	},
+	"comparison-table": {
+		required: ["headers", "rows"],
+		scalars: [],
+		lists: { headers: { kind: "strings" }, rows: { kind: "strings" } },
+	},
+	"layer-cake": {
+		required: ["layers"],
+		scalars: [],
+		lists: { layers: { kind: "strings" } },
+	},
+	pyramid: {
+		required: ["levels"],
+		scalars: [],
+		lists: { levels: { kind: "strings" } },
+	},
+	funnel: {
+		required: ["stages"],
+		scalars: [],
+		lists: { stages: { kind: "strings" } },
+	},
+};
+
+/**
+ * Validate slides-visuals `:::` blocks in a single markdown slide body.
+ * This contract is intentionally strict so writers/devs don’t guess at edge cases.
+ */
+export function validateSlidesVisualsFences(markdown: string): SlidesVisualsFenceDiagnostic[] {
+	const diagnostics: SlidesVisualsFenceDiagnostic[] = [];
+	const lines = markdown.replaceAll("\r\n", "\n").split("\n");
+
+	let mdFence: FenceState | null = null;
+	let inVisual = false;
+	let visualType = "";
+	let visualStart = 0;
+	let seenKeys = new Set<string>();
+	let currentListKey: string | null = null;
+	let listItems = 0;
+	let listItemFields: Record<string, Set<string>> | null = null;
+
+	function err(line: number, message: string) {
+		diagnostics.push({ line, message, type: inVisual ? visualType : undefined });
+	}
+
+	function finishFence(closeLine: number) {
+		const rules = SLIDES_VISUALS_RULES[visualType];
+		if (!rules) return;
+
+		for (const key of rules.required) {
+			if (!seenKeys.has(key)) {
+				err(visualStart, `Missing required key: ${key}`);
+			}
+		}
+
+		if (currentListKey && listItems === 0) {
+			err(closeLine, `List '${currentListKey}' must have at least one item`);
+		}
+
+		if (listItemFields) {
+			for (const [requiredKey, fields] of Object.entries(listItemFields)) {
+				const listRule = rules.lists[requiredKey];
+				if (!listRule || listRule.kind !== "objects") continue;
+				for (const req of listRule.fields) {
+					if (!fields.has(req))
+						err(visualStart, `List '${requiredKey}' items must include '${req}'`);
+				}
+			}
+		}
+	}
+
+	for (let i = 0; i < lines.length; i++) {
+		const raw = lines[i];
+		const trimmed = raw.trim();
+
+		mdFence = updateFenceState(trimmed, mdFence);
+		if (mdFence) continue;
+
+		if (!inVisual) {
+			if (trimmed.startsWith(":::") && !raw.startsWith(":::")) {
+				const mBad = trimmed.match(/^:::\s*([a-z0-9-]+)\s*$/i);
+				const type = mBad?.[1]?.toLowerCase();
+				diagnostics.push({
+					line: i + 1,
+					message: "Opening ::: fence must start at column 0",
+					type,
+				});
+				continue;
+			}
+			const m = raw.match(/^:::\s*([a-z0-9-]+)\s*$/i);
+			if (!m) continue;
+			const type = m[1].toLowerCase();
+			if (!SLIDES_VISUALS_TYPES.has(type)) {
+				diagnostics.push({
+					line: i + 1,
+					message: `Unknown slides-visuals block type: ${type}`,
+					type,
+				});
+				continue;
+			}
+			inVisual = true;
+			visualType = type;
+			visualStart = i + 1;
+			seenKeys = new Set();
+			currentListKey = null;
+			listItems = 0;
+			listItemFields = null;
+			continue;
+		}
+
+		// inside visual fence
+		if (trimmed === ":::" && !raw.startsWith(":::")) {
+			err(i + 1, "Closing ::: fence must start at column 0");
+			continue;
+		}
+
+		if (raw.match(/^:::\s*$/)) {
+			finishFence(i + 1);
+			inVisual = false;
+			visualType = "";
+			currentListKey = null;
+			continue;
+		}
+
+		if (trimmed === "") {
+			err(i + 1, "Blank lines are not allowed inside ::: blocks");
+			continue;
+		}
+
+		if (/^\s/.test(raw)) {
+			// list item or list continuation
+			if (!currentListKey) {
+				err(i + 1, "Indented content is only allowed inside a list");
+				continue;
+			}
+
+			const listRule = SLIDES_VISUALS_RULES[visualType]?.lists[currentListKey];
+			const item = raw.match(/^ {2}-\s+(.+)$/);
+			if (item) {
+				listItems += 1;
+				if (listRule?.kind === "objects") {
+					const kv = item[1].match(/^([a-z][a-z0-9-]*)\s*:\s*(.+)$/i);
+					if (!listItemFields) listItemFields = {};
+					const fields = listItemFields;
+					fields[currentListKey] ??= new Set<string>();
+					if (kv) fields[currentListKey].add(kv[1].toLowerCase());
+				}
+				continue;
+			}
+
+			const cont = raw.match(/^ {4}([a-z][a-z0-9-]*)\s*:\s*(.+)$/i);
+			if (cont) {
+				if (listRule?.kind !== "objects") {
+					err(i + 1, `List '${currentListKey}' items must be strings (no object fields)`);
+					continue;
+				}
+				if (!listItemFields) listItemFields = {};
+				const fields = listItemFields;
+				fields[currentListKey] ??= new Set<string>();
+				fields[currentListKey].add(cont[1].toLowerCase());
+				continue;
+			}
+
+			err(i + 1, "Invalid list syntax (expected '  - ...' or '    field: value')");
+			continue;
+		}
+
+		const rules = SLIDES_VISUALS_RULES[visualType];
+		if (!rules) continue;
+
+		const kv = raw.match(/^([a-z][a-z0-9-]*)\s*:\s*(.*)$/i);
+		if (!kv) {
+			err(i + 1, "Invalid line inside ::: block (expected 'key: value' or 'key:')");
+			continue;
+		}
+
+		const key = kv[1].toLowerCase();
+		const value = kv[2];
+
+		if (value === "") {
+			// list key
+			const listRule = rules.lists[key];
+			if (!listRule) {
+				err(i + 1, `Key '${key}' is not a supported list for ${visualType}`);
+				continue;
+			}
+			seenKeys.add(key);
+			currentListKey = key;
+			listItems = 0;
+			continue;
+		}
+
+		// scalar key
+		if (!rules.scalars.includes(key)) {
+			err(i + 1, `Key '${key}' is not a supported scalar for ${visualType}`);
+			continue;
+		}
+		seenKeys.add(key);
+		currentListKey = null;
+	}
+
+	if (inVisual) {
+		diagnostics.push({
+			line: visualStart,
+			message: `Unclosed ::: block (missing closing ':::')`,
+			type: visualType,
+		});
+	}
+
+	return diagnostics;
+}
+
+/**
+ * Split markdown content into slide chunks using explicit delimiter.
+ * Delimiter lines inside fenced code blocks are ignored.
+ */
+export function splitSlides(content: string): string[] {
+	const lines = content.split(/\r?\n/);
+	const slides: string[] = [];
+	let current: string[] = [];
+	let fence: FenceState | null = null;
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		fence = updateFenceState(trimmed, fence);
+
+		if (!fence && trimmed === "--- slide ---") {
+			slides.push(current.join("\n"));
+			current = [];
+			continue;
+		}
+
+		current.push(line);
+	}
+	slides.push(current.join("\n"));
+
+	return slides.filter((s) => s.trim() !== "");
+}
+
+function extractHeadingTitle(markdown: string): string | undefined {
+	const lines = markdown.split(/\r?\n/);
+	let fence: FenceState | null = null;
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		fence = updateFenceState(trimmed, fence);
+
+		if (fence) continue;
+		const match = trimmed.match(/^#{1,6}\s+(.+)$/);
+		if (match) {
+			return match[1].replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").trim();
+		}
+	}
+
+	return undefined;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed === "" ? undefined : trimmed;
+}
+
+function sanitizeClassNameList(value: unknown): string | undefined {
+	const classList = asNonEmptyString(value);
+	if (!classList) return undefined;
+
+	const safeTokens = classList
+		.split(/\s+/)
+		.map((token) => token.trim())
+		.filter(Boolean)
+		.filter((token) => /^[A-Za-z0-9_-]+$/.test(token));
+
+	return safeTokens.length > 0 ? safeTokens.join(" ") : undefined;
+}
+
+/**
+ * Parse markdown into slide segments with resolved titles and optional classes.
+ * Title precedence: frontmatter.title -> first heading -> fallback title.
+ */
+export function segmentSlides(content: string, fallbackTitle: string): SlideSegment[] {
+	const parts = splitSlides(content);
+	const total = parts.length;
+
+	return parts.map((part, index) => {
+		const { frontmatter, body } = parseFrontmatter(part);
+		const fmTitle = asNonEmptyString(frontmatter.title);
+		const headingTitle = extractHeadingTitle(body);
+		const autoFallback = total > 1 ? `${fallbackTitle} (${index + 1})` : fallbackTitle;
+		const title = fmTitle || headingTitle || autoFallback;
+		const className = sanitizeClassNameList(frontmatter.class);
+
+		return {
+			index,
+			frontmatter,
+			body,
+			title,
+			className,
+		};
+	});
+}
+
+/**
+ * Collect slide content objects from discovered content files.
+ * Markdown files can produce multiple slides via explicit delimiters.
+ */
+export async function collectSlides(files: ContentFile[]): Promise<SlideContent[]> {
+	const slides: SlideContent[] = [];
+	let index = 0;
+
+	for (const file of files) {
+		const raw = await readFile(file.path, "utf-8");
+		const stem = basename(file.path, extname(file.path));
+
+		if (file.path.endsWith(".md")) {
+			const segments = segmentSlides(raw, stem);
+			for (const segment of segments) {
+				index += 1;
+				slides.push({
+					...segment,
+					id: `slide-${index}`,
+					section: file.section,
+					sourcePath: file.path,
+					sourceUrlPath: file.urlPath,
+					kind: "markdown",
+				});
+			}
+			continue;
+		}
+
+		index += 1;
+		slides.push({
+			index: 0,
+			frontmatter: {},
+			body: raw,
+			title: stem,
+			className: undefined,
+			id: `slide-${index}`,
+			section: file.section,
+			sourcePath: file.path,
+			sourceUrlPath: file.urlPath,
+			kind: file.path.endsWith(".yaml") ? "yaml" : "json",
+		});
+	}
+
+	return slides;
+}
+
+export function buildSlideNav(
+	slides: SlideContent[],
+	config: SiteConfig,
+	currentSlideId?: string,
+): string {
+	const grouped = new Map<string, SlideContent[]>();
+	for (const slide of slides) {
+		if (!grouped.has(slide.section)) grouped.set(slide.section, []);
+		grouped.get(slide.section)?.push(slide);
+	}
+
+	let html = "<ul>";
+	for (const section of config.sections) {
+		const items = grouped.get(section.name);
+		if (!items || items.length === 0) continue;
+		html += `<li><span class="nav-section">${escapeHtml(section.name)}</span><ul>`;
+		for (const slide of items) {
+			const active = currentSlideId === slide.id ? ' class="active"' : "";
+			html += `<li><a href="#${slide.id}"${active}>${escapeHtml(slide.title)}</a></li>`;
+		}
+		html += "</ul></li>";
+	}
+	html += "</ul>";
+	return html;
+}
+
+function resolveRelativeContentPath(pathOrRef: string, currentUrlPath?: string): string {
+	let cleaned = pathOrRef;
+	if (currentUrlPath && !cleaned.startsWith("/")) {
+		const base = currentUrlPath.includes("/")
+			? currentUrlPath.slice(0, currentUrlPath.lastIndexOf("/"))
+			: "";
+		cleaned = base ? `${base}/${cleaned}` : cleaned;
+	}
+
+	const segments = cleaned.split("/");
+	const resolved: string[] = [];
+	for (const segment of segments) {
+		if (!segment || segment === ".") continue;
+		if (segment === "..") resolved.pop();
+		else resolved.push(segment);
+	}
+	return resolved.join("/");
+}
+
+function splitUrlSuffix(url: string): { path: string; suffix: string } {
+	const idx = url.search(/[?#]/);
+	if (idx < 0) return { path: url, suffix: "" };
+	return { path: url.slice(0, idx), suffix: url.slice(idx) };
+}
+
+function isExternalOrAnchorRef(ref: string): boolean {
+	return /^(https?:|mailto:|tel:|data:|javascript:|#|\/\/)/i.test(ref);
+}
+
+// Rewrite relative href/src URLs so slide assets resolve from their source folder.
+export function rewriteRelativeAssetUrls(
+	html: string,
+	currentUrlPath?: string,
+	pathPrefix = "/",
+): string {
+	const assetHrefPattern =
+		/\.(pdf|png|jpe?g|gif|webp|svg|ico|bmp|avif|json|ya?ml|csv|txt|zip|mp4|webm|mov|mp3|wav|ogg)$/i;
+
+	return html.replace(/\b(href|src)="([^"]+)"/g, (_m, attr, value: string) => {
+		if (isExternalOrAnchorRef(value) || value.startsWith("/")) {
+			return `${attr}="${value}"`;
+		}
+		if (attr === "href") {
+			const isExplicitRelative = value.startsWith("./") || value.startsWith("../");
+			const { path } = splitUrlSuffix(value);
+			if (!isExplicitRelative || !assetHrefPattern.test(path)) {
+				return `${attr}="${value}"`;
+			}
+		}
+
+		const { path, suffix } = splitUrlSuffix(value);
+		const resolved = resolveRelativeContentPath(path, currentUrlPath);
+		const prefix = pathPrefix.endsWith("/") ? pathPrefix : `${pathPrefix}/`;
+		const rewritten = `${prefix}${resolved}${suffix}`;
+		return `${attr}="${rewritten}"`;
+	});
+}
+
 // ---------------------------------------------------------------------------
 // Navigation/template building
 // ---------------------------------------------------------------------------
@@ -1081,7 +1634,32 @@ export async function resolveSiteVersion(
 	configuredVersion?: string,
 ): Promise<string | undefined> {
 	if (typeof configuredVersion === "string" && configuredVersion.trim() !== "") {
-		return configuredVersion.trim();
+		const value = configuredVersion.trim();
+		const lower = value.toLowerCase();
+
+		if (lower === "auto") {
+			const autoVersion = await readVersionLine(join(root, "VERSION"));
+			if (autoVersion) return autoVersion;
+		} else if (lower.startsWith("file:")) {
+			const rawPath = value.slice(5).trim();
+			if (!rawPath) {
+				console.warn("version file: path is empty");
+			} else if (isAbsoluteVersionPath(rawPath)) {
+				console.warn(`version file: absolute paths are not allowed: ${rawPath}`);
+			} else {
+				const normalizedRoot = resolve(root);
+				const resolvedPath = resolve(root, rawPath);
+				const rel = relative(normalizedRoot, resolvedPath);
+				if (rel.startsWith("..") || rel === ".." || rel.includes(`${sep}..${sep}`)) {
+					console.warn(`version file: path escapes site root: ${rawPath}`);
+				} else {
+					const fileVersion = await readVersionLine(resolvedPath);
+					if (fileVersion) return fileVersion;
+				}
+			}
+		} else {
+			return value;
+		}
 	}
 
 	try {
@@ -1102,6 +1680,23 @@ export async function resolveSiteVersion(
 	return undefined;
 }
 
+function isAbsoluteVersionPath(pathValue: string): boolean {
+	return isAbsolute(pathValue) || /^[A-Za-z]:/.test(pathValue) || pathValue.startsWith("\\\\");
+}
+
+async function readVersionLine(path: string): Promise<string | undefined> {
+	try {
+		const content = await readFile(path, "utf-8");
+		for (const line of content.split(/\r?\n/)) {
+			const trimmed = line.trim();
+			if (trimmed) return trimmed;
+		}
+	} catch {
+		// Fall through to git tag resolution
+	}
+	return undefined;
+}
+
 /**
  * Generate provenance information
  * @param root - The root directory
@@ -1182,6 +1777,14 @@ export async function loadSiteConfig(
 			docroot: parsed.docroot || ".",
 			title: parsed.title,
 			version: typeof parsedRecord.version === "string" ? parsedRecord.version : undefined,
+			mode: parsedRecord.mode === "slides" ? "slides" : "docs",
+			aspect:
+				parsedRecord.aspect === "4/3" ||
+				parsedRecord.aspect === "3/2" ||
+				parsedRecord.aspect === "16/10" ||
+				parsedRecord.aspect === "16/9"
+					? parsedRecord.aspect
+					: "16/9",
 			home: parsed.home as string | undefined,
 			brand: {
 				...parsed.brand,
@@ -1221,6 +1824,8 @@ export async function loadSiteConfig(
 			return {
 				docroot: "content",
 				title: "Documentation",
+				mode: "docs",
+				aspect: "16/9",
 				brand: { name: "Docs", url: "/" },
 				sections,
 			};
@@ -1233,6 +1838,8 @@ export async function loadSiteConfig(
 	return {
 		docroot: ".",
 		title: defaultTitle,
+		mode: "docs",
+		aspect: "16/9",
 		brand: { name: "Handbook", url: "/" },
 		sections: [],
 	};