@mainahq/core 1.0.3 → 1.1.1

package/src/wiki/graph.ts

@@ -0,0 +1,445 @@
+/**
+ * Knowledge Graph — unified graph with 11 edge types for wiki compilation.
+ *
+ * Builds a graph from code entities, features, decisions, and workflow traces.
+ * Supports PageRank computation and mapping graph nodes to wiki article paths.
+ */
+
+import type { CodeEntity } from "./extractors/code";
+import type {
+	EdgeType,
+	ExtractedDecision,
+	ExtractedFeature,
+	ExtractedWorkflowTrace,
+} from "./types";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface GraphNode {
+	id: string;
+	type: "entity" | "module" | "feature" | "decision" | "workflow";
+	label: string;
+	file?: string;
+	pageRank: number;
+}
+
+export interface GraphEdge {
+	source: string;
+	target: string;
+	type: EdgeType;
+	weight: number;
+}
+
+export interface KnowledgeGraph {
+	nodes: Map<string, GraphNode>;
+	edges: GraphEdge[];
+	adjacency: Map<string, Set<string>>;
+}
+
+// ─── Graph Construction ─────────────────────────────────────────────────
+
+function addNode(graph: KnowledgeGraph, node: GraphNode): void {
+	if (!graph.nodes.has(node.id)) {
+		graph.nodes.set(node.id, node);
+	}
+	if (!graph.adjacency.has(node.id)) {
+		graph.adjacency.set(node.id, new Set<string>());
+	}
+}
+
+function addEdge(graph: KnowledgeGraph, edge: GraphEdge): void {
+	graph.edges.push(edge);
+
+	// Ensure both nodes are in adjacency
+	if (!graph.adjacency.has(edge.source)) {
+		graph.adjacency.set(edge.source, new Set<string>());
+	}
+	if (!graph.adjacency.has(edge.target)) {
+		graph.adjacency.set(edge.target, new Set<string>());
+	}
+
+	graph.adjacency.get(edge.source)?.add(edge.target);
+	graph.adjacency.get(edge.target)?.add(edge.source);
+}
+
+/**
+ * Derive a module name from a file path.
+ * "packages/core/src/wiki/state.ts" -> "wiki"
+ * "src/auth/jwt.ts" -> "auth"
+ */
+function deriveModule(file: string): string {
+	const parts = file.replace(/\\/g, "/").split("/");
+	// Find the directory containing the file
+	if (parts.length >= 2) {
+		return parts[parts.length - 2] ?? "root";
+	}
+	return "root";
+}
+
+function addCodeEntities(graph: KnowledgeGraph, entities: CodeEntity[]): void {
+	// Group entities by module (directory)
+	const moduleEntities = new Map<string, CodeEntity[]>();
+
+	for (const entity of entities) {
+		const moduleName = deriveModule(entity.file);
+
+		// Add entity node
+		const entityId = `entity:${entity.name}`;
+		addNode(graph, {
+			id: entityId,
+			type: "entity",
+			label: entity.name,
+			file: entity.file,
+			pageRank: 0,
+		});
+
+		// Track module membership
+		const list = moduleEntities.get(moduleName) ?? [];
+		list.push(entity);
+		moduleEntities.set(moduleName, list);
+	}
+
+	// Create module nodes and member_of edges
+	for (const [moduleName, members] of moduleEntities) {
+		const moduleId = `module:${moduleName}`;
+		addNode(graph, {
+			id: moduleId,
+			type: "module",
+			label: moduleName,
+			pageRank: 0,
+		});
+
+		for (const member of members) {
+			addEdge(graph, {
+				source: `entity:${member.name}`,
+				target: moduleId,
+				type: "member_of",
+				weight: 1.0,
+			});
+		}
+
+		// Add imports edges between entities in the same file
+		// (simplified: entities from the same file reference each other)
+		const fileGroups = new Map<string, CodeEntity[]>();
+		for (const member of members) {
+			const fg = fileGroups.get(member.file) ?? [];
+			fg.push(member);
+			fileGroups.set(member.file, fg);
+		}
+
+		for (const fileEntities of fileGroups.values()) {
+			for (let i = 0; i < fileEntities.length; i++) {
+				for (let j = i + 1; j < fileEntities.length; j++) {
+					const a = fileEntities[i];
+					const b = fileEntities[j];
+					if (a && b) {
+						addEdge(graph, {
+							source: `entity:${a.name}`,
+							target: `entity:${b.name}`,
+							type: "references",
+							weight: 0.5,
+						});
+					}
+				}
+			}
+		}
+	}
+}
+
+function addFeatures(
+	graph: KnowledgeGraph,
+	features: ExtractedFeature[],
+): void {
+	for (const feature of features) {
+		const featureId = `feature:${feature.id}`;
+		addNode(graph, {
+			id: featureId,
+			type: "feature",
+			label: feature.title || feature.id,
+			pageRank: 0,
+		});
+
+		// Link to modified entities
+		for (const entityName of feature.entitiesModified) {
+			const entityId = `entity:${entityName}`;
+			if (graph.nodes.has(entityId)) {
+				addEdge(graph, {
+					source: entityId,
+					target: featureId,
+					type: "modified_by",
+					weight: 1.0,
+				});
+			}
+		}
+
+		// Link to created decisions
+		for (const decisionName of feature.decisionsCreated) {
+			const decisionId = `decision:${decisionName}`;
+			if (graph.nodes.has(decisionId)) {
+				addEdge(graph, {
+					source: featureId,
+					target: decisionId,
+					type: "motivated_by",
+					weight: 0.8,
+				});
+			}
+		}
+
+		// Spec assertions create specified_by edges
+		if (feature.specAssertions.length > 0) {
+			addEdge(graph, {
+				source: featureId,
+				target: featureId,
+				type: "specified_by",
+				weight: 0.3,
+			});
+		}
+	}
+}
+
+function addDecisions(
+	graph: KnowledgeGraph,
+	decisions: ExtractedDecision[],
+): void {
+	for (const decision of decisions) {
+		const decisionId = `decision:${decision.id}`;
+		addNode(graph, {
+			id: decisionId,
+			type: "decision",
+			label: decision.title || decision.id,
+			pageRank: 0,
+		});
+
+		// Link to entity mentions
+		for (const mention of decision.entityMentions) {
+			// Try to find the entity by matching the end of the path
+			for (const [nodeId, node] of graph.nodes) {
+				if (node.type === "entity" && node.file === mention) {
+					addEdge(graph, {
+						source: nodeId,
+						target: decisionId,
+						type: "decided_by",
+						weight: 0.8,
+					});
+				}
+			}
+		}
+
+		// Constitution alignment creates aligns_with edges
+		for (const alignment of decision.constitutionAlignment) {
+			if (alignment) {
+				addEdge(graph, {
+					source: decisionId,
+					target: decisionId,
+					type: "aligns_with",
+					weight: 0.2,
+				});
+			}
+		}
+
+		// If decision constrains entities, add constrains edges
+		if (decision.status === "accepted") {
+			for (const mention of decision.entityMentions) {
+				for (const [nodeId, node] of graph.nodes) {
+					if (node.type === "entity" && node.file === mention) {
+						addEdge(graph, {
+							source: decisionId,
+							target: nodeId,
+							type: "constrains",
+							weight: 0.6,
+						});
+					}
+				}
+			}
+		}
+	}
+}
+
+function addWorkflowTraces(
+	graph: KnowledgeGraph,
+	traces: ExtractedWorkflowTrace[],
+): void {
+	for (const trace of traces) {
+		if (!trace.featureId) continue;
+
+		const workflowId = `workflow:${trace.featureId}`;
+		addNode(graph, {
+			id: workflowId,
+			type: "workflow",
+			label: `Workflow: ${trace.featureId}`,
+			pageRank: 0,
+		});
+
+		// Link to the feature
+		const featureId = `feature:${trace.featureId}`;
+		if (graph.nodes.has(featureId)) {
+			addEdge(graph, {
+				source: workflowId,
+				target: featureId,
+				type: "references",
+				weight: 0.5,
+			});
+		}
+	}
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Build a unified knowledge graph from all extracted data.
+ */
+export function buildKnowledgeGraph(
+	entities: CodeEntity[],
+	features: ExtractedFeature[],
+	decisions: ExtractedDecision[],
+	traces: ExtractedWorkflowTrace[],
+): KnowledgeGraph {
+	const graph: KnowledgeGraph = {
+		nodes: new Map(),
+		edges: [],
+		adjacency: new Map(),
+	};
+
+	addCodeEntities(graph, entities);
+	addDecisions(graph, decisions);
+	addFeatures(graph, features);
+	addWorkflowTraces(graph, traces);
+
+	return graph;
+}
+
+/**
+ * Compute PageRank scores for all nodes in the graph.
+ * Uses iterative power method with damping factor 0.85.
+ */
+export function computePageRank(
+	graph: KnowledgeGraph,
+	iterations = 20,
+): Map<string, number> {
+	const nodeIds = [...graph.nodes.keys()];
+	const n = nodeIds.length;
+
+	if (n === 0) return new Map();
+
+	const damping = 0.85;
+	const scores = new Map<string, number>();
+
+	// Initialize with uniform distribution
+	for (const id of nodeIds) {
+		scores.set(id, 1 / n);
+	}
+
+	// Build outgoing edge map
+	const outgoing = new Map<string, string[]>();
+	for (const edge of graph.edges) {
+		const list = outgoing.get(edge.source) ?? [];
+		list.push(edge.target);
+		outgoing.set(edge.source, list);
+	}
+
+	// Iterative computation
+	for (let iter = 0; iter < iterations; iter++) {
+		const newScores = new Map<string, number>();
+
+		for (const id of nodeIds) {
+			newScores.set(id, (1 - damping) / n);
+		}
+
+		for (const id of nodeIds) {
+			const outs = outgoing.get(id) ?? [];
+			if (outs.length === 0) {
+				// Dangling node: distribute evenly
+				const share = (scores.get(id) ?? 0) / n;
+				for (const target of nodeIds) {
+					newScores.set(target, (newScores.get(target) ?? 0) + damping * share);
+				}
+			} else {
+				const share = (scores.get(id) ?? 0) / outs.length;
+				for (const target of outs) {
+					newScores.set(target, (newScores.get(target) ?? 0) + damping * share);
+				}
+			}
+		}
+
+		// Update scores
+		for (const [id, score] of newScores) {
+			scores.set(id, score);
+		}
+	}
+
+	// Update graph nodes with computed PageRank
+	for (const [id, score] of scores) {
+		const node = graph.nodes.get(id);
+		if (node) {
+			node.pageRank = score;
+		}
+	}
+
+	return scores;
+}
+
+/**
+ * Map graph nodes to wiki article paths based on PageRank and community assignment.
+ * - Top 20% PageRank entities -> wiki/entities/
+ * - Louvain clusters -> wiki/modules/
+ * - Features -> wiki/features/
+ * - Decisions -> wiki/decisions/
+ */
+export function mapToArticles(
+	graph: KnowledgeGraph,
+	communities: Map<number, string[]>,
+): Map<string, string> {
+	const articleMap = new Map<string, string>();
+
+	// Compute PageRank threshold for top 20%
+	const entityNodes = [...graph.nodes.entries()]
+		.filter(([, node]) => node.type === "entity")
+		.sort(([, a], [, b]) => b.pageRank - a.pageRank);
+
+	const top20Idx = Math.max(1, Math.ceil(entityNodes.length * 0.2));
+	const threshold =
+		entityNodes.length > 0
+			? (entityNodes[Math.min(top20Idx - 1, entityNodes.length - 1)]?.[1]
+					?.pageRank ?? 0)
+			: 0;
+
+	// Map top 20% entities
+	for (const [id, node] of entityNodes) {
+		if (node.pageRank >= threshold && threshold > 0) {
+			const safeName = node.label.replace(/[^a-zA-Z0-9_-]/g, "-");
+			articleMap.set(id, `wiki/entities/${safeName}.md`);
+		}
+	}
+
+	// Map Louvain clusters to module articles
+	for (const [commId, members] of communities) {
+		// Find a representative label for the community
+		const moduleNodes = members.filter(
+			(m) => graph.nodes.get(m)?.type === "module",
+		);
+		const label =
+			moduleNodes.length > 0
+				? (graph.nodes.get(moduleNodes[0] ?? "")?.label ?? `cluster-${commId}`)
+				: `cluster-${commId}`;
+		const safeName = label.replace(/[^a-zA-Z0-9_-]/g, "-");
+		articleMap.set(`community:${commId}`, `wiki/modules/${safeName}.md`);
+	}
+
+	// Map features
+	for (const [id, node] of graph.nodes) {
+		if (node.type === "feature") {
+			const safeName = node.label.replace(/[^a-zA-Z0-9_-]/g, "-");
+			articleMap.set(id, `wiki/features/${safeName}.md`);
+		}
+	}
+
+	// Map decisions
+	for (const [id, node] of graph.nodes) {
+		if (node.type === "decision") {
+			const safeName = node.label.replace(/[^a-zA-Z0-9_-]/g, "-");
+			articleMap.set(id, `wiki/decisions/${safeName}.md`);
+		}
+	}
+
+	return articleMap;
+}

package/src/wiki/hooks.ts

@@ -0,0 +1,49 @@
+/**
+ * Wiki Post-Commit Hook — triggers incremental compilation after commits.
+ *
+ * Runs silently in the background. Never breaks the commit flow —
+ * all errors are caught and swallowed.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { compile } from "./compiler";
+import { loadState } from "./state";
+
+/**
+ * Post-commit hook for wiki incremental compilation.
+ *
+ * Checks if the wiki has been initialized (has .state.json),
+ * then runs an incremental compile. Swallows all errors to
+ * never break the commit flow.
+ */
+export async function onPostCommit(
+	mainaDir: string,
+	repoRoot: string,
+): Promise<void> {
+	try {
+		const wikiDir = join(mainaDir, "wiki");
+
+		// Skip if wiki directory does not exist
+		if (!existsSync(wikiDir)) {
+			return;
+		}
+
+		// Skip if wiki has not been initialized (no .state.json)
+		const state = loadState(wikiDir);
+		if (!state) {
+			return;
+		}
+
+		// Run incremental compilation (not full)
+		await compile({
+			repoRoot,
+			mainaDir,
+			wikiDir,
+			full: false,
+			dryRun: false,
+		});
+	} catch {
+		// Swallow all errors — never break the commit flow
+	}
+}

package/src/wiki/indexer.ts

@@ -0,0 +1,105 @@
+/**
+ * Wiki Indexer — generates the index.md table of contents for the wiki.
+ *
+ * Groups articles by type, sorts by PageRank within each group,
+ * and includes freshness indicators based on last compilation time.
+ */
+
+import type { ArticleType, WikiArticle } from "./types";
+
+// ─── Freshness Indicators ───────────────────────────────────────────────
+
+/**
+ * Compute a freshness indicator based on how recently the article was compiled.
+ * Returns a symbol: fresh (< 1 day), recent (< 7 days), aging (< 30 days), stale (> 30 days).
+ */
+function freshnessIndicator(lastCompiled: string): string {
+	if (!lastCompiled) return "[stale]";
+
+	const compiled = new Date(lastCompiled).getTime();
+	const now = Date.now();
+	const daysAgo = (now - compiled) / (1000 * 60 * 60 * 24);
+
+	if (daysAgo < 1) return "[fresh]";
+	if (daysAgo < 7) return "[recent]";
+	if (daysAgo < 30) return "[aging]";
+	return "[stale]";
+}
+
+// ─── Type Labels ────────────────────────────────────────────────────────
+
+const TYPE_LABELS: Record<ArticleType, string> = {
+	architecture: "Architecture",
+	module: "Modules",
+	entity: "Entities",
+	feature: "Features",
+	decision: "Decisions",
+	raw: "Other",
+};
+
+const TYPE_ORDER: ArticleType[] = [
+	"architecture",
+	"module",
+	"entity",
+	"feature",
+	"decision",
+	"raw",
+];
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Generate the wiki index.md content.
+ * Groups articles by type, sorts by PageRank (descending) within each group,
+ * and includes freshness indicators.
+ */
+export function generateIndex(articles: WikiArticle[]): string {
+	const lines: string[] = [];
+
+	lines.push("# Wiki Index");
+	lines.push("");
+	lines.push(
+		`> Auto-generated index. ${articles.length} articles across ${countTypes(articles)} categories.`,
+	);
+	lines.push("");
+
+	// Group articles by type
+	const grouped = new Map<ArticleType, WikiArticle[]>();
+	for (const article of articles) {
+		const list = grouped.get(article.type) ?? [];
+		list.push(article);
+		grouped.set(article.type, list);
+	}
+
+	// Render each type section in defined order
+	for (const type of TYPE_ORDER) {
+		const group = grouped.get(type);
+		if (!group || group.length === 0) continue;
+
+		// Sort by PageRank descending
+		const sorted = [...group].sort((a, b) => b.pageRank - a.pageRank);
+
+		const label = TYPE_LABELS[type];
+		lines.push(`## ${label}`);
+		lines.push("");
+
+		for (const article of sorted) {
+			const freshness = freshnessIndicator(article.lastCompiled);
+			lines.push(`- [${article.title}](${article.path}) ${freshness}`);
+		}
+
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function countTypes(articles: WikiArticle[]): number {
+	const types = new Set<ArticleType>();
+	for (const article of articles) {
+		types.add(article.type);
+	}
+	return types.size;
+}

package/src/wiki/linker.ts

@@ -0,0 +1,117 @@
+/**
+ * Wiki Linker — generates forward links and backlinks between wiki articles.
+ *
+ * Traverses the knowledge graph edges and maps them to wiki article paths
+ * to produce bidirectional link maps used for wikilink injection.
+ */
+
+import type { KnowledgeGraph } from "./graph";
+import type { WikiLink } from "./types";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface LinkResult {
+	forwardLinks: Map<string, WikiLink[]>;
+	backlinks: Map<string, WikiLink[]>;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function addToLinkMap(
+	map: Map<string, WikiLink[]>,
+	key: string,
+	link: WikiLink,
+): void {
+	const list = map.get(key) ?? [];
+	list.push(link);
+	map.set(key, list);
+}
+
+/**
+ * Find the article path for a given node ID.
+ * Checks direct mapping first, then checks if the node belongs to a community.
+ */
+function resolveArticlePath(
+	nodeId: string,
+	articleMap: Map<string, string>,
+	graph: KnowledgeGraph,
+): string | null {
+	// Direct match
+	const direct = articleMap.get(nodeId);
+	if (direct) return direct;
+
+	// Check if the node is part of a community that has an article
+	for (const [key, path] of articleMap) {
+		if (key.startsWith("community:")) {
+			// This is a module article — check if the node is in this community's adjacency
+			const node = graph.nodes.get(nodeId);
+			if (node?.type === "module") {
+				const moduleName = node.label;
+				if (path.includes(moduleName)) {
+					return path;
+				}
+			}
+		}
+	}
+
+	return null;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Generate forward links and backlinks between wiki articles based on graph edges.
+ *
+ * For each edge in the knowledge graph, if both source and target map to
+ * wiki articles, create a forward link from source article to target article
+ * and a backlink from target article to source article.
+ */
+export function generateLinks(
+	graph: KnowledgeGraph,
+	articleMap: Map<string, string>,
+): LinkResult {
+	const forwardLinks = new Map<string, WikiLink[]>();
+	const backlinks = new Map<string, WikiLink[]>();
+
+	for (const edge of graph.edges) {
+		const sourcePath = resolveArticlePath(edge.source, articleMap, graph);
+		const targetPath = resolveArticlePath(edge.target, articleMap, graph);
+
+		if (!sourcePath || !targetPath) continue;
+		if (sourcePath === targetPath) continue;
+
+		// Forward link: source -> target
+		addToLinkMap(forwardLinks, sourcePath, {
+			target: targetPath,
+			type: edge.type,
+			weight: edge.weight,
+		});
+
+		// Backlink: target -> source
+		addToLinkMap(backlinks, targetPath, {
+			target: sourcePath,
+			type: edge.type,
+			weight: edge.weight,
+		});
+	}
+
+	// Deduplicate links (same target + type = single link with max weight)
+	const dedup = (map: Map<string, WikiLink[]>): void => {
+		for (const [key, links] of map) {
+			const seen = new Map<string, WikiLink>();
+			for (const link of links) {
+				const dedupKey = `${link.target}:${link.type}`;
+				const existing = seen.get(dedupKey);
+				if (!existing || link.weight > existing.weight) {
+					seen.set(dedupKey, link);
+				}
+			}
+			map.set(key, [...seen.values()]);
+		}
+	};
+
+	dedup(forwardLinks);
+	dedup(backlinks);
+
+	return { forwardLinks, backlinks };
+}