|
| 1 | +# Cargo Tool |
| 2 | + |
| 3 | +A comprehensive Cargo validation and transformation tool for the Rhema Action Protocol. This tool provides extensive Rust project management capabilities including compilation checking, testing, linting, formatting, and dependency analysis. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +### Validation Commands |
| 8 | +- **`check`**: Compile without producing executables (fastest) |
| 9 | +- **`build`**: Full compilation with executable generation |
| 10 | +- **`test`**: Run all tests in the project |
| 11 | +- **`clippy`**: Run Clippy linter for additional checks |
| 12 | +- **`audit`**: Security vulnerability scanning |
| 13 | +- **`outdated`**: Check for outdated dependencies |
| 14 | + |
| 15 | +### Transformation Commands |
| 16 | +- **`fmt`**: Code formatting using rustfmt |
| 17 | +- **`clippy --fix`**: Auto-fix Clippy suggestions |
| 18 | + |
| 19 | +### Advanced Features |
| 20 | +- **JSON Output Parsing**: Structured error and warning reporting |
| 21 | +- **Parallel Execution**: Run commands in parallel for better performance |
| 22 | +- **Configurable Output**: Toggle between JSON and human-readable output |
| 23 | +- **Verbose Logging**: Detailed operation logging |
| 24 | +- **Error Categorization**: Separate error and warning handling |
| 25 | +- **File Location Tracking**: Precise error location reporting |
| 26 | +- **Workspace Support**: Multi-crate workspace handling with flexible execution modes |
| 27 | + |
| 28 | +## Usage |
| 29 | + |
| 30 | +### Basic Validation |
| 31 | + |
| 32 | +```rust |
| 33 | +use rhema_action_tool::{ActionIntent, ActionType, SafetyLevel}; |
| 34 | +use rhema_action_cargo::CargoTool; |
| 35 | + |
| 36 | +let intent = ActionIntent { |
| 37 | + id: "basic-check".to_string(), |
| 38 | + action_type: ActionType::Validation, |
| 39 | + scope: vec!["Cargo.toml".to_string()], |
| 40 | + metadata: None, |
| 41 | + safety_level: SafetyLevel::Low, |
| 42 | +}; |
| 43 | + |
| 44 | +let cargo_tool = CargoTool; |
| 45 | +let result = cargo_tool.validate(&intent).await?; |
| 46 | +``` |
| 47 | + |
| 48 | +### Comprehensive Validation |
| 49 | + |
| 50 | +```rust |
| 51 | +use serde_json::json; |
| 52 | + |
| 53 | +let intent = ActionIntent { |
| 54 | + id: "comprehensive".to_string(), |
| 55 | + action_type: ActionType::Validation, |
| 56 | + scope: vec!["Cargo.toml".to_string()], |
| 57 | + metadata: Some(json!({ |
| 58 | + "commands": ["check", "clippy", "test", "audit"], |
| 59 | + "json_output": true, |
| 60 | + "verbose": true |
| 61 | + })), |
| 62 | + safety_level: SafetyLevel::Medium, |
| 63 | +}; |
| 64 | +``` |
| 65 | + |
| 66 | +### Code Transformation |
| 67 | + |
| 68 | +```rust |
| 69 | +let intent = ActionIntent { |
| 70 | + id: "format-code".to_string(), |
| 71 | + action_type: ActionType::Transformation, |
| 72 | + scope: vec!["Cargo.toml".to_string()], |
| 73 | + metadata: Some(json!({ |
| 74 | + "commands": ["fmt", "clippy"], |
| 75 | + "json_output": true |
| 76 | + })), |
| 77 | + safety_level: SafetyLevel::Medium, |
| 78 | +}; |
| 79 | + |
| 80 | +let result = cargo_tool.execute(&intent).await?; |
| 81 | +``` |
| 82 | + |
| 83 | +### Workspace Support |
| 84 | + |
| 85 | +```rust |
| 86 | +// Execute on all workspace members |
| 87 | +let mut workspace_intent = ActionIntent::new( |
| 88 | + "workspace-validation", |
| 89 | + ActionType::Test, |
| 90 | + "Validate workspace", |
| 91 | + vec!["Cargo.toml".to_string()], |
| 92 | + SafetyLevel::Medium, |
| 93 | +); |
| 94 | +workspace_intent.metadata = json!({ |
| 95 | + "commands": ["check", "clippy", "test"], |
| 96 | + "workspace_mode": "all_members", |
| 97 | + "json_output": true, |
| 98 | + "verbose": false |
| 99 | +}); |
| 100 | + |
| 101 | +let result = cargo_tool.validate(&workspace_intent).await?; |
| 102 | +``` |
| 103 | + |
| 104 | +## Configuration |
| 105 | + |
| 106 | +The tool accepts configuration through the `metadata` field of `ActionIntent`: |
| 107 | + |
| 108 | +### Available Options |
| 109 | + |
| 110 | +- **`commands`**: Array of command strings to execute |
| 111 | + - `"check"` - Cargo check |
| 112 | + - `"build"` - Cargo build |
| 113 | + - `"test"` - Cargo test |
| 114 | + - `"clippy"` - Cargo clippy |
| 115 | + - `"fmt"` - Cargo fmt |
| 116 | + - `"audit"` - Cargo audit |
| 117 | + - `"outdated"` - Cargo outdated |
| 118 | + |
| 119 | +- **`parallel`**: Boolean (default: `true`) |
| 120 | + - Enable parallel execution of commands |
| 121 | + |
| 122 | +- **`json_output`**: Boolean (default: `true`) |
| 123 | + - Use JSON output format for better parsing |
| 124 | + |
| 125 | +- **`verbose`**: Boolean (default: `false`) |
| 126 | + - Enable verbose logging |
| 127 | + |
| 128 | +- **`workspace_mode`**: String (default: `"root_and_members"`) |
| 129 | + - `"root_only"` - Execute on workspace root only |
| 130 | + - `"all_members"` - Execute on all workspace members |
| 131 | + - `"root_and_members"` - Execute on workspace root and all members |
| 132 | + - `"selected_members"` - Execute only on specified members |
| 133 | + |
| 134 | +- **`member_filter`**: Array of strings (optional) |
| 135 | + - List of member names to include when using `selected_members` mode |
| 136 | + |
| 137 | +- **`exclude_members`**: Array of strings (optional) |
| 138 | + - List of member names to exclude from execution |
| 139 | + |
| 140 | +### Default Configuration |
| 141 | + |
| 142 | +```json |
| 143 | +{ |
| 144 | + "commands": ["check"], |
| 145 | + "parallel": true, |
| 146 | + "json_output": true, |
| 147 | + "verbose": false, |
| 148 | + "workspace_mode": "root_and_members" |
| 149 | +} |
| 150 | +``` |
| 151 | + |
| 152 | +## Output Format |
| 153 | + |
| 154 | +### ToolResult Structure |
| 155 | + |
| 156 | +```rust |
| 157 | +pub struct ToolResult { |
| 158 | + pub success: bool, // Overall success status |
| 159 | + pub changes: Vec<String>, // Applied changes |
| 160 | + pub output: String, // General output message |
| 161 | + pub errors: Vec<String>, // Error messages with locations |
| 162 | + pub warnings: Vec<String>, // Warning messages |
| 163 | + pub duration: Duration, // Execution time |
| 164 | +} |
| 165 | +``` |
| 166 | + |
| 167 | +### Error Format |
| 168 | + |
| 169 | +Errors include file locations and line numbers when available: |
| 170 | +``` |
| 171 | +src/main.rs:15: expected `;`, found `}` |
| 172 | +``` |
| 173 | + |
| 174 | +## Examples |
| 175 | + |
| 176 | +See `examples/enhanced_cargo_example.rs` for comprehensive usage examples. |
| 177 | + |
| 178 | +See `examples/workspace_example.rs` for workspace-specific examples. |
| 179 | + |
| 180 | +## Dependencies |
| 181 | + |
| 182 | +- `async-trait`: Async trait support |
| 183 | +- `tokio`: Async runtime |
| 184 | +- `tracing`: Logging framework |
| 185 | +- `serde_json`: JSON parsing |
| 186 | +- `rhema-action-tool`: Core action tool traits |
| 187 | + |
| 188 | +## Safety Levels |
| 189 | + |
| 190 | +- **Low**: Basic validation commands (check, outdated) |
| 191 | +- **Medium**: Transformation commands (fmt, clippy) |
| 192 | +- **High**: Build and test commands (build, test) |
| 193 | + |
| 194 | +## Error Handling |
| 195 | + |
| 196 | +The tool provides comprehensive error handling: |
| 197 | + |
| 198 | +1. **Tool Execution Errors**: Cargo command failures |
| 199 | +2. **Validation Errors**: Invalid configurations or file paths |
| 200 | +3. **Parsing Errors**: JSON output parsing failures |
| 201 | +4. **Availability Errors**: Cargo not installed or accessible |
| 202 | + |
| 203 | +## Performance Considerations |
| 204 | + |
| 205 | +- **Parallel Execution**: Commands run in parallel by default |
| 206 | +- **JSON Output**: Faster parsing than text output |
| 207 | +- **Incremental Compilation**: Leverages Cargo's built-in caching |
| 208 | +- **Selective Commands**: Only run necessary commands |
| 209 | + |
| 210 | +## Integration |
| 211 | + |
| 212 | +The cargo tool integrates seamlessly with the Rhema Action Protocol: |
| 213 | + |
| 214 | +- **Validation Tool**: For checking code quality and correctness |
| 215 | +- **Transformation Tool**: For automatic code improvements |
| 216 | +- **Safety Tool**: For security and dependency analysis |
| 217 | + |
| 218 | +## Future Enhancements |
| 219 | + |
| 220 | +Planned improvements include: |
| 221 | + |
| 222 | +- **Cross-compilation**: Target-specific builds |
| 223 | +- **Feature Flags**: Conditional compilation support |
| 224 | +- **Profile Support**: Debug/release profile handling |
| 225 | +- **Metrics Collection**: Compilation time and size tracking |
| 226 | +- **Dependency Graph**: Visual dependency analysis |
| 227 | +- **Advanced Workspace Features**: Workspace dependency resolution, member ordering |
0 commit comments