libmagic_rs/

lib.rs

// Copyright (c) 2025-2026 the libmagic-rs contributors
// SPDX-License-Identifier: Apache-2.0

//! Rust Libmagic - A pure-Rust implementation of libmagic
//!
//! This library provides safe, efficient file type identification through magic rule evaluation.
//! It parses magic files into an Abstract Syntax Tree (AST) and evaluates them against file
//! buffers using memory-mapped I/O for optimal performance.
//!
//! # Security Features
//!
//! This implementation prioritizes security through:
//! - **Memory Safety**: Pure Rust with no unsafe code (except in vetted dependencies)
//! - **Bounds Checking**: Comprehensive validation of all buffer accesses
//! - **Resource Limits**: Configurable limits to prevent resource exhaustion attacks
//! - **Input Validation**: Strict validation of magic files and configuration
//! - **Error Handling**: Secure error messages that don't leak sensitive information
//! - **Timeout Protection**: Configurable timeouts to prevent denial of service
//!
//! # Examples
//!
//! ## Complete Workflow: Load → Evaluate → Output
//!
//! ```rust,no_run
//! use libmagic_rs::MagicDatabase;
//!
//! // Load magic rules from a text file
//! let db = MagicDatabase::load_from_file("/usr/share/misc/magic")?;
//!
//! // Evaluate a file to determine its type
//! let result = db.evaluate_file("sample.bin")?;
//! println!("File type: {}", result.description);
//!
//! // Access metadata about loaded rules
//! if let Some(path) = db.source_path() {
//!     println!("Rules loaded from: {}", path.display());
//! }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ## Loading from a Directory
//!
//! ```rust,no_run
//! use libmagic_rs::MagicDatabase;
//!
//! // Load all magic files from a directory (Magdir pattern)
//! let db = MagicDatabase::load_from_file("/usr/share/misc/magic.d")?;
//!
//! // Evaluate multiple files
//! for file in &["file1.bin", "file2.bin", "file3.bin"] {
//!     let result = db.evaluate_file(file)?;
//!     println!("{}: {}", file, result.description);
//! }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ## Error Handling for Binary Files
//!
//! ```rust,no_run
//! use libmagic_rs::MagicDatabase;
//!
//! // Attempt to load a binary .mgc file
//! match MagicDatabase::load_from_file("/usr/share/misc/magic.mgc") {
//!     Ok(db) => {
//!         let result = db.evaluate_file("sample.bin")?;
//!         println!("File type: {}", result.description);
//!     }
//!     Err(e) => {
//!         eprintln!("Error loading magic file: {}", e);
//!         eprintln!("Hint: Binary .mgc files are not supported.");
//!         eprintln!("Use --use-builtin option to use built-in rules,");
//!         eprintln!("or provide a text-based magic file or directory.");
//!     }
//! }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ## Debugging with Source Path Metadata
//!
//! ```rust,no_run
//! use libmagic_rs::MagicDatabase;
//!
//! let db = MagicDatabase::load_from_file("/usr/share/misc/magic")?;
//!
//! // Use source_path() for debugging and logging
//! if let Some(source) = db.source_path() {
//!     println!("Loaded {} from {}",
//!              "magic rules",
//!              source.display());
//! }
//!
//! // Evaluate files with source tracking
//! let result = db.evaluate_file("sample.bin")?;
//! println!("Detection result: {}", result.description);
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```

#![deny(missing_docs)]
#![deny(unsafe_code)]
#![deny(clippy::all)]
#![warn(clippy::pedantic)]

use std::io::Read;
use std::path::{Path, PathBuf};

use serde::Serialize;

// Re-export modules
pub mod builtin_rules;
mod config;
pub mod error;
pub mod evaluator;
pub mod io;
pub mod mime;
pub mod output;
pub mod parser;
pub mod tags;

pub use config::EvaluationConfig;

/// Build-time helpers for compiling magic rules.
///
/// This module contains functionality used by the build script to parse magic files
/// and generate Rust code for built-in rules. It is only available during tests and
/// documentation builds to enable comprehensive testing of the build process.
#[cfg(any(test, doc))]
pub mod build_helpers;

// Re-export core AST types for convenience
pub use parser::ast::{
    Endianness, MagicRule, OffsetSpec, Operator, PStringLengthWidth, StrengthModifier, TypeKind,
    Value,
};

// Re-export evaluator types for convenience
pub use evaluator::{EvaluationContext, RuleMatch};

// Re-export error types for convenience
pub use error::{EvaluationError, LibmagicError, ParseError};

/// Result type for library operations
pub type Result<T> = std::result::Result<T, LibmagicError>;

impl From<crate::io::IoError> for LibmagicError {
    fn from(err: crate::io::IoError) -> Self {
        // Preserve the structured error message (includes path and operation context)
        LibmagicError::FileError(err.to_string())
    }
}

/// Main interface for magic rule database
#[derive(Debug)]
#[non_exhaustive]
pub struct MagicDatabase {
    /// Named subroutine definitions extracted from magic file `name` rules,
    /// keyed by identifier. The evaluator consults this table when a rule of
    /// type `TypeKind::Meta(MetaType::Use { name, .. })` is reached.
    name_table: std::sync::Arc<crate::parser::name_table::NameTable>,
    /// Top-level rules as a shared immutable slice. This is the primary rule
    /// storage for the database. Passed through the evaluation context as part
    /// of the rule environment so whole-database operations (e.g. `indirect`)
    /// can re-enter at the root without re-sorting or cloning the rule tree.
    root_rules: std::sync::Arc<[MagicRule]>,
    config: EvaluationConfig,
    /// Optional path to the source magic file or directory from which rules were loaded.
    /// This is used for debugging and logging purposes.
    source_path: Option<PathBuf>,
    /// Cached MIME type mapper to avoid rebuilding the lookup table on every evaluation
    mime_mapper: mime::MimeMapper,
}

/// GNU `file`'s description for a one-byte file (`funcs.c::file_buffer`).
const VERY_SHORT_FILE: &str = "very short file (no magic)";

impl MagicDatabase {
    /// Create a database using built-in magic rules.
    ///
    /// Loads magic rules that are compiled into the library binary at build time
    /// from `src/builtin_rules.magic`. These rules provide high-confidence detection
    /// for common file types including executables (ELF, PE/DOS), archives (ZIP, TAR,
    /// GZIP), images (JPEG, PNG, GIF, BMP), and documents (PDF).
    ///
    /// # Security
    ///
    /// This constructor uses [`EvaluationConfig::default()`], which leaves
    /// `timeout_ms` unset (unbounded). When processing untrusted input
    /// (adversarial file buffers, large uploads, etc.), prefer
    /// [`MagicDatabase::with_builtin_rules_and_config`] with
    /// [`EvaluationConfig::performance()`] (which sets a 1-second timeout)
    /// or construct a config explicitly with a non-`None` timeout sized
    /// for your workload. The `Default` impl intentionally targets CLI
    /// one-shot usage rather than long-running services.
    ///
    /// # Thread safety
    ///
    /// `MagicDatabase` is `Send + Sync` and holds no interior mutability,
    /// so an `Arc<MagicDatabase>` can be shared across threads for
    /// parallel file scanning. A fresh evaluation context is constructed
    /// per `evaluate_buffer` / `evaluate_file` call, so concurrent calls
    /// do not interfere.
    ///
    /// # Errors
    ///
    /// Currently always returns `Ok`. In future implementations, this may return
    /// an error if the built-in rules fail to load or validate.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use libmagic_rs::MagicDatabase;
    ///
    /// let db = MagicDatabase::with_builtin_rules()?;
    /// let result = db.evaluate_buffer(b"\x7fELF")?;
    /// // Returns actual file type detection (e.g., "ELF")
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn with_builtin_rules() -> Result<Self> {
        Self::with_builtin_rules_and_config(EvaluationConfig::default())
    }

    /// Create database with built-in rules and custom configuration.
    ///
    /// Loads built-in magic rules compiled at build time and applies the specified
    /// evaluation configuration (e.g., custom timeout settings).
    ///
    /// # Security
    ///
    /// For untrusted input (adversarial file buffers, web uploads, mail
    /// scanning), pass a config with an explicit timeout such as
    /// [`EvaluationConfig::performance()`]. The default config has
    /// `timeout_ms = None` which leaves evaluation unbounded; see the
    /// rationale on [`EvaluationConfig::default`].
    ///
    /// # Arguments
    ///
    /// * `config` - Custom evaluation configuration to use with the built-in rules
    ///
    /// # Errors
    ///
    /// Returns `LibmagicError` if the configuration is invalid (e.g., timeout is zero).
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use libmagic_rs::{MagicDatabase, EvaluationConfig};
    ///
    /// // Prefer the performance() preset over default() when processing
    /// // untrusted input. default() has no timeout by design.
    /// let config = EvaluationConfig::performance();
    /// let db = MagicDatabase::with_builtin_rules_and_config(config)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn with_builtin_rules_and_config(config: EvaluationConfig) -> Result<Self> {
        config.validate()?;
        let mut rules = crate::builtin_rules::get_builtin_rules();
        // Sort only the TOP-LEVEL rules by strength (libmagic's
        // `apprentice_sort` orders whole magic entries by their first line's
        // strength). Continuation/child rules are NOT reordered -- they run
        // in file order, which is load-bearing for order-sensitive directives
        // like `default`/`clear` and for multi-fragment descriptions whose
        // pieces must render in source order (e.g. gzip's "last modified,
        // max compression, from Unix"). See the non-recursive contract note
        // on `sort_rules_by_strength`.
        crate::evaluator::strength::sort_rules_by_strength(&mut rules);
        let root_rules: std::sync::Arc<[MagicRule]> =
            std::sync::Arc::from(rules.into_boxed_slice());
        Ok(Self {
            name_table: std::sync::Arc::new(crate::parser::name_table::NameTable::empty()),
            root_rules,
            config,
            source_path: None,
            mime_mapper: mime::MimeMapper::new(),
        })
    }

    /// Load magic rules from a file
    ///
    /// # Security
    ///
    /// This constructor uses [`EvaluationConfig::default()`], which
    /// leaves `timeout_ms` unset. See the security note on
    /// [`Self::with_builtin_rules`] for the implications and prefer
    /// [`Self::load_from_file_with_config`] with an explicit timeout
    /// when processing untrusted input.
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the magic file to load
    ///
    /// # Errors
    ///
    /// Returns `LibmagicError::IoError` if the file cannot be read.
    /// Returns `LibmagicError::ParseError` if the magic file format is invalid.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use libmagic_rs::MagicDatabase;
    ///
    /// let db = MagicDatabase::load_from_file("magic.db")?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn load_from_file<P: AsRef<Path>>(path: P) -> Result<Self> {
        Self::load_from_file_with_config(path, EvaluationConfig::default())
    }

    /// Load from file with custom config (e.g., timeout).
    ///
    /// # Security
    ///
    /// For untrusted input, pass [`EvaluationConfig::performance()`] or
    /// a config with an explicit non-`None` `timeout_ms`. See
    /// [`Self::with_builtin_rules`] for the full rationale.
    ///
    /// # Errors
    ///
    /// Returns error if file cannot be read, parsed, or config is invalid
    pub fn load_from_file_with_config<P: AsRef<Path>>(
        path: P,
        config: EvaluationConfig,
    ) -> Result<Self> {
        config.validate()?;
        let parsed = parser::load_magic_file(path.as_ref()).map_err(Self::map_parse_error)?;
        Ok(Self::from_parsed(
            parsed,
            config,
            Some(path.as_ref().to_path_buf()),
        ))
    }

    /// Load text magic rules from owned bytes.
    ///
    /// This consumes the supplied [`Vec<u8>`] and reuses its allocation when
    /// the input is valid UTF-8, avoiding the additional full-buffer copy made
    /// when loading already-buffered data through [`Self::load_from_reader`].
    /// Invalid UTF-8 is replaced as documented for file and reader loading and
    /// may require another allocation. Input is bounded by the same 1 GiB limit
    /// as [`Self::load_from_file`]. Compiled binary `.mgc` databases are not
    /// supported.
    ///
    /// Databases loaded from bytes have no filesystem source, so
    /// [`Self::source_path`] returns `None`.
    ///
    /// # Parsing behavior
    ///
    /// Parsing is tolerant, matching [`Self::load_from_file`]: a rule line
    /// that fails to parse is skipped along with its indented subtree, and a
    /// warning is logged rather than returned. Input in which every line fails
    /// to parse therefore yields an `Ok` database with no rules, not an error.
    ///
    /// # Security
    ///
    /// This constructor uses [`EvaluationConfig::default()`], which leaves
    /// `timeout_ms` unset. See the security note on
    /// [`Self::with_builtin_rules`] and prefer
    /// [`Self::load_from_bytes_with_config`] with an explicit timeout when
    /// processing untrusted input.
    ///
    /// # Errors
    ///
    /// Returns [`LibmagicError::ParseError`] if the input is oversized,
    /// compiled `.mgc` data, or cannot be parsed as a text magic database.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use libmagic_rs::MagicDatabase;
    ///
    /// let rules = b"0 string INKMEM in-memory magic\n".to_vec();
    /// let db = MagicDatabase::load_from_bytes(rules)?;
    /// let result = db.evaluate_buffer(b"INKMEM payload")?;
    /// assert!(result.description.contains("in-memory magic"));
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn load_from_bytes(bytes: Vec<u8>) -> Result<Self> {
        Self::load_from_bytes_with_config(bytes, EvaluationConfig::default())
    }

    /// Load text magic rules from owned bytes with custom evaluation config.
    ///
    /// See [`Self::load_from_bytes`] for ownership, size limits, and
    /// source-path behavior.
    ///
    /// # Security
    ///
    /// For untrusted input, pass [`EvaluationConfig::performance()`] or a
    /// config with an explicit non-`None` `timeout_ms`.
    ///
    /// # Errors
    ///
    /// Returns an error if the config is invalid or the input is oversized,
    /// compiled `.mgc` data, or cannot be parsed as a text magic database.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use libmagic_rs::{EvaluationConfig, MagicDatabase};
    ///
    /// let rules = b"0 string INKMEM in-memory magic\n".to_vec();
    /// let config = EvaluationConfig::performance();
    /// let db = MagicDatabase::load_from_bytes_with_config(rules, config)?;
    /// let result = db.evaluate_buffer(b"INKMEM payload")?;
    /// assert!(result.description.contains("in-memory magic"));
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn load_from_bytes_with_config(bytes: Vec<u8>, config: EvaluationConfig) -> Result<Self> {
        config.validate()?;
        let parsed = parser::load_magic_bytes(bytes).map_err(Self::map_parse_error)?;
        Ok(Self::from_parsed(parsed, config, None))
    }

    /// Load text magic rules from a reader.
    ///
    /// This accepts any [`Read`] implementation, including byte slices,
    /// [`std::io::Cursor`], files, and buffered readers. Input is bounded by
    /// the same 1 GiB limit as [`Self::load_from_file`]. Compiled binary
    /// `.mgc` databases are not supported.
    ///
    /// Databases loaded from a reader have no filesystem source, so
    /// [`Self::source_path`] returns `None`.
    ///
    /// # Parsing behavior
    ///
    /// Parsing is tolerant, matching [`Self::load_from_file`]: a rule line
    /// that fails to parse is skipped along with its indented subtree, and a
    /// warning is logged rather than returned. Input in which every line fails
    /// to parse therefore yields an `Ok` database with no rules, not an error.
    ///
    /// The reader is drained until it reports end of input. A stream that ends
    /// early -- a reset socket, a truncated pipe -- is indistinguishable from a
    /// short magic database, so it loads successfully with only the rules that
    /// arrived. Callers that need completeness guarantees must enforce them on
    /// the stream before calling this method.
    ///
    /// # Security
    ///
    /// This constructor uses [`EvaluationConfig::default()`], which leaves
    /// `timeout_ms` unset. See the security note on
    /// [`Self::with_builtin_rules`] and prefer
    /// [`Self::load_from_reader_with_config`] with an explicit timeout when
    /// processing untrusted input.
    ///
    /// Note that `timeout_ms` bounds rule *evaluation*, not this read. The
    /// reader is capped in size, but not in time: a reader that blocks or
    /// trickles bytes without reaching end of input stalls this call. Apply
    /// your own read timeout or deadline before passing in a stream you do
    /// not control.
    ///
    /// # Errors
    ///
    /// Returns [`LibmagicError::IoError`] if the reader fails, or
    /// [`LibmagicError::ParseError`] if the input is oversized, compiled
    /// `.mgc` data, or cannot be parsed as a text magic database.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use libmagic_rs::MagicDatabase;
    ///
    /// let rules = b"0 string INKMEM in-memory magic\n";
    /// let db = MagicDatabase::load_from_reader(rules.as_slice())?;
    /// let result = db.evaluate_buffer(b"INKMEM payload")?;
    /// assert!(result.description.contains("in-memory magic"));
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn load_from_reader<R: Read>(reader: R) -> Result<Self> {
        Self::load_from_reader_with_config(reader, EvaluationConfig::default())
    }

    /// Load text magic rules from a reader with custom evaluation config.
    ///
    /// See [`Self::load_from_reader`] for supported inputs, size limits, and
    /// source-path behavior.
    ///
    /// # Security
    ///
    /// For untrusted input, pass [`EvaluationConfig::performance()`] or a
    /// config with an explicit non-`None` `timeout_ms`.
    ///
    /// # Errors
    ///
    /// Returns an error if the config is invalid, the reader fails, or the
    /// input is oversized, compiled `.mgc` data, or cannot be parsed as a text
    /// magic database.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use libmagic_rs::{EvaluationConfig, MagicDatabase};
    ///
    /// let rules = b"0 string INKMEM in-memory magic\n";
    /// let config = EvaluationConfig::performance();
    /// let db = MagicDatabase::load_from_reader_with_config(rules.as_slice(), config)?;
    /// let result = db.evaluate_buffer(b"INKMEM payload")?;
    /// assert!(result.description.contains("in-memory magic"));
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn load_from_reader_with_config<R: Read>(
        reader: R,
        config: EvaluationConfig,
    ) -> Result<Self> {
        config.validate()?;
        let parsed = parser::load_magic_reader(reader).map_err(Self::map_parse_error)?;
        Ok(Self::from_parsed(parsed, config, None))
    }

    fn map_parse_error(error: ParseError) -> LibmagicError {
        match error {
            ParseError::IoError(io_error) => LibmagicError::IoError(io_error),
            other => LibmagicError::ParseError(other),
        }
    }

    fn from_parsed(
        parsed: parser::ParsedMagic,
        config: EvaluationConfig,
        source_path: Option<PathBuf>,
    ) -> Self {
        let parser::ParsedMagic {
            mut rules,
            name_table,
        } = parsed;
        // Sort only the TOP-LEVEL rules by strength, mirroring libmagic's
        // `apprentice_sort` (which orders whole magic entries by their first
        // line's strength and never reorders continuation lines). Child rules
        // and `name`-block subroutine bodies stay in file order: they are
        // continuation-level rules, and their order is load-bearing for
        // `default`/`clear` firing and for multi-fragment descriptions that
        // must render in source order (e.g. the `gzip-info` subroutine's
        // "last modified, max compression, from Unix"). Strength-sorting them
        // reorders a comparison-bearing sibling ahead of a low-strength
        // `default`, wrongly suppressing the `default` message. See the
        // non-recursive contract note on `sort_rules_by_strength`.
        crate::evaluator::strength::sort_rules_by_strength(&mut rules);

        let root_rules: std::sync::Arc<[MagicRule]> =
            std::sync::Arc::from(rules.into_boxed_slice());
        Self {
            name_table: std::sync::Arc::new(name_table),
            root_rules,
            config,
            source_path,
            mime_mapper: mime::MimeMapper::new(),
        }
    }

    /// Evaluate magic rules against a file
    ///
    /// # Arguments
    ///
    /// * `path` - Path to the file to evaluate
    ///
    /// # Errors
    ///
    /// Returns `LibmagicError::IoError` if the file cannot be accessed.
    /// Returns `LibmagicError::EvaluationError` if rule evaluation fails.
    ///
    /// # Security
    ///
    /// This method has a time-of-check/time-of-use (TOCTOU) window between
    /// resolving the path and memory-mapping the file
    /// ([CWE-367](https://cwe.mitre.org/data/definitions/367.html)).
    /// Internally, `evaluate_file` first calls `std::fs::metadata(path)` to
    /// detect the empty-file case, then opens and memory-maps the file via
    /// [`io::FileBuffer::new`], which itself re-validates file metadata
    /// (regular file, size bounds) before calling `create_memory_mapping`.
    /// Between these validation steps and the final `mmap` call, the path
    /// may be swapped (for example, via a symlink replacement or rename)
    /// by another process. The content that gets mapped may therefore
    /// differ from the file that passed validation.
    ///
    /// The I/O layer mitigates the common shapes of this attack by
    /// canonicalizing the path and rejecting special file types, and the
    /// mapping itself is read-only, so a successful exploit cannot corrupt
    /// the victim file. The residual risk is that `evaluate_file` may
    /// classify a different file than the caller intended.
    ///
    /// **For adversarial or untrusted environments, prefer
    /// [`MagicDatabase::evaluate_buffer`]**: load the bytes yourself using
    /// whatever resource-bounded, TOCTOU-aware I/O strategy your
    /// application requires (e.g., `openat` with `O_NOFOLLOW`, holding an
    /// open file descriptor across validation and read), then pass the
    /// in-memory slice directly to `evaluate_buffer`. See
    /// [the security assurance case](https://evilbit-labs.github.io/libmagic-rs/security-assurance.html)
    /// for the residual-risk discussion.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use libmagic_rs::MagicDatabase;
    ///
    /// let db = MagicDatabase::load_from_file("magic.db")?;
    /// let result = db.evaluate_file("sample.bin")?;
    /// println!("File type: {}", result.description);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn evaluate_file<P: AsRef<Path>>(&self, path: P) -> Result<EvaluationResult> {
        use crate::io::FileBuffer;
        use std::fs;
        use std::time::Instant;

        let path = path.as_ref();

        // Check if file is empty - if so, evaluate as empty buffer
        // This allows empty files to be processed like any other file
        let file_metadata = fs::metadata(path)?;
        let file_size = file_metadata.len();

        if file_size == 0 {
            // Empty file - evaluate as empty buffer but preserve file metadata
            let mut result = self.evaluate_buffer_internal(b"", Instant::now())?;
            result.metadata.file_size = 0;
            result.metadata.magic_file.clone_from(&self.source_path);
            return Ok(result);
        }

        // Load the file into memory. Reuse the metadata we just read instead
        // of having FileBuffer::new call canonicalize+metadata again.
        let file_buffer = FileBuffer::from_path_and_metadata(path, &file_metadata)?;
        let buffer = file_buffer.as_slice();

        // Route the evaluation through `evaluate_buffer_internal` so the
        // rule environment (name table + root rules) is attached to the
        // context identically for in-memory and on-disk paths.
        // The timeout budget and the reported evaluation time start here,
        // after the file is loaded, so both passes share one origin.
        let mut result = self.evaluate_buffer_internal(buffer, Instant::now())?;
        result.metadata.file_size = file_size;
        Ok(result)
    }

    /// Evaluate magic rules against an in-memory buffer
    ///
    /// This method evaluates a byte buffer directly without reading from disk,
    /// which is useful for stdin input or pre-loaded data.
    ///
    /// # Arguments
    ///
    /// * `buffer` - Byte buffer to evaluate
    ///
    /// # Errors
    ///
    /// Returns `LibmagicError::EvaluationError` if rule evaluation fails.
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use libmagic_rs::MagicDatabase;
    ///
    /// let db = MagicDatabase::load_from_file("/usr/share/misc/magic")?;
    /// let buffer = b"test data";
    /// let result = db.evaluate_buffer(buffer)?;
    /// println!("Buffer type: {}", result.description);
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn evaluate_buffer(&self, buffer: &[u8]) -> Result<EvaluationResult> {
        use std::time::Instant;
        self.evaluate_buffer_internal(buffer, Instant::now())
    }

    /// Internal buffer evaluation with externally provided start time
    fn evaluate_buffer_internal(
        &self,
        buffer: &[u8],
        start_time: std::time::Instant,
    ) -> Result<EvaluationResult> {
        use crate::evaluator::test_type::{PassMode, TopLevelPass};
        use crate::evaluator::{
            EvaluationContext, RuleEnvironment, evaluate_rules, has_message_bearing_match,
        };
        use crate::output::ascmagic::{TextEncoding, classify, text_pass_buffer, text_window};

        let file_size = buffer.len() as u64;

        // Validate config once at the entry point to match the previous
        // behavior of `evaluate_rules_with_config`.
        self.config.validate()?;

        // GNU `file` never consults magic for an empty or one-byte file
        // (`funcs.c::file_buffer`).
        let fixed = match buffer.len() {
            0 => Some(("", TextEncoding::Empty)),
            1 => Some((VERY_SHORT_FILE, TextEncoding::Data)),
            _ => None,
        };
        // Reset the thread-local regex compile cache so it is bounded to
        // the lifetime of a single top-level evaluation call, including
        // one that never consults a rule.
        crate::evaluator::types::regex::reset_regex_cache();

        if let Some((rendered, class)) = fixed {
            let result =
                self.build_result(Vec::new(), rendered, class, None, file_size, start_time);
            // No rule was consulted on this path.
            return Ok(EvaluationResult {
                metadata: EvaluationMetadata {
                    rules_evaluated: 0,
                    ..result.metadata
                },
                ..result
            });
        }

        let env = std::sync::Arc::new(RuleEnvironment {
            name_table: std::sync::Arc::clone(&self.name_table),
            root_rules: std::sync::Arc::clone(&self.root_rules),
        });

        // Two passes, as `file_buffer` -> `file_softmagic(BINTEST)` then
        // `file_ascmagic` -> `file_softmagic(TEXTTEST)` (GOTCHAS S13.7).
        // A text buffer gets the text pass only when the binary pass
        // printed nothing, unless `stop_at_first_match` is off (`file -k`,
        // which keeps going); the text pass always ends with `, <class>`.
        // `file_buffer`'s `looks_text` hint is taken before trailing NULs
        // are trimmed; `file_ascmagic` classifies and runs the text pass over
        // the trimmed, 64 KiB-capped window, and gives up on a trimmed read
        // of at most one byte (`file_ascmagic_with_encoding`).
        let window = text_window(buffer);
        let buffer_is_text = classify(window.hint).is_text();
        let class = if window.scan.len() <= 1 {
            TextEncoding::Data
        } else {
            classify(window.scan)
        };
        let bin_pass = TopLevelPass {
            mode: PassMode::Bin,
            buffer_is_text,
        };
        let mut context = EvaluationContext::new(self.config.clone())
            .with_rule_env(std::sync::Arc::clone(&env))
            .with_top_level_pass(Some(bin_pass));
        let mut matches = evaluate_rules(&self.root_rules, buffer, &mut context)?;

        let binary_pass_printed = has_message_bearing_match(&matches, 0);
        if !class.is_text() || (self.config.stop_at_first_match && binary_pass_printed) {
            let rendered = Self::concatenate_messages(&matches);
            return Ok(self.build_result(matches, &rendered, class, None, file_size, start_time));
        }

        // One timeout budget across both passes: `evaluate_rules` starts
        // its own clock per call, so pass 2 gets only what pass 1 left.
        let remaining = self.remaining_timeout_ms(start_time)?;
        let text_pass = TopLevelPass {
            mode: PassMode::Text,
            buffer_is_text,
        };
        let mut context = EvaluationContext::new(self.config.clone().with_timeout_ms(remaining))
            .with_rule_env(env)
            .with_top_level_pass(Some(text_pass));
        let text_buffer = text_pass_buffer(window.scan, class);
        let text_matches = evaluate_rules(&self.root_rules, &text_buffer, &mut context)
            .map_err(|e| self.with_configured_timeout(e))?;
        matches.extend(text_matches);

        let rendered = Self::concatenate_messages(&matches);
        Ok(self.build_result(
            matches,
            &rendered,
            class,
            Some(window.scan),
            file_size,
            start_time,
        ))
    }

    /// The timeout left for a second pass, measured from `start_time`,
    /// the moment evaluation began (file loading is not charged to it).
    ///
    /// `None` when no timeout is configured; `Timeout` when the budget is
    /// already spent.
    fn remaining_timeout_ms(&self, start_time: std::time::Instant) -> Result<Option<u64>> {
        let Some(timeout_ms) = self.config.timeout_ms else {
            return Ok(None);
        };
        let elapsed = u64::try_from(start_time.elapsed().as_millis()).unwrap_or(u64::MAX);
        match timeout_ms.checked_sub(elapsed) {
            Some(left) if left > 0 => Ok(Some(left)),
            _ => Err(LibmagicError::Timeout { timeout_ms }),
        }
    }

    /// Relabel a `Timeout` raised by pass 2 with the configured budget,
    /// not the remainder that pass was run with.
    fn with_configured_timeout(&self, error: LibmagicError) -> LibmagicError {
        match error {
            LibmagicError::Timeout { timeout_ms } => LibmagicError::Timeout {
                timeout_ms: self.config.timeout_ms.unwrap_or(timeout_ms),
            },
            other => other,
        }
    }

    /// Build an `EvaluationResult`.
    ///
    /// `rendered` is the description text so far (concatenated rule text,
    /// possibly empty) and `class` the text/data classification that
    /// replaces it when it is blank (GOTCHAS S13.3). With `text` set the
    /// text pass ran (over the UTF-8 widening of that window,
    /// `text_pass_buffer`): the description gets the `, <class>` tail and
    /// the qualifiers scanned over the window itself (GOTCHAS S13.7). The MIME
    /// type comes from the rule text before the tail, since `MimeMapper`
    /// picks the longest keyword (`HTML document, ASCII text` would map to
    /// `text/plain`), then from the class.
    fn build_result(
        &self,
        matches: Vec<evaluator::RuleMatch>,
        rendered: &str,
        class: crate::output::ascmagic::TextEncoding,
        text: Option<&[u8]>,
        file_size: u64,
        start_time: std::time::Instant,
    ) -> EvaluationResult {
        use crate::evaluator::is_message_bearing;
        use crate::output::ascmagic::{append_text_class, text_qualifiers};

        let has_rule_text = !rendered.trim().is_empty();
        let rule_text = if has_rule_text { rendered } else { "" };
        let description = match text {
            Some(scan) => append_text_class(rule_text, class.label(), &text_qualifiers(scan)),
            None if has_rule_text => rendered.to_string(),
            None => class.label().to_string(),
        };

        // Confidence comes from the first message-bearing match; a
        // fallback-only description carries none.
        let confidence = if has_rule_text {
            matches
                .iter()
                .find(|m| is_message_bearing(&m.message))
                .map_or(0.0, |m| m.confidence)
        } else {
            0.0
        };

        let mime_type = if self.config.enable_mime_types {
            let primary = if has_rule_text {
                rendered
            } else {
                class.label()
            };
            self.mime_mapper
                .get_mime_type(primary)
                .or_else(|| text.and_then(|_| self.mime_mapper.get_mime_type(class.label())))
                .map(String::from)
        } else {
            None
        };

        EvaluationResult {
            description,
            mime_type,
            confidence,
            matches,
            metadata: EvaluationMetadata {
                file_size,
                evaluation_time_ms: start_time.elapsed().as_secs_f64() * 1000.0,
                rules_evaluated: self.root_rules.len(),
                magic_file: self.source_path.clone(),
                timed_out: false,
            },
        }
    }

    /// Concatenate match messages following libmagic behavior
    ///
    /// Each match's `message` is first run through
    /// [`crate::output::format::format_magic_message`], which substitutes
    /// printf-style specifiers (`%lld`, `%02x`, `%s`, etc.) with the
    /// rule's read value. Matches that render to an empty string (a
    /// message-less gating rule -- see GOTCHAS S13.2 -- or a
    /// `default`/`indirect`/`offset`/`use` directive with no message)
    /// contribute nothing and are skipped entirely, so they cannot
    /// introduce a stray separating space between the descriptions on
    /// either side of them. The remaining rendered strings are joined
    /// with spaces, except when a rendered string starts with the
    /// backspace character (`\b`, U+0008) which suppresses both the
    /// separating space and the backspace itself (GOTCHAS.md S14.1).
    ///
    /// The backspace check runs on the *post-substitution* text so rules
    /// like `\b, version %s` compose correctly once the specifier has been
    /// rendered.
    fn concatenate_messages(matches: &[evaluator::RuleMatch]) -> String {
        use crate::output::format::format_magic_message;

        let capacity: usize = matches.iter().map(|m| m.message.len() + 1).sum();
        let mut result = String::with_capacity(capacity);
        for m in matches {
            let rendered = format_magic_message(&m.message, &m.value, &m.type_kind);
            if rendered.is_empty() {
                // No text to contribute -- skip so this match cannot
                // introduce a stray separating space.
                continue;
            }
            // GNU `file`'s no-separator convention: a description beginning
            // with a backspace suppresses both the separating space and the
            // marker itself (GOTCHAS.md S14.1). The marker most often reaches
            // us as the literal two-character sequence `\b` (backslash + 'b'),
            // because the message parser preserves description text verbatim --
            // matching GNU `file`, which keeps the desc literal and
            // special-cases a leading `\b` at print time (e.g. the msdos
            // `\b, for MS Windows` and Mach-O universal `\b]` rules). We also
            // accept a bare U+0008 for programmatically-constructed messages.
            let without_marker = crate::evaluator::strip_no_separator_marker(&rendered);
            if let Some(rest) = without_marker {
                result.push_str(rest);
            } else if !result.is_empty() {
                result.push(' ');
                result.push_str(&rendered);
            } else {
                result.push_str(&rendered);
            }
        }
        result
    }

    /// Returns the evaluation configuration used by this database.
    ///
    /// This provides read-only access to the evaluation configuration for
    /// callers that need to inspect resource limits or evaluation options.
    #[must_use]
    pub fn config(&self) -> &EvaluationConfig {
        &self.config
    }

    /// Returns the path from which magic rules were loaded.
    ///
    /// This method returns the source path that was used to load the magic rules
    /// into this database. It is useful for debugging, logging, and tracking the
    /// origin of magic rules.
    ///
    /// # Returns
    ///
    /// - `Some(&Path)` - If the database was loaded from a file or directory using
    ///   [`load_from_file()`](Self::load_from_file)
    /// - `None` - If the database was constructed programmatically or the source
    ///   path was not recorded
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use libmagic_rs::MagicDatabase;
    ///
    /// let db = MagicDatabase::load_from_file("/usr/share/misc/magic")?;
    /// if let Some(path) = db.source_path() {
    ///     println!("Rules loaded from: {}", path.display());
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    #[must_use]
    pub fn source_path(&self) -> Option<&Path> {
        self.source_path.as_deref()
    }
}

/// Metadata about the evaluation process
///
/// Contains diagnostic information about how the evaluation was performed,
/// including performance metrics and statistics about rule processing.
///
/// # Examples
///
/// ```
/// use libmagic_rs::EvaluationMetadata;
/// use std::path::PathBuf;
///
/// let metadata = EvaluationMetadata::new(
///     8192,
///     2.5,
///     42,
///     Some(PathBuf::from("/usr/share/misc/magic")),
///     false,
/// );
///
/// assert_eq!(metadata.file_size, 8192);
/// assert!(!metadata.timed_out);
/// ```
#[derive(Debug, Clone, Serialize)]
#[non_exhaustive]
pub struct EvaluationMetadata {
    /// Size of the analyzed file or buffer in bytes
    pub file_size: u64,
    /// Time taken to evaluate rules in milliseconds
    pub evaluation_time_ms: f64,
    /// Number of top-level rules that were evaluated
    pub rules_evaluated: usize,
    /// Path to the magic file used, or `None` for built-in, byte-loaded, or
    /// reader-loaded rules
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub magic_file: Option<PathBuf>,
    /// Whether evaluation was stopped due to timeout
    pub timed_out: bool,
}

