slopcheck-lint 0.1.0__tar.gz

slopcheck_lint-0.1.0/.agents/skills/slopcheck/SKILL.md

@@ -0,0 +1 @@
+../../../skills/slopcheck/SKILL.md

slopcheck_lint-0.1.0/.claude/skills/slopcheck/SKILL.md

@@ -0,0 +1 @@
+../../../skills/slopcheck/SKILL.md

slopcheck_lint-0.1.0/.cursor/skills/slopcheck/SKILL.md

@@ -0,0 +1 @@
+../../../skills/slopcheck/SKILL.md

slopcheck_lint-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,34 @@
+name: Bug
+description: A rule misfired, a score looks wrong, or a command failed
+title: "SLPxxx: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: Include the rule id, the file, and the score if you have one.
+    validations:
+      required: true
+  - type: textarea
+    id: code
+    attributes:
+      label: Smallest Python snippet
+      description: Ten lines that reproduce it. Strip secrets.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: slopcheck version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true

slopcheck_lint-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

slopcheck_lint-0.1.0/.github/ISSUE_TEMPLATE/rule.yml

@@ -0,0 +1,29 @@
+name: Rule idea
+description: A pattern agents keep leaving that slopcheck should flag
+title: "Rule: "
+labels: ["rule"]
+body:
+  - type: textarea
+    id: pattern
+    attributes:
+      label: The pattern
+      description: Show the messy version and the version you want to keep.
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why Ruff or Pylint does not already cover it
+    validations:
+      required: true
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Suggested severity
+      options:
+        - error
+        - warning
+        - note
+    validations:
+      required: true

slopcheck_lint-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## What
+
+## Why
+
+## Check
+
+- [ ] `pytest`
+- [ ] `slopcheck .` still scores 100
+- [ ] README rule table updated if a rule id changed

slopcheck_lint-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: pytest
+      - name: Dogfood
+        run: slopcheck .

slopcheck_lint-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/slopcheck-lint
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag matches package version
+        run: |
+          python - << 'PY'
+          import os
+          import pathlib
+          import re
+          import sys
+
+          text = pathlib.Path("src/slopcheck/version.py").read_text(encoding="utf-8")
+          match = re.search(r'__version__ = "([^"]+)"', text)
+          version = match.group(1) if match else ""
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          if version != tag:
+              sys.exit(f"tag {tag} does not match package {version}")
+          PY
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

slopcheck_lint-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+env/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+*.log
+.DS_Store

slopcheck_lint-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,9 @@
+- id: slopcheck
+  name: slopcheck
+  description: Flag AI-agent slop in Python
+  entry: slopcheck
+  language: python
+  language_version: python3
+  types_or: [python, pyi]
+  pass_filenames: true
+  minimum_pre_commit_version: "3.2.0"

slopcheck_lint-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-10-26
+
+First release.
+
+- Published on PyPI as `slopcheck-lint`, because `slopcheck` on PyPI belongs to another project. The CLI command and the import package are `slopcheck`: `pip install slopcheck-lint`, then run `slopcheck`.
+- Fifteen rules, `SLP001` through `SLP015`, and a Slop Score from 0 to 100.
+- Terminal, JSON, SARIF, HTML, SVG badge, and an agent fix prompt.
+- Config in `[tool.slopcheck]`, inline `# slopcheck: ignore`.
+- pre-commit hook, GitHub Action, and a skill for Claude Code, Codex, and Cursor.
+- Python 3.10 through 3.13.

