//! ZIP file manipulation module for C API exposure

//!

//! Provides a ZipFile struct for reading/writing ZIP archives.

use alloc::string::String;

use alloc::vec::Vec;

use alloc::format;

use core::fmt;

#[cfg(feature = "std")]

use std::path::Path;

// ============================================================================

// Configuration types

// ============================================================================

/// Configuration for reading ZIP archives

#[derive(Copy, Debug, Clone, Default)]

#[repr(C)]

pub struct ZipReadConfig {

    /// Maximum file size to extract (0 = unlimited)

    pub max_file_size: u64,

    /// Whether to allow paths with ".." (path traversal) - default: false

    pub allow_path_traversal: bool,

    /// Whether to skip encrypted files instead of erroring - default: false  

    pub skip_encrypted: bool,

}

impl ZipReadConfig {

}

/// Configuration for writing ZIP archives

#[derive(Debug, Clone)]

#[repr(C)]

pub struct ZipWriteConfig {

    /// Compression method: 0 = Store (no compression), 1 = Deflate

    pub compression_method: u8,

    /// Compression level (0-9, only for Deflate)

    pub compression_level: u8,

    /// Unix permissions for files (default: 0o644)

    pub unix_permissions: u32,

    /// Archive comment

    pub comment: String,

}

impl Default for ZipWriteConfig {

}

impl ZipWriteConfig {

    #[must_use]

}

// ============================================================================

// Entry types

// ============================================================================

/// Path entry in a ZIP archive (metadata only, no data)

#[derive(Debug, Clone)]

#[repr(C)]

pub struct ZipPathEntry {

    /// File path within the archive

    pub path: String,

    /// Whether this is a directory

    pub is_directory: bool,

    /// Uncompressed size in bytes

    pub size: u64,

    /// Compressed size in bytes

    pub compressed_size: u64,

    /// CRC32 checksum

    pub crc32: u32,

}

/// Vec of `ZipPathEntry`

pub type ZipPathEntryVec = Vec<ZipPathEntry>;

/// File entry in a ZIP archive (with data, for writing)

#[derive(Debug, Clone)]

#[repr(C)]

pub struct ZipFileEntry {

    /// File path within the archive

    pub path: String,

    /// File contents (empty for directories)

    pub data: Vec<u8>,

    /// Whether this is a directory

    pub is_directory: bool,

}

impl ZipFileEntry {

    /// Create a new file entry

    /// Create a new directory entry

}

/// Vec of `ZipFileEntry`  

pub type ZipFileEntryVec = Vec<ZipFileEntry>;

// ============================================================================

// Error types

// ============================================================================

/// Error when reading ZIP archives

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C, u8)]

pub enum ZipReadError {

    /// Invalid ZIP format

    InvalidFormat(String),

    /// File not found in archive

    FileNotFound(String),

    /// I/O error

    IoError(String),

    /// Path traversal attack detected

    UnsafePath(String),

    /// File is encrypted (unsupported)

    EncryptedFile(String),

    /// File too large

    FileTooLarge { path: String, size: u64, max_size: u64 },

}

impl fmt::Display for ZipReadError {

            }

        }

}

#[cfg(feature = "std")]

impl std::error::Error for ZipReadError {}

/// Error when writing ZIP archives

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C, u8)]

pub enum ZipWriteError {

    /// I/O error

    IoError(String),

    /// Invalid path

    InvalidPath(String),

    /// Compression error

    CompressionError(String),

}

impl fmt::Display for ZipWriteError {

        }

}

#[cfg(feature = "std")]

impl std::error::Error for ZipWriteError {}

// ============================================================================

// ZipFile struct

// ============================================================================

/// A ZIP archive that can be read from or written to

#[derive(Debug, Clone, Default)]

#[repr(C)]

pub struct ZipFile {

    /// The entries in the archive

    pub entries: ZipFileEntryVec,

}

impl ZipFile {

    /// Create a new empty ZIP archive

    /// List contents of a ZIP archive without loading file data

    /// 

    /// # Arguments

    /// * `data` - ZIP file bytes

    /// * `config` - Read configuration

    /// 

    /// # Returns

    /// List of path entries (metadata only)

    #[cfg(feature = "zip")]

    /// # Errors

    ///

    /// Returns a `ZipReadError` if the archive is malformed or cannot be read.

        use std::io::Cursor;

