Cargo Rail

https://docs.rs/cargo-rail/latest/
Admin
Cargo Rail is a Rust monorepo orchestration tool that provides CI optimization, dependency...
Tokens:1,354,381
Snippets:8,095
Trust Score:9.7
Update:10 months ago
Show doc for...
Tokens:
Raw
### Initialize TomlFormatter with Default Settings

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/toml/format.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new `TomlFormatter` instance with predefined default settings for array thresholds and indentation. This is the most common way to get started with the formatter.

```rust
use cargo_rail::toml::TomlFormatter;

let formatter = TomlFormatter::new();
// formatter now has default settings: inline_array_threshold: 4, inline_feature_threshold: 10, indent: "  "
```

--------------------------------

### Workspace Context Architecture Example (Rust)

Source: https://docs.rs/cargo-rail/latest/cargo_rail/workspace/context/index

Illustrates how the WorkspaceContext is built once in main.rs and passed by reference to different commands.

```rust
main.rs:
  WorkspaceContext::build() -> &WorkspaceContext
  |
  v
commands/split.rs, sync.rs, etc:
  fn execute(ctx: &WorkspaceContext)
```

--------------------------------

### Rust: Initialize RailConfigBuilder

Source: https://docs.rs/cargo-rail/latest/cargo_rail/toml/builder/struct.RailConfigBuilder_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to create a new instance of the RailConfigBuilder. This is the starting point for configuring rail settings.

```Rust
pub struct RailConfigBuilder { /* private fields */ }

// ... later in code ...
let mut builder = RailConfigBuilder::new();
```

--------------------------------

### Cargo Rail Config Validate Examples

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/cli.rs_search=

Provides examples for validating the `rail.toml` configuration file. Shows how to validate the configuration and output validation results in JSON format.

```text
Examples:
  cargo rail config validate            # Validate rail.toml
  cargo rail config validate -f json    # JSON output for CI
```

--------------------------------

### Define `init` subcommand help text

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/cli.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This snippet defines the help message and examples for the `init` subcommand. It shows how to generate the `rail.toml` configuration file, preview the generated configuration, and specify a custom output path.

```rust
const INIT_HELP: &str = "\\
Examples:
  cargo rail init                       # Generate .config/rail.toml
  cargo rail init --check               # Preview generated config
  cargo rail init -o rail.toml          # Custom output path
";
```

--------------------------------

### Check for Example Files - Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/change_detection/classify.rs

Identifies if a file path corresponds to an example file within the project. It checks for paths containing '/examples/' or starting with 'examples/'.

```rust
fn is_example_file(path_str: &str) -> bool {
  // Match patterns:
  // - examples/*.rs
  // - crates/*/examples/*.rs
  // - */examples/*.rs (any depth)
  path_str.contains("/examples/") || path_str.starts_with("examples/")
}
```

--------------------------------

### Get Rust Target List

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/targets.rs_search=

Retrieves a list of all available Rust target triples from the installed `rustc`. It expects `rustc` to be installed and accessible in the system's PATH. Returns a `Vec<String>` containing the target triples.

```rust
fn get_rust_target_list() -> Result<Vec<String>, Box<dyn std::error::Error>>
```

--------------------------------

### Define Init Subcommand Help and Arguments

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/cli.rs_search=u32+-%3E+bool

Defines the help message and arguments for the 'init' subcommand using clap. This command generates the initial 'rail.toml' configuration file.

```rust
use clap::{Parser, Subcommand};
use std::path::PathBuf;

const INIT_HELP: &str = "...';

// ... (Other struct and enum definitions)

// Assuming Commands enum has an 'Init' variant:
// #[derive(Subcommand)]
// pub enum Commands {
//   Init(InitArgs),
//   // ... other commands
// }

// #[derive(Parser)]
// pub struct InitArgs {
//   /// Generate .config/rail.toml
//   #[arg(long, short)]
//   pub output: Option<PathBuf>,
//
//   /// Preview generated config
//   #[arg(long)]
//   pub check: bool,
// };
```

--------------------------------

### Get Rust Target List in Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/targets.rs_search=std%3A%3Avec

Retrieves the list of all available target triples supported by the installed `rustc`. This function is crucial for knowing which platforms the Rust compiler can build for. It expects `rustc` to be installed and accessible in the system's PATH.

```rust
fn get_rust_target_list() -> Result<Vec<String>, anyhow::Error>
```

--------------------------------

### Define `release` subcommand help text

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/cli.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This snippet defines the help message and examples for the `release` subcommand. It covers initializing release configurations, checking release readiness, previewing release plans, performing releases with different bump types, and skipping the publish step.

```rust
const RELEASE_HELP: &str = "\\
Examples:
  cargo rail release init my-crate              # Configure release for my-crate
  cargo rail release check my-crate             # Validate release readiness
  cargo rail release check my-crate --extended  # Run extended checks (dry-run, MSRV)
  cargo rail release run my-crate --check       # Preview release plan
  cargo rail release run my-crate               # Release (patch bump)
  cargo rail release run my-crate --bump minor
  cargo rail release run my-crate --bump prerelease  # 1.0.0 -> 1.0.0-rc.1
  cargo rail release run my-crate --bump release     # 1.0.0-rc.2 -> 1.0.0
  cargo rail release run --all --bump patch     # Release all crates
  cargo rail release run my-crate --skip-publish  # Tag only, no crates.io";
```

--------------------------------

### Initialize Cargo-Rail Project

Source: https://docs.rs/cargo-rail/latest/cargo_rail/commands/init/fn.run_init_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This endpoint is used to generate the 'rail.toml' configuration file for a new Cargo-Rail project.

