graphwise 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,41 @@
+# graphwise
+
+Low-dependency TypeScript graph algorithms for citation network analysis.
+
+## Features
+
+- **Expansion algorithms**: BASE, DOME, EDGE, HAE, PIPE, SAGE, REACH, MAZE + baselines
+- **MI variants**: Jaccard, Adamic-Adar, SCALE, SKEW, SPAN, ETCH, NOTCH, Unified Adaptive
+- **Path ranking**: PARSE + baselines (Katz, Communicability, PageRank, etc.)
+- **Seed selection**: GRASP, Stratified
+- **Subgraph extraction**: ego-network, k-core, k-truss, motif, induced, filter
+- **Optional WebGPU acceleration**
+
+## Installation
+
+```bash
+pnpm add graphwise
+```
+
+## Usage
+
+```typescript
+import { AdjacencyMapGraph, dome, parse, jaccard } from 'graphwise';
+
+const graph = AdjacencyMapGraph.undirected();
+// add nodes and edges...
+
+const result = dome(graph, seeds);
+const ranked = parse(graph, result.paths, { mi: jaccard });
+```
+
+## Commands
+
+```bash
+pnpm build          # Build ESM + CJS + UMD
+pnpm test           # Run tests
+pnpm test:coverage  # Run tests with coverage
+pnpm typecheck      # Type check only
+pnpm lint           # Run ESLint
+pnpm validate       # Full QA: typecheck + lint + test + build
+```

package/dist/expansion/base.d.ts

@@ -0,0 +1,12 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Run BASE expansion algorithm.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function base<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=base.d.ts.map

package/dist/expansion/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/expansion/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,eAAe,EAEf,MAAM,SAAS,CAAC;AAqBjB;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAoOjB"}

package/dist/expansion/base.unit.test.d.ts

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

package/dist/expansion/base.unit.test.d.ts.map

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

package/dist/expansion/dome.d.ts

@@ -0,0 +1,16 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Run DOME expansion (degree-ordered).
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function dome<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+/**
+ * DOME with reverse priority (high degree first).
+ */
+export declare function domeHighDegree<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=dome.d.ts.map

package/dist/expansion/dome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dome.d.ts","sourceRoot":"","sources":["../../src/expansion/dome.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAGjB;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAejB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACpE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAejB"}

package/dist/expansion/dome.unit.test.d.ts

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

package/dist/expansion/dome.unit.test.d.ts.map

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

package/dist/expansion/edge.d.ts

@@ -0,0 +1,15 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Run EDGE expansion algorithm.
+ *
+ * Expands from seeds prioritising low-degree edges first.
+ * Useful for avoiding hubs and exploring sparse regions.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function edge<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=edge.d.ts.map

package/dist/expansion/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/expansion/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAwBjB;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAKjB"}

package/dist/expansion/edge.unit.test.d.ts

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

package/dist/expansion/edge.unit.test.d.ts.map

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

package/dist/expansion/hae.d.ts

@@ -0,0 +1,22 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Configuration for HAE expansion.
+ */
+export interface HAEConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> extends ExpansionConfig<N, E> {
+    /** MI function for computing edge priorities (default: jaccard) */
+    readonly mi?: (graph: ReadableGraph<N, E>, source: string, target: string) => number;
+}
+/**
+ * Run HAE expansion algorithm.
+ *
+ * Expands from seeds prioritising high-MI edges.
+ * Useful for finding paths with strong semantic associations.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration with MI function
+ * @returns Expansion result with discovered paths
+ */
+export declare function hae<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: HAEConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=hae.d.ts.map

package/dist/expansion/hae.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hae.d.ts","sourceRoot":"","sources":["../../src/expansion/hae.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAIjB;;GAEG;AACH,MAAM,WAAW,SAAS,CACzB,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAC5B,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,CAAC,EAAE,CACb,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,KACV,MAAM,CAAC;CACZ;AA0CD;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACzD,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GACtB,eAAe,CAUjB"}

package/dist/expansion/hae.unit.test.d.ts

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

package/dist/expansion/hae.unit.test.d.ts.map

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

package/dist/expansion/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Expansion algorithms module.
+ *
+ * Provides bidirectional expansion algorithms for discovering paths
+ * between seed nodes in a graph.
+ *
+ * @module expansion
+ */
+export type { Seed, SeedRole, ExpansionResult, ExpansionPath, ExpansionStats, ExpansionConfig, PriorityFunction, PriorityContext, } from './types';
+export { base } from './base';
+export { dome } from './dome';
+export { edge } from './edge';
+export { hae } from './hae';
+export type { HAEConfig } from './hae';
+export { pipe } from './pipe';
+export { sage } from './sage';
+export type { SAGEConfig } from './sage';
+export { reach } from './reach';
+export type { REACHConfig } from './reach';
+export { maze } from './maze';
+export type { MAZEConfig } from './maze';
+//# sourceMappingURL=index.d.ts.map

