Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Shared LLM summary generation for branches.
//!
//! Generates branch summaries using the configured LLM command, with caching
//! in `.git/wt/cache/summary/{sanitized_branch}/{diff_hash}.json`. The
//! combined diff (branch diff + working tree diff) is hashed with SHA-256
//! and the hex-truncated digest becomes the filename — so a cache hit is
//! just "does the file exist?" rather than parsing JSON to compare a field.
//!
//! Used by both `wt list --full` (Summary column) and `wt switch` (preview tab).
//!
//! # Layout and invalidation
//!
//! Content-addressed filename: a successful write to `{hash}.json` means that
//! file holds the summary for that exact diff. No TTL, no separate staleness
//! check — see [`worktrunk::cache`] for the shared torn-write semantics.
//!
//! The hash covers the diff, not the prompt built from it: [`SUMMARY_TEMPLATE`]
//! and [`prepare_diff`]'s filtering both sit downstream of it. Rewording the
//! prompt therefore leaves every finished branch holding the summary the old
//! one produced. Closing that means hashing the rendered prompt rather than the
//! diff; it stays open because the value is display-only and rebuilding it
//! costs a model call per branch.
//!
//! # Prune on write
//!
//! After a successful write, the branch directory is trimmed to one entry
//! via [`cache::sweep_lru`] with a cap of 1 — same mechanism `sha_cache`
//! uses, just at a per-branch directory with a size of one. The newest-mtime
//! file (the one we just wrote) survives; older hashes are dead weight.
//!
//! Best-effort: two concurrent writers for the same branch can briefly
//! leave two entries, and a sweep racing a just-written sibling can delete
//! it. Worst case is one extra LLM call on the next invocation.
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::LazyLock;
use anstyle::Reset;
use color_print::cformat;
use minijinja::Environment;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use worktrunk::cache;
use worktrunk::git::{CommandError, ErrorExt, Repository};
use worktrunk::path::sanitize_for_filename;
use worktrunk::styling::INFO_SYMBOL;
use worktrunk::sync::Semaphore;
use worktrunk::utils::epoch_now;
use crate::llm::{execute_llm_command, prepare_diff};
/// Limits concurrent LLM calls to avoid overwhelming the network / LLM
/// provider. 8 permits balances parallelism with resource usage — LLM calls
/// are I/O-bound (1-5s network waits), so more permits than the CPU-bound
/// `HEAVY_OPS_SEMAPHORE` (4) but still bounded.
static LLM_SEMAPHORE: LazyLock<Semaphore> = LazyLock::new(|| Semaphore::new(8));
/// Subdirectory of `.git/wt/cache/` holding cached summaries.
const KIND: &str = "summary";
/// Cached summary stored in `.git/wt/cache/summary/{branch}/{hash}.json`.
///
/// The diff hash lives in the filename; the branch lives in the directory
/// name. The `branch` field holds the original (un-sanitized) branch name
/// so `list_all` can surface it for display without needing to reverse
/// `sanitize_for_filename`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub(crate) struct CachedSummary {
pub summary: String,
/// Original branch name (for display in `wt config state get`).
pub branch: String,
/// Unix timestamp when the summary was generated. Used for the "Age"
/// column in `wt config state get`. Mirrors `CachedCiStatus::checked_at`.
#[serde(default)]
pub generated_at: u64,
}
/// Combined diff output for a branch (branch diff + working tree diff)
pub(crate) struct CombinedDiff {
pub diff: String,
pub stat: String,
}
/// Template for summary generation.
///
/// Uses commit-message format (subject + body) which naturally produces
/// imperative-mood summaries without "This branch..." preamble.
const SUMMARY_TEMPLATE: &str = r#"<task>Write a summary of this branch's changes as a commit message.</task>
<format>
- Subject line under 50 chars, imperative mood ("Add feature" not "Adds feature")
- Blank line, then a body paragraph or bullet list explaining the key changes
- Output only the message — no quotes, code blocks, or labels
</format>
<diffstat>
{{ git_diff_stat }}
</diffstat>
<diff>
{{ git_diff }}
</diff>
"#;
impl CachedSummary {
/// Root of all summary cache entries: `.git/wt/cache/summary/`.
pub(crate) fn cache_root(repo: &Repository) -> PathBuf {
cache::cache_dir(repo, KIND)
}
/// Per-branch directory holding one file per cached diff hash.
fn branch_dir(repo: &Repository, branch: &str) -> PathBuf {
Self::cache_root(repo).join(sanitize_for_filename(branch))
}
/// Full path for a specific (branch, hash) pair.
pub(crate) fn cache_file(repo: &Repository, branch: &str, hash: &str) -> PathBuf {
Self::branch_dir(repo, branch).join(format!("{hash}.json"))
}
/// Read the cached summary for a branch at a specific diff hash.
/// See [`worktrunk::cache::read_json`] for the miss semantics.
pub(crate) fn read(repo: &Repository, branch: &str, hash: &str) -> Option<Self> {
cache::read_json(&Self::cache_file(repo, branch, hash))
}
/// Write the summary at `{branch}/{hash}.json` and prune sibling hashes
/// for the same branch. `hash` is the SHA-256 digest of the combined
/// diff that produced this summary.
pub(crate) fn write(&self, repo: &Repository, hash: &str) {
cache::write_json(&Self::cache_file(repo, &self.branch, hash), self);
cache::sweep_lru(&Self::branch_dir(repo, &self.branch), 1);
}
/// List one cached summary per branch — the freshest by `generated_at`
/// when multiple entries coexist transiently from concurrent writers.
/// Returns newest-first with branch-name tiebreak.
pub(crate) fn list_all(repo: &Repository) -> Vec<Self> {
let root = Self::cache_root(repo);
let Ok(branch_dirs) = fs::read_dir(&root) else {
return Vec::new();
};
let mut out: Vec<Self> = branch_dirs
.filter_map(|e| e.ok())
.filter_map(|entry| {
if !entry.file_type().ok()?.is_dir() {
return None;
}
freshest_entry(&entry.path())
})
.collect();
out.sort_by(|a, b| {
b.generated_at
.cmp(&a.generated_at)
.then_with(|| a.branch.cmp(&b.branch))
});
out
}
/// Clear all cached summaries, returning the count of `.json` entries removed.
///
/// Summaries are two levels deep (`summary/{branch}/{hash}.json`), so
/// iterate branch subdirs and delegate per-directory cleanup to
/// [`cache::clear_json_files`]. Non-directory entries at the root are
/// skipped. Empty branch dirs get best-effort rmdir so the tree stays
/// tidy.
pub(crate) fn clear_all(repo: &Repository) -> anyhow::Result<usize> {
let root = Self::cache_root(repo);
let branch_dirs = match fs::read_dir(&root) {
Ok(entries) => entries,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(0),
Err(e) => {
return Err(
anyhow::Error::new(e).context(format!("failed to read {}", root.display()))
);
}
};
let mut cleared = 0;
for entry in branch_dirs.flatten() {
if !entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
continue;
}
let dir = entry.path();
cleared += cache::clear_json_files(&dir)?;
let _ = fs::remove_dir(&dir);
}
Ok(cleared)
}
}
/// Load every `.json` cache entry in a branch directory and return the one
/// with the newest `generated_at`. Corrupt entries are skipped.
fn freshest_entry(dir: &Path) -> Option<CachedSummary> {
fs::read_dir(dir)
.ok()?
.filter_map(|e| e.ok())
.filter(|e| e.file_name().to_str().is_some_and(|s| s.ends_with(".json")))
.filter_map(|e| cache::read_json::<CachedSummary>(&e.path()))
.max_by_key(|s| s.generated_at)
}
/// Hash a string with SHA-256 and return the first 16 hex chars (64 bits).
///
/// 64 bits is more than enough entropy to make collisions astronomically
/// unlikely at realistic cache sizes. We truncate for shorter, friendlier
/// filenames — the full 256-bit digest would produce 64-char filenames
/// with no practical benefit.
///
/// `DefaultHasher` (previously used) is explicitly undocumented as
/// stable across Rust versions, which is unsafe for a value persisted
/// to disk. SHA-256 is deterministic across toolchains and platforms.
pub(crate) fn hash_diff(diff: &str) -> String {
use std::fmt::Write as _;
let mut hasher = Sha256::new();
hasher.update(diff.as_bytes());
let mut out = String::with_capacity(16);
for b in hasher.finalize().iter().take(8) {
let _ = write!(out, "{b:02x}");
}
out
}
/// Compute the combined diff for a branch (branch diff + working tree diff).
///
/// The branch diff measures against the upstream-aware comparison base (see
/// [`Repository::branch_diff_spec`]) — the same ref the `wt list` columns use,
/// not the raw local default — so a stale fork default can't describe upstream
/// commits as the branch's own changes; orphan branches contribute their full
/// content rather than nothing. Returns `None` if there's nothing to summarize
/// (default branch with no changes, or no comparison base and no working tree
/// diff).
pub(crate) fn compute_combined_diff(
branch: &str,
head: &str,
worktree_path: Option<&Path>,
repo: &Repository,
) -> Option<CombinedDiff> {
let mut diff = String::new();
let mut stat = String::new();
// Branch diff vs the comparison base — skipped for the default-branch row
// itself (the baseline) and when no comparison base resolves.
let is_default_branch = repo.default_branch().as_deref() == Some(branch);
if !is_default_branch
&& let Some(spec) = repo.branch_diff_spec(head)
&& let Some(base) = spec.diff_base
{
let prepared = repo.prepare_diff(base, head);
if let Ok(text) = prepared.capture(["--stat"]) {
stat.push_str(&text);
}
if let Ok(text) = prepared.capture(["--patch"]) {
diff.push_str(&text);
}
}
// Working tree diff: uncommitted changes
if let Some(wt_path) = worktree_path {
let prepared = repo.worktree_at(wt_path).prepare_diff("HEAD");
if let Ok(wt_stat) = prepared.capture(["--stat"])
&& !wt_stat.trim().is_empty()
{
stat.push_str(&wt_stat);
}
if let Ok(wt_diff) = prepared.capture(["--patch"])
&& !wt_diff.trim().is_empty()
{
diff.push_str(&wt_diff);
}
}
if diff.trim().is_empty() {
return None;
}
Some(CombinedDiff { diff, stat })
}
/// Render the summary prompt template
pub(crate) fn render_prompt(diff: &str, stat: &str) -> anyhow::Result<String> {
let env = Environment::new();
let tmpl = env.template_from_str(SUMMARY_TEMPLATE)?;
let rendered = tmpl.render(minijinja::context! {
git_diff => diff,
git_diff_stat => stat,
})?;
Ok(rendered)
}
/// Core summary generation pipeline: diff → cache check → LLM → cache write.
///
/// Returns `Ok(None)` when there are no changes to summarize (e.g., default branch
/// with clean worktree). Returns `Ok(Some(full_summary))` on success. Errors
/// propagate from template rendering or LLM execution.
///
/// Both `generate_summary` (TUI) and the list summary task delegate
/// to this function, wrapping its result with their own error formatting.
pub(crate) fn generate_summary_core(
branch: &str,
head: &str,
worktree_path: Option<&Path>,
llm_command: &str,
repo: &Repository,
) -> anyhow::Result<Option<String>> {
let Some(combined) = compute_combined_diff(branch, head, worktree_path, repo) else {
return Ok(None);
};
let diff_hash = hash_diff(&combined.diff);
// Cache hit is "does the file exist?" — no JSON parse needed for the
// staleness check because the hash lives in the filename.
if let Some(cached) = CachedSummary::read(repo, branch, &diff_hash) {
return Ok(Some(cached.summary));
}
// Prepare diff (filter large diffs)
let prepared = prepare_diff(combined.diff, combined.stat);
let prompt = render_prompt(&prepared.diff, &prepared.stat)?;
// Acquire the LLM permit only around the actual LLM call. The no-changes
// and cache-hit fast paths above return without contending — otherwise a
// clean `main` branch sits behind up to 8 slow summary calls and misses
// the picker's collect deadline, surfacing as a `·` in the Summary column.
let _permit = LLM_SEMAPHORE.acquire();
let summary = execute_llm_command(llm_command, &prompt)?;
let cached = CachedSummary {
summary: summary.clone(),
branch: branch.to_string(),
generated_at: epoch_now(),
};
cached.write(repo, &diff_hash);
Ok(Some(summary))
}
/// Generate a summary for a single branch, using cache when available.
///
/// This is the TUI-friendly wrapper that returns a formatted string for all cases,
/// including errors and "no changes" — suitable for `wt switch` preview pane.
pub(crate) fn generate_summary(
branch: &str,
head: &str,
worktree_path: Option<&Path>,
llm_command: &str,
repo: &Repository,
) -> String {
match generate_summary_core(branch, head, worktree_path, llm_command, repo) {
Ok(Some(summary)) => summary,
Ok(None) => {
let reset = Reset;
cformat!("{INFO_SYMBOL}{reset} <bold>{branch}</>{reset} has no changes to summarize\n")
}
Err(e) => format_summary_error(&e),
}
}
/// Format a summary-generation error for the preview pane.
///
/// A typed command failure carries the LLM command's captured output —
/// `display_message` surfaces that rather than the single-line chain
/// summary. For anything else (shell spawn failure, template bug) keep
/// the full anyhow chain, which `display_message` would collapse to its
/// outermost line.
fn format_summary_error(e: &anyhow::Error) -> String {
if CommandError::find_in(e).is_some() {
format!("Error: {}", e.display_message())
} else {
format!("Error: {e:#}")
}
}
#[cfg(test)]
mod tests {
use super::*;
/// A non-command error (spawn failure, template bug) keeps its full
/// anyhow chain in the preview pane; command failures are covered by
/// `test_generate_summary_llm_error`.
#[test]
fn format_summary_error_keeps_chain_for_non_command_errors() {
use anyhow::Context;
let err = std::io::Error::new(std::io::ErrorKind::NotFound, "No such file or directory");
let err = anyhow::Result::<()>::Err(err.into())
.context("Failed to spawn LLM command")
.unwrap_err();
assert_eq!(
format_summary_error(&err),
"Error: Failed to spawn LLM command: No such file or directory"
);
}
#[test]
fn test_render_prompt_includes_diff_and_stat() {
let result = render_prompt("diff content here", "stat content here").unwrap();
insta::assert_snapshot!(result, @r#"
<task>Write a summary of this branch's changes as a commit message.</task>
<format>
- Subject line under 50 chars, imperative mood ("Add feature" not "Adds feature")
- Blank line, then a body paragraph or bullet list explaining the key changes
- Output only the message — no quotes, code blocks, or labels
</format>
<diffstat>
stat content here
</diffstat>
<diff>
diff content here
</diff>
"#);
}
#[test]
fn test_hash_diff_is_sha256_prefix() {
// SHA-256("hello world") hex prefix is "b94d27b9934d3e08".
assert_eq!(hash_diff("hello world"), "b94d27b9934d3e08");
// Deterministic.
assert_eq!(hash_diff("hello world"), hash_diff("hello world"));
// Different inputs → different hashes.
assert_ne!(hash_diff("hello"), hash_diff("world"));
}
}