# Rash - Bidirectional Shell Safety Tool
[](https://crates.io/crates/bashrs)
[](https://docs.rs/bashrs)
[](https://paiml.github.io/bashrs/)
[](LICENSE)
[](https://github.com/paiml/bashrs/actions)
[](https://github.com/paiml/bashrs/actions)
[](https://github.com/paiml/bashrs/blob/main/rash/src/testing/)
[](https://github.com/paiml/bashrs/actions)
[](https://github.com/paiml/bashrs)
**Rash** is a bidirectional shell safety tool that lets you write shell scripts in REAL Rust and automatically purify legacy bash scripts.
## Why Rash?
- 🛡️ **Safety First**: Automatic protection against shell injection attacks
- 🔍 **Compile-Time Verification**: Catch errors before deployment
- 📦 **Zero Runtime Dependencies**: Generated scripts work on any POSIX shell
- 🎯 **Deterministic Output**: Same input always produces identical scripts
- ✅ **ShellCheck Compliant**: All output passes strict linting
## How Rash Exceeds ShellCheck
ShellCheck is an excellent linter that **detects** problems in shell scripts.
Rash goes **far beyond** by understanding the full AST and **automatically transforming** code to fix issues.
| ⚠️ **Warns**: "$RANDOM is non-deterministic" | ✅ **Rewrites** to version-based deterministic IDs |
| ⚠️ **Warns**: "mkdir may fail if exists" | ✅ **Transforms** to `mkdir -p` (idempotent) |
| ⚠️ **Warns**: "Unquoted variable expansion" | ✅ **Quotes** all variables automatically |
| ⚠️ **Warns**: "Timestamp in $(date +%s)" | ✅ **Replaces** with fixed version tags |
| ⚠️ **Warns**: "rm may fail if doesn't exist" | ✅ **Adds** `-f` flag for safe removal |
| Static pattern matching | **Full AST semantic understanding** |
| Detects issues (read-only) | **Fixes issues (read-write transformation)** |
### Example: Non-Deterministic Deployment Script
**Input (Messy Bash)**:
```bash
#!/bin/bash
SESSION_ID=$RANDOM # Non-deterministic
RELEASE="release-$(date +%s)" # Timestamp-based
mkdir /app/releases/$RELEASE # Non-idempotent
rm /app/current # Fails if doesn't exist
ln -s /app/releases/$RELEASE /app/current
```
**ShellCheck Output** (manual fixes required):
```
⚠️ SC2086: Quote variable to prevent word splitting
⚠️ $RANDOM is non-deterministic (YOU must fix manually)
⚠️ mkdir may fail if directory exists (YOU must add -p flag)
⚠️ rm may fail if doesn't exist (YOU must add -f flag)
```
**Rash Output** (automatically purified):
```bash
#!/bin/sh
# ✅ Automatically fixed by Rash - no manual work needed
deploy_app() {
_version="$1"
session_id="session-${_version}" # ✅ Deterministic
release="release-${_version}" # ✅ Version-based (not timestamp)
mkdir -p "/app/releases/${release}" # ✅ Idempotent
rm -f "/app/current" # ✅ Safe removal
ln -sf "/app/releases/${release}" "/app/current" # ✅ Idempotent symlink
}
```
**Key Difference**: ShellCheck tells you what's wrong. Rash **understands your code's intent** and rewrites it to be safe, deterministic, and idempotent — automatically.
This is only possible because Rash parses shell scripts into a full Abstract Syntax Tree (AST), understands the semantic meaning of each construct, and can perform intelligent transformations that preserve functionality while eliminating entire classes of bugs.
---
## How Rash Works: Two Workflows
Rash operates in **two directions** to maximize shell script safety:
### 🚀 PRIMARY: Rust → Safe Shell (Production-Ready)
**Write new scripts in REAL Rust, transpile to provably safe shell.**
```
Rust Code (.rs) → cargo test → Transpile → Safe POSIX Shell
↑ Test FIRST with Rust tooling
```
**Use cases**:
- Bootstrap installers (Node.js, Rust toolchain, etc.)
- CI/CD deployment scripts
- System configuration tools
- Any new shell automation
**Benefits**:
- Full Rust std library support
- Test with `cargo test`, lint with `cargo clippy`
- Property-based testing with proptest
- 100% deterministic, idempotent output
### 🔄 SECONDARY: Bash → Rust → Purified Bash (Legacy Cleanup)
**Ingest messy bash, convert to Rust with tests, output purified shell.**
```
Messy Bash → Parser → Rust + Tests → Transpile → Purified Bash
↑ Tests auto-generated
```
**Use cases**:
- Clean up legacy bash scripts
- Remove non-deterministic constructs ($RANDOM, timestamps, $$)
- Enforce idempotency (mkdir -p, rm -f)
- Generate comprehensive test suites
**Benefits**:
- Automatic test generation
- Remove unsafe patterns
- Maintain shell compatibility
- Preserve functionality while improving safety
See [`examples/PURIFICATION_WORKFLOW.md`](examples/PURIFICATION_WORKFLOW.md) for detailed purification examples.
---
## Quick Start (PRIMARY Workflow)
Write Rust:
```rust
// install.rs
#[rash::main]
fn main() {
let version = env_var_or("VERSION", "1.0.0");
let prefix = env_var_or("PREFIX", "/usr/local");
echo("Installing MyApp {version} to {prefix}");
// Create installation directories
mkdir_p("{prefix}/bin");
mkdir_p("{prefix}/share/myapp");
// Copy files (with automatic quoting)
if exec("cp myapp {prefix}/bin/") {
echo("✓ Binary installed");
} else {
echo("✗ Failed to install binary");
exit(1);
}
}
```
Get POSIX shell:
```bash
$ bashrs build install.rs -o install.sh
$ cat install.sh
#!/bin/sh
# Generated by Rash v0.4.0
# POSIX-compliant shell script
set -euf
IFS='
'
export LC_ALL=C
# Rash runtime functions
rash_require() {
if ! "$@"; then
echo "FATAL: Requirement failed: $*" >&2
exit 1
fi
}
# Main script begins
main() {
VERSION="${VERSION:-1.0.0}"
PREFIX="${PREFIX:-/usr/local}"
echo "Installing MyApp $VERSION to $PREFIX"
mkdir -p "$PREFIX/bin"
mkdir -p "$PREFIX/share/myapp"
if cp myapp "$PREFIX/bin/"; then
echo "✓ Binary installed"
else
echo "✗ Failed to install binary"
exit 1
fi
}
# Execute main function
main "$@"
```
## Installation
### From crates.io (Recommended)
```bash
# Install latest release candidate
cargo install bashrs --version 1.0.0-rc1
# Or install latest stable
cargo install bashrs
```
### Binary Releases
Pre-built binaries are available for Linux and macOS:
```bash
# Linux x86_64
curl -L https://github.com/paiml/bashrs/releases/latest/download/bashrs-x86_64-unknown-linux-musl.tar.gz | tar xz
# macOS x86_64
curl -L https://github.com/paiml/bashrs/releases/latest/download/bashrs-x86_64-apple-darwin.tar.gz | tar xz
# macOS ARM64
### Using cargo-binstall
```bash
cargo binstall bashrs
```
### From Source
```bash
# Full build with all features
cargo install --git https://github.com/paiml/bashrs
# Minimal build (smaller binary, ~2MB)
cargo install --git https://github.com/paiml/bashrs --no-default-features --features minimal
```
## Usage
### Basic Commands
```bash
# Transpile a Rust file to shell
bashrs build input.rs -o output.sh
# Check if a file is valid Rash
bashrs check input.rs
# Initialize a new Rash project
bashrs init my-project
# Verify safety properties
bashrs verify input.rs output.sh
# Inspect AST and safety properties
bashrs inspect input.rs
# Lint shell scripts for safety issues (NEW in v1.1)
bashrs lint script.sh
# Compile to self-extracting script (BETA)
bashrs compile input.rs -o install --self-extracting
```
### Native Linter (NEW in v1.1) 🔍
bashrs includes a **native linter** that validates shell scripts for safety issues, with zero external dependencies:
```bash
# Lint a shell script (human-readable output)
$ bashrs lint unsafe.sh
⚠ 8:3-9 [warning] SC2086: Double quote to prevent globbing and word splitting on $FILES
Fix: "$FILES"
⚠ 12:7-30 [warning] SC2046: Quote this to prevent word splitting: $(find . -name '*.txt')
Fix: "$(find . -name '*.txt')"
ℹ 16:9-24 [info] SC2116: Useless echo; just use $result directly
Fix: $result
Summary: 0 error(s), 5 warning(s), 1 info(s)
# JSON format for CI/CD integration
$ bashrs lint script.sh --format=json
{
"file": "script.sh",
"diagnostics": [
{
"code": "SC2086",
"severity": "warning",
"message": "Double quote to prevent globbing and word splitting",
"span": { "start_line": 8, "start_col": 3, "end_line": 8, "end_col": 9 },
"fix": "\"$FILES\""
}
],
"summary": { "errors": 0, "warnings": 5, "infos": 1 }
}
# SARIF format for security scanners
$ bashrs lint script.sh --format=sarif
```
**Linter Features**:
- ✅ **Zero external dependencies** - No ShellCheck installation required
- ✅ **3 output formats** - Human, JSON, SARIF for CI/CD integration
- ✅ **Auto-fix** (NEW in v1.2) - Automatically apply fixes with `--fix` flag
- ✅ **Smart detection** - Context-aware to prevent false positives
- ✅ **ShellCheck parity** - Implements critical SC-series rules
**Auto-Fix** (NEW in v1.2):
```bash
# Apply fixes automatically (creates backup)
$ bashrs lint script.sh --fix
[INFO] Applied 6 fix(es) to script.sh
[INFO] Backup created at script.sh.bak
✓ All issues fixed!
```
Before:
```bash
DIR=/tmp/mydir
mkdir $DIR
FILES=$(ls *.txt)
```
After:
```bash
DIR=/tmp/mydir
mkdir "$DIR"
FILES="$(ls *.txt)"
```
**Rules Implemented** (v1.1):
- **SC2086**: Unquoted variable expansion (prevents word splitting & glob expansion)
- **SC2046**: Unquoted command substitution
- **SC2116**: Useless echo in command substitution
**Exit Codes**:
- `0` - No issues found
- `1` - Warnings detected
- `2` - Errors detected
**Comparison: bashrs vs ShellCheck**:
| **Core Capability** | Static pattern detection | **Full AST parsing + transformation** |
| **Output** | Warnings only | **Automatically fixed code** |
| Installation | External binary required | Built-in, zero dependencies |
| Output formats | checkstyle, gcc, json | human, JSON, SARIF |
| Auto-fix | ❌ No | ✅ Yes - automatic code transformation |
| **Determinism** | Warns about $RANDOM | **Replaces with deterministic constructs** |
| **Idempotency** | Warns about mkdir | **Transforms to mkdir -p** |
| Semantic understanding | Pattern matching only | **Full AST semantic analysis** |
| Code transformation | ❌ Read-only | ✅ **Read-write (purification)** |
| Performance | ~50ms | <2ms (native Rust) |
See the [Safety Comparison Guide](docs/SAFETY_COMPARISON.md) for detailed vulnerability prevention examples.
### CLI Options
```bash
USAGE:
bashrs [OPTIONS] <COMMAND>
COMMANDS:
build Transpile Rust to shell script
check Validate Rust source without transpiling
init Initialize a new Rash project
verify Verify shell script matches source
inspect Analyze AST and safety properties
lint Lint shell scripts for safety issues (NEW in v1.1)
compile Compile to standalone binary (BETA - experimental)
OPTIONS:
-v, --verbose Enable verbose output
-V, --version Print version information
-h, --help Print help information
--target <SHELL> Target shell: posix, bash, ash (default: posix)
--verify <LEVEL> Verification level: none, basic, strict, paranoid
--validation <LEVEL> Validation level: none, minimal, strict, paranoid
BUILD OPTIONS:
-o, --output <FILE> Output file (default: stdout)
--optimize Enable optimization passes
--strict Enable strict mode checks
--emit-proof Emit verification proof alongside output
```
## Documentation
### 📚 The Rash Book
**Comprehensive guide with tested examples**: [https://paiml.github.io/bashrs/](https://paiml.github.io/bashrs/)
The Rash Book is the official, comprehensive documentation for Rash. All code examples in the book are automatically tested, ensuring they stay up-to-date with the code.
**What's in the book:**
- **Getting Started**: Installation, quick start, your first purification
- **Core Concepts**: Determinism, idempotency, POSIX compliance
- **Shell Script Linting**: Security, determinism, and idempotency rules
- **Configuration Management**: Purifying .bashrc and .zshrc files (CONFIG-001, CONFIG-002)
- **Makefile Linting**: Security and best practices
- **Real-World Examples**: Bootstrap installers, deployment scripts, CI/CD
- **Advanced Topics**: AST transformation, property testing, mutation testing
- **Reference**: CLI commands, configuration, exit codes, rules reference
**Why the book is special:**
- ✅ All examples are tested automatically (TDD)
- ✅ Cannot release without updating the book
- ✅ Enforced quality through pre-release checks
- ✅ Toyota Way principles applied to documentation
### API Documentation
Rust API documentation is available on [docs.rs/bashrs](https://docs.rs/bashrs).
### Quick Links
- [Installation Guide](https://paiml.github.io/bashrs/getting-started/installation.html)
- [Quick Start](https://paiml.github.io/bashrs/getting-started/quick-start.html)
- [CONFIG-001: PATH Deduplication](https://paiml.github.io/bashrs/config/rules/config-001.html)
- [CONFIG-002: Quote Variables](https://paiml.github.io/bashrs/config/rules/config-002.html)
- [Security Rules](https://paiml.github.io/bashrs/linting/security.html)
- [Contributing Guide](https://paiml.github.io/bashrs/contributing/setup.html)
## Language Features
### Supported Rust Subset
Rash supports a carefully chosen subset of Rust that maps cleanly to shell:
#### Variables and Types
```rust
let name = "Alice"; // String literals
let count = 42; // Integers (including negatives: -42)
let flag = true; // Booleans
let user = env("USER"); // Environment variables
let result = capture("date"); // Command output
```
#### Arithmetic Operations
```rust
let x = 1 + 2; // Addition → $((1 + 2))
let y = 10 - 3; // Subtraction → $((10 - 3))
let z = 4 * 5; // Multiplication → $((4 * 5))
let w = 20 / 4; // Division → $((20 / 4))
```
#### Comparison Operators
```rust
if x > 0 { // Greater than → [ "$x" -gt 0 ]
println!("Positive"); // println! macro supported
}
if y == 5 { ... } // Equal → [ "$y" -eq 5 ]
if z < 10 { ... } // Less than → [ "$z" -lt 10 ]
```
#### User-Defined Functions
```rust
fn add(a: i32, b: i32) -> i32 {
a + b // Return value via echo
}
fn main() {
let sum = add(1, 2); // Captured with $(add 1 2)
println!("Sum: {}", sum);
}
```
#### Built-in Functions
```rust
// I/O operations
echo("Hello, World!"); // Print to stdout
println!("Hello, World!"); // println! macro (Sprint 10)
eprint("Error!"); // Print to stderr
// File system
mkdir_p("/tmp/myapp"); // Create directory recursively
write_file("config.txt", data); // Write file
let content = read_file("config.txt"); // Read file
if path_exists("/etc/config") { ... } // Check path
// Process management
exec("ls -la"); // Run command
let output = capture("date"); // Capture command output
exit(0); // Exit with code
// Environment
set_env("KEY", "value"); // Set environment variable
let val = env("KEY"); // Get environment variable
let val = env_var_or("KEY", "default"); // With default
```
#### Control Flow
```rust
// Conditionals
if condition {
// ...
} else if other {
// ...
} else {
// ...
}
// ✅ Pattern matching - SUPPORTED (experimental in v1.0.0-rc1)
match value {
"linux" => echo("Linux detected"),
"darwin" => echo("macOS detected"),
_ => echo("Unknown OS"),
}
```
#### Loops ✅ (Supported in v1.0.0-rc1)
```rust
// ✅ For loops - FULLY SUPPORTED
for i in 0..10 {
echo("Iteration: {i}");
}
// ✅ While loops - FULLY SUPPORTED
let mut count = 0;
while count < 10 {
count = count + 1;
echo("Count: {count}");
}
```
### Safety Features
All generated scripts are protected against:
- **Command Injection**: All variables are properly quoted
- **Path Traversal**: Paths are validated and escaped
- **Glob Expansion**: Glob patterns are quoted when needed
- **Word Splitting**: IFS is set to safe value
- **Undefined Variables**: `set -u` catches undefined vars
Example of automatic safety:
```rust
let user_input = env("UNTRUSTED");
exec("echo {user_input}"); // Safe: becomes echo "$user_input"
```
## Beta Features ⚗️
The following features are available but marked as **experimental** in v1.0:
### Binary Compilation (BETA)
Compile Rust to self-extracting shell scripts or container images:
```bash
# Self-extracting script (includes runtime)
bashrs compile install.rs -o install --self-extracting
# Container image (OCI format)
bashrs compile app.rs -o app --container --format oci
```
**Status**:
- ✅ Self-extracting scripts work and are tested
- ⚠️ Container packaging is experimental
- ⚠️ Binary optimization is in progress
**Limitations**:
- Container formats are not fully implemented
- Advanced runtime optimizations pending
- Limited to dash/bash/busybox runtimes
**Recommendation**: Use `bashrs build` for production deployments. Use `compile` for quick testing or when you need a single-file installer.
### Proof Generation (BETA)
Generate formal verification proofs alongside transpiled scripts:
```bash
bashrs build input.rs -o output.sh --emit-proof
```
This creates `output.proof` with formal correctness guarantees.
**Status**: ⚠️ Proof format is experimental and may change
## Examples
See the [`examples/`](examples/) directory for complete examples:
- **Basic**
- [Hello World](examples/hello.rs) - Simplest example
- [Variables](examples/basic/variables.rs) - Variable usage and escaping
- [Functions](examples/basic/functions.rs) - Built-in functions
- [Standard Library](examples/stdlib_demo.rs) - Stdlib functions demo
- **Control Flow**
- [Conditionals](examples/control_flow/conditionals.rs) - If/else statements
- [Loops](examples/control_flow/loops.rs) - Bounded iteration
- **Safety**
- [Injection Prevention](examples/safety/injection_prevention.rs) - Security examples
- [String Escaping](examples/safety/escaping.rs) - Special character handling
- **Real-World**
- [Node Installer](examples/node-installer.rs) - Node.js bootstrap script
- [Rust Installer](examples/rust-installer.rs) - Rust toolchain installer
## Shell Compatibility
Generated scripts are tested on:
| POSIX sh | - | ✅ Full support |
| dash | 0.5.11+ | ✅ Full support |
| bash | 3.2+ | ✅ Full support |
| ash (BusyBox) | 1.30+ | ✅ Full support |
| zsh | 5.0+ | ✅ Full support |
| mksh | R59+ | ✅ Full support |
## Standards Compliance
bashrs adheres to industry-standard shell scripting best practices and specifications:
### POSIX Shell Compliance
bashrs generates scripts compliant with the [POSIX Shell Command Language](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) specification:
| Variable quoting | Automatic single quotes for literals | ✅ Enforced |
| Command substitution | `$(command)` syntax | ✅ Compliant |
| Arithmetic expansion | `$((expression))` syntax | ✅ Compliant |
| Parameter expansion | `${var}` and `"$var"` patterns | ✅ Compliant |
| Test expressions | `[ condition ]` POSIX syntax | ✅ Compliant |
| String escaping | Proper handling of special characters | ✅ Safe |
### Google Shell Style Guide
Aligns with [Google's Shell Style Guide](https://google.github.io/styleguide/shellguide.html) recommendations:
| Always quote variables | Automatic quoting (no unquoted vars possible) | ✅ Enforced |
| Use `$(...)` not backticks | Generates modern `$(...)` syntax | ✅ Compliant |
| Check return values | Effect system tracks side effects | ✅ Implemented |
| Error messages to STDERR | Built-in `eprint()` function | ✅ Available |
| Avoid complex shell scripts | **Write Rust instead!** | ✅ **Core value** |
### ShellCheck Validation
All generated scripts pass [ShellCheck](https://www.shellcheck.net/) static analysis:
- ✅ **SC2086**: No unquoted variable expansions (automatic quoting)
- ✅ **SC2046**: No unquoted command substitutions
- ✅ **SC2116**: No useless echo wrapping
- ✅ **SC2005**: No useless echo in command substitution
- ✅ **24/24 ShellCheck tests passing** (100% compliance)
### Safety Guarantees
bashrs provides **automatic protection** against common shell vulnerabilities:
| **Command Injection** | Unquoted `$var` allows arbitrary commands | All variables auto-quoted |
| **Word Splitting** | `$var` splits on IFS characters | Uses `"$var"` or `'literal'` |
| **Glob Expansion** | `$var` expands wildcards (`*`, `?`) | Proper quoting prevents expansion |
| **Path Traversal** | `cd $dir` allows `../../../etc` | Safe path handling |
| **Exit on Error** | Commands fail silently by default | `set -e` enforced (optional) |
### Comparison: Raw Shell vs bashrs
**Unsafe Raw Shell**:
```bash
#!/bin/bash
USER_INPUT=$1
eval "echo $USER_INPUT" # DANGEROUS!
rm -rf $DIRECTORY # Word splitting risk
```
**Safe bashrs**:
```rust
fn main() {
let user_input = env("1");
echo("{user_input}"); // Auto-quoted → echo "$user_input"
let directory = env("DIRECTORY");
exec("rm -rf {directory}"); // Auto-quoted → rm -rf "$directory"
}
```
**Generated Safe Shell**:
```bash
#!/bin/sh
set -euf
IFS='
'
export LC_ALL=C
main() {
USER_INPUT="${1}"
echo "$USER_INPUT" # Safely quoted
DIRECTORY="${DIRECTORY}"
rm -rf "$DIRECTORY" # Safely quoted
}
main "$@"
```
### Standards Documentation
For detailed compliance information, see:
- [POSIX Shell Specification](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html)
- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
- [ShellCheck Wiki](https://www.shellcheck.net/wiki/)
- **[bashrs Safety Comparison](docs/SAFETY_COMPARISON.md)** - Comprehensive vulnerability prevention guide
## Performance
Rash is designed for fast transpilation with exceptional real-world performance:
**Makefile Parsing & Purification** (v3.0.0):
- Small Makefiles (46 lines): **0.034ms** - 297x faster than 10ms target
- Medium Makefiles (174 lines): **0.156ms** - 320x faster than 50ms target
- Large Makefiles (2,021 lines): **1.43ms** - 70x faster than 100ms target
- Linear O(n) scaling: ~0.37 µs/line parsing, ~0.35 µs/line purification
**Rust-to-Shell Transpilation**:
- **21.1µs** transpile time for simple scripts (100x better than target!)
- Memory usage <10MB for most scripts
- Generated scripts add minimal overhead (~20 lines boilerplate)
## Quality Metrics (v3.0.0)
| **Tests** | 1,752 passing ✅ | 100% pass rate (Sprints 81-84) |
| **Property Tests** | 52 properties ✅ | ~26,000+ test cases, 0 failures |
| **Core Coverage** | 94.85% ✅ | makefile/purify.rs (critical module) |
| **Overall Coverage** | 88.71% ✅ | All modules (exceeds 85% target) |
| **Mutation Testing** | 167 mutants identified ✅ | Comprehensive mutation analysis |
| **Multi-Shell** | 100% pass ✅ | sh, dash, bash, ash, zsh, mksh |
| **ShellCheck** | 100% pass ✅ | All generated scripts POSIX-compliant |
| **Makefile Linter Rules** | 28 transformations ✅ | Parallel, reproducibility, performance, error, portability |
| **Makefile Parsing** | 0.034-1.43ms ✅ | 70-320x faster than targets |
| **Complexity** | Median 1.0 ✅ | All core functions <10 |
| **Edge Cases** | 100% complete ✅ | All identified issues resolved |
**v3.0.0 Status**: ✅ **PRODUCTION-READY** - Phase 1 Complete: Makefile World-Class
## Troubleshooting
Having issues? Check our **[Error Guide](docs/ERROR_GUIDE.md)** for common errors and solutions.
## MCP Server
Rash provides a Model Context Protocol (MCP) server for AI-assisted shell script generation:
```bash
# Install from crates.io
cargo install rash-mcp
# Run MCP server
rash-mcp
```
The MCP server is available in the official registry as `io.github.paiml/rash`.
**For developers**: See [MCP Registry Publishing Guide](docs/mcp-registry-publish.md) for details on the automated publishing process.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/paiml/rash.git
cd rash
# Run tests
make test
# Run with all checks
make validate
# Build release binary
make release
```
### Publishing to MCP Registry
For maintainers publishing new MCP server versions, see the [MCP Registry Publishing Guide](docs/mcp-registry-publish.md).
## License
Rash is licensed under the MIT License. See [LICENSE](LICENSE) for details.
## Acknowledgments
Rash is built with safety principles inspired by:
- [ShellCheck](https://www.shellcheck.net/) for shell script analysis
- [Oil Shell](https://www.oilshell.org/) for shell language design
- The Rust community for memory safety practices
## Roadmap
### v3.0.0 (Current Release) ✅
**Status**: PRODUCTION-READY - Phase 1 Complete: Makefile World-Class
**Released**: 2025-10-20
**Achievement**: World-class Makefile linting, parsing, and purification with exceptional performance
**Quality Metrics**:
- 1,752 tests passing (100% pass rate, Sprints 81-84)
- 94.85% coverage on critical modules (makefile/purify.rs)
- 88.71% overall coverage (exceeds 85% target)
- 167 mutants identified through comprehensive mutation testing
- 0 shellcheck warnings
- 52 property tests (~26,000+ cases)
- 70-320x faster than performance targets
**Core Features** (Complete):
- [x] **Makefile Purification** (v3.0.0 - NEW!) - World-class linting and transformation
- 28 transformation types across 5 categories
- Parallel safety analysis, reproducibility enforcement
- Performance optimization, error handling detection
- Portability checks (bashisms, platform-specific commands)
- 70-320x faster than performance targets
- [x] Rust-to-Shell transpilation (POSIX, Bash, Dash, Ash)
- [x] Full AST parsing and validation (98.92% coverage)
- [x] IR generation and optimization (87-99% coverage)
- [x] Safety verification and escape handling (95.45% coverage)
- [x] Multi-shell compatibility testing (100% pass rate)
- [x] Property-based testing (114k executions, 0 failures)
- [x] Fuzzing infrastructure (0 failures)
- [x] ShellCheck compliance (24/24 tests pass)
- [x] Arithmetic expressions and comparisons
- [x] User-defined functions
- [x] `println!` macro support
- [x] MCP server (rash-mcp)
**CLI Tools** (Complete):
- [x] `bashrs build` - Transpile Rust to shell
- [x] `bashrs check` - Validate Rust compatibility
- [x] `bashrs init` - Project scaffolding
- [x] `bashrs verify` - Script verification
- [x] `bashrs inspect` - Formal verification reports
**Shipped in v1.0.0-rc1**:
- [x] Control flow (if/else if/else) - STABLE
- [x] For loops (0..n, 0..=n) - STABLE
- [x] While loops (with max_iterations safety) - STABLE
- [x] Match expressions (basic pattern matching) - EXPERIMENTAL
- [x] Logical operators (&&, ||, !) - STABLE
- [x] String and integer comparisons - STABLE
- [x] Self-extracting scripts - STABLE
- [ ] Container packaging (in progress)
- [ ] Proof generation (experimental format)
### v1.1.0 (Released - October 2025) ✅
**Native Linting** (Complete):
- [x] `bashrs lint` subcommand with zero external dependencies
- [x] SC2086 - Unquoted variable expansion detection
- [x] SC2046 - Unquoted command substitution detection
- [x] SC2116 - Useless echo detection
- [x] Human, JSON, and SARIF output formats
- [x] Auto-fix suggestions for all violations
- [x] 48 comprehensive linter tests (100% passing)
- [x] 88.5% code coverage (exceeds 85% target)
**Quality Improvements**:
- [x] Increased test coverage from 85.36% to 88.5%
- [x] Added 48 new linter tests (804 total tests)
- [x] Comprehensive documentation with Sprint 1 report
### v1.2 (Planned)
**Enhanced Linting**:
- [ ] SC2115 - Use `${var:?}` to ensure variable is set
- [ ] SC2128 - Expanding array without index
- [ ] BP-series rules (POSIX compliance validation)
- [ ] SE-series rules (Security taint analysis)
- [ ] Auto-fix application (`--fix` flag)
- [ ] AST-based semantic analysis (replace regex)
**Interactive Features**:
- [ ] Playground/REPL (separate `rash-playground` crate)
- [ ] Web-based transpiler
- [ ] Live syntax highlighting
**Language Features**:
- [x] For loops (`for i in 0..10`) - SHIPPED in v1.0.0-rc1
- [x] Match expressions (pattern matching) - SHIPPED in v1.0.0-rc1
- [x] While loops - SHIPPED in v1.0.0-rc1
- [ ] Arrays and collections (advanced operations)
- [ ] Enhanced pattern matching guards
**Tooling**:
- [ ] Language server protocol (LSP)
- [ ] IDE integration examples
- [ ] Better error diagnostics
### v1.2+ (Future)
**Advanced Features**:
- [ ] Incremental compilation
- [ ] More shell targets (fish, PowerShell, nushell)
- [ ] Package manager integration
- [ ] Advanced optimizations (constant folding, DCE)
- [ ] Formal verification with SMT solvers
**Documentation**:
- [ ] Video tutorials
- [ ] Interactive examples
- [ ] Best practices guide
See [v1.0-feature-scope.md](.quality/v1.0-feature-scope.md) for detailed feature decisions.