diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index 33fcd680..07c3c56d 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -324,6 +324,18 @@ Plan: `docs/intent/symbol-graph/`. Backlog area `area-symbol-graph` in `pgm/data | Folder contents on graph boxes (children by LOC as a colored strip; "Largest inside" in the hover card) | `viz/deps/metrics.ts` (`viewContents`, `stripSegments`); `ContentsStrip` and `NodeCard` in `viz/deps/DependencyCanvas.tsx` | | Local dependency-graph fixtures for layout tests (gitignored `__fixtures__/local/`) | `scripts/capture-dep-graph.sh` | +Graph legibility rules (keep these when you change the layout or canvas): + +- Speed comes first. No legibility change may slow loading, focus or drill. +- Every box is one uniform grid cell. A box never spans rows, because the router needs free gutters from end to end. A folder shows its size with a bar and summary lines inside its cell. +- `rankPackings` packs a mid-level view to the viewport's shape (aspect within 0.5–2×), not into a long strip. +- Neighbors group by package or folder, then by owning file, from the hierarchy, not from clustering. Each group is contiguous in its column with a labeled frame. Ordering runs per group first, then inside the group. +- A file that exports one used symbol draws as that symbol, with the file name as quiet context. +- Color and LOC join on the client by `absPath` against the treemap tree (`metrics.ts`). The graph payload carries no metrics. A metric switch re-tints without relayout. A box with no treemap match gets a neutral fill and no LOC. +- Edge bundles spread by edge count (`bundleOffsets` in `layout.ts`), capped so a large trunk stays one trunk. +- Compare mode shares `layoutViewSync`, so its tests must stay green after a layout change. +- Commit no private repository's graph JSON. Use srcly's own fixture, small synthetic graphs, or the gitignored local fixtures. + ### Client: UI primitives | Primitive | Where | diff --git a/docs/initiative-history.json b/docs/initiative-history.json new file mode 100644 index 00000000..c766c1c5 --- /dev/null +++ b/docs/initiative-history.json @@ -0,0 +1,17 @@ +[ + { + "title": "Dependency graph legibility", + "slug": "dependency-graph-legibility", + "outcome": "completed", + "retired_at": "2026-11-12", + "summary": "The dependency graph now packs mid-level views to the viewport, draws two-line boxes with distinct, size-aware folders, groups neighbors by package then file, takes color and LOC from the treemap, and spreads edge bundles. Reconciled against origin/main 0bfb05ba.", + "reason": "All five milestones merged on 2026-10-15 (#50, #56, #58, #60, #61).", + "documentation": [ + "docs/CODE_MAP.md" + ], + "revision": "0bfb05ba", + "follow_ups": [ + "Peripheral ideas C13-C15 (peek in context, surface a folder's most-used items, quieter dashed edges) were not planned milestones. Later work covers part of them: expand in place (#84, #91) and hub badges (#64)." + ] + } +] diff --git a/docs/intent/dependency-graph-legibility/implementation-plan.md b/docs/intent/dependency-graph-legibility/implementation-plan.md deleted file mode 100644 index e64d27b8..00000000 --- a/docs/intent/dependency-graph-legibility/implementation-plan.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: "Dependency graph legibility — implementation plan" -slug: "dependency-graph-legibility" -phase: plan -status: current -last_updated: "2026-10-15" ---- - -# Dependency graph legibility — implementation plan - -## Plan at a glance - -Each milestone changes one stage of the existing pipeline: view model → grid layout → canvas. Each one is gated by a geometry test, so a regression shows up as a failing number rather than a screenshot argument. - -1. **Packing.** This was the most visible failure in the session, and it is a contained fix to the layout's option scoring. -2. **Two-line boxes and folder styling**, using data the graph already has (member counts, hierarchy). -3. **Grouping.** The highest-value change, and the riskiest for routing. -4. **Joining LOC and the treemap color onto the graph.** No server change. -5. **Edge spreading.** - -Every milestone leaves the graph shippable. Compare mode, which shares `layoutViewSync`, stays green throughout. - -**Pushback:** -- The shape had folders spanning several rows. The router assumes gutters are free from end to end (`layout.ts:9-10`). A spanning box would block the gutters it covers, so edges would cross it. The plan keeps uniform cells. Every box gets taller to hold two lines, and folder size becomes an in-box size bar. -- Realism without leaking data: srcly is public, so modeler graphs can't be committed. A capture script writes them to a gitignored `__fixtures__/local/` folder. Tests that use them skip when the folder is absent, and committed tests use srcly's own fixture plus small synthetic graphs. - -## Implementation strategy - -- **First proof:** milestone 1's aspect-band test on a synthetic `server`-shaped graph and on local modeler captures. -- **Primary seam:** the pure functions `buildViewModel(index, opts)` (`viewModel.ts:74`) and `layoutViewSync(vm, opts)` (`layout.ts:203`). They already have Vitest coverage, so no new seam is needed. -- **Fast local loop:** `cd client && pnpm test -- viz/deps compare/graphModel`. Capture fixtures with `scripts/capture-dep-graph.sh `. The script calls `GET /api/analysis/dependency-graph?path=` on a running server and writes `client/src/viz/deps/__fixtures__/local/.json`, a folder that is added to `.gitignore`. -- **Local dependencies:** none. -- **Live confirmation:** before/after screenshots of modeler `server`, `agent_skills` and `client/apps/modeler/src/components`, attached to each PR and never committed. -- **Rollout and rollback:** each milestone is its own PR. - -## Milestone 1: Mid-level views fill the viewport - -- **Change: arrange scoring** (`client/src/viz/deps/layout.ts:312-325`) - - Among options within 90% of the best scale, pick the one whose width:height is closest to the viewport's on a log scale. Today it picks the most unfolded one. - - `chooseRows` (`:129-145`) uses the depth-level counts per region instead of raw region counts. -- **Change: test helpers** (`layout.test.ts`) - - Add `aspectOf(layout)`. Assert that it stays within 0.5–2× the viewport aspect for: - - the srcly fixture's folder focuses; - - a synthetic graph of 15 children spread over 5 depth levels; - - local modeler captures, when present. - - Replace the weak `> 1.2` assertion (`:46`). - - Keep `countNodeCrossings === 0` and record the crossing count as a baseline. -- **Change:** add the capture script and the `.gitignore` entry. - -### Desired end state - -- Modeler `server` and `primitives` render roughly viewport-shaped and centered, not 4–7:1 strips. -- All layout, viewModel and graphModel tests pass. - -## Milestone 2: Two-line boxes and visibly different folders - -- **Change: box size** (`layout.ts:13-14`): `NODE_HEIGHT` 28 → 40. Rows and gutters follow, because everything already derives from the constant. -- **Change: context line** - - `viewModel.ts:349-369` sets `subtitle` on every `ViewNode`: - - a symbol gets module · file; - - a file gets its parent folder; - - a folder gets "N files · M folders", from the hierarchy. - - Symbol `label` becomes the bare symbol name instead of `qualifiedSymbol` (`:420-423`). - - `compare/graphModel.ts:197-225` sets `subtitle` too. The field is optional. -- **Change: rendering** (`DependencyCanvas.tsx:276-345`) - - Line 1 is dark and medium weight. Line 2 is muted. - - Folders get a tinted fill and a 1.5px frame. - - A 3px bottom size bar shows width ∝ log(memberCount) against the largest sibling in view. -- **Test:** viewModel tests for `subtitle` per kind. - -### Desired end state - -- `relationship_focus.RelationshipFocus` reads as `RelationshipFocus` over `model_making · relationship_focus.py`. -- In `components`, the 276-file folder has the longest bar, and folders and files are told apart at a glance. - -## Milestone 3: Neighbors grouped by package, then file - -- **Change: group key** (`viewModel.ts`) - - `ViewNode.group?: { id, label }`. - - For side nodes, the key is the first folder below the common ancestor of the focus and that node. For symbols, it is the owning file, nested inside the package. - - Single-symbol collapse: when every edge into a side file targets one symbol, emit that symbol with the file as `subtitle`. -- **Change: ordering** (`layout.ts:278`, `:336-359`) - - Within a column, barycenter runs over groups first, then over members inside each group, so groups stay contiguous. -- **Change: frames** (`DependencyCanvas.tsx`, reusing the `focusFrame` pattern at `:145-154`, `:224-237`) - - One light frame per group run in each column, labeled at the top-left in the frame padding. -- **Tests:** - - every group's nodes are contiguous in their column; - - 0 node crossings; - - crossings no more than about 25% over the milestone 1 baseline; - - single-symbol collapse on a synthetic graph. - -### Desired end state - -- Around modeler `identify_properties.py`, `agent-skills`, `agent-core` and `agent-shared` neighbors sit in labeled frames. -- `edit-in-place` shows as its component. - -## Milestone 4: Shared color and LOC from the treemap - -- **Change: metrics index** - - `Treemap.tsx:250-255` passes `metricsIndex` (a `Map` built once per scan) and `colorMetric` (`Treemap.tsx:66`) into `DependencyView`. - - Agree on this prop with the unified-navigation worker. It is the only change this initiative makes to `DependencyView`'s props. -- **Change: tint and LOC** - - In a memo separate from layout, so a color change never triggers a relayout, the canvas fills each box with `treemapFillColor` (`viz/treemap/utils/colors.ts:58`). Text color comes from `treemapLabelColor`. - - The file subtitle shows LOC. The folder subtitle adds total LOC, and the size bar switches to LOC. - - A node with no match keeps a neutral fill and no LOC. -- **Test:** a pure `nodeMetrics(index, absPath)` with hit and miss cases. - -### Desired end state - -- Changing the color metric in the toolbar re-tints the graph instantly with no relayout. -- `pipeline.py` shows its LOC. - -## Milestone 5: Edges spread out - -- **Change: bundle width** (`layout.ts:663-743`): drop the 8px cap and use `gap = max(1.5, min(BUNDLE_GAP, channelWidth / n))`. -- **Change: gutter choice** (`layout.ts:389`): when both candidate gutters are valid, choose the less loaded one. -- **Tests:** bundle offsets within the channel bounds; crossings no worse than the milestone 3 result; no extra overlapping segments. - -### Desired end state - -- The `server` focus no longer funnels its edges through one 30px band, and each bundle's width reflects its edge count. - -## Open decisions and spikes - -- **Frames per column vs across columns.** Decide after the milestone 3 screenshots. If the per-column frames look fragmented when a package spans depth levels, try one frame across adjacent columns, with gutters inside it allowed. Fallback: group labels without frames. - - **Decided (milestone 3): per column.** Depth layering already separates most packages by column, and a package's lone box in another column gets no frame; its subtitle names the package. A frame across columns would have to contain the channels where other packages' edges run. - -## Below the cut line - -- Folders spanning several rows, which needs a span-aware router. -- Peek or fly-in of a neighbor's contents. -- A folder's most-used items on the parent view. -- LOC and color on the compare graph. -- Fewer faint edges in busy views. diff --git a/docs/intent/dependency-graph-legibility/initiative-map.json b/docs/intent/dependency-graph-legibility/initiative-map.json deleted file mode 100644 index e5a20775..00000000 --- a/docs/intent/dependency-graph-legibility/initiative-map.json +++ /dev/null @@ -1,759 +0,0 @@ -{ - "schema_version": "0.5.0", - "initiative": { - "title": "Dependency graph legibility", - "slug": "dependency-graph-legibility", - "scale": "capability", - "current_phase": "plan", - "last_updated": "2026-10-15", - "summary": "Make mid-level dependency views readable: group neighbors by module/package then file, make folders visibly distinct and size-aware, pack to a sane aspect ratio with spread-out edges, show LOC and the shared treemap color overlay, all without regressing performance.", - "status": "planned", - "next_action": "Worker: m1 packing after quick-fix mA/mB merge" - }, - "artifacts": { - "intent_brief": { - "path": "intent-brief.md", - "status": "current", - "updated_at": "2026-10-15" - }, - "brainstorm": { - "path": "brainstorm.md", - "status": "not-requested", - "updated_at": null - }, - "shape_brief": { - "path": "shape-brief.md", - "status": "current", - "updated_at": "2026-10-15" - }, - "implementation_plan": { - "path": "implementation-plan.md", - "status": "current", - "updated_at": "2026-10-15" - } - }, - "related_initiatives": [ - { - "slug": "dependency-view", - "relation": "follow-up; supersedes its C6 uniform-box rule for folder boxes" - }, - { - "slug": "unified-navigation", - "relation": "shared color overlay and peek/fly-in touch navigation" - }, - { - "slug": "dependency-and-treemap-quick-fixes", - "relation": "legend, header removal, hover bug land there first" - }, - { - "slug": "pr-compare", - "relation": "compare graph reuses layoutViewSync" - } - ], - "sources": [ - { - "id": "req-1", - "type": "request", - "location": "conversation", - "anchor": "2026-10-15 request: process voiceover, pull initiatives + low-hanging fruit", - "authority": "direct current intent" - }, - { - "id": "vo", - "type": "voiceover-transcript", - "location": "/Users/byronwall/Movies/ContextRecorder/2026-10-15_08-58-32/session.md", - "anchor": "Full transcript; srcly against /Users/byronwall/repos/modeler", - "authority": "direct current intent" - }, - { - "id": "vo-0015", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "0:15-0:30 'incredibly fast ... everything we do needs to avoid compromising performance'", - "authority": "direct current intent" - }, - { - "id": "vo-0050", - "type": "voiceover-transcript", - "location": "session.md + screenshots/001.png", - "anchor": "0:50-1:26 mark 001 folders look like files; bigger folder box with contents summary", - "authority": "direct current intent" - }, - { - "id": "vo-0126", - "type": "voiceover-transcript", - "location": "session.md + screenshots/002.png", - "anchor": "1:26-1:50 mark 002 server focus: odd wide aspect ratio, want grouped in middle", - "authority": "direct current intent" - }, - { - "id": "vo-0150", - "type": "voiceover-transcript", - "location": "session.md + screenshots/003.png", - "anchor": "1:50-2:25 mark 003 edges all through same 30px; files vs folders mixed", - "authority": "direct current intent" - }, - { - "id": "vo-0301", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "3:01-3:56 hint of what's in folders; expand in place (doubted); folders+files mixed, muddled", - "authority": "direct current intent" - }, - { - "id": "vo-0414", - "type": "voiceover-transcript", - "location": "session.md + screenshots/006.png", - "anchor": "4:14-4:29 mark 006 app.py: grouping, mcp_runtime same file/class", - "authority": "direct current intent" - }, - { - "id": "vo-0601", - "type": "voiceover-transcript", - "location": "session.md + frames/007.jpg", - "anchor": "6:01-7:01 mark 007 group by module (agent-skills/agent-core) then file/class; 2-3 line labels", - "authority": "direct current intent" - }, - { - "id": "vo-0710", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "7:10-7:38 respect color scale in dep view; common color overlay, projections", - "authority": "direct current intent" - }, - { - "id": "vo-0741", - "type": "voiceover-transcript", - "location": "session.md + frames/009.jpg", - "anchor": "7:41-8:03 mark 009 like left-to-right; narrow views work; grouping missing", - "authority": "direct current intent" - }, - { - "id": "vo-0803", - "type": "voiceover-transcript", - "location": "session.md + frames/010.jpg", - "anchor": "8:03-8:47 mark 010 agent_skills: aspect ratio, lines to same spots, use viewport, small text, dashed too much?, group by module/project", - "authority": "direct current intent" - }, - { - "id": "vo-0850", - "type": "voiceover-transcript", - "location": "session.md + frames/011.jpg", - "anchor": "8:50-9:15 mark 011 create_identities excellent; click to fly in contents / bring in context", - "authority": "direct current intent" - }, - { - "id": "vo-0927", - "type": "voiceover-transcript", - "location": "session.md + frames/012.jpg", - "anchor": "9:27-9:41 mark 012 pipeline.py: want LOC on file and per symbol", - "authority": "direct current intent" - }, - { - "id": "vo-1039", - "type": "voiceover-transcript", - "location": "session.md + frames/013.jpg, frames/014.jpg", - "anchor": "10:39-11:18 components 276 doesn't convey massive; can't tell files/folders; see big things on previous view", - "authority": "direct current intent" - }, - { - "id": "vo-1132", - "type": "voiceover-transcript", - "location": "session.md + frames/015.jpg", - "anchor": "11:32-11:56 mark 015 primitives: 4:1 aspect, break into pieces", - "authority": "direct current intent" - }, - { - "id": "vo-1203", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "12:03-12:56 single-export file: show symbol, file as container, compact containers", - "authority": "direct current intent" - }, - { - "id": "vo-1300", - "type": "voiceover-transcript", - "location": "session.md + frames/016.jpg", - "anchor": "13:00-13:29 tiles: box around same-folder files; overall wildly better; quick fixes", - "authority": "direct current intent" - }, - { - "id": "repo-layout", - "type": "repository", - "location": "client/src/viz/deps/layout.ts", - "anchor": "NODE_WIDTH/HEIGHT L13-14; chooseRows L129-145; arrange L312-325; gutter choice L389; bundleOffsets L663-743", - "authority": "current implementation reality" - }, - { - "id": "repo-canvas", - "type": "repository", - "location": "client/src/viz/deps/DependencyCanvas.tsx", - "anchor": "KindGlyph L41-62; focusFrame L145-154; labelFor L177-181; memberCount L331-341", - "authority": "current implementation reality" - }, - { - "id": "repo-viewmodel", - "type": "repository", - "location": "client/src/viz/deps/viewModel.ts", - "anchor": "roll-up L222-318; faint L336-338; qualifiedSymbol L358-361; disambiguateLabels L393", - "authority": "current implementation reality" - }, - { - "id": "repo-contract", - "type": "repository", - "location": "server/app/models.py:73-105; client/src/viz/deps/contract.ts", - "anchor": "DepGraphNode has no LOC/metrics/end line", - "authority": "current implementation reality" - }, - { - "id": "repo-colors", - "type": "repository", - "location": "client/src/viz/treemap/utils/colors.ts", - "anchor": "TREEMAP_RAMP L14; treemapFillColor L58", - "authority": "current implementation reality" - }, - { - "id": "prior-dependency-view", - "type": "prior-initiative", - "location": "docs/intent/dependency-view/initiative-map.json", - "anchor": "C6 uniform boxes; C9 folder grouping; C20 aspect packing", - "authority": "earlier direct intent" - }, - { - "id": "qa-round-1", - "type": "question-round", - "location": "conversation", - "anchor": "2026-10-15 round 1", - "authority": "direct current intent" - } - ], - "intent": { - "claims": [ - { - "id": "C1", - "type": "constraint", - "statement": "Performance is the standout strength; no change may compromise load or drill speed.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0015" - ], - "code_anchors": [ - "server/app/services/deps/graph.py:66 (mtime-cached build)", - "client/src/viz/deps/DependencyView.tsx:85-95 (layout recompute per focus)" - ] - }, - { - "id": "C2", - "type": "problem", - "statement": "Folders are visually indistinguishable from files; mixed folder/file views are muddled.", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0050", - "vo-0150", - "vo-0301", - "vo-1039" - ], - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:41-62 KindGlyph is the only distinction", - "client/src/viz/deps/layout.ts:13-14 uniform 196x28 boxes" - ] - }, - { - "id": "C3", - "type": "desired experience", - "statement": "Folder boxes are larger and show a few summary lines: subfolders, files, LOC.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0050", - "vo-0301" - ], - "supersedes": "dependency-view C6 (uniform box size) for folder boxes", - "code_anchors": [ - "client/src/viz/deps/layout.ts:597-606 PositionedNode from constants", - "client/src/viz/deps/viewModel.ts:21,363 memberCount" - ] - }, - { - "id": "C4", - "type": "required behavior", - "statement": "Relative size must read visually; a 276-file folder must look massive, not just carry a number.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1039", - "vo-0050" - ], - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:331-341 count badge only" - ] - }, - { - "id": "C5", - "type": "problem", - "statement": "Mid-level views come out as 4:1-7:1 strips; they should be compact and centered, using the viewport.", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0126", - "vo-0803", - "vo-1132" - ], - "code_anchors": [ - "client/src/viz/deps/layout.ts:129-145 chooseRows", - "client/src/viz/deps/layout.ts:312-325 arrange tie-break picks t=1", - "client/src/viz/deps/layout.ts:25 MAX_SCALE", - "client/src/viz/deps/layout.test.ts:46 only asserts aspect > 1.2", - "client/src/viz/deps/DependencyCanvas.tsx:87-101 fit frames occupied band" - ] - }, - { - "id": "C6", - "type": "problem", - "statement": "Edges all run through the same narrow channel; they should spread out so the graph can be read.", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0150", - "vo-0803" - ], - "code_anchors": [ - "client/src/viz/deps/layout.ts:389 gutter next to anchor row", - "client/src/viz/deps/layout.ts:663-743 bundleOffsets caps bundle at ~8px", - "client/src/viz/deps/layout.ts:15-21 TRACK/MIN_GUTTER" - ] - }, - { - "id": "C7", - "type": "desired experience", - "statement": "Group neighbors by module/package first, then by file or class, with a visible frame per group.", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0414", - "vo-0601", - "vo-0741", - "vo-0803", - "vo-1300" - ], - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:145-154,224-237 focusFrame (reusable pattern)", - "client/src/viz/deps/viewModel.ts:222-318 parent chain/roll-up", - "client/src/viz/deps/layout.ts:278,336-359 level sort + barycenter (would need group-contiguous ordering)" - ] - }, - { - "id": "C8", - "type": "desired experience", - "statement": "Symbol boxes use two or three lines (module, file, symbol) instead of truncating the important part.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0601" - ], - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:177-181 labelFor 134-164px", - "client/src/viz/deps/viewModel.ts:358-361,420-423 qualifiedSymbol" - ] - }, - { - "id": "C9", - "type": "desired experience", - "statement": "Files as containers of symbols: a file exporting one symbol shows the symbol; busy containers render compact.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1203" - ], - "code_anchors": [ - "server/app/services/deps/graph.py:84-171 symbol nodes only when edge targets them" - ] - }, - { - "id": "C10", - "type": "desired experience", - "statement": "Show LOC on file nodes and ideally per symbol.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0927", - "vo-0050" - ], - "code_anchors": [ - "server/app/models.py:73-105 no LOC on DepGraphNode", - "server/app/services/analysis.py:1145,1180 treemap path = absolute, joinable with absPath" - ] - }, - { - "id": "C11", - "type": "decision", - "statement": "One shared color overlay: the dependency graph respects the treemap color metric; treemap and graph are projections of the same data.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0710" - ], - "code_anchors": [ - "client/src/viz/treemap/utils/colors.ts:14,58", - "client/src/components/Treemap.tsx:66 primaryMetric", - "client/src/components/Treemap.tsx:250-255 DependencyView gets only path" - ] - }, - { - "id": "C12", - "type": "constraint", - "statement": "Preserve left-to-right flow and the narrow-focus views that already work well.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0741", - "vo-0850", - "vo-1300" - ] - }, - { - "id": "C13", - "type": "future possibility", - "statement": "Peek / fly-in: expand a neighbor's contents in context without refocusing.", - "commitment": "tentative", - "importance": "peripheral", - "status": "active", - "time_horizon": "later", - "sources": [ - "vo-0301", - "vo-0850" - ], - "notes": "User doubted expand-in-place at 3:30 but asked again at 9:02." - }, - { - "id": "C14", - "type": "future possibility", - "statement": "Surface a folder's most-used items on the parent view (e.g. camera inside model-viz).", - "commitment": "tentative", - "importance": "peripheral", - "status": "active", - "time_horizon": "later", - "sources": [ - "vo-1039" - ] - }, - { - "id": "C15", - "type": "open question", - "statement": "Dashed (faint neighbor-to-neighbor) edges may be too much in busy views.", - "commitment": "tentative", - "importance": "peripheral", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0803" - ], - "code_anchors": [ - "client/src/viz/deps/viewModel.ts:336-338", - "client/src/viz/deps/DependencyCanvas.tsx:245-254" - ] - }, - { - "id": "C16", - "type": "current repository reality", - "statement": "Compare mode reuses layoutViewSync, so layout changes ripple into compare graphs.", - "commitment": "derived", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "repo-layout" - ], - "code_anchors": [ - "client/src/compare/CompareGraph.tsx:9", - "client/src/compare/graphModel.ts" - ] - }, - { - "id": "C17", - "type": "decision", - "statement": "A file exporting a single symbol renders as the symbol node, with the file name as quiet context.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "qa-round-1" - ] - } - ], - "themes": [ - "structure via grouping", - "kind and size legibility", - "viewport packing and edge spread", - "shared metric overlay", - "performance preservation" - ], - "conflicts": [ - { - "claims": [ - "C3", - "prior-dependency-view:C6" - ], - "resolution": "Newer direct dictation wins: folder boxes may be larger; symbol/file boxes stay uniform within kind." - } - ], - "human_questions": [] - }, - "brainstorm": { - "status": "not-requested", - "requested_count": 7, - "options": [], - "selected_option": null - }, - "shape": { - "status": "current", - "appetite": "Medium: client view model, layout, canvas only; no server or contract change.", - "problem": "Mid-level focus views are wide strips with piled edges, folders look like files, size is invisible, and neighbors are not grouped.", - "recommended_shape": { - "slices": [ - { - "id": "packing", - "files": [ - "client/src/viz/deps/layout.ts:129-145 chooseRows", - "client/src/viz/deps/layout.ts:312-325 arrange tie-break" - ] - }, - { - "id": "two-line-boxes", - "files": [ - "client/src/viz/deps/layout.ts:13-14 NODE_HEIGHT", - "client/src/viz/deps/DependencyCanvas.tsx:177-181 labelFor", - "client/src/viz/deps/viewModel.ts:358-361 qualifiedSymbol" - ] - }, - { - "id": "grouping", - "files": [ - "client/src/viz/deps/viewModel.ts:222-318 hierarchy", - "client/src/viz/deps/layout.ts:278,336-359 ordering", - "client/src/viz/deps/DependencyCanvas.tsx:145-154 frame pattern" - ] - }, - { - "id": "folder-row-span", - "files": [ - "client/src/viz/deps/layout.ts:597-606 PositionedNode" - ] - }, - { - "id": "single-symbol-files", - "files": [ - "client/src/viz/deps/viewModel.ts" - ] - }, - { - "id": "color-and-loc-join", - "files": [ - "client/src/components/Treemap.tsx:250-255 pass index", - "client/src/viz/treemap/utils/colors.ts:58 treemapFillColor", - "client/src/utils/dataProcessing.ts:69-77 findTreeNodeByPath" - ] - }, - { - "id": "edge-spread", - "files": [ - "client/src/viz/deps/layout.ts:389,663-743" - ] - } - ] - }, - "success_moves": [ - "Join LOC/metrics client-side by absPath from the treemap tree instead of extending DepGraphNode (no payload or build-time cost)", - "Keep the uniform-cell grid router; show folder size with an in-box size bar (row spans would block gutters and break the free-gutter invariant, layout.ts:9-10)", - "Group keys from existing hierarchy; barycenter at group level then within group", - "Geometry tests gate each slice: aspect band, zero box crossings, group contiguity, crossing count", - "Local gitignored modeler fixtures for realism; committed tests use srcly fixture plus synthetic graphs (public repo)" - ], - "first_proof": { - "question": "Do aspect-targeted packing, two-line boxes and grouping make mid-level views readable without breaking routing?", - "artifact": "layout/viewModel changes plus geometry tests on srcly fixture and local modeler server/ and components/ graphs; before/after screenshots", - "observation": "aspect within 0.5-2x viewport, 0 node crossings, groups contiguous, crossings not worse than baseline", - "decision_rule": "pass -> folder row-span, color join, edge spread; grouping raises crossings >~25% -> group labels without contiguity and revisit" - }, - "rabbit_holes": [ - "row spans blocking gutters (moved to evaluate; size bar is the plan)", - "per-column frames looking fragmented when a group spans depth levels", - "compare graph regressions via shared layoutViewSync", - "two-line height reducing boxes that fit the budget" - ], - "open_decisions": [] - }, - "implementation": { - "status": "current", - "repository_snapshot": { - "root": "/Users/byronwall/repos/srcly", - "revision": "5e396c3", - "worktree_status": "clean", - "subsystems": [ - "client/src/viz/deps", - "client/src/compare/graphModel.ts", - "client/src/components/Treemap.tsx" - ], - "test_commands": [ - "cd client && pnpm test -- viz/deps compare/graphModel" - ], - "deployment_surfaces": [] - }, - "dependencies": [], - "fast_local_loop": { - "command": "cd client && pnpm test -- viz/deps compare/graphModel", - "starts": "nothing; optional scripts/capture-dep-graph.sh writes gitignored local fixtures from a running server", - "network": false, - "failure_injection": "synthetic graphs (15 children over 5 depths, multi-package neighbors, single-symbol files)" - }, - "milestones": [ - { - "id": "m1", - "title": "Mid-level views fill the viewport", - "outcome": "Folder focus views pack to roughly the viewport aspect instead of wide strips.", - "dependencies_introduced": [], - "proof": "layout.test.ts aspectOf within 0.5-2x viewport on srcly fixture, synthetic server-shaped graph, local modeler captures; 0 node crossings; crossing baseline recorded", - "valid_intermediate_state": "Same boxes and routing, better packing", - "rollback": "Revert arrange scoring", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/deps/layout.ts:129-145,312-325", - "client/src/viz/deps/layout.test.ts:46", - "scripts/capture-dep-graph.sh (new)", - ".gitignore" - ] - }, - { - "id": "m2", - "title": "Two-line boxes and visibly different folders", - "outcome": "Every box has name + context line; folders styled distinctly with a size bar.", - "dependencies_introduced": [], - "proof": "viewModel tests for subtitle per kind; graphModel tests green; screenshots", - "valid_intermediate_state": "Compare graph shows subtitles where set", - "rollback": "Restore NODE_HEIGHT 28 and single label", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/deps/layout.ts:13-14", - "client/src/viz/deps/viewModel.ts:12-27,349-369,420-423", - "client/src/viz/deps/DependencyCanvas.tsx:276-345", - "client/src/compare/graphModel.ts:197-225" - ] - }, - { - "id": "m3", - "title": "Neighbors grouped by package, then file", - "outcome": "Side neighbors contiguous and framed by package/module; single-symbol files render as the symbol.", - "dependencies_introduced": [], - "proof": "tests: group contiguity, 0 node crossings, crossings <=~125% of m1 baseline, single-symbol collapse", - "valid_intermediate_state": "Groups optional on ViewNode; compare unaffected", - "rollback": "Ignore group key in layout and skip frames", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/deps/viewModel.ts", - "client/src/viz/deps/layout.ts:278,336-359", - "client/src/viz/deps/DependencyCanvas.tsx:145-154,224-237" - ] - }, - { - "id": "m4", - "title": "Shared color and LOC from the treemap", - "outcome": "Graph boxes tinted by the treemap color metric and show LOC; recolor without relayout.", - "dependencies_introduced": [], - "proof": "vitest nodeMetrics hit/miss; manual metric switch re-tints without relayout", - "valid_intermediate_state": "Missing matches render neutral", - "rollback": "Stop passing metricsIndex", - "status": "planned", - "evidence": [], - "files": [ - "client/src/components/Treemap.tsx:66,250-255", - "client/src/viz/deps/DependencyView.tsx (props only)", - "client/src/viz/deps/DependencyCanvas.tsx", - "client/src/viz/treemap/utils/colors.ts:58,91" - ], - "coordination": "metricsIndex/colorMetric prop agreed with unified-navigation worker" - }, - { - "id": "m5", - "title": "Edges spread out", - "outcome": "Bundles widen with edge count; gutter choice balances load.", - "dependencies_introduced": [], - "proof": "tests: offsets within channel bounds, crossings not worse than m3, no added overlaps; server screenshot", - "valid_intermediate_state": "Routing invariants unchanged", - "rollback": "Restore 8px cap and anchor-adjacent gutter", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/deps/layout.ts:389,663-743" - ] - } - ], - "cut_line": [ - "multi-row folder spans (needs span-aware router)", - "peek/fly-in", - "most-used items on parent view", - "LOC/color on compare graph", - "reducing faint edges" - ], - "open_decisions": [ - { - "decision": "Group frames per column vs spanning adjacent columns", - "evidence": "m3 screenshots on modeler", - "fallback": "group labels without frames" - } - ], - "sequencing": "Start after quick-fix mA and mB merge (DependencyCanvas.tsx). Can run in parallel with unified-navigation if m4 prop is agreed." - }, - "history": [ - { - "date": "2026-10-15", - "event": "Initiative created from 2026-10-15 voiceover session (marks 001-016) against the modeler repo; intent drafted with code source map." - }, - { - "date": "2026-10-15", - "event": "Round 1: single-symbol files render as the symbol." - }, - { - "date": "2026-10-15", - "event": "Shape brief written: client-only join for color/LOC, grid kept with folder row-spans, hierarchy-based grouping." - }, - { - "date": "2026-10-15", - "event": "Shape amended during planning: folder row-span moved to evaluate; in-box size bar instead (row spans block routing gutters)." - }, - { - "date": "2026-10-15", - "event": "Implementation plan written: packing, two-line boxes, grouping, color/LOC join, edge spread; local gitignored modeler fixtures." - } - ], - "closure": null -} diff --git a/docs/intent/dependency-graph-legibility/intent-brief.md b/docs/intent/dependency-graph-legibility/intent-brief.md deleted file mode 100644 index 703b203f..00000000 --- a/docs/intent/dependency-graph-legibility/intent-brief.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "Dependency graph legibility" -slug: "dependency-graph-legibility" -phase: intent -status: current -last_updated: "2026-10-15" ---- - -# Dependency graph legibility - -## My read - -The multi-scale dependency view landed, and you called it "wildly better than before". Narrow focus views already work: a file in the middle, dependents on the left, dependencies on the right. What still fails is reading a *mid-level* view: a folder like `server`, `model-server-new`, `agent_skills` or `components`. Those views have four problems: - -- They come out as wide strips (4:1 to 7:1). -- Every edge runs through the same ~30px channel. -- Folders look exactly like files. -- Nothing shows which neighbors belong together. - -The goal is that a glance at any focus shows how big each thing is, what kind of thing it is, and which neighbors cluster by module, package or file. All of this has to happen without slowing srcly down. Speed is the thing you praised first, and every change has to protect it. - -## What matters most - -- **Structure is visible.** Neighbors group into containers by module or package, then by file (or class). You raised this more than any other point: "we've really got to just get all these group together". -- **Kind and size are obvious.** A folder reads as a folder and shows what it holds (subfolders, files, LOC). A 276-file folder looks massive. -- **Use the viewport.** Mid-level views fill the screen at a sane aspect ratio, and edges spread out instead of piling into one gutter. -- **Performance holds.** Loading and drilling stay as fast as they are today. - -## The experience you appear to want - -You focus on `components`. A box per subfolder, sized up and labeled with its counts, makes it obvious that `model-viz` and `inspector` are the heavy ones. Neighbors on each side sit inside light frames by package. Inside each package frame, files sharing a folder sit together, and a box around them shows they belong to the same folder. A file that exports a single component shows as that component, with the file as a thin container. Symbol labels take two or three lines (module, file, symbol), so `relationship_focus.Relatio…` is never cut down to nothing. Boxes carry LOC and are tinted with the treemap's current color metric, so the graph and the treemap feel like two views of one dataset. The layout centers in the screen, and edges spread across real gutters. - -## Boundaries - -### Must be true - -- Folder, file and symbol boxes are visually distinct, and folders can be larger than files. This **supersedes** the "all boxes the same size" rule from `dependency-view` for folder boxes. -- Left-to-right flow (incoming ◀ focus ▶ outgoing) stays, along with the narrow-focus views that already read well. -- Edges stay orthogonal and never pass through a box. Grouping frames count as obstacles. -- No measurable regression in first-open or drill latency on the ~2k-file modeler repo. - -### Must be avoided - -- Wide one-row or two-row strips, with every edge forced through a single gutter. -- Truncation that hides the part of the name that matters. -- A second color scheme that disagrees with the treemap. - -## What seems settled - -- Group by module or package first, then by file or class. The groups come from the hierarchy srcly already has, not from clustering. -- The color overlay is shared: the treemap and the dependency graph are "different projections" of the same metric colors. -- Containers stay compact when they hold many items, and collapse to their single symbol when that is all they hold. - -## Possibilities, not decisions - -- **Peek or fly-in:** click a neighbor and its contents expand in context, without refocusing. You doubted it yourself ("maybe expand in place was not going to look good"), so treat it as a later experiment. -- Showing a folder's most-used items on the parent view, e.g. `camera` inside a `model-viz` box. -- Toning down dashed edges (you weren't sure they help: "maybe the dashed lines is just too much"). The legend in [quick-fixes](../dependency-and-treemap-quick-fixes/intent-brief.md) comes first. - -## Current reality that matters - -- **Why views come out as strips.** Each layout cell is about 5.8:1 (196×28 boxes). When candidate layouts tie at `MAX_SCALE`, the code always picks the most unfolded one. The relevant code is `chooseRows` and `arrange`, `client/src/viz/deps/layout.ts:129-145` and `:312-325`. The only test asks for an aspect ratio above 1.2 (`layout.test.ts:46`). -- **Why edges pile up.** With 1–3 rows there are very few gutters, and edges that share an anchor share one track. `bundleOffsets` caps every bundle at about 8px (`layout.ts:389`, `:663-743`). -- **Neighbors are not grouped.** Each side is sorted by label, then reordered by barycenter. The only frame drawn is around the focus symbols (`DependencyCanvas.tsx:145-154`). The view model already knows each node's parent chain (`viewModel.ts:222-318`). -- **No size data on the graph.** Its nodes carry no LOC or metrics (`server/app/models.py:73-105`, `contract.ts`). The treemap tree holds both, and its absolute paths match the graph's `absPath` field. -- **Compare reuses this code.** Compare mode uses `layoutViewSync` and its own view model (`compare/CompareGraph.tsx:9`, `compare/graphModel.ts`), so layout changes affect it too. - -## Decided in round 1 - -- A file that exports a single symbol renders as that symbol, with the file name as quiet context. - -## Next step after confirmation - -Shape the work. The first proof would be grouped side layout plus aspect-ratio packing on `server` and `components` from modeler, checked with geometry tests and screenshots. diff --git a/docs/intent/dependency-graph-legibility/shape-brief.md b/docs/intent/dependency-graph-legibility/shape-brief.md deleted file mode 100644 index 5f5d4cb7..00000000 --- a/docs/intent/dependency-graph-legibility/shape-brief.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "Dependency graph legibility — shape brief" -slug: "dependency-graph-legibility" -phase: shape -status: current -last_updated: "2026-10-15" ---- - -# Dependency graph legibility — what we are adding - -**Outcome:** A mid-level focus such as `server`, `agent_skills` or `components` reads at a glance. You can see what kind each box is, how big it is, which neighbors belong together, and where the edges go. Both views use one metric color. - -**Primary flow:** Focus a folder → a compact, centered layout → neighbors sit in package frames, sized folders show their counts → you spot the heavy box and the cluster → drill in. - -## Feature scope - -```text -Dependency graph legibility -├── PLANNED ADDITIONS -│ ├── Packing -│ │ ├── layout choice targets the viewport's aspect ratio, not "most unfolded" -│ │ └── rows sized to the depth levels actually used, so no empty grid -│ ├── Two-line boxes (all kinds) -│ │ ├── line 1: name, dark -│ │ └── line 2: context, muted -│ │ ├── symbol → module · file -│ │ ├── file → LOC -│ │ └── folder → "12 files · 3 folders · 4.1k LOC" -│ ├── Folder vs file -│ │ ├── folders get their own style (tinted fill, heavier frame) -│ │ └── a size bar inside the box, scaled by log(LOC) against the largest sibling, -│ │ plus a bold count, so a 276-file folder looks massive -│ ├── Grouping -│ │ ├── side neighbors kept together by package/module (first folder below the -│ │ │ common ancestor), then by owning file for symbols -│ │ └── a light labeled frame around each group's run of boxes in a column -│ ├── Single-symbol files -│ │ └── every edge hits one symbol → draw the symbol; the file name becomes context -│ ├── Shared color overlay -│ │ └── fill tinted by the treemap's current color metric, joined by absolute path -│ └── Edge spread -│ └── bundles widen with edge count (no 8px cap); cross-column edges use -│ more gutters once more rows exist -├── EVALUATE BEFORE COMMITTING -│ ├── folders spanning 1–3 rows (only if the router can treat a span as blocking its gutters) -│ ├── frames that span several columns, if per-column frames read as fragmented -│ ├── fewer faint dashed edges when a view is busy -│ └── LOC and color on the compare graph -└── LATER POSSIBILITIES - ├── peek / fly-in of a neighbor's contents without refocusing - └── a folder's most-used items shown on the parent view -``` - -## Behavior - -| Situation | Expected result | -| --- | --- | -| Focus `server` (15 children, mixed files and folders) | Roughly viewport-shaped, centered. Folders are clearly bigger and styled differently | -| 30 neighbors from 4 packages | Each package's boxes are contiguous and framed, with the package name on the frame | -| `edit-in-place.tsx` exports one component that three neighbors use | One box: `EditInPlace`, with "edit-in-place.tsx" as its context line | -| Color metric changed in the treemap | The graph re-tints with no refetch and no relayout | -| Graph node with no treemap match (filtered or excluded) | Neutral fill, and the LOC line is omitted | - -## Decisions and boundaries - -**Appetite:** Medium. All of the work is in the client's view model, layout, and canvas. No server or contract change. - -**Key decisions:** -- **Join metrics on the client.** The treemap tree already holds LOC and every metric, keyed by the same absolute path as the graph's `absPath`. Pass a path → node index into `DependencyView` instead of adding metrics to `DepGraphNode`. The graph payload and server build time stay unchanged, which meets the performance bar. -- **Keep the grid.** Every box stays one uniform (now two-line) cell, and folder size is shown by a size bar inside the box. A box spanning several rows would cover the gutters that edges route through, so it would break the router's "gutters are free end to end" guarantee (`layout.ts:9-10`, `:389`, `:556-606`). Row spans are under evaluation, not in the plan. -- **Groups come from the hierarchy.** Group keys use folders and owning files the view model already knows, not clustering. Barycenter ordering runs at the group level first, then inside each group. - -**Boundary:** -- Compare mode shares `layoutViewSync`, so its tests must stay green. -- The ~48-box budget is unchanged. -- No modeler graph JSON is committed, because srcly is public. Modeler fixtures stay in a gitignored local folder, and committed tests use srcly's own fixture plus small synthetic graphs. - -**Collisions:** Start after quick-fix PRs A and B merge, since they share `DependencyCanvas.tsx`. Coordinate with unified-navigation: it changes how `DependencyView` gets its location, while this work adds the metrics index prop. - -**First proof:** -- **Try:** Change only the packing, two-line boxes and grouping, against srcly's fixture plus local modeler `server` and `components` graphs. -- **Observe:** Geometry tests report: - - aspect ratio within 0.5–2× the viewport; - - zero edges through boxes; - - every group contiguous in its column; - - crossing count no worse than today. - - Before/after screenshots of `server`, `agent_skills`, and `components`. -- **Decide:** If the tests pass and the screenshots read clearly, continue with folder styling and size bars, the color join and edge spread. If grouping raises crossings by more than about 25%, drop to group labels without contiguity and revisit. - -Intent: [intent-brief.md](intent-brief.md)