facett-core 0.1.19

//! **Embedded assets, and the one thing that can silently replace them.**
//!
//! # The defect, measured on oden 2026-08-27
//!
//! `/home/rickard/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);
        assert!(POINTER && !FONT, "evaluated at compile time, and the values are these");
    }
}