@mainahq/core 1.0.3 → 1.1.1

package/src/wiki/extractors/code.ts

@@ -0,0 +1,90 @@
+/**
+ * Code Entity Extractor — thin adapter for wiki compilation.
+ *
+ * Uses regex-based extraction of exported entities from TypeScript files.
+ * This is a lightweight approach for the wiki foundation — the full
+ * tree-sitter + PageRank analysis lives in the Semantic layer and will
+ * be integrated in Sprint 1 (Knowledge Graph).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Result } from "../../db/index";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface CodeEntity {
+	name: string;
+	kind: "function" | "class" | "interface" | "type" | "variable" | "enum";
+	file: string;
+	line: number;
+	exported: boolean;
+}
+
+// ─── Extraction ──────────────────────────────────────────────────────────
+
+/**
+ * Extract entities from a single TypeScript file using regex patterns.
+ * Captures exported functions, classes, interfaces, types, variables, and enums.
+ */
+function extractFromFile(repoRoot: string, relativePath: string): CodeEntity[] {
+	const fullPath = join(repoRoot, relativePath);
+	if (!existsSync(fullPath)) return [];
+
+	let content: string;
+	try {
+		content = readFileSync(fullPath, "utf-8");
+	} catch {
+		return [];
+	}
+
+	const entities: CodeEntity[] = [];
+	const lines = content.split("\n");
+
+	const patterns: Array<{
+		regex: RegExp;
+		kind: CodeEntity["kind"];
+	}> = [
+		{ regex: /^export\s+(?:async\s+)?function\s+(\w+)/, kind: "function" },
+		{ regex: /^export\s+class\s+(\w+)/, kind: "class" },
+		{ regex: /^export\s+interface\s+(\w+)/, kind: "interface" },
+		{ regex: /^export\s+type\s+(\w+)/, kind: "type" },
+		{ regex: /^export\s+(?:const|let|var)\s+(\w+)/, kind: "variable" },
+		{ regex: /^export\s+enum\s+(\w+)/, kind: "enum" },
+	];
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		for (const { regex, kind } of patterns) {
+			const match = line.match(regex);
+			if (match?.[1]) {
+				entities.push({
+					name: match[1],
+					kind,
+					file: relativePath,
+					line: i + 1,
+					exported: true,
+				});
+				break;
+			}
+		}
+	}
+
+	return entities;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+export function extractCodeEntities(
+	repoRoot: string,
+	files: string[],
+): Result<CodeEntity[]> {
+	const allEntities: CodeEntity[] = [];
+
+	for (const file of files) {
+		const entities = extractFromFile(repoRoot, file);
+		allEntities.push(...entities);
+	}
+
+	return { ok: true, value: allEntities };
+}

package/src/wiki/extractors/decision.ts

