auto-code-fixer 0.4.0
Automatically fix Python code using ChatGPT
License: MIT
Requires Python: >=3.9

# Auto Code Fixer

Auto Code Fixer is a CLI tool that **detects runtime failures** and automatically fixes Python code using OpenAI.

It is designed for real projects where an entry script imports multiple local modules. The tool runs your code in an **isolated sandbox + venv**, installs missing external dependencies, and applies fixes only after the code executes successfully.

---

## Installation

```bash
pip install auto-code-fixer
```

---

## Quick start

```bash
auto-code-fixer path/to/main.py --project-root . --ask
```

If you want it to overwrite without asking:

```bash
auto-code-fixer path/to/main.py --project-root . --no-ask
```

---

## What it fixes (core behavior)

### ✅ Local/internal imports are treated as project code
If your entry file imports something like:

```py
from mylib import add
```

…and `mylib.py` exists inside the project, Auto Code Fixer will:
- copy `main.py` + `mylib.py` into a sandbox
- execute inside the sandbox
- if the traceback points to `mylib.py`, it will fix `mylib.py`
- then apply the fix back to your repo (with backups)

### ✅ External imports are auto-installed
If execution fails with:

```
ModuleNotFoundError: No module named 'requests'
```

…it will run:

```bash
pip install requests
```

…but only inside the sandbox venv (so your system env isn’t polluted).

---

## Safety

### Backups
Before overwriting any file, it creates a backup:
- `file.py.bak` (or `.bak1`, `.bak2`, ...)

### Approval mode (diff review)
```bash
auto-code-fixer path/to/main.py --project-root . --approve
```
In patch-protocol mode, approvals are **file-by-file** (apply/skip).

### Diff / size guards
To prevent huge edits from being applied accidentally:
- `--max-diff-lines` limits unified-diff size per file
- `--max-file-bytes` limits the proposed new content size per file
- `--max-total-bytes` limits total proposed new content across all files

### Dry run
```bash
auto-code-fixer path/to/main.py --project-root . --dry-run
```

---

## Advanced options

### Fixpack mode (folder/package runner)
Fixpack runs a command (default: `pytest -q`) against a **full-project sandbox**, then iteratively fixes the failing file(s) until green or you hit `--max-retries`.

```bash
auto-code-fixer path/to/package --project-root . --fixpack --no-ask
# equivalent explicit command:
auto-code-fixer path/to/package --project-root . --fixpack --run "pytest -q" --no-ask
```

### Run a custom command (pytest, etc.)
Instead of `python main.py`, run tests:

```bash
auto-code-fixer . --project-root . --run "pytest -q" --no-ask
```

When you use `--run`, the tool (by default) also performs a **post-apply check**:
after copying fixes back to your project, it re-runs the same command against the real project files
(using the sandbox venv for dependencies).

You can disable that extra check with:

```bash
auto-code-fixer . --project-root . --run "pytest -q" --no-post-apply-check
```

### Model selection
```bash
export AUTO_CODE_FIXER_MODEL=gpt-4.1-mini
# or
auto-code-fixer main.py --model gpt-4.1-mini
```

### Max retries / timeout
```bash
auto-code-fixer main.py --max-retries 8 --timeout 30
```

### Optional AI planning (which file to edit)
```bash
auto-code-fixer main.py --ai-plan
```
This enables a helper that can suggest which local file to edit. It is best-effort.

### Structured patch protocol (JSON + sha256) (default)
By default, Auto Code Fixer uses a structured **patch protocol** where the model returns strict JSON:

`{ "files": [ {"path": "...", "new_content": "...", "sha256": "..."}, ... ] }`

The tool verifies the SHA-256 hash of `new_content` before applying edits.

To disable this and use legacy full-text mode only:

```bash
auto-code-fixer main.py --legacy-mode
```

### Ruff-first mode (best-effort)
Before calling the LLM, you can try Ruff auto-fixes (including import sorting) and Ruff formatting:

```bash
auto-code-fixer path/to/package --project-root . --fixpack --ruff-first
```

### Optional formatting / linting (best-effort)
```bash
auto-code-fixer main.py --format black
auto-code-fixer main.py --lint ruff --fix
```
These run inside the sandbox venv and are skipped if the tools are not installed.

### JSON report (explain)
Write a machine-readable report with attempts, files touched, and unified diffs:

```bash
auto-code-fixer main.py --explain
# or
auto-code-fixer main.py --report /tmp/report.json
```

---

## Environment variables

- `OPENAI_API_KEY` (required unless you always pass `--api-key`)
- `AUTO_CODE_FIXER_MODEL` (default model)
- `AUTO_CODE_FIXER_ASK=true|false`
- `AUTO_CODE_FIXER_VERBOSE=true|false`

---

## Notes

- This tool edits code. Use it on a git repo so you can review diffs.
- For maximum safety, run with `--ask` and/or `--dry-run`.