@git-stunts/git-warp 11.5.1 → 12.0.0

package/src/domain/services/LogicalTraversal.js

@@ -1,11 +1,18 @@
 /**
  * LogicalTraversal - Traversal utilities for the logical WARP graph.
  *
+ * **Deprecated**: delegates to GraphTraversal + AdjacencyNeighborProvider
+ * internally. The public API is unchanged for backward compatibility.
+ * New code should use GraphTraversal directly.
+ *
  * Provides deterministic BFS/DFS/shortestPath/connectedComponent over
  * the materialized logical graph (node/edge OR-Sets), not the Git DAG.
  */
 
 import TraversalError from '../errors/TraversalError.js';
+import GraphTraversal from './GraphTraversal.js';
+import AdjacencyNeighborProvider from './AdjacencyNeighborProvider.js';
+import { orsetElements } from '../crdt/ORSet.js';
 
 const DEFAULT_MAX_DEPTH = 1000;
 
@@ -33,15 +40,15 @@ function assertDirection(direction) {
  * Normalizes a label filter into a Set for efficient lookup.
  *
  * Accepts a single label string, an array of labels, or undefined. Returns
- * a Set containing the label(s) or null if no filter is specified.
+ * a Set containing the label(s) or undefined if no filter is specified.
  *
  * @param {string|string[]|undefined} labelFilter - The label filter to normalize
- * @returns {Set<string>|null} A Set of labels for filtering, or null if no filter
+ * @returns {Set<string>|undefined} A Set of labels for filtering, or undefined if no filter
  * @throws {TraversalError} If labelFilter is neither a string, array, nor undefined
  */
 function normalizeLabelFilter(labelFilter) {
   if (labelFilter === undefined) {
-    return null;
+    return undefined;
   }
   if (Array.isArray(labelFilter)) {
     return new Set(labelFilter);
@@ -55,73 +62,10 @@ function normalizeLabelFilter(labelFilter) {
   });
 }
 
-/**
- * Filters a list of neighbor edges by label.
- *
- * If no label set is provided (null), returns all neighbors unchanged.
- * If an empty label set is provided, returns an empty array.
- * Otherwise, returns only edges whose label is in the set.
- *
- * @param {Array<{neighborId: string, label: string}>} neighbors - The list of neighbor edges to filter
- * @param {Set<string>|null} labelSet - The set of allowed labels, or null to allow all
- * @returns {Array<{neighborId: string, label: string}>} The filtered list of neighbor edges
- */
-function filterByLabel(neighbors, labelSet) {
-  if (!labelSet) {
-    return neighbors;
-  }
-  if (labelSet.size === 0) {
-    return [];
-  }
-  return neighbors.filter((edge) => labelSet.has(edge.label));
-}
-
-/**
- * Retrieves neighbors of a node based on direction and label filter.
- *
- * Returns outgoing neighbors for 'out', incoming neighbors for 'in', or
- * a merged and sorted list of both for 'both'. Results are filtered by
- * label if a label set is provided.
- *
- * For 'both' direction, neighbors are sorted first by neighborId, then by label,
- * ensuring deterministic traversal order.
- *
- * @param {Object} params - The neighbor lookup parameters
- * @param {string} params.nodeId - The node ID to get neighbors for
- * @param {'out'|'in'|'both'} params.direction - The edge direction to follow
- * @param {Object} params.adjacency - The adjacency structure from materialized graph
- * @param {Map<string, Array<{neighborId: string, label: string}>>} params.adjacency.outgoing - Outgoing edge map
- * @param {Map<string, Array<{neighborId: string, label: string}>>} params.adjacency.incoming - Incoming edge map
- * @param {Set<string>|null} params.labelSet - The set of allowed labels, or null to allow all
- * @returns {Array<{neighborId: string, label: string}>} The list of neighbor edges
- */
-function getNeighbors({ nodeId, direction, adjacency, labelSet }) {
-  const outgoing = filterByLabel(adjacency.outgoing.get(nodeId) || [], labelSet);
-  const incoming = filterByLabel(adjacency.incoming.get(nodeId) || [], labelSet);
-
-  if (direction === 'out') {
-    return outgoing;
-  }
-  if (direction === 'in') {
-    return incoming;
-  }
-
-  const merged = outgoing.concat(incoming);
-  merged.sort((a, b) => {
-    if (a.neighborId !== b.neighborId) {
-      return a.neighborId < b.neighborId ? -1 : 1;
-    }
-    return a.label < b.label ? -1 : a.label > b.label ? 1 : 0;
-  });
-  return merged;
-}
-
 /**
  * Deterministic graph traversal engine for the materialized WARP graph.
  *
- * Provides BFS, DFS, shortest path (Dijkstra/A*), topological sort, and
- * connected component algorithms over the logical node/edge OR-Sets.
- * All traversals produce deterministic results via sorted neighbor ordering.
+ * @deprecated Use GraphTraversal + AdjacencyNeighborProvider directly.
  */
 export default class LogicalTraversal {
   /**
@@ -134,26 +78,60 @@ export default class LogicalTraversal {
   }
 
   /**
-   * Prepares common traversal state by materializing the graph and validating inputs.
+   * Prepares a GraphTraversal engine backed by the current adjacency.
+   * Does NOT validate any start node — use this for methods that accept
+   * multiple starts or no start at all (topologicalSort, commonAncestors).
    *
-   * This private method is called by all traversal methods to ensure the graph is
-   * materialized, the start node exists, and options are normalized.
+   * @private
+   * @param {Object} opts - The traversal options
+   * @param {'out'|'in'|'both'} [opts.dir] - Edge direction to follow
+   * @param {string|string[]} [opts.labelFilter] - Edge label(s) to include
+   * @param {number} [opts.maxDepth] - Maximum depth to traverse
+   * @returns {Promise<{engine: GraphTraversal, direction: 'out'|'in'|'both', options: {labels?: Set<string>}|undefined, depthLimit: number}>}
+   * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
+   * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
+   */
+  async _prepareEngine({ dir, labelFilter, maxDepth }) {
+    // Private access: _materializeGraph is a WarpGraph internal.
+    // This coupling will be removed when the LogicalTraversal facade is sunset
+    // and callers migrate to GraphTraversal + NeighborProvider directly.
+    const materialized = await /** @type {{ _materializeGraph: () => Promise<{state: {nodeAlive: import('../crdt/ORSet.js').ORSet}, adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}}> }} */ (this._graph)._materializeGraph();
+
+    const direction = assertDirection(dir);
+    const labelSet = normalizeLabelFilter(labelFilter);
+    const { adjacency, state } = materialized;
+    const depthLimit = maxDepth ?? DEFAULT_MAX_DEPTH;
+
+    const provider = new AdjacencyNeighborProvider({
+      outgoing: adjacency.outgoing,
+      incoming: adjacency.incoming,
+      aliveNodes: new Set(orsetElements(state.nodeAlive)),
+    });
+    const engine = new GraphTraversal({ provider });
+
+    /** @type {{labels?: Set<string>}|undefined} */
+    const options = labelSet ? { labels: labelSet } : undefined;
+
+    return { engine, direction, options, depthLimit };
+  }
+
+  /**
+   * Prepares a GraphTraversal engine and validates a single start node.
    *
    * @private
    * @param {string} start - The starting node ID for traversal
-   * @param {Object} options - The traversal options to normalize
-   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
-   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @param {number} [options.maxDepth] - Maximum depth to traverse
-   * @returns {Promise<{dir: 'out'|'in'|'both', labelSet: Set<string>|null, adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}, depthLimit: number}>}
-   *   The normalized traversal parameters
+   * @param {Object} opts - The traversal options
+   * @param {'out'|'in'|'both'} [opts.dir] - Edge direction to follow
+   * @param {string|string[]} [opts.labelFilter] - Edge label(s) to include
+   * @param {number} [opts.maxDepth] - Maximum depth to traverse
+   * @returns {Promise<{engine: GraphTraversal, direction: 'out'|'in'|'both', options: {labels?: Set<string>}|undefined, depthLimit: number}>}
    * @throws {TraversalError} If the start node is not found (NODE_NOT_FOUND)
    * @throws {TraversalError} If the direction is invalid (INVALID_DIRECTION)
    * @throws {TraversalError} If the labelFilter is invalid (INVALID_LABEL_FILTER)
    */
-  async _prepare(start, { dir, labelFilter, maxDepth }) {
-    const materialized = await /** @type {{ _materializeGraph: () => Promise<{adjacency: {outgoing: Map<string, Array<{neighborId: string, label: string}>>, incoming: Map<string, Array<{neighborId: string, label: string}>>}}> }} */ (this._graph)._materializeGraph();
-
+  async _prepare(start, opts) {
+    const prepared = await this._prepareEngine(opts);
+    // Note: engine also validates via provider.hasNode — redundant but harmless.
     if (!(await this._graph.hasNode(start))) {
       throw new TraversalError(`Start node not found: ${start}`, {
         code: 'NODE_NOT_FOUND',
@@ -161,12 +139,7 @@ export default class LogicalTraversal {
       });
     }
 
-    const resolvedDir = assertDirection(dir);
-    const labelSet = normalizeLabelFilter(labelFilter);
-    const { adjacency } = materialized;
-    const depthLimit = maxDepth ?? DEFAULT_MAX_DEPTH;
-
-    return { dir: resolvedDir, labelSet, adjacency, depthLimit };
+    return prepared;
   }
 
   /**
@@ -181,42 +154,15 @@ export default class LogicalTraversal {
    * @throws {TraversalError} If the start node is not found or direction is invalid
    */
   async bfs(start, options = {}) {
-    const { dir, labelSet, adjacency, depthLimit } = await this._prepare(start, options);
-    const visited = new Set();
-    const queue = [{ nodeId: start, depth: 0 }];
-    const result = [];
-
-    while (queue.length > 0) {
-      const current = /** @type {{nodeId: string, depth: number}} */ (queue.shift());
-      if (visited.has(current.nodeId)) {
-        continue;
-      }
-      if (current.depth > depthLimit) {
-        continue;
-      }
-
-      visited.add(current.nodeId);
-      result.push(current.nodeId);
-
-      if (current.depth === depthLimit) {
-        continue;
-      }
-
-      const neighbors = getNeighbors({
-        nodeId: current.nodeId,
-        direction: dir,
-        adjacency,
-        labelSet,
-      });
-
-      for (const edge of neighbors) {
-        if (!visited.has(edge.neighborId)) {
-          queue.push({ nodeId: edge.neighborId, depth: current.depth + 1 });
-        }
-      }
-    }
-
-    return result;
+    const { engine, direction, options: opts, depthLimit } = await this._prepare(start, options);
+    const { nodes } = await engine.bfs({
+      start,
+      direction,
+      options: opts,
+      maxDepth: depthLimit,
+      maxNodes: Infinity,
+    });
+    return await Promise.resolve(nodes);
   }
 
   /**
@@ -231,43 +177,15 @@ export default class LogicalTraversal {
    * @throws {TraversalError} If the start node is not found or direction is invalid
    */
   async dfs(start, options = {}) {
-    const { dir, labelSet, adjacency, depthLimit } = await this._prepare(start, options);
-    const visited = new Set();
-    const stack = [{ nodeId: start, depth: 0 }];
-    const result = [];
-
-    while (stack.length > 0) {
-      const current = /** @type {{nodeId: string, depth: number}} */ (stack.pop());
-      if (visited.has(current.nodeId)) {
-        continue;
-      }
-      if (current.depth > depthLimit) {
-        continue;
-      }
-
-      visited.add(current.nodeId);
-      result.push(current.nodeId);
-
-      if (current.depth === depthLimit) {
-        continue;
-      }
-
-      const neighbors = getNeighbors({
-        nodeId: current.nodeId,
-        direction: dir,
-        adjacency,
-        labelSet,
-      });
-
-      for (let i = neighbors.length - 1; i >= 0; i -= 1) {
-        const edge = neighbors[i];
-        if (!visited.has(edge.neighborId)) {
-          stack.push({ nodeId: edge.neighborId, depth: current.depth + 1 });
-        }
-      }
-    }
-
-    return result;
+    const { engine, direction, options: opts, depthLimit } = await this._prepare(start, options);
+    const { nodes } = await engine.dfs({
+      start,
+      direction,
+      options: opts,
+      maxDepth: depthLimit,
+      maxNodes: Infinity,
+    });
+    return await Promise.resolve(nodes);
   }
 
   /**
@@ -285,68 +203,269 @@ export default class LogicalTraversal {
    * @throws {TraversalError} If the start node is not found or direction is invalid
    */
   async shortestPath(from, to, options = {}) {
-    const { dir, labelSet, adjacency, depthLimit } = await this._prepare(from, options);
+    const { engine, direction, options: opts, depthLimit } = await this._prepare(from, options);
+    const { found, path, length } = await engine.shortestPath({
+      start: from,
+      goal: to,
+      direction,
+      options: opts,
+      maxDepth: depthLimit,
+      maxNodes: Infinity,
+    });
+    return await Promise.resolve({ found, path, length });
+  }
 
-    if (from === to) {
-      return { found: true, path: [from], length: 0 };
-    }
+  /**
+   * Connected component (undirected by default).
+   *
+   * @param {string} start - Starting node ID
+   * @param {Object} [options] - Traversal options
+   * @param {number} [options.maxDepth] - Maximum depth to traverse (default: 1000)
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @returns {Promise<string[]>} Node IDs in visit order
+   * @throws {TraversalError} If the start node is not found
+   */
+  async connectedComponent(start, options = {}) {
+    return await this.bfs(start, { ...options, dir: 'both' });
+  }
 
-    const visited = new Set();
-    const queue = [{ nodeId: from, depth: 0 }];
-    const parent = new Map();
+  /**
+   * Reachability check — BFS with early termination.
+   *
+   * Non-existent nodes are simply unreachable (no NODE_NOT_FOUND throw).
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {Object} [options] - Traversal options
+   * @param {number} [options.maxDepth] - Maximum search depth
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {AbortSignal} [options.signal] - Abort signal
+   * @returns {Promise<{reachable: boolean}>}
+   */
+  async isReachable(from, to, options = {}) {
+    const { engine, direction, options: opts, depthLimit } = await this._prepareEngine(options);
+    const { reachable } = await engine.isReachable({
+      start: from,
+      goal: to,
+      direction,
+      options: opts,
+      maxDepth: depthLimit,
+      maxNodes: Infinity,
+      signal: options.signal,
+    });
+    return { reachable };
+  }
 
-    visited.add(from);
+  /**
+   * Weighted shortest path (Dijkstra's algorithm).
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {Object} [options] - Traversal options
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
+   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
+   * @param {AbortSignal} [options.signal] - Abort signal
+   * @returns {Promise<{path: string[], totalCost: number}>}
+   * @throws {TraversalError} code 'NO_PATH' if unreachable
+   * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
+   */
+  async weightedShortestPath(from, to, options = {}) {
+    const { engine, direction, options: opts } = await this._prepare(from, options);
+    const { path, totalCost } = await engine.weightedShortestPath({
+      start: from,
+      goal: to,
+      direction,
+      options: opts,
+      weightFn: options.weightFn,
+      nodeWeightFn: options.nodeWeightFn,
+      maxNodes: Infinity,
+      signal: options.signal,
+    });
+    return { path, totalCost };
+  }
 
-    while (queue.length > 0) {
-      const current = /** @type {{nodeId: string, depth: number}} */ (queue.shift());
-      if (current.depth >= depthLimit) {
-        continue;
-      }
+  /**
+   * A* search with heuristic guidance.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {Object} [options] - Traversal options
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
+   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
+   * @param {(nodeId: string, goalId: string) => number} [options.heuristicFn] - Heuristic function
+   * @param {AbortSignal} [options.signal] - Abort signal
+   * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>}
+   * @throws {TraversalError} code 'NO_PATH' if unreachable
+   * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
+   */
+  async aStarSearch(from, to, options = {}) {
+    const { engine, direction, options: opts } = await this._prepare(from, options);
+    const { path, totalCost, nodesExplored } = await engine.aStarSearch({
+      start: from,
+      goal: to,
+      direction,
+      options: opts,
+      weightFn: options.weightFn,
+      nodeWeightFn: options.nodeWeightFn,
+      heuristicFn: options.heuristicFn,
+      maxNodes: Infinity,
+      signal: options.signal,
+    });
+    return { path, totalCost, nodesExplored };
+  }
 
-      const neighbors = getNeighbors({
-        nodeId: current.nodeId,
-        direction: dir,
-        adjacency,
-        labelSet,
+  /**
+   * Bidirectional A* search.
+   *
+   * Direction is fixed: forward uses 'out', backward uses 'in'.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
+   * @param {Object} [options] - Traversal options
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
+   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
+   * @param {(nodeId: string, goalId: string) => number} [options.forwardHeuristic] - Forward heuristic
+   * @param {(nodeId: string, goalId: string) => number} [options.backwardHeuristic] - Backward heuristic
+   * @param {AbortSignal} [options.signal] - Abort signal
+   * @returns {Promise<{path: string[], totalCost: number, nodesExplored: number}>}
+   * @throws {TraversalError} code 'NO_PATH' if unreachable
+   * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
+   */
+  async bidirectionalAStar(from, to, options = {}) {
+    const { engine, options: opts } = await this._prepareEngine(options);
+
+    if (!(await this._graph.hasNode(from))) {
+      throw new TraversalError(`Start node not found: ${from}`, {
+        code: 'NODE_NOT_FOUND',
+        context: { start: from },
       });
+    }
 
-      for (const edge of neighbors) {
-        if (visited.has(edge.neighborId)) {
-          continue;
-        }
-        visited.add(edge.neighborId);
-        parent.set(edge.neighborId, current.nodeId);
+    const { path, totalCost, nodesExplored } = await engine.bidirectionalAStar({
+      start: from,
+      goal: to,
+      options: opts,
+      weightFn: options.weightFn,
+      nodeWeightFn: options.nodeWeightFn,
+      forwardHeuristic: options.forwardHeuristic,
+      backwardHeuristic: options.backwardHeuristic,
+      maxNodes: Infinity,
+      signal: options.signal,
+    });
+    return { path, totalCost, nodesExplored };
+  }
 
-        if (edge.neighborId === to) {
-          const path = [to];
-          /** @type {string|undefined} */
-          let cursor = current.nodeId;
-          while (cursor) {
-            path.push(cursor);
-            cursor = parent.get(cursor);
-          }
-          path.reverse();
-          return { found: true, path, length: path.length - 1 };
-        }
+  /**
+   * Topological sort (Kahn's algorithm).
+   *
+   * @param {string|string[]} start - One or more start nodes
+   * @param {Object} [options] - Traversal options
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {boolean} [options.throwOnCycle] - Whether to throw on cycle detection
+   * @param {AbortSignal} [options.signal] - Abort signal
+   * @returns {Promise<{sorted: string[], hasCycle: boolean}>}
+   * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if throwOnCycle and cycle found
+   * @throws {TraversalError} code 'NODE_NOT_FOUND' if a start node does not exist
+   */
+  async topologicalSort(start, options = {}) {
+    const { engine, direction, options: opts } = await this._prepareEngine(options);
+
+    // Validate each start node
+    const starts = Array.isArray(start) ? start : [start];
+    for (const s of starts) {
+      if (!(await this._graph.hasNode(s))) {
+        throw new TraversalError(`Start node not found: ${s}`, {
+          code: 'NODE_NOT_FOUND',
+          context: { start: s },
+        });
+      }
+    }
+
+    const { sorted, hasCycle } = await engine.topologicalSort({
+      start,
+      direction,
+      options: opts,
+      maxNodes: Infinity,
+      throwOnCycle: options.throwOnCycle,
+      signal: options.signal,
+    });
+    return { sorted, hasCycle };
+  }
 
-        queue.push({ nodeId: edge.neighborId, depth: current.depth + 1 });
+  /**
+   * Common ancestors — multi-source ancestor intersection.
+   *
+   * Direction is fixed to 'in' (backward BFS).
+   *
+   * @param {string[]} nodes - Nodes to find common ancestors of
+   * @param {Object} [options] - Traversal options
+   * @param {number} [options.maxDepth] - Maximum search depth
+   * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
+   * @param {number} [options.maxResults] - Maximum number of results
+   * @param {AbortSignal} [options.signal] - Abort signal
+   * @returns {Promise<{ancestors: string[]}>}
+   * @throws {TraversalError} code 'NODE_NOT_FOUND' if a node does not exist
+   */
+  async commonAncestors(nodes, options = {}) {
+    const { engine, options: opts, depthLimit } = await this._prepareEngine(options);
+
+    // Validate each node
+    for (const n of nodes) {
+      if (!(await this._graph.hasNode(n))) {
+        throw new TraversalError(`Node not found: ${n}`, {
+          code: 'NODE_NOT_FOUND',
+          context: { node: n },
+        });
       }
     }
 
-    return { found: false, path: [], length: -1 };
+    const { ancestors } = await engine.commonAncestors({
+      nodes,
+      options: opts,
+      maxDepth: depthLimit,
+      maxResults: options.maxResults,
+      signal: options.signal,
+    });
+    return { ancestors };
   }
 
   /**
-   * Connected component (undirected by default).
+   * Weighted longest path via topological sort + DP.
    *
-   * @param {string} start - Starting node ID
+   * Only valid on DAGs.
+   *
+   * @param {string} from - Source node ID
+   * @param {string} to - Target node ID
    * @param {Object} [options] - Traversal options
-   * @param {number} [options.maxDepth] - Maximum depth to traverse (default: 1000)
+   * @param {'out'|'in'|'both'} [options.dir] - Edge direction to follow
    * @param {string|string[]} [options.labelFilter] - Edge label(s) to include
-   * @returns {Promise<string[]>} Node IDs in visit order
-   * @throws {TraversalError} If the start node is not found
+   * @param {(from: string, to: string, label: string) => number | Promise<number>} [options.weightFn] - Edge weight function
+   * @param {(nodeId: string) => number | Promise<number>} [options.nodeWeightFn] - Node weight function (mutually exclusive with weightFn)
+   * @param {AbortSignal} [options.signal] - Abort signal
+   * @returns {Promise<{path: string[], totalCost: number}>}
+   * @throws {TraversalError} code 'ERR_GRAPH_HAS_CYCLES' if graph has cycles
+   * @throws {TraversalError} code 'NO_PATH' if unreachable
+   * @throws {TraversalError} code 'E_WEIGHT_FN_CONFLICT' if both weightFn and nodeWeightFn provided
    */
-  async connectedComponent(start, options = {}) {
-    return await this.bfs(start, { ...options, dir: 'both' });
+  async weightedLongestPath(from, to, options = {}) {
+    const { engine, direction, options: opts } = await this._prepare(from, options);
+    const { path, totalCost } = await engine.weightedLongestPath({
+      start: from,
+      goal: to,
+      direction,
+      options: opts,
+      weightFn: options.weightFn,
+      nodeWeightFn: options.nodeWeightFn,
+      maxNodes: Infinity,
+      signal: options.signal,
+    });
+    return { path, totalCost };
   }
 }