package/dist/expansion/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expansion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EACX,IAAI,EACJ,QAAQ,EACR,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,eAAe,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGzC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC"}

package/dist/expansion/maze.d.ts

@@ -0,0 +1,25 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Configuration for MAZE expansion.
+ */
+export interface MAZEConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> extends ExpansionConfig<N, E> {
+    /** Density threshold for switching to EDGE mode (default: 0.5) */
+    readonly densityThreshold?: number;
+    /** Bridge threshold for switching to PIPE mode (default: 0.3) */
+    readonly bridgeThreshold?: number;
+}
+/**
+ * Run MAZE expansion algorithm.
+ *
+ * Adaptively switches between expansion strategies based on
+ * local graph structure. Useful for heterogeneous graphs
+ * with varying density.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function maze<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: MAZEConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=maze.d.ts.map

package/dist/expansion/maze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maze.d.ts","sourceRoot":"","sources":["../../src/expansion/maze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAGjB;;GAEG;AACH,MAAM,WAAW,UAAU,CAC1B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAC5B,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CAClC;AA8FD;;;;;;;;;;;GAWG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,eAAe,CAcjB"}

package/dist/expansion/maze.unit.test.d.ts

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

package/dist/expansion/maze.unit.test.d.ts.map

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

package/dist/expansion/pipe.d.ts

@@ -0,0 +1,15 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Run PIPE expansion algorithm.
+ *
+ * Expands from seeds prioritising bridge nodes.
+ * Useful for finding paths through structurally important nodes.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function pipe<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=pipe.d.ts.map

package/dist/expansion/pipe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipe.d.ts","sourceRoot":"","sources":["../../src/expansion/pipe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAsCjB;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,eAAe,CAKjB"}

package/dist/expansion/pipe.unit.test.d.ts

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

package/dist/expansion/pipe.unit.test.d.ts.map

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

package/dist/expansion/reach.d.ts

@@ -0,0 +1,26 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Configuration for REACH expansion.
+ */
+export interface REACHConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> extends ExpansionConfig<N, E> {
+    /** MI function for salience computation (default: jaccard) */
+    readonly mi?: (graph: ReadableGraph<N, E>, source: string, target: string) => number;
+    /** MI percentile threshold for phase 2 (default: 0.25) */
+    readonly miThreshold?: number;
+    /** Maximum nodes for phase 1 sampling (default: 1000) */
+    readonly phase1MaxNodes?: number;
+}
+/**
+ * Run REACH expansion algorithm.
+ *
+ * Two-phase adaptive expansion that learns MI thresholds
+ * from initial sampling, then uses them for guided expansion.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function reach<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: REACHConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=reach.d.ts.map

package/dist/expansion/reach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reach.d.ts","sourceRoot":"","sources":["../../src/expansion/reach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAIjB;;GAEG;AACH,MAAM,WAAW,WAAW,CAC3B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAC5B,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,EAAE,CACb,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,KACV,MAAM,CAAC;IACZ,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAsCD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC3D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,eAAe,CAWjB"}

package/dist/expansion/reach.unit.test.d.ts

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

package/dist/expansion/reach.unit.test.d.ts.map

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

package/dist/expansion/sage.d.ts

@@ -0,0 +1,24 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Configuration for SAGE expansion.
+ */
+export interface SAGEConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> extends ExpansionConfig<N, E> {
+    /** MI function for salience computation (default: jaccard) */
+    readonly mi?: (graph: ReadableGraph<N, E>, source: string, target: string) => number;
+    /** Weight for salience component (0-1, default: 0.5) */
+    readonly salienceWeight?: number;
+}
+/**
+ * Run SAGE expansion algorithm.
+ *
+ * Combines structural exploration with semantic salience.
+ * Useful for finding paths that are both short and semantically meaningful.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration with MI function
+ * @returns Expansion result with discovered paths
+ */
+export declare function sage<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: SAGEConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=sage.d.ts.map

package/dist/expansion/sage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sage.d.ts","sourceRoot":"","sources":["../../src/expansion/sage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EAEf,MAAM,SAAS,CAAC;AAIjB;;GAEG;AACH,MAAM,WAAW,UAAU,CAC1B,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAC7B,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAC5B,SAAQ,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,EAAE,CACb,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,KACV,MAAM,CAAC;IACZ,wDAAwD;IACxD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAyCD;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC1D,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACvB,eAAe,CAUjB"}

package/dist/expansion/sage.unit.test.d.ts

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

package/dist/expansion/sage.unit.test.d.ts.map

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

package/dist/expansion/types.d.ts

