feat(graph): add --open flag for LLM-friendly compact output (GH#3544) (#3778)

* feat(graph): add --open flag for LLM-friendly compact layer output (GH#3544)

Add --open flag to `bd graph` that filters out closed/deferred issues and
renders only actionable items in compact layer format.

Key behaviors:
- Filters to open/in_progress/blocked statuses only
- Computes transitive closure of blocking edges through removed nodes
  (if A blocks B(closed) blocks C, adds synthetic edge A→C)
- Auto-selects compact layer rendering for LLM-friendly output
- Works with both single-issue and --all modes
- Deduplicates edges when direct and transitive paths overlap
- Falls back to highest-priority open issue when root is filtered out

* docs: regenerate CLI reference for --open flag and federation updates
This commit is contained in:
Kevin Glynn 2026-07-14 13:17:30 -04:00 • committed by GitHub
commit f5dd5072b8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 353 additions and 2 deletions

View file

@ -36,6 +36,7 @@ var (
graphAll bool
graphDOT bool
graphHTML bool
graphOpen bool
)
var graphCmd = &cobra.Command{
@ -48,6 +49,7 @@ For epics, shows all children and their dependencies.
For regular issues, shows the issue and its direct dependencies.
With --all, shows all open issues grouped by connected component.
With --open, filters to only open/actionable issues (compact layer format).
Display formats:
(default) DAG with columns and box-drawing edges (terminal-native)
@ -55,6 +57,7 @@ Display formats:
--compact Tree format, one line per issue, more scannable
--dot Graphviz DOT format (pipe to dot -Tsvg > graph.svg)
--html Self-contained interactive HTML with D3.js visualization
--open Open issues only, compact layers (LLM-friendly)
The graph shows execution order:
- Layer 0 / leftmost = no dependencies (can start immediately)
@ -69,7 +72,9 @@ Examples:
bd graph --dot issue-id | dot -Tsvg > graph.svg # SVG via Graphviz
bd graph --dot issue-id | dot -Tpng > graph.png # PNG via Graphviz
bd graph --html issue-id > graph.html # Interactive browser view
bd graph --all --html > all.html # All issues, interactive`,
bd graph --all --html > all.html # All issues, interactive
bd graph --open issue-id # Open issues only, layered by blocking order
bd graph --all --open # All open issues, compact layers`,
Args: cobra.RangeArgs(0, 1),
SilenceUsage: true,
SilenceErrors: true,
@ -103,6 +108,17 @@ Examples:
return HandleErrorRespectJSON("loading all issues: %v", err)
}
if graphOpen {
var filtered []*TemplateSubgraph
for _, sg := range subgraphs {
f := filterSubgraphOpen(sg)
if f != nil && len(f.Issues) > 0 {
filtered = append(filtered, f)
}
}
subgraphs = filtered
}
if len(subgraphs) == 0 {
fmt.Println("No open issues found")
return nil
@ -112,13 +128,24 @@ Examples:
return outputJSON(subgraphs)
}
if graphHTML {
if graphHTML && !graphOpen {
merged := mergeSubgraphsForHTML(subgraphs)
layout := computeLayout(merged)
renderGraphHTML(layout, merged)
return nil
}
if graphOpen {
for i, subgraph := range subgraphs {
layout := computeLayout(subgraph)
renderGraphCompact(layout, subgraph)
if i < len(subgraphs)-1 {
fmt.Println(strings.Repeat("─", 60))
}
}
return nil
}
for i, subgraph := range subgraphs {
layout := computeLayout(subgraph)
if graphDOT {
@ -147,6 +174,14 @@ Examples:
return HandleErrorRespectJSON("loading graph: %v", err)
}
if graphOpen {
subgraph = filterSubgraphOpen(subgraph)
if subgraph == nil || len(subgraph.Issues) == 0 {
fmt.Println("No open issues in subgraph")
return nil
}
}
layout := computeLayout(subgraph)
if jsonOutput {
@ -157,6 +192,11 @@ Examples:
})
}
if graphOpen {
renderGraphCompact(layout, subgraph)
return nil
}
if graphDOT {
renderGraphDOT(layout, subgraph)
} else if graphHTML {
@ -262,6 +302,7 @@ func init() {
graphCmd.Flags().BoolVar(&graphBox, "box", false, "ASCII boxes showing layers")
graphCmd.Flags().BoolVar(&graphDOT, "dot", false, "Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg)")
graphCmd.Flags().BoolVar(&graphHTML, "html", false, "Output self-contained interactive HTML (redirect to file)")
graphCmd.Flags().BoolVar(&graphOpen, "open", false, "Show only open issues (filters out closed/deferred), forces compact layer format")
graphCmd.ValidArgsFunction = issueIDCompletion
rootCmd.AddCommand(graphCmd)
graphCmd.AddCommand(graphCheckCmd)
@ -542,6 +583,130 @@ func loadAllGraphSubgraphs(ctx context.Context, s storage.DoltStorage) ([]*Templ
return subgraphs, nil
}
// isOpenStatus returns true for statuses considered "open" / actionable.
// Closed and deferred (frozen) issues are excluded by --open.
func isOpenStatus(s types.Status) bool {
switch s {
case types.StatusOpen, types.StatusInProgress, types.StatusBlocked:
return true
default:
return false
}
}
// filterSubgraphOpen removes closed/deferred issues from a subgraph and
// computes a transitive closure of blocking edges through removed nodes so
// that indirect blocking relationships are preserved.
//
// Example: if A(open) blocks B(closed) blocks C(open), the filtered graph
// contains A and C with a synthetic edge A→C.
func filterSubgraphOpen(subgraph *TemplateSubgraph) *TemplateSubgraph {
if subgraph == nil {
return nil
}
openSet := make(map[string]bool)
for _, issue := range subgraph.Issues {
if isOpenStatus(issue.Status) {
openSet[issue.ID] = true
}
}
if len(openSet) == 0 {
return nil
}
// Build full blocking graph (all nodes, including closed) for transitive
// closure. blocksAdj: A→B means "A blocks B" (B depends on A).
blocksAdj := make(map[string][]string)
for _, dep := range subgraph.Dependencies {
if dep.Type == types.DepBlocks {
blocksAdj[dep.DependsOnID] = append(blocksAdj[dep.DependsOnID], dep.IssueID)
}
}
// For each open node, BFS forward through the blocking graph to find all
// reachable open nodes. Each such reachable open node has a transitive
// blocking relationship.
type edge struct{ from, to string }
syntheticEdges := make(map[edge]bool)
for src := range openSet {
visited := map[string]bool{src: true}
queue := []string{src}
for len(queue) > 0 {
cur := queue[0]
queue = queue[1:]
for _, next := range blocksAdj[cur] {
if visited[next] {
continue
}
visited[next] = true
if openSet[next] {
syntheticEdges[edge{src, next}] = true
}
if !openSet[next] {
queue = append(queue, next)
}
}
}
}
// Build filtered subgraph
filtered := &TemplateSubgraph{
IssueMap: make(map[string]*types.Issue, len(openSet)),
}
for _, issue := range subgraph.Issues {
if openSet[issue.ID] {
filtered.Issues = append(filtered.Issues, issue)
filtered.IssueMap[issue.ID] = issue
}
}
// Keep non-blocks deps where both ends are open, and rebuild blocks
// deps from the transitive closure.
seen := make(map[edge]bool)
for _, dep := range subgraph.Dependencies {
if !openSet[dep.IssueID] || !openSet[dep.DependsOnID] {
continue
}
if dep.Type == types.DepBlocks {
e := edge{dep.DependsOnID, dep.IssueID}
if !seen[e] {
seen[e] = true
filtered.Dependencies = append(filtered.Dependencies, dep)
}
} else {
filtered.Dependencies = append(filtered.Dependencies, dep)
}
}
// Add synthetic transitive edges
for e := range syntheticEdges {
if seen[e] {
continue
}
seen[e] = true
filtered.Dependencies = append(filtered.Dependencies, &types.Dependency{
IssueID: e.to,
DependsOnID: e.from,
Type: types.DepBlocks,
})
}
// Pick root: prefer original root if still open, else highest-priority open issue
if subgraph.Root != nil && openSet[subgraph.Root.ID] {
filtered.Root = subgraph.Root
} else {
for _, issue := range filtered.Issues {
if filtered.Root == nil || issue.Priority < filtered.Root.Priority {
filtered.Root = issue
}
}
}
return filtered
}
// computeLayout assigns layers to nodes using topological sort
// mergeSubgraphsForHTML joins disconnected components into one subgraph so
// `bd graph --all --html` emits a single valid HTML document.

View file

@ -494,3 +494,179 @@ func TestComputeLayout(t *testing.T) {
}
})
}
func TestFilterSubgraphOpen(t *testing.T) {
t.Run("nil subgraph", func(t *testing.T) {
if filterSubgraphOpen(nil) != nil {
t.Error("expected nil for nil input")
}
})
t.Run("all closed returns nil", func(t *testing.T) {
sg := &TemplateSubgraph{
Root: &types.Issue{ID: "a", Status: types.StatusClosed},
Issues: []*types.Issue{{ID: "a", Status: types.StatusClosed}},
IssueMap: map[string]*types.Issue{
"a": {ID: "a", Status: types.StatusClosed},
},
}
if filterSubgraphOpen(sg) != nil {
t.Error("expected nil when all issues are closed")
}
})
t.Run("removes closed issues", func(t *testing.T) {
open := &types.Issue{ID: "open-1", Title: "Open", Status: types.StatusOpen, Priority: 1}
closed := &types.Issue{ID: "closed-1", Title: "Closed", Status: types.StatusClosed, Priority: 0}
sg := &TemplateSubgraph{
Root: open,
Issues: []*types.Issue{open, closed},
IssueMap: map[string]*types.Issue{
"open-1": open, "closed-1": closed,
},
}
f := filterSubgraphOpen(sg)
if f == nil {
t.Fatal("expected non-nil filtered subgraph")
}
if len(f.Issues) != 1 {
t.Errorf("len(Issues) = %d, want 1", len(f.Issues))
}
if f.Issues[0].ID != "open-1" {
t.Errorf("remaining issue = %q, want open-1", f.Issues[0].ID)
}
})
t.Run("removes deferred issues", func(t *testing.T) {
open := &types.Issue{ID: "open-1", Title: "Open", Status: types.StatusOpen, Priority: 1}
deferred := &types.Issue{ID: "def-1", Title: "Deferred", Status: types.StatusDeferred, Priority: 2}
sg := &TemplateSubgraph{
Root: open,
Issues: []*types.Issue{open, deferred},
IssueMap: map[string]*types.Issue{
"open-1": open, "def-1": deferred,
},
}
f := filterSubgraphOpen(sg)
if len(f.Issues) != 1 || f.Issues[0].ID != "open-1" {
t.Errorf("expected only open-1, got %d issues", len(f.Issues))
}
})
t.Run("transitive closure through closed node", func(t *testing.T) {
// A(open) blocks B(closed) blocks C(open) → synthetic A blocks C
a := &types.Issue{ID: "a", Title: "A", Status: types.StatusOpen, Priority: 1}
b := &types.Issue{ID: "b", Title: "B", Status: types.StatusClosed, Priority: 2}
c := &types.Issue{ID: "c", Title: "C", Status: types.StatusOpen, Priority: 2}
sg := &TemplateSubgraph{
Root: a,
Issues: []*types.Issue{a, b, c},
Dependencies: []*types.Dependency{
{IssueID: "b", DependsOnID: "a", Type: types.DepBlocks},
{IssueID: "c", DependsOnID: "b", Type: types.DepBlocks},
},
IssueMap: map[string]*types.Issue{"a": a, "b": b, "c": c},
}
f := filterSubgraphOpen(sg)
if f == nil {
t.Fatal("expected non-nil")
}
if len(f.Issues) != 2 {
t.Fatalf("expected 2 issues, got %d", len(f.Issues))
}
// Should have a synthetic blocks edge from a→c
foundEdge := false
for _, dep := range f.Dependencies {
if dep.Type == types.DepBlocks && dep.DependsOnID == "a" && dep.IssueID == "c" {
foundEdge = true
}
}
if !foundEdge {
t.Error("expected transitive blocking edge a→c, not found")
}
})
t.Run("preserves direct edges between open nodes", func(t *testing.T) {
a := &types.Issue{ID: "a", Title: "A", Status: types.StatusOpen, Priority: 1}
b := &types.Issue{ID: "b", Title: "B", Status: types.StatusInProgress, Priority: 2}
sg := &TemplateSubgraph{
Root: a,
Issues: []*types.Issue{a, b},
Dependencies: []*types.Dependency{
{IssueID: "b", DependsOnID: "a", Type: types.DepBlocks},
},
IssueMap: map[string]*types.Issue{"a": a, "b": b},
}
f := filterSubgraphOpen(sg)
if len(f.Dependencies) != 1 {
t.Errorf("expected 1 dep, got %d", len(f.Dependencies))
}
})
t.Run("root fallback when root is closed", func(t *testing.T) {
root := &types.Issue{ID: "root", Title: "Root", Status: types.StatusClosed, Priority: 0}
hi := &types.Issue{ID: "hi", Title: "High", Status: types.StatusOpen, Priority: 1}
lo := &types.Issue{ID: "lo", Title: "Low", Status: types.StatusOpen, Priority: 3}
sg := &TemplateSubgraph{
Root: root,
Issues: []*types.Issue{root, hi, lo},
IssueMap: map[string]*types.Issue{
"root": root, "hi": hi, "lo": lo,
},
}
f := filterSubgraphOpen(sg)
if f.Root == nil || f.Root.ID != "hi" {
rootID := "<nil>"
if f.Root != nil {
rootID = f.Root.ID
}
t.Errorf("expected root=hi (highest priority), got %s", rootID)
}
})
t.Run("no duplicate edges", func(t *testing.T) {
// Direct edge a→c exists AND transitive path a→(closed b)→c exists.
// Should produce exactly one blocking edge a→c, not two.
a := &types.Issue{ID: "a", Title: "A", Status: types.StatusOpen, Priority: 1}
b := &types.Issue{ID: "b", Title: "B", Status: types.StatusClosed, Priority: 2}
c := &types.Issue{ID: "c", Title: "C", Status: types.StatusOpen, Priority: 2}
sg := &TemplateSubgraph{
Root: a,
Issues: []*types.Issue{a, b, c},
Dependencies: []*types.Dependency{
{IssueID: "b", DependsOnID: "a", Type: types.DepBlocks},
{IssueID: "c", DependsOnID: "b", Type: types.DepBlocks},
{IssueID: "c", DependsOnID: "a", Type: types.DepBlocks},
},
IssueMap: map[string]*types.Issue{"a": a, "b": b, "c": c},
}
f := filterSubgraphOpen(sg)
blockCount := 0
for _, dep := range f.Dependencies {
if dep.Type == types.DepBlocks && dep.DependsOnID == "a" && dep.IssueID == "c" {
blockCount++
}
}
if blockCount != 1 {
t.Errorf("expected exactly 1 blocking edge a→c, got %d", blockCount)
}
})
t.Run("preserves non-blocks deps between open nodes", func(t *testing.T) {
a := &types.Issue{ID: "a", Title: "A", Status: types.StatusOpen, Priority: 1}
b := &types.Issue{ID: "b", Title: "B", Status: types.StatusOpen, Priority: 2}
sg := &TemplateSubgraph{
Root: a,
Issues: []*types.Issue{a, b},
Dependencies: []*types.Dependency{
{IssueID: "b", DependsOnID: "a", Type: types.DepParentChild},
},
IssueMap: map[string]*types.Issue{"a": a, "b": b},
}
f := filterSubgraphOpen(sg)
if len(f.Dependencies) != 1 || f.Dependencies[0].Type != types.DepParentChild {
t.Error("expected parent-child dep to be preserved")
}
})
}

View file

@ -2148,6 +2148,7 @@ For epics, shows all children and their dependencies.
For regular issues, shows the issue and its direct dependencies.
With --all, shows all open issues grouped by connected component.
With --open, filters to only open/actionable issues (compact layer format).
Display formats:
(default) DAG with columns and box-drawing edges (terminal-native)
@ -2155,6 +2156,7 @@ Display formats:
--compact Tree format, one line per issue, more scannable
--dot Graphviz DOT format (pipe to dot -Tsvg &gt; graph.svg)
--html Self-contained interactive HTML with D3.js visualization
--open Open issues only, compact layers (LLM-friendly)
The graph shows execution order:
- Layer 0 / leftmost = no dependencies (can start immediately)
@ -2170,6 +2172,8 @@ Examples:
bd graph --dot issue-id | dot -Tpng &gt; graph.png # PNG via Graphviz
bd graph --html issue-id &gt; graph.html # Interactive browser view
bd graph --all --html &gt; all.html # All issues, interactive
bd graph --open issue-id # Open issues only, layered by blocking order
bd graph --all --open # All open issues, compact layers
```
bd graph [issue-id] [flags]
@ -2184,6 +2188,7 @@ bd graph [command]
--compact Tree format, one line per issue, more scannable
--dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg)
--html Output self-contained interactive HTML (redirect to file)
--open Show only open issues (filters out closed/deferred), forces compact layer format
```
#### bd graph check

View file

@ -13,6 +13,7 @@ For epics, shows all children and their dependencies.
For regular issues, shows the issue and its direct dependencies.
With --all, shows all open issues grouped by connected component.
With --open, filters to only open/actionable issues (compact layer format).
Display formats:
(default) DAG with columns and box-drawing edges (terminal-native)
@ -20,6 +21,7 @@ Display formats:
--compact Tree format, one line per issue, more scannable
--dot Graphviz DOT format (pipe to dot -Tsvg &gt; graph.svg)
--html Self-contained interactive HTML with D3.js visualization
--open Open issues only, compact layers (LLM-friendly)
The graph shows execution order:
- Layer 0 / leftmost = no dependencies (can start immediately)
@ -35,6 +37,8 @@ Examples:
bd graph --dot issue-id | dot -Tpng &gt; graph.png # PNG via Graphviz
bd graph --html issue-id &gt; graph.html # Interactive browser view
bd graph --all --html &gt; all.html # All issues, interactive
bd graph --open issue-id # Open issues only, layered by blocking order
bd graph --all --open # All open issues, compact layers
```
bd graph [issue-id] [flags]
@ -49,6 +53,7 @@ bd graph [command]
--compact Tree format, one line per issue, more scannable
--dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg)
--html Output self-contained interactive HTML (redirect to file)
--open Show only open issues (filters out closed/deferred), forces compact layer format
```
## bd graph check