            // Security check

        }

    /// Extract a single file from ZIP data

    /// 

    /// # Arguments

    /// * `data` - ZIP file bytes

    /// * `entry` - The path entry to extract

    /// * `config` - Read configuration

    /// 

    /// # Returns

    /// The file contents, or None if not found

    #[cfg(feature = "zip")]

    /// # Errors

    ///

    /// Returns a `ZipReadError` if the archive is malformed or cannot be read.

        use std::io::{Cursor, Read};

        // Size check

        };

    /// Load a ZIP archive from bytes

    /// 

    /// # Arguments

    /// * `data` - ZIP file bytes (borrowed)

    /// * `config` - Read configuration

    #[cfg(feature = "zip")]

    /// # Errors

    ///

    /// Returns a `ZipReadError` if the archive is malformed or cannot be read.

        use std::io::{Cursor, Read};

            // Security check

            // Size check

        }

    /// Load a ZIP archive from a file path

    #[cfg(all(feature = "zip", feature = "std"))]

    /// # Errors

    ///

    /// Returns a `ZipReadError` if the archive is malformed or cannot be read.

    /// Write the ZIP archive to bytes

    /// 

    /// # Arguments

    /// * `config` - Write configuration

    #[cfg(feature = "zip")]

    /// # Errors

    ///

    /// Returns a `ZipWriteError` if the archive cannot be built or written.

        use std::io::{Cursor, Write};

        use zip::write::SimpleFileOptions;

        // Set archive comment

        };

            } else {

            }

        }

    /// Write the ZIP archive to a file

    #[cfg(all(feature = "zip", feature = "std"))]

    /// # Errors

    ///

    /// Returns a `ZipWriteError` if the archive cannot be built or written.

    // ========================================================================

    // Convenience methods for modifying the archive

    // ========================================================================

    /// Add a file entry (consumes the data, no clone)

        // Remove existing entry with same path

    /// Add a directory entry

    /// Remove an entry by path

    /// Get an entry by path

    /// Check if archive contains a path

    /// Get list of all paths

    /// Filter entries by suffix (e.g., ".fluent", ".json")

}

// ============================================================================

// Convenience functions (for simpler use cases)

// ============================================================================

/// Create a ZIP archive from file entries (consumes entries, no clone)

#[cfg(feature = "zip")]

/// # Errors

///

/// Returns a `ZipWriteError` if the archive cannot be built or written.

/// Create a ZIP archive from path/data pairs (consumes entries, no clone)

#[cfg(feature = "zip")]

/// # Errors

///

/// Returns a `ZipWriteError` if the archive cannot be built or written.

/// Extract all files from ZIP data

#[cfg(feature = "zip")]

/// # Errors

///

/// Returns a `ZipReadError` if the archive is malformed or cannot be read.

/// List contents of ZIP data without extracting

#[cfg(feature = "zip")]

/// # Errors

///

/// Returns a `ZipReadError` if the archive is malformed or cannot be read.

// ============================================================================

// Tests

// ============================================================================

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    #[test]

    #[cfg(feature = "zip")]

    #[test]

        ];

    #[cfg(feature = "zip")]

    #[test]

        // Overwrite existing

}

// ============================================================================

// Autotest: adversarial tests

// ============================================================================

#[cfg(test)]

mod autotest_generated {

    use super::*;

    // ------------------------------------------------------------------

    // helpers

    // ------------------------------------------------------------------

    /// A ZIP that this module can actually produce: default (Deflate/6) config.

    #[cfg(feature = "zip")]

    fn build(entries: Vec<ZipFileEntry>) -> Vec<u8> {

        zip_create(entries, &ZipWriteConfig::default()).expect("default write config must work")

    }

    /// Hand-rolled 22-byte "end of central directory" record = an empty archive.

    #[cfg(feature = "zip")]

    fn eocd_only() -> Vec<u8> {

        let mut v = vec![0x50, 0x4B, 0x05, 0x06];

        v.extend_from_slice(&[0u8; 18]);

        v

    }

    /// Adversarial path strings reused across the lookup tests.

