Metadata-Version: 2.4
Name: auto-linter
Version: 1.8.0
Summary: MCP server for autonomous linting and architecture 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,architecture,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
Requires-Dist: jinja2
Requires-Dist: nest_asyncio
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)
[![Test Count: 1518](https://img.shields.io/badge/tests-1518-blue.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 for AI agents and developers.

## AI Agent Integration

AI agents use the MCP interface to perform automated linting and code quality tasks:

| 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 |
| **Prototype Developer**          | [Quick Start](#quick-start)                         | Fast AI-assisted coding          |
| **Architecture Engineer**      | [Architecture](#architecture)                       | Architectural rules              |
| **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

### 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                        |
| **Rapid Iteration**      | Fast feedback loop, automated quality gates        |
| **Architecture**   | 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**       | 6-domain architecture with clear boundaries      |
| **Comprehensive Tests**   | 1518 tests (100% branch coverage)                |
| **Architecture Built-In** | Linting architecture 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

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 architecture 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.python.yaml

```yaml
thresholds:
  score: 100.0
  complexity: 10

output_dir: "output"

adapters:
  - name: "ruff"
    weight: 1.0
  - name: "mypy"
    weight: 1.0
  - name: "bandit"
    weight: 1.0
  - name: "radon"
    weight: 1.0
  - name: "architecture"
    weight: 3.0
```

---

## Architecture

6-domain structure with strict architectural enforcement (AES):

```
src/
├── agent/              # Orchestration & DI. MANDATORY: contract(io)
├── capabilities/       # Thinking logic (pure). MANDATORY: contract(protocol)
├── contract/           # Definitions: _io (Agent), _port (Infra), _protocol (Cap)
├── infrastructure/     # Technical details (IO). MANDATORY: contract(port)
├── surfaces/           # Entry points (CLI, MCP). No logic allowed.
└── taxonomy/           # Shared language (Value Objects, Entities, Events)
```

### Architectural Enforcement Standards (AES)

Auto Linter enforces a 100/100 compliance score based on these rules:

1. **3-Word Naming**: Every file (except `__init__.py`) must have exactly 3 words separated by underscores (e.g., `user_data_vo.py`).
2. **Mandatory Classes**: Every logic file must encapsulate its logic in a class. Standalone functions are prohibited.
3. **Contract Inheritance**: Every class must inherit from a domain contract defined in `src/contract/`.
4. **Strict Layering**: No layer bypasses. Surfaces can only call the Agent layer. Infrastructure and Capabilities must be pure adapters/processors.
5. **No Bypasses**: Usage of `# noqa`, `# type: ignore`, or `# nosec` results in immediate failure (-5 points per violation, CRITICAL).

### Dependency Rules

```
agent          → taxonomy, contract, infrastructure, capabilities  ALLOWED
surfaces       → agent, taxonomy, contract(io)                     ALLOWED
capabilities   → taxonomy, contract(protocol)                      ALLOWED
infrastructure → taxonomy, contract(port)                          ALLOWED
contract       → taxonomy                                          ALLOWED
taxonomy       → taxonomy                                          ALLOWED
```

### Contract Governance

To prevent architectural bypasses, each layer must inherit from its corresponding contract type:

| Layer                    | Suffix Rule | Mandatory Contract | Purpose                              |
| ------------------------ | ----------- | ------------------ | ------------------------------------ |
| **Agent**          | Strict      | `_io.py`         | Executive orchestration recipes      |
| **Capabilities**   | Flexible    | `_protocol.py`   | Pure domain logic interfaces         |
| **Infrastructure** | Flexible    | `_port.py`       | Technical adapter abstractions       |
| **Surfaces**       | Strict      | N/A                | Entry points calling the Agent brain |
| **Taxonomy**       | Strict      | `_vo.py` etc.    | Value Objects for domain integrity   |

> [!IMPORTANT]
> Merely importing the contract is not enough. You **MUST** use the contract as a base class. The linter checks for semantic implementation via AST analysis.

---

## Contributing

### How to Add an Adapter

1. Create adapter in `src/infrastructure/python_<tool>_adapter.py` (3 words) implementing `ILinterAdapterPort`.
2. Register in [`src/agent/dependency_injection_container.py`](src/agent/dependency_injection_container.py).
3. Add tests in `tests/infrastructure/test_python_<tool>_adapter.py`.
4. Run: `auto-lint check src/` to verify 100.0 score.

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

### How to Add a CLI Command

1. Choose module in `src/surfaces/cli_<domain>_command.py` based on command type.
2. Add command using Click decorators within a handler class.
3. Register in [`src/surfaces/mcp_command_store.py`](src/surfaces/mcp_command_store.py).
4. Add tests.

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

---

## License

MIT License. See [LICENSE](LICENSE).