```APIDOC
## POST /run_init

### Description
Generates the 'rail.toml' configuration file for a Cargo-Rail project.

### Method
POST

### Endpoint
/run_init

### Parameters
#### Query Parameters
- **output_path** (string) - Required - The path where the rail.toml file will be generated.
- **force** (boolean) - Optional - If true, overwrite the existing rail.toml file if it exists.
- **check** (boolean) - Optional - If true, perform a check without writing the file.
- **json** (boolean) - Optional - If true, output in JSON format.

### Request Body
This endpoint does not require a request body.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful generation or check.

#### Response Example
{
  "message": "rail.toml generated successfully."
}
```

--------------------------------

### Rust: Get metadata of a path with and_then

Source: https://docs.rs/cargo-rail/latest/cargo_rail/error/type.RailResult_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This example shows how to use `and_then` with `Path::metadata` and `modified` to get the modification time of a file or directory. It handles potential errors like the path not existing. The code demonstrates successful retrieval of metadata for the root directory and an error for a non-existent path.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Rust SyncEngine Initialization and Helper Methods

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/sync/engine.rs_search=std%3A%3Avec

Implements the SyncEngine with methods for initialization, ensuring mappings are loaded, and determining the correct branch reference. It utilizes context, configuration, and conflict resolution strategies.

```Rust
/// Bidirectional sync engine
pub struct SyncEngine<'a> {
  /// Workspace context
  ctx: &'a WorkspaceContext,
  /// Sync configuration
  config: SyncConfig,
  /// Commit mapping store
  mapping_store: MappingStore,
  /// Cargo.toml transformer
  transform: CargoTransform,
  /// Conflict resolver
  conflict_resolver: ConflictResolver,
  /// Track which repos we've loaded mappings from (to avoid redundant loads)
  loaded_repos: std::collections::HashSet<PathBuf>,
}

impl<'a> SyncEngine<'a> {
  /// Create a new sync engine
  pub fn new(ctx: &'a WorkspaceContext, config: SyncConfig, conflict_strategy: ConflictStrategy) -> RailResult<Self> {
    let mapping_store = MappingStore::new(config.crate_name.clone());
    let transformer = CargoTransform::new(ctx.cargo.metadata().clone());

    // Create unique temporary directory for conflict resolution (avoid conflicts in parallel tests)
    let temp_dir = std::env::temp_dir().join(format!(
      "cargo-rail-conflicts-{}-வைக் {} - {}",
      config.crate_name,
      std::process::id(),
      std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap_or_else(|_| std::time::Duration::from_secs(0))
        .as_nanos()
    ));
    std::fs::create_dir_all(&temp_dir)?;
    let conflict_resolver = ConflictResolver::new(conflict_strategy, temp_dir);

    Ok(Self {
      ctx,
      config,
      mapping_store,
      transform: transformer,

      conflict_resolver,
      loaded_repos: std::collections::HashSet::new(),
    })
  }

  /// Load mappings from a repo if not already loaded (avoids redundant subprocess calls)
  fn ensure_mappings_loaded(&mut self, repo_path: &Path) -> RailResult<()> {
    if !self.loaded_repos.contains(repo_path) {
      self.mapping_store.load(repo_path)?;
      self.loaded_repos.insert(repo_path.to_path_buf());
    }
    Ok(())
  }

  /// Get the appropriate branch reference (origin/branch for remotes, just branch for local)
  fn get_branch_ref(&self) -> String {
    if utils::is_local_path(&self.config.remote_url) {
      self.config.branch.clone()
    } else {
      format!("origin/{}", self.config.branch)
    }
  }

  /// Sync changes from monorepo to remote repository
  pub fn sync_to_remote(&mut self) -> RailResult<SyncResult> {
    println!("   Syncing monorepo → remote...");

    // Load mappings (cached - only loads if not already loaded)

    self.ensure_mappings_loaded(self.ctx.workspace_root())?;

    // Open remote repo
    let target_repo_path = self.config.target_repo_path.clone();
    let remote_git = SystemGit::open(&target_repo_path)?;

    // Fetch latest from remote (skip for local paths)
    if !utils::is_local_path(&self.config.remote_url) {
      remote_git.fetch_from_remote("origin")?;
      self.mapping_store.fetch_notes(&target_repo_path, "origin")?;
    } else {
      println!("   Skipping fetch (local testing mode)");
    }
  }
}
```

--------------------------------

### Rust: Initialize and Use ConflictResolver

Source: https://docs.rs/cargo-rail/latest/cargo_rail/sync/conflict/struct.ConflictResolver

Demonstrates how to create a new `ConflictResolver` instance with a specified strategy and working directory, and how to resolve conflicts in a single file. It outlines the expected outcomes for successful merges, detected conflicts, and merge failures.

```rust
use cargo_rail::sync::{ConflictResolver, ConflictStrategy, MergeResult, RailResult};
use std::path::Path;
use std::path::PathBuf;

fn main() -> RailResult<()> {
    let strategy = ConflictStrategy::TakeOurs;
    let work_dir = PathBuf::from("./repo");
    let resolver = ConflictResolver::new(strategy, work_dir);

    let current_path = Path::new("file.txt");
    let base_content = b"// Base content\n";
    let incoming_content = b"// Incoming content\n";

    match resolver.resolve_file(current_path, base_content, incoming_content) {
        Ok(MergeResult::Success) => {
            println!("File merged successfully.");
        }
        Ok(MergeResult::Conflicts) => {
            println!("Conflicts detected and marked in file.");
        }
        Err(e) => {
            eprintln!("Merge failed: {:?}", e);
        }
    }

    Ok(())
}

```

