bloatcheck 0.1.2
Static analysis for Python bloat and code smells.
Requires Python: >=3.10
Keywords: static-analysis, code-quality, technical-debt, maintainability, python

# bloatcheck

bloatcheck is a small, deterministic static analysis tool for Python repositories.
It focuses on signals that quietly erode codebases: dead code candidates,
duplicate logic, silent exceptions, and growing complexity.

It is designed for day-to-day use and agent-friendly workflows: fast to run,
predictable output, and stable fingerprints for baselines.

## What it checks

- Dead code candidates (including test-only references)
- Exact and near-duplicate function bodies
- Silent exception handlers
- Function size, complexity, nesting, and signature limits
- Structural smells (large modules, flat namespaces)
- TODO/FIXME markers

## Quick start

Project name: `bloatcheck` (GitHub repo: `py-bloatcheck`).

Install from PyPI:

```bash
pip install bloatcheck
```

Install from the repo:

```bash
git clone https://github.com/egecemkirci/py-bloatcheck.git
cd py-bloatcheck
uv pip install -e .
```

Run it on a repo and get a quick summary:

```bash
bloatcheck --repo-root . --json -
```

## Run (installed)
```bash
bloatcheck --repo-root . --json -
python -m bloatcheck --repo-root .
bloatcheck --version
```

## Run as submodule

```bash
python tools/bloatcheck/run.py --repo-root . --json tmp/bloatcheck.json
python tools/bloatcheck/run.py --repo-root . --update-baseline
```

## Configuration

In `pyproject.toml`:

```toml
[tool.bloatcheck]
src_dirs = ["src"]
test_dirs = ["tests"]
extra_dirs = ["scripts"]
exclude_globs = ["**/.venv/**", "**/__pycache__/**", "**/node_modules/**"]

[tool.bloatcheck.thresholds]
long_function_lines = 50
cyclomatic_complexity = 10
nesting_depth = 4
param_count = 5
god_class_methods = 15
large_module_lines = 600
flat_module_count = 10
near_duplicate_similarity = 0.9

[tool.bloatcheck.baseline]
path = "bloatcheck_baseline.json"
mode = "regressions"
fail_on = ["error"]
```

## Baseline

Run with `--update-baseline` to create or refresh the baseline. In regressions mode, only active issues fail the run. In `all` mode, baselined issues still fail.

## Metrics

Metrics are collected on demand and included in JSON output when `--json` is used.

Available metrics:

- SLOC and comment density
- Cyclomatic complexity totals and averages
- Halstead measures
- Maintainability index
- Coupling fan-in/fan-out
- Dependency instability (afferent/efferent)
- Cohesion (LCOM-style)
- Data-flow (def/use overlap)
- Risk score (instability × complexity)
- Function-level metrics (SLOC, CC, Halstead, MI)

Example:

```bash
bloatcheck --repo-root . --metrics
bloatcheck --repo-root . --metrics-json -
```

## Suppressions

Use inline directives:

```
# audit: ignore[DEAD001]
# audit: ignore[DEAD001, DUP001] reason: legacy code
# audit: ignore-file[TD001] reason: legacy module
```

## CI example

```bash
python tools/bloatcheck/run.py --repo-root . --json tmp/bloatcheck.json
```

## Structure rules

- `STR001`: large module (line count over threshold)
- `STR002`: flat module namespace (too many top-level modules)

## Project layout

```
bloatcheck/
  analysis/      # shared analysis helpers
  core/          # config, index, schema, baseline, suppress, util
  metrics/       # quantitative metrics collectors
  reporting/     # report rendering and JSON assembly
  rules/         # issue rules
```

## Development

```bash
uv pip install -e .[dev]
pre-commit install
```

## Contributing

See `CONTRIBUTING.md` for development workflow and guidelines.

## Security

See `SECURITY.md` for reporting vulnerabilities.

## Docs

- `docs/architecture.md`
- `docs/metrics.md`

## Code of Conduct

See `CODE_OF_CONDUCT.md` for expected community behavior.