M4.7: blame annotations in the editor gutter

- crates/vcs: blame.rs (git blame --porcelain, --contents - from a
  buffer, revisions, untracked files and empty repositories give no
  lines; property-tested parser, ISO dates without a date crate)
- engine: git.blame {path, rev?} -> {lines, version} through start_with;
  an open buffer is blamed as it would be saved (line ending, BOM)
- ui: blame.ts gutter toggled per file (vcs.toggleBlame, Git menu, no
  shortcut), date + author per run, bar coloured by age from tokens,
  hover card with the full commit message, click opens the commit in
  the Log (vcs.showCommit); refreshed on edits and gitChanged
- docs: architecture "Blame (M4.7)"

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-30 17:52:44 +01:00
parent dc4a00ea0b
commit 2f758d76b9
18 changed files with 2003 additions and 3 deletions

View file

@ -650,6 +650,15 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- **Checked in the app** (debug build with the bundled UI, Windows 11, git 2.47.1, control port 7946, a demo repository with a feature branch merged with `--no-ff`, a rename, a tag and an unmerged branch; screenshots only, no input): `git.log` 75–79 ms over the control channel; `vcs.showLog` showed the lanes branching at the merge and joining at the fork point, the badges (HEAD, main, feature, hotfix, v1.0) and the first commit's details; `vcs.showHistory {path: "Renamed.php"}` showed its three commits back to the import as `Old.php`, without the other branch. The diff at a commit needs a double-click, so it is covered by Vitest only.
- **Tests:** `crates/vcs/tests/log.rs` (5 tests against real temp repositories: empty repository, paging, merge parents and refs, tags, literal text filter, author filter, history across a rename, a folder's history, commit details and a root commit, contents at a commit and its parent, bad input, a project inside a repository); unit and property tests in `log.rs`; `crates/engine/tests/git_log.rs` (the command shapes, paging, filters, an absolute path, bad params, no `gitChanged`); Vitest `ui/tests/vcs/Log.test.ts` (21 tests: lanes for linear and merged histories, across pages and capped, parsers, badges, paging, filters with stale answers, reloads on `gitChanged`, errors, details, the window's rows, keyboard, filters and chip, the diff at a commit with both sides read-only, commands and the tree menu).
### Blame (M4.7)
- **Backend (`crates/vcs/src/blame.rs`, appended to `Repo`):** `blame(path, rev?, contents?)` runs `git blame --porcelain [--contents -] [rev] -- path`. Without `rev` and with `contents`, git blames that text (an editor buffer) on top of HEAD, converting its line endings as for a commit, so a CRLF buffer under `core.autocrlf` matches its LF blob; with `rev`, the contents are ignored. The revision is checked like `show_at` (no leading `-`, no `:` or control characters) and passed without `--end-of-options`, which makes blame read the revision as a path. A file git does not know there (untracked, a repository without commits) and contents over 32 MiB give no lines, not an error. The parser reads the porcelain groups (`<hash> <orig> <final> [<count>]`, the commit's fields once per hash, the line after a tab), skips malformed headers and is property-tested with random bytes. Dates are the author time in the author's offset as ISO 8601 (`civil_from_days`, no date crate). Lines not committed yet carry git's all-zero hash (`is_uncommitted`).
- **Command** (`crates/engine/src/cmd/git_blame.rs`, through `start_with`; read-only, pending, no `gitChanged`): `git.blame {path, rev?}` → `{lines: [{hash, author, date, summary, origLine}], version}`, one entry per line in file order, `origLine` 1-based in that commit. Without `rev`, an open buffer for the path is blamed as it stands: under the lock only its rope is cloned, and the git thread builds the saved text (buffer line ending, BOM again in front when the file has one). `version` is that buffer's version, `null` when no buffer was used (an addition to the C6 contract, like `git.lineChanges`). A bad path or revision is `invalid_params`; an unknown revision is `failed` with git's message.
- **Gutter** (`ui/src/components/editor/blame.ts`, appended to `editorExtensions` for buffers): annotations per file, toggled by the UI command `vcs.toggleBlame {path?}` (menu Git › Annotate with Git Blame; without a path, the active tab's file; no default shortcut). Every editor of the file shows them until toggled off or the project changes. The first line of a run from one commit shows the short local date and the author (22 characters wide, cut with an ellipsis); every annotated line has a 3 px bar mixed from `--lt-accent` by age (a day, a week, a month, a year, older), and uncommitted lines a `--lt-vcs-modified` bar and "Not committed yet". Queries go through `runWaiting` when shown, 500 ms after the last edit and on every `gitChanged` (the status store calls `refreshBlame`); like the change markers they wait for the buffer sync's `idle()` and drop answers for a changed document. Between answers the annotations move with the text (a line inserted at a line start pushes the annotation down); new lines stay blank. Failures keep the annotations.
- **Hover and click:** resting on an annotation for 300 ms shows a card with the short hash, author, local date and the subject, replaced by the full message from `git.showCommit` (cached per hash, at most 200); leaving the gutter and the card hides it. A click on a committed line runs the UI command `vcs.showCommit {hash}` (no menu entry, no default shortcut), which shows the Log tab (M4.6) with that commit selected, even one outside the loaded pages.
- **Checked in the app** (debug build with the bundled UI, Windows 11, git 2.47.1, control port 7947, a demo repository with three authors from 2024, August 2026 and three hours ago; screenshots only, no input): `git.blame` 210 ms for the first call (git detection, opening the repository), then 68 ms; `vcs.toggleBlame` showed date and author on each run with the strongest bar on today's lines and the faintest on 2024's; an unsaved line inserted through `buffer.edit` showed "Not committed yet" and pushed the others down; `vcs.showCommit` opened the Log with the commit selected and its full message. Hover and click need the mouse, so they are covered by Vitest only.
- **Tests:** `crates/vcs/tests/blame.rs` (2 tests against real temp repositories: authors and summaries, buffer contents with CRLF under autocrlf, revisions, a rename, untracked files, bad input, a project inside a repository, an empty repository); unit and property tests in `blame.rs` (groups, content that looks like a header, header checks, dates and offsets); `crates/engine/tests/git_blame.rs` (2 tests: the working copy, a buffer with an unsaved line, a revision, a CRLF buffer with a BOM, untracked, bad params, an unknown revision, no `gitChanged`, no commits, no project); Vitest `ui/tests/editor/blame.test.ts` (11: parsing, age levels, runs and clamping, labels, the toggle, debounce and mapping, stale answers, failures, `refreshBlame`/`clearBlame`, click, hover with the full message, commands, tokens only) and one layout test in `ui/tests/vcs/Log.test.ts` (`vcs.showCommit` selects the commit, `vcs.toggleBlame`).
### Branches (M4.5)
- **Where:** `ui/src/components/vcs/branches/`: `branches.ts` is the Pinia store, `BranchStatusItem.vue` the status-bar item (one line in `StatusBar.vue`, after H3's progress item), `BranchPopup.vue` the popup. The item supplies the UI commands, so they exist wherever the status bar is.
@ -747,6 +756,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-30 | minor | M4.7: blame (`git.blame` with `--contents` from the buffer, the annotation gutter by age, hover with the commit message, `vcs.toggleBlame`, `vcs.showCommit`) |
| 2026-10-28 | minor | M4.6: history backend (`git.log`, `git.showCommit`, `git.showAt`), the shared hook for new git commands, the Log tab, diffs at a commit |
| 2026-10-28 | minor | M4.10: remotes (`Call::network` with progress and cancel, URL redaction, `git.fetch/pull/push/clone/cancel/remotes/remoteAdd/remoteSetUrl/remoteRemove`, `gitProgress`, `git.pull.mode`, the clone and remotes dialogs) |
| 2026-10-28 | minor | M4.8: merge conflicts (`git.merge`, `git.mergeAbort`, `git.conflictVersions`, `git.markResolved`, the merge dialog with a three-pane resolve view) |