feat: add core graph algorithms

Implement traversal, analysis, and clustering algorithms:
- Traversal: BFS, DFS, bidirectional BFS, degree-prioritised expansion
- Analysis: connected components, SCC, topological sort, cycle detection
- Clustering: Louvain, Leiden, Infomap, label propagation
- Pathfinding: Dijkstra, mutual information, path ranking
- Decomposition: biconnected, k-core, core-periphery
- Extraction: ego networks, motifs, trusses, subgraphs
- Graph data structure with adapter pattern

Author: Mearman

src/algorithms/analysis/connected-components.ts

@@ -0,0 +1,74 @@
+import { type Graph } from "../graph/graph";
+import { type Component } from "../types/algorithm-results";
+import { type InvalidInputError } from "../types/errors";
+import { type Edge,type Node } from "../types/graph";
+import { Err as Error_,Ok, type Result } from "../types/result";
+
+/**
+ * Find all connected components in an undirected graph (or weakly connected components in directed graph).
+ *
+ * Uses DFS to traverse each component. For directed graphs, treats edges as undirected.
+ *
+ * Time Complexity: O(V + E)
+ * Space Complexity: O(V)
+ * @param graph - The graph to analyze
+ * @returns Result containing array of components
+ */
+export const connectedComponents = <N extends Node, E extends Edge = Edge>(graph: Graph<N, E>): Result<Component<N>[], InvalidInputError> => {
+	if (!graph) {
+		return Error_({
+			type: "invalid-input",
+			message: "Graph cannot be null or undefined",
+		});
+	}
+
+	const nodes = graph.getAllNodes();
+	const visited = new Set<string>();
+	const components: Component<N>[] = [];
+	let componentId = 0;
+
+	const dfs = (nodeId: string, componentNodes: N[]): void => {
+		visited.add(nodeId);
+
+		const node = graph.getNode(nodeId);
+		if (node.some) {
+			componentNodes.push(node.value);
+		}
+
+		// Get neighbors (treats directed graph as undirected for connectivity)
+		const neighborsResult = graph.getNeighbors(nodeId);
+		if (neighborsResult.ok) {
+			for (const neighborId of neighborsResult.value) {
+				if (!visited.has(neighborId)) {
+					dfs(neighborId, componentNodes);
+				}
+			}
+		}
+
+		// For directed graphs, also check reverse edges (incoming edges)
+		if (graph.isDirected()) {
+			const allEdges = graph.getAllEdges();
+			for (const edge of allEdges) {
+				if (edge.target === nodeId && !visited.has(edge.source)) {
+					dfs(edge.source, componentNodes);
+				}
+			}
+		}
+	};
+
+	// Find all components
+	for (const node of nodes) {
+		if (!visited.has(node.id)) {
+			const componentNodes: N[] = [];
+			dfs(node.id, componentNodes);
+
+			components.push({
+				id: componentId++,
+				nodes: componentNodes,
+				size: componentNodes.length,
+			});
+		}
+	}
+
+	return Ok(components);
+};

src/algorithms/analysis/cycle-detection.ts

@@ -0,0 +1,139 @@
+import { type Graph } from "../graph/graph";
+import { type CycleInfo } from "../types/algorithm-results";
+import { type InvalidInputError } from "../types/errors";
+import { type Edge,type Node } from "../types/graph";
+import { None,type Option, Some } from "../types/option";
+import { Err as Error_,Ok, type Result } from "../types/result";
+
+/**
+ * Detect cycles in a graph using DFS.
+ *
+ * For directed graphs: detects back edges (edges to ancestors in DFS tree)
+ * For undirected graphs: detects any edge except parent edge
+ *
+ * Time Complexity: O(V + E)
+ * Space Complexity: O(V)
+ * @param graph - The graph to check for cycles
+ * @returns Result containing Option with cycle info if found
+ */
+export const detectCycle = <N extends Node, E extends Edge>(graph: Graph<N, E>): Result<Option<CycleInfo<N, E>>, InvalidInputError> => {
+	if (!graph) {
+		return Error_({
+			type: "invalid-input",
+			message: "Graph cannot be null or undefined",
+		});
+	}
+
+	const nodes = graph.getAllNodes();
+	const visited = new Set<string>();
+	const inStack = new Set<string>();
+	const parent = new Map<string, string | null>();
+
+	const dfsDirected = (nodeId: string): Option<CycleInfo<N, E>> => {
+		visited.add(nodeId);
+		inStack.add(nodeId);
+
+		const neighborsResult = graph.getNeighbors(nodeId);
+		if (neighborsResult.ok) {
+			for (const neighborId of neighborsResult.value) {
+				if (inStack.has(neighborId)) {
+					// Back edge - cycle found!
+					return reconstructCycle(nodeId, neighborId);
+				}
+
+				if (!visited.has(neighborId)) {
+					parent.set(neighborId, nodeId);
+					const cycleResult = dfsDirected(neighborId);
+					if (cycleResult.some) {
+						return cycleResult;
+					}
+				}
+			}
+		}
+
+		inStack.delete(nodeId);
+		return None();
+	};
+
+	const dfsUndirected = (nodeId: string, parentId: string | null): Option<CycleInfo<N, E>> => {
+		visited.add(nodeId);
+
+		const neighborsResult = graph.getNeighbors(nodeId);
+		if (neighborsResult.ok) {
+			for (const neighborId of neighborsResult.value) {
+				if (!visited.has(neighborId)) {
+					parent.set(neighborId, nodeId);
+					const cycleResult = dfsUndirected(neighborId, nodeId);
+					if (cycleResult.some) {
+						return cycleResult;
+					}
+				} else if (neighborId !== parentId) {
+					// Back edge (not to parent) - cycle found!
+					return reconstructCycle(nodeId, neighborId);
+				}
+			}
+		}
+
+		return None();
+	};
+
+	const reconstructCycle = (fromId: string, toId: string): Option<CycleInfo<N, E>> => {
+		const cycleNodes: N[] = [];
+		const cycleEdges: E[] = [];
+
+		// Build path from 'from' back to 'to'
+		let current = fromId;
+		const path: string[] = [current];
+
+		// Trace back through parents until we find 'to'
+		while (current !== toId && parent.has(current)) {
+			const parentId = parent.get(current);
+			if (parentId) {
+				path.unshift(parentId);
+				current = parentId;
+			} else {
+				break;
+			}
+		}
+
+		// Add closing edge
+		path.push(toId);
+
+		// Convert to nodes and edges
+		for (let index = 0; index < path.length; index++) {
+			const node = graph.getNode(path[index]);
+			if (node.some) {
+				cycleNodes.push(node.value);
+			}
+
+			if (index < path.length - 1) {
+				const edges = graph.getOutgoingEdges(path[index]);
+				if (edges.ok) {
+					const edge = edges.value.find(e => e.target === path[index + 1]);
+					if (edge) {
+						cycleEdges.push(edge);
+					}
+				}
+			}
+		}
+
+		return Some({ nodes: cycleNodes, edges: cycleEdges });
+	};
+
+	// Run DFS from all unvisited nodes
+	for (const node of nodes) {
+		if (!visited.has(node.id)) {
+			parent.set(node.id, null);
+
+			const cycleResult = graph.isDirected()
+				? dfsDirected(node.id)
+				: dfsUndirected(node.id, null);
+
+			if (cycleResult.some) {
+				return Ok(cycleResult);
+			}
+		}
+	}
+
+	return Ok(None());
+};

