Metadata-Version: 2.4
Name: evo-preflight
Version: 0.1.0
Summary: Describe exactly what Git is about to commit.
Author: Preflight contributors
License-Expression: MIT
Keywords: git,commit,cli,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: mypy<2,>=1.11; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: twine<7,>=5.1; extra == "dev"
Dynamic: license-file

# Preflight

> What exactly am I about to commit?

Preflight is a deterministic, read-only CLI that inspects the Git index immediately before `git commit`. It summarizes the staged snapshot and reports evidence-backed repository states developers commonly regret committing.

```console
python -m pip install evo-preflight
preflight
```

Preflight inspects staged paths and blob sizes, common generated artifacts, tracked files matching `.gitignore`, foundational repository files, and the repository default branch. Every finding says what was observed, why it matters, and a suggested fix.

It never blocks a commit, changes repository state, runs tests or builds, scans secrets, certifies releases, installs hooks, uses AI, sends telemetry, or accesses the network.

## Commands

```console
preflight
preflight --json
preflight --largest
preflight --version
preflight explain large-staged-file
preflight --config preflight.toml
```

Findings always return exit code `0`. Exit code `2` means the repository or configuration is unavailable; `3` means an unexpected internal error occurred.

## What it reports

- staged files of at least 100 MB;
- staged snapshots of at least 500 MB, with largest contributors;
- Python caches: `__pycache__`, `*.pyc`, and `*.pyo`;
- virtual environments: `.venv` and `venv`;
- build artifacts: `build`, `dist`, `*.whl`, and `*.egg-info`;
- `*.jsonl` and configured generated directories;
- tracked files matching standard Git ignore rules;
- a missing root README, LICENSE, or `.gitignore`;
- a default branch named `master`, reported without claiming it is wrong;
- the ten largest tracked files when `--largest` is requested.

Preflight reads staged content from Git, so unstaged edits are never described as part of the next commit.

## Configuration

Preflight automatically reads `preflight.toml` from the repository root. Configuration is declarative, has no commands or scripting, and rejects unknown keys.

```toml
version = 1

[limits]
large_file_mb = 100
large_snapshot_mb = 500

[generated]
directories = ["benchmarks/results", "telemetry"]
```

## Development

```console
python -m pip install -e ".[dev]"
ruff check .
mypy
python -m unittest discover -s tests -v
python -m build
twine check dist/*
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and [CHANGELOG.md](CHANGELOG.md) for release history.
