@mainahq/core 1.0.3 → 1.1.1

package/src/wiki/louvain.ts

@@ -0,0 +1,190 @@
+/**
+ * Louvain Community Detection — identifies module boundaries in the knowledge graph.
+ *
+ * Implements the Louvain method for community detection:
+ * 1. Start each node in its own community
+ * 2. For each node, try moving to a neighbor's community if it improves modularity
+ * 3. Repeat until no improvement (convergence)
+ * 4. Return communities map + modularity score
+ *
+ * Deterministic: nodes are sorted before iteration. Handles disconnected components.
+ * Scales to 1000+ nodes in < 1 second.
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface LouvainNode {
+	id: string;
+	community: number;
+}
+
+export interface LouvainResult {
+	communities: Map<number, string[]>;
+	modularity: number;
+}
+
+// ─── Modularity Helpers ─────────────────────────────────────────────────
+
+/**
+ * Total number of edges (each undirected edge counted once).
+ */
+function totalEdges(adjacency: Map<string, Set<string>>): number {
+	let count = 0;
+	for (const neighbors of adjacency.values()) {
+		count += neighbors.size;
+	}
+	// Each edge is counted twice in an undirected adjacency list
+	return count / 2;
+}
+
+/**
+ * Compute modularity for the current community assignment.
+ * Q = (1/2m) * sum_ij [ A_ij - (k_i * k_j) / 2m ] * delta(c_i, c_j)
+ */
+function computeModularity(
+	adjacency: Map<string, Set<string>>,
+	communityOf: Map<string, number>,
+	m: number,
+): number {
+	if (m === 0) return 0;
+
+	let q = 0;
+	const twoM = 2 * m;
+
+	for (const [nodeI, neighbors] of adjacency) {
+		const ci = communityOf.get(nodeI) ?? -1;
+		const ki = neighbors.size;
+
+		for (const nodeJ of neighbors) {
+			const cj = communityOf.get(nodeJ) ?? -1;
+			if (ci !== cj) continue;
+
+			const kj = adjacency.get(nodeJ)?.size ?? 0;
+			// A_ij = 1 since nodeJ is in neighbors of nodeI
+			q += 1 - (ki * kj) / twoM;
+		}
+	}
+
+	return q / twoM;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Detect communities using the Louvain method.
+ * Input: adjacency list (node -> Set<neighbor>).
+ * Output: communities map (community ID -> node IDs) + modularity score.
+ *
+ * Optimized with pre-computed degree map and running community degree totals
+ * to avoid O(N) scan per modularity gain computation.
+ */
+export function detectCommunities(
+	adjacency: Map<string, Set<string>>,
+): LouvainResult {
+	const nodes = [...adjacency.keys()].sort();
+
+	if (nodes.length === 0) {
+		return { communities: new Map(), modularity: 0 };
+	}
+
+	const m = totalEdges(adjacency);
+
+	// Pre-compute degrees
+	const deg = new Map<string, number>();
+	for (const [node, neighbors] of adjacency) {
+		deg.set(node, neighbors.size);
+	}
+
+	// Phase 1: Assign each node to its own community
+	const communityOf = new Map<string, number>();
+	// Track sum of degrees per community for O(1) lookup
+	const commSumTot = new Map<number, number>();
+
+	for (let i = 0; i < nodes.length; i++) {
+		const node = nodes[i] ?? "";
+		communityOf.set(node, i);
+		commSumTot.set(i, deg.get(node) ?? 0);
+	}
+
+	// Phase 2: Iteratively move nodes to improve modularity
+	const maxIterations = 100;
+	for (let iter = 0; iter < maxIterations; iter++) {
+		let improved = false;
+
+		for (const nodeId of nodes) {
+			const currentComm = communityOf.get(nodeId) ?? 0;
+			const neighbors = adjacency.get(nodeId) ?? new Set<string>();
+			const ki = deg.get(nodeId) ?? 0;
+
+			if (ki === 0) continue;
+
+			// Find neighbor communities and count edges into each
+			const neighborCommEdges = new Map<number, number>();
+			for (const neighbor of neighbors) {
+				const nc = communityOf.get(neighbor) ?? -1;
+				neighborCommEdges.set(nc, (neighborCommEdges.get(nc) ?? 0) + 1);
+			}
+
+			// Current community edges (k_in for current)
+			const kInCurrent = neighborCommEdges.get(currentComm) ?? 0;
+			// sumTot for current community minus this node's own degree
+			const sumTotCurrent = (commSumTot.get(currentComm) ?? 0) - ki;
+
+			let bestGain = 0;
+			let bestComm = currentComm;
+
+			// Evaluate moving to each neighbor community
+			const candidateComms = [...neighborCommEdges.keys()]
+				.filter((c) => c !== currentComm)
+				.sort((a, b) => a - b);
+
+			for (const candidateComm of candidateComms) {
+				const kInCandidate = neighborCommEdges.get(candidateComm) ?? 0;
+				const sumTotCandidate = commSumTot.get(candidateComm) ?? 0;
+
+				// delta_Q = [k_in_new / m - ki * sumTot_new / (2m^2)]
+				//         - [k_in_old / m - ki * sumTot_old / (2m^2)]
+				const gainNew = kInCandidate / m - (ki * sumTotCandidate) / (2 * m * m);
+				const lossCurrent = kInCurrent / m - (ki * sumTotCurrent) / (2 * m * m);
+				const netGain = gainNew - lossCurrent;
+
+				if (netGain > bestGain) {
+					bestGain = netGain;
+					bestComm = candidateComm;
+				}
+			}
+
+			if (bestComm !== currentComm) {
+				// Update community assignment and running totals
+				commSumTot.set(currentComm, (commSumTot.get(currentComm) ?? 0) - ki);
+				commSumTot.set(bestComm, (commSumTot.get(bestComm) ?? 0) + ki);
+				communityOf.set(nodeId, bestComm);
+				improved = true;
+			}
+		}
+
+		if (!improved) break;
+	}
+
+	// Phase 3: Build communities map, renumbering to be contiguous
+	const rawCommunities = new Map<number, string[]>();
+	for (const [node, comm] of communityOf) {
+		const list = rawCommunities.get(comm) ?? [];
+		list.push(node);
+		rawCommunities.set(comm, list);
+	}
+
+	// Renumber communities to 0..N-1
+	const communities = new Map<number, string[]>();
+	let idx = 0;
+	for (const [, members] of [...rawCommunities.entries()].sort(
+		([a], [b]) => a - b,
+	)) {
+		communities.set(idx, members.sort());
+		idx++;
+	}
+
+	const modularity = computeModularity(adjacency, communityOf, m);
+
+	return { communities, modularity };
+}

package/src/wiki/prompts/compile-architecture.md

@@ -0,0 +1,59 @@
+---
+task: compile-architecture
+tier: mechanical
+version: 1
+---
+
+# Architecture Article Compilation
+
+Given the following system overview:
+
+Modules:
+{module_list}
+
+Module dependency graph:
+{dependency_graph}
+
+Community clusters (Louvain):
+{communities}
+
+Key decisions:
+{key_decisions}
+
+Cross-cutting concerns:
+{cross_cutting}
+
+Generate an architecture article that:
+1. Provides a high-level overview of the system structure
+2. Describes the module dependency graph and layering
+3. Identifies community clusters and their purposes
+4. Lists key architectural decisions that shaped the system
+5. Notes cross-cutting concerns (error handling, logging, auth patterns)
+6. Highlights potential architectural risks or debt
+
+## Output Format
+
+```markdown
+# Architecture Overview
+
+## System Structure
+{high-level description of how the system is organized}
+
+## Module Map
+{list of modules with brief descriptions and layer assignments}
+
+## Dependency Graph
+{description of how modules depend on each other}
+
+## Community Clusters
+{groups of tightly-coupled modules with shared purpose}
+
+## Key Decisions
+{links to important architectural decisions}
+
+## Cross-Cutting Concerns
+{patterns that span multiple modules}
+
+## Risks
+{architectural debt or areas needing attention}
+```

package/src/wiki/prompts/compile-decision.md

@@ -0,0 +1,66 @@
+---
+task: compile-decision
+tier: mechanical
+version: 1
+---
+
+# Decision Article Compilation
+
+Given the following decision record:
+- ID: {decision_id}
+- Title: {decision_title}
+- Status: {status}
+
+Context:
+{context}
+
+Decision:
+{decision}
+
+Rationale:
+{rationale}
+
+Alternatives rejected:
+{alternatives_rejected}
+
+Entities affected:
+{entity_mentions}
+
+Constitution alignment:
+{constitution_alignment}
+
+Generate a decision article that:
+1. Clearly states the decision and its current status
+2. Explains the context that motivated the decision
+3. Documents the rationale with specific reasons
+4. Lists alternatives that were considered and why they were rejected
+5. Links to entities and modules affected by this decision
+6. Notes alignment with project constitution
+
+## Output Format
+
+```markdown
+# {decision_title}
+
+**Status:** {proposed|accepted|deprecated|superseded}
+**ID:** {decision_id}
+
+## Context
+{what problem or situation prompted this decision}
+
+## Decision
+{the actual decision made}
+
+## Rationale
+{why this decision was chosen over alternatives}
+
+## Alternatives Considered
+{list of rejected alternatives with reasons}
+
+## Impact
+- Entities affected: {links to entity articles}
+- Modules affected: {links to module articles}
+
+## Constitution Alignment
+{how this decision aligns with project principles}
+```

package/src/wiki/prompts/compile-entity.md

@@ -0,0 +1,56 @@
+---
+task: compile-entity
+tier: mechanical
+version: 1
+---
+
+# Entity Article Compilation
+
+Given the following entity definition:
+{entity_definition}
+
+Located in module `{module_name}` at `{file_path}:{line_number}`:
+{source_context}
+
+With the following lifecycle context:
+- Features that modified this entity: {features}
+- Decisions that affect this entity: {decisions}
+- Dependents (who uses this): {dependents}
+- Dependencies (what this uses): {dependencies}
+
+Generate an entity article that:
+1. Describes what the entity is and what it does
+2. Shows its type signature or interface
+3. Lists which features introduced or modified it
+4. References relevant architectural decisions
+5. Notes breaking change risk based on dependent count
+
+## Output Format
+
+```markdown
+# {entity_name}
+
+**Kind:** {function|class|interface|type|const|enum}
+**File:** `{file_path}:{line_number}`
+**Module:** [[modules/{module_name}.md]]
+
+## Description
+{what this entity does and why it exists}
+
+## Signature
+```typescript
+{type_signature_or_definition}
+```
+
+## Lifecycle
+- Introduced by: [[features/{feature}.md]]
+- Modified by: {list of feature links}
+- Governed by: {list of decision links}
+
+## Dependencies
+- Uses: {list of entity links}
+- Used by: {list of entity links}
+
+## Change Risk
+{low|medium|high} — {N} dependents
+```

package/src/wiki/prompts/compile-feature.md

@@ -0,0 +1,60 @@
+---
+task: compile-feature
+tier: mechanical
+version: 1
+---
+
+# Feature Article Compilation
+
+Given the following feature metadata:
+- ID: {feature_id}
+- Title: {feature_title}
+- Branch: {branch}
+- PR: {pr_number}
+- Merged: {merged}
+
+Spec quality score: {spec_quality_score}
+Spec assertions: {spec_assertions}
+
+Tasks:
+{task_list}
+
+Entities modified:
+{entities_modified}
+
+Decisions created:
+{decisions_created}
+
+Generate a feature history article that:
+1. Summarizes what the feature does
+2. Lists acceptance criteria from the spec
+3. Shows implementation progress (completed tasks vs total)
+4. Links to entities that were added or modified
+5. Links to decisions that were made during implementation
+6. Notes the branch and PR for traceability
+
+## Output Format
+
+```markdown
+# {feature_title}
+
+**Feature:** {feature_id}
+**Status:** {merged|in-progress|planned}
+**Branch:** `{branch}`
+**PR:** #{pr_number}
+
+## Summary
+{what this feature does and why}
+
+## Acceptance Criteria
+{list of spec assertions}
+
+## Implementation
+{task_list with completion status}
+
+## Entities Modified
+{links to entity articles}
+
+## Decisions
+{links to decision articles created during this feature}
+```

package/src/wiki/prompts/compile-module.md

@@ -0,0 +1,42 @@
+---
+task: compile-module
+tier: mechanical
+version: 1
+---
+
+# Module Article Compilation
+
+Given the following entities in module `{module_name}`:
+{entity_list}
+
+And the following dependency relationships:
+{dependencies}
+
+Generate a clear, concise module overview article that:
+1. Describes what this module does in 1-2 sentences
+2. Lists key entities grouped by purpose (exports, types, internal helpers)
+3. Shows dependency relationships as a list of imports/exports
+4. Notes which other modules depend on this one (consumers)
+5. Links to related features and decisions using [[path]] notation
+
+## Output Format
+
+```markdown
+# {module_name}
+
+{one_line_description}
+
+## Purpose
+{2-3 sentences explaining the module's role in the system}
+
+## Key Entities
+{grouped list of functions, types, classes with brief descriptions}
+
+## Dependencies
+- **Imports from:** {list of modules this depends on}
+- **Exported to:** {list of modules that import from this}
+
+## Related
+- Features: {links to feature articles}
+- Decisions: {links to decision articles}
+```

package/src/wiki/prompts/wiki-query.md

@@ -0,0 +1,25 @@
+---
+task: wiki-query
+tier: mechanical
+version: 1
+---
+
+# Wiki Query Synthesis
+
+You are answering a question about a codebase using wiki documentation.
+
+Question: {question}
+
+Here are relevant wiki articles:
+
+{articles}
+
+## Instructions
+
+1. Provide a clear, concise answer that directly addresses the question
+2. Cite relevant articles using [[article_path]] notation (e.g., [[modules/core.md]])
+3. If the articles don't contain enough information, say so explicitly
+4. Do NOT guess or hallucinate information not present in the articles
+5. If anything is ambiguous, use [NEEDS CLARIFICATION: specific question]
+6. Prioritize accuracy over completeness
+7. Keep the answer focused — avoid restating the entire article content