# Sized core

Shared Rust filesystem scanning for [Sized](https://gitea.speelman.ca/gamertan/sized)
and [SizeQueen](https://gitea.speelman.ca/gamertan/sizequeen), by Gamertan.
This is a private extraction experiment. The existing applications still use
their current scanner copies; adopting this repository is a separate change.

The library reports apparent bytes and allocated 512-byte blocks, counts hard
links deterministically, preserves partial-scan issues, and supports cancellation,
progress, per-scan worker selection, ignore rules and filesystem boundaries.
It contains no desktop, terminal formatting, web or Swift dependencies.
Linux and macOS are supported; Windows allocation is not implemented.

## Use

The Cargo package is `sized-core`; its library import remains `sized` for
compatibility with the current SizeQueen snapshot. Pin a reviewed Git revision
when adopting it. Private Git dependencies require access to this repository.

```rust
use sized::{scan_tree, ScanControl, ScanError, ScanOptions, ScanReport};
use std::path::Path;

fn scan_chosen_path(path: &Path) -> Result<ScanReport, ScanError> {
    scan_tree(path, &ScanOptions::default(), &ScanControl::default())
}
// Inspect report.issues and report.root.complete before calling a scan complete.
```

Use `scan_tree` for new consumers. The legacy `build_tree` helper converts a
failed scan to an unavailable node and does not preserve diagnostics.
Cancellation is cooperative between filesystem calls. Allocated blocks do not
predict recoverable space on filesystems with shared extents or snapshots.

## Check

Run tests as an ordinary user; permission regressions intentionally fail as root.

```sh
cargo fmt --all -- --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
./scripts/check-linux.sh linux/arm64
./scripts/check-linux.sh linux/amd64
```

The Linux script pins Rust 1.88.0, runs as UID 65532 with capabilities dropped,
creates two actual tmpfs devices, and checks a release-built example against an
owned fixture. The mount test is ignored in normal Cargo runs and explicitly
enabled by the script.
The example requires an explicit path: `cargo run --locked --example scan -- PATH`.

### Gitea CI

`.gitea/workflows/linux.yml` runs the same checks on the existing cliff-mads
runner's `himesan-node24` label with a pinned Rust/Node job image. The image
pre-owns `/workspace/gamertan/sized-core` for UID 65532, including checkout.
Jobs have no Docker socket or privileged mode; the runner mounts the two tmpfs
devices. No runner configuration, labels or unrelated jobs are changed.

Rebuild the local image intentionally with:

```sh
ssh cliff-mads 'docker build --platform linux/amd64 --tag local/gamertan-ci:sized-core-rust188 -' < scripts/gitea-linux.Dockerfile
ssh cliff-mads 'docker image inspect local/gamertan-ci:sized-core-rust188 --format "{{.Id}}"'
```

Review and update the workflow image ID after a rebuild. It stays local to
cliff-mads. Repository Actions must be enabled. Checks cover owner-triggered,
same-repository pushes on main/review branches and PRs to main; manual dispatch
is available. Documentation-only pushes skip builds. No package or release is
published. `TODO.md` records the actual provider result and tested source commit.

Source provenance and licence are in [PROVENANCE.md](PROVENANCE.md) and
[LICENSE](LICENSE). The live iteration queue is [TODO.md](TODO.md).