    fn nasty_paths() -> Vec<String> {

        vec![

            String::new(),

            "   ".to_string(),

            "\t\n".to_string(),

            "\0".to_string(),

            "a\0b".to_string(),

            "..".to_string(),

            "../../etc/passwd".to_string(),

            "./a.txt".to_string(),

            "a.txt ".to_string(),

            " a.txt".to_string(),

            "a.txt;garbage".to_string(),

            "0".to_string(),

            "-0".to_string(),

            "NaN".to_string(),

            "inf".to_string(),

            "-inf".to_string(),

            "9223372036854775807".to_string(),

            "-9223372036854775808".to_string(),

            "18446744073709551615".to_string(),

            "1e309".to_string(),

            "\u{1F600}".to_string(),

            "e\u{0301}\u{0301}\u{0301}.txt".to_string(),

            "\u{202E}txt.exe".to_string(),

            "\u{FEFF}a.txt".to_string(),

            "A/".repeat(2000),

            "x".repeat(100_000),

        ]

    }

    // ==================================================================

    // constructors / config (feature-independent)

    // ==================================================================

    #[test]

    fn autotest_read_config_builders_at_numeric_extremes() {

        let base = ZipReadConfig::new();

        let def = ZipReadConfig::default();

        assert_eq!(base.max_file_size, def.max_file_size);

        assert_eq!(base.allow_path_traversal, def.allow_path_traversal);

        assert_eq!(base.skip_encrypted, def.skip_encrypted);

        assert_eq!(base.max_file_size, 0);

        assert!(!base.allow_path_traversal);

        assert!(!base.skip_encrypted);

        for size in [0u64, 1, u64::from(u32::MAX), u64::MAX / 2, u64::MAX - 1, u64::MAX] {

            let c = ZipReadConfig::new().with_max_file_size(size);

            assert_eq!(c.max_file_size, size);

            // the other fields must not be perturbed by the builder

            assert!(!c.allow_path_traversal);

            assert!(!c.skip_encrypted);

        }

        for allow in [false, true] {

            let c = ZipReadConfig::new()

                .with_max_file_size(u64::MAX)

                .with_allow_path_traversal(allow);

            assert_eq!(c.allow_path_traversal, allow);

            assert_eq!(c.max_file_size, u64::MAX);

        }

        // builders are order-independent and idempotent

        let a = ZipReadConfig::new().with_max_file_size(7).with_allow_path_traversal(true);

        let b = ZipReadConfig::new().with_allow_path_traversal(true).with_max_file_size(7);

        assert_eq!(a.max_file_size, b.max_file_size);

        assert_eq!(a.allow_path_traversal, b.allow_path_traversal);

        let c = a.with_max_file_size(7);

        assert_eq!(c.max_file_size, 7);

        assert!(c.allow_path_traversal);

        // ZipReadConfig is Copy: the "consumed" value is still usable

        let orig = ZipReadConfig::new();

        let _moved = orig.with_max_file_size(99);

        assert_eq!(orig.max_file_size, 0);

    }

    #[test]

    fn autotest_write_config_new_store_and_defaults() {

        let new = ZipWriteConfig::new();

        let def = ZipWriteConfig::default();

        assert_eq!(new.compression_method, def.compression_method);

        assert_eq!(new.compression_level, def.compression_level);

        assert_eq!(new.unix_permissions, def.unix_permissions);

        assert_eq!(new.comment, def.comment);

        assert_eq!(new.compression_method, 1);

        assert_eq!(new.compression_level, 6);

        assert_eq!(new.unix_permissions, 0o644);

        assert!(new.comment.is_empty());

        let store = ZipWriteConfig::store();

        assert_eq!(store.compression_method, 0);

        assert_eq!(store.compression_level, 0);

        // store() only overrides the two compression fields

        assert_eq!(store.unix_permissions, 0o644);

        assert!(store.comment.is_empty());

    }

    #[test]

    fn autotest_write_config_deflate_saturates_level() {

        // documented clamp is `level.min(9)`; verify across the whole u8 domain

        for level in 0u16..=255 {

            let level = u8::try_from(level).unwrap();

            let cfg = ZipWriteConfig::deflate(level);

            assert_eq!(cfg.compression_method, 1, "deflate() must always select Deflate");

            assert_eq!(

                cfg.compression_level,

                level.min(9),

                "deflate({level}) did not saturate at 9"

            );

            assert!(cfg.compression_level <= 9);

        }

        // explicit boundary spot checks

        assert_eq!(ZipWriteConfig::deflate(0).compression_level, 0);

        assert_eq!(ZipWriteConfig::deflate(9).compression_level, 9);

        assert_eq!(ZipWriteConfig::deflate(10).compression_level, 9);

        assert_eq!(ZipWriteConfig::deflate(u8::MIN).compression_level, 0);

        assert_eq!(ZipWriteConfig::deflate(u8::MAX).compression_level, 9);

    }

