@mainahq/core 0.2.0

package/src/context/selector.ts

@@ -0,0 +1,93 @@
+import type { BudgetMode } from "./budget.ts";
+
+export type MainaCommand =
+	| "commit"
+	| "verify"
+	| "context"
+	| "review"
+	| "plan"
+	| "explain"
+	| "design"
+	| "ticket"
+	| "analyze"
+	| "pr";
+
+export interface ContextNeeds {
+	working: boolean;
+	episodic: boolean | string[];
+	semantic: boolean | string[];
+	retrieval: boolean;
+}
+
+const CONTEXT_NEEDS: Record<MainaCommand, ContextNeeds> = {
+	commit: {
+		working: true,
+		episodic: false,
+		semantic: ["conventions"],
+		retrieval: false,
+	},
+	verify: {
+		working: true,
+		episodic: ["recent-reviews"],
+		semantic: ["adrs", "conventions"],
+		retrieval: false,
+	},
+	context: { working: true, episodic: true, semantic: true, retrieval: true },
+	review: {
+		working: true,
+		episodic: ["past-reviews"],
+		semantic: ["adrs"],
+		retrieval: false,
+	},
+	plan: {
+		working: true,
+		semantic: ["adrs", "conventions"],
+		episodic: false,
+		retrieval: false,
+	},
+	explain: { working: true, episodic: false, semantic: true, retrieval: true },
+	design: {
+		working: true,
+		episodic: false,
+		semantic: ["adrs"],
+		retrieval: false,
+	},
+	ticket: {
+		working: false,
+		episodic: false,
+		semantic: ["modules"],
+		retrieval: false,
+	},
+	analyze: { working: true, episodic: true, semantic: true, retrieval: false },
+	pr: {
+		working: true,
+		episodic: ["past-reviews"],
+		semantic: true,
+		retrieval: true,
+	},
+};
+
+export function getContextNeeds(command: MainaCommand): ContextNeeds {
+	return CONTEXT_NEEDS[command];
+}
+
+export function needsLayer(
+	needs: ContextNeeds,
+	layer: "working" | "episodic" | "semantic" | "retrieval",
+): boolean {
+	const value = needs[layer];
+	if (Array.isArray(value)) {
+		return value.length > 0;
+	}
+	return value === true;
+}
+
+export function getBudgetMode(command: MainaCommand): BudgetMode {
+	if (command === "commit") {
+		return "focused";
+	}
+	if (command === "context" || command === "explain") {
+		return "explore";
+	}
+	return "default";
+}

package/src/context/semantic.ts

@@ -0,0 +1,331 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { getContextDb } from "../db/index";
+import {
+	buildGraph,
+	type DependencyGraph,
+	scoreRelevance,
+	type TaskContext,
+} from "./relevance";
+import { parseFile } from "./treesitter";
+
+export interface SemanticContext {
+	entities: {
+		filePath: string;
+		name: string;
+		kind: string;
+		relevance: number;
+	}[];
+	graph: DependencyGraph;
+	scores: Map<string, number>;
+	constitution: string | null;
+	customContext: string[];
+}
+
+const SOURCE_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".py",
+	".pyi",
+	".go",
+	".rs",
+]);
+
+/**
+ * Recursively walks a directory and collects source files,
+ * excluding node_modules, dist, and .git directories.
+ */
+function collectSourceFiles(dir: string): string[] {
+	const results: string[] = [];
+	const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+	function walk(current: string): void {
+		let entries: string[];
+		try {
+			entries = readdirSync(current) as unknown as string[];
+		} catch {
+			return;
+		}
+
+		for (const entry of entries) {
+			if (SKIP_DIRS.has(entry)) continue;
+
+			const fullPath = join(current, entry);
+			let stat: ReturnType<typeof statSync> | undefined;
+			try {
+				stat = statSync(fullPath);
+			} catch {
+				continue;
+			}
+
+			if (stat.isDirectory()) {
+				walk(fullPath);
+			} else if (stat.isFile()) {
+				const dotIdx = entry.lastIndexOf(".");
+				const ext = dotIdx >= 0 ? entry.slice(dotIdx) : "";
+				if (SOURCE_EXTENSIONS.has(ext)) {
+					results.push(fullPath);
+				}
+			}
+		}
+	}
+
+	walk(dir);
+	return results;
+}
+
+/**
+ * Reads .maina/constitution.md if it exists, returning its content.
+ * Returns null if the file does not exist or cannot be read.
+ */
+export async function loadConstitution(
+	mainaDir: string,
+): Promise<string | null> {
+	const constitutionPath = join(mainaDir, "constitution.md");
+	try {
+		const exists = await Bun.file(constitutionPath).exists();
+		if (!exists) return null;
+		return await Bun.file(constitutionPath).text();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Reads all files from .maina/context/semantic/custom/ and returns their contents.
+ * Returns an empty array if the directory doesn't exist or is empty.
+ */
+export async function loadCustomContext(mainaDir: string): Promise<string[]> {
+	const customDir = join(mainaDir, "context", "semantic", "custom");
+
+	let entries: string[];
+	try {
+		entries = readdirSync(customDir) as unknown as string[];
+	} catch {
+		return [];
+	}
+
+	const results: string[] = [];
+	for (const entry of entries) {
+		const filePath = join(customDir, entry);
+		try {
+			const stat = statSync(filePath);
+			if (!stat.isFile()) continue;
+			const content = await Bun.file(filePath).text();
+			results.push(content);
+		} catch {}
+	}
+
+	return results;
+}
+
+/**
+ * Builds the full semantic context for a repo:
+ * - Scans .ts/.js files (excluding node_modules/dist/.git)
+ * - Builds dependency graph
+ * - Runs PageRank (personalized toward task context)
+ * - Loads constitution and custom context
+ * - Attaches relevance scores to all parsed entities
+ */
+export async function buildSemanticContext(
+	repoRoot: string,
+	mainaDir: string,
+	taskContext: TaskContext,
+): Promise<SemanticContext> {
+	// Collect all relevant source files
+	const files = collectSourceFiles(repoRoot);
+
+	// Build dependency graph
+	const graph = await buildGraph(files);
+
+	// Run PageRank with task personalization
+	const scores = scoreRelevance(graph, taskContext);
+
+	// Parse entities from all files and annotate with relevance.
+	// Entity filePaths are stored as relative to repoRoot for LLM consumption.
+	const entities: SemanticContext["entities"] = [];
+
+	for (const file of files) {
+		const fileScore = scores.get(file) ?? 0;
+		const relPath = relative(repoRoot, file);
+		let parsed: Awaited<ReturnType<typeof parseFile>> | undefined;
+		try {
+			parsed = await parseFile(file);
+		} catch {
+			continue;
+		}
+
+		for (const entity of parsed.entities) {
+			entities.push({
+				filePath: relPath,
+				name: entity.name,
+				kind: entity.kind,
+				relevance: fileScore,
+			});
+		}
+	}
+
+	// Load constitution and custom context
+	const [constitution, customContext] = await Promise.all([
+		loadConstitution(mainaDir),
+		loadCustomContext(mainaDir),
+	]);
+
+	return {
+		entities,
+		graph,
+		scores,
+		constitution,
+		customContext,
+	};
+}
+
+/**
+ * Returns top N entities sorted by relevance score (descending).
+ * Default N is 20.
+ */
+export function getTopEntities(
+	context: SemanticContext,
+	n = 20,
+): { filePath: string; name: string; kind: string; relevance: number }[] {
+	return [...context.entities]
+		.sort((a, b) => b.relevance - a.relevance)
+		.slice(0, n);
+}
+
+/**
+ * Formats the semantic context for LLM consumption.
+ * If filter is provided, only includes sections matching the filter terms.
+ */
+export function assembleSemanticText(
+	context: SemanticContext,
+	filter?: string[],
+): string {
+	const parts: string[] = [];
+
+	const shouldInclude = (sectionName: string): boolean => {
+		if (!filter || filter.length === 0) return true;
+		const lower = sectionName.toLowerCase();
+		return filter.some((f) => lower.includes(f.toLowerCase()));
+	};
+
+	// Constitution
+	if (context.constitution && shouldInclude("constitution")) {
+		parts.push("## Project Constitution\n");
+		parts.push(context.constitution);
+	}
+
+	// Custom context files
+	if (context.customContext.length > 0) {
+		for (const content of context.customContext) {
+			// Determine section name from content heading (first line)
+			const firstLine = content.split("\n")[0] ?? "";
+			const sectionName = firstLine.replace(/^#+\s*/, "").trim() || "custom";
+
+			if (shouldInclude(sectionName) || shouldInclude("custom")) {
+				parts.push(content);
+			}
+		}
+	}
+
+	// Codebase overview section: group entities by file, sorted by relevance
+	if (shouldInclude("entities") || !filter || filter.length === 0) {
+		const topEntities = getTopEntities(context, 200);
+		if (topEntities.length > 0) {
+			// Group entities by filePath
+			const byFile = new Map<
+				string,
+				{ kind: string; name: string; relevance: number }[]
+			>();
+			for (const entity of topEntities) {
+				const existing = byFile.get(entity.filePath) ?? [];
+				existing.push({
+					kind: entity.kind,
+					name: entity.name,
+					relevance: entity.relevance,
+				});
+				byFile.set(entity.filePath, existing);
+			}
+
+			// Sort files by max relevance descending
+			const sortedFiles = [...byFile.entries()].sort((a, b) => {
+				const maxA = Math.max(...a[1].map((e) => e.relevance));
+				const maxB = Math.max(...b[1].map((e) => e.relevance));
+				return maxB - maxA;
+			});
+
+			parts.push("## Codebase Overview\n");
+			for (const [filePath, entities] of sortedFiles) {
+				const fileScore = Math.max(...entities.map((e) => e.relevance));
+				parts.push(`### ${filePath} (relevance: ${fileScore.toFixed(4)})`);
+				for (const entity of entities) {
+					parts.push(`- \`${entity.name}\` (${entity.kind})`);
+				}
+				parts.push("");
+			}
+		}
+	}
+
+	return parts.join("\n");
+}
+
+/**
+ * Persist semantic context (entities + dependency edges) to the context DB.
+ * Replaces all existing data — this is a full re-index.
+ * Never throws — silently fails on DB errors.
+ */
+export function persistSemanticContext(
+	mainaDir: string,
+	context: SemanticContext,
+	repoRoot: string,
+): void {
+	try {
+		const dbResult = getContextDb(mainaDir);
+		if (!dbResult.ok) return;
+
+		const db = dbResult.value.db;
+		const now = new Date().toISOString();
+
+		// Clear existing data and re-insert (full re-index)
+		db.exec("DELETE FROM semantic_entities");
+		db.exec("DELETE FROM dependency_edges");
+
+		// Insert entities
+		const insertEntity = db.prepare(
+			`INSERT INTO semantic_entities (id, file_path, name, kind, start_line, end_line, updated_at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		);
+		for (const entity of context.entities) {
+			insertEntity.run(
+				crypto.randomUUID(),
+				entity.filePath,
+				entity.name,
+				entity.kind,
+				0,
+				0,
+				now,
+			);
+		}
+
+		// Insert dependency edges
+		const insertEdge = db.prepare(
+			`INSERT INTO dependency_edges (id, source_file, target_file, weight, type)
+			 VALUES (?, ?, ?, ?, ?)`,
+		);
+		for (const [source, targets] of context.graph.edges) {
+			for (const [target, weight] of targets) {
+				insertEdge.run(
+					crypto.randomUUID(),
+					relative(repoRoot, source),
+					relative(repoRoot, target),
+					weight,
+					"import",
+				);
+			}
+		}
+	} catch {
+		// Persistence failure should never propagate
+	}
+}

package/src/context/treesitter.ts

@@ -0,0 +1,216 @@
+export interface ParsedEntity {
+	name: string;
+	kind: "function" | "class" | "interface" | "type" | "variable";
+	startLine: number;
+	endLine: number;
+}
+
+export interface ParsedImport {
+	source: string;
+	specifiers: string[];
+	isDefault: boolean;
+}
+
+export interface ParsedExport {
+	name: string;
+	kind: string;
+}
+
+export interface ParseResult {
+	imports: ParsedImport[];
+	exports: ParsedExport[];
+	entities: ParsedEntity[];
+}
+
+/**
+ * Extracts import statements from TypeScript/JavaScript source content.
+ * Handles named imports, default imports, namespace imports, and type imports.
+ * Results are returned in source-order (line order).
+ */
+export function extractImports(content: string): ParsedImport[] {
+	// Collect all matches with their index so we can sort by position
+	type RawMatch = { index: number; result: ParsedImport };
+	const raw: RawMatch[] = [];
+
+	// Match: import * as X from "..."
+	const namespaceRe = /^import\s+\*\s+as\s+(\w+)\s+from\s+["']([^"']+)["']/gm;
+	for (const match of content.matchAll(namespaceRe)) {
+		const name = match[1];
+		const source = match[2];
+		if (name && source) {
+			raw.push({
+				index: match.index ?? 0,
+				result: { source, specifiers: [name], isDefault: false },
+			});
+		}
+	}
+
+	// Match: import { X, Y } from "..." (including import type { ... })
+	const namedRe =
+		/^import\s+(?:type\s+)?\{\s*([^}]+)\}\s+from\s+["']([^"']+)["']/gm;
+	for (const match of content.matchAll(namedRe)) {
+		const specifierStr = match[1];
+		const source = match[2];
+		if (specifierStr && source) {
+			const specifiers = specifierStr
+				.split(",")
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0);
+			raw.push({
+				index: match.index ?? 0,
+				result: { source, specifiers, isDefault: false },
+			});
+		}
+	}
+
+	// Match: import X from "..." (default import, but NOT namespace or named)
+	const defaultRe = /^import\s+(\w+)\s+from\s+["']([^"']+)["']/gm;
+	for (const match of content.matchAll(defaultRe)) {
+		const name = match[1];
+		const source = match[2];
+		if (name && source) {
+			// Avoid double-counting "type" keyword (import type { ... } matched above)
+			if (name === "type") continue;
+			raw.push({
+				index: match.index ?? 0,
+				result: { source, specifiers: [name], isDefault: true },
+			});
+		}
+	}
+
+	// Sort by position in source file and return
+	raw.sort((a, b) => a.index - b.index);
+	return raw.map((r) => r.result);
+}
+
+/**
+ * Extracts export declarations from TypeScript/JavaScript source content.
+ * Handles exported functions, classes, interfaces, types, consts, defaults, and re-exports.
+ */
+export function extractExports(content: string): ParsedExport[] {
+	const results: ParsedExport[] = [];
+
+	// export function / export async function
+	const funcRe = /^export\s+(?:async\s+)?function\s+(\w+)/gm;
+	for (const match of content.matchAll(funcRe)) {
+		const name = match[1];
+		if (name) results.push({ name, kind: "function" });
+	}
+
+	// export class
+	const classRe = /^export\s+class\s+(\w+)/gm;
+	for (const match of content.matchAll(classRe)) {
+		const name = match[1];
+		if (name) results.push({ name, kind: "class" });
+	}
+
+	// export interface
+	const interfaceRe = /^export\s+interface\s+(\w+)/gm;
+	for (const match of content.matchAll(interfaceRe)) {
+		const name = match[1];
+		if (name) results.push({ name, kind: "interface" });
+	}
+
+	// export type X =
+	const typeRe = /^export\s+type\s+(\w+)\s*=/gm;
+	for (const match of content.matchAll(typeRe)) {
+		const name = match[1];
+		if (name) results.push({ name, kind: "type" });
+	}
+
+	// export const / export let / export var
+	const constRe = /^export\s+(?:const|let|var)\s+(\w+)/gm;
+	for (const match of content.matchAll(constRe)) {
+		const name = match[1];
+		if (name) results.push({ name, kind: "variable" });
+	}
+
+	// export default (class/function/expression)
+	const defaultClassRe = /^export\s+default\s+(?:class|function)\s+(\w+)/gm;
+	for (const _match of content.matchAll(defaultClassRe)) {
+		// Named default export — still record as "default"
+		results.push({ name: "default", kind: "default" });
+	}
+	// export default (bare keyword, no named class/function)
+	const defaultBareRe = /^export\s+default\s+(?!class\s+\w|function\s+\w)/gm;
+	for (const _match of content.matchAll(defaultBareRe)) {
+		results.push({ name: "default", kind: "default" });
+	}
+
+	// export { X, Y } or export { X, Y } from "..."
+	const reExportRe = /^export\s+\{\s*([^}]+)\}/gm;
+	for (const match of content.matchAll(reExportRe)) {
+		const specifierStr = match[1];
+		if (specifierStr) {
+			const specifiers = specifierStr
+				.split(",")
+				.map((s) => {
+					// handle "X as Y" — use the exported name (Y)
+					const parts = s.trim().split(/\s+as\s+/);
+					return (parts[parts.length - 1] ?? "").trim();
+				})
+				.filter((s) => s.length > 0);
+			for (const name of specifiers) {
+				results.push({ name, kind: "reexport" });
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Extracts top-level entity declarations (functions, classes, interfaces, types, variables)
+ * with their starting line numbers.
+ */
+export function extractEntities(content: string): ParsedEntity[] {
+	const results: ParsedEntity[] = [];
+	const lines = content.split("\n");
+
+	// Patterns: each tuple is [regex, kind]
+	const patterns: Array<[RegExp, ParsedEntity["kind"]]> = [
+		// function declarations (exported or not, async or not)
+		[/^(?:export\s+)?(?:async\s+)?function\s+(\w+)/, "function"],
+		// class declarations
+		[/^(?:export\s+)?class\s+(\w+)/, "class"],
+		// interface declarations
+		[/^(?:export\s+)?interface\s+(\w+)/, "interface"],
+		// type alias: type X =
+		[/^(?:export\s+)?type\s+(\w+)\s*=/, "type"],
+		// top-level const/let/var (must start at column 0)
+		[/^(?:export\s+)?(?:const|let|var)\s+(\w+)/, "variable"],
+	];
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		const lineNum = i + 1; // 1-based
+
+		for (const [pattern, kind] of patterns) {
+			const match = line.match(pattern);
+			if (match) {
+				const name = match[1];
+				if (name) {
+					results.push({ name, kind, startLine: lineNum, endLine: lineNum });
+					break; // only match one pattern per line
+				}
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * Reads a TypeScript/JavaScript file from disk and returns its parsed structure:
+ * imports, exports, and top-level entities with line numbers.
+ */
+export async function parseFile(filePath: string): Promise<ParseResult> {
+	const file = Bun.file(filePath);
+	const content = await file.text();
+
+	return {
+		imports: extractImports(content),
+		exports: extractExports(content),
+		entities: extractEntities(content),
+	};
+}