diff --git a/plan.md b/plan.md deleted file mode 100644 index 49e553f..0000000 --- a/plan.md +++ /dev/null @@ -1,234 +0,0 @@ -## 🦀 Engineering Plan: `rust-testscript` Crate - -### **1. Project Vision & Core Principles** - -The goal is to create `rust-testscript`, a crate for testing command-line tools using filesystem-based script files, mirroring the functionality and developer experience of Go's `rogpeppe/go-internal/testscript`. - - * **Idiomatic Rust:** The library must feel natural to Rust developers. This means using `Result` for error handling, leveraging iterators, employing the builder pattern for configuration, and using traits for extensibility. - * **Modularity:** Components like the parser, environment manager, and command executor should be distinct and testable in isolation. - * **Extensibility:** Users must be able to easily define their own custom commands and conditions, just like in the Go version. - * **Minimal Dependencies:** We will rely on well-vetted, popular crates where necessary (e.g., for temp files, command execution) but avoid unnecessary bloat. - -### **2. High-Level Architecture** - -The library will consist of several key components that work together: - -1. **Test Runner:** The main entry point for the user. It discovers test script files and orchestrates their execution. -2. **Script Parser:** Responsible for parsing the `.txtar` format into a structured representation of commands and files. -3. **Execution Environment:** Manages the temporary, isolated directory for each test script run, including file setup and environment variables. -4. **Command Engine:** A dispatcher that interprets and executes parsed commands (e.g., `exec`, `cmp`, `stdout`) against the execution environment. -5. **Configuration (`RunParams`):** A builder struct that allows users to customize the test run, such as by adding custom commands or setup logic. - ------ - -### **3. Phase 1: The Core Engine (MVP)** - -This phase focuses on building the non-extensible core functionality. The goal is to successfully parse and run a basic test script with built-in commands. - -#### **Task 3.1: Project Scaffolding** - - * Initialize a new Rust library crate: `cargo new --lib rust-testscript`. - * Set up the initial `Cargo.toml` with metadata (authors, license, description). - * Add initial dependencies: - * `anyhow` for simple, flexible error handling. - * `thiserror` for creating custom, structured error types. - * `tempfile` for creating isolated temporary directories for test runs. - * `walkdir` for discovering test script files. - -#### **Task 3.2: Implement the `txtar` Parser** - - * Create a new module: `mod parser;`. - * **Data Structures:** Define structs to represent the parsed script. - ```rust - // Represents a single file block in the archive - pub struct TxtarFile { - pub name: String, - pub contents: Vec, - } - - // Represents the parsed script and its associated files - pub struct Script { - pub commands: Vec, - pub files: Vec, - } - - // Represents a single command line in the script - pub struct Command { - pub name: String, - pub args: Vec, - pub line_num: usize, - } - ``` - * **Parsing Logic:** Implement a function `parser::parse(content: &str) -> Result