slopcheck_lint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Issues and pull requests go to [yungcs/slopcheck](https://github.com/yungcs/slopcheck).
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pytest
+slopcheck .
+```
+
+`slopcheck .` has to score 100. The demo and the test fixtures are excluded on purpose. Scan them by passing the path: `slopcheck demo`.
+
+Python 3.10 through 3.13. CI runs that matrix.
+
+## A new rule
+
+1. Add `SLP0xx` in `src/slopcheck/rules/`, and register it in `src/slopcheck/rules/__init__.py`.
+2. Add `tests/fixtures/sloppy/SLP0xx_*.py` that the rule flags, and a case in `tests/test_rules.py` for something it must keep.
+3. Put the id in both `README.md` and `README.zh-CN.md`.
+4. Keep the tool's own tree clean. Do not silence a rule to hide a hit in `src/`.
+
+Rule ids are stable. Do not renumber one that has shipped.
+
+## Pictures
+
+```bash
+python scripts/render_assets.py    # SVG terminal, badge, HTML sample
+python scripts/render_launch.py    # hero, GIF, report shot, before/after, social card
+```
+
+`render_launch.py` needs Pillow (installed with `.[dev]`) and ffmpeg. The GIF is built from a real `slopcheck demo` run (score 29) and a fixed tree tuned to score 94. Headless Chrome takes `docs/report.png`. If Chrome stays open after writing the PNG, the script stops it.
+
+`docs/social-preview.png` is 1280×640 for the GitHub social preview setting. It is not embedded in the README.
+
+## Releasing
+
+Tag `vX.Y.Z` only when `src/slopcheck/version.py` has the same version. [`.github/workflows/release.yml`](.github/workflows/release.yml) publishes to PyPI with trusted publishing.
+
+The PyPI distribution is `slopcheck-lint` (the CLI command and import name stay `slopcheck`). On PyPI, add this GitHub repo as a trusted publisher for the `slopcheck-lint` project:
+
+- Owner: `yungcs`
+- Repository: `slopcheck`
+- Workflow: `release.yml`
+- Environment: `pypi`
+
+The GitHub environment named `pypi` needs the `id-token: write` permission the workflow already requests.

slopcheck_lint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 slopcheck contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slopcheck_lint-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.5
+Name: slopcheck-lint
+Version: 0.1.0
+Summary: A linter for the mess AI coding agents leave in Python.
+Project-URL: Homepage, https://github.com/yungcs/slopcheck
+Project-URL: Repository, https://github.com/yungcs/slopcheck
+Project-URL: Issues, https://github.com/yungcs/slopcheck/issues
+Project-URL: Changelog, https://github.com/yungcs/slopcheck/blob/main/CHANGELOG.md
+Author: slopcheck contributors
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,cli,codex,cursor,linter,python,sarif,slop,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pillow>=10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center"><strong>English</strong> · <a href="README.zh-CN.md">简体中文</a></p>
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/hero-dark.png">
+    <img src="docs/hero-light.png" alt="slopcheck — A linter for the mess AI agents leave in Python" width="820">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/slopcheck-lint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/slopcheck-lint?label=pypi"></a>
+  <a href="https://github.com/yungcs/slopcheck/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/yungcs/slopcheck/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <img alt="Python 3.10 through 3.13" src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776AB">
+  <img alt="Slop Score 100" src="docs/slop-score.svg">
+</p>
+
+<p align="center"><strong>One command. A score from 0 to 100. Higher is cleaner.</strong></p>
+
+<p align="center">
+  <img src="docs/demo.gif" alt="uvx --from slopcheck-lint slopcheck demo scores 29, slopcheck prompt, then a fixed tree scores 94" width="720">
+</p>
+
+Ruff and Pylint will not catch this. Agents still ship it: a bare `except`, `import requets`, a `_v2` twin, a `breakpoint()` left in the fetch path. slopcheck flags that residue and hands the findings to Claude Code, Codex, or Cursor.
+
+## Install in 5 seconds
+
+```bash
+uvx --from slopcheck-lint slopcheck .
+```
+
+```bash
+pipx install slopcheck-lint
+```
+
+```bash
+pip install slopcheck-lint
+```
+
+The PyPI package is `slopcheck-lint`; the command it installs is `slopcheck`, and the import name stays `slopcheck`.
+
+Python 3.10 or newer. From a checkout of this repo: `pip install -e ".[dev]"`.
+
+## Quick start
+
+```bash
+slopcheck .                         # terminal report and a Slop Score
+slopcheck . --format sarif -o slopcheck.sarif
+slopcheck prompt . > fix.md         # paste into Claude Code, Codex, or Cursor
+slopcheck . --fix-with-agent
+```
+
+The bundled demo is the messy tree in the GIF. It ends at `20 findings · score 29 · fail`. The plain transcript is [`docs/demo.txt`](docs/demo.txt). `demo/taskflow/ok.py`, scanned alone, scores 100.
+
+An error weighs 8, a warning 4, a note 2. `budget = lines / 5`, and the score is `round(100 * budget / (budget + raw))`. No findings is 100. A 200-line project with five errors scores 50.
+
+| Score | Label |
+| --- | --- |
+| 90–100 | clean |
+| 75–89 | light residue |
+| 50–74 | needs a wash |
+| 25–49 | sloppy |
+| 0–24 | hazardous sludge |
+
+Exit `0` when nothing error-or-warning remains and the score clears `--min-score`. Exit `1` for findings, parse errors, or a score under the minimum. Exit `2` for bad arguments. Notes alone do not fail the process unless `min-score` says they do. `--exit-zero` always exits 0.
+
+## Why
+
+Agents write code that looks finished and fails quietly. Ruff is the fast linter (it will flag a bare `except` as E722). Pylint has its own score. Neither one is looking for the residue around that `except`.
+
+| Pattern | Ruff / Pylint | slopcheck |
+| --- | --- | --- |
+| `except KeyError: return {}` | no | SLP003 |
+| `import requets` | no | SLP010 |
+| `summarize_tasks_v2` next to `summarize_tasks` | no | SLP007, SLP013 |
+| `# increment index` above `index += 1` | no | SLP004 |
+| `print(f"{tasks=}")` and `breakpoint()` | not by default | SLP005 |
+
+Run both. Ruff formats and finds bugs. slopcheck is the pass after the agent.
+
+<p align="center">
+  <img src="docs/before-after.png" alt="Before and after for a bare except, a hallucinated import, and a _v2 function" width="820">
+</p>
+
+## Rules
+
+| ID | Sev | What a tiny example looks like |
+| --- | --- | --- |
+| SLP001 | error | `except:` then `pass` |
+| SLP002 | error | `except Exception: return None` |
+| SLP003 | error | `except KeyError: return {}` |
+| SLP004 | note | `# increment index` |
+| SLP005 | warning | `print(f"{tasks=}")`, `breakpoint()` |
+| SLP006 | warning | `def _helper(): ...` and nothing calls it |
+| SLP007 | warning | a second function with the same shape |
+| SLP008 | note | `name = "ada"` then `if name is not None` |
+| SLP009 | warning | `def export_tasks(): pass` |
+| SLP010 | error | `import requets` |
+| SLP011 | warning | `try` inside `try` inside `try` |
+| SLP012 | note | an essay docstring on `return len(tasks)` |
+| SLP013 | warning | `def summarize_tasks_v2` |
+| SLP014 | note | `# status = "archived"` |
+| SLP015 | warning | `return "Error: failed to fetch title"` |
+
+`slopcheck rules` prints the hint that ships with each finding.
+
+Left alone on purpose: a comment that says why, `print(f"tasks={tasks}")` (the flagged form is `f"{tasks=}"`), imports inside `except ImportError`, abstract methods, `Protocol`, `.pyi` files, and `return False` from `__exit__`.
+
+Silence a line with `# slopcheck: ignore[SLP003]`. A comment-only line applies to the next line of code. `# slopcheck: disable` covers the rest of the file until `# slopcheck: enable`.
+
+```toml
+[tool.slopcheck]
+exclude = ["demo/**", "tests/fixtures/**"]
+ignore = ["SLP004"]
+min-score = 90
+
+[tool.slopcheck.rules.SLP010]
+allowed_modules = ["pytest"]
+```
+
+`--select` replaces the config selection. `--ignore` is added on top. This repo sets `min-score = 100` and excludes the demo, so `slopcheck .` fails on any finding. `slopcheck demo` opts that path back in.
+
+<p align="center">
+  <img src="docs/report.png" alt="HTML report for the demo, score 29, with filters and the first findings" width="760">
+</p>
+
+`slopcheck . --format html -o report.html` writes one file. No network requests. The same run as JSON, SARIF 2.1.0, or an SVG badge: `slopcheck badge . -o slop-score.svg`.
+
+## Use with Claude Code, Codex, and Cursor
+
+```bash
+slopcheck prompt . > fix.md
+```
+
+The prompt says: keep behavior, raise instead of returning a dummy, do not silence rules to inflate the score, then run slopcheck again.
+
+The skill is [`skills/slopcheck/SKILL.md`](skills/slopcheck/SKILL.md). The same file is linked from `.claude/skills`, `.cursor/skills`, and `.agents/skills`.
+
+Claude Code can lint after each edit. Copy [`examples/hooks/slopcheck.sh`](examples/hooks/slopcheck.sh) and the matcher in [`examples/hooks/claude-code.settings.json`](examples/hooks/claude-code.settings.json).
+
+## CI, pre-commit, GitHub Action
+
+pre-commit, once `v0.1.0` is tagged:
+
+```yaml
+repos:
+  - repo: https://github.com/yungcs/slopcheck
+    rev: v0.1.0
+    hooks:
+      - id: slopcheck
+```
+
+GitHub Action, with SARIF upload for code scanning:
+
+```yaml
+- uses: yungcs/slopcheck@v0.1.0
+  with:
+    path: .
+    upload-sarif: "true"
+```
+
+The action is [`action.yml`](action.yml). A full workflow is [`examples/workflows/slopcheck.yml`](examples/workflows/slopcheck.yml). CI for this repo runs pytest and `slopcheck .` on Python 3.10–3.13.
+
+## Comparison
+
+| | slopcheck | Ruff | Pylint | eslint-plugin-slop |
+| --- | --- | --- | --- | --- |
+| Language | Python | Python | Python | TypeScript |
+| Fake fallback `return {}` | yes | no | no | no |
+| Hallucinated import | yes | no | no | no |
+| Near-duplicate `_v2` | yes | no | no | no |
+| Narrating comments | yes | no | no | no |
+| Score meant for agents | 0–100 | no | 0–10, different job | no |
+| Fix prompt | yes | no | no | no |
+| SARIF | yes | yes | no | via ESLint |
+| Replaces the others | no | no | no | different language |
+
+[eslint-plugin-slop](https://github.com/antfu/eslint-plugin-slop) is the TypeScript cousin. [no-ai-slop](https://github.com/petergyang/no-ai-slop) edits prose. [hallmark](https://github.com/Nutlope/hallmark) lints interface. This one is for Python.
+
+## FAQ
+
+**Does this replace Ruff?** No. Turn Ruff on. Add slopcheck for the residue Ruff is not built to name.
+
+**Will it call my code AI-written?** No. It flags patterns. Humans write `except: pass` too.
+
+**A note failed my build.** Notes weigh 2 points. They fail the process only when the score drops under `--min-score`. This repo uses 100, so a note fails `slopcheck .`.
+
+**How do I keep a false positive?** `# slopcheck: ignore[SLP010]` on the line, or `allowed_modules` for an extra that is not installed here.
+
+**Which Python?** 3.10, 3.11, 3.12, and 3.13.
+
+## Roadmap
+
+- Safe edits for narrating comments, commented-out code, and debug leftovers.
+- A baseline file, so a dirty tree can ratchet forward.
+- An LSP, so the score shows up while the agent is still typing.
+- Hallucinated keyword arguments.
+- A plugin API for rules that only make sense in one codebase.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). `pytest` and `slopcheck .` should both be clean before you open a PR. The changelog is [CHANGELOG.md](CHANGELOG.md).
+
+## Star history
+
+<p align="center">
+  <a href="https://star-history.com/#yungcs/slopcheck&Date">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=yungcs/slopcheck&type=Date&theme=dark">
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=yungcs/slopcheck&type=Date">
+      <img alt="Star history of yungcs/slopcheck" src="https://api.star-history.com/svg?repos=yungcs/slopcheck&type=Date">
+    </picture>
+  </a>
+</p>
+
+## License
+
+[MIT](LICENSE)