dream_archivetool 0.1.0

Inspect, extract, create, and update Bethesda BSA and BA2 archives
Documentation
// SPDX-License-Identifier: GPL-3.0-or-later

use std::collections::BTreeMap;
use std::io;
use std::path::Path;

use serde::{Deserialize, Serialize};

use crate::paths::{
    archive_path_bytes_to_display, archive_path_bytes_to_hex, safe_target_path_normalized,
};
use crate::{ArchiveFormat, Result};

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
/// Options controlling archive verification.
pub struct VerifyOptions {
    /// Attempt to stream every named payload to a sink to check that extraction succeeds.
    ///
    /// Payload reads are skipped when duplicate normalized paths prevent proving per-entry
    /// coverage; the report will include a warning in that case.
    pub read_payloads: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Archive verification report suitable for CLI and GUI callers.
#[non_exhaustive]
pub struct VerifyReport {
    /// Archive label/path formatted for display.
    pub path: String,
    /// Detected archive family.
    pub format: ArchiveFormat,
    /// Total file entries in the archive.
    pub file_count: usize,
    /// Entries with recoverable path names.
    pub named_entry_count: usize,
    /// Entries without recoverable path names.
    pub unnameable_entries: usize,
    /// Whether this tool can rewrite the archive without known lossy behavior.
    pub rewritable: bool,
    /// Explanation when `rewritable` is false.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rewrite_blocker: Option<String>,
    /// Duplicate normalized lookup paths found in the archive.
    pub duplicate_normalized_paths: Vec<VerifyPathIssue>,
    /// Paths rejected by safe extraction target validation.
    pub unsafe_paths: Vec<VerifyPathIssue>,
    /// Number of payloads streamed when payload verification was requested and possible.
    pub payloads_read: Option<usize>,
    /// Non-fatal verification warnings.
    pub warnings: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
/// Path-level issue reported by verification.
#[non_exhaustive]
pub struct VerifyPathIssue {
    /// Archive path formatted for display.
    pub path: String,
    /// Hex-encoded normalized archive-path lookup key, not raw identity.
    pub path_bytes_hex: String,
    /// Hex-encoded raw archive path bytes for the entry being reported.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub raw_path_bytes_hex: Option<String>,
    /// Hex-encoded raw path bytes for a previous entry with the same normalized lookup key.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub colliding_raw_path_bytes_hex: Option<String>,
}

/// Verify archive index health and, optionally, payload readability.
///
/// # Errors
///
/// Returns an error if the archive cannot be opened or payload verification cannot read requested
/// entry data.
pub fn verify_archive(path: &Path, options: &VerifyOptions) -> Result<VerifyReport> {
    let archive = crate::loaded::LoadedArchive::open(path)?;
    verify_loaded_archive(&path.display().to_string(), archive.as_ref(), *options)
}

pub(crate) fn verify_loaded_archive(
    label: &str,
    archive: crate::loaded::LoadedArchiveRef<'_>,
    options: VerifyOptions,
) -> Result<VerifyReport> {
    let info = crate::archive::archive_info_ref(label, archive);
    let entries = archive.list_loaded_entries()?;
    let mut seen: BTreeMap<Vec<u8>, Vec<u8>> = BTreeMap::new();
    let mut duplicate_normalized_paths = Vec::new();
    let mut unsafe_paths = Vec::new();

    for entry in &entries {
        if let Some(previous_raw_path) = seen.get(&entry.path) {
            duplicate_normalized_paths.push(duplicate_path_issue(
                &entry.path,
                previous_raw_path,
                &entry.raw_path,
            ));
        } else {
            seen.insert(entry.path.clone(), entry.raw_path.clone());
        }
        if crate::paths::validate_archive_path_bytes_for_extraction(&entry.raw_path).is_err()
            || safe_target_path_normalized(Path::new("."), &entry.path).is_err()
        {
            unsafe_paths.push(path_issue(&entry.raw_path));
        }
    }

    let payloads_read = if options.read_payloads && duplicate_normalized_paths.is_empty() {
        let mut sink = io::sink();
        for entry in &entries {
            archive.extract_normalized_entry_path_to_writer(&entry.path, &mut sink)?;
        }
        Some(entries.len())
    } else {
        None
    };

    let mut warnings = Vec::new();
    if info.has_unnameable_entries {
        warnings.push("archive contains entries without recoverable path names".to_string());
    }
    if !duplicate_normalized_paths.is_empty() {
        warnings.push("archive contains duplicate normalized paths".to_string());
    }
    if options.read_payloads && !duplicate_normalized_paths.is_empty() {
        warnings.push(
            "payload read verification skipped because duplicate normalized paths prevent per-entry coverage"
                .to_string(),
        );
    }
    if !unsafe_paths.is_empty() {
        warnings.push("archive contains paths unsafe to extract directly".to_string());
    }
    Ok(VerifyReport {
        path: info.path,
        format: info.format,
        file_count: info.file_count,
        named_entry_count: info.named_entry_count,
        unnameable_entries: info.file_count.saturating_sub(info.named_entry_count),
        rewritable: info.rewritable,
        rewrite_blocker: info.rewrite_blocker,
        duplicate_normalized_paths,
        unsafe_paths,
        payloads_read,
        warnings,
    })
}

fn path_issue(path: &[u8]) -> VerifyPathIssue {
    VerifyPathIssue {
        path: archive_path_bytes_to_display(path),
        path_bytes_hex: archive_path_bytes_to_hex(path),
        raw_path_bytes_hex: None,
        colliding_raw_path_bytes_hex: None,
    }
}

fn duplicate_path_issue(
    path: &[u8],
    first_raw_path: &[u8],
    duplicate_raw_path: &[u8],
) -> VerifyPathIssue {
    VerifyPathIssue {
        path: archive_path_bytes_to_display(path),
        path_bytes_hex: archive_path_bytes_to_hex(path),
        raw_path_bytes_hex: Some(archive_path_bytes_to_hex(duplicate_raw_path)),
        colliding_raw_path_bytes_hex: Some(archive_path_bytes_to_hex(first_raw_path)),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn duplicate_path_issue_reports_duplicate_then_previous_raw_path() {
        let issue = duplicate_path_issue(
            b"textures/example.dds",
            b"Textures/Example.dds",
            b"textures/example.dds",
        );

        assert_eq!(
            issue.path_bytes_hex,
            "74657874757265732f6578616d706c652e646473"
        );
        assert_eq!(
            issue.raw_path_bytes_hex.as_deref(),
            Some("74657874757265732f6578616d706c652e646473")
        );
        assert_eq!(
            issue.colliding_raw_path_bytes_hex.as_deref(),
            Some("54657874757265732f4578616d706c652e646473")
        );
    }
}