Metadata-Version: 2.4
Name: slopmop
Version: 1.0.2
Summary: Quality gates for AI-assisted codebases — catch the slop LLMs leave behind.
Author: ScienceIsNeato
License: Slop-Mop Attribution License v1.0
Project-URL: Homepage, https://github.com/ScienceIsNeato/slop-mop
Project-URL: Repository, https://github.com/ScienceIsNeato/slop-mop
Project-URL: Issues, https://github.com/ScienceIsNeato/slop-mop/issues
Project-URL: Changelog, https://github.com/ScienceIsNeato/slop-mop/releases
Keywords: quality-gate,linting,testing,ci-cd,code-quality,ai,llm,vibe-coding
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=1.0.0; python_version < "3.11"
Requires-Dist: packaging>=21.0
Provides-Extra: templates
Requires-Dist: jinja2>=3.0.0; extra == "templates"
Provides-Extra: lint
Requires-Dist: black>=26.3.1; extra == "lint"
Requires-Dist: isort>=5.12.0; extra == "lint"
Requires-Dist: autoflake>=2.0.0; extra == "lint"
Requires-Dist: flake8>=6.0.0; extra == "lint"
Requires-Dist: ruff>=0.1.0; extra == "lint"
Provides-Extra: typing
Requires-Dist: mypy>=1.17.0; extra == "typing"
Requires-Dist: pyright>=1.1.0; extra == "typing"
Provides-Extra: analysis
Requires-Dist: vulture>=2.14; extra == "analysis"
Requires-Dist: radon>=5.1.0; extra == "analysis"
Provides-Extra: security
Requires-Dist: bandit>=1.7.0; extra == "security"
Requires-Dist: detect-secrets>=1.4.0; extra == "security"
Requires-Dist: cryptography>=46.0.7; extra == "security"
Requires-Dist: pyasn1>=0.6.3; extra == "security"
Requires-Dist: requests>=2.33.0; extra == "security"
Requires-Dist: semgrep>=1.140.0; extra == "security"
Requires-Dist: pip-audit>=2.0.0; extra == "security"
Provides-Extra: testing
Requires-Dist: pytest>=9.0.3; extra == "testing"
Requires-Dist: pytest-cov>=4.0.0; extra == "testing"
Requires-Dist: pytest-testmon>=2.0.0; extra == "testing"
Requires-Dist: diff-cover>=7.0.0; extra == "testing"
Requires-Dist: jsonschema>=4.0.0; extra == "testing"
Provides-Extra: tools
Requires-Dist: slopmop[lint]; extra == "tools"
Requires-Dist: slopmop[typing]; extra == "tools"
Requires-Dist: slopmop[analysis]; extra == "tools"
Requires-Dist: slopmop[security]; extra == "tools"
Requires-Dist: slopmop[testing]; extra == "tools"
Requires-Dist: slopmop[templates]; extra == "tools"
Provides-Extra: all
Requires-Dist: slopmop[tools]; extra == "all"
Provides-Extra: dev
Requires-Dist: slopmop[all]; extra == "dev"
Dynamic: license-file

# 🪣 Slop-Mop

<p>
  <a href="https://github.com/ScienceIsNeato/slop-mop/actions/workflows/slopmop-sarif.yml"><img src="https://github.com/ScienceIsNeato/slop-mop/actions/workflows/slopmop-sarif.yml/badge.svg" alt="Primary code scanning gate"/></a>
  <a href="https://codecov.io/gh/ScienceIsNeato/slop-mop"><img src="https://codecov.io/gh/ScienceIsNeato/slop-mop/branch/main/graph/badge.svg" alt="Coverage"/></a>
  <a href="https://pypi.org/project/slopmop/"><img src="https://img.shields.io/pypi/v/slopmop.svg" alt="PyPI version"/></a>
  <a href="https://pypi.org/project/slopmop/"><img src="https://img.shields.io/pypi/pyversions/slopmop.svg" alt="Python versions"/></a>
  <a href="https://github.com/ScienceIsNeato/slop-mop/releases"><img src="https://img.shields.io/github/v/release/ScienceIsNeato/slop-mop?display_name=tag&amp;sort=semver" alt="Latest GitHub release"/></a>
  <a href="https://github.com/ScienceIsNeato/slop-mop/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Slop--Mop%20Attribution%20v1.0-blue.svg" alt="License"/></a>
