vpxtool 0.33.2

use chrono::{DateTime, Utc};
use jwalk::WalkDir;
use log::info;
use rayon::prelude::*;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use std::collections::{BTreeMap, HashMap, HashSet};
use std::fmt::Debug;
use std::fs::Metadata;
use std::io::{BufReader, BufWriter, Read};
use std::sync::LazyLock;
use std::time::SystemTime;
use std::{
    ffi::OsStr,
    fs::{self, File},
    io,
    path::{Path, PathBuf},
};
use vpin::vpx;
use vpin::vpx::jsonmodel::json_to_info;
use vpin::vpx::tableinfo::TableInfo;

use vpx::gamedata::GameData;

use crate::atomicwrite::atomic_write;

pub const DEFAULT_INDEX_FILE_NAME: &str = "vpxtool_index.json";

// Compile regexes once to avoid per-table startup cost while indexing large collections.
static LINE_WITH_CGAMENAME_REGEX: LazyLock<regex::Regex> = LazyLock::new(|| {
    regex::Regex::new(r#"(?i)cgamename\s*=\s*\"([^"\\]*(?:\\.[^"\\]*)*)\""#).unwrap()
});
static LINE_WITH_DOT_GAMENAME_REGEX: LazyLock<regex::Regex> = LazyLock::new(|| {
    regex::Regex::new(r#"(?i)\.gamename\s*=\s*\"([^"\\]*(?:\\.[^"\\]*)*)\""#).unwrap()
});
static LOADVPM_SUB_REGEX: LazyLock<regex::Regex> =
    LazyLock::new(|| regex::Regex::new(r#"sub\s*loadvpm"#).unwrap());

// Pulls a `Const <id> = "..."` declaration. `(?m)` so `^` matches the start
// of each line (constants always appear at top-level in VBS).
static CONST_DECL_REGEX: LazyLock<regex::Regex> = LazyLock::new(|| {
    regex::Regex::new(r#"(?im)^\s*Const\s+([A-Za-z_]\w*)\s*=\s*"([^"]*)""#).unwrap()
});

// Also catch plain `<id> = "..."` assignments (no `Const`), which scripts
// use after a `Dim <id>` declaration: John Wick, for instance, writes
// `Dim MyTable` then `MyTable = "JPsIT"` and reads
// `LoadValue(MyTable, "HighScore1")`. The line-anchored regex skips
// keyword-prefixed lines (`Const`, `Dim`, `Sub`, `If`, ...) because they
// either declare or call rather than bind a string literal.
static VAR_ASSIGN_REGEX: LazyLock<regex::Regex> =
    LazyLock::new(|| regex::Regex::new(r#"(?im)^\s*([A-Za-z_]\w*)\s*=\s*"([^"]*)"\s*$"#).unwrap());

// Matches `(Load|Save)Value(<arg>, "<score-key>")` for either the modern
// `HighScoreN` / `HighScoreNName` shape or the legacy EM `hiscore` / `hsa<N>`
// shape. Captures the section-key argument (an identifier or a quoted
// literal) so the dispatcher can try every distinct section name a script
// writes under, regardless of which storage variant it uses.
static VPREG_HIGHSCORE_CALL_REGEX: LazyLock<regex::Regex> = LazyLock::new(|| {
    regex::Regex::new(
        r#"(?i)(?:Load|Save)Value\s*\(?\s*([A-Za-z_]\w*|"[^"\r\n]+")\s*,\s*"(?:HighScore\d+(?:Name)?|hiscore|hsa\d+)""#,
    )
    .unwrap()
});

/// Introduced because we want full control over serialization
#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
pub struct IndexedTableInfo {
    pub table_name: Option<String>,
    pub author_name: Option<String>,
    //pub screenshot: Option<Vec<u8>>,
    pub table_blurb: Option<String>,
    pub table_rules: Option<String>,
    pub author_email: Option<String>,
    pub release_date: Option<String>,
    pub table_save_rev: Option<String>,
    pub table_version: Option<String>,
    pub author_website: Option<String>,
    pub table_save_date: Option<String>,
    pub table_description: Option<String>,
    // serialized in alphabetical key order for stable diffs; the VPX insertion order
    // (defined in "GameStg/CustomInfoTags") is not preserved by the source HashMap
    pub properties: BTreeMap<String, String>,
}
impl From<TableInfo> for IndexedTableInfo {
    fn from(table_info: TableInfo) -> Self {
        IndexedTableInfo {
            table_name: table_info.table_name,
            author_name: table_info.author_name,
            //screenshot: table_info.screenshot, // TODO we might want to write this to a file next to the table?
            table_blurb: table_info.table_blurb,
            table_rules: table_info.table_rules,
            author_email: table_info.author_email,
            release_date: table_info.release_date,
            table_save_rev: table_info.table_save_rev,
            table_version: table_info.table_version,
            author_website: table_info.author_website,
            table_save_date: table_info.table_save_date,
            table_description: table_info.table_description,
            properties: table_info.properties.into_iter().collect(),
        }
    }
}

pub struct PathWithMetadata {
    pub path: PathBuf,
    pub last_modified: SystemTime,
}

#[derive(Clone, Copy, PartialEq, Debug, Eq, Ord, PartialOrd)]
pub struct IsoSystemTime(SystemTime);
impl From<SystemTime> for IsoSystemTime {
    fn from(system_time: SystemTime) -> Self {
        IsoSystemTime(system_time)
    }
}
impl From<IsoSystemTime> for SystemTime {
    fn from(iso_system_time: IsoSystemTime) -> Self {
        iso_system_time.0
    }
}
impl Serialize for IsoSystemTime {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let now: DateTime<Utc> = self.0.into();
        now.to_rfc3339().serialize(serializer)
    }
}
impl<'de> Deserialize<'de> for IsoSystemTime {
    fn deserialize<D>(deserializer: D) -> Result<IsoSystemTime, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        let dt = DateTime::parse_from_rfc3339(&s).map_err(serde::de::Error::custom)?;
        Ok(IsoSystemTime(dt.into()))
    }
}

#[derive(Serialize, Deserialize, PartialEq, Debug, Clone)]
pub struct IndexedTable {
    pub path: PathBuf,
    pub table_info: IndexedTableInfo,
    pub game_name: Option<String>,
    pub b2s_path: Option<PathBuf>,
    /// The rom path, in the table folder or in the global pinmame roms folder
    rom_path: Option<PathBuf>,
    /// deprecated: only used for reading the old index format
    #[serde(skip_serializing_if = "Option::is_none")]
    local_rom_path: Option<PathBuf>,
    pub wheel_path: Option<PathBuf>,
    /// AltSound directory (audio replacement pack) found next to the vpx file.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub altsound_path: Option<PathBuf>,
    /// DMD colorization directory (Serum / VNI / legacy altcolor) found next to
    /// the vpx file.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub altcolor_path: Option<PathBuf>,
    /// PinUP Player video pack directory found next to the vpx file.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pup_pack_path: Option<PathBuf>,
    pub requires_pinmame: bool,
    pub last_modified: IsoSystemTime,
}

impl IndexedTable {
    pub fn rom_path(&self) -> Option<&PathBuf> {
        self.rom_path.as_ref().or(self.local_rom_path.as_ref())
    }
}

#[derive(Serialize, Deserialize, PartialEq, Debug)]
pub struct TablesIndex {
    tables: HashMap<PathBuf, IndexedTable>,
}

impl TablesIndex {
    pub(crate) fn empty() -> TablesIndex {
        TablesIndex {
            tables: HashMap::new(),
        }
    }

    pub fn len(&self) -> usize {
        self.tables.len()
    }

    pub fn is_empty(&self) -> bool {
        self.tables.is_empty()
    }

    pub(crate) fn insert(&mut self, table: IndexedTable) {
        self.tables.insert(table.path.clone(), table);
    }

    pub fn insert_all(&mut self, new_tables: Vec<IndexedTable>) {
        for table in new_tables {
            self.insert(table);
        }
    }

    pub fn merge(&mut self, other: TablesIndex) {
        self.tables.extend(other.tables);
    }

    pub fn tables(&self) -> Vec<IndexedTable> {
        self.tables.values().cloned().collect()
    }

    pub(crate) fn should_index(&self, path_with_metadata: &PathWithMetadata) -> bool {
        // if exists with different last modified or missing
        match self.tables.get(&path_with_metadata.path) {
            Some(existing) => {
                let existing_last_modified: SystemTime = existing.last_modified.into();
                existing_last_modified != path_with_metadata.last_modified
            }
            None => true,
        }
    }

    pub(crate) fn remove_missing(&mut self, paths: &[PathWithMetadata]) -> usize {
        // create a hashset with the paths
        let len = self.tables.len();
        let paths_set: HashSet<PathBuf> = paths.iter().map(|p| p.path.clone()).collect();
        self.tables.retain(|path, _| paths_set.contains(path));
        len - self.tables.len()
    }
}

/// We prefer keeping a flat index instead of an object
#[derive(Serialize, Deserialize, PartialEq, Debug)]
pub struct TablesIndexJson {
    tables: Vec<IndexedTable>,
}

impl From<TablesIndex> for TablesIndexJson {
    fn from(index: TablesIndex) -> Self {
        TablesIndexJson {
            tables: sort_tables(index.tables()),
        }
    }
}

impl From<&TablesIndex> for TablesIndexJson {
    fn from(table: &TablesIndex) -> Self {
        TablesIndexJson {
            tables: sort_tables(table.tables()),
        }
    }
}

fn sort_tables(mut tables: Vec<IndexedTable>) -> Vec<IndexedTable> {
    tables.sort_by(|a, b| {
        a.path
            .to_string_lossy()
            .to_lowercase()
            .cmp(&b.path.to_string_lossy().to_lowercase())
    });
    tables
}

/// Convert a platform-specific path to a normalized string using forward slashes.
fn to_normalized_path(path: &Path) -> String {
    path.to_string_lossy().replace('\\', "/")
}

/// Convert a normalized forward-slash path string back to a platform-specific `PathBuf`.
fn from_normalized_path(normalized: &str) -> PathBuf {
    #[cfg(windows)]
    {
        PathBuf::from(normalized.replace('/', "\\"))
    }
    #[cfg(not(windows))]
    {
        PathBuf::from(normalized)
    }
}

/// Try to make `path` relative to `base`, returning a forward-slash normalized string.
/// If `path` is not under `base`, returns the normalized absolute path instead.
/// `canonical_base` is the pre-canonicalized form of `base` (computed once by the caller).
/// The cheap `strip_prefix` on the original paths is tried first; only if that fails is
/// `path` itself canonicalized, to handle mapped-drive / UNC / symlink mismatches.
fn try_make_relative_normalized(path: &Path, base: &Path, canonical_base: Option<&Path>) -> String {
    // Fast path: no syscalls needed when the paths share a common prefix as-is.
    if let Ok(relative) = path.strip_prefix(base) {
        return to_normalized_path(relative);
    }
    // Slow path: canonicalize just this path and retry against the pre-canonicalized base.
    let canonical_path = path.canonicalize().ok();
    let path_to_check = canonical_path.as_deref().unwrap_or(path);
    let base_to_check = canonical_base.unwrap_or(base);
    if let Ok(relative) = path_to_check.strip_prefix(base_to_check) {
        to_normalized_path(relative)
    } else {
        to_normalized_path(path_to_check)
    }
}

/// Resolve a normalized path string back to an absolute `PathBuf`.
/// Relative paths are joined with `base`; absolute paths are used as-is.
fn resolve_normalized_path(normalized: &str, base: Option<&Path>) -> PathBuf {
    let path = from_normalized_path(normalized);
    if path.is_absolute() {
        path
    } else if let Some(base_path) = base {
        base_path.join(path)
    } else {
        path
    }
}

/// Returns all roms names lower case for the roms in the given folder
pub fn find_roms(rom_path: &Path) -> io::Result<HashMap<String, PathBuf>> {
    if !rom_path.exists() {
        return Ok(HashMap::new());
    }
    // TODO
    // TODO if there is an ini file for the table we might have to check locally for the rom
    //   currently only a standalone feature
    let mut roms = HashMap::new();
    // TODO is there a cleaner version like try_filter_map?
    let mut entries = fs::read_dir(rom_path)?;
    entries.try_for_each(|entry| {
        let dir_entry = entry?;
        let path = dir_entry.path();
        if path.is_file()
            && let Some("zip") = path.extension().and_then(OsStr::to_str)
        {
            let rom_name = path
                .file_stem()
                .unwrap()
                .to_str()
                .unwrap()
                .to_string()
                .to_lowercase();
            roms.insert(rom_name, path);
        }
        Ok::<(), io::Error>(())
    })?;
    Ok(roms)
}

pub fn find_vpx_files(
    recursive: bool,
    max_depth: Option<usize>,
    tables_path: &Path,
) -> io::Result<Vec<PathWithMetadata>> {
    let vpx_paths: Vec<PathBuf> = if recursive {
        // jwalk parallelises readdir calls across directories using rayon, so
        // all subdirectory reads (e.g. one per manufacturer folder) happen
        // concurrently rather than serially.
        let mut walk = WalkDir::new(tables_path).skip_hidden(false);
        if let Some(depth) = max_depth {
            walk = walk.max_depth(depth);
        }
        walk.process_read_dir(|_, _, _, entries| {
            // Drop .git and __MACOSX subdirectory entries before they are
            // enqueued for parallel reads, avoiding wasted network RPCs.
            entries.retain(|entry| match entry {
                Ok(e) if e.file_type().is_dir() => {
                    !matches!(e.file_name().to_str(), Some(".git" | "__MACOSX"))
                }
                _ => true,
            });
        })
        .into_iter()
        .filter_map(|entry| {
            let entry = match entry {
                Ok(e) => e,
                Err(e) => return Some(Err(io::Error::from(e))),
            };
            if !entry.file_type().is_file() {
                return None;
            }
            if !matches!(
                entry.path().extension().and_then(OsStr::to_str),
                Some("vpx")
            ) {
                return None;
            }
            Some(Ok(entry.path()))
        })
        .collect::<io::Result<Vec<_>>>()?
    } else {
        let mut paths = Vec::new();
        for entry in fs::read_dir(tables_path)? {
            let dir_entry = entry?;
            if dir_entry.file_type()?.is_file() {
                let path = dir_entry.path();
                if matches!(path.extension().and_then(OsStr::to_str), Some("vpx")) {
                    paths.push(path);
                }
            }
        }
        paths
    };
    // Fetch mtimes in parallel. On a NAS each stat is a network RPC, so a
    // serial pass over many tables dominates startup time.
    vpx_paths
        .par_iter()
        .map(|path| {
            let last_modified = last_modified(path)?;
            Ok(PathWithMetadata {
                path: path.clone(),
                last_modified,
            })
        })
        .collect()
}

pub trait Progress {
    fn set_length(&self, len: u64);
    fn set_position(&self, i: u64);
    fn finish_and_clear(&self);
}

pub struct VoidProgress;
impl Progress for VoidProgress {
    fn set_length(&self, _len: u64) {}
    fn set_position(&self, _i: u64) {}
    fn finish_and_clear(&self) {}
}

pub enum IndexError {
    FolderDoesNotExist(PathBuf),
    IoError(io::Error),
}
impl Debug for IndexError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            IndexError::FolderDoesNotExist(path) => {
                write!(f, "Folder does not exist: {}", path.display())
            }
            IndexError::IoError(e) => write!(f, "IO error: {e}"),
        }
    }
}
impl From<IndexError> for io::Error {
    fn from(e: IndexError) -> io::Error {
        io::Error::other(format!("{e:?}"))
    }
}

impl From<io::Error> for IndexError {
    fn from(e: io::Error) -> Self {
        IndexError::IoError(e)
    }
}

/// Indexes all vpx files in the given folder and writes the index to a file.
/// Returns the index.
/// If the index file already exists, it will be read and updated.
/// If the index file does not exist, it will be created.
///
/// Arguments:
/// * `recursive`: if true, all subdirectories will be searched for vpx files.
/// * `tables_folder`: the folder to search for vpx files.
/// * `tables_index_path`: the path to the index file.
/// * `global_pinmame_path`: the path to the global pinmame folder. Eg ~/.pinmame/roms on *nix systems.
/// * `configured_pinmame_path`: the path to the local pinmame folder configured in the vpinball config.
/// * `progress`: lister for progress updates.
/// * `force_reindex`: a list of vpx files to reindex, even if they are not modified.
#[allow(clippy::too_many_arguments)]
pub fn index_folder(
    recursive: bool,
    max_depth: Option<usize>,
    tables_folder: &Path,
    tables_index_path: &Path,
    global_pinmame_path: Option<&Path>,
    configured_pinmame_path: Option<&Path>,
    progress: &impl Progress,
    force_reindex: Vec<PathBuf>,
    force_all: bool,
) -> Result<TablesIndex, IndexError> {
    info!("Indexing {}", tables_folder.display());

    if !tables_folder.exists() {
        return Err(IndexError::FolderDoesNotExist(tables_folder.to_path_buf()));
    }

    // When --force is set we discard the cached index so every table is re-
    // indexed from scratch; this is the upgrade path for new fields like the
    // altsound / altcolor / pup-pack flags added in newer vpxtool versions.
    let existing_index = if force_all {
        info!("  Forcing full re-index; ignoring any cached entries");
        None
    } else {
        read_index_json(tables_index_path, Some(tables_folder))?
    };
    if let Some(index) = &existing_index {
        info!(
            "  Found existing index with {} tables at {}",
            index.tables.len(),
            tables_index_path.display()
        );
    }
    let mut index = existing_index.unwrap_or(TablesIndex::empty());

    let vpx_files = find_vpx_files(recursive, max_depth, tables_folder)?;
    info!("  Found {} tables", vpx_files.len());
    // remove files that are missing
    let removed_len = index.remove_missing(&vpx_files);
    info!("  {removed_len} missing tables have been removed");

    let tables_with_missing_rom: HashSet<PathBuf> = index
        .tables()
        .par_iter()
        .filter_map(|table| {
            table
                .rom_path()
                .filter(|rom_path| !rom_path.exists())
                .map(|_| table.path.clone())
        })
        .collect();
    info!(
        "  {} tables will be re-indexed because their rom is missing",
        tables_with_missing_rom.len()
    );

    // find files that are missing or have been modified
    let mut vpx_files_to_index = Vec::new();
    for vpx_file in vpx_files {
        if tables_with_missing_rom.contains(&vpx_file.path)
            || force_reindex.contains(&vpx_file.path)
            || index.should_index(&vpx_file)
        {
            vpx_files_to_index.push(vpx_file);
        }
    }

    // The index is dirty if files were removed or any files need (re)indexing.
    // When clean, we skip the write to avoid an unnecessary NAS round-trip.
    let index_dirty = removed_len > 0 || !vpx_files_to_index.is_empty();

    info!("  {} tables need (re)indexing.", vpx_files_to_index.len());
    let vpx_files_with_table_info = index_vpx_files(
        vpx_files_to_index,
        global_pinmame_path,
        configured_pinmame_path,
        progress,
    )?;

    // add new files to index
    index.merge(vpx_files_with_table_info);

    if index_dirty {
        // write the index to a file
        write_index_json(&index, tables_index_path, Some(tables_folder))?;
    }

    Ok(index)
}

/// Indexes all vpx files in the given folder and returns the index.
/// note: The index is unordered, so the order of the tables is not guaranteed.
///
/// Arguments:
/// * `vpx_files`: the vpx files to index.
/// * `global_roms_path`: the path to the global roms folder. Eg ~/.pinmame/roms on *nix systems.
/// * `pinmame_roms_path`: the path to the local pinmame roms folder configured in the vpinball config
/// * `progress`: lister for progress updates.
///
/// see https://github.com/francisdb/vpxtool/issues/526
pub fn index_vpx_files(
    vpx_files: Vec<PathWithMetadata>,
    global_pinmame_path: Option<&Path>,
    configured_pinmame_path: Option<&Path>,
    progress: &impl Progress,
) -> io::Result<TablesIndex> {
    let global_roms = global_pinmame_path
        .map(|pinmame_path| {
            let roms_path = pinmame_path.join("roms");
            find_roms(&roms_path)
        })
        .unwrap_or_else(|| Ok(HashMap::new()))?;

    let pinmame_roms_path = configured_pinmame_path.map(|p| p.join("roms").to_path_buf());

    let (progress_tx, progress_rx) = std::sync::mpsc::channel();

    progress.set_length(vpx_files.len() as u64);
    let index_thread = std::thread::spawn(move || {
        vpx_files
            .par_iter()
            .flat_map(|vpx_file| {
                let res = match index_vpx_file(vpx_file, pinmame_roms_path.as_deref(), &global_roms)
                {
                    Ok(indexed_table) => Some(indexed_table),
                    Err(e) => {
                        // TODO we want to return any failures instead of printing here
                        let warning =
                            format!("Not a valid vpx file {}: {}", vpx_file.path.display(), e);
                        println!("{warning}");
                        None
                    }
                };
                // We don't care if something fails, it's just progress reporting.
                let _ = progress_tx.send(1);
                res
            })
            .collect()
    });

    let mut finished = 0;
    // The sender is automatically closed when it goes out of scope, we can be sure
    // that this does not block forever.
    for i in progress_rx {
        finished += i;
        progress.set_position(finished);
    }

    let vpx_files_with_table_info = index_thread
        .join()
        .map_err(|e| io::Error::other(format!("{e:?}")))?;

    Ok(TablesIndex {
        tables: vpx_files_with_table_info,
    })
}

fn index_vpx_file(
    vpx_file_path: &PathWithMetadata,
    configured_roms_path: Option<&Path>,
    global_roms: &HashMap<String, PathBuf>,
) -> io::Result<(PathBuf, IndexedTable)> {
    let path = &vpx_file_path.path;
    let mut vpx_file = vpx::open(path)?;
    // if there's an .info.json file, we should use that instead of the info in the vpx file
    let info_file_path = path.with_extension("info.json");
    let table_info = if info_file_path.exists() {
        read_table_info_json(&info_file_path)
    } else {
        vpx_file.read_tableinfo()
    }?;
    let game_data = vpx_file.read_gamedata()?;
    let code = consider_sidecar_vbs(path, game_data)?;
    //  also this sidecar should be part of the cache key
    let game_name = extract_game_name(&code);
    let requires_pinmame = requires_pinmame(&code);
    let rom_path = find_local_rom_path(path, &game_name, configured_roms_path)?.or_else(|| {
        game_name
            .as_ref()
            .and_then(|game_name| global_roms.get(&game_name.to_lowercase()).cloned())
    });
    let b2s_path = find_b2s_path(path);
    let wheel_path = find_wheel_path(path);
    // Read the vpx_parent directory once and share it across all asset
    // detectors. Critical on NAS where each read_dir is a network round-trip.
    let parent_index = path
        .parent()
        .map(CaseInsensitiveDir::read)
        .unwrap_or_else(|| CaseInsensitiveDir {
            entries: HashMap::new(),
        });
    let altsound_path = find_altsound_path(&parent_index, &game_name);
    let altcolor_path = find_altcolor_path(&parent_index, &game_name);
    let pup_pack_path = find_pup_pack_path(&parent_index, &game_name);
    let last_modified = last_modified(path)?;
    let indexed_table_info = IndexedTableInfo::from(table_info);

    let indexed = IndexedTable {
        path: path.clone(),
        table_info: indexed_table_info,
        game_name,
        b2s_path,
        rom_path,
        local_rom_path: None,
        wheel_path,
        altsound_path,
        altcolor_path,
        pup_pack_path,
        requires_pinmame,
        last_modified: IsoSystemTime(last_modified),
    };
    Ok((indexed.path.clone(), indexed))
}

pub fn get_romname_from_vpx(vpx_path: &Path) -> io::Result<Option<String>> {
    let mut vpx_file = vpx::open(vpx_path)?;
    let game_data = vpx_file.read_gamedata()?;
    let code = consider_sidecar_vbs(vpx_path, game_data)?;
    let game_name = extract_game_name(&code);
    let requires_pinmame = requires_pinmame(&code);
    if requires_pinmame {
        Ok(game_name)
    } else {
        Ok(None)
    }
}

/// Read the script's `cGameName` (or FlexDMD `.GameName`) constant regardless
/// of whether the table is PinMAME-based. Companion to [`get_romname_from_vpx`]
/// for callers that need the in-script identifier as a section/file key (e.g.
/// `[<cGameName>]` in VPReg.ini, `<cGameName>_glf.ini` for GLF tables).
pub fn get_gamename_from_vpx(vpx_path: &Path) -> io::Result<Option<String>> {
    let mut vpx_file = vpx::open(vpx_path)?;
    let game_data = vpx_file.read_gamedata()?;
    let code = consider_sidecar_vbs(vpx_path, game_data)?;
    Ok(extract_game_name(&code))
}

/// Pull every distinct VPReg.ini section key a script writes under, in
/// first-seen order. A real table can use a mix of section names per
/// `LoadValue(<arg>, "HighScoreN")` call: a constant (`cGameName`,
/// `TableName`, `MyTable`, `cGameSaveName`, ...) or a hardcoded literal.
/// The dispatcher iterates this list when probing VPReg, so it doesn't
/// matter which convention the script chose - whichever section happens
/// to be present in the on-disk VPReg.ini will resolve.
pub fn get_vpreg_section_keys_from_vpx(vpx_path: &Path) -> io::Result<Vec<String>> {
    let mut vpx_file = vpx::open(vpx_path)?;
    let game_data = vpx_file.read_gamedata()?;
    let code = consider_sidecar_vbs(vpx_path, game_data)?;
    Ok(extract_vpreg_section_keys(&code))
}

/// Two-pass scan over a VBS script:
///   1. Collect every `Const <id> = "..."` declaration into a lookup map.
///      Identifier comparison is case-insensitive (VBS itself treats
///      identifiers case-insensitively).
///   2. Walk `(Load|Save)Value(<arg>, "HighScore...")` call sites; for each
///      `<arg>` that's a quoted literal use it directly, otherwise resolve
///      it against the Const map. Unknown identifiers are skipped silently.
///
/// Returns the distinct list of section keys preserving the order of first
/// occurrence in the script. Comments (lines starting with `'`) are stripped
/// before either pass so a commented-out example doesn't pollute the result.
fn extract_vpreg_section_keys<S: AsRef<str>>(code: S) -> Vec<String> {
    let unified = unify_line_endings(code.as_ref());
    let stripped: String = unified
        .lines()
        .map(|line| {
            // Naive comment strip: cuts at the first single-quote. VBS
            // comments can appear mid-line after expressions, and string
            // literals inside double-quotes shouldn't contain unescaped `'`
            // for the cases we care about (LoadValue with HighScoreN keys).
            line.split_once('\'').map(|(c, _)| c).unwrap_or(line)
        })
        .collect::<Vec<_>>()
        .join("\n");

    let mut consts: std::collections::HashMap<String, String> = std::collections::HashMap::new();
    for caps in CONST_DECL_REGEX.captures_iter(&stripped) {
        let id = caps.get(1).unwrap().as_str().to_ascii_lowercase();
        let value = caps.get(2).unwrap().as_str().to_string();
        // First declaration wins: VBS would treat a redeclaration as a
        // compile error, but tolerate it just in case.
        consts.entry(id).or_insert(value);
    }
    // Then fold in plain `<id> = "..."` assignments. Const wins where
    // there's a conflict (more reliable signal); the assignment path
    // exists to cover `Dim X` + `X = "..."` scripts like John Wick.
    for caps in VAR_ASSIGN_REGEX.captures_iter(&stripped) {
        let id = caps.get(1).unwrap().as_str().to_ascii_lowercase();
        let value = caps.get(2).unwrap().as_str().to_string();
        consts.entry(id).or_insert(value);
    }

    let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
    let mut out: Vec<String> = Vec::new();
    for caps in VPREG_HIGHSCORE_CALL_REGEX.captures_iter(&stripped) {
        let arg = caps.get(1).unwrap().as_str();
        let resolved = if arg.starts_with('"') && arg.ends_with('"') && arg.len() >= 2 {
            // Quoted literal - strip the surrounding quotes.
            Some(arg[1..arg.len() - 1].to_string())
        } else {
            consts.get(&arg.to_ascii_lowercase()).cloned()
        };
        if let Some(key) = resolved
            && seen.insert(key.clone())
        {
            out.push(key);
        }
    }
    out
}

fn read_table_info_json(info_file_path: &Path) -> io::Result<TableInfo> {
    let info_file = File::open(info_file_path)?;
    let reader = BufReader::new(info_file);
    let json = serde_json::from_reader(reader).map_err(|e| {
        io::Error::other(format!(
            "Failed to parse/read json {}: {}",
            info_file_path.display(),
            e
        ))
    })?;
    let (table_info, _custom_info_tags) = json_to_info(json, None)?;
    Ok(table_info)
}

/// Locate the `.nv` file for a vpx by reading the script for the rom name and
/// then probing the same set of pinmame folders the indexer uses for roms:
///   1. configured PinMAMEPath (resolved relative to the vpx if relative)
///   2. `<vpx_parent>/pinmame` (vpinball's local fallback)
///   3. global pinmame folder (`~/.pinmame` or `VPinMAME` on Windows)
///
/// Returns `Ok(None)` for non-PinMAME tables or when no `.nv` file is found.
pub fn find_nvram_for_vpx(
    vpx_path: &Path,
    configured_pinmame_folder: Option<&Path>,
    global_pinmame_folder: Option<&Path>,
) -> io::Result<Option<PathBuf>> {
    let Some(rom_name) = get_romname_from_vpx(vpx_path)? else {
        return Ok(None);
    };
    Ok(find_nvram_for_rom(
        &rom_name,
        vpx_path,
        configured_pinmame_folder,
        global_pinmame_folder,
    ))
}

/// Find a `<rom>.nv` file by probing, in order: the configured PinMAMEPath, the
/// `<vpx_parent>/pinmame` local fallback, and the global pinmame folder.
fn find_nvram_for_rom(
    rom_name: &str,
    vpx_path: &Path,
    configured_pinmame_folder: Option<&Path>,
    global_pinmame_folder: Option<&Path>,
) -> Option<PathBuf> {
    let nv_file = format!("{}.nv", rom_name.to_lowercase());
    let vpx_parent = vpx_path.parent().unwrap_or(Path::new("."));

    let mut candidates: Vec<PathBuf> = Vec::new();
    if let Some(p) = configured_pinmame_folder {
        let base = if p.is_relative() {
            vpx_parent.join(p)
        } else {
            p.to_path_buf()
        };
        candidates.push(base.join("nvram").join(&nv_file));
    }
    candidates.push(vpx_parent.join("pinmame").join("nvram").join(&nv_file));
    if let Some(p) = global_pinmame_folder {
        candidates.push(p.join("nvram").join(&nv_file));
    }
    candidates.into_iter().find(|p| p.is_file())
}

/// Visual pinball always falls back to the [vpx_folder]/pinmame/roms folder,
/// even if the PinMAMEPath folder is configured in the vpinball config.
fn find_local_rom_path(
    vpx_file_path: &Path,
    game_name: &Option<String>,
    configured_roms_path: Option<&Path>,
) -> io::Result<Option<PathBuf>> {
    if let Some(game_name) = game_name {
        let rom_file_name = format!("{}.zip", game_name.to_lowercase());

        let pinmame_roms_path = if let Some(configured_roms_path) = configured_roms_path {
            let configured_roms_path = if configured_roms_path.is_relative() {
                vpx_file_path.parent().unwrap().join(configured_roms_path)
            } else {
                configured_roms_path.to_owned()
            };
            if configured_roms_path.exists() {
                configured_roms_path
            } else {
                vpx_file_path.parent().unwrap().join("pinmame").join("roms")
            }
        } else {
            vpx_file_path.parent().unwrap().join("pinmame").join("roms")
        };

        let rom_path = pinmame_roms_path.join(rom_file_name);
        return if rom_path.exists() {
            Ok(Some(rom_path.canonicalize()?))
        } else {
            Ok(None)
        };
    };
    Ok(None)
}

fn find_b2s_path(vpx_file_path: &Path) -> Option<PathBuf> {
    let b2s_file_name = format!(
        "{}.directb2s",
        vpx_file_path.file_stem().unwrap().to_string_lossy()
    );
    let b2s_path = vpx_file_path.parent().unwrap().join(b2s_file_name);
    if b2s_path.exists() {
        Some(b2s_path)
    } else {
        None
    }
}

/// Locate the altsound directory for this table.
///
/// Matches the priority order of vpinball-standalone's altsound plugin:
///   1. `<vpx_parent>/altsound/<rom>/`
///   2. `<vpx_parent>/pinmame/altsound/<rom>/`
///
/// Global altsound paths (configured in vpinball settings) are not probed yet.
fn find_altsound_path(
    parent_index: &CaseInsensitiveDir,
    game_name: &Option<String>,
) -> Option<PathBuf> {
    find_table_asset_dir(
        parent_index,
        game_name,
        &[&["altsound"], &["pinmame", "altsound"]],
    )
}

/// Locate the DMD colorization directory for this table.
///
/// DMD colorization comes in two formats with different file conventions, so
/// directory-presence alone isn't a reliable signal (empty directories happen).
/// We probe the per-table locations used by the serum and vni plugins in
/// vpinball-standalone, in their priority order, and require an actual
/// colorization file to exist before reporting a hit:
///
/// Serum (`<rom>.cromc` or `<rom>.crz`):
///   1. `<vpx_parent>/serum/<rom>/`
///   2. `<vpx_parent>/pinmame/altcolor/<rom>/`
///
/// VNI (`<rom>.pal` + `<rom>.vni`, or `pin2dmd.pal` + `pin2dmd.vni`):
///   1. `<vpx_parent>/vni/<rom>/`
///   2. `<vpx_parent>/pinmame/altcolor/<rom>/`
///
/// Returns the directory of the first hit. Global colorization paths
/// (configured in vpinball settings) are not probed yet.
fn find_altcolor_path(
    parent_index: &CaseInsensitiveDir,
    game_name: &Option<String>,
) -> Option<PathBuf> {
    let rom = game_name.as_deref()?;

    let candidates: &[&[&str]] = &[&["serum"], &["vni"], &["pinmame", "altcolor"]];
    'candidate: for segments in candidates {
        let first = segments.first()?;
        let mut dir = match parent_index.get(first) {
            Some(p) => p.to_path_buf(),
            None => continue 'candidate,
        };
        for seg in &segments[1..] {
            match find_case_insensitive_child(&dir, seg) {
                Some(matched) => dir = matched,
                None => continue 'candidate,
            }
        }
        let Some(rom_dir) = find_case_insensitive_child(&dir, rom) else {
            continue;
        };
        if dir_contains_colorization(&rom_dir, rom) {
            return Some(rom_dir);
        }
    }
    None
}

/// Does `dir` contain a colorization file for `rom`? Matches the file-pattern
/// checks vpinball-standalone's serum and vni plugins do (any of `.cromc`,
/// `.crz`, `.pal` named after the rom; or `pin2dmd.pal` for the shared-name
/// VNI fallback). Case-insensitive: real tables ship colorization with
/// mixed-case extensions like `.cROMc` and `.cRZ`.
fn dir_contains_colorization(dir: &Path, rom: &str) -> bool {
    if !dir.is_dir() {
        return false;
    }
    let targets = [
        format!("{rom}.cromc"),
        format!("{rom}.crz"),
        format!("{rom}.pal"),
        "pin2dmd.pal".to_string(),
    ];
    let Ok(entries) = fs::read_dir(dir) else {
        return false;
    };
    for entry in entries.flatten() {
        let name = entry.file_name();
        let Some(name) = name.to_str() else { continue };
        if targets
            .iter()
            .any(|target| name.eq_ignore_ascii_case(target))
            && entry.path().is_file()
        {
            return true;
        }
    }
    false
}

/// Locate the PinUP Player video pack for this table.
///
/// Matches the lookup in vpinball-standalone's PUPManager:
///   1. `<vpx_parent>/pupvideos/<rom>/`
///
/// The global PUP path (configured in PinUP Player) is not probed yet.
fn find_pup_pack_path(
    parent_index: &CaseInsensitiveDir,
    game_name: &Option<String>,
) -> Option<PathBuf> {
    find_table_asset_dir(parent_index, game_name, &[&["pupvideos"]])
}

/// Probe a list of `<vpx_parent>/<segments...>/<rom>/` directories and return
/// the first one that exists. Returns `None` when there is no rom name or no
/// candidate exists.
///
/// The first segment is resolved against the cached `parent_index` so we
/// avoid re-reading vpx_parent for each candidate. Deeper segments still need
/// a directory scan, but those only happen when an asset folder is actually
/// present (the minority case in real cab installs), so the total syscall
/// count is dominated by the single cached read.
///
/// Path component matching is case-insensitive (ASCII): real-world cab
/// installs ship folders with inconsistent casing (`AltSound/`, `AltColor/`)
/// and rom-named subfolders that don't match the vpx script's casing.
/// vpinball-standalone handles this with `find_case_insensitive_directory_path`
/// in every plugin; we mirror that behavior here.
fn find_table_asset_dir(
    parent_index: &CaseInsensitiveDir,
    game_name: &Option<String>,
    candidates: &[&[&str]],
) -> Option<PathBuf> {
    let rom = game_name.as_deref()?;
    'candidate: for segments in candidates {
        let first = segments.first()?;
        let mut path = match parent_index.get(first) {
            Some(p) => p.to_path_buf(),
            None => continue 'candidate,
        };
        for seg in &segments[1..] {
            match find_case_insensitive_child(&path, seg) {
                Some(matched) => path = matched,
                None => continue 'candidate,
            }
        }
        if let Some(rom_dir) = find_case_insensitive_child(&path, rom)
            && rom_dir.is_dir()
        {
            return Some(rom_dir);
        }
    }
    None
}

/// Case-insensitive view of a directory's entries.
///
/// Materializing this once per table costs a single `read_dir` syscall and
/// converts the subsequent per-asset lookups into in-memory `HashMap`
/// queries. Critical on NAS where each syscall is a network round-trip:
/// without this cache the asset finders re-read `vpx_parent` once per
/// candidate top-level segment (~6 times per table for the altsound /
/// altcolor / pup combo).
struct CaseInsensitiveDir {
    /// Map of ASCII-lowercased file name to the actual on-disk path.
    entries: HashMap<String, PathBuf>,
}

impl CaseInsensitiveDir {
    /// Scan `dir` and build the case-insensitive index. Returns an empty
    /// index when the directory cannot be read (missing, permission denied,
    /// etc.) so callers can treat it uniformly without a None branch.
    fn read(dir: &Path) -> Self {
        let entries = fs::read_dir(dir)
            .ok()
            .map(|iter| {
                iter.flatten()
                    .filter_map(|entry| {
                        entry
                            .file_name()
                            .to_str()
                            .map(|n| (n.to_ascii_lowercase(), entry.path()))
                    })
                    .collect()
            })
            .unwrap_or_default();
        Self { entries }
    }

    /// Look up an entry by its file name, case-insensitively (ASCII).
    fn get(&self, name: &str) -> Option<&Path> {
        self.entries
            .get(&name.to_ascii_lowercase())
            .map(|p| p.as_path())
    }
}

/// Return the path of an entry directly under `parent` whose file name matches
/// `name` case-insensitively. Returns `None` if `parent` is not readable or
/// no entry matches.
///
/// Used for traversals deeper than the top-level vpx_parent scan (which goes
/// through [`CaseInsensitiveDir`] for caching). We always scan the directory
/// (no exact-case fast path) because on case-insensitive filesystems
/// (macOS, Windows) `parent.join(name).exists()` returns true for any case
/// variant, which would silently return the requested casing rather than the
/// actual on-disk name. That asymmetry breaks both downstream display and any
/// prefix-stripping the index does.
fn find_case_insensitive_child(parent: &Path, name: &str) -> Option<PathBuf> {
    let entries = fs::read_dir(parent).ok()?;
    for entry in entries.flatten() {
        if entry
            .file_name()
            .to_str()
            .is_some_and(|n| n.eq_ignore_ascii_case(name))
        {
            return Some(entry.path());
        }
    }
    None
}

/// Tries to find a wheel image for the given vpx file.
/// 2 locations are tried:
/// * ../wheels/<vpx_file_name>.png
/// * <vpx_file_name>.wheel.png
fn find_wheel_path(vpx_file_path: &Path) -> Option<PathBuf> {
    let wheel_file_name = format!(
        "wheels/{}.png",
        vpx_file_path.file_stem().unwrap().to_string_lossy()
    );
    let wheel_path = vpx_file_path.parent().unwrap().join(wheel_file_name);
    if wheel_path.exists() {
        return Some(wheel_path);
    }
    let wheel_path = vpx_file_path.with_extension("wheel.png");
    if wheel_path.exists() {
        return Some(wheel_path);
    }
    None
}

/// If there is a file with the same name and extension .vbs we pick that code
/// instead of the code in the vpx file.
///
/// TODO if this file changes the index entry is currently not invalidated
fn consider_sidecar_vbs(path: &Path, game_data: GameData) -> io::Result<String> {
    let vbs_path = path.with_extension("vbs");
    let code = if vbs_path.exists() {
        let vbs_file = File::open(vbs_path)?;
        let mut reader = BufReader::new(vbs_file);
        let mut code = String::new();
        reader.read_to_string(&mut code)?;
        code
    } else {
        game_data.code.string
    };
    Ok(code)
}

/// Clone `table`, normalizing every path field to be relative to `tables_root`
/// (forward slashes). `canonical_root` is the pre-canonicalized form of
/// `tables_root`, computed once by the caller so we don't redo the syscall per
/// path field.
fn normalize_table_for_json(
    table: &IndexedTable,
    tables_root: &Path,
    canonical_root: Option<&Path>,
) -> IndexedTable {
    let norm =
        |p: &Path| PathBuf::from(try_make_relative_normalized(p, tables_root, canonical_root));
    IndexedTable {
        path: norm(&table.path),
        table_info: table.table_info.clone(),
        game_name: table.game_name.clone(),
        b2s_path: table.b2s_path.as_ref().map(|p| norm(p)),
        rom_path: table.rom_path.as_ref().map(|p| norm(p)),
        local_rom_path: table.local_rom_path.as_ref().map(|p| norm(p)),
        wheel_path: table.wheel_path.as_ref().map(|p| norm(p)),
        altsound_path: table.altsound_path.as_ref().map(|p| norm(p)),
        altcolor_path: table.altcolor_path.as_ref().map(|p| norm(p)),
        pup_pack_path: table.pup_pack_path.as_ref().map(|p| norm(p)),
        requires_pinmame: table.requires_pinmame,
        last_modified: table.last_modified,
    }
}

/// Resolve every path field in `table` from a forward-slash string back to an
/// absolute platform path. Takes ownership so we don't clone strings we're
/// about to throw away.
fn denormalize_table_from_json(table: IndexedTable, tables_root: Option<&Path>) -> IndexedTable {
    let resolve = |p: PathBuf| resolve_normalized_path(&p.to_string_lossy(), tables_root);
    IndexedTable {
        path: resolve(table.path),
        table_info: table.table_info,
        game_name: table.game_name,
        b2s_path: table.b2s_path.map(resolve),
        rom_path: table.rom_path.map(resolve),
        local_rom_path: table.local_rom_path.map(resolve),
        wheel_path: table.wheel_path.map(resolve),
        altsound_path: table.altsound_path.map(resolve),
        altcolor_path: table.altcolor_path.map(resolve),
        pup_pack_path: table.pup_pack_path.map(resolve),
        requires_pinmame: table.requires_pinmame,
        last_modified: table.last_modified,
    }
}

fn last_modified(path: &Path) -> io::Result<SystemTime> {
    let metadata: Metadata = path.metadata()?;
    metadata.modified()
}

pub fn write_index_json(
    indexed_tables: &TablesIndex,
    json_path: &Path,
    tables_root: Option<&Path>,
) -> io::Result<()> {
    // Canonicalize the root once so the per-path helper doesn't repeat the syscall.
    let canonical_root = tables_root.and_then(|r| r.canonicalize().ok());
    let canonical_root_ref = canonical_root.as_deref();
    let tables: Vec<IndexedTable> = indexed_tables
        .tables
        .values()
        .map(|t| match tables_root {
            Some(root) => normalize_table_for_json(t, root, canonical_root_ref),
            None => t.clone(),
        })
        .collect();
    let indexed_tables_json = TablesIndexJson {
        tables: sort_tables(tables),
    };
    atomic_write(json_path, |file| {
        let mut writer = BufWriter::new(file);
        serde_json::to_writer_pretty(&mut writer, &indexed_tables_json)
            .map_err(io::Error::other)?;
        writer.into_inner().map_err(|e| e.into_error())?;
        Ok(())
    })
}

pub fn read_index_json(
    json_path: &Path,
    tables_root: Option<&Path>,
) -> io::Result<Option<TablesIndex>> {
    if !json_path.exists() {
        return Ok(None);
    }
    let json_file = File::open(json_path)?;
    let reader = BufReader::new(json_file);
    match serde_json::from_reader::<_, TablesIndexJson>(reader) {
        Ok(json) => {
            let tables = json
                .tables
                .into_iter()
                .map(|t| {
                    let denormalized = denormalize_table_from_json(t, tables_root);
                    (denormalized.path.clone(), denormalized)
                })
                .collect();
            Ok(Some(TablesIndex { tables }))
        }
        Err(e) => {
            println!("Failed to parse index file, ignoring existing index. ({e})");
            Ok(None)
        }
    }
}

fn extract_game_name<S: AsRef<str>>(code: S) -> Option<String> {
    let unified = unify_line_endings(code.as_ref());
    unified
        .lines()
        // skip rows that start with ' or whitespace followed by '
        .filter(|line| !line.trim().starts_with('\''))
        .filter(|line| {
            let lower: String = line.to_owned().to_lowercase().trim().to_string();
            lower.contains("cgamename") || lower.contains(".gamename")
        })
        .flat_map(|line| {
            let caps = LINE_WITH_CGAMENAME_REGEX
                .captures(line)
                .or(LINE_WITH_DOT_GAMENAME_REGEX.captures(line))?;
            let first = caps.get(1)?;
            Some(first.as_str().to_string())
        })
        .next()
}

fn requires_pinmame<S: AsRef<str>>(code: S) -> bool {
    let unified = unify_line_endings(code.as_ref());
    let lower = unified.to_lowercase();
    lower
        .lines()
        .filter(|line| !line.trim().starts_with('\''))
        .any(|line| line.contains("loadvpm") && !LOADVPM_SUB_REGEX.is_match(line))
}

/// Some scripts contain only CR as line separator. Eg "Monte Carlo (Premier 1987) (10.7) 1.6.vpx"
/// Therefore we replace first all CRLF and then all leftover CR with LF
fn unify_line_endings(code: &str) -> String {
    code.replace("\r\n", "\n").replace('\r', "\n")
}

#[cfg(test)]
mod tests {
    use super::*;
    use pretty_assertions::assert_eq;
    use serde_json::json;
    use std::io::Write;
    use testdir::testdir;
    use vpin::vpx;

