Add start vertex support to topological sort

eosfor · eosfor · commit ae46694ea706 · 2026-05-17T22:21:30.000-07:00
Allow Get-GraphTopologicalSort to limit sorting to the subgraph reachable from a provided StartVertex. The cmdlet now canonicalizes the start vertex against the graph, builds a reachable subgraph by following outgoing edges, and applies the existing forward/reverse topological ordering to that subgraph only.

This makes reverse topological traversal usable for computation graphs where callers want to backpropagate from a selected output vertex while ignoring independent graph components. Unreachable cycles no longer block StartVertex-scoped sorting, while cycles reachable from the start vertex still fail as before.

Add tests for reachable ordering, reverse ordering, missing start vertices, and unreachable cycles. Update the Get-GraphTopologicalSort documentation with the new parameter and example.
diff --git a/PSGraph.Tests/GetGraphTopologicalSortTests.cs b/PSGraph.Tests/GetGraphTopologicalSortTests.cs
@@ -114,6 +114,88 @@ public void GetGraphTopologicalSort_NonUniqueLabels_ReturnsDistinctVertices()
             AssertTopologicalOrder(graph, vertices!);
         }
 
+        [Fact]
+        public void GetGraphTopologicalSort_StartVertex_ReturnsReachableVerticesInTopologicalOrder()
+        {
+            var graph = CreateDiamondGraph();
+            var x = new PSVertex("X");
+            var y = new PSVertex("Y");
+            graph.AddVerticesAndEdge(new PSEdge(x, y));
+
+            var startVertex = graph.Vertices.Single(vertex => vertex.Label == "B");
+
+            _powershell.AddCommand("Get-GraphTopologicalSort")
+                .AddParameter("Graph", graph)
+                .AddParameter("StartVertex", startVertex);
+
+            var results = _powershell.Invoke();
+
+            var vertices = results.Select(result => result.BaseObject as PSVertex).ToList();
+            vertices.Should().Equal(
+                startVertex,
+                graph.Vertices.Single(vertex => vertex.Label == "D"));
+            AssertTopologicalOrder(graph, vertices!);
+        }
+
+        [Fact]
+        public void GetGraphTopologicalSort_StartVertexReverse_ReturnsReachableVerticesInReverseTopologicalOrder()
+        {
+            var graph = CreateDiamondGraph();
+            var startVertex = graph.Vertices.Single(vertex => vertex.Label == "A");
+
+            _powershell.AddCommand("Get-GraphTopologicalSort")
+                .AddParameter("Graph", graph)
+                .AddParameter("StartVertex", startVertex)
+                .AddParameter("Reverse");
+
+            var results = _powershell.Invoke();
+
+            var vertices = results.Select(result => result.BaseObject as PSVertex).ToList();
+            vertices.Should().HaveCount(4);
+            vertices.Last().Should().Be(startVertex);
+            AssertReverseTopologicalOrder(graph, vertices!);
+        }
+
+        [Fact]
+        public void GetGraphTopologicalSort_StartVertex_ThrowsWhenVertexIsNotInGraph()
+        {
+            var graph = CreateDiamondGraph();
+            var startVertex = new PSVertex("X");
+
+            _powershell.AddCommand("Get-GraphTopologicalSort")
+                .AddParameter("Graph", graph)
+                .AddParameter("StartVertex", startVertex);
+
+            Action act = () => _powershell.Invoke();
+
+            act.Should().Throw<CmdletInvocationException>()
+                .WithMessage("*The graph does not contain the provided start vertex*");
+        }
+
+        [Fact]
+        public void GetGraphTopologicalSort_StartVertex_IgnoresUnreachableCycle()
+        {
+            var graph = CreateDiamondGraph();
+            var x = new PSVertex("X");
+            var y = new PSVertex("Y");
+            graph.AddVerticesAndEdge(new PSEdge(x, y));
+            graph.AddVerticesAndEdge(new PSEdge(y, x));
+
+            var startVertex = graph.Vertices.Single(vertex => vertex.Label == "A");
+
+            _powershell.AddCommand("Get-GraphTopologicalSort")
+                .AddParameter("Graph", graph)
+                .AddParameter("StartVertex", startVertex);
+
+            var results = _powershell.Invoke();
+
+            var vertices = results.Select(result => result.BaseObject as PSVertex).ToList();
+            vertices.Should().HaveCount(4);
+            vertices.Should().NotContain(vertex => vertex!.Label == "X");
+            vertices.Should().NotContain(vertex => vertex!.Label == "Y");
+            AssertTopologicalOrder(graph, vertices!);
+        }
+
         private static PsBidirectionalGraph CreateDiamondGraph()
         {
             var graph = new PsBidirectionalGraph();
@@ -137,6 +219,11 @@ private static void AssertTopologicalOrder(PsBidirectionalGraph graph, IList<PSV
 
             foreach (var edge in graph.Edges)
             {
+                if (!index.ContainsKey(edge.Source) || !index.ContainsKey(edge.Target))
+                {
+                    continue;
+                }
+
                 index[edge.Source].Should().BeLessThan(index[edge.Target]);
             }
         }
@@ -148,6 +235,11 @@ private static void AssertReverseTopologicalOrder(PsBidirectionalGraph graph, IL
 
             foreach (var edge in graph.Edges)
             {
+                if (!index.ContainsKey(edge.Source) || !index.ContainsKey(edge.Target))
+                {
+                    continue;
+                }
+
                 index[edge.Target].Should().BeLessThan(index[edge.Source]);
             }
         }
diff --git a/PSGraph/cmdlets/graph/GetGraphTopologicalSortCmdlet.cs b/PSGraph/cmdlets/graph/GetGraphTopologicalSortCmdlet.cs
@@ -1,4 +1,6 @@
 using System;
+using System.Collections.Generic;
+using System.Linq;
 using System.Management.Automation;
 using PSGraph.Model;
 using QuikGraph.Algorithms;
@@ -16,23 +18,82 @@ public class GetGraphTopologicalSortCmdlet : PSCmdlet
     [Parameter(Mandatory = false)]
     public SwitchParameter Reverse { get; set; }
 
+    [Parameter(Mandatory = false)]
+    [ValidateNotNull]
+    public PSVertex? StartVertex { get; set; }
+
     protected override void ProcessRecord()
     {
-        if (!Graph.IsDag)
+        var graphToSort = StartVertex is null
+            ? Graph
+            : CreateReachableSubgraph(StartVertex);
+
+        if (!graphToSort.IsDag)
         {
             ThrowTerminatingError(new ErrorRecord(
                 new InvalidOperationException("Topological sort requires a directed acyclic graph."),
                 "GraphContainsCycle",
                 ErrorCategory.InvalidData,
-                Graph));
+                graphToSort));
             return;
         }
 
         var direction = Reverse.IsPresent
             ? TopologicalSortDirection.Backward
             : TopologicalSortDirection.Forward;
 
