lindera-dictionary 5.3.0

use std::error::Error;
use std::ffi::OsString;
use std::fs::{self, File, rename};
use std::io::{self, Cursor, Read, Write};
use std::path::{Path, PathBuf};
use std::thread::sleep;
use std::time::Duration;

use flate2::read::GzDecoder;
use log::{debug, error, info, warn};
use md5::Context;
use rand::{SeedableRng, rngs::SmallRng, seq::SliceRandom};
use tar::Archive;
use ureq::Agent;

use crate::LinderaResult;
use crate::builder::DictionaryBuilder;
use crate::dictionary::metadata::{DICTIONARY_FORMAT_VERSION, Metadata};
use crate::error::LinderaErrorKind;

const MAX_ROUND: usize = 3;

pub struct FetchParams {
    /// Dictionary file name
    pub file_name: &'static str,

    /// MeCab directory (archive root directory name)
    pub input_dir: &'static str,

    /// Subdirectory within input_dir to use as the dictionary source.
    /// When `Some("dict-src")`, the dictionary builder reads from `input_dir/dict-src/`
    /// instead of `input_dir/` directly. This is useful when the archive contains
    /// both raw and trained dictionary files in separate directories.
    pub src_subdir: Option<&'static str>,

    /// Lindera directory
    pub output_dir: &'static str,

    /// Dummy input for docs.rs
    pub dummy_input: &'static str,

    /// URLs from which to fetch the asset
    pub download_urls: &'static [&'static str],

    /// MD5 hash of the file
    pub md5_hash: &'static str,
}

#[cfg(target_os = "windows")]
fn copy_dir_all(src: &Path, dst: &Path) -> LinderaResult<()> {
    if !dst.is_dir() {
        fs::create_dir_all(dst).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!("Failed to create directory: {dst:?}"))
        })?;
    }

    for entry in fs::read_dir(src).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!("Failed to read directory: {src:?}"))
    })? {
        let entry = entry.map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!("Failed to get directory entry in: {src:?}"))
        })?;
        let entry_path = entry.path();
        let dst_path = dst.join(entry.file_name());

        if entry_path.is_dir() {
            copy_dir_all(&entry_path, &dst_path)?;
        } else {
            fs::copy(&entry_path, &dst_path).map_err(|err| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!(err))
                    .add_context(format!(
                        "Failed to copy file: {entry_path:?} to {dst_path:?}"
                    ))
            })?;
        }
    }
    Ok(())
}

fn empty_directory(dir: &Path) -> LinderaResult<()> {
    if dir.exists() {
        fs::remove_dir_all(dir).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!("Failed to remove directory: {dir:?}"))
        })?;
    }

    fs::create_dir_all(dir).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!("Failed to create directory: {dir:?}"))
    })?;

    Ok(())
}

fn rename_directory(dir: &Path, new_dir: &Path) -> LinderaResult<()> {
    // Ensure parent directory of new_dir exists
    if let Some(parent) = new_dir.parent() {
        fs::create_dir_all(parent).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!("Failed to create parent directory: {parent:?}"))
        })?;
    }

    #[cfg(not(target_os = "windows"))]
    {
        rename(dir, new_dir).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!(
                    "Failed to rename directory: {dir:?} to {new_dir:?}"
                ))
        })?;
    }

    #[cfg(target_os = "windows")]
    {
        copy_dir_all(dir, new_dir).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!("{err}"))
                .add_context(format!("Failed to copy directory: {dir:?} to {new_dir:?}"))
        })?;

        fs::remove_dir_all(dir).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!(
                    "Failed to remove source directory after copy: {dir:?}"
                ))
        })?;
    }

    Ok(())
}

