Metadata-Version: 2.4
Name: sloptools
Version: 0.2.0
Summary: Deterministic code-quality tools for Python codebases: sloptrace (complexity erosion over git history).
Author: sjtechdev
License-Expression: MIT
Project-URL: Homepage, https://github.com/sjtechdev/sloptools
Project-URL: Repository, https://github.com/sjtechdev/sloptools
Project-URL: Issues, https://github.com/sjtechdev/sloptools/issues
Keywords: complexity,code-quality,static-analysis,technical-debt,ai-generated-code
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: radon>=6.0
Requires-Dist: complexipy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# sloptools

Deterministic code-quality tools for Python codebases. Everything is computed
from the source with plain AST analysis (no LLM), so the same code always
gives the same results.

| Tool | What it does |
|---|---|
| [`sloptrace`](#sloptrace) | Measures whether a codebase is getting messier, and tracks it over git history. |

Formerly published as `sloptrace`; that package now just installs `sloptools`.

## Install

```bash
pip install sloptools
```

Requires Python 3.9+.

## sloptrace

Is your Python codebase getting messier? sloptrace measures it, and tracks how
the numbers change over your git history.

It reports four things:

| Metric | What it tells you |
|---|---|
| **Erosion** | How much of your code's complexity is concentrated in a few huge functions, plus a ranked list of those functions. Watch the trend, not the absolute value. |
| **Clones** | Copy-pasted functions and code blocks, with `file:line` for each copy. |
| **Repeated literals** | Strings or lists of literals repeated across the code; usually a missing constant. |
| **Import cycles** | Modules that import each other and can't be understood on their own. |

The approach is adapted from the SlopCodeBench paper (Orlanski et al., 2025).

### Usage

```bash
sloptrace .                                  # analyse the current checkout
sloptrace /path/to/repo --history            # ...and how it changed over git history
sloptrace . --history --every 20 --max-commits 15   # sample every 20th commit, at most 15
sloptrace . --history --since 2024-01-01 -o out.json
sloptrace . --show-literals                  # also list repeated literals (noisy, off by default)
sloptrace --help                             # all options
```

Which files are scanned: in a git repo, everything tracked or untracked but
not ignored; otherwise the whole directory tree. Tests, docs, build output,
virtualenvs and vendored code are skipped by default; change that with
`--exclude`.

### Docs

[Metric reference](docs/metrics.html): the exact formula and a worked example
for each metric.

### Compared to scb-check

The paper's authors also publish [`scb-check`](https://pypi.org/project/scb-check/).
It supports many languages and flags code with lots of pattern rules.
sloptrace only handles Python, but gives you evidence (which functions, which
copies) and trends over history.

Its erosion number won't exactly match the paper's: the two tools count
branches slightly differently, so don't compare absolute values with the
paper's published baselines.

## Development

```bash
git clone https://github.com/sjtechdev/sloptools.git
cd sloptools
pip install -e ".[test]"
pytest
```
