@mainahq/core 1.0.2 → 1.1.0

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

@@ -0,0 +1,349 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { calculateTokens } from "../budget";
+import { assembleWikiText, loadWikiContext } from "../wiki";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTempDir(): string {
+	const dir = join(
+		tmpdir(),
+		`maina-wiki-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+function writeWikiFile(
+	wikiDir: string,
+	relPath: string,
+	content: string,
+): void {
+	const fullPath = join(wikiDir, relPath);
+	const dir = fullPath.substring(0, fullPath.lastIndexOf("/"));
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(fullPath, content, "utf8");
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("loadWikiContext", () => {
+	let wikiDir: string;
+
+	beforeEach(() => {
+		wikiDir = makeTempDir();
+	});
+
+	afterEach(() => {
+		try {
+			rmSync(wikiDir, { recursive: true, force: true });
+		} catch {
+			// ignore cleanup errors
+		}
+	});
+
+	it("returns null when wiki directory does not exist", () => {
+		const result = loadWikiContext({
+			wikiDir: join(tmpdir(), "nonexistent-wiki-dir-xyz"),
+		});
+		expect(result).toBeNull();
+	});
+
+	it("returns null when wiki directory is empty", () => {
+		// wikiDir exists but has no files
+		const result = loadWikiContext({ wikiDir });
+		expect(result).toBeNull();
+	});
+
+	it("loads index.md when wiki exists", () => {
+		writeWikiFile(wikiDir, "index.md", "# Wiki Index\nOverview of articles.");
+
+		const result = loadWikiContext({ wikiDir });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("Wiki Index");
+		expect(result?.text).toContain("Overview of articles");
+	});
+
+	it("loads decision articles for review command", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"decisions/adr-001.md",
+			"# ADR-001: Use TypeScript\nWe chose TypeScript for type safety.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"features/feature-auth.md",
+			"# Auth Feature\nAuthentication implementation details.",
+		);
+
+		const result = loadWikiContext({ wikiDir, command: "review" });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("ADR-001");
+		// review loads decisions and modules, not features
+		expect(result?.text).not.toContain("Auth Feature");
+	});
+
+	it("loads feature articles for commit command", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"features/feature-wiki.md",
+			"# Wiki Feature\nWiki context layer details.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"decisions/adr-001.md",
+			"# ADR-001: TypeScript\nDecision content.",
+		);
+
+		const result = loadWikiContext({ wikiDir, command: "commit" });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("Wiki Feature");
+		// commit loads features and architecture, not decisions
+		expect(result?.text).not.toContain("ADR-001");
+	});
+
+	it("loads all article types for explain command (exploration mode)", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"decisions/adr-001.md",
+			"# ADR-001\nDecision content.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"features/feature-auth.md",
+			"# Auth Feature\nAuth details.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"modules/context-engine.md",
+			"# Context Engine\nEngine docs.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"architecture/overview.md",
+			"# Architecture Overview\nSystem design.",
+		);
+
+		const result = loadWikiContext({ wikiDir, command: "explain" });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("ADR-001");
+		expect(result?.text).toContain("Auth Feature");
+		expect(result?.text).toContain("Context Engine");
+		expect(result?.text).toContain("Architecture Overview");
+	});
+
+	it("loads decision articles for design command (conflict detection)", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"decisions/adr-001.md",
+			"# ADR-001\nDecision content.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"features/feature-auth.md",
+			"# Auth Feature\nShould not be loaded.",
+		);
+
+		const result = loadWikiContext({ wikiDir, command: "design" });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("ADR-001");
+		expect(result?.text).not.toContain("Auth Feature");
+	});
+
+	it("respects token budget (returns content within reasonable bounds)", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		// Create several articles
+		for (let i = 0; i < 10; i++) {
+			writeWikiFile(
+				wikiDir,
+				`decisions/adr-${String(i).padStart(3, "0")}.md`,
+				`# ADR-${i}\n${"Content line. ".repeat(100)}`,
+			);
+		}
+
+		const result = loadWikiContext({ wikiDir, command: "review" });
+		expect(result).not.toBeNull();
+		expect(result?.tokens).toBeGreaterThan(0);
+		// Tokens should match calculateTokens of the text
+		expect(result?.tokens).toBe(calculateTokens(result?.text ?? ""));
+	});
+
+	it("returns valid LayerContent with correct name and priority", () => {
+		writeWikiFile(wikiDir, "index.md", "# Wiki Index");
+
+		const result = loadWikiContext({ wikiDir });
+		expect(result).not.toBeNull();
+		expect(result?.name).toBe("wiki");
+		expect(result?.priority).toBe(4);
+		expect(typeof result?.text).toBe("string");
+		expect(typeof result?.tokens).toBe("number");
+	});
+
+	it("handles empty wiki directory gracefully", () => {
+		// Create a subdirectory but no files
+		mkdirSync(join(wikiDir, "decisions"), { recursive: true });
+
+		const result = loadWikiContext({ wikiDir });
+		// Directory has an entry (subdirectory) but no actual content
+		expect(result).toBeNull();
+	});
+
+	it("boosts articles relevant to working files", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"modules/context-engine.md",
+			"# Context Engine\nRelevant to working files.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"modules/git-ops.md",
+			"# Git Operations\nNot relevant to working files.",
+		);
+
+		const result = loadWikiContext({
+			wikiDir,
+			workingFiles: ["packages/core/src/context/engine.ts"],
+			command: "review",
+		});
+		expect(result).not.toBeNull();
+		// Both should be loaded since both are modules and command is review
+		expect(result?.text).toContain("Context Engine");
+	});
+
+	it("returns null when wiki dir has only empty subdirectories", () => {
+		mkdirSync(join(wikiDir, "decisions"), { recursive: true });
+		mkdirSync(join(wikiDir, "modules"), { recursive: true });
+
+		const result = loadWikiContext({ wikiDir });
+		expect(result).toBeNull();
+	});
+
+	it("includes index content in output even without other articles", () => {
+		writeWikiFile(wikiDir, "index.md", "# Project Wiki\nThis is the index.");
+
+		const result = loadWikiContext({ wikiDir });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("## Wiki Knowledge (Layer 5)");
+		expect(result?.text).toContain("### Index");
+		expect(result?.text).toContain("Project Wiki");
+	});
+
+	it("formats articles with wiki/ path prefix", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"decisions/adr-001.md",
+			"# ADR-001: Use Bun\nBun is faster.",
+		);
+
+		const result = loadWikiContext({ wikiDir, command: "review" });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("wiki/decisions/adr-001.md");
+	});
+
+	it("loads all articles when no command is specified (default)", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"decisions/adr-001.md",
+			"# Decision\nDecision content.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"features/feature.md",
+			"# Feature\nFeature content.",
+		);
+
+		const result = loadWikiContext({ wikiDir });
+		expect(result).not.toBeNull();
+		expect(result?.text).toContain("Decision");
+		expect(result?.text).toContain("Feature");
+	});
+
+	it("records loaded articles to signals file for RL tracking", () => {
+		writeWikiFile(wikiDir, "index.md", "# Index");
+		writeWikiFile(
+			wikiDir,
+			"decisions/adr-001.md",
+			"# ADR-001\nDecision content.",
+		);
+		writeWikiFile(
+			wikiDir,
+			"modules/context-engine.md",
+			"# Context Engine\nEngine docs.",
+		);
+
+		const result = loadWikiContext({ wikiDir, command: "review" });
+		expect(result).not.toBeNull();
+
+		// Check that the signals file was created
+		const signalsPath = join(wikiDir, ".signals.json");
+		expect(existsSync(signalsPath)).toBe(true);
+
+		const raw = readFileSync(signalsPath, "utf-8");
+		const parsed = JSON.parse(raw);
+		expect(parsed.loadSignals).toBeDefined();
+		expect(parsed.loadSignals.length).toBeGreaterThan(0);
+		expect(parsed.loadSignals[0].command).toBe("review");
+		expect(Array.isArray(parsed.loadSignals[0].articles)).toBe(true);
+	});
+});
+
+describe("assembleWikiText", () => {
+	it("formats with correct headers", () => {
+		const text = assembleWikiText("# Index content", [
+			{
+				path: "decisions/adr-001.md",
+				title: "ADR-001",
+				content: "Decision content.",
+				category: "decision",
+				score: 0.9,
+			},
+		]);
+
+		expect(text).toContain("## Wiki Knowledge (Layer 5)");
+		expect(text).toContain("### Index");
+		expect(text).toContain("# Index content");
+		expect(text).toContain("### Relevant Articles");
+		expect(text).toContain("#### ADR-001 (wiki/decisions/adr-001.md)");
+		expect(text).toContain("Decision content.");
+		expect(text).toContain("---");
+	});
+
+	it("handles empty index", () => {
+		const text = assembleWikiText("", [
+			{
+				path: "decisions/adr-001.md",
+				title: "ADR-001",
+				content: "Content.",
+				category: "decision",
+				score: 0.9,
+			},
+		]);
+
+		expect(text).toContain("## Wiki Knowledge (Layer 5)");
+		expect(text).not.toContain("### Index");
+		expect(text).toContain("### Relevant Articles");
+	});
+
+	it("handles empty articles", () => {
+		const text = assembleWikiText("# Index", []);
+
+		expect(text).toContain("## Wiki Knowledge (Layer 5)");
+		expect(text).toContain("### Index");
+		expect(text).not.toContain("### Relevant Articles");
+	});
+});

