facett-core/src/asset.rs
//! **Embedded assets, and the one thing that can silently replace them.**
//!
//! # The defect, measured on oden 2026-08-27
//!
//! `~/git/facett` reported `git status --porcelain` as **clean — zero
//! lines** while **14 of its 14 Git-LFS-tracked files were 131-byte pointers**. Among
//! them, both fonts this crate and `facett-docview` compile into their binaries:
//!
//! ```text
//! facett-core/assets/fonts/Inter-Regular.ttf 131 B on disk, 876 576 B expected
//! facett-docview/assets/DejaVuSans.ttf 131 B on disk, 759 720 B expected
//! ```
//!
//! `git status` is silent about this **by construction**: the LFS clean filter passes a
//! pointer through unchanged, so the pointer in the working tree hashes to the pointer in
//! `HEAD` and there is no diff to report. Every repo in the constellation that tracks LFS
//! at all was in this state — 61 files across 8 repos — and every one of them called
//! itself clean.
//!
//! What `include_bytes!` does with a 131-byte "font" is the interesting half: **it
//! compiles.** The build is green, the binary is smaller, and the failure surfaces as text
//! that does not shape, or as `egui`'s built-in fallback quietly standing in for the face
//! the design specified. No test that renders a *picture* catches it either, because
//! something is always drawn.
//!
//! # The guard
//!
//! [`is_a_git_lfs_pointer`] is a `const fn`, so the check runs in `const` context beside
//! the `include_bytes!` that needs it and the BUILD fails — the only place this can be
//! caught for free, on every host, before anything ships. One predicate for every embed
//! site in the workspace (LAW 5); the alternative is each crate re-deriving "what does a
//! broken asset look like", and the two answers drifting.
//!
//! Pair it with a size floor: a pointer is the common failure and the one that has
//! actually happened, but a truncated or empty asset is the same class of lie and the
//! magic bytes say nothing about it.
//!
//! ```
//! const FONT: &[u8] = include_bytes!("../assets/fonts/Inter-Regular.ttf");
//! const _: () = assert!(
//! !facett_core::asset::is_a_git_lfs_pointer(FONT) && FONT.len() > 4096,
//! "Inter-Regular.ttf is a Git-LFS pointer or a stub, not a font — run `git lfs checkout`"
//! );
//! ```
/// The first line every Git-LFS pointer file starts with, per the v1 spec.
///
/// The whole file is three short lines — `version`, `oid sha256:…`, `size …` — and the
/// version line is fixed text, so matching its prefix is exact rather than heuristic.
const LFS_POINTER_MAGIC: &[u8] = b"version https://git-lfs.github.com/spec/v1";
/// **Are these bytes a Git-LFS pointer instead of the asset they claim to be?**
///
/// `const` on purpose: the answer is wanted at compile time, next to the
/// `include_bytes!`, where it can stop a build instead of describing one.
///
/// Deliberately a prefix test and not a size test. A size floor belongs at the call site,
/// where the caller knows what "too small for THIS asset" means; a 131-byte PNG and a
/// 131-byte font need different floors, and this function must not pretend to pick one.
pub const fn is_a_git_lfs_pointer(bytes: &[u8]) -> bool {
if bytes.len() < LFS_POINTER_MAGIC.len() {
return false;
}
let mut i = 0;
while i < LFS_POINTER_MAGIC.len() {
if bytes[i] != LFS_POINTER_MAGIC[i] {
return false;
}
i += 1;
}
true
}
#[cfg(test)]
mod tests {
use super::is_a_git_lfs_pointer;
/// ★ **The predicate separates a pointer from an asset, in both directions.**
///
/// The pointer is the REAL one that was sitting in
/// `facett-core/assets/fonts/Inter-Regular.ttf` on oden on 2026-08-27, byte for byte,
/// oid and all — not a paraphrase of one, because a paraphrase is where a prefix test
/// quietly stops matching the thing it is for.
///
/// The negative arm is the point of the test. A predicate that answered `true` for
/// everything would satisfy every `assert!(!is_a_git_lfs_pointer(..))` written against
/// it by failing every build, and one that answered `false` for everything is the
/// silent-green this whole module exists to stop — so both constants are asserted, and
/// the empty and short cases are asserted too, because a `bytes[i]` on a shorter slice
/// is a panic, and a panic in a `const` context is a build failure that names the
/// wrong file.
#[test]
fn a_pointer_reads_as_a_pointer_and_a_font_does_not() {
const REAL_POINTER: &[u8] = b"version https://git-lfs.github.com/spec/v1\n\
oid sha256:29160a80ff49ddcab2c97711247e08b1fab27a484a329ce8b813d820dc559031\n\
size 876576\n";
assert!(
is_a_git_lfs_pointer(REAL_POINTER),
"the 131-byte file that stood in for Inter-Regular.ttf must read as a pointer"
);
// A TrueType file starts with the version tag 0x00010000; an OpenType one with
// `OTTO`. Neither is text, and neither may trip this.
assert!(!is_a_git_lfs_pointer(&[0x00, 0x01, 0x00, 0x00, 0x00, 0x0d]), "ttf header");
assert!(!is_a_git_lfs_pointer(b"OTTO\x00\x0f\x00\x80"), "otf header");
assert!(!is_a_git_lfs_pointer(b"\x89PNG\r\n\x1a\n"), "png header");
// Text that merely mentions LFS is not a pointer — the magic is a PREFIX.
assert!(
!is_a_git_lfs_pointer(b"# see version https://git-lfs.github.com/spec/v1"),
"the magic is anchored at byte 0, or every doc that quotes it becomes a pointer"
);
// Shorter than the magic: must answer `false`, never index out of bounds. In a
// `const` context an out-of-bounds read is a compile error attributed to this
// file, which would send the reader looking in exactly the wrong place.
assert!(!is_a_git_lfs_pointer(b""), "empty");
assert!(!is_a_git_lfs_pointer(b"version https"), "a prefix OF the magic");
}
/// ★ **The guard runs in `const` context** — which is the whole reason it is a
/// `const fn`, and the property that a plain unit test cannot demonstrate.
///
/// If this ever stops compiling as a `const`, every `const _: () = assert!(…)` at a
/// real embed site silently becomes a runtime check that nothing calls.
#[test]
fn the_predicate_is_usable_where_it_has_to_be() {
const POINTER: bool = is_a_git_lfs_pointer(b"version https://git-lfs.github.com/spec/v1\n");
const FONT: bool = is_a_git_lfs_pointer(&[0x00, 0x01, 0x00, 0x00]);
const _: () = assert!(POINTER && !FONT, "evaluated at compile time, and the values are these");
}
}