    #[test]

    fn autotest_write_config_with_comment_extremes() {

        // empty

        let c = ZipWriteConfig::new().with_comment("");

        assert!(c.comment.is_empty());

        // unicode + control chars + NUL are stored verbatim (no sanitising)

        for s in [

            "\u{1F600}\u{1F9F0}",

            "e\u{0301}combining",

            "line1\nline2\r\n",

            "nul\0inside",

            "\u{202E}rtl",

        ] {

            let c = ZipWriteConfig::new().with_comment(s);

            assert_eq!(c.comment, s);

            assert_eq!(c.comment.chars().count(), s.chars().count());

        }

        // very long comment (well past the u16 EOCD comment-length field)

        let huge = "z".repeat(200_000);

        let c = ZipWriteConfig::new().with_comment(huge.clone());

        assert_eq!(c.comment.len(), 200_000);

        assert_eq!(c.comment, huge);

        // other fields untouched

        assert_eq!(c.compression_method, 1);

        assert_eq!(c.compression_level, 6);

        // with_comment accepts both &str and String, and last write wins

        let c = ZipWriteConfig::store().with_comment("a").with_comment(String::from("b"));

        assert_eq!(c.comment, "b");

        assert_eq!(c.compression_method, 0);

    }

    #[test]

    fn autotest_zip_file_entry_constructors_no_panic() {

        // empty path

        let e = ZipFileEntry::file("", Vec::new());

        assert!(e.path.is_empty());

        assert!(e.data.is_empty());

        assert!(!e.is_directory);

        // path/data extremes

        let long_path = "p".repeat(200_000);

        let e = ZipFileEntry::file(long_path.clone(), vec![0xFFu8; 4096]);

        assert_eq!(e.path, long_path);

        assert_eq!(e.data.len(), 4096);

        assert!(!e.is_directory);

        // non-UTF8-looking bytes as *data* are fine (data is Vec<u8>)

        let e = ZipFileEntry::file("bin", vec![0xFFu8, 0xFE, 0x00, 0x80]);

        assert_eq!(e.data, vec![0xFFu8, 0xFE, 0x00, 0x80]);

        // directory() always discards data and flags is_directory

        for p in nasty_paths() {

            let d = ZipFileEntry::directory(p.clone());

            assert_eq!(d.path, p);

            assert!(d.is_directory);

            assert!(d.data.is_empty());

        }

        // constructors never rewrite the path (no trailing-slash normalisation)

        assert_eq!(ZipFileEntry::directory("sub").path, "sub");

        assert_eq!(ZipFileEntry::directory("sub/").path, "sub/");

    }

    // ==================================================================

    // Display / error serialisation

    // ==================================================================

    #[test]

    fn autotest_read_error_display_all_variants_non_empty() {

        let cases = vec![

            (ZipReadError::InvalidFormat("bad magic".into()), "bad magic"),

            (ZipReadError::FileNotFound("a.txt".into()), "a.txt"),

            (ZipReadError::IoError("eof".into()), "eof"),

            (ZipReadError::UnsafePath("../x".into()), "../x"),

            (ZipReadError::EncryptedFile("s.bin".into()), "s.bin"),

            (

                ZipReadError::FileTooLarge {

                    path: "big".into(),

                    size: 10,

                    max_size: 5,

                },

                "big",

            ),

        ];

        for (err, needle) in cases {

            let s = err.to_string();

            assert!(!s.is_empty(), "empty Display for {err:?}");

            assert!(s.contains(needle), "Display {s:?} lost payload {needle:?}");

            // Debug must also be non-empty and must not equal Display

            assert!(!format!("{err:?}").is_empty());

        }

    }

    #[test]

