Unify detail flag and add traversal depth controls

Author: cailmdaley

CLAUDE.md

@@ -24,7 +24,7 @@ Fibers are minimal by default. All fields except title are optional.
 
 **Status is opt-in.** `felt add "title"` creates a statusless fiber. `felt add "title" -s open` enters tracking. `felt edit <id> -s active` enters tracking. `felt ls` only shows tracked fibers.
 
-**Progressive disclosure.** `felt show <id> -d compact` shows metadata + outcome without body. Levels: title, compact, summary, full (default). `felt upstream/downstream <id> -d compact` renders each connected fiber at that depth.
+**Progressive disclosure.** `felt show <id> -d compact` shows metadata + outcome without body. Levels: title, compact, summary, full (default). `felt upstream/downstream <id> -d compact` renders each connected fiber at that detail level.
 
 **Backward compat:** `close-reason` reads as `outcome`, `kind` reads as a tag. Both migrate on next write.
 

README.md

@@ -77,7 +77,7 @@ felt show <id> -d compact     # see outcome without full body
 
 ### Progressive Disclosure
 
-`felt show` supports depth levels via `--depth` / `-d`:
+`felt show` supports detail levels via `--detail` / `-d`:
 
 | Level | What you see |
 |---|---|

cmd/graph.go

@@ -8,8 +8,9 @@ import (
 )
 
 var (
-	graphFormat string
-	upDownDepth string
+	graphFormat  string
+	upDownDetail string
+	traversalAll bool
 )
 
 var graphCmd = &cobra.Command{
@@ -54,27 +55,43 @@ var graphCmd = &cobra.Command{
 var upstreamCmd = &cobra.Command{
 	Use:   "upstream <id>",
 	Short: "Show what a felt depends on",
-	Long:  `Lists all transitive dependencies of a felt. Use --depth to control detail per item.`,
-	Args:  cobra.ExactArgs(1),
+	Long: `Lists dependencies of a felt.
+
+By default shows direct dependencies only (depth 1).
+Use --all for the full transitive closure (all ancestors).
+Use -d/--detail to control detail level per item.`,
+	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
+		depth := 1
+		if traversalAll {
+			depth = 0
+		}
 		return runTraversal(args[0], traversalConfig{
-			getRelated:  func(g *felt.Graph, id string) []string { return g.GetUpstream(id) },
-			edgeLabel:   func(g *felt.Graph, fiberID, relatedID string) string { return edgeLabelInGraph(g, relatedID, fiberID) },
-			emptyMsg:    "No dependencies",
+			getRelated: func(g *felt.Graph, id string) []string { return g.GetUpstreamN(id, depth) },
+			edgeLabel:  func(g *felt.Graph, fiberID, relatedID string) string { return edgeLabelInGraph(g, relatedID, fiberID) },
+			emptyMsg:   "No dependencies",
 		})
 	},
 }
 
 var downstreamCmd = &cobra.Command{
 	Use:   "downstream <id>",
 	Short: "Show what depends on a felt",
-	Long:  `Lists all felts that transitively depend on this one. Use --depth to control detail per item.`,
-	Args:  cobra.ExactArgs(1),
+	Long: `Lists felts that depend on this one.
+
+By default shows direct dependents only (depth 1).
+Use --all for the full transitive closure (all descendants).
+Use -d/--detail to control detail level per item.`,
+	Args: cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
+		depth := 1
+		if traversalAll {
+			depth = 0
+		}
 		return runTraversal(args[0], traversalConfig{
-			getRelated:  func(g *felt.Graph, id string) []string { return g.GetDownstream(id) },
-			edgeLabel:   func(g *felt.Graph, fiberID, relatedID string) string { return edgeLabelInGraph(g, fiberID, relatedID) },
-			emptyMsg:    "Nothing depends on this",
+			getRelated: func(g *felt.Graph, id string) []string { return g.GetDownstreamN(id, depth) },
+			edgeLabel:  func(g *felt.Graph, fiberID, relatedID string) string { return edgeLabelInGraph(g, fiberID, relatedID) },
+			emptyMsg:   "Nothing depends on this",
 		})
 	},
 }
@@ -93,8 +110,8 @@ func runTraversal(fiberArg string, cfg traversalConfig) error {
 		return fmt.Errorf("not in a felt repository")
 	}
 
