Interactive Code Graph — Focused Entry-Point View with Force-Directed Layout (#196)

---

User Story: Focused Entry-Point Graph View

Story ID: GH-196
Epic: Phase 1 — Visual Developer Interface
Priority: High
Story Points: 5
Sprint Fit: Medium — Sprint G (depends on GH-193 file-level canvas)

Note: This story replaces the "show all files in a grid" default with a focused, entry-point-driven view that is the core "wow factor" of the dependency graph.

Problem

The current graph dumps every file in the repository (426 nodes for code-compress) into a naive grid. This produces an unreadable wall regardless of screen size. The grid has no semantic meaning — spatially adjacent nodes share no relationship.

A dependency graph only becomes useful when:

1. Position conveys information (force-directed: tightly-coupled nodes cluster, isolated ones spread)
2. The view is scoped to a meaningful starting point (not the entire codebase at once)

Story Statement

As a developer using the dependency graph,
I want to search for a file (e.g. an API controller or service class) and see its N-hop dependency neighbourhood rendered with force-directed layout,
So that I can visually understand the coupling and blast radius of that component without cognitive overload.

Acceptance Criteria

Scenario: Default graph view shows an entry-point selector, not all files
  Given a user navigates to /repo/{id}/graph
  Then they see a search box prompting "Search for a file to explore…"
  And no diagram canvas is rendered yet
  And a "Show full graph" secondary option is available

Scenario: Searching selects an entry point and renders a focused subgraph
  Given the user types a filename fragment into the entry-point search box
  When they select a result (e.g. "AccountController.cs")
  Then the canvas renders a subgraph of that file + its 1-hop and 2-hop dependencies
  And the total node count is capped at 60
  And nodes are positioned using force-directed layout (not a grid)

Scenario: Hop depth is adjustable
  Given a focused subgraph is displayed
  When the user changes the hop depth control from 2 to 1
  Then only the direct dependencies of the entry-point file are shown
  When they change to 3
  Then transitive dependencies up to 3 hops are included (still capped at 60)

Scenario: The entry-point node is visually distinguished
  Given a focused subgraph is displayed
  Then the entry-point file node has a distinct visual treatment (accent ring or highlight)
  And it is centred in the layout

Scenario: Full graph mode is available as an opt-in
  Given a user clicks "Show full graph"
  Then all files are rendered (existing behaviour)
  And a warning badge shows the node count
  And a "Back to search" button returns to the entry-point view

Scenario: Language filters narrow the visible nodes
  Given a focused or full graph is displayed
  When the user clicks a language filter chip (e.g. ".cs only")
  Then nodes of other extension types are hidden
  And their edges are also hidden
  And the layout reflows to fill the space

Technical Notes

Entry-point search:

• Reuse IIndexFacade.SearchSymbolsAsync or add IIndexFacade.SearchFilesAsync (search by relative path fragment)
• Render results in a BbCombobox or simple dropdown — select fires OnParametersSetAsync equivalent
• Store selected file path in component state; trigger subgraph load

Subgraph construction:

• Add GraphDataService.GetNeighbourhoodAsync(string filePath, int hops, int maxNodes)
• Performs BFS from the entry-point file over the dependency edges returned by IIndexFacade.GetDependencyGraphAsync
• Caps at maxNodes by pruning lowest-degree nodes at the frontier
• Returns (IReadOnlyList<FileNodeViewModel> Nodes, IReadOnlyList<EdgeViewModel> Edges)

Force-directed layout:

• Check Z.Blazor.Diagrams.Algorithms for a built-in layout — if present, use it
• If not, implement a simple Fruchterman-Reingold pass in DiagramBuilder (pure C#, ~80 lines, no JS)
• Apply layout after SuspendRefresh, before Refresh()
• Entry-point node pinned at centre (IsLocked = true)

Language filter chips:

• IReadOnlyList<string> _activeExtensions state in Graph.razor
• Filter chips rendered in the toolbar (one per distinct extension in the current graph)
• On toggle: rebuild diagram from cached ViewModels filtered by extension

DiagramBuilder changes:

• Build signature unchanged (backwards compatible)
• New overload: Build(nodes, edges, FileNodeViewModel? centreNode = null) — uses force layout when centreNode is set, grid layout when null (full-graph fallback)

Dependencies

Dependency	Status
GH-193 File-Level Canvas	Done
GH-194 Symbol Drill-Down	Independent — can ship before or after

Out of Scope

• Symbol-level nodes (GH-194)
• Saving/sharing a specific graph view
• Graph export (PNG/SVG)
• Cross-repo dependency edges

Definition of Done

• Default graph route shows entry-point search, not a full grid
• GraphDataService.GetNeighbourhoodAsync implemented with BFS + cap
• Force-directed (or Z.Blazor.Diagrams.Algorithms) layout applied to focused subgraphs
• Entry-point node visually distinguished and centred
• Hop depth control (1–3) in toolbar
• Language filter chips in toolbar
• Full-graph opt-in with node count warning
• bUnit tests: neighbourhood BFS, cap behaviour, filter logic
• SonarAnalyzer passes with zero warnings

---

Start by reading Graph.razor, DiagramBuilder, and GraphDataService, then inspect the IIndexFacade dependency-graph and search APIs. Use the stated acceptance criteria and bUnit coverage requirements to verify the focused view, BFS cap, layout, hop control, filters, and full-graph fallback are complete.