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,230 @@
//! `git.blame` (M4.7) through the engine: the working copy, an open
//! buffer with unsaved edits and a BOM, a revision, an untracked file, bad
//! params, and no `gitChanged` from it. Skips with a message when git is
//! not installed.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::panic,
clippy::indexing_slicing
)]
use std::path::Path;
use std::process::Command;
use std::sync::Mutex;
use lutra_engine::{Engine, EngineError, Event, run_waiting};
use serde_json::{Value, json};
/// Whether git is installed; prints why a test is skipped.
fn have_git() -> bool {
let ok = Command::new("git")
.arg("--version")
.output()
.is_ok_and(|o| o.status.success());
if !ok {
eprintln!("skipped: git is not installed");
}
ok
}
/// Runs git for test setup.
fn git(dir: &Path, args: &[&str]) -> String {
let out = Command::new("git")
.args(args)
.current_dir(dir)
.output()
.unwrap();
assert!(
out.status.success(),
"git {args:?}: {}",
String::from_utf8_lossy(&out.stderr)
);
String::from_utf8_lossy(&out.stdout).trim().to_string()
}
/// Writes `text` to `path` and commits everything as `author`.
fn commit(dir: &Path, path: &str, text: &str, message: &str, author: &str) -> String {
std::fs::write(dir.join(path), text).unwrap();
git(dir, &["add", "-A"]);
git(dir, &["commit", "-q", "--author", author, "-m", message]);
git(dir, &["rev-parse", "HEAD"])
}
/// An engine with `root` open, recording events.
struct Host {
/// The engine.
engine: Mutex<Engine>,
/// Events published so far.
events: Mutex<Vec<Event>>,
}
impl Host {
/// Opens `root` as the project.
fn open(root: &Path) -> Self {
let host = Self {
engine: Mutex::new(Engine::new().unwrap()),
events: Mutex::new(Vec::new()),
};
host.run("project.open", json!({"path": root})).unwrap();
host
}
/// Runs a command the way hosts do.
fn run(&self, command: &str, params: Value) -> Result<Value, EngineError> {
run_waiting(
|| self.engine.lock().unwrap(),
command,
params,
|events| self.events.lock().unwrap().extend_from_slice(events),
)
.map(|o| o.value)
}
}
/// The hashes of a blame's lines.
fn hashes(blame: &Value) -> Vec<String> {
blame["lines"]
.as_array()
.unwrap()
.iter()
.map(|l| l["hash"].as_str().unwrap().to_string())
.collect()
}
#[test]
fn blame_working_copy_buffer_and_revision() {
if !have_git() {
return;
}
let dir = tempfile::tempdir().unwrap();
let d = dir.path();
git(d, &["init", "-q", "-b", "main"]);
for (key, value) in [
("user.name", "Lutra Test"),
("user.email", "test@lutra.invalid"),
("commit.gpgsign", "false"),
("core.autocrlf", "false"),
("core.hooksPath", ".git/hooks"),
] {
git(d, &["config", key, value]);
}
let first = commit(
d,
"a.php",
"<?php\n// one\n",
"First",
"Ann <ann@x.invalid>",
);
let second = commit(
d,
"a.php",
"<?php\n// one\n// two\n",
"Second\n\nBody",
"Bo <bo@x.invalid>",
);
std::fs::write(d.join("bom.php"), "\u{feff}<?php\r\n// bom\r\n").unwrap();
git(d, &["add", "-A"]);
git(d, &["commit", "-q", "-m", "Bom"]);
let bom_commit = git(d, &["rev-parse", "HEAD"]);
let host = Host::open(d);
host.events.lock().unwrap().clear();
let blame = host.run("git.blame", json!({"path": "a.php"})).unwrap();
assert_eq!(
hashes(&blame),
[first.as_str(), first.as_str(), second.as_str()]
);
assert_eq!(blame["version"], Value::Null);
let line = &blame["lines"][2];
assert_eq!(line["author"], "Bo");
assert_eq!(line["summary"], "Second");
assert_eq!(line["origLine"], 3);
assert!(line["date"].as_str().unwrap().len() >= 25, "{line}");
// An open buffer with an unsaved line: that line is not committed.
let opened = host.run("file.open", json!({"path": "a.php"})).unwrap();
let id = opened["id"].clone();
host.run(
"buffer.edit",
json!({"id": id, "baseVersion": opened["version"], "edits": [{"from": 6, "to": 6, "insert": "// new\n"}]}),
)
.unwrap();
let blame = host.run("git.blame", json!({"path": "a.php"})).unwrap();
let zeros = "0".repeat(first.len());
assert_eq!(
hashes(&blame),
[
first.as_str(),
zeros.as_str(),
first.as_str(),
second.as_str()
]
);
assert_ne!(blame["version"], Value::Null);
assert_eq!(blame["lines"][2]["origLine"], 2);
// A revision ignores the buffer.
let at = host
.run("git.blame", json!({"path": "a.php", "rev": first}))
.unwrap();
assert_eq!(hashes(&at), [first.as_str(), first.as_str()]);
assert_eq!(at["version"], Value::Null);
// A CRLF buffer with a BOM matches its blob.
host.run("file.open", json!({"path": "bom.php"})).unwrap();
let blame = host.run("git.blame", json!({"path": "bom.php"})).unwrap();
assert_eq!(hashes(&blame), [bom_commit.as_str(), bom_commit.as_str()]);
// Untracked: no lines.
std::fs::write(d.join("new.php"), "<?php\n").unwrap();
let untracked = host.run("git.blame", json!({"path": "new.php"})).unwrap();
assert_eq!(untracked["lines"], json!([]));
for params in [
json!({}),
json!({"path": "a.php", "bogus": 1}),
json!({"path": "a.php", "rev": "-L1"}),
json!({"path": "../x.php"}),
] {
let err = host.run("git.blame", params.clone()).unwrap_err();
assert_eq!(err.code(), "invalid_params", "{params}");
}
let err = host
.run("git.blame", json!({"path": "a.php", "rev": "nope"}))
.unwrap_err();
assert_eq!(err.code(), "failed");
let changed = host
.events
.lock()
.unwrap()
.iter()
.filter(|e| matches!(e, Event::GitChanged(_)))
.count();
assert_eq!(changed, 0);
}
#[test]
fn blame_without_commits_or_project() {
if !have_git() {
return;
}
let dir = tempfile::tempdir().unwrap();
git(dir.path(), &["init", "-q", "-b", "main"]);
std::fs::write(dir.path().join("a.php"), "<?php\n").unwrap();
let host = Host::open(dir.path());
let blame = host.run("git.blame", json!({"path": "a.php"})).unwrap();
assert_eq!(blame["lines"], json!([]));
host.run("file.open", json!({"path": "a.php"})).unwrap();
let blame = host.run("git.blame", json!({"path": "a.php"})).unwrap();
assert_eq!(blame["lines"], json!([]));
let bare = Host {
engine: Mutex::new(Engine::new().unwrap()),
events: Mutex::new(Vec::new()),
};
let err = bare.run("git.blame", json!({"path": "a.php"})).unwrap_err();
assert_eq!(err.code(), "disabled");
}