pure_magic/

lib.rs

#![forbid(unsafe_code)]
#![deny(unused_imports)]
#![deny(missing_docs)]
//! # `pure-magic`: A pure and safe Rust Reimplementation of `libmagic`
//!
//! Unlike many file identification crates, `pure-magic` is highly compatible with the standard
//! `magic` rule format, allowing seamless reuse of existing
//! [rules](https://github.com/qjerome/magic-rs/tree/main/magic-db/src/magdir). This makes it an ideal
//! drop-in replacement for crates relying on **`libmagic` C bindings**, where memory safety is critical.
//!
//! **Key Features:**
//! - File type detection
//! - MIME type inference
//! - Custom magic rule parsing
//!
//! ## Installation
//! Add `pure-magic` to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! pure-magic = "0.1"  # Replace with the latest version
//! ```
//!
//! Or add the latest version with cargo:
//!
//! ```sh
//! cargo add pure-magic
//! ```
//!
//! ## Quick Start
//!
//! ### Detect File Types Programmatically
//! ```rust
//! use pure_magic::{MagicDb, MagicSource, DataReader};
//! use std::fs::File;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let mut db = MagicDb::new();
//!     // Create a MagicSource from a file
//!     let rust_magic = MagicSource::open("../magic-db/src/magdir/rust")?;
//!     db.load(rust_magic);
//!     // Verification is not mandatory
//!     db.verify()?;
//!
//!     // Detect file type
//!     let magic = db.first_magic_file("src/lib.rs")?;
//!
//!     println!(
//!         "File type: {} (MIME: {}, strength: {})",
//!         magic.message(),
//!         magic.mime_type(),
//!         magic.strength()
//!     );
//!     Ok(())
//! }
//! ```
//!
//! ### Get All Matching Rules
//! ```rust
//! use pure_magic::{MagicDb, MagicSource, DataReader};
//! use std::fs::File;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let mut db = MagicDb::new();
//!     // Create a MagicSource from a file
//!     let rust_magic = MagicSource::open("../magic-db/src/magdir/rust")?;
//!     db.load(rust_magic);
//!
//!     // Get all matching rules, sorted by strength
//!     let magics = db.all_magics_file("src/lib.rs")?;
//!
//!     // Must contain rust file magic and default text magic
//!     assert!(magics.len() > 1);
//!
//!     for magic in magics {
//!         println!(
//!             "Match: {} (strength: {}, source: {})",
//!             magic.message(),
//!             magic.strength(),
//!             magic.source().unwrap_or("unknown")
//!         );
//!     }
//!     Ok(())
//! }
//! ```
//!
//! ### Serialize a Database to Disk
//! ```rust
//! use pure_magic::{MagicDb, MagicSource};
//! use std::fs::File;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let mut db = MagicDb::new();
//!     // Create a MagicSource from a file
//!     let rust_magic = MagicSource::open("../magic-db/src/magdir/rust")?;
//!     db.load(rust_magic);
//!
//!     // Serialize the database to a file
//!     let mut output = File::create("/tmp/compiled.db")?;
//!     db.serialize(&mut output)?;
//!
//!     println!("Database saved to file");
//!     Ok(())
//! }
//! ```
//!
//! ### Deserialize a Database
//! ```rust
//! use pure_magic::{MagicDb, MagicSource};
//! use std::fs::File;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let mut db = MagicDb::new();
//!     // Create a MagicSource from a file
//!     let rust_magic = MagicSource::open("../magic-db/src/magdir/rust")?;
//!     db.load(rust_magic);
//!
//!     // Serialize the database in a vector
//!     let mut ser = vec![];
//!     db.serialize(&mut ser)?;
//!     println!("Database saved to vector");
//!
//!     // We deserialize from slice
//!     let db = MagicDb::deserialize(&mut ser.as_slice())?;
//!
//!     assert!(!db.rules().is_empty());
//!
//!     Ok(())
//! }
//! ```
//!
//! ## License
//! This project is dual-licensed under either:
//! - **GPL-3.0**
//! - **BSD-2-Clause**
//!
//! ## Contributing
//! Contributions are welcome! Open an issue or submit a pull request.
//!
//! ## Acknowledgments
//! - Inspired by the original `libmagic` (part of the `file` command).

use dyf::{DynDisplay, FormatString, dformat};
use flaglet::flags;
use flate2::{Compression, read::GzDecoder, write::GzEncoder};
use memchr::memchr;
use pest::{Span, error::ErrorVariant};
use regex::bytes::{self};
use serde::{Deserialize, Serialize};
use std::{
    borrow::Cow,
    cmp::max,
    collections::{HashMap, HashSet},
    fmt::{self, Debug, Display},
    fs::File,
    io::{self, Read, SeekFrom, Write},
    mem::swap,
    ops::{Add, BitAnd, BitOr, BitXor, Deref, Div, Mul, Rem, Sub},
    path::Path,
    sync::OnceLock,
};
use tar::Archive;
use thiserror::Error;
use tracing::{Level, debug, enabled, error, trace};

use crate::{
    numeric::{Float, FloatDataType, Scalar, ScalarDataType},
    parser::{FileMagicParser, Rule},
    readers::DataRead,
    utils::{
        debug_string_from_vec_u8, debug_string_from_vec_u16, decode_id3, find_json_boundaries,
        run_utf8_validation,
    },
};

mod numeric;
mod parser;
pub mod readers;
pub use readers::DataReader;
mod utils;

const HARDCODED_MAGIC_STRENGTH: u64 = 2048;
const HARDCODED_SOURCE: &str = "hardcoded";
// corresponds to FILE_INDIR_MAX constant defined in libmagic
const MAX_RECURSION: usize = 50;
// constant found in libmagic. It is used to limit for regex tests
const FILE_REGEX_MAX: usize = 8192;

/// Maximum number of bytes to read for search tests.
///
/// This constant is derived from `libmagic` and is used to limit the number of bytes
/// read during search tests to ensure performance and efficiency. The value is set
/// to 7 megabytes.
pub const FILE_BYTES_MAX: usize = 7 * 1024 * 1024;
/// Default mimetype for un-identified binary data
pub const DEFAULT_BIN_MIMETYPE: &str = "application/octet-stream";
/// Default mimetype for un-identified text data
pub const DEFAULT_TEXT_MIMETYPE: &str = "text/plain";

pub(crate) const TIMESTAMP_FORMAT: &str = "%Y-%m-%d %H:%M:%S";

macro_rules! debug_panic {
    ($($arg:tt)*) => {
        if cfg!(debug_assertions) {
            panic!($($arg)*);
        }
    };
}

macro_rules! read {
    ($r: expr, $ty: ty) => {{
        let mut a = [0u8; std::mem::size_of::<$ty>()];
        $r.read_exact_into(&mut a)?;
        a
    }};
}

macro_rules! read_le {
    ($r:expr, $ty: ty ) => {{ <$ty>::from_le_bytes(read!($r, $ty)) }};
}

macro_rules! read_be {
    ($r:expr, $ty: ty ) => {{ <$ty>::from_be_bytes(read!($r, $ty)) }};
}

macro_rules! read_me {
    ($r: expr) => {{ ((read_le!($r, u16) as i32) << 16) | (read_le!($r, u16) as i32) }};
}

#[inline(always)]
fn read_octal_u64<D: DataRead>(haystack: &mut D) -> Option<u64> {
    let s = haystack
        .read_while_or_limit(|b| matches!(b, b'0'..=b'7'), 22)
        .map(|buf| str::from_utf8(buf))
        .ok()?
        .ok()?;

    if !s.starts_with("0") {
        return None;
    }

    u64::from_str_radix(s, 8).ok()
}

/// Represents all possible errors that can occur during file type detection and processing.
#[derive(Debug, Error)]
pub enum Error {
    /// A generic error with a custom message.
    #[error("{0}")]
    Msg(String),

    /// Indicate a rule load failure
    #[error("source={0} line={1} error={2}")]
    Verify(String, usize, Box<Error>),

    /// An error with a source location and a nested error.
    #[error("source={0} line={1} error={2}")]
    Localized(String, usize, Box<Error>),

    /// Indicates a required rule was not found.
    #[error("missing rule: {0}")]
    MissingRule(String),

    /// Indicates the maximum recursion depth was reached.
    #[error("maximum recursion reached: {0}")]
    MaximumRecursion(usize),

    /// Wraps an I/O error.
    #[error("io: {0}")]
    Io(#[from] io::Error),

    /// Wraps a parsing error from the `pest` parser.
    #[error("parser error: {0}")]
    Parse(#[from] Box<pest::error::Error<Rule>>),

    /// Wraps a formatting error from the `dyf` crate.
    #[error("formatting: {0}")]
    Format(#[from] dyf::Error),

    /// Wraps a regex-related error.
    #[error("regex: {0}")]
    Regex(#[from] regex::Error),

    /// Wraps a serialization error from `bincode`.
    #[error("{0}")]
    Serialize(#[from] bincode::error::EncodeError),

    /// Wraps a deserialization error from `bincode`.
    #[error("{0}")]
    Deserialize(#[from] bincode::error::DecodeError),
}

impl Error {
    #[inline]
    fn parser<S: ToString>(msg: S, span: Span<'_>) -> Self {
        Self::Parse(Box::new(pest::error::Error::new_from_span(
            ErrorVariant::CustomError {
                message: msg.to_string(),
            },
            span,
        )))
    }

    fn msg<M: AsRef<str>>(msg: M) -> Self {
        Self::Msg(msg.as_ref().into())
    }

    fn localized<S: AsRef<str>>(source: S, line: usize, err: Error) -> Self {
        Self::Localized(source.as_ref().into(), line, err.into())
    }

    /// Unwraps the localized error
    pub fn unwrap_localized(&self) -> &Self {
        match self {
            Self::Localized(_, _, e) => e,
            _ => self,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
enum Message {
    String(String),
    Format {
        printf_spec: String,
        fs: FormatString,
    },
}

impl Display for Message {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::String(s) => write!(f, "{s}"),
            Self::Format { printf_spec: _, fs } => write!(f, "{}", fs.to_string_lossy()),
        }
    }
}

impl Message {
    fn to_string_lossy(&self) -> Cow<'_, str> {
        match self {
            Message::String(s) => Cow::Borrowed(s),
            Message::Format { printf_spec: _, fs } => fs.to_string_lossy(),
        }
    }

    #[inline(always)]
    fn format_with(&self, mr: Option<&MatchRes>) -> Result<Cow<'_, str>, Error> {
        match self {
            Self::String(s) => Ok(Cow::Borrowed(s.as_str())),
            Self::Format {
                printf_spec: c_spec,
                fs,
            } => {
                if let Some(mr) = mr {
                    match mr {
                        MatchRes::Float(_, _) | MatchRes::Bytes(_, _, _, _) => {
                            Ok(Cow::Owned(dformat!(fs, mr)?))
                        }
                        MatchRes::Scalar(_, scalar) => {
                            // we want to print a byte as char
                            if c_spec.as_str() == "c" {
                                match scalar {
                                    Scalar::byte(b) => {
                                        let b = (*b as u8) as char;
                                        Ok(Cow::Owned(dformat!(fs, b)?))
                                    }
                                    Scalar::ubyte(b) => {
                                        let b = *b as char;
                                        Ok(Cow::Owned(dformat!(fs, b)?))
                                    }
                                    _ => Ok(Cow::Owned(dformat!(fs, mr)?)),
                                }
                            } else {
                                Ok(Cow::Owned(dformat!(fs, mr)?))
                            }
                        }
                    }
                } else {
                    Ok(fs.to_string_lossy())
                }
            }
        }
    }
}

impl ScalarDataType {
    #[inline(always)]
    fn read<R: DataRead>(&self, from: &mut R, switch_endianness: bool) -> Result<Scalar, Error> {
        macro_rules! _read_le {
            ($ty: ty) => {{
                if switch_endianness {
                    <$ty>::from_be_bytes(read!(from, $ty))
                } else {
                    <$ty>::from_le_bytes(read!(from, $ty))
                }
            }};
        }

        macro_rules! _read_be {
            ($ty: ty) => {{
                if switch_endianness {
                    <$ty>::from_le_bytes(read!(from, $ty))
                } else {
                    <$ty>::from_be_bytes(read!(from, $ty))
                }
            }};
        }

        macro_rules! _read_ne {
            ($ty: ty) => {{
                if cfg!(target_endian = "big") {
                    _read_be!($ty)
                } else {
                    _read_le!($ty)
                }
            }};
        }

        macro_rules! _read_me {
            () => {
                ((_read_le!(u16) as i32) << 16) | (_read_le!(u16) as i32)
            };
        }

        Ok(match self {
            // signed
            Self::byte => Scalar::byte(read!(from, u8)[0] as i8),
            Self::short => Scalar::short(_read_ne!(i16)),
            Self::long => Scalar::long(_read_ne!(i32)),
            Self::date => Scalar::date(_read_ne!(i32)),
            Self::ldate => Scalar::ldate(_read_ne!(i32)),
            Self::qwdate => Scalar::qwdate(_read_ne!(i64)),
            Self::leshort => Scalar::leshort(_read_le!(i16)),
            Self::lelong => Scalar::lelong(_read_le!(i32)),
            Self::lequad => Scalar::lequad(_read_le!(i64)),
            Self::bequad => Scalar::bequad(_read_be!(i64)),
            Self::belong => Scalar::belong(_read_be!(i32)),
            Self::bedate => Scalar::bedate(_read_be!(i32)),
            Self::beldate => Scalar::beldate(_read_be!(i32)),
            Self::beqdate => Scalar::beqdate(_read_be!(i64)),
            Self::beqldate => Scalar::beqldate(_read_be!(i64)),
            // unsigned
            Self::ubyte => Scalar::ubyte(read!(from, u8)[0]),
            Self::ushort => Scalar::ushort(_read_ne!(u16)),
            Self::uleshort => Scalar::uleshort(_read_le!(u16)),
            Self::ulelong => Scalar::ulelong(_read_le!(u32)),
            Self::uledate => Scalar::uledate(_read_le!(u32)),
            Self::ulequad => Scalar::ulequad(_read_le!(u64)),
            Self::offset => Scalar::offset(from.stream_position()),
            Self::ubequad => Scalar::ubequad(_read_be!(u64)),
            Self::medate => Scalar::medate(_read_me!()),
            Self::meldate => Scalar::meldate(_read_me!()),
            Self::melong => Scalar::melong(_read_me!()),
            Self::beshort => Scalar::beshort(_read_be!(i16)),
            Self::quad => Scalar::quad(_read_ne!(i64)),
            Self::uquad => Scalar::uquad(_read_ne!(u64)),
            Self::ledate => Scalar::ledate(_read_le!(i32)),
            Self::leldate => Scalar::leldate(_read_le!(i32)),
            Self::leqdate => Scalar::leqdate(_read_le!(i64)),
            Self::leqldate => Scalar::leqldate(_read_le!(i64)),
            Self::leqwdate => Scalar::leqwdate(_read_le!(i64)),
            Self::ubelong => Scalar::ubelong(_read_be!(u32)),
            Self::ulong => Scalar::ulong(_read_ne!(u32)),
            Self::ubeshort => Scalar::ubeshort(_read_be!(u16)),
            Self::ubeqdate => Scalar::ubeqdate(_read_be!(u64)),
            Self::lemsdosdate => Scalar::lemsdosdate(_read_le!(u16)),
            Self::lemsdostime => Scalar::lemsdostime(_read_le!(u16)),
            // Microsoft mixed-endian GUID: data1/data2/data3 little-endian, data4 raw.
            Self::guid => Scalar::guid(
                (_read_le!(u32) as u128) << 96
                    | (_read_le!(u16) as u128) << 80
                    | (_read_le!(u16) as u128) << 64
                    | (_read_be!(u64) as u128),
            ),
            Self::leguid => Scalar::leguid(
                (_read_le!(u32) as u128) << 96
                    | (_read_le!(u16) as u128) << 80
                    | (_read_le!(u16) as u128) << 64
                    | (_read_be!(u64) as u128),
            ),
            Self::beguid => Scalar::beguid(_read_be!(u128)),
        })
    }
}

impl FloatDataType {
    #[inline(always)]
    fn read<R: DataRead>(&self, from: &mut R, switch_endianness: bool) -> Result<Float, Error> {
        macro_rules! _read_le {
            ($ty: ty) => {{
                if switch_endianness {
                    <$ty>::from_be_bytes(read!(from, $ty))
                } else {
                    <$ty>::from_le_bytes(read!(from, $ty))
                }
            }};
        }

        macro_rules! _read_be {
            ($ty: ty) => {{
                if switch_endianness {
                    <$ty>::from_le_bytes(read!(from, $ty))
                } else {
                    <$ty>::from_be_bytes(read!(from, $ty))
                }
            }};
        }

        macro_rules! _read_ne {
            ($ty: ty) => {{
                if cfg!(target_endian = "big") {
                    _read_be!($ty)
                } else {
                    _read_le!($ty)
                }
            }};
        }

        macro_rules! _read_me {
            () => {
                ((_read_le!(u16) as i32) << 16) | (_read_le!(u16) as i32)
            };
        }

        Ok(match self {
            Self::lefloat => Float::lefloat(_read_le!(f32)),
            Self::befloat => Float::befloat(_read_le!(f32)),
            Self::ledouble => Float::ledouble(_read_le!(f64)),
            Self::bedouble => Float::bedouble(_read_be!(f64)),
        })
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
enum Op {
    Mul,
    Add,
    Sub,
    Div,
    Mod,
    And,
    Xor,
    Or,
}

impl Display for Op {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Op::Mul => write!(f, "*"),
            Op::Add => write!(f, "+"),
            Op::Sub => write!(f, "-"),
            Op::Div => write!(f, "/"),
            Op::Mod => write!(f, "%"),
            Op::And => write!(f, "&"),
            Op::Or => write!(f, "|"),
            Op::Xor => write!(f, "^"),
        }
    }
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
enum CmpOp {
    Eq,
    Lt,
    Gt,
    BitAnd,
    Neq, // ! operator
    Xor,
    Not, // ~ operator
}

impl CmpOp {
    #[inline(always)]
    fn is_neq(&self) -> bool {
        matches!(self, Self::Neq)
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct ScalarTransform {
    op: Op,
    num: Scalar,
}

impl ScalarTransform {
    fn apply(&self, s: Scalar) -> Option<Scalar> {
        match self.op {
            Op::Add => s.checked_add(self.num),
            Op::Sub => s.checked_sub(self.num),
            Op::Mul => s.checked_mul(self.num),
            Op::Div => s.checked_div(self.num),
            Op::Mod => s.checked_rem(self.num),
            Op::And => Some(s.bitand(self.num)),
            Op::Xor => Some(s.bitxor(self.num)),
            Op::Or => Some(s.bitor(self.num)),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct FloatTransform {
    op: Op,
    num: Float,
}

impl FloatTransform {
    fn apply(&self, s: Float) -> Float {
        match self.op {
            Op::Add => s.add(self.num),
            Op::Sub => s.sub(self.num),
            Op::Mul => s.mul(self.num),
            // returns inf when div by 0
            Op::Div => s.div(self.num),
            // returns NaN when rem by 0
            Op::Mod => s.rem(self.num),
            // parser makes sure those operators cannot be used
            Op::And | Op::Xor | Op::Or => {
                debug_panic!("unsupported operation");
                s
            }
        }
    }
}

#[derive(Clone, Serialize, Deserialize)]
enum TestValue<T> {
    Value(T),
    Any,
}

impl Debug for TestValue<Vec<u8>> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Value(v) => write!(f, "\"{}\"", debug_string_from_vec_u8(v)),
            Self::Any => write!(f, "ANY"),
        }
    }
}

impl Debug for TestValue<Vec<u16>> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Value(v) => write!(f, "\"{}\"", debug_string_from_vec_u16(v)),
            Self::Any => write!(f, "ANY"),
        }
    }
}

impl Debug for TestValue<Scalar> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Value(s) => write!(f, "{s:?}"),
            Self::Any => write!(f, "ANY"),
        }
    }
}

impl Debug for TestValue<Float> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Value(fl) => write!(f, "{fl:?}"),
            Self::Any => write!(f, "ANY"),
        }
    }
}

impl<T> TestValue<T> {
    #[inline(always)]
    fn as_ref(&self) -> TestValue<&T> {
        match self {
            Self::Value(v) => TestValue::Value(v),
            Self::Any => TestValue::Any,
        }
    }
}

#[flags(u8)]
#[derive(Debug, Serialize, Deserialize)]
enum ReMod {
    CaseInsensitive = 1 << 0,
    StartOffsetUpdate = 1 << 1,
    LineLimit = 1 << 2,
    ForceBin = 1 << 3,
    ForceText = 1 << 4,
    TrimMatch = 1 << 5,
}

#[derive(Debug, Clone)]
struct Regex {
    s: String,
    captures_len: usize,
    re: OnceLock<bytes::Regex>,
}

#[derive(Serialize, Deserialize)]
struct SerializedRegex {
    s: String,
    captures_len: usize,
}

impl Serialize for Regex {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        SerializedRegex {
            s: self.s.clone(),
            captures_len: self.captures_len,
        }
        .serialize(serializer)
    }
}

