@graphty/algorithms 1.3.1 → 1.4.2

package/src/algorithms/traversal/dfs.ts

@@ -1,5 +1,5 @@
-import {Graph} from "../../core/graph.js";
-import type {NodeId, TraversalOptions, TraversalResult} from "../../types/index.js";
+import { Graph } from "../../core/graph.js";
+import type { NodeId, TraversalOptions, TraversalResult } from "../../types/index.js";
 
 /**
  * Depth-First Search (DFS) implementation
@@ -18,12 +18,12 @@ export interface DFSOptions extends TraversalOptions {
 
 /**
  * Perform depth-first search starting from a given node
+ * @param graph - The input graph to traverse
+ * @param startNode - The node to start the DFS from
+ * @param options - DFS options (recursive mode, pre/post order, etc.)
+ * @returns Traversal result with visited nodes, order, and tree structure
  */
-export function depthFirstSearch(
-    graph: Graph,
-    startNode: NodeId,
-    options: DFSOptions = {},
-): TraversalResult {
+export function depthFirstSearch(graph: Graph, startNode: NodeId, options: DFSOptions = {}): TraversalResult {
     if (!graph.hasNode(startNode)) {
         throw new Error(`Start node ${String(startNode)} not found in graph`);
     }
@@ -38,11 +38,17 @@ export function depthFirstSearch(
         dfsIterative(graph, startNode, visited, order, tree, options);
     }
 
-    return {visited, order, tree};
+    return { visited, order, tree };
 }
 
 /**
  * Iterative DFS implementation (safer for browsers)
+ * @param graph - The input graph to traverse
+ * @param startNode - The node to start the DFS from
+ * @param visited - Set to track visited nodes
+ * @param order - Array to store traversal order
+ * @param tree - Map to store parent relationships
+ * @param options - DFS options (recursive mode, pre/post order, etc.)
  */
 function dfsIterative(
     graph: Graph,
@@ -58,8 +64,8 @@ function dfsIterative(
         return;
     }
 
-    const stack: {node: NodeId, parent: NodeId | null, depth: number}[] = [];
-    stack.push({node: startNode, parent: null, depth: 0});
+    const stack: { node: NodeId; parent: NodeId | null; depth: number }[] = [];
+    stack.push({ node: startNode, parent: null, depth: 0 });
 
     while (stack.length > 0) {
         const current = stack.pop();
@@ -89,7 +95,7 @@ function dfsIterative(
             for (let i = neighbors.length - 1; i >= 0; i--) {
                 const neighbor = neighbors[i];
                 if (neighbor !== undefined && !visited.has(neighbor)) {
-                    stack.push({node: neighbor, parent: current.node, depth: current.depth + 1});
+                    stack.push({ node: neighbor, parent: current.node, depth: current.depth + 1 });
                 }
             }
         }
@@ -98,6 +104,14 @@ function dfsIterative(
 
 /**
  * Recursive DFS implementation
+ * @param graph - The input graph to traverse
+ * @param node - Current node being visited
+ * @param visited - Set to track visited nodes
+ * @param order - Array to store traversal order
+ * @param tree - Map to store parent relationships
+ * @param options - DFS options (recursive mode, pre/post order, etc.)
+ * @param depth - Current depth in the traversal tree
+ * @param parent - Parent node of the current node
  */
 function dfsRecursive(
     graph: Graph,
@@ -145,6 +159,8 @@ function dfsRecursive(
 
 /**
  * Detect cycles in a graph using DFS
+ * @param graph - The input graph to check for cycles
+ * @returns True if the graph contains a cycle, false otherwise
  */
 export function hasCycleDFS(graph: Graph): boolean {
     const visited = new Set<NodeId>();
@@ -170,13 +186,13 @@ export function hasCycleDFS(graph: Graph): boolean {
 
 /**
  * Utility function for cycle detection in directed graphs
+ * @param graph - The directed graph to check
+ * @param node - Current node being visited
+ * @param visited - Set of all visited nodes
+ * @param recursionStack - Set of nodes in the current recursion path
+ * @returns True if a cycle is found, false otherwise
  */
-function hasCycleUtilDirected(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    recursionStack: Set<NodeId>,
-): boolean {
+function hasCycleUtilDirected(graph: Graph, node: NodeId, visited: Set<NodeId>, recursionStack: Set<NodeId>): boolean {
     visited.add(node);
     recursionStack.add(node);
 
@@ -198,13 +214,13 @@ function hasCycleUtilDirected(
 
 /**
  * Utility function for cycle detection in undirected graphs
+ * @param graph - The undirected graph to check
+ * @param node - Current node being visited
+ * @param visited - Set of all visited nodes
+ * @param parent - Parent node of the current node
+ * @returns True if a cycle is found, false otherwise
  */
-function hasCycleUtilUndirected(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    parent: NodeId | null,
-): boolean {
+function hasCycleUtilUndirected(graph: Graph, node: NodeId, visited: Set<NodeId>, parent: NodeId | null): boolean {
     visited.add(node);
 
     // Check all neighbors
@@ -224,6 +240,8 @@ function hasCycleUtilUndirected(
 
 /**
  * Topological sorting using DFS (for directed acyclic graphs)
+ * @param graph - The directed acyclic graph to sort
+ * @returns Array of node IDs in topological order, or null if graph has cycles
  */
 export function topologicalSort(graph: Graph): NodeId[] | null {
     if (!graph.isDirected) {
@@ -251,13 +269,12 @@ export function topologicalSort(graph: Graph): NodeId[] | null {
 
 /**
  * Utility function for topological sorting
+ * @param graph - The directed graph being sorted
+ * @param node - Current node being visited
+ * @param visited - Set of visited nodes
+ * @param stack - Stack to store nodes in reverse topological order
  */
-function topologicalSortUtil(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    stack: NodeId[],
-): void {
+function topologicalSortUtil(graph: Graph, node: NodeId, visited: Set<NodeId>, stack: NodeId[]): void {
     visited.add(node);
 
     // Visit all neighbors first
@@ -273,6 +290,8 @@ function topologicalSortUtil(
 
 /**
  * Find strongly connected components using DFS (for directed graphs)
+ * @param graph - The directed graph to analyze
+ * @returns Array of strongly connected components (each is an array of node IDs)
  */
 export function findStronglyConnectedComponents(graph: Graph): NodeId[][] {
     if (!graph.isDirected) {
@@ -310,13 +329,12 @@ export function findStronglyConnectedComponents(graph: Graph): NodeId[][] {
 
 /**
  * DFS to record finish order
+ * @param graph - The graph being traversed
+ * @param node - Current node being visited
+ * @param visited - Set of visited nodes
+ * @param finishOrder - Array to store nodes in order of completion
  */
-function dfsFinishOrder(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    finishOrder: NodeId[],
-): void {
+function dfsFinishOrder(graph: Graph, node: NodeId, visited: Set<NodeId>, finishOrder: NodeId[]): void {
     visited.add(node);
 
     for (const neighbor of Array.from(graph.neighbors(node))) {
@@ -330,13 +348,12 @@ function dfsFinishOrder(
 
 /**
  * DFS to collect nodes in a component
+ * @param graph - The graph being traversed
+ * @param node - Current node being visited
+ * @param visited - Set of visited nodes
+ * @param component - Array to collect nodes in the current component
  */
-function dfsCollectComponent(
-    graph: Graph,
-    node: NodeId,
-    visited: Set<NodeId>,
-    component: NodeId[],
-): void {
+function dfsCollectComponent(graph: Graph, node: NodeId, visited: Set<NodeId>, component: NodeId[]): void {
     visited.add(node);
     component.push(node);
 
@@ -349,9 +366,11 @@ function dfsCollectComponent(
 
 /**
  * Create transpose (reverse) of a directed graph
+ * @param graph - The directed graph to transpose
+ * @returns A new graph with all edges reversed
  */
 function createTransposeGraph(graph: Graph): Graph {
-    const transpose = new Graph({directed: true});
+    const transpose = new Graph({ directed: true });
 
     // Add all nodes
     for (const node of Array.from(graph.nodes())) {

package/src/algorithms/traversal/index.ts

@@ -2,6 +2,6 @@
  * Graph traversal algorithms
  */
 
-export {breadthFirstSearch, isBipartite, shortestPathBFS, singleSourceShortestPathBFS} from "./bfs.js";
-export type {DFSOptions} from "./dfs.js";
-export {depthFirstSearch, findStronglyConnectedComponents, hasCycleDFS, topologicalSort} from "./dfs.js";
+export { breadthFirstSearch, isBipartite, shortestPathBFS, singleSourceShortestPathBFS } from "./bfs.js";
+export type { DFSOptions } from "./dfs.js";
+export { depthFirstSearch, findStronglyConnectedComponents, hasCycleDFS, topologicalSort } from "./dfs.js";

package/src/benchmark-all-algorithms.ts

@@ -8,7 +8,7 @@
  */
 
 import * as algorithms from "./algorithms/index.js";
-import {Graph} from "./core/graph.js";
+import { Graph } from "./core/graph.js";
 
 interface BenchmarkResult {
     algorithm: string;
@@ -35,8 +35,8 @@ const ALGORITHM_CATEGORIES = {
         ],
         config: {
             name: "Traversal",
-            quick: {nodes: 1000, edges: 5000, runs: 3},
-            full: {nodes: 10000, edges: 50000, runs: 10},
+            quick: { nodes: 1000, edges: 5000, runs: 3 },
+            full: { nodes: 10000, edges: 50000, runs: 10 },
         },
     },
     shortestPath: {
@@ -54,8 +54,8 @@ const ALGORITHM_CATEGORIES = {
         ],
         config: {
             name: "Shortest Path",
-            quick: {nodes: 100, edges: 500, runs: 1}, // Smaller for O(V³) algorithms
-            full: {nodes: 500, edges: 2500, runs: 3},
+            quick: { nodes: 100, edges: 500, runs: 1 }, // Smaller for O(V³) algorithms
+            full: { nodes: 500, edges: 2500, runs: 3 },
         },
     },
     centrality: {
@@ -71,8 +71,8 @@ const ALGORITHM_CATEGORIES = {
         ],
         config: {
             name: "Centrality",
-            quick: {nodes: 500, edges: 2500, runs: 1},
-            full: {nodes: 2000, edges: 10000, runs: 3},
+            quick: { nodes: 500, edges: 2500, runs: 1 },
+            full: { nodes: 2000, edges: 10000, runs: 3 },
         },
     },
     components: {
@@ -90,44 +90,48 @@ const ALGORITHM_CATEGORIES = {
         ],
         config: {
             name: "Components",
-            quick: {nodes: 2000, edges: 10000, runs: 3},
-            full: {nodes: 10000, edges: 50000, runs: 10},
+            quick: { nodes: 2000, edges: 10000, runs: 3 },
+            full: { nodes: 10000, edges: 50000, runs: 10 },
         },
     },
     mst: {
         algorithms: ["kruskalMST", "primMST", "minimumSpanningTree"],
         config: {
             name: "Minimum Spanning Tree",
-            quick: {nodes: 1000, edges: 5000, runs: 5},
-            full: {nodes: 5000, edges: 25000, runs: 10},
+            quick: { nodes: 1000, edges: 5000, runs: 5 },
+            full: { nodes: 5000, edges: 25000, runs: 10 },
         },
     },
     community: {
         algorithms: ["girvanNewman", "labelPropagation", "leiden", "louvain"],
         config: {
             name: "Community Detection",
-            quick: {nodes: 200, edges: 1000, runs: 1}, // Very expensive algorithms
-            full: {nodes: 1000, edges: 5000, runs: 2},
+            quick: { nodes: 200, edges: 1000, runs: 1 }, // Very expensive algorithms
+            full: { nodes: 1000, edges: 5000, runs: 2 },
         },
     },
     matching: {
         algorithms: ["bipartitePartition", "greedyBipartiteMatching", "maximumBipartiteMatching"],
         config: {
             name: "Matching",
-            quick: {nodes: 500, edges: 1000, runs: 3},
-            full: {nodes: 2000, edges: 4000, runs: 5},
+            quick: { nodes: 500, edges: 1000, runs: 3 },
+            full: { nodes: 2000, edges: 4000, runs: 5 },
         },
     },
 } as const;
 
 /**
  * Main benchmark runner
+ * @param mode - The benchmark mode: "quick" for fast tests or "full" for comprehensive tests
+ * @returns Array of benchmark results for all tested algorithms
  */
 export function runAllAlgorithmsBenchmark(mode: "quick" | "full" = "full"): BenchmarkResult[] {
     const startTime = Date.now();
     const timeLimit = mode === "quick" ? 2 * 60 * 1000 : 60 * 60 * 1000; // 2 min or 1 hour
 
-    console.log(`🚀 ${mode === "quick" ? "Quick" : "Comprehensive"} Benchmark - All ${String(getTotalAlgorithmCount())} Algorithms`);
+    console.log(
+        `🚀 ${mode === "quick" ? "Quick" : "Comprehensive"} Benchmark - All ${String(getTotalAlgorithmCount())} Algorithms`,
+    );
     console.log(`=${"=".repeat(60)}`);
     console.log(`Time limit: ${mode === "quick" ? "2 minutes" : "1 hour"}`);
     console.log(`Start time: ${new Date().toLocaleTimeString()}\n`);
@@ -175,7 +179,9 @@ export function runAllAlgorithmsBenchmark(mode: "quick" | "full" = "full"): Benc
     console.log("===================");
     console.log(`Total time: ${totalTime.toFixed(1)}s`);
     console.log(`Algorithms tested: ${String(totalTested)}`);
-    console.log(`Success rate: ${String(totalPassed)}/${String(totalTested)} (${(totalPassed / totalTested * 100).toFixed(1)}%)`);
+    console.log(
+        `Success rate: ${String(totalPassed)}/${String(totalTested)} (${((totalPassed / totalTested) * 100).toFixed(1)}%)`,
+    );
 
     if (mode === "full") {
         displayDetailedResults(results);
@@ -186,6 +192,12 @@ export function runAllAlgorithmsBenchmark(mode: "quick" | "full" = "full"): Benc
 
 /**
  * Benchmark a single algorithm
+ * @param algoName - The name of the algorithm to benchmark
+ * @param category - The category the algorithm belongs to
+ * @param graph - The test graph to run the algorithm on
+ * @param runs - Number of times to run the algorithm for averaging
+ * @param mode - The benchmark mode (quick or full)
+ * @returns The benchmark result containing timing and success information
  */
 function benchmarkAlgorithm(
     algoName: string,
@@ -216,7 +228,7 @@ function benchmarkAlgorithm(
             const args = getAlgorithmArgs(algoName, graph);
             const start = performance.now();
 
-            (algo as (... args: unknown[]) => unknown)(... args);
+            (algo as (...args: unknown[]) => unknown)(...args);
 
             const time = performance.now() - start;
             times.push(time);
@@ -251,6 +263,9 @@ function benchmarkAlgorithm(
 
 /**
  * Get appropriate arguments for each algorithm
+ * @param algoName - The name of the algorithm to get arguments for
+ * @param graph - The base graph to use for generating arguments
+ * @returns Array of arguments to pass to the algorithm function
  */
 function getAlgorithmArgs(algoName: string, graph: Graph): unknown[] {
     // Get random nodes for algorithms that need them
@@ -326,6 +341,10 @@ function getAlgorithmArgs(algoName: string, graph: Graph): unknown[] {
 
 /**
  * Create test graph appropriate for each algorithm category
+ * @param nodes - Number of nodes in the test graph
+ * @param edges - Target number of edges in the test graph
+ * @param category - The algorithm category to optimize the graph structure for
+ * @returns A new test graph with the specified structure
  */
 function createTestGraph(nodes: number, edges: number, category: string): Graph {
     const graph = new Graph();
@@ -362,6 +381,8 @@ function createTestGraph(nodes: number, edges: number, category: string): Graph
 
 /**
  * Create a connected random graph
+ * @param graph - The graph to add edges to
+ * @param targetEdges - Target number of edges to create
  */
 function createConnectedGraph(graph: Graph, targetEdges: number): void {
     const nodes = graph.nodeCount;
@@ -387,6 +408,8 @@ function createConnectedGraph(graph: Graph, targetEdges: number): void {
 
 /**
  * Create small-world graph (Watts-Strogatz model)
+ * @param graph - The graph to add edges to
+ * @param avgDegree - Target average degree for each node
  */
 function createSmallWorldGraph(graph: Graph, avgDegree: number): void {
     const nodes = graph.nodeCount;
@@ -418,6 +441,8 @@ function createSmallWorldGraph(graph: Graph, avgDegree: number): void {
 
 /**
  * Create graph with community structure
+ * @param graph - The graph to add edges to
+ * @param targetEdges - Target number of edges to create
  */
 function createCommunityGraph(graph: Graph, targetEdges: number): void {
     const nodes = graph.nodeCount;
@@ -433,7 +458,8 @@ function createCommunityGraph(graph: Graph, targetEdges: number): void {
 
         for (let i = start; i < end && edgesAdded < targetEdges; i++) {
             for (let j = i + 1; j < end && edgesAdded < targetEdges; j++) {
-                if (Math.random() < 0.8) { // High probability within community
+                if (Math.random() < 0.8) {
+                    // High probability within community
                     graph.addEdge(i, j);
                     edgesAdded++;
                 }
@@ -455,9 +481,11 @@ function createCommunityGraph(graph: Graph, targetEdges: number): void {
 
 /**
  * Create directed version of graph
+ * @param undirectedGraph - The undirected graph to convert
+ * @returns A new directed graph with the same nodes and edges
  */
 function createDirectedGraph(undirectedGraph: Graph): Graph {
-    const directedGraph = new Graph({directed: true});
+    const directedGraph = new Graph({ directed: true });
 
     // Copy nodes
     for (const node of undirectedGraph.nodes()) {
@@ -474,6 +502,8 @@ function createDirectedGraph(undirectedGraph: Graph): Graph {
 
 /**
  * Create bipartite graph
+ * @param nodesPerPartition - Number of nodes in each partition
+ * @returns A new bipartite graph with sparse connections between partitions
  */
 function createBipartiteGraph(nodesPerPartition: number): Graph {
     const graph = new Graph();
@@ -486,7 +516,8 @@ function createBipartiteGraph(nodesPerPartition: number): Graph {
     // Add edges only between partitions
     for (let i = 0; i < nodesPerPartition; i++) {
         for (let j = nodesPerPartition; j < nodesPerPartition * 2; j++) {
-            if (Math.random() < 0.3) { // Sparse bipartite graph
+            if (Math.random() < 0.3) {
+                // Sparse bipartite graph
                 graph.addEdge(i, j);
             }
         }
@@ -497,14 +528,15 @@ function createBipartiteGraph(nodesPerPartition: number): Graph {
 
 /**
  * Get total algorithm count
+ * @returns The total number of algorithms across all categories
  */
 function getTotalAlgorithmCount(): number {
-    return Object.values(ALGORITHM_CATEGORIES).reduce((total, category) =>
-        total + category.algorithms.length, 0);
+    return Object.values(ALGORITHM_CATEGORIES).reduce((total, category) => total + category.algorithms.length, 0);
 }
 
 /**
  * Display detailed results for full benchmark
+ * @param results - Array of benchmark results to display
  */
 function displayDetailedResults(results: BenchmarkResult[]): void {
     console.log("\n📊 Detailed Results");
@@ -530,8 +562,8 @@ function displayDetailedResults(results: BenchmarkResult[]): void {
         if (successful.length > 0) {
             const avgTime = successful.reduce((sum, r) => sum + r.executionTime, 0) / successful.length;
             console.log(`  Average time: ${avgTime.toFixed(2)}ms`);
-            const minTime = Math.min(... successful.map((r) => r.executionTime));
-            const maxTime = Math.max(... successful.map((r) => r.executionTime));
+            const minTime = Math.min(...successful.map((r) => r.executionTime));
+            const maxTime = Math.max(...successful.map((r) => r.executionTime));
             console.log(`  Range: ${minTime.toFixed(2)}ms - ${maxTime.toFixed(2)}ms`);
         }
 

package/src/clustering/hierarchical.ts

@@ -6,10 +6,12 @@
  * structure in graphs.
  */
 
-import type {Graph} from "../core/graph.js";
+import type { Graph } from "../core/graph.js";
 
 /**
  * Convert Graph to adjacency set representation for clustering
+ * @param graph - The input graph to convert
+ * @returns Map of node IDs to sets of neighbor node IDs
  */
 function graphToAdjacencySet(graph: Graph): Map<string, Set<string>> {
     const adjacency = new Map<string, Set<string>>();
@@ -62,11 +64,10 @@ export type LinkageMethod = "single" | "complete" | "average" | "ward";
 
 /**
  * Compute distance between two nodes based on graph structure
+ * @param graph - Adjacency map representation of the graph
+ * @param distances - Map to store computed distances between nodes
  */
-function computeGraphDistance<T>(
-    graph: Map<T, Set<T>>,
-    distances: Map<T, Map<T, number>>,
-): void {
+function computeGraphDistance<T>(graph: Map<T, Set<T>>, distances: Map<T, Map<T, number>>): void {
     // Use BFS to compute shortest path distances
     for (const start of graph.keys()) {
         const dist = new Map<T, number>();
@@ -97,6 +98,11 @@ function computeGraphDistance<T>(
 
 /**
  * Compute distance between two clusters based on linkage method
+ * @param cluster1 - First cluster node
+ * @param cluster2 - Second cluster node
+ * @param distances - Precomputed distance matrix between nodes
+ * @param linkage - Linkage method to use for computing cluster distance
+ * @returns The distance between the two clusters
  */
 function clusterDistance<T>(
     cluster1: ClusterNode<T>,
@@ -126,9 +132,9 @@ function clusterDistance<T>(
 
     switch (linkage) {
         case "single":
-            return Math.min(... allDistances);
+            return Math.min(...allDistances);
         case "complete":
-            return Math.max(... allDistances);
+            return Math.max(...allDistances);
         case "average":
             return allDistances.reduce((a, b) => a + b, 0) / allDistances.length;
         case "ward": {
@@ -139,12 +145,15 @@ function clusterDistance<T>(
             return avgDist * ((size1 * size2) / (size1 + size2));
         }
         default:
-            return Math.min(... allDistances);
+            return Math.min(...allDistances);
     }
 }
 
 /**
  * Internal implementation of agglomerative hierarchical clustering
+ * @param graph - Adjacency map representation of the graph
+ * @param linkage - Linkage method for cluster distance computation
+ * @returns Hierarchical clustering result with dendrogram and cluster assignments
  */
 function hierarchicalClusteringImpl<T>(
     graph: Map<T, Set<T>>,
@@ -155,7 +164,7 @@ function hierarchicalClusteringImpl<T>(
 
     if (n === 0) {
         return {
-            root: {id: "empty", members: new Set(), distance: 0, height: 0},
+            root: { id: "empty", members: new Set(), distance: 0, height: 0 },
             dendrogram: [],
             clusters: new Map(),
         };
@@ -173,7 +182,7 @@ function hierarchicalClusteringImpl<T>(
         height: 0,
     }));
 
-    const dendrogram: ClusterNode<T>[] = [... clusters];
+    const dendrogram: ClusterNode<T>[] = [...clusters];
     let clusterCount = n;
 
     // Distance matrix between clusters
@@ -220,9 +229,8 @@ function hierarchicalClusteringImpl<T>(
                     continue;
                 }
 
-                const dist = distMap.get(cluster2.id) ??
-                    clusterDistances.get(cluster2.id)?.get(cluster1.id) ??
-                    Infinity;
+                const dist =
+                    distMap.get(cluster2.id) ?? clusterDistances.get(cluster2.id)?.get(cluster1.id) ?? Infinity;
 
                 if (dist < minDist) {
                     minDist = dist;
@@ -239,7 +247,7 @@ function hierarchicalClusteringImpl<T>(
                 id: `forest-${String(clusterCount++)}`,
                 members: new Set(nodes),
                 distance: Infinity,
-                height: Math.max(... trees.map((t) => t.height)) + 1,
+                height: Math.max(...trees.map((t) => t.height)) + 1,
                 trees,
             };
             dendrogram.push(forestRoot);
@@ -251,7 +259,7 @@ function hierarchicalClusteringImpl<T>(
         // Create new cluster
         const newCluster: ClusterNode<T> = {
             id: `cluster-${String(clusterCount++)}`,
-            members: new Set([... mergeCluster1.members, ... mergeCluster2.members]),
+            members: new Set([...mergeCluster1.members, ...mergeCluster2.members]),
             left: mergeCluster1,
             right: mergeCluster2,
             distance: minDist,
@@ -301,7 +309,7 @@ function hierarchicalClusteringImpl<T>(
 
     if (!root) {
         return {
-            root: {id: "empty", members: new Set(), distance: 0, height: 0},
+            root: { id: "empty", members: new Set(), distance: 0, height: 0 },
             dendrogram: [],
             clusters: new Map(),
         };
@@ -320,11 +328,11 @@ function hierarchicalClusteringImpl<T>(
 
 /**
  * Cut dendrogram at specific height to get clusters
+ * @param root - Root node of the dendrogram
+ * @param height - Height at which to cut the dendrogram
+ * @returns Array of sets representing clusters at the specified height
  */
-export function cutDendrogram<T>(
-    root: ClusterNode<T>,
-    height: number,
-): Set<T>[] {
+export function cutDendrogram<T>(root: ClusterNode<T>, height: number): Set<T>[] {
     const clusters: Set<T>[] = [];
 
     function traverse(node: ClusterNode<T>): void {
@@ -354,11 +362,11 @@ export function cutDendrogram<T>(
 
 /**
  * Cut dendrogram to get exactly k clusters
+ * @param root - Root node of the dendrogram
+ * @param k - Target number of clusters
+ * @returns Array of sets representing exactly k clusters
  */
-export function cutDendrogramKClusters<T>(
-    root: ClusterNode<T>,
-    k: number,
-): Set<T>[] {
+export function cutDendrogramKClusters<T>(root: ClusterNode<T>, k: number): Set<T>[] {
     if (k <= 0) {
         return [];
     }
@@ -390,17 +398,17 @@ export function cutDendrogramKClusters<T>(
 /**
  * Compute modularity-based hierarchical clustering
  * Uses modularity gain to decide merges
+ * @param graph - The input graph to cluster
+ * @returns Hierarchical clustering result with dendrogram and cluster assignments
  */
-export function modularityHierarchicalClustering(
-    graph: Graph,
-): HierarchicalClusteringResult<string> {
+export function modularityHierarchicalClustering(graph: Graph): HierarchicalClusteringResult<string> {
     const adjacencySet = graphToAdjacencySet(graph);
     const nodes = Array.from(adjacencySet.keys());
     const n = nodes.length;
 
     if (n === 0) {
         return {
-            root: {id: "empty", members: new Set(), distance: 0, height: 0},
+            root: { id: "empty", members: new Set(), distance: 0, height: 0 },
             dendrogram: [],
             clusters: new Map(),
         };
@@ -426,7 +434,7 @@ export function modularityHierarchicalClustering(
         height: 0,
     }));
 
-    const dendrogram: ClusterNode<string>[] = [... clusters];
+    const dendrogram: ClusterNode<string>[] = [...clusters];
     let clusterCount = n;
 
     // Active clusters
@@ -466,8 +474,7 @@ export function modularityHierarchicalClustering(
                     }
                 }
 
-                const gain = (edgesBetween / totalEdges) -
-                    (degreeProduct / (4 * totalEdges * totalEdges));
+                const gain = edgesBetween / totalEdges - degreeProduct / (4 * totalEdges * totalEdges);
 
                 if (gain > maxGain) {
                     maxGain = gain;
@@ -484,7 +491,7 @@ export function modularityHierarchicalClustering(
         // Create new cluster
         const newCluster: ClusterNode<string> = {
             id: `cluster-${String(clusterCount++)}`,
-            members: new Set([... mergeCluster1.members, ... mergeCluster2.members]),
+            members: new Set([...mergeCluster1.members, ...mergeCluster2.members]),
             left: mergeCluster1,
             right: mergeCluster2,
             distance: -maxGain, // Use negative gain as distance
@@ -507,7 +514,7 @@ export function modularityHierarchicalClustering(
 
     if (!root) {
         return {
-            root: {id: "empty", members: new Set(), distance: 0, height: 0},
+            root: { id: "empty", members: new Set(), distance: 0, height: 0 },
             dendrogram: [],
             clusters: new Map(),
         };
@@ -527,7 +534,6 @@ export function modularityHierarchicalClustering(
 /**
  * Agglomerative hierarchical clustering
  * Builds clusters bottom-up by merging closest pairs
- *
  * @param graph - Undirected graph - accepts Graph class or Map<T, Set<T>>
  * @param linkage - Linkage method for cluster distance
  * @returns Hierarchical clustering result