graphwise 1.4.3 → 1.5.0

package/dist/__test__/fixtures/index.d.ts

@@ -7,4 +7,5 @@
 export * from './types';
 export * from './helpers';
 export * from './graphs';
+export * from './metrics';
 //# sourceMappingURL=index.d.ts.map

package/dist/__test__/fixtures/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/__test__/fixtures/metrics.d.ts

@@ -0,0 +1,86 @@
+import { NodeId, NodeData, EdgeData, ReadableGraph } from '../../graph';
+import { ExpansionResult } from '../../expansion/types';
+import { PARSEResult } from '../../ranking/parse';
+/**
+ * Fraction of visited nodes whose degree is below the 90th percentile of all
+ * sampled node degrees. A high ratio indicates the algorithm successfully
+ * defers high-degree hubs in favour of lower-degree nodes.
+ */
+export declare function hubDeferralRatio<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, result: ExpansionResult): number;
+/**
+ * Count of distinct intermediate nodes (i.e. excluding endpoints) across all
+ * discovered paths. Higher values indicate broader path diversity.
+ */
+export declare function pathDiversity(result: ExpansionResult): number;
+/**
+ * Ratio of sampled edges to sampled nodes. Reflects how densely the sampled
+ * subgraph is connected (higher = more edges per node).
+ */
+export declare function subgraphDensity(result: ExpansionResult): number;
+/**
+ * Ratio of discovered paths to total nodes visited. Measures how efficiently
+ * the expansion produced useful paths relative to exploration cost.
+ */
+export declare function coverageEfficiency(result: ExpansionResult): number;
+/**
+ * Ratio of total iterations to paths discovered. Measures how many
+ * iterations were required per path. Returns Infinity when no paths
+ * were found (expansion terminated without connecting seeds).
+ */
+export declare function firstPathLatency(result: ExpansionResult): number;
+/**
+ * Number of distinct node types present in the sampled node set.
+ * Nodes without a `type` property are counted as a single unnamed type.
+ */
+export declare function typeCoverage<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, result: ExpansionResult): number;
+/**
+ * Number of connected components that contain at least one path node,
+ * determined via union-find over the sampled edge set. Higher values
+ * indicate paths spanning structurally distant regions of the graph.
+ */
+export declare function communitySpan(result: ExpansionResult): number;
+/**
+ * Spearman rank correlation coefficient between two rankings (arrays of node
+ * IDs ordered from highest to lowest). Returns a value in [-1, 1] where 1
+ * means identical order and -1 means perfectly reversed.
+ *
+ * Only nodes present in both rankings are considered.
+ */
+export declare function spearmanRho(rankingA: readonly NodeId[], rankingB: readonly NodeId[]): number;
+/**
+ * Kendall tau rank correlation coefficient between two rankings. Returns a
+ * value in [-1, 1] where 1 means identical and -1 means fully reversed.
+ *
+ * Only nodes present in both rankings are considered.
+ */
+export declare function kendallTau(rankingA: readonly NodeId[], rankingB: readonly NodeId[]): number;
+/**
+ * Ratio of weak-link path salience to consistent-path salience. Values below
+ * 1 indicate the consistent path scores higher (expected behaviour); values
+ * above 1 indicate the weak-link path is incorrectly ranked higher.
+ *
+ * @param consistent - Mean salience of paths expected to rank highest
+ * @param weakLink   - Mean salience of paths expected to rank lower
+ */
+export declare function weakLinkSensitivity(consistent: number, weakLink: number): number;
+/**
+ * Sample variance of salience scores across all ranked paths. Returns 0 when
+ * all paths have identical scores (no discriminative power).
+ */
+export declare function scoreVariance(parseResult: PARSEResult): number;
+/**
+ * Pearson correlation between path length (number of edges) and salience
+ * score. Values near 0 indicate length-unbiased ranking; strong positive or
+ * negative values indicate length bias.
+ */
+export declare function lengthBias(parseResult: PARSEResult): number;
+/**
+ * Ratio of hub path salience to peripheral path salience. Values below 1
+ * indicate hub paths score lower (hub penalty is working); values at or above
+ * 1 indicate no penalty.
+ *
+ * @param peripheral - Mean salience of paths through low-degree nodes
+ * @param hub        - Mean salience of paths through high-degree hub nodes
+ */
+export declare function hubPenaltyStrength(peripheral: number, hub: number): number;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/__test__/fixtures/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/__test__/fixtures/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMvD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACtE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,eAAe,GACrB,MAAM,CAaR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAa7D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAM/D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAMlE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKhE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAClE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,MAAM,EAAE,eAAe,GACrB,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA4C7D;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAC1B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CA+BR;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CAsCR;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACd,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAS9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CA+B3D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAK1E"}

package/dist/__test__/fixtures/metrics.unit.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Unit tests for the comparison metrics module.
+ *
+ * Tests use minimal mock data to verify each metric function independently.
+ */
+export {};
+//# sourceMappingURL=metrics.unit.test.d.ts.map

package/dist/__test__/fixtures/metrics.unit.test.d.ts.map

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

