Skip to content

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

refactor: rename ResolutionContext to OperationMode (#759)

Maximilian Roos74269fffba69
diff --git a/.claude/rules/accessor-conventions.md b/.claude/rules/accessor-conventions.md
new file mode 100644
index 000000000..864f2f680
--- /dev/null
+++ b/.claude/rules/accessor-conventions.md
@@ -0,0 +1,54 @@
+# Accessor Function Naming Conventions
+
+Function prefixes signal return behavior and side effects.
+
+## Prefix Semantics
+
+| Prefix | Returns | Side Effects | Error Handling | Example |
+|--------|---------|--------------|----------------|---------|
+| `get_*` | `Option<T>` or `T` | None (may cache) | Returns None/default if absent | `get_config()`, `get_switch_previous()` |
+| `require_*` | `Result<T>` | None | Errors if absent | `require_branch()`, `require_target_ref()` |
+| `fetch_*` | `Result<T>` | Network I/O | Errors on failure | `fetch_pr_info()`, `fetch_mr_info()` |
+| `load_*` | `Result<T>` | File I/O | Errors on failure | `load_project_config()`, `load_template()` |
+
+## When to Use Each
+
+**`get_*`** — Value may not exist and that's fine
+```rust
+// Returns Option - caller handles None
+if let Some(prev) = repo.get_switch_previous() {
+ // use prev
+}
+
+// Returns T with sensible default
+let width = get_terminal_width(); // defaults to 80 if detection fails
+```
+
+**`require_*`** — Value must exist for operation to proceed
+```rust
+// Error propagates if branch is missing
+let branch = env.require_branch("squash")?;
+```
+
+**`fetch_*`** — Retrieve from external service (network)
+```rust
+// May fail due to network, auth, rate limits
+let pr = fetch_pr_info(123, &repo_root)?;
+```
+
+**`load_*`** — Read from filesystem
+```rust
+// May fail due to missing file, parse errors
+let config = repo.load_project_config()?;
+```
+
+## Anti-patterns
+
+Avoid mixing semantics:
+- Don't use `get_*` if the function makes network calls (use `fetch_*`)
+- Don't use `get_*` if absence is an error (use `require_*`)
+- Don't use `load_*` for computed values (use `get_*`)
+
+## Related Patterns
+
+For caching behavior, see `caching-strategy.md`.
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index 5a9fb9a36..1b6ba437e 100644
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -42,7 +42,7 @@ pub(crate) use step_commands::{
step_show_squash_prompt,
};
pub(crate) use worktree::{
- ResolutionContext, execute_switch, handle_remove, handle_remove_current,
+ OperationMode, execute_switch, handle_remove, handle_remove_current,
is_worktree_at_expected_path, plan_switch, resolve_worktree_arg, worktree_display_name,
};
diff --git a/src/commands/worktree/mod.rs b/src/commands/worktree/mod.rs
index c52f8aa51..1682bdeb0 100644
--- a/src/commands/worktree/mod.rs
+++ b/src/commands/worktree/mod.rs
@@ -93,6 +93,6 @@ pub use resolve::{
};
pub use switch::{execute_switch, plan_switch};
pub use types::{
- BranchDeletionMode, MergeOperations, RemoveResult, ResolutionContext, SwitchBranchInfo,
+ BranchDeletionMode, MergeOperations, OperationMode, RemoveResult, SwitchBranchInfo,
SwitchResult,
};
diff --git a/src/commands/worktree/resolve.rs b/src/commands/worktree/resolve.rs
index cf4d4a8ea..a5019c937 100644
--- a/src/commands/worktree/resolve.rs
+++ b/src/commands/worktree/resolve.rs
@@ -9,7 +9,7 @@ use normalize_path::NormalizePath;
use worktrunk::config::UserConfig;
use worktrunk::git::{GitError, Repository, ResolvedWorktree};
-use super::types::ResolutionContext;
+use super::types::OperationMode;
/// Resolve a worktree argument using branch-first lookup.
///
@@ -28,7 +28,7 @@ pub fn resolve_worktree_arg(
repo: &Repository,
name: &str,
config: &UserConfig,
- context: ResolutionContext,
+ context: OperationMode,
) -> anyhow::Result<ResolvedWorktree> {
// Special symbols - delegate to Repository for consistent error handling
match name {
@@ -50,7 +50,7 @@ pub fn resolve_worktree_arg(
}
// No worktree for branch - check if expected path is occupied (only for create/switch)
- if context == ResolutionContext::CreateOrSwitch {
+ if context == OperationMode::CreateOrSwitch {
let expected_path = compute_worktree_path(repo, name, config)?;
if let Some((_, occupant_branch)) = repo.worktree_at_path(&expected_path)? {
// Path is occupied by a different branch's worktree
diff --git a/src/commands/worktree/types.rs b/src/commands/worktree/types.rs
index 8a01b9258..097cd4752 100644
--- a/src/commands/worktree/types.rs
+++ b/src/commands/worktree/types.rs
@@ -204,9 +204,9 @@ pub enum RemoveResult {
},
}
-/// Context for worktree resolution - determines which checks are performed.
+/// Operation mode for worktree resolution - determines which checks are performed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum ResolutionContext {
+pub enum OperationMode {
/// Creating or switching to a worktree - path occupation is an error
/// because we need to create a worktree at the expected path.
CreateOrSwitch,
diff --git a/src/main.rs b/src/main.rs
index e0e0bde25..524a90b31 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -36,7 +36,7 @@ use commands::command_executor::{CommandContext, build_hook_context};
use commands::handle_select;
use commands::worktree::{SwitchResult, handle_push};
use commands::{
- MergeOptions, RebaseResult, ResolutionContext, SquashResult, add_approvals, approve_hooks,
+ MergeOptions, OperationMode, RebaseResult, SquashResult, add_approvals, approve_hooks,
clear_approvals, execute_switch, handle_completions, handle_config_create, handle_config_show,
handle_configure_shell, handle_hints_clear, handle_hints_get, handle_hook_show, handle_init,
handle_list, handle_merge, handle_rebase, handle_remove, handle_remove_current,
@@ -963,7 +963,7 @@ fn main() {
&repo,
branch_name,
&config,
- ResolutionContext::Remove,
+ OperationMode::Remove,
) {
Ok(r) => r,
Err(e) => {
diff --git a/tests/integration_tests/remove.rs b/tests/integration_tests/remove.rs
index 463b5f9ad..e2f5e15ad 100644
--- a/tests/integration_tests/remove.rs
+++ b/tests/integration_tests/remove.rs
@@ -199,7 +199,7 @@ fn test_remove_nonexistent_worktree(repo: TestRepo) {
///
/// Regression test for bug where `wt remove npm` would show "Cannot create worktree for npm"
-/// when the expected path was occupied. The fix uses `ResolutionContext::Remove` which skips
+/// when the expected path was occupied. The fix uses `OperationMode::Remove` which skips
/// the path occupation check entirely, correctly treating this as a branch-only removal.
///
/// Setup: