agent-slop-lint 1.0.0

Agentic code quality linter — catches slop before it becomes architectural rot

slop

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

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

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.

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/. For threshold tuning and the default / lax / strict profiles, see the configuration reference.

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

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.

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. AI assistance and contributor credits in the project CITATIONS.

License

Apache 2.0. See LICENSE.