1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// Copyright 2026 wolfy <wolfy@shitwolfymakes.com>
// SPDX-License-Identifier: Apache-2.0
//! matrix256 — reproducible fingerprints for optical discs and filesystem trees.
//!
//! The active algorithm version lives in [`v1`]: a SHA-256 over a canonical
//! serialization of the (path, size) records of every regular file under the
//! walk root. See `SPEC.md` in the spec repo for the normative specification:
//! <https://github.com/shitwolfymakes/matrix256/blob/main/SPEC.md>.
//!
//! Calling code addresses the algorithm explicitly:
//!
//! ```no_run
//! use matrix256::v1;
//! let digest = v1::fingerprint("/media/user/DISC")?;
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! The crate exposes nothing at the top level so future versions can be added
//! as sibling submodules (`v2`, …) without a "current" default that would
//! silently change behavior.
// Library-discipline lints. The promise to consumers: a process using this
// crate must never break because of code we shipped. The lints below
// enforce that promise by making the relevant footguns into compile errors
// rather than review comments.
//
// - `forbid(unsafe_code)` No `unsafe { }` blocks, ever. Cannot
// be opted out via `#[allow]`.
// - `deny(missing_docs)` Every public item carries a `///`
// doc comment. Public API stays
// self-describing.
// - Panic-discipline (clippy): `unwrap_used`, `expect_used`,
// `unwrap_in_result`, `panic`,
// `unreachable`, `todo`, `unimplemented`,
// `dbg_macro` — every direct or stylistic
// route to a runtime panic is denied.
// - Bounds-checking (clippy): `indexing_slicing`, `string_slice` —
// `arr[i]` and `&s[i..j]` are panic
// sites; force the `.get(...)` /
// `.get_mut(...)` Option-returning forms.
// - Conversion safety (clippy): `as_conversions` — `as` casts can
// silently truncate or lose precision;
// force `From` / `TryFrom`.
// - Output discipline (clippy): `print_stdout`, `print_stderr` — lib
// code has no business writing to
// stdout/stderr from a fingerprint call.
//
// Tests in `src/.../mod tests` opt back out via an inner `#![allow(...)]`
// where the lint conflicts with idiomatic test code. Integration tests
// under `tests/` are a separate crate and not affected by this block.