From 97a1219b9a92d8361cae77f14a018a8beb729c8e Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Thu, 12 Nov 2026 21:52:58 -0500 Subject: [PATCH] docs: retire dependency-and-treemap-quick-fixes All five milestones merged on 2026-10-15 (#46, #48, #51, #53, #57). Move the durable facts into the lasting docs, add the closure record to docs/initiative-history.json, and remove the planning folder. Co-Authored-By: Claude Opus 5.5 --- docs/CODE_MAP.md | 4 + docs/initiative-history.json | 13 + .../implementation-plan.md | 137 ---- .../initiative-map.json | 699 ------------------ .../intent-brief.md | 78 -- .../shape-brief.md | 89 --- 6 files changed, 17 insertions(+), 1003 deletions(-) delete mode 100644 docs/intent/dependency-and-treemap-quick-fixes/implementation-plan.md delete mode 100644 docs/intent/dependency-and-treemap-quick-fixes/initiative-map.json delete mode 100644 docs/intent/dependency-and-treemap-quick-fixes/intent-brief.md delete mode 100644 docs/intent/dependency-and-treemap-quick-fixes/shape-brief.md diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index 8b723a3c..ab469f0e 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -267,6 +267,10 @@ Navigation rules: | Scope `(body)` nodes with shared unchanged branches, path lookup | `client/src/viz/treemap/utils/tree.ts`, `viz/treemap/utils/path.ts` | | Label text fitting | `client/src/utils/svgText.ts` | +Treemap rules: labels are dark monospace. Every `TREEMAP_RAMP` stop keeps label contrast at 4.5:1 or more (`colors.test.ts`). Compare mode uses the same ramp, so check a ramp change in compare too, and do not fork it. + +Graph-to-code rule: there is one `CodeModal`. Opening from the graph resolves the file and scope on the client, through the treemap tree (`absPath` equals the tree's `path`). The scope's end line comes from the treemap, so the graph contract needs no extra field. + ### Client: 2x2 view | Feature | Where | diff --git a/docs/initiative-history.json b/docs/initiative-history.json index 074dc98f..b9c46cd5 100644 --- a/docs/initiative-history.json +++ b/docs/initiative-history.json @@ -43,5 +43,18 @@ "follow_ups": [ "Peripheral idea C8 (animated canvas transition between treemap and graph) was never planned and is not tracked." ] + }, + { + "title": "Dependency and treemap quick fixes", + "slug": "dependency-and-treemap-quick-fixes", + "outcome": "completed", + "retired_at": "2026-11-12", + "summary": "Opening code from the graph now uses the app's code viewer at the right scope, the graph has a legend and no side headers, the treemap has dark mono labels and a stronger ramp, popovers open one at a time, and the code viewer shows one table of applicable metrics. Reconciled against origin/main 0bfb05ba.", + "reason": "All five milestones merged on 2026-10-15 (#46, #48, #51, #53, #57).", + "documentation": [ + "docs/CODE_MAP.md" + ], + "revision": "0bfb05ba", + "follow_ups": [] } ] diff --git a/docs/intent/dependency-and-treemap-quick-fixes/implementation-plan.md b/docs/intent/dependency-and-treemap-quick-fixes/implementation-plan.md deleted file mode 100644 index 89588648..00000000 --- a/docs/intent/dependency-and-treemap-quick-fixes/implementation-plan.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Dependency and treemap quick fixes — implementation plan" -slug: "dependency-and-treemap-quick-fixes" -phase: plan -status: current -last_updated: "2026-10-15" ---- - -# Dependency and treemap quick fixes — implementation plan - -## Plan at a glance - -There are five milestones, one PR each. A goes first because it fixes the bugs and changes the code path that unified-navigation builds on. C, D and E share no files with A or B, so they can run in parallel worktrees from the start. B waits for A because both edit `DependencyCanvas.tsx`. - -**Pushback:** -- The shape hoped to match graph symbols to treemap scopes by `file::name`. The code says no. Treemap scope names decorate classes and types (Python `(class) Foo`, TS `Foo (class)`, `X (interface)`), while graph symbols use the bare name and only list top-level declarations. A therefore matches by line inside the file's scope list and uses a normalized name to break ties. It stays client-only. -- The client has no component-test library, only pure-function Vitest tests. Each fix pulls its branching logic into a pure function that a test can cover: - - `staleHover` - - `findScopeForSymbol` - - a click-intent timer - - `applicableMetrics` - -## Implementation strategy - -- **First proof:** milestone A. Open a symbol from the graph and it lands scoped, with the sidebar and metrics. A drill leaves nothing gray. -- **Primary seam:** client only. No server, cache or contract change in any milestone. -- **Fast local loop:** `cd client && pnpm test`. For browser checks, run `./dev.sh` with the server started in the repo under test (`srcly` on itself, then modeler by hand). -- **Local dependencies:** none beyond the dev server. -- **Live confirmation:** manual before/after on modeler. Screenshots go in the PR description only, never committed, because srcly is public. -- **Rollout and rollback:** each milestone is a separate revertable PR. - -## Milestone 1: (A) Opening from the graph works like opening from the treemap - -- **Change: hover reset** (`client/src/viz/deps/DependencyCanvas.tsx:75-142`) - - Clear `hoverNode` and `hoverEdge` in an effect on `props.layout`, and in the node `onClick`. - - `activeNodes` and `activeEdges` ignore ids that are not in the current layout, via a pure `liveHover(layout, id)`. - - Test: given a stale id, `activeNodes` returns null. -- **Change: click intent** (`DependencyCanvas.tsx:294-303`) - - A single click focuses after about 220ms unless a second click arrives, in which case it opens. - - `auxclick` with button 1 (middle) and ⌘/Ctrl-click open immediately. - - Update the tooltip hint (`:384`) to "Click to focus · double-click or middle-click to open". - - Test: a pure timer state machine. -- **Change: one CodeModal** - - `DependencyView` gains an `onOpenFile(absPath, line?)` prop, passed `Treemap.tsx:250-255` → `App.handleFileFromTreemap`. - - Remove the local `CodeModal` and the `openFile` signal (`DependencyView.tsx:55`, `:107-112`, `:200-202`). -- **Change: symbol → scope** (`client/src/utils/dataProcessing.ts`, next to `findNodes`) - - `findScopeForSymbol(fileNode, name, line)` picks the scope whose `start_line` is closest to `line` (within ±3, so decorators and const declarators are covered). It prefers a normalized-name match, stripping `(class)`, `(async)`, `(interface)` and `(type)`. - - On a hit, pass `start_line`/`end_line` and the node. On a miss, open the file at `line` with full file metrics. - - Tests: - - a Python class and a decorated function; - - a TS `const Foo = () =>` and an interface; - - duplicate names, and a miss. - -### Desired end state - -- On modeler, double-clicking `pipeline.py › run_pipeline` (or middle-clicking) opens the code viewer on that function, with the left symbol tree and both metric sections. -- After drilling into any node with the mouse held still, no node is dimmed. -- `pnpm test` is green. - -## Milestone 2: (B) The graph explains itself - -Starts after A merges. - -- **Change: headers** (`DependencyCanvas.tsx:17-21`, `:157-170`, `:207-222`) - - Drop the side headers. Keep the accent title when the focus is a file group. -- **Change: legend** (new `DependencyLegend.tsx`, absolutely positioned bottom-right in the graph host, `DependencyView.tsx:172`) - - It shows four swatches drawn with the same stroke constants as the canvas: import, context (dashed), weight (thick), external (dashed box). - - It can be collapsed, and the collapsed state is remembered in localStorage inside a try/catch. - -### Desired end state - -- No headers appear in any focus view, and the legend explains every visual encoding the graph uses. - -## Milestone 3: (C) The treemap draws the eye - -Parallel from the start. - -- **Change: label color and font** (`client/src/viz/treemap/components/TreemapCanvas.tsx:65-90`, `:153`, `:199-207`) - - Folder labels use `--plc-on-surface`, read once from computed style. Chunk labels lose their 0.7 alpha. - - The font becomes `"IBM Plex Mono"` for file and chunk labels. Folder headers stay Inter, then evaluate on screen. -- **Change: ramp** (`client/src/viz/treemap/utils/colors.ts:14-31`) - - Stronger stops, for example blue-200 → amber-300 → red-400, interpolated in HCL with `d3.interpolateHcl`. - - Depth brightening drops from 0.15 to about 0.05 per level. - - The legend gradient (`TreemapHeader.tsx:116-131`) and compare treemap follow automatically. Check the compare view by hand. -- **Change: spacing** (`client/src/components/Treemap.tsx:200-207`): use `paddingOuter(3)` and `paddingInner(1)`. Check that labels still clear the 20px header. -- **Change: tooltip** (`viz/treemap/hooks/useTreemapTooltip.ts:68-121`, `components/TreemapTooltip.tsx`) - - Restyle with the `plc-floating` and `plc-data-sm` columns. - - Show the top 5 child scopes by LOC, and `ts_import_coupling_count` or `python_import_count` as "imports". - - Flip at viewport edges, as in `compare/CompareTreemap.tsx:172+`. - - Extend `useTreemapTooltip.test.ts` for the symbol list. -- **Test:** a contrast check (WCAG ≥ 4.5:1) for label color against each ramp stop. - -### Desired end state - -- On modeler `model_making`, labels are dark and monospace, hot files stand out without looking muddy, and the tooltip lists the file's biggest functions. - -## Milestone 4: (D) Popovers behave - -Parallel from the start. - -- **Change: single open** (`client/src/components/Popover.tsx`) - - A module-level `openPopoverId` signal. Opening one popover sets it, and every other popover closes when it changes. - - This removes the reliance on the outside-click capture race (`:50-58`, `:88-102`). -- **Change: positioning** - - Render hidden (`visibility: hidden`), measure synchronously, then show. No 0,0 flash (`:36`, `:69-85`). - - Flip and clamp on all four edges (`:82`). -- **Change: motion.** A 120ms scale 0.97 → 1 plus opacity transition from the trigger-side origin, following `emil-design-eng`. Under `prefers-reduced-motion`, no motion. - -### Desired end state - -- Opening the file filter while the Color picker is open closes the Color picker. -- Neither popover flashes or jumps, by hand in Chrome on modeler. - -## Milestone 5: (E) A coherent code-viewer metrics panel - -Parallel from the start. - -- **Change: applicability** (`client/src/utils/metricsStore.tsx:32-73`) - - Add `scope: "file" | "any"` to each metric (for example `python_import_count`, `file_size` and `ts_import_coupling_count` are file-only). - - Add a pure `applicableMetrics(path, isScope)` that uses the existing `group` plus the file extension. - - Test it for Python, TSX, Markdown, and scope vs file. -- **Change: one table** (`client/src/components/CodeModal/MetricsSidebar.tsx:34-46`, `MetricsSection.tsx:12-21`) - - Replace the two long lists with grouped rows (Size · Complexity · Language): metric | scope | file. Zeros show only for applicable metrics. - -### Desired end state - -- A Python function shows about 10 relevant rows with scope and file values side by side, and no TSX or Markdown rows. - -## Open decisions and spikes - -- **Folder header font.** Decide whether folder headers go monospace too, after seeing C on modeler. If it is unclear, keep them Inter. - -## Below the cut line - -- Splitting the color metric into its own single-select, apart from Hot Spots. -- Edge legend entries for type-only edges. They aren't visually distinct today. -- Sending server metric definitions to the client. diff --git a/docs/intent/dependency-and-treemap-quick-fixes/initiative-map.json b/docs/intent/dependency-and-treemap-quick-fixes/initiative-map.json deleted file mode 100644 index a021eb07..00000000 --- a/docs/intent/dependency-and-treemap-quick-fixes/initiative-map.json +++ /dev/null @@ -1,699 +0,0 @@ -{ - "schema_version": "0.5.0", - "initiative": { - "title": "Dependency and treemap quick fixes", - "slug": "dependency-and-treemap-quick-fixes", - "scale": "capability", - "current_phase": "plan", - "last_updated": "2026-10-15", - "summary": "Independently shippable odds and ends from the 2026-10-15 voiceover: graph hover/open bugs, open-to-symbol, header removal and legend, treemap contrast/mono/color/spacing/tooltip, toolbar popover friction, and a coherent code-viewer metrics panel.", - "status": "planned", - "next_action": "Workers: mA first; mC, mD, mE in parallel worktrees now; mB after mA merges" - }, - "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-graph-legibility", - "relation": "structural graph work; quick fixes land first" - }, - { - "slug": "unified-navigation", - "relation": "open-from-graph routes through shared app modal" - }, - { - "slug": "pr-compare", - "relation": "compare treemap reuses TREEMAP_RAMP; verify after color change" - } - ], - "sources": [ - { - "id": "req-1", - "type": "request", - "location": "conversation", - "anchor": "2026-10-15 request: low-hanging fruit, odds and ends", - "authority": "direct current intent" - }, - { - "id": "vo-0015", - "type": "voiceover-transcript", - "location": "/Users/byronwall/Movies/ContextRecorder/2026-10-15_08-58-32/session.md", - "anchor": "0:15-0:30 keep performance", - "authority": "direct current intent" - }, - { - "id": "vo-0231", - "type": "voiceover-transcript", - "location": "session.md + screenshots/004.png", - "anchor": "2:31-2:43 mark 004 headers imported by/focus/imports get in the way", - "authority": "direct current intent" - }, - { - "id": "vo-0243", - "type": "voiceover-transcript", - "location": "session.md + frames/005.jpg", - "anchor": "2:43-3:01 mark 005 dashed vs solid unclear; legend bottom right", - "authority": "direct current intent" - }, - { - "id": "vo-0702", - "type": "voiceover-transcript", - "location": "session.md + frames/008.jpg", - "anchor": "7:02-7:10 mark 008 open source viewer from graph: No metrics available", - "authority": "direct current intent" - }, - { - "id": "vo-0943", - "type": "voiceover-transcript", - "location": "session.md + frames/012.jpg", - "anchor": "9:43-10:12 mark 012 didn't open to symbol; missing left sidebar; double-click doesn't work", - "authority": "direct current intent" - }, - { - "id": "vo-1030", - "type": "voiceover-transcript", - "location": "session.md + frames/013.jpg, frames/014.jpg", - "anchor": "10:30-10:53 marks 013-014 gray for a second; hover problem, everything gray", - "authority": "direct current intent" - }, - { - "id": "vo-1323", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "13:23-13:29 overall wildly better; quick fixes to get dependency viewer tight", - "authority": "direct current intent" - }, - { - "id": "vo-1335", - "type": "voiceover-transcript", - "location": "session.md + frames/016.jpg, frames/017.jpg", - "anchor": "13:35-14:00 marks 016-017 treemap spacing a pixel too big; washed out color; popovers and clicky things annoying", - "authority": "direct current intent" - }, - { - "id": "vo-1407", - "type": "voiceover-transcript", - "location": "session.md + screenshots/018.png", - "anchor": "14:07-14:28 mark 018 why is text gray; make important text black; monospace", - "authority": "direct current intent" - }, - { - "id": "vo-1434", - "type": "voiceover-transcript", - "location": "session.md + frames/019.jpg", - "anchor": "14:34-14:54 mark 019 tooltip radically underperforming; rich info, symbols, connectivity", - "authority": "direct current intent" - }, - { - "id": "vo-1513", - "type": "voiceover-transcript", - "location": "session.md + frames/020.jpg, screenshots/021.png, screenshots/022.png", - "anchor": "15:13-15:28 marks 020-022 code view great; metrics complete mess, rework into coherent display", - "authority": "direct current intent" - }, - { - "id": "repo-canvas", - "type": "repository", - "location": "client/src/viz/deps/DependencyCanvas.tsx", - "anchor": "REGION_TITLE L17-21; hover signals L75-76; activeEdges/Nodes L119-142; headers L157-170,207-222; edge style L245-254; dim L279-284; click/dblclick L294-303", - "authority": "current implementation reality" - }, - { - "id": "repo-depview", - "type": "repository", - "location": "client/src/viz/deps/DependencyView.tsx", - "anchor": "onOpenNode L107-112; local CodeModal L200-202", - "authority": "current implementation reality" - }, - { - "id": "repo-codemodal", - "type": "repository", - "location": "client/src/components/CodeModal/", - "anchor": "CodeModal.tsx props L18-28; MetricsSidebar.tsx L22,34-46; MetricsSection.tsx L12-21", - "authority": "current implementation reality" - }, - { - "id": "repo-treemap-canvas", - "type": "repository", - "location": "client/src/viz/treemap/components/TreemapCanvas.tsx", - "anchor": "strokes L38-40; labelStyle L65-90 sans-serif; folder label #888 L199-207", - "authority": "current implementation reality" - }, - { - "id": "repo-colors", - "type": "repository", - "location": "client/src/viz/treemap/utils/colors.ts", - "anchor": "TREEMAP_RAMP L14; applyDepthEffect L25-31", - "authority": "current implementation reality" - }, - { - "id": "repo-metrics-registry", - "type": "repository", - "location": "server/app/services/reporting.py; client/src/utils/metricsStore.tsx", - "anchor": "MetricDefinition languages/scope L21-59; HOTSPOT_METRICS L49-73", - "authority": "current implementation reality" - }, - { - "id": "qa-round-1", - "type": "question-round", - "location": "conversation", - "anchor": "2026-10-15 round 1", - "authority": "direct current intent" - } - ], - "intent": { - "claims": [ - { - "id": "C1", - "type": "problem", - "statement": "Graph dims everything gray when nothing is hovered (stale hover after refocus).", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1030" - ], - "item": 1, - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:75-76", - "client/src/viz/deps/DependencyCanvas.tsx:119-142", - "client/src/viz/deps/DependencyCanvas.tsx:279-284", - "client/src/viz/deps/DependencyView.tsx:186 unkeyed Show keeps canvas instance" - ] - }, - { - "id": "C2", - "type": "problem", - "statement": "Opening code from the graph shows 'No metrics available' and no symbol sidebar.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0702", - "vo-0943" - ], - "item": 2, - "code_anchors": [ - "client/src/viz/deps/DependencyView.tsx:107-112,200-202", - "client/src/components/CodeModal/MetricsSidebar.tsx:22,34-46", - "client/src/App.tsx:66-121 findNodes", - "client/src/App.tsx:353-406 handleFileFromTreemap/selectedNodes" - ] - }, - { - "id": "C3", - "type": "required behavior", - "statement": "Opening a symbol from the graph opens to that symbol's scope, not the whole file.", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0943" - ], - "item": 3, - "code_anchors": [ - "client/src/viz/deps/contract.ts:23-24 line only", - "server/app/services/deps/graph.py:127,130 symbol id/line", - "server/app/services/analysis.py:208 scope path file::func", - "client/src/components/CodeModal/CodeModal.tsx:86-102 lineFilterEnabled" - ] - }, - { - "id": "C4", - "type": "problem", - "statement": "Double-click to open (per the tooltip) doesn't work on neighbors; single click refocuses first.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0943" - ], - "item": 4, - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:294-303", - "client/src/viz/deps/DependencyCanvas.tsx:384 tooltip text" - ] - }, - { - "id": "C5", - "type": "preference", - "statement": "Remove the 'Imported by / Focus / Imports' column headers.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0231" - ], - "item": 5, - "code_anchors": [ - "client/src/viz/deps/DependencyCanvas.tsx:17-21,157-170,207-222" - ] - }, - { - "id": "C6", - "type": "desired experience", - "statement": "A legend (bottom right) explaining dashed vs solid edges and other encodings.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0243" - ], - "item": 6, - "code_anchors": [ - "client/src/viz/deps/viewModel.ts:336-338 faint", - "client/src/viz/deps/DependencyCanvas.tsx:245-254,318", - "client/src/viz/deps/DependencyCanvas.tsx:27-30 stroke width by weight" - ] - }, - { - "id": "C7", - "type": "problem", - "statement": "Important treemap text is low-contrast gray; make it dark.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1407" - ], - "item": 7, - "code_anchors": [ - "client/src/viz/treemap/components/TreemapCanvas.tsx:199-207", - "client/src/index.css:26-49 plc tokens" - ] - }, - { - "id": "C8", - "type": "preference", - "statement": "Treemap labels in monospace to signal code.", - "commitment": "tentative", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1407" - ], - "item": 8, - "code_anchors": [ - "client/src/viz/treemap/components/TreemapCanvas.tsx:87,153", - "client/src/index.css:9-18 --font-mono" - ] - }, - { - "id": "C9", - "type": "problem", - "statement": "Treemap color scale feels washed out.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1335" - ], - "item": 9, - "code_anchors": [ - "client/src/viz/treemap/utils/colors.ts:14-31", - "client/src/viz/treemap/components/TreemapCanvas.tsx:165-167 folders white", - "client/src/compare/CompareTreemap.tsx:5,296 reuse" - ] - }, - { - "id": "C10", - "type": "problem", - "statement": "Treemap spacing between nodes feels a pixel too big.", - "commitment": "tentative", - "importance": "peripheral", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1335" - ], - "item": 10, - "code_anchors": [ - "client/src/components/Treemap.tsx:200-207", - "client/src/viz/treemap/components/TreemapCanvas.tsx:38-40,171-173" - ] - }, - { - "id": "C11", - "type": "desired experience", - "statement": "Treemap tooltip shows rich info: symbols inside, connectivity hint; stop wasting space.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1434" - ], - "item": 11, - "code_anchors": [ - "client/src/viz/treemap/hooks/useTreemapTooltip.ts:51-121", - "client/src/viz/treemap/components/TreemapTooltip.tsx:14-33", - "client/src/compare/CompareTreemap.tsx:172+ HoverCard pattern", - "DESIGN.md:343-348,669-670" - ] - }, - { - "id": "C12", - "type": "problem", - "statement": "Both toolbar popovers (Color metric picker and file filter) feel bad: opening one does not close the other, and they feel jumpy/off. Use emil-design-eng guidance for polish.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1335", - "qa-round-1" - ], - "item": 12, - "code_anchors": [ - "client/src/components/MetricPicker.tsx:42-49,106-113", - "client/src/components/Treemap.tsx:66 only first metric colors", - "client/src/components/Popover.tsx:44-46,69-85" - ] - }, - { - "id": "C13", - "type": "problem", - "statement": "Code-viewer metrics panel is a mess; rework into a coherent display while keeping the code pane.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1513" - ], - "item": 13, - "code_anchors": [ - "client/src/components/CodeModal/MetricsSection.tsx:12-21", - "server/app/models.py:4-46 defaults 0", - "server/app/services/reporting.py:21-59 languages/scope", - "client/src/utils/metricsStore.tsx:32-73" - ] - }, - { - "id": "C14", - "type": "constraint", - "statement": "No change to scan, cache, or graph-build cost.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-0015" - ] - } - ], - "themes": [ - "graph open-path bugs", - "visual hierarchy and contrast", - "coherent metrics" - ], - "conflicts": [], - "human_questions": [] - }, - "brainstorm": { - "status": "not-requested", - "requested_count": 7, - "options": [], - "selected_option": null - }, - "shape": { - "status": "current", - "appetite": "Small: five independent PRs, each a handful of files; no scan/cache/contract change.", - "problem": "Graph open path is broken (stale hover dimming, no metrics/sidebar, file not symbol, dblclick swallowed); treemap hierarchy is low-contrast; popovers misbehave; metrics panel is noise.", - "recommended_shape": { - "prs": [ - { - "id": "A", - "name": "Graph open path", - "items": [ - 1, - 2, - 3, - 4 - ], - "files": [ - "client/src/viz/deps/DependencyCanvas.tsx", - "client/src/viz/deps/DependencyView.tsx", - "client/src/components/Treemap.tsx", - "client/src/App.tsx" - ] - }, - { - "id": "B", - "name": "Graph polish", - "items": [ - 5, - 6 - ], - "files": [ - "client/src/viz/deps/DependencyCanvas.tsx" - ] - }, - { - "id": "C", - "name": "Treemap visuals", - "items": [ - 7, - 8, - 9, - 10, - 11 - ], - "files": [ - "client/src/viz/treemap/components/TreemapCanvas.tsx", - "client/src/viz/treemap/utils/colors.ts", - "client/src/components/Treemap.tsx:200-207", - "client/src/viz/treemap/hooks/useTreemapTooltip.ts", - "client/src/viz/treemap/components/TreemapTooltip.tsx" - ] - }, - { - "id": "D", - "name": "Popovers", - "items": [ - 12 - ], - "files": [ - "client/src/components/Popover.tsx", - "client/src/components/MetricPicker.tsx", - "client/src/components/FileTypeFilter.tsx" - ] - }, - { - "id": "E", - "name": "Code viewer metrics", - "items": [ - 13 - ], - "files": [ - "client/src/components/CodeModal/MetricsSection.tsx", - "client/src/components/CodeModal/MetricsSidebar.tsx", - "client/src/utils/metricsStore.tsx" - ] - } - ], - "sequencing": "A before B (same file) and before unified-navigation; B before dependency-graph-legibility layout work; C, D, E parallel." - }, - "success_moves": [ - "Resolve fileNode/scopeNode client-side: file by absPath, scope by symbol line within that file (treemap names differ: '(class) Foo' / 'Foo (class)'); no contract change unless line matching misses", - "Route graph open through the single app CodeModal (removes the duplicate instance; seeds unified-navigation)", - "Metric applicability from existing HOTSPOT_METRICS group plus a scope flag, not a new definitions API", - "Shared module-level open-popover signal so one Popover closes others; measure before paint", - "Vitest checks for hover reset, symbol-to-scope lookup, click timing; modeler screenshots kept out of the public repo" - ], - "first_proof": { - "question": "Does a client-side absPath+symbol lookup reliably open the right scope with metrics, and does resetting hover fix the gray state?", - "artifact": "PR A: vitest for hover reset, scope lookup hit/miss/duplicate, click timing; manual check on modeler agent_skills/qa/pipeline.py", - "observation": "double-clicked symbol opens scoped with sidebar and metrics; drilling leaves nothing gray", - "decision_rule": "pass -> ship B-E in parallel worktrees; scope misses on real Python classes/methods -> add endLine to graph symbol contract before B" - }, - "rabbit_holes": [ - "Python class/method scope naming may not match graph symbol names", - "dblclick delay making single click feel laggy (keep under ~250ms)", - "ramp change shifts compare treemap colors", - "monospace widening labels so fewer fit" - ], - "open_decisions": [] - }, - "implementation": { - "status": "current", - "repository_snapshot": { - "root": "/Users/byronwall/repos/srcly", - "revision": "5e396c3", - "worktree_status": "clean", - "subsystems": [ - "client/src/viz/deps", - "client/src/viz/treemap", - "client/src/components/CodeModal", - "client/src/components/Popover.tsx", - "client/src/utils" - ], - "test_commands": [ - "cd client && pnpm test" - ], - "deployment_surfaces": [] - }, - "dependencies": [], - "fast_local_loop": { - "command": "cd client && pnpm test", - "starts": "nothing (pure-function vitest); ./dev.sh for manual browser checks", - "network": false, - "failure_injection": "pure functions take stale ids, missing scopes, and click sequences as inputs" - }, - "milestones": [ - { - "id": "mA", - "title": "Opening from the graph works like opening from the treemap", - "outcome": "Double/middle-click a graph symbol opens the shared CodeModal scoped to that symbol with sidebar and metrics; no stale gray dimming.", - "dependencies_introduced": [], - "proof": "vitest: liveHover stale id, click-intent timer, findScopeForSymbol (Python class, decorated fn, TS const component, interface, duplicate, miss); manual modeler pipeline.py check", - "valid_intermediate_state": "Graph and treemap both open the single app CodeModal", - "rollback": "Revert PR A", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/deps/DependencyCanvas.tsx:75-142,294-303,384", - "client/src/viz/deps/DependencyView.tsx:55,107-112,200-202", - "client/src/components/Treemap.tsx:250-255", - "client/src/App.tsx:353-406", - "client/src/utils/dataProcessing.ts" - ], - "worker_parallel": "first; blocks mB and unified-navigation" - }, - { - "id": "mB", - "title": "The graph explains itself", - "outcome": "No side headers; bottom-right legend explains import, context, weight, external.", - "dependencies_introduced": [], - "proof": "manual check across focus views; legend uses canvas stroke constants", - "valid_intermediate_state": "Legend collapsible", - "rollback": "Revert PR B", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/deps/DependencyCanvas.tsx:17-21,157-170,207-222", - "client/src/viz/deps/DependencyLegend.tsx (new)", - "client/src/viz/deps/DependencyView.tsx:172" - ], - "worker_parallel": "after mA" - }, - { - "id": "mC", - "title": "The treemap draws the eye", - "outcome": "Dark monospace labels, stronger HCL ramp, tighter padding, rich tooltip with top scopes and imports.", - "dependencies_introduced": [], - "proof": "vitest contrast >=4.5:1 per ramp stop; useTreemapTooltip.test.ts symbol list; manual modeler and compare treemap check", - "valid_intermediate_state": "Compare treemap follows shared ramp", - "rollback": "Revert PR C", - "status": "planned", - "evidence": [], - "files": [ - "client/src/viz/treemap/components/TreemapCanvas.tsx:65-90,153,199-207", - "client/src/viz/treemap/utils/colors.ts:14-31", - "client/src/components/Treemap.tsx:200-207", - "client/src/viz/treemap/hooks/useTreemapTooltip.ts:68-121", - "client/src/viz/treemap/components/TreemapTooltip.tsx" - ], - "worker_parallel": "from start" - }, - { - "id": "mD", - "title": "Popovers behave", - "outcome": "One popover open at a time; positioned before paint, flipped/clamped; subtle origin-aware motion.", - "dependencies_introduced": [], - "proof": "manual: opening file filter closes Color picker; no 0,0 flash", - "valid_intermediate_state": "All existing popovers use the shared Popover", - "rollback": "Revert PR D", - "status": "planned", - "evidence": [], - "files": [ - "client/src/components/Popover.tsx", - "client/src/components/MetricPicker.tsx", - "client/src/components/FileTypeFilter.tsx" - ], - "worker_parallel": "from start" - }, - { - "id": "mE", - "title": "A coherent code-viewer metrics panel", - "outcome": "Only applicable metrics, grouped, scope vs file in one table.", - "dependencies_introduced": [], - "proof": "vitest applicableMetrics for Python, TSX, Markdown, scope vs file", - "valid_intermediate_state": "Code pane unchanged", - "rollback": "Revert PR E", - "status": "planned", - "evidence": [], - "files": [ - "client/src/utils/metricsStore.tsx:32-73", - "client/src/components/CodeModal/MetricsSidebar.tsx:34-46", - "client/src/components/CodeModal/MetricsSection.tsx:12-21" - ], - "worker_parallel": "from start" - } - ], - "cut_line": [ - "single-select color metric separate from Hot Spots", - "type-only edge legend entry", - "server metric definitions API" - ], - "open_decisions": [ - { - "decision": "Folder header font mono or Inter", - "evidence": "mC screenshots on modeler", - "fallback": "Inter" - } - ] - }, - "history": [ - { - "date": "2026-10-15", - "event": "Initiative created from 2026-10-15 voiceover session; 13 items with code anchors and likely causes." - }, - { - "date": "2026-10-15", - "event": "Round 1: both popovers; failure is not closing when another opens, plus jumpy positioning." - }, - { - "date": "2026-10-15", - "event": "Shape brief written: five PRs A-E with sequencing and collision notes." - }, - { - "date": "2026-10-15", - "event": "Shape amended during planning: symbol-to-scope lookup is line-based because treemap and graph names differ for classes/types." - }, - { - "date": "2026-10-15", - "event": "Implementation plan written: milestones A-E, one PR each; line-based symbol-to-scope lookup." - } - ], - "closure": null -} diff --git a/docs/intent/dependency-and-treemap-quick-fixes/intent-brief.md b/docs/intent/dependency-and-treemap-quick-fixes/intent-brief.md deleted file mode 100644 index 8aede2b2..00000000 --- a/docs/intent/dependency-and-treemap-quick-fixes/intent-brief.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Dependency and treemap quick fixes" -slug: "dependency-and-treemap-quick-fixes" -phase: intent -status: current -last_updated: "2026-10-15" ---- - -# Dependency and treemap quick fixes - -## My read - -You said "we've got some quick fixes here to get the dependency viewer to be nice and tight". These are the odds and ends from the session: real bugs, small visual corrections, and a couple of contained reworks. Each one is independently shippable, and none needs a new layout or navigation model. The larger themes live in [dependency-graph-legibility](../dependency-graph-legibility/intent-brief.md), [unified-navigation](../unified-navigation/intent-brief.md), and [compare-ref-picker](../compare-ref-picker/intent-brief.md). - -The common goal: your eye goes to the important thing first. That means dark text, monospace for code, a color ramp with punch, and a tooltip that earns its space. Opening code from anywhere should behave as well as it does from the treemap. Performance stays untouched. - -## What matters most - -- **Fix the bugs first:** stuck gray dimming, "No metrics available", opening the file instead of the symbol, and double-click that doesn't open. -- **Contrast and hierarchy** in the treemap. -- **Coherent metrics** in the code viewer. - -## The fixes - -### Bugs - -1. **Everything stays gray after a click** (10:30, 10:52). - - Cause: `hoverNode` and `hoverEdge` survive a refocus. Their DOM nodes are replaced, so `mouseleave` never fires. `activeNodes` then holds a stale id and dims everything (`client/src/viz/deps/DependencyCanvas.tsx:75-76`, `:119-142`, `:279-284`). - - Fix: clear the hover state when the layout changes, or ignore ids the layout no longer contains. -2. **"No metrics available" and no symbol sidebar when code is opened from the graph** (7:02, 9:52). - - Cause: `DependencyView` renders its own `CodeModal` with only `filePath` (`DependencyView.tsx:107-112`, `:200-202`). `MetricsSidebar` hides everything without a `fileNode` (`CodeModal/MetricsSidebar.tsx:22`, `:34-46`). - - Fix: route the graph's open action through the app's modal and `findNodes` (`App.tsx:66-121`, `:353-406`). The graph's `absPath` matches the treemap's absolute `path`. -3. **Opens the whole file, not the symbol** (9:45, 10:06). - - Cause: the symbol is dropped, and no line range is passed. - - Fix: map `absPath` plus the symbol `line` to the treemap scope node (`${file}::${name}`), then pass its `start_line`/`end_line` and the node. Today the contract carries only a start `line` (`contract.ts:23-24`, `server/app/services/deps/graph.py:130`). -4. **Double-click to open doesn't work on neighbors** (9:59). - - Cause: the first click refocuses and re-renders, so the second click lands elsewhere (`DependencyCanvas.tsx:294-303`). - - Fix: delay single-click focus until the double-click window has passed, or make open a visible action. You mentioned "middle click", and no middle-click handler exists; adding `auxclick` is cheap. - -### Dependency graph polish - -5. **Drop the "Imported by / Focus / Imports" headers** (2:31). They "just sort of get in the way" (`DependencyCanvas.tsx:17-21`, `:157-170`, `:207-222`). Keep the file-name title when a file is the focus. -6. **Add a legend at the bottom right** (2:43–3:01). Dashed means a faint neighbor↔neighbor or internal edge (`viewModel.ts:336-338`), not type-only. A dashed box border means an external package (`DependencyCanvas.tsx:245-254`, `:318`). The legend should also cover edge thickness, meaning weight. - -### Treemap visuals - -7. **Make important text dark.** Folder labels are hard-coded `#888888`, and chunk labels sit at alpha 0.7 (`client/src/viz/treemap/components/TreemapCanvas.tsx:199-207`). Use `--plc-on-surface` and `--plc-on-muted` instead. -8. **Use monospace labels** to signal "code stuff" (14:22). The canvas uses the generic `sans-serif` (`TreemapCanvas.tsx:87`, `:153`). Use IBM Plex Mono (`--font-mono`, `index.css:9-18`). -9. **Fix the washed-out color.** The ramp is three pastels (`#dbeafe → #fde68a → #fecaca`), interpolated in RGB, and `brighter(depth*0.15)` lightens each level further (`viz/treemap/utils/colors.ts:14-31`). Use stronger stops, interpolate in a perceptual space, and soften the depth effect. Compare's treemap and legend reuse this ramp. -10. **Tighten the spacing slightly** ("a pixel too big"). Current values are `paddingOuter(4)`, `paddingInner(2)`, white leaf strokes, and a 20px header (`client/src/components/Treemap.tsx:200-207`, `TreemapCanvas.tsx:38-40`). -11. **Enrich the tooltip** (14:34–14:54). It wastes space today. It should show the symbols inside, a connectivity hint (fan-in and fan-out), and mono tabular numbers. The current card is in `viz/treemap/hooks/useTreemapTooltip.ts:68-121` and `components/TreemapTooltip.tsx`. `CompareTreemap`'s `HoverCard` (`plc-floating`, `plc-data-sm`, edge flip) is the pattern to copy. -12. **Toolbar popovers feel bad** (13:46, confirmed in round 1). Both the Color picker and the file filter are affected. - - Opening one doesn't close the other. Check how the trigger's `stopPropagation` (`Popover.tsx:50-58`) interacts with the outside-click handler (`:88-102`). - - They feel jumpy or "off". The content renders at 0,0 for a frame before rAF positions it (`:36`, `:69-85`), and it has no flip or clamp on the right or bottom (`:82`). - - Polish them with `emil-design-eng` guidance on origin-aware motion and open/close behavior. - - The Color picker is also a multi-select where only the first metric colors the map (`MetricPicker.tsx:42-49`, `:106-113`; `Treemap.tsx:66`). - -### Code viewer - -13. **Rework the metrics panel into a coherent display** (15:22). Every one of 22 metrics prints for scope and file, including TSX metrics on Python and zeros everywhere (`CodeModal/MetricsSection.tsx:12-21`; `server/app/models.py:4-46` defaults to 0). The server already records which language and scope each metric applies to (`server/app/services/reporting.py:21-59`), but the client never receives that data. Show the applicable metrics, grouped, with the scope value against the file value. Keep the code pane as it is ("all of that's really good"). - -## Boundaries - -- No change to scan, cache, or graph-build cost. -- Each fix ships alone and gets a test where the logic branches: the hover reset, symbol lookup, click timing, and metric applicability. -- Compare views pick up the ramp and font changes. Check them, don't fork them. - -## What seems settled - -- Bugs 1–4 come first, and the code pane in the viewer stays as it is. -- Both toolbar popovers get the open/close and positioning fix (round 1). - -## Possibilities, not decisions - -- Monospace may only suit file and symbol labels, with folder headers staying sans. Check this on screen. -## Next step after confirmation - -Fix bugs 1–4 together as one PR, since they share the graph-open path. Then make the treemap visual pass (7–11) as one PR with before/after screenshots on modeler. diff --git a/docs/intent/dependency-and-treemap-quick-fixes/shape-brief.md b/docs/intent/dependency-and-treemap-quick-fixes/shape-brief.md deleted file mode 100644 index 34ec02f9..00000000 --- a/docs/intent/dependency-and-treemap-quick-fixes/shape-brief.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Dependency and treemap quick fixes — shape brief" -slug: "dependency-and-treemap-quick-fixes" -phase: shape -status: current -last_updated: "2026-10-15" ---- - -# Dependency and treemap quick fixes — what we are adding - -**Outcome:** Opening code from the graph behaves exactly like opening it from the treemap. The treemap draws your eye to what matters. Popovers and the metrics panel stop getting in the way. - -**Primary flow:** Drill the graph → double-click (or middle-click) a symbol → the code viewer opens on that symbol with its sidebar and metrics → close → the graph is not stuck gray. - -## Feature scope - -```text -Quick fixes (five independent PRs, in this order) -├── PLANNED ADDITIONS -│ ├── A · Graph open path (bugs 1–4) -│ │ ├── hover state resets whenever the layout changes; no stale dimming -│ │ ├── open goes through the app's single CodeModal: fileNode + scopeNode found by path -│ │ ├── symbol → its treemap scope, matched by line in that file (names differ: "(class) Foo", -│ │ │ "Foo (class)") → opens on that range -│ │ └── single click focuses after the dblclick window; middle-click and ⌘-click open -│ ├── B · Graph polish -│ │ ├── side headers removed; the focus file title stays -│ │ └── legend bottom-right: solid = import, dashed = context edge, -│ │ thickness = weight, dashed box = external package -│ ├── C · Treemap visuals -│ │ ├── labels dark on light fills (plc tokens), no alpha on chunk text -│ │ ├── IBM Plex Mono for file and symbol labels; folder headers stay Inter (evaluate) -│ │ ├── stronger ramp with perceptual interpolation; much lighter depth brightening -│ │ ├── padding one step tighter -│ │ └── tooltip: mono tabular numbers, top symbols by LOC, fan-out, edge flip -│ │ (CompareTreemap HoverCard pattern) -│ ├── D · Popovers -│ │ ├── only one open at a time: opening one closes the others -│ │ ├── positioned before first paint, flipped/clamped to the viewport -│ │ └── short origin-aware scale/opacity entry (emil-design-eng) -│ └── E · Code viewer metrics -│ ├── only metrics that apply to the file's language and the node's scope -│ ├── grouped: Size · Complexity · Language-specific -│ └── one table: metric | scope | file -└── LATER POSSIBILITIES - └── color metric as a single-select, separate from the Hot Spots multi-select -``` - -## Behavior - -| Situation | Expected result | -| --- | --- | -| Click a neighbor, then don't move the mouse | The graph drills in with no node dimmed | -| Double-click a neighbor | It opens in the code viewer without refocusing the graph | -| Open a symbol whose name has no matching scope | The viewer opens the file at the symbol's line, with full file metrics | -| Open the file filter while the Color picker is open | The Color picker closes | -| Python file in the code viewer | No TSX, `useEffect`, or Markdown rows | -| A metric is 0 but applies | It still shows, since 0 is information | - -## Decisions and boundaries - -**Appetite:** Small. Each PR stays within a handful of files and changes no scan, cache, or graph contract. - -**Key decisions:** -- **No server change for the open path.** The graph's `absPath` already matches the treemap tree's absolute `path`. `findNodes` resolves the file and the scope client-side, so the contract stays as it is. The scope end line comes from the treemap, not from a new `endLine` field. -- **Metric applicability lives in the client.** `HOTSPOT_METRICS` already carries a language `group`. Add a scope flag (file-only metrics such as `python_import_count` and `file_size`) instead of building a definitions API. -- **One CodeModal.** Moving the graph's open into the app's modal is also the first step of [unified-navigation](../unified-navigation/shape-brief.md). It stops two modal instances from drifting apart. - -**Boundary:** -- Compare mode picks up the ramp and font changes through the shared `TREEMAP_RAMP`. Check it there, don't fork it. -- No modeler-derived fixtures get committed, because srcly is public. Before/after screenshots of modeler stay in the PR description only. - -**Worktree collisions:** -- A and B both touch `DependencyCanvas.tsx`, so land A first or run them in sequence. -- C and E don't collide with anything. -- D touches only `Popover.tsx` and its pickers. -- A must merge before unified-navigation starts, and B before the legibility layout work. - -**First proof:** -- **Try:** PR A on srcly's own client folder, then by hand on modeler `agent_skills/qa/pipeline.py`. -- **Observe:** Vitest checks pass for: - - the hover reset after the layout changes; - - `absPath` + symbol → scope lookup (hit, miss, duplicate name); - - click/dblclick timing. - - In the browser, a double-clicked symbol opens on its line range with the sidebar and metrics, and a drill leaves nothing gray. -- **Decide:** If all three pass, ship PRs B–E in parallel worktrees. If the scope lookup misses on real Python classes or methods, add `endLine` to the graph symbol contract (one server field) before B. - -Intent: [intent-brief.md](intent-brief.md)