</p>

Slop-mop is a quality gate runner for AI-assisted codebases.

<figure>
  <img src="https://raw.githubusercontent.com/ScienceIsNeato/slop-mop/main/assets/sm-swab-human-readable.png" alt="Human-readable sm swab output showing grouped quality gates and a no slop detected summary" />
  <figcaption>
    The default <code>sm swab</code> view is built for humans: grouped gates,
    progress, timings, and a clear final verdict. Agent loops can use
    <code>--porcelain</code> when they need terse output instead.
  </figcaption>
</figure>

It does not try to make agents smart. It gives them greased rails: a path of
least resistance toward more maintainable choices. Run the tool, read what
failed, fix that thing, run it again.

That is the whole idea.

Agents are good at closing the ticket in front of them. They are less good at
not leaving the codebase worse than they found it. Slop-mop looks for the mess
that still passes normal checks: shallow tests, duplicated logic, missing
coverage, complexity creep, stale config, unhandled PR feedback.

It is opinionated. Sometimes loudly. That is on purpose.

## Project Status

slop-mop has reached 1.0.0. The current public policy surface for release and
stability expectations lives here:

- [DOCS/COMPATIBILITY.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/COMPATIBILITY.md)
- [DOCS/MIGRATIONS.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/MIGRATIONS.md)
- [DOCS/RELEASING.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/RELEASING.md)
- [SECURITY.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/SECURITY.md)

## Quick Start

Install it:

```bash
pipx install slopmop[all]
```

Set up a repo:

```bash
sm init
```

Choose a starting point.

For an existing repo, start with refit. It walks the project through a
structured cleanup before you enter the day-to-day maintenance loop:

```bash
sm refit --start
sm refit --iterate
sm refit --finish
```

If you cannot do the full refit right now, generate a baseline as a temporary
escape hatch. That keeps new failures loud while you come back to the cleanup:

```bash
sm status --generate-baseline-snapshot
sm swab --ignore-baseline-failures
```

Run the normal loop:

```bash
sm swab
```

If it fails, fix what it reported and run `sm swab` again. When it passes,
commit. Before opening or updating a PR, run the deeper pass:

```bash
sm scour
```

After CI or review feedback lands:

```bash
sm buff
```

If you are not sure what comes next, use the auto-advance command:

```bash
sm sail
```

It reads the current workflow state and runs the next obvious slop-mop verb.

## The Loop

Slop-mop has five verbs you will actually use:

| Verb | What it is for | When to run it |
| --- | --- | --- |
| `sm status` | Workflow state and baseline snapshots | When you need current state or a temporary baseline |
| `sm swab` | Code-centric local feedback | After meaningful code changes |
| `sm scour` | Code-centric pre-PR sweep | Before opening or updating a PR |
| `sm buff` | Process-centric CI and review follow-up | After CI completes or review feedback lands |
| `sm sail` | Process-centric next-step selection | When you are not sure what to do next |

The boring version:

```text
write code -> sm swab -> commit -> sm scour -> push/open PR -> sm buff
```

The workflow state machine is documented in [DOCS/WORKFLOW.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/WORKFLOW.md).

## What It Checks

Slop-mop groups gates around four common agent failure modes.

**Overconfidence**  
Code exists, but is it tested? Typed? Covered? This catches missing tests,
coverage gaps, and type-checking blind spots.

**Deceptiveness**  
Tests pass, but do they prove anything? This catches bogus tests, debugger
artifacts, and other signs that the repo only looks clean.

**Laziness**  
The code works, but it is starting to rot. This catches complexity creep, dead
code, formatting drift, repeated code, stale docs, and silenced gates.

