graphbox 1.0.0 → 1.0.5

package/README.md

@@ -0,0 +1,191 @@
+# GraphBox
+
+**GraphBox** = Graph Sandbox + Graph Toolbox
+
+Abstract and experimental graph algorithms for academic research. The name reflects its dual purpose:
+
+- **Sandbox** — A space for experimenting with graph algorithms, data structures, and traversal strategies
+- **Toolbox** — A collection of reusable, well-tested graph utilities for production use
+
+GraphBox provides a toolkit for graph manipulation, analysis, and generation, specifically designed for academic research in graph theory, network science, and citation analysis.
+
+## Overview
+
+Graph-Box consolidates three previously separate BibGraph packages into a single, focused package:
+
+- **graph-core**: Core graph interfaces and adapters
+- **graph-expansion**: Graph expansion, traversal algorithms, and neighborhood exploration
+- **graph-gen**: Graph specification, generation, and validation system
+
+## Installation
+
+```bash
+pnpm install graph-box
+```
+
+## Key Features
+
+### Graph Adapters
+
+`GraphAdapter` provides a bridge between different graph implementations, allowing you to use generic algorithms with your specific graph data structures.
+
+```typescript
+import { GraphAdapter } from 'graph-box';
+
+const adapter = new GraphAdapter(graph);
+```
+
+### Graph Traversal
+
+Multiple traversal algorithms for exploring graph neighborhoods:
+
+- **BFS** - Breadth-first search
+- **DFS** - Depth-first search
+- **Bidirectional BFS** - Optimized bidirectional search
+- **Degree-Prioritized** - Expansion based on node degree
+- **Priority Queue** - Custom priority-based expansion
+
+```typescript
+import { bfs, dfs, extractEgoNetwork } from 'graph-box';
+
+const bfsResult = bfs(adapter, 'startNodeId');
+const dfsResult = dfs(adapter, 'startNodeId');
+```
+
+### Graph Extraction
+
+Extract ego networks and multi-source neighborhoods:
+
+```typescript
+const egoNetwork = extractEgoNetwork(adapter, {
+  radius: 2,
+  seedNodes: ['nodeId'],
+});
+```
+
+### Graph Generation
+
+Type-safe graph generation with mathematical constraint validation:
+
+```typescript
+import { generateGraph, validateGraph } from 'graph-box';
+
+const spec = {
+  type: 'complete',
+  nodeCount: 100,
+  edgeDensity: 0.1,
+  constraints: {
+    minDegree: 2,
+    maxDegree: 10,
+    connected: true
+  }
+};
+
+const graph = generateGraph(spec);
+const valid = validateGraph(graph, spec.constraints);
+```
+
+### Graph Validation
+
+Mathematical constraint validation for graph properties:
+
+```typescript
+import { validateGraph, checkConstraints } from 'graph-box';
+
+const isValid = validateGraph(graph, constraints);
+```
+
+## Usage Examples
+
+### Basic Traversal
+
+```typescript
+import { GraphAdapter, bfs } from 'graph-box';
+
+const graph = { /* your graph */ };
+const adapter = new GraphAdapter(graph);
+
+const result = bfs(adapter, 'startNodeId');
+console.log(result.visited); // Array of visited node IDs
+```
+
+### Ego Network Extraction
+
+```typescript
+import { extractEgoNetwork } from 'graph-box';
+
+const adapter = new GraphAdapter(graph);
+
+const egoNetwork = extractEgoNetwork(adapter, {
+  radius: 2,
+  seedNodes: ['author123'],
+  includeEdgeWeights: true
+});
+
+console.log(egoNetwork);
+```
+
+### Graph Generation
+
+```typescript
+import { generateGraph, GraphSpec } from 'graph-box';
+
+const spec: GraphSpec = {
+  type: 'complete',
+  nodeCount: 50,
+  edgeDensity: 0.15
+};
+
+const graph = generateGraph(spec);
+```
+
+### Graph Validation
+
+```typescript
+import { validateGraph } from 'graph-box';
+
+const graph = { /* graph object */ };
+const isValid = validateGraph(graph);
+```
+
+## API Reference
+
+### Core Classes
+
+- **GraphAdapter** - Adapter pattern for graph abstraction
+- **GraphExpander** - Interface for dynamic graph expansion
+- **PriorityQueue** - Priority queue for degree-based expansion
+
+### Traversal Algorithms
+
+- **bfs(adapter, startNodeId, options?)** - Breadth-first search
+- **dfs(adapter, startNodeId, options?)** - Depth-first search
+- **BidirectionalBFS** - Bidirectional BFS search
+
+### Extraction Methods
+
+- **extractEgoNetwork(adapter, options)** - Extract ego-centered subgraph
+- **extractMultiSourceEgoNetwork(adapter, options)** - Multi-source extraction
+
+### Generation Functions
+
+- **generateGraph(spec)** - Generate graph from specification
+- **validateGraph(graph, constraints)** - Validate graph against constraints
+
+## Contributing
+
+This package is part of academic research work. Contributions are welcome, please open an issue first.
+
+## License
+
+MIT
+
+## Author
+
+Joe Mearman
+
+## Related Projects
+
+- **BibGraph**: Main BibGraph monorepo
+- **algorithms**: Graph algorithms package for BibGraph
+- **types**: Shared TypeScript types for BibGraph

