@mainahq/core 0.2.0

package/src/index.ts

@@ -0,0 +1,356 @@
+export const VERSION = "0.1.0";
+
+// AI
+export { generateCommitMessage } from "./ai/commit-msg";
+export {
+	type DesignApproach,
+	generateDesignApproaches,
+} from "./ai/design-approaches";
+export { generate } from "./ai/index";
+export { generatePrSummary } from "./ai/pr-summary";
+export {
+	generateSpecQuestions,
+	type SpecQuestion,
+} from "./ai/spec-questions";
+export {
+	type DelegationPrompt,
+	type TryAIResult,
+	tryAIGenerate,
+} from "./ai/try-generate";
+// AI validation
+export { type AIValidationResult, validateAIOutput } from "./ai/validate";
+export {
+	buildReport,
+	buildTier3Report,
+	formatComparison,
+	formatTier3Comparison,
+} from "./benchmark/reporter";
+export { parseTestOutput, runBenchmark } from "./benchmark/runner";
+export { listStories, loadStory } from "./benchmark/story-loader";
+// Benchmark
+export type {
+	BenchmarkMetrics,
+	BenchmarkReport,
+	LoadedStory,
+	StepMetrics,
+	StoryConfig,
+	Tier3Results,
+	Tier3Totals,
+} from "./benchmark/types";
+// Cache
+export {
+	type CacheManager,
+	type CacheStats,
+	createCacheManager,
+} from "./cache/manager";
+// Config
+export { getApiKey, isHostMode, shouldDelegateToHost } from "./config/index";
+export { calculateTokens } from "./context/budget";
+export {
+	type AssembledContext,
+	assembleContext,
+	type ContextOptions,
+	type LayerReport,
+} from "./context/engine";
+// Context — episodic
+export { addEntry as addEpisodicEntry } from "./context/episodic";
+export type { MainaCommand } from "./context/selector";
+// Context — working
+export {
+	loadWorkingContext,
+	saveWorkingContext,
+	setVerificationResult,
+	trackFile,
+} from "./context/working";
+// DB (Result type)
+export type { Result } from "./db/index";
+// Design (ADR)
+export {
+	type AdrSummary,
+	generateHldLld,
+	getNextAdrNumber,
+	listAdrs,
+	scaffoldAdr,
+} from "./design/index";
+// Design Review
+export {
+	buildReviewContext,
+	findAdrByNumber,
+	type ReviewContext,
+	type ReviewFinding,
+	type ReviewOptions,
+	type ReviewResult,
+	reviewDesign,
+} from "./design/review";
+// Explain
+export {
+	type DiagramOptions,
+	generateDependencyDiagram,
+	generateModuleSummary,
+	type ModuleSummary,
+} from "./explain/index";
+// Features
+export {
+	type AnalysisFinding,
+	type AnalysisReport,
+	analyze,
+} from "./features/analyzer";
+export {
+	type CheckResult,
+	type VerificationReport,
+	verifyPlan,
+} from "./features/checklist";
+export {
+	createFeatureDir,
+	type DesignChoices,
+	getNextFeatureNumber,
+	scaffoldFeature,
+	scaffoldFeatureWithContext,
+} from "./features/numbering";
+export { type QualityScore, scoreSpec } from "./features/quality";
+export { generateTestStubs } from "./features/test-stubs";
+export type {
+	TaskTrace,
+	TraceabilityReport,
+	TraceDeps,
+} from "./features/traceability";
+export { traceFeature } from "./features/traceability";
+// Feedback
+export {
+	type FeedbackRecord,
+	getFeedbackSummary,
+	getWorkflowId,
+	recordFeedback,
+	recordFeedbackAsync,
+	recordFeedbackWithCompression,
+} from "./feedback/collector";
+export {
+	compressReview,
+	storeCompressedReview,
+} from "./feedback/compress";
+export {
+	acknowledgeFinding,
+	dismissFinding,
+	getNoisyRules,
+	loadPreferences,
+	type Preferences,
+	type RulePreference,
+	savePreferences,
+} from "./feedback/preferences";
+// Git
+export {
+	type Commit,
+	getBranchName,
+	getChangedFiles,
+	getCurrentBranch,
+	getDiff,
+	getRecentCommits,
+	getRepoRoot,
+	getStagedFiles,
+	getTrackedFiles,
+} from "./git/index";
+// Hooks
+export {
+	executeHook,
+	type HookContext,
+	type HookEvent,
+	type HookResult,
+	runHooks,
+	scanHooks,
+} from "./hooks/index";
+// Init
+export {
+	bootstrap,
+	type DetectedStack,
+	type InitOptions,
+	type InitReport,
+} from "./init/index";
+// Language
+export {
+	detectLanguages,
+	getPrimaryLanguage,
+} from "./language/detect";
+export {
+	GO_PROFILE,
+	getProfile,
+	getSupportedLanguages,
+	type LanguageId,
+	type LanguageProfile,
+	PYTHON_PROFILE,
+	RUST_PROFILE,
+	TYPESCRIPT_PROFILE,
+} from "./language/profile";
+export { loadDefault, type PromptTask } from "./prompts/defaults/index";
+// Prompts
+export {
+	type BuiltPrompt,
+	buildSystemPrompt,
+	type FeedbackOutcome,
+	getPromptStats,
+	type PromptStat,
+	recordOutcome,
+} from "./prompts/engine";
+export {
+	type ABResolution,
+	abTest,
+	analyseFeedback,
+	analyseWorkflowFeedback,
+	analyseWorkflowRuns,
+	type CandidatePrompt,
+	createCandidate,
+	type FeedbackAnalysis,
+	promote,
+	resolveABTests,
+	retire,
+	type WorkflowRunSummary,
+	type WorkflowStepAnalysis,
+} from "./prompts/evolution";
+// Comprehensive Review (Superpowers-style)
+export {
+	type ComprehensiveReviewFinding,
+	type ComprehensiveReviewOptions,
+	type ComprehensiveReviewResult,
+	comprehensiveReview,
+	type ReviewSeverity,
+} from "./review/comprehensive";
+// PR Review (two-stage)
+export {
+	type ReviewFinding as PrReviewFinding,
+	type ReviewOptions as PrReviewOptions,
+	type ReviewResult as PrReviewResult,
+	type ReviewStageResult,
+	reviewCodeQuality,
+	reviewCodeQualityWithAI,
+	reviewSpecCompliance,
+	runTwoStageReview,
+} from "./review/index";
+// Stats
+export {
+	type CommitSnapshot,
+	type ComparisonReport,
+	getComparison,
+	getLatest,
+	getSkipRate,
+	getStats,
+	getTrends,
+	recordSnapshot,
+	type SnapshotInput,
+	type StatsReport,
+	type TrendDirection,
+	type TrendsReport,
+} from "./stats/tracker";
+// Ticket
+export {
+	buildIssueBody,
+	createTicket,
+	detectModules,
+	type SpawnDeps,
+	type TicketOptions,
+	type TicketResult,
+} from "./ticket/index";
+// Utils
+export { toKebabCase } from "./utils";
+// Verify — AI Review
+export {
+	type AIReviewOptions,
+	type AIReviewResult,
+	type EntityWithBody,
+	type ReferencedFunction,
+	resolveReferencedFunctions,
+	runAIReview,
+} from "./verify/ai-review";
+// Verify — Coverage
+export {
+	type CoverageOptions,
+	type CoverageResult,
+	parseDiffCoverJson,
+	runCoverage,
+} from "./verify/coverage";
+export {
+	type DetectedTool,
+	detectTool,
+	detectTools,
+	isToolAvailable,
+	TOOL_REGISTRY,
+	type ToolName,
+} from "./verify/detect";
+export {
+	type DiffFilterResult,
+	type Finding,
+	filterByDiff,
+	filterByDiffWithMap,
+	parseChangedLines,
+} from "./verify/diff-filter";
+export {
+	type FixOptions,
+	type FixResult,
+	type FixSuggestion,
+	generateFixes,
+	hashFinding,
+	parseFixResponse,
+} from "./verify/fix";
+// Verify — Mutation
+export {
+	type MutationOptions,
+	type MutationResult,
+	parseStrykerReport,
+	runMutation,
+} from "./verify/mutation";
+// Verify — Pipeline
+export {
+	type PipelineOptions,
+	type PipelineResult,
+	runPipeline,
+	type ToolReport,
+} from "./verify/pipeline";
+// Verify — Proof
+export {
+	formatVerificationProof,
+	gatherVerificationProof,
+	type ProofOptions,
+	type ToolProof,
+	type VerificationProof,
+} from "./verify/proof";
+export {
+	detectCommentedCode,
+	detectConsoleLogs,
+	detectEmptyBodies,
+	detectHallucinatedImports,
+	detectSlop,
+	detectTodosWithoutTickets,
+	type SlopResult,
+	type SlopRule,
+} from "./verify/slop";
+// Verify — SonarQube
+export {
+	parseSonarReport,
+	runSonar,
+	type SonarOptions,
+	type SonarResult,
+} from "./verify/sonar";
+export {
+	parseBiomeOutput,
+	type SyntaxDiagnostic,
+	type SyntaxGuardResult,
+	syntaxGuard,
+} from "./verify/syntax-guard";
+// Verify — Visual
+export {
+	captureScreenshot,
+	compareImages,
+	detectWebProject,
+	loadVisualConfig,
+	runVisualVerification,
+	type ScreenshotOptions,
+	type ScreenshotResult,
+	updateBaselines,
+	type VisualConfig,
+	type VisualDiffResult,
+	type VisualVerifyResult,
+} from "./verify/visual";
+// Workflow
+export {
+	appendWorkflowStep,
+	loadWorkflowContext,
+	resetWorkflowContext,
+} from "./workflow/context";

