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

@ -0,0 +1,116 @@
//! `git.blame` (M4.7): which commit last changed each line of a file, for
//! the editor's annotation gutter. Read-only and run like every `git.*`
//! command (a pending outcome off the lock, git and the repository cached
//! by [`super::git`]).
//!
//! Without `rev` an open buffer for the path is blamed as it stands
//! (`--contents -`, the text as it would be saved, BOM included), so
//! unsaved edits show as not committed and the lines match the editor.
//! Under the lock only the buffer's rope is cloned (shared chunks); the
//! text is built on the git thread.
use lutra_text::Buffer;
use lutra_vcs::BlameLine;
use serde::Deserialize;
use serde_json::{Value, json};
use super::git::start_with;
use super::params::{parse, project_path};
use crate::workspace::path_string;
use crate::{Command, CommandSpec, EngineError, Outcome, Registry, State};
/// The UTF-8 byte order mark.
const BOM: &str = "\u{feff}";
/// Registers `git.blame`.
///
/// # Errors
/// [`EngineError::Internal`] if the id is taken.
pub fn register(registry: &mut Registry) -> Result<(), EngineError> {
registry.register(Box::new(Blame))
}
/// One line of `git.blame`.
fn line_json(line: &BlameLine) -> Value {
json!({
"hash": line.hash,
"author": line.author,
"date": line.date,
"summary": line.summary,
"origLine": line.orig_line,
})
}
/// Params of `git.blame`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct BlameParams {
/// The file.
path: String,
/// A revision to blame the file at instead of the working copy.
#[serde(default)]
rev: Option<String>,
}
/// `git.blame`.
struct Blame;
impl Command for Blame {
fn spec(&self) -> &CommandSpec {
&CommandSpec {
id: "git.blame",
label: "Git: Blame",
menu_path: None,
default_shortcut: None,
params: "{ path: project-relative path, rev?: commit hash or revision (default: the working copy, an open buffer's unsaved text included) }; returns { lines: [{ hash, author, date (ISO 8601), summary, origLine }], version } with one entry per line in file order (hash all zeros for lines not committed yet; origLine 1-based in that commit); no lines when the file is untracked or the repository has no commits; version is the blamed buffer's version, null when no buffer was used",
}
}
fn enabled(&self, state: &State) -> bool {
state.has_project()
}
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError> {
let command = self.spec().id;
let p: BlameParams = parse(command, params)?;
let rel = project_path(state, command, &p.path)?;
let path = path_string(&rel);
let rev = p
.rev
.map(|r| r.trim().to_string())
.filter(|r| !r.is_empty());
let buffer: Option<(Buffer, bool, u64)> = if rev.is_none() {
state
.buffers
.find(&rel)
.and_then(|id| state.buffers.get(id))
.map(|open| (open.buffer.clone(), open.bom, open.version))
} else {
None
};
start_with(
state,
command,
false,
Box::new(move |repo| {
let contents = buffer.as_ref().map(|(buffer, bom, _)| {
let text = buffer.save_text();
if *bom { format!("{BOM}{text}") } else { text }
});
let lines: Vec<Value> = repo
.blame(
&path,
rev.as_deref(),
contents.as_deref().map(str::as_bytes),
)?
.iter()
.map(line_json)
.collect();
Ok(json!({
"lines": lines,
"version": buffer.as_ref().map(|(_, _, version)| *version),
}))
}),
)
}
}

View file

@ -4,6 +4,7 @@ mod app;
mod buffer;
mod file;
pub mod git;
pub mod git_blame;
pub mod git_lines;
pub mod git_log;
pub mod git_merge;
@ -72,6 +73,7 @@ pub fn register_builtins(registry: &mut Registry) -> Result<(), EngineError> {
lsp_nav::register(registry)?;
git::register(registry)?;
git_lines::register(registry)?;
git_blame::register(registry)?;
git_log::register(registry)?;
git_remote::register(registry)?;
git_merge::register(registry)?;

View file

@ -481,6 +481,7 @@ mod tests {
"file.open",
"file.save",
"file.saveAll",
"git.blame",
"git.branches",
"git.cancel",
"git.checkout",