mago_database/

file.rs

use std::borrow::Cow;
use std::hash::DefaultHasher;
use std::hash::Hash;
use std::hash::Hasher;
use std::path::Path;
use std::path::PathBuf;

use crate::error::DatabaseError;
use crate::utils::read_file;

/// A stable, unique identifier for a file.
///
/// This ID is generated by hashing the file's logical name, ensuring it remains
/// consistent across application runs and is unaffected by content modifications.
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[repr(transparent)]
pub struct FileId(u64);

/// Distinguishes between the origins of source files.
#[derive(Debug, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[repr(u8)]
pub enum FileType {
    /// The file is part of the primary project source code.
    /// These files typically reside on the filesystem and are actively developed.
    Host,

    /// The file belongs to a third-party dependency (e.g., a Composer package).
    /// These files exist on the filesystem within the project (e.g., in `vendor/`)
    /// but are not considered part of the primary source code.
    Vendored,

    /// The file represents a built-in language construct (e.g., a core PHP function or class).
    /// These "files" do not exist on the filesystem and their content is typically
    /// provided as pre-defined stubs for analysis.
    Builtin,

    /// The file is a user-provided patch that overrides type information for vendored or
    /// built-in code with corrected PHPDoc / type declarations.
    /// Like vendored files, patches are not actively analyzed, linted, or formatted,
    /// but their metadata takes precedence over both vendored and built-in definitions.
    Patch,

    /// An in-memory source contributed by an external analyzer plugin during initialization.
    /// External files are scanned for symbols, but are never analyzed, linted, formatted, or fixed.
    External,
}

/// A file that's either stored on the host system's file system or in the vendored file system.
///
/// This struct encapsulates all the necessary information about a file, including its content,
/// location, and metadata for change detection.
#[derive(Debug, Eq, PartialEq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct File {
    /// A stable, unique identifier for the file, generated from its logical name.
    /// This ID persists across application runs and content modifications.
    pub id: FileId,

    /// The logical name of the file, typically the path relative to the root of the project.
    pub name: Cow<'static, [u8]>,

    /// The absolute path of the file on the host's filesystem, if it exists there.
    /// This will be `None` for vendored files that don't have a physical counterpart.
    pub path: Option<PathBuf>,

    /// The type of the file, indicating its origin.
    pub file_type: FileType,

    /// The contents of the file, if available.
    pub contents: Cow<'static, [u8]>,

    /// The size of the file's contents in bytes.
    pub size: u32,

    /// A vector containing the starting byte offsets of each line in `contents`.
    /// The first line always starts at offset 0. This is useful for quickly
    /// navigating to a specific line number without scanning the whole file.
    pub lines: Vec<u32>,
}

pub trait HasFileId {
    /// Returns the unique identifier of the file.
    fn file_id(&self) -> FileId;
}

impl File {
    /// Creates a new `File` instance from its name, type, path, and contents.
    ///
    /// It automatically calculates the size, and line start offsets.
    #[inline]
    #[must_use]
    pub fn new(
        name: Cow<'static, [u8]>,
        file_type: FileType,
        path: Option<PathBuf>,
        contents: Cow<'static, [u8]>,
    ) -> Self {
        let id = FileId::new(&name);
        let size = contents.len() as u32;
        let lines = line_starts(contents.as_ref());

        Self { id, name, path, file_type, contents, size, lines }
    }

    /// Creates a new `File` instance by reading its contents from the filesystem.
    ///
    /// This is the primary factory function for creating a `File` from a disk source.
    /// It handles determining the file's logical name relative to the workspace,
    /// reading its contents, and robustly handling non-UTF-8 text via lossy conversion.
    ///
    /// # Arguments
    ///
    /// * `workspace`: The root directory of the project, used to calculate the logical name.
    /// * `path`: The absolute path to the file to read from disk.
    /// * `file_type`: The [`FileType`] to assign to the created file.
    ///
    /// # Errors
    ///
    /// Returns a [`DatabaseError::IOError`] if the file cannot be read from the disk.
    #[inline(always)]
    pub fn read(workspace: &Path, path: &Path, file_type: FileType) -> Result<Self, DatabaseError> {
        read_file(workspace, path, file_type)
    }

    /// Creates an ephemeral, in-memory `File` from a name and content.
    ///
    /// This is a convenience method for situations like testing or formatting where
    /// a full file context (e.g., a real path) is not required. It defaults to
    /// `FileType::Host` and a `path` of `None`.
    #[inline]
    #[must_use]
    pub fn ephemeral(name: Cow<'static, [u8]>, contents: Cow<'static, [u8]>) -> Self {
        Self::new(name, FileType::Host, None, contents)
    }

