diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index d12fcacb..83ad5e83 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -181,6 +181,15 @@ A metric is its analyzer plus one catalog entry; the step-by-step checklist is ` | Before/after dependency graphs on one union layout (changed files center, importers left, imports right; added/removed edges; ghosts for absent files; "used by N" hubs; linked pan/zoom; expand) | `client/src/compare/CompareGraph.tsx`, model in `client/src/compare/graphModel.ts` (feeds `viz/deps/layout.ts:layoutViewSync`) | | Shared bits (status icon, diffstat, health, magnitude and split bars), labels/formatting/health | `client/src/compare/bits.tsx`, `client/src/compare/metrics.ts` | +Compare design: + +- The diff runs on the server, and the client only draws. `diff.py` is a pure module that turns two cached trees and two graphs into one payload, so the UI and `srcly compare` share one definition of better and worse. +- Compare gives each metric and each file its own better, worse or neutral verdict. It gives no single verdict for the whole change. A metric that is N/A on either side gets no delta. +- Views focus on changed files by default. The output comes from disk and the git diff only, with no LLM in the path. +- The treemap and the graph each lay out the union of both sides once, then filter per side. Unchanged nodes keep the same position on both sides. +- A commit snapshot is a `git worktree add --detach` in srcly's cache directory. It never touches your checkout, branch or stash, and real paths keep tsconfig and package roots working. +- Compare is its own view beside the normal one. Non-git folders and commits outside the local clone are out of scope. + Ref picker rules: - A PR's base is the merge-base of its own `baseRefName` and its head, as GitHub diffs it. PRs are often stacked, so the default branch is the wrong base. diff --git a/docs/initiative-history.json b/docs/initiative-history.json index eed010d7..8b6b0918 100644 --- a/docs/initiative-history.json +++ b/docs/initiative-history.json @@ -69,5 +69,20 @@ ], "revision": "0bfb05ba", "follow_ups": [] + }, + { + "title": "PR compare mode", + "slug": "pr-compare", + "outcome": "completed", + "retired_at": "2026-11-12", + "summary": "srcly compare and a compare mode UI landed: a CLI with commit snapshots and metric deltas, a changed-files table, side-by-side treemaps and before/after dependency graphs on shared union layouts. Reconciled against origin/main 0bfb05ba.", + "reason": "All four milestones were marked completed and their PRs merged on 2026-10-15 (#38, #39, #40, #41).", + "documentation": [ + "docs/CODE_MAP.md" + ], + "revision": "0bfb05ba", + "follow_ups": [ + "Longer-horizon ideas in claim C8 (change islands, PR splittability, ripple frontier) were never planned and are not tracked." + ] } ] diff --git a/docs/intent/pr-compare/implementation-plan.md b/docs/intent/pr-compare/implementation-plan.md deleted file mode 100644 index add06924..00000000 --- a/docs/intent/pr-compare/implementation-plan.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "PR compare mode — implementation plan" -slug: "pr-compare" -phase: plan -status: current -last_updated: "2026-10-15" ---- - -# PR compare mode — implementation plan - -## Plan at a glance - -The plan proves the backend before it draws anything. Milestone 1 is a headless `srcly compare` command that snapshots two refs, scans both, and prints one compare payload as JSON. That payload holds the change set, per-file metric deltas, and the dependency edge diff. It answers the two questions that would sink the feature: whether a commit can be scanned correctly from a temporary checkout, and what a compare costs. No UI work is spent on them first. - -After that, every milestone adds one view on top of the same payload. The Explorer table comes first because it is the cheapest way to show better and worse. The treemap comes next, then the dependency graph, which is the hardest view. Each milestone ships a working compare mode, and the normal single-scan view is never touched. - -**Pushback:** the shape had the headless report under evaluation. The plan builds it first anyway, because it is the fastest test loop, and agents can use it straight away. Diffing also happens on the server, so the UI, the CLI, and the tests share one definition of a "worse" change. That definition reuses the existing `higher_is_riskier` flags in `reporting.py:METRIC_DEFINITIONS`. - -## Implementation strategy - -- **First proof:** `srcly compare aa3ed35^ aa3ed35 --json` on srcly itself. -- **Primary seam:** a `snapshots` service that turns a ref (a SHA, a branch, `WORKTREE`, or `merge-base`) into a scannable directory plus a cache key. Everything after it treats both sides the same way. -- **Fast local loop:** `cd server && uv run pytest tests/test_compare*.py`. The tests use a real throwaway git repo built in `tmp_path`, which is cheap and needs no network. `cd client && pnpm test` covers the pure union-layout functions. -- **Local dependencies:** only the git CLI. It is real at every rung, because faking git would hide the exact path and rename behavior being tested. -- **Rollout and rollback:** compare is a new CLI subcommand, a new `/api/compare` router, and a compare mode reached through its own URL parameter. Removing the entry point removes the feature. - -## Milestone 1: `srcly compare` prints a correct compare payload - -This proves snapshot scanning and diff correctness with no UI. - -- **Change: ref resolution and snapshots** (`server/app/services/compare/snapshots.py`) - - Resolve refs with `git rev-parse`. `merge-base` means `git merge-base HEAD`, and `WORKTREE` means scan the repo root in place. - - For a commit, run `git worktree add --detach /snapshots/`, scan it, then run `git worktree remove --force` in a `finally` block. Prune stale snapshot directories when the service starts. - - Test: the user's branch, HEAD, stash list, and `git worktree list` are unchanged after the run, including after a forced exception. -- **Change: cache commit scans by SHA** (`services/cache.py`) - - Add a commit-keyed entry where the fingerprint is `sha + srcly version`, so no tree walk is needed. The working-tree side keeps the existing path and mtime fingerprint. - - Test: a second compare loads both commit sides from disk without starting a worker pool. -- **Change: the pure compare module** (`services/compare/diff.py`) - - Inputs are two `Node` trees, two `DepGraph`s, and the output of `git diff --name-status -M` plus `--numstat`. Paths are made relative to each snapshot root before matching, because `Node.path` is absolute and differs per snapshot. - - Outputs are a change set (added, removed, modified, renamed, with +/− lines) and per-file metric deltas, each marked better, worse, or neutral using `higher_is_riskier`. A net summary counts the changed files and sums their deltas. The edge diff lists dependency edges added and removed at file level, and flags edges that cross folders. - - Tests: fixture trees with rename, add, delete, a metric where lower is better, and an unchanged file. There are no git calls in these tests. -- **Change: the CLI subcommand** in `run.py` (`compare [head] [--json|--out DIR]`, head defaults to `WORKTREE`). It shares payload code with the future API. - -### Desired end state - -- `srcly compare aa3ed35^ aa3ed35 --json` lists all 15 changed files (7 added, 2 deleted, 6 modified), and a hand-checked sample of their deltas is correct. -- The dependency edge diff shows the new `deps/` modules wired in. -- The first run takes no more than about 2× a normal srcly scan, and the second run is served from the cache. -- **Decision:** if tsconfig or package-root resolution differs inside the snapshot directory, use the Spike below before Milestone 2. - -## Milestone 2: compare mode in the UI with a focused Explorer table - -This is the first visible proof. It is cheap because it reuses the Explorer. - -- **Change: API.** `POST /api/compare {base, head}` starts or joins a scan for each side through `ScanJobManager` and returns a compare job with SSE progress, following the `/api/scans` pattern. `GET /api/compare/{id}/result` returns the payload. Raise `MAX_MEMORY_ENTRIES` or pin the two compare entries so switching views does not evict a side. -- **Change: base content for the code viewer.** `GET /api/files/content?ref=` uses `git show`, because the before-side snapshot directory is deleted after its scan. -- **Change: the compare shell** (`client/src/compare/`). It has a ref picker with recent branches and commits, `merge-base` → `WORKTREE` as the default, and a swap button. The `?compare=base..head` URL parameter makes a view shareable. A summary strip shows file counts, net LOC, per-metric movement, and edges gained and lost. -- **Change: Explorer compare mode.** Rows are the changed files and their ancestor folders. Each metric column shows before → after with a signed delta in the existing ramp's good and bad colors, and you can sort by delta. A "show unchanged" toggle widens the list. - -### Desired end state - -- Opening `?compare=aa3ed35^..aa3ed35` shows only the 15 files and the summary strip, and a red delta means worse for that metric. -- Opening a removed file shows its base content. -- Vitest covers the compare row model, and pytest covers the API. - -## Milestone 3: side-by-side treemaps share one layout - -- **Change: union treemap layout** (`viz/treemap/utils/compare.ts`). Build a union hierarchy from the change set's paths, weight each tile by max(before LOC, after LOC), and run `d3.treemap` once. -- **Change: two canvases from one layout.** Each side fills its tile to its own LOC, using an inset rectangle scaled to the side's share of the area. Each side colors by the selected metric, and a missing file is drawn as an empty hatched slot. Zooming and selection are linked across both sides. -- **Spike: readability.** **Decision required:** whether max-weight tiles stay readable in PRs with many adds and deletes. **Evidence to gather:** screenshots of `aa3ed35` and `6687816` (15 added files). **Fallback:** group added and removed files into their own bands within each folder. - -### Desired end state - -- Every changed file is in the same place on both sides. A file that grew is visibly fuller on the right, and a deleted file is hatched on the right. -- A vitest test asserts that the tile rectangles are identical across the two sides. - -## Milestone 4: dependency graph before and after on one union layout - -- **Change: union graph view model.** Merge the two `DepGraph`s, giving each node and edge a status: both, before-only, or after-only. Focus by default on the changed files plus their 1-hop neighbors. Then run the existing `buildViewModel` budget and roll-up over the union. A rolled-up folder shows its own change counts. -- **Change: draw it twice.** Call `layoutViewSync` once and render two `DependencyCanvas` instances. The left draws removed items in strong color, the right draws added items, and unchanged items are muted. A changed file used by more than N files is drawn as "used by N" with one bundled edge. -- **Test:** vitest asserts identical box positions across both sides, and the existing geometry checks (zero edges through boxes) hold on the union. - -### Desired end state - -- The `88a48f1` compare shows the symbol-focus changes on the right, in the same positions as on the left. -- A hub-file change does not light up the whole graph. - -## Open decisions and spikes - -- **Snapshot path fidelity (Milestone 1).** **Decision required:** can a worktree in the cache directory resolve like the real checkout? **Evidence to gather:** compare the dependency graph of HEAD scanned in place with the same commit scanned as a snapshot. They should be identical. **Fallback:** create the snapshot as a sibling directory of the repo root. - -## Below the cut line - -- Change islands as a hint for splitting a PR. This is a cheap follow-on, because it needs only connected components over the edge diff. -- Ripple and frontier views, route and component lenses, and opening a GitHub PR by number. -- Rename matching at the symbol level, and side-by-side source diffs inside the code viewer. -- Comparing more than two refs, or watching a branch over time. diff --git a/docs/intent/pr-compare/initiative-map.json b/docs/intent/pr-compare/initiative-map.json deleted file mode 100644 index 802ca8a5..00000000 --- a/docs/intent/pr-compare/initiative-map.json +++ /dev/null @@ -1,403 +0,0 @@ -{ - "schema_version": "0.5.0", - "initiative": { - "title": "PR compare mode", - "slug": "pr-compare", - "scale": "capability", - "current_phase": "execution", - "last_updated": "2026-10-15", - "summary": "Compare two git commits (PR base vs head) in srcly: focused before/after tree and dependency graph views limited to changed files by default, with per-metric better/worse deltas, all deterministic from disk and git.", - "status": "active", - "next_action": "Review and squash-merge the stacked PRs in order: #37 docs → #38 CLI → #39 table → #40 treemap → #41 graph; then retire or extend the initiative" - }, - "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" - } - }, - "sources": [ - { - "id": "req-1", - "type": "request", - "location": "conversation", - "anchor": "initial request 2026-10-15", - "authority": "direct current intent" - }, - { - "id": "memo-2026-08-23", - "type": "transcript", - "location": "/Users/byronwall/.v2c-voice-memos/20260823-202007-6B46813F-context/transcript/transcript.txt", - "anchor": "Deterministic PR Diagramming via Data-Flow Views", - "authority": "prior first-party thinking; broader than this initiative" - }, - { - "id": "memo-2026-07-05", - "type": "transcript", - "location": "/Users/byronwall/.v2c-voice-memos/20260705-210437-CC6EF8BD-context/transcript/transcript.txt", - "anchor": "Code Visualization and Data-Flow Mapping (summary only)", - "authority": "adjacent background; weak match" - }, - { - "id": "repo-cache", - "type": "repository", - "location": "server/app/services/cache.py", - "anchor": "fingerprint / AnalysisCache", - "authority": "current implementation reality" - }, - { - "id": "repo-discover", - "type": "repository", - "location": "server/app/services/analysis.py", - "anchor": "discover_files (git ls-files)", - "authority": "current implementation reality" - }, - { - "id": "repo-depgraph", - "type": "repository", - "location": "server/app/routers/analysis.py", - "anchor": "get_dependency_graph; models.DepGraph", - "authority": "current implementation reality" - }, - { - "id": "repo-deps-client", - "type": "repository", - "location": "client/src/viz/deps/", - "anchor": "viewModel.ts, layout.ts (custom grid layout)", - "authority": "current implementation reality" - }, - { - "id": "init-dependency-view", - "type": "initiative", - "location": "docs/intent/dependency-view/", - "anchor": "active, stacked PRs awaiting merge", - "authority": "related initiative" - }, - { - "id": "qa-round-1", - "type": "question-round", - "location": "conversation", - "anchor": "1", - "authority": "direct current intent" - } - ], - "intent": { - "claims": [ - { - "id": "C1", - "statement": "Compare metrics and dependencies between two git commits, typically before/after a PR.", - "kind": "goal", - "strength": "must", - "sources": [ - "req-1" - ], - "confidence": "high" - }, - { - "id": "C2", - "statement": "Strong left/right (before/after) views of the tree view and the dependency graph.", - "kind": "requirement", - "strength": "must", - "sources": [ - "req-1", - "memo-2026-08-23" - ], - "confidence": "high" - }, - { - "id": "C3", - "statement": "The user can tell whether things got better or worse.", - "kind": "requirement", - "strength": "must", - "sources": [ - "req-1" - ], - "confidence": "high" - }, - { - "id": "C4", - "statement": "Views are truncated/focused to only changed files by default.", - "kind": "requirement", - "strength": "must", - "sources": [ - "req-1", - "memo-2026-08-23" - ], - "confidence": "high" - }, - { - "id": "C5", - "statement": "The diagram is generated deterministically from disk and diff with no LLM in the path.", - "kind": "constraint", - "strength": "must", - "sources": [ - "memo-2026-08-23" - ], - "confidence": "high" - }, - { - "id": "C6", - "statement": "Unchanged nodes appear in the same positions on both sides so before/after connectivity is comparable.", - "kind": "requirement", - "strength": "must", - "sources": [ - "memo-2026-08-23" - ], - "confidence": "high" - }, - { - "id": "C7", - "statement": "Widely used changed components should be surfaced as such rather than lighting up everything.", - "kind": "requirement", - "strength": "should", - "sources": [ - "memo-2026-08-23" - ], - "confidence": "medium" - }, - { - "id": "C8", - "statement": "Change islands / PR splittability, ripple-frontier, and route/component lenses are longer-horizon ideas.", - "kind": "possibility", - "strength": "could", - "sources": [ - "memo-2026-08-23" - ], - "confidence": "medium" - }, - { - "id": "C9", - "statement": "Show changed files with +/- line counts grouped by folder (memo notes GitHub file tree lacks per-file magnitude).", - "kind": "possibility", - "strength": "should", - "sources": [ - "memo-2026-08-23" - ], - "confidence": "medium" - }, - { - "id": "C10", - "statement": "Show per-metric deltas plus a neutral net line; no overall verdict.", - "kind": "decision", - "strength": "must", - "sources": [ - "qa-round-1" - ], - "confidence": "high" - }, - { - "id": "C11", - "statement": "Side-by-side treemaps are in v1 alongside the Explorer compare table.", - "kind": "decision", - "strength": "must", - "sources": [ - "qa-round-1" - ], - "confidence": "high" - }, - { - "id": "C12", - "statement": "Default head is the working tree; base and head must be configurable to arbitrary commits early.", - "kind": "decision", - "strength": "must", - "sources": [ - "qa-round-1" - ], - "confidence": "high" - } - ], - "themes": [ - "before/after alignment", - "focus on changed set", - "metric direction", - "determinism" - ], - "conflicts": [], - "human_questions": [] - }, - "brainstorm": { - "status": "not-requested", - "requested_count": 7, - "options": [], - "selected_option": null - }, - "shape": { - "status": "current", - "appetite": "One compare mode over existing tree, metrics, and dependency graph. No new analyzers, call graph, or GitHub API.", - "problem": "Judging a PR's structural effect today means scanning two checkouts by hand and eyeballing two full-repo views.", - "recommended_shape": "Snapshot both commits via detached git worktrees, scan with the normal pipeline cached by SHA, diff server-side into one compare payload, and render focused before/after Explorer and a union-layout dependency graph drawn twice.", - "success_moves": [ - { - "id": "S1", - "move": "Cache scans by commit SHA instead of mtime fingerprint.", - "benefit": "Commits are immutable; repeated compares are instant and the fingerprint walk is skipped." - }, - { - "id": "S2", - "move": "Pure Python compare module (two trees + two graphs + git name-status -> payload) shared by UI and future CLI.", - "benefit": "One definition of better/worse; fixture-testable in pytest with no git or UI." - }, - { - "id": "S3", - "move": "Union-graph layout computed once, filtered per side.", - "benefit": "Guarantees stable positions without a new layout engine; reuses pure grid layout." - }, - { - "id": "S4", - "move": "First proof is CLI JSON on srcly's own history before any UI.", - "benefit": "Proves snapshot path resolution and delta correctness, the riskiest backend pieces, cheaply." - }, - { - "id": "S5", - "move": "Compare mode is a separate view; single-scan view untouched.", - "benefit": "Rollback is removing an entry point; no regression risk to the main view." - } - ], - "first_proof": { - "question": "Can srcly snapshot two commits, scan both with correct path resolution, and produce a correct change set with metric deltas and dependency edge diffs at acceptable cost?", - "artifact": "CLI JSON for aa3ed35^ -> aa3ed35 on srcly; rename fixture in pytest", - "decision_rule": "Deltas match hand-checked sample and both scans < ~2x a normal scan -> build UI on payload. Path resolution breaks in snapshots -> switch to git archive into a mirrored path first." - }, - "rabbit_holes": [ - "Treemap union layout with max-weight tiles: verify readability when many files are added or removed", - "Rename matching for symbols (not just files)", - "Hub files lighting up the whole graph", - "Working-tree side uses fingerprint cache while commit sides use SHA cache", - "Scan time for two full scans on large repos" - ], - "open_decisions": [] - }, - "implementation": { - "status": "completed", - "repository_snapshot": { - "root": "/Users/byronwall/Projects/srcly", - "revision": "11d098c", - "worktree_status": "clean", - "subsystems": [ - "server/app/services/analysis.py", - "server/app/services/cache.py", - "server/app/services/deps/", - "client/src/viz/deps/", - "client/src/components/Explorer.tsx" - ], - "test_commands": [ - "cd server && uv run pytest", - "cd client && pnpm test" - ], - "deployment_surfaces": [] - }, - "dependencies": [ - { - "name": "git CLI (worktree add/remove, diff --name-status -M, merge-base)", - "first_proof_role": "real", - "strategy": "Real local git on srcly repo; pure compare module tested with fixture trees and name-status text." - } - ], - "fast_local_loop": "cd server && uv run pytest tests/test_compare*.py (real throwaway git repo in tmp_path); cd client && pnpm test for union layouts", - "milestones": [ - { - "id": "m1", - "title": "srcly compare prints a correct compare payload", - "outcome": "Headless CLI snapshots two refs, scans both (SHA-cached), and emits change set, metric deltas, and dependency edge diff as JSON.", - "dependencies_introduced": [ - "git CLI worktree/diff" - ], - "proof": "pytest fixtures (rename/add/delete/inverted metric) + srcly compare aa3ed35^ aa3ed35 lists 15 files with hand-checked deltas; second run from cache; <=2x scan time.", - "valid_intermediate_state": "New CLI subcommand only; UI untouched.", - "rollback": "Remove the subcommand and compare package.", - "status": "completed", - "evidence": [ - "PR byronwall/srcly#38; server/tests/test_compare_diff.py, test_compare_snapshots.py; aa3ed35^..aa3ed35 lists 15 files, 3.7s cold / 0.5s cached" - ] - }, - { - "id": "m2", - "title": "Compare mode in the UI with a focused Explorer table", - "outcome": "?compare=base..head shows ref picker, summary strip, and changed-files-only Explorer with before->after deltas.", - "dependencies_introduced": [], - "proof": "Browser check on aa3ed35 compare; vitest compare row model; pytest /api/compare.", - "valid_intermediate_state": "Compare mode is a separate URL-gated view; single-scan view unchanged.", - "rollback": "Remove the compare entry point.", - "status": "completed", - "evidence": [ - "PR byronwall/srcly#39 (redesigned: scorecard rail, per-file verdicts, magnitude bars, inspector); server/tests/test_compare_api.py, client/src/compare/rows.test.ts" - ] - }, - { - "id": "m3", - "title": "Side-by-side treemaps share one layout", - "outcome": "Union treemap weighted by max(before, after), drawn twice with fill-to-size and hatched absent slots.", - "dependencies_introduced": [], - "proof": "vitest identical rects across sides; screenshots of aa3ed35 and 6687816.", - "valid_intermediate_state": "Treemap tab added to compare mode; table still works alone.", - "rollback": "Hide the treemap tab.", - "status": "completed", - "evidence": [ - "PR byronwall/srcly#40; client/src/compare/treemapLayout.test.ts; screenshots of aa3ed35 and 6687816" - ] - }, - { - "id": "m4", - "title": "Dependency graph before and after on one union layout", - "outcome": "Union DepGraph focused on changed files + 1 hop, laid out once, rendered twice with removed/added emphasis and hub collapse.", - "dependencies_introduced": [], - "proof": "vitest identical box positions and zero edge-through-box on union; 88a48f1 compare visual check.", - "valid_intermediate_state": "Graph tab added to compare mode.", - "rollback": "Hide the graph tab.", - "status": "completed", - "evidence": [ - "PR byronwall/srcly#41; client/src/compare/graphModel.test.ts incl. zero node crossings" - ] - } - ], - "cut_line": [ - "change islands", - "ripple/frontier view", - "route/component lenses", - "GitHub PR by number", - "symbol-level rename matching", - "source diff in code viewer", - "more than two refs / branch over time" - ], - "open_decisions": [] - }, - "history": [ - { - "date": "2026-10-15", - "event": "Initiative created from request, 2026-08-23 PR diagramming memo, and repository survey; intent and shape briefs written." - }, - { - "date": "2026-10-15", - "event": "Question round 1: per-metric + net, treemaps in v1, working-tree default with arbitrary refs. Shape updated: treemap union layout added." - }, - { - "date": "2026-10-15", - "event": "Implementation plan written: CLI payload first (m1), then Explorer (m2), treemap (m3), dependency graph (m4). Headless compare moved from evaluate into m1." - }, - { - "date": "2026-10-15", - "event": "Implemented m1–m4 as stacked PRs #38–#41 on top of docs PR #37. Spikes resolved: snapshot graph identical to in-place (keep cache-dir worktrees); max-weight treemap readable on add-heavy 6687816 (no band fallback). Deviations: treemap tiles use √LOC so small edits stay visible; summed metrics judged like-for-like; compare table redesigned with scorecard, verdicts, inspector at user request." - }, - { - "date": "2026-10-15", - "event": "2026-10-15 voiceover: follow-up compare-ref-picker promotes GitHub PR picking and commit stepping from the cut line." - } - ], - "closure": null -} diff --git a/docs/intent/pr-compare/intent-brief.md b/docs/intent/pr-compare/intent-brief.md deleted file mode 100644 index ba76970f..00000000 --- a/docs/intent/pr-compare/intent-brief.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "PR compare mode" -slug: "pr-compare" -phase: intent -status: current -last_updated: "2026-10-15" ---- - -# PR compare mode - -## My read - -You want srcly to answer "what did this PR do to the codebase, and did it make things better or worse?" in one glance. You'd pick two commits, usually the PR's base and its head. srcly analyzes both and shows them side by side: the file tree and the dependency graph, before on the left and after on the right. - -The views are focused by default. Only the files the PR touched appear, plus just enough nearby context to make sense of them. You can widen the view on request. The tool doesn't hand you two full dashboards to compare by eye. - -The output has to be deterministic. It comes straight from the code on disk and the git diff, with no LLM in the loop. The 2026-08-23 memo frames this as the bar for a trustworthy PR diagram. Once the analysis exists, lighting up a change on it is "a pretty straightforward matter". - -That memo also asks a broader question: are a PR's changes coherent, or could they be split? It suggests answering it with "islands of change" and how far an edit ripples up and down the call chain. That is the longer horizon. This initiative is about srcly's existing tree, metrics, and dependency graph. - -## What matters most - -- **Strong before/after left/right views** of the tree and the dependency graph, with unchanged items in the same place on both sides. -- **A clear better/worse signal** from metric deltas (complexity, size, nesting, coupling) whose direction you can read at a glance. -- **Focused on the changed files by default**, so a 12-file PR in a 2,000-file repo reads like a 12-file PR. - -## The experience you appear to want - -Pick any two refs, or accept the default: the working tree against its merge-base with `main`. srcly scans both. The landing view summarizes the PR: files added, removed, and modified, net metric movement, and edges gained or lost. The tree lists only the changed files, with before → after values and colored deltas. The dependency graph shows the changed files and their direct neighbors twice, before and after. Each side marks what was removed or added, and both share one layout so your eye can jump between them. Widening the focus brings in unchanged context, which renders quietly. - -## Boundaries - -### Must be true - -- The same two commits always produce the same picture. -- Nodes that exist on both sides sit in the same position on both sides. -- "Better" and "worse" follow each metric's real direction. srcly already records which metrics are lower-is-better. -- Scanning a commit leaves your working tree, branch, and stash alone. - -### Must be avoided - -- Two independent full-repo renders that you have to diff by eye. -- Lighting up the whole graph when a widely used file changes, without saying that's what happened. -- An LLM-generated summary standing in for the analysis. - -## What seems settled - -- The comparison runs between two git commits. -- It covers the tree view and the dependency graph first. "Other metrics" means the existing per-file metrics. -- Focusing on changed files is the default, not an option. - -## Possibilities, not decisions - -- Change "islands": finding groups of changed files that don't connect, as a sign the PR could be split. -- Ripple and frontier views (callers of a changed function that did or didn't need edits), plus route and component lenses from the tsx-data-flow memo. -- Opening a GitHub PR by number, or a headless `srcly compare` report for agents and CI. - -## Current reality that matters - -- Scans target a directory, and the cache is keyed by path plus an mtime fingerprint. Nothing yet scans a commit that isn't checked out. -- The dependency graph uses one language-neutral contract (folder → file → symbol, for TS and Python), and the client does the roll-up and layout. A diff of two graphs fits that contract naturally. -- The dependency layout is srcly's own grid layout (`client/src/viz/deps/layout.ts`), not ELK. Pinning a shared layout across two graphs is under our control. -- The dependency-view initiative is still active, with stacked PRs awaiting merge. Compare mode builds on top of it. - -## Decided in question round 1 - -- Per-metric movement plus a neutral net line, with no overall verdict. -- "Tree view" covers the Explorer table and side-by-side treemaps in v1. -- The default head is the working tree. Base and head can be set to any commit, because comparing arbitrary commits is coming soon. - -## Next step after confirmation - -Next is an implementation plan with a first proof on srcly's own history. diff --git a/docs/intent/pr-compare/shape-brief.md b/docs/intent/pr-compare/shape-brief.md deleted file mode 100644 index 3f25a4e2..00000000 --- a/docs/intent/pr-compare/shape-brief.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "PR compare mode — shape brief" -slug: "pr-compare" -phase: shape -status: current -last_updated: "2026-10-15" ---- - -# PR compare mode — what we are adding - -**Outcome:** For any two commits, you can see what changed in the file tree and the dependency graph, side by side. You can also tell whether each changed area got better or worse. - -**Primary flow:** Choose base and head (default: merge-base with `main` → working tree; any two commits from a picker) → srcly scans both → PR summary → focused before/after tree and dependency graph → widen for context. - -## Feature scope - -```text -PR compare mode -├── PLANNED ADDITIONS -│ ├── Snapshots: any commit, branch, or the working tree on either side -│ │ ├── commits are checked out read-only into a temp directory and scanned normally, cached by SHA -│ │ └── the working tree is scanned in place with the existing fingerprint cache -│ ├── Change set: added / removed / modified / renamed files from git, with +/- lines -│ ├── PR summary strip -│ │ ├── file counts by change type, net LOC -│ │ ├── per-metric movement over changed files (complexity, nesting, size, fan-in/out) -│ │ └── edges gained / lost, cross-folder edges called out -│ ├── Tree compare (Explorer in compare mode) -│ │ ├── only changed files plus their ancestor folders by default -│ │ ├── before → after columns with a signed delta, green or red by each metric's direction -│ │ └── "show unchanged" toggle and sorting by the size of the delta -│ ├── Treemap compare -│ │ ├── one layout over the union tree, each tile sized by max(before, after), drawn twice -│ │ ├── each side fills its tile to its own size; an empty hatched slot marks a file absent on that side -│ │ └── default scope is changed files and their folders; color uses the existing metric ramp -│ ├── Dependency compare -│ │ ├── one layout computed over the union of both graphs, drawn twice (left = before, right = after) -│ │ ├── left marks removed nodes and edges, right marks added; unchanged items are muted and stay in place -│ │ ├── default focus is the changed files plus 1-hop neighbors; the existing roll-up budget still applies -│ │ └── a widely used changed file shows "used by N files" instead of drawing every edge -│ └── Entry points: compare picker in the app shell, a shareable base/head URL, and `srcly compare` JSON for agents -├── EVALUATE BEFORE COMMITTING -│ └── change islands: connected groups of changed files as a hint for splitting the PR -└── LATER POSSIBILITIES - ├── ripple / frontier view: callers of a changed symbol that did or did not change - ├── route and component lenses (tsx-data-flow memo) - └── open a GitHub PR by number -``` - -## Behavior - -| Situation | Expected result | -| --- | --- | -| A file exists in both commits | Same box, same position on both sides; delta badges only on the right | -| A file was renamed | Matched by git rename detection and drawn as one moved node, not a delete plus an add | -| A metric where lower is better rises | The delta is red, whatever its sign | -| The changed set exceeds the budget | Folders roll up as they do today, and a rolled-up folder shows its own change counts | -| A widely used utility changed | It is marked "used by N files" with a bundled edge, and the rest of the graph is not lit up | -| A file grew from 100 to 400 LOC | Its treemap tile sits in the same place on both sides; the left fills a quarter of it, the right fills all of it | - -## Decisions and boundaries - -**Appetite:** One compare mode over the existing tree, metrics, and dependency graph. No new analyzers, no call-graph analysis, and no GitHub API. - -**Key decisions:** -- **Union layout, drawn twice, for both the treemap and the graph.** Laying out each side on its own would move boxes between the two views. This shape lays out the union once and filters what each side shows. That guarantees stable positions. The existing grid layout handles the graph, and the treemap only needs different tile weights. -- **Diff on the server, drawing on the client.** A pure Python module turns two cached trees and two graphs into one compare payload: the change set, node status, and metric deltas. The UI and a future headless report share one definition of better and worse. -- **Snapshots via `git worktree add --detach` into srcly's cache directory**, removed after the scan. It leaves your checkout, branch, and stash alone, and it keeps the path layout real so tsconfig and package roots resolve. - -**Boundary:** Compare mode is a separate view. The normal single-scan view stays as it is. Repositories that aren't git and commits outside the local clone are out of scope. - -**First proof:** **Try:** Compare `aa3ed35^` → `aa3ed35` (the language-neutral graph PR, with 7 files added, 2 deleted, and 6 modified) on srcly itself, from the command line. Snapshot and scan both commits, then print the change set, metric deltas for each changed file, and the added and removed dependency edges as JSON. **Observe:** Every file from `git diff --name-status` appears with plausible deltas, and a second run finishes from the cache. **Decide:** If the deltas match a hand-checked sample and both scans take under about 2× a normal scan, build the compare UI on this payload. If snapshot scanning breaks path resolution, switch to `git archive` into a mirror of the path before building any UI. - -**Settled:** per-metric deltas plus a neutral net line, with no overall verdict. Treemaps are in v1. The default head is the working tree, and both sides can be set to any commit. - -See [intent-brief.md](intent-brief.md).