impl Default for EvaluationMetadata {
    fn default() -> Self {
        Self {
            file_size: 0,
            evaluation_time_ms: 0.0,
            rules_evaluated: 0,
            magic_file: None,
            timed_out: false,
        }
    }
}

/// Result of magic rule evaluation
///
/// Contains the file type description, optional MIME type, confidence score,
/// individual match details, and evaluation metadata.
///
/// # Relationship to [`crate::output::EvaluationResult`]
///
/// This is the **library-facing** result type returned by [`MagicDatabase::evaluate_file`]
/// and [`MagicDatabase::evaluate_buffer`].
/// It carries a rolled-up description, MIME type, and confidence score along with
/// raw [`evaluator::RuleMatch`] values. It intentionally does **not** carry the
/// analyzed filename or a surface-level error string, because those are caller
/// concerns (a caller may evaluate an in-memory buffer that has no filename).
///
/// The parallel type [`crate::output::EvaluationResult`] is the **output-facing**
/// result used by the CLI and JSON/text formatters. It adds `filename` and
/// `error`, carries enriched [`crate::output::MatchResult`] values (with
/// extracted tags), and uses `u32` counters in its metadata to match the JSON
/// output schema.
///
/// The two types are **intentionally distinct** — do not try to unify them.
/// Convert library → output explicitly via
/// [`crate::output::EvaluationResult::from_library_result`], which is the single
/// named conversion point. Any drift between the two hierarchies should be
/// resolved there, not by back-channel field copying in call sites.
///
/// # Examples
///
/// ```
/// use libmagic_rs::{EvaluationResult, EvaluationMetadata};
///
/// let result = EvaluationResult::new(
///     "ELF 64-bit executable".to_string(),
///     Some("application/x-executable".to_string()),
///     0.9,
///     vec![],
///     EvaluationMetadata::default(),
/// );
///
/// assert_eq!(result.description, "ELF 64-bit executable");
/// assert!(result.confidence > 0.5);
/// ```
#[derive(Debug, Clone, Serialize)]
#[non_exhaustive]
pub struct EvaluationResult {
    /// Human-readable file type description
    ///
    /// This is the concatenated message from all matching rules,
    /// following libmagic behavior where hierarchical matches
    /// are joined with spaces (unless backspace character is used).
    pub description: String,
    /// Optional MIME type for the detected file type
    ///
    /// Only populated when `enable_mime_types` is set in the configuration.
    /// Omitted from the serialized form when unset (rather than emitted
    /// as `"mime_type": null`) so downstream JSON consumers can treat
    /// presence as the "MIME type is known" indicator.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub mime_type: Option<String>,
    /// Confidence score (0.0 to 1.0)
    ///
    /// Based on the depth of the match in the rule hierarchy.
    /// Deeper matches indicate more specific identification.
    pub confidence: f64,
    /// Individual match results from rule evaluation
    ///
    /// Contains details about each rule that matched, including
    /// offset, matched value, and per-match confidence.
    pub matches: Vec<evaluator::RuleMatch>,
    /// Metadata about the evaluation process
    pub metadata: EvaluationMetadata,
}