-        var sortedVertices = Graph.SourceFirstBidirectionalTopologicalSort(direction);
+        var sortedVertices = graphToSort.SourceFirstBidirectionalTopologicalSort(direction);
         WriteObject(sortedVertices, enumerateCollection: true);
     }
+
+    private PsBidirectionalGraph CreateReachableSubgraph(PSVertex startVertex)
+    {
+        var canonicalStartVertex = Graph.Vertices.FirstOrDefault(v => v.Equals(startVertex));
+        if (canonicalStartVertex is null)
+        {
+            ThrowTerminatingError(new ErrorRecord(
+                new InvalidOperationException("The graph does not contain the provided start vertex."),
+                "StartVertexNotFound",
+                ErrorCategory.ObjectNotFound,
+                startVertex));
+            return new PsBidirectionalGraph(Graph.AllowParallelEdges, Graph.UseNonUniqueLabels);
+        }
+
+        var reachableVertices = GetReachableVertices(canonicalStartVertex);
+        var subgraph = new PsBidirectionalGraph(Graph.AllowParallelEdges, Graph.UseNonUniqueLabels);
+        subgraph.AddVertexRange(reachableVertices);
+        subgraph.AddEdgeRange(Graph.Edges.Where(edge =>
+            reachableVertices.Contains(edge.Source) &&
+            reachableVertices.Contains(edge.Target)));
+
+        return subgraph;
+    }
+
+    private HashSet<PSVertex> GetReachableVertices(PSVertex startVertex)
+    {
+        var reachableVertices = new HashSet<PSVertex>();
+        var pendingVertices = new Stack<PSVertex>();
+        pendingVertices.Push(startVertex);
+
+        while (pendingVertices.Count > 0)
+        {
+            var currentVertex = pendingVertices.Pop();
+            if (!reachableVertices.Add(currentVertex))
+            {
+                continue;
+            }
+
+            if (!Graph.TryGetOutEdges(currentVertex, out var outEdges))
+            {
+                continue;
+            }
+
+            foreach (var edge in outEdges)
+            {
+                pendingVertices.Push(edge.Target);
+            }
+        }
+
+        return reachableVertices;
+    }
 }
diff --git a/docs/Get-GraphTopologicalSort.md b/docs/Get-GraphTopologicalSort.md
@@ -13,7 +13,7 @@ Return vertices from a directed acyclic graph in topological order.
 ## SYNTAX
 
 ```
-Get-GraphTopologicalSort -Graph <PsBidirectionalGraph> [-Reverse] [-ProgressAction <ActionPreference>] [<CommonParameters>]
+Get-GraphTopologicalSort -Graph <PsBidirectionalGraph> [-Reverse] [-StartVertex <PSVertex>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -27,6 +27,9 @@ positions as long as every edge preserves the source-before-target constraint.
 If the graph contains a cycle, the cmdlet writes a terminating error. Use DSM sequencing or
 condensation algorithms when cyclic components need to be grouped before ordering.
 
+When `-StartVertex` is specified, the cmdlet sorts only the vertices reachable from that vertex
+by outgoing edges. Cycles outside the reachable subgraph do not affect the result.
+
 ## EXAMPLES
 
 ### Example 1
@@ -56,6 +59,24 @@ Get-GraphTopologicalSort -Graph $g -Reverse | ForEach-Object Name
 ```
 
 ### Example 3
+Sort only the reachable subgraph from a start vertex.
+
+```powershell
+$g = New-Graph
+$a = Add-Vertex -Vertex A -Graph $g
+$b = Add-Vertex -Vertex B -Graph $g
+$c = Add-Vertex -Vertex C -Graph $g
+$x = Add-Vertex -Vertex X -Graph $g
+
+Add-Edge -From $a -To $b -Graph $g | Out-Null
+Add-Edge -From $b -To $c -Graph $g | Out-Null
+
+Get-GraphTopologicalSort -Graph $g -StartVertex $b | ForEach-Object Name
+```
+
+The command returns `B`, then `C`. The independent vertex `X` is not emitted.
+
+### Example 4
 Cycles are rejected.
 
 ```powershell
@@ -85,6 +106,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -StartVertex
+Optional vertex that limits the sort to the subgraph reachable from that vertex by outgoing edges.
+
+```yaml
+Type: PSVertex
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Reverse
 Return a valid reverse topological ordering, where targets appear before sources.
 