package/src/context/budget.ts

@@ -5,6 +5,7 @@ export interface BudgetAllocation {
 	episodic: number;
 	semantic: number;
 	retrieval: number;
+	wiki: number;
 	total: number;
 	headroom: number; // reserved for AI reasoning
 }
@@ -45,10 +46,11 @@ export function getBudgetRatio(mode: BudgetMode): number {
  * Calculates per-layer token allocations for a given mode and model context window.
  *
  * Layer proportions within the usable budget:
- *   working:   ~25%
- *   semantic:  ~33%
- *   episodic:  ~25%
- *   retrieval: ~17%  (remainder after the above three)
+ *   working:   ~12%
+ *   episodic:  ~12%
+ *   semantic:  ~16%
+ *   retrieval: ~8%  (remainder after the above four)
+ *   wiki:      ~12%
  */
 export function assembleBudget(
 	mode: BudgetMode,
@@ -58,17 +60,19 @@ export function assembleBudget(
 	const budget = Math.floor(modelContextWindow * ratio);
 	const headroom = modelContextWindow - budget;
 
-	const working = Math.floor(budget * 0.25);
-	const semantic = Math.floor(budget * 0.33);
-	const episodic = Math.floor(budget * 0.25);
+	const working = Math.floor(budget * 0.12);
+	const episodic = Math.floor(budget * 0.12);
+	const semantic = Math.floor(budget * 0.16);
+	const wiki = Math.floor(budget * 0.12);
 	// retrieval gets the exact remainder so all layer tokens sum to budget
-	const retrieval = budget - working - semantic - episodic;
+	const retrieval = budget - working - episodic - semantic - wiki;
 
 	return {
 		working,
 		semantic,
 		episodic,
 		retrieval,
+		wiki,
 		headroom,
 		total: modelContextWindow,
 	};

package/src/context/engine.ts

@@ -21,6 +21,7 @@ import {
 } from "./retrieval";
 import type { MainaCommand } from "./selector";
 import { getBudgetMode, getContextNeeds, needsLayer } from "./selector";
+import { loadWikiContext } from "./wiki";
 import { assembleWorkingText, loadWorkingContext } from "./working";
 
 // ── Public types ──────────────────────────────────────────────────────────────
@@ -418,6 +419,42 @@ export async function assembleContext(
 		}
 	}
 
+	// Wiki layer — synchronous, wrapped in a promise for parallel execution
+	if (needsLayer(needs, "wiki")) {
+		const wikiDir = join(mainaDir, "wiki");
+		// Gather working files from a quick git check
+		let workingFiles: string[] | undefined;
+		try {
+			const [staged, changed] = await Promise.all([
+				getStagedFiles(repoRoot),
+				getChangedFiles("HEAD~3", repoRoot),
+			]);
+			workingFiles = [...new Set([...staged, ...changed])];
+		} catch {
+			workingFiles = undefined;
+		}
+
+		const wikiResult = loadWikiContext({
+			wikiDir,
+			workingFiles,
+			command,
+		});
+
+		if (wikiResult !== null) {
+			layerPromises.push(Promise.resolve(wikiResult));
+		} else {
+			// Empty placeholder so it appears in reports
+			layerPromises.push(
+				Promise.resolve({
+					name: "wiki",
+					text: "",
+					tokens: 0,
+					priority: 4,
+				}),
+			);
+		}
+	}
+
 	// Build all layers in parallel
 	const builtLayers = await Promise.all(layerPromises);
 

package/src/context/selector.ts

@@ -17,6 +17,7 @@ export interface ContextNeeds {
 	episodic: boolean | string[];
 	semantic: boolean | string[];
 	retrieval: boolean;
+	wiki: boolean;
 }
 
 const CONTEXT_NEEDS: Record<MainaCommand, ContextNeeds> = {
@@ -25,45 +26,70 @@ const CONTEXT_NEEDS: Record<MainaCommand, ContextNeeds> = {
 		episodic: false,
 		semantic: ["conventions"],
 		retrieval: false,
+		wiki: true,
 	},
 	verify: {
 		working: true,
 		episodic: ["recent-reviews"],
 		semantic: ["adrs", "conventions"],
 		retrieval: false,
+		wiki: true,
+	},
+	context: {
+		working: true,
+		episodic: true,
+		semantic: true,
+		retrieval: true,
+		wiki: true,
 	},
-	context: { working: true, episodic: true, semantic: true, retrieval: true },
 	review: {
 		working: true,
 		episodic: ["past-reviews"],
 		semantic: ["adrs"],
 		retrieval: false,
+		wiki: true,
 	},
 	plan: {
 		working: true,
 		semantic: ["adrs", "conventions"],
 		episodic: false,
 		retrieval: false,
+		wiki: true,
+	},
+	explain: {
+		working: true,
+		episodic: false,
+		semantic: true,
+		retrieval: true,
+		wiki: true,
 	},
-	explain: { working: true, episodic: false, semantic: true, retrieval: true },
 	design: {
 		working: true,
 		episodic: false,
 		semantic: ["adrs"],
 		retrieval: false,
+		wiki: true,
 	},
 	ticket: {
 		working: false,
 		episodic: false,
 		semantic: ["modules"],
 		retrieval: false,
+		wiki: false,
+	},
+	analyze: {
+		working: true,
+		episodic: true,
+		semantic: true,
+		retrieval: false,
+		wiki: true,
 	},
-	analyze: { working: true, episodic: true, semantic: true, retrieval: false },
 	pr: {
 		working: true,
 		episodic: ["past-reviews"],
 		semantic: true,
 		retrieval: true,
+		wiki: true,
 	},
 };
 
@@ -73,7 +99,7 @@ export function getContextNeeds(command: MainaCommand): ContextNeeds {
 
 export function needsLayer(
 	needs: ContextNeeds,
-	layer: "working" | "episodic" | "semantic" | "retrieval",
+	layer: "working" | "episodic" | "semantic" | "retrieval" | "wiki",
 ): boolean {
 	const value = needs[layer];
 	if (Array.isArray(value)) {