package/dist/__tests__/analyzer.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analyzer.unit.test.d.ts.map

package/dist/__tests__/analyzer.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/analyzer.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/constraints.unit.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for graph spec constraints analyzer
+ */
+export {};
+//# sourceMappingURL=constraints.unit.test.d.ts.map

package/dist/__tests__/constraints.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/constraints.unit.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/generator.unit.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for graph generator
+ */
+export {};
+//# sourceMappingURL=generator.unit.test.d.ts.map

package/dist/__tests__/generator.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/generator.unit.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/graph-properties.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=graph-properties.unit.test.d.ts.map

package/dist/__tests__/graph-properties.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-properties.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/graph-properties.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/graph-validator.unit.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for graph validator
+ */
+export {};
+//# sourceMappingURL=graph-validator.unit.test.d.ts.map

package/dist/__tests__/graph-validator.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-validator.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/graph-validator.unit.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/algorithms/analysis/connected-components.d.ts

@@ -0,0 +1,17 @@
+import { Graph } from '../graph/graph';
+import { Component } from '../types/algorithm-results';
+import { InvalidInputError } from '../types/errors';
+import { Edge, Node } from '../types/graph';
+import { 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 declare const connectedComponents: <N extends Node, E extends Edge = Edge>(graph: Graph<N, E>) => Result<Component<N>[], InvalidInputError>;
+//# sourceMappingURL=connected-components.d.ts.map

package/dist/algorithms/analysis/connected-components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connected-components.d.ts","sourceRoot":"","sources":["../../../src/algorithms/analysis/connected-components.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,KAAK,IAAI,EAAC,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAoB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,GAAG,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,iBAAiB,CAyDvI,CAAC"}

package/dist/algorithms/analysis/cycle-detection.d.ts

@@ -0,0 +1,19 @@
+import { Graph } from '../graph/graph';
+import { CycleInfo } from '../types/algorithm-results';
+import { InvalidInputError } from '../types/errors';
+import { Edge, Node } from '../types/graph';
+import { Option } from '../types/option';
+import { 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 declare const detectCycle: <N extends Node, E extends Edge>(graph: Graph<N, E>) => Result<Option<CycleInfo<N, E>>, InvalidInputError>;
+//# sourceMappingURL=cycle-detection.d.ts.map

package/dist/algorithms/analysis/cycle-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detection.d.ts","sourceRoot":"","sources":["../../../src/algorithms/analysis/cycle-detection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,KAAK,IAAI,EAAC,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAO,KAAK,MAAM,EAAQ,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAoB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,iBAAiB,CAwHjI,CAAC"}

package/dist/algorithms/analysis/index.d.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';
+//# sourceMappingURL=index.d.ts.map

package/dist/algorithms/analysis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/algorithms/analysis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,OAAO,CAAC;AACtB,cAAc,oBAAoB,CAAC"}

package/dist/algorithms/analysis/scc.d.ts

@@ -0,0 +1,18 @@
+import { Graph } from '../graph/graph';
+import { Component } from '../types/algorithm-results';
+import { InvalidInputError } from '../types/errors';
+import { Edge, Node } from '../types/graph';
+import { 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 declare const stronglyConnectedComponents: <N extends Node, E extends Edge = Edge>(graph: Graph<N, E>) => Result<Component<N>[], InvalidInputError>;
+//# sourceMappingURL=scc.d.ts.map

package/dist/algorithms/analysis/scc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scc.d.ts","sourceRoot":"","sources":["../../../src/algorithms/analysis/scc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,KAAK,IAAI,EAAC,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAoB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,GAAG,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,iBAAiB,CAiF/I,CAAC"}

package/dist/algorithms/analysis/topological-sort.d.ts

@@ -0,0 +1,17 @@
+import { Graph } from '../graph/graph';
+import { CycleDetectedError, InvalidInputError } from '../types/errors';
+import { Edge, Node } from '../types/graph';
+import { Result } from '../types/result';
+/**
+ * Topological sort using DFS-based reverse postorder.
+ *
+ * Returns a linear ordering of vertices such that for every directed edge (u, v),
+ * u comes before v in the ordering. Only works on Directed Acyclic Graphs (DAGs).
+ *
+ * Time Complexity: O(V + E)
+ * Space Complexity: O(V)
+ * @param graph - The directed graph to sort
+ * @returns Result containing ordered nodes or cycle error
+ */
+export declare const topologicalSort: <N extends Node, E extends Edge = Edge>(graph: Graph<N, E>) => Result<N[], CycleDetectedError | InvalidInputError>;
+//# sourceMappingURL=topological-sort.d.ts.map

package/dist/algorithms/analysis/topological-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topological-sort.d.ts","sourceRoot":"","sources":["../../../src/algorithms/analysis/topological-sort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,KAAK,IAAI,EAAC,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAoB,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,GAAG,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,EAAE,kBAAkB,GAAG,iBAAiB,CAmF7I,CAAC"}

package/dist/algorithms/clustering/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Automatically generated by barrelsby.
+ */
+export * from './infomap';
+export * from './label-propagation';
+export * from './leiden';
+export * from './louvain';
+//# sourceMappingURL=index.d.ts.map

package/dist/algorithms/clustering/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/algorithms/clustering/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/algorithms/clustering/infomap.d.ts

@@ -0,0 +1,37 @@
+import { Graph } from '../graph/graph';
+import { InfomapResult } from '../types/clustering-types';
+import { Edge, Node } from '../types/graph';
+import { WeightFunction } from '../types/weight-function';
+/**
+ * Detect communities using the Infomap algorithm.
+ *
+ * Infomap uses information theory to find communities by minimizing the
+ * description length (map equation) of random walks on the network.
+ * @template N - Node type
+ * @template E - Edge type
+ * @param graph - Input graph (directed or undirected)
+ * @param options - Optional configuration
+ * @param options.weightFn - Weight function for edges (default: all edges weight 1.0)
+ * @param options.maxIterations - Maximum iterations for optimization (default: 100)
+ * @param options.numTrials - Number of random trials for greedy search (default: 10)
+ * @param options.seed - Random seed for reproducibility (default: undefined)
+ * @returns Result containing modules with compression ratio
+ * @example
+ * ```typescript
+ * const graph = new Graph<PaperNode, CitationEdge>(true);
+ * // ... add nodes and edges ...
+ *
+ * const result = infomap(graph);
+ * if (result.ok) {
+ *   console.log(`Found ${result.value.modules.length} modules`);
+ *   console.log(`Compression ratio: ${result.value.compressionRatio}`);
+ * }
+ * ```
+ */
+export declare const infomap: <N extends Node, E extends Edge>(graph: Graph<N, E>, options?: {
+    weightFn?: WeightFunction<N, E>;
+    maxIterations?: number;
+    numTrials?: number;
+    seed?: number;
+}) => InfomapResult<N>;
+//# sourceMappingURL=infomap.d.ts.map

package/dist/algorithms/clustering/infomap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infomap.d.ts","sourceRoot":"","sources":["../../../src/algorithms/clustering/infomap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,KAAK,EAAE,IAAI,EAAC,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAqB/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAS;IACpF,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACT,KAAG,aAAa,CAAC,CAAC,CAmOvB,CAAC"}

package/dist/algorithms/clustering/label-propagation.d.ts

@@ -0,0 +1,37 @@
+import { Graph } from '../graph/graph';
+import { LabelPropagationResult } from '../types/clustering-types';
+import { Edge, Node } from '../types/graph';
+import { WeightFunction } from '../types/weight-function';
+/**
+ * Label Propagation clustering algorithm.
+ *
+ * Fast semi-supervised clustering algorithm that propagates labels through
+ * the network based on neighbor voting. Nodes iteratively adopt the most
+ * frequent label among their neighbors.
+ * @template N - Node type
+ * @template E - Edge type
+ * @param graph - Input graph (directed or undirected)
+ * @param options - Optional configuration
+ * @param options.weightFn - Weight function for edges (default: all edges weight 1.0)
+ * @param options.maxIterations - Maximum iterations (default: 100)
+ * @param options.seed - Random seed for reproducibility (default: Date.now())
+ * @returns Result containing clusters or error
+ * @example
+ * ```typescript
+ * const graph = new Graph<PaperNode, CitationEdge>(true);
+ * // ... add nodes and edges ...
+ *
+ * const result = labelPropagation(graph);
+ * if (result.ok) {
+ *   console.log(`Found ${result.value.clusters.length} clusters`);
+ *   console.log(`Converged: ${result.value.metadata.converged}`);
+ *   console.log(`Iterations: ${result.value.metadata.iterations}`);
+ * }
+ * ```
+ */
+export declare const labelPropagation: <N extends Node, E extends Edge>(graph: Graph<N, E>, options?: {
+    weightFn?: WeightFunction<N, E>;
+    maxIterations?: number;
+    seed?: number;
+}) => LabelPropagationResult<N>;
+//# sourceMappingURL=label-propagation.d.ts.map

package/dist/algorithms/clustering/label-propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-propagation.d.ts","sourceRoot":"","sources":["../../../src/algorithms/clustering/label-propagation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAIX,sBAAsB,EACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,IAAI,EAAC,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAS;IAC7F,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACT,KAAG,sBAAsB,CAAC,CAAC,CA+MhC,CAAC"}

package/dist/algorithms/clustering/leiden.d.ts

@@ -0,0 +1,50 @@
+import { Graph } from '../graph/graph';
+import { ClusteringError, ClusterMetrics, LeidenCommunity } from '../types/clustering-types';
+import { Edge, Node } from '../types/graph';
+import { Result } from '../types/result';
+import { WeightFunction } from '../types/weight-function';
+/**
+ * Detect communities using the Leiden algorithm.
+ *
+ * The Leiden algorithm improves upon Louvain by adding a refinement phase that
+ * guarantees all detected communities are connected subgraphs.
+ * @template N - Node type
+ * @template E - Edge type
+ * @param graph - Input graph (directed or undirected)
+ * @param options - Optional configuration
+ * @param options.weightFn - Weight function for edges (default: all edges weight 1.0)
+ * @param options.resolution - Resolution parameter (default: 1.0, higher values favor more communities)
+ * @param options.maxIterations - Maximum iterations per phase (default: 100)
+ * @returns Result with array of detected Leiden communities
+ * @example
+ * ```typescript
+ * const graph = new Graph<PaperNode, CitationEdge>(true);
+ * // ... add nodes and edges ...
+ *
+ * const result = leiden(graph);
+ * if (result.ok) {
+ *   console.log(`Found ${result.value.communities.length} communities`);
+ *   result.value.communities.forEach((community) => {
+ *     console.log(`Community ${community.id}: ${community.nodes.size} nodes, connected: ${community.isConnected}`);
+ *   });
+ * }
+ * ```
+ */
+export declare const leiden: <N extends Node, E extends Edge>(graph: Graph<N, E>, options?: {
+    weightFn?: WeightFunction<N, E>;
+    resolution?: number;
+    maxIterations?: number;
+}) => Result<{
+    communities: LeidenCommunity<N>[];
+    metrics: ClusterMetrics;
+    metadata: {
+        algorithm: "leiden";
+        runtime: number;
+        iterations: number;
+        parameters: {
+            resolution?: number;
+            maxIterations?: number;
+        };
+    };
+}, ClusteringError>;
+//# sourceMappingURL=leiden.d.ts.map

package/dist/algorithms/clustering/leiden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leiden.d.ts","sourceRoot":"","sources":["../../../src/algorithms/clustering/leiden.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,OAAO,KAAK,EAAE,eAAe,EAAC,cAAc,EAAa,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5G,OAAO,KAAK,EAAE,IAAI,EAAC,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAY/D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAS;IACnF,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,MAAM,CACd;IACC,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE;QACT,SAAS,EAAE,QAAQ,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE;YACX,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,aAAa,CAAC,EAAE,MAAM,CAAC;SACvB,CAAC;KACF,CAAC;CACF,EACD,eAAe,CA+Rf,CAAC"}

package/dist/algorithms/clustering/louvain.d.ts

@@ -0,0 +1,110 @@
+import { Graph } from '../graph/graph';
+import { Community } from '../types/clustering-types';
+import { Edge, Node } from '../types/graph';
+import { WeightFunction } from '../types/weight-function';
+/**
+ * Get adaptive convergence threshold based on graph size.
+ * @param nodeCount - Number of nodes in graph
+ * @returns Convergence threshold (1e-5 for large graphs, 1e-6 for small graphs)
+ * @remarks
+ * Large graphs (>500 nodes) use looser threshold for faster convergence.
+ * Small graphs (≤500 nodes) use stricter threshold for higher quality.
+ */
+export declare const getAdaptiveThreshold: (nodeCount: number) => number;
+/**
+ * Get adaptive iteration limit based on graph size and hierarchy level.
+ * @param nodeCount - Number of nodes in graph
+ * @param level - Hierarchy level (0 = first level)
+ * @returns Maximum iterations (20, 40, or 50)
+ * @remarks
+ * First hierarchy level (level 0) with large graphs (>200 nodes) uses lower limit (20)
+ * because most node movements happen in the first iteration.
+ * Subsequent levels and small graphs use higher limits (40-50) for refinement.
+ */
+export declare const getAdaptiveIterationLimit: (nodeCount: number, level: number) => number;
+/**
+ * Determine optimal neighbor selection mode based on graph size.
+ * @param nodeCount - Number of nodes in graph
+ * @returns Neighbor selection mode ("best" or "random")
+ * @remarks
+ * **UPDATE (Phase 4 debugging)**: Random mode disabled for citation networks.
+ *
+ * Testing revealed Fast Louvain random-neighbor selection causes severe quality degradation
+ * for citation network graphs (Q=0.05-0.12 vs Q=0.37 with best mode), failing the minimum
+ * quality threshold of Q≥0.19. Random mode also paradoxically SLOWED convergence (201 iterations
+ * vs 103 with best mode), resulting in 3x slower runtime.
+ *
+ * Root cause: Citation networks have different structural properties than the social/web networks
+ * where Fast Louvain was benchmarked in literature. Accepting first positive ΔQ leads to poor-quality
+ * moves that require many iterations to correct.
+ *
+ * **Current strategy**: Always use best-neighbor mode for quality. Random mode remains available
+ * via explicit `mode: "random"` parameter for experimentation but is not recommended.
+ */
+export declare const determineOptimalMode: () => "best" | "random";
+/**
+ * Shuffle an array in-place using Fisher-Yates algorithm.
+ * @param array - Array to shuffle (modified in-place)
+ * @param seed - Optional random seed for deterministic shuffling (for tests)
+ * @returns The shuffled array (same reference as input)
+ * @remarks
+ * Fisher-Yates shuffle guarantees uniform distribution of permutations.
+ * If seed is provided, uses simple linear congruential generator (LCG) for PRNG.
+ * If seed is undefined, uses Math.random() (non-deterministic).
+ *
+ * LCG parameters: a=1664525, c=1013904223, m=2^32 (Numerical Recipes)
+ */
+export declare const shuffle: <T>(array: T[], seed?: number) => T[];
+/**
+ * Detect communities using the Louvain algorithm.
+ *
+ * The Louvain method is a greedy optimization method that attempts to optimize
+ * the modularity of a partition of the network.
+ * @template N - Node type
+ * @template E - Edge type
+ * @param graph - Input graph (directed or undirected)
+ * @param options - Optional configuration (combines legacy and optimization parameters)
+ * @param options.weightFn - Weight function for edges (default: all edges weight 1.0) [Legacy]
+ * @param options.resolution - Resolution parameter (default: 1.0, higher values favor more communities) [Legacy]
+ * @param options.mode - Neighbor selection strategy ("auto", "best", "random") [spec-027 Phase 2]
+ * @param options.seed - Random seed for deterministic shuffling [spec-027 Phase 2]
+ * @param options.minModularityIncrease - Minimum modularity improvement to continue (adaptive default via getAdaptiveThreshold)
+ * @param options.maxIterations - Maximum iterations per phase (adaptive default via getAdaptiveIterationLimit)
+ * @returns Array of detected communities
+ * @remarks
+ * **Adaptive Defaults** (spec-027 Phase 1):
+ * - `minModularityIncrease`: 1e-5 for >500 nodes, 1e-6 otherwise
+ * - `maxIterations`: 20 for >200 nodes (level 0), 40-50 otherwise
+ *
+ * **Neighbor Selection Modes** (spec-027 Phase 2):
+ * - `"auto"`: Best-neighbor for <200 nodes, random for ≥500 nodes
+ * - `"best"`: Always use best-neighbor (quality-first)
+ * - `"random"`: Always use random-neighbor (speed-first, Fast Louvain)
+ * @example
+ * ```typescript
+ * const graph = new Graph<PaperNode, CitationEdge>(true);
+ * // ... add nodes and edges ...
+ *
+ * // Basic usage (adaptive defaults)
+ * const communities = detectCommunities(graph);
+ * console.log(`Found ${communities.length} communities`);
+ *
+ * // Quality-first mode
+ * const qualityCommunities = detectCommunities(graph, { mode: "best" });
+ *
+ * // Speed-first mode for large graphs
+ * const fastCommunities = detectCommunities(graph, { mode: "random", maxIterations: 10 });
+ *
+ * // Reproducible results
+ * const deterministicCommunities = detectCommunities(graph, { seed: 42 });
+ * ```
+ */
+export declare const detectCommunities: <N extends Node, E extends Edge>(graph: Graph<N, E>, options?: {
+    weightFn?: WeightFunction<N, E>;
+    resolution?: number;
+    mode?: "auto" | "best" | "random";
+    seed?: number;
+    minModularityIncrease?: number;
+    maxIterations?: number;
+}) => Community<N>[];
+//# sourceMappingURL=louvain.d.ts.map

package/dist/algorithms/clustering/louvain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"louvain.d.ts","sourceRoot":"","sources":["../../../src/algorithms/clustering/louvain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAC,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAa/D;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,WAAW,MAAM,KAAG,MAAuC,CAAC;AAEjG;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GAAI,WAAW,MAAM,EAAE,OAAO,MAAM,KAAG,MAK5E,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MAAM,GAAG,QAAkB,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,MAAM,KAAG,CAAC,EAsBvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,UAAS;IAC9F,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;CAClB,KAAG,SAAS,CAAC,CAAC,CAAC,EAwXpB,CAAC"}