/// Scaffold the dummy dictionary source files used for docs.rs documentation builds.
///
/// The files are created in the directory the dictionary builder actually reads
/// from: `input_dir` itself, or `input_dir/<src_subdir>` when `src_subdir` is
/// `Some`. Directory creation is idempotent so that repeated builds against a
/// reused target directory (as on docs.rs) succeed.
///
/// # Arguments
///
/// * `input_dir` - Root input directory for the dictionary build.
/// * `src_subdir` - Optional subdirectory within `input_dir` that the
///   dictionary builder reads the source files from.
/// * `dummy_input` - Contents of the dummy dictionary CSV file.
///
/// # Returns
///
/// `Ok(())` if all dummy files were created, or a `LinderaError` on I/O failure.
fn create_dummy_dictionary_source(
    input_dir: &Path,
    src_subdir: Option<&str>,
    dummy_input: &str,
) -> LinderaResult<()> {
    // The dictionary builder reads from `input_dir/<src_subdir>` when set, so
    // the dummy files must be scaffolded there as well.
    let dummy_src_dir = match src_subdir {
        Some(subdir) => input_dir.join(subdir),
        None => input_dir.to_path_buf(),
    };

    // `create_dir_all` keeps this idempotent: docs.rs reuses the target
    // directory, so the directory may already exist from a previous run.
    fs::create_dir_all(&dummy_src_dir).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!(
                "Failed to create dummy input directory: {dummy_src_dir:?}"
            ))
    })?;

    // Create dummy char.def
    let mut dummy_char_def = File::create(dummy_src_dir.join("char.def")).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!(
                "Failed to create dummy char.def: {:?}",
                dummy_src_dir.join("char.def")
            ))
    })?;
    dummy_char_def
        .write_all(b"DEFAULT 0 1 0\n")
        .map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context("Failed to write to dummy char.def")
        })?;

    // Create dummy CSV file
    let mut dummy_dict_csv = File::create(dummy_src_dir.join("dummy_dict.csv")).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!(
                "Failed to create dummy CSV file: {:?}",
                dummy_src_dir.join("dummy_dict.csv")
            ))
    })?;
    dummy_dict_csv
        .write_all(dummy_input.as_bytes())
        .map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context("Failed to write to dummy CSV file")
        })?;

    // Create dummy unk.def
    File::create(dummy_src_dir.join("unk.def")).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!(
                "Failed to create dummy unk.def: {:?}",
                dummy_src_dir.join("unk.def")
            ))
    })?;

    // Create dummy matrix.def
    let mut dummy_matrix_def = File::create(dummy_src_dir.join("matrix.def")).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!(
                "Failed to create dummy matrix.def: {:?}",
                dummy_src_dir.join("matrix.def")
            ))
    })?;
    dummy_matrix_def.write_all(b"0 1 0\n").map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context("Failed to write to dummy matrix.def")
    })?;

    Ok(())
}

/// Dictionary archives run to hundreds of megabytes, so the 10 MB default body
/// limit does not apply here. The MD5 check below is what guards against a
/// truncated or substituted download.
const BODY_LIMIT: u64 = u64::MAX;

fn download_with_retry(
    agent: &Agent,
    download_urls: Vec<&str>,
    max_rounds: usize,
    expected_md5: &str,
) -> Result<Vec<u8>, Box<dyn Error>> {
    if download_urls.is_empty() {
        return Err("No download URLs provided".into());
    }

    for round in 0..max_rounds {
        let mut urls = download_urls.clone();

        let mut rng = SmallRng::seed_from_u64(
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .unwrap_or_default()
                .as_nanos() as u64,
        );
        urls.shuffle(&mut rng);

        debug!(
            "Round {}/{}: Trying {} URLs",
            round + 1,
            max_rounds,
            urls.len()
        );

        for url in urls {
            debug!("Attempting to download from {url}");
            match agent.get(url).call() {
                Ok(resp) if resp.status().is_success() => {
                    debug!("HTTP download successful from {url}");

                    match resp
                        .into_body()
                        .with_config()
                        .limit(BODY_LIMIT)
                        .read_to_vec()
                    {
                        Ok(content) => {
                            // Calculate MD5 hash
                            let mut context = Context::new();
                            context.consume(&content);
                            let actual_md5 = format!("{:x}", context.finalize());

                            debug!("Expected MD5: {expected_md5}");
                            debug!("Actual   MD5: {actual_md5}");

                            if actual_md5 == expected_md5 {
                                debug!("MD5 check passed from {url}");
                                return Ok(content);
                            } else {
                                warn!(
                                    "MD5 mismatch from {url}, Expected {expected_md5}, got {actual_md5}"
                                );
                                // continue to next url
                            }
                        }
                        Err(e) => {
                            warn!("Failed to download content from {url}: {e}");
                            // continue to next url
                        }
                    }
                }
                Ok(resp) => {
                    warn!("HTTP download failed from {}: HTTP {}", url, resp.status());
                    // continue to next url
                }
                Err(e) => {
                    warn!("Request error from {url}: {e}");
                    // continue to next url
                }
            }
        }

        sleep(Duration::from_secs(1));
    }

    error!("All {max_rounds} attempts failed");
    Err("Failed to download a valid file from all sources".into())
}

