From adf11cc3cf6b570e1ecd177354a531e4f1e400b0 Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Thu, 12 Nov 2026 21:52:07 -0500 Subject: [PATCH] docs: retire compare-ref-picker All four milestones merged on 2026-10-15 (#47, #52, #54, #59). 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 | 8 + docs/initiative-history.json | 15 + .../compare-ref-picker/implementation-plan.md | 115 ---- .../compare-ref-picker/initiative-map.json | 549 ------------------ .../intent/compare-ref-picker/intent-brief.md | 83 --- docs/intent/compare-ref-picker/shape-brief.md | 81 --- 6 files changed, 23 insertions(+), 828 deletions(-) delete mode 100644 docs/intent/compare-ref-picker/implementation-plan.md delete mode 100644 docs/intent/compare-ref-picker/initiative-map.json delete mode 100644 docs/intent/compare-ref-picker/intent-brief.md delete mode 100644 docs/intent/compare-ref-picker/shape-brief.md diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index 07c3c56d..bef0addc 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -181,6 +181,14 @@ 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` | +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. +- `gh` is a seam with a timeout and a stated failure reason. Without `gh` or a network, the picker still lists worktrees and branches, and free-text refs still work. +- The picker hides prunable worktrees. A worktree head is scanned in place. Compare never changes any worktree's state. +- A commit's result is cached by SHA. The stepper pre-warms the next commit, so stepping through a PR does not repeat cold scans. +- Phase timings show where a slow first run spends its time. + ### Client: app shell and first run | Feature | Where | diff --git a/docs/initiative-history.json b/docs/initiative-history.json index c766c1c5..76700bac 100644 --- a/docs/initiative-history.json +++ b/docs/initiative-history.json @@ -13,5 +13,20 @@ "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)." ] + }, + { + "title": "Compare ref picker: PRs, worktrees, commits", + "slug": "compare-ref-picker", + "outcome": "completed", + "retired_at": "2026-11-12", + "summary": "Compare now resolves pr: refs through a gh seam with phase timings, offers a picker over PRs, worktrees and branches, compares another worktree on disk as the head, and steps through a PR commit by commit. Reconciled against origin/main 0bfb05ba.", + "reason": "All four milestones merged on 2026-10-15 (#47, #52, #54, #59).", + "documentation": [ + "docs/CODE_MAP.md" + ], + "revision": "0bfb05ba", + "follow_ups": [ + "Evaluate dependency compare on a real PR (claim C7). Nothing tracks it." + ] } ] diff --git a/docs/intent/compare-ref-picker/implementation-plan.md b/docs/intent/compare-ref-picker/implementation-plan.md deleted file mode 100644 index 3c5c9f49..00000000 --- a/docs/intent/compare-ref-picker/implementation-plan.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Compare ref picker — implementation plan" -slug: "compare-ref-picker" -phase: plan -status: current -last_updated: "2026-10-15" ---- - -# Compare ref picker — implementation plan - -## Plan at a glance - -The plan proves PR resolution before building any picker. Milestone 1 adds a `gh` seam and a sources endpoint. It also adds `pr:` as a ref that `resolve_ref` understands. That makes `srcly compare pr:1922` from the CLI the first proof. It answers the question that would sink the feature: does the PR's own base give the same diff as GitHub, including for stacked PRs? It costs one server change and no UI. - -Milestone 2 replaces the datalist with the picker, using sources that load independently. Milestone 3 makes "another worktree" a head. It reuses the existing in-place scan, so no new snapshot machinery is needed. Milestone 4 adds the commit stepper. Phase timings land in Milestone 1, so every later speed decision rests on measurements instead of the feeling that "the first run was slow". - -**Pushback:** -- The shape puts the picker first. The plan puts `pr:` ref resolution first, because the CLI, the URL (`?compare=pr:1922..`) and the picker can all share it. One resolver also means one place to get stacked bases right. -- `gh` is used only through `run_gh`, a single monkeypatchable function, so tests never need the network. - -## Implementation strategy - -- **First proof:** `srcly compare pr:1925` and `srcly compare pr:1922` on modeler. The changed-file counts must equal `gh pr view N --json changedFiles`. -- **Primary seam:** `services/compare/github.py`. `run_gh(repo, *args)` handles the timeout, the JSON parse, and the reasons for failure (no binary, not authenticated, no network). On top of it sit `list_prs(repo)` and `pr_info(repo, n)`. -- **Fast local loop:** `cd server && uv run pytest tests/test_compare*.py`. It uses the real-git `repo` fixture (`tests/test_compare_snapshots.py:40-57`) and monkeypatches `run_gh` with recorded JSON. Client: `cd client && pnpm test`. -- **Local dependencies:** git is real at every rung, as today. `gh` is faked in tests and real only in manual modeler checks. -- **Live confirmation:** run the CLI and the UI by hand on modeler PRs #1925 (base `main`) and #1922 (stacked). Record before/after timings in the PR description, not in the repo, since srcly is public. -- **Rollout and rollback:** the free-text base/head fields stay under "Advanced". Any source the picker can't load hides itself and shows a reason. Reverting Milestone 2 brings back the old RefBar. - -### Material dependency proof strategy - -`gh` is the only new external dependency. - -```text -recorded gh JSON via monkeypatched run_gh (pytest) - → real gh on modeler, by hand (CLI + UI) -``` - -No contract suite is needed, because the server reads only fields that are stable in `gh pr list --json`. - -## Milestone 1: `pr:` resolves to a GitHub-equal compare, with phase timings - -- **Change: gh seam** (`server/app/services/compare/github.py`, new) - - `run_gh(repo, *args, timeout=10)` runs `subprocess.run(["gh", ...], cwd=repo)`. A missing binary, a non-zero exit or a timeout comes back as `GhUnavailable(reason)`. - - `list_prs(repo, mine=True)` runs `gh pr list [--author @me] --limit 50 --json number,title,headRefName,baseRefName,headRefOid,isDraft,reviewDecision,updatedAt,author,statusCheckRollup`. The result is cached in memory for 60s per repo. - - Tests: monkeypatch `run_gh` for the success path, the missing-gh path, and the non-zero exit path. -- **Change: resolve `pr:`** (`git_refs.py:99-107`) - - Base is `git merge-base origin/ `. If that ref is missing, fall back to the local ``. - - Head is `headRefOid`. If the commit isn't local, run `git fetch origin pull//head`, which only fetches objects (no branch or worktree change). Then verify the commit again. - - `ResolvedRef.label` becomes `# `. - - Tests: build a stacked branch in the fixture repo, fake the PR JSON, and check that the change set holds only the top PR's files. -- **Change: phase timings** (`jobs.py:109-112` `_set_phase`) - - Record `phase_seconds` in the snapshot (`jobs.py:73-83`). - - `CompareProgress.tsx` shows the elapsed time per phase, plus "cached" from `payload.base` and `payload.head` (`service.py:20-29`). -- **Change: path passthrough.** `fetchRefs` and `startCompare` (`client/src/compare/api.ts:53-60`) send the analyzed repo path instead of relying on the server's `ROOT_PATH`. - -### Desired end state - -- `srcly compare pr:1925` and `pr:1922` on modeler match GitHub's changed-file counts. -- The progress panel shows where a cold compare spends its time. -- **Decision:** if stacked PRs mismatch because of rebases or force-pushes, use the PR's merge commit base from `gh pr view --json baseRefOid` instead. - -## Milestone 2: Rich picker with independent sources - -- **Change: `GET /api/compare/sources?path=&kind=prs|worktrees|branches`** (`routers/compare.py`) - - Each kind is fetched separately, so the git kinds return immediately. - - Worktrees come from `git worktree list --porcelain`, with prunable entries and srcly's own `snapshots/` entries dropped. They are sorted by HEAD commit date. This follows the parser in `git-visual-files/src/lib/gitWorktrees.ts:75-184`. - - Branches come from `for-each-ref refs/heads refs/remotes` with `%(upstream:track)`, as in `git-visual-files/src/lib/gitBranchSummaries.ts:188-227`. - - Tests: fixture repo with two worktrees, one of them prunable. -- **Change: `ComparePicker.tsx`**, a popover that replaces the datalist (`client/src/compare/RefBar.tsx:28-57`). - - It has sections for My PRs (with an "all open" toggle), Worktrees and Branches, plus search, and Advanced holding the old free-text fields. - - PR rows show #, title, head → base, draft or review state, a checks summary, the update time, and the badges "worktree" and "needs fetch". - - Picking a PR navigates to `?compare=pr:<n>..pr:<n>` (`compareHref`, `api.ts:119-124`). The resolver treats `pr:n` on the base side as the PR base. - - Use the shared `Popover`. If quick-fix PR D has landed, pick up its fixes. -- **Change: PR context in the header.** When the compare is a PR, the summary strip shows the PR title and number. - -### Desired end state - -- Opening the picker on modeler renders the worktree and branch sections in under 300ms. PRs appear within about 2s, or a reason is shown. -- One click on a PR lands on the correct compare, and the URL can be shared. - -## Milestone 3: A worktree as the head - -- **Change: a `worktree:<path>` head ref** - - `ResolvedRef` gains `dir: Optional[Path]`. - - `load_side` calls `_load_worktree(dir)` (`snapshots.py:247-276`). That cache is keyed by absolute path, so worktrees don't collide. - - `list_changes` runs with `cwd=dir` for the head (`git_refs.py:113-155`). - - Base: the PR base when `list_prs` finds an open PR for the worktree's branch, otherwise the merge-base with the default branch. - - Tests: compare a second worktree of the fixture repo that has uncommitted edits. The result shows those edits, and neither worktree's state changes. -- **Change:** the picker's worktree rows produce `?compare=auto..worktree:<path>`. - -### Desired end state - -- Picking any live modeler worktree compares it correctly, without a checkout, using its PR base when one exists. - -## Milestone 4: Commit stepper inside a PR or range - -- **Change: `GET /api/compare/commits?base=&head=`** returns `git rev-list --first-parent --reverse base..head` with subjects. Cap it at 100 commits. -- **Change: `CommitStepper.tsx`** under the summary strip: a strip of commits with ◀ ▶ buttons and click-to-select. Step i navigates to `c[i-1]..c[i]`, where `c[-1]` is the merge-base. The whole-PR view stays one click away. -- **Spike: parallel sides or pre-warming.** Use the Milestone 1 timings. - - **Decision required:** keep sequential sides, run them in parallel (`service.py:49-67`), or pre-warm the next step's side. - - **Evidence to gather:** cold-side seconds on modeler, with sequential vs parallel scans under the shared process pool. - - **Fallback:** keep sequential sides and pre-warm only the next commit. - -### Desired end state - -- Stepping forward through a modeler PR costs at most one new side scan per step. -- Each step shows only that commit's changes. - -## Below the cut line - -- Reusing per-file analysis across commits, keyed by blob hash. -- A `?pr=1922` shorthand and `srcly compare --pr` sugar. `pr:<n>` already covers both. -- PRs from forks whose head can't be fetched. -- Review comments and check details inside srcly. diff --git a/docs/intent/compare-ref-picker/initiative-map.json b/docs/intent/compare-ref-picker/initiative-map.json deleted file mode 100644 index 2631c394..00000000 --- a/docs/intent/compare-ref-picker/initiative-map.json +++ /dev/null @@ -1,549 +0,0 @@ -{ - "schema_version": "0.5.0", - "initiative": { - "title": "Compare ref picker: PRs, worktrees, commits", - "slug": "compare-ref-picker", - "scale": "capability", - "current_phase": "plan", - "last_updated": "2026-10-15", - "summary": "Replace free-text compare refs with a rich picker of open PRs (via gh CLI), worktrees, and branches; picking a PR sets base/head; add commit-by-commit stepping inside a PR; keep compares fast.", - "status": "planned", - "next_action": "Worker: implement m1 (pr:<n> resolution + gh seam + phase timings)" - }, - "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": "pr-compare", - "relation": "follow-up; promotes 'GitHub PR by number' and 'more than two refs / branch over time' from its cut line" - } - ], - "sources": [ - { - "id": "req-1", - "type": "request", - "location": "conversation", - "anchor": "2026-10-15 request", - "authority": "direct current intent" - }, - { - "id": "vo-1541", - "type": "voiceover-transcript", - "location": "/Users/byronwall/Movies/ContextRecorder/2026-10-15_08-58-32/session.md + frames/023.jpg", - "anchor": "15:41-15:58 mark 023 compare slower than expected; later fast, maybe cached", - "authority": "direct current intent" - }, - { - "id": "vo-1558", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "15:58-16:19 woefully underpowered picking; tons of worktrees and PRs; PR viewer showing a PR's diff", - "authority": "direct current intent" - }, - { - "id": "vo-1619", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "16:19-16:29 commit-level viewer inside a PR, current vs previous commit", - "authority": "direct current intent" - }, - { - "id": "vo-1629", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "16:29-16:45 reference: visual git exploration project on this computer", - "authority": "direct current intent" - }, - { - "id": "vo-1645", - "type": "voiceover-transcript", - "location": "session.md + frames/024.jpg", - "anchor": "16:45-16:56 mark 024 treemap compare so good; dep compare okay, needs a real PR", - "authority": "direct current intent" - }, - { - "id": "vo-1656", - "type": "voiceover-transcript", - "location": "session.md", - "anchor": "16:56-17:06 quickly select correct working spot; run gh CLI for rich context; rich nice picker", - "authority": "direct current intent" - }, - { - "id": "repo-refbar", - "type": "repository", - "location": "client/src/compare/RefBar.tsx", - "anchor": "datalist L28-38; free-text inputs L39-57; swap disabled for WORKTREE L58-68", - "authority": "current implementation reality" - }, - { - "id": "repo-refs-api", - "type": "repository", - "location": "server/app/routers/compare.py", - "anchor": "GET /api/compare/refs L52-86 (20 local branches, 30 commits)", - "authority": "current implementation reality" - }, - { - "id": "repo-snapshots", - "type": "repository", - "location": "server/app/services/compare/snapshots.py", - "anchor": "worktree add L126-140; SideCache LRU 40 L37,58-116; load_side full scan L210-244", - "authority": "current implementation reality" - }, - { - "id": "repo-service", - "type": "repository", - "location": "server/app/services/compare/service.py", - "anchor": "build_compare sequential sides L32-72", - "authority": "current implementation reality" - }, - { - "id": "repo-git-refs", - "type": "repository", - "location": "server/app/services/compare/git_refs.py", - "anchor": "pseudo-refs L10-13; default_branch L82-96; resolve_ref L99-107", - "authority": "current implementation reality" - }, - { - "id": "prior-igitit", - "type": "repository", - "location": "/Users/byronwall/repos/git-visual-files", - "anchor": "src/lib/gitWorktrees.ts L157-161 (git worktree list --porcelain); src/lib/gitBranchSummaries.ts L188-199 (for-each-ref with upstream:track); src/lib/gitFileCommits.ts L214-237 (git log forkBase..target); src/components/RefPicker.tsx, WorktreePopover.tsx, RepoTimelineDrawer.tsx", - "authority": "user-referenced prior art" - }, - { - "id": "prior-gh-graphql", - "type": "repository", - "location": "/Users/byronwall/repos/daily-planning/viewer/link-metadata.ts", - "anchor": "L86 execFile gh api graphql; reads stdout on non-zero exit", - "authority": "reusable pattern" - }, - { - "id": "prior-pr-compare", - "type": "prior-initiative", - "location": "docs/intent/pr-compare/initiative-map.json", - "anchor": "cut_line: 'GitHub PR by number', 'more than two refs / branch over time'", - "authority": "earlier agent-recorded deferral" - }, - { - "id": "qa-round-1", - "type": "question-round", - "location": "conversation", - "anchor": "2026-10-15 round 1", - "authority": "direct current intent" - }, - { - "id": "probe-modeler-gh", - "type": "probe", - "location": "/Users/byronwall/repos/modeler", - "anchor": "2026-10-15: gh pr list ~2.0s; PRs stacked (1927 base codex/concurrency-02-trace-visibility, 1922 base codex/concurrency-05-build-reuse, 1925 base main); git worktree list = 240 entries incl. prunable", - "authority": "observed environment fact" - } - ], - "intent": { - "claims": [ - { - "id": "C1", - "type": "problem", - "statement": "Choosing what to compare is woefully underpowered for someone with many worktrees and PRs.", - "commitment": "repeated", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1558", - "vo-1656" - ], - "code_anchors": [ - "client/src/compare/RefBar.tsx:28-57", - "server/app/routers/compare.py:52-86" - ] - }, - { - "id": "C2", - "type": "desired experience", - "statement": "Select by PR: picking a PR shows that PR's diff.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1558" - ] - }, - { - "id": "C3", - "type": "desired experience", - "statement": "Select by worktree, alongside PRs.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1558" - ], - "code_anchors": [ - "/Users/byronwall/repos/git-visual-files/src/lib/gitWorktrees.ts:157-184" - ] - }, - { - "id": "C4", - "type": "decision", - "statement": "Use the gh CLI to gather rich PR context for a rich picker.", - "commitment": "explicit", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1656" - ], - "code_anchors": [ - "/Users/byronwall/repos/daily-planning/viewer/link-metadata.ts:86" - ] - }, - { - "id": "C5", - "type": "desired experience", - "statement": "Within a PR, a commit-level viewer comparing each commit to its predecessor to see the PR's development.", - "commitment": "tentative", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1619" - ], - "notes": "'Maybe within a PR'" - }, - { - "id": "C6", - "type": "problem", - "statement": "Compare felt much slower than expected on first run; a repeat was fast (likely cache).", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1541" - ], - "code_anchors": [ - "server/app/services/compare/service.py:32-72 sequential sides", - "server/app/services/compare/snapshots.py:210-244 full scan per side", - "server/app/services/compare/snapshots.py:37 MAX_SIDE_ENTRIES=40" - ] - }, - { - "id": "C7", - "type": "preference", - "statement": "Compare treemap is very good; dependency compare is okay and needs a real-PR evaluation.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "proof", - "sources": [ - "vo-1645" - ] - }, - { - "id": "C8", - "type": "example", - "statement": "The prior visual-git exploration project is a reference for picker and timeline patterns.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "vo-1629", - "prior-igitit" - ] - }, - { - "id": "C9", - "type": "constraint", - "statement": "Picker must degrade gracefully without gh or network; deterministic results and no working-tree mutation continue to hold.", - "commitment": "derived", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "prior-pr-compare" - ] - }, - { - "id": "C10", - "type": "derived implication", - "statement": "Commit stepping multiplies cold-scan cost unless per-file results are reused across commits.", - "commitment": "derived", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "repo-snapshots" - ] - }, - { - "id": "C11", - "type": "decision", - "statement": "A picked worktree compares against its open PR base when gh finds one, else merge-base with the default branch.", - "commitment": "explicit", - "importance": "supporting", - "status": "active", - "time_horizon": "first release", - "sources": [ - "qa-round-1" - ] - }, - { - "id": "C12", - "type": "derived implication", - "statement": "PRs are stacked, so the compare base must be merge-base with the PR baseRefName, not the default branch; worktree lists are large and include prunable entries; gh latency ~2s requires async loading.", - "commitment": "derived", - "importance": "core", - "status": "active", - "time_horizon": "first release", - "sources": [ - "probe-modeler-gh" - ] - } - ], - "themes": [ - "work-context-aware picking", - "PR as unit", - "development within a PR", - "compare speed" - ], - "conflicts": [], - "human_questions": [] - }, - "brainstorm": { - "status": "not-requested", - "requested_count": 7, - "options": [], - "selected_option": null - }, - "shape": { - "status": "current", - "appetite": "Medium: one sources endpoint, a picker component, worktree-as-head, and a commit stepper; compare engine and views unchanged.", - "problem": "Choosing a comparison needs typed refs; no PR, worktree, or commit-stepping support; cold compares feel slow without visibility into why.", - "recommended_shape": { - "endpoint": "GET /api/compare/sources -> {prs (gh pr list --json number,title,headRefName,baseRefName,headRefOid,isDraft,reviewDecision,updatedAt,statusCheckRollup,author), worktrees (git worktree list --porcelain, non-prunable, sorted by HEAD date), branches (for-each-ref heads+remotes with upstream:track)}", - "pick_rules": { - "pr": "base=merge-base(origin/baseRefName, headRefOid); head=headRefOid; fetch head objects if missing", - "worktree": "head=scan of worktree path; base=open PR base for its branch else merge-base(default, HEAD)", - "branch": "merge-base(default, branch)" - }, - "stepper": "git rev-list --first-parent --reverse base..head; step i = c[i-1]..c[i]", - "files": [ - "client/src/compare/RefBar.tsx", - "client/src/compare/CompareApp.tsx", - "client/src/compare/CompareProgress.tsx", - "client/src/compare/api.ts", - "server/app/routers/compare.py", - "server/app/services/compare/git_refs.py", - "server/app/services/compare/snapshots.py", - "server/app/services/compare/service.py", - "server/app/services/compare/jobs.py" - ], - "prior_art": [ - "/Users/byronwall/repos/git-visual-files/src/lib/gitWorktrees.ts", - "/Users/byronwall/repos/git-visual-files/src/lib/gitBranchSummaries.ts", - "/Users/byronwall/repos/git-visual-files/src/components/RefPicker.tsx", - "/Users/byronwall/repos/git-visual-files/src/components/WorktreePopover.tsx" - ] - }, - "success_moves": [ - "Single server seam for gh with timeout, short cache, and recorded-JSON fake in tests; picker never blocks on GitHub", - "Use PR baseRefName for merge-base so stacked PRs match GitHub", - "Sections load independently so git lists render instantly and PRs fill in", - "Worktree head reuses the WORKTREE path-scan and mtime cache instead of a checkout", - "Add per-phase timings to compare progress before optimizing parallel sides or prewarming", - "Stepper reuses the previous side from SideCache so each step costs at most one scan" - ], - "first_proof": { - "question": "Does a gh+git sources endpoint with PR-based base resolution produce GitHub-equal diffs, including stacked PRs, with a fast picker?", - "artifact": "sources endpoint + picker (PR picking only) on modeler #1925 and stacked #1922", - "observation": "changed-file count equals gh pr view N --json changedFiles; git sections <300ms; cold-side phase timings visible", - "decision_rule": "match -> worktree heads and stepper; stacked mismatch -> fix base resolution (remote base ref, fetch) first" - }, - "rabbit_holes": [ - "PR head commits missing locally (fork PRs, unfetched)", - "240-worktree listing cost and prunable entries", - "WORKTREE semantics generalized to another path vs SideCache keys", - "stepping cost on large repos without per-file reuse", - "gh auth inside sandboxed environments (Keychain)" - ], - "open_decisions": [] - }, - "implementation": { - "status": "current", - "repository_snapshot": { - "root": "/Users/byronwall/repos/srcly", - "revision": "5e396c3", - "worktree_status": "clean", - "subsystems": [ - "server/app/services/compare", - "server/app/routers/compare.py", - "client/src/compare" - ], - "test_commands": [ - "cd server && uv run pytest tests/test_compare*.py", - "cd client && pnpm test" - ], - "deployment_surfaces": [] - }, - "dependencies": [ - { - "id": "gh", - "name": "GitHub CLI (gh)", - "material": true, - "application_seam": "server/app/services/compare/github.py run_gh(repo,*args,timeout) -> parsed JSON or GhUnavailable(reason)", - "failure_modes": [ - "gh not installed", - "not authenticated / Keychain unavailable in sandbox", - "network offline or timeout", - "head commit not local", - "stacked base branch missing on origin" - ], - "proof_rungs": [ - "recorded JSON via monkeypatched run_gh in pytest", - "real gh on modeler by hand (CLI then UI)" - ], - "first_proof_role": { - "mode": "real", - "rationale": "The m1 question is whether GitHub-reported PR base/head reproduce the GitHub diff; only real gh on modeler answers it, while faked gh covers logic in tests." - }, - "local_proof": "pytest with monkeypatched run_gh plus real-git fixture repo with stacked branches", - "live_proof": "srcly compare pr:1925 and pr:1922 on modeler match gh pr view --json changedFiles", - "rollout": "Picker sections hide with a reason when gh is unavailable; Advanced free-text refs remain; reverting m2 restores RefBar" - } - ], - "fast_local_loop": { - "command": "cd server && uv run pytest tests/test_compare*.py", - "starts": "nothing; real git in tmp_path", - "network": false, - "failure_injection": "monkeypatch run_gh to raise GhUnavailable or return recorded JSON" - }, - "milestones": [ - { - "id": "m1", - "title": "pr:<n> resolves to a GitHub-equal compare, with phase timings", - "outcome": "srcly compare pr:N on modeler matches GitHub changed-file counts, including stacked PRs; progress shows per-phase seconds; UI sends the analyzed repo path.", - "dependencies_introduced": [ - "gh" - ], - "proof": "pytest: stacked-branch fixture + faked PR JSON; gh-missing path; manual CLI on modeler #1925 and #1922", - "valid_intermediate_state": "Picker unchanged; pr:<n> usable from CLI and typed into the existing ref fields", - "rollback": "Remove pr: handling in resolve_ref; github.py unused", - "status": "planned", - "evidence": [], - "files": [ - "server/app/services/compare/github.py (new)", - "server/app/services/compare/git_refs.py:22-34,99-107", - "server/app/services/compare/jobs.py:73-83,109-112", - "client/src/compare/CompareProgress.tsx", - "client/src/compare/api.ts:53-60", - "client/src/compare/types.ts:15-27" - ] - }, - { - "id": "m2", - "title": "Rich picker with independent sources", - "outcome": "One picker lists My PRs, live worktrees, branches with search; one click lands on the correct compare.", - "dependencies_introduced": [], - "proof": "pytest for /api/compare/sources worktree parsing (prunable filtered); manual modeler check: git sections under 300ms, PRs ~2s or reason", - "valid_intermediate_state": "Advanced free-text refs still available", - "rollback": "Revert to RefBar datalist", - "status": "planned", - "evidence": [], - "files": [ - "server/app/routers/compare.py", - "client/src/compare/ComparePicker.tsx (new)", - "client/src/compare/RefBar.tsx:28-57", - "client/src/compare/SummaryStrip.tsx" - ] - }, - { - "id": "m3", - "title": "A worktree as the head", - "outcome": "Picking any live worktree compares its on-disk state against its PR base or merge-base without a checkout.", - "dependencies_introduced": [], - "proof": "pytest: second worktree with uncommitted edits shows edits; no worktree state mutated", - "valid_intermediate_state": "PR and branch picking unaffected", - "rollback": "Hide worktree rows; worktree: ref rejected", - "status": "planned", - "evidence": [], - "files": [ - "server/app/services/compare/git_refs.py:113-155", - "server/app/services/compare/snapshots.py:210-276", - "server/app/services/compare/service.py:49-67" - ] - }, - { - "id": "m4", - "title": "Commit stepper inside a PR or range", - "outcome": "Step through a PR commit by commit; each step costs at most one new side scan.", - "dependencies_introduced": [], - "proof": "pytest for /api/compare/commits; manual stepping on a modeler PR with timings", - "valid_intermediate_state": "Whole-PR compare remains default", - "rollback": "Hide stepper", - "status": "planned", - "evidence": [], - "files": [ - "server/app/routers/compare.py", - "client/src/compare/CommitStepper.tsx (new)", - "client/src/compare/CompareApp.tsx" - ] - } - ], - "cut_line": [ - "per-file analysis reuse across commits", - "?pr= shorthand and --pr CLI sugar", - "fork PRs with unfetchable heads", - "review comments and check details" - ], - "open_decisions": [ - { - "decision": "Parallel sides vs pre-warm vs sequential", - "evidence": "m1 phase timings on modeler cold compares", - "fallback": "sequential + pre-warm next commit" - } - ] - }, - "history": [ - { - "date": "2026-10-15", - "event": "Initiative created from 2026-10-15 voiceover session (15:41-17:06) with code and prior-art source map." - }, - { - "date": "2026-10-15", - "event": "Round 1: worktree default base = open PR base, else merge-base." - }, - { - "date": "2026-10-15", - "event": "Shape brief written after modeler probe (stacked PRs, 240 worktrees, gh ~2s): PR baseRefName merge-base, independent sources, worktree-as-head, stepper." - }, - { - "date": "2026-10-15", - "event": "Implementation plan written: m1 pr:<n> resolver first, then picker, worktree head, stepper." - } - ], - "closure": null -} diff --git a/docs/intent/compare-ref-picker/intent-brief.md b/docs/intent/compare-ref-picker/intent-brief.md deleted file mode 100644 index 855a7de9..00000000 --- a/docs/intent/compare-ref-picker/intent-brief.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Compare ref picker: PRs, worktrees, commits" -slug: "compare-ref-picker" -phase: intent -status: current -last_updated: "2026-10-15" ---- - -# Compare ref picker: PRs, worktrees, commits - -## My read - -The compare views work. You said the compare treemap is "so good", and the dependency compare "feels okay" but needs testing on a real PR. What fails is *getting to the right comparison*. You work across "a ton of worktrees, a ton of PRs". Today srcly offers only two free-text ref boxes with a native datalist of local branches and recent commits. Your verdict: "woefully underpowered in terms of being able to like pick what you are looking for." - -You want a rich picker that knows your actual working context: - -- open PRs, pulled through the `gh` CLI with as much useful context as it gives; -- the repo's worktrees and branches. - -Picking a PR should show that PR's diff. Inside a PR you also want to step commit by commit, current commit against the previous one, to watch how the PR developed. Compare should also feel fast. The first run felt slow; a later run was quick, probably from the cache. - -## What matters most - -- **Select the right working spot fast.** A PR, a worktree or a branch is one pick away, not a ref you type. -- **PR as the unit.** Choosing a PR sets base and head for you. -- **Development inside a PR.** You can step through its commits one at a time. - -## The experience you appear to want - -You click Compare. A picker opens, listing your open PRs for this repo with number, title, branch, author, draft or review state, and age. Beside them it lists local worktrees with their branches. You pick PR #1831, and srcly compares its merge-base with its head. A commit strip shows the PR's commits. Stepping to commit 3 of 7 shows commit 3 against commit 2, in the same treemap and graph views. Picking a worktree compares that worktree's state against its base, the same way the working tree works today. - -## Boundaries - -### Must be true - -- The working tree, branch and stash stay untouched. The existing snapshot rule from `pr-compare` holds. -- The picker still works without `gh` or without network access. It falls back to worktrees, branches and commits. -- Results stay deterministic for the same two commits. -- Repeat compares are fast, and the first compare is no slower than today. - -### Must be avoided - -- Making you type or remember SHAs and ref syntax for routine PR work. -- Sending repo data anywhere new. `gh` is only used to *read* PR metadata. - -## What seems settled - -- Use the `gh` CLI for PR context, not a GitHub token flow inside srcly. -- The PR diff is the primary mode. Commit-level stepping within a PR is the next layer. -- The compare treemap and graph stay as the views. This initiative is about choosing the input, and about speed. - -## Possibilities, not decisions - -- Prior art: your `git-visual-files` ("igitit") project, a SolidStart app. Its pieces include: - - a worktree popover, from `git worktree list --porcelain`; - - a branch picker with ahead/behind counts and linked-worktree badges, from `git for-each-ref`; - - a range timeline drawer, from `git log forkBase..target`. - - It has no `gh` usage. `daily-planning/viewer/link-metadata.ts` has the only `gh api graphql` pattern found. -- Pre-warming the snapshot cache for open PRs in the background. -- Opening srcly directly on a PR by number (`?pr=1831`). - -## Current reality that matters - -- **The picker** is two `<TextInput list>` fields fed by one datalist (`client/src/compare/RefBar.tsx:28-57`). -- **The ref list:** `GET /api/compare/refs` returns 20 local branches and 30 commits on HEAD (`server/app/routers/compare.py:52-86`). -- **Missing entirely:** worktree listing, remote branches, `gh` usage, and any commit stepping. -- **Why a cold compare is slow.** Each uncached commit side gets: - - a `git worktree add`; - - a full `scan_codebase` of the whole repo; - - an uncached dependency graph build. - - The two sides run sequentially (`server/app/services/compare/service.py:32-72`, `snapshots.py:210-244`). The cache is keyed by whole commit SHA, with an LRU of 40 entries and no per-file reuse across commits. -- **Commit stepping would multiply the cold cost.** Each step means one new side scan unless per-file results are reused. -- **Progress** comes from polling `GET /api/compare/{id}` every 250ms (`client/src/compare/api.ts:69-103`). - -## Decided in round 1 - -- A picked worktree compares against its open PR's base when `gh` finds one. Otherwise it uses the merge-base with the default branch. - -## Next step after confirmation - -Shape the work. The first proof would be a `gh pr list` and `git worktree list` endpoint plus the picker, choosing a PR on modeler and landing in the existing compare. diff --git a/docs/intent/compare-ref-picker/shape-brief.md b/docs/intent/compare-ref-picker/shape-brief.md deleted file mode 100644 index 6c8a7c66..00000000 --- a/docs/intent/compare-ref-picker/shape-brief.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Compare ref picker — shape brief" -slug: "compare-ref-picker" -phase: shape -status: current -last_updated: "2026-10-15" ---- - -# Compare ref picker — what we are adding - -**Outcome:** One picker that knows your work. Your open PRs (stacked ones included), your live worktrees and your branches are each one click from a correct compare. Inside a PR, you can step commit by commit. - -**Primary flow:** Compare → picker opens on "My PRs" → pick #1922 → srcly compares its merge-base with `codex/concurrency-05-build-reuse` against its head → step through its commits with ◀ ▶. - -## Feature scope - -```text -Compare ref picker (replaces RefBar's datalist inputs) -├── PLANNED ADDITIONS -│ ├── Sources, each loading independently -│ │ ├── My PRs (via gh), with a toggle for all open PRs -│ │ │ ├── row: #, title, head → base, draft / review state, checks, updated -│ │ │ └── badges: "worktree", "local", "needs fetch" -│ │ ├── Worktrees: live ones only (no prunable), newest HEAD first, -│ │ │ searchable, showing branch and path -│ │ ├── Branches: local and remote, with ahead/behind counts -│ │ └── Advanced: today's free-text base/head fields, kept -│ ├── Picking -│ │ ├── PR → base = merge-base(origin/<baseRefName>, head), head = headRefOid -│ │ ├── worktree → head = that worktree's files on disk; base = its open PR's base, -│ │ │ else merge-base with the default branch -│ │ └── branch → merge-base with the default branch, as today -│ ├── Commit stepper (when a PR or branch range is picked) -│ │ ├── strip of first-parent commits, oldest → newest; ◀ ▶ and click -│ │ └── step i compares commit i-1 → commit i (the first step uses the merge-base) -│ └── Speed visibility -│ └── progress shows per-phase timings and cache hits -├── EVALUATE BEFORE COMMITTING -│ ├── scan the two sides in parallel instead of one after the other -│ └── pre-warm the next commit's side after each step lands -└── LATER POSSIBILITIES - ├── reuse per-file analysis across commits (keyed by blob hash) - └── ?pr=1922 deep link, plus the srcly compare --pr CLI -``` - -## Behavior - -| Situation | Expected result | -| --- | --- | -| `gh` missing, not authed, or offline | The PR section shows the reason. Worktrees, branches and Advanced still work | -| Stacked PR (base is not `main`) | Only that PR's own changes appear, matching GitHub's file count | -| PR head commit not present locally | One click fetches it (objects only, no branch or worktree change), then compares | -| Picker opens on modeler (240 worktrees) | Git sections appear in under 300ms. PRs fill in when `gh` returns (about 2s, then cached briefly) | -| Step forward through a PR | Each step costs at most one new side scan. The previous side is a cache hit | - -## Decisions and boundaries - -**Appetite:** Medium. It adds one server sources endpoint, a picker component, worktree-as-head support, and a stepper. The compare engine and its views stay unchanged. - -**Key decisions:** -- **Use the PR's real base.** Your PRs are stacked (#1927 → `codex/concurrency-02-trace-visibility`). The PR's `baseRefName` is used, not the default branch, so the diff matches GitHub's. -- **`gh pr list --json` behind one server seam.** One subprocess with a timeout and a short in-memory cache feeds everything. It is faked in tests from recorded JSON. The rest of the picker never depends on GitHub being reachable. -- **Worktree head means a scan of a directory.** It is today's WORKTREE semantics pointed at another path, reusing the path-and-mtime analysis cache. No checkout is needed. -- **Measure before optimizing.** The progress UI first shows phase timings, so it is clear whether the slow first run comes from checkout, scan or graph build. Parallel sides and pre-warming are evaluated afterward. - -**Boundary:** -- srcly never changes branches, the stash, or any worktree's files. Fetching a missing PR head adds objects only. -- `gh` is read-only: list and view. -- Fixtures are synthetic or srcly's own PRs. No modeler PR data is committed, because the repo is public. - -**Collisions:** Independent of the other three initiatives. It touches `client/src/compare/RefBar.tsx`, `CompareApp.tsx`, `CompareProgress.tsx`, `api.ts`, and `server/app/routers/compare.py` and `services/compare/*`. Unified-navigation also touches `compare/api.ts`, but only its push/popstate helpers. Keep that seam. - -**First proof:** -- **Try:** `GET /api/compare/sources` (PRs, worktrees, branches) plus the picker, with PR picking only. Use modeler #1925 (base `main`) and stacked #1922. -- **Observe:** - - each PR's changed-file count equals `gh pr view N --json changedFiles`; - - the git sections render in under 300ms; - - the phase timings for a cold side are visible. -- **Decide:** If the counts match, add worktree heads and the stepper. If stacked counts mismatch, fix base resolution (remote base ref, fetch) before anything else. - -Intent: [intent-brief.md](intent-brief.md)