@mainahq/core 0.2.0 → 0.4.0

package/src/verify/__tests__/zap.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "bun:test";
+import { parseZapJson, runZap } from "../zap";
+
+// ─── parseZapJson ─────────────────────────────────────────────────────────
+
+describe("parseZapJson", () => {
+	it("should return empty array for empty alerts", () => {
+		const json = JSON.stringify({ site: [{ alerts: [] }] });
+		const findings = parseZapJson(json);
+		expect(findings).toEqual([]);
+	});
+
+	it("should parse a single alert from ZAP JSON output", () => {
+		const json = JSON.stringify({
+			site: [
+				{
+					alerts: [
+						{
+							pluginid: "10021",
+							alert: "X-Content-Type-Options Header Missing",
+							riskdesc: "Low (Medium)",
+							desc: "The Anti-MIME-Sniffing header is not set.",
+							instances: [
+								{
+									uri: "https://example.com/api/health",
+									method: "GET",
+								},
+							],
+						},
+					],
+				},
+			],
+		});
+
+		const findings = parseZapJson(json);
+		expect(findings.length).toBe(1);
+		expect(findings[0]?.tool).toBe("zap");
+		expect(findings[0]?.file).toBe("https://example.com/api/health");
+		expect(findings[0]?.line).toBe(0);
+		expect(findings[0]?.message).toContain(
+			"X-Content-Type-Options Header Missing",
+		);
+		expect(findings[0]?.severity).toBe("info");
+		expect(findings[0]?.ruleId).toBe("10021");
+	});
+
+	it("should map ZAP risk levels to severity correctly", () => {
+		const makeZap = (riskdesc: string) =>
+			JSON.stringify({
+				site: [
+					{
+						alerts: [
+							{
+								pluginid: "10001",
+								alert: "Test Alert",
+								riskdesc,
+								desc: "Test description",
+								instances: [{ uri: "https://example.com", method: "GET" }],
+							},
+						],
+					},
+				],
+			});
+
+		expect(parseZapJson(makeZap("High (Medium)"))[0]?.severity).toBe("error");
+		expect(parseZapJson(makeZap("Medium (Low)"))[0]?.severity).toBe("warning");
+		expect(parseZapJson(makeZap("Low (Medium)"))[0]?.severity).toBe("info");
+		expect(parseZapJson(makeZap("Informational (Low)"))[0]?.severity).toBe(
+			"info",
+		);
+	});
+
+	it("should handle multiple alerts with multiple instances", () => {
+		const json = JSON.stringify({
+			site: [
+				{
+					alerts: [
+						{
+							pluginid: "10021",
+							alert: "Alert A",
+							riskdesc: "High (Medium)",
+							desc: "Description A",
+							instances: [
+								{ uri: "https://example.com/a", method: "GET" },
+								{ uri: "https://example.com/b", method: "POST" },
+							],
+						},
+						{
+							pluginid: "10022",
+							alert: "Alert B",
+							riskdesc: "Low (Low)",
+							desc: "Description B",
+							instances: [{ uri: "https://example.com/c", method: "GET" }],
+						},
+					],
+				},
+			],
+		});
+
+		const findings = parseZapJson(json);
+		expect(findings.length).toBe(3);
+		expect(findings[0]?.file).toBe("https://example.com/a");
+		expect(findings[1]?.file).toBe("https://example.com/b");
+		expect(findings[2]?.file).toBe("https://example.com/c");
+	});
+
+	it("should handle alerts with no instances", () => {
+		const json = JSON.stringify({
+			site: [
+				{
+					alerts: [
+						{
+							pluginid: "10021",
+							alert: "No Instances Alert",
+							riskdesc: "Medium (Medium)",
+							desc: "No instances",
+							instances: [],
+						},
+					],
+				},
+			],
+		});
+
+		const findings = parseZapJson(json);
+		expect(findings.length).toBe(1);
+		expect(findings[0]?.file).toBe("");
+		expect(findings[0]?.message).toContain("No Instances Alert");
+	});
+
+	it("should return empty array for invalid JSON", () => {
+		const findings = parseZapJson("not valid json {{{");
+		expect(findings).toEqual([]);
+	});
+
+	it("should return empty array for malformed structure", () => {
+		const findings = parseZapJson(JSON.stringify({ unexpected: true }));
+		expect(findings).toEqual([]);
+	});
+
+	it("should handle missing site array gracefully", () => {
+		const findings = parseZapJson(JSON.stringify({ site: "not-an-array" }));
+		expect(findings).toEqual([]);
+	});
+
+	it("should handle site entries without alerts", () => {
+		const json = JSON.stringify({
+			site: [{ name: "example.com" }],
+		});
+		const findings = parseZapJson(json);
+		expect(findings).toEqual([]);
+	});
+});
+
+// ─── runZap ───────────────────────────────────────────────────────────────
+
+describe("runZap", () => {
+	it("should skip when docker is not available", async () => {
+		const result = await runZap({
+			targetUrl: "https://example.com",
+			cwd: "/tmp",
+			available: false,
+		});
+		expect(result.findings).toEqual([]);
+		expect(result.skipped).toBe(true);
+	});
+
+	it("should skip when no targetUrl is provided", async () => {
+		const result = await runZap({
+			targetUrl: "",
+			cwd: "/tmp",
+			available: true,
+		});
+		expect(result.findings).toEqual([]);
+		expect(result.skipped).toBe(true);
+	});
+
+	it("should return correct result shape", async () => {
+		const result = await runZap({
+			targetUrl: "https://example.com",
+			cwd: "/tmp",
+			available: false,
+		});
+		expect(result).toHaveProperty("findings");
+		expect(result).toHaveProperty("skipped");
+		expect(Array.isArray(result.findings)).toBe(true);
+		expect(typeof result.skipped).toBe("boolean");
+	});
+});

