Scanner workspace

Rust workspace for filesystem scanning: a public scanner library crate and the scanfs CLI.

Latest release: v0.2.3

Layout

Requirements

• Rust toolchain: pinned in rust-toolchain.toml (channel, rustfmt, clippy). CI uses the same file via dtolnay/rust-toolchain@stable in this directory.
• Lockfile: CI and make check / make ci-local use cargo … --locked for reproducible builds (Primer — reproducibility).

Rust Project Primer map

This workspace follows Checks, CI / GitHub Actions, and Releasing:

The scanner-core crate depends on internal scanner-* crates from this workspace. The release workflow publishes those internal crates first, then publishes scanner-core, all with locked dependency resolution. | Versioning | CHANGELOG.md (Keep a Changelog); pre-1.0 SemVer: minor bumps may be breaking for 0.x consumers |

Branch protection and release (prepare step): If main requires pull requests or restricts who can push, the prepare job must be allowed to push commits and tags (same run then builds and creates the GitHub Release). Typical options: allow github-actions[bot] to bypass rules for this workflow, or use a branch policy that permits bot pushes. Without that, Commit, tag, and push fails after tests.

Manual release (tag-only path)

To ship without the automated prepare step (no bot commit on main):

1. Bump version = across scanner/, scanfs/, and crates/*/ Cargo.toml files (e.g. cargo set-version from cargo-edit).
2. cargo generate-lockfile, cargo test --workspace --locked, and update CHANGELOG.md.
3. Commit and merge to main, then git tag v0.2.3 and git push origin v0.2.3. That push triggers release.yml preflight → artifacts → GitHub Release.

To disable only CI-driven auto bumps: remove or narrow the workflow_run trigger in release.yml; you can still use Actions → Release → Run workflow or manual tags.

Monorepo note: If this tree lives inside a larger repo, GitHub only runs workflows from the repository root .github/workflows/. Copy or call these jobs from the root workflow if you need them on every PR.

Using the library

In Cargo.toml:

scanner = { package = "scanner-core", path = "scanner/scanner" }  # adjust path from your crate

Example:

use scanner::{scan, ScanOptions};

fn main() -> Result<(), scanner::ScanError> {
    let mut opts = ScanOptions::default();
    opts.roots = vec!["/path/to/root".into()];
    scan(&opts, &mut std::io::stdout())?;
    Ok(())
}

Using the CLI

From this directory:

cargo run -p scanfs -- --help
cargo run -p scanfs -- --root /data --format json

Environment:

• SCAN_FS_SOURCE — label for the source field in JSON output (default: hostname).

Development

With GNU Make (Git Bash, Linux, macOS):

make help
make ci-local   # same sequence as CI matrix job (fmt, clippy, doc, scanfs, test; all --locked where applicable)
make check      # fmt-check + clippy + doc + test + build-scanfs
make lint-extra # typos + taplo + cargo deny (install tools locally or rely on CI)

Or invoke cargo directly:

cargo fmt --all
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo doc --workspace --no-deps --locked
cargo test --workspace --locked
cargo build --locked --bin scanfs

Release binary:

cargo build --release --locked -p scanfs

Optional distribution (not wired by default)

If you ship scanfs as a container or system package, see the Primer: containers (e.g. multi-stage build with cargo-chef for layer cache) and packaging (cargo-deb / cargo-generate-rpm). Add a Dockerfile or deb metadata only when that is a product goal.