Metadata-Version: 2.4
Name: auto-linter
Version: 1.6.3
Summary: MCP server for autonomous linting and governance auditing
Author-email: Raka Arwaky <arwaky90@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/rakaarwaky/auto-linter
Project-URL: Repository, https://github.com/rakaarwaky/auto-linter
Project-URL: Install (Linux/macOS), https://raw.githubusercontent.com/rakaarwaky/auto-linter/main/install.sh
Project-URL: Install (Windows), https://raw.githubusercontent.com/rakaarwaky/auto-linter/main/install.ps1
Keywords: mcp,linting,governance,ruff,mypy,ai
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]
Requires-Dist: fastmcp
Requires-Dist: pydantic
Requires-Dist: ruff
Requires-Dist: mypy
Requires-Dist: click
Requires-Dist: watchdog
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml
Requires-Dist: python-dotenv
Requires-Dist: toml
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pyre-check; extra == "dev"
Dynamic: license-file

# Auto Linter

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-green.svg)](tests/)
[![Test Count: 1500+](https://img.shields.io/badge/tests-1500%2B-green.svg)](tests/)
[![MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/)
[![AI Agent Ready](https://img.shields.io/badge/AI%20Agent-Ready-green.svg)](tests/)

> # Autonomous code quality. Built for AI agents that code 24/7.

## 🤖 AI Agent Benefits

> In AI Era, no one manually codes anymore. Your AI agent does the work.

| Benefit                      | Description                                              |
| ---------------------------- | -------------------------------------------------------- |
| **Autonomous Linting** | Agent runs lint check without human intervention         |
| **Self-Healing Code**  | Agent auto-fixes issues automatically                    |
| **Multi-Agent Collab** | 24/7 multi agents can coordinate via shared job registry |
| **Continuous Quality** | Agent enforces quality gates 24/7                        |
| **Context-Aware**      | Agent understands architectural rules                    |

## Choose Your Path

| I'm a...                      | Start Here                                       | What I'll Do                     |
| ----------------------------- | ------------------------------------------------ | -------------------------------- |
| **AI Agent**            | [SKILL.md](./SKILL.md)                              | Autonomous linting, self-healing |
| **Vibe Coder**          | [Quick Start](#quick-start)                         | Fast AI-assisted coding          |
| **Vibe Architect**      | [Architecture](#architecture)                       | Architectural governance         |
| **Developer**           | [Setup for AI Agents](#setup-for-ai-agents)         | Add features, fix bugs           |
| **Adapter Contributor** | [Contributing: Add Adapter](#how-to-add-an-adapter) | Integrate new linter tools       |
| **CLI Contributor**     | [Contributing: Add CLI](#how-to-add-a-cli-command)  | Add new CLI commands             |

---

## Why Use Auto Linter

>  **Stop Wasting Hours on Manual Linting** — Your competitors are already using automated quality gates.

### For Users

| Benefit                  | Description                                                 |
| ------------------------ | ----------------------------------------------------------- |
| **Easy Config**    | Works out-of-the-box with sensible defaults                 |
| **Multi-Language** | Python, JavaScript, TypeScript in one tool                  |
| **AI Ready**       | MCP server for automated code review                        |
| **Vibe Mode**      | Fast AI-assisted iterations, quality gates                  |
| **Governance**     | Architectural rule enforcement (AES, Clean, Hexagonal, DDD) |
| **CI-Ready**       | SARIF, JUnit, JSON reports with exit codes                  |
| **Auto-Fix**       | Safe fixes applied automatically                            |
| **Quality Trends** | Track code quality over time                                |

### For Contributors

| Benefit                       | Description                                    |
| ----------------------------- | ---------------------------------------------- |
| **Well-Structured**     | 5-domain architecture with clear boundaries    |
| **Comprehensive Tests** | 1000+ tests, 100% coverage                     |
| **Governance Built-In** | Linting governance adapter prevents violations |
| **Clear Paths**         | Documented guides for adapters, CLI, MCP       |
| **Active Project**      | Regular updates, responsive maintainer         |

## Install

```bash
pip install auto-linter
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv tool install auto-linter
```

Or zero-install:

```bash
uvx auto-lint check ./src/
```

Or one-liner installer (Linux/macOS):

```bash
curl -sSL https://raw.githubusercontent.com/rakaarwaky/auto-linter/main/install.sh | bash
```

Or for Windows (PowerShell):

```powershell
Invoke-WebRequest -Uri https://raw.githubusercontent.com/rakaarwaky/auto-linter/main/install.ps1 | Invoke-Expression
```

### Verify

```bash
auto-lint version
auto-lint setup doctor
```

---

## Quick Start

```bash
# Lint your code
auto-lint check ./src/

# Auto-fix safe issues
auto-lint fix ./src/

# Security scan
auto-lint security ./src/

# Generate report
auto-lint report ./src/ --output-format json
```

---

## Setup for AI Agents

### Hermes Agent

```bash
pip install auto-linter
auto-lint setup hermes
```

This auto-detects DesktopCommander and configures Hermes automatically.

### Claude Desktop / VS Code

```bash
auto-lint setup mcp-config --client claude
```

Copy the output to your MCP config file.

### MCP Tools (5 tools)

The server registers 5 MCP tools:

| Tool                   | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `execute_command`    | Execute any CLI command                           |
| `list_commands`      | List all available CLI commands with descriptions |
| `read_skill_context` | Read SKILL.md documentation sections              |
| `check_status`       | Check status of running lint jobs                 |
| `health_check`       | Check DesktopCommander and transport health       |

> **Note**: Job cancellation is a CLI command: `auto-lint cancel <job_id>`

---

## Transport

Auto-linter connects to DesktopCommander for command execution. Supports 3 transport modes with **auto-detection**:

```
DESKTOP_COMMANDER_URL              Mode             Requires
──────────────────────────────────────────────────────────────
/run/desktop-commander/socket      Unix Socket      DesktopCommander
http://host:port/execute           HTTP             DesktopCommander HTTP wrapper
auto (default)                     Auto-detect      tries socket -> http -> stdio
```

The default socket path is `/run/desktop-commander/socket`. Set `DESKTOP_COMMANDER_URL` to override.

---

## CLI Commands

### Core

| Command           | Description                                     |
| ----------------- | ----------------------------------------------- |
| `check <path>`  | Run all linters, check governance score         |
|                   | `--git-diff` flag: only lint changed files    |
| `scan <path>`   | Alias for check (CI-friendly)                   |
| `fix <path>`    | Apply safe fixes automatically                  |
| `report <path>` | Generate quality report (text/json/sarif/junit) |
| `ci <path>`     | CI-optimized with exit codes                    |

### Scans

| Command                 | Description                    |
| ----------------------- | ------------------------------ |
| `security <path>`     | Bandit vulnerability scanning  |
| `complexity <path>`   | Cyclomatic complexity analysis |
| `duplicates <path>`   | Code duplication detection     |
| `trends <path>`       | Quality trends over time       |
| `dependencies <path>` | Dependency vulnerability scan  |

### Setup

| Command              | Description                                |
| -------------------- | ------------------------------------------ |
| `setup init`       | Auto-configure for your system             |
| `setup hermes`     | Auto-install into Hermes Agent             |
| `setup doctor`     | Diagnose configuration issues              |
| `setup mcp-config` | Print MCP config for Claude/Hermes/VS Code |

### Dev

| Command                     | Description                                 |
| --------------------------- | ------------------------------------------- |
| `diff <path1> <path2>`    | Compare lint results between two versions   |
| `suggest <path>`          | AI-powered fix suggestions (--ai flag)      |
| `config show\|edit\|reset`  | View, edit, or reset configuration settings |
| `export sarif\|junit\|json` | Export lint reports to file (-o output)     |
| `import <config.json>`    | Import configurations from file             |
| `ignore <rule>`           | Manage ignore rules (--remove to delete)    |
| `init`                    | Initialize a new Auto-Linter configuration  |
| `install-hook`            | Install git pre-commit hook                 |
| `uninstall-hook`          | Remove git pre-commit hook                  |

### Maintenance

| Command             | Description          |
| ------------------- | -------------------- |
| `cancel <job_id>` | Cancel a running job |
| `stats <path>`    | Statistics dashboard |
| `clean`           | Cleanup cache        |
| `update`          | Update adapters      |
| `doctor`          | Diagnose issues      |
| `version`         | Show version         |
| `adapters`        | List enabled linters |

### Other

| Command                      | Description                          |
| ---------------------------- | ------------------------------------ |
| `watch <path>`             | Watch files and auto-lint on changes |
| `batch <path1> <path2>`    | Check multiple paths                 |
| `plugins`                  | List discovered plugins              |
| `multi-project <paths...>` | Lint multiple projects, aggregate    |

Full list: `auto-lint --help`

---

## Configuration

### .env (optional)

```bash
# DesktopCommander transport (auto-detected if not set):
DESKTOP_COMMANDER_URL=/run/desktop-commander/socket

# For JS/TS linters:
PHANTOM_ROOT=$HOME/
```

Create with: `auto-lint setup init`

### auto_linter.config.yaml

```yaml
thresholds:
  score: 90.0
  complexity: 10
  max_file_lines: 500

adapters:
  - name: ruff
    status: enabled
    weight: 1.0
  - name: mypy
    status: enabled
    weight: 1.0
```

---

## Architecture

5-domain structure:

```
src/
├── agent/              # Lifecycle, orchestration, pipeline, DI container
├── capabilities/       # Thinking logic — analysis, formatting, governance
├── infrastructure/     # Adapters — ruff, mypy, eslint, transports
├── surfaces/           # Interfaces — CLI (Click), MCP (FastMCP)
└── taxonomy/           # Value objects, models, shared language
```

### Dependency Rules

```
surfaces      → capabilities       OK
surfaces      → infrastructure     NO
capabilities  → infrastructure     NO (use taxonomy interfaces)
capabilities  → surfaces           NO
infrastructure → taxonomy          OK
agent         → everything         OK (wiring layer)
```

---

## Contributing

### How to Add an Adapter

1. Create adapter in `src/infrastructure/<tool>_adapter.py` implementing [`ILinterAdapter`](src/taxonomy/interfaces.py)
2. Register in [`src/agent/dependency_injection_container.py`](src/agent/dependency_injection_container.py)
3. Add tests in `tests/infrastructure/test_<tool>_adapter.py`
4. Run: `python3 -m pytest tests/ -q`

See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.

### How to Add a CLI Command

1. Choose module in `src/surfaces/cli_*_commands.py` based on command type
2. Add command using Click decorators
3. Register in [`src/surfaces/mcp_command_catalog.py`](src/surfaces/mcp_command_catalog.py)
4. Add tests

See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.

---

## License

MIT License. See [LICENSE](LICENSE).
