@mainahq/core 0.2.0

package/src/verify/syntax-guard.ts

@@ -0,0 +1,251 @@
+/**
+ * Syntax Guard — the first gate in the Verify Engine pipeline.
+ *
+ * Runs Biome check on the provided files and returns structured errors.
+ * If syntax fails, the pipeline rejects immediately — no tests, no coverage,
+ * no slop detection. This must complete in <500ms for 10 files.
+ *
+ * Uses `--reporter=json` for machine-parseable output.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Result } from "../db/index";
+import type { LanguageProfile } from "../language/profile";
+import { TYPESCRIPT_PROFILE } from "../language/profile";
+import { parseClippyOutput } from "./linters/clippy";
+import { parseGoVetOutput } from "./linters/go-vet";
+import { parseRuffOutput } from "./linters/ruff";
+
+export interface SyntaxDiagnostic {
+	file: string;
+	line: number;
+	column: number;
+	message: string;
+	severity: "error" | "warning";
+}
+
+export type SyntaxGuardResult = Result<void, SyntaxDiagnostic[]>;
+
+/** Shape of a single diagnostic in Biome's JSON reporter output. */
+interface BiomeDiagnostic {
+	severity: string;
+	message: string;
+	category: string;
+	location: {
+		path: string;
+		start: { line: number; column: number };
+		end: { line: number; column: number };
+	};
+	advices: unknown[];
+}
+
+/** Shape of Biome's JSON reporter output. */
+interface BiomeJsonOutput {
+	summary: {
+		changed: number;
+		unchanged: number;
+		errors: number;
+		warnings: number;
+	};
+	diagnostics: BiomeDiagnostic[];
+	command: string;
+}
+
+/**
+ * Find the biome binary — prefer local node_modules/.bin, fall back to global.
+ */
+function findBiomeBinary(cwd: string): string {
+	const localBin = join(cwd, "node_modules", ".bin", "biome");
+	if (existsSync(localBin)) {
+		return localBin;
+	}
+
+	// Walk up to find node_modules/.bin
+	let dir = cwd;
+	const root = "/";
+	while (dir !== root) {
+		const binPath = join(dir, "node_modules", ".bin", "biome");
+		if (existsSync(binPath)) {
+			return binPath;
+		}
+		const parent = join(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+
+	// Fall back to bare "biome" (assumes it's on PATH)
+	return "biome";
+}
+
+/**
+ * Parse Biome's JSON reporter output into structured SyntaxDiagnostic[].
+ * Returns an empty array if the output cannot be parsed.
+ */
+export function parseBiomeOutput(output: string): SyntaxDiagnostic[] {
+	try {
+		const parsed: BiomeJsonOutput = JSON.parse(output);
+		if (!parsed.diagnostics || !Array.isArray(parsed.diagnostics)) {
+			return [];
+		}
+
+		return parsed.diagnostics
+			.filter(
+				(d) =>
+					d.location?.path &&
+					d.location?.start &&
+					typeof d.location.start.line === "number",
+			)
+			.map((d) => ({
+				file: d.location.path,
+				line: d.location.start.line,
+				column: d.location.start.column,
+				message: d.message,
+				severity:
+					d.severity === "error" ? ("error" as const) : ("warning" as const),
+			}));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Run Biome check on the provided files and return a Result.
+ *
+ * - If no files are provided, returns Ok immediately.
+ * - If Biome exits with code 0, returns Ok.
+ * - If Biome exits non-zero, parses errors and returns Err if any errors exist.
+ * - Only errors (not warnings) trigger a rejection.
+ */
+export async function syntaxGuard(
+	files: string[],
+	cwd?: string,
+	profile?: LanguageProfile,
+): Promise<SyntaxGuardResult> {
+	if (files.length === 0) {
+		return { ok: true, value: undefined };
+	}
+
+	const lang = profile ?? TYPESCRIPT_PROFILE;
+	const workDir = cwd ?? process.cwd();
+
+	// Route to language-specific linter for non-TypeScript
+	if (lang.id !== "typescript") {
+		return runLanguageLinter(files, workDir, lang);
+	}
+	const biomeBin = findBiomeBinary(workDir);
+
+	try {
+		const proc = Bun.spawn(
+			[
+				biomeBin,
+				"check",
+				"--reporter=json",
+				"--no-errors-on-unmatched",
+				"--colors=off",
+				...files,
+			],
+			{
+				cwd: workDir,
+				stdout: "pipe",
+				stderr: "pipe",
+			},
+		);
+
+		const stdout = await new Response(proc.stdout).text();
+		const exitCode = await proc.exited;
+
+		if (exitCode === 0) {
+			return { ok: true, value: undefined };
+		}
+
+		// Parse diagnostics from JSON output
+		const allDiagnostics = parseBiomeOutput(stdout);
+
+		// Only reject on errors, not warnings
+		const errors = allDiagnostics.filter((d) => d.severity === "error");
+
+		if (errors.length === 0) {
+			// Only warnings — pass
+			return { ok: true, value: undefined };
+		}
+
+		// Return all diagnostics (errors + warnings) for context,
+		// but the presence of errors triggers the rejection.
+		return { ok: false, error: allDiagnostics };
+	} catch (e) {
+		// Biome not found or spawn failure
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: [
+				{
+					file: "",
+					line: 0,
+					column: 0,
+					message: `Failed to run biome: ${message}`,
+					severity: "error",
+				},
+			],
+		};
+	}
+}
+
+/**
+ * Run a language-specific linter and return structured diagnostics.
+ * Gracefully handles tool-not-found by returning an error diagnostic.
+ */
+async function runLanguageLinter(
+	files: string[],
+	cwd: string,
+	profile: LanguageProfile,
+): Promise<SyntaxGuardResult> {
+	const args = profile.syntaxArgs(files, cwd);
+
+	try {
+		const proc = Bun.spawn(args, {
+			cwd,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		const stdout = await new Response(proc.stdout).text();
+		const stderr = await new Response(proc.stderr).text();
+		await proc.exited;
+
+		let diagnostics: SyntaxDiagnostic[] = [];
+
+		switch (profile.id) {
+			case "python":
+				diagnostics = parseRuffOutput(stdout);
+				break;
+			case "go":
+				diagnostics = parseGoVetOutput(stderr);
+				break;
+			case "rust":
+				diagnostics = parseClippyOutput(stdout);
+				break;
+		}
+
+		const errors = diagnostics.filter((d) => d.severity === "error");
+		if (errors.length === 0) {
+			return { ok: true, value: undefined };
+		}
+
+		return { ok: false, error: diagnostics };
+	} catch (e) {
+		const message = e instanceof Error ? e.message : String(e);
+		return {
+			ok: false,
+			error: [
+				{
+					file: "",
+					line: 0,
+					column: 0,
+					message: `Failed to run ${profile.syntaxTool}: ${message}`,
+					severity: "error",
+				},
+			],
+		};
+	}
+}

package/src/verify/trivy.ts

@@ -0,0 +1,161 @@
+/**
+ * Trivy Integration for the Verify Engine.
+ *
+ * Runs Trivy for dependency CVE scanning.
+ * Parses JSON output into the unified Finding type.
+ * Gracefully skips if trivy is not installed.
+ */
+
+import { isToolAvailable } from "./detect";
+import type { Finding } from "./diff-filter";
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface TrivyOptions {
+	scanType?: "fs" | "repo";
+	cwd?: string;
+	/** Pre-resolved availability — skips redundant detection if provided. */
+	available?: boolean;
+}
+
+export interface TrivyResult {
+	findings: Finding[];
+	skipped: boolean;
+}
+
+// ─── JSON Parsing ─────────────────────────────────────────────────────────
+
+/**
+ * Map Trivy severity string to unified severity.
+ */
+function mapTrivySeverity(severity: string): "error" | "warning" | "info" {
+	switch (severity.toUpperCase()) {
+		case "CRITICAL":
+		case "HIGH":
+			return "error";
+		case "MEDIUM":
+			return "warning";
+		default:
+			return "info";
+	}
+}
+
+/**
+ * Parse Trivy JSON output into Finding[].
+ *
+ * Trivy JSON has this structure:
+ * ```json
+ * {
+ *   "Results": [{
+ *     "Target": "package-lock.json",
+ *     "Type": "npm",
+ *     "Vulnerabilities": [{
+ *       "VulnerabilityID": "CVE-...",
+ *       "PkgName": "lodash",
+ *       "InstalledVersion": "4.17.20",
+ *       "FixedVersion": "4.17.21",
+ *       "Severity": "HIGH",
+ *       "Title": "Prototype Pollution"
+ *     }]
+ *   }]
+ * }
+ * ```
+ *
+ * Handles malformed JSON and unexpected structures gracefully.
+ */
+export function parseTrivyJson(json: string): Finding[] {
+	let parsed: Record<string, unknown>;
+	try {
+		parsed = JSON.parse(json) as Record<string, unknown>;
+	} catch {
+		return [];
+	}
+
+	const results = parsed.Results;
+	if (!Array.isArray(results)) {
+		return [];
+	}
+
+	const findings: Finding[] = [];
+
+	for (const result of results) {
+		const r = result as Record<string, unknown>;
+		const target = (r.Target as string) ?? "";
+		const vulnerabilities = r.Vulnerabilities;
+
+		if (!Array.isArray(vulnerabilities)) {
+			continue;
+		}
+
+		for (const vuln of vulnerabilities) {
+			const v = vuln as Record<string, unknown>;
+			const vulnId = (v.VulnerabilityID as string) ?? "";
+			const pkgName = (v.PkgName as string) ?? "";
+			const installedVersion = (v.InstalledVersion as string) ?? "";
+			const fixedVersion = (v.FixedVersion as string) ?? undefined;
+			const severity = (v.Severity as string) ?? "UNKNOWN";
+			const title = (v.Title as string) ?? "";
+
+			let message = `${pkgName}@${installedVersion}: ${title}`;
+			if (fixedVersion) {
+				message += ` (fix: ${fixedVersion})`;
+			}
+
+			findings.push({
+				tool: "trivy",
+				file: target,
+				line: 0,
+				message,
+				severity: mapTrivySeverity(severity),
+				ruleId: vulnId || undefined,
+			});
+		}
+	}
+
+	return findings;
+}
+
+// ─── Runner ───────────────────────────────────────────────────────────────
+
+/**
+ * Run Trivy and return parsed findings.
+ *
+ * If trivy is not installed, returns `{ findings: [], skipped: true }`.
+ * If trivy fails, returns `{ findings: [], skipped: false }`.
+ */
+export async function runTrivy(options?: TrivyOptions): Promise<TrivyResult> {
+	const toolAvailable = options?.available ?? (await isToolAvailable("trivy"));
+	if (!toolAvailable) {
+		return { findings: [], skipped: true };
+	}
+
+	const scanType = options?.scanType ?? "fs";
+	const cwd = options?.cwd ?? process.cwd();
+
+	const args = [
+		"trivy",
+		scanType,
+		"--format",
+		"json",
+		"--scanners",
+		"vuln",
+		".",
+	];
+
+	try {
+		const proc = Bun.spawn(args, {
+			cwd,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		const stdout = await new Response(proc.stdout).text();
+		await new Response(proc.stderr).text();
+		await proc.exited;
+
+		const findings = parseTrivyJson(stdout);
+		return { findings, skipped: false };
+	} catch {
+		return { findings: [], skipped: false };
+	}
+}