@@ -0,0 +1,105 @@
+import { NodeId, NodeData, EdgeData, ReadableGraph } from '../graph';
+/**
+ * Role of a seed node in expansion.
+ */
+export type SeedRole = "source" | "target" | "bidirectional";
+/**
+ * A seed node for expansion.
+ */
+export interface Seed {
+    /** Node identifier */
+    readonly id: NodeId;
+    /** Optional role - default is 'bidirectional' */
+    readonly role?: SeedRole;
+}
+/**
+ * Context provided to priority functions.
+ */
+export interface PriorityContext<N extends NodeData = NodeData, E extends EdgeData = EdgeData> {
+    /** The source graph */
+    readonly graph: ReadableGraph<N, E>;
+    /** Degree of the node being prioritised */
+    readonly degree: number;
+    /** Index of the frontier this node belongs to */
+    readonly frontierIndex: number;
+    /** Map of node ID to frontier index that visited it */
+    readonly visitedByFrontier: ReadonlyMap<NodeId, number>;
+    /** Set of all visited nodes */
+    readonly allVisited: ReadonlySet<NodeId>;
+    /** Paths discovered so far */
+    readonly discoveredPaths: readonly ExpansionPath[];
+    /** Current iteration number */
+    readonly iteration: number;
+    /** Optional MI score (for REACH phase 2) */
+    readonly mi?: number;
+}
+/**
+ * Function that computes expansion priority for a node.
+ * Lower values = higher priority (expanded first).
+ */
+export type PriorityFunction<N extends NodeData = NodeData, E extends EdgeData = EdgeData> = (nodeId: NodeId, context: PriorityContext<N, E>) => number;
+/**
+ * A path discovered by bidirectional expansion.
+ */
+export interface ExpansionPath {
+    /** Source seed */
+    readonly fromSeed: Seed;
+    /** Target seed */
+    readonly toSeed: Seed;
+    /** Nodes in the path (inclusive of endpoints) */
+    readonly nodes: readonly NodeId[];
+    /** Optional salience score */
+    readonly salience?: number;
+}
+/**
+ * Statistics from expansion.
+ */
+export interface ExpansionStats {
+    /** Total iterations */
+    readonly iterations: number;
+    /** Total nodes visited */
+    readonly nodesVisited: number;
+    /** Total edges traversed */
+    readonly edgesTraversed: number;
+    /** Paths discovered */
+    readonly pathsFound: number;
+    /** Expansion duration in milliseconds */
+    readonly durationMs: number;
+    /** Algorithm name */
+    readonly algorithm: string;
+    /** Termination reason */
+    readonly termination: "exhausted" | "limit" | "collision" | "error";
+}
+/**
+ * Result of an expansion algorithm.
+ */
+export interface ExpansionResult {
+    /** All discovered paths */
+    readonly paths: readonly ExpansionPath[];
+    /** Nodes sampled during expansion */
+    readonly sampledNodes: ReadonlySet<NodeId>;
+    /** Edges sampled during expansion */
+    readonly sampledEdges: ReadonlySet<readonly [NodeId, NodeId]>;
+    /** Nodes visited per frontier */
+    readonly visitedPerFrontier: readonly ReadonlySet<NodeId>[];
+    /** Expansion statistics */
+    readonly stats: ExpansionStats;
+}
+/**
+ * Configuration for expansion algorithms.
+ */
+export interface ExpansionConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> {
+    /** Maximum number of nodes to visit (0 = unlimited) */
+    readonly maxNodes?: number;
+    /** Maximum number of iterations (0 = unlimited) */
+    readonly maxIterations?: number;
+    /** Maximum paths to discover before stopping (0 = unlimited) */
+    readonly maxPaths?: number;
+    /** Custom priority function */
+    readonly priority?: PriorityFunction<N, E>;
+    /** Random seed for reproducibility */
+    readonly seed?: number;
+    /** Enable debug logging */
+    readonly debug?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/expansion/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/expansion/types.ts"],"names":[],"mappings":"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"}

package/dist/extraction/ego-network.d.ts

@@ -0,0 +1,32 @@
+import { NodeId, NodeData, EdgeData, ReadableGraph } from '../graph';
+import { AdjacencyMapGraph } from '../graph/adjacency-map';
+/**
+ * Options for ego-network extraction.
+ */
+export interface EgoNetworkOptions {
+    /** Number of hops from the centre node. Default: 1. */
+    readonly hops?: number;
+}
+/**
+ * Extract the ego-network (k-hop neighbourhood) of a centre node.
+ *
+ * The ego-network includes all nodes reachable within k hops from the
+ * centre node, plus all edges between those nodes (induced subgraph).
+ *
+ * For directed graphs, the search follows outgoing edges by default.
+ * To include incoming edges, use direction 'both' in the underlying traversal.
+ *
+ * @param graph - The source graph
+ * @param centre - The centre node ID
+ * @param options - Extraction options
+ * @returns An induced subgraph of the k-hop neighbourhood
+ * @throws Error if the centre node does not exist in the graph
+ *
+ * @example
+ * ```typescript
+ * // 2-hop neighbourhood
+ * const ego = extractEgoNetwork(graph, 'A', { hops: 2 });
+ * ```
+ */
+export declare function extractEgoNetwork<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, centre: NodeId, options?: EgoNetworkOptions): AdjacencyMapGraph<N, E>;
+//# sourceMappingURL=ego-network.d.ts.map

