@mainahq/core 1.0.3 → 1.1.0

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

@@ -0,0 +1,229 @@
+import { describe, expect, it } from "bun:test";
+import { detectCommunities } from "../louvain";
+
+describe("Louvain Community Detection", () => {
+	describe("empty graph", () => {
+		it("should return empty communities and zero modularity", () => {
+			const adjacency = new Map<string, Set<string>>();
+			const result = detectCommunities(adjacency);
+
+			expect(result.communities.size).toBe(0);
+			expect(result.modularity).toBe(0);
+		});
+	});
+
+	describe("single node", () => {
+		it("should place a single node in its own community", () => {
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set());
+
+			const result = detectCommunities(adjacency);
+			expect(result.communities.size).toBe(1);
+
+			const allNodes = [...result.communities.values()].flat();
+			expect(allNodes).toContain("A");
+		});
+	});
+
+	describe("two connected nodes", () => {
+		it("should place two connected nodes in the same community", () => {
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set(["B"]));
+			adjacency.set("B", new Set(["A"]));
+
+			const result = detectCommunities(adjacency);
+
+			// They should be in the same community
+			const allMembers = [...result.communities.values()];
+			const communityWithA = allMembers.find((m) => m.includes("A"));
+			expect(communityWithA).toContain("B");
+		});
+	});
+
+	describe("known graph with two clusters", () => {
+		it("should detect two communities in a barbell graph", () => {
+			// Barbell: A-B-C fully connected, D-E-F fully connected, C-D bridge
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set(["B", "C"]));
+			adjacency.set("B", new Set(["A", "C"]));
+			adjacency.set("C", new Set(["A", "B", "D"]));
+			adjacency.set("D", new Set(["C", "E", "F"]));
+			adjacency.set("E", new Set(["D", "F"]));
+			adjacency.set("F", new Set(["D", "E"]));
+
+			const result = detectCommunities(adjacency);
+
+			// Should detect 2 communities
+			expect(result.communities.size).toBe(2);
+
+			// Verify each cluster is together
+			const allMembers = [...result.communities.values()];
+			const clusterWithA = allMembers.find((m) => m.includes("A"));
+			const clusterWithD = allMembers.find((m) => m.includes("D"));
+
+			expect(clusterWithA).toBeDefined();
+			expect(clusterWithD).toBeDefined();
+			expect(clusterWithA).toContain("B");
+			expect(clusterWithA).toContain("C");
+			expect(clusterWithD).toContain("E");
+			expect(clusterWithD).toContain("F");
+		});
+
+		it("should have positive modularity for a clustered graph", () => {
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set(["B", "C"]));
+			adjacency.set("B", new Set(["A", "C"]));
+			adjacency.set("C", new Set(["A", "B", "D"]));
+			adjacency.set("D", new Set(["C", "E", "F"]));
+			adjacency.set("E", new Set(["D", "F"]));
+			adjacency.set("F", new Set(["D", "E"]));
+
+			const result = detectCommunities(adjacency);
+			expect(result.modularity).toBeGreaterThan(0);
+		});
+	});
+
+	describe("disconnected components", () => {
+		it("should handle disconnected components correctly", () => {
+			const adjacency = new Map<string, Set<string>>();
+			// Component 1: A-B
+			adjacency.set("A", new Set(["B"]));
+			adjacency.set("B", new Set(["A"]));
+			// Component 2: C-D
+			adjacency.set("C", new Set(["D"]));
+			adjacency.set("D", new Set(["C"]));
+			// Isolated node
+			adjacency.set("E", new Set());
+
+			const result = detectCommunities(adjacency);
+
+			// All nodes should be assigned to a community
+			const allNodes = [...result.communities.values()].flat();
+			expect(allNodes).toContain("A");
+			expect(allNodes).toContain("B");
+			expect(allNodes).toContain("C");
+			expect(allNodes).toContain("D");
+			expect(allNodes).toContain("E");
+			expect(allNodes).toHaveLength(5);
+		});
+
+		it("should keep disconnected components in separate communities", () => {
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set(["B"]));
+			adjacency.set("B", new Set(["A"]));
+			adjacency.set("C", new Set(["D"]));
+			adjacency.set("D", new Set(["C"]));
+
+			const result = detectCommunities(adjacency);
+
+			// A and B should be together, C and D should be together
+			const allMembers = [...result.communities.values()];
+			const withA = allMembers.find((m) => m.includes("A"));
+			const withC = allMembers.find((m) => m.includes("C"));
+			expect(withA).toContain("B");
+			expect(withC).toContain("D");
+		});
+	});
+
+	describe("determinism", () => {
+		it("should produce the same result on repeated runs", () => {
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set(["B", "C"]));
+			adjacency.set("B", new Set(["A", "C"]));
+			adjacency.set("C", new Set(["A", "B", "D"]));
+			adjacency.set("D", new Set(["C", "E"]));
+			adjacency.set("E", new Set(["D"]));
+
+			const result1 = detectCommunities(adjacency);
+			const result2 = detectCommunities(adjacency);
+
+			expect(result1.communities.size).toBe(result2.communities.size);
+			expect(result1.modularity).toBe(result2.modularity);
+
+			for (const [key, members1] of result1.communities) {
+				const members2 = result2.communities.get(key);
+				expect(members2).toBeDefined();
+				expect(members1).toEqual(members2 ?? []);
+			}
+		});
+	});
+
+	describe("performance", () => {
+		it("should handle 1000+ nodes in under 1 second", () => {
+			const nodeCount = 1000;
+			const adjacency = new Map<string, Set<string>>();
+
+			// Create a graph with 10 clusters of 100 nodes each
+			for (let cluster = 0; cluster < 10; cluster++) {
+				for (let i = 0; i < 100; i++) {
+					const nodeId = `node-${cluster}-${i}`;
+					const neighbors = new Set<string>();
+
+					// Connect to ~10 nodes within the cluster
+					for (let j = 0; j < 10; j++) {
+						const neighborIdx = (i + j + 1) % 100;
+						neighbors.add(`node-${cluster}-${neighborIdx}`);
+					}
+
+					// One cross-cluster connection
+					if (i === 0 && cluster < 9) {
+						neighbors.add(`node-${cluster + 1}-0`);
+						// Also add the reverse connection
+						const nextNode = adjacency.get(`node-${cluster + 1}-0`);
+						if (nextNode) {
+							nextNode.add(nodeId);
+						}
+					}
+
+					adjacency.set(nodeId, neighbors);
+				}
+			}
+
+			// Ensure reverse edges for cross-cluster
+			for (let cluster = 0; cluster < 9; cluster++) {
+				const targetNode = adjacency.get(`node-${cluster + 1}-0`);
+				if (targetNode) {
+					targetNode.add(`node-${cluster}-0`);
+				}
+			}
+
+			const start = performance.now();
+			const result = detectCommunities(adjacency);
+			const elapsed = performance.now() - start;
+
+			expect(elapsed).toBeLessThan(1000);
+			expect(result.communities.size).toBeGreaterThan(0);
+
+			// All 1000 nodes should be assigned
+			const allNodes = [...result.communities.values()].flat();
+			expect(allNodes).toHaveLength(nodeCount);
+		});
+	});
+
+	describe("community numbering", () => {
+		it("should number communities starting from 0", () => {
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set(["B"]));
+			adjacency.set("B", new Set(["A"]));
+			adjacency.set("C", new Set(["D"]));
+			adjacency.set("D", new Set(["C"]));
+
+			const result = detectCommunities(adjacency);
+			const keys = [...result.communities.keys()].sort((a, b) => a - b);
+			expect(keys[0]).toBe(0);
+		});
+
+		it("should have contiguous community IDs", () => {
+			const adjacency = new Map<string, Set<string>>();
+			adjacency.set("A", new Set(["B"]));
+			adjacency.set("B", new Set(["A"]));
+			adjacency.set("C", new Set());
+
+			const result = detectCommunities(adjacency);
+			const keys = [...result.communities.keys()].sort((a, b) => a - b);
+			for (let i = 0; i < keys.length; i++) {
+				expect(keys[i]).toBe(i);
+			}
+		});
+	});
+});

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

