Adopt pinned public core snapshot and prepare Sized 2.0.0

2026-10-10 13:11:02 -04:00
parent c2cc458f27
commit e0707447ad
30 changed files with 1533 additions and 101 deletions
@@ -0,0 +1,75 @@
+# 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).