cargo-rail: fixed the WorkspaceContext not being passed efficiently; all commands now use the single main.rs WorkspaceContext; added rustdocs

Author: loadingalias

src/cargo/mod.rs

@@ -1,3 +1,12 @@
+//! Cargo workspace integration and manipulation
+//!
+//! This module provides utilities for working with Cargo workspaces:
+//!
+//! - **metadata**: Load and query Cargo.toml metadata using cargo_metadata
+//! - **transform**: Transform Cargo.toml files (flatten workspace inheritance, convert path deps)
+//! - **files**: Discover and copy auxiliary files (.cargo, rust-toolchain, etc.)
+//! - **helpers**: Cargo-specific utility functions
+
 pub mod files;
 pub mod helpers;
 pub mod metadata;

src/commands/doctor.rs

@@ -2,25 +2,22 @@
 //!
 //! The doctor command runs all health checks and reports any issues found.
 
-use std::env;
-
 use crate::checks::{CheckContext, create_default_runner};
+use crate::core::context::WorkspaceContext;
 use crate::core::error::{ExitCode, RailError, RailResult};
 
 /// Run the doctor command to diagnose issues
 ///
 /// Returns Ok(()) if all checks pass, or exits with error code if checks fail
-pub fn run_doctor(thorough: bool, json: bool) -> RailResult<()> {
-  let current_dir = env::current_dir()?;
-
-  let ctx = CheckContext {
-    workspace_root: current_dir,
+pub fn run_doctor(ctx: &WorkspaceContext, thorough: bool, json: bool) -> RailResult<()> {
+  let check_ctx = CheckContext {
+    workspace_root: ctx.workspace_root().to_path_buf(),
     crate_name: None,
     thorough,
   };
 
   let runner = create_default_runner();
-  let results = runner.run_all(&ctx)?;
+  let results = runner.run_all(&check_ctx)?;
 
   if json {
     // JSON output for CI/automation
@@ -83,31 +80,27 @@ pub fn run_doctor(thorough: bool, json: bool) -> RailResult<()> {
 ///
 /// This is useful for commands that want to verify the environment is ready
 /// before starting work. Returns true if all checks pass, false otherwise.
-pub fn run_preflight_check(thorough: bool) -> RailResult<bool> {
-  let current_dir = env::current_dir()?;
-
-  let ctx = CheckContext {
-    workspace_root: current_dir,
+pub fn run_preflight_check(ctx: &WorkspaceContext, thorough: bool) -> RailResult<bool> {
+  let check_ctx = CheckContext {
+    workspace_root: ctx.workspace_root().to_path_buf(),
     crate_name: None,
     thorough,
   };
 
   let runner = create_default_runner();
-  runner.run_all_and_check(&ctx)
+  runner.run_all_and_check(&check_ctx)
 }
 
 /// Run checks for a specific crate
 ///
 /// Useful for validating a single crate before split/sync operations
-pub fn run_crate_check(crate_name: &str, thorough: bool) -> RailResult<bool> {
-  let current_dir = env::current_dir()?;
-
-  let ctx = CheckContext {
-    workspace_root: current_dir,
+pub fn run_crate_check(ctx: &WorkspaceContext, crate_name: &str, thorough: bool) -> RailResult<bool> {
+  let check_ctx = CheckContext {
+    workspace_root: ctx.workspace_root().to_path_buf(),
     crate_name: Some(crate_name.to_string()),
     thorough,
   };
 
   let runner = create_default_runner();
-  runner.run_all_and_check(&ctx)
+  runner.run_all_and_check(&check_ctx)
 }

src/commands/lint.rs

@@ -1,17 +1,16 @@
 //! Lint command implementation
 
 use crate::checks::{CheckContext, Severity, create_manifest_runner};
-use crate::core::config::RailConfig;
+use crate::core::context::WorkspaceContext;
 use crate::core::error::{RailError, RailResult};
 use crate::lint::{DepsLinter, DepsReport, VersionsLinter, VersionsReport};
 use cargo_metadata::MetadataCommand;
-use std::env;
 
 /// Run the lint deps command
-pub fn run_lint_deps(fix: bool, apply: bool, json: bool, strict: bool) -> RailResult<()> {
+pub fn run_lint_deps(ctx: &WorkspaceContext, fix: bool, apply: bool, json: bool, strict: bool) -> RailResult<()> {
   // Load workspace metadata
   let metadata = MetadataCommand::new()
-    .current_dir(env::current_dir()?)
+    .current_dir(ctx.workspace_root())
     .exec()
     .map_err(|e| RailError::message(format!("Failed to load workspace metadata: {}", e)))?;
 
@@ -130,16 +129,16 @@ fn print_fix_report(report: &crate::lint::DepsFixReport) {
 }
 
 /// Run the lint versions command
-pub fn run_lint_versions(fix: bool, apply: bool, json: bool, strict: bool) -> RailResult<()> {
+pub fn run_lint_versions(ctx: &WorkspaceContext, fix: bool, apply: bool, json: bool, strict: bool) -> RailResult<()> {
   // Load workspace metadata
   let metadata = MetadataCommand::new()
-    .current_dir(env::current_dir()?)
+    .current_dir(ctx.workspace_root())
     .exec()
     .map_err(|e| RailError::message(format!("Failed to load workspace metadata: {}", e)))?;
 
   // Try to load policy config
-  let config = RailConfig::load(&env::current_dir()?).ok();
-  let policy = config.as_ref().map(|c| c.policy.clone());
+  let config = ctx.config.as_ref();
+  let policy = config.map(|c| c.policy.clone());
 
   let linter = VersionsLinter::new(metadata, policy);
 
@@ -282,19 +281,17 @@ fn print_versions_fix_report(report: &crate::lint::VersionsFixReport) {
 }
 
 /// Run the lint manifest command
-pub fn run_lint_manifest(json: bool, strict: bool) -> RailResult<()> {
-  let workspace_root = env::current_dir()?;
-
+pub fn run_lint_manifest(ctx: &WorkspaceContext, json: bool, strict: bool) -> RailResult<()> {
   // Create context for checks
-  let ctx = CheckContext {
-    workspace_root: workspace_root.clone(),
+  let check_ctx = CheckContext {
+    workspace_root: ctx.workspace_root().to_path_buf(),
     crate_name: None,
     thorough: false, // Manifest checks are never expensive
   };
 
   // Run manifest-specific checks
   let runner = create_manifest_runner();
-  let results = runner.run_all(&ctx)?;
+  let results = runner.run_all(&check_ctx)?;
 
   // Output results
   if json {

src/commands/mappings.rs

@@ -1,8 +1,7 @@
 use serde::{Deserialize, Serialize};
-use std::env;
 use std::process::Command;
 
-use crate::core::config::RailConfig;
+use crate::core::context::WorkspaceContext;
 use crate::core::error::{ConfigError, RailError, RailResult};
 use crate::core::mapping::MappingStore;
 use crate::ui::progress::FileProgress;
@@ -56,17 +55,8 @@ pub struct IntegrityCheck {
 }
 
 /// Run the mappings command
-pub fn run_mappings(crate_name: String, check: bool, json: bool) -> RailResult<()> {
-  let current_dir = env::current_dir()?;
-
-  // Load configuration
-  if !RailConfig::exists(&current_dir) {
-    return Err(RailError::Config(ConfigError::NotFound {
-      workspace_root: current_dir,
-    }));
-  }
-
-  let config = RailConfig::load(&current_dir)?;
+pub fn run_mappings(ctx: &WorkspaceContext, crate_name: String, check: bool, json: bool) -> RailResult<()> {
+  let config = ctx.require_config()?.as_ref();
 
   // Find crate configuration
   let split_config = config.splits.iter().find(|s| s.name == crate_name).ok_or_else(|| {
@@ -78,7 +68,7 @@ pub fn run_mappings(crate_name: String, check: bool, json: bool) -> RailResult<(
   // Load mappings
   let notes_ref = format!("refs/notes/rail/{}", crate_name);
   let mut mapping_store = MappingStore::new(crate_name.clone());
-  mapping_store.load(&current_dir)?;
+  mapping_store.load(ctx.workspace_root())?;
 
   let raw_mappings = mapping_store.all_mappings();
 
@@ -104,8 +94,8 @@ pub fn run_mappings(crate_name: String, check: bool, json: bool) -> RailResult<(
 
     if check {
       // Verify both commits exist
-      let mono_exists = commit_exists(&current_dir, mono_sha)?;
-      let remote_exists = if let Some(target_path) = get_target_path(&current_dir, split_config) {
+      let mono_exists = commit_exists(ctx.workspace_root(), mono_sha)?;
+      let remote_exists = if let Some(target_path) = get_target_path(ctx.workspace_root(), split_config) {
         commit_exists(&target_path, remote_sha)?
       } else {
         false

src/commands/mod.rs

@@ -1,3 +1,31 @@
+//! CLI commands for cargo-rail
+//!
+//! This module contains all user-facing command implementations:
+//!
+//! ## Setup & Inspection
+//! - **init**: Initialize rail.toml configuration for a workspace
+//! - **doctor**: Run health checks and validation
+//! - **status**: Show split/sync status for all crates
+//! - **mappings**: View git commit mappings for split crates
+//!
+//! ## Split & Sync (Pillar 2)
+//! - **split**: Split monorepo crates to separate repositories
+//! - **sync**: Bidirectional sync between monorepo and split repos
+//!
+//! ## Graph Operations (Pillar 1)
+//! - **affected**: Find crates affected by changes
+//! - **test**: Run tests for affected crates only
+//! - **check**: Run cargo check for affected crates
+//! - **clippy**: Run clippy for affected crates
+//!
+//! ## Linting (Pillar 3)
+//! - **lint**: Workspace policy enforcement (deps, versions, manifest)
+//!
+//! ## Releases (Pillar 4)
+//! - **release**: Release planning and execution with changelog generation
+//!
+//! All commands accept `&WorkspaceContext` to avoid redundant workspace loads.
+
 pub mod affected;
 pub mod check;
 pub mod clippy;

src/commands/release.rs

@@ -6,17 +6,15 @@
 //! 3. Every release has name + version + last_sha
 
 use crate::core::config::ReleaseConfig;
+use crate::core::context::WorkspaceContext;
 use crate::core::error::{RailError, RailResult};
 use crate::quality::changelog::{Changelog, ChangelogFormat, ConventionalCommit};
 use crate::release::{ReleasePlan, ReleaseTracker, VersionBump};
-use std::env;
 
 /// Run the release plan command
-pub fn run_release_plan(name: Option<String>, all: bool, json: bool) -> RailResult<()> {
-  let workspace_root = env::current_dir()?;
-
+pub fn run_release_plan(ctx: &WorkspaceContext, name: Option<String>, all: bool, json: bool) -> RailResult<()> {
   // Load release tracker
-  let tracker = ReleaseTracker::load(&workspace_root)?;
+  let tracker = ReleaseTracker::load(ctx.workspace_root())?;
 
   // Determine which releases to plan
   let releases: Vec<_> = if all {
@@ -47,7 +45,7 @@ pub fn run_release_plan(name: Option<String>, all: bool, json: bool) -> RailResu
   // Analyze each release
   let mut plans = Vec::new();
   for release in &releases {
-    let plan = ReleasePlan::analyze(&workspace_root, release)?;
+    let plan = ReleasePlan::analyze(ctx.workspace_root(), release)?;
     plans.push(plan);
   }
 
@@ -63,15 +61,14 @@ pub fn run_release_plan(name: Option<String>, all: bool, json: bool) -> RailResu
 
 /// Run the release apply command
 pub fn run_release_apply(
+  ctx: &WorkspaceContext,
   name: String,
   dry_run: bool,
   // Skip syncing to split repos - deferred to post-v1 (see TODO.md Post-v1: Auto-sync to split repos)
   #[allow(unused_variables)] skip_sync: bool,
 ) -> RailResult<()> {
-  let workspace_root = env::current_dir()?;
-
   // Load release tracker
-  let mut tracker = ReleaseTracker::load(&workspace_root)?;
+  let mut tracker = ReleaseTracker::load(ctx.workspace_root())?;
 
   // Find the release
   let release = tracker
@@ -80,7 +77,7 @@ pub fn run_release_apply(
     .clone();
 
   // Generate plan
-  let plan = ReleasePlan::analyze(&workspace_root, &release)?;
+  let plan = ReleasePlan::analyze(ctx.workspace_root(), &release)?;
 
   if !plan.has_changes {
     println!("⚠️  No changes detected for '{}'", name);
@@ -125,25 +122,29 @@ pub fn run_release_apply(
   println!("✅ Applying release...");
 
   // 1. Update Cargo.toml version
-  update_crate_version(&workspace_root, &release.crate_path, &plan.proposed_version.to_string())?;
+  update_crate_version(
+    ctx.workspace_root(),
+    &release.crate_path,
+    &plan.proposed_version.to_string(),
+  )?;
   println!("   Updated Cargo.toml version");
 
   // 2. Generate and update changelog (if configured)
   if let Some(changelog_path) = &release.changelog {
-    generate_changelog(&workspace_root, &release, &plan, changelog_path)?;
+    generate_changelog(ctx.workspace_root(), &release, &plan, changelog_path)?;
     println!("   Updated {}", changelog_path.display());
   }
 
   // 3. Get current HEAD SHA
-  let head_sha = get_head_sha(&workspace_root)?;
+  let head_sha = get_head_sha(ctx.workspace_root())?;
 
   // 4. Update rail.toml metadata
   tracker.update_release(&name, &plan.proposed_version.to_string(), &head_sha)?;
   tracker.save()?;
   println!("   Updated rail.toml metadata");
 
   // 5. Create git tag
-  create_git_tag(&workspace_root, &name, &plan.proposed_version.to_string())?;
+  create_git_tag(ctx.workspace_root(), &name, &plan.proposed_version.to_string())?;
   println!("   Created tag: {}-v{}", name, plan.proposed_version);
 
   println!();