impl EvaluationResult {
    /// Construct a new library-side `EvaluationResult`.
    ///
    /// This is the outbound type returned by [`MagicDatabase::evaluate_file`]
    /// and [`MagicDatabase::evaluate_buffer`]. For the output-facing
    /// type used by the CLI and JSON/text formatters, see
    /// [`crate::output::EvaluationResult::from_library_result`].
    #[must_use]
    pub fn new(
        description: String,
        mime_type: Option<String>,
        confidence: f64,
        matches: Vec<evaluator::RuleMatch>,
        metadata: EvaluationMetadata,
    ) -> Self {
        Self {
            description,
            mime_type,
            confidence,
            matches,
            metadata,
        }
    }
}

impl EvaluationMetadata {
    /// Construct a new library-side `EvaluationMetadata` from the four
    /// always-set fields. `magic_file` and `timed_out` default to `None`
    /// / `false`; use struct-update syntax with [`EvaluationMetadata::default()`]
    /// to set them explicitly.
    #[must_use]
    pub fn new(
        file_size: u64,
        evaluation_time_ms: f64,
        rules_evaluated: usize,
        magic_file: Option<PathBuf>,
        timed_out: bool,
    ) -> Self {
        Self {
            file_size,
            evaluation_time_ms,
            rules_evaluated,
            magic_file,
            timed_out,
        }
    }
}

#[cfg(test)]
mod tests;