    /// Retrieve the line number for the given byte offset.
    ///
    /// # Parameters
    ///
    /// - `offset`: The byte offset to retrieve the line number for.
    ///
    /// # Returns
    ///
    /// The line number for the given byte offset (0-based index).
    #[inline]
    #[must_use]
    pub fn line_number(&self, offset: u32) -> u32 {
        self.lines.binary_search(&offset).unwrap_or_else(|next_line| next_line - 1) as u32
    }

    /// Retrieve the byte offset for the start of the given line.
    ///
    /// # Parameters
    ///
    /// - `line`: The line number to retrieve the start offset for.
    ///
    /// # Returns
    ///
    /// The byte offset for the start of the given line (0-based index).
    #[inline]
    #[must_use]
    pub fn get_line_start_offset(&self, line: u32) -> Option<u32> {
        self.lines.get(line as usize).copied()
    }

    /// Retrieve the byte offset for the end of the given line.
    ///
    /// # Parameters
    ///
    /// - `line`: The line number to retrieve the end offset for.
    ///
    /// # Returns
    ///
    /// The byte offset for the end of the given line (0-based index).
    #[inline]
    #[must_use]
    pub fn get_line_end_offset(&self, line: u32) -> Option<u32> {
        match self.lines.get(line as usize + 1) {
            Some(&end) => Some(end - 1),
            None if line as usize == self.lines.len() - 1 => Some(self.size),
            _ => None,
        }
    }

    /// Retrieve the column number for the given byte offset.
    ///
    /// # Parameters
    ///
    /// - `offset`: The byte offset to retrieve the column number for.
    ///
    /// # Returns
    ///
    /// The column number for the given byte offset (0-based index).
    #[inline]
    #[must_use]
    pub fn column_number(&self, offset: u32) -> u32 {
        let line = self.line_number(offset) as usize;

        offset - self.lines[line]
    }
}

impl FileType {
    /// Returns `true` if the file is a host file, meaning it is part of the project's source code.
    #[inline]
    #[must_use]
    pub const fn is_host(self) -> bool {
        matches!(self, FileType::Host)
    }

    /// Returns `true` if the file is a vendored file, meaning it comes from an external library or dependency.
    #[inline]
    #[must_use]
    pub const fn is_vendored(self) -> bool {
        matches!(self, FileType::Vendored)
    }

    /// Returns `true` if the file is a built-in file, meaning it represents a core language construct.
    #[inline]
    #[must_use]
    pub const fn is_builtin(self) -> bool {
        matches!(self, FileType::Builtin)
    }

    /// Returns `true` if the file is a patch, meaning it overrides type information for vendored or built-in code.
    #[must_use]
    pub const fn is_patch(self) -> bool {
        matches!(self, FileType::Patch)
    }

    /// Returns `true` if the file is an in-memory source contributed by an external analyzer plugin.
    #[must_use]
    pub const fn is_external(self) -> bool {
        matches!(self, FileType::External)
    }
}

impl FileId {
    #[inline]
    #[must_use]
    pub fn new(logical_name: &[u8]) -> Self {
        let mut hasher = DefaultHasher::new();
        logical_name.hash(&mut hasher);
        Self(hasher.finish())
    }

    #[inline]
    #[must_use]
    pub const fn zero() -> Self {
        Self(0)
    }

    #[inline]
    #[must_use]
    pub const fn is_zero(self) -> bool {
        self.0 == 0
    }

    #[inline]
    #[must_use]
    pub fn as_u64(self) -> u64 {
        self.0
    }
}

impl HasFileId for File {
    #[inline]
    fn file_id(&self) -> FileId {
        self.id
    }
}

impl std::fmt::Display for FileId {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// Returns a vec over the starting byte offsets of each line in `source`.
#[inline]
pub(crate) fn line_starts(source: &[u8]) -> Vec<u32> {
    // Heuristic: On the test corpus, the mean length is about 30 bytes, the median is 23.
    // Since the whole vec will be small, we prefer slight over-allocation to avoid re-allocations
    // in the common case
    const LINE_WIDTH_HEURISTIC: usize = 20;

    // Pre-allocate to avoid calling `realloc` thousands of times per file.
    let mut lines = Vec::with_capacity(source.len() / LINE_WIDTH_HEURISTIC);
    lines.push(0);

    // Detect line ending style from the first \r or \n.  Real files use one
    // convention throughout, so we never need to handle mixed \r\n / bare \r.
    match memchr::memchr2(b'\r', b'\n', source) {
        // No line endings: single-line file, nothing more to push.
        None => {}
        // Old Mac (\r only): first line-ending char is a bare \r.
        Some(cr) if source[cr] == b'\r' && source.get(cr + 1) != Some(&b'\n') => {
            for pos in memchr::memchr_iter(b'\r', source) {
                lines.push((pos + 1) as u32);
            }
        }
        // Unix (\n only) or Windows (\r\n): \n marks every line start.
        _ => {
            for pos in memchr::memchr_iter(b'\n', source) {
                lines.push((pos + 1) as u32);
            }
        }
    }

    lines
}