--------------------------------

### Rust Test: Get Rust Target List

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/targets.rs_search=

Tests the `get_rust_target_list` function to ensure it can retrieve targets from the `rustc` installation. It checks the approximate number of targets and the presence of common ones.

```rust
#[cfg(test)]
mod tests {
  use super::*;
  use std::fs;
  use tempfile::TempDir;

  #[test]
  fn test_get_rust_target_list() {
    let targets = get_rust_target_list().expect("rustc should be available");

    // Should have many targets (current rustc has ~285)
    assert!(targets.len() > 200, "Expected >200 targets, got {}", targets.len());

    // Should contain common targets
    assert!(targets.contains(&"x86_64-unknown-linux-gnu".to_string()));
    assert!(targets.contains(&"aarch64-apple-darwin".to_string()));
    assert!(targets.contains(&"wasm32-unknown-unknown".to_string()));
  }
}
```

--------------------------------

### Get Rust Target List (Rust)

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/targets.rs

This test function verifies the `get_rust_target_list` function, which retrieves the list of available targets from the installed rustc. It asserts that the list contains a substantial number of targets (expected to be over 200) and includes common target triples. This test assumes that `rustc` is installed and accessible in the system's PATH. Dependencies include `super::*` and `String`.

```Rust
#[test]
fn test_get_rust_target_list() {
  let targets = get_rust_target_list().expect("rustc should be available");

  assert!(targets.len() > 200, "Expected >200 targets, got {}", targets.len());

  assert!(targets.contains(&"x86_64-unknown-linux-gnu".to_string()));
  assert!(targets.contains(&"aarch64-apple-darwin".to_string()));
  assert!(targets.contains(&"wasm32-unknown-unknown".to_string()));
}
```

--------------------------------

### Initialize Cargo Rail Configuration (Rust)

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/init.rs_search=std%3A%3Avec

This Rust function `run_init` is the entry point for the `cargo rail init` command. It orchestrates the process of generating a `rail.toml` configuration file. It uses `run_init_impl` to perform the core logic, which involves detecting workspace settings, building a `RailConfig` object, and writing it to the specified output path. It handles options like forcing overwrites, checking for existing configurations, and JSON output.

```rust
/// Generate rail.toml configuration
pub fn run_init(ctx: &WorkspaceContext, output_path: &str, force: bool, check: bool, json: bool) -> RailResult<()> {
  run_init_impl(ctx.workspace_root(), output_path, force, check, json)
}
```

--------------------------------

### Generate Changelog from Git History

Source: https://docs.rs/cargo-rail/latest/cargo_rail/release/changelog/struct.ChangelogGenerator_search=std%3A%3Avec

Generates a changelog string from the git history of the repository. It allows specifying a starting tag (exclusive) and an ending reference (inclusive), and optionally filtering commits by specific paths for monorepo setups.

```Rust
pub fn generate( &self, from_tag: Option<&str>, to_ref: &str, paths: Option<&[&Path]>, ) -> RailResult<String>
```

--------------------------------

### Get Available Rust Target List

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/targets.rs_search=u32+-%3E+bool

Retrieves a list of all target triples supported by the installed Rust compiler ('rustc'). This function is essential for validating user-provided targets or for discovering all possible compilation targets. It relies on executing the 'rustc --print target-list' command.

```rust
fn get_rust_target_list() -> Result<Vec<String>, RailError> {
  let output = std::process::Command::new("rustc")
    .args(["--print", "target-list"])
    .output()
    .map_err(|_| RailError::message("Failed to execute rustc --print target-list."))?;

  if !output.status.success() {
    return Err(RailError::message(
      "Failed to get target list from rustc. Ensure rustc is installed and in PATH."
    ));
  }

  let stdout = String::from_utf8(output.stdout).unwrap();
  Ok(
    stdout
      .lines()
      .map(|s| s.trim().to_string())
      .filter(|s| !s.is_empty())
      .collect()
  )
}
```

--------------------------------

### run_init Command

Source: https://docs.rs/cargo-rail/latest/cargo_rail/commands/init/fn.run_init_search=std%3A%3Avec

Generates the rail.toml configuration file.

```APIDOC
## run_init

### Description
Generates the rail.toml configuration file.

### Method
Not applicable (function call within the Rust crate).

### Endpoint
Not applicable.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example of calling the function in Rust code:
use cargo_rail::commands::init::run_init;
use cargo_rail::context::WorkspaceContext;

let ctx = WorkspaceContext::new(); // Assuming WorkspaceContext can be initialized like this
let output_path = "./";
let force = false;
let check = false;
let json = false;

match run_init(&ctx, output_path, force, check, json) {
    Ok(_) => println!("Rail configuration generated successfully."),
    Err(e) => eprintln!("Error generating rail configuration: {:?}", e),
}
```

### Response
#### Success Response (200)
Indicates successful generation of the rail.toml file. The function returns `RailResult<()>`, signifying success or failure.

#### Response Example
```json
// No direct JSON response, but successful execution implies file creation.
// On error, a RailResult error type would be returned.
```
```

--------------------------------

### ReleasePlanner Initialization

Source: https://docs.rs/cargo-rail/latest/cargo_rail/release/planner/struct.ReleasePlanner_search=

This section details how to create a new instance of the ReleasePlanner.

```APIDOC
## POST /release/planner/new

### Description
Creates a new release planner instance.

### Method
POST

### Endpoint
/release/planner/new

### Parameters
#### Request Body
- **ctx** (WorkspaceContext) - Required - The workspace context.
- **release_config** (ReleaseConfig) - Required - The release configuration.

