toobig 0.1.0

Keep source files small enough for humans and coding agents

toobig

toobig is a fast, dependency-free line-limit linter for any text-based source language. It applies graduated thresholds so a file can become visible before it becomes a hard failure.

Small files are easier for people to review, navigate, test, and refactor. They also fit more readily into the context windows used by coding agents and LLM tools, leaving more room for the task, related code, and test output. toobig turns that shared maintainability constraint into a simple, automatable check.

Quick start

Install the toobig command with uv:

uv tool install toobig

Or install it with pipx or pip:

pipx install toobig
# or, inside a virtual environment
python -m pip install toobig

Scan Python files under src/, failing when any file exceeds 1,000 lines:

toobig src 1000 850 700

The three limits are the hard, warning, and informational thresholds, in that order. The default include pattern is *.py.

Usage

toobig [-v]... [--include GLOB]... [--files-only] DIRECTORY LINE_LIMIT WARNING_LIMIT INFO_LIMIT

Patterns match file basenames and can be repeated. The scan is recursive, includes hidden files, and does not follow symlinks or apply .gitignore rules.

For a Python project:

toobig src 1000 850 700
toobig --include '*.py' --include '*.pyi' src 1000 850 700

For a Rust project:

toobig --include '*.rs' crates 800 650 500

Use -v to include OK lines for files below every threshold. Use -vv for additional diagnostics about the scan. Line counts follow wc -l: they count newline characters, so a final line without a trailing newline is not counted.

Threshold semantics

Threshold comparisons are strict. A file exactly at a threshold does not enter that threshold's category.

File length	Classification	Effect
> LINE_LIMIT	VIOLATION	Hard failure
> WARNING_LIMIT	WARNING	Reported, but does not fail
> INFO_LIMIT	FYI	Early heads-up, but does not fail
<= INFO_LIMIT	OK	Shown only with -v

Exit codes

Code	Meaning
0	The scan completed with no violations; warnings and FYIs may still have been reported
1	A file exceeded the hard limit, the directory was invalid, or a threshold was invalid
2	Command-line usage error, such as a missing positional argument

Feed paths to another command

--files-only prints each unique file classified as a violation, warning, or FYI to stdout, in sorted order. It keeps the normal scan's exit code and emits no log output, making it suitable for scripts:

toobig --files-only src 1000 850 700 | xargs -r editor

When there are no files above the informational threshold, stdout is empty.

Continuous integration

A small Justfile recipe keeps the project policy easy to run locally and in CI:

toobig:
    uvx --from toobig toobig src 1000 850 700

Then call the same recipe from GitHub Actions:

- uses: astral-sh/setup-uv@v4
- uses: extractions/setup-just@v3
- run: just toobig

Pin toobig to the version range appropriate for your project when reproducibility is important.

Development

The repository uses uv for environments and dependency installation, and just as its task runner. From a clone:

just install
just check

just check verifies formatting, runs Ruff and strict mypy, and executes the pytest suite. The package supports Python 3.10 through 3.14 and has no runtime dependencies.

Releases

Commits and pull-request titles follow Conventional Commits. On every push to master, release-please updates or opens a release pull request containing the next version and changelog. Merging that pull request creates the GitHub release, builds and smoke-tests both distributions, and publishes toobig to PyPI using trusted publishing (GitHub Actions OIDC), without a long-lived PyPI token.

License

toobig is available under the MIT License.