kitfly 0.1.2 → 0.2.1

package/src/__tests__/shared.test.ts

@@ -14,14 +14,17 @@ import {
 	buildNavSimple,
 	buildNavStatic,
 	buildPageMeta,
+	buildSlideNav,
 	buildToc,
 	type ContentFile,
 	collectFiles,
+	collectSlides,
 	envBool,
 	envInt,
 	envString,
 	escapeHtml,
 	exists,
+	filterUnknownSlidesVisualsTypeDiagnostics,
 	formatDate,
 	generateProvenance,
 	getGitInfo,
@@ -32,11 +35,15 @@ import {
 	parseValue,
 	parseYaml,
 	resolveSiteVersion,
+	rewriteRelativeAssetUrls,
 	type SiteConfig,
+	segmentSlides,
 	slugify,
+	splitSlides,
 	stripQuotes,
 	toUrlPath,
 	validatePath,
+	validateSlidesVisualsFences,
 } from "../shared.ts";
 
 describe("slugify", () => {
@@ -88,6 +95,287 @@ description: A test page
 		expect(Object.keys(frontmatter)).toHaveLength(0);
 		expect(body).toBe(content);
 	});
+
+	it("extracts frontmatter with leading whitespace (delimiter-split slides)", () => {
+		const content = `\n\n  ---\n  title: Slide Two\n  ---\n\n# Two`;
+		const { frontmatter, body } = parseFrontmatter(content);
+		expect(frontmatter.title).toBe("Slide Two");
+		expect(body.trim()).toBe("# Two");
+	});
+});
+
+describe("splitSlides", () => {
+	it("splits markdown on explicit slide delimiter", () => {
+		const input = `# One
+
+--- slide ---
+
+# Two`;
+		const slides = splitSlides(input);
+		expect(slides).toHaveLength(2);
+		expect(slides[0]).toContain("# One");
+		expect(slides[1]).toContain("# Two");
+	});
+
+	it("does not split on plain horizontal rules", () => {
+		const input = `# One
+
+---
+
+Still one slide`;
+		const slides = splitSlides(input);
+		expect(slides).toHaveLength(1);
+	});
+
+	it("ignores delimiter text inside fenced code blocks", () => {
+		const input = `# One
+
+\`\`\`md
+--- slide ---
+\`\`\`
+
+--- slide ---
+
+# Two`;
+		const slides = splitSlides(input);
+		expect(slides).toHaveLength(2);
+		expect(slides[0]).toContain("```md");
+		expect(slides[0]).toContain("--- slide ---");
+	});
+
+	it("does not break on 4-backtick fences containing 3-backtick lines", () => {
+		const input = `\`\`\`\`md
+\`\`\` still code
+--- slide ---
+\`\`\`\`
+--- slide ---
+# Real slide`;
+		const slides = splitSlides(input);
+		expect(slides).toHaveLength(2);
+		expect(slides[0]).toContain("--- slide ---");
+		expect(slides[1].trim()).toBe("# Real slide");
+	});
+});
+
+describe("slides-visuals diagnostics filtering", () => {
+	it("drops unknown-type diagnostics while preserving schema violations", () => {
+		const markdown = `:::future-thing
+foo: bar
+:::
+
+:::kpi
+label: Missing value
+:::`;
+		const diagnostics = validateSlidesVisualsFences(markdown);
+		const filtered = filterUnknownSlidesVisualsTypeDiagnostics(diagnostics);
+		expect(
+			diagnostics.some((d) => d.message.startsWith("Unknown slides-visuals block type:")),
+		).toBe(true);
+		expect(filtered.some((d) => d.message.startsWith("Unknown slides-visuals block type:"))).toBe(
+			false,
+		);
+		expect(filtered.some((d) => d.message.includes("Missing required key: value"))).toBe(true);
+	});
+});
+
+describe("segmentSlides", () => {
+	it("uses frontmatter title and class when present", () => {
+		const input = `---
+title: Intro Slide
+class: two-column
+---
+
+# Welcome`;
+		const segments = segmentSlides(input, "Deck");
+		expect(segments).toHaveLength(1);
+		expect(segments[0].title).toBe("Intro Slide");
+		expect(segments[0].className).toBe("two-column");
+	});
+
+	it("falls back to first heading when frontmatter title is missing", () => {
+		const input = `# Architecture Overview
+
+Body`;
+		const segments = segmentSlides(input, "Deck");
+		expect(segments[0].title).toBe("Architecture Overview");
+	});
+
+	it("ignores headings inside fenced code blocks when deriving title", () => {
+		const input = `\`\`\`md
+# Not a real heading
+\`\`\`
+
+# Real Heading`;
+		const segments = segmentSlides(input, "Deck");
+		expect(segments[0].title).toBe("Real Heading");
+	});
+
+	it("falls back to indexed title when no frontmatter title or heading exists", () => {
+		const input = `Just text
+--- slide ---
+More text`;
+		const segments = segmentSlides(input, "Runbook Deck");
+		expect(segments).toHaveLength(2);
+		expect(segments[0].title).toBe("Runbook Deck (1)");
+		expect(segments[1].title).toBe("Runbook Deck (2)");
+	});
+
+	it("parses frontmatter per slide segment", () => {
+		const input = `---
+title: First
+---
+
+# One
+--- slide ---
+---
+title: Second
+class: centered
+---
+
+# Two`;
+		const segments = segmentSlides(input, "Deck");
+		expect(segments).toHaveLength(2);
+		expect(segments[0].title).toBe("First");
+		expect(segments[1].title).toBe("Second");
+		expect(segments[1].className).toBe("centered");
+	});
+
+	it("sanitizes frontmatter class to safe class tokens", () => {
+		const input = `---
+class: centered two-column "><img src=x onerror=alert(1)>
+---
+
+# Safe classes only`;
+		const segments = segmentSlides(input, "Deck");
+		expect(segments[0].className).toBe("centered two-column");
+	});
+});
+
+describe("collectSlides and buildSlideNav", () => {
+	const tempDirs: string[] = [];
+
+	afterEach(async () => {
+		for (const dir of tempDirs) {
+			await rm(dir, { recursive: true, force: true });
+		}
+		tempDirs.length = 0;
+	});
+
+	it("collects segmented markdown slides and assigns sequential ids", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-slides-collect-"));
+		tempDirs.push(dir);
+		const mdPath = join(dir, "deck.md");
+		await writeFile(
+			mdPath,
+			`---
+title: Intro
+---
+
+# Intro
+--- slide ---
+# Next`,
+			"utf-8",
+		);
+
+		const files: ContentFile[] = [
+			{ path: mdPath, urlPath: "slides/deck", section: "Slides", sectionBase: "slides" },
+		];
+
+		const slides = await collectSlides(files);
+		expect(slides).toHaveLength(2);
+		expect(slides[0].id).toBe("slide-1");
+		expect(slides[1].id).toBe("slide-2");
+		expect(slides[0].title).toBe("Intro");
+		expect(slides[1].title).toBe("Next");
+		expect(slides[0].kind).toBe("markdown");
+	});
+
+	it("collects yaml/json files as single non-markdown slides", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-slides-kinds-"));
+		tempDirs.push(dir);
+		const yamlPath = join(dir, "config.yaml");
+		const jsonPath = join(dir, "data.json");
+		await writeFile(yamlPath, "name: test\n", "utf-8");
+		await writeFile(jsonPath, '{"ok":true}\n', "utf-8");
+
+		const files: ContentFile[] = [
+			{ path: yamlPath, urlPath: "ref/config", section: "Reference", sectionBase: "ref" },
+			{ path: jsonPath, urlPath: "ref/data", section: "Reference", sectionBase: "ref" },
+		];
+		const slides = await collectSlides(files);
+		expect(slides).toHaveLength(2);
+		expect(slides[0].kind).toBe("yaml");
+		expect(slides[1].kind).toBe("json");
+		expect(slides[0].title).toBe("config");
+		expect(slides[1].title).toBe("data");
+	});
+
+	it("builds slide nav grouped by section using slide ids", () => {
+		const nav = buildSlideNav(
+			[
+				{
+					index: 0,
+					frontmatter: {},
+					body: "# A",
+					title: "Slide A",
+					id: "slide-1",
+					section: "Slides",
+					sourcePath: "/tmp/a.md",
+					sourceUrlPath: "slides/a",
+					kind: "markdown",
+				},
+				{
+					index: 1,
+					frontmatter: {},
+					body: "# B",
+					title: "Slide B",
+					id: "slide-2",
+					section: "Slides",
+					sourcePath: "/tmp/b.md",
+					sourceUrlPath: "slides/b",
+					kind: "markdown",
+				},
+			],
+			{
+				docroot: ".",
+				title: "Deck",
+				brand: { name: "Test", url: "/" },
+				sections: [{ name: "Slides", path: "slides" }],
+			},
+			"slide-2",
+		);
+		expect(nav).toContain('<a href="#slide-1">Slide A</a>');
+		expect(nav).toContain('<a href="#slide-2" class="active">Slide B</a>');
+		expect(nav).toContain('<span class="nav-section">Slides</span>');
+	});
+});
+
+describe("rewriteRelativeAssetUrls", () => {
+	it("rewrites image sources relative to the source markdown path", () => {
+		const html = '<p><img src="./img/diagram.png" alt="diagram"></p>';
+		const rewritten = rewriteRelativeAssetUrls(html, "slides/deck", "/");
+		expect(rewritten).toContain('src="/slides/img/diagram.png"');
+	});
+
+	it("preserves external and anchor refs", () => {
+		const html = '<a href="https://example.com">ext</a> <a href="#slide-2">hash</a>';
+		const rewritten = rewriteRelativeAssetUrls(html, "slides/deck", "./");
+		expect(rewritten).toContain('href="https://example.com"');
+		expect(rewritten).toContain('href="#slide-2"');
+	});
+
+	it("keeps query/hash suffix when rewriting", () => {
+		const html = '<a href="../files/report.pdf?dl=1#v2">report</a>';
+		const rewritten = rewriteRelativeAssetUrls(html, "slides/deck", "./");
+		expect(rewritten).toContain('href="./files/report.pdf?dl=1#v2"');
+	});
+
+	it("does not rewrite non-asset href links", () => {
+		const html = '<a href="other.md">doc</a> <a href="./other.md">doc2</a>';
+		const rewritten = rewriteRelativeAssetUrls(html, "slides/deck", "./");
+		expect(rewritten).toContain('href="other.md"');
+		expect(rewritten).toContain('href="./other.md"');
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -818,6 +1106,8 @@ describe("loadSiteConfig", () => {
 		const result = await loadSiteConfig("/nonexistent/path", "Default Title");
 		expect(result.docroot).toBe(".");
 		expect(result.title).toBe("Default Title");
+		expect(result.mode).toBe("docs");
+		expect(result.aspect).toBe("16/9");
 		expect(result.brand.name).toBe("Handbook");
 		expect(result.sections).toEqual([]);
 	});
@@ -887,6 +1177,58 @@ ${links}
 			await rm(dir, { recursive: true, force: true });
 		}
 	});
+
+	it("parses slides mode and aspect from site.yaml", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-slides-config-"));
+		try {
+			await writeFile(
+				join(dir, "site.yaml"),
+				`title: Slides
+mode: slides
+aspect: "4/3"
+brand:
+  name: Test
+  url: /
+sections:
+  - name: Deck
+    path: slides
+`,
+				"utf-8",
+			);
+
+			const config = await loadSiteConfig(dir);
+			expect(config.mode).toBe("slides");
+			expect(config.aspect).toBe("4/3");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("falls back to default docs mode and aspect when invalid", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-slides-defaults-"));
+		try {
+			await writeFile(
+				join(dir, "site.yaml"),
+				`title: Defaults
+mode: invalid
+aspect: "21/9"
+brand:
+  name: Test
+  url: /
+sections:
+  - name: Deck
+    path: slides
+`,
+				"utf-8",
+			);
+
+			const config = await loadSiteConfig(dir);
+			expect(config.mode).toBe("docs");
+			expect(config.aspect).toBe("16/9");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -1017,6 +1359,115 @@ describe("resolveSiteVersion", () => {
 		const version = await resolveSiteVersion("/nonexistent/path", "9.9.9");
 		expect(version).toBe("9.9.9");
 	});
+
+	it("resolves auto from VERSION first non-empty line", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-version-auto-"));
+		try {
+			await writeFile(join(dir, "VERSION"), "\n \n 1.2.3 \n2.0.0\n", "utf-8");
+			const version = await resolveSiteVersion(dir, "auto");
+			expect(version).toBe("1.2.3");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("resolves version from file path with spaces", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-version-file-"));
+		try {
+			await mkdir(join(dir, "meta"), { recursive: true });
+			await writeFile(join(dir, "meta", "site version.txt"), "2026.02.12\n", "utf-8");
+			const version = await resolveSiteVersion(dir, "file:./meta/site version.txt");
+			expect(version).toBe("2026.02.12");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("rejects absolute file path and falls back", async () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		try {
+			const version = await resolveSiteVersion("/nonexistent/path", "file:/etc/hostname");
+			expect(version).toBeUndefined();
+			expect(warn).toHaveBeenCalledWith(
+				expect.stringContaining("version file: absolute paths are not allowed"),
+			);
+		} finally {
+			warn.mockRestore();
+		}
+	});
+
+	it("rejects windows absolute file path and falls back", async () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		try {
+			const version = await resolveSiteVersion("/nonexistent/path", "file:C:\\temp\\VERSION");
+			expect(version).toBeUndefined();
+			expect(warn).toHaveBeenCalledWith(
+				expect.stringContaining("version file: absolute paths are not allowed"),
+			);
+		} finally {
+			warn.mockRestore();
+		}
+	});
+
+	it("rejects windows drive-relative file path and falls back", async () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		try {
+			const version = await resolveSiteVersion("/nonexistent/path", "file:C:VERSION");
+			expect(version).toBeUndefined();
+			expect(warn).toHaveBeenCalledWith(
+				expect.stringContaining("version file: absolute paths are not allowed"),
+			);
+		} finally {
+			warn.mockRestore();
+		}
+	});
+
+	it("rejects path that escapes site root and falls back", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-version-escape-"));
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		try {
+			const version = await resolveSiteVersion(dir, "file:../../etc/passwd");
+			expect(version).toBeUndefined();
+			expect(warn).toHaveBeenCalledWith(
+				expect.stringContaining("version file: path escapes site root"),
+			);
+		} finally {
+			warn.mockRestore();
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("warns for empty file path and falls back", async () => {
+		const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		try {
+			const version = await resolveSiteVersion("/nonexistent/path", "file:");
+			expect(version).toBeUndefined();
+			expect(warn).toHaveBeenCalledWith("version file: path is empty");
+		} finally {
+			warn.mockRestore();
+		}
+	});
+
+	it("falls back when auto VERSION file is missing", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-version-auto-missing-"));
+		try {
+			const version = await resolveSiteVersion(dir, "auto");
+			expect(version).toBeUndefined();
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("falls back when auto VERSION file is empty", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "kitfly-version-auto-empty-"));
+		try {
+			await writeFile(join(dir, "VERSION"), "\n \n\t\n", "utf-8");
+			const version = await resolveSiteVersion(dir, "auto");
+			expect(version).toBeUndefined();
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/slides-visuals-fence-contract.test.ts

@@ -0,0 +1,28 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { validateSlidesVisualsFences } from "../shared.ts";
+
+const FIXTURES = join(__dirname, "fixtures", "fences", "slides-visuals");
+
+describe("slides-visuals fence contract", () => {
+	it("accepts valid fixtures", async () => {
+		const dir = join(FIXTURES, "valid");
+		const files = await readdir(dir);
+		for (const f of files) {
+			const md = await readFile(join(dir, f), "utf-8");
+			const diags = validateSlidesVisualsFences(md);
+			expect(diags, `${f} should be valid`).toHaveLength(0);
+		}
+	});
+
+	it("rejects invalid fixtures", async () => {
+		const dir = join(FIXTURES, "invalid");
+		const files = await readdir(dir);
+		for (const f of files) {
+			const md = await readFile(join(dir, f), "utf-8");
+			const diags = validateSlidesVisualsFences(md);
+			expect(diags.length, `${f} should be invalid`).toBeGreaterThan(0);
+		}
+	});
+});

package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts

@@ -0,0 +1,147 @@
+import { expect, test } from "bun:test";
+
+type SlidesVisualsTestHooks = {
+	parseBodyNodesWithFirstLines: (
+		firstLines: string[],
+		between: any[],
+		end: any,
+		type: string,
+	) => Record<string, unknown>;
+	rowCells: (row: unknown) => string[];
+};
+
+class FakeElement {
+	tagName: string;
+	textContent: string;
+	#children: FakeElement[];
+
+	constructor(tagName: string, textContent = "", children: FakeElement[] = []) {
+		this.tagName = tagName;
+		this.textContent = textContent;
+		this.#children = children;
+	}
+
+	querySelectorAll(selector: string): FakeElement[] {
+		if (selector === ":scope > li") return this.#children;
+		if (selector === ":scope > p") return [];
+		return [];
+	}
+}
+
+async function loadHooks(): Promise<SlidesVisualsTestHooks> {
+	// Executes the plugin file and registers hooks on globalThis (in non-DOM test env).
+	// @ts-expect-error — JS plugin file, no declaration needed
+	await import("../../plugins-dist/slides-visuals.js");
+	const hooks = (globalThis as any).__kitflySlidesVisualsTest as SlidesVisualsTestHooks | undefined;
+	if (!hooks) throw new Error("slides-visuals test hooks not found on globalThis");
+	return hooks;
+}
+
+test("slides-visuals: absorbed scalar marker preserves preceding item (compare)", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+
+	const out = parseBodyNodesWithFirstLines(
+		['left-title: "Build In-House"', "left:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", "Ongoing maintenance burden\nright-title: Auth0 / Clerk"),
+			new FakeElement("LI", "Production-ready in 2 weeks"),
+		]),
+		"compare",
+	);
+
+	expect(out["left-title"]).toBe("Build In-House");
+	expect(out["right-title"]).toBe("Auth0 / Clerk");
+	expect(out.left).toEqual(["Ongoing maintenance burden"]);
+	expect(out.right).toEqual(["Production-ready in 2 weeks"]);
+});
+
+test("slides-visuals: absorbed list marker preserves preceding item (comparison-table)", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+
+	const out = parseBodyNodesWithFirstLines(
+		["headers:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", "Feature"),
+			new FakeElement("LI", "Us"),
+			new FakeElement("LI", "Competitor A"),
+			new FakeElement("LI", "Competitor B\nrows:"),
+			new FakeElement("LI", '["Real-time sync", "Yes", "Yes", "No"]'),
+		]),
+		"comparison-table",
+	);
+
+	expect(out.headers).toEqual(["Feature", "Us", "Competitor A", "Competitor B"]);
+	expect(out.rows).toEqual(['["Real-time sync", "Yes", "Yes", "No"]']);
+});
+
+test("slides-visuals: strips trailing ::: from string list items (layer-cake)", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+
+	const out = parseBodyNodesWithFirstLines(
+		["layers:"],
+		[],
+		new FakeElement("UL", "", [new FakeElement("LI", "Infrastructure :::")]),
+		"layer-cake",
+	);
+
+	expect(out.layers).toEqual(["Infrastructure"]);
+});
+
+test("slides-visuals: parses object list items for stat-grid metrics", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+
+	const out = parseBodyNodesWithFirstLines(
+		["metrics:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", "label: Users\nvalue: 1.2M\ntrend: +6%"),
+			new FakeElement("LI", "label: MRR\nvalue: $240k"),
+		]),
+		"stat-grid",
+	);
+
+	expect(out.metrics).toEqual([
+		{ label: "Users", value: "1.2M", trend: "+6%" },
+		{ label: "MRR", value: "$240k" },
+	]);
+});
+
+test("slides-visuals: rowCells parses JSON array strings", async () => {
+	const hooks = await loadHooks();
+	expect(hooks.rowCells('["A", "B", "C"]')).toEqual(["A", "B", "C"]);
+});
+
+test("slides-visuals: absorbed scalar marker preserves preceding item (flow-converging)", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+
+	const out = parseBodyNodesWithFirstLines(
+		["sources:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", "Frontend Logs\ntarget: Dashboard"),
+			new FakeElement("LI", "API Logs"),
+		]),
+		"flow-converging",
+	);
+
+	expect(out.target).toBe("Dashboard");
+	expect(out.sources).toEqual(["Frontend Logs", "API Logs"]);
+});
+
+test("slides-visuals: parses object list items for timeline events", async () => {
+	const { parseBodyNodesWithFirstLines } = await loadHooks();
+
+	const out = parseBodyNodesWithFirstLines(
+		["events:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", "label: Kickoff\ndate: Jan 2026"),
+			new FakeElement("LI", "label: Alpha"),
+		]),
+		"timeline-horizontal",
+	);
+
+	expect(out.events).toEqual([{ label: "Kickoff", date: "Jan 2026" }, { label: "Alpha" }]);
+});