    fn autotest_read_error_display_edge_payloads() {

        // empty payloads still produce a non-empty, prefixed message

        for err in [

            ZipReadError::InvalidFormat(String::new()),

            ZipReadError::FileNotFound(String::new()),

            ZipReadError::IoError(String::new()),

            ZipReadError::UnsafePath(String::new()),

            ZipReadError::EncryptedFile(String::new()),

        ] {

            let s = err.to_string();

            assert!(!s.is_empty(), "empty payload produced empty Display");

            assert!(s.contains(':'), "expected a prefixed message, got {s:?}");

        }

        // u64 boundaries in FileTooLarge

        for (size, max_size) in [

            (0u64, 0u64),

            (0, u64::MAX),

            (u64::MAX, 0),

            (u64::MAX, u64::MAX),

            (u64::MAX - 1, u64::MAX),

        ] {

            let err = ZipReadError::FileTooLarge {

                path: "\u{1F600}/p".into(),

                size,

                max_size,

            };

            let s = err.to_string();

            assert!(s.contains(&format!("{size}")));

            assert!(s.contains(&format!("{max_size}")));

            assert!(s.contains("\u{1F600}"));

        }

        // unicode / control / NUL payloads round-trip through Display unchanged

        for payload in ["\u{1F600}", "e\u{0301}", "a\0b", "line\nbreak", &"L".repeat(50_000)] {

            let err = ZipReadError::UnsafePath(payload.to_string());

            assert!(err.to_string().contains(payload));

        }

    }

    #[test]

    fn autotest_write_error_display_all_variants_non_empty() {

        let cases = vec![

            (ZipWriteError::IoError("disk full".into()), "disk full"),

            (ZipWriteError::InvalidPath("\u{1F600}".into()), "\u{1F600}"),

            (ZipWriteError::CompressionError("level".into()), "level"),

        ];

        for (err, needle) in cases {

            let s = err.to_string();

            assert!(!s.is_empty());

            assert!(s.contains(needle));

            assert!(s.contains(':'));

        }

        for err in [

            ZipWriteError::IoError(String::new()),

            ZipWriteError::InvalidPath(String::new()),

            ZipWriteError::CompressionError(String::new()),

        ] {

            assert!(!err.to_string().is_empty());

        }

        // huge + NUL payloads do not panic

        let big = ZipWriteError::CompressionError("\0".to_string() + &"q".repeat(100_000));

        assert!(big.to_string().len() >= 100_000);

    }

    #[test]

    fn autotest_error_equality_and_std_error_impls() {

        assert_eq!(

            ZipReadError::UnsafePath("a".into()),

            ZipReadError::UnsafePath("a".into())

        );

        assert_ne!(

            ZipReadError::UnsafePath("a".into()),

            ZipReadError::FileNotFound("a".into())

        );

        assert_ne!(

            ZipReadError::FileTooLarge { path: "p".into(), size: 1, max_size: 2 },

            ZipReadError::FileTooLarge { path: "p".into(), size: 1, max_size: 3 }

        );

        assert_eq!(

            ZipWriteError::IoError("x".into()),

            ZipWriteError::IoError("x".into())

        );

        assert_ne!(

            ZipWriteError::IoError("x".into()),

            ZipWriteError::InvalidPath("x".into())

        );

        // Clone must preserve equality

        let e = ZipReadError::FileTooLarge {

            path: "p".into(),

            size: u64::MAX,

            max_size: 0,

        };

        assert_eq!(e.clone(), e);

        #[cfg(feature = "std")]

        {

            let r: &dyn std::error::Error = &e;

            assert!(!r.to_string().is_empty());

            let w = ZipWriteError::IoError("x".into());

            let r: &dyn std::error::Error = &w;

            assert!(!r.to_string().is_empty());

        }

    }

    // ==================================================================

    // in-memory ZipFile invariants (feature-independent)

    // ==================================================================

    #[test]

    fn autotest_zipfile_new_and_default_are_empty() {

        let a = ZipFile::new();

        let b = ZipFile::default();

        assert!(a.entries.is_empty());

        assert!(b.entries.is_empty());

        assert!(a.paths().is_empty());

        assert!(a.filter_by_suffix("").is_empty());

        assert!(a.filter_by_suffix(".txt").is_empty());

        assert!(a.get("").is_none());

        assert!(!a.contains(""));

        // every adversarial lookup on an empty archive is None/false, never a panic

        for p in nasty_paths() {

            assert!(a.get(&p).is_none());

            assert!(!a.contains(&p));

        }

        // remove on an empty archive is a no-op

        let mut c = ZipFile::new();

        c.remove("nope");

        c.remove("");

        assert!(c.entries.is_empty());

    }

    #[test]

    fn autotest_add_file_dedup_keeps_last_write() {

        let mut zip = ZipFile::new();

        zip.add_file("a", b"1".to_vec());

        zip.add_file("b", b"2".to_vec());

        zip.add_file("a", b"3".to_vec());

        assert_eq!(zip.entries.len(), 2);

        assert_eq!(zip.get("a").unwrap().data, b"3");

        // the replaced entry is re-appended at the end, so order changes

        assert_eq!(zip.paths(), vec!["b", "a"]);

        // repeated writes to the same path never grow the archive

        for i in 0..100u32 {

            zip.add_file("a", format!("{i}").into_bytes());

        }

        assert_eq!(zip.entries.len(), 2);

        assert_eq!(zip.get("a").unwrap().data, b"99");

    }

    #[test]

    fn autotest_add_directory_and_add_file_share_the_path_namespace() {

        let mut zip = ZipFile::new();

        zip.add_file("x", b"data".to_vec());

        assert!(!zip.get("x").unwrap().is_directory);

        // add_directory replaces a file at the same path

        zip.add_directory("x");

        assert_eq!(zip.entries.len(), 1);

        assert!(zip.get("x").unwrap().is_directory);

        assert!(zip.get("x").unwrap().data.is_empty());

        // ...and vice versa

        zip.add_file("x", b"back".to_vec());

        assert_eq!(zip.entries.len(), 1);

        assert!(!zip.get("x").unwrap().is_directory);

        assert_eq!(zip.get("x").unwrap().data, b"back");

        // "x" and "x/" are *different* paths at this layer

        zip.add_directory("x/");

        assert_eq!(zip.entries.len(), 2);

        assert!(zip.contains("x"));

        assert!(zip.contains("x/"));

    }

    #[test]

    fn autotest_add_and_remove_adversarial_paths_no_panic() {

        let mut zip = ZipFile::new();

        let paths = nasty_paths();

        for (i, p) in paths.iter().enumerate() {

            zip.add_file(p.clone(), vec![u8::try_from(i % 256).unwrap()]);

        }

        // nasty_paths() has no duplicates, so every path survived

        assert_eq!(zip.entries.len(), paths.len());

        for p in &paths {

            assert!(zip.contains(p), "lost path {p:?}");

            assert!(zip.get(p).is_some());

        }

        for p in &paths {

            zip.remove(p);

            assert!(!zip.contains(p));

        }

        assert!(zip.entries.is_empty());

        // removing a path that is a *prefix*/*suffix* of a stored path must not match

        let mut zip = ZipFile::new();

        zip.add_file("dir/file.txt", b"d".to_vec());

        zip.remove("dir/");

        zip.remove("file.txt");

        zip.remove("dir/file.tx");

        zip.remove("dir/file.txt ");

        assert_eq!(zip.entries.len(), 1, "remove() must match the whole path only");

        zip.remove("dir/file.txt");

        assert!(zip.entries.is_empty());

    }

    #[test]

    fn autotest_get_and_contains_agree_and_reject_junk() {

        let mut zip = ZipFile::new();

        zip.add_file("a.txt", b"A".to_vec());

        zip.add_file("\u{1F600}.txt", b"E".to_vec());

        zip.add_directory("sub/");

        // exact matches only

        assert!(zip.contains("a.txt"));

        assert!(zip.contains("\u{1F600}.txt"));

        assert!(zip.contains("sub/"));

        // leading/trailing junk, case changes and near-misses are all rejected

        for p in [

            " a.txt", "a.txt ", "A.TXT", "a.txt\0", "./a.txt", "/a.txt", "a.txt;x", "sub", "sub//",

            "\u{1F600}", "\u{1F600}.TXT",

        ] {

            assert!(!zip.contains(p), "unexpected match for {p:?}");

            assert!(zip.get(p).is_none());

        }

        // get()/contains() must never disagree, for any input

        for p in nasty_paths() {

            assert_eq!(zip.get(&p).is_some(), zip.contains(&p), "disagree on {p:?}");

        }

        // a 1M-char probe neither panics nor hangs

        let huge = "y".repeat(1_000_000);

        assert!(zip.get(&huge).is_none());

        assert!(!zip.contains(&huge));

    }

    #[test]