package/src/init/__tests__/init.test.ts

@@ -0,0 +1,228 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrap } from "../index";
+
+function makeTmpDir(): string {
+	const dir = join(
+		tmpdir(),
+		`maina-init-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+	);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+describe("bootstrap", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTmpDir();
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	test("creates .maina/ directory", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(existsSync(join(tmpDir, ".maina"))).toBe(true);
+			expect(result.value.directory).toBe(join(tmpDir, ".maina"));
+		}
+	});
+
+	test("creates constitution.md with template", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+
+		const constitutionPath = join(tmpDir, ".maina", "constitution.md");
+		expect(existsSync(constitutionPath)).toBe(true);
+
+		const content = readFileSync(constitutionPath, "utf-8");
+		expect(content).toContain("# Project Constitution");
+		expect(content).toContain("## Stack");
+		expect(content).toContain("## Architecture");
+		expect(content).toContain("## Verification");
+		expect(content).toContain("[NEEDS CLARIFICATION]");
+	});
+
+	test("creates AGENTS.md at repo root", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+
+		const agentsPath = join(tmpDir, "AGENTS.md");
+		expect(existsSync(agentsPath)).toBe(true);
+
+		const content = readFileSync(agentsPath, "utf-8");
+		expect(content).toContain("# AGENTS.md");
+		expect(content).toContain("maina verify");
+		expect(content).toContain("maina commit");
+		expect(content).toContain("maina context");
+		expect(content).toContain("maina doctor");
+		expect(content).toContain("constitution.md");
+	});
+
+	test("creates CI workflow", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+
+		const ciPath = join(tmpDir, ".github", "workflows", "maina-ci.yml");
+		expect(existsSync(ciPath)).toBe(true);
+
+		const content = readFileSync(ciPath, "utf-8");
+		expect(content).toContain("name: Maina CI");
+		expect(content).toContain("actions/checkout@v4");
+	});
+
+	test("detects bun stack from package.json", async () => {
+		// Create a Bun project
+		writeFileSync(
+			join(tmpDir, "package.json"),
+			JSON.stringify({ devDependencies: { "@types/bun": "latest" } }),
+		);
+		writeFileSync(join(tmpDir, "tsconfig.json"), "{}");
+
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.detectedStack.runtime).toBe("bun");
+			expect(result.value.detectedStack.language).toBe("typescript");
+
+			const ci = readFileSync(
+				join(tmpDir, ".github", "workflows", "maina-ci.yml"),
+				"utf-8",
+			);
+			expect(ci).toContain("oven-sh/setup-bun@v2");
+			expect(ci).toContain("bun install");
+		}
+	});
+
+	test("creates prompts directory with defaults", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+
+		const promptsDir = join(tmpDir, ".maina", "prompts");
+		expect(existsSync(promptsDir)).toBe(true);
+
+		const reviewPath = join(promptsDir, "review.md");
+		expect(existsSync(reviewPath)).toBe(true);
+		const reviewContent = readFileSync(reviewPath, "utf-8");
+		expect(reviewContent.length).toBeGreaterThan(0);
+
+		const commitPath = join(promptsDir, "commit.md");
+		expect(existsSync(commitPath)).toBe(true);
+		const commitContent = readFileSync(commitPath, "utf-8");
+		expect(commitContent.length).toBeGreaterThan(0);
+	});
+
+	test("creates hooks directory", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+
+		const hooksDir = join(tmpDir, ".maina", "hooks");
+		expect(existsSync(hooksDir)).toBe(true);
+	});
+
+	test("skips existing files (no overwrite)", async () => {
+		// Pre-create constitution.md with custom content
+		const mainaDir = join(tmpDir, ".maina");
+		mkdirSync(mainaDir, { recursive: true });
+		const constitutionPath = join(mainaDir, "constitution.md");
+		writeFileSync(constitutionPath, "# My Custom Constitution\n");
+
+		// Pre-create AGENTS.md with custom content
+		const agentsPath = join(tmpDir, "AGENTS.md");
+		writeFileSync(agentsPath, "# My Custom Agents\n");
+
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.skipped).toContain(".maina/constitution.md");
+			expect(result.value.skipped).toContain("AGENTS.md");
+
+			// Content should NOT have been overwritten
+			const content = readFileSync(constitutionPath, "utf-8");
+			expect(content).toBe("# My Custom Constitution\n");
+
+			const agentsContent = readFileSync(agentsPath, "utf-8");
+			expect(agentsContent).toBe("# My Custom Agents\n");
+		}
+	});
+
+	test("force flag overwrites existing", async () => {
+		// Pre-create constitution.md with custom content
+		const mainaDir = join(tmpDir, ".maina");
+		mkdirSync(mainaDir, { recursive: true });
+		const constitutionPath = join(mainaDir, "constitution.md");
+		writeFileSync(constitutionPath, "# My Custom Constitution\n");
+
+		const result = await bootstrap(tmpDir, { force: true });
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.created).toContain(".maina/constitution.md");
+			expect(result.value.skipped).not.toContain(".maina/constitution.md");
+
+			// Content should have been overwritten with template
+			const content = readFileSync(constitutionPath, "utf-8");
+			expect(content).toContain("# Project Constitution");
+		}
+	});
+
+	test("returns correct created/skipped lists", async () => {
+		// Pre-create one file
+		const mainaDir = join(tmpDir, ".maina");
+		mkdirSync(mainaDir, { recursive: true });
+		writeFileSync(join(mainaDir, "constitution.md"), "existing\n");
+
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			// constitution.md should be skipped
+			expect(result.value.skipped).toContain(".maina/constitution.md");
+			expect(result.value.created).not.toContain(".maina/constitution.md");
+
+			// Other files should be created
+			expect(result.value.created).toContain("AGENTS.md");
+			expect(result.value.created).toContain(".github/workflows/maina-ci.yml");
+			expect(result.value.created).toContain(".maina/prompts/review.md");
+			expect(result.value.created).toContain(".maina/prompts/commit.md");
+
+			// Total files should add up
+			const total = result.value.created.length + result.value.skipped.length;
+			expect(total).toBeGreaterThanOrEqual(5);
+		}
+	});
+
+	test("works on empty directory", async () => {
+		// tmpDir is already empty
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.created.length).toBeGreaterThanOrEqual(5);
+			expect(result.value.skipped.length).toBe(0);
+			expect(result.value.directory).toBe(join(tmpDir, ".maina"));
+		}
+	});
+
+	test("detects available verification tools in report", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.detectedTools).toBeDefined();
+			expect(Array.isArray(result.value.detectedTools)).toBe(true);
+			// Each tool should have name and available flag
+			for (const tool of result.value.detectedTools) {
+				expect(typeof tool.name).toBe("string");
+				expect(typeof tool.available).toBe("boolean");
+			}
+		}
+	});
+});