package/dist/expansion/dfs-priority.d.ts

@@ -0,0 +1,23 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig, PriorityContext } from './types';
+/**
+ * DFS priority function: negative iteration produces LIFO ordering.
+ *
+ * Lower priority values are expanded first, so negating the iteration
+ * counter ensures the most recently enqueued node is always next.
+ */
+export declare function dfsPriorityFn<N extends NodeData, E extends EdgeData>(_nodeId: string, context: PriorityContext<N, E>): number;
+/**
+ * Run DFS-priority expansion (LIFO discovery order).
+ *
+ * Uses the BASE framework with a negative-iteration priority function,
+ * which causes the most recently discovered node to be expanded first —
+ * equivalent to depth-first search behaviour.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Expansion configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function dfsPriority<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: ExpansionConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=dfs-priority.d.ts.map

package/dist/expansion/dfs-priority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dfs-priority.d.ts","sourceRoot":"","sources":["../../src/expansion/dfs-priority.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EACf,eAAe,EACf,eAAe,EACf,MAAM,SAAS,CAAC;AAGjB;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACnE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC5B,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACjE,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/dfs-priority.unit.test.d.ts

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

package/dist/expansion/dfs-priority.unit.test.d.ts.map

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

package/dist/expansion/index.d.ts

@@ -24,4 +24,7 @@ export * from './flux';
 export * from './standard-bfs';
 export * from './frontier-balanced';
 export * from './random-priority';
+export * from './dfs-priority';
+export * from './k-hop';
+export * from './random-walk';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expansion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expansion/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC"}

package/dist/expansion/k-hop.d.ts

@@ -0,0 +1,26 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult, ExpansionConfig } from './types';
+/**
+ * Configuration for k-hop expansion.
+ */
+export interface KHopConfig<N extends NodeData = NodeData, E extends EdgeData = EdgeData> extends ExpansionConfig<N, E> {
+    /**
+     * Maximum number of hops from any seed node.
+     * Defaults to 2.
+     */
+    readonly k?: number;
+}
+/**
+ * Run k-hop expansion (fixed-depth BFS).
+ *
+ * Explores all nodes reachable within exactly k hops of any seed using
+ * breadth-first search. Paths between seeds are detected when a node
+ * is reached by frontiers from two different seeds.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - K-hop configuration (k defaults to 2)
+ * @returns Expansion result with discovered paths
+ */
+export declare function kHop<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: KHopConfig<N, E>): ExpansionResult;
+//# sourceMappingURL=k-hop.d.ts.map

package/dist/expansion/k-hop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k-hop.d.ts","sourceRoot":"","sources":["../../src/expansion/k-hop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;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;;;OAGG;IACH,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;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,CA4JjB"}

package/dist/expansion/k-hop.unit.test.d.ts

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

package/dist/expansion/k-hop.unit.test.d.ts.map

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

package/dist/expansion/random-walk.d.ts

@@ -0,0 +1,35 @@
+import { NodeData, EdgeData, ReadableGraph } from '../graph';
+import { Seed, ExpansionResult } from './types';
+/**
+ * Configuration for random-walk-with-restart expansion.
+ */
+export interface RandomWalkConfig {
+    /** Probability of restarting a walk from its seed node (default: 0.15). */
+    readonly restartProbability?: number;
+    /** Number of walks to perform per seed node (default: 10). */
+    readonly walks?: number;
+    /** Maximum steps per walk (default: 20). */
+    readonly walkLength?: number;
+    /** Random seed for deterministic reproducibility (default: 0). */
+    readonly seed?: number;
+}
+/**
+ * Run random-walk-with-restart expansion.
+ *
+ * For each seed, performs `walks` independent random walks of up to
+ * `walkLength` steps. At each step the walk either restarts (with
+ * probability `restartProbability`) or moves to a uniformly sampled
+ * neighbour. All visited nodes and traversed edges are collected.
+ *
+ * Inter-seed paths are detected when a walk reaches a node that was
+ * previously reached by a walk originating from a different seed.
+ * The recorded path contains only the two seed endpoints rather than
+ * the full walk trajectory, consistent with the ExpansionPath contract.
+ *
+ * @param graph - Source graph
+ * @param seeds - Seed nodes for expansion
+ * @param config - Random walk configuration
+ * @returns Expansion result with discovered paths
+ */
+export declare function randomWalk<N extends NodeData, E extends EdgeData>(graph: ReadableGraph<N, E>, seeds: readonly Seed[], config?: RandomWalkConfig): ExpansionResult;
+//# sourceMappingURL=random-walk.d.ts.map

package/dist/expansion/random-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random-walk.d.ts","sourceRoot":"","sources":["../../src/expansion/random-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAU,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1E,OAAO,KAAK,EACX,IAAI,EACJ,eAAe,EAGf,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAqBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAChE,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,CAAC,EAAE,gBAAgB,GACvB,eAAe,CAwJjB"}

package/dist/expansion/random-walk.unit.test.d.ts

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

package/dist/expansion/random-walk.unit.test.d.ts.map

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