-	if upDownDepth != "" {
-		if err := validateDepth(upDownDepth); err != nil {
+	if upDownDetail != "" {
+		if err := validateDepth(upDownDetail); err != nil {
 			return err
 		}
 	}
@@ -129,12 +146,12 @@ func runTraversal(fiberArg string, cfg traversalConfig) error {
 	}
 
 	// Depth-aware rendering
-	if upDownDepth != "" {
+	if upDownDetail != "" {
 		for i, id := range related {
 			dep := g.Nodes[id]
 			if dep != nil {
-				fmt.Print(renderFelt(dep, g, upDownDepth))
-				if upDownDepth != DepthTitle && i < len(related)-1 {
+				fmt.Print(renderFelt(dep, g, upDownDetail))
+				if upDownDetail != DepthTitle && i < len(related)-1 {
 					fmt.Println()
 				}
 			}
@@ -261,6 +278,8 @@ func init() {
 	rootCmd.AddCommand(checkCmd)
 
 	graphCmd.Flags().StringVarP(&graphFormat, "format", "f", "mermaid", "Output format (mermaid, dot, text)")
-	upstreamCmd.Flags().StringVarP(&upDownDepth, "depth", "d", "", "Detail level per item (title, compact, summary, full)")
-	downstreamCmd.Flags().StringVarP(&upDownDepth, "depth", "d", "", "Detail level per item (title, compact, summary, full)")
+	upstreamCmd.Flags().StringVarP(&upDownDetail, "detail", "d", "", "Detail level per item (title, compact, summary, full)")
+	downstreamCmd.Flags().StringVarP(&upDownDetail, "detail", "d", "", "Detail level per item (title, compact, summary, full)")
+	upstreamCmd.Flags().BoolVar(&traversalAll, "all", false, "Traverse full transitive closure (all ancestors)")
+	downstreamCmd.Flags().BoolVar(&traversalAll, "all", false, "Traverse full transitive closure (all descendants)")
 }

cmd/hook.go

@@ -223,12 +223,16 @@ felt show <id> -d compact       # metadata + outcome only
 felt ls                         # tracked fibers (open/active)
 felt ls -t tapestry:            # any filter widens to all statuses
 felt ls -s closed "query"       # explicit -s overrides; -e exact, -r regex
-felt upstream/downstream <id>   # DAG traversal
--d title|compact|summary|full   # depth for show, ls, upstream, downstream
-Also: link, unlink, tag, untag, tree, ready, rm
+felt upstream <id>               # direct dependencies
+felt upstream <id> -d summary    # with summaries
+felt upstream <id> --all         # full transitive closure
+felt downstream <id>             # direct dependents
+felt downstream <id> -d summary  # with summaries
+felt downstream <id> --all       # full transitive closure
+Also: link, unlink, tag, untag, path, tree, ready, rm
 ` + "```" + `
 Statuses: · untracked, ○ open, ◐ active, ● closed
-Depth: title < compact < summary < full (default). Summary shows the **lede** — the first paragraph of the body. Write it to stand alone.
+Detail: title < compact < summary < full (default). Summary shows the **lede** — the first paragraph of the body. Write it to stand alone.
 To patch body text (not replace), edit .felt/<id>.md directly.
 
 `

cmd/integration_test.go

@@ -153,6 +153,31 @@ func TestIntegration(t *testing.T) {
 	if !strings.Contains(out, "second fiber") {
 		t.Fatalf("downstream: expected child fiber, got: %s", out)
 	}
+	fiber3ID := strings.TrimSpace(mustFelt(t, dir, "add", "third fiber", "-s", "open"))
+	if fiber3ID == "" {
+		t.Fatal("add: expected fiber3 ID")
+	}
+	mustFelt(t, dir, "link", fiber3ID, fiber2ID)
+
+	// Traversal defaults to direct neighbors only.
+	out = mustFelt(t, dir, "downstream", fiberID)
+	if strings.Contains(out, "third fiber") {
+		t.Fatalf("downstream default: expected direct dependents only, got: %s", out)
+	}
+	// --all includes transitive dependents.
+	out = mustFelt(t, dir, "downstream", fiberID, "--all")
+	if !strings.Contains(out, "second fiber") || !strings.Contains(out, "third fiber") {
+		t.Fatalf("downstream --all: expected transitive closure, got: %s", out)
+	}
+
+	out = mustFelt(t, dir, "upstream", fiber3ID)
+	if strings.Contains(out, "test fiber") || !strings.Contains(out, "second fiber") {
+		t.Fatalf("upstream default: expected direct dependencies only, got: %s", out)
+	}
+	out = mustFelt(t, dir, "upstream", fiber3ID, "--all")
+	if !strings.Contains(out, "second fiber") || !strings.Contains(out, "test fiber") {
+		t.Fatalf("upstream --all: expected transitive closure, got: %s", out)
+	}
 
 	// tag and untag
 	mustFelt(t, dir, "tag", fiber2ID, "testlabel")
@@ -166,6 +191,7 @@ func TestIntegration(t *testing.T) {
 	mustFelt(t, dir, "ready")
 
 	// rm --force
+	mustFelt(t, dir, "rm", "--force", fiber3ID)
 	mustFelt(t, dir, "rm", "--force", fiber2ID)
 	lsOut := mustFelt(t, dir, "ls", "-s", "all")
 	if strings.Contains(lsOut, "second fiber") {

cmd/show.go

@@ -9,15 +9,15 @@ import (
 
 var (
 	showBodyOnly bool
-	showDepth    string
+	showDetail   string
 )
 
 var showCmd = &cobra.Command{
 	Use:   "show <id>",
 	Short: "Show details of a felt",
-	Long: `Displays details of a felt at the requested depth level.
+	Long: `Displays details of a felt at the requested detail level.
 
-Depth levels control progressive disclosure:
+Detail levels control progressive disclosure:
   title    Title and tags only
   compact  Structured overview: metadata, outcome, dependency IDs
   summary  Compact + lede paragraph + dependency titles
@@ -29,11 +29,11 @@ Depth levels control progressive disclosure:
 			return fmt.Errorf("not in a felt repository")
 		}
 
-		depth := showDepth
-		if depth == "" {
-			depth = DepthFull
+		detail := showDetail
+		if detail == "" {
+			detail = DepthFull
 		}
-		if err := validateDepth(depth); err != nil {
+		if err := validateDepth(detail); err != nil {
 			return err
 		}
 
@@ -60,13 +60,13 @@ Depth levels control progressive disclosure:
 		}
 		graph := felt.BuildGraph(felts)
 
-		fmt.Print(renderFelt(f, graph, depth))
+		fmt.Print(renderFelt(f, graph, detail))
 		return nil
 	},
 }
 
 func init() {
 	rootCmd.AddCommand(showCmd)
 	showCmd.Flags().BoolVarP(&showBodyOnly, "body", "b", false, "Output only the body (for piping)")
-	showCmd.Flags().StringVarP(&showDepth, "depth", "d", "", "Detail level (title, compact, summary, full)")
+	showCmd.Flags().StringVarP(&showDetail, "detail", "d", "", "Detail level (title, compact, summary, full)")
 }

docs/README.md

@@ -62,7 +62,7 @@ felt show <id> -d compact     # see outcome without full body
 
 ### Progressive Disclosure
 
-`felt show` supports depth levels via `--depth` / `-d`:
+`felt show` supports detail levels via `--detail` / `-d`:
 
 | Level | What you see |
 |---|---|

internal/felt/graph.go

@@ -40,35 +40,59 @@ func BuildGraph(felts []*Felt) *Graph {
 // GetUpstream returns all transitive dependencies of the given ID.
 // Uses BFS for level-order traversal.
 func (g *Graph) GetUpstream(id string) []string {
-	return g.bfs(id, g.Upstream)
+	return g.bfs(id, g.Upstream, 0)
 }
 
 // GetDownstream returns all nodes that transitively depend on the given ID.
 // Uses BFS for level-order traversal.
 func (g *Graph) GetDownstream(id string) []string {
-	return g.bfs(id, g.Downstream)
+	return g.bfs(id, g.Downstream, 0)
+}
+
+// GetUpstreamN returns dependencies up to maxLevels deep.
+// maxLevels=1 returns direct dependencies only.
+// maxLevels=0 returns the full transitive closure (same as GetUpstream).
+func (g *Graph) GetUpstreamN(id string, maxLevels int) []string {
+	return g.bfs(id, g.Upstream, maxLevels)
+}
+
+// GetDownstreamN returns dependents up to maxLevels deep.
+// maxLevels=1 returns direct dependents only.
+// maxLevels=0 returns the full transitive closure (same as GetDownstream).
+func (g *Graph) GetDownstreamN(id string, maxLevels int) []string {
+	return g.bfs(id, g.Downstream, maxLevels)
 }
 
 // bfs performs breadth-first traversal from start using the given adjacency map.
-func (g *Graph) bfs(start string, adj map[string]Dependencies) []string {
+// maxLevels controls how many levels to traverse (0 = unlimited).
+func (g *Graph) bfs(start string, adj map[string]Dependencies, maxLevels int) []string {
+	type entry struct {
+		id    string
+		level int
+	}
 	visited := make(map[string]bool)
 	var result []string
-	queue := []string{start}
+	queue := []entry{{id: start, level: 0}}
 	visited[start] = true
 
 	for len(queue) > 0 {
 		current := queue[0]
 		queue = queue[1:]
 
 		// Don't include start in result
-		if current != start {
-			result = append(result, current)
+		if current.id != start {
+			result = append(result, current.id)
+		}
+
+		// Stop expanding if we've reached the max depth
+		if maxLevels > 0 && current.level >= maxLevels {
+			continue
 		}
 
-		for _, dep := range adj[current] {
+		for _, dep := range adj[current.id] {
 			if !visited[dep.ID] {
 				visited[dep.ID] = true
-				queue = append(queue, dep.ID)
+				queue = append(queue, entry{id: dep.ID, level: current.level + 1})
 			}
 		}
 	}