/// Environment variable that designates the dictionary build cache directory.
const CACHE_DIR_ENV: &str = "LINDERA_BUILD_DICTIONARY_CACHE_DIR";

/// Deprecated alias of [`CACHE_DIR_ENV`], kept as a fallback for backward
/// compatibility. It will be removed in v6.0.0.
const CACHE_DIR_ENV_DEPRECATED: &str = "LINDERA_DICTIONARIES_PATH";

/// Selects the cache directory from the new and deprecated variable values.
/// The new name takes precedence when both are set.
///
/// # Arguments
///
/// * `new` - Value of [`CACHE_DIR_ENV`], if set.
/// * `deprecated` - Value of [`CACHE_DIR_ENV_DEPRECATED`], if set.
///
/// # Returns
///
/// The cache directory to use, or `None` when neither variable is set.
fn resolve_cache_dir(new: Option<OsString>, deprecated: Option<OsString>) -> Option<OsString> {
    new.or(deprecated)
}

/// Reads the dictionary build cache directory from the environment,
/// honoring the deprecated variable name as a fallback.
///
/// # Returns
///
/// The configured cache directory, or `None` when neither
/// [`CACHE_DIR_ENV`] nor [`CACHE_DIR_ENV_DEPRECATED`] is set.
fn dictionary_cache_dir_from_env() -> Option<OsString> {
    resolve_cache_dir(
        std::env::var_os(CACHE_DIR_ENV),
        std::env::var_os(CACHE_DIR_ENV_DEPRECATED),
    )
}

/// Fetch the necessary assets and then build the dictionary using `builder`.
///
/// # Arguments
///
/// * `params` - Describes the asset to fetch (archive name, mirrors, MD5 hash)
///   and the input/output directory layout of the dictionary build.
/// * `builder` - Dictionary builder that turns the extracted MeCab sources into
///   the Lindera dictionary format.
///
/// # Returns
///
/// `Ok(())` once the dictionary has been built into the output directory, or a
/// `LinderaError` if the download, extraction, or build fails.
/// Whether a cached dictionary directory was built in the format this crate
/// reads.
///
/// Anything unexpected -- a missing or unreadable `metadata.json`, a version
/// that does not match -- answers `false`, so the caller rebuilds. A cache is
/// an optimization; refusing to use a questionable one costs a rebuild,
/// whereas trusting one costs correctness.
///
/// # Arguments
///
/// * `output_dir` - The cached dictionary directory to inspect.
///
/// # Returns
///
/// `true` only when `metadata.json` is present, parses, and declares
/// [`DICTIONARY_FORMAT_VERSION`].
fn cached_dictionary_is_current(output_dir: &Path) -> bool {
    let path = output_dir.join("metadata.json");
    let Ok(data) = fs::read(&path) else {
        debug!("Cache miss: cannot read {}", path.display());
        return false;
    };
    let Ok(metadata) = serde_json::from_slice::<Metadata>(&data) else {
        debug!("Cache miss: cannot parse {}", path.display());
        return false;
    };
    if metadata.format_version != DICTIONARY_FORMAT_VERSION {
        debug!(
            "Cache miss: {} declares dictionary format version {}, expected {}",
            path.display(),
            metadata.format_version,
            DICTIONARY_FORMAT_VERSION
        );
        return false;
    }
    true
}

