Workspace Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/project.rs
• src/main.rs
• src/init.rs
• src/isolation.rs
• src/config.rs
• README.md

Workspace Integration in cargo-cooldown refers to the system's ability to discover, isolate, and manage configuration for complex Cargo project structures, including single packages and multi-member workspaces. The integration ensures that cooldown policies are applied correctly based on whether a command targets the entire workspace or a specific active member.

The system relies on project discovery to locate workspace roots and members, temporary isolation to perform speculative dependency resolution without corrupting the user's local state, and a hierarchical configuration loading mechanism. Sources: src/project.rs, src/isolation.rs, src/config.rs.

Project Discovery and Context

The discovery module is responsible for identifying the project shape (Crate or Workspace) and locating relevant manifests. It uses cargo locate-project and cargo_metadata to resolve paths and identify workspace members. Sources: src/project.rs:90-112

Discovery Logic

Discovery differs based on whether the tool is running a standard command (runtime) or the setup wizard (init). Runtime discovery resolves the workspace root and identifies an "active member" if the user has targeted a specific package via CLI flags like --package or --manifest-path. Sources: src/project.rs:60-70, src/project.rs:166-211

The diagram shows the logical flow of discovering project information and determining if a specific workspace member is the focus of the current execution. Sources: src/project.rs:90-130

Key Data Structures

Structure	Description	Fields
ProjectContext	Full context of the discovered project.	kind, workspace_root, target_directory, members, active_member
ProjectMember	Data for a specific workspace member.	name, manifest_path, dir
ProjectKind	Enum defining project shape.	Crate, Workspace

Sources: src/project.rs:13-38

Configuration Hierarchy

cargo-cooldown implements a layered configuration system where settings are merged from multiple sources. Workspace-wide defaults can be overridden by member-specific configurations. Sources: src/config.rs:100-115

Merge Precedence

Configuration is loaded in the following order (strongest to weakest):

1. Environment Variables: Prefix COOLDOWN_.
2. Active Member Config: cooldown.toml inside a specific member's directory (only if exactly one member is targeted).
3. Workspace/Crate Root Config: cooldown.toml at the project root.
4. User Global Config: $CARGO_HOME/cooldown.toml.

Sources: src/config.rs:107-113, README.md:120-125

Path Resolution

The ProjectContext provides helper methods to find these configuration files:

• workspace_config_path(): Returns the path to the root cooldown.toml. Sources: src/project.rs:133-135
• member_config_path(): Returns the path to an active member's override, ensuring it is distinct from the workspace root. Sources: src/project.rs:138-143

Workspace Isolation

To prevent speculative dependency resolution from interfering with the user's active development environment, cargo-cooldown utilizes an isolated workspace. Sources: src/isolation.rs:11-15

Isolation Mechanism

The system creates a temporary copy of the workspace (excluding build artifacts and .git directories) and performs all cargo operations within that temporary directory. Sources: src/isolation.rs:194-220

The diagram illustrates the process of isolating the workspace to perform resolution and then committing the results back to the original project. Sources: src/isolation.rs:31-64, src/isolation.rs:114-135

Lockfile Hold Guard

A "sentinel" file is placed at the real Cargo.lock location while the isolation is active. This prevents other processes from modifying the lockfile and provides a recovery path if the process is interrupted. Sources: src/isolation.rs:138-160

Interactive Initialization (init)

The init module provides a wizard to set up workspace configurations. For workspaces, it offers two modes:

1. Workspace-wide defaults only: A single cooldown.toml at the root.
2. Per-member overrides: Individual cooldown.toml files for selected members.

Sources: src/init.rs:80-110

Initialization Plan

fn build_workspace_plan(project: &ProjectContext) -> Result<InitPlan> {
    // ... logic to prompt for member overrides ...
    let mut files = vec![InitFile {
        path: project.workspace_config_path(),
        contents: render_config_file(&base_template, false),
    }];
    // ... adds member override files if requested ...
}

Sources: src/init.rs:80-124

Summary

Workspace integration ensures that cargo-cooldown behaves predictably across diverse project structures. By combining automated discovery of workspace members with a robust configuration hierarchy and temporary isolation, the tool can safely manage dependency cooling for both individual packages and large multi-crate repositories. Sources: src/project.rs, src/isolation.rs, README.md.