    fn autotest_paths_mirrors_entries_in_order() {

        let mut zip = ZipFile::new();

        assert!(zip.paths().is_empty());

        for i in 0..50u32 {

            zip.add_file(format!("f{i}"), vec![u8::try_from(i).unwrap()]);

        }

        zip.add_directory("d/");

        let paths = zip.paths();

        assert_eq!(paths.len(), zip.entries.len());

        for (p, e) in paths.iter().zip(zip.entries.iter()) {

            assert_eq!(*p, e.path.as_str());

        }

        // directories are included in paths()

        assert!(paths.contains(&"d/"));

        // duplicates constructed directly are all reported

        let dup = ZipFile {

            entries: vec![

                ZipFileEntry::file("same", b"1".to_vec()),

                ZipFileEntry::file("same", b"2".to_vec()),

            ],

        };

        assert_eq!(dup.paths(), vec!["same", "same"]);

        // get() returns the *first* match

        assert_eq!(dup.get("same").unwrap().data, b"1");

        assert!(dup.contains("same"));

        // ...and remove() drops every duplicate

        let mut dup = dup;

        dup.remove("same");

        assert!(dup.entries.is_empty());

    }

    #[test]

    fn autotest_filter_by_suffix_edge_cases() {

        let zip = ZipFile {

            entries: vec![

                ZipFileEntry::file("a.txt", b"1".to_vec()),

                ZipFileEntry::file("b.TXT", b"2".to_vec()),

                ZipFileEntry::file("README", b"3".to_vec()),

                ZipFileEntry::file("", b"4".to_vec()),

                ZipFileEntry::file("\u{1F600}.json", b"5".to_vec()),

                ZipFileEntry::directory("dir.txt"),

                ZipFileEntry::directory("sub/"),

            ],

        };

        // empty suffix matches every *non-directory* entry

        assert_eq!(zip.filter_by_suffix("").len(), 5);

        assert!(zip.filter_by_suffix("").iter().all(|e| !e.is_directory));

        // directories are excluded even when their path ends with the suffix

        let txt = zip.filter_by_suffix(".txt");

        assert_eq!(txt.len(), 1);

        assert_eq!(txt[0].path, "a.txt");

        // matching is case-sensitive

        assert_eq!(zip.filter_by_suffix(".TXT").len(), 1);

        assert_eq!(zip.filter_by_suffix(".Txt").len(), 0);

        // whole-path suffix matches

        assert_eq!(zip.filter_by_suffix("README").len(), 1);

        // multibyte suffix must not split a char boundary or panic

        assert_eq!(zip.filter_by_suffix("\u{1F600}.json").len(), 1);

        assert_eq!(zip.filter_by_suffix("json").len(), 1);

        // suffix longer than any path -> empty, no panic

        assert!(zip.filter_by_suffix(&"n".repeat(100_000)).is_empty());

        // junk suffixes

        assert!(zip.filter_by_suffix("\0").is_empty());

        assert!(zip.filter_by_suffix("  ").is_empty());

    }

    // ==================================================================

    // parsers: malformed / hostile input

    // ==================================================================

    #[cfg(feature = "zip")]

    #[test]

    fn autotest_readers_reject_empty_and_garbage_without_panicking() {

        let cfg = ZipReadConfig::default();

        let inputs: Vec<Vec<u8>> = vec![

            Vec::new(),

            b"   ".to_vec(),

            b"\t\n\r ".to_vec(),

            b"not a zip file at all".to_vec(),

            vec![0u8; 22],

            vec![0xFF, 0xFE, 0x00],

            vec![0xC3, 0x28, 0xA0, 0xA1],           // invalid UTF-8

            b"PK".to_vec(),                          // truncated signature

            b"PK\x03\x04".to_vec(),                  // local header signature only

            b"PK\x05\x06".to_vec(),                  // truncated EOCD

            b"0 -0 NaN inf 9223372036854775807".to_vec(),

            "\u{1F600}\u{0301}".as_bytes().to_vec(), // multibyte unicode

            b"[".repeat(10_000),                     // "deeply nested" junk

            b"PK\x05\x06".repeat(5_000),             // many EOCD-ish signatures

        ];

        for data in inputs {

            let listed = ZipFile::list(&data, &cfg);

            let loaded = ZipFile::from_bytes(&data, &cfg);

            let extracted = zip_extract_all(&data, &cfg);

            let contents = zip_list_contents(&data, &cfg);

            // the free functions must agree with the inherent methods

            assert_eq!(loaded.is_err(), extracted.is_err());

            assert_eq!(listed.is_err(), contents.is_err());

            match loaded {

                Err(e) => {

                    // garbage must surface as a *parse* failure, never as a

                    // security/limit verdict (UnsafePath / FileTooLarge / ...)

                    assert!(

                        matches!(

                            e,

                            ZipReadError::InvalidFormat(_) | ZipReadError::IoError(_)

                        ),

                        "unexpected error kind for {:?}: {e:?}",

                        &data[..data.len().min(8)]

                    );

                    assert!(!e.to_string().is_empty());

                }

                // if it *did* parse, it must be a degenerate empty archive

                Ok(z) => assert!(z.entries.is_empty()),

            }

        }

        // empty input specifically is a format error, not an I/O error

        assert!(matches!(

            ZipFile::from_bytes(b"", &cfg),

            Err(ZipReadError::InvalidFormat(_))

        ));

        assert!(matches!(

            ZipFile::list(b"", &cfg),

            Err(ZipReadError::InvalidFormat(_))

        ));

    }