package/src/verify/consistency.ts

@@ -0,0 +1,199 @@
+/**
+ * Cross-function Consistency Check — deterministic AST-based analysis.
+ *
+ * Catches the class of bug that lost Maina 2 points in the Tier 3 benchmark:
+ * functions that call a validator on one code path but skip it on another.
+ *
+ * Two modes:
+ * 1. Spec-based: reads spec.md / constitution.md for stated constraints,
+ *    builds a rule set, checks compliance
+ * 2. Heuristic: if no spec exists, looks for inconsistent validator usage
+ *    patterns across related functions
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { Finding } from "./diff-filter";
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface ConsistencyRule {
+	pattern: string;
+	source: "spec" | "heuristic";
+}
+
+export interface ConsistencyResult {
+	findings: Finding[];
+	rulesChecked: number;
+}
+
+// ─── Rule Extraction ─────────────────────────────────────────────────────
+
+/**
+ * Extract consistency rules from spec/constitution content.
+ * Looks for patterns like "use X when Y", "always call X", "validate with X".
+ */
+function extractRulesFromSpec(content: string): ConsistencyRule[] {
+	const rules: ConsistencyRule[] = [];
+	const patterns = [
+		/always (?:use|call|check|validate with) (\w+)/gi,
+		/must (?:use|call|check) (\w+)/gi,
+		/validate.*(?:with|using) (\w+)/gi,
+	];
+
+	for (const pattern of patterns) {
+		for (const match of content.matchAll(pattern)) {
+			rules.push({
+				pattern: match[1] ?? "",
+				source: "spec",
+			});
+		}
+	}
+
+	return rules;
+}
+
+/**
+ * Load spec/constitution content from the maina directory.
+ */
+function loadSpecContent(mainaDir: string): string {
+	const paths = [join(mainaDir, "constitution.md"), join(mainaDir, "spec.md")];
+
+	const parts: string[] = [];
+	for (const p of paths) {
+		if (existsSync(p)) {
+			parts.push(readFileSync(p, "utf-8"));
+		}
+	}
+
+	return parts.join("\n");
+}
+
+// ─── Heuristic Analysis ──────────────────────────────────────────────────
+
+/**
+ * Find functions that call validators inconsistently.
+ * If functionA calls isValid(x) and functionB doesn't but both take similar
+ * params, that's a potential inconsistency.
+ */
+function findHeuristicIssues(source: string, file: string): Finding[] {
+	const findings: Finding[] = [];
+
+	// Extract function calls per function body
+	const functionPattern =
+		/function\s+(\w+)\s*\([^)]*\)\s*\{([^}]*(?:\{[^}]*\}[^}]*)*)\}/g;
+	const functions: Array<{ name: string; body: string; line: number }> = [];
+
+	for (const match of source.matchAll(functionPattern)) {
+		const lineNumber = source.substring(0, match.index ?? 0).split("\n").length;
+		functions.push({
+			name: match[1] ?? "",
+			body: match[2] ?? "",
+			line: lineNumber,
+		});
+	}
+
+	// Find validator-like calls (isX, validateX, checkX)
+	const validatorPattern = /\b(is[A-Z]\w+|validate\w+|check\w+)\s*\(/g;
+	const validatorsByFunction = new Map<string, Set<string>>();
+
+	for (const fn of functions) {
+		const validators = new Set<string>();
+		for (const validatorMatch of fn.body.matchAll(validatorPattern)) {
+			validators.add(validatorMatch[1] ?? "");
+		}
+		validatorsByFunction.set(fn.name, validators);
+	}
+
+	// Compare: if most functions use a validator but one doesn't, flag it
+	const allValidators = new Set<string>();
+	for (const validators of validatorsByFunction.values()) {
+		for (const v of validators) allValidators.add(v);
+	}
+
+	if (functions.length >= 2) {
+		for (const validator of allValidators) {
+			const usersCount = Array.from(validatorsByFunction.values()).filter((v) =>
+				v.has(validator),
+			).length;
+
+			// If majority uses it but some don't, flag the ones that don't
+			if (usersCount > 0 && usersCount < functions.length) {
+				for (const fn of functions) {
+					const fnValidators = validatorsByFunction.get(fn.name);
+					if (fnValidators && !fnValidators.has(validator)) {
+						findings.push({
+							tool: "consistency",
+							file,
+							line: fn.line,
+							message: `Function '${fn.name}' does not call '${validator}' — other functions in this file do. Possible inconsistency.`,
+							severity: "warning",
+							ruleId: `consistency/${validator}`,
+						});
+					}
+				}
+			}
+		}
+	}
+
+	return findings;
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────
+
+export async function checkConsistency(
+	files: string[],
+	cwd: string,
+	mainaDir: string,
+): Promise<ConsistencyResult> {
+	const specContent = existsSync(mainaDir) ? loadSpecContent(mainaDir) : "";
+	const specRules = extractRulesFromSpec(specContent);
+	const allFindings: Finding[] = [];
+
+	for (const file of files) {
+		const filePath = join(cwd, file);
+		if (!existsSync(filePath)) continue;
+
+		const source = readFileSync(filePath, "utf-8");
+
+		// Check spec-based rules
+		for (const rule of specRules) {
+			const callPattern = new RegExp(`\\b${rule.pattern}\\s*\\(`, "g");
+			const fnPattern = /function\s+(\w+)/g;
+
+			// Find functions that should use this pattern but don't
+			for (const fnMatch of source.matchAll(fnPattern)) {
+				const fnStart = fnMatch.index ?? 0;
+				const fnEnd = source.indexOf("}", fnStart + 1);
+				if (fnEnd === -1) continue;
+
+				const fnBody = source.substring(fnStart, fnEnd);
+				if (!callPattern.test(fnBody)) {
+					const relatedTerms = rule.pattern
+						.toLowerCase()
+						.replace(/^is|^validate|^check/, "");
+					if (fnBody.toLowerCase().includes(relatedTerms)) {
+						const line = source.substring(0, fnStart).split("\n").length;
+						allFindings.push({
+							tool: "consistency",
+							file,
+							line,
+							message: `Spec requires '${rule.pattern}' — function '${fnMatch[1]}' may need it.`,
+							severity: "warning",
+							ruleId: `consistency/spec-${rule.pattern}`,
+						});
+					}
+				}
+			}
+		}
+
+		// Heuristic checks (always run)
+		allFindings.push(...findHeuristicIssues(source, file));
+	}
+
+	return {
+		findings: allFindings,
+		rulesChecked: specRules.length + 1, // +1 for heuristic check
+	};
+}

package/src/verify/detect.ts

@@ -22,7 +22,13 @@ export type ToolName =
 	| "golangci-lint"
 	| "cargo-clippy"
 	| "cargo-audit"
-	| "playwright";
+	| "playwright"
+	| "dotnet-format"
+	| "checkstyle"
+	| "spotbugs"
+	| "pmd"
+	| "zap"
+	| "lighthouse";
 
 export interface DetectedTool {
 	name: string;
@@ -47,6 +53,12 @@ export const TOOL_REGISTRY: Record<
 	"cargo-clippy": { command: "cargo", versionFlag: "clippy --version" },
 	"cargo-audit": { command: "cargo-audit", versionFlag: "--version" },
 	playwright: { command: "npx", versionFlag: "playwright --version" },
+	"dotnet-format": { command: "dotnet", versionFlag: "format --version" },
+	checkstyle: { command: "checkstyle", versionFlag: "--version" },
+	spotbugs: { command: "spotbugs", versionFlag: "-version" },
+	pmd: { command: "pmd", versionFlag: "--version" },
+	zap: { command: "docker", versionFlag: "--version" },
+	lighthouse: { command: "lighthouse", versionFlag: "--version" },
 };
 
 /**

package/src/verify/lighthouse.ts

@@ -0,0 +1,173 @@
+/**
+ * Lighthouse Integration for the Verify Engine.
+ *
+ * Runs Google Lighthouse against a URL and checks category scores
+ * against configurable thresholds.
+ * Generates findings when scores fall below thresholds.
+ * Gracefully skips if lighthouse is not installed.
+ */
+
+import { isToolAvailable } from "./detect";
+import type { Finding } from "./diff-filter";
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface LighthouseOptions {
+	url: string;
+	cwd: string;
+	/** Pre-resolved availability — skips redundant detection if provided. */
+	available?: boolean;
+	/** Score thresholds (0-100). Categories below threshold generate findings. */
+	thresholds?: Record<string, number>;
+}
+
+export interface LighthouseResult {
+	findings: Finding[];
+	skipped: boolean;
+	scores: Record<string, number>;
+}
+
+/** Default thresholds — 90 for the three core categories. */
+const DEFAULT_THRESHOLDS: Record<string, number> = {
+	performance: 90,
+	accessibility: 90,
+	seo: 90,
+};
+
+// ─── JSON Parsing ─────────────────────────────────────────────────────────
+
+/**
+ * Determine severity based on how far below the threshold a score is.
+ * Below 50: error. Below threshold: warning.
+ */
+function scoreSeverity(
+	score: number,
+	_threshold: number,
+): "error" | "warning" | "info" {
+	if (score < 50) {
+		return "error";
+	}
+	return "warning";
+}
+
+/**
+ * Parse Lighthouse JSON output into findings and scores.
+ *
+ * Lighthouse JSON has this structure:
+ * ```json
+ * {
+ *   "requestedUrl": "https://example.com",
+ *   "categories": {
+ *     "performance": { "score": 0.95 },
+ *     "accessibility": { "score": 0.88 },
+ *     "seo": { "score": 0.92 },
+ *     "best-practices": { "score": 0.85 }
+ *   }
+ * }
+ * ```
+ *
+ * Scores are 0-1 floats. We multiply by 100 for human-readable percentages.
+ * Findings are generated for categories whose scores fall below the thresholds.
+ *
+ * Handles malformed JSON and unexpected structures gracefully.
+ */
+export function parseLighthouseJson(
+	json: string,
+	thresholds?: Record<string, number>,
+): Omit<LighthouseResult, "skipped"> {
+	let parsed: Record<string, unknown>;
+	try {
+		parsed = JSON.parse(json) as Record<string, unknown>;
+	} catch {
+		return { findings: [], scores: {} };
+	}
+
+	const categories = parsed.categories;
+	if (typeof categories !== "object" || categories === null) {
+		return { findings: [], scores: {} };
+	}
+
+	const requestedUrl = (parsed.requestedUrl as string) ?? "";
+	const activeThresholds = thresholds ?? DEFAULT_THRESHOLDS;
+	const scores: Record<string, number> = {};
+	const findings: Finding[] = [];
+
+	const cats = categories as Record<string, unknown>;
+
+	for (const [categoryName, categoryData] of Object.entries(cats)) {
+		const cat = categoryData as Record<string, unknown> | null;
+		if (!cat || typeof cat.score !== "number") {
+			continue;
+		}
+
+		const rawScore = cat.score as number;
+		const score = Math.round(rawScore * 100);
+		scores[categoryName] = score;
+
+		const threshold = activeThresholds[categoryName];
+		if (threshold !== undefined && score < threshold) {
+			findings.push({
+				tool: "lighthouse",
+				file: requestedUrl,
+				line: 0,
+				message: `Lighthouse ${categoryName} score ${score} is below threshold ${threshold}`,
+				severity: scoreSeverity(score, threshold),
+				ruleId: `lighthouse/${categoryName}`,
+			});
+		}
+	}
+
+	return { findings, scores };
+}
+
+// ─── Runner ───────────────────────────────────────────────────────────────
+
+/**
+ * Run Lighthouse and return parsed findings with scores.
+ *
+ * If lighthouse is not installed or no URL is provided,
+ * returns `{ findings: [], skipped: true, scores: {} }`.
+ * If lighthouse fails, returns `{ findings: [], skipped: false, scores: {} }`.
+ */
+export async function runLighthouse(
+	options: LighthouseOptions,
+): Promise<LighthouseResult> {
+	if (!options.url) {
+		return { findings: [], skipped: true, scores: {} };
+	}
+
+	const toolAvailable =
+		options.available ?? (await isToolAvailable("lighthouse"));
+	if (!toolAvailable) {
+		return { findings: [], skipped: true, scores: {} };
+	}
+
+	const cwd = options.cwd;
+
+	const args = [
+		"lighthouse",
+		options.url,
+		"--output=json",
+		'--chrome-flags="--headless --no-sandbox"',
+	];
+
+	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, scores } = parseLighthouseJson(
+			stdout,
+			options.thresholds,
+		);
+		return { findings, skipped: false, scores };
+	} catch {
+		return { findings: [], skipped: false, scores: {} };
+	}
+}

