Struct WorkspaceContext 

pub struct WorkspaceContext {
    pub workspace_root: PathBuf,
    pub git: Arc<GitState>,
    pub cargo: Arc<CargoState>,
    pub graph: Arc<WorkspaceGraph>,
    pub config: Option<Arc<RailConfig>>,
    /* private fields */
}

Unified workspace context containing all shared workspace-level data.

Built once at startup, passed by reference to all commands and operations. This eliminates redundant loads and provides a single source of truth for workspace state.

Uses Arc for efficient sharing across threads and parallel operations. Cloning is extremely cheap (just increments Arc refcounts).

Fields

workspace_root: PathBuf

Cargo workspace root (Cargo.toml location) Note: In most cases, git repo root == workspace root. Access git root via ctx.git.repo_root() if needed.

git: Arc<GitState>

Git state and operations (Arc for cheap cloning across threads)

cargo: Arc<CargoState>

Cargo metadata and workspace info (Arc for cheap cloning across threads)

graph: Arc<WorkspaceGraph>

Dependency graph (built from cargo metadata) Wrapped in Arc for efficient sharing across threads/commands

config: Option<Arc<RailConfig>>

Rail configuration (rail.toml) Optional because not all commands require configuration Wrapped in Arc for efficient sharing

Implementations

impl WorkspaceContext

pub fn build(workspace_root: &Path) -> RailResult<Self>

Build workspace context from a root directory.

Loads git state, cargo metadata, builds graph, and attempts to load rail.toml config. Config is optional - commands that require it should check and error.

Performance

• Git state: <5ms (single git rev-parse)
• Cargo metadata: 50-200ms for large workspaces
• Graph build: 10-50ms
• Config load: <5ms (or None if not found)
• Total: ~100-300ms (vs 100-300ms × N commands without context)

pub fn require_config(&self) -> RailResult<&Arc<RailConfig>>

Get config or error if not found.

Use this in commands that require rail.toml configuration.

pub fn multi_target_metadata(&self) -> RailResult<Arc<MultiTargetMetadata>>

Get multi-target metadata, loading lazily on first access.

This is only used by cargo rail unify. Other commands don’t need it, so lazy loading saves 150-600ms for commands like plan, run, split, etc.

The metadata is cached after first load - subsequent calls return the cached value.

pub fn workspace_root(&self) -> &Path

Get workspace root as Path reference (convenience)

pub fn workspace_prefix(&self) -> Option<PathBuf>

Get the relative path from git root to workspace root.

Returns Some(prefix) if workspace is nested inside git repo (e.g., “codex-rs”), or None if they’re the same directory.

This is used to strip the prefix from git-relative paths so they can be matched against workspace-relative paths (e.g., for crate membership).

pub fn to_workspace_path(&self, git_path: &Path) -> Option<PathBuf>

Convert a git-relative path to a workspace-relative path.

If the workspace is nested inside the git repo (e.g., git at /repo, workspace at /repo/rust), git returns paths like rust/src/lib.rs but the workspace expects src/lib.rs.

Returns None if the path doesn’t belong to this workspace.