@@ -0,0 +1,316 @@
+/**
+ * Tests for wiki query — AI-powered question answering over wiki articles.
+ */
+
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Mock AI before importing queryWiki ──────────────────────────────────
+
+let mockAIResponse: {
+	text: string | null;
+	fromAI: boolean;
+	hostDelegation: boolean;
+	promptHash?: string;
+} = { text: null, fromAI: false, hostDelegation: false };
+
+mock.module(join(import.meta.dir, "..", "..", "ai", "try-generate"), () => ({
+	tryAIGenerate: async () => mockAIResponse,
+}));
+
+const { queryWiki } = await import("../query");
+
+// ── Test Helpers ────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let wikiDir: string;
+
+function createTmpDir(): string {
+	const dir = join(
+		import.meta.dir,
+		`tmp-query-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function seedWikiArticles(wiki: string): void {
+	const subdirs = [
+		"modules",
+		"entities",
+		"features",
+		"decisions",
+		"architecture",
+		"raw",
+	];
+	for (const subdir of subdirs) {
+		mkdirSync(join(wiki, subdir), { recursive: true });
+	}
+
+	writeFileSync(
+		join(wiki, "modules", "core.md"),
+		[
+			"# Core Module",
+			"",
+			"The core module provides authentication and caching functionality.",
+			"",
+			"## Exports",
+			"",
+			"- `authenticate` (function)",
+			"- `CacheManager` (class)",
+			"- `Config` (interface)",
+		].join("\n"),
+	);
+
+	writeFileSync(
+		join(wiki, "entities", "user.md"),
+		[
+			"# User",
+			"",
+			"**Kind:** interface",
+			"**File:** `packages/core/src/user.ts:5`",
+			"",
+			"Represents an authenticated user in the system.",
+			"Contains email, role, and session token fields.",
+		].join("\n"),
+	);
+
+	writeFileSync(
+		join(wiki, "features", "login-flow.md"),
+		[
+			"# Login Flow",
+			"",
+			"## Acceptance Criteria",
+			"",
+			"- Users can log in with email and password",
+			"- JWT tokens are issued on success",
+			"- Failed attempts are rate-limited",
+		].join("\n"),
+	);
+
+	writeFileSync(
+		join(wiki, "decisions", "use-jwt.md"),
+		[
+			"# Use JWT for Authentication",
+			"",
+			"**Status:** accepted",
+			"",
+			"## Context",
+			"",
+			"We need stateless authentication for the API.",
+			"",
+			"## Decision",
+			"",
+			"Use JWT tokens with short expiry and refresh tokens.",
+		].join("\n"),
+	);
+
+	writeFileSync(
+		join(wiki, "architecture", "overview.md"),
+		[
+			"# Architecture Overview",
+			"",
+			"The system uses a layered architecture with three engines:",
+			"Context, Prompt, and Verify.",
+		].join("\n"),
+	);
+}
+
+beforeEach(() => {
+	tmpDir = createTmpDir();
+	wikiDir = join(tmpDir, ".maina", "wiki");
+	// Default: AI unavailable
+	mockAIResponse = { text: null, fromAI: false, hostDelegation: false };
+});
+
+afterEach(() => {
+	try {
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		// ignore
+	}
+});
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("queryWiki", () => {
+	test("returns not-initialized message when wiki dir missing", async () => {
+		const result = await queryWiki({
+			wikiDir: join(tmpDir, "nonexistent"),
+			question: "test",
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.answer).toContain("not initialized");
+			expect(result.value.sources).toHaveLength(0);
+		}
+	});
+
+	test("returns empty message when wiki has no articles", async () => {
+		mkdirSync(join(wikiDir, "modules"), { recursive: true });
+
+		const result = await queryWiki({ wikiDir, question: "anything" });
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.answer).toContain("empty");
+			expect(result.value.sources).toHaveLength(0);
+		}
+	});
+
+	test("returns no-match message for unrelated query", async () => {
+		seedWikiArticles(wikiDir);
+
+		const result = await queryWiki({
+			wikiDir,
+			question: "quantum computing blockchain",
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.answer).toContain("No articles match");
+			expect(result.value.sources).toHaveLength(0);
+		}
+	});
+
+	test("falls back to keyword excerpts when AI unavailable", async () => {
+		seedWikiArticles(wikiDir);
+		mockAIResponse = { text: null, fromAI: false, hostDelegation: false };
+
+		const result = await queryWiki({
+			wikiDir,
+			question: "authentication JWT",
+			repoRoot: tmpDir,
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.sources.length).toBeGreaterThan(0);
+			expect(result.value.answer).toContain("keyword match");
+			expect(result.value.cached).toBe(false);
+			// Should find JWT decision or core module
+			const hasAuthRelated = result.value.sources.some(
+				(s) => s.includes("use-jwt") || s.includes("core"),
+			);
+			expect(hasAuthRelated).toBe(true);
+		}
+	});
+
+	test("returns synthesized answer when AI is available", async () => {
+		seedWikiArticles(wikiDir);
+		mockAIResponse = {
+			text: "Authentication uses JWT tokens as described in [[decisions/use-jwt.md]]. The core module provides the authenticate function [[modules/core.md]].",
+			fromAI: true,
+			hostDelegation: false,
+			promptHash: "abc123",
+		};
+
+		const result = await queryWiki({
+			wikiDir,
+			question: "how does authentication work?",
+			repoRoot: tmpDir,
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.answer).toContain("JWT");
+			expect(result.value.answer).toContain("[[decisions/use-jwt.md]]");
+			expect(result.value.sources.length).toBeGreaterThan(0);
+			expect(result.value.cached).toBe(false);
+		}
+	});
+
+	test("respects maxArticles limit", async () => {
+		seedWikiArticles(wikiDir);
+		mockAIResponse = { text: null, fromAI: false, hostDelegation: false };
+
+		// Add many more articles to exceed limit
+		for (let i = 0; i < 15; i++) {
+			writeFileSync(
+				join(wikiDir, "entities", `entity-${i}.md`),
+				`# Entity ${i}\n\nThis entity handles authentication task ${i}.`,
+			);
+		}
+
+		const result = await queryWiki({
+			wikiDir,
+			question: "authentication",
+			maxArticles: 3,
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			// Sources should be limited to maxArticles
+			expect(result.value.sources.length).toBeLessThanOrEqual(3);
+		}
+	});
+
+	test("returns cached false for non-cached results", async () => {
+		seedWikiArticles(wikiDir);
+
+		const result = await queryWiki({
+			wikiDir,
+			question: "authentication",
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.cached).toBe(false);
+		}
+	});
+
+	test("handles AI error gracefully with fallback", async () => {
+		seedWikiArticles(wikiDir);
+
+		// Override mock to throw — re-mock the module
+		mock.module(
+			join(import.meta.dir, "..", "..", "ai", "try-generate"),
+			() => ({
+				tryAIGenerate: async () => {
+					throw new Error("API key invalid");
+				},
+			}),
+		);
+
+		const result = await queryWiki({
+			wikiDir,
+			question: "authentication JWT",
+			repoRoot: tmpDir,
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			// Should still return fallback results
+			expect(result.value.sources.length).toBeGreaterThan(0);
+			expect(result.value.answer).toContain("keyword match");
+		}
+
+		// Restore normal mock
+		mock.module(
+			join(import.meta.dir, "..", "..", "ai", "try-generate"),
+			() => ({
+				tryAIGenerate: async () => mockAIResponse,
+			}),
+		);
+	});
+
+	test("scores title matches higher than content matches", async () => {
+		seedWikiArticles(wikiDir);
+		mockAIResponse = { text: null, fromAI: false, hostDelegation: false };
+
+		const result = await queryWiki({
+			wikiDir,
+			question: "User",
+		});
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			// "User" entity should rank high since it matches the title
+			if (result.value.sources.length > 0) {
+				expect(result.value.sources[0]).toContain("user");
+			}
+		}
+	});
+});

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

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "bun:test";
+import {
+	DEFAULT_SCHEMA,
+	getArticleMaxLength,
+	getLinkSyntax,
+	validateArticleStructure,
+} from "../schema";
+import type { ArticleType } from "../types";
+
+describe("Wiki Schema", () => {
+	describe("DEFAULT_SCHEMA", () => {
+		it("should define rules for all 6 article types", () => {
+			const types: ArticleType[] = [
+				"module",
+				"entity",
+				"feature",
+				"decision",
+				"architecture",
+				"raw",
+			];
+			for (const type of types) {
+				expect(DEFAULT_SCHEMA.articleRules[type]).toBeDefined();
+			}
+		});
+
+		it("should have a schema version", () => {
+			expect(DEFAULT_SCHEMA.version).toBeTruthy();
+		});
+	});
+
+	describe("getArticleMaxLength", () => {
+		it("should return max length for each article type", () => {
+			expect(getArticleMaxLength("module")).toBeGreaterThan(0);
+			expect(getArticleMaxLength("entity")).toBeGreaterThan(0);
+			expect(getArticleMaxLength("feature")).toBeGreaterThan(0);
+			expect(getArticleMaxLength("decision")).toBeGreaterThan(0);
+			expect(getArticleMaxLength("architecture")).toBeGreaterThan(0);
+			expect(getArticleMaxLength("raw")).toBeGreaterThan(0);
+		});
+
+		it("should have entities shorter than modules", () => {
+			expect(getArticleMaxLength("entity")).toBeLessThanOrEqual(
+				getArticleMaxLength("module"),
+			);
+		});
+	});
+
+	describe("getLinkSyntax", () => {
+		it("should return wikilink format for entities", () => {
+			expect(getLinkSyntax("entity", "runPipeline")).toBe(
+				"[[entity:runPipeline]]",
+			);
+		});
+
+		it("should return wikilink format for features", () => {
+			expect(getLinkSyntax("feature", "001-auth")).toBe("[[feature:001-auth]]");
+		});
+
+		it("should return wikilink format for decisions", () => {
+			expect(getLinkSyntax("decision", "002-jwt")).toBe("[[decision:002-jwt]]");
+		});
+
+		it("should return wikilink format for modules", () => {
+			expect(getLinkSyntax("module", "auth")).toBe("[[module:auth]]");
+		});
+
+		it("should return wikilink format for architecture", () => {
+			expect(getLinkSyntax("architecture", "verify-pipeline")).toBe(
+				"[[architecture:verify-pipeline]]",
+			);
+		});
+	});
+
+	describe("validateArticleStructure", () => {
+		it("should pass for a valid module article", () => {
+			const content = [
+				"# Auth Module",
+				"",
+				"## Overview",
+				"Handles authentication.",
+				"",
+				"## Entities",
+				"- jwt.ts",
+				"",
+				"## Dependencies",
+				"- crypto module",
+			].join("\n");
+
+			const result = validateArticleStructure("module", content);
+			expect(result.valid).toBe(true);
+			expect(result.issues).toHaveLength(0);
+		});
+
+		it("should fail for article missing title", () => {
+			const content = "No title here, just text.";
+			const result = validateArticleStructure("entity", content);
+			expect(result.valid).toBe(false);
+			expect(result.issues.length).toBeGreaterThan(0);
+		});
+
+		it("should fail for article exceeding max length", () => {
+			const content = `# Long Article\n${"x".repeat(50_000)}`;
+			const result = validateArticleStructure("entity", content);
+			expect(result.valid).toBe(false);
+			expect(result.issues.some((i) => i.includes("length"))).toBe(true);
+		});
+
+		it("should pass for empty content with just a title", () => {
+			const content = "# Minimal Entity";
+			const result = validateArticleStructure("entity", content);
+			expect(result.valid).toBe(true);
+		});
+	});
+});