**Myopia**  
The local change looks fine, but the repo-wide picture is worse. This catches
duplication, security issues, dependency risk, and similar cross-cutting mess.

The full gate reasoning lives in [DOCS/GATE_REASONING.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/GATE_REASONING.md).

## Refit vs Maintenance

There are two modes.

Use **refit** first when a repo is already dirty and you need a structured
cleanup plan:

```bash
sm refit --start
sm refit --iterate
sm refit --finish
```

Use **maintenance** once the repo is in decent shape:

```bash
sm swab
sm scour
sm buff
```

Refit is the first-class onboarding path. Baseline mode is secondary: use it
only to unblock yourself temporarily when you cannot run the full refit yet.
Maintenance is the day-to-day loop after the repo is in decent shape.

## Minimal Install

If you only want the framework without optional gate dependencies:

```bash
pipx install slopmop
```

Minimal install gives you the framework. Gates that need tools like `black`,
`pyright`, `bandit`, or `pytest` will tell you what is missing.

Developer setup details live in [DOCS/DEVELOPING.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/DEVELOPING.md).

## Configuration

`sm init` writes `.sb_config.json` after looking at the repo. It enables gates
that appear relevant and leaves non-applicable gates alone.

Useful commands:

```bash
sm config --show
sm config --enable myopia:vulnerability-blindness.py
sm config --disable laziness:complexity-creep.py
```

Disabling a gate should be temporary. If a gate is wrong, tune it or file the
tooling bug. If the repo is not ready yet, use refit first. Use baseline mode
only as a short-term unblocker when refit is not practical in the moment.

Migration behavior is documented in [DOCS/MIGRATIONS.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/MIGRATIONS.md).

## Baselines

Sometimes you inherit a repo that is already messy and cannot stop for a full
refit. Slop-mop can snapshot the current failures so new failures stay loud
while old ones get paid down.

```bash
sm status --generate-baseline-snapshot
sm swab --ignore-baseline-failures
sm scour --ignore-baseline-failures
```

This is not a way to hide problems or skip refit. It is a temporary unblocker:
stop old problems from blocking every unrelated change, then come back and clean
them up deliberately.

## CI

Run slop-mop in CI the same way you run it locally: install it and run the gate
command.

See [DOCS/CI.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/CI.md) for a GitHub Actions template.

## Agent Setup

Slop-mop can install repo-local agent instructions for common coding agents:

```bash
sm agent install
```

You can target one agent if you prefer:

```bash
sm agent install --target copilot
sm agent install --target cursor
sm agent install --target claude
```

Generated agent files are local workspace configuration. They should stay out
of source control; the reusable source templates live in this repository under
`slopmop/agent_install/templates/`.

The short version for agents: ride the rail, fix what it reports, do not bypass
the gate.

## Custom Gates

Slop-mop's CI framework is well adapted to existing checks that are not covered
by built-in gates. Add your own check as a custom gate and manage it like any
other slop-mop quality gate.

Start with [DOCS/NEW_GATE_PROTOCOL.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/NEW_GATE_PROTOCOL.md).

## When To Push Back On The Tool

Sometimes slop-mop is wrong.

That is useful information. Do not route around it with ad-hoc commands and
pretend the rail is fine. Fix the gate, tune the config, or file the bug. The
point is not obedience. The point is making the correct workflow easier than the
wrong one.

For slop-mop tooling friction, start with:

```bash
sm barnacle --help
```

## Contributing

For repo conventions, see [DOCS/CONVENTIONS.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/CONVENTIONS.md).

For contribution guidance, see [DOCS/CONTRIBUTING.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/CONTRIBUTING.md).

For local development, see [DOCS/DEVELOPING.md](https://github.com/ScienceIsNeato/slop-mop/blob/main/DOCS/DEVELOPING.md).

## License

Slop-mop uses the [Slop-Mop Attribution License v1.0](https://github.com/ScienceIsNeato/slop-mop/blob/main/LICENSE).

If you use it, attribution is required.
