@mainahq/core 1.0.3 → 1.1.0

package/src/wiki/__tests__/extractors/decision.test.ts

@@ -0,0 +1,323 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	extractDecisions,
+	extractSingleDecision,
+} from "../../extractors/decision";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		tmpdir(),
+		`wiki-decision-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("Decision Extractor", () => {
+	describe("extractSingleDecision", () => {
+		it("happy path: should extract a full ADR", () => {
+			const adrPath = join(tmpDir, "0002-jwt-strategy.md");
+			writeFileSync(
+				adrPath,
+				[
+					"# ADR-0002: Use JWT for Authentication",
+					"",
+					"## Status",
+					"Accepted",
+					"",
+					"## Context",
+					"We need stateless auth for microservices.",
+					"",
+					"## Decision",
+					"Use JWT tokens with RS256 signing.",
+					"",
+					"## Rationale",
+					"Stateless, scalable, widely supported.",
+					"",
+					"## Alternatives Considered",
+					"- Session-based auth — rejected because stateful",
+					"- OAuth2 only — rejected because too complex",
+					"",
+					"## Entities",
+					"- src/auth/jwt.ts",
+					"- src/middleware/auth.ts",
+				].join("\n"),
+			);
+
+			const result = extractSingleDecision(adrPath);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.id).toBe("0002-jwt-strategy");
+			expect(result.value.title).toBe("Use JWT for Authentication");
+			expect(result.value.status).toBe("accepted");
+			expect(result.value.context).toContain("stateless auth");
+			expect(result.value.decision).toContain("JWT tokens");
+			expect(result.value.rationale).toContain("Stateless");
+			expect(result.value.alternativesRejected).toHaveLength(2);
+			expect(result.value.entityMentions).toHaveLength(2);
+		});
+
+		it("should handle ADR with minimal sections", () => {
+			const adrPath = join(tmpDir, "0001-simple.md");
+			writeFileSync(
+				adrPath,
+				[
+					"# ADR-0001: Simple Decision",
+					"",
+					"## Status",
+					"Proposed",
+					"",
+					"## Decision",
+					"Do the thing.",
+				].join("\n"),
+			);
+
+			const result = extractSingleDecision(adrPath);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.id).toBe("0001-simple");
+			expect(result.value.status).toBe("proposed");
+			expect(result.value.alternativesRejected).toHaveLength(0);
+		});
+
+		it("should normalize status to lowercase", () => {
+			const adrPath = join(tmpDir, "0003-caps.md");
+			writeFileSync(
+				adrPath,
+				"# ADR-0003: Caps Status\n\n## Status\nDEPRECATED\n\n## Decision\nOld thing.",
+			);
+
+			const result = extractSingleDecision(adrPath);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+			expect(result.value.status).toBe("deprecated");
+		});
+
+		it("should handle superseded status", () => {
+			const adrPath = join(tmpDir, "0004-old.md");
+			writeFileSync(
+				adrPath,
+				"# ADR-0004: Old Decision\n\n## Status\nSuperseded by ADR-0005\n\n## Decision\nOld approach.",
+			);
+
+			const result = extractSingleDecision(adrPath);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+			expect(result.value.status).toBe("superseded");
+		});
+
+		it("edge case: non-existent file returns error", () => {
+			const result = extractSingleDecision(join(tmpDir, "nonexistent.md"));
+			expect(result.ok).toBe(false);
+		});
+	});
+
+	describe("extractDecisions", () => {
+		it("should extract all ADRs from a directory", () => {
+			writeFileSync(
+				join(tmpDir, "0001-first.md"),
+				"# ADR-0001: First\n\n## Status\nAccepted\n\n## Decision\nDo A.",
+			);
+			writeFileSync(
+				join(tmpDir, "0002-second.md"),
+				"# ADR-0002: Second\n\n## Status\nProposed\n\n## Decision\nDo B.",
+			);
+
+			const result = extractDecisions(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value).toHaveLength(2);
+		});
+
+		it("should skip non-markdown files", () => {
+			writeFileSync(join(tmpDir, "README.txt"), "Not an ADR");
+			writeFileSync(
+				join(tmpDir, "0001-real.md"),
+				"# ADR-0001: Real\n\n## Status\nAccepted\n\n## Decision\nX.",
+			);
+
+			const result = extractDecisions(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+			expect(result.value).toHaveLength(1);
+		});
+
+		it("should return empty array for empty directory", () => {
+			const result = extractDecisions(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+			expect(result.value).toHaveLength(0);
+		});
+
+		it("should return error for non-existent directory", () => {
+			const result = extractDecisions(join(tmpDir, "nonexistent"));
+			expect(result.ok).toBe(false);
+		});
+	});
+
+	describe("maina ADR format: # NNNN. Title", () => {
+		it("should parse maina-style ADR with nested consequences", () => {
+			const adrPath = join(tmpDir, "0001-karpathy-spec.md");
+			writeFileSync(
+				adrPath,
+				[
+					"# 0001. Karpathy-Principled Spec Quality System",
+					"",
+					"Date: 2026-04-03",
+					"",
+					"## Status",
+					"",
+					"Proposed",
+					"",
+					"## Context",
+					"",
+					"After 8 sprints and 769 tests, maina has a complete verification pipeline.",
+					"",
+					"## Decision",
+					"",
+					"Build a spec quality scoring system that scores specs 0-100.",
+					"",
+					"## Consequences",
+					"",
+					"### Positive",
+					"",
+					"- Specs become measurably better over time",
+					"- Developers can't rationalize skipping verification",
+					"",
+					"### Negative",
+					"",
+					"- Additional overhead on each commit",
+					"- False positives from measurability heuristics",
+					"",
+					"### Neutral",
+					"",
+					"- Requires cultural shift",
+				].join("\n"),
+			);
+
+			const result = extractSingleDecision(adrPath);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.id).toBe("0001-karpathy-spec");
+			expect(result.value.title).toBe(
+				"Karpathy-Principled Spec Quality System",
+			);
+			expect(result.value.status).toBe("proposed");
+			expect(result.value.context).toContain("769 tests");
+			expect(result.value.decision).toContain("spec quality scoring");
+			// Consequences should be merged into rationale
+			expect(result.value.rationale).toContain("Positive");
+			expect(result.value.rationale).toContain("measurably better");
+			expect(result.value.rationale).toContain("Negative");
+			expect(result.value.rationale).toContain("overhead");
+			// No alternatives section in maina ADRs
+			expect(result.value.alternativesRejected).toHaveLength(0);
+		});
+
+		it("should parse ADR with HLD/LLD and code paths", () => {
+			const adrPath = join(tmpDir, "0002-multi-lang.md");
+			writeFileSync(
+				adrPath,
+				[
+					"# 0002. Multi-language verify pipeline",
+					"",
+					"Date: 2026-04-03",
+					"",
+					"## Status",
+					"",
+					"Accepted",
+					"",
+					"## Context",
+					"",
+					"Verify pipeline was hardcoded for TypeScript.",
+					"",
+					"## Decision",
+					"",
+					"Introduce a LanguageProfile abstraction.",
+					"Uses src/verify/syntax-guard.ts and packages/core/src/context/semantic.ts.",
+					"",
+					"## Consequences",
+					"",
+					"### Positive",
+					"",
+					"- Maina works with Python, Go, and Rust projects",
+					"",
+					"### Negative",
+					"",
+					"- More tools to maintain",
+				].join("\n"),
+			);
+
+			const result = extractSingleDecision(adrPath);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.id).toBe("0002-multi-lang");
+			expect(result.value.title).toBe("Multi-language verify pipeline");
+			expect(result.value.status).toBe("accepted");
+			// Entity mentions extracted from full content
+			expect(result.value.entityMentions.length).toBeGreaterThan(0);
+			expect(result.value.entityMentions).toContain(
+				"src/verify/syntax-guard.ts",
+			);
+		});
+	});
+
+	describe("dogfood: extract from maina's own ADRs", () => {
+		it("should extract all 12 ADRs from maina's adr/ directory", () => {
+			const adrDir = join(process.cwd(), "adr");
+
+			const result = extractDecisions(adrDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value).toHaveLength(12);
+			for (const d of result.value) {
+				expect(d.id).toBeTruthy();
+				expect(d.title).toBeTruthy();
+				expect(d.title).not.toMatch(/^\d+\./);
+				expect(["proposed", "accepted", "deprecated", "superseded"]).toContain(
+					d.status,
+				);
+				expect(d.context.length).toBeGreaterThan(0);
+				expect(d.decision.length).toBeGreaterThan(0);
+				// All maina ADRs have Consequences sections
+				expect(d.rationale.length).toBeGreaterThan(0);
+			}
+		});
+
+		it("should extract correct titles from maina ADRs", () => {
+			const adrDir = join(process.cwd(), "adr");
+			const result = extractDecisions(adrDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			const titles = result.value.map((d) => d.title);
+			expect(titles).toContain("Karpathy-Principled Spec Quality System");
+			expect(titles).toContain("Multi-language verify pipeline");
+			expect(titles).toContain("Visual verification with Playwright");
+		});
+
+		it("should detect accepted status on maina ADRs", () => {
+			const adrDir = join(process.cwd(), "adr");
+			const result = extractDecisions(adrDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			const accepted = result.value.filter((d) => d.status === "accepted");
+			expect(accepted.length).toBeGreaterThanOrEqual(3);
+		});
+	});
+});

package/src/wiki/__tests__/extractors/feature.test.ts

@@ -0,0 +1,186 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	extractFeatures,
+	extractSingleFeature,
+} from "../../extractors/feature";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		tmpdir(),
+		`wiki-feature-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("Feature Extractor", () => {
+	describe("extractSingleFeature", () => {
+		it("happy path: should extract from plan.md + spec.md + tasks.md", () => {
+			const featureDir = join(tmpDir, "001-token-refresh");
+			mkdirSync(featureDir, { recursive: true });
+
+			writeFileSync(
+				join(featureDir, "plan.md"),
+				[
+					"# Implementation Plan: Token Refresh",
+					"",
+					"## Architecture",
+					"- Pattern: Background timer with JWT rotation",
+					"",
+					"## Tasks",
+					"- [ ] T001: Add refresh timer",
+					"- [x] T002: Wire error handler",
+				].join("\n"),
+			);
+
+			writeFileSync(
+				join(featureDir, "spec.md"),
+				[
+					"# Feature: Token Refresh",
+					"",
+					"## Acceptance Criteria",
+					"- [ ] Tokens refresh 5 minutes before expiry",
+					"- [ ] Failed refresh triggers re-login",
+					"",
+					"## Scope",
+					"Add automatic JWT token refresh to the auth module",
+				].join("\n"),
+			);
+
+			writeFileSync(
+				join(featureDir, "tasks.md"),
+				[
+					"# Task Breakdown",
+					"",
+					"## Tasks",
+					"- [ ] T001: Add refresh timer",
+					"- [x] T002: Wire error handler",
+				].join("\n"),
+			);
+
+			const result = extractSingleFeature(featureDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.id).toBe("001-token-refresh");
+			expect(result.value.title).toBe("Token Refresh");
+			expect(result.value.scope).toContain("JWT token refresh");
+			expect(result.value.tasks).toHaveLength(2);
+			expect(result.value.tasks[0]?.completed).toBe(false);
+			expect(result.value.tasks[1]?.completed).toBe(true);
+			expect(result.value.specAssertions).toHaveLength(2);
+		});
+
+		it("should extract from plan.md only when spec and tasks are missing", () => {
+			const featureDir = join(tmpDir, "002-simple");
+			mkdirSync(featureDir, { recursive: true });
+
+			writeFileSync(
+				join(featureDir, "plan.md"),
+				[
+					"# Implementation Plan: Simple Feature",
+					"",
+					"## Tasks",
+					"- [ ] T001: Do the thing",
+				].join("\n"),
+			);
+
+			const result = extractSingleFeature(featureDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.id).toBe("002-simple");
+			expect(result.value.title).toBe("Simple Feature");
+			expect(result.value.specAssertions).toHaveLength(0);
+		});
+
+		it("edge case: empty feature directory", () => {
+			const featureDir = join(tmpDir, "003-empty");
+			mkdirSync(featureDir, { recursive: true });
+
+			const result = extractSingleFeature(featureDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.id).toBe("003-empty");
+			expect(result.value.title).toBe("");
+			expect(result.value.tasks).toHaveLength(0);
+		});
+
+		it("edge case: non-existent directory returns error", () => {
+			const result = extractSingleFeature(join(tmpDir, "nonexistent"));
+			expect(result.ok).toBe(false);
+		});
+	});
+
+	describe("extractFeatures", () => {
+		it("should extract all features from a features directory", () => {
+			// Create two features
+			const feat1 = join(tmpDir, "001-auth");
+			mkdirSync(feat1, { recursive: true });
+			writeFileSync(
+				join(feat1, "plan.md"),
+				"# Implementation Plan: Auth\n\n## Tasks\n- [ ] T001: Login",
+			);
+
+			const feat2 = join(tmpDir, "002-cache");
+			mkdirSync(feat2, { recursive: true });
+			writeFileSync(
+				join(feat2, "plan.md"),
+				"# Implementation Plan: Cache\n\n## Tasks\n- [ ] T001: LRU",
+			);
+
+			const result = extractFeatures(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value).toHaveLength(2);
+			expect(result.value.map((f) => f.id)).toContain("001-auth");
+			expect(result.value.map((f) => f.id)).toContain("002-cache");
+		});
+
+		it("should return empty array for empty features directory", () => {
+			const result = extractFeatures(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+			expect(result.value).toHaveLength(0);
+		});
+
+		it("should skip non-directory entries", () => {
+			writeFileSync(join(tmpDir, "README.md"), "# Features");
+			const feat1 = join(tmpDir, "001-auth");
+			mkdirSync(feat1, { recursive: true });
+			writeFileSync(join(feat1, "plan.md"), "# Implementation Plan: Auth");
+
+			const result = extractFeatures(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+			expect(result.value).toHaveLength(1);
+		});
+	});
+
+	describe("dogfood: extract from maina's own features", () => {
+		it("should extract features from maina's .maina/features/", () => {
+			const mainaFeaturesDir = join(process.cwd(), ".maina", "features");
+
+			const result = extractFeatures(mainaFeaturesDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			// Maina has 35+ features at this point
+			expect(result.value.length).toBeGreaterThan(0);
+			// Each feature should have an id
+			for (const f of result.value) {
+				expect(f.id).toBeTruthy();
+			}
+		});
+	});
+});

package/src/wiki/__tests__/extractors/workflow.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { extractWorkflowTrace } from "../../extractors/workflow";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		tmpdir(),
+		`wiki-workflow-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(join(tmpDir, "workflow"), { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("Workflow Trace Extractor", () => {
+	describe("extractWorkflowTrace", () => {
+		it("happy path: should extract steps from workflow markdown", () => {
+			writeFileSync(
+				join(tmpDir, "workflow", "current.md"),
+				[
+					"# Workflow: token-refresh",
+					"",
+					"## brainstorm (2026-04-07T10:00:00.000Z)",
+					"Explored auth options with wiki context.",
+					"",
+					"## plan (2026-04-07T10:30:00.000Z)",
+					"Scaffolded feature 001-token-refresh.",
+					"",
+					"## commit (2026-04-07T12:00:00.000Z)",
+					"Committed initial implementation. 10 tools passed.",
+				].join("\n"),
+			);
+
+			const result = extractWorkflowTrace(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.featureId).toBe("token-refresh");
+			expect(result.value.steps).toHaveLength(3);
+			expect(result.value.steps[0]?.command).toBe("brainstorm");
+			expect(result.value.steps[0]?.timestamp).toBe("2026-04-07T10:00:00.000Z");
+			expect(result.value.steps[0]?.summary).toContain("Explored auth");
+			expect(result.value.steps[2]?.command).toBe("commit");
+		});
+
+		it("should handle workflow with only header", () => {
+			writeFileSync(
+				join(tmpDir, "workflow", "current.md"),
+				"# Workflow: empty-feature\n",
+			);
+
+			const result = extractWorkflowTrace(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.featureId).toBe("empty-feature");
+			expect(result.value.steps).toHaveLength(0);
+		});
+
+		it("should handle multi-line summaries", () => {
+			writeFileSync(
+				join(tmpDir, "workflow", "current.md"),
+				[
+					"# Workflow: multi-line",
+					"",
+					"## verify (2026-04-07T14:00:00.000Z)",
+					"Ran verification pipeline.",
+					"10 tools passed, 0 findings.",
+					"Coverage: 85%.",
+				].join("\n"),
+			);
+
+			const result = extractWorkflowTrace(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.steps).toHaveLength(1);
+			expect(result.value.steps[0]?.summary).toContain("10 tools passed");
+			expect(result.value.steps[0]?.summary).toContain("Coverage: 85%");
+		});
+
+		it("should return error when no workflow file exists", () => {
+			rmSync(join(tmpDir, "workflow", "current.md"), { force: true });
+
+			const result = extractWorkflowTrace(tmpDir);
+			expect(result.ok).toBe(false);
+		});
+
+		it("should handle workflow without feature name header", () => {
+			writeFileSync(
+				join(tmpDir, "workflow", "current.md"),
+				[
+					"# Workflow",
+					"",
+					"## commit (2026-04-07T12:00:00.000Z)",
+					"Quick commit.",
+				].join("\n"),
+			);
+
+			const result = extractWorkflowTrace(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.featureId).toBe("");
+			expect(result.value.steps).toHaveLength(1);
+		});
+
+		it("edge case: step without timestamp", () => {
+			writeFileSync(
+				join(tmpDir, "workflow", "current.md"),
+				["# Workflow: no-time", "", "## brainstorm", "No timestamp here."].join(
+					"\n",
+				),
+			);
+
+			const result = extractWorkflowTrace(tmpDir);
+			expect(result.ok).toBe(true);
+			if (!result.ok) return;
+
+			expect(result.value.steps).toHaveLength(1);
+			expect(result.value.steps[0]?.command).toBe("brainstorm");
+			expect(result.value.steps[0]?.timestamp).toBe("");
+		});
+	});
+});