errorfix-cli/README.md

# ErrorFix CLI

A CLI tool that takes error output from compilers, linters, or build tools and generates actionable fix suggestions using a pattern-matching rule system. Works completely offline with extensible YAML/JSON rule definitions for different languages and tools.

## Features

- **Pattern-based fixes**: Uses regex patterns to match error messages and suggest fixes
- **Multi-language support**: Python, JavaScript, TypeScript, and more
- **Extensible rules**: Add custom YAML/JSON rules for your specific errors
- **Plugin system**: Load community rule packages via entry points
- **Multiple output formats**: Text, JSON, or structured output
- **Pipeline integration**: Works with stdin/stdout for CI/CD integration
- **Offline operation**: No network calls required

## Installation

```bash
pip install errorfix-cli
```

Or install from source:

```bash
pip install -e .
```

## Usage

### Basic usage with stdin

```bash
echo "NameError: name 'foo' is not defined" | errorfix fix
```

### With custom rules

```bash
errorfix fix -r /path/to/rules "Your error message here"
```

### Specify output format

```bash
errorfix fix -f json "TypeError: unsupported operand type"
```

### Filter by language

```bash
errorfix fix -l python "SyntaxError: invalid syntax"
```

## Commands

### fix

Analyze error text and suggest fixes.

```bash
errorfix fix [OPTIONS] [INPUT_FILE]

Options:
  -f, --output-format [text|json|structured]
                                  Output format (default: text)
  -l, --language TEXT            Filter rules by language
  -t, --tool TEXT                Filter rules by tool
  --limit INTEGER                Limit number of matches
  --no-color                     Disable colored output
```

### plugins

List loaded plugins.

```bash
errorfix plugins
```

### check

Check loaded rules from specified paths.

```bash
errorfix check -r /path/to/rules
```

## Configuration

### Environment Variables

- `ERRORFIX_RULES_PATH`: Custom path to rule directory (default: `rules/`)

### Rule Files

Rules are defined in YAML or JSON format:

```yaml
- id: python-name-error
  name: "Python Name Error"
  pattern: "NameError: name '(?P<name>[a-zA-Z_][a-zA-Z0-9_]*)' is not defined"
  fix: "Define '{name}' before using it"
  description: "A name is not defined"
  severity: error
  language: python
  tool: python
  tags: [name-error, undefined]
  priority: 9
```

### Rule Fields

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique identifier for the rule |
| `name` | Yes | Human-readable name |
| `pattern` | Yes | Regex pattern to match error messages |
| `fix` | Yes | Fix suggestion (can use `{variable}` for captured groups) |
| `description` | Yes | Description of the error |
| `severity` | No | `error`, `warning`, `info`, or `suggestion` (default: `error`) |
| `language` | No | Programming language (e.g., `python`, `javascript`) |
| `tool` | No | Tool that produced the error (e.g., `python`, `node`) |
| `tags` | No | List of tags for categorization |
| `priority` | No | Priority for matching order (default: 0) |

## Plugins

Create a plugin by defining an entry point:

```python
# my_plugin.py
from errorfix.plugins import Plugin

class MyPlugin(Plugin):
    @property
    def name(self) -> str:
        return "my-plugin"

    @property
    def version(self) -> str:
        return "1.0.0"

    @property
    def description(self) -> str:
        return "My custom error rules"

    def load_rules(self) -> list:
        return [
            {
                'id': 'custom-error',
                'name': 'Custom Error',
                'pattern': 'CustomError: .*',
                'fix': 'Fix the custom error',
                'description': 'Custom error rule',
            }
        ]

def register():
    return MyPlugin()
```

Add to your `pyproject.toml`:

```toml
[project.entry-points]
errorfix.plugins = "my_plugin:register"
```

## Examples

### Python Error

```bash
$ echo "ModuleNotFoundError: No module named 'requests'" | errorfix fix
Fix #1: Python Import Error
--------------------------------------------------
Rule ID: python-import-error
Description: A module could not be found
Severity: error
Language: python

Matched:
ModuleNotFoundError: No module named 'requests'

Suggested Fix:
Install the module 'requests' using pip: pip install requests
```

### Git Error

```bash
$ echo "CONFLICT (content): Merge conflict in src/main.py" | errorfix fix -r rules/tools
Fix #1: Git Merge Conflict
--------------------------------------------------
Rule ID: git-merge-conflict
Description: A merge conflict was detected
Severity: error
Tool: git

Matched:
CONFLICT (content): Merge conflict in src/main.py

Suggested Fix:
Open src/main.py and resolve the merge conflict. Remove the conflict markers...
```

### JSON Output

```bash
$ echo "TypeError: unsupported operand type" | errorfix fix -f json
{
  "input_text": "TypeError: unsupported operand type",
  "match_count": 1,
  "matches": [
    {
      "rule": {
        "id": "python-type-error",
        "name": "Python Type Error",
        "description": "An operation was performed on incompatible types",
        "severity": "error",
        "language": "python",
        "tool": "python",
        "tags": ["type", "type-error"]
      },
      "matched_text": "TypeError: unsupported operand type",
      "captured_variables": {},
      "suggested_fix": "Check the types of your operands."
    }
  ]
}
```

## Built-in Rules

The tool includes rules for:

- **Python**: SyntaxError, NameError, TypeError, ImportError, AttributeError, IndexError, KeyError, and more
- **JavaScript/TypeScript**: ReferenceError, TypeError, SyntaxError, ModuleNotFound
- **Git**: Merge conflicts, repository errors, remote errors
- **Docker**: Container conflicts, image not found
- **Make**: Target not found, command not found
- **NPM**: Package not found, missing script

## Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ --cov=errorfix
```

## License

MIT