@mainahq/core 0.2.0

package/src/verify/fix.ts

@@ -0,0 +1,317 @@
+/**
+ * AI Fix Generation — generates minimal code fixes for verification findings.
+ *
+ * Takes findings from the Verify Engine, checks cache first, then uses the
+ * Prompt Engine + AI to generate unified-diff fixes. Results are cached so
+ * identical findings never hit the AI twice.
+ *
+ * Response format expected from AI:
+ *   ### Fix for finding: <tool>/<ruleId> at <file>:<line>
+ *   **Explanation:** <why this fix works>
+ *   **Confidence:** high|medium|low
+ *   ```diff
+ *   --- a/<file>
+ *   +++ b/<file>
+ *   @@ ... @@
+ *    context
+ *   -old line
+ *   +new line
+ *   ```
+ */
+
+import { generate } from "../ai/index";
+import { hashContent } from "../cache/keys";
+import { createCacheManager } from "../cache/manager";
+import { buildSystemPrompt } from "../prompts/engine";
+import type { Finding } from "./diff-filter";
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface FixSuggestion {
+	finding: Finding;
+	diff: string;
+	explanation: string;
+	confidence: "high" | "medium" | "low";
+}
+
+export interface FixResult {
+	suggestions: FixSuggestion[];
+	cached: boolean;
+	model?: string;
+}
+
+export interface FixOptions {
+	mainaDir: string;
+	cwd?: string;
+	contextText?: string;
+}
+
+// ─── Hashing ──────────────────────────────────────────────────────────────
+
+/**
+ * Deterministic hash of a finding for cache key generation.
+ * Includes tool, file, line, message, and ruleId.
+ */
+export function hashFinding(finding: Finding): string {
+	const input = [
+		finding.tool,
+		finding.file,
+		String(finding.line),
+		finding.message,
+		finding.ruleId ?? "",
+	].join("|");
+	return hashContent(input);
+}
+
+/**
+ * Build a composite cache key from multiple findings.
+ */
+function buildFixCacheKey(findings: Finding[]): string {
+	const hashes = findings.map(hashFinding).sort();
+	return hashContent(`fix:${hashes.join(":")}`);
+}
+
+// ─── Response Parsing ─────────────────────────────────────────────────────
+
+/**
+ * Match a parsed fix block to its original finding by matching tool/ruleId
+ * and file:line from the header.
+ */
+function matchFinding(
+	header: string,
+	findings: Finding[],
+): Finding | undefined {
+	// Header format: "### Fix for finding: <tool>/<ruleId> at <file>:<line>"
+	// or "### Fix for finding: <tool> at <file>:<line>" (no ruleId)
+	const headerMatch = header.match(
+		/### Fix for finding:\s*(\S+?)(?:\/(\S+))?\s+at\s+(\S+?):(\d+)/,
+	);
+	if (!headerMatch) {
+		// Fall back to index-based matching (handled by caller)
+		return undefined;
+	}
+
+	const [, tool, ruleId, file, lineStr] = headerMatch;
+	const line = Number.parseInt(lineStr ?? "0", 10);
+
+	// Try exact match first (tool + ruleId + file + line)
+	for (const f of findings) {
+		if (f.tool === tool && f.file === file && f.line === line) {
+			return f;
+		}
+	}
+
+	// Try matching by tool/ruleId and file
+	for (const f of findings) {
+		const fTool = f.ruleId ? `${f.tool}/${f.ruleId}` : f.tool;
+		const headerTool = ruleId ? `${tool}/${ruleId}` : (tool ?? "");
+		if (fTool === headerTool && f.file === file) {
+			return f;
+		}
+	}
+
+	// Try matching by file and line only
+	for (const f of findings) {
+		if (f.file === file && f.line === line) {
+			return f;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Parse the structured AI response into FixSuggestion objects.
+ *
+ * Expected format per fix:
+ *   ### Fix for finding: <tool>/<ruleId> at <file>:<line>
+ *   **Explanation:** <text>
+ *   **Confidence:** high|medium|low
+ *   ```diff
+ *   <unified diff content>
+ *   ```
+ */
+export function parseFixResponse(
+	response: string,
+	findings: Finding[],
+): FixSuggestion[] {
+	if (!response.trim()) {
+		return [];
+	}
+
+	const suggestions: FixSuggestion[] = [];
+
+	// Split response into fix blocks by "### Fix for finding:" headers
+	const blocks = response.split(/(?=### Fix for finding:)/);
+
+	let blockIndex = 0;
+	for (const block of blocks) {
+		if (!block.includes("### Fix for finding:")) {
+			continue;
+		}
+
+		// Extract explanation
+		const explanationMatch = block.match(
+			/\*\*Explanation:\*\*\s*(.+?)(?:\n\n|\n\*\*)/s,
+		);
+		const explanation = explanationMatch?.[1]?.trim() ?? "";
+
+		// Extract confidence
+		const confidenceMatch = block.match(
+			/\*\*Confidence:\*\*\s*(high|medium|low)/i,
+		);
+		const confidence = (confidenceMatch?.[1]?.toLowerCase() ??
+			"low") as FixSuggestion["confidence"];
+
+		// Extract diff
+		const diffMatch = block.match(/```diff\n([\s\S]*?)```/);
+		const diff = diffMatch?.[1]?.trim() ?? "";
+
+		if (!diff) {
+			continue;
+		}
+
+		// Match to finding
+		const header = block.split("\n")[0] ?? "";
+		const finding = matchFinding(header, findings) ?? findings[blockIndex];
+
+		if (!finding) {
+			continue;
+		}
+
+		suggestions.push({
+			finding,
+			diff,
+			explanation,
+			confidence,
+		});
+
+		blockIndex++;
+	}
+
+	return suggestions;
+}
+
+// ─── Prompt Formatting ───────────────────────────────────────────────────
+
+/**
+ * Format findings into a text block for the prompt template.
+ */
+function formatFindings(findings: Finding[]): string {
+	return findings
+		.map((f, i) => {
+			const ruleInfo = f.ruleId ? ` (${f.ruleId})` : "";
+			const colInfo = f.column ? `:${f.column}` : "";
+			return `${i + 1}. [${f.severity.toUpperCase()}] ${f.tool}${ruleInfo} — ${f.file}:${f.line}${colInfo}\n   ${f.message}`;
+		})
+		.join("\n\n");
+}
+
+/**
+ * Build the user prompt instructing the AI how to format its response.
+ */
+function buildUserPrompt(findings: Finding[]): string {
+	const formatted = formatFindings(findings);
+	return [
+		"Generate fixes for the following findings. Use this exact format for each fix:",
+		"",
+		"### Fix for finding: <tool>/<ruleId> at <file>:<line>",
+		"",
+		"**Explanation:** <why this fix works>",
+		"",
+		"**Confidence:** high|medium|low",
+		"",
+		"```diff",
+		"--- a/<file>",
+		"+++ b/<file>",
+		"@@ ... @@",
+		" context",
+		"-old line",
+		"+new line",
+		"```",
+		"",
+		"---",
+		"",
+		"Findings:",
+		"",
+		formatted,
+	].join("\n");
+}
+
+// ─── Main Entry Point ────────────────────────────────────────────────────
+
+/**
+ * Generate fixes for the given findings using AI.
+ *
+ * 1. Return early for empty findings.
+ * 2. Check cache by findings hash — return cached result if found.
+ * 3. Build system prompt via Prompt Engine.
+ * 4. Call AI with formatted findings and context.
+ * 5. Parse response into FixSuggestion objects.
+ * 6. Cache the result and return.
+ */
+export async function generateFixes(
+	findings: Finding[],
+	options: FixOptions,
+): Promise<FixResult> {
+	// No findings, no work
+	if (findings.length === 0) {
+		return { suggestions: [], cached: false };
+	}
+
+	const { mainaDir, contextText } = options;
+
+	// Build cache key from all findings
+	const cacheKey = buildFixCacheKey(findings);
+
+	// Check cache first
+	const cache = createCacheManager(mainaDir);
+	const cachedEntry = cache.get(cacheKey);
+	if (cachedEntry !== null) {
+		try {
+			const parsed = JSON.parse(cachedEntry.value) as FixResult;
+			return { ...parsed, cached: true };
+		} catch {
+			// Corrupted cache entry — fall through to regenerate
+		}
+	}
+
+	// Build system prompt via Prompt Engine
+	const sourceText = contextText ?? "No additional source context available.";
+	const findingsText = formatFindings(findings);
+
+	const builtPrompt = await buildSystemPrompt("fix", mainaDir, {
+		findings: findingsText,
+		source: sourceText,
+		conventions: "",
+	});
+
+	// Build user prompt
+	const userPrompt = buildUserPrompt(findings);
+
+	// Call AI (single call for all findings — batched)
+	const aiResult = await generate({
+		task: "fix",
+		systemPrompt: builtPrompt.prompt,
+		userPrompt,
+		files: findings.map((f) => f.file),
+		mainaDir,
+	});
+
+	// Parse the response
+	const suggestions = parseFixResponse(aiResult.text, findings);
+
+	const result: FixResult = {
+		suggestions,
+		cached: false,
+		model: aiResult.model,
+	};
+
+	// Cache the result (TTL 0 = forever for fix tasks, keyed by content hash)
+	cache.set(cacheKey, JSON.stringify(result), {
+		ttl: 0,
+		model: aiResult.model,
+	});
+
+	return result;
+}

package/src/verify/linters/clippy.ts

@@ -0,0 +1,52 @@
+/**
+ * Clippy output parser for Rust linting.
+ * Parses `cargo clippy --message-format=json` output.
+ */
+
+import type { SyntaxDiagnostic } from "../syntax-guard";
+
+export function parseClippyOutput(output: string): SyntaxDiagnostic[] {
+	const diagnostics: SyntaxDiagnostic[] = [];
+	const lines = output.split("\n");
+
+	for (const line of lines) {
+		if (!line.trim()) continue;
+
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+
+		if (parsed.reason !== "compiler-message") continue;
+
+		const msg = parsed.message as Record<string, unknown> | undefined;
+		if (!msg) continue;
+
+		const level = (msg.level as string) ?? "warning";
+		const message = (msg.message as string) ?? "";
+		const code = (msg.code as Record<string, string> | undefined)?.code ?? "";
+		const spans = msg.spans as Array<Record<string, unknown>> | undefined;
+
+		if (!spans || spans.length === 0) continue;
+
+		const span = spans[0] as Record<string, unknown>;
+		const fileName = (span.file_name as string) ?? "";
+		const lineStart = (span.line_start as number) ?? 0;
+		const columnStart = (span.column_start as number) ?? 0;
+
+		const severity: "error" | "warning" =
+			level === "error" ? "error" : "warning";
+
+		diagnostics.push({
+			file: fileName,
+			line: lineStart,
+			column: columnStart,
+			message: code ? `${code}: ${message}` : message,
+			severity,
+		});
+	}
+
+	return diagnostics;
+}

package/src/verify/linters/go-vet.ts

@@ -0,0 +1,32 @@
+/**
+ * Go vet output parser.
+ * Parses `go vet` stderr text output (format: file:line:col: message).
+ */
+
+import type { SyntaxDiagnostic } from "../syntax-guard";
+
+export function parseGoVetOutput(output: string): SyntaxDiagnostic[] {
+	const diagnostics: SyntaxDiagnostic[] = [];
+	const lines = output.split("\n");
+
+	for (const line of lines) {
+		if (!line.trim() || line.startsWith("#") || line.startsWith("vet:"))
+			continue;
+
+		const match = line.match(/^(.+?):(\d+):(\d+):\s+(.+)$/);
+		if (!match) continue;
+
+		const [, file, lineStr, colStr, message] = match;
+		if (!file || !lineStr || !message) continue;
+
+		diagnostics.push({
+			file,
+			line: Number.parseInt(lineStr, 10),
+			column: Number.parseInt(colStr ?? "0", 10),
+			message,
+			severity: "error",
+		});
+	}
+
+	return diagnostics;
+}

package/src/verify/linters/ruff.ts

@@ -0,0 +1,47 @@
+/**
+ * Ruff output parser for Python syntax/lint checking.
+ * Parses `ruff check --output-format=json` output.
+ */
+
+import type { SyntaxDiagnostic } from "../syntax-guard";
+
+/**
+ * Parse ruff JSON output into SyntaxDiagnostic[].
+ * F-codes (pyflakes) are errors, E-codes (pycodestyle) are warnings.
+ */
+export function parseRuffOutput(json: string): SyntaxDiagnostic[] {
+	let items: unknown[];
+	try {
+		items = JSON.parse(json);
+	} catch {
+		return [];
+	}
+
+	if (!Array.isArray(items)) return [];
+
+	const diagnostics: SyntaxDiagnostic[] = [];
+
+	for (const item of items) {
+		const i = item as Record<string, unknown>;
+		const code = (i.code as string) ?? "";
+		const message = (i.message as string) ?? "";
+		const filename = (i.filename as string) ?? "";
+		const location = i.location as Record<string, number> | undefined;
+		const row = location?.row ?? 0;
+		const column = location?.column ?? 0;
+
+		const severity: "error" | "warning" = code.startsWith("F")
+			? "error"
+			: "warning";
+
+		diagnostics.push({
+			file: filename,
+			line: row,
+			column,
+			message: `${code}: ${message}`,
+			severity,
+		});
+	}
+
+	return diagnostics;
+}

package/src/verify/mutation.ts

@@ -0,0 +1,143 @@
+/**
+ * Stryker Mutation Testing Integration for the Verify Engine.
+ *
+ * Runs Stryker and parses the JSON report for survived mutants.
+ * Survived mutants indicate untested code paths.
+ * Gracefully skips if stryker is not installed.
+ */
+
+import { isToolAvailable } from "./detect";
+import type { Finding } from "./diff-filter";
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface MutationOptions {
+	cwd?: string;
+	/** Pre-resolved availability — skips redundant detection if provided. */
+	available?: boolean;
+}
+
+export interface MutationResult {
+	findings: Finding[];
+	skipped: boolean;
+}
+
+// ─── JSON Parsing ─────────────────────────────────────────────────────────
+
+/**
+ * Parse Stryker JSON report into Finding[].
+ * Only survived mutants become findings — killed/timeout/no-coverage are ignored.
+ *
+ * Expected format:
+ * ```json
+ * {
+ *   "files": {
+ *     "src/app.ts": {
+ *       "mutants": [{
+ *         "id": "1",
+ *         "mutatorName": "ConditionalExpression",
+ *         "status": "Survived",
+ *         "location": { "start": { "line": 10, "column": 5 } },
+ *         "description": "Replaced x > 0 with false"
+ *       }]
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export function parseStrykerReport(json: string): Finding[] {
+	let parsed: Record<string, unknown>;
+	try {
+		parsed = JSON.parse(json) as Record<string, unknown>;
+	} catch {
+		return [];
+	}
+
+	const files = parsed.files;
+	if (!files || typeof files !== "object") {
+		return [];
+	}
+
+	const findings: Finding[] = [];
+
+	for (const [filePath, fileData] of Object.entries(
+		files as Record<string, unknown>,
+	)) {
+		const data = fileData as Record<string, unknown>;
+		const mutants = data.mutants;
+		if (!Array.isArray(mutants)) continue;
+
+		for (const mutant of mutants) {
+			const m = mutant as Record<string, unknown>;
+			const status = (m.status as string) ?? "";
+
+			// Only report survived mutants — they indicate untested code
+			if (status !== "Survived") continue;
+
+			const mutatorName = (m.mutatorName as string) ?? "Unknown";
+			const description = (m.description as string) ?? "";
+			const location = m.location as Record<string, unknown> | undefined;
+			const start = location?.start as Record<string, unknown> | undefined;
+			const line = (start?.line as number) ?? 0;
+
+			findings.push({
+				tool: "stryker",
+				file: filePath,
+				line,
+				message: `Survived mutant: ${description} (${mutatorName})`,
+				severity: "warning",
+				ruleId: `stryker/${mutatorName}`,
+			});
+		}
+	}
+
+	return findings;
+}
+
+// ─── Runner ───────────────────────────────────────────────────────────────
+
+/**
+ * Run Stryker mutation testing and return parsed findings.
+ *
+ * If stryker is not installed, returns `{ findings: [], skipped: true }`.
+ * If stryker fails, returns `{ findings: [], skipped: false }`.
+ */
+export async function runMutation(
+	options?: MutationOptions,
+): Promise<MutationResult> {
+	const toolAvailable =
+		options?.available ?? (await isToolAvailable("stryker"));
+	if (!toolAvailable) {
+		return { findings: [], skipped: true };
+	}
+
+	const cwd = options?.cwd ?? process.cwd();
+
+	const args = ["stryker", "run", "--reporters", "json"];
+
+	try {
+		const proc = Bun.spawn(args, {
+			cwd,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		await new Response(proc.stdout).text();
+		await new Response(proc.stderr).text();
+		await proc.exited;
+
+		// Read the generated report file
+		const reportPath = `${cwd}/reports/mutation/mutation.json`;
+		const reportFile = Bun.file(reportPath);
+		const exists = await reportFile.exists();
+		if (!exists) {
+			return { findings: [], skipped: false };
+		}
+
+		const reportJson = await reportFile.text();
+		const findings = parseStrykerReport(reportJson);
+		return { findings, skipped: false };
+	} catch {
+		return { findings: [], skipped: false };
+	}
+}