@mainahq/core 0.2.0

package/src/features/traceability.ts

@@ -0,0 +1,260 @@
+/**
+ * Plan-to-code traceability.
+ *
+ * Reads plan.md from a feature directory, extracts tasks (T001, T002, etc.),
+ * and traces each task to matching test files, implementation files, and commits.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Result } from "../db/index";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface TaskTrace {
+	taskId: string;
+	description: string;
+	testFile: string | null;
+	implFile: string | null;
+	commitHash: string | null;
+}
+
+export interface TraceabilityReport {
+	featureDir: string;
+	tasks: TaskTrace[];
+	coverage: {
+		withTests: number;
+		withImpl: number;
+		withCommits: number;
+		total: number;
+	};
+}
+
+export interface TraceDeps {
+	gitLog?: (repoRoot: string) => Promise<string>;
+}
+
+// ── Task Parsing ─────────────────────────────────────────────────────────────
+
+interface ParsedTask {
+	id: string;
+	description: string;
+}
+
+/**
+ * Parse task lines from plan.md content.
+ * Matches: - T001: description, - [ ] T001: description, - [x] T001: description
+ */
+function parseTasks(planContent: string): ParsedTask[] {
+	const lines = planContent.split("\n");
+	const tasks: ParsedTask[] = [];
+	const taskPattern = /^-\s+(?:\[[ x]\]\s+)?T(\d+):\s*(.+)$/;
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		const match = trimmed.match(taskPattern);
+		if (match?.[1] && match[2]) {
+			tasks.push({
+				id: `T${match[1]}`,
+				description: match[2].trim(),
+			});
+		}
+	}
+
+	return tasks;
+}
+
+// ── File Search ──────────────────────────────────────────────────────────────
+
+/**
+ * Recursively collect file paths from a directory, skipping node_modules and hidden dirs.
+ */
+function collectFiles(dir: string): string[] {
+	const results: string[] = [];
+
+	if (!existsSync(dir)) return results;
+
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return results;
+	}
+
+	for (const entry of entries) {
+		if (entry.startsWith(".") || entry === "node_modules") continue;
+
+		const fullPath = join(dir, entry);
+		try {
+			const stat = statSync(fullPath);
+			if (stat.isDirectory()) {
+				results.push(...collectFiles(fullPath));
+			} else if (stat.isFile()) {
+				results.push(fullPath);
+			}
+		} catch {
+			// Skip inaccessible files
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Search for a test file containing the given task ID.
+ */
+function findTestFile(taskId: string, allFiles: string[]): string | null {
+	const testFiles = allFiles.filter(
+		(f) =>
+			f.includes("__tests__") ||
+			f.endsWith(".test.ts") ||
+			f.endsWith(".test.tsx") ||
+			f.endsWith(".test.js"),
+	);
+
+	for (const file of testFiles) {
+		try {
+			const content = readFileSync(file, "utf-8");
+			if (content.includes(taskId)) {
+				return file;
+			}
+		} catch {
+			// Skip unreadable files
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Search for an implementation file containing the task ID.
+ * Excludes test files.
+ */
+function findImplFile(taskId: string, allFiles: string[]): string | null {
+	const implFiles = allFiles.filter(
+		(f) =>
+			!f.includes("__tests__") &&
+			!f.endsWith(".test.ts") &&
+			!f.endsWith(".test.tsx") &&
+			!f.endsWith(".test.js") &&
+			(f.endsWith(".ts") || f.endsWith(".tsx") || f.endsWith(".js")),
+	);
+
+	for (const file of implFiles) {
+		try {
+			const content = readFileSync(file, "utf-8");
+			if (content.includes(taskId)) {
+				return file;
+			}
+		} catch {
+			// Skip unreadable files
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Search git log output for a commit mentioning the task ID.
+ * Returns the commit hash if found, null otherwise.
+ */
+function findCommit(taskId: string, gitLogOutput: string): string | null {
+	const lines = gitLogOutput.split("\n");
+	for (const line of lines) {
+		if (line.includes(taskId)) {
+			const hash = line.trim().split(" ")[0];
+			if (hash && hash.length >= 7) {
+				return hash;
+			}
+		}
+	}
+
+	return null;
+}
+
+// ── Default git log ──────────────────────────────────────────────────────────
+
+async function defaultGitLog(repoRoot: string): Promise<string> {
+	try {
+		const proc = Bun.spawn(["git", "log", "--oneline", "--all"], {
+			cwd: repoRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const stdout = await new Response(proc.stdout).text();
+		await proc.exited;
+		return stdout;
+	} catch {
+		return "";
+	}
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Trace a feature's plan tasks to test files, implementation files, and commits.
+ *
+ * @param featureDir - Path to the feature directory (containing plan.md)
+ * @param repoRoot - Path to the repository root (for file and commit search)
+ * @param deps - Optional dependency overrides (e.g., mock git log)
+ */
+export async function traceFeature(
+	featureDir: string,
+	repoRoot: string,
+	deps?: TraceDeps,
+): Promise<Result<TraceabilityReport, string>> {
+	if (!existsSync(featureDir)) {
+		return {
+			ok: false,
+			error: `Feature directory does not exist: ${featureDir}`,
+		};
+	}
+
+	const planPath = join(featureDir, "plan.md");
+	if (!existsSync(planPath)) {
+		return {
+			ok: false,
+			error: `plan.md not found at ${planPath}`,
+		};
+	}
+
+	const planContent = readFileSync(planPath, "utf-8");
+	const parsedTasks = parseTasks(planContent);
+
+	// Collect all files from repo root
+	const allFiles = collectFiles(repoRoot);
+
+	// Get git log
+	const gitLogFn = deps?.gitLog ?? defaultGitLog;
+	let gitLogOutput = "";
+	try {
+		gitLogOutput = await gitLogFn(repoRoot);
+	} catch {
+		// Git log failure should not block traceability
+	}
+
+	// Build task traces
+	const tasks: TaskTrace[] = parsedTasks.map((task) => ({
+		taskId: task.id,
+		description: task.description,
+		testFile: findTestFile(task.id, allFiles),
+		implFile: findImplFile(task.id, allFiles),
+		commitHash: findCommit(task.id, gitLogOutput),
+	}));
+
+	const coverage = {
+		withTests: tasks.filter((t) => t.testFile !== null).length,
+		withImpl: tasks.filter((t) => t.implFile !== null).length,
+		withCommits: tasks.filter((t) => t.commitHash !== null).length,
+		total: tasks.length,
+	};
+
+	return {
+		ok: true,
+		value: {
+			featureDir,
+			tasks,
+			coverage,
+		},
+	};
+}

package/src/feedback/__tests__/async-feedback.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "bun:test";
+import { getWorkflowId, recordFeedbackAsync } from "../collector";
+
+describe("recordFeedbackAsync", () => {
+	it("should not throw when called", () => {
+		// Fire-and-forget — should never throw
+		expect(() => {
+			recordFeedbackAsync(".maina", {
+				promptHash: "test-hash",
+				task: "commit",
+				accepted: true,
+				timestamp: new Date().toISOString(),
+				workflowStep: "commit",
+				workflowId: "test-wf-id",
+			});
+		}).not.toThrow();
+	});
+
+	it("should not block execution", () => {
+		const start = performance.now();
+		recordFeedbackAsync(".maina", {
+			promptHash: "test-hash",
+			task: "verify",
+			accepted: true,
+			timestamp: new Date().toISOString(),
+			workflowStep: "verify",
+			workflowId: "test-wf-id",
+		});
+		const elapsed = performance.now() - start;
+		// Should complete in <1ms (just queues a microtask)
+		expect(elapsed).toBeLessThan(5);
+	});
+});
+
+describe("getWorkflowId", () => {
+	it("should return consistent ID for same branch", () => {
+		const id1 = getWorkflowId("feature/015-test");
+		const id2 = getWorkflowId("feature/015-test");
+		expect(id1).toBe(id2);
+	});
+
+	it("should return different IDs for different branches", () => {
+		const id1 = getWorkflowId("feature/015-test");
+		const id2 = getWorkflowId("feature/016-other");
+		expect(id1).not.toBe(id2);
+	});
+
+	it("should return a 12-char string", () => {
+		const id = getWorkflowId("feature/test");
+		expect(id).toHaveLength(12);
+	});
+});

package/src/feedback/__tests__/collector.test.ts

@@ -0,0 +1,219 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getContextDb, getFeedbackDb } from "../../db/index";
+import { recordOutcome } from "../../prompts/engine";
+import {
+	type FeedbackRecord,
+	getFeedbackSummary,
+	recordFeedback,
+	recordFeedbackWithCompression,
+} from "../collector";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-collector-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	try {
+		const { rmSync } = require("node:fs");
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		// ignore
+	}
+});
+
+describe("recordFeedback", () => {
+	test("writes to feedback.db", () => {
+		const record: FeedbackRecord = {
+			promptHash: "test-hash-123",
+			task: "commit",
+			accepted: true,
+			timestamp: new Date().toISOString(),
+		};
+
+		recordFeedback(tmpDir, record);
+
+		// Verify directly in db
+		const dbResult = getFeedbackDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+
+		const { db } = dbResult.value;
+		const rows = db
+			.query("SELECT * FROM feedback WHERE prompt_hash = ?")
+			.all("test-hash-123") as Array<{
+			prompt_hash: string;
+			command: string;
+			accepted: number;
+			context: string | null;
+		}>;
+
+		expect(rows.length).toBe(1);
+		expect(rows[0]?.prompt_hash).toBe("test-hash-123");
+		expect(rows[0]?.command).toBe("commit");
+		expect(rows[0]?.accepted).toBe(1);
+	});
+
+	test("records modification as context", () => {
+		const record: FeedbackRecord = {
+			promptHash: "mod-hash",
+			task: "commit",
+			accepted: true,
+			modification: "user edited the message",
+			timestamp: new Date().toISOString(),
+		};
+
+		recordFeedback(tmpDir, record);
+
+		const dbResult = getFeedbackDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+
+		const { db } = dbResult.value;
+		const rows = db
+			.query("SELECT * FROM feedback WHERE prompt_hash = ?")
+			.all("mod-hash") as Array<{ context: string | null }>;
+
+		expect(rows[0]?.context).toBe("user edited the message");
+	});
+});
+
+describe("getFeedbackSummary", () => {
+	test("returns correct counts and rate", () => {
+		// Record some feedback using recordOutcome directly (same underlying storage)
+		recordOutcome(tmpDir, "hash-1", { accepted: true, command: "commit" });
+		recordOutcome(tmpDir, "hash-2", { accepted: true, command: "commit" });
+		recordOutcome(tmpDir, "hash-3", { accepted: false, command: "commit" });
+		recordOutcome(tmpDir, "hash-4", { accepted: false, command: "commit" });
+		recordOutcome(tmpDir, "hash-5", { accepted: true, command: "review" });
+
+		const summary = getFeedbackSummary(tmpDir, "commit");
+
+		expect(summary.total).toBe(4);
+		expect(summary.accepted).toBe(2);
+		expect(summary.rejected).toBe(2);
+		expect(summary.acceptRate).toBeCloseTo(0.5, 5);
+	});
+
+	test("returns zeros when no data exists", () => {
+		const summary = getFeedbackSummary(tmpDir, "commit");
+
+		expect(summary.total).toBe(0);
+		expect(summary.accepted).toBe(0);
+		expect(summary.rejected).toBe(0);
+		expect(summary.acceptRate).toBe(0);
+	});
+});
+
+describe("recordFeedbackWithCompression", () => {
+	test("accepted review with aiOutput triggers compression and episodic storage", () => {
+		recordFeedbackWithCompression(tmpDir, {
+			promptHash: "review-hash-1",
+			task: "review",
+			accepted: true,
+			timestamp: new Date().toISOString(),
+			aiOutput: "Overall: code looks good. Warning: missing null check.",
+			diff: `--- a/src/index.ts
++++ b/src/index.ts
+@@ -1,3 +1,5 @@
++import { bar } from './bar';`,
+		});
+
+		// Verify episodic entry was created in context DB
+		const dbResult = getContextDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+
+		const { db } = dbResult.value;
+		const rows = db
+			.query(
+				"SELECT * FROM episodic_entries WHERE type = 'review' ORDER BY created_at DESC",
+			)
+			.all() as Array<{
+			content: string;
+			summary: string;
+			type: string;
+		}>;
+
+		expect(rows.length).toBe(1);
+		expect(rows[0]?.type).toBe("review");
+		expect(rows[0]?.summary).toBe("Accepted review");
+		expect(rows[0]?.content).toContain("[review] Accepted review");
+	});
+
+	test("rejected review does NOT trigger compression", () => {
+		recordFeedbackWithCompression(tmpDir, {
+			promptHash: "review-hash-2",
+			task: "review",
+			accepted: false,
+			timestamp: new Date().toISOString(),
+			aiOutput: "Some review output",
+			diff: "some diff",
+		});
+
+		// Verify no episodic entry was created
+		const dbResult = getContextDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+
+		const { db } = dbResult.value;
+		const rows = db
+			.query("SELECT * FROM episodic_entries WHERE type = 'review'")
+			.all();
+
+		expect(rows.length).toBe(0);
+	});
+
+	test("accepted non-review task does NOT trigger compression", () => {
+		recordFeedbackWithCompression(tmpDir, {
+			promptHash: "commit-hash-1",
+			task: "commit",
+			accepted: true,
+			timestamp: new Date().toISOString(),
+			aiOutput: "Generated commit message",
+			diff: "some diff",
+		});
+
+		// Verify no episodic entry was created
+		const dbResult = getContextDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+
+		const { db } = dbResult.value;
+		const rows = db
+			.query("SELECT * FROM episodic_entries WHERE type = 'review'")
+			.all();
+
+		expect(rows.length).toBe(0);
+	});
+
+	test("missing aiOutput on accepted review does NOT trigger compression", () => {
+		recordFeedbackWithCompression(tmpDir, {
+			promptHash: "review-hash-3",
+			task: "review",
+			accepted: true,
+			timestamp: new Date().toISOString(),
+			// No aiOutput provided
+			diff: "some diff",
+		});
+
+		// Verify no episodic entry was created
+		const dbResult = getContextDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+
+		const { db } = dbResult.value;
+		const rows = db
+			.query("SELECT * FROM episodic_entries WHERE type = 'review'")
+			.all();
+
+		expect(rows.length).toBe(0);
+	});
+});

package/src/feedback/__tests__/compress.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getContextDb } from "../../db/index";
+import { compressReview, storeCompressedReview } from "../compress";
+
+let tmpDir: string;
+
+beforeEach(() => {
+	tmpDir = join(
+		import.meta.dir,
+		`tmp-compress-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+	try {
+		const { rmSync } = require("node:fs");
+		rmSync(tmpDir, { recursive: true, force: true });
+	} catch {
+		// ignore
+	}
+});
+
+describe("compressReview", () => {
+	test("returns compressed string for accepted review", () => {
+		const result = compressReview({
+			diff: `--- a/src/index.ts
++++ b/src/index.ts
+@@ -1,3 +1,5 @@
+ import { foo } from './foo';
++import { bar } from './bar';
+
+-export const x = 1;
++export const x = foo() + bar();
++export const y = 2;`,
+			aiOutput: `## Review Summary
+Found 2 issues in the changes:
+1. Warning: Missing error handling in foo() call
+2. Issue: Variable 'y' is exported but never tested
+
+Overall: Acceptable with minor improvements suggested.`,
+			task: "review",
+			accepted: true,
+		});
+
+		expect(result).not.toBeNull();
+		expect(typeof result).toBe("string");
+		expect(result?.length).toBeGreaterThan(0);
+	});
+
+	test("returns null for rejected review", () => {
+		const result = compressReview({
+			diff: "some diff",
+			aiOutput: "some output",
+			task: "review",
+			accepted: false,
+		});
+
+		expect(result).toBeNull();
+	});
+
+	test("compressed output is under 2000 characters (approx 500 tokens)", () => {
+		// Create a large diff and review output
+		const longDiff = Array(100)
+			.fill(null)
+			.map(
+				(_, i) => `--- a/src/file${i}.ts
++++ b/src/file${i}.ts
+@@ -1,3 +1,5 @@
+ import { something } from './something';
++import { newThing } from './new-thing';
+
+-export const old = 1;
++export const updated = newThing();
++export const extra = 2;`,
+			)
+			.join("\n");
+
+		const longAiOutput = Array(50)
+			.fill(null)
+			.map(
+				(_, i) =>
+					`${i + 1}. Warning: issue found in file${i}.ts — missing error handling for edge case where input is null. This could lead to runtime errors in production. Fix: add null check before calling the function.`,
+			)
+			.join("\n");
+
+		const result = compressReview({
+			diff: longDiff,
+			aiOutput: longAiOutput,
+			task: "review",
+			accepted: true,
+		});
+
+		expect(result).not.toBeNull();
+		expect(result?.length).toBeLessThanOrEqual(2000);
+	});
+
+	test("extracts file names from diff headers", () => {
+		const result = compressReview({
+			diff: `--- a/packages/core/src/ai/index.ts
++++ b/packages/core/src/ai/index.ts
+@@ -1,3 +1,5 @@
++import { bar } from './bar';
+--- a/packages/cli/src/commands/verify.ts
++++ b/packages/cli/src/commands/verify.ts
+@@ -10,3 +10,5 @@
++const x = 1;`,
+			aiOutput: `Review found no critical issues.
+Minor warning: consider adding type annotations.`,
+			task: "review",
+			accepted: true,
+		});
+
+		expect(result).not.toBeNull();
+		expect(result).toContain("packages/core/src/ai/index.ts");
+		expect(result).toContain("packages/cli/src/commands/verify.ts");
+	});
+});
+
+describe("storeCompressedReview", () => {
+	test("writes compressed review to episodic DB", () => {
+		const compressed =
+			"[review] Files: src/index.ts | Findings: missing error handling | Verdict: accepted";
+
+		storeCompressedReview(tmpDir, compressed, "review");
+
+		// Verify entry exists in episodic_entries
+		const dbResult = getContextDb(tmpDir);
+		expect(dbResult.ok).toBe(true);
+		if (!dbResult.ok) return;
+
+		const { db } = dbResult.value;
+		const rows = db
+			.query(
+				"SELECT * FROM episodic_entries WHERE type = 'review' ORDER BY created_at DESC",
+			)
+			.all() as Array<{
+			content: string;
+			summary: string;
+			type: string;
+		}>;
+
+		expect(rows.length).toBe(1);
+		expect(rows[0]?.content).toBe(compressed);
+		expect(rows[0]?.summary).toBe("Accepted review");
+		expect(rows[0]?.type).toBe("review");
+	});
+});