impl<'de> Deserialize<'de> for Regex {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let sr = SerializedRegex::deserialize(deserializer)?;
        Ok(Self {
            s: sr.s,
            captures_len: sr.captures_len,
            re: OnceLock::new(),
        })
    }
}

impl Regex {
    #[inline]
    fn new(s: String) -> Result<Self, regex::Error> {
        let compiled = bytes::Regex::new(&s)?;
        let captures_len = compiled.captures_len();
        let re = OnceLock::from(compiled);
        Ok(Self {
            s,
            captures_len,
            re,
        })
    }

    #[inline]
    fn get_re(&self) -> Result<&bytes::Regex, regex::Error> {
        match self.re.get() {
            Some(re) => Ok(re),
            None => {
                let _ = self.re.set(bytes::Regex::new(self.s.as_str())?);
                Ok(self
                    .re
                    .get()
                    .expect("unreachable: cell is guaranteed to contain a value"))
            }
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct RegexTest {
    re: Regex,
    length: Option<usize>,
    mods: ReModFlags,
    str_mods: StringModFlags,
    non_magic_len: usize,
    binary: bool,
    cmp_op: CmpOp,
}

impl RegexTest {
    fn match_buf<'buf>(
        &self,
        off_buf: u64, // absolute buffer offset in content
        stream_kind: StreamKind,
        buf: &'buf [u8],
    ) -> Option<MatchRes<'buf>> {
        let mr = match stream_kind {
            StreamKind::Text(_) => {
                let mut off_txt = off_buf;

                let mut line_limit = self.length.unwrap_or(usize::MAX);

                for line in buf.split(|c| c == &b'\n') {
                    // we don't need to break on offset
                    // limit as buf contains the good amount
                    // of bytes to match against
                    if line_limit == 0 {
                        break;
                    }

                    if let Some(re_match) = self
                        .re
                        .get_re()
                        .inspect_err(|e| {
                            error!(
                                "deferred compile of regex pattern {:?} failed: {e}",
                                self.re.s
                            )
                        })
                        .ok()?
                        .find(line)
                    {
                        // the offset of the string is computed from the start of the buffer
                        let start_offset = off_txt + re_match.start() as u64;

                        // if we matched until EOL we need to add one to include the delimiter removed from the split
                        let stop_offset = if re_match.end() == line.len() {
                            Some(start_offset + re_match.as_bytes().len() as u64 + 1)
                        } else {
                            None
                        };

                        return Some(MatchRes::Bytes(
                            start_offset,
                            stop_offset,
                            re_match.as_bytes(),
                            Encoding::Utf8,
                        ));
                    }

                    off_txt += line.len() as u64;
                    // we have to add one because lines do not contain splitting character
                    off_txt += 1;
                    line_limit = line_limit.saturating_sub(1)
                }
                None
            }

            StreamKind::Binary => {
                self.re
                    .get_re()
                    .inspect_err(|e| {
                        error!(
                            "deferred compile of regex pattern {:?} failed: {e}",
                            self.re.s
                        )
                    })
                    .ok()?
                    .find(buf)
                    .map(|re_match| {
                        MatchRes::Bytes(
                            // the offset of the string is computed from the start of the buffer
                            off_buf + re_match.start() as u64,
                            None,
                            re_match.as_bytes(),
                            Encoding::Utf8,
                        )
                    })
            }
        };

        // handle the case where we want the regex not to match
        if self.cmp_op.is_neq() && mr.is_none() {
            return Some(MatchRes::Bytes(off_buf, None, buf, Encoding::Utf8));
        }

        mr
    }
}

impl From<RegexTest> for Test {
    fn from(value: RegexTest) -> Self {
        Self::Regex(value)
    }
}

#[flags(u8)]
#[derive(Debug, Serialize, Deserialize)]
enum StringMod {
    ForceBin = 1 << 0,
    UpperInsensitive = 1 << 1,
    LowerInsensitive = 1 << 2,
    FullWordMatch = 1 << 3,
    Trim = 1 << 4,
    ForceText = 1 << 5,
    CompactWhitespace = 1 << 6,
    OptBlank = 1 << 7,
}

impl StringModFlags {
    /// Whether a match's consumption can genuinely exceed the matched
    /// pattern's own length
    #[inline(always)]
    fn has_unbounded_length(&self) -> bool {
        !self.is_disjoint(StringMod::CompactWhitespace | StringMod::OptBlank)
    }

    /// FullWordMatch needs to peek one byte past the pattern's own
    /// length, to check that byte isn't part of the same word.
    #[inline(always)]
    fn word_boundary_lookahead(&self) -> u64 {
        self.contains(StringMod::FullWordMatch) as u64
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct StringTest {
    test_val: TestValue<Vec<u8>>,
    cmp_op: CmpOp,
    length: Option<usize>,
    mods: StringModFlags,
    binary: bool,
}

impl From<StringTest> for Test {
    fn from(value: StringTest) -> Self {
        Self::String(value)
    }
}

#[inline(always)]
fn string_match(str: &[u8], mods: StringModFlags, buf: &[u8]) -> (bool, usize) {
    let mut consumed = 0;
    // we can do a simple string comparison
    if mods.is_disjoint(
        StringMod::UpperInsensitive
            | StringMod::LowerInsensitive
            | StringMod::FullWordMatch
            | StringMod::CompactWhitespace
            | StringMod::OptBlank,
    ) {
        // we check if target contains
        if buf.starts_with(str) {
            (true, str.len())
        } else {
            (false, consumed)
        }
    } else {
        let mut i_src = 0;
        let mut iter = buf.iter().peekable();

        macro_rules! consume_target {
            () => {{
                if iter.next().is_some() {
                    consumed += 1;
                }
            }};
        }

        macro_rules! continue_next_iteration {
            () => {{
                consume_target!();
                i_src += 1;
                continue;
            }};
        }

        while let Some(&&b) = iter.peek() {
            let Some(&ref_byte) = str.get(i_src) else {
                break;
            };

            if mods.contains(StringMod::OptBlank) && (b == b' ' || ref_byte == b' ') {
                if b == b' ' {
                    // we ignore whitespace in target
                    consume_target!();
                }

                if ref_byte == b' ' {
                    // we ignore whitespace in test
                    i_src += 1;
                }

                continue;
            }

            if mods.contains(StringMod::UpperInsensitive) {
                //upper case characters in the magic match both lower and upper case characters in the target
                if ref_byte.is_ascii_uppercase() && ref_byte == b.to_ascii_uppercase()
                    || ref_byte == b
                {
                    continue_next_iteration!()
                }
            }

            if mods.contains(StringMod::LowerInsensitive)
                && (ref_byte.is_ascii_lowercase() && ref_byte == b.to_ascii_lowercase()
                    || ref_byte == b)
            {
                continue_next_iteration!()
            }

            if mods.contains(StringMod::CompactWhitespace) && ref_byte == b' ' {
                let mut src_blk = 0;
                while let Some(b' ') = str.get(i_src) {
                    src_blk += 1;
                    i_src += 1;
                }

                let mut tgt_blk = 0;
                while let Some(b' ') = iter.peek() {
                    tgt_blk += 1;
                    consume_target!();
                }

                if src_blk > tgt_blk {
                    return (false, consumed);
                }

                continue;
            }

            if ref_byte == b {
                continue_next_iteration!()
            } else {
                return (false, consumed);
            }
        }

        if mods.contains(StringMod::FullWordMatch)
            && let Some(b) = iter.peek()
            && !b.is_ascii_whitespace()
        {
            return (false, consumed);
        }

        (
            consumed > 0 && str.get(i_src).is_none() && consumed <= buf.len(),
            consumed,
        )
    }
}

impl StringTest {
    fn has_length_mod(&self) -> bool {
        !self.mods.is_disjoint(
            StringMod::UpperInsensitive
                | StringMod::LowerInsensitive
                | StringMod::FullWordMatch
                | StringMod::CompactWhitespace
                | StringMod::OptBlank,
        )
    }

    #[inline(always)]
    fn test_value_len(&self) -> usize {
        match self.test_val.as_ref() {
            TestValue::Value(s) => s.len(),
            TestValue::Any => 0,
        }
    }
}

#[derive(Clone, Serialize, Deserialize)]
struct ByteVec(Vec<u8>);

impl Debug for ByteVec {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "\"{}\"", debug_string_from_vec_u8(self))
    }
}

impl From<Vec<u8>> for ByteVec {
    fn from(value: Vec<u8>) -> Self {
        Self(value)
    }
}

impl Deref for ByteVec {
    type Target = Vec<u8>;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct SearchTest {
    str: ByteVec,
    n_pos: Option<usize>,
    str_mods: StringModFlags,
    re_mods: ReModFlags,
    binary: bool,
    cmp_op: CmpOp,
}

impl From<SearchTest> for Test {
    fn from(value: SearchTest) -> Self {
        Self::Search(value)
    }
}

impl SearchTest {
    // off_buf: absolute buffer offset in content
    #[inline]
    fn match_buf<'buf>(&self, off_buf: u64, buf: &'buf [u8]) -> Option<MatchRes<'buf>> {
        let mut i = 0;

        let needle = self.str.first()?;

        // A match may only *start* within n_pos -- same as libmagic's own
        // `idx < str_range` candidate loop
        let scan_end = self
            .n_pos
            .map(|n| n.saturating_add(1).min(buf.len()))
            .unwrap_or(buf.len());

        while i < scan_end {
            // we cannot match if the first character isn't the same
            // so we accelerate the search by finding potential matches
            let Some(k) = memchr(*needle, &buf[i..scan_end]) else {
                break;
            };

            i += k;

            // if we want a full word match
            if self.str_mods.contains(StringMod::FullWordMatch) {
                let prev_is_whitespace = buf
                    .get(i.saturating_sub(1))
                    .map(|c| c.is_ascii_whitespace())
                    .unwrap_or_default();

                // if it is not the first character
                // and its previous character isn't
                // a whitespace. It cannot be a
                // fullword match
                if i > 0 && !prev_is_whitespace {
                    i += 1;
                    continue;
                }
            }

            let pos = i;
            let (ok, consumed) = string_match(&self.str, self.str_mods, &buf[i..]);

            if ok {
                return Some(MatchRes::Bytes(
                    off_buf.saturating_add(pos as u64),
                    None,
                    &buf[i..i + consumed],
                    Encoding::Utf8,
                ));
            } else {
                i += max(consumed, 1)
            }
        }

        // handles the case where we want the string not to be found
        if self.cmp_op.is_neq() {
            return Some(MatchRes::Bytes(off_buf, None, buf, Encoding::Utf8));
        }

        None
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct ScalarTest {
    ty: ScalarDataType,
    transform: Option<ScalarTransform>,
    cmp_op: CmpOp,
    test_val: TestValue<Scalar>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct FloatTest {
    ty: FloatDataType,
    transform: Option<FloatTransform>,
    cmp_op: CmpOp,
    test_val: TestValue<Float>,
}

// the value read from the haystack we want to match against
// 'buf is the lifetime of the buffer we are scanning
#[derive(PartialEq)]
enum ReadValue<'buf> {
    Float(u64, Float),
    Scalar(u64, Scalar),
    Bytes(u64, &'buf [u8]),
}

impl<'buf> Debug for ReadValue<'buf> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Float(_, fl) => write!(f, "{fl:?}"),
            Self::Scalar(_, s) => write!(f, "{s:?}"),
            Self::Bytes(_, b) => {
                if b.len() <= 128 {
                    write!(f, "\"{}\"", debug_string_from_vec_u8(b))
                } else {
                    let limit = 128;
                    write!(
                        f,
                        "\"{}\" (first {limit} bytes)",
                        debug_string_from_vec_u8(&b[..limit])
                    )
                }
            }
        }
    }
}

impl DynDisplay for ReadValue<'_> {
    fn dyn_fmt(&self, f: &mut dyf::Formatter<'_>) -> dyf::Result {
        use std::fmt::Write;
        match self {
            Self::Float(_, s) => DynDisplay::dyn_fmt(s, f),
            Self::Scalar(_, s) => DynDisplay::dyn_fmt(s, f),
            Self::Bytes(_, b) => Ok(write!(f, "{b:?}")?),
        }
    }
}

impl DynDisplay for &ReadValue<'_> {
    fn dyn_fmt(&self, f: &mut dyf::Formatter<'_>) -> dyf::Result {
        // Dereference self to get the TestValue and call its fmt method
        DynDisplay::dyn_fmt(*self, f)
    }
}

impl Display for ReadValue<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Float(_, v) => write!(f, "{v}"),
            Self::Scalar(_, s) => write!(f, "{s}"),
            Self::Bytes(_, b) => write!(f, "{b:?}"),
        }
    }
}

enum Encoding {
    Utf16(String16Encoding),
    Utf8,
}

// Carry the offset of the start of the data in the stream
// and the data itself
enum MatchRes<'buf> {
    // Bytes.0: offset of the match
    // Bytes.1: optional end of match (to address the need of EOL adjustment in string regex)
    // Bytes.2: the bytes matching
    // Bytes.3: encoding of the buffer
    Bytes(u64, Option<u64>, &'buf [u8], Encoding),
    Scalar(u64, Scalar),
    Float(u64, Float),
}

impl DynDisplay for &MatchRes<'_> {
    fn dyn_fmt(&self, f: &mut dyf::Formatter) -> dyf::Result {
        (*self).dyn_fmt(f)
    }
}

impl DynDisplay for MatchRes<'_> {
    fn dyn_fmt(&self, f: &mut dyf::Formatter) -> dyf::Result {
        match self {
            Self::Scalar(_, v) => v.dyn_fmt(f),
            Self::Float(_, v) => v.dyn_fmt(f),
            Self::Bytes(_, _, v, enc) => match enc {
                Encoding::Utf8 => String::from_utf8_lossy(v).to_string().dyn_fmt(f),
                Encoding::Utf16(enc) => {
                    let utf16: Vec<u16> = slice_to_utf16_iter(v, *enc).collect();
                    String::from_utf16_lossy(&utf16).dyn_fmt(f)
                }
            },
        }
    }
}

impl MatchRes<'_> {
    // start offset of the match
    #[inline]
    fn start_offset(&self) -> u64 {
        match self {
            MatchRes::Bytes(o, _, _, _) => *o,
            MatchRes::Scalar(o, _) => *o,
            MatchRes::Float(o, _) => *o,
        }
    }

    // start offset of the match
    #[inline]
    fn end_offset(&self) -> u64 {
        match self {
            MatchRes::Bytes(start, end, buf, _) => match end {
                Some(end) => *end,
                None => start.saturating_add(buf.len() as u64),
            },
            MatchRes::Scalar(o, sc) => o.add(sc.size_of() as u64),
            MatchRes::Float(o, f) => o.add(f.size_of() as u64),
        }
    }
}