### Request Example
```json
{
  "ctx": { ... },
  "release_config": { ... }
}
```

### Response
#### Success Response (200)
- **ReleasePlanner** (object) - The newly created release planner instance.

#### Response Example
```json
{
  "planner_instance": { ... } 
}
```
```

--------------------------------

### Get Git Commits Touching a Specific Path (Rust)

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/git/ops.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a list of commits that have modified a particular file or directory within the Git history. The `get_commits_touching_path` method allows specifying a path, a revision range (optional), and a starting revision. The test verifies that commits are returned and checks their chronological order.

```rust
// Get commits that touched Cargo.toml
let commits = git
  .get_commits_touching_path(Path::new("Cargo.toml"), None, "HEAD")
  .unwrap();

// Cargo.toml should have been modified at least once
assert!(!commits.is_empty(), "Cargo.toml should have commits");

// Verify chronological order (oldest first)
if commits.len() >= 2 {
  assert!(
    commits[0].timestamp <= commits[1].timestamp,
    "Commits should be in chronological order"
  );
}
```

--------------------------------

### Rust: SplitSyncConfigBuilder Initialization and Configuration Methods

Source: https://docs.rs/cargo-rail/latest/cargo_rail/commands/common/struct.SplitSyncConfigBuilder_search=u32+-%3E+bool

Provides methods for initializing and configuring the SplitSyncConfigBuilder. This includes creating a new builder, selecting crates by name or all, overriding remote URLs, and validating configurations.

```rust
pub fn new(ctx: &'a WorkspaceContext) -> RailResult<Self>
pub fn with_crate(self, crate_name: &str) -> RailResult<Self>
pub fn with_all_crates(self) -> Self
pub fn with_crate_or_all( self, crate_name: Option<String>, all: bool, ) -> RailResult<Self>
pub fn with_remote_override(self, remote: Option<String>) -> Self
pub fn validate(self) -> RailResult<Self>
```

--------------------------------

### Get Changed Files between Commits in Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/sync/engine.rs

Retrieves a list of files that have changed between two git commits. This function is crucial for identifying the scope of modifications in a repository. It takes a start commit and an optional end commit (defaults to HEAD) and returns a HashSet of PathBufs representing the modified file paths.

```Rust
let mono_changed_paths: std::collections::HashSet<PathBuf> = if let Some(ref last) = last_synced {
      self
        .ctx
        .git
        .git()
        .get_changed_files_between(last, Some("HEAD"))?
        .into_iter()
        .map(|(path, _)| path)
        .collect()
    } else {
      std::collections::HashSet::new()
    };
```

--------------------------------

### Get Commits from Git Log (Rust)

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/release/changelog.rs_search=

This function retrieves commit information from a Git repository using the `git log` command. It takes optional start and end tags/references, and optional paths to filter commits. It constructs the git command, executes it, parses the output to extract SHA, subject, and body for each commit.

```rust
fn get_commits(
    &self,
    from_tag: Option<&str>,
    to_ref: &str,
    paths: Option<&[&Path]>
  ) -> RailResult<Vec<(String, String, Option<String>)>> {
    let range = if let Some(from) = from_tag {
      format!("{}..{}", from, to_ref)
    } else {
      to_ref.to_string()
    };
    let mut cmd = Command::new("git");
    cmd.current_dir(&self.workspace_root).args([
      "log",
      &range,
      "--format=%H%x00%s%x00%b%x00",
      "--no-merges",
    ]);
    if let Some(paths) = paths
      && !paths.is_empty()
    {
      cmd.arg("--");
      for path in paths {
        cmd.arg(path);
      }
    }
    let output = cmd
      .output()
      .map_err(|e| RailError::message(format!("Failed to execute git log: {}", e)))?;
    if !output.status.success() {
      let stderr = String::from_utf8_lossy(&output.stderr);
      return Err(RailError::message(format!("git log failed: {}", stderr)));
    }
    let log = String::from_utf8_lossy(&output.stdout);
    let mut commits = Vec::new();
    for commit_block in log.split("\0\0") {
      if commit_block.trim().is_empty() {
        continue;
      }
      let mut parts = commit_block.split("\0");
      let sha = parts.next().unwrap_or_default().to_string();
      let subject = parts.next().unwrap_or_default().to_string();
      let body = parts.next().map(String::from);
      commits.push((sha, subject, body));
    }
    Ok(commits)
  }
```

--------------------------------

### Build Configuration with Splits Template in Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/init.rs_search=std%3A%3Avec

Demonstrates building a configuration object using a builder pattern in Rust, specifically utilizing the `splits_template()` method. This snippet is part of a larger process to generate configuration files.

```rust
    .splits_template()
    .build()?;

```

--------------------------------

### Classify Example Files - Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/change_detection/classify.rs_search=std%3A%3Avec

Tests the classification of example files, typically Rust files located in an 'examples' directory. This helps in distinguishing executable examples from other source code.

```Rust
assert_eq!(classify_file(Path::new("examples/demo.rs")), ChangeKind::Example);
    assert_eq!(classify_file(Path::new("crates/foo/examples/demo.rs")), ChangeKind::Example);
    assert_eq!(classify_file(Path::new("foo/bar/examples/demo.rs")), ChangeKind::Example);
```

--------------------------------

### Rust: Create and Use TomlBatchEditor

Source: https://docs.rs/cargo-rail/latest/cargo_rail/toml/editor/struct.TomlBatchEditor_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to create a new TomlBatchEditor, add individual TomlEditors to it, validate all added editors, and finally commit the changes atomically. This ensures all modifications are written or none are, preventing partial updates.

```rust
use cargo_rail::toml::{TomlEditor, TomlBatchEditor};

// Create a new batch editor
let mut batch_editor = TomlBatchEditor::new();

// Assume toml_editor_1 and toml_editor_2 are instances of TomlEditor
// For example, loading from files:
// let toml_editor_1 = TomlEditor::from_path("file1.toml")?;
// let toml_editor_2 = TomlEditor::from_path("file2.toml")?;

// Add editors to the batch
// batch_editor.add(toml_editor_1);
// batch_editor.add(toml_editor_2);

// Validate all editors before committing
// match batch_editor.validate_all() {
//     Ok(_) => {
//         // If validation succeeds, commit the changes
//         match batch_editor.commit() {
//             Ok(_) => println!("All TOML files committed successfully."),
//             Err(e) => eprintln!("Error committing TOML files: {}", e)
//         }
//     },
//     Err(e) => eprintln!("Validation failed for one or more TOML files: {}", e)
// }

```

--------------------------------

### BackupManager Initialization and Basic Operations (Rust)

Source: https://docs.rs/cargo-rail/latest/cargo_rail/backup/struct.BackupManager

Initializes a BackupManager for a given workspace root and provides core functionalities like creating, restoring, listing, and checking for backups. The `create_backup` function takes files, metadata, and a maximum number of backups to retain. `restore_backup` restores a specified backup, and `list_backups` returns all available backup records.

```rust
pub struct BackupManager { /* private fields */ }

impl BackupManager {
    pub fn new(workspace_root: impl Into<PathBuf>) -> Self;
    pub fn create_backup(&self, files: &[PathBuf], metadata: BackupMetadata, max_backups: usize) -> RailResult<BackupId>;
    pub fn restore_backup(&self, backup_id: &str) -> RailResult<()>;
    pub fn list_backups(&self) -> RailResult<Vec<BackupRecord>>;
    pub fn get_latest_backup(&self) -> RailResult<Option<BackupRecord>>;
    pub fn cleanup_old_backups(&self, keep_count: usize) -> RailResult<usize>;
    pub fn has_backups(&self) -> bool;
}
```

--------------------------------

### Get Crate Information with WorkspaceView

Source: https://docs.rs/cargo-rail/latest/cargo_rail/workspace/view/index

This example demonstrates how to instantiate a WorkspaceView and retrieve information about a specific crate by its name. It shows how to access the crate's root path and whether it is a proc-macro. This functionality is useful for tools that need to inspect crate details within a project workspace. No external dependencies beyond the cargo-rail crate itself are implied for this basic usage.

```rust
let view = WorkspaceView::new(&ctx);
if let Some(info) = view.crate_info("my-crate") {
    println!("Path: {}", info.crate_root.display());
    println!("Is proc-macro: {}", info.is_proc_macro);
}
```

--------------------------------

### Test Change Category Logic (Example Changes) in Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/workspace/change_analyzer.rs_search=u32+-%3E+bool

Tests the 'has_example_changes' method of the ChangeCategories struct. It asserts that a category containing an example file is correctly identified as having example changes.

```Rust
@cfg(test)
mod tests {
  use super::*;

  // ... other test functions ...

  #[test]
  fn test_change_categories_example_changes() {
    let mut cat = ChangeCategories::default();
    cat.example_files.push(PathBuf::from("examples/demo.rs"));

    assert!(!cat.is_docs_only());
    assert!(cat.has_example_changes());
  }
}
```

--------------------------------

### POST /run_init

Source: https://docs.rs/cargo-rail/latest/cargo_rail/commands/init/fn.run_init_search=

Generates the rail.toml configuration file for a Cargo-Rail project. Supports options for forcing overwrites, checking existing configurations, and outputting in JSON format.

```APIDOC
## POST /run_init

### Description
Generates the `rail.toml` configuration file for a Cargo-Rail project. This command can be used to initialize a new project with default settings or to regenerate the configuration file.

### Method
POST

### Endpoint
`/run_init`

### Parameters
#### Query Parameters
- **output_path** (string) - Required - The path where the `rail.toml` file should be generated.
- **force** (boolean) - Optional - If true, overwrites the `rail.toml` file if it already exists.
- **check** (boolean) - Optional - If true, performs checks on the existing configuration before generating.
- **json** (boolean) - Optional - If true, outputs the configuration in JSON format instead of TOML.

### Request Body
This endpoint does not require a request body.

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful generation of the `rail.toml` file.

#### Response Example
```json
{
  "message": "rail.toml generated successfully at /path/to/output"
}
```
```

--------------------------------

### Check for Example File Changes in Rust

Source: https://docs.rs/cargo-rail/latest/cargo_rail/workspace/change_analyzer/struct.ChangeCategories

The `has_example_changes` method identifies if any example files within the project have been altered. This helps in determining if the project's examples need to be updated or re-verified.

```Rust
pub fn has_example_changes(&self) -> bool
```

--------------------------------

### MappingStore Initialization and Loading in Rust

Source: https://docs.rs/cargo-rail/latest/cargo_rail/git/mappings/struct.MappingStore_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides functions to create a new MappingStore for a specific crate and to load existing mappings from Git notes within a given repository path. These operations are essential for managing commit associations.

```rust
pub fn new(crate_name: String) -> Self

pub fn load(&mut self, repo_path: &Path) -> RailResult<()>
```

--------------------------------

### Define `split` subcommand help text

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/cli.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This snippet defines the help message and examples for the `split` subcommand. It covers initializing split configurations, previewing generated configurations, and executing the split process for individual or all configured crates.

```rust
const SPLIT_HELP: &str = "\\
Examples:
  cargo rail split init my-crate          # Configure split for my-crate
  cargo rail split init my-crate --check  # Preview generated config
  cargo rail split run my-crate --check   # Preview the split
  cargo rail split run my-crate           # Execute the split
  cargo rail split run --all              # Split all configured crates";
```

--------------------------------

### Test Example File Classification in Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/change_detection/classify.rs

Tests the classification of example files, which typically reside in 'examples/' directories at various levels of the project structure. The `classify_file` function should identify these as 'Example' types.

```rust
#[test]
  fn test_classify_examples() {
    assert_eq!(classify_file(Path::new("examples/demo.rs")), ChangeKind::Example);
    assert_eq!(
      classify_file(Path::new("crates/foo/examples/demo.rs")),
      ChangeKind::Example
    );
    assert_eq!(
      classify_file(Path::new("foo/bar/examples/demo.rs")),
      ChangeKind::Example
    );
  }
```

--------------------------------

### POST /run_release_init

Source: https://docs.rs/cargo-rail/latest/cargo_rail/commands/release/fn.run_release_init_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes the release configuration for the Cargo Rail project. This function sets up the necessary configurations for managing releases.

```APIDOC
## POST /run_release_init

### Description
Initializes the release configuration for the Cargo Rail project. This function sets up the necessary configurations for managing releases.

### Method
POST

### Endpoint
/run_release_init

### Parameters
#### Query Parameters
- **crates** (Option<Vec<String>>) - Optional - A list of crate names to include in the release initialization.
- **check** (bool) - Optional - A flag to indicate if a check should be performed during initialization.

### Request Body
This endpoint does not have a request body.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A message detailing the outcome of the release initialization.

#### Response Example
```json
{
  "status": "success",
  "message": "Release configuration initialized successfully."
}
```
```

--------------------------------

### Rust: Example Searches for Type Signatures

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/graph/core.rs_search=

Provides examples of search queries used to find functions or types based on their signatures. These examples help users locate specific functionalities within the codebase, such as vector operations or type transformations.

```rust
Example searches:
  * std::vec
  * u32 -> bool
  * Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Get File Count for BackupRecord

Source: https://docs.rs/cargo-rail/latest/cargo_rail/backup/struct.BackupRecord

Method to get the number of files associated with a backup record. Returns the count as a usize.

```Rust
pub fn file_count(&self) -> usize
```

--------------------------------

### Implement Initialization Logic (`init.rs`)

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/init.rs

The `run_init_impl` function contains the core logic for initializing the cargo-rail configuration. It handles warnings for non-Cargo workspaces, checks for existing configuration files, and uses detected targets to build the `RailConfig`.

```rust
/// Shared implementation for both run_init and run_init_standalone
fn run_init_impl(workspace_root: &Path, output_path: &str, force: bool, check: bool, json: bool) -> RailResult<()> {
  let config_path = workspace_root.join(output_path);

  // Warn if not a Cargo workspace (skip warnings in quiet/JSON mode)
  if !is_cargo_workspace(workspace_root) && !check && !json && !crate::output::is_quiet() {
    eprintln!("warning: no Cargo workspace detected in {}", workspace_root.display());
    eprintln!("         cargo-rail works best with Cargo workspaces\n");
  }

  // Check if target path already exists
  // In --check mode, we just preview - so existence doesn't matter
  if config_path.exists() && !check {
    if !force {
      return Err(RailError::with_help(
        format!("configuration exists: {}", config_path.display()),
        "use --force to overwrite, or use --check to preview what would be generated",
      ));
    }
    if !json {
      progress!("overwriting: {}", config_path.display());
    }
  } else if let Some(existing) = check_existing_config(workspace_root) {
    // A config exists elsewhere - warn but allow writing to different path
    if !check && !json && !crate::output::is_quiet() {
      eprintln!("note: existing config found at {}", existing.display());
      eprintln!("      (search order: rail.toml, .rail.toml, .cargo/rail.toml, .config/rail.toml)\n");
    }
  }

  let detected_targets = detect_targets(workspace_root);
  let config = build_rail_config(detected_targets.clone());

  let toml_content = RailConfigBuilder::new()
    .header()
    .targets(&config.targets)
    .unify(&config.unify)
    .release(&config.release)

```

--------------------------------

### Rust: TomlBatchEditor Initialization and Default

Source: https://docs.rs/cargo-rail/latest/cargo_rail/toml/editor/struct.TomlBatchEditor_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to create a new TomlBatchEditor using its `new` function and how to obtain a default instance using the `Default` trait implementation. The `default()` function provides a TomlBatchEditor with no editors added.

```rust
use cargo_rail::toml::TomlBatchEditor;

// Create a new instance using the constructor
let mut editor_new = TomlBatchEditor::new();

// Create a new instance using the Default trait
let mut editor_default: TomlBatchEditor = Default::default();

// Both editor_new and editor_default are now empty TomlBatchEditor instances.
```

--------------------------------

### Overwrite Existing Config Example

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/cli.rs_search=

An example demonstrating how to force an overwrite of an existing Cargo Rail configuration file using the `--force` flag.

```bash
cargo rail init --force               # Overwrite existing config
```

--------------------------------

### SyncEngine Initialization and Synchronization

Source: https://docs.rs/cargo-rail/latest/cargo_rail/sync/engine/struct.SyncEngine_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

This section details the methods available for the SyncEngine, including its creation and various synchronization strategies.

```APIDOC
## SyncEngine

### Description
Bidirectional sync engine.

### Methods

#### `new(ctx: &'a WorkspaceContext, config: SyncConfig, conflict_strategy: ConflictStrategy) -> RailResult<Self>`
**Description**: Creates a new sync engine.

#### `sync_to_remote(&mut self) -> RailResult<SyncResult>`
**Description**: Sync changes from monorepo to remote repository.

#### `sync_from_remote(&mut self) -> RailResult<SyncResult>`
**Description**: Sync changes from remote repository to monorepo.

#### `sync_bidirectional(&mut self) -> RailResult<SyncResult>`
**Description**: Sync changes bidirectionally between monorepo and remote.

### Request Body Examples (Illustrative)

`new` method might conceptually use configuration:
```json
{
  "workspace_context": "<context_details>",
  "sync_config": {
    "remote_url": "<url>",
    "branch": "<branch_name>"
  },
  "conflict_strategy": "<strategy>"
}
```

### Response Examples (Illustrative)

```json
{
  "status": "success",
  "changes_applied": 10
}
```

### Error Handling

**`RailResult`**: Indicates potential errors during sync operations. Specific error types would depend on the `RailResult` enum definition.
```

--------------------------------

### Get Rail Configuration from WorkspaceContext in Rust

Source: https://docs.rs/cargo-rail/latest/cargo_rail/workspace/context/struct.WorkspaceContext

The `rail_config` method provides a convenient wrapper to get the `RailConfig` from the `WorkspaceContext`. It relies on `require_config` internally and is suitable for accessing the configuration when its presence is expected.

```rust
pub fn rail_config(&self) -> RailResult<&RailConfig>
```

--------------------------------

### Rust: Initialize and Use WorkspaceDepsBuilder

Source: https://docs.rs/cargo-rail/latest/cargo_rail/toml/builder/struct.WorkspaceDepsBuilder

Demonstrates the creation and basic usage of the WorkspaceDepsBuilder. It shows how to instantiate the builder and add simple dependencies.

```rust
use cargo_rail::toml::builder::WorkspaceDepsBuilder;

// Create a new builder
let mut builder = WorkspaceDepsBuilder::new();

// Add a dependency
builder.add("rand", "0.8.5");

// Add a dependency with a comment
builder.add_with_comment("serde", "1.0", "// For serialization");

// Build the TOML string
let toml_string = builder.build().unwrap();
println!("{}", toml_string);
```

--------------------------------

### Rust: Get Value from TOML Document with TomlEditor

Source: https://docs.rs/cargo-rail/latest/cargo_rail/toml/editor/struct.TomlEditor_search=

Allows retrieving a value from the TOML document at a specified path. The `get` method returns an `Option<&Item>`, providing read-only access to the value.

```Rust
pub fn get(&self, path: &str) -> Option<&Item>
```

--------------------------------

### Rust: Initialize and Use ReleasePlanner

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/release/planner.rs

Demonstrates how to create and utilize the `ReleasePlanner` struct in Rust. The `new` function initializes the planner with workspace context and release configuration, while the `plan` function orchestrates the creation of a `ReleasePlan` by considering specific crates and a version bump type.

```rust
/// Release planner
pub struct ReleasePlanner<'a> {
  /// Workspace context
  ctx: &'a WorkspaceContext,
  /// Release configuration
  release_config: &'a ReleaseConfig,
}

impl<'a> ReleasePlanner<'a> {
  /// Create a new release planner
  pub fn new(ctx: &'a WorkspaceContext, release_config: &'a ReleaseConfig) -> Self {
    Self { ctx, release_config }
  }

  /// Build a release plan
  ///
  /// # Arguments
  /// * `crate_names` - Specific crates to release, or None for all workspace members
  /// * `bump_type` - How to bump versions
  pub fn plan(&self, crate_names: Option<Vec<String>>, bump_type: &BumpType) -> RailResult<ReleasePlan> {
    // Determine which crates to release
    let target_crates = if let Some(names) = crate_names {
      names
    } else {
      self.ctx.graph.workspace_members().to_vec()
    };

    // Get crates in dependency order
    let all_ordered = self.ctx.graph.publish_order()?;
    let ordered_targets: Vec<String> = all_ordered
      .into_iter()
      .filter(|name| target_crates.contains(name))
      .collect();

    // Build plan for each crate
    let mut crate_plans = Vec::new();
    let mut version_map: HashMap<String, Version> = HashMap::new();

    for crate_name in &ordered_targets {
      let plan = self.plan_crate(crate_name, bump_type, &version_map)?;
      version_map.insert(crate_name.clone(), plan.new_version.clone());
      crate_plans.push(plan);
    }

    // Build summary
    let crates_to_publish = crate_plans.iter().filter(|p| p.publish).count();
    let summary = ReleaseSummary {
      total_crates: crate_plans.len(),
      crates_to_publish,
      crates_to_tag: crate_plans.len(),
    };

    Ok(ReleasePlan {
      crates: crate_plans,
      summary,
    })
  }

  /// Plan release for a single crate
  fn plan_crate(
    &self,
    crate_name: &str,
    bump_type: &BumpType,
    _version_map: &HashMap<String, Version>,
  ) -> RailResult<CrateReleasePlan> {
    // Get crate metadata
    let package = self
      .ctx
      .cargo
      .get_package(crate_name)
      .ok_or_else(|| RailError::message(format!("Crate '{}' not found", crate_name)))?;

    let manifest_path = package.manifest_path.clone().into_std_path_buf();

    // Get current version from cargo_metadata (already resolves workspace inheritance)
    let current_version = package.version.clone();

    // Calculate new version
    let new_version = bump_type.apply(&current_version);

    // Determine tag name
    let tag_name = self.format_tag(crate_name, &new_version);

    // Get per-crate config (if any)
    let crate_config = self.ctx.config.as_ref().and_then(|c| c.crates.get(crate_name));

    // Get changelog path - check per-crate config first, then fall back to global
    let changelog_relative_path = crate_config
      .and_then(|c| c.changelog.as_ref())
      .and_then(|ch| ch.path.as_ref())
      .map(|p| p.to_string_lossy().to_string())
      .unwrap_or_else(|| self.release_config.changelog_path.clone());

    // Resolve the path based on changelog_relative_to setting
    // ... (implementation continues)
    unimplemented!()
  }

  // Placeholder for format_tag method
  fn format_tag(&self, _crate_name: &str, _version: &Version) -> String {
    "some-tag".to_string()
  }
}
```

--------------------------------

### Test Change Categories: Example Changes (Rust)

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/workspace/change_analyzer.rs_search=std%3A%3Avec

Tests the `ChangeCategories::has_example_changes()` method. A `ChangeCategories` object is created with an example file, and it's asserted that `has_example_changes()` is true, while `is_docs_only()` is false.

```rust
#[test]
  fn test_change_categories_example_changes() {
    let mut cat = ChangeCategories::default();
    cat.example_files.push(PathBuf::from("examples/demo.rs"));

    assert!(!cat.is_docs_only());
    assert!(cat.has_example_changes());
  }
```

--------------------------------

### Test Example Changes in Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/workspace/change_analyzer.rs_search=

This test checks the 'has_example_changes' method of the ChangeCategories struct. It asserts that if example files are included in the category, the method returns true, and 'is_docs_only' returns false.

```rust
  #[test]
  fn test_change_categories_example_changes() {
    let mut cat = ChangeCategories::default();
    cat.example_files.push(PathBuf::from("examples/demo.rs"));

    assert!(!cat.is_docs_only());
    assert!(cat.has_example_changes());
  }

```

--------------------------------

### Configuration Loading

Source: https://docs.rs/cargo-rail/latest/cargo_rail/config/index_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Explains the process and search order for loading cargo-rail configuration files.

```APIDOC
## Configuration Loading

### Description
This section details how cargo-rail loads its configuration. It outlines the search order for configuration files and the primary configuration structure.

### Method
N/A (Configuration loading is typically part of the application's startup process)

### Endpoint
N/A

### Parameters
N/A

### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **`RailConfig`** (struct) - The main configuration struct loaded from a configuration file.
- **`ConfigLoadResult`** (enum) - The result of the configuration loading attempt.

#### Response Example
```json
{
  "loaded_config": {
    "unify": {
      "mode": "Major" 
    },
    "release": {
      "version_strategy": "default"
    }
  },
  "load_result": "Success"
}
```

### Configuration File Search Order
Configuration files are searched in the following order:
1. `rail.toml`
2. `.rail.toml`
3. `.cargo/rail.toml`
4. `.config/rail.toml`
```

--------------------------------

### SystemGit Initialization

Source: https://docs.rs/cargo-rail/latest/cargo_rail/git/system/struct.SystemGit_search=

Opens a Git repository at the specified path.

```APIDOC
## POST /git/system/open

### Description
Opens a Git repository at the specified path.
This performs ONE subprocess call to get the repository metadata.

### Method
POST

### Endpoint
/git/system/open

### Parameters
#### Query Parameters
- **path** (Path) - Required - The path to the Git repository.

### Request Example
```json
{
  "path": "/path/to/your/repo"
}
```

### Response
#### Success Response (200)
- **SystemGit** (object) - An instance of the SystemGit object representing the opened repository.

#### Response Example
```json
{
  "message": "Repository opened successfully"
}
```
```

--------------------------------

### MappingStore Get Size Function (Test Only) - Rust

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/git/mappings.rs_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Implements a function to get the number of mappings in the `MappingStore`, conditionally compiled for testing. This is useful for assertions and verifying the state of the store during test execution.

```rust
/// Get the number of mappings (only used in tests)
  #[cfg(test)]
  pub fn len(&self) -> usize {
    self.mappings.len()
  }
```

--------------------------------

### Build TOML Configuration with Builder Pattern

Source: https://docs.rs/cargo-rail/latest/src/cargo_rail/commands/init.rs_search=u32+-%3E+bool

This snippet demonstrates how to build a TOML configuration using the `RailConfigBuilder`. It utilizes the `.splits_template()` method and `.build()` to generate the TOML string. The assertions check for the presence of section headers and comments, indicating a correctly formatted configuration.

```Rust
let config = RailConfig {
  targets: vec![],
  unify: UnifyConfig::default(),
  release: ReleaseConfig::default(),
  change_detection: crate::config::ChangeDetectionConfig::default(),
  crates: Default::default(),
};

let toml = RailConfigBuilder::new()
  .header()
  .targets(&config.targets)
  .unify(&config.unify)
  .release(&config.release)
  .splits_template()
  .build()
  .unwrap();

// Should contain section headers
assert!(toml.contains("[unify]"));

// Should contain helpful comments
assert!(toml.contains("cargo-rail configuration"));
assert!(toml.contains("Documentation:"));
```

--------------------------------

### Rust String Concatenation Example

Source: https://docs.rs/cargo-rail/latest/cargo_rail/backup/type.BackupId_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to concatenate two `String`s using the `+` operator. The first example shows consuming the left `String`, while the second shows cloning it to preserve the original. It also shows concatenating string slices by converting the first to a `String`.

```rust
let a = String::from("hello");
let b = String::from(" world");
let c = a + &b;

let a = String::from("hello");
let b = String::from(" world");
let c = a.clone() + &b;

let a = "hello";
let b = " world";
let c = a.to_string() + b;
```
Tokens:
Raw