package/src/verify/linters/checkstyle.ts

@@ -0,0 +1,41 @@
+/**
+ * Checkstyle output parser for Java linting.
+ * Parses Checkstyle XML output.
+ */
+
+import type { SyntaxDiagnostic } from "../syntax-guard";
+
+/**
+ * Parse Checkstyle XML output into SyntaxDiagnostic[].
+ */
+export function parseCheckstyleOutput(xml: string): SyntaxDiagnostic[] {
+	const diagnostics: SyntaxDiagnostic[] = [];
+
+	// Simple XML parsing — extract <error> elements
+	// Format: <file name="path"><error line="10" column="5" severity="error" message="desc" source="rule"/></file>
+	const filePattern = /<file\s+name="([^"]+)">([\s\S]*?)<\/file>/g;
+	const errorPattern =
+		/<error\s+line="(\d+)"\s+(?:column="(\d+)"\s+)?severity="(\w+)"\s+message="([^"]+)"/g;
+
+	for (const fileMatch of xml.matchAll(filePattern)) {
+		const filePath = fileMatch[1] ?? "";
+		const fileContent = fileMatch[2] ?? "";
+
+		for (const errorMatch of fileContent.matchAll(errorPattern)) {
+			const line = Number.parseInt(errorMatch[1] ?? "0", 10);
+			const column = Number.parseInt(errorMatch[2] ?? "0", 10);
+			const severity = errorMatch[3] ?? "warning";
+			const message = errorMatch[4] ?? "";
+
+			diagnostics.push({
+				file: filePath,
+				line,
+				column,
+				message,
+				severity: severity === "error" ? "error" : "warning",
+			});
+		}
+	}
+
+	return diagnostics;
+}

