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

pip install errorfix-cli

Or install from source:

pip install -e .

Usage

Basic usage with stdin

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

With custom rules

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

Specify output format

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

Filter by language

errorfix fix -l python "SyntaxError: invalid syntax"

Commands

fix

Analyze error text and suggest fixes.

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.

errorfix plugins

check

Check loaded rules from specified paths.

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:

- 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:

# 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:

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

Examples

Python Error

$ 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

$ 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

$ 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",
      "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

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

# Run tests
pytest tests/ -v

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

License

MIT