Metadata-Version: 2.4
Name: agent-slop-lint
Version: 1.0.0
Summary: Agentic code quality linter — catches slop before it becomes architectural rot
Author: Jordan Godau
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agentic,code-quality,complexity,coupling,linter,slop
Requires-Python: >=3.10
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: tree-sitter-bash>=0.21.0
Requires-Dist: tree-sitter-c-sharp>=0.21.0
Requires-Dist: tree-sitter-c>=0.21.0
Requires-Dist: tree-sitter-cpp>=0.21.0
Requires-Dist: tree-sitter-go>=0.21.0
Requires-Dist: tree-sitter-java>=0.21.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: tree-sitter-julia>=0.21.0
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter-ruby>=0.21.0
Requires-Dist: tree-sitter-rust>=0.21.0
Requires-Dist: tree-sitter-typescript>=0.21.0
Requires-Dist: tree-sitter>=0.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# slop

A code quality linter for codebases where AI agents are writing most of the diffs.

[![PyPI](https://img.shields.io/pypi/v/agent-slop-lint)](https://pypi.org/project/agent-slop-lint/)
[![Python](https://img.shields.io/pypi/pyversions/agent-slop-lint)](https://pypi.org/project/agent-slop-lint/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

Static-analysis defaults were calibrated for codebases where a productive human wrote ~100 lines on a busy day and another human reviewed every one. An agent can drop that much into a single file before emitting its first status message, and the structural damage — deep coupling, WMC-heavy classes, files that grow 500 LOC in a week — lands inside one session rather than over quarters. `slop` runs well-cited structural metrics (McCabe, Chidamber & Kemerer, Halstead, Nejmeh, Martin, Tornhill, Campbell) at thresholds tuned for that pace.

## Example

```
$ slop lint

slop 1.0.0 — scanning .

structural.complexity
  cyclomatic
    ✗ src/pipeline/ingest.py:44 process_batch — CCX 18 exceeds 10
    ✗ src/pipeline/ingest.py:112 _normalize_rows — CCX 14 exceeds 10
  cognitive
    ✗ src/pipeline/ingest.py:44 process_batch — CogC 26 exceeds 15
  6 violations, 142 checked

structural.hotspots (14 days ago)
  ✗ src/lifecycle/tasks/write.py — CCX=41, growth +556 LOC
  ✗ src/pipeline/transformation.py — CCX=45, growth +367 LOC
  2 violations

structural.packages
  ⚠ src/config — Zone of Pain (I=0.12, A=0.00)
  1 advisory

────────────────────────────────────────
8 violations | 1 advisory | 22 rules checked | FAIL
```

Exit `0` clean, `1` on violations, `2` on error. Works in CI, pre-commit, and interactively.

## Install

```bash
pip install agent-slop-lint
```

slop shells out to `rg`, `fd`, and `git`. Install via your system package manager (`apt install ripgrep fd-find git`, `brew install ripgrep fd git`, or equivalent) and run `slop doctor` to verify. Full per-platform steps, CI recipes, and pre-commit wiring are in the [setup guide](https://github.com/JordanGunn/agent-slop-lint/blob/main/docs/SETUP.md).

## Rules

slop ships 25 rules across three suites:

- **`structural.*`** — control-flow complexity, CK class metrics, hotspots, package distance, dependency cycles, duplication, god modules, type-discipline rules.
- **`information.*`** — Halstead volume and difficulty, magic literals, section-divider comments.
- **`lexical.*`** — identifier verbosity, tersity, and stutter against the enclosing scope.

The full rule index with default thresholds, citations, and per-rule pages lives in [`docs/rules/`](https://github.com/JordanGunn/agent-slop-lint/blob/main/docs/rules/README.md). For threshold tuning and the `default` / `lax` / `strict` profiles, see the [configuration reference](https://github.com/JordanGunn/agent-slop-lint/blob/main/docs/CONFIG.md).

## Languages

| Language | Complexity | Hotspots | Packages | Deps | Class |
|---|---|---|---|---|---|
| Python, JavaScript, TypeScript, Go, Java, C# | yes | yes | yes | yes | yes |
| Rust | yes | yes | yes | — | yes |
| Julia | yes | yes | yes | yes | — |

Language-specific caveats (JavaScript packages, Rust deps, Julia CK metrics and short-form functions) are documented in the [Julia notes](https://github.com/JordanGunn/agent-slop-lint/blob/main/docs/JULIA.md) and the relevant rule pages.

## CLI

```
slop lint                         Run all enabled rules
slop check <category|rule>        Run one category or rule
slop init [default|lax|strict]    Generate .slop.toml
slop doctor                       Check fd, rg, git are installed
slop hook                         Install a git pre-commit hook
slop skill <dir>                  Install the bundled agent skill
slop rules                        List rules with thresholds
slop schema                       Config schema as JSON
```

Output formats are `--output human` (default), `--output json` (CI and agents), and `--output quiet`. Run `slop --help` for the full flag list.

## Configuration

slop walks upward from CWD looking for `.slop.toml` first, then `pyproject.toml` with a `[tool.slop]` table — the same discovery ruff and mypy use. `root` resolves relative to the config file's directory. `--config` and `--root` on the CLI override both.

```bash
slop init          # balanced defaults
slop init lax      # legacy or gradual adoption
slop init strict   # greenfield or quality-focused
```

Every threshold, profile, and waiver mechanism is documented in the [configuration reference](https://github.com/JordanGunn/agent-slop-lint/blob/main/docs/CONFIG.md).

## Architecture

slop ships its own discovery primitives and metric kernels. Each rule is a thin wrapper that loads config, calls a deterministic kernel, and emits `Violation` objects for threshold breaches. Primitives are organised by substrate — `_fs` (fd), `_text` (ripgrep), `_ast` (tree-sitter) — with cross-tool primitives in `_compose` and metric kernels in `_structural` and `_lexical`. One `pip install` gives you the whole thing; no companion runtime.

## Acknowledgments

slop implements metrics from McCabe, Halstead, Chidamber & Kemerer, Nejmeh, Martin, Lakos, Tornhill, and Campbell. Full bibliography in [NOTICE](NOTICE). AI assistance and contributor credits in the [project CITATIONS](https://github.com/JordanGunn/agent-slop-lint/blob/main/CITATIONS.md).

## License

Apache 2.0. See [LICENSE](LICENSE).