fn slice_to_utf16_iter(read: &[u8], encoding: String16Encoding) -> impl Iterator<Item = u16> {
    let even = read
        .iter()
        .enumerate()
        .filter(|(i, _)| i % 2 == 0)
        .map(|t| t.1);

    let odd = read
        .iter()
        .enumerate()
        .filter(|(i, _)| i % 2 != 0)
        .map(|t| t.1);

    even.zip(odd).map(move |(e, o)| match encoding {
        String16Encoding::Le => u16::from_le_bytes([*e, *o]),
        String16Encoding::Be => u16::from_be_bytes([*e, *o]),
    })
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
enum String16Encoding {
    Le,
    Be,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct String16Test {
    orig: String,
    test_val: TestValue<Vec<u16>>,
    encoding: String16Encoding,
}

impl String16Test {
    /// if the test value is a specific value this method returns
    /// the number of utf16 characters. To obtain the length in
    /// bytes the return value needs to be multiplied by two.
    #[inline(always)]
    fn test_value_len(&self) -> usize {
        match self.test_val.as_ref() {
            TestValue::Value(str16) => str16.len(),
            TestValue::Any => 0,
        }
    }
}

#[flags(u8)]
#[derive(Debug, Serialize, Deserialize)]
enum IndirectMod {
    Relative = 1 << 0,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
enum PStringLen {
    Byte,    // B
    ShortBe, // H
    ShortLe, // h
    LongBe,  // L
    LongLe,  // l
}

impl PStringLen {
    #[inline(always)]
    const fn size_of_len(&self) -> usize {
        match self {
            PStringLen::Byte => 1,
            PStringLen::ShortBe => 2,
            PStringLen::ShortLe => 2,
            PStringLen::LongBe => 4,
            PStringLen::LongLe => 4,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct PStringTest {
    len: PStringLen,
    test_val: TestValue<Vec<u8>>,
    include_len: bool,
}

impl PStringTest {
    #[inline]
    fn read<'cache, R: DataRead>(
        &self,
        haystack: &'cache mut R,
    ) -> Result<Option<&'cache [u8]>, Error> {
        let mut len = match self.len {
            PStringLen::Byte => read_le!(haystack, u8) as u32,
            PStringLen::ShortBe => read_be!(haystack, u16) as u32,
            PStringLen::ShortLe => read_le!(haystack, u16) as u32,
            PStringLen::LongBe => read_be!(haystack, u32),
            PStringLen::LongLe => read_le!(haystack, u32),
        } as usize;

        if self.include_len {
            len = len.saturating_sub(self.len.size_of_len())
        }

        if let TestValue::Value(s) = self.test_val.as_ref()
            && len != s.len()
        {
            return Ok(None);
        }

        let read = haystack.read_exact_count(len as u64)?;

        Ok(Some(read))
    }

    #[inline(always)]
    fn test_value_len(&self) -> usize {
        match self.test_val.as_ref() {
            TestValue::Value(s) => s.len(),
            TestValue::Any => 0,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
enum Test {
    Name(String),
    Use(bool, String),
    Scalar(ScalarTest),
    Float(FloatTest),
    String(StringTest),
    Search(SearchTest),
    PString(PStringTest),
    Regex(RegexTest),
    Indirect(IndirectModFlags),
    String16(String16Test),
    // FIXME: placeholder for strength computation
    #[allow(dead_code)]
    Der,
    Clear,
    Default,
}

impl Display for Test {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Test::Name(name) => write!(f, "name {name}"),
            Test::Use(flip, rule) => {
                if *flip {
                    write!(f, "use {rule}")
                } else {
                    write!(f, "use ^{rule}")
                }
            }
            Test::Scalar(st) => write!(f, "{st:?}"),
            Test::Float(ft) => write!(f, "{ft:?}"),
            Test::String(st) => write!(f, "{st:?}"),
            Test::Search(st) => write!(f, "{st:?}"),
            Test::PString(pt) => write!(f, "{pt:?}"),
            Test::Regex(rt) => write!(f, "{rt:?}"),
            Test::Indirect(fs) => write!(f, "indirect {fs:?}"),
            Test::String16(s16t) => write!(f, "{s16t:?}"),
            Test::Der => write!(f, "unimplemented der"),
            Test::Clear => write!(f, "clear"),
            Test::Default => write!(f, "default"),
        }
    }
}

impl Test {
    // read the value to test from the haystack
    #[inline]
    fn read_test_value<'haystack, D: DataRead>(
        &self,
        haystack: &'haystack mut D,
        switch_endianness: bool,
    ) -> Result<Option<ReadValue<'haystack>>, Error> {
        let test_value_offset = haystack.stream_position();

        match self {
            Self::Scalar(t) => {
                t.ty.read(haystack, switch_endianness)
                    .map(|s| Some(ReadValue::Scalar(test_value_offset, s)))
            }

            Self::Float(t) => {
                t.ty.read(haystack, switch_endianness)
                    .map(|f| Some(ReadValue::Float(test_value_offset, f)))
            }
            Self::String(t) => {
                match t.test_val.as_ref() {
                    TestValue::Value(str) => {
                        let buf = if let Some(length) = t.length {
                            // if there is a length specified
                            haystack.read_exact_count(length as u64)?
                        } else {
                            // no length specified we read until end of string

                            match t.cmp_op {
                                CmpOp::Eq | CmpOp::Neq => {
                                    if t.mods.has_unbounded_length() {
                                        haystack.read_count(FILE_BYTES_MAX as u64)?
                                    } else {
                                        let len =
                                            str.len() as u64 + t.mods.word_boundary_lookahead();
                                        haystack.read_count(len)?
                                    }
                                }
                                CmpOp::Lt | CmpOp::Gt => {
                                    let read =
                                        haystack.read_until_any_delim_or_limit(b"\n\0", 8092)?;

                                    if read.ends_with(b"\0") || read.ends_with(b"\n") {
                                        &read[..read.len() - 1]
                                    } else {
                                        read
                                    }
                                }
                                _ => {
                                    return Err(Error::Msg(format!(
                                        "string test does not support {:?} operator",
                                        t.cmp_op
                                    )));
                                }
                            }
                        };

                        Ok(Some(ReadValue::Bytes(test_value_offset, buf)))
                    }
                    TestValue::Any => {
                        let read = haystack.read_until_any_delim_or_limit(b"\0\n", 8192)?;
                        // we don't take last byte if it matches end of string
                        let bytes = if read.ends_with(b"\0") || read.ends_with(b"\n") {
                            &read[..read.len() - 1]
                        } else {
                            read
                        };

                        Ok(Some(ReadValue::Bytes(test_value_offset, bytes)))
                    }
                }
            }

            Self::String16(t) => {
                match t.test_val.as_ref() {
                    TestValue::Value(str16) => {
                        let read = haystack.read_exact_count((str16.len() * 2) as u64)?;

                        Ok(Some(ReadValue::Bytes(test_value_offset, read)))
                    }
                    TestValue::Any => {
                        let read = haystack.read_until_utf16_or_limit(b"\x00\x00", 8192)?;

                        // we make sure we have an even number of elements
                        let end = if read.len() % 2 == 0 {
                            read.len()
                        } else {
                            // we decide to read anyway even though
                            // length isn't even
                            read.len().saturating_sub(1)
                        };

                        Ok(Some(ReadValue::Bytes(test_value_offset, &read[..end])))
                    }
                }
            }

            Self::PString(t) => {
                let Some(read) = t.read(haystack)? else {
                    return Ok(None);
                };
                Ok(Some(ReadValue::Bytes(test_value_offset, read)))
            }

            Self::Search(s) => {
                let length = if s.str_mods.has_unbounded_length() {
                    FILE_BYTES_MAX as u64
                } else {
                    s.n_pos
                        .map(|n| n as u64)
                        .unwrap_or(FILE_BYTES_MAX as u64)
                        .saturating_add(s.str.len() as u64)
                        .saturating_add(s.str_mods.word_boundary_lookahead())
                };
                let buf = haystack.read_count(length)?;
                Ok(Some(ReadValue::Bytes(test_value_offset, buf)))
            }

            Self::Regex(r) => {
                let length = {
                    match r.length {
                        Some(len) => {
                            if r.mods.contains(ReMod::LineLimit) {
                                len * 80
                            } else {
                                len
                            }
                        }

                        None => FILE_REGEX_MAX,
                    }
                };

                let read = haystack.read_count(length as u64)?;
                Ok(Some(ReadValue::Bytes(test_value_offset, read)))
            }

            Self::Name(_)
            | Self::Use(_, _)
            | Self::Indirect(_)
            | Self::Clear
            | Self::Default
            | Self::Der => Err(Error::msg("no value to read for this test")),
        }
    }

    #[inline(always)]
    fn match_value<'s>(
        &'s self,
        tv: &ReadValue<'s>,
        stream_kind: StreamKind,
    ) -> Option<MatchRes<'s>> {
        match (self, tv) {
            (Self::Scalar(t), ReadValue::Scalar(o, ts)) => {
                let read_value: Scalar = match t.transform.as_ref() {
                    Some(t) => t.apply(*ts)?,
                    None => *ts,
                };

                match t.test_val {
                    TestValue::Value(test_value) => {
                        let ok = match t.cmp_op {
                            // NOTE: this should not happen in practice because
                            // we convert it into Eq equivalent at parsing time
                            CmpOp::Not => read_value == !test_value,
                            CmpOp::Eq => read_value == test_value,
                            CmpOp::Lt => read_value < test_value,
                            CmpOp::Gt => read_value > test_value,
                            CmpOp::Neq => read_value != test_value,
                            CmpOp::BitAnd => read_value & test_value == test_value,
                            CmpOp::Xor => (read_value & test_value).is_zero(),
                        };

                        if ok {
                            Some(MatchRes::Scalar(*o, read_value))
                        } else {
                            None
                        }
                    }

                    TestValue::Any => Some(MatchRes::Scalar(*o, read_value)),
                }
            }

            (Self::Float(t), ReadValue::Float(o, f)) => {
                let read_value: Float = t.transform.as_ref().map(|t| t.apply(*f)).unwrap_or(*f);

                match t.test_val {
                    TestValue::Value(tf) => {
                        let ok = match t.cmp_op {
                            CmpOp::Eq => read_value == tf,
                            CmpOp::Lt => read_value < tf,
                            CmpOp::Gt => read_value > tf,
                            CmpOp::Neq => read_value != tf,
                            _ => {
                                // this should never be reached as we validate
                                // operator in parser
                                debug_panic!("unsupported float comparison");
                                debug!("unsupported float comparison");
                                false
                            }
                        };

                        if ok {
                            Some(MatchRes::Float(*o, read_value))
                        } else {
                            None
                        }
                    }
                    TestValue::Any => Some(MatchRes::Float(*o, read_value)),
                }
            }

            (Self::String(st), ReadValue::Bytes(o, buf)) => {
                macro_rules! trim_buf {
                    ($buf: expr) => {{
                        if st.mods.contains(StringMod::Trim) {
                            $buf.trim_ascii()
                        } else {
                            $buf
                        }
                    }};
                }

                match st.test_val.as_ref() {
                    TestValue::Value(str) => {
                        match st.cmp_op {
                            CmpOp::Eq => {
                                if let (true, _) = string_match(str, st.mods, buf) {
                                    Some(MatchRes::Bytes(*o, None, trim_buf!(str), Encoding::Utf8))
                                } else {
                                    None
                                }
                            }
                            CmpOp::Neq => {
                                if let (false, _) = string_match(str, st.mods, buf) {
                                    Some(MatchRes::Bytes(*o, None, trim_buf!(str), Encoding::Utf8))
                                } else {
                                    None
                                }
                            }
                            CmpOp::Gt => {
                                if buf.len() > str.len() {
                                    Some(MatchRes::Bytes(*o, None, trim_buf!(buf), Encoding::Utf8))
                                } else {
                                    None
                                }
                            }
                            CmpOp::Lt => {
                                if buf.len() < str.len() {
                                    Some(MatchRes::Bytes(*o, None, trim_buf!(buf), Encoding::Utf8))
                                } else {
                                    None
                                }
                            }

                            // unsupported for strings
                            _ => {
                                // this should never be reached as we validate
                                // operator in parser
                                debug_panic!("unsupported string comparison");
                                debug!("unsupported string comparison");
                                None
                            }
                        }
                    }
                    TestValue::Any => {
                        Some(MatchRes::Bytes(*o, None, trim_buf!(buf), Encoding::Utf8))
                    }
                }
            }

            (Self::PString(m), ReadValue::Bytes(o, buf)) => match m.test_val.as_ref() {
                TestValue::Value(psv) => {
                    if buf == psv {
                        Some(MatchRes::Bytes(*o, None, buf, Encoding::Utf8))
                    } else {
                        None
                    }
                }
                TestValue::Any => Some(MatchRes::Bytes(*o, None, buf, Encoding::Utf8)),
            },

            (Self::String16(t), ReadValue::Bytes(o, buf)) => {
                match t.test_val.as_ref() {
                    TestValue::Value(str16) => {
                        // strings cannot be equal
                        if str16.len() * 2 != buf.len() {
                            return None;
                        }

                        // we check string equality
                        for (i, utf16_char) in slice_to_utf16_iter(buf, t.encoding).enumerate() {
                            if str16[i] != utf16_char {
                                return None;
                            }
                        }

                        Some(MatchRes::Bytes(
                            *o,
                            None,
                            t.orig.as_bytes(),
                            Encoding::Utf16(t.encoding),
                        ))
                    }

                    TestValue::Any => {
                        Some(MatchRes::Bytes(*o, None, buf, Encoding::Utf16(t.encoding)))
                    }
                }
            }

            (Self::Regex(r), ReadValue::Bytes(o, buf)) => r.match_buf(*o, stream_kind, buf),

            (Self::Search(t), ReadValue::Bytes(o, buf)) => t.match_buf(*o, buf),

            _ => None,
        }
    }

    #[inline(always)]
    fn strength(&self) -> u64 {
        const MULT: usize = 10;

        let mut out = 2 * MULT;

        // FIXME: octal is missing but it is not used in practice ...
        match self {
            Test::Scalar(s) => {
                out += s.ty.type_size() * MULT;
            }

            Test::Float(t) => {
                out += t.ty.type_size() * MULT;
            }

            Test::String(t) => out += t.test_value_len().saturating_mul(MULT),

            Test::PString(t) => out += t.test_value_len().saturating_mul(MULT),

            Test::Search(s) => {
                // NOTE: this implementation deviates from what is in
                // C libmagic. The purpose of this implementation is to
                // minimize the difference between similar tests,
                // implemented differently (ex: string test VS very localized search test).
                let n_pos = s.n_pos.unwrap_or(FILE_BYTES_MAX);

                match n_pos {
                    // a search on one line should be equivalent to a string match
                    0..=80 => out += s.str.len().saturating_mul(MULT),
                    // search on the first 3 lines gets a little penalty
                    81..=240 => out += s.str.len() * s.str.len().clamp(0, MULT - 2),
                    // a search on more than 3 lines isn't considered very accurate
                    _ => out += s.str.len(),
                }
            }

            Test::Regex(r) => {
                // NOTE: this implementation deviates from what is in
                // C libmagic. The purpose of this implementation is to
                // minimize the difference between similar tests,
                // implemented differently (ex: string test VS very localized regex test).

                // we divide length by the number of capture group
                // which gives us a value close to he average string
                // length match in the regex.
                let v = r.non_magic_len / r.re.captures_len.max(1);

                let len = r
                    .length
                    .map(|l| {
                        if r.mods.contains(ReMod::LineLimit) {
                            l * 80
                        } else {
                            l
                        }
                    })
                    .unwrap_or(FILE_BYTES_MAX);

                match len {
                    // a search on one line should be equivalent to a string match
                    0..=80 => out += v.saturating_mul(MULT),
                    // search on the first 3 lines gets a little penalty
                    81..=240 => out += v * v.clamp(0, MULT - 2),
                    // a search on more than 3 lines isn't considered very accurate
                    _ => out += v,
                }
            }

            Test::String16(t) => {
                // NOTE: in libmagic the result is div by 2
                // but I GUESS it is because the len is expressed
                // in number bytes. In our case length is expressed
                // in number of u16 so we shouldn't divide.
                out += t.test_value_len().saturating_mul(MULT);
            }

            Test::Der => out += MULT,

            Test::Default | Test::Name(_) | Test::Use(_, _) | Test::Indirect(_) | Test::Clear => {
                return 0;
            }
        }

        // matching any output gets penalty
        if self.is_match_any() {
            return 0;
        }

        if let Some(op) = self.cmp_op() {
            match op {
                // matching almost any gets penalty
                CmpOp::Neq => out = 0,
                CmpOp::Eq | CmpOp::Not => out += MULT,
                CmpOp::Lt | CmpOp::Gt => out -= 2 * MULT,
                CmpOp::Xor | CmpOp::BitAnd => out -= MULT,
            }
        }

        out as u64
    }

    #[inline(always)]
    fn cmp_op(&self) -> Option<CmpOp> {
        match self {
            Self::String(t) => Some(t.cmp_op),
            Self::Scalar(s) => Some(s.cmp_op),
            Self::Float(t) => Some(t.cmp_op),
            Self::Search(t) => Some(t.cmp_op),
            Self::Regex(t) => Some(t.cmp_op),
            Self::Name(_)
            | Self::Use(_, _)
            | Self::PString(_)
            | Self::Clear
            | Self::Default
            | Self::Indirect(_)
            | Self::String16(_)
            | Self::Der => None,
        }
    }

    #[inline(always)]
    fn is_recursive(&self) -> bool {
        matches!(self, Test::Use(_, _) | Test::Indirect(_))
    }

    #[inline(always)]
    fn is_match_any(&self) -> bool {
        match self {
            Test::Name(_) => false,
            Test::Use(_, _) => false,
            Test::Scalar(scalar_test) => matches!(scalar_test.test_val, TestValue::Any),
            Test::Float(float_test) => matches!(float_test.test_val, TestValue::Any),
            Test::String(string_test) => matches!(string_test.test_val, TestValue::Any),
            Test::Search(_) => false,
            Test::PString(pstring_test) => matches!(pstring_test.test_val, TestValue::Any),
            Test::Regex(_) => false,
            Test::Indirect(_) => false,
            Test::String16(string16_test) => matches!(string16_test.test_val, TestValue::Any),
            Test::Der => false,
            Test::Clear => false,
            Test::Default => false,
        }
    }

    /// Whether this test carries an explicit `/b` (force-binary)
    /// modifier, as opposed to a type's default classification.
    #[inline(always)]
    fn has_explicit_bin_mod(&self) -> bool {
        match self {
            Self::String(t) => t.mods.contains(StringMod::ForceBin),
            Self::Search(t) => t.str_mods.contains(StringMod::ForceBin),
            Self::Regex(t) => {
                t.mods.contains(ReMod::ForceBin) || t.str_mods.contains(StringMod::ForceBin)
            }
            _ => false,
        }
    }

    /// Same as [`Test::has_explicit_bin_mod`], for an explicit `/t`
    /// (force-text) modifier.
    #[inline(always)]
    fn has_explicit_text_mod(&self) -> bool {
        match self {
            Self::String(t) => t.mods.contains(StringMod::ForceText),
            Self::Search(t) => t.str_mods.contains(StringMod::ForceText),
            Self::Regex(t) => {
                t.mods.contains(ReMod::ForceText) || t.str_mods.contains(StringMod::ForceText)
            }
            _ => false,
        }
    }

    /// Type-based binary/text default, ignoring explicit `/b`/`/t`.
    /// Numeric/string/pstring/string16/DER default to binary;
    /// `regex`/`search` are content-sniffed; structural types have no
    /// binary-or-text nature, hence `None`.
    #[inline(always)]
    fn type_default_is_binary(&self) -> Option<bool> {
        match self {
            Self::Scalar(_) | Self::Float(_) | Self::Der => Some(true),
            Self::String(_) | Self::PString(_) | Self::String16(_) => Some(true),
            Self::Search(t) => Some(t.binary),
            Self::Regex(t) => Some(t.binary),
            Self::Name(_) | Self::Use(_, _) | Self::Indirect(_) | Self::Clear | Self::Default => {
                None
            }
        }
    }

    /// Classifies the runtime stream-kind gate for this entry (cached on
    /// [`Match`]). `/bt` together means never skip, not a contradiction.
    /// Binary-default entries never skip either way; only default-text
    /// skips, and only on a binary stream.
    #[inline(always)]
    fn stream_gate(&self) -> StreamGate {
        let explicit_bin = self.has_explicit_bin_mod();
        let explicit_text = self.has_explicit_text_mod();
        if explicit_bin && explicit_text {
            return StreamGate::Never;
        }
        if explicit_bin {
            return StreamGate::SkipOnText;
        }
        if explicit_text || self.type_default_is_binary() == Some(false) {
            return StreamGate::SkipOnBinary;
        }
        StreamGate::Never
    }

    /// Returns true if the [`Test`] consumes bytes
    #[inline(always)]
    fn consumes_bytes(&self) -> bool {
        !matches!(
            self,
            Test::Use(_, _) | Test::Indirect(_) | Test::Default | Test::Clear | Test::Name(_)
        )
    }
}

/// Cached classification of an entry's runtime stream-kind gate. See
/// [`Test::stream_gate`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
enum StreamGate {
    SkipOnText,
    SkipOnBinary,
    Never,
}

impl StreamGate {
    #[inline(always)]
    fn should_skip(self, stream_kind: StreamKind) -> bool {
        match self {
            Self::SkipOnText => stream_kind.is_text(),
            Self::SkipOnBinary => stream_kind.is_binary(),
            Self::Never => false,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
enum OffsetType {
    Byte,
    DoubleLe,
    DoubleBe,
    ShortLe,
    ShortBe,
    Id3Le,
    Id3Be,
    LongLe,
    LongBe,
    Middle,
    Octal,
    QuadBe,
    QuadLe,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
enum Shift {
    Direct(u64),
    Indirect(i64),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
struct IndOffset {
    // where to find the offset
    off_addr: DirOffset,
    // signed or unsigned
    signed: bool,
    // type of the offset
    ty: OffsetType,
    op: Option<Op>,
    shift: Option<Shift>,
}

impl IndOffset {
    // if we overflow we must not return an offset
    fn read_offset<D: DataRead>(
        &self,
        haystack: &mut D,
        offset_base: Option<u64>,
        last_upper_match_offset: Option<u64>,
    ) -> Result<Option<u64>, io::Error> {
        let offset_address = match self.off_addr {
            DirOffset::Start(s) => {
                let Some(o) = s.checked_add(offset_base.unwrap_or_default()) else {
                    return Ok(None);
                };

                haystack.seek(SeekFrom::Start(o))?
            }
            DirOffset::LastUpper(c) => haystack.seek(SeekFrom::Start(
                (last_upper_match_offset.unwrap_or_default() as i64 + c) as u64,
            ))?,
            DirOffset::End(e) => haystack.seek(SeekFrom::End(e))?,
        };

        macro_rules! read_value {
            () => {
                match self.ty {
                    OffsetType::Byte => {
                        if self.signed {
                            read_le!(haystack, u8) as u64
                        } else {
                            read_le!(haystack, i8) as u64
                        }
                    }
                    OffsetType::DoubleLe => read_le!(haystack, f64) as u64,
                    OffsetType::DoubleBe => read_be!(haystack, f64) as u64,
                    OffsetType::ShortLe => {
                        if self.signed {
                            read_le!(haystack, i16) as u64
                        } else {
                            read_le!(haystack, u16) as u64
                        }
                    }
                    OffsetType::ShortBe => {
                        if self.signed {
                            read_be!(haystack, i16) as u64
                        } else {
                            read_be!(haystack, u16) as u64
                        }
                    }
                    OffsetType::Id3Le => decode_id3(read_le!(haystack, u32)) as u64,
                    OffsetType::Id3Be => decode_id3(read_be!(haystack, u32)) as u64,
                    OffsetType::LongLe => {
                        if self.signed {
                            read_le!(haystack, i32) as u64
                        } else {
                            read_le!(haystack, u32) as u64
                        }
                    }
                    OffsetType::LongBe => {
                        if self.signed {
                            read_be!(haystack, i32) as u64
                        } else {
                            read_be!(haystack, u32) as u64
                        }
                    }
                    OffsetType::Middle => read_me!(haystack) as u64,
                    OffsetType::Octal => {
                        if let Some(o) = read_octal_u64(haystack) {
                            o
                        } else {
                            debug!("failed to read octal offset @ {offset_address}");
                            return Ok(None);
                        }
                    }
                    OffsetType::QuadLe => {
                        if self.signed {
                            read_le!(haystack, i64) as u64
                        } else {
                            read_le!(haystack, u64)
                        }
                    }
                    OffsetType::QuadBe => {
                        if self.signed {
                            read_be!(haystack, i64) as u64
                        } else {
                            read_be!(haystack, u64)
                        }
                    }
                }
            };
        }

        // in theory every offset read should end up in something seekable from start, so we can use u64 to store the result
        let o = read_value!();

        trace!(
            "offset read @ {offset_address} value={o} op={:?} shift={:?}",
            self.op, self.shift
        );

        // apply transformation
        if let (Some(op), Some(shift)) = (self.op, self.shift) {
            let shift = match shift {
                Shift::Direct(i) => i,
                Shift::Indirect(i) => {
                    let tmp = offset_address as i128 + i as i128;
                    if tmp.is_negative() {
                        return Ok(None);
                    } else {
                        haystack.seek(SeekFrom::Start(tmp as u64))?;
                    };
                    // NOTE: here we assume that the shift has the same
                    // type as the main offset !
                    read_value!()
                }
            };

            match op {
                Op::Add => return Ok(o.checked_add(shift)),
                Op::Mul => return Ok(o.checked_mul(shift)),
                Op::Sub => return Ok(o.checked_sub(shift)),
                Op::Div => return Ok(o.checked_div(shift)),
                Op::Mod => return Ok(o.checked_rem(shift)),
                Op::And => return Ok(Some(o & shift)),
                Op::Or => return Ok(Some(o | shift)),
                Op::Xor => return Ok(Some(o ^ shift)),
            }
        }

        Ok(Some(o))
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
enum DirOffset {
    Start(u64),
    // relative to the last up-level field
    LastUpper(i64),
    End(i64),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
enum Offset {
    Direct(DirOffset),
    Indirect(IndOffset),
}

impl Offset {
    #[inline(always)]
    fn is_indirect(&self) -> bool {
        matches!(self, Self::Indirect(_))
    }
}

impl From<DirOffset> for Offset {
    fn from(value: DirOffset) -> Self {
        Self::Direct(value)
    }
}

impl From<IndOffset> for Offset {
    fn from(value: IndOffset) -> Self {
        Self::Indirect(value)
    }
}

impl Display for DirOffset {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            DirOffset::Start(i) => write!(f, "{i}"),
            DirOffset::LastUpper(c) => write!(f, "&{c}"),
            DirOffset::End(e) => write!(f, "-{e}"),
        }
    }
}

impl Default for DirOffset {
    fn default() -> Self {
        Self::LastUpper(0)
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct Match {
    line: usize,
    depth: u8,
    offset: Offset,
    test: Test,
    test_strength: u64,
    message: Option<Message>,
    stream_gate: StreamGate,
}

impl From<Use> for Match {
    fn from(value: Use) -> Self {
        let test = Test::Use(value.switch_endianness, value.rule_name);
        let test_strength = test.strength();
        let stream_gate = test.stream_gate();
        Self {
            line: value.line,
            depth: value.depth,
            offset: value.start_offset,
            test,
            test_strength,
            message: value.message,
            stream_gate,
        }
    }
}

impl From<Name> for Match {
    fn from(value: Name) -> Self {
        let test = Test::Name(value.name);
        let test_strength = test.strength();
        let stream_gate = test.stream_gate();
        Self {
            line: value.line,
            depth: 0,
            offset: Offset::Direct(DirOffset::Start(0)),
            test,
            test_strength,
            message: value.message,
            stream_gate,
        }
    }
}

impl Match {
    /// Whether the runtime stream-kind gate should skip this entry.
    #[inline(always)]
    fn should_skip_for_stream(&self, stream_kind: StreamKind) -> bool {
        self.stream_gate.should_skip(stream_kind)
    }

    /// Turns the `Match`'s offset into an absolute offset from the start of the stream
    #[inline(always)]
    fn offset_from_start<D: DataRead>(
        &self,
        haystack: &mut D,
        offset_base: Option<u64>,
        last_level_offset: Option<u64>,
    ) -> Result<Option<u64>, io::Error> {
        match self.offset {
            Offset::Direct(dir_offset) => match dir_offset {
                DirOffset::Start(s) => Ok(Some(s)),
                DirOffset::LastUpper(shift) => {
                    let o = last_level_offset.unwrap_or_default() as i64 + shift;

                    if o >= 0 { Ok(Some(o as u64)) } else { Ok(None) }
                }
                DirOffset::End(e) => Ok(Some(haystack.offset_from_start(SeekFrom::End(e)))),
            },
            Offset::Indirect(ind_offset) => {
                let Some(o) = ind_offset.read_offset(haystack, offset_base, last_level_offset)?
                else {
                    return Ok(None);
                };

                Ok(Some(o))
            }
        }
    }

    /// This entry's own absolute anchor position.
    #[inline(always)]
    fn anchor_offset<D: DataRead>(
        &self,
        haystack: &mut D,
        buf_base_offset: Option<u64>,
        offset_base: Option<u64>,
        last_level_offset: Option<u64>,
    ) -> Result<Option<u64>, io::Error> {
        let Some(offset) = self.offset_from_start(haystack, offset_base, last_level_offset)? else {
            return Ok(None);
        };

        Ok(Some(match self.offset {
            // the result we get for an indirect offset is relative to
            // the start of the libmagic buffer so we need to add base to
            // make it absolute.
            Offset::Indirect(_) => buf_base_offset.unwrap_or_default().saturating_add(offset),
            // Bare offsets are relative to offset_base -- see
            // EntryNode::matches for how it's computed.
            Offset::Direct(DirOffset::Start(_)) => {
                offset_base.unwrap_or_default().saturating_add(offset)
            }
            _ => offset,
        }))
    }

    /// this method emulates the buffer based matching
    /// logic implemented in libmagic. It needs some aweful
    /// and weird offset convertions to turn buffer
    /// relative offsets (libmagic is based on) into
    /// absolute offset in the file.
    ///
    /// this method shoud bubble up only critical errors
    /// all the other errors should make the match result
    /// false and be logged via debug!
    ///
    /// the function returns an error if the maximum recursion
    /// has been reached or if a dependency rule is missing.
    #[inline]
    #[allow(clippy::too_many_arguments)]
    fn matches<'a: 'h, 'h, D: DataRead>(
        &'a self,
        source: Option<&str>,
        magic: &mut Magic<'a>,
        stream_kind: StreamKind,
        state: &mut MatchState,
        offset: u64,
        haystack: &'h mut D,
        switch_endianness: bool,
        db: &'a MagicDb,
        rec_depth: usize,
        test_depth: usize,
    ) -> Result<(bool, Option<MatchRes<'h>>), Error> {
        let source = source.unwrap_or("unknown");
        let line = self.line;

        if rec_depth >= MAX_RECURSION {
            return Err(Error::localized(
                source,
                line,
                Error::MaximumRecursion(MAX_RECURSION),
            ));
        }

        match &self.test {
            Test::Clear => {
                trace!("source={source} line={line} clear");
                state.clear_continuation_level(&self.continuation_level());
                Ok((true, None))
            }

            Test::Name(name) => {
                trace!(
                    "source={source} line={line} running rule {name} switch_endianness={switch_endianness}",
                );
                Ok((true, None))
            }

            Test::Use(flip_endianness, rule_name) => {
                trace!(
                    "source={source} line={line} use {rule_name} switch_endianness={flip_endianness}",
                );

                // switch_endianness must propagate down the rule call stack
                let switch_endianness = switch_endianness ^ flip_endianness;

                let dr: &DependencyRule = db.dependencies.get(rule_name).ok_or(
                    Error::localized(source, line, Error::MissingRule(rule_name.clone())),
                )?;

                let new_buf_base_off = if self.offset.is_indirect() {
                    Some(offset)
                } else {
                    None
                };

                let nmatch = dr.rule.magic(
                    magic,
                    stream_kind,
                    new_buf_base_off,
                    Some(offset),
                    haystack,
                    db,
                    switch_endianness,
                    rec_depth.saturating_add(1),
                    test_depth,
                )?;

                // The name is always true, so we consider there to be a match
                // if more than one test succeeded
                let matched = nmatch > 0;
                if matched {
                    state.set_continuation_level(self.continuation_level());
                }

                Ok((matched, None))
            }

            Test::Indirect(m) => {
                trace!(
                    "source={source} line={line} indirect mods={:?} offset={offset:#x}",
                    m
                );

                let new_buf_base_off = if m.contains(IndirectMod::Relative) {
                    Some(offset)
                } else {
                    None
                };

                // Own message prints only if the scan matches, spliced before its output.
                let msg_checkpoint = magic.message.len();

                let mut nmatch = 0u64;
                for r in db.rules.iter() {
                    nmatch = nmatch.saturating_add(r.magic(
                        magic,
                        stream_kind,
                        new_buf_base_off,
                        Some(offset),
                        haystack,
                        db,
                        false,
                        rec_depth.saturating_add(1),
                        test_depth,
                    )?);

                    if nmatch > 0 {
                        break;
                    }
                }

                if nmatch > 0
                    && let Some(msg) = self.message.as_ref()
                {
                    let msg = msg.to_string_lossy();
                    if !msg.is_empty() {
                        debug!("pushing message: msg={msg} len={}", msg.len());
                        magic.message.insert(msg_checkpoint, msg);
                    }
                }

                Ok((nmatch > 0, None))
            }

            Test::Default => {
                // default matches if nothing else at the continuation level matched
                let ok = !state.get_continuation_level(&self.continuation_level());

                trace!("source={source} line={line} default match={ok}");
                if ok {
                    state.set_continuation_level(self.continuation_level());
                }

                Ok((ok, None))
            }

            _ => {
                if let Err(e) = haystack.seek(SeekFrom::Start(offset)) {
                    debug!("source={source} line={line} failed to seek in haystack: {e}");
                    return Ok((false, None));
                }

                let mut trace_msg = None;

                if enabled!(Level::DEBUG) {
                    trace_msg = Some(vec![format!(
                        "source={source} line={line} depth={} stream_offset={:#x}",
                        self.depth,
                        haystack.stream_position()
                    )])
                }

                // NOTE: we may have a way to optimize here. In case we do a Any
                // test and we don't use the value to format the message, we don't
                // need to read the value.
                match self.test.read_test_value(haystack, switch_endianness) {
                    Err(e) => {
                        debug!(
                            "source={source} line={line} error while reading test value @{offset}: {e}",
                        );

                        // libmagic mget(): unreadable data satisfies a `!=` test.
                        if self.test.cmp_op().is_some_and(|op| op.is_neq()) {
                            trace!(
                                "source={source} line={line} unreadable data treated as match for negated test",
                            );
                            state.set_continuation_level(self.continuation_level());
                            return Ok((true, None));
                        }
                    }
                    Ok(opt_test_value) => {
                        if let Some(v) = trace_msg.as_mut() {
                            v.push(format!("test={}", self.test))
                        }

                        if let Some(v) = trace_msg.as_mut() {
                            let drv = match opt_test_value.as_ref() {
                                Some(r) => format!("{r:?}"),
                                None => String::new(),
                            };
                            v.push(format!("read_in_stream={drv}"))
                        }

                        let match_res =
                            opt_test_value.and_then(|tv| self.test.match_value(&tv, stream_kind));

                        if let Some(v) = trace_msg.as_mut() {
                            v.push(format!(
                                "message=\"{}\" match={}",
                                self.message
                                    .as_ref()
                                    .map(|fs| fs.to_string_lossy())
                                    .unwrap_or_default(),
                                match_res.is_some()
                            ))
                        }

                        // trace message
                        if enabled!(Level::DEBUG) && !enabled!(Level::TRACE) && match_res.is_some()
                        {
                            if let Some(m) = trace_msg {
                                debug!("{}", m.join(" "));
                            }
                        } else if enabled!(Level::TRACE)
                            && let Some(m) = trace_msg
                        {
                            trace!("{}", m.join(" "));
                        }

                        if let Some(mr) = match_res {
                            state.set_continuation_level(self.continuation_level());
                            return Ok((true, Some(mr)));
                        }
                    }
                }

                Ok((false, None))
            }
        }
    }

    #[inline(always)]
    fn continuation_level(&self) -> ContinuationLevel {
        ContinuationLevel(self.depth)
    }
}

#[derive(Debug, Clone)]
struct Use {
    line: usize,
    depth: u8,
    start_offset: Offset,
    rule_name: String,
    switch_endianness: bool,
    message: Option<Message>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct StrengthMod {
    op: Op,
    by: u8,
}

impl StrengthMod {
    #[inline(always)]
    fn apply(&self, strength: u64) -> u64 {
        let by = self.by as u64;
        debug!("applying strength modifier: {strength} {} {}", self.op, by);
        match self.op {
            Op::Mul => strength.saturating_mul(by),
            Op::Add => strength.saturating_add(by),
            Op::Sub => strength.saturating_sub(by),
            Op::Div => {
                if by > 0 {
                    strength.saturating_div(by)
                } else {
                    strength
                }
            }
            Op::Mod => strength % by,
            Op::And => strength & by,
            // this should never happen as strength operators
            // are enforced by our parser
            Op::Xor | Op::Or => {
                debug_panic!("unsupported strength operator");
                strength
            }
        }
    }
}

#[derive(Debug, Clone)]
enum Flag {
    Mime(String),
    Ext(HashSet<String>),
    Strength(StrengthMod),
    Apple(String),
}

#[derive(Debug, Clone)]
struct Name {
    line: usize,
    name: String,
    message: Option<Message>,
}

#[derive(Debug, Clone)]
enum Entry<'span> {
    Match(Span<'span>, Match),
    Flag(Span<'span>, Flag),
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct EntryNode {
    root: bool,
    entry: Match,
    children: Vec<EntryNode>,
    mimetype: Option<String>,
    apple: Option<String>,
    strength_mod: Option<StrengthMod>,
    exts: HashSet<String>,
}

#[derive(Debug, Default)]
struct EntryNodeVisitor {
    exts: HashSet<String>,
    score: u64,
    max_score: u64,
}

impl EntryNodeVisitor {
    fn new() -> Self {
        Self {
            ..Default::default()
        }
    }

    fn merge(&mut self, other: Self) {
        self.exts.extend(other.exts);
        self.max_score += other.max_score;
    }
}

impl EntryNode {
    #[inline]
    fn update_visitor(&self, v: &mut EntryNodeVisitor, depth: usize) {
        // update extensions
        for ext in self.exts.iter() {
            if !v.exts.contains(ext) {
                v.exts.insert(ext.clone());
            }
        }

        if self.root {
            let mut score = self.entry.test_strength;
            if let Some(sm) = self.strength_mod.as_ref() {
                score = sm.apply(score);
            }
            // libmagic gives entries with no message/description a bonus,
            // since they rely on later continuations to print anything.
            if self.entry.message.is_none() {
                score += 1;
            }
            v.score = score;

            v.max_score = v
                .max_score
                .saturating_add(score)
                .saturating_add(self.best_path_bonus(depth));
        }
    }

    /// The strongest additional strength achievable from a single
    /// root-to-leaf path through this node's local continuation tree.
    fn best_path_bonus(&self, depth: usize) -> u64 {
        self.children
            .iter()
            // `Test::Use` is excluded -- handled separately via `EntryNodeVisitor::merge`.
            .filter(|c| !matches!(c.entry.test, Test::Use(_, _)))
            .map(|c| {
                let d = depth.saturating_add(1);
                // Mirror runtime computation
                (c.entry.test_strength >> d).saturating_add(c.best_path_bonus(d))
            })
            .max()
            .unwrap_or(0)
    }

    fn visit(
        &self,
        v: &mut EntryNodeVisitor,
        deps: &HashMap<String, DependencyRule>,
        marked: &mut HashSet<String>,
        depth: usize,
    ) -> Result<(), Error> {
        // updating visitor
        self.update_visitor(v, depth);

        // Merge the dependency's contribution too, without skipping
        // recursion into this entry's own children below.
        if let Test::Use(_, ref name) = self.entry.test
            && !marked.contains(name)
        {
            marked.insert(name.clone());

            if let Some(r) = deps.get(name) {
                let dv = r.rule.visit_all_entries(deps, marked, depth)?;
                v.merge(dv);
            } else {
                return Err(Error::MissingRule(name.clone()));
            }
        }

        // recursively visiting
        for c in self.children.iter() {
            c.visit(v, deps, marked, depth + 1)?;
        }

        Ok(())
    }

    /// Executes the magic matching logic recursively and returns the count of matches that produce messages.
    /// Matches that don't result in message appends are not counted, consistent with libmagic's behavior.
    #[inline]
    #[allow(clippy::too_many_arguments)]
    fn matches<'r, D: DataRead>(
        &'r self,
        opt_source: Option<&str>,
        magic: &mut Magic<'r>,
        state: &mut MatchState,
        stream_kind: StreamKind,
        buf_base_offset: Option<u64>,
        offset_base: Option<u64>,
        last_level_offset: Option<u64>,
        haystack: &mut D,
        db: &'r MagicDb,
        switch_endianness: bool,
        rec_depth: usize,  // recursion depth
        test_depth: usize, // test entry depth
    ) -> Result<u64, Error> {
        let mut nmatch = 0u64;
        let source = opt_source.unwrap_or("unknown");
        let line = self.entry.line;

        if self.root && self.entry.should_skip_for_stream(stream_kind) {
            trace!("skip test source={source} line={line} stream_kind={stream_kind:?}");
            return Ok(0);
        }

        // Entry's own anchor position
        let Some(own_anchor) = self
            .entry
            .anchor_offset(haystack, buf_base_offset, offset_base, last_level_offset)
            .inspect_err(|e| debug!("source={source} line={line} failed at computing offset: {e}"))
            .ok()
            .flatten()
        else {
            // we cannot resolve offset at which we should match
            return Ok(0);
        };

        let (ok, opt_match_res) = self.entry.matches(
            opt_source,
            magic,
            stream_kind,
            state,
            own_anchor,
            haystack,
            switch_endianness,
            db,
            rec_depth,
            test_depth,
        )?;

        if ok {
            // Update the magic with the message if the match is successful
            // Skip updating if the test is recursive, as it's already handled
            // in the Match::matches function
            if !self.entry.test.is_recursive()
                && let Some(msg) = self.entry.message.as_ref()
                && let Ok(msg) = msg.format_with(opt_match_res.as_ref()).inspect_err(|e| {
                    debug!("source={source} line={line} failed to format message: {e}")
                })
            {
                nmatch = nmatch.saturating_add(1);
                magic.push_message(msg);
            }

            // we need to adjust stream offset in case of regex/search tests
            if let Some(mr) = opt_match_res {
                match &self.entry.test {
                    Test::String(t) if t.has_length_mod() => {
                        let o = mr.end_offset();
                        haystack.seek(SeekFrom::Start(o))?;
                    }
                    Test::Search(t) => {
                        if t.re_mods.contains(ReMod::StartOffsetUpdate) {
                            let o = mr.start_offset();
                            haystack.seek(SeekFrom::Start(o))?;
                        } else {
                            let o = mr.end_offset();
                            haystack.seek(SeekFrom::Start(o))?;
                        }
                    }

                    Test::Regex(t) => {
                        if t.mods.contains(ReMod::StartOffsetUpdate) {
                            let o = mr.start_offset();
                            haystack.seek(SeekFrom::Start(o))?;
                        } else {
                            let o = mr.end_offset();
                            haystack.seek(SeekFrom::Start(o))?;
                        }
                    }
                    // other types do not need offset adjustement
                    _ => {}
                }
            }

            if let Some(mimetype) = self.mimetype.as_ref() {
                magic.set_mime_type(Cow::Borrowed(mimetype));
            }

            if let Some(apple_ty) = self.apple.as_ref() {
                magic.set_creator_code(Cow::Borrowed(apple_ty));
            }

            if !self.exts.is_empty() {
                magic.insert_extensions(self.exts.iter().map(|s| s.as_str()));
            }

            // NOTE: here we try to implement a similar logic as in file_magic_strength.
            // Sticking to the exact same strength computation logic is complicated due
            // to implementation differences. Let's wait and see if that is a real issue.
            let mut strength = self.entry.test_strength;

            strength >>= test_depth;

            // `strength_mod` is only ever `Some` on the root entry
            if let Some(sm) = self.strength_mod.as_ref() {
                strength = sm.apply(strength);
            }

            // entries with no message get a bonus
            if self.entry.message.is_none() {
                strength += 1
            }

            magic.update_strength(strength);

            // Position handed to this entry's children as their `&`-relative
            // base: the shared stream cursor, unless this entry doesn't
            // consume bytes itself, in which case that cursor can't be
            // trusted (e.g. left wherever `use`'s sub-scan ended up).
            let end_upper_level = if self.entry.test.consumes_bytes() {
                haystack.stream_position()
            } else {
                own_anchor
            };

            // Anchor point for this entry's children: what a bare offset
            // like `>>0` (or the "N" in an indirect `(N.b)`) counts from.
            let offset_base = match self.entry.offset {
                // A true end-relative top-level entry (`-N`) establishes a
                // fresh anchor for its children
                Offset::Direct(DirOffset::End(_)) if self.root => Some(own_anchor),
                // An `&`-relative entry (`>&N`) clears the anchor for its
                // own children, back to absolute file start.
                Offset::Direct(DirOffset::LastUpper(_)) => None,
                // Anything else (a plain `Start` continuation, or a
                // non-end-relative root) leaves the inherited anchor as-is.
                _ => offset_base,
            };

            for e in self.children.iter() {
                nmatch = nmatch.saturating_add(e.matches(
                    opt_source,
                    magic,
                    state,
                    stream_kind,
                    buf_base_offset,
                    offset_base,
                    Some(end_upper_level),
                    haystack,
                    db,
                    switch_endianness,
                    rec_depth,
                    test_depth.saturating_add(1),
                )?);
            }
        }

        Ok(nmatch)
    }
}

/// Represents a parsed magic rule
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MagicRule {
    id: usize,
    source: Option<String>,
    entries: EntryNode,
    extensions: HashSet<String>,
    /// score used for rule ranking
    score: u64,
    /// cached result of the (non-trivial) text/binary classification
    is_text: bool,
    finalized: bool,
    max_score: u64,
}

impl MagicRule {
    #[inline(always)]
    fn set_id(&mut self, id: usize) {
        self.id = id
    }

    fn visit_all_entries(
        &self,
        deps: &HashMap<String, DependencyRule>,
        marked: &mut HashSet<String>,
        depth: usize,
    ) -> Result<EntryNodeVisitor, Error> {
        let mut v = EntryNodeVisitor::new();
        self.entries.visit(&mut v, deps, marked, depth)?;
        Ok(v)
    }

    /// Finalize a rule by searching for all extensions and computing its
    /// score and text/binary classification for ranking. If the
    /// `MagicRule` is already finalized it returns immediately.
    fn try_finalize(&mut self, deps: &HashMap<String, DependencyRule>) -> Result<(), Error> {
        if self.finalized {
            return Ok(());
        }

        // rule can be finalized all deps are found
        let v = self.visit_all_entries(deps, &mut HashSet::new(), 0)?;

        self.extensions.extend(v.exts);
        self.score = v.score;
        self.is_text = self.compute_is_text();
        self.finalized = true;
        self.max_score = v.max_score;

        Ok(())
    }

    #[inline]
    #[allow(clippy::too_many_arguments)]
    fn magic_entrypoint<'r, D: DataRead>(
        &'r self,
        magic: &mut Magic<'r>,
        stream_kind: StreamKind,
        haystack: &mut D,
        db: &'r MagicDb,
        switch_endianness: bool,
        rec_depth: usize,
        test_depth: usize,
    ) -> Result<u64, Error> {
        self.entries.matches(
            self.source.as_deref(),
            magic,
            &mut MatchState::empty(),
            stream_kind,
            None,
            None,
            None,
            haystack,
            db,
            switch_endianness,
            rec_depth,
            test_depth,
        )
    }

    /// Executes the magic matching logic and returns the count of matches that produce messages.
    /// Matches that don't result in message appends are not counted, consistent with libmagic's behavior.
    #[inline]
    #[allow(clippy::too_many_arguments)]
    fn magic<'r, D: DataRead>(
        &'r self,
        magic: &mut Magic<'r>,
        stream_kind: StreamKind,
        buf_base_offset: Option<u64>,
        offset_base: Option<u64>,
        haystack: &mut D,
        db: &'r MagicDb,
        switch_endianness: bool,
        rec_depth: usize,
        test_depth: usize,
    ) -> Result<u64, Error> {
        self.entries.matches(
            self.source.as_deref(),
            magic,
            &mut MatchState::empty(),
            stream_kind,
            buf_base_offset,
            offset_base,
            None,
            haystack,
            db,
            switch_endianness,
            rec_depth,
            test_depth,
        )
    }

    /// Checks if the rule is for matching against text content.
    ///
    /// # Returns
    ///
    /// * `bool` - True if the rule is for text files
    #[inline(always)]
    pub fn is_text(&self) -> bool {
        self.is_text
    }

    /// Computes the rule's text/binary classification, used for rule
    /// ranking. Decided per rule group, not per entry: an explicit
    /// `/b`/`/t` on the top-level entry decides the whole group;
    /// otherwise it's an OR of each entry's own type default across the
    /// group (top + children), with binary taking priority over text if
    /// both appear.
    fn compute_is_text(&self) -> bool {
        let top = &self.entries.entry.test;

        if top.has_explicit_bin_mod() {
            return false;
        }
        if top.has_explicit_text_mod() {
            return true;
        }

        // Binary wins on conflict, so the first `Some(true)` already
        // pins the answer to `false` -- no need to scan further.
        let mut any_text = false;
        for t in std::iter::once(top).chain(self.entries.children.iter().map(|e| &e.entry.test)) {
            match t.type_default_is_binary() {
                Some(true) => return false,
                Some(false) => any_text = true,
                None => {}
            }
        }

        any_text
    }

    /// Gets the rule's score used for ranking rules between them
    ///
    /// # Returns
    ///
    /// * `u64` - The rule's score
    #[inline(always)]
    pub fn score(&self) -> u64 {
        self.score
    }

    /// Gets the rule's filename if any
    ///
    /// # Returns
    ///
    /// * `Option<&str>` - The rule's source if available
    #[inline(always)]
    pub fn source(&self) -> Option<&str> {
        self.source.as_deref()
    }

    /// Gets the line number at which the rule is defined
    ///
    /// # Returns
    ///
    /// * `usize` - The rule's line number
    #[inline(always)]
    pub fn line(&self) -> usize {
        self.entries.entry.line
    }

    /// Gets all the file extensions associated to the rule
    ///
    /// # Returns
    ///
    /// * `&HashSet<String>` - The set of all associated extensions
    #[inline(always)]
    pub fn extensions(&self) -> &HashSet<String> {
        &self.extensions
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct DependencyRule {
    name: String,
    rule: MagicRule,
}

/// A parsed source of magic rules
///
/// # Methods
///
/// * `open` - Opens a magic file from a path
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MagicSource {
    rules: Vec<MagicRule>,
    dependencies: HashMap<String, DependencyRule>,
}

impl MagicSource {
    /// Opens and parses a magic file from a path
    ///
    /// # Arguments
    ///
    /// * `p` - The path to the magic file
    ///
    /// # Returns
    ///
    /// * `Result<Self, Error>` - The parsed magic file or an error
    pub fn open<P: AsRef<Path>>(p: P) -> Result<Self, Error> {
        FileMagicParser::parse_file(p)
    }
}

#[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
struct ContinuationLevel(u8);

/// The encoding encountered for a given `StreamKind::Text`
// FIXME: magic handles many more text encodings
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum TextEncoding {
    /// ASCII
    Ascii,
    /// UTF-8
    Utf8,
    /// Unspecified
    Unknown,
}

impl TextEncoding {
    const fn as_magic_str(&self) -> &'static str {
        match self {
            TextEncoding::Ascii => "ASCII",
            TextEncoding::Utf8 => "UTF-8",
            TextEncoding::Unknown => "Unknown",
        }
    }
}

/// Represents the kind of encountered data
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum StreamKind {
    /// A binary stream
    Binary,
    /// A text stream with encoding information
    Text(TextEncoding),
}

impl StreamKind {
    /// Returns whether this is a text stream
    ///
    /// # Returns
    ///
    /// * `bool` - True if this is a StreamKind::Text
    #[inline(always)]
    pub const fn is_text(&self) -> bool {
        matches!(self, StreamKind::Text(_))
    }

    /// Returns whether this is a binary stream
    ///
    /// # Returns
    ///
    /// * `bool` - True if this is a StreamKind::Binary
    #[inline(always)]
    pub const fn is_binary(&self) -> bool {
        matches!(self, StreamKind::Binary)
    }

    /// Returns a stable, machine-readable string representation.
    ///
    /// # Returns
    ///
    /// * `&'static str` - One of `"binary"`, `"text/ascii"`,
    ///   `"text/utf-8"` or `"text/unknown"`
    #[inline(always)]
    pub const fn as_str(&self) -> &'static str {
        match self {
            StreamKind::Binary => "binary",
            StreamKind::Text(TextEncoding::Ascii) => "text/ascii",
            StreamKind::Text(TextEncoding::Utf8) => "text/utf-8",
            StreamKind::Text(TextEncoding::Unknown) => "text/unknown",
        }
    }
}

#[derive(Debug)]
struct MatchState {
    continuation_levels: [bool; 256],
}

impl MatchState {
    #[inline(always)]
    fn empty() -> Self {
        MatchState {
            continuation_levels: [false; 256],
        }
    }

    #[inline(always)]
    fn get_continuation_level(&mut self, level: &ContinuationLevel) -> bool {
        self.continuation_levels
            .get(level.0 as usize)
            .cloned()
            .unwrap_or_default()
    }

    #[inline(always)]
    fn set_continuation_level(&mut self, level: ContinuationLevel) {
        if let Some(b) = self.continuation_levels.get_mut(level.0 as usize) {
            *b = true
        }
    }

    #[inline(always)]
    fn clear_continuation_level(&mut self, level: &ContinuationLevel) {
        if let Some(b) = self.continuation_levels.get_mut(level.0 as usize) {
            *b = false;
        }
    }
}

/// Represents a file magic detection result
#[derive(Debug, Default)]
pub struct Magic<'m> {
    stream_kind: Option<StreamKind>,
    source: Option<Cow<'m, str>>,
    message: Vec<Cow<'m, str>>,
    mime_type: Option<Cow<'m, str>>,
    creator_code: Option<Cow<'m, str>>,
    strength: u64,
    exts: HashSet<Cow<'m, str>>,
    is_default: bool,
}

impl<'m> Magic<'m> {
    #[inline(always)]
    fn set_source(&mut self, source: Option<&'m str>) {
        self.source = source.map(Cow::Borrowed);
    }

    #[inline(always)]
    fn set_stream_kind(&mut self, stream_kind: StreamKind) {
        self.stream_kind = Some(stream_kind)
    }

    /// Gets the detected `StreamKind` describing the type of detected data,
    /// or `None` if it was not determined.
    ///
    /// # Returns
    ///
    /// * `Option<StreamKind>` - The detected kind or `None`
    #[inline(always)]
    pub fn stream_kind(&self) -> Option<StreamKind> {
        self.stream_kind
    }

    #[inline(always)]
    fn reset(&mut self) {
        self.stream_kind = None;
        self.source = None;
        self.message.clear();
        self.mime_type = None;
        self.creator_code = None;
        self.strength = 0;
        self.exts.clear();
        self.is_default = false;
    }

    /// Converts borrowed data into owned data. This method involves
    /// data cloning, so you must use this method only if you need to
    /// extend the lifetime of a [`Magic`] struct.
    ///
    /// # Returns
    ///
    /// * `Magic<'owned>` - A new [`Magic`] with owned data
    #[inline]
    pub fn into_owned<'owned>(self) -> Magic<'owned> {
        Magic {
            stream_kind: self.stream_kind,
            source: self.source.map(|s| Cow::Owned(s.into_owned())),
            message: self
                .message
                .into_iter()
                .map(Cow::into_owned)
                .map(Cow::Owned)
                .collect(),
            mime_type: self.mime_type.map(|m| Cow::Owned(m.into_owned())),
            creator_code: self.creator_code.map(|m| Cow::Owned(m.into_owned())),
            strength: self.strength,
            exts: self
                .exts
                .into_iter()
                .map(|e| Cow::Owned(e.into_owned()))
                .collect(),
            is_default: self.is_default,
        }
    }

    /// Gets the formatted message describing the file type
    ///
    /// # Returns
    ///
    /// * `String` - The formatted message
    ///
    /// # Note
    ///
    /// The returned string only ever contains printable ASCII (graphic
    /// characters and spaces). Any other byte, including non-ASCII UTF-8
    /// sequences, control characters and Unicode format/bidi characters, is
    /// escaped as `\NNN` (octal), the same way libmagic does. This makes the
    /// output safe to print directly to a terminal.
    #[inline(always)]
    pub fn message(&self) -> String {
        let mut out = String::new();

        macro_rules! push_str {
            ($input: expr) => {{
                for c in $input.as_bytes() {
                    match c {
                        b'\r' => out.push_str("\\r"),
                        b'\t' => out.push_str("\\t"),
                        b'\n' => out.push_str("\\n"),
                        b' ' => out.push(' '),
                        c if c.is_ascii_graphic() => out.push(*c as char),
                        // the way libmagic handles non printable bytes
                        _ => out.push_str(&format!("\\{:03o}", *c as u8)),
                    }
                }
            }};
        }

        for (i, m) in self.message.iter().enumerate() {
            if let Some(s) = m.strip_prefix(r#"\b"#) {
                push_str!(s);
            } else {
                // don't put space on first string
                if i > 0 {
                    out.push(' ');
                }
                push_str!(m);
            }
        }
        out
    }

    /// Returns an iterator over the individual raw parts of the magic message
    ///
    /// A magic message is typically composed of multiple parts, each appended
    /// during successful magic tests. This method provides an efficient way to
    /// iterate over these parts without concatenating them into a new string,
    /// as done when calling [`Magic::message`].
    ///
    /// # Returns
    ///
    /// * `impl Iterator<Item = &str>` - An iterator yielding string slices of each message part
    ///
    /// # Note
    ///
    /// Unlike [`Magic::message`], the returned parts are **not** sanitized:
    /// they may contain raw control characters (e.g. `ESC`) extracted from
    /// the scanned data. Do not print them directly to a terminal, as this
    /// could result in terminal escape sequence injection. This method is
    /// intended for programmatic inspection only.
    #[inline]
    pub fn message_parts(&self) -> impl Iterator<Item = &str> {
        self.message.iter().map(|p| p.as_ref())
    }

    #[inline(always)]
    fn update_strength(&mut self, value: u64) {
        debug!("update strength = {} + {value}", self.strength);
        self.strength = self.strength.saturating_add(value);
        debug!("updated strength = {}", self.strength)
    }

    /// Gets the detected MIME type
    ///
    /// # Returns
    ///
    /// * `&str` - The MIME type or default based on stream kind
    #[inline(always)]
    pub fn mime_type(&self) -> &str {
        self.mime_type.as_deref().unwrap_or(match self.stream_kind {
            Some(StreamKind::Text(_)) => DEFAULT_TEXT_MIMETYPE,
            Some(StreamKind::Binary) | None => DEFAULT_BIN_MIMETYPE,
        })
    }

    #[inline(always)]
    fn push_message<'a: 'm>(&mut self, msg: Cow<'a, str>) {
        if !msg.is_empty() {
            debug!("pushing message: msg={msg} len={}", msg.len());
            self.message.push(msg);
        }
    }

    #[inline(always)]
    fn set_mime_type<'a: 'm>(&mut self, mime: Cow<'a, str>) {
        if self.mime_type.is_none() {
            debug!("insert mime: {:?}", mime);
            self.mime_type = Some(mime)
        }
    }

    #[inline(always)]
    fn set_creator_code<'a: 'm>(&mut self, apple_ty: Cow<'a, str>) {
        if self.creator_code.is_none() {
            debug!("insert apple type: {apple_ty:?}");
            self.creator_code = Some(apple_ty)
        }
    }

    #[inline(always)]
    fn insert_extensions<'a: 'm, I: Iterator<Item = &'a str>>(&mut self, exts: I) {
        if self.exts.is_empty() {
            self.exts.extend(exts.filter_map(|e| {
                if e.is_empty() {
                    None
                } else {
                    Some(Cow::Borrowed(e))
                }
            }));
        }
    }

    /// Gets the confidence score of the detection. This
    /// value is used to sort [`Magic`] in [`MagicDb::best_magic`]
    /// and [`MagicDb::all_magics`].
    ///
    /// # Returns
    ///
    /// * `u64` - The confidence score attributed to that [`Magic`]
    #[inline(always)]
    pub fn strength(&self) -> u64 {
        self.strength
    }

    /// Gets the filename where the magic rule was defined
    ///
    /// # Returns
    ///
    /// * `Option<&str>` - The source if available
    #[inline(always)]
    pub fn source(&self) -> Option<&str> {
        self.source.as_deref()
    }

    /// Gets the Apple creator code if available
    ///
    /// # Returns
    ///
    /// * `Option<&str>` - The creator code if available
    #[inline(always)]
    pub fn creator_code(&self) -> Option<&str> {
        self.creator_code.as_deref()
    }

    /// Gets the possible file extensions for the detected [`Magic`]
    ///
    /// # Returns
    ///
    /// * `&HashSet<Cow<'m, str>>` - The set of possible extensions
    #[inline(always)]
    pub fn extensions(&self) -> &HashSet<Cow<'m, str>> {
        &self.exts
    }

    /// Checks if this is a default fallback detection
    ///
    /// # Returns
    ///
    /// * `bool` - True if this is a default detection
    #[inline(always)]
    pub fn is_default(&self) -> bool {
        self.is_default
    }
}

/// Represents a database of [`MagicRule`]
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
pub struct MagicDb {
    rule_id: usize,
    rules: Vec<MagicRule>,
    dependencies: HashMap<String, DependencyRule>,
    finalized: usize,
}

#[inline(always)]
/// Returns `true` if the byte stream is likely text.
fn is_likely_text(bytes: &[u8]) -> bool {
    const CHUNK_SIZE: usize = std::mem::size_of::<usize>();

    if bytes.is_empty() {
        return false;
    }

    let mut printable = 0f64;
    let mut high_bytes = 0f64; // Bytes > 0x7F (non-ASCII)

    let (chunks, remainder) = bytes.as_chunks::<CHUNK_SIZE>();

    macro_rules! handle_byte {
        ($byte: expr) => {
            match $byte {
                0x00 => return false,
                0x09 | 0x0A | 0x0D => printable += 1.0, // Whitespace
                0x20..=0x7E => printable += 1.0,        // Printable ASCII
                _ => high_bytes += 1.0,
            }
        };
    }

    for bytes in chunks {
        for b in bytes {
            handle_byte!(b)
        }
    }

    for b in remainder {
        handle_byte!(b)
    }

    let total = bytes.len() as f64;
    let printable_ratio = printable / total;
    let high_bytes_ratio = high_bytes / total;

    // Heuristic thresholds (adjust as needed):
    printable_ratio > 0.85 && high_bytes_ratio < 0.20
}

#[inline(always)]
fn guess_stream_kind<S: AsRef<[u8]>>(stream: S) -> StreamKind {
    let buf = stream.as_ref();

    match run_utf8_validation(buf) {
        Ok(is_ascii) => {
            if is_ascii {
                StreamKind::Text(TextEncoding::Ascii)
            } else {
                StreamKind::Text(TextEncoding::Utf8)
            }
        }
        Err(e) => {
            if is_likely_text(&buf[e.valid_up_to..]) {
                StreamKind::Text(TextEncoding::Unknown)
            } else {
                StreamKind::Binary
            }
        }
    }
}

impl MagicDb {
    /// Creates a new empty database
    ///
    /// # Returns
    ///
    /// * [`MagicDb`] - A new empty database
    pub fn new() -> Self {
        Self::default()
    }

    #[inline(always)]
    fn next_rule_id(&mut self) -> usize {
        let t = self.rule_id;
        self.rule_id += 1;
        t
    }

    #[inline(always)]
    fn try_json<D: DataRead>(
        haystack: &mut D,
        stream_kind: StreamKind,
        magic: &mut Magic,
    ) -> Result<bool, Error> {
        // cannot be json if content is binary
        if matches!(stream_kind, StreamKind::Binary) {
            return Ok(false);
        }

        let buf = haystack.read_range(0..FILE_BYTES_MAX as u64)?.trim_ascii();

        let Some((start, end)) = find_json_boundaries(buf) else {
            return Ok(false);
        };

        // if anything else than whitespace before start
        // this is not json
        for c in buf[0..start].iter() {
            if !c.is_ascii_whitespace() {
                return Ok(false);
            }
        }

        let mut is_ndjson = false;

        trace!("maybe a json document");
        let ok = serde_json::from_slice::<serde_json::Value>(&buf[start..=end]).is_ok();
        if !ok {
            return Ok(false);
        }

        // we are sure it is json now we must look if we are ndjson
        if end + 1 < buf.len() {
            // after first json
            let buf = &buf[end + 1..];
            if let Some((second_start, second_end)) = find_json_boundaries(buf) {
                // there is a new line between the two json docs
                if memchr(b'\n', &buf[..second_start]).is_some() {
                    trace!("might be ndjson");
                    is_ndjson = serde_json::from_slice::<serde_json::Value>(
                        &buf[second_start..=second_end],
                    )
                    .is_ok();
                }
            }
        }

        if is_ndjson {
            magic.push_message(Cow::Borrowed("New Line Delimited"));
            magic.set_mime_type(Cow::Borrowed("application/x-ndjson"));
            magic.insert_extensions(["ndjson", "jsonl"].into_iter());
        } else {
            magic.set_mime_type(Cow::Borrowed("application/json"));
            magic.insert_extensions(["json"].into_iter());
        }

        magic.push_message(Cow::Borrowed("JSON text data"));
        magic.set_source(Some(HARDCODED_SOURCE));
        magic.update_strength(HARDCODED_MAGIC_STRENGTH);
        Ok(true)
    }

    #[inline(always)]
    fn try_csv<D: DataRead>(
        haystack: &mut D,
        stream_kind: StreamKind,
        magic: &mut Magic,
    ) -> Result<bool, Error> {
        // cannot be csv if content is binary
        let StreamKind::Text(enc) = stream_kind else {
            return Ok(false);
        };

        let buf = haystack.read_range(0..FILE_BYTES_MAX as u64)?;
        let mut reader = csv::ReaderBuilder::new()
            .has_headers(false)
            .from_reader(io::Cursor::new(buf));
        let mut records = reader.records();

        let Some(Ok(first)) = records.next() else {
            return Ok(false);
        };

        // very not likely a CSV otherwise all programming
        // languages having ; line terminator would be
        // considered as CSV
        if first.len() <= 1 {
            return Ok(false);
        }

        // we already parsed first line
        let mut n = 1;
        for i in records.take(9) {
            if let Ok(rec) = i {
                if first.len() != rec.len() {
                    return Ok(false);
                }
            } else {
                return Ok(false);
            }
            n += 1;
        }

        // we need at least 2 lines (matches file command https://github.com/file/file/commit/b4e621d1d5b3e9d142dd23030cca09f6f198e18b)
        if n < 2 {
            return Ok(false);
        }

        magic.set_mime_type(Cow::Borrowed("text/csv"));
        magic.push_message(Cow::Borrowed("CSV"));
        magic.push_message(Cow::Borrowed(enc.as_magic_str()));
        magic.push_message(Cow::Borrowed("text"));
        magic.insert_extensions(["csv"].into_iter());
        magic.set_source(Some(HARDCODED_SOURCE));
        magic.update_strength(HARDCODED_MAGIC_STRENGTH);
        Ok(true)
    }

    #[inline(always)]
    fn try_tar<D: DataRead>(
        haystack: &mut D,
        stream_kind: StreamKind,
        magic: &mut Magic,
    ) -> Result<bool, Error> {
        // cannot be json if content is not binary
        if !matches!(stream_kind, StreamKind::Binary) {
            return Ok(false);
        }

        let buf = haystack.read_range(0..FILE_BYTES_MAX as u64)?;
        let mut ar = Archive::new(io::Cursor::new(buf));

        let Ok(mut entries) = ar.entries() else {
            return Ok(false);
        };

        let Some(Ok(first)) = entries.next() else {
            return Ok(false);
        };

        let header = first.header();

        if header.as_ustar().is_some() {
            magic.push_message(Cow::Borrowed("POSIX tar archive"));
        } else if header.as_gnu().is_some() {
            magic.push_message(Cow::Borrowed("POSIX tar archive (GNU)"));
        } else {
            magic.push_message(Cow::Borrowed("tar archive"));
        }

        magic.set_mime_type(Cow::Borrowed("application/x-tar"));
        magic.set_source(Some(HARDCODED_SOURCE));
        magic.update_strength(HARDCODED_MAGIC_STRENGTH);
        magic.insert_extensions(["tar"].into_iter());
        Ok(true)
    }

    #[inline(always)]
    fn try_hard_magic<D: DataRead>(
        haystack: &mut D,
        stream_kind: StreamKind,
        magic: &mut Magic,
    ) -> Result<bool, Error> {
        Ok(Self::try_json(haystack, stream_kind, magic)?
            || Self::try_csv(haystack, stream_kind, magic)?
            || Self::try_tar(haystack, stream_kind, magic)?)
    }

    #[inline(always)]
    fn magic_default<'m, D: DataRead>(
        cache: &mut D,
        stream_kind: StreamKind,
        magic: &mut Magic<'m>,
    ) {
        magic.set_source(Some(HARDCODED_SOURCE));
        magic.set_stream_kind(stream_kind);
        magic.is_default = true;

        if cache.data_size() == 0 {
            magic.push_message(Cow::Borrowed("empty"));
            magic.set_mime_type(Cow::Borrowed(DEFAULT_BIN_MIMETYPE));
        }

        match stream_kind {
            StreamKind::Binary => {
                magic.push_message(Cow::Borrowed("data"));
            }
            StreamKind::Text(e) => {
                magic.push_message(Cow::Borrowed(e.as_magic_str()));
                magic.push_message(Cow::Borrowed("text"));
            }
        }
    }

    fn load_rules_no_prepare(&mut self, rules: Vec<MagicRule>) {
        for rule in rules.into_iter() {
            let mut rule = rule;
            rule.set_id(self.next_rule_id());

            self.rules.push(rule);
        }
    }

    /// Loads rules from a [`MagicSource`]
    ///
    /// # Arguments
    ///
    /// * `ms` - The [`MagicSource`] to load rules from
    pub fn load(&mut self, ms: MagicSource) -> &mut Self {
        self.load_rules_no_prepare(ms.rules);
        self.dependencies.extend(ms.dependencies);
        self.try_finalize();
        self
    }

    /// Loads multiple [`MagicSource`] items efficiently in bulk.
    ///
    /// This is more efficient than loading each individually. After processing
    /// all sources, it applies finalization step only once.
    pub fn load_bulk<I: Iterator<Item = MagicSource>>(&mut self, it: I) -> &mut Self {
        for ms in it {
            self.load_rules_no_prepare(ms.rules);
            self.dependencies.extend(ms.dependencies);
        }
        self.try_finalize();
        self
    }

    /// Gets all rules in the database
    ///
    /// # Returns
    ///
    /// * `&[MagicRule]` - A slice of all rules
    pub fn rules(&self) -> &[MagicRule] {
        &self.rules
    }

    #[inline]
    fn first_magic_with_stream_kind<D: DataRead>(
        &self,
        haystack: &mut D,
        stream_kind: StreamKind,
        extension: Option<&str>,
    ) -> Result<Magic<'_>, Error> {
        // re-using magic makes this function faster
        let mut magic = Magic::default();

        if Self::try_hard_magic(haystack, stream_kind, &mut magic)? {
            return Ok(magic);
        }

        macro_rules! do_magic {
            ($rule: expr) => {{
                $rule.magic_entrypoint(&mut magic, stream_kind, haystack, &self, false, 0, 0)?;

                if !magic.message.is_empty() {
                    magic.set_stream_kind(stream_kind);
                    magic.set_source($rule.source.as_deref());
                    return Ok(magic);
                }

                magic.reset();
            }};
        }

        if let Some(ext) = extension.map(|e| e.to_lowercase())
            && !ext.is_empty()
        {
            let mut marked = vec![false; self.rules.len()];
            for rule in self.rules.iter().filter(|r| r.extensions.contains(&ext)) {
                do_magic!(rule);
                if let Some(f) = marked.get_mut(rule.id) {
                    *f = true
                }
            }
            for rule in self
                .rules
                .iter()
                // we don't run again rules run by extension
                .filter(|r| !*marked.get(r.id).unwrap_or(&false))
            {
                do_magic!(rule)
            }
        } else {
            for rule in self.rules.iter() {
                do_magic!(rule)
            }
        }

        Self::magic_default(haystack, stream_kind, &mut magic);

        Ok(magic)
    }

    /// Detects file [`Magic`] stopping at the first matching magic. Magic
    /// rules are evaluated from the best to the least relevant, so this method
    /// returns most of the time the best magic. For the rare cases where
    /// it doesn't or if the best result is always required, use [`MagicDb::best_magic`]
    ///
    /// # Arguments
    ///
    /// * `r` - A reader implementing [`DataRead`]
    /// * `extension` - Optional file extension to use for acceleration
    ///
    /// # Returns
    ///
    /// * `Result<Magic<'_>, Error>` - The detection result or an error
    ///
    /// # Notes
    ///
    /// * Use this method **only** if you need to re-use a `reader` for future **read** operations.
    /// * Use [`DataReader`] to create a generic `reader`
    ///
    /// # Warning
    ///
    /// File extension acceleration is made to evaluate rules faster by testing
    /// first the rules defining this extension with an `!:ext` entry.
    /// Whether you use `extension` acceleration or not with this function should not
    /// produce different results. Yet this makes the assumption rules are written
    /// correctly and every rule concerned defines `!:ext` when it is appropriate.
    /// If some rules are missing it, results might differ.
    pub fn first_magic<R: DataRead>(
        &self,
        r: &mut R,
        extension: Option<&str>,
    ) -> Result<Magic<'_>, Error> {
        let stream_kind = guess_stream_kind(r.read_range(0..FILE_BYTES_MAX as u64)?);
        self.first_magic_with_stream_kind(r, stream_kind, extension)
    }

    /// Detects file [`Magic`] from a file path.
    ///
    /// This is a convenience method that opens the file and creates a [`DataReader::File`]
    /// internally. The file extension is automatically extracted and passed to
    /// [`MagicDb::first_magic`].
    ///
    /// # Errors
    ///
    /// Returns an error if the file cannot be opened or if magic detection fails.
    pub fn first_magic_file<P: AsRef<Path>>(&self, path: P) -> Result<Magic<'_>, Error> {
        let ext = path.as_ref().extension().and_then(|e| e.to_str());
        self.first_magic(&mut DataReader::from_file(File::open(path.as_ref())?)?, ext)
    }

    /// Detects file [`Magic`] from an in-memory byte slice.
    ///
    /// This is a convenience method that creates a [`DataReader::Slice`] internally.
    ///
    /// # Errors
    ///
    /// Returns an error if magic detection fails.
    pub fn first_magic_slice<S: AsRef<[u8]>>(
        &self,
        s: S,
        extension: Option<&str>,
    ) -> Result<Magic<'_>, Error> {
        self.first_magic(&mut DataReader::from_slice(s.as_ref()), extension)
    }

    #[inline(always)]
    fn all_magics_sort_with_stream_kind<R: DataRead>(
        &self,
        haystack: &mut R,
        stream_kind: StreamKind,
    ) -> Result<Vec<Magic<'_>>, Error> {
        let mut out = Vec::new();

        let mut magic = Magic::default();

        if Self::try_hard_magic(haystack, stream_kind, &mut magic)? {
            out.push(magic);
            magic = Magic::default();
        }

        for rule in self.rules.iter() {
            rule.magic_entrypoint(&mut magic, stream_kind, haystack, self, false, 0, 0)?;

            // it is possible we have a strength with no message
            if !magic.message.is_empty() {
                magic.set_stream_kind(stream_kind);
                magic.set_source(rule.source.as_deref());
                out.push(magic);
                magic = Magic::default();
            }

            magic.reset();
        }

        Self::magic_default(haystack, stream_kind, &mut magic);
        out.push(magic);

        out.sort_by_key(|b| std::cmp::Reverse(b.strength()));

        Ok(out)
    }

    /// Detects all [`Magic`] matching a given content.
    ///
    /// # Arguments
    ///
    /// * `r` - A reader implementing [`DataRead`]
    ///
    /// # Returns
    ///
    /// * `Result<Vec<Magic<'_>>, Error>` - All detection results sorted by strength or an error
    ///
    /// # Notes
    ///
    /// * Use this method **only** if you need to re-use a `reader` for future **read** operations.
    /// * Use [`DataReader`] to create a generic `reader`
    #[inline]
    pub fn all_magics<R: DataRead>(&self, r: &mut R) -> Result<Vec<Magic<'_>>, Error> {
        let stream_kind = guess_stream_kind(r.read_range(0..FILE_BYTES_MAX as u64)?);
        self.all_magics_sort_with_stream_kind(r, stream_kind)
    }

    /// Detects all matching [`Magic`] entries from a file path.
    ///
    /// This is a convenience method that opens the file and creates a [`DataReader::File`]
    /// internally, then calls [`MagicDb::all_magics`].
    ///
    /// # Errors
    ///
    /// Returns an error if the file cannot be opened or if magic detection fails.
    pub fn all_magics_file<P: AsRef<Path>>(&self, path: P) -> Result<Vec<Magic<'_>>, Error> {
        self.all_magics(&mut DataReader::from_file(File::open(path)?)?)
    }

    /// Detects all matching [`Magic`] entries from an in-memory byte slice.
    ///
    /// This is a convenience method that creates a [`DataReader::Slice`] internally,
    /// then calls [`MagicDb::all_magics`].
    ///
    /// # Errors
    ///
    /// Returns an error if magic detection fails.
    pub fn all_magics_slice<S: AsRef<[u8]>>(&self, slice: S) -> Result<Vec<Magic<'_>>, Error> {
        self.all_magics(&mut DataReader::from_slice(slice.as_ref()))
    }

    #[inline(always)]
    fn best_magic_with_stream_kind<R: DataRead>(
        &self,
        haystack: &mut R,
        stream_kind: StreamKind,
        extension: Option<&str>,
    ) -> Result<Magic<'_>, Error> {
        // re-using magic makes this function faster
        let mut magic = Magic::default();
        let mut best = Magic::default();
        let mut best_id = None;

        if Self::try_hard_magic(haystack, stream_kind, &mut magic)? {
            swap(&mut magic, &mut best);
            magic.reset();
        }

        macro_rules! do_best {
            ($rule: expr) => {{
                $rule.magic_entrypoint(&mut magic, stream_kind, haystack, &self, false, 0, 0)?;

                if !magic.message.is_empty()
                    && (magic.strength > best.strength || best.message.is_empty())
                {
                    magic.set_stream_kind(stream_kind);
                    magic.set_source($rule.source.as_deref());
                    swap(&mut magic, &mut best);
                    let _ = best_id.insert($rule.id);
                }

                magic.reset();
            }};
        }

        let ext = extension.map(|e| e.to_lowercase());
        if let Some(ext) = ext.as_ref()
            && !ext.is_empty()
        {
            for rule in self.rules.iter().filter(|r| r.extensions.contains(ext)) {
                // don't prune while best is empty -- a 0-strength match still beats none
                if !best.message.is_empty() && rule.max_score <= best.strength {
                    continue;
                }
                do_best!(rule);
            }
        }

        for rule in self.rules.iter() {
            // don't prune while best is empty -- a 0-strength match still beats none
            if (!best.message.is_empty() && rule.max_score <= best.strength)
                || best_id == Some(rule.id)
            {
                continue;
            }

            do_best!(rule)
        }

        if best.message.is_empty() {
            Self::magic_default(haystack, stream_kind, &mut best);
        }

        Ok(best)
    }

    /// Detects the best [`Magic`] matching a given content.
    ///
    /// # Arguments
    ///
    /// * `r` - A reader implementing [`DataRead`]
    ///
    /// # Returns
    ///
    /// * `Result<Magic<'_>, Error>` - The best detection result or an error
    ///
    /// # Notes
    ///
    /// * Use this method **only** if you need to re-use a `reader` for future **read** operations.
    /// * Use [`DataReader`] to create a generic `reader`
    #[inline]
    pub fn best_magic<R: DataRead>(
        &self,
        r: &mut R,
        extension: Option<&str>,
    ) -> Result<Magic<'_>, Error> {
        let stream_kind = guess_stream_kind(r.read_range(0..FILE_BYTES_MAX as u64)?);
        self.best_magic_with_stream_kind(r, stream_kind, extension)
    }

    /// Detects the best matching [`Magic`] from a file path.
    ///
    /// This is a convenience method that opens the file and creates a [`DataReader::File`]
    /// internally, then calls [`MagicDb::best_magic`].
    ///
    /// # Errors
    ///
    /// Returns an error if the file cannot be opened or if magic detection fails.
    pub fn best_magic_file<P: AsRef<Path>>(&self, path: P) -> Result<Magic<'_>, Error> {
        let ext = path.as_ref().extension().and_then(|e| e.to_str());
        self.best_magic(&mut DataReader::from_file(File::open(&path)?)?, ext)
    }

    /// Detects the best matching [`Magic`] from an in-memory byte slice.
    ///
    /// This is a convenience method that creates a [`DataReader::Slice`] internally,
    /// then calls [`MagicDb::best_magic`].
    ///
    /// # Errors
    ///
    /// Returns an error if magic detection fails.
    pub fn best_magic_slice<S: AsRef<[u8]>>(
        &self,
        slice: S,
        extension: Option<&str>,
    ) -> Result<Magic<'_>, Error> {
        self.best_magic(&mut DataReader::from_slice(slice.as_ref()), extension)
    }

    /// Serializes the database to a generic writer implementing [`io::Write`]
    ///
    /// # Returns
    ///
    /// * `Result<(), Error>` - The serialized database or an error
    pub fn serialize<W: Write>(self, w: &mut W) -> Result<(), Error> {
        let mut encoder = GzEncoder::new(w, Compression::best());

        bincode::serde::encode_into_std_write(&self, &mut encoder, bincode::config::standard())?;
        encoder.finish()?;
        Ok(())
    }

    /// Deserializes the database from a generic reader implementing [`io::Read`]
    ///
    /// # Arguments
    ///
    /// * `r` - The reader to deserialize from
    ///
    /// # Returns
    ///
    /// * `Result<Self, Error>` - The deserialized database or an error
    pub fn deserialize<R: Read>(r: &mut R) -> Result<Self, Error> {
        let mut buf = vec![];
        let mut gz = GzDecoder::new(r);
        gz.read_to_end(&mut buf).map_err(|e| {
            bincode::error::DecodeError::OtherString(format!("failed to read: {e}"))
        })?;
        let (sdb, _): (MagicDb, usize) =
            bincode::serde::decode_from_slice(&buf, bincode::config::standard())?;
        Ok(sdb)
    }

    /// Verifies the consistency of the [`MagicDb`] database.
    /// This method must be called when the database is built once and used later.
    /// It catches [`enum@Error`] that would raise at rule evaluation time.
    ///
    /// # Errors
    /// Returns an error if any rule fails verification
    pub fn verify(&mut self) -> Result<(), Error> {
        if self.rules.len() == self.finalized {
            return Ok(());
        }

        for r in self.rules.iter_mut().filter(|r| !r.finalized) {
            // return at the first rule failing verification
            r.try_finalize(&self.dependencies).map_err(|e| {
                Error::Verify(
                    r.source.clone().unwrap_or(String::from("unknown")),
                    r.line(),
                    e.into(),
                )
            })?;
            self.finalized += 1;
        }

        debug_assert!(self.finalized <= self.rules.len());

        Ok(())
    }

    #[inline(always)]
    fn try_finalize(&mut self) {
        if self.rules.len() == self.finalized {
            return;
        }

        let mut finalized = 0usize;
        self.rules.iter_mut().for_each(|r| {
            if r.try_finalize(&self.dependencies).is_ok() {
                finalized += 1;
            }
        });

        self.finalized = finalized;

        debug_assert!(self.finalized <= self.rules.len());

        // put text rules at the end
        self.rules.sort_by_key(|r| (r.is_text(), -(r.score as i64)));
    }
}

