@mainahq/core 0.2.0

package/src/explain/__tests__/explain.test.ts

@@ -0,0 +1,173 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getContextDb } from "../../db/index.ts";
+import { generateDependencyDiagram, generateModuleSummary } from "../index.ts";
+
+const TEST_DIR = join(tmpdir(), `maina-explain-test-${Date.now()}`);
+
+beforeAll(() => {
+	mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterAll(() => {
+	rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+function makeDir(sub: string): string {
+	const d = join(TEST_DIR, sub);
+	mkdirSync(d, { recursive: true });
+	return d;
+}
+
+// ── generateDependencyDiagram ───────────────────────────────────────────────
+
+describe("generateDependencyDiagram", () => {
+	test("no edges returns empty graph", () => {
+		const mainaDir = makeDir("diagram-empty");
+		const result = generateDependencyDiagram(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value).toBe("graph LR\n");
+	});
+
+	test("with edges returns valid Mermaid syntax", () => {
+		const mainaDir = makeDir("diagram-edges");
+
+		const dbResult = getContextDb(mainaDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+
+		db.exec(`
+			INSERT INTO dependency_edges (id, source_file, target_file, weight, type)
+			VALUES
+				('e1', 'src/context/engine.ts', 'src/context/budget.ts', 1.0, 'import'),
+				('e2', 'src/context/engine.ts', 'src/context/selector.ts', 1.0, 'import'),
+				('e3', 'src/verify/pipeline.ts', 'src/verify/syntax-guard.ts', 1.0, 'import')
+		`);
+
+		const result = generateDependencyDiagram(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		expect(result.value).toContain("graph LR");
+		expect(result.value).toContain("context/engine --> context/budget");
+		expect(result.value).toContain("context/engine --> context/selector");
+		expect(result.value).toContain("verify/pipeline --> verify/syntax-guard");
+		db.close();
+	});
+
+	test("with scope filter only returns matching edges", () => {
+		const mainaDir = makeDir("diagram-scope");
+
+		const dbResult = getContextDb(mainaDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+
+		db.exec(`
+			INSERT INTO dependency_edges (id, source_file, target_file, weight, type)
+			VALUES
+				('e1', 'src/context/engine.ts', 'src/context/budget.ts', 1.0, 'import'),
+				('e2', 'src/verify/pipeline.ts', 'src/verify/syntax-guard.ts', 1.0, 'import'),
+				('e3', 'src/context/engine.ts', 'src/verify/detect.ts', 0.5, 'reference')
+		`);
+
+		const result = generateDependencyDiagram(mainaDir, {
+			scope: "context",
+		});
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		expect(result.value).toContain("context/engine --> context/budget");
+		// Edge e3 involves context, so it should be included
+		expect(result.value).toContain("context/engine --> verify/detect");
+		// Edge e2 is verify-only, should not be included
+		expect(result.value).not.toContain(
+			"verify/pipeline --> verify/syntax-guard",
+		);
+		db.close();
+	});
+
+	test("DB error returns error Result", () => {
+		// Use a path that can't be a DB (e.g. inside a non-existent deeply nested path with null bytes)
+		const result = generateDependencyDiagram("/dev/null/nonexistent");
+		expect(result.ok).toBe(false);
+		if (result.ok) return;
+		expect(typeof result.error).toBe("string");
+	});
+});
+
+// ── generateModuleSummary ───────────────────────────────────────────────────
+
+describe("generateModuleSummary", () => {
+	test("no entities returns empty array", () => {
+		const mainaDir = makeDir("summary-empty");
+		const result = generateModuleSummary(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.value).toEqual([]);
+	});
+
+	test("with entities returns correct counts per module", () => {
+		const mainaDir = makeDir("summary-entities");
+
+		const dbResult = getContextDb(mainaDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+		const { db } = dbResult.value;
+
+		db.exec(`
+			INSERT INTO semantic_entities (id, file_path, name, kind, start_line, end_line, updated_at)
+			VALUES
+				('s1', 'src/context/engine.ts', 'assembleContext', 'function', 1, 50, '2026-01-01'),
+				('s2', 'src/context/engine.ts', 'ContextOptions', 'interface', 51, 60, '2026-01-01'),
+				('s3', 'src/context/budget.ts', 'calculateTokens', 'function', 1, 30, '2026-01-01'),
+				('s4', 'src/verify/pipeline.ts', 'runPipeline', 'function', 1, 100, '2026-01-01'),
+				('s5', 'src/verify/pipeline.ts', 'PipelineResult', 'type', 101, 110, '2026-01-01'),
+				('s6', 'src/verify/pipeline.ts', 'PipelineRunner', 'class', 111, 200, '2026-01-01')
+		`);
+
+		const result = generateModuleSummary(mainaDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const summaries = result.value;
+
+		// Should have entries for context/engine, context/budget, verify/pipeline
+		expect(summaries.length).toBe(3);
+
+		const contextEngine = summaries.find((s) => s.module === "context/engine");
+		expect(contextEngine).toBeDefined();
+		expect(contextEngine?.entityCount).toBe(2);
+		expect(contextEngine?.functions).toBe(1);
+		expect(contextEngine?.interfaces).toBe(1);
+		expect(contextEngine?.classes).toBe(0);
+		expect(contextEngine?.types).toBe(0);
+
+		const verifyPipeline = summaries.find(
+			(s) => s.module === "verify/pipeline",
+		);
+		expect(verifyPipeline).toBeDefined();
+		expect(verifyPipeline?.entityCount).toBe(3);
+		expect(verifyPipeline?.functions).toBe(1);
+		expect(verifyPipeline?.classes).toBe(1);
+		expect(verifyPipeline?.types).toBe(1);
+
+		const contextBudget = summaries.find((s) => s.module === "context/budget");
+		expect(contextBudget).toBeDefined();
+		expect(contextBudget?.entityCount).toBe(1);
+		expect(contextBudget?.functions).toBe(1);
+
+		db.close();
+	});
+
+	test("DB error returns error Result", () => {
+		const result = generateModuleSummary("/dev/null/nonexistent");
+		expect(result.ok).toBe(false);
+		if (result.ok) return;
+		expect(typeof result.error).toBe("string");
+	});
+});

package/src/explain/index.ts

@@ -0,0 +1,181 @@
+/**
+ * Explain Module — Generate Mermaid dependency diagrams and module summaries.
+ *
+ * Uses the Context Engine semantic layer (dependency_edges and semantic_entities
+ * tables) to visualize codebase structure.
+ */
+
+import type { Result } from "../db/index.ts";
+import { getContextDb } from "../db/index.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface ModuleSummary {
+	module: string;
+	entityCount: number;
+	functions: number;
+	classes: number;
+	interfaces: number;
+	types: number;
+}
+
+export interface DiagramOptions {
+	scope?: string;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Extract a short module label from a file path.
+ * e.g. "src/context/engine.ts" -> "context/engine"
+ *      "context/budget.ts" -> "context/budget"
+ */
+function toModuleLabel(filePath: string): string {
+	// Strip leading src/ if present
+	const stripped = filePath.replace(/^src\//, "");
+	// Remove file extension
+	return stripped.replace(/\.[^/.]+$/, "");
+}
+
+// ── generateDependencyDiagram ────────────────────────────────────────────────
+
+/**
+ * Read the dependency graph from the Context Engine DB (dependency_edges table)
+ * and generate a Mermaid flowchart diagram string.
+ *
+ * If `scope` is provided, filters to only edges where source or target
+ * involves that directory.
+ *
+ * Returns a Mermaid markdown string on success, or an error on failure.
+ * Never throws.
+ */
+export function generateDependencyDiagram(
+	mainaDir: string,
+	options?: DiagramOptions,
+): Result<string> {
+	try {
+		const dbResult = getContextDb(mainaDir);
+		if (!dbResult.ok) return { ok: false, error: dbResult.error };
+
+		const { db } = dbResult.value;
+
+		const rows = db
+			.prepare("SELECT source_file, target_file FROM dependency_edges")
+			.all() as Array<{ source_file: string; target_file: string }>;
+
+		let lines = rows.map((row) => ({
+			source: toModuleLabel(row.source_file),
+			target: toModuleLabel(row.target_file),
+		}));
+
+		// Apply scope filter if provided
+		if (options?.scope) {
+			const scope = options.scope;
+			lines = lines.filter(
+				(edge) =>
+					edge.source.startsWith(scope) || edge.target.startsWith(scope),
+			);
+		}
+
+		// Build Mermaid diagram
+		let diagram = "graph LR\n";
+		for (const edge of lines) {
+			diagram += `  ${edge.source} --> ${edge.target}\n`;
+		}
+
+		db.close();
+		return { ok: true, value: diagram };
+	} catch (e) {
+		return { ok: false, error: e instanceof Error ? e.message : String(e) };
+	}
+}
+
+// ── generateModuleSummary ───────────────────────────────────────────────────
+
+/**
+ * Read semantic_entities table from Context Engine DB, group entities by
+ * file/module, and return a summary of each module.
+ *
+ * Returns an array of ModuleSummary on success, or an error on failure.
+ * Never throws.
+ */
+export function generateModuleSummary(
+	mainaDir: string,
+): Result<ModuleSummary[]> {
+	try {
+		const dbResult = getContextDb(mainaDir);
+		if (!dbResult.ok) return { ok: false, error: dbResult.error };
+
+		const { db } = dbResult.value;
+
+		const rows = db
+			.prepare("SELECT file_path, kind FROM semantic_entities")
+			.all() as Array<{ file_path: string; kind: string }>;
+
+		if (rows.length === 0) {
+			db.close();
+			return { ok: true, value: [] };
+		}
+
+		// Group by module label
+		const moduleMap = new Map<
+			string,
+			{
+				functions: number;
+				classes: number;
+				interfaces: number;
+				types: number;
+				total: number;
+			}
+		>();
+
+		for (const row of rows) {
+			const mod = toModuleLabel(row.file_path);
+			const entry = moduleMap.get(mod) ?? {
+				functions: 0,
+				classes: 0,
+				interfaces: 0,
+				types: 0,
+				total: 0,
+			};
+
+			entry.total++;
+			switch (row.kind) {
+				case "function":
+					entry.functions++;
+					break;
+				case "class":
+					entry.classes++;
+					break;
+				case "interface":
+					entry.interfaces++;
+					break;
+				case "type":
+					entry.types++;
+					break;
+			}
+
+			moduleMap.set(mod, entry);
+		}
+
+		const summaries: ModuleSummary[] = [];
+		for (const [mod, entry] of moduleMap) {
+			summaries.push({
+				module: mod,
+				entityCount: entry.total,
+				functions: entry.functions,
+				classes: entry.classes,
+				interfaces: entry.interfaces,
+				types: entry.types,
+			});
+		}
+
+		// Sort by module name for deterministic output
+		summaries.sort((a, b) => a.module.localeCompare(b.module));
+
+		db.close();
+		return { ok: true, value: summaries };
+	} catch (e) {
+		return { ok: false, error: e instanceof Error ? e.message : String(e) };
+	}
+}

package/src/features/__tests__/analyzer.test.ts

@@ -0,0 +1,358 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { analyze } from "../analyzer";
+
+function makeTmpDir(): string {
+	const dir = join(
+		tmpdir(),
+		`maina-analyzer-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+const SPEC_CONTENT = `# Feature: User Auth
+
+## User stories
+- As a user, I want to log in with email/password
+
+## Acceptance criteria
+- Login validates email format
+- Failed login shows error message
+`;
+
+const PLAN_CONTENT = `# Implementation Plan
+
+## Architecture
+- JWT authentication with bcrypt
+
+## Tasks
+- T001: Implement login with email format validation
+- T002: Add error messages for failed login attempts
+`;
+
+const TASKS_CONTENT = `# Tasks
+
+- [ ] T001: Implement login with email format validation
+- [ ] T002: Add error messages for failed login attempts
+`;
+
+describe("analyze", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTmpDir();
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	// --- Feature dir doesn't exist → error Result ---
+	test("non-existent feature dir returns error Result", () => {
+		const result = analyze(join(tmpDir, "non-existent"));
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.error).toContain("does not exist");
+		}
+	});
+
+	// --- All three files present and consistent → no findings ---
+	test("all three consistent files produce no findings", () => {
+		writeFileSync(join(tmpDir, "spec.md"), SPEC_CONTENT);
+		writeFileSync(join(tmpDir, "plan.md"), PLAN_CONTENT);
+		writeFileSync(join(tmpDir, "tasks.md"), TASKS_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		expect(result.value.findings).toHaveLength(0);
+		expect(result.value.summary.errors).toBe(0);
+		expect(result.value.summary.warnings).toBe(0);
+		expect(result.value.summary.info).toBe(0);
+	});
+
+	// --- Missing spec.md → finding with category "missing-file" ---
+	test("missing spec.md produces missing-file finding", () => {
+		writeFileSync(join(tmpDir, "plan.md"), PLAN_CONTENT);
+		writeFileSync(join(tmpDir, "tasks.md"), TASKS_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const missingFile = result.value.findings.find(
+			(f) => f.category === "missing-file" && f.file === "spec.md",
+		);
+		expect(missingFile).toBeDefined();
+		expect(missingFile?.severity).toBe("warning");
+	});
+
+	// --- Missing plan.md → finding with category "missing-file" ---
+	test("missing plan.md produces missing-file finding", () => {
+		writeFileSync(join(tmpDir, "spec.md"), SPEC_CONTENT);
+		writeFileSync(join(tmpDir, "tasks.md"), TASKS_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const missingFile = result.value.findings.find(
+			(f) => f.category === "missing-file" && f.file === "plan.md",
+		);
+		expect(missingFile).toBeDefined();
+		expect(missingFile?.severity).toBe("warning");
+	});
+
+	// --- Missing tasks.md → finding with category "missing-file" ---
+	test("missing tasks.md produces missing-file finding", () => {
+		writeFileSync(join(tmpDir, "spec.md"), SPEC_CONTENT);
+		writeFileSync(join(tmpDir, "plan.md"), PLAN_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const missingFile = result.value.findings.find(
+			(f) => f.category === "missing-file" && f.file === "tasks.md",
+		);
+		expect(missingFile).toBeDefined();
+		expect(missingFile?.severity).toBe("info");
+	});
+
+	// --- Spec criterion not covered by any task → "spec-coverage" error ---
+	test("uncovered spec criterion produces spec-coverage error", () => {
+		writeFileSync(
+			join(tmpDir, "spec.md"),
+			`# Feature: User Auth
+
+## Acceptance criteria
+- Login validates email format
+- Failed login shows error message
+- Password reset sends email within 30 seconds
+`,
+		);
+		writeFileSync(
+			join(tmpDir, "plan.md"),
+			`# Implementation Plan
+
+## Tasks
+- T001: Implement login with email format validation
+- T002: Add error messages for failed login attempts
+`,
+		);
+		writeFileSync(
+			join(tmpDir, "tasks.md"),
+			`# Tasks
+
+- [ ] T001: Implement login with email format validation
+- [ ] T002: Add error messages for failed login attempts
+`,
+		);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const coverageFindings = result.value.findings.filter(
+			(f) => f.category === "spec-coverage",
+		);
+		expect(coverageFindings.length).toBeGreaterThan(0);
+		expect(coverageFindings[0]?.severity).toBe("error");
+		expect(
+			coverageFindings.some((f) =>
+				f.message.toLowerCase().includes("password reset"),
+			),
+		).toBe(true);
+	});
+
+	// --- Task in plan.md not mapping to spec → "orphaned-task" warning ---
+	test("orphaned task in plan.md produces orphaned-task warning", () => {
+		writeFileSync(
+			join(tmpDir, "spec.md"),
+			`# Feature: User Auth
+
+## Acceptance criteria
+- Login validates email format
+`,
+		);
+		writeFileSync(
+			join(tmpDir, "plan.md"),
+			`# Implementation Plan
+
+## Tasks
+- T001: Implement login with email format validation
+- T002: Set up Kubernetes deployment pipeline
+`,
+		);
+		writeFileSync(
+			join(tmpDir, "tasks.md"),
+			`# Tasks
+
+- [ ] T001: Implement login with email format validation
+- [ ] T002: Set up Kubernetes deployment pipeline
+`,
+		);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const orphaned = result.value.findings.filter(
+			(f) => f.category === "orphaned-task",
+		);
+		expect(orphaned.length).toBeGreaterThan(0);
+		expect(orphaned[0]?.severity).toBe("warning");
+		expect(
+			orphaned.some((f) => f.message.toLowerCase().includes("kubernetes")),
+		).toBe(true);
+	});
+
+	// --- spec.md contains implementation keywords → "separation-violation" warning ---
+	test("spec.md with implementation keywords produces separation-violation", () => {
+		writeFileSync(
+			join(tmpDir, "spec.md"),
+			`# Feature: User Auth
+
+## Acceptance criteria
+- Login validates email format using JWT endpoint
+- Failed login shows error message via REST API
+`,
+		);
+		writeFileSync(join(tmpDir, "plan.md"), PLAN_CONTENT);
+		writeFileSync(join(tmpDir, "tasks.md"), TASKS_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const violations = result.value.findings.filter(
+			(f) => f.category === "separation-violation" && f.file === "spec.md",
+		);
+		expect(violations.length).toBeGreaterThan(0);
+		expect(violations[0]?.severity).toBe("warning");
+	});
+
+	// --- plan.md contains user story language → "separation-violation" warning ---
+	test("plan.md with user story language produces separation-violation", () => {
+		writeFileSync(join(tmpDir, "spec.md"), SPEC_CONTENT);
+		writeFileSync(
+			join(tmpDir, "plan.md"),
+			`# Implementation Plan
+
+## Architecture
+- JWT authentication with bcrypt
+- As a user, I want fast login
+
+## Tasks
+- T001: Implement login with email format validation
+- T002: Add error messages for failed login attempts
+`,
+		);
+		writeFileSync(join(tmpDir, "tasks.md"), TASKS_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const violations = result.value.findings.filter(
+			(f) => f.category === "separation-violation" && f.file === "plan.md",
+		);
+		expect(violations.length).toBeGreaterThan(0);
+		expect(violations[0]?.severity).toBe("warning");
+	});
+
+	// --- Different task counts between plan.md and tasks.md → "task-consistency" warning ---
+	test("different task counts between plan.md and tasks.md produces task-consistency warning", () => {
+		writeFileSync(join(tmpDir, "spec.md"), SPEC_CONTENT);
+		writeFileSync(
+			join(tmpDir, "plan.md"),
+			`# Implementation Plan
+
+## Tasks
+- T001: Implement login with email format validation
+- T002: Add error messages for failed login attempts
+- T003: Add rate limiting
+`,
+		);
+		writeFileSync(join(tmpDir, "tasks.md"), TASKS_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const consistency = result.value.findings.filter(
+			(f) => f.category === "task-consistency",
+		);
+		expect(consistency.length).toBeGreaterThan(0);
+		expect(consistency[0]?.severity).toBe("warning");
+		expect(consistency[0]?.message).toContain("3");
+		expect(consistency[0]?.message).toContain("2");
+	});
+
+	// --- Contradicting task descriptions → "contradiction" warning ---
+	test("contradicting task descriptions produce contradiction warning", () => {
+		writeFileSync(join(tmpDir, "spec.md"), SPEC_CONTENT);
+		writeFileSync(
+			join(tmpDir, "plan.md"),
+			`# Implementation Plan
+
+## Tasks
+- T001: Implement login with email format validation
+- T002: Add error messages for failed login attempts
+`,
+		);
+		writeFileSync(
+			join(tmpDir, "tasks.md"),
+			`# Tasks
+
+- [ ] T001: Implement login with email format validation
+- [ ] T002: Build notification service for alerts
+`,
+		);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const contradictions = result.value.findings.filter(
+			(f) => f.category === "contradiction",
+		);
+		expect(contradictions.length).toBeGreaterThan(0);
+		expect(contradictions[0]?.severity).toBe("warning");
+		expect(contradictions[0]?.message).toContain("T002");
+	});
+
+	// --- Summary correctly counts errors/warnings/info ---
+	test("summary correctly counts errors, warnings, and info", () => {
+		// Missing spec → warning, missing plan → warning, missing tasks → info
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		const { summary } = result.value;
+		// 3 missing-file findings: spec (warning), plan (warning), tasks (info)
+		expect(summary.warnings).toBe(2);
+		expect(summary.info).toBe(1);
+		expect(summary.errors).toBe(0);
+		expect(summary.errors + summary.warnings + summary.info).toBe(
+			result.value.findings.length,
+		);
+	});
+
+	// --- featureDir is captured in report ---
+	test("report includes featureDir", () => {
+		writeFileSync(join(tmpDir, "spec.md"), SPEC_CONTENT);
+		writeFileSync(join(tmpDir, "plan.md"), PLAN_CONTENT);
+		writeFileSync(join(tmpDir, "tasks.md"), TASKS_CONTENT);
+
+		const result = analyze(tmpDir);
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+
+		expect(result.value.featureDir).toBe(tmpDir);
+	});
+});