Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(list): align stale compute_status_symbols comments with refresh_status_symbols (#3175)

Worktrunk Bot41bd66535b23
diff --git a/src/commands/list/collect/execution.rs b/src/commands/list/collect/execution.rs
index 8f27d62c7..7a8cd35b5 100644
--- a/src/commands/list/collect/execution.rs
+++ b/src/commands/list/collect/execution.rs
@@ -9,14 +9,15 @@
//!
//! ## Status field bookkeeping at spawn time
//!
-//! `compute_status_symbols` refuses to compute until every required field on
-//! `ListItem` / `WorktreeData` is `Some`. Tasks that *will* run are written
-//! by the drain as their results arrive. Tasks that will *not* run (stale
-//! branches skip expensive tasks, unborn branches skip commit-dependent
-//! tasks, `--skip-tasks` filters, branches with no worktree have no
-//! worktree-only tasks) have their fields seeded here via
-//! [`seed_skipped_task_defaults`] with conservative defaults — otherwise
-//! the fields would stay `None` forever and status would never compute.
+//! `refresh_status_symbols` resolves each gate independently, reading that
+//! gate's required fields on `ListItem` / `WorktreeData` as they become
+//! `Some`. Tasks that *will* run are written by the drain as their results
+//! arrive. Tasks that will *not* run (stale branches skip expensive tasks,
+//! unborn branches skip commit-dependent tasks, `--skip-tasks` filters,
+//! branches with no worktree have no worktree-only tasks) have their fields
+//! seeded here via [`seed_skipped_task_defaults`] with conservative defaults
+//! — otherwise the fields would stay `None` forever and their gate would
+//! never resolve.
use std::sync::Arc;
@@ -517,16 +518,17 @@ pub fn work_items_for_branch(
});
}
// `UserMarker` is never in the branch task list above (it only runs
- // for worktrees), but the branch arm of `compute_status_symbols`
- // *does* read `item.user_marker` and will bail while it is `None`.
- // Seed it here so branches can compute status.
+ // for worktrees), but the user-marker gate of `refresh_status_symbols`
+ // *does* read `item.user_marker` and leaves position 6 unresolved while
+ // it is `None`. Seed it here so the marker gate resolves for branches.
seed_skipped_task_defaults(item, TaskKind::UserMarker);
- // `WorkingTreeDiff` / `WorkingTreeConflicts` / `GitOperation` only
- // affect the worktree arm of `compute_status_symbols`, which is never
- // entered for `ItemKind::Branch`. Seeding them is a no-op today (the
- // seed helper branches on `ItemKind::Worktree` internally) but makes
- // the per-item task set explicit and keeps this loop forward-compatible
- // if the branch arm ever starts reading them.
+ // `WorkingTreeDiff` / `WorkingTreeConflicts` / `GitOperation` feed
+ // worktree-specific inputs; for branches the gates that read them
+ // resolve via dedicated `ItemKind::Branch` arms in
+ // `refresh_status_symbols`, never reading these fields. Seeding them is
+ // a no-op today (the seed helper branches on `ItemKind::Worktree`
+ // internally) but makes the per-item task set explicit and keeps this
+ // loop forward-compatible if the branch path ever starts reading them.
for kind in [
TaskKind::WorkingTreeDiff,
TaskKind::WorkingTreeConflicts,
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rs
index 2d7311d24..4d7beb46a 100644
--- a/src/commands/list/collect/mod.rs
+++ b/src/commands/list/collect/mod.rs
@@ -2086,7 +2086,7 @@ pub fn populate_item(
});
// Drain task results (blocking until complete). `drain_results`
- // writes each result onto the item and calls `compute_status_symbols`
+ // writes each result onto the item and calls `refresh_status_symbols`
// after every write, so the callback here is just a no-op — there is
// no progressive table to refresh on the statusline path.
let drain_outcome = drain_results(
diff --git a/src/commands/list/collect/results.rs b/src/commands/list/collect/results.rs
index d7033dcf5..c5de447eb 100644
--- a/src/commands/list/collect/results.rs
+++ b/src/commands/list/collect/results.rs
@@ -101,8 +101,8 @@ fn pick_pending_hint<'a>(
///
/// Errors are collected in the `errors` vec for display after rendering. No
/// defaults are applied — an errored field stays `None`, so the renderer
-/// shows its standard placeholder and `compute_status_symbols` stays a
-/// no-op for that item.
+/// shows its standard placeholder and the gate that reads it in
+/// `refresh_status_symbols` stays unresolved.
///
/// Callers decide how to handle timeout:
/// - `collect()`: Shows user-facing diagnostic (interactive command)
@@ -417,9 +417,9 @@ mod tests {
item.upstream = Some(UpstreamStatus::default());
}
- /// True iff `compute_status_symbols` produced its full output (using
+ /// True iff `refresh_status_symbols` resolved every gate (using
/// the seed values from `seed_all_fields`). False iff status is at
- /// default (nothing computed) or the metadata-only fallback ran.
+ /// default (nothing computed) or only the metadata-only gate ran.
fn full_computation_ran(item: &ListItem) -> bool {
item.status_symbols.main_state == Some(MainState::Diverged)
}
diff --git a/src/commands/list/collect/types.rs b/src/commands/list/collect/types.rs
index 2224e1f28..1304810b2 100644
--- a/src/commands/list/collect/types.rs
+++ b/src/commands/list/collect/types.rs
@@ -191,7 +191,8 @@ pub enum ErrorCause {
///
/// Tasks return this instead of swallowing errors. The drain layer
/// collects errors for display after rendering; errored fields stay
-/// `None` so `compute_status_symbols` naturally skips the item.
+/// `None` so `refresh_status_symbols` naturally leaves the affected gate
+/// unresolved.
#[derive(Debug, Clone)]
pub struct TaskError {
pub item_idx: usize,
diff --git a/src/commands/list/json_output.rs b/src/commands/list/json_output.rs
index dd7fa84f8..39f5749df 100644
--- a/src/commands/list/json_output.rs
+++ b/src/commands/list/json_output.rs
@@ -314,7 +314,7 @@ impl JsonItem {
// Working tree: read directly from `WorktreeData`, not from
// `status_symbols.working_tree`. `status_symbols` may be set by
- // the metadata-only fallback in `compute_status_symbols` (locked
+ // the metadata-only Gate 2 of `refresh_status_symbols` (locked
// / prunable / mismatched worktrees) carrying a default
// `WorkingTreeStatus`. The JSON output must reflect whether
// `WorkingTreeDiff` actually loaded the field — collapsing
diff --git a/src/commands/list/model/item.rs b/src/commands/list/model/item.rs
index 57d5fe8e8..6ce9ef5c3 100644
--- a/src/commands/list/model/item.rs
+++ b/src/commands/list/model/item.rs
@@ -15,8 +15,8 @@ use crate::commands::list::columns::ColumnKind;
/// Compute the `WorktreeState` from `WorktreeData` metadata alone.
///
-/// Used by both `compute_status_symbols` (full computation) and the
-/// metadata-only fallback path. The decision priority is:
+/// Used by `refresh_status_symbols` to resolve the worktree-state position
+/// (Gate 2) from metadata alone. The decision priority is:
/// `branch_worktree_mismatch` > `prunable` > `locked` > `None`.
fn metadata_worktree_state(data: &WorktreeData) -> WorktreeState {
if data.branch_worktree_mismatch {
diff --git a/src/commands/list/model/status_symbols.rs b/src/commands/list/model/status_symbols.rs
index b18dfb0f4..ff2610ec8 100644
--- a/src/commands/list/model/status_symbols.rs
+++ b/src/commands/list/model/status_symbols.rs
@@ -220,8 +220,7 @@
//! skeleton render — every gate starts as `None` → `·`. Per-gate resolution
//! populates individual fields as task results arrive.
//!
-//! `refresh_status_symbols` (replacing the current "all or nothing"
-//! `compute_status_symbols`) is called after every drain tick: it tries each
+//! `refresh_status_symbols` is called after every drain tick: it tries each
//! gate independently and sets any fields whose inputs are now ready. It is
//! idempotent — a gate, once resolved, is never un-resolved.
//!
@@ -273,7 +272,7 @@ impl PositionMask {
1, // MODIFIED: ! (1 char)
1, // UNTRACKED: ? (1 char)
1, // WORKTREE_STATE: ✘⤴⤵/⚑⊟⊞ (1 char, priority: conflicts > rebase > merge > branch_worktree_mismatch > prunable > locked > branch)
- 1, // MAIN_STATE: ^✗_–⊂↕↑↓ (1 char, priority: is_main > would_conflict > empty > same_commit > integrated > diverged > ahead > behind)
+ 1, // MAIN_STATE: ^✗_–⊂↕↑↓ (1 char, priority: is_main > orphan > would_conflict > empty > same_commit > integrated > diverged > ahead > behind)
1, // UPSTREAM_DIVERGENCE: |⇡⇣⇅ (1 char)
2, // USER_MARKER: single emoji or two chars (allocate 2)
],