SlopSniff

A lightweight CLI for catching code-quality drift ("slop") before it hardens into team-wide tech debt.

Quick Start

# One-off run
npx slopsniff-cli .

# or install locally
npm i -D slopsniff-cli

{
  "scripts": {
    "slopsniff": "slopsniff .",
    "slopsniff:branch": "slopsniff . --branch",
    "slopsniff:strict": "slopsniff . --fail-threshold 0 --format json"
  }
}

# install in your Python project
uv add --dev slopsniff
# or: pip install slopsniff

# run in your project
slopsniff .
# only files changed vs main (git diff)
slopsniff . --branch
# optional strict mode
slopsniff . --fail-threshold 0 --format json

Notes:

• The npm package is a wrapper around the Python CLI.
• It runs slopsniff via uv tool run --from slopsniff ....
• On macOS/Linux, it will attempt to install uv automatically if missing.
• Commit a slopsniff.json in your project root to configure rules and exclusions.

What it catches

timeout = os.getenv("TIMEOUT", 0)

const retries = process.env.RETRIES || 0;

timeout = require_env("TIMEOUT")

const retries = requireEnv("RETRIES");

except Exception:
    return []

catch (e) { return null; }

except TimeoutError:
    logger.warning("upstream timeout")
    raise

catch (e) {
  if (e instanceof RateLimitError) { ... }
  throw e;
}

API_KEY = "sk-proj-abc123..."

API_KEY = os.environ["API_KEY"]

scanner.py — 800+ lines
def do_everything(): — 120 lines

scanner.py — focused orchestrator
def scan(): — delegates to helpers

utils.py:  def format_date(d): ...
helpers.py: def format_date(d): ...  # identical

dates.py: def format_date(d): ...  # single source

utils.py, helpers.py, common.py
send_email_v2(), format_data_old()

email_service.py, formatters.py
send_email(), format_data()

Local Setup (Open Source Dev)

git clone https://github.com/joshuagilley/slopsniff
cd slopsniff
uv sync --dev
pre-commit install

Quick sanity run:

uv run pytest
uv run ruff check .
env PYTHONPATH=src uv run python -m slopsniff.cli . --fail-threshold 30

Notes:

• Pre-commit runs ruff, ruff-format, slopsniff, and pytest.
• Default terminal output is compact and Rich-colored: one summary line (files, issue count, score, status), then findings grouped by directory and file (paths relative to the current working directory when possible). Use --format json for machine output.
• For local runs, prefer env PYTHONPATH=src uv run python -m slopsniff.cli ....

Basic Usage

# Scan current directory
env PYTHONPATH=src uv run python -m slopsniff.cli .

# Scan a specific path
env PYTHONPATH=src uv run python -m slopsniff.cli ./src

# JSON output for CI/machines
env PYTHONPATH=src uv run python -m slopsniff.cli . --format json

# Override thresholds ad hoc
env PYTHONPATH=src uv run python -m slopsniff.cli . --max-file-lines 300 --max-function-lines 40

# Only files changed vs main (git diff main --name-only --diff-filter=ACMR, then normal include/exclude rules)
env PYTHONPATH=src uv run python -m slopsniff.cli . --branch
env PYTHONPATH=src uv run python -m slopsniff.cli . --changed-since origin/main

--branch is a shortcut for --changed-since main. The scan root must sit inside a git work tree. Untracked files are not included until they are committed or staged in a way that shows up in that diff (same as plain git diff <ref>).

Terminal vs JSON: default output is human-oriented and grouped as above; pass --format json for CI or tooling. Use --verbose to print each finding’s score contribution.

Configuration (slopsniff.json)

SlopSniff auto-loads slopsniff.json from the scan root (the path you pass to slopsniff). You can tune scoring thresholds, file selection, and enabled rules in one place.

Example:

{
  "fail-threshold": 20,
  "max-file-lines-warning": 400,
  "max-file-lines-high": 800,
  "max-function-lines-warning": 50,
  "max-function-lines-high": 100,
  "verbose": false,
  "include-extensions": [".py", ".js", ".ts", ".tsx", ".jsx", ".vue", ".html"],
  "large-file-extensions": [".py", ".js", ".ts", ".tsx", ".jsx", ".vue"],
  "exclude-files": ["temp_slop_examples.py", "src/fixtures/example.py"],
  "exclude-severities": ["low"],
  "exclude-dirs": [".git", "node_modules", ".venv", "tests", "dist", "build"],
  "include": [
    "fallback-defaults",
    "exposed-secrets",
    "large-function",
    "large-file",
    "duplicate-functions",
    "helper-sprawl"
  ]
}

Rule IDs for include:

• fallback-defaults
• exposed-secrets
• large-function
• large-file
• duplicate-functions
• helper-sprawl

File and function size (line counts)

These keys control the large-file and large-function rules (line counts include the whole file or function body).

Raise the warning thresholds when large components or test files are normal for your repo (for example "max-file-lines-warning": 750 so a 592-line file is below the warning cutoff). CLI flags --max-file-lines and --max-function-lines still override only the warning thresholds for a one-off run.

Notes:

• CLI flags still work and override file values (for example, --fail-threshold).
• If include is omitted, all rules run.
• exclude-files accepts either bare filenames or scan-root-relative paths.
• exclude-severities is an array of low, medium, and/or high; matching findings are dropped from output and from the total score (case-insensitive).
• Unknown keys and unknown rule IDs fail fast with clear errors.

Contributing and Commits

Standard flow:

1. Create a feature branch from main.
2. Make changes.
3. Run checks locally:

   uv run pytest
   uv run ruff check .
   env PYTHONPATH=src uv run python -m slopsniff.cli . --fail-threshold 30
   

4. Commit with a clear message.
5. Open a PR and merge after CI passes.

Release Process

Publishing is handled by .github/workflows/publish.yml. It runs on GitHub Release published (not on tag push alone).

Recommended: one-command release script

From repo root, on main, with a clean working tree:

./scripts/release.py 0.1.9
# or:
uv run python scripts/release.py v0.1.9

What it does:

1. Pulls main.
2. Bumps version in pyproject.toml and src/slopsniff/__init__.py.
3. Runs uv lock.
4. Commits chore: release X.Y.Z.
5. Pushes main.
6. Tags vX.Y.Z and pushes the tag.
7. Creates/publishes a GitHub release with gh release create.

Useful flags:

• --dry-run
• --no-pull
• --allow-dirty
• --notes-file PATH
• --expect-repo OWNER/REPO

Optional guard:

• Set SLOPSNIFF_RELEASE_EXPECT_REPO=joshuagilley/slopsniff to prevent accidental release from a fork clone.

If release/publish fails

• HTTP 400 from PyPI: that version already exists; bump to a new version and release again.
• HTTP 422 from gh release create: release already exists for that tag. Re-run workflow for that release if needed.
• Re-running old releases uses the same tagged commit; it does not pick up newer main.

Minimal Architecture Notes

Pipeline:

1. Walk repo (or, with --changed-since / --branch, only paths from git diff) and collect included files.
2. Parse functions (ast for Python, heuristic parser for JS/TS/TSX/JSX/Vue).
3. Run per-file rules.
4. Run cross-file rules.
5. Aggregate findings and score.
6. Report (compact Rich terminal or json) and exit non-zero on threshold fail.

Key paths:

• src/slopsniff/cli.py — CLI entrypoint
• src/slopsniff/scanner.py — orchestration
• src/slopsniff/rules/ — rule implementations
• src/slopsniff/reporters/ — terminal/json output
• scripts/release.py — scripted release flow