pub fn fetch(params: FetchParams, builder: DictionaryBuilder) -> LinderaResult<()> {
    println!("cargo:rerun-if-changed=build.rs");
    println!("cargo:rerun-if-changed=Cargo.toml");
    // `metadata.json` drives build-time behavior (schema, flags such as
    // `connection_id_mapping`), so a change to it must rebuild the dictionary.
    println!("cargo:rerun-if-changed=metadata.json");
    println!("cargo:rerun-if-changed={CONTEXT_ID_FREQ_FILE}");
    println!("cargo:rerun-if-env-changed=LINDERA_CTX_FREQ_FILE");
    println!("cargo:rerun-if-env-changed={CACHE_DIR_ENV}");
    println!("cargo:rerun-if-env-changed={CACHE_DIR_ENV_DEPRECATED}");
    println!("cargo:rerun-if-env-changed=DOCS_RS");

    if std::env::var_os(CACHE_DIR_ENV).is_none()
        && std::env::var_os(CACHE_DIR_ENV_DEPRECATED).is_some()
    {
        println!(
            "cargo:warning={CACHE_DIR_ENV_DEPRECATED} is deprecated and will be removed in v6.0.0; use {CACHE_DIR_ENV} instead"
        );
    }

    // Directory path for build package
    // if the cache directory variable is defined, behaves like a cache, where data is invalidated only:
    // - on new lindera-assets version
    // - if the cache directory changed
    // otherwise, keeps behavior of always redownloading and rebuilding
    let (build_dir, is_cache) = if let Some(path) = dictionary_cache_dir_from_env() {
        let mut cache_dir = PathBuf::from(path);
        if !cache_dir.is_absolute()
            && let Ok(current_dir) = std::env::current_dir()
        {
            // If current_dir is a crate directory in a workspace, try to find the workspace root
            let mut root_dir = current_dir.clone();
            if let Some(parent) = current_dir.parent()
                && parent.join("Cargo.toml").exists()
            {
                root_dir = parent.to_path_buf();
            }
            cache_dir = root_dir.join(cache_dir);
        }

        let pkg_version = std::env::var("CARGO_PKG_VERSION").map_err(|_| {
            LinderaErrorKind::Io.with_error(anyhow::anyhow!(
                "CARGO_PKG_VERSION environment variable is not set"
            ))
        })?;

        // The dictionary format version is part of the cache key, not just the
        // crate version. Without it, bumping a dependency whose serialized
        // form is written verbatim -- crawdad for `dict.trie`, rkyv for
        // `char_def.bin`/`unk.bin` -- while reusing a cache directory would
        // serve artifacts in the old layout to a binary that walks a
        // different one. Keying on the format version turns that into a
        // cache miss.
        (
            cache_dir.join(format!("{pkg_version}-fmt{DICTIONARY_FORMAT_VERSION}")),
            true,
        )
    } else {
        (
            PathBuf::from(std::env::var_os("OUT_DIR").ok_or_else(|| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!("OUT_DIR environment variable is not set"))
            })?), /* ex) target/debug/build/<pkg>/out */
            false,
        )
    };

    // environment variable passed to dependents, that will actually be used to include the dictionary in the library
    println!("cargo::rustc-env=LINDERA_WORKDIR={}", build_dir.display());

    fs::create_dir_all(&build_dir).map_err(|err| {
        LinderaErrorKind::Io
            .with_error(anyhow::anyhow!(err))
            .add_context(format!("Failed to create build directory: {build_dir:?}"))
    })?;

    let input_dir = build_dir.join(params.input_dir);

    let output_dir = build_dir.join(params.output_dir);

    // Fast path where the data is already in cache.
    //
    // The directory name already carries the format version, so a mismatch is
    // normally a cache miss rather than a stale hit. This re-reads the cached
    // `metadata.json` anyway, because the cheap failure mode -- an interrupted
    // build that left a half-written directory behind, or a directory copied
    // in by hand -- is not covered by the key, and a stale artifact would be
    // embedded verbatim into the binary. A cache entry that fails the check
    // is rebuilt rather than trusted.
    if is_cache && output_dir.is_dir() && cached_dictionary_is_current(&output_dir) {
        return Ok(());
    }

    if std::env::var("DOCS_RS").is_ok() {
        create_dummy_dictionary_source(&input_dir, params.src_subdir, params.dummy_input)?;
    } else {
        // Source file path for build package
        let source_path_for_build = &build_dir.join(params.file_name);

        // Check if source file already exists and is valid
        let need_download = if source_path_for_build.exists() {
            debug!(
                "Found existing source file: {}",
                source_path_for_build.display()
            );

            // Verify MD5 hash
            let mut file = File::open(source_path_for_build).map_err(|err| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!(err))
                    .add_context(format!(
                        "Failed to open source file for MD5 check: {source_path_for_build:?}"
                    ))
            })?;
            let mut context = Context::new();
            let mut buffer = [0; 8192];
            loop {
                let count = file.read(&mut buffer).map_err(|err| {
                    LinderaErrorKind::Io
                        .with_error(anyhow::anyhow!(err))
                        .add_context(format!(
                            "Failed to read source file for MD5 check: {source_path_for_build:?}"
                        ))
                })?;
                if count == 0 {
                    break;
                }
                context.consume(&buffer[..count]);
            }
            let actual_md5 = format!("{:x}", context.finalize());

            if actual_md5 == params.md5_hash {
                debug!("MD5 check passed for cached file. Skipping download.");
                false
            } else {
                warn!(
                    "MD5 mismatch for cached file. Expected: {}, Actual: {}",
                    params.md5_hash, actual_md5
                );
                // Remove invalid file
                fs::remove_file(source_path_for_build).map_err(|err| {
                    LinderaErrorKind::Io
                        .with_error(anyhow::anyhow!(err))
                        .add_context(format!(
                            "Failed to remove invalid source file: {source_path_for_build:?}"
                        ))
                })?;
                true
            }
        } else {
            debug!("Source file not found. Will download.");
            true
        };

        if need_download {
            // Download source file to build directory
            let tmp_download_path =
                Path::new(&build_dir).join(params.file_name.to_owned() + ".download");

            // Download a tarball. `http_status_as_error` is turned off so that a
            // non-2xx response is reported per URL and the next mirror is tried,
            // rather than aborting the round.
            let agent: Agent = Agent::config_builder()
                .user_agent(format!("Lindera/{}", env!("CARGO_PKG_VERSION")))
                .http_status_as_error(false)
                .build()
                .into();

            debug!("Downloading {:?}", params.download_urls);
            let mut dest = File::create(tmp_download_path.as_path()).map_err(|err| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!(err))
                    .add_context(format!(
                        "Failed to create temporary download file: {tmp_download_path:?}"
                    ))
            })?;
            let content = download_with_retry(
                &agent,
                params.download_urls.to_vec(),
                MAX_ROUND,
                params.md5_hash,
            )
            .map_err(|err| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!("{err}"))
                    .add_context("Failed to download dictionary assets")
            })?;

            io::copy(&mut Cursor::new(content.as_slice()), &mut dest).map_err(|err| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!(err))
                    .add_context(format!(
                        "Failed to copy downloaded content to file: {tmp_download_path:?}"
                    ))
            })?;
            dest.flush().map_err(|err| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!(err))
                    .add_context(format!(
                        "Failed to flush download file: {tmp_download_path:?}"
                    ))
            })?;
            drop(dest);

            debug!("Content-Length: {}", content.len());
            debug!("Downloaded to {}", tmp_download_path.display());
            rename(tmp_download_path.clone(), source_path_for_build).map_err(|err| {
                LinderaErrorKind::Io
                    .with_error(anyhow::anyhow!(err))
                    .add_context(format!(
                        "Failed to rename temporary download file: {tmp_download_path:?} to {source_path_for_build:?}"
                    ))
            })?;

            info!("Source file cached at: {}", source_path_for_build.display());
        }

        // Decompress a tar.gz file
        let tmp_extract_path =
            Path::new(&build_dir).join(format!("tmp-archive-{}", params.input_dir));
        let tmp_extracted_path = tmp_extract_path.join(params.input_dir);
        let _ = fs::remove_dir_all(&tmp_extract_path);
        fs::create_dir_all(&tmp_extract_path).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!(
                    "Failed to create temporary extraction directory: {tmp_extract_path:?}"
                ))
        })?;

        let mut tar_gz = File::open(source_path_for_build).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!(
                    "Failed to open source file: {source_path_for_build:?}"
                ))
        })?;
        let mut buffer = Vec::new();
        tar_gz.read_to_end(&mut buffer).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!(
                    "Failed to read source file: {source_path_for_build:?}"
                ))
        })?;
        let cursor = Cursor::new(buffer);
        let decoder = GzDecoder::new(cursor);
        let mut archive = Archive::new(decoder);
        archive.unpack(&tmp_extract_path).map_err(|err| {
            LinderaErrorKind::Io
                .with_error(anyhow::anyhow!(err))
                .add_context(format!(
                    "Failed to unpack archive: {source_path_for_build:?} to {tmp_extract_path:?}"
                ))
        })?;

        // Empty the input directory first to avoid conflicts when renaming the directory later on Linux and macOS systems (which do not support overwriting directories).
        empty_directory(&input_dir)?;

        rename_directory(&tmp_extracted_path, &input_dir)?;

        let _ = fs::remove_dir_all(&tmp_extract_path);
    }

    let tmp_output_path = build_dir.join(format!("tmp-output-{}", params.output_dir));
    let _ = fs::remove_dir_all(&tmp_output_path);

    let build_input_dir = match params.src_subdir {
        Some(subdir) => input_dir.join(subdir),
        None => input_dir.clone(),
    };

    builder
        .build_dictionary(&build_input_dir, &tmp_output_path)
        .map_err(|err| {
            LinderaErrorKind::Build
                .with_error(anyhow::anyhow!("{err}"))
                .add_context("Failed to build dictionary")
        })?;

    // Empty the output directory
    empty_directory(&output_dir)?;

    // Rename tmp_output_path to output_dir
    rename_directory(&tmp_output_path, &output_dir)?;

    let _ = fs::remove_dir_all(input_dir);

    Ok(())
}

/// Shared body of every per-dictionary crate's `build.rs`.
///
/// Name of the optional per-dictionary context-ID access-frequency histogram,
/// shipped in the dictionary crate root next to `metadata.json`. Produced by the
/// `ctxfreq` instrumentation (see the `ctxfreq_dump` example) and consumed when
/// `connection_id_mapping` is enabled.
const CONTEXT_ID_FREQ_FILE: &str = "context_id_freq.txt";

/// Reads `metadata.json` from the crate root, fetches and builds the
/// dictionary described by `params`, and embeds the result under
/// `LINDERA_WORKDIR`.
///
/// When the crate's embed feature is disabled (`embed_enabled == false`) and
/// no cache override is set via `LINDERA_BUILD_DICTIONARY_CACHE_DIR` (or its
/// deprecated alias `LINDERA_DICTIONARIES_PATH`), this is a no-op so the
/// crate builds without downloading any data.
///
/// # Arguments
///
/// * `embed_enabled` - Whether the calling crate's embed feature is enabled,
///   i.e. whether the built dictionary is compiled into the binary.
/// * `params` - Describes the asset to fetch (archive name, mirrors, MD5 hash)
///   and the input/output directory layout of the dictionary build.
///
/// # Returns
///
/// `Ok(())` once the dictionary has been built, or when the build was skipped
/// because neither the embed feature nor a cache override is set. Returns an
/// error if `metadata.json` cannot be read or the dictionary build fails.
pub fn build_embedded_dictionary(
    embed_enabled: bool,
    params: FetchParams,
) -> Result<(), Box<dyn Error>> {
    if dictionary_cache_dir_from_env().is_none() && !embed_enabled {
        return Ok(());
    }

    let metadata_json = fs::read_to_string("metadata.json")?;
    let metadata: crate::dictionary::metadata::Metadata = serde_json::from_str(&metadata_json)?;
    let mut builder = DictionaryBuilder::new(metadata);

    // A dictionary crate may ship a context-ID access-frequency histogram next to
    // `metadata.json`; it is what makes `connection_id_mapping` actually pay off.
    if std::path::Path::new(CONTEXT_ID_FREQ_FILE).is_file() {
        builder = builder.with_context_id_freq(CONTEXT_ID_FREQ_FILE);
    }

    fetch(params, builder)?;

    Ok(())
}