    #[cfg(feature = "zip")]

    #[test]

    fn autotest_readers_handle_one_megabyte_of_junk() {

        let cfg = ZipReadConfig::default();

        // 1 MiB with no valid central directory: must fail fast, not hang or OOM

        let junk = vec![b'A'; 1_000_000];

        assert!(ZipFile::from_bytes(&junk, &cfg).is_err());

        assert!(ZipFile::list(&junk, &cfg).is_err());

        // 1 MiB of zeros (a plausible sparse/zeroed file)

        let zeros = vec![0u8; 1_000_000];

        assert!(ZipFile::from_bytes(&zeros, &cfg).is_err());

        // 1 MiB ending in something that looks like an EOCD but isn't consistent

        let mut fake = vec![b'B'; 1_000_000];

        fake.extend_from_slice(&[0x50, 0x4B, 0x05, 0x06]);

        fake.extend_from_slice(&[0xFFu8; 18]);

        let res = ZipFile::from_bytes(&fake, &cfg);

        assert!(

            res.map_or(true, |z| z.entries.is_empty()),

            "a bogus EOCD must not yield phantom entries"

        );

    }

    #[cfg(feature = "zip")]

    #[test]

    fn autotest_minimal_valid_archives_parse_as_empty() {

        let cfg = ZipReadConfig::default();

        // positive control #1: what this module itself writes for an empty archive

        let own = ZipFile::new()

            .to_bytes(&ZipWriteConfig::default())

            .expect("empty archive must be writable");

        let round = ZipFile::from_bytes(&own, &cfg).expect("own empty archive must re-read");

        assert!(round.entries.is_empty());

        assert!(ZipFile::list(&own, &cfg).unwrap().is_empty());

        // an empty archive is also writable with the store() config (no file entries)

        assert!(ZipFile::new().to_bytes(&ZipWriteConfig::store()).is_ok());

        // positive control #2: the canonical 22-byte EOCD-only archive

        let eocd = eocd_only();

        assert_eq!(eocd.len(), 22);

        if let Ok(z) = ZipFile::from_bytes(&eocd, &cfg) {

            assert!(z.entries.is_empty());

        }

    }

    #[cfg(feature = "zip")]

    #[test]

    fn autotest_truncated_and_bitflipped_archives_never_panic() {

        let cfg = ZipReadConfig::default();

        let good = build(vec![

            ZipFileEntry::file("a.txt", b"hello hello hello hello".to_vec()),

            ZipFileEntry::file("b.bin", vec![7u8; 512]),

        ]);

        assert!(ZipFile::from_bytes(&good, &cfg).is_ok());

        // every truncation prefix must be handled (Err or degenerate Ok), never a panic

        for cut in [0, 1, 3, 4, 10, good.len() / 4, good.len() / 2, good.len() - 1] {

            let _ = ZipFile::from_bytes(&good[..cut], &cfg);

            let _ = ZipFile::list(&good[..cut], &cfg);

        }

        // single-byte corruption anywhere in the stream

        for i in (0..good.len()).step_by(7) {

            let mut bad = good.clone();

            bad[i] ^= 0xFF;

            let _ = ZipFile::from_bytes(&bad, &cfg);

            let _ = ZipFile::list(&bad, &cfg);

        }