@mainahq/core 1.0.3 → 1.1.1

package/src/wiki/__tests__/indexer.test.ts

@@ -0,0 +1,285 @@
+import { describe, expect, it } from "bun:test";
+import { generateIndex } from "../indexer";
+import type { WikiArticle } from "../types";
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function makeArticle(
+	overrides: Partial<WikiArticle> & {
+		path: string;
+		type: WikiArticle["type"];
+		title: string;
+	},
+): WikiArticle {
+	return {
+		content: "",
+		contentHash: "abc123",
+		sourceHashes: [],
+		backlinks: [],
+		forwardLinks: [],
+		pageRank: 0,
+		lastCompiled: new Date().toISOString(),
+		referenceCount: 0,
+		ebbinghausScore: 1.0,
+		...overrides,
+	};
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────
+
+describe("Wiki Indexer", () => {
+	describe("generateIndex", () => {
+		it("should generate a markdown index with title", () => {
+			const index = generateIndex([]);
+			expect(index).toContain("# Wiki Index");
+		});
+
+		it("should show article count in the description", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/auth.md",
+					type: "module",
+					title: "Auth Module",
+				}),
+				makeArticle({
+					path: "wiki/entities/jwt.md",
+					type: "entity",
+					title: "JWT",
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("2 articles");
+		});
+
+		it("should group articles by type", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/auth.md",
+					type: "module",
+					title: "Auth Module",
+				}),
+				makeArticle({
+					path: "wiki/entities/jwt.md",
+					type: "entity",
+					title: "JWT",
+				}),
+				makeArticle({
+					path: "wiki/features/login.md",
+					type: "feature",
+					title: "Login Feature",
+				}),
+				makeArticle({
+					path: "wiki/decisions/use-jwt.md",
+					type: "decision",
+					title: "Use JWT",
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("## Modules");
+			expect(index).toContain("## Entities");
+			expect(index).toContain("## Features");
+			expect(index).toContain("## Decisions");
+		});
+
+		it("should include markdown links to articles", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/auth.md",
+					type: "module",
+					title: "Auth Module",
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("[Auth Module](wiki/modules/auth.md)");
+		});
+
+		it("should sort articles by PageRank within each group", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/entities/low.md",
+					type: "entity",
+					title: "Low PR",
+					pageRank: 0.1,
+				}),
+				makeArticle({
+					path: "wiki/entities/high.md",
+					type: "entity",
+					title: "High PR",
+					pageRank: 0.9,
+				}),
+				makeArticle({
+					path: "wiki/entities/mid.md",
+					type: "entity",
+					title: "Mid PR",
+					pageRank: 0.5,
+				}),
+			];
+
+			const index = generateIndex(articles);
+			const highIdx = index.indexOf("High PR");
+			const midIdx = index.indexOf("Mid PR");
+			const lowIdx = index.indexOf("Low PR");
+
+			expect(highIdx).toBeLessThan(midIdx);
+			expect(midIdx).toBeLessThan(lowIdx);
+		});
+
+		it("should include freshness indicators", () => {
+			const now = new Date().toISOString();
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/fresh.md",
+					type: "module",
+					title: "Fresh Module",
+					lastCompiled: now,
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("[fresh]");
+		});
+
+		it("should show stale indicator for old articles", () => {
+			const oldDate = new Date(
+				Date.now() - 60 * 24 * 60 * 60 * 1000,
+			).toISOString();
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/old.md",
+					type: "module",
+					title: "Old Module",
+					lastCompiled: oldDate,
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("[stale]");
+		});
+
+		it("should show aging indicator for articles 8-30 days old", () => {
+			const agingDate = new Date(
+				Date.now() - 15 * 24 * 60 * 60 * 1000,
+			).toISOString();
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/aging.md",
+					type: "module",
+					title: "Aging Module",
+					lastCompiled: agingDate,
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("[aging]");
+		});
+
+		it("should show recent indicator for articles 2-6 days old", () => {
+			const recentDate = new Date(
+				Date.now() - 3 * 24 * 60 * 60 * 1000,
+			).toISOString();
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/recent.md",
+					type: "module",
+					title: "Recent Module",
+					lastCompiled: recentDate,
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("[recent]");
+		});
+
+		it("should handle empty lastCompiled as stale", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/nodate.md",
+					type: "module",
+					title: "No Date",
+					lastCompiled: "",
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("[stale]");
+		});
+
+		it("should not render sections for types with no articles", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/auth.md",
+					type: "module",
+					title: "Auth Module",
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("## Modules");
+			expect(index).not.toContain("## Entities");
+			expect(index).not.toContain("## Features");
+			expect(index).not.toContain("## Decisions");
+		});
+
+		it("should render type sections in defined order", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/decisions/d.md",
+					type: "decision",
+					title: "Decision",
+				}),
+				makeArticle({
+					path: "wiki/features/f.md",
+					type: "feature",
+					title: "Feature",
+				}),
+				makeArticle({
+					path: "wiki/modules/m.md",
+					type: "module",
+					title: "Module",
+				}),
+				makeArticle({
+					path: "wiki/entities/e.md",
+					type: "entity",
+					title: "Entity",
+				}),
+			];
+
+			const index = generateIndex(articles);
+			const moduleIdx = index.indexOf("## Modules");
+			const entityIdx = index.indexOf("## Entities");
+			const featureIdx = index.indexOf("## Features");
+			const decisionIdx = index.indexOf("## Decisions");
+
+			// Order: Architecture > Modules > Entities > Features > Decisions
+			expect(moduleIdx).toBeLessThan(entityIdx);
+			expect(entityIdx).toBeLessThan(featureIdx);
+			expect(featureIdx).toBeLessThan(decisionIdx);
+		});
+
+		it("should report category count correctly", () => {
+			const articles = [
+				makeArticle({
+					path: "wiki/modules/a.md",
+					type: "module",
+					title: "A",
+				}),
+				makeArticle({
+					path: "wiki/modules/b.md",
+					type: "module",
+					title: "B",
+				}),
+				makeArticle({
+					path: "wiki/features/c.md",
+					type: "feature",
+					title: "C",
+				}),
+			];
+
+			const index = generateIndex(articles);
+			expect(index).toContain("2 categories");
+		});
+	});
+});