package/src/verify/linters/dotnet-format.ts

@@ -0,0 +1,37 @@
+/**
+ * dotnet format output parser for C# linting.
+ * Parses `dotnet format --verify-no-changes` output.
+ */
+
+import type { SyntaxDiagnostic } from "../syntax-guard";
+
+/**
+ * Parse dotnet format text output into SyntaxDiagnostic[].
+ * dotnet format outputs: "path/file.cs(line,col): severity CODE: message"
+ */
+export function parseDotnetFormatOutput(output: string): SyntaxDiagnostic[] {
+	const diagnostics: SyntaxDiagnostic[] = [];
+	const lines = output.split("\n");
+
+	for (const line of lines) {
+		if (!line.trim()) continue;
+		// Format: file.cs(line,col): warning CS1234: message
+		const match = line.match(
+			/^(.+?)\((\d+),(\d+)\):\s*(error|warning)\s+(\w+):\s*(.+)$/,
+		);
+		if (!match) continue;
+
+		const [, file, lineStr, colStr, severity, _code, message] = match;
+		if (!file || !lineStr || !message) continue;
+
+		diagnostics.push({
+			file,
+			line: Number.parseInt(lineStr, 10),
+			column: Number.parseInt(colStr ?? "0", 10),
+			message,
+			severity: severity === "error" ? "error" : "warning",
+		});
+	}
+
+	return diagnostics;
+}