#[cfg(test)]
mod tests {

    use regex::bytes::Regex;

    use crate::{readers::BufReader, utils::unix_local_time_to_string};

    use super::*;

    macro_rules! buf_reader {
        ($l: literal) => {
            BufReader::from_slice($l.as_bytes())
        };
    }

    fn best_magic(
        rule: &str,
        content: &[u8],
        stream_kind: StreamKind,
    ) -> Result<Magic<'static>, Error> {
        let mut md = MagicDb::new();
        md.load(
            FileMagicParser::parse_str(rule, None)
                .inspect_err(|e| eprintln!("{e}"))
                .unwrap(),
        );
        let mut reader = BufReader::from_slice(content);
        let v = md.best_magic_with_stream_kind(&mut reader, stream_kind, None)?;
        Ok(v.into_owned())
    }

    /// helper macro to debug tests
    #[allow(unused_macros)]
    macro_rules! enable_trace {
        () => {
            tracing_subscriber::fmt()
                .with_max_level(tracing_subscriber::filter::LevelFilter::TRACE)
                .try_init();
        };
    }

    macro_rules! parse_assert {
        ($rule:expr) => {
            FileMagicParser::parse_str($rule, None)
                .inspect_err(|e| eprintln!("{e}"))
                .unwrap()
        };
    }

    macro_rules! assert_magic_match_bin {
        ($rule: literal, $content:literal) => {{ best_magic($rule, $content, StreamKind::Binary).unwrap() }};
        ($rule: literal, $content:literal, $message:expr) => {{
            assert_eq!(
                best_magic($rule, $content, StreamKind::Binary)
                    .unwrap()
                    .message(),
                $message
            );
        }};
    }

    macro_rules! assert_magic_match_text {
        ($rule: literal, $content:literal) => {{ best_magic($rule, $content, StreamKind::Text(TextEncoding::Utf8)).unwrap() }};
        ($rule: literal, $content:literal, $message:expr) => {{
            assert_eq!(
                best_magic($rule, $content, StreamKind::Text(TextEncoding::Utf8))
                    .unwrap()
                    .message(),
                $message
            );
        }};
    }

    macro_rules! assert_magic_not_match_text {
        ($rule: literal, $content:literal) => {{
            assert!(
                best_magic($rule, $content, StreamKind::Text(TextEncoding::Utf8))
                    .unwrap()
                    .is_default()
            );
        }};
    }

    macro_rules! assert_magic_not_match_bin {
        ($rule: literal, $content:literal) => {{
            assert!(
                best_magic($rule, $content, StreamKind::Binary)
                    .unwrap()
                    .is_default()
            );
        }};
    }

    #[test]
    fn test_regex() {
        assert_magic_match_text!(
            r#"
0	regex/1024 \^#![[:space:]]*/usr/bin/env[[:space:]]+
!:mime	text/x-shellscript
>&0  regex/64 .*($|\\b) %s shell script text executable
    "#,
            br#"#!/usr/bin/env bash
        echo hello world"#,
            // the magic generated
            "bash shell script text executable"
        );

        let re = Regex::new(r"(?-u)\x42\x82").unwrap();
        assert!(re.is_match(b"\x42\x82"));

        assert_magic_match_bin!(
            r#"0 regex \x42\x82 binary regex match"#,
            b"\x00\x00\x00\x00\x00\x00\x42\x82"
        );

        // test regex continuation after match
        assert_magic_match_bin!(
            r#"
            0 regex \x42\x82
            >&0 string \xde\xad\xbe\xef it works
            "#,
            b"\x00\x00\x00\x00\x00\x00\x42\x82\xde\xad\xbe\xef"
        );

        assert_magic_match_bin!(
            r#"
            0 regex/s \x42\x82
            >&0 string \x42\x82\xde\xad\xbe\xef it works
            "#,
            b"\x00\x00\x00\x00\x00\x00\x42\x82\xde\xad\xbe\xef"
        );

        // ^ must match stat of line when matching text
        assert_magic_match_text!(
            r#"
0	regex/1024 \^HelloWorld$ HelloWorld String"#,
            br#"
// this is a comment after an empty line
HelloWorld
            "#
        );
    }

    #[test]
    fn test_string_with_mods() {
        assert_magic_match_text!(
            r#"0	string/w	#!\ \ \ /usr/bin/env\ bash	BASH
        "#,
            b"#! /usr/bin/env bash i
        echo hello world"
        );

        // test uppercase insensitive
        assert_magic_match_text!(
            r#"0	string/C	HelloWorld	it works
        "#,
            b"helloworld"
        );

        assert_magic_not_match_text!(
            r#"0	string/C	HelloWorld	it works
        "#,
            b"hELLOwORLD"
        );

        // test lowercase insensitive
        assert_magic_match_text!(
            r#"0	string/c	HelloWorld	it works
        "#,
            b"HELLOWORLD"
        );

        assert_magic_not_match_text!(
            r#"0	string/c	HelloWorld	it works
        "#,
            b"helloworld"
        );

        // test full word match
        assert_magic_match_text!(
            r#"0	string/f	#!/usr/bin/env\ bash	BASH
        "#,
            b"#!/usr/bin/env bash"
        );

        assert_magic_not_match_text!(
            r#"0	string/f	#!/usr/bin/python PYTHON"#,
            b"#!/usr/bin/pythonic"
        );

        // testing whitespace compacting
        assert_magic_match_text!(
            r#"0	string/W	#!/usr/bin/env\ python  PYTHON"#,
            b"#!/usr/bin/env    python"
        );

        assert_magic_not_match_text!(
            r#"0	string/W	#!/usr/bin/env\ \ python  PYTHON"#,
            b"#!/usr/bin/env python"
        );
    }

    #[test]
    fn test_search_with_mods() {
        assert_magic_match_text!(
            r#"0	search/1/fwt	#!\ /usr/bin/luatex	LuaTex script text executable"#,
            b"#!          /usr/bin/luatex "
        );

        // test matching from the beginning
        assert_magic_match_text!(
            r#"
            0	search/s	/usr/bin/env
            >&0 string /usr/bin/env it works
            "#,
            b"#!/usr/bin/env    python"
        );

        assert_magic_not_match_text!(
            r#"
            0	search	/usr/bin/env
            >&0 string /usr/bin/env it works
            "#,
            b"#!/usr/bin/env    python"
        );
    }

    #[test]
    fn test_pstring() {
        assert_magic_match_bin!(r#"0 pstring Toast it works"#, b"\x05Toast");

        assert_magic_match_bin!(r#"0 pstring Toast %s"#, b"\x05Toast", "Toast");

        assert_magic_not_match_bin!(r#"0 pstring Toast Doesn't work"#, b"\x07Toaster");

        // testing with modifiers
        assert_magic_match_bin!(r#"0 pstring/H Toast it works"#, b"\x00\x05Toast");

        assert_magic_match_bin!(r#"0 pstring/HJ Toast it works"#, b"\x00\x07Toast");

        assert_magic_match_bin!(r#"0 pstring/HJ Toast %s"#, b"\x00\x07Toast", "Toast");

        assert_magic_match_bin!(r#"0 pstring/h Toast it works"#, b"\x05\x00Toast");

        assert_magic_match_bin!(r#"0 pstring/hJ Toast it works"#, b"\x07\x00Toast");

        assert_magic_match_bin!(r#"0 pstring/L Toast it works"#, b"\x00\x00\x00\x05Toast");

        assert_magic_match_bin!(r#"0 pstring/LJ Toast it works"#, b"\x00\x00\x00\x09Toast");

        assert_magic_match_bin!(r#"0 pstring/l Toast it works"#, b"\x05\x00\x00\x00Toast");

        assert_magic_match_bin!(r#"0 pstring/lJ Toast it works"#, b"\x09\x00\x00\x00Toast");
    }

    #[test]
    fn test_max_recursion() {
        let res = best_magic(
            r#"0	indirect x"#,
            b"#!          /usr/bin/luatex ",
            StreamKind::Binary,
        );
        assert!(res.is_err());
        let _ = res.inspect_err(|e| {
            assert!(matches!(
                e.unwrap_localized(),
                Error::MaximumRecursion(MAX_RECURSION)
            ))
        });
    }

    #[test]
    fn test_string_ops() {
        assert_magic_match_text!("0	string/b MZ MZ File", b"MZ\0");
        assert_magic_match_text!("0	string !MZ Not MZ File", b"AZ\0");
        assert_magic_match_text!("0	string >\0 Any String", b"A\0");
        assert_magic_match_text!("0	string >Test Any String", b"Test 1\0");
        assert_magic_match_text!("0	string <Test Any String", b"\0");
        assert_magic_not_match_text!("0	string >Test Any String", b"\0");
    }

    #[test]
    fn test_lestring16() {
        assert_magic_match_bin!(
            "0 lestring16 abcd Little-endian UTF-16 string",
            b"\x61\x00\x62\x00\x63\x00\x64\x00"
        );
        assert_magic_match_bin!(
            "0 lestring16 x %s",
            b"\x61\x00\x62\x00\x63\x00\x64\x00\x00",
            "abcd"
        );
        assert_magic_not_match_bin!(
            "0 lestring16 abcd Little-endian UTF-16 string",
            b"\x00\x61\x00\x62\x00\x63\x00\x64"
        );
        assert_magic_match_bin!(
            "4 lestring16 abcd Little-endian UTF-16 string",
            b"\x00\x00\x00\x00\x61\x00\x62\x00\x63\x00\x64\x00"
        );
    }

    #[test]
    fn test_bestring16() {
        assert_magic_match_bin!(
            "0 bestring16 abcd Big-endian UTF-16 string",
            b"\x00\x61\x00\x62\x00\x63\x00\x64"
        );
        assert_magic_match_bin!(
            "0 bestring16 x %s",
            b"\x00\x61\x00\x62\x00\x63\x00\x64",
            "abcd"
        );
        assert_magic_not_match_bin!(
            "0 bestring16 abcd Big-endian UTF-16 string",
            b"\x61\x00\x62\x00\x63\x00\x64\x00"
        );
        assert_magic_match_bin!(
            "4 bestring16 abcd Big-endian UTF-16 string",
            b"\x00\x00\x00\x00\x00\x61\x00\x62\x00\x63\x00\x64"
        );
    }

    #[test]
    fn test_offset_from_end() {
        assert_magic_match_bin!("-1 ubyte 0x42 last byte ok", b"\x00\x00\x42");
        assert_magic_match_bin!("-2 ubyte 0x41 last byte ok", b"\x00\x41\x00");
    }

    #[test]
    fn test_relative_offset() {
        assert_magic_match_bin!(
            "
            0 ubyte 0x42
            >&0 ubyte 0x00
            >>&0 ubyte 0x41 third byte ok
            ",
            b"\x42\x00\x41\x00"
        );
    }

    #[test]
    fn test_indirect_offset() {
        assert_magic_match_bin!("(0.l) ubyte 0x42 it works", b"\x04\x00\x00\x00\x42");
        // adding fixed value to offset
        assert_magic_match_bin!("(0.l+3) ubyte 0x42 it works", b"\x01\x00\x00\x00\x42");
        // testing offset pair
        assert_magic_match_bin!(
            "(0.l+(4)) ubyte 0x42 it works",
            b"\x04\x00\x00\x00\x04\x00\x00\x00\x42"
        );
    }

    // A `use` line's own message is never printed by libmagic (softmagic.c's
    // FILE_USE case never calls file_printf on its own `desc`) -- only the
    // named rule's own text (here the `name` line's "then second match")
    // shows up, confirmed against real `file`.
    #[test]
    fn test_use_with_message() {
        assert_magic_match_bin!(
            r#"
0 string MZ
>0 use mz first match

0 name mz then second match
>0 string MZ
"#,
            b"MZ\0",
            "then second match"
        );
    }

    // An `indirect` line's own message only prints if the recursive scan at
    // its target offset actually finds something (softmagic.c's
    // FILE_INDIRECT case prints `desc` conditionally, then the nested
    // match's own output), and in that order: own text first, nested second.
    #[test]
    fn test_indirect_message_only_on_nested_match() {
        let rule = r#"
0 string AB
>2 indirect x contains:

0 string CD nested match
"#;

        let m = best_magic(rule, b"ABCD", StreamKind::Binary).unwrap();
        assert_eq!(m.message(), "contains: nested match");

        let m = best_magic(rule, b"ABXX", StreamKind::Binary).unwrap();
        assert!(m.is_default());
    }

    #[test]
    fn test_scalar_transform() {
        assert_magic_match_bin!("0 ubyte+1 0x1 add works", b"\x00");
        assert_magic_match_bin!("0 ubyte-1 0xfe sub works", b"\xff");
        assert_magic_match_bin!("0 ubyte%2 0 mod works", b"\x0a");
        assert_magic_match_bin!("0 ubyte&0x0f 0x0f bitand works", b"\xff");
        assert_magic_match_bin!("0 ubyte|0x0f 0xff bitor works", b"\xf0");
        assert_magic_match_bin!("0 ubyte^0x0f 0xf0 bitxor works", b"\xff");

        FileMagicParser::parse_str("0 ubyte%0 mod by zero", None)
            .expect_err("expect div by zero error");
        FileMagicParser::parse_str("0 ubyte/0 div by zero", None)
            .expect_err("expect div by zero error");
    }

    #[test]
    fn test_strength_hoisted_to_root() {
        // `!:strength` declared on a nested continuation must be treated
        // exactly as if it had been declared on the group's root
        let base_rule = r"
0	string	MAGIC	found it
>0	byte	x	x
        ";
        let with_strength_rule = r"
0	string	MAGIC	found it
>0	byte	x	x
!:strength +100
        ";

        let mut db = MagicDb::new();
        db.load(parse_assert!(base_rule));
        db.load(parse_assert!(with_strength_rule));

        // reached the top at load time
        let modded_score = db.rules()[0].score();
        let base_score = db.rules()[1].score();

        assert_eq!(
            modded_score,
            base_score + 100,
            "!:strength on a nested continuation must still affect the root's static score"
        );

        let base_strength = best_magic(base_rule, b"MAGIC", StreamKind::Binary)
            .unwrap()
            .strength();
        let modded_strength = best_magic(with_strength_rule, b"MAGIC", StreamKind::Binary)
            .unwrap()
            .strength();

        assert_eq!(
            modded_strength,
            base_strength + 100,
            "!:strength on a nested continuation must still affect the runtime strength"
        );
    }

    #[test]
    fn test_duplicate_strength_rejected() {
        // real libmagic rejects a second !:strength in the same rule
        FileMagicParser::parse_str(
            r"
0	string	MAGIC	found it
!:strength +10
>0	byte	x	x
!:strength +20
            ",
            None,
        )
        .expect_err("a second !:strength in the same rule must be rejected");
    }

    #[test]
    fn test_strength_on_name_entry_rejected() {
        FileMagicParser::parse_str(
            r"
0	name	dep
!:strength +10
>0	byte	x	x
            ",
            None,
        )
        .expect_err("!:strength directly on a name entry must be rejected");

        FileMagicParser::parse_str(
            r"
0	name	dep
>0	byte	x	x
!:strength +10
            ",
            None,
        )
        .expect_err("!:strength anywhere in a name-headed group must be rejected");
    }

    #[test]
    fn test_search_binary_default_matches_libmagic_text_chars() {
        // libmagic counts BEL (0x07) as text, not binary. Both
        // assertions need a message, or a silent match looks identical
        // to a correctly-skipped one.
        assert_magic_not_match_bin!(r"0	search	\007test	found", b"\x07test");
        assert_magic_match_text!(r"0	search	\007test	found", b"\x07test", "found");
    }

    #[test]
    fn test_search_binary_default_accepts_valid_utf8() {
        // A valid multi-byte UTF-8 escape sequence must default to
        // text, not binary just because its bytes are >= 0x80.
        assert_magic_not_match_bin!(r"0	search	caf\xc3\xa9	found", b"caf\xc3\xa9");
        assert_magic_match_text!(r"0	search	caf\xc3\xa9	found", b"caf\xc3\xa9", "found");
    }

    #[test]
    fn test_belong() {
        // Test that a file with a four-byte value at offset 0 that matches the given value in big-endian byte order
        assert_magic_match_bin!("0 belong 0x12345678 Big-endian long", b"\x12\x34\x56\x78");
        // Test that a file with a four-byte value at offset 0 that does not match the given value in big-endian byte order
        assert_magic_not_match_bin!("0 belong 0x12345678 Big-endian long", b"\x78\x56\x34\x12");
        // Test that a file with a four-byte value at a non-zero offset that matches the given value in big-endian byte order
        assert_magic_match_bin!(
            "4 belong 0x12345678 Big-endian long",
            b"\x00\x00\x00\x00\x12\x34\x56\x78"
        );
        // Test < operator
        assert_magic_match_bin!("0 belong <0x12345678 Big-endian long", b"\x12\x34\x56\x77");
        assert_magic_not_match_bin!("0 belong <0x12345678 Big-endian long", b"\x12\x34\x56\x78");

        // Test > operator
        assert_magic_match_bin!("0 belong >0x12345678 Big-endian long", b"\x12\x34\x56\x79");
        assert_magic_not_match_bin!("0 belong >0x12345678 Big-endian long", b"\x12\x34\x56\x78");

        // Test & operator
        assert_magic_match_bin!("0 belong &0x5678 Big-endian long", b"\x00\x00\x56\x78");
        assert_magic_not_match_bin!("0 belong &0x0000FFFF Big-endian long", b"\x12\x34\x56\x78");

        // Test ^ operator (bitwise AND with complement)
        assert_magic_match_bin!("0 belong ^0xFFFF0000 Big-endian long", b"\x00\x00\x56\x78");
        assert_magic_not_match_bin!("0 belong ^0xFFFF0000 Big-endian long", b"\x00\x01\x56\x78");

        // Test ~ operator
        assert_magic_match_bin!("0 belong ~0x12345678 Big-endian long", b"\xed\xcb\xa9\x87");
        assert_magic_not_match_bin!("0 belong ~0x12345678 Big-endian long", b"\x12\x34\x56\x78");

        // Test x operator
        assert_magic_match_bin!("0 belong x Big-endian long", b"\x12\x34\x56\x78");
        assert_magic_match_bin!("0 belong x Big-endian long", b"\x78\x56\x34\x12");
    }

    #[test]
    fn test_parse_search() {
        parse_assert!("0 search test");
        parse_assert!("0 search/24/s test");
        parse_assert!("0 search/s/24 test");
    }

    #[test]
    fn test_bedate() {
        assert_magic_match_bin!(
            "0 bedate 946684800 Unix date (Jan 1, 2000)",
            b"\x38\x6D\x43\x80"
        );
        assert_magic_not_match_bin!(
            "0 bedate 946684800 Unix date (Jan 1, 2000)",
            b"\x00\x00\x00\x00"
        );
        assert_magic_match_bin!(
            "4 bedate 946684800 %s",
            b"\x00\x00\x00\x00\x38\x6D\x43\x80",
            "2000-01-01 00:00:00"
        );
    }
    #[test]
    fn test_beldate() {
        assert_magic_match_bin!(
            "0 beldate 946684800 Local date (Jan 1, 2000)",
            b"\x38\x6D\x43\x80"
        );
        assert_magic_not_match_bin!(
            "0 beldate 946684800 Local date (Jan 1, 2000)",
            b"\x00\x00\x00\x00"
        );

        assert_magic_match_bin!(
            "4 beldate 946684800 {}",
            b"\x00\x00\x00\x00\x38\x6D\x43\x80",
            unix_local_time_to_string(946684800)
        );
    }

    #[test]
    fn test_beqdate() {
        assert_magic_match_bin!(
            "0 beqdate 946684800 Unix date (Jan 1, 2000)",
            b"\x00\x00\x00\x00\x38\x6D\x43\x80"
        );

        assert_magic_not_match_bin!(
            "0 beqdate 946684800 Unix date (Jan 1, 2000)",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        );

        assert_magic_match_bin!(
            "0 beqdate 946684800 %s",
            b"\x00\x00\x00\x00\x38\x6D\x43\x80",
            "2000-01-01 00:00:00"
        );
    }

    #[test]
    fn test_beqldate() {
        assert_magic_match_bin!(
            "0 beqldate 946684800 Local date (Jan 1, 2000)",
            b"\x00\x00\x00\x00\x38\x6D\x43\x80"
        );

        assert_magic_not_match_bin!(
            "0 beqldate 946684800 Local date (Jan 1, 2000)",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        );

        assert_magic_match_bin!(
            "0 beqldate 946684800 %s",
            b"\x00\x00\x00\x00\x38\x6D\x43\x80",
            unix_local_time_to_string(946684800)
        );
    }

    #[test]
    fn test_medate() {
        assert_magic_match_bin!(
            "0 medate 946684800 Unix date (Jan 1, 2000)",
            b"\x6D\x38\x80\x43"
        );

        assert_magic_not_match_bin!(
            "0 medate 946684800 Unix date (Jan 1, 2000)",
            b"\x00\x00\x00\x00"
        );

        assert_magic_match_bin!(
            "4 medate 946684800 %s",
            b"\x00\x00\x00\x00\x6D\x38\x80\x43",
            "2000-01-01 00:00:00"
        );
    }

    #[test]
    fn test_meldate() {
        assert_magic_match_bin!(
            "0 meldate 946684800 Local date (Jan 1, 2000)",
            b"\x6D\x38\x80\x43"
        );
        assert_magic_not_match_bin!(
            "0 meldate 946684800 Local date (Jan 1, 2000)",
            b"\x00\x00\x00\x00"
        );

        assert_magic_match_bin!(
            "4 meldate 946684800 %s",
            b"\x00\x00\x00\x00\x6D\x38\x80\x43",
            unix_local_time_to_string(946684800)
        );
    }

    #[test]
    fn test_date() {
        assert_magic_match_bin!(
            "0 date 946684800 Local date (Jan 1, 2000)",
            b"\x80\x43\x6D\x38"
        );
        assert_magic_not_match_bin!(
            "0 date 946684800 Local date (Jan 1, 2000)",
            b"\x00\x00\x00\x00"
        );
        assert_magic_match_bin!(
            "4 date 946684800 {}",
            b"\x00\x00\x00\x00\x80\x43\x6D\x38",
            "2000-01-01 00:00:00"
        );
    }

    #[test]
    fn test_leldate() {
        assert_magic_match_bin!(
            "0 leldate 946684800 Local date (Jan 1, 2000)",
            b"\x80\x43\x6D\x38"
        );
        assert_magic_not_match_bin!(
            "0 leldate 946684800 Local date (Jan 1, 2000)",
            b"\x00\x00\x00\x00"
        );
        assert_magic_match_bin!(
            "4 leldate 946684800 {}",
            b"\x00\x00\x00\x00\x80\x43\x6D\x38",
            unix_local_time_to_string(946684800)
        );
    }

    #[test]
    fn test_leqdate() {
        assert_magic_match_bin!(
            "0 leqdate 1577836800 Unix date (Jan 1, 2020)",
            b"\x00\xe1\x0b\x5E\x00\x00\x00\x00"
        );

        assert_magic_not_match_bin!(
            "0 leqdate 1577836800 Unix date (Jan 1, 2020)",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        );
        assert_magic_match_bin!(
            "8 leqdate 1577836800 %s",
            b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\xE1\x0B\x5E\x00\x00\x00\x00",
            "2020-01-01 00:00:00"
        );
    }

    #[test]
    fn test_leqldate() {
        assert_magic_match_bin!(
            "0 leqldate 1577836800 Unix date (Jan 1, 2020)",
            b"\x00\xe1\x0b\x5E\x00\x00\x00\x00"
        );

        assert_magic_not_match_bin!(
            "0 leqldate 1577836800 Unix date (Jan 1, 2020)",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        );
        assert_magic_match_bin!(
            "8 leqldate 1577836800 %s",
            b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\xE1\x0B\x5E\x00\x00\x00\x00",
            unix_local_time_to_string(1577836800)
        );
    }

    #[test]
    fn test_melong() {
        // Test = operator
        assert_magic_match_bin!(
            "0 melong =0x12345678 Middle-endian long",
            b"\x34\x12\x78\x56"
        );
        assert_magic_not_match_bin!(
            "0 melong =0x12345678 Middle-endian long",
            b"\x00\x00\x00\x00"
        );

        // Test < operator
        assert_magic_match_bin!(
            "0 melong <0x12345678 Middle-endian long",
            b"\x34\x12\x78\x55"
        ); // 0x12345677 in middle-endian
        assert_magic_not_match_bin!(
            "0 melong <0x12345678 Middle-endian long",
            b"\x34\x12\x78\x56"
        ); // 0x12345678 in middle-endian

        // Test > operator
        assert_magic_match_bin!(
            "0 melong >0x12345678 Middle-endian long",
            b"\x34\x12\x78\x57"
        ); // 0x12345679 in middle-endian
        assert_magic_not_match_bin!(
            "0 melong >0x12345678 Middle-endian long",
            b"\x34\x12\x78\x56"
        ); // 0x12345678 in middle-endian

        // Test & operator
        assert_magic_match_bin!("0 melong &0x5678 Middle-endian long", b"\xab\xcd\x78\x56"); // 0x00007856 in middle-endian
        assert_magic_not_match_bin!(
            "0 melong &0x0000FFFF Middle-endian long",
            b"\x34\x12\x78\x56"
        ); // 0x12347856 in middle-endian

        // Test ^ operator (bitwise AND with complement)
        assert_magic_match_bin!(
            "0 melong ^0xFFFF0000 Middle-endian long",
            b"\x00\x00\x78\x56"
        ); // 0x00007856 in middle-endian
        assert_magic_not_match_bin!(
            "0 melong ^0xFFFF0000 Middle-endian long",
            b"\x00\x01\x78\x56"
        ); // 0x00017856 in middle-endian

        // Test ~ operator
        assert_magic_match_bin!(
            "0 melong ~0x12345678 Middle-endian long",
            b"\xCB\xED\x87\xA9"
        );
        assert_magic_not_match_bin!(
            "0 melong ~0x12345678 Middle-endian long",
            b"\x34\x12\x78\x56"
        ); // The original value

        // Test x operator
        assert_magic_match_bin!("0 melong x Middle-endian long", b"\x34\x12\x78\x56");
        assert_magic_match_bin!("0 melong x Middle-endian long", b"\x00\x00\x00\x00");
    }

    #[test]
    fn test_uquad() {
        // Test = operator
        assert_magic_match_bin!(
            "0 uquad =0x123456789ABCDEF0 Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12"
        );
        assert_magic_not_match_bin!(
            "0 uquad =0x123456789ABCDEF0 Unsigned quad",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        );

        // Test < operator
        assert_magic_match_bin!(
            "0 uquad <0x123456789ABCDEF0 Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x11"
        );
        assert_magic_not_match_bin!(
            "0 uquad <0x123456789ABCDEF0 Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12"
        );

        // Test > operator
        assert_magic_match_bin!(
            "0 uquad >0x123456789ABCDEF0 Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x13"
        );
        assert_magic_not_match_bin!(
            "0 uquad >0x123456789ABCDEF0 Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12"
        );

        // Test & operator
        assert_magic_match_bin!(
            "0 uquad &0xF0 Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12"
        );
        assert_magic_not_match_bin!(
            "0 uquad &0xFF Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12"
        );

        // Test ^ operator (bitwise AND with complement)
        assert_magic_match_bin!(
            "0 uquad ^0xFFFFFFFFFFFFFFFF Unsigned quad",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        ); // All bits clear
        assert_magic_not_match_bin!(
            "0 uquad ^0xFFFFFFFFFFFFFFFF Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12"
        ); // Some bits set

        // Test ~ operator
        assert_magic_match_bin!(
            "0 uquad ~0x123456789ABCDEF0 Unsigned quad",
            b"\x0F\x21\x43\x65\x87\xA9\xCB\xED"
        );
        assert_magic_not_match_bin!(
            "0 uquad ~0x123456789ABCDEF0 Unsigned quad",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12"
        ); // The original value

        // Test x operator
        assert_magic_match_bin!(
            "0 uquad x {:#x}",
            b"\xF0\xDE\xBC\x9A\x78\x56\x34\x12",
            "0x123456789abcdef0"
        );
        assert_magic_match_bin!(
            "0 uquad x Unsigned quad",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        );
    }

    // guid stores data1/data2/data3 little-endian (the Microsoft
    // mixed-endian GUID layout), only data4 is raw bytes -- confirmed
    // against real `file`.
    #[test]
    fn test_guid() {
        assert_magic_match_bin!(
            "0 guid DDCCBBAA-FFEE-1100-2233-445566778899 It works",
            b"\xAA\xBB\xCC\xDD\xEE\xFF\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99"
        );

        assert_magic_not_match_bin!(
            "0 guid DDCCBBAA-FFEE-1100-2233-445566778899 It works",
            b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F"
        );

        assert_magic_match_bin!(
            "0 guid x %s",
            b"\xAA\xBB\xCC\xDD\xEE\xFF\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99",
            "DDCCBBAA-FFEE-1100-2233-445566778899"
        );
    }

    // leguid has identical semantics to guid.
    #[test]
    fn test_leguid() {
        assert_magic_match_bin!(
            "0 leguid DDCCBBAA-FFEE-1100-2233-445566778899 It works",
            b"\xAA\xBB\xCC\xDD\xEE\xFF\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99"
        );

        assert_magic_not_match_bin!(
            "0 leguid DDCCBBAA-FFEE-1100-2233-445566778899 It works",
            b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F"
        );

        assert_magic_match_bin!(
            "0 leguid x %s",
            b"\xAA\xBB\xCC\xDD\xEE\xFF\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99",
            "DDCCBBAA-FFEE-1100-2233-445566778899"
        );
    }

    // beguid has no on-disk mixed-endian convention, unlike guid/leguid: the
    // 16 bytes are one plain big-endian number, matching the string's
    // sequential digit order directly.
    #[test]
    fn test_beguid() {
        assert_magic_match_bin!(
            "0 beguid AABBCCDD-EEFF-0011-2233-445566778899 It works",
            b"\xAA\xBB\xCC\xDD\xEE\xFF\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99"
        );

        assert_magic_not_match_bin!(
            "0 beguid AABBCCDD-EEFF-0011-2233-445566778899 It works",
            b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F"
        );

        assert_magic_match_bin!(
            "0 beguid x %s",
            b"\xAA\xBB\xCC\xDD\xEE\xFF\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99",
            "AABBCCDD-EEFF-0011-2233-445566778899"
        );
    }

    #[test]
    fn test_ubeqdate() {
        assert_magic_match_bin!(
            "0 ubeqdate 1633046400 It works",
            b"\x00\x00\x00\x00\x61\x56\x4f\x80"
        );

        assert_magic_match_bin!(
            "0 ubeqdate x %s",
            b"\x00\x00\x00\x00\x61\x56\x4f\x80",
            "2021-10-01 00:00:00"
        );

        assert_magic_not_match_bin!(
            "0 ubeqdate 1633046400 It should not work",
            b"\x00\x00\x00\x00\x00\x00\x00\x00"
        );
    }

    #[test]
    fn test_ldate() {
        assert_magic_match_bin!("0 ldate 1640551520 It works", b"\x60\xd4\xC8\x61");

        assert_magic_not_match_bin!("0 ldate 1633046400 It should not work", b"\x00\x00\x00\x00");

        assert_magic_match_bin!(
            "0 ldate x %s",
            b"\x60\xd4\xC8\x61",
            unix_local_time_to_string(1640551520)
        );
    }

    #[test]
    fn test_scalar_with_transform() {
        assert_magic_match_bin!("0 ubyte/10 2 {}", b"\x14", "2");
        assert_magic_match_bin!("0 ubyte/10 x {}", b"\x14", "2");
        assert_magic_match_bin!("0 ubyte%10 x {}", b"\x14", "0");
    }

    #[test]
    fn test_float_with_transform() {
        assert_magic_match_bin!("0 lefloat/10 2 {}", b"\x00\x00\xa0\x41", "2");
        assert_magic_match_bin!("0 lefloat/10 x {}", b"\x00\x00\xa0\x41", "2");
        assert_magic_match_bin!("0 lefloat%10 x {}", b"\x00\x00\xa0\x41", "0");
    }

    #[test]
    fn test_read_octal() {
        // Basic cases
        assert_eq!(read_octal_u64(&mut buf_reader!("0")), Some(0));
        assert_eq!(read_octal_u64(&mut buf_reader!("00")), Some(0));
        assert_eq!(read_octal_u64(&mut buf_reader!("01")), Some(1));
        assert_eq!(read_octal_u64(&mut buf_reader!("07")), Some(7));
        assert_eq!(read_octal_u64(&mut buf_reader!("010")), Some(8));
        assert_eq!(read_octal_u64(&mut buf_reader!("0123")), Some(83));
        assert_eq!(read_octal_u64(&mut buf_reader!("0755")), Some(493));

        // With trailing non-octal characters
        assert_eq!(read_octal_u64(&mut buf_reader!("0ABC")), Some(0));
        assert_eq!(read_octal_u64(&mut buf_reader!("01ABC")), Some(1));
        assert_eq!(read_octal_u64(&mut buf_reader!("0755ABC")), Some(493));
        assert_eq!(read_octal_u64(&mut buf_reader!("0123ABC")), Some(83));

        // Invalid octal digits
        assert_eq!(read_octal_u64(&mut buf_reader!("08")), Some(0)); // stops at '8'
        assert_eq!(read_octal_u64(&mut buf_reader!("01238")), Some(83)); // stops at '8'

        // No leading '0'
        assert_eq!(read_octal_u64(&mut buf_reader!("123")), None);
        assert_eq!(read_octal_u64(&mut buf_reader!("755")), None);

        // Empty string
        assert_eq!(read_octal_u64(&mut buf_reader!("")), None);

        // Only non-octal characters
        assert_eq!(read_octal_u64(&mut buf_reader!("ABC")), None);
        assert_eq!(read_octal_u64(&mut buf_reader!("8ABC")), None); // first char is not '0'

        // Longer valid octal (but within u64 range)
        assert_eq!(
            read_octal_u64(&mut buf_reader!("01777777777")),
            Some(268435455)
        );
    }

    #[test]
    fn test_offset_bug_1() {
        // this tests the exact behaviour
        // expected by libmagic/file
        assert_magic_match_bin!(
            r"
1	string		TEST Bread is
# offset computation is relative to
# rule start
>(5.b)	use toasted

0 name toasted
>0	string twice Toasted
>>0  use toasted_twice

0 name toasted_twice
>(6.b) string x %s
        ",
            b"\x00TEST\x06twice\x00\x06",
            "Bread is Toasted twice"
        );
    }

    // this test implement the exact same logic as
    // test_offset_bug_1 except that the rule starts
    // matching from end. Surprisingly we need to
    // adjust indirect offsets so that it works in
    // libmagic/file
    #[test]
    fn test_offset_bug_2() {
        // this tests the exact behaviour
        // expected by libmagic/file
        assert_magic_match_bin!(
            r"
-12	string		TEST Bread is
>(4.b)	use toasted

0 name toasted
>0	string twice Toasted
>>0  use toasted_twice

0 name toasted_twice
>(6.b) string x %
        ",
            b"\x00TEST\x06twice\x00\x06",
            "Bread is Toasted twice"
        )
    }

    #[test]
    fn test_offset_bug_3() {
        // this tests the exact behaviour
        // expected by libmagic/file
        assert_magic_match_bin!(
            r"
1	string		TEST Bread is
>(5.b) indirect/r x

0	string twice Toasted
>0  use toasted_twice

0 name toasted_twice
>0 string x %s
        ",
            b"\x00TEST\x06twice\x00\x08",
            "Bread is Toasted twice"
        )
    }

    #[test]
    fn test_offset_bug_4() {
        // this tests the exact behaviour
        // expected by libmagic/file
        assert_magic_match_bin!(
            r"
1	string		Bread %s
>(6.b) indirect/r x

# this one uses a based offset
# computed at indirection
1	string is\ Toasted %s
>(11.b)  use toasted_twice

# this one is using a new base
# offset being previous base
# offset + offset of use
0 name toasted_twice
>0 string x %s
            ",
            b"\x00Bread\x06is Toasted\x0ctwice\x00",
            "Bread is Toasted twice"
        )
    }

    #[test]
    fn test_offset_bug_5() {
        assert_magic_match_bin!(
            r"
1	string		TEST Bread is
>(5.b) indirect/r x

0	string twice Toasted
>0  use toasted_twice

0 name toasted_twice
>0 string twice
>>&1 byte 0x08 twice
            ",
            b"\x00TEST\x06twice\x00\x08",
            "Bread is Toasted twice"
        )
    }

    #[test]
    fn test_bug_6() {
        // An indirect use test should not be successful
        // even if a match with no message occurs

        assert_magic_match_bin!(
            r"
1	string		TEST Bread is toasted
>&0 use toasted
>>&0 default x but not burnt

0 name toasted
>1 string toasted
            ",
            b"\x00TEST\x06toasted",
            "Bread is toasted"
        )
    }

    #[test]
    fn test_offset_bug_7() {
        // Bug: nested 'use' directives with indirect offsets don't properly
        // adjust offsets during recursion. This test encodes the behavior
        // libmagic has when dealing with such scenarios.
        assert_magic_match_bin!(
            r"
1	string		TEST Bread is
# offset computation is relative to
# rule start
>(5.b)	use toasted

0 name toasted
>0	string toast Toasted
>>(6.b)  use toasted_twice

0 name toasted_twice
>1 string x %s
        ",
            b"\x00TEST\x06toast\x00\x06twice\x00",
            "Bread is Toasted twice"
        );
    }

    #[test]
    fn test_offset_bug_8() {
        // A bare (non-'&') nested offset under an '&'-relative sibling
        // must resolve as absolute from file start, not relative to the
        // enclosing end-relative top-level anchor.
        //   -2 uleshort 0
        //   >&-22 string PK\005\006
        //   >>0 string SIG  <- must check absolute offset 0, not
        //                      "top-level anchor" + 0.
        assert_magic_match_bin!(
            r"
-2	uleshort	0
>&-22	string	PK\005\006
>>0	string	SIG	found SIG at absolute start
            ",
            b"SIG\x00\x00\x00\x00\x00PK\x05\x06\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00",
            "found SIG at absolute start"
        );
    }

    #[test]
    fn test_offset_bug_9() {
        // Same root cause as test_offset_bug_8, but for the "N" in an
        // indirect `(N.b)` offset expression instead of a bare `>>N`
        // continuation. Byte 0 holds 3: if `(0.b)` resolves absolute
        // (correct, matching real file), it reads that 3 and dispatches
        // `whichbyte` at offset 3, where "YES" sits. If it wrongly
        // resolves relative to the stale end-relative anchor (byte 28,
        // part of the `-2 uleshort 0` test, always 0 here), it
        // dispatches at offset 0 instead, landing back on the literal
        // byte 3 itself.
        assert_magic_match_bin!(
            r"
-2	uleshort	0
>&-22	string	PK\005\006
>>(0.b)	use	whichbyte

0	name	whichbyte
>0	byte	0x03	found byte 0x03 (wrong: stale anchor)
>0	string	YES	found YES marker (correct: absolute)
            ",
            b"\x03\x00\x00YES\x00\x00PK\x05\x06\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00",
            "found YES marker (correct: absolute)"
        );
    }

    #[test]
    fn test_offset_bug_10() {
        // Regression (real-world case: magic-db/src/magdir/msooxml
        // failing to detect .xlsx/.docx/.pptx). `inner`'s failed
        // `search/1000` for "NEEDLE" scans all the way to EOF, leaving
        // the shared stream cursor there. The sibling `default` entry
        // reads nothing of its own, so it must use its own anchor
        // (0x10) for its children's `&`-relative offsets instead of
        // that leftover EOF cursor -- otherwise `>>&5` computes
        // 40 + 5 = 45 (out of bounds) instead of landing on "TARGET"
        // at byte 21.
        assert_magic_match_bin!(
            r"
0	string	MAGIC
>0x10	use	inner
>0x10	default	x
>>&5	string	TARGET	found target via correct anchor

0	name	inner
>0	search/1000	NEEDLE
            ",
            b"MAGIC\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00TARGET\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00",
            "found target via correct anchor"
        );
    }

    #[test]
    fn test_offset_bug_11() {
        // Same root cause as test_offset_bug_10, confirmed independently
        // for `clear` (a `default` sibling isn't the only entry type that
        // reads nothing of its own and so is vulnerable to inheriting a
        // preceding `use`'s leftover stream position).
        assert_magic_match_bin!(
            r"
0	string	MAGIC
>0x10	use	inner
>0x10	clear	x
>>&5	string	TARGET	found target via correct anchor

0	name	inner
>0	search/1000	NEEDLE
            ",
            b"MAGIC\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00TARGET\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00",
            "found target via correct anchor"
        );
    }

    #[test]
    fn test_message_parts() {
        let m = best_magic(
            r#"0	string/W	#!/usr/bin/env\ python  PYTHON"#,
            b"#!/usr/bin/env    python",
            StreamKind::Text(TextEncoding::Ascii),
        )
        .unwrap();

        assert!(m.message_parts().any(|p| p.eq_ignore_ascii_case("python")))
    }

    #[test]
    fn test_magic_stream_kind_reflects_detection() {
        let mut db = MagicDb::new();
        db.load(parse_assert!("0\tsearch\t__NEVER_MATCH__\tnope\n"));

        let mut ascii = BufReader::from_slice(b"hello world");
        let m = db.best_magic(&mut ascii, None).unwrap();
        assert_eq!(m.stream_kind(), Some(StreamKind::Text(TextEncoding::Ascii)));

        let mut utf8 = BufReader::from_slice("héllo wörld".as_bytes());
        let m = db.best_magic(&mut utf8, None).unwrap();
        assert_eq!(m.stream_kind(), Some(StreamKind::Text(TextEncoding::Utf8)));

        let mut binary = BufReader::from_slice(&[0x00u8, 0x01, 0x02, 0xff, 0xfe, 0x00, 0x00, 0x00]);
        let m = db.best_magic(&mut binary, None).unwrap();
        assert_eq!(m.stream_kind(), Some(StreamKind::Binary));
    }

    // Regression: a buffer that's valid ASCII/UTF-8 byte-for-byte (every byte
    // < 0x80) can still contain control bytes (e.g. embedded NUL, as in a
    // fuzzed PE header) that libmagic's text_chars whitelist rejects
    // (encoding.c: looks_ascii/file_looks_utf8), making it treat the buffer
    // as binary rather than text. Confirmed against real `file
    // --mime-encoding`.
    #[test]
    fn test_stream_kind_rejects_ascii_with_forbidden_control_bytes() {
        assert_eq!(
            guess_stream_kind(b"MZ\x00\x00\x00\x00this is otherwise all printable ASCII"),
            StreamKind::Binary
        );
    }

    #[test]
    fn test_load_bulk() {
        let mut db = MagicDb::new();

        let rules = vec![
            parse_assert!("0 search test"),
            parse_assert!("0 search/24/s test"),
            parse_assert!("0 search/s/24 test"),
        ];

        db.load_bulk(rules.into_iter());
        db.verify().unwrap();
    }

    #[test]
    fn test_load_bulk_failure() {
        let mut db = MagicDb::new();

        let rules = vec![parse_assert!(
            r#"
0 search/s/24 test
>0 use test
"#
        )];

        db.load_bulk(rules.into_iter());
        assert!(matches!(db.verify(), Err(Error::Verify(_, _, _))));
    }

    // try_csv runs before any rule; pass a never-matching rule so the
    // harness only exercises the hardcoded CSV detector.
    fn csv_magic(content: &[u8]) -> Magic<'static> {
        best_magic(
            "0\tstring\t__NEVER_MATCH__\tnope\n",
            content,
            StreamKind::Text(TextEncoding::Utf8),
        )
        .unwrap()
    }

    #[test]
    fn test_csv_two_rows_two_cols() {
        let m = csv_magic(b"a,b\n1,2\n");
        assert_eq!(m.mime_type(), "text/csv");
    }

    #[test]
    fn test_csv_short_consistent_rows() {
        let m = csv_magic(b"a,b,c\n1,2,3\n4,5,6\n7,8,9\n10,11,12\n");
        assert_eq!(m.mime_type(), "text/csv");
    }

    #[test]
    fn test_csv_many_rows_still_detected() {
        let body: &[u8] = b"a,b,c\n1,2,3\n4,5,6\n7,8,9\n10,11,12\n13,14,15\n16,17,18\n19,20,21\n22,23,24\n25,26,27\n28,29,30\n31,32,33\n";
        let m = csv_magic(body);
        assert_eq!(m.mime_type(), "text/csv");
    }

    #[test]
    fn test_csv_single_field_rejected() {
        let m = csv_magic(b"hello\nworld\nfoo\n");
        assert_ne!(m.mime_type(), "text/csv");
    }

    #[test]
    fn test_csv_ragged_columns_rejected() {
        let m = csv_magic(b"a,b,c\n1,2\n3,4,5\n");
        assert_ne!(m.mime_type(), "text/csv");
    }

    // Regression: nested scalar tests under a top-level `string` match used to
    // be dropped on text inputs because the binary/text gate ran inside every
    // recursion. The shape mirrors magdir/rtf:11–18 — the message lives on
    // the level-2 ubyte child, so dropping the children silently strips the
    // whole rule. Upstream libmagic's softmagic.c::match() applies the gate
    // only at the outer match loop.
    #[test]
    fn test_string_parent_with_scalar_children_on_text_stream() {
        assert_magic_match_text!(
            r"
0	string		{\\rtf
>5	ubyte		!0xAB
>>5	ubyte		!0x5C		Rich Text Format data
!:mime	text/rtf
!:ext	rtf
            ",
            b"{\\rtf1\\ansi\\ansicpg1252\nHello world}",
            "Rich Text Format data"
        );
    }

    // The level-1 `>5 ubyte !0xAB` qualifier exists upstream specifically to
    // skip DROID fmt-355-signature-id-522.rtf. With \xAB at offset 5 the rule
    // must NOT emit a message even now that children run on text streams.
    #[test]
    fn test_rtf_droid_skip_still_rejects() {
        assert_magic_not_match_text!(
            r"
0	string		{\\rtf
>5	ubyte		!0xAB
>>5	ubyte		!0x5C		Rich Text Format data
            ",
            b"{\\rtf\xab......\n"
        );
    }

    // Regression: a `!=` test against out-of-bounds data is considered true.
    #[test]
    fn test_neq_test_on_unreadable_offset_matches() {
        let mut content = vec![0u8; 64];
        content[0] = b'M';
        content[1] = b'Z';
        // offset 0x3c holds a 4-byte LE offset pointing far past EOF
        content[0x3c..0x40].copy_from_slice(&0xFFFF_FFF0u32.to_le_bytes());

        let m = best_magic(
            "0\tstring\tMZ\n>(0x3c.l)\tstring\t!PE\\0\\0\tMS-DOS executable\n",
            &content,
            StreamKind::Binary,
        )
        .unwrap();
        assert_eq!(m.message(), "MS-DOS executable");
    }

    #[test]
    fn test_eq_test_on_unreadable_offset_does_not_match() {
        let mut content = vec![0u8; 64];
        content[0] = b'M';
        content[1] = b'Z';
        content[0x3c..0x40].copy_from_slice(&0xFFFF_FFF0u32.to_le_bytes());

        let m = best_magic(
            "0\tstring\tMZ\n>(0x3c.l)\tstring\tPE\\0\\0\tPE executable\n",
            &content,
            StreamKind::Binary,
        )
        .unwrap();
        assert_eq!(m.message(), "data");
    }
}