package/src/wiki/__tests__/linker.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it } from "bun:test";
+import type { KnowledgeGraph } from "../graph";
+import { generateLinks } from "../linker";
+import type { EdgeType } from "../types";
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+function makeGraph(
+	edges: Array<{ source: string; target: string; type: EdgeType }>,
+): KnowledgeGraph {
+	const nodes = new Map<
+		string,
+		{
+			id: string;
+			type: "entity" | "module" | "feature" | "decision" | "workflow";
+			label: string;
+			pageRank: number;
+		}
+	>();
+	const adjacency = new Map<string, Set<string>>();
+
+	for (const edge of edges) {
+		if (!nodes.has(edge.source)) {
+			nodes.set(edge.source, {
+				id: edge.source,
+				type: "entity",
+				label: edge.source,
+				pageRank: 0,
+			});
+		}
+		if (!nodes.has(edge.target)) {
+			nodes.set(edge.target, {
+				id: edge.target,
+				type: "entity",
+				label: edge.target,
+				pageRank: 0,
+			});
+		}
+
+		if (!adjacency.has(edge.source)) {
+			adjacency.set(edge.source, new Set());
+		}
+		if (!adjacency.has(edge.target)) {
+			adjacency.set(edge.target, new Set());
+		}
+		adjacency.get(edge.source)?.add(edge.target);
+		adjacency.get(edge.target)?.add(edge.source);
+	}
+
+	return {
+		nodes,
+		edges: edges.map((e) => ({ ...e, weight: 1.0 })),
+		adjacency,
+	};
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────
+
+describe("Wiki Linker", () => {
+	describe("generateLinks", () => {
+		it("should create forward links from source to target", () => {
+			const graph = makeGraph([
+				{ source: "entity:A", target: "entity:B", type: "calls" },
+			]);
+			const articleMap = new Map<string, string>();
+			articleMap.set("entity:A", "wiki/entities/A.md");
+			articleMap.set("entity:B", "wiki/entities/B.md");
+
+			const result = generateLinks(graph, articleMap);
+
+			const aLinks = result.forwardLinks.get("wiki/entities/A.md") ?? [];
+			expect(aLinks.length).toBe(1);
+			expect(aLinks[0]?.target).toBe("wiki/entities/B.md");
+			expect(aLinks[0]?.type).toBe("calls");
+		});
+
+		it("should create backlinks from target to source", () => {
+			const graph = makeGraph([
+				{ source: "entity:A", target: "entity:B", type: "calls" },
+			]);
+			const articleMap = new Map<string, string>();
+			articleMap.set("entity:A", "wiki/entities/A.md");
+			articleMap.set("entity:B", "wiki/entities/B.md");
+
+			const result = generateLinks(graph, articleMap);
+
+			const bBacklinks = result.backlinks.get("wiki/entities/B.md") ?? [];
+			expect(bBacklinks.length).toBe(1);
+			expect(bBacklinks[0]?.target).toBe("wiki/entities/A.md");
+		});
+
+		it("should skip edges where source or target has no article", () => {
+			const graph = makeGraph([
+				{ source: "entity:A", target: "entity:B", type: "calls" },
+			]);
+			const articleMap = new Map<string, string>();
+			articleMap.set("entity:A", "wiki/entities/A.md");
+			// entity:B has no article mapping
+
+			const result = generateLinks(graph, articleMap);
+
+			const aLinks = result.forwardLinks.get("wiki/entities/A.md") ?? [];
+			expect(aLinks.length).toBe(0);
+		});
+
+		it("should skip self-referential links (same article)", () => {
+			const graph = makeGraph([
+				{
+					source: "entity:A",
+					target: "entity:A",
+					type: "specified_by",
+				},
+			]);
+			const articleMap = new Map<string, string>();
+			articleMap.set("entity:A", "wiki/entities/A.md");
+
+			const result = generateLinks(graph, articleMap);
+
+			const aLinks = result.forwardLinks.get("wiki/entities/A.md") ?? [];
+			expect(aLinks.length).toBe(0);
+		});
+
+		it("should deduplicate links with the same target and type", () => {
+			const graph = makeGraph([
+				{ source: "entity:A", target: "entity:B", type: "calls" },
+				{ source: "entity:A", target: "entity:B", type: "calls" },
+			]);
+			const articleMap = new Map<string, string>();
+			articleMap.set("entity:A", "wiki/entities/A.md");
+			articleMap.set("entity:B", "wiki/entities/B.md");
+
+			const result = generateLinks(graph, articleMap);
+
+			const aLinks = result.forwardLinks.get("wiki/entities/A.md") ?? [];
+			expect(aLinks.length).toBe(1);
+		});
+
+		it("should keep links of different types to the same target", () => {
+			const graph = makeGraph([
+				{ source: "entity:A", target: "entity:B", type: "calls" },
+				{ source: "entity:A", target: "entity:B", type: "imports" },
+			]);
+			const articleMap = new Map<string, string>();
+			articleMap.set("entity:A", "wiki/entities/A.md");
+			articleMap.set("entity:B", "wiki/entities/B.md");
+
+			const result = generateLinks(graph, articleMap);
+
+			const aLinks = result.forwardLinks.get("wiki/entities/A.md") ?? [];
+			expect(aLinks.length).toBe(2);
+			const types = aLinks.map((l) => l.type).sort();
+			expect(types).toEqual(["calls", "imports"]);
+		});
+
+		it("should handle all 11 edge types", () => {
+			const allEdgeTypes: EdgeType[] = [
+				"calls",
+				"imports",
+				"inherits",
+				"references",
+				"member_of",
+				"modified_by",
+				"specified_by",
+				"decided_by",
+				"motivated_by",
+				"constrains",
+				"aligns_with",
+			];
+
+			const edges = allEdgeTypes.map((type, i) => ({
+				source: `entity:src-${i}`,
+				target: `entity:tgt-${i}`,
+				type,
+			}));
+
+			const graph = makeGraph(edges);
+			const articleMap = new Map<string, string>();
+			for (let i = 0; i < allEdgeTypes.length; i++) {
+				articleMap.set(`entity:src-${i}`, `wiki/entities/src-${i}.md`);
+				articleMap.set(`entity:tgt-${i}`, `wiki/entities/tgt-${i}.md`);
+			}
+
+			const result = generateLinks(graph, articleMap);
+
+			// Each edge type should produce at least one forward link
+			for (let i = 0; i < allEdgeTypes.length; i++) {
+				const links =
+					result.forwardLinks.get(`wiki/entities/src-${i}.md`) ?? [];
+				expect(links.length).toBeGreaterThanOrEqual(1);
+				expect(links[0]?.type).toBe(allEdgeTypes[i]);
+			}
+		});
+
+		it("should return empty maps for a graph with no edges", () => {
+			const graph: KnowledgeGraph = {
+				nodes: new Map(),
+				edges: [],
+				adjacency: new Map(),
+			};
+			const articleMap = new Map<string, string>();
+
+			const result = generateLinks(graph, articleMap);
+
+			expect(result.forwardLinks.size).toBe(0);
+			expect(result.backlinks.size).toBe(0);
+		});
+
+		it("should handle multiple forward links from one article", () => {
+			const graph = makeGraph([
+				{ source: "entity:A", target: "entity:B", type: "calls" },
+				{ source: "entity:A", target: "entity:C", type: "imports" },
+				{
+					source: "entity:A",
+					target: "entity:D",
+					type: "references",
+				},
+			]);
+			const articleMap = new Map<string, string>();
+			articleMap.set("entity:A", "wiki/entities/A.md");
+			articleMap.set("entity:B", "wiki/entities/B.md");
+			articleMap.set("entity:C", "wiki/entities/C.md");
+			articleMap.set("entity:D", "wiki/entities/D.md");
+
+			const result = generateLinks(graph, articleMap);
+
+			const aLinks = result.forwardLinks.get("wiki/entities/A.md") ?? [];
+			expect(aLinks.length).toBe(3);
+		});
+	});
+});