#[cfg(test)]
mod tests {
    use std::ffi::OsString;

    #[test]
    fn resolve_cache_dir_prefers_new_name() {
        let result = super::resolve_cache_dir(
            Some(OsString::from("/new")),
            Some(OsString::from("/deprecated")),
        );
        assert_eq!(result, Some(OsString::from("/new")));
    }

    #[test]
    fn resolve_cache_dir_falls_back_to_deprecated_name() {
        let result = super::resolve_cache_dir(None, Some(OsString::from("/deprecated")));
        assert_eq!(result, Some(OsString::from("/deprecated")));
    }

    #[test]
    fn resolve_cache_dir_returns_none_when_unset() {
        assert_eq!(super::resolve_cache_dir(None, None), None);
    }

    use super::*;

    #[test]
    fn test_create_dummy_dictionary_source_without_subdir() {
        let temp_dir = tempfile::tempdir().unwrap();
        let input_dir = temp_dir.path().join("mecab-test");

        create_dummy_dictionary_source(&input_dir, None, "dummy,0,0,0\n").unwrap();

        assert!(input_dir.join("char.def").is_file());
        assert!(input_dir.join("dummy_dict.csv").is_file());
        assert!(input_dir.join("unk.def").is_file());
        assert!(input_dir.join("matrix.def").is_file());
        assert_eq!(
            fs::read_to_string(input_dir.join("dummy_dict.csv")).unwrap(),
            "dummy,0,0,0\n"
        );
    }

