kitfly 0.2.3 → 0.2.4

package/src/__tests__/build.test.ts

@@ -624,4 +624,128 @@ plugins:
 		expect(html).toContain('data-kitfly-plugin="slides-visuals@0.2.1"');
 		expect(html).toContain("future-thing");
 	});
+
+	it("enforces planning-visuals fence contract in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "docs" });
+		await writeMd(
+			siteDir,
+			"docs/plan.md",
+			`# Plan
+
+:::gantt
+time-unit: week
+time-start: 2026-W10
+time-end: 2026-W12
+:::
+`,
+		);
+
+		const js = "console.log('planning visuals');";
+		const css = ".kitfly-planning-gantt{border:1px solid red;}";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.css"), css, "utf-8");
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-03-03"
+baseUrl: ""
+plugins:
+  planning-visuals:
+    name: "Planning Visuals"
+    description: "Test planning visuals"
+    version: "0.2.4"
+    contract: "1"
+    kitfly: ">=0.2.4 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/planning-visuals.js"
+      css: "plugins-dist/planning-visuals.css"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+        css: "sha256:${sha256Hex(css)}"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - planning-visuals@0.2.4\n",
+			"utf-8",
+		);
+
+		await expect(build({ folder: siteDir, out: outDir })).rejects.toThrow(
+			/planning-visuals fence contract violations/i,
+		);
+	});
+
+	it("ignores unknown planning-visuals block types while enforcing known contracts", async () => {
+		const siteDir = await makeTempDir();
+		const outDir = "out";
+		await writeSiteYaml(siteDir, { mode: "docs" });
+		await writeMd(
+			siteDir,
+			"docs/plan.md",
+			`# Plan
+
+:::future-plan
+note: pass-through
+:::
+
+:::gantt
+time-unit: month
+time-start: 2026-04
+time-end: 2026-08
+tracks:
+  - label: Wave 1
+    depth: 1
+    start: 2026-04
+    end: 2026-06
+:::
+`,
+		);
+
+		const js = "console.log('planning visuals');";
+		const css = ".kitfly-planning-gantt{border:1px solid red;}";
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.css"), css, "utf-8");
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-03-03"
+baseUrl: ""
+plugins:
+  planning-visuals:
+    name: "Planning Visuals"
+    description: "Test planning visuals"
+    version: "0.2.4"
+    contract: "1"
+    kitfly: ">=0.2.4 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/planning-visuals.js"
+      css: "plugins-dist/planning-visuals.css"
+      assetSha256:
+        js: "sha256:${sha256Hex(js)}"
+        css: "sha256:${sha256Hex(css)}"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - planning-visuals@0.2.4\n",
+			"utf-8",
+		);
+
+		await expect(build({ folder: siteDir, out: outDir })).resolves.toBeUndefined();
+		const html = await readFile(join(siteDir, outDir, "index.html"), "utf-8");
+		expect(html).toContain('data-kitfly-plugin="planning-visuals@0.2.4"');
+		expect(html).toContain("future-plan");
+	});
 });

package/src/__tests__/bundle.test.ts

@@ -864,6 +864,67 @@ describe("bundleSite plugin integration", () => {
 		expect(html).toContain("kitfly-chart-wrapper");
 	});
 