src/algorithms/analysis/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Automatically generated by barrelsby.
+ */
+
+export * from "./connected-components";
+export * from "./cycle-detection";
+export * from "./scc";
+export * from "./topological-sort";

src/algorithms/analysis/scc.ts

@@ -0,0 +1,99 @@
+import { type Graph } from "../graph/graph";
+import { type Component } from "../types/algorithm-results";
+import { type InvalidInputError } from "../types/errors";
+import { type Edge,type Node } from "../types/graph";
+import { Err as Error_,Ok, type Result } from "../types/result";
+
+/**
+ * Find all strongly connected components using Tarjan's algorithm.
+ *
+ * A strongly connected component (SCC) is a maximal set of vertices where
+ * every vertex is reachable from every other vertex in the set.
+ *
+ * Time Complexity: O(V + E)
+ * Space Complexity: O(V)
+ * @param graph - The directed graph to analyze
+ * @returns Result containing array of SCCs
+ */
+export const stronglyConnectedComponents = <N extends Node, E extends Edge = Edge>(graph: Graph<N, E>): Result<Component<N>[], InvalidInputError> => {
+	if (!graph) {
+		return Error_({
+			type: "invalid-input",
+			message: "Graph cannot be null or undefined",
+		});
+	}
+
+	const nodes = graph.getAllNodes();
+	const index = new Map<string, number>();
+	const lowlink = new Map<string, number>();
+	const onStack = new Set<string>();
+	const stack: string[] = [];
+	const components: Component<N>[] = [];
+	let currentIndex = 0;
+	let componentId = 0;
+
+	const strongConnect = (nodeId: string): void => {
+		// Set depth index for node
+		index.set(nodeId, currentIndex);
+		lowlink.set(nodeId, currentIndex);
+		currentIndex++;
+		stack.push(nodeId);
+		onStack.add(nodeId);
+
+		// Consider successors
+		const neighborsResult = graph.getNeighbors(nodeId);
+		if (neighborsResult.ok) {
+			for (const neighborId of neighborsResult.value) {
+				if (!index.has(neighborId)) {
+					// Successor not yet visited; recurse
+					strongConnect(neighborId);
+					const nodeLowlink = lowlink.get(nodeId);
+					const neighborLowlink = lowlink.get(neighborId);
+					if (nodeLowlink !== undefined && neighborLowlink !== undefined) {
+						lowlink.set(nodeId, Math.min(nodeLowlink, neighborLowlink));
+					}
+				} else if (onStack.has(neighborId)) {
+					// Successor is on stack and hence in current SCC
+					const nodeLowlink = lowlink.get(nodeId);
+					const neighborIndex = index.get(neighborId);
+					if (nodeLowlink !== undefined && neighborIndex !== undefined) {
+						lowlink.set(nodeId, Math.min(nodeLowlink, neighborIndex));
+					}
+				}
+			}
+		}
+
+		// If nodeId is a root node, pop the stack and create SCC
+		if (lowlink.get(nodeId) === index.get(nodeId)) {
+			const sccNodes: N[] = [];
+			let w: string;
+
+			do {
+				const popped = stack.pop();
+				if (popped === undefined) break;
+				w = popped;
+				onStack.delete(w);
+
+				const node = graph.getNode(w);
+				if (node.some) {
+					sccNodes.push(node.value);
+				}
+			} while (w !== nodeId);
+
+			components.push({
+				id: componentId++,
+				nodes: sccNodes,
+				size: sccNodes.length,
+			});
+		}
+	};
+
+	// Run Tarjan's algorithm from all unvisited nodes
+	for (const node of nodes) {
+		if (!index.has(node.id)) {
+			strongConnect(node.id);
+		}
+	}
+
+	return Ok(components);
+};