    #[test]
    fn test_create_dummy_dictionary_source_with_subdir() {
        let temp_dir = tempfile::tempdir().unwrap();
        let input_dir = temp_dir.path().join("mecab-test");

        create_dummy_dictionary_source(&input_dir, Some("dict-src"), "dummy,0,0,0\n").unwrap();

        // Files must be scaffolded where the dictionary builder reads from:
        // `input_dir/dict-src`, not `input_dir` itself.
        let src_dir = input_dir.join("dict-src");
        assert!(src_dir.join("char.def").is_file());
        assert!(src_dir.join("dummy_dict.csv").is_file());
        assert!(src_dir.join("unk.def").is_file());
        assert!(src_dir.join("matrix.def").is_file());
        assert!(!input_dir.join("char.def").exists());
    }

    #[test]
    fn test_create_dummy_dictionary_source_is_idempotent() {
        let temp_dir = tempfile::tempdir().unwrap();
        let input_dir = temp_dir.path().join("mecab-test");

        // A second run against the same directory must succeed because docs.rs
        // reuses the build target directory across runs.
        create_dummy_dictionary_source(&input_dir, Some("dict-src"), "dummy,0,0,0\n").unwrap();
        create_dummy_dictionary_source(&input_dir, Some("dict-src"), "dummy,0,0,0\n").unwrap();

        assert!(input_dir.join("dict-src").join("char.def").is_file());
    }

    /// Writes `metadata.json` declaring `format_version` into a fresh
    /// directory, standing in for a cached dictionary build.
    fn cached_dir_with_format_version(version: u32) -> tempfile::TempDir {
        let dir = tempfile::tempdir().unwrap();
        let metadata = Metadata {
            format_version: version,
            ..Metadata::default()
        };
        fs::write(
            dir.path().join("metadata.json"),
            serde_json::to_vec_pretty(&metadata).unwrap(),
        )
        .unwrap();
        dir
    }

    #[test]
    fn cache_hit_requires_the_current_format_version() {
        let dir = cached_dir_with_format_version(DICTIONARY_FORMAT_VERSION);
        assert!(cached_dictionary_is_current(dir.path()));
    }

    #[test]
    fn cache_from_another_format_version_is_a_miss() {
        // The directory name normally keys on the format version, so this
        // covers the leftovers: a hand-copied directory, or one from an
        // interrupted build.
        let dir = cached_dir_with_format_version(DICTIONARY_FORMAT_VERSION + 1);
        assert!(!cached_dictionary_is_current(dir.path()));
    }

    #[test]
    fn cache_without_metadata_is_a_miss() {
        let dir = tempfile::tempdir().unwrap();
        assert!(!cached_dictionary_is_current(dir.path()));
    }

    #[test]
    fn cache_with_unparsable_metadata_is_a_miss() {
        // A half-written metadata.json from an interrupted build must not be
        // trusted; rebuilding is cheap, misreading a dictionary is not.
        let dir = tempfile::tempdir().unwrap();
        fs::write(dir.path().join("metadata.json"), b"{\"name\":").unwrap();
        assert!(!cached_dictionary_is_current(dir.path()));
    }
}