+	it("enforces planning-visuals fence contract in docs mode", async () => {
+		const siteDir = await makeTempDir();
+		await mkdir(join(siteDir, "docs"), { recursive: true });
+		await mkdir(join(siteDir, "plugins-dist"), { recursive: true });
+		await mkdir(join(siteDir, "registry"), { recursive: true });
+
+		const js = "console.log('planning visuals');";
+		const css = ".kitfly-planning-gantt{border:1px solid red;}";
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.js"), js, "utf-8");
+		await writeFile(join(siteDir, "plugins-dist", "planning-visuals.css"), css, "utf-8");
+		await writeFile(
+			join(siteDir, "registry", "plugins.yaml"),
+			`version: 1
+updated: "2026-03-03"
+baseUrl: ""
+plugins:
+  planning-visuals:
+    name: "Planning Visuals"
+    description: "Test planning visuals"
+    version: "0.2.4"
+    contract: "1"
+    kitfly: ">=0.2.4 <1.0.0"
+    license: MIT
+    verified: true
+    assets:
+      js: "plugins-dist/planning-visuals.js"
+      css: "plugins-dist/planning-visuals.css"
+      assetSha256:
+        js: "sha256:4932eca4b9f9735541953e9be72a916d7e8a08213a28cc6e0a34899dab98b880"
+        css: "sha256:e73d687d58def8a6608ae51d1a1a09af6eaf2ec4c0b5d0849ebf260679e80e21"
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "site.yaml"),
+			'title: "Bundle Plan Test"\nbrand:\n  name: "Test"\n  url: "/"\nsections:\n  - name: Docs\n    path: docs\n',
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "docs", "index.md"),
+			`# Plan
+
+:::gantt
+time-unit: week
+time-start: 2026-W10
+time-end: 2026-W12
+:::
+`,
+			"utf-8",
+		);
+		await writeFile(
+			join(siteDir, "kitfly.plugins.yaml"),
+			"plugins:\n  - planning-visuals@0.2.4\n",
+			"utf-8",
+		);
+
+		await expect(
+			bundleSite({ folder: siteDir, out: "bundles", name: "bundle.html" }),
+		).rejects.toThrow(/planning-visuals fence contract violations/i);
+	});
+
 	it("inlines footer logo image when configured", async () => {
 		const siteDir = await makeTempDir();
 		await mkdir(join(siteDir, "docs"), { recursive: true });

package/src/__tests__/docs.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Tests for the kitfly docs command and embed-docs codegen.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { findSimilar } from "../commands/docs.ts";
+import { EMBEDDED_DOCS } from "../generated/embedded-docs.ts";
+
+describe("embed-docs codegen", () => {
+	it("generates embedded-docs.ts with entries", () => {
+		expect(existsSync("src/generated/embedded-docs.ts")).toBe(true);
+		expect(EMBEDDED_DOCS.length).toBeGreaterThan(0);
+	});
+
+	it("each entry has [slug, title, content] tuple", () => {
+		for (const entry of EMBEDDED_DOCS) {
+			expect(entry).toHaveLength(3);
+			const [slug, title, content] = entry;
+			expect(typeof slug).toBe("string");
+			expect(slug.length).toBeGreaterThan(0);
+			expect(typeof title).toBe("string");
+			expect(title.length).toBeGreaterThan(0);
+			expect(typeof content).toBe("string");
+			expect(content.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("slugs do not contain .md extension", () => {
+		for (const [slug] of EMBEDDED_DOCS) {
+			expect(slug).not.toMatch(/\.md$/);
+		}
+	});
+
+	it("slugs do not start with docs/ or content/", () => {
+		for (const [slug] of EMBEDDED_DOCS) {
+			expect(slug).not.toMatch(/^(docs|content)\//);
+		}
+	});
+
+	it("README/index files collapse to parent directory slug", () => {
+		// The docs/userguide/cli/README.md should become userguide/cli
+		const slugs = EMBEDDED_DOCS.map(([slug]) => slug);
+		expect(slugs).toContain("userguide/cli");
+		expect(slugs).not.toContain("userguide/cli/readme");
+		expect(slugs).not.toContain("userguide/cli/README");
+	});
+
+	it("excludes docs/releases/** and docs/decisions/**", () => {
+		const slugs = EMBEDDED_DOCS.map(([slug]) => slug);
+		for (const slug of slugs) {
+			expect(slug).not.toMatch(/^releases\//);
+			expect(slug).not.toMatch(/^decisions\//);
+		}
+	});
+
+	it("content has frontmatter stripped", () => {
+		for (const [, , content] of EMBEDDED_DOCS) {
+			// Content should not start with --- (frontmatter delimiter)
+			expect(content.trimStart()).not.toMatch(/^---\s*\n/);
+		}
+	});
+
+	it("entries are sorted by slug", () => {
+		const slugs = EMBEDDED_DOCS.map(([slug]) => slug);
+		const sorted = [...slugs].sort();
+		expect(slugs).toEqual(sorted);
+	});
+});
+
+describe("findSimilar", () => {
+	const slugs = [
+		"userguide/cli/dev",
+		"userguide/cli/build",
+		"userguide/cli/bundle",
+		"userguide/sharing",
+		"reference/configuration",
+		"reference/plugins",
+		"guide/getting-started",
+	];
+
+	it("finds prefix matches", () => {
+		const results = findSimilar("userguide/cli", slugs, 3);
+		expect(results.length).toBeGreaterThan(0);
+		expect(results.every((r) => r.startsWith("userguide/cli"))).toBe(true);
+	});
+
+	it("finds substring matches", () => {
+		const results = findSimilar("config", slugs, 3);
+		expect(results).toContain("reference/configuration");
+	});
+
+	it("returns at most max results", () => {
+		const results = findSimilar("userguide", slugs, 2);
+		expect(results.length).toBeLessThanOrEqual(2);
+	});
+
+	it("returns empty for no match", () => {
+		const results = findSimilar("nonexistent-slug-xyz", slugs, 3);
+		expect(results).toEqual([]);
+	});
+
+	it("prioritizes prefix over substring", () => {
+		const results = findSimilar("guide", slugs, 3);
+		// "guide/getting-started" is a prefix match, should come first
+		expect(results[0]).toBe("guide/getting-started");
+	});
+});
+
+describe("embed-docs script", () => {
+	it("regenerates from manifest without errors", () => {
+		const output = execSync("bun scripts/embed-docs.ts", { encoding: "utf-8" });
+		expect(output).toContain("Embedded");
+		expect(output).toContain("docs into src/generated/embedded-docs.ts");
+	});
+});

package/src/__tests__/fixtures/fences/planning-visuals/invalid/bad-month-format.md

@@ -0,0 +1,10 @@
+:::gantt
+time-unit: month
+time-start: "2026-13"
+time-end: "2026-10"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/marker-format-mismatch.md

@@ -0,0 +1,13 @@
+:::gantt
+time-unit: month
+time-start: "2026-04"
+time-end: "2026-10"
+markers:
+  - label: "Gate"
+    date: "2026-W20"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/milestone-format-mismatch.md

@@ -0,0 +1,13 @@
+:::gantt
+time-unit: month
+time-start: "2026-04"
+time-end: "2026-10"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+milestones:
+  - label: "Go-live"
+    date: "2026-W20"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/missing-tracks.md

@@ -0,0 +1,5 @@
+:::gantt
+time-unit: week
+time-start: "2026-W01"
+time-end: "2026-W06"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/invalid/track-reversed.md

@@ -0,0 +1,10 @@
+:::gantt
+time-unit: week
+time-start: "2026-W14"
+time-end: "2026-W20"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-W18"
+    end: "2026-W15"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/markers-basic.md

@@ -0,0 +1,15 @@
+:::gantt
+time-unit: week
+time-start: "2026-W14"
+time-end: "2026-W30"
+markers:
+  - label: "Go/No-Go"
+    date: "2026-W20"
+  - label: "Phase Gate"
+    date: "2026-W28"
+tracks:
+  - label: "Phase 1"
+    depth: 1
+    start: "2026-W14"
+    end: "2026-W24"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/markers-no-milestones.md

@@ -0,0 +1,13 @@
+:::gantt
+time-unit: month
+time-start: "2026-03"
+time-end: "2026-10"
+markers:
+  - label: "Funding Gate"
+    date: "2026-06"
+tracks:
+  - label: "Build"
+    depth: 1
+    start: "2026-03"
+    end: "2026-10"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/month-basic.md

@@ -0,0 +1,16 @@
+:::gantt
+label: "Rollout"
+time-unit: month
+time-start: "2026-04"
+time-end: "2026-10"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-04"
+    end: "2026-07"
+  - label: "Wave 2"
+    depth: 1
+    start: "2026-08"
+    end: "2026-10"
+today: "2026-06"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/no-milestones.md

@@ -0,0 +1,10 @@
+:::gantt
+time-unit: week
+time-start: "2026-W01"
+time-end: "2026-W06"
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-W01"
+    end: "2026-W04"
+:::

package/src/__tests__/fixtures/fences/planning-visuals/valid/week-basic.md

@@ -0,0 +1,20 @@
+:::gantt
+label: "Rollout"
+time-unit: week
+time-start: "2026-W14"
+time-end: "2026-W20"
+max-depth: 2
+tracks:
+  - label: "Wave 1"
+    depth: 1
+    start: "2026-W14"
+    end: "2026-W18"
+    status: active
+  - label: "Client A"
+    depth: 2
+    start: "2026-W15"
+    end: "2026-W17"
+milestones:
+  - label: "Sign-off"
+    date: "2026-W19"
+:::

package/src/__tests__/planning-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 { validatePlanningVisualsFences } from "../shared.ts";
+
+const FIXTURES = join(__dirname, "fixtures", "fences", "planning-visuals");
+
+describe("planning-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 = validatePlanningVisualsFences(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 = validatePlanningVisualsFences(md);
+			expect(diags.length, `${f} should be invalid`).toBeGreaterThan(0);
+		}
+	});
+});

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

@@ -0,0 +1,68 @@
+import { expect, test } from "bun:test";
+
+type PlanningVisualsRegressionHooks = {
+	parseGanttNodesWithFirstLines: (
+		firstLines: string[],
+		between: any[],
+		endNode: any,
+	) => Record<string, unknown>;
+};
+
+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<PlanningVisualsRegressionHooks> {
+	// @ts-expect-error JS plugin registers test hooks on globalThis in non-DOM environments.
+	await import("../../plugins-dist/planning-visuals.js");
+	const hooks = (globalThis as any).__kitflyPlanningVisualsTest as
+		| PlanningVisualsRegressionHooks
+		| undefined;
+	if (!hooks) throw new Error("planning-visuals test hooks not found on globalThis");
+	return hooks;
+}
+
+test("planning-visuals: fragmented list-key switch preserves markers and milestones", async () => {
+	const { parseGanttNodesWithFirstLines } = await loadHooks();
+	const data = parseGanttNodesWithFirstLines(
+		['time-unit: "month"', 'time-start: "2026-03"', 'time-end: "2026-09"', "markers:"],
+		[],
+		new FakeElement("UL", "", [
+			new FakeElement("LI", 'label: "P66 Conf (May 26)"\ndate: "2026-05"\ntracks:'),
+			new FakeElement(
+				"LI",
+				'label: "Wave 1"\ndepth: 1\nstart: "2026-03"\nend: "2026-04"\nmilestones:',
+			),
+			new FakeElement("LI", 'label: "Auto Go-Live May 19"\ndate: "2026-05"\ntracks:'),
+			new FakeElement("LI", 'label: "Wave 2"\ndepth: 1\nstart: "2026-05"\nend: "2026-06"'),
+		]),
+	);
+
+	const markers = data.markers as Array<Record<string, string>>;
+	const tracks = data.tracks as Array<Record<string, string>>;
+	const milestones = data.milestones as Array<Record<string, string>>;
+
+	expect(markers).toHaveLength(1);
+	expect(markers[0].label).toBe("P66 Conf (May 26)");
+
+	expect(milestones).toHaveLength(1);
+	expect(milestones[0].label).toBe("Auto Go-Live May 19");
+
+	expect(tracks).toHaveLength(2);
+	expect(tracks[0].label).toBe("Wave 1");
+	expect(tracks[1].label).toBe("Wave 2");
+});