guardrail-ai 0.1.8
A CLI tool that generates and runs tests for changed Python functions before executing commands
License: MIT
Requires Python: >=3.8
Keywords: testing, guardrail, cli, python

# GuardRail

A CLI tool that automatically generates and runs tests for changed Python functions before executing commands. GuardRail uses AI to analyze your code changes, generate comprehensive tests, and blocks execution if tests fail.

## Features

- 🔍 **Automatic Change Detection** - Detects changed Python functions using git diff
- 🧠 **AI-Powered Test Generation** - Uses OpenAI to generate comprehensive pytest tests
- 🛡️ **Side-Effect Detection** - Automatically skips functions with side effects (network, DB, file I/O)
- ✅ **Test Execution** - Runs generated tests automatically before your command
- 🚫 **Execution Blocking** - Prevents command execution if tests fail
- 🔧 **Fix Prompts** - Provides detailed fix prompts when tests fail

## Installation

### Quick Install (from Git)

```bash
# Clone the repository
git clone https://github.com/yourusername/GuardRail.git
cd GuardRail

# Install in editable mode
pip install -e .
```

### Install from Local Directory

If you have the GuardRail folder:

```bash
cd /path/to/GuardRail
pip install -e .
```

### Install from PyPI (when published)

```bash
pip install guardrail
```

See [INSTALLATION.md](INSTALLATION.md) for detailed installation instructions.

## Quick Start

### 1. Initialize GuardRail

```bash
guardrail init
```

This will:

- Create `.guardrail/config.toml` - Configuration file
- Create `.guardrail/cache.sqlite` - Cache database
- Prompt you for your OpenAI API key (or set `OPENAI_API_KEY` environment variable)

### 2. Run Commands with GuardRail

```bash
guardrail run -- pytest
guardrail run -- python main.py
guardrail run -- uvicorn app:app
```

GuardRail will:

1. Detect changed Python functions
2. Classify them (pure vs side-effect)
3. Generate tests for pure functions
4. Run the tests
5. Block execution if tests fail
6. Execute your command if tests pass

### 3. Manual Check (without running command)

```bash
guardrail check
```

Runs the same detection and test generation flow without executing a command at the end.

## How It Works

### 1. Change Detection

GuardRail uses `git diff` to detect unstaged changes in Python files and identifies which functions were modified.

### 2. Function Analysis

- Parses Python files using AST
- Extracts function definitions with line numbers
- Maps changed lines to specific functions

### 3. Side-Effect Classification

Automatically detects and skips functions with:

- Network calls (`requests`, `httpx`, `aiohttp`)
- Database operations (`sqlite3`, `psycopg2`, `pymongo`, `redis`)
- File I/O (`open()`, file operations)
- System calls (`subprocess`, `os.system`)

### 4. Test Generation

For pure functions, GuardRail:

- Generates a SpecCard (function specification) using AI
- Generates comprehensive pytest tests based on the SpecCard
- Saves tests to `tests/guardrail_generated/`

### 5. Test Execution

- Runs pytest on generated tests
- Blocks command execution if tests fail
- Provides detailed fix prompts for failing tests

## Configuration

Configuration is stored in `.guardrail/config.toml`:

```toml
version = "0.1.0"
test_dir = "tests/guardrail_generated"
cache_enabled = true
openai_api_key = "sk-..."  # Stored securely
```

### Environment Variables

- `OPENAI_API_KEY` - OpenAI API key (alternative to storing in config)

## Example Workflow

```bash
# Make changes to a Python function
$ vim my_module.py

# Run your command with GuardRail
$ guardrail run -- python main.py

🔍 Detecting changed files...
📝 Found 1 changed Python file(s):
  📄 my_module.py (lines: 10-15)

🔎 Analyzing changed functions...
  📄 my_module.py
    Functions touched: 1
      ✅ calculate_total - Pure-ish

🤖 Generating tests for 1 pure function(s)...
  📝 Generating spec for calculate_total...
  ✅ Spec generated (confidence: high)
  🧪 Generating tests...
  ✅ Test saved: tests/guardrail_generated/test_my_module_calculate_total.py

✅ Generated 1 test file(s)

🧪 Running generated tests...
✅ All tests passed!

🚀 Running: python main.py
[Your command output...]
```

## Requirements

- Python 3.8+
- Git repository (for change detection)
- OpenAI API key
- pytest (for running tests)

## Development Status

✅ **V1 Complete** - All core features implemented

### Completed Features

- ✅ Change detection (git diff)
- ✅ AST function locator
- ✅ Side-effect classifier
- ✅ AI-powered test generation
- ✅ Test execution and blocking
- ✅ Fix prompt generation
- ✅ Manual check command
- ✅ Caching system

## Troubleshooting

### "OpenAI API key not found"

Run `guardrail init` to configure your API key, or set the `OPENAI_API_KEY` environment variable.

### "pytest not found"

Install pytest: `pip install pytest`

### "Not a git repository"

GuardRail requires a git repository for change detection. Initialize git: `git init`

### Tests failing but function seems correct

The generated tests might be too strict. Check the test file in `tests/guardrail_generated/` and adjust if needed.

## License

MIT