package/dist/extraction/ego-network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ego-network.d.ts","sourceRoot":"","sources":["../../src/extraction/ego-network.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACvE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,iBAAiB,GACzB,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CA4DzB"}

package/dist/extraction/ego-network.unit.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for ego-network extraction.
+ */
+export {};
+//# sourceMappingURL=ego-network.unit.test.d.ts.map

package/dist/extraction/ego-network.unit.test.d.ts.map

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

package/dist/extraction/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Subgraph extraction algorithms module.
+ *
+ * Provides algorithms for extracting various subgraphs from a graph:
+ * - Ego-networks (k-hop neighbourhoods)
+ * - K-core decomposition
+ * - K-truss decomposition
+ * - Motif enumeration
+ * - Induced subgraphs
+ * - Filtered subgraphs
+ *
+ * @module extraction
+ */
+export { extractEgoNetwork, type EgoNetworkOptions } from './ego-network';
+export { extractKCore } from './k-core';
+export { extractKTruss } from './truss';
+export { enumerateMotifs, enumerateMotifsWithInstances, getMotifName, type MotifCensus, } from './motif';
+export { extractInducedSubgraph } from './induced-subgraph';
+export { filterSubgraph, type FilterOptions } from './node-filter';
+//# sourceMappingURL=index.d.ts.map

package/dist/extraction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extraction/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EACN,eAAe,EACf,4BAA4B,EAC5B,YAAY,EACZ,KAAK,WAAW,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/extraction/induced-subgraph.d.ts

@@ -0,0 +1,19 @@
+import { NodeId, NodeData, EdgeData, ReadableGraph } from '../graph';
+import { AdjacencyMapGraph } from '../graph/adjacency-map';
+/**
+ * Extract the induced subgraph containing exactly the specified nodes.
+ *
+ * The induced subgraph includes all nodes from the input set that exist
+ * in the original graph, plus all edges where both endpoints are in the set.
+ *
+ * @param graph - The source graph
+ * @param nodes - Set of node IDs to include in the subgraph
+ * @returns A new graph containing the induced subgraph
+ *
+ * @example
+ * ```typescript
+ * const subgraph = extractInducedSubgraph(graph, new Set(['A', 'B', 'C']));
+ * ```
+ */
+export declare function extractInducedSubgraph<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, nodes: ReadonlySet<NodeId>): AdjacencyMapGraph<N, E>;
+//# sourceMappingURL=induced-subgraph.d.ts.map

package/dist/extraction/induced-subgraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"induced-subgraph.d.ts","sourceRoot":"","sources":["../../src/extraction/induced-subgraph.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC5E,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAqBzB"}

package/dist/extraction/induced-subgraph.unit.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for induced subgraph extraction.
+ */
+export {};
+//# sourceMappingURL=induced-subgraph.unit.test.d.ts.map

package/dist/extraction/induced-subgraph.unit.test.d.ts.map

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

package/dist/extraction/k-core.d.ts

@@ -0,0 +1,24 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { AdjacencyMapGraph } from '../graph/adjacency-map';
+/**
+ * Extract the k-core of a graph.
+ *
+ * The k-core is the maximal connected subgraph where every node has
+ * degree at least k. This is computed using a peeling algorithm that
+ * iteratively removes nodes with degree less than k.
+ *
+ * For undirected graphs, degree counts all adjacent nodes.
+ * For directed graphs, degree counts both in- and out-neighbours.
+ *
+ * @param graph - The source graph
+ * @param k - The minimum degree threshold
+ * @returns A new graph containing the k-core (may be empty)
+ *
+ * @example
+ * ```typescript
+ * // Extract the 3-core (nodes with at least 3 neighbours)
+ * const core3 = extractKCore(graph, 3);
+ * ```
+ */
+export declare function extractKCore<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, k: number): AdjacencyMapGraph<N, E>;
+//# sourceMappingURL=k-core.d.ts.map

package/dist/extraction/k-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k-core.d.ts","sourceRoot":"","sources":["../../src/extraction/k-core.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAClE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,CAAC,EAAE,MAAM,GACP,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CA8EzB"}

package/dist/extraction/k-core.unit.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for k-core decomposition.
+ */
+export {};
+//# sourceMappingURL=k-core.unit.test.d.ts.map

package/dist/extraction/k-core.unit.test.d.ts.map

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