@@ -0,0 +1,217 @@
+/**
+ * Decision Extractor — parses adr/*.md into structured ExtractedDecision records.
+ *
+ * ADRs follow the structured format from `maina design`:
+ *   # ADR-NNNN: Title (or # NNNN. Title)
+ *   ## Status
+ *   ## Context
+ *   ## Decision
+ *   ## Rationale / Consequences
+ *   ## Alternatives Considered
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Result } from "../../db/index";
+import type { DecisionStatus, ExtractedDecision } from "../types";
+
+// ─── Parsing Helpers ─────────────────────────────────────────────────────
+
+/**
+ * Extract sections from an ADR markdown file.
+ * Returns a map of lowercase section name → content.
+ *
+ * Handles nested subsections (### Positive, ### Negative) by merging
+ * them into the parent ## section rather than creating separate entries.
+ */
+function parseSections(content: string): Map<string, string> {
+	const sections = new Map<string, string>();
+	const lines = content.split("\n");
+	let currentSection = "";
+	const currentLines: string[] = [];
+
+	function flushSection(): void {
+		if (currentSection) {
+			sections.set(currentSection, currentLines.join("\n").trim());
+		}
+		currentLines.length = 0;
+	}
+
+	for (const line of lines) {
+		// Match ## headings (h2) but NOT ### headings (h3)
+		const h2Match = line.match(/^##\s+(?!#)(.+)/);
+		if (h2Match) {
+			flushSection();
+			currentSection = (h2Match[1] ?? "").trim().toLowerCase();
+			continue;
+		}
+		// ### subsections get merged into the current parent section
+		if (currentSection) {
+			currentLines.push(line);
+		}
+	}
+	flushSection();
+
+	return sections;
+}
+
+/**
+ * Extract ID from filename. Handles:
+ *   "0002-jwt-strategy.md" → "0002-jwt-strategy"
+ */
+function extractId(filename: string): string {
+	return basename(filename, ".md");
+}
+
+/**
+ * Extract title from first H1 heading. Handles:
+ *   "# ADR-0002: Use JWT for Authentication"
+ *   "# 0002. Use JWT for Authentication"
+ */
+function extractTitle(content: string): string {
+	const firstLine = content.split("\n")[0] ?? "";
+	const heading = firstLine.replace(/^#+\s*/, "");
+
+	// Strip "ADR-NNNN: " or "NNNN. " prefixes
+	const stripped = heading.replace(/^ADR-\d+:\s*/, "").replace(/^\d+\.\s*/, "");
+
+	return stripped.trim();
+}
+
+/**
+ * Normalize status string to DecisionStatus.
+ * The status section may contain the status on its own line,
+ * possibly with additional text (e.g. "Superseded by ADR-0005").
+ * Extract the first meaningful line and match against known statuses.
+ */
+function normalizeStatus(raw: string): DecisionStatus {
+	// Take the first non-empty line from the status section
+	const firstLine =
+		raw
+			.split("\n")
+			.map((l) => l.trim())
+			.find((l) => l.length > 0) ?? "";
+	const lower = firstLine.toLowerCase();
+	if (lower.startsWith("accepted")) return "accepted";
+	if (lower.startsWith("proposed")) return "proposed";
+	if (lower.startsWith("deprecated")) return "deprecated";
+	if (lower.startsWith("superseded")) return "superseded";
+	return "proposed";
+}
+
+/**
+ * Extract bullet list items from a section.
+ */
+function extractBulletItems(text: string): string[] {
+	const items: string[] = [];
+	for (const line of text.split("\n")) {
+		const match = line.match(/^-\s+(.+)/);
+		if (match?.[1]) {
+			items.push(match[1].trim());
+		}
+	}
+	return items;
+}
+
+/**
+ * Extract file/entity references from content.
+ * Looks for paths like src/auth/jwt.ts or packages/core/src/...
+ */
+function extractEntityMentions(content: string): string[] {
+	const mentions: string[] = [];
+	const regex = /(?:src\/|packages\/)[^\s,)]+\.(?:ts|js|tsx|jsx|py|go|rs)/g;
+	let match: RegExpExecArray | null;
+	// biome-ignore lint/suspicious/noAssignInExpressions: standard pattern for regex exec
+	while ((match = regex.exec(content)) !== null) {
+		mentions.push(match[0]);
+	}
+	return [...new Set(mentions)];
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+export function extractSingleDecision(
+	adrPath: string,
+): Result<ExtractedDecision> {
+	if (!existsSync(adrPath)) {
+		return { ok: false, error: `ADR file does not exist: ${adrPath}` };
+	}
+
+	let content: string;
+	try {
+		content = readFileSync(adrPath, "utf-8");
+	} catch (_e) {
+		return { ok: false, error: `Failed to read ADR: ${adrPath}` };
+	}
+
+	const id = extractId(adrPath);
+	const title = extractTitle(content);
+	const sections = parseSections(content);
+
+	const statusRaw = sections.get("status") ?? "";
+	const status = normalizeStatus(statusRaw);
+
+	const context = sections.get("context") ?? "";
+	const decision = sections.get("decision") ?? "";
+
+	// Rationale can be under "rationale", "consequences", or "positive"
+	const rationale =
+		sections.get("rationale") ??
+		sections.get("consequences") ??
+		sections.get("positive") ??
+		"";
+
+	// Alternatives under various headings — gracefully return empty if missing
+	const altSection =
+		sections.get("alternatives considered") ??
+		sections.get("alternatives") ??
+		"";
+	const alternativesRejected = extractBulletItems(altSection);
+
+	// Entity mentions: check "entities" section first, then always fall back to full content scan
+	const entitiesSection = sections.get("entities") ?? "";
+	const entityBullets = extractBulletItems(entitiesSection);
+	const entityMentions =
+		entityBullets.length > 0 ? entityBullets : extractEntityMentions(content);
+
+	return {
+		ok: true,
+		value: {
+			id,
+			title,
+			status,
+			context,
+			decision,
+			rationale,
+			alternativesRejected,
+			entityMentions,
+			constitutionAlignment: [],
+		},
+	};
+}
+
+export function extractDecisions(adrDir: string): Result<ExtractedDecision[]> {
+	if (!existsSync(adrDir)) {
+		return { ok: false, error: `ADR directory does not exist: ${adrDir}` };
+	}
+
+	let entries: string[];
+	try {
+		entries = readdirSync(adrDir);
+	} catch {
+		return { ok: false, error: `Failed to read ADR directory: ${adrDir}` };
+	}
+
+	const decisions: ExtractedDecision[] = [];
+
+	for (const entry of entries) {
+		if (!entry.endsWith(".md")) continue;
+
+		const result = extractSingleDecision(join(adrDir, entry));
+		if (result.ok) {
+			decisions.push(result.value);
+		}
+	}
+
+	return { ok: true, value: decisions };
+}

package/src/wiki/extractors/feature.ts

@@ -0,0 +1,206 @@
+/**
+ * Feature Extractor — parses plan.md, spec.md, tasks.md from feature directories
+ * into structured ExtractedFeature records.
+ *
+ * These are already structured markdown generated by maina, so parsing
+ * is deterministic (not LLM-dependent).
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Result } from "../../db/index";
+import type { ExtractedFeature, TaskItem } from "../types";
+
+// ─── Parsing Helpers ─────────────────────────────────────────────────────
+
+function readOptionalFile(path: string): string | null {
+	if (!existsSync(path)) return null;
+	try {
+		return readFileSync(path, "utf-8");
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extract title from plan.md or spec.md heading.
+ * Handles:
+ *   "# Implementation Plan: Token Refresh"
+ *   "# Feature: Token Refresh"
+ *   "# Token Refresh"
+ */
+function extractTitle(content: string): string {
+	const firstLine = content.split("\n")[0] ?? "";
+	const heading = firstLine.replace(/^#+\s*/, "");
+
+	// Strip common prefixes
+	const prefixes = ["Implementation Plan:", "Feature:", "Plan:"];
+	for (const prefix of prefixes) {
+		if (heading.startsWith(prefix)) {
+			return heading.slice(prefix.length).trim();
+		}
+	}
+	return heading.trim();
+}
+
+/**
+ * Extract tasks from markdown checklist format.
+ * Supports: "- [ ] T001: description" and "- [x] T002: description"
+ */
+function extractTasks(content: string): TaskItem[] {
+	const tasks: TaskItem[] = [];
+	const lines = content.split("\n");
+
+	for (const line of lines) {
+		const match = line.match(/^-\s+\[([ xX])\]\s+(T\d+):\s+(.+)/);
+		if (match?.[2]) {
+			tasks.push({
+				id: match[2],
+				description: (match[3] ?? "").trim(),
+				completed: match[1] !== " ",
+			});
+		}
+	}
+
+	return tasks;
+}
+
+/**
+ * Extract acceptance criteria / assertions from spec.md.
+ * Looks for checklist items under Acceptance Criteria section.
+ */
+function extractSpecAssertions(specContent: string): string[] {
+	const assertions: string[] = [];
+	const lines = specContent.split("\n");
+	let inSection = false;
+
+	for (const line of lines) {
+		// Detect start of acceptance criteria section
+		if (/^##\s+Acceptance Criteria/i.test(line)) {
+			inSection = true;
+			continue;
+		}
+		// End of section at next heading
+		if (inSection && /^##\s/.test(line)) {
+			break;
+		}
+		if (inSection) {
+			const match = line.match(/^-\s+\[[ xX]?\]\s+(.+)/);
+			if (match?.[1]) {
+				assertions.push(match[1].trim());
+			}
+		}
+	}
+
+	return assertions;
+}
+
+/**
+ * Extract scope from spec.md. Looks for text under ## Scope section.
+ */
+function extractScope(specContent: string): string {
+	const lines = specContent.split("\n");
+	let inSection = false;
+	const scopeLines: string[] = [];
+
+	for (const line of lines) {
+		if (/^##\s+Scope/i.test(line)) {
+			inSection = true;
+			continue;
+		}
+		if (inSection && /^##\s/.test(line)) {
+			break;
+		}
+		if (inSection && line.trim()) {
+			scopeLines.push(line.trim());
+		}
+	}
+
+	return scopeLines.join(" ");
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+export function extractSingleFeature(
+	featureDir: string,
+): Result<ExtractedFeature> {
+	if (!existsSync(featureDir)) {
+		return {
+			ok: false,
+			error: `Feature directory does not exist: ${featureDir}`,
+		};
+	}
+
+	const id = basename(featureDir);
+	const planContent = readOptionalFile(join(featureDir, "plan.md"));
+	const specContent = readOptionalFile(join(featureDir, "spec.md"));
+	const tasksContent = readOptionalFile(join(featureDir, "tasks.md"));
+
+	// Extract title from plan or spec
+	let title = "";
+	if (planContent) {
+		title = extractTitle(planContent);
+	} else if (specContent) {
+		title = extractTitle(specContent);
+	}
+
+	// Extract tasks from tasks.md or plan.md
+	let tasks: TaskItem[] = [];
+	if (tasksContent) {
+		tasks = extractTasks(tasksContent);
+	} else if (planContent) {
+		tasks = extractTasks(planContent);
+	}
+
+	// Extract spec assertions and scope
+	const specAssertions = specContent ? extractSpecAssertions(specContent) : [];
+	const scope = specContent ? extractScope(specContent) : "";
+
+	return {
+		ok: true,
+		value: {
+			id,
+			title,
+			scope,
+			specQualityScore: 0,
+			specAssertions,
+			tasks,
+			entitiesModified: [],
+			decisionsCreated: [],
+			branch: "",
+			prNumber: null,
+			merged: false,
+		},
+	};
+}
+
+export function extractFeatures(
+	featuresDir: string,
+): Result<ExtractedFeature[]> {
+	if (!existsSync(featuresDir)) {
+		return {
+			ok: false,
+			error: `Features directory does not exist: ${featuresDir}`,
+		};
+	}
+
+	const entries = readdirSync(featuresDir);
+	const features: ExtractedFeature[] = [];
+
+	for (const entry of entries) {
+		const entryPath = join(featuresDir, entry);
+		try {
+			const stat = statSync(entryPath);
+			if (!stat.isDirectory()) continue;
+		} catch {
+			continue;
+		}
+
+		const result = extractSingleFeature(entryPath);
+		if (result.ok) {
+			features.push(result.value);
+		}
+	}
+
+	return { ok: true, value: features };
+}

package/src/wiki/extractors/workflow.ts

@@ -0,0 +1,112 @@
+/**
+ * Workflow Trace Extractor — parses .maina/workflow/current.md into
+ * structured ExtractedWorkflowTrace records.
+ *
+ * Workflow traces follow the rolling markdown format:
+ *   # Workflow: feature-name
+ *   ## step-name (ISO-timestamp)
+ *   Summary text.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Result } from "../../db/index";
+import type { ExtractedWorkflowTrace, WorkflowStep } from "../types";
+
+// ─── Parsing ─────────────────────────────────────────────────────────────
+
+/**
+ * Extract feature name from "# Workflow: feature-name" header.
+ */
+function extractFeatureId(firstLine: string): string {
+	const match = firstLine.match(/^#\s+Workflow:\s*(.+)/);
+	return match?.[1]?.trim() ?? "";
+}
+
+/**
+ * Parse workflow steps from markdown content.
+ * Each step is an H2 heading with optional ISO timestamp in parens.
+ */
+function parseSteps(content: string): WorkflowStep[] {
+	const steps: WorkflowStep[] = [];
+	const lines = content.split("\n");
+	let currentCommand = "";
+	let currentTimestamp = "";
+	const summaryLines: string[] = [];
+
+	function flushStep(): void {
+		if (currentCommand) {
+			steps.push({
+				command: currentCommand,
+				timestamp: currentTimestamp,
+				summary: summaryLines.join("\n").trim(),
+			});
+		}
+		summaryLines.length = 0;
+	}
+
+	for (const line of lines) {
+		// Match step headers like "## brainstorm (2026-04-07T10:00:00.000Z)"
+		const stepMatch = line.match(
+			/^##\s+(\S+)(?:\s+\((\d{4}-\d{2}-\d{2}T[^)]+)\))?/,
+		);
+		if (stepMatch) {
+			flushStep();
+			currentCommand = stepMatch[1] ?? "";
+			currentTimestamp = stepMatch[2] ?? "";
+			continue;
+		}
+
+		// Skip H1 header
+		if (line.startsWith("# ")) {
+			continue;
+		}
+
+		if (currentCommand) {
+			summaryLines.push(line);
+		}
+	}
+	flushStep();
+
+	return steps;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+export function extractWorkflowTrace(
+	mainaDir: string,
+): Result<ExtractedWorkflowTrace> {
+	const workflowPath = join(mainaDir, "workflow", "current.md");
+
+	if (!existsSync(workflowPath)) {
+		return {
+			ok: false,
+			error: `Workflow file does not exist: ${workflowPath}`,
+		};
+	}
+
+	let content: string;
+	try {
+		content = readFileSync(workflowPath, "utf-8");
+	} catch {
+		return {
+			ok: false,
+			error: `Failed to read workflow file: ${workflowPath}`,
+		};
+	}
+
+	const firstLine = content.split("\n")[0] ?? "";
+	const featureId = extractFeatureId(firstLine);
+	const steps = parseSteps(content);
+
+	return {
+		ok: true,
+		value: {
+			featureId,
+			steps,
+			wikiRefsRead: [],
+			wikiRefsWritten: [],
+			rlSignals: [],
+		},
+	};
+}