Metadata-Version: 2.4
Name: jettison
Version: 0.1.0
License-File: LICENSE
License-File: NOTICE
Summary: Native disk usage scanner with a Rust CLI and Python bindings
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# Candidate disk scanner

Rust library + native CLI + Python abi3 extension. The provisional name is
recorded in NAME.md; nothing has been published or reserved.

```sh
soldr cargo run --release -p jettison-cli -- /home --top 20 --one-filesystem
soldr cargo run --release -p jettison-cli -- /home --json --depth 2
soldr cargo run --release -p jettison-cli -- /home --summary --threads 8
uv build --wheel                     # soldr PEP 517 backend, native CLI bundled
python3 ci/wheel.py smoke            # clean installed-wheel tests
./ci.py all                         # Linux gates (no publishing)
```

The installed command is `jettison-cli`; it is the Rust executable itself,
not a generated Python console-script launcher. `--help` lists every option.
Default sizes are allocated blocks, so sparse holes are excluded. `--apparent`
ranks logical sizes. Hardlinks count once; the alias that receives the charge
can vary with worker order. Directories include their own metadata allocation.
`--depth` and `--top` limit output, never traversal or totals. Human output ranks
all visible nodes globally; JSON applies top/depth to each directory's children.
`--summary` uses the streaming API and retains no file tree.

```python
import jettison
result = jettison.scan("/home", one_filesystem=True, threads=8)
print(result["allocated"], result["errors"])
```

The Python call releases the GIL during traversal. A scan of a root that cannot
be opened raises an error. Descendant failures increment `errors`; CLI exit 1
means partial results, exit 2 means invalid arguments or root failure. Progress
is on stderr when attached to a terminal. A live scan is not a snapshot, and
concurrent filesystem changes can affect results. Filename bytes are preserved
in Rust paths; JSON/Python display paths replace invalid Unicode.

Linux uses getdents64 + fd-relative statx/openat with worker deques. Windows
attempts raw NTFS MFT, then USN, then FindFirstFileExW and a compatibility walk.
macOS uses getattrlistbulk, adapted from MIT-licensed Kencho5/derust. Windows
and macOS are cross-compiled here; their native runtime paths remain UNVERIFIED
until the corresponding CI lanes execute. See docs/DESIGN.md and NOTICE.

The six native lanes compile on Linux and run their test executables and wheel
on their own runner OS. Musl triples are declared for release-only work. There
is no release/tag/upload workflow in this candidate repository.

Tests create real fixtures under ignored `target/test-fixtures/` directories, including a
3000-entry directory, sparse data, hardlinks, unreadable files and symlink loops.
Fixtures remain available for diagnosis; remove them with `safe-rm -r` after use.
No filesystem is mocked. Pure NTFS and macOS byte decoders run on Linux too.

The core crate can be packaged independently for crates.io; the wheel includes
the same core, a PyO3 `abi3-py310` module, and the native executable. Before a
release, a human must approve the name, complete native validation, and review
the registry availability again. See RELEASE.md, LINTING.md and docs/DESIGN.md.