    #[test]
    fn extract_vpreg_keys_picks_up_cgamename_const() {
        // Most common shape: one const referenced from LoadValue calls.
        let code = r#"
Const cGameName = "TheMatrix"
x = LoadValue(cGameName, "HighScore1")
y = LoadValue(cGameName, "HighScore1Name")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["TheMatrix"]);
    }

    #[test]
    fn extract_vpreg_keys_picks_up_tablename_const() {
        // Aerosmith-style: the load target is a separate `TableName` const,
        // distinct from `cGameName`.
        let code = r#"
Const cGameName = "aerosmith"
Const TableName = "aerosmith_VPX"
x = LoadValue(TableName, "HighScore1")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["aerosmith_VPX"]);
    }

    #[test]
    fn extract_vpreg_keys_picks_up_quoted_literal_section() {
        // Some scripts hardcode the section name inline.
        let code = r#"
SaveValue "MyHardcodedKey", "HighScore1", 1000
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["MyHardcodedKey"]);
    }

    #[test]
    fn extract_vpreg_keys_returns_distinct_first_seen_order() {
        // Iron Maiden-style: the script writes under two different consts.
        // Caller probes them in order so the first-seen one wins when both
        // sections exist (unusual but real).
        let code = r#"
Const cGameName = "ironmaiden"
Const TableName = "ironmaiden_vr"
x = LoadValue(cGameName, "HighScore1")
y = LoadValue(TableName, "HighScore2")
z = LoadValue(cGameName, "HighScore3")
"#;
        assert_eq!(
            extract_vpreg_section_keys(code),
            vec!["ironmaiden", "ironmaiden_vr"]
        );
    }

    #[test]
    fn extract_vpreg_keys_resolves_arbitrary_const_names() {
        // We don't hardcode `cGameName` / `TableName`; any const that's
        // declared and referenced from a LoadValue call resolves.
        let code = r#"
Const MyTable = "DragonBallZ"
x = LoadValue(MyTable, "HighScore1")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["DragonBallZ"]);
    }

    #[test]
    fn extract_vpreg_keys_ignores_unresolved_identifiers() {
        // If the section-key identifier isn't backed by a `Const X = "..."`
        // declaration, we can't resolve it - skip silently rather than
        // pollute the probe list with garbage.
        let code = r#"
x = LoadValue(SomeUndefinedVar, "HighScore1")
"#;
        assert!(extract_vpreg_section_keys(code).is_empty());
    }

    #[test]
    fn extract_vpreg_keys_picks_up_legacy_em_score_keys() {
        // Older EM tables (Abra Ca Dabra etc.) use `LoadValue(<arg>,
        // "hiscore")` and `LoadValue(<arg>, "hsa1")` rather than modern
        // HighScoreN. The section name surfaces just the same.
        let code = r#"
temp = LoadValue("Abra_Ca_Dabra", "credit")
temp = LoadValue("Abra_Ca_Dabra", "hiscore")
temp = LoadValue("Abra_Ca_Dabra", "hsa1")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["Abra_Ca_Dabra"]);
    }

    #[test]
    fn extract_vpreg_keys_ignores_non_highscore_loadvalue_calls() {
        // VPReg also stores LUT image / volume / etc. Those use different
        // value keys; we only care about HighScoreN/HighScoreNName so the
        // section list stays focused on scoring code paths.
        let code = r#"
Const cGameName = "foo"
x = LoadValue(cGameName, "LUTImage")
y = LoadValue(cGameName, "BgVolume")
"#;
        assert!(extract_vpreg_section_keys(code).is_empty());
    }

    #[test]
    fn extract_vpreg_keys_ignores_commented_out_examples() {
        // A commented-out example LoadValue call must not contribute.
        let code = r#"
Const cGameName = "Real"
' Const TableName = "OldExample"
' x = LoadValue(TableName, "HighScore1")
y = LoadValue(cGameName, "HighScore1")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["Real"]);
    }

    #[test]
    fn extract_vpreg_keys_picks_up_dim_plus_assignment() {
        // John Wick-style: `Dim MyTable` declares the var, separate line
        // assigns the literal. Used by tables that need to set the section
        // key dynamically before the Const block (rare but real).
        let code = r#"
Dim MyTable
MyTable = "JPsIT"
x = LoadValue(MyTable, "HighScore1")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["JPsIT"]);
    }

    #[test]
    fn extract_vpreg_keys_const_wins_over_plain_assignment() {
        // If a script binds the same identifier both as Const and as a
        // standalone assignment, the Const value is the authoritative one
        // (VBS would actually reject reassignment of a Const at compile
        // time, but the regex would otherwise see both).
        let code = r#"
Const cGameName = "FromConst"
cGameName = "FromAssign"
x = LoadValue(cGameName, "HighScore1")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["FromConst"]);
    }

    #[test]
    fn extract_vpreg_keys_treats_identifier_case_insensitively() {
        // VBS identifiers are case-insensitive. A declaration with
        // `Const TableName` should resolve `tablename`-cased references.
        let code = r#"
Const TableName = "MixedCaseHit"
x = LoadValue(tablename, "HighScore1")
"#;
        assert_eq!(extract_vpreg_section_keys(code), vec!["MixedCaseHit"]);
    }

    #[test]
    fn test_index_vpx_files() -> io::Result<()> {
        // Test setup looks like this:
        // test_dir/
        // ├── test.vpx
        // ├── test2.vpx
        // ├── subdir
        // │   └── test3.vpx
        // ├── test3.vpx
        // ├── __MACOSX/
        // │   └── ignored.vpx
        // ├── .git/
        // │   └── ignored2.vpx
        // ├── pinmame/
        // │   └── roms/
        // │       └── testgamename.zip
        // global_pinmame/
        // ├── roms/
        // │   └── testgamename2.zip
        let global_pinmame_dir = testdir!().join("global_pinmame");
        fs::create_dir(&global_pinmame_dir)?;
        let global_roms_dir = global_pinmame_dir.join("roms");
        fs::create_dir(&global_roms_dir)?;
        let tables_dir = testdir!().join("tables");
        fs::create_dir(&tables_dir)?;
        let temp_dir = testdir!().join("temp");
        fs::create_dir(&temp_dir)?;
        // the next two folders should be ignored
        let macosx = tables_dir.join("__MACOSX");
        fs::create_dir(&macosx)?;
        File::create(macosx.join("ignored.vpx"))?;
        let git = tables_dir.join(".git");
        fs::create_dir(&git)?;
        File::create(git.join("ignored2.vpx"))?;
        fs::create_dir(tables_dir.join("subdir"))?;
        // actual vpx files to index
        let vpx_1_path = tables_dir.join("test.vpx");
        let vpx_2_path = tables_dir.join("test2.vpx");
        let vpx_3_path = tables_dir.join("subdir").join("test3.vpx");

        vpx::new_minimal_vpx(&vpx_1_path)?;
        let script1 = test_script(&temp_dir, "testgamename")?;
        vpx::importvbs(&vpx_1_path, Some(script1))?;
        // local rom
        let mut rom1_path_local = tables_dir
            .join("pinmame")
            .join("roms")
            .join("testgamename.zip");
        // recursively create dir
        fs::create_dir_all(rom1_path_local.parent().unwrap())?;
        File::create(&rom1_path_local)?;
        // this canonicalize makes a strange dir starting with //?/
        rom1_path_local = rom1_path_local.canonicalize()?;

        vpx::new_minimal_vpx(&vpx_2_path)?;
        let script2 = test_script(&temp_dir, "testgamename2")?;
        vpx::importvbs(&vpx_2_path, Some(script2))?;
        // global rom
        let rom2_path_global = global_roms_dir.join("testgamename2.zip");
        File::create(&rom2_path_global)?;

        vpx::new_minimal_vpx(&vpx_3_path)?;
        // no rom

        // let output = std::process::Command::new("tree")
        //     .arg(&tables_dir)
        //     .output()
        //     .expect("failed to execute process");
        // let output_str = String::from_utf8_lossy(&output.stdout);
        // println!("test_dir:\n{}", output_str);
        //
        // let output = std::process::Command::new("tree")
        //     .arg(&global_pinmame_dir)
        //     .output()
        //     .expect("failed to execute process");
        // let output_str = String::from_utf8_lossy(&output.stdout);
        // println!("global_pinmame_dir:\n{}", output_str);

        let vpx_files = find_vpx_files(true, None, &tables_dir)?;
        assert_eq!(vpx_files.len(), 3);
        let global_roms = find_roms(&global_roms_dir)?;
        assert_eq!(global_roms.len(), 1);
        let configured_roms_path = Some(PathBuf::from("./"));
        let indexed_tables = index_vpx_files(
            vpx_files,
            Some(&global_pinmame_dir),
            configured_roms_path.as_deref(),
            &VoidProgress,
        )?;
        assert_eq!(indexed_tables.tables.len(), 3);
        let table1 = indexed_tables
            .tables
            .get(&vpx_1_path)
            .expect("table1 not found");
        let table2 = indexed_tables
            .tables
            .get(&vpx_2_path)
            .expect("table2 not found");
        let table3 = indexed_tables
            .tables
            .get(&vpx_3_path)
            .expect("table3 not found");
        assert_eq!(table1.path, vpx_1_path);
        assert_eq!(table2.path, vpx_2_path);
        assert_eq!(table3.path, vpx_3_path);
        assert_eq!(table1.rom_path, Some(rom1_path_local.clone()));
        assert_eq!(table2.rom_path, Some(rom2_path_global.clone()));
        assert_eq!(table3.rom_path, None);
        Ok(())
    }

    #[test]
    #[cfg(unix)]
    fn test_index_folder_skips_write_when_unchanged() -> io::Result<()> {
        // A second index_folder call with no filesystem changes must skip the
        // index write. atomic_write replaces the file via rename on every real
        // write, so a preserved inode proves the write was skipped.
        use std::os::unix::fs::MetadataExt;

        let tables_dir = testdir!().join("tables");
        fs::create_dir(&tables_dir)?;
        vpx::new_minimal_vpx(tables_dir.join("test.vpx"))?;
        let index_path = testdir!().join("vpxtool_index.json");

        index_folder(
            true,
            None,
            &tables_dir,
            &index_path,
            None,
            None,
            &VoidProgress,
            vec![],
            false,
        )?;
        let inode_before = fs::metadata(&index_path)?.ino();

        index_folder(
            true,
            None,
            &tables_dir,
            &index_path,
            None,
            None,
            &VoidProgress,
            vec![],
            false,
        )?;
        let inode_after = fs::metadata(&index_path)?.ino();

        assert_eq!(
            inode_before, inode_after,
            "index_folder rewrote the index when nothing had changed"
        );
        Ok(())
    }

    #[test]
    fn test_index_to_json_is_sorted() -> io::Result<()> {
        let tables_dir = testdir!().join("tables");
        fs::create_dir(&tables_dir)?;
        let temp_dir = testdir!().join("temp");
        fs::create_dir(&temp_dir)?;

        // Create vpx files whose paths are not in alphabetical order to verify sort
        let vpx_z_path = tables_dir.join("z_table.vpx");
        let vpx_a_path = tables_dir.join("a_table.vpx");
        let vpx_m_path = tables_dir.join("m_table.vpx");

        vpx::new_minimal_vpx(&vpx_z_path)?;
        vpx::new_minimal_vpx(&vpx_a_path)?;
        vpx::new_minimal_vpx(&vpx_m_path)?;

        let vpx_files = find_vpx_files(true, None, &tables_dir)?;
        let indexed = index_vpx_files(vpx_files, None, None, &VoidProgress)?;

        let json: TablesIndexJson = indexed.into();
        let filenames: Vec<_> = json
            .tables
            .iter()
            .map(|t| t.path.file_name().unwrap().to_str().unwrap().to_string())
            .collect();
        assert_eq!(filenames, vec!["a_table.vpx", "m_table.vpx", "z_table.vpx"]);
        Ok(())
    }

    #[test]
    fn test_find_vpx_files_max_depth() -> io::Result<()> {
        let tables_dir = testdir!().join("tables");
        fs::create_dir(&tables_dir)?;
        let sub1 = tables_dir.join("sub1");
        fs::create_dir(&sub1)?;
        let sub2 = sub1.join("sub2");
        fs::create_dir(&sub2)?;

        let top_vpx = tables_dir.join("top.vpx");
        let mid_vpx = sub1.join("mid.vpx");
        let deep_vpx = sub2.join("deep.vpx");
        vpx::new_minimal_vpx(&top_vpx)?;
        vpx::new_minimal_vpx(&mid_vpx)?;
        vpx::new_minimal_vpx(&deep_vpx)?;

        fn names(files: &[PathWithMetadata]) -> Vec<String> {
            let mut v: Vec<_> = files
                .iter()
                .map(|f| f.path.file_name().unwrap().to_string_lossy().into_owned())
                .collect();
            v.sort();
            v
        }

        // None means unlimited - all three files found.
        assert_eq!(
            names(&find_vpx_files(true, None, &tables_dir)?),
            vec!["deep.vpx", "mid.vpx", "top.vpx"]
        );

        // Depth 1: only the top-level file.
        assert_eq!(
            names(&find_vpx_files(true, Some(1), &tables_dir)?),
            vec!["top.vpx"]
        );

        // Depth 2: top-level + one subdir level.
        assert_eq!(
            names(&find_vpx_files(true, Some(2), &tables_dir)?),
            vec!["mid.vpx", "top.vpx"]
        );

        // Depth 3: everything.
        assert_eq!(
            names(&find_vpx_files(true, Some(3), &tables_dir)?),
            vec!["deep.vpx", "mid.vpx", "top.vpx"]
        );

        // Depth 0 yields only the root dir entry, which is not a .vpx file.
        assert!(find_vpx_files(true, Some(0), &tables_dir)?.is_empty());

        Ok(())
    }

    fn test_script(temp_dir: &Path, game_name: &str) -> io::Result<PathBuf> {
        // write simple script in tempdir
        let script = format!(
            r#"
    Const cGameName = "{game_name}"
    Sub LoadVPM
    "#
        );
        let script_path = temp_dir.join(game_name).with_extension("vbs");
        let mut script_file = File::create(&script_path)?;
        script_file.write_all(script.as_bytes())?;
        Ok(script_path)
    }

    #[test]
    fn test_write_read_empty_array() -> io::Result<()> {
        let index = TablesIndex::empty();
        let test_dir = testdir!();
        let index_path = test_dir.join("test.json");
        // write empty json array using serde_json
        let json_file = File::create(&index_path)?;
        let json_object = json!({
            "tables": []
        });
        serde_json::to_writer_pretty(json_file, &json_object)?;
        let read = read_index_json(&index_path, None)?;
        assert_eq!(read, Some(index));
        Ok(())
    }

    #[test]
    fn test_write_read_invalid_file() -> io::Result<()> {
        let test_dir = testdir!();
        let index_path = test_dir.join("test.json");
        // write empty json array using serde_json
        let json_file = File::create(&index_path)?;
        // write garbage to file
        serde_json::to_writer_pretty(json_file, &"garbage")?;
        let read = read_index_json(&index_path, None)?;
        assert_eq!(read, None);
        Ok(())
    }

    #[test]
    fn test_write_read_empty_index() -> io::Result<()> {
        let index = TablesIndex::empty();
        let test_dir = testdir!();
        let index_path = test_dir.join("test.json");
        write_index_json(&index, &index_path, None)?;
        let read = read_index_json(&index_path, None)?;
        assert_eq!(read, Some(index));
        Ok(())
    }

    #[test]
    fn test_write_read_single_item_index() -> io::Result<()> {
        let mut index = TablesIndex::empty();
        index.insert(IndexedTable {
            path: PathBuf::from("test.vpx"),
            table_info: IndexedTableInfo {
                table_name: Some("test".to_string()),
                author_name: Some("test".to_string()),
                table_blurb: None,
                table_rules: None,
                author_email: None,
                release_date: None,
                table_save_rev: None,
                table_version: None,
                author_website: None,
                table_save_date: None,
                table_description: None,
                properties: BTreeMap::new(),
            },
            game_name: Some("testrom".to_string()),
            b2s_path: Some(PathBuf::from("test.b2s")),
            rom_path: Some(PathBuf::from("testrom.zip")),
            local_rom_path: None,
            wheel_path: Some(PathBuf::from("test.png")),
            altsound_path: None,
            altcolor_path: None,
            pup_pack_path: None,
            requires_pinmame: true,
            last_modified: IsoSystemTime(SystemTime::UNIX_EPOCH),
        });
        let test_dir = testdir!();
        let index_path = test_dir.join("test.json");
        write_index_json(&index, &index_path, None)?;
        let read = read_index_json(&index_path, None)?;
        assert_eq!(read, Some(index));
        Ok(())
    }

    #[test]
    fn test_properties_serialized_in_alphabetical_order() -> io::Result<()> {
        let mut properties = BTreeMap::new();
        // Insert in reverse-alphabetical order to prove ordering is not insertion-driven.
        properties.insert("zebra".to_string(), "z".to_string());
        properties.insert("mango".to_string(), "m".to_string());
        properties.insert("apple".to_string(), "a".to_string());

        let mut index = TablesIndex::empty();
        index.insert(IndexedTable {
            path: PathBuf::from("test.vpx"),
            table_info: IndexedTableInfo {
                table_name: None,
                author_name: None,
                table_blurb: None,
                table_rules: None,
                author_email: None,
                release_date: None,
                table_save_rev: None,
                table_version: None,
                author_website: None,
                table_save_date: None,
                table_description: None,
                properties,
            },
            game_name: None,
            b2s_path: None,
            rom_path: None,
            local_rom_path: None,
            wheel_path: None,
            altsound_path: None,
            altcolor_path: None,
            pup_pack_path: None,
            requires_pinmame: false,
            last_modified: IsoSystemTime::from(SystemTime::UNIX_EPOCH),
        });
        let test_dir = testdir!();
        let index_path = test_dir.join("test.json");
        write_index_json(&index, &index_path, None)?;

        // Check raw JSON key order is alphabetical.
        let json_str = std::fs::read_to_string(&index_path)?;
        let apple_pos = json_str.find("\"apple\"").expect("apple not found");
        let mango_pos = json_str.find("\"mango\"").expect("mango not found");
        let zebra_pos = json_str.find("\"zebra\"").expect("zebra not found");
        assert!(apple_pos < mango_pos, "apple should come before mango");
        assert!(mango_pos < zebra_pos, "mango should come before zebra");

        // Round-trip preserves all entries.
        let read = read_index_json(&index_path, None)?.expect("index missing after write");
        let keys: Vec<_> = read
            .tables()
            .into_iter()
            .next()
            .unwrap()
            .table_info
            .properties
            .keys()
            .cloned()
            .collect();
        assert_eq!(keys, vec!["apple", "mango", "zebra"]);
        Ok(())
    }

    #[test]
    fn test_read_index_missing() -> io::Result<()> {
        let index_path = PathBuf::from("missing_index_file.json");
        let read = read_index_json(&index_path, None)?;
        assert_eq!(read, None);
        Ok(())
    }

    #[test]
    fn test_write_read_index_paths_are_relative_and_normalized() -> io::Result<()> {
        use std::fs;
        let test_dir = testdir!();
        let tables_root = test_dir.join("tables");
        fs::create_dir(&tables_root)?;
        let vpx_path = tables_root.join("subdir").join("game.vpx");
        fs::create_dir_all(vpx_path.parent().unwrap())?;
        // Create the file so canonicalize works
        fs::write(&vpx_path, [])?;

        let mut index = TablesIndex::empty();
        index.insert(IndexedTable {
            path: vpx_path.clone(),
            table_info: IndexedTableInfo {
                table_name: None,
                author_name: None,
                table_blurb: None,
                table_rules: None,
                author_email: None,
                release_date: None,
                table_save_rev: None,
                table_version: None,
                author_website: None,
                table_save_date: None,
                table_description: None,
                properties: BTreeMap::new(),
            },
            game_name: None,
            b2s_path: None,
            rom_path: None,
            local_rom_path: None,
            wheel_path: None,
            altsound_path: None,
            altcolor_path: None,
            pup_pack_path: None,
            requires_pinmame: false,
            last_modified: IsoSystemTime(SystemTime::UNIX_EPOCH),
        });

        let index_path = test_dir.join("index.json");
        write_index_json(&index, &index_path, Some(&tables_root))?;

        // Verify the JSON contains a relative forward-slash path
        let json_str = std::fs::read_to_string(&index_path)?;
        assert!(
            json_str.contains("subdir/game.vpx"),
            "expected relative forward-slash path in JSON, got: {json_str}"
        );
        assert!(
            !json_str.contains(&tables_root.to_string_lossy().to_string()),
            "absolute path should not appear in JSON, got: {json_str}"
        );

        // Read back with tables_root — should restore absolute path
        let restored = read_index_json(&index_path, Some(&tables_root))?.expect("index missing");
        let restored_table = restored.tables().into_iter().next().unwrap();
        assert_eq!(restored_table.path, vpx_path);
        Ok(())
    }

    #[test]
    fn test_extract_game_name() {
        let code = r#"
  Dim tableheight: tableheight = Table1.height

  Const cGameName="godzilla",UseSolenoids=2,UseLamps=1,UseGI=0, SCoin=""
  Const UseVPMModSol = True

"#
        .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("godzilla".to_string()));
    }

    #[test]
    fn test_extract_game_name_commented() {
        let code = r#"
  'Const cGameName = "commented"
  Const cGameName = "actual"
"#
        .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("actual".to_string()));
    }

    #[test]
    fn test_extract_game_name_spaced() {
        let code = r#"
  Const cGameName = "gg"
"#
        .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("gg".to_string()));
    }

    #[test]
    fn test_extract_game_name_casing() {
        let code = r#"
  const cgamenamE = "othercase"
"#
        .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("othercase".to_string()));
    }

    #[test]
    fn test_extract_game_name_uppercase_name() {
        let code = r#"
Const cGameName = "BOOM"
"#
        .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("BOOM".to_string()));
    }

    #[test]
    fn test_extract_game_name_with_underscore() {
        let code = r#"
Const cGameName="simp_a27",UseSolenoids=1,UseLamps=0,UseGI=0,SSolenoidOn="SolOn",SSolenoidOff="SolOff", SCoin="coin"

LoadVPM "01000200", "DE.VBS", 3.36
"#
            .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("simp_a27".to_string()));
    }

    #[test]
    fn test_extract_game_name_multidef_end() {
        let code = r#"
Const UseSolenoids=2,UseLamps=0,UseSync=1,UseGI=0,SCoin="coin",cGameName="barbwire"
"#
        .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("barbwire".to_string()));
    }

    /// https://github.com/francisdb/vpxtool/issues/203
    #[test]
    fn test_extract_game_name_in_controller() {
        let code = r#"
        Sub Gorgar_Init
    LoadLUT
	On Error Resume Next
	With Controller
	.GameName="grgar_l1"
        "#;
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("grgar_l1".to_string()));
    }

    #[test]
    fn test_extract_game_name_dot_gamename_inline() {
        let code = r#"
    With Controller : .GameName = "inline_l1" : End With
"#;
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("inline_l1".to_string()));
    }

    #[test]
    fn test_extract_game_name_2_line_dim() {
        let code = r#"
Dim cGameName
cGameName = "abv106"
"#
        .to_string();
        let game_name = extract_game_name(code);
        assert_eq!(game_name, Some("abv106".to_string()));
    }

    #[test]
    fn test_requires_pinmame() {
        let code = r#"#
  LoadVPM "01210000", "sys80.VBS", 3.1
"#
        .to_string();
        assert!(requires_pinmame(code));
    }

    #[test]
    fn test_requires_pinmame_other_casing() {
        let code = r#"
  loadVpm "01210000", \"sys80.VBS\", 3.1
"#
        .to_string();
        assert!(requires_pinmame(code));
    }

    #[test]
    fn test_requires_pinmame_not() {
        let code = r#"
Const cGameName = "GTB_4Square_1971"
"#
        .to_string();
        assert!(!requires_pinmame(code));
    }

    #[test]
    fn test_requires_pinmame_with_same_sub() {
        // got this from blood machines
        let code = r#"
Sub LoadVPM(VPMver, VBSfile, VBSver)
	LoadVBSFiles VPMver, VBSfile, VBSver
	LoadController("VPM")
End Sub
"#
        .to_string();
        assert!(!requires_pinmame(code));
    }

    #[test]
    fn test_requires_pinmame_comment() {
        // got this from blood machines
        let code = r#"
' VRRoom set based on RenderingMode
' Internal DMD in Desktop Mode, using a textbox (must be called before LoadVPM)
Dim UseVPMDMD, VRRoom, DesktopMode
If RenderingMode = 2 Then VRRoom = VRRoomChoice Else VRRoom = 0
"#
        .to_string();
        assert!(!requires_pinmame(code));
    }

    #[test]
    fn test_requires_pinmame_comment_and_used() {
        // got this from blood machines
        let code = r#"
Const SCoin="coin3",cCredits=""

LoadVPM "01210000","sys80.vbs",3.10

'Sub LoadVPM(VPMver, VBSfile, VBSver)
'	On Error Resume Next
"#
        .to_string();
        assert!(requires_pinmame(code));
    }

    #[test]
    fn test_requires_pinmame_cr_only_lines_and_commented_sub_loadvpm() {
        // This code was taken from "Monte Carlo (Premier 1987) (10.7) 1.6.vpx"
        let code =
            "LoadVPM \"01210000\", \"sys80.VBS\", 3.1\r\r'Sub LoadVPM(VPMver, VBSfile, VBSver)\r";
        assert!(requires_pinmame(code));
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn test_find_local_rom_path_relative_linux() {
        // On Batocera the PinMAMEPath is configured as ./
        // That gives us a roms path of ./roms
        let test_table_dir = testdir!();
        let vpx_path = test_table_dir.join("test.vpx");
        let expected_rom_path = test_table_dir.join("roms").join("testgamename.zip");
        fs::create_dir_all(expected_rom_path.parent().unwrap()).unwrap();
        File::create(&expected_rom_path).unwrap();

        let local_rom = find_local_rom_path(
            &vpx_path,
            &Some("testgamename".to_string()),
            Some(&PathBuf::from("./roms")),
        )
        .unwrap();
        assert_eq!(local_rom, Some(expected_rom_path));
    }

    #[test]
    fn test_find_nvram_prefers_configured_pinmame_folder() {
        let dir = testdir!();
        let vpx_path = dir.join("test.vpx");
        let configured = dir.join("configured");
        let global = dir.join("global");
        let local_fallback = dir.join("pinmame");
        for base in [&configured, &global, &local_fallback] {
            fs::create_dir_all(base.join("nvram")).unwrap();
        }
        let configured_nv = configured.join("nvram").join("rom1.nv");
        File::create(&configured_nv).unwrap();
        File::create(local_fallback.join("nvram").join("rom1.nv")).unwrap();
        File::create(global.join("nvram").join("rom1.nv")).unwrap();

        let found = find_nvram_for_rom("rom1", &vpx_path, Some(&configured), Some(&global));
        assert_eq!(found, Some(configured_nv));
    }

    #[test]
    fn test_find_nvram_falls_back_to_local_pinmame_folder() {
        let dir = testdir!();
        let vpx_path = dir.join("test.vpx");
        let configured = dir.join("configured");
        let global = dir.join("global");
        fs::create_dir_all(dir.join("pinmame").join("nvram")).unwrap();
        let expected = dir.join("pinmame").join("nvram").join("rom1.nv");
        File::create(&expected).unwrap();

        let found = find_nvram_for_rom("rom1", &vpx_path, Some(&configured), Some(&global));
        assert_eq!(found, Some(expected));
    }

    #[test]
    fn test_find_nvram_falls_back_to_global_pinmame_folder() {
        let dir = testdir!();
        let vpx_path = dir.join("test.vpx");
        let global = dir.join("global");
        fs::create_dir_all(global.join("nvram")).unwrap();
        let expected = global.join("nvram").join("rom1.nv");
        File::create(&expected).unwrap();

        let found = find_nvram_for_rom("rom1", &vpx_path, None, Some(&global));
        assert_eq!(found, Some(expected));
    }

    #[test]
    fn test_find_nvram_lowercases_rom_name() {
        let dir = testdir!();
        let vpx_path = dir.join("test.vpx");
        let global = dir.join("global");
        fs::create_dir_all(global.join("nvram")).unwrap();
        let expected = global.join("nvram").join("rom1.nv");
        File::create(&expected).unwrap();

        let found = find_nvram_for_rom("ROM1", &vpx_path, None, Some(&global));
        assert_eq!(found, Some(expected));
    }

    #[test]
    fn test_find_nvram_returns_none_when_missing() {
        let dir = testdir!();
        let vpx_path = dir.join("test.vpx");
        let found = find_nvram_for_rom("rom1", &vpx_path, None, None);
        assert_eq!(found, None);
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn test_find_nvram_resolves_relative_configured_folder() {
        // Mirrors test_find_local_rom_path_relative_linux: on Batocera the
        // PinMAMEPath can be configured as ./, so it must resolve relative to
        // the vpx parent.
        let dir = testdir!();
        let vpx_path = dir.join("test.vpx");
        let expected = dir.join("nvram").join("rom1.nv");
        fs::create_dir_all(expected.parent().unwrap()).unwrap();
        File::create(&expected).unwrap();

        let found = find_nvram_for_rom("rom1", &vpx_path, Some(&PathBuf::from("./")), None);
        assert_eq!(found, Some(expected));
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn test_find_local_rom_path_relative_not_found_linux() {
        // On Batocera the PinMAMEPath is configured as ./
        // That gives us a roms path of ./roms
        let test_table_dir = testdir!();
        let vpx_path = test_table_dir.join("test.vpx");
        let expected_rom_path = test_table_dir.join("roms").join("testgamename.zip");
        fs::create_dir_all(expected_rom_path.parent().unwrap()).unwrap();

        let local_rom = find_local_rom_path(
            &vpx_path,
            &Some("testgamename".to_string()),
            Some(&PathBuf::from("./roms")),
        )
        .unwrap();
        assert_eq!(local_rom, None);
    }

    #[test]
    fn test_find_altsound_path_per_table_priority() {
        let dir = testdir!();
        // Both per-table layouts present. Priority 1 (altsound/) wins.
        let expected = dir.join("altsound").join("rom1");
        fs::create_dir_all(&expected).unwrap();
        fs::create_dir_all(dir.join("pinmame").join("altsound").join("rom1")).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altsound_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(expected));
    }

    #[test]
    fn test_find_altsound_path_falls_back_to_pinmame_subfolder() {
        let dir = testdir!();
        let expected = dir.join("pinmame").join("altsound").join("rom1");
        fs::create_dir_all(&expected).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altsound_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(expected));
    }

    #[test]
    fn test_find_altsound_path_none_when_dir_missing() {
        let dir = testdir!();
        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altsound_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, None);
    }

    #[test]
    fn test_find_pup_pack_path() {
        let dir = testdir!();
        let expected = dir.join("pupvideos").join("rom1");
        fs::create_dir_all(&expected).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_pup_pack_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(expected));
    }

    #[test]
    fn test_find_altcolor_path_requires_serum_file() {
        // Empty serum/<rom>/ should not be reported as colorization.
        let dir = testdir!();
        let serum_dir = dir.join("serum").join("rom1");
        fs::create_dir_all(&serum_dir).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altcolor_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(
            found, None,
            "empty serum dir should not count as colorization present"
        );

        // Once we drop a .crz file in, the directory is reported.
        File::create(serum_dir.join("rom1.crz")).unwrap();
        let found = find_altcolor_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(serum_dir));
    }

    #[test]
    fn test_find_altcolor_path_vni_pin2dmd_fallback() {
        // pin2dmd.pal is the shared-name VNI fallback per vpinball-standalone.
        let dir = testdir!();
        let vni_dir = dir.join("vni").join("rom1");
        fs::create_dir_all(&vni_dir).unwrap();
        File::create(vni_dir.join("pin2dmd.pal")).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altcolor_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(vni_dir));
    }

    #[test]
    fn test_find_altcolor_path_legacy_altcolor_subfolder() {
        let dir = testdir!();
        let altcolor_dir = dir.join("pinmame").join("altcolor").join("rom1");
        fs::create_dir_all(&altcolor_dir).unwrap();
        File::create(altcolor_dir.join("rom1.pal")).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altcolor_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(altcolor_dir));
    }

    #[test]
    fn test_find_altcolor_path_case_insensitive_folder_and_extension() {
        // Real-world cab tables: `pinmame/AltColor/<rom>/<rom>.cROMc`.
        // Both the directory name and the file extension can be in any case;
        // we must match like vpinball-standalone's find_case_insensitive_*.
        let dir = testdir!();
        let altcolor_dir = dir.join("pinmame").join("AltColor").join("rom1");
        fs::create_dir_all(&altcolor_dir).unwrap();
        File::create(altcolor_dir.join("rom1.cROMc")).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altcolor_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(altcolor_dir));
    }

    #[test]
    fn test_find_altsound_path_case_insensitive() {
        // AltSound/<ROM>/ on disk; script gives lower-case rom name.
        let dir = testdir!();
        let altsound_dir = dir.join("AltSound").join("ROM1");
        fs::create_dir_all(&altsound_dir).unwrap();

        let parent_index = CaseInsensitiveDir::read(&dir);
        let found = find_altsound_path(&parent_index, &Some("rom1".to_string()));
        assert_eq!(found, Some(altsound_dir));
    }

    fn make_indexed_table(path: &str, table_name: Option<&str>) -> IndexedTable {
        IndexedTable {
            path: PathBuf::from(path),
            table_info: IndexedTableInfo {
                table_name: table_name.map(|s| s.to_string()),
                author_name: None,
                table_blurb: None,
                table_rules: None,
                author_email: None,
                release_date: None,
                table_save_rev: None,
                table_version: None,
                author_website: None,
                table_save_date: None,
                table_description: None,
                properties: BTreeMap::new(),
            },
            game_name: None,
            b2s_path: None,
            rom_path: None,
            local_rom_path: None,
            wheel_path: None,
            altsound_path: None,
            altcolor_path: None,
            pup_pack_path: None,
            requires_pinmame: false,
            last_modified: IsoSystemTime::from(SystemTime::UNIX_EPOCH),
        }
    }

    #[test]
    fn test_sort_tables_by_path_case_insensitive() {
        let tables = vec![
            make_indexed_table("dir/Zebra.vpx", Some("Alpha")),
            make_indexed_table("dir/apple.vpx", Some("Zeta")),
            make_indexed_table("dir/Mango.vpx", Some("Beta")),
        ];
        let sorted = sort_tables(tables);
        let paths: Vec<_> = sorted.iter().map(|t| t.path.to_str().unwrap()).collect();
        assert_eq!(
            paths,
            vec!["dir/apple.vpx", "dir/Mango.vpx", "dir/Zebra.vpx"]
        );
    }

    #[test]
    fn test_sort_tables_by_full_path_not_just_filename() {
        let tables = vec![
            make_indexed_table("z_dir/apple.vpx", None),
            make_indexed_table("a_dir/zebra.vpx", None),
        ];
        let sorted = sort_tables(tables);
        let paths: Vec<_> = sorted.iter().map(|t| t.path.to_str().unwrap()).collect();
        // a_dir sorts before z_dir even though apple < zebra doesn't matter
        assert_eq!(paths, vec!["a_dir/zebra.vpx", "z_dir/apple.vpx"]);
    }
}