arc_mac/

stuffit.rs

// SPDX-License-Identifier: MIT
//! Classic StuffIt (`.sit`) + StuffIt self-extracting (`.sea`) reader.
//!
//! Container layout (reverse-engineered; see XADMaster `XADStuffItParser.m`,
//! mirrored in `docs/native_mac_archives.md`):
//!
//! ```text
//! Archive header (22 bytes):
//!   [0..4]  "SIT!" magic
//!   [4..6]  number of entries (u16 BE)        (informational; we walk to EOF)
//!   [6..10] total archive length (u32 BE)
//!   [10..14] "rLau" secondary signature
//!   [14..22] version + reserved + header CRC
//!
//! Per-entry header (112 bytes):
//!   [0]   resource-fork compression method
//!   [1]   data-fork compression method
//!   [2]   filename length (<= 31)
//!   [3..34] filename (Mac Roman)
//!   [66..70] file type        [70..74] creator
//!   [74..76] Finder flags
//!   [76..80] creation date    [80..84] modification date  (Mac 1904 epoch)
//!   [84..88] resource fork uncompressed length
//!   [88..92] data fork uncompressed length
//!   [92..96] resource fork compressed length
//!   [96..100] data fork compressed length
//!   [100..102] resource CRC   [102..104] data CRC  (CRC-16/ARC)
//!   [110..112] header CRC (CRC-16/ARC over [0..110])
//! Then: <compressed resource fork><compressed data fork>
//! ```
//!
//! A method byte's high bit (`0x80`) marks an encrypted fork; `0x20`/`0x21`
//! (after masking the encryption + folder-contains-encrypted bits) mark the
//! start/end of a folder. The low nibble is the compression method.

use anyhow::{bail, Result};
use byteorder::{BigEndian, ByteOrder};

use fs_mac::binhex;

const ARCHIVE_HEADER_LEN: usize = 22;
const ENTRY_HEADER_LEN: usize = 112;

const ENCRYPTED_FLAG: u8 = 0x80;
const FOLDER_CONTAINS_ENCRYPTED: u8 = 0x10;
const START_FOLDER: u8 = 0x20;
const END_FOLDER: u8 = 0x21;
/// Mask that strips the encryption + "contains encrypted" bits, leaving the
/// folder marker (or the raw method) behind.
const FOLDER_MASK: u8 = !(ENCRYPTED_FLAG | FOLDER_CONTAINS_ENCRYPTED);

/// Which decompressor a [`ForkInfo`] needs. StuffIt and Compact Pro share the
/// same entry/fork plumbing (the directory tree in [`StuffItEntry`] and every
/// output format in `extract`) but use entirely different fork codecs and
/// checksums, so the codec tag picks the right decompressor at extract time.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ForkCodec {
    /// StuffIt method lives in [`ForkInfo::method`]; checksum is the
    /// CRC-16/ARC in [`ForkInfo::crc`].
    StuffIt,
    /// Compact Pro (`super::compactpro`): byte-level RLE, optionally preceded
    /// by an LZH (LZSS + Huffman) layer. Compact Pro stores one CRC-32 per
    /// file (in [`ForkInfo::crc32`]) over the resource fork followed by the
    /// data fork, so it's verified once per entry rather than per fork.
    CompactPro { lzh: bool },
}

/// One fork (data or resource) of a StuffIt or Compact Pro entry.
#[derive(Debug, Clone)]
pub struct ForkInfo {
    /// StuffIt compression method (low nibble: 0=none, 1=RLE90, 3=Huffman,
    /// 13=LZ+Huffman, 15=Arsenic, …). Ignored for [`ForkCodec::CompactPro`].
    pub method: u8,
    /// Which codec decompresses this fork.
    pub codec: ForkCodec,
    /// True when the fork is password-encrypted (not supported for extraction).
    pub encrypted: bool,
    /// Decompressed length in bytes.
    pub uncompressed_len: u32,
    /// Compressed length in bytes (as stored in the archive).
    pub compressed_len: u32,
    /// Stored CRC-16/ARC of the decompressed fork (StuffIt forks only).
    pub crc: u16,
    /// Stored CRC-32 of the decompressed fork (Compact Pro forks only).
    pub crc32: u32,
    /// Absolute byte offset of the compressed data within the archive.
    pub offset: u64,
}

impl ForkInfo {
    /// Human-readable compression method name, codec-aware.
    pub fn method_name(&self) -> &'static str {
        match self.codec {
            ForkCodec::StuffIt => method_name(self.method),
            ForkCodec::CompactPro { lzh: true } => "Compact Pro (LZH+RLE)",
            ForkCodec::CompactPro { lzh: false } => "Compact Pro (RLE)",
        }
    }
}

/// One file or folder in a StuffIt archive.
#[derive(Debug, Clone)]
pub struct StuffItEntry {
    /// Path components from the archive root (last element is the name).
    pub path: Vec<String>,
    /// Leaf name (Mac Roman → UTF-8).
    pub name: String,
    /// True for folder markers (no fork data).
    pub is_dir: bool,
    pub type_code: [u8; 4],
    pub creator_code: [u8; 4],
    pub finder_flags: u16,
    /// Mac 1904-epoch timestamps.
    pub create_date: u32,
    pub mod_date: u32,
    /// Data fork (absent for folders).
    pub data: Option<ForkInfo>,
    /// Resource fork (absent for folders).
    pub rsrc: Option<ForkInfo>,
}

impl StuffItEntry {
    /// Display path joined with `/`.
    pub fn display_path(&self) -> String {
        self.path.join("/")
    }
}

/// A parsed StuffIt archive (entries in archive order; directory structure is
/// reflected in each entry's `path`).
#[derive(Debug, Clone)]
pub struct StuffItArchive {
    pub entries: Vec<StuffItEntry>,
    /// `Some` when the archive header declares more bytes than the container
    /// actually holds — see [`SitTruncation`].
    pub truncated: Option<SitTruncation>,
    /// Stretches of unexpected bytes the entry walk skipped; see [`SitDamage`].
    pub damage: Vec<SitDamage>,
}

/// Bytes between two entries that no header accounts for, skipped by the entry walk (#101).
/// See `docs/native_mac_archives.md` section 6a.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SitDamage {
    /// Offset from the `SIT!` signature where an entry header was expected.
    pub offset: u64,
    /// Bytes skipped before the next valid entry header.
    pub skipped: u64,
}

impl SitDamage {
    /// One-line ASCII summary for logs and the CLI.
    pub fn describe(&self) -> String {
        format!(
            "Warning: damaged StuffIt archive - {} unexpected bytes at offset {} where an entry \
             header should be; skipped to the next valid header. The entry before the gap is \
             likely damaged too and may fail its CRC.",
            self.skipped, self.offset
        )
    }
}

/// An archive whose header declares a longer stream than is present.
///
/// The entry headers sit early in the stream, so such an archive still *parses*
/// and *lists* — but any entry whose compressed fork lies past the cut cannot be
/// extracted, because those bytes are simply not in the file.
///
/// The usual cause is a StuffIt InstallerMaker installer, which fills disk 1 to
/// capacity and continues the same byte stream on disk 2..N. Handed only disk 1,
/// we see a complete, CRC-valid file carrying a partial archive. Recording this
/// at parse time lets the extract path say so up front rather than emitting a
/// per-entry "extends past end of archive" that reads like a decoder bug.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SitTruncation {
    /// Total archive length declared in the header at `[6..10]`.
    pub declared: u64,
    /// Bytes actually present from the archive base to end-of-buffer.
    pub available: u64,
}

impl SitTruncation {
    /// Bytes the header accounts for that the container does not hold.
    pub fn missing(&self) -> u64 {
        self.declared.saturating_sub(self.available)
    }

    /// One-line ASCII summary for logs and the CLI (no Unicode glyphs — the
    /// egui font has no symbol coverage).
    pub fn describe(&self) -> String {
        format!(
            "Warning: truncated StuffIt archive - header declares {} bytes, {} present ({} missing). \
             Any entry whose data lies past the cut will be skipped. StuffIt InstallerMaker splits \
             large installers across several disks, so this is likely the first disk of a set.",
            self.declared,
            self.available,
            self.missing()
        )
    }
}

fn method_name(method: u8) -> &'static str {
    match method & 0x0f {
        0 => "None",
        1 => "RLE",
        2 => "Compress (LZW)",
        3 => "Huffman",
        5 => "LZAH",
        6 => "Fixed Huffman",
        8 => "MW",
        13 => "LZ+Huffman",
        14 => "Installer",
        15 => "Arsenic",
        _ => "Unknown",
    }
}

/// CRC-16/ARC (reflected, poly 0xA001, init 0) — StuffIt's header and fork CRC.
pub(crate) fn crc16_arc(data: &[u8]) -> u16 {
    let mut crc: u16 = 0;
    for &b in data {
        crc ^= b as u16;
        for _ in 0..8 {
            if crc & 1 != 0 {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc >>= 1;
            }
        }
    }
    crc
}

/// Detect whether `data` begins with a classic StuffIt archive.
pub fn is_stuffit(data: &[u8]) -> bool {
    data.len() >= 14 && &data[0..4] == b"SIT!" && &data[10..14] == b"rLau"
}

/// Locate the StuffIt archive inside a `.sea` (self-extracting archive). A
/// StuffIt SEA is a Mac application whose payload is a plain `.sit` stream; we
/// scan for the `SIT!`…`rLau` signature. Returns the offset of the archive.
pub fn find_sea_archive(data: &[u8]) -> Option<usize> {
    if is_stuffit(data) {
        return Some(0);
    }
    // Scan for "SIT!" followed by "rLau" 10 bytes later.
    data.windows(14)
        .position(|w| &w[0..4] == b"SIT!" && &w[10..14] == b"rLau")
}

/// Parse a StuffIt archive (or the `.sit` stream embedded in a `.sea`).
pub fn parse(data: &[u8]) -> Result<StuffItArchive> {
    let base = find_sea_archive(data)
        .ok_or_else(|| anyhow::anyhow!("not a StuffIt archive (no SIT!/rLau signature)"))?;
    let archive = &data[base..];
    if archive.len() < ARCHIVE_HEADER_LEN {
        bail!("StuffIt: truncated archive header");
    }

    let declared_total = BigEndian::read_u32(&archive[6..10]) as usize;
    // Clamp to what we actually have (some SEAs over-report) so the entry walk
    // stays in bounds, but remember the shortfall: it's the difference between
    // "this archive is complete" and "this is disk 1 of an InstallerMaker set".
    let total_size = declared_total.min(archive.len());
    let truncated = (declared_total > archive.len()).then_some(SitTruncation {
        declared: declared_total as u64,
        available: archive.len() as u64,
    });

    let mut entries = Vec::new();
    let mut damage = Vec::new();
    let mut currdir: Vec<String> = Vec::new();
    let mut pos = ARCHIVE_HEADER_LEN;

    while pos + ENTRY_HEADER_LEN <= total_size {
        let h = &archive[pos..pos + ENTRY_HEADER_LEN];

        if !entry_header_valid(h) {
            if let Some(next) = find_next_entry_header(archive, pos + 1, total_size) {
                damage.push(SitDamage {
                    offset: pos as u64,
                    skipped: (next - pos) as u64,
                });
                pos = next;
                continue;
            }
            if h[..110].iter().all(|&b| b == 0) {
                break; // zero padding to the end
            }
            let stored_hdr_crc = BigEndian::read_u16(&h[110..112]);
            let computed = crc16_arc(&h[0..110]);
            bail!(
                "StuffIt: entry header CRC mismatch at offset {pos} (got {computed:#06x}, expected {stored_hdr_crc:#06x}){}",
                damage_hint(data)
            );
        }

        let rmethod = h[0];
        let dmethod = h[1];
        let mut namelen = h[2] as usize;
        if namelen > 31 {
            namelen = 31;
        }
        let name = fs_mac::hfs::decode_mac_filename(&h[3..3 + namelen]);

        let data_start = (base + pos + ENTRY_HEADER_LEN) as u64;

        if (dmethod & FOLDER_MASK) == START_FOLDER || (rmethod & FOLDER_MASK) == START_FOLDER {
            currdir.push(name.clone());
            // currdir now includes this folder as its last component.
            entries.push(StuffItEntry {
                path: currdir.clone(),
                name,
                is_dir: true,
                type_code: [0; 4],
                creator_code: [0; 4],
                finder_flags: BigEndian::read_u16(&h[74..76]),
                create_date: BigEndian::read_u32(&h[76..80]),
                mod_date: BigEndian::read_u32(&h[80..84]),
                data: None,
                rsrc: None,
            });
            pos += ENTRY_HEADER_LEN; // folder marker carries no fork data
            continue;
        }

        if (dmethod & FOLDER_MASK) == END_FOLDER || (rmethod & FOLDER_MASK) == END_FOLDER {
            currdir.pop();
            pos += ENTRY_HEADER_LEN;
            continue;
        }

        // Regular file.
        let rsrc_len = BigEndian::read_u32(&h[84..88]);
        let data_len = BigEndian::read_u32(&h[88..92]);
        let rsrc_clen = BigEndian::read_u32(&h[92..96]);
        let data_clen = BigEndian::read_u32(&h[96..100]);
        let rsrc_crc = BigEndian::read_u16(&h[100..102]);
        let data_crc = BigEndian::read_u16(&h[102..104]);

        let mut type_code = [0u8; 4];
        type_code.copy_from_slice(&h[66..70]);
        let mut creator_code = [0u8; 4];
        creator_code.copy_from_slice(&h[70..74]);

        let rsrc = if rsrc_len > 0 || rsrc_clen > 0 {
            Some(ForkInfo {
                method: rmethod & !ENCRYPTED_FLAG,
                codec: ForkCodec::StuffIt,
                encrypted: rmethod & ENCRYPTED_FLAG != 0,
                uncompressed_len: rsrc_len,
                compressed_len: rsrc_clen,
                crc: rsrc_crc,
                crc32: 0,
                offset: data_start,
            })
        } else {
            None
        };
        let data = Some(ForkInfo {
            method: dmethod & !ENCRYPTED_FLAG,
            codec: ForkCodec::StuffIt,
            encrypted: dmethod & ENCRYPTED_FLAG != 0,
            uncompressed_len: data_len,
            compressed_len: data_clen,
            crc: data_crc,
            crc32: 0,
            offset: data_start + rsrc_clen as u64,
        });

        let mut path = currdir.clone();
        path.push(name.clone());
        entries.push(StuffItEntry {
            path,
            name,
            is_dir: false,
            type_code,
            creator_code,
            finder_flags: BigEndian::read_u16(&h[74..76]),
            create_date: BigEndian::read_u32(&h[76..80]),
            mod_date: BigEndian::read_u32(&h[80..84]),
            data,
            rsrc,
        });

        pos += ENTRY_HEADER_LEN + rsrc_clen as usize + data_clen as usize;
    }

    Ok(StuffItArchive {
        entries,
        truncated,
        damage,
    })
}

/// CRC-valid and not all zero (a zero block's CRC is also zero).
fn entry_header_valid(h: &[u8]) -> bool {
    BigEndian::read_u16(&h[110..112]) == crc16_arc(&h[0..110]) && h[..110].iter().any(|&b| b != 0)
}

/// Offset of the next plausible, CRC-valid entry header in `from..`, if any.
fn find_next_entry_header(archive: &[u8], from: usize, total_size: usize) -> Option<usize> {
    let method_ok = |m: u8| {
        let f = m & FOLDER_MASK;
        f == START_FOLDER || f == END_FOLDER || (m & !ENCRYPTED_FLAG) <= 0x0f
    };
    (from..(total_size + 1).saturating_sub(ENTRY_HEADER_LEN)).find(|&q| {
        let h = &archive[q..q + ENTRY_HEADER_LEN];
        h[2] <= 31 && method_ok(h[0]) && method_ok(h[1]) && entry_header_valid(h)
    })
}

/// A hint naming the damage when the file shows the marks of a text conversion.
/// See `docs/native_mac_archives.md` section 6a for why each signature is conclusive.
pub(crate) fn damage_hint(data: &[u8]) -> &'static str {
    if data.len() < 4096 {
        return "";
    }
    let mut seen = [false; 256];
    for &b in data {
        seen[b as usize] = true;
    }
    if !seen[0x0d] {
        return " - the file holds no CR (0x0d) bytes at all, so it went through a text-mode \
                (line-ending) conversion that rewrote the compressed data; it cannot be repaired, \
                fetch a copy transferred in binary mode";
    }
    if !seen[0xc0] && !seen[0xc1] && !seen[0xf5..].contains(&true) {
        return " - the file holds none of the bytes C0, C1, F5-FF (the ones UTF-8 never uses), \
                so it went through a text-encoding conversion that rewrote the compressed data; it \
                cannot be repaired, fetch a copy transferred in binary mode";
    }
    ""
}

/// Decompress one fork from the archive bytes, verifying its CRC.
///
/// `archive` is the full file passed to [`parse`] (offsets in [`ForkInfo`] are
/// absolute within it). Returns an error for encrypted forks and for
/// compression methods not yet implemented.
pub fn decompress_fork(archive: &[u8], fork: &ForkInfo) -> Result<Vec<u8>> {
    if fork.encrypted {
        bail!("StuffIt: encrypted forks are not supported");
    }
    let start = fork.offset as usize;
    let end = start + fork.compressed_len as usize;
    if end > archive.len() {
        // Not a bounds-check bug: `compressed_len` is the on-disk length, so
        // this fires only when those bytes genuinely aren't in the container
        // (a truncated / multi-disk archive). Quote the arithmetic so the next
        // reader doesn't have to re-derive it.
        bail!(
            "StuffIt: fork data extends past end of archive (needs {} compressed bytes at offset \
             {start}, archive holds {}; {} missing - the archive is truncated)",
            fork.compressed_len,
            archive.len(),
            end - archive.len()
        );
    }
    let comp = &archive[start..end];
    let want = fork.uncompressed_len as usize;

    let out = match fork.method & 0x0f {
        0 => comp.to_vec(),
        1 => binhex::rle90_decode(comp),
        2 => super::stuffit_lzw::decompress(comp, want, 0x8e)?,
        3 => super::stuffit_huffman::decompress(comp, want)?,
        5 => super::stuffit_lzah::decompress(comp, want)?,
        13 => super::stuffit_lzh::decompress(comp, want)?,
        15 => super::stuffit_arsenic::decompress(comp, want)?,
        m => bail!(
            "StuffIt: compression method {m} ({}) not yet supported",
            method_name(fork.method)
        ),
    };

    let out = if out.len() > want {
        out[..want].to_vec()
    } else {
        out
    };
    if out.len() != want {
        bail!(
            "StuffIt: decompressed length {} != expected {want}",
            out.len()
        );
    }

    // Arsenic (15) carries its own checksum; everything else uses CRC-16/ARC.
    if fork.method & 0x0f != 15 {
        let got = crc16_arc(&out);
        if got != fork.crc {
            bail!(
                "StuffIt: fork CRC mismatch (got {got:#06x}, expected {:#06x})",
                fork.crc
            );
        }
    }

    Ok(out)
}

// ---------------------------------------------------------------------------
// Writer
// ---------------------------------------------------------------------------

/// Compression to use when writing a fork.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WriteMethod {
    /// Store uncompressed (method 0).
    Store,
    /// RLE90 (method 1), falling back to Store when it doesn't shrink the fork.
    Rle,
}

/// A single file to place into a StuffIt archive.
#[derive(Debug, Clone)]
pub struct StuffItInput {
    /// Mac filename (truncated to 31 bytes).
    pub name: String,
    pub type_code: [u8; 4],
    pub creator_code: [u8; 4],
    pub finder_flags: u16,
    /// Mac 1904-epoch timestamps (0 is acceptable).
    pub create_date: u32,
    pub mod_date: u32,
    pub data_fork: Vec<u8>,
    pub resource_fork: Vec<u8>,
}

/// A node in a StuffIt input tree — either a file or a folder containing
/// further nodes. Used by [`build_archive_tree`] to emit nested directory
/// structures via the START_FOLDER (0x20) / END_FOLDER (0x21) marker
/// entries that classic StuffIt uses for hierarchy.
#[derive(Debug, Clone)]
pub enum StuffItInputNode {
    File(StuffItInput),
    Folder {
        /// Mac folder name (truncated to 31 bytes).
        name: String,
        /// Finder flags; usually 0 for ordinary folders.
        finder_flags: u16,
        /// Mac 1904-epoch timestamps; 0 is acceptable.
        create_date: u32,
        mod_date: u32,
        /// Nested entries inside this folder, in archive order.
        children: Vec<StuffItInputNode>,
    },
}

/// Compress a fork for writing, returning `(method_byte, bytes)`.
fn compress_fork(data: &[u8], method: WriteMethod) -> (u8, Vec<u8>) {
    match method {
        WriteMethod::Store => (0, data.to_vec()),
        WriteMethod::Rle => {
            let encoded = binhex::rle90_encode(data);
            if encoded.len() < data.len() {
                (1, encoded)
            } else {
                (0, data.to_vec())
            }
        }
    }
}

/// Build a classic StuffIt (`.sit`) archive from a flat list of files.
///
/// Produces correct 112-byte entry-header CRCs and per-fork CRC-16/ARC values
/// (the checksums real readers verify), so the result round-trips through
/// [`parse`] and is accepted by The Unarchiver. The 16-bit archive-header field
/// at offset 20 (whose derivation is unknown and which XAD ignores) is written
/// as zero.
///
/// Use [`build_archive_tree`] when you need to emit nested directory
/// structures; this entry point keeps the older flat-file shape for callers
/// that build a single top-level entry list.
pub fn build_archive(files: &[StuffItInput], method: WriteMethod) -> Result<Vec<u8>> {
    let nodes: Vec<StuffItInputNode> = files.iter().cloned().map(StuffItInputNode::File).collect();
    build_archive_tree(&nodes, method)
}

/// Build a classic StuffIt (`.sit`) archive from a node tree, emitting
/// START_FOLDER (0x20) / END_FOLDER (0x21) marker entries for nested
/// directories. Children of a `Folder` node appear between its start
/// and end markers; the round-trip through [`parse`] reconstructs the
/// directory path in each entry's `path` field.
///
/// The archive-header `num_files` field is written as the **top-level**
/// entry count, matching what classic StuffIt produced. Readers
/// (including ours) iterate entries until they hit `archiveLength`,
/// so this field is informational.
pub fn build_archive_tree(tree: &[StuffItInputNode], method: WriteMethod) -> Result<Vec<u8>> {
    let mut body = Vec::new();
    for node in tree {
        emit_node(&mut body, node, method);
    }

    let total = (ARCHIVE_HEADER_LEN + body.len()) as u32;
    let mut out = Vec::with_capacity(total as usize);
    out.extend_from_slice(b"SIT!");
    out.extend_from_slice(&(tree.len() as u16).to_be_bytes());
    out.extend_from_slice(&total.to_be_bytes());
    out.extend_from_slice(b"rLau");
    out.push(1); // version
    out.push(0); // reserved
    out.extend_from_slice(&(ARCHIVE_HEADER_LEN as u32).to_be_bytes());
    out.extend_from_slice(&[0, 0]); // archive-header field at [20]; XAD ignores it
    debug_assert_eq!(out.len(), ARCHIVE_HEADER_LEN);
    out.extend_from_slice(&body);
    Ok(out)
}

/// Serialize a single node (file or folder) into `body`. For folders this
/// emits the START marker, recurses into each child, and emits the END
/// marker; for files it writes the standard 112-byte header + forks.
fn emit_node(body: &mut Vec<u8>, node: &StuffItInputNode, method: WriteMethod) {
    match node {
        StuffItInputNode::File(f) => emit_file_entry(body, f, method),
        StuffItInputNode::Folder {
            name,
            finder_flags,
            create_date,
            mod_date,
            children,
        } => {
            emit_folder_marker(
                body,
                name,
                *finder_flags,
                *create_date,
                *mod_date,
                START_FOLDER,
            );
            for child in children {
                emit_node(body, child, method);
            }
            emit_folder_marker(body, "", 0, 0, 0, END_FOLDER);
        }
    }
}

fn emit_file_entry(body: &mut Vec<u8>, f: &StuffItInput, method: WriteMethod) {
    let name_bytes = mac_name_bytes(&f.name);
    let namelen = name_bytes.len();

    let (rmethod, rcomp) = if f.resource_fork.is_empty() {
        (0u8, Vec::new())
    } else {
        compress_fork(&f.resource_fork, method)
    };
    let (dmethod, dcomp) = compress_fork(&f.data_fork, method);

    let mut h = [0u8; ENTRY_HEADER_LEN];
    h[0] = rmethod;
    h[1] = dmethod;
    h[2] = namelen as u8;
    h[3..3 + namelen].copy_from_slice(&name_bytes);
    // [34..36] filename CRC (size byte + name); not verified by readers.
    let fname_crc = crc16_arc(&h[2..3 + namelen]);
    BigEndian::write_u16(&mut h[34..36], fname_crc);
    h[66..70].copy_from_slice(&f.type_code);
    h[70..74].copy_from_slice(&f.creator_code);
    BigEndian::write_u16(&mut h[74..76], f.finder_flags);
    BigEndian::write_u32(&mut h[76..80], f.create_date);
    BigEndian::write_u32(&mut h[80..84], f.mod_date);
    BigEndian::write_u32(&mut h[84..88], f.resource_fork.len() as u32);
    BigEndian::write_u32(&mut h[88..92], f.data_fork.len() as u32);
    BigEndian::write_u32(&mut h[92..96], rcomp.len() as u32);
    BigEndian::write_u32(&mut h[96..100], dcomp.len() as u32);
    BigEndian::write_u16(&mut h[100..102], crc16_arc(&f.resource_fork));
    BigEndian::write_u16(&mut h[102..104], crc16_arc(&f.data_fork));
    // [62..66] child offset: -1 marks a file entry (as real archives do).
    h[62..66].copy_from_slice(&[0xff, 0xff, 0xff, 0xff]);
    // Header CRC over the first 110 bytes.
    let hdr_crc = crc16_arc(&h[0..110]);
    BigEndian::write_u16(&mut h[110..112], hdr_crc);

    body.extend_from_slice(&h);
    body.extend_from_slice(&rcomp);
    body.extend_from_slice(&dcomp);
}

/// Emit a folder-start or folder-end marker. The parser keys off the
/// method byte (`START_FOLDER` or `END_FOLDER`) after masking the
/// encryption + "contains encrypted" bits; the rest of the 112-byte
/// header follows the same layout as a file entry, with zeroed forks.
fn emit_folder_marker(
    body: &mut Vec<u8>,
    name: &str,
    finder_flags: u16,
    create_date: u32,
    mod_date: u32,
    marker: u8,
) {
    let name_bytes = if marker == START_FOLDER {
        mac_name_bytes(name)
    } else {
        Vec::new()
    };
    let namelen = name_bytes.len();

    let mut h = [0u8; ENTRY_HEADER_LEN];
    // Both fork-method bytes carry the marker. The parser accepts either
    // position; we write both so the resulting archive is unambiguous.
    h[0] = marker;
    h[1] = marker;
    h[2] = namelen as u8;
    if namelen > 0 {
        h[3..3 + namelen].copy_from_slice(&name_bytes);
        let fname_crc = crc16_arc(&h[2..3 + namelen]);
        BigEndian::write_u16(&mut h[34..36], fname_crc);
    }
    // No type / creator codes on folder markers (the parser zeros them out).
    BigEndian::write_u16(&mut h[74..76], finder_flags);
    BigEndian::write_u32(&mut h[76..80], create_date);
    BigEndian::write_u32(&mut h[80..84], mod_date);
    // Fork lengths and compressed lengths stay zero — folders carry no data.
    // [62..66] child offset is left at zero for folder markers.
    let hdr_crc = crc16_arc(&h[0..110]);
    BigEndian::write_u16(&mut h[110..112], hdr_crc);

    body.extend_from_slice(&h);
}

/// Encode a name to at most 31 Mac Roman bytes (lossy ASCII fallback).
fn mac_name_bytes(name: &str) -> Vec<u8> {
    let mut bytes = fs_mac::hfs::utf8_to_mac_roman(name).unwrap_or_else(|_| {
        name.chars()
            .map(|c| if c.is_ascii() { c as u8 } else { b'_' })
            .collect()
    });
    bytes.truncate(31);
    bytes
}

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

    #[test]
    fn crc16_arc_known() {
        // CRC-16/ARC of "123456789" is 0xBB3D (standard check value).
        assert_eq!(crc16_arc(b"123456789"), 0xBB3D);
    }

    #[test]
    fn detects_signature() {
        let mut buf = vec![0u8; 22];
        buf[0..4].copy_from_slice(b"SIT!");
        buf[10..14].copy_from_slice(b"rLau");
        assert!(is_stuffit(&buf));
        assert!(!is_stuffit(b"not a sit file"));
    }

    #[test]
    fn truncated_archive_is_reported_not_silently_clamped() {
        // Mirrors a StuffIt InstallerMaker disk 1: a well-formed prefix of an
        // archive whose header still declares the full multi-disk length. Such a
        // file parses and lists fine, so the truncation has to be reported
        // explicitly or it surfaces only as a confusing per-entry skip.
        let files = vec![
            StuffItInput {
                name: "Small".to_string(),
                type_code: *b"TEXT",
                creator_code: *b"ttxt",
                finder_flags: 0,
                create_date: 0,
                mod_date: 0,
                data_fork: b"fits before the cut".to_vec(),
                resource_fork: Vec::new(),
            },
            StuffItInput {
                name: "Big".to_string(),
                type_code: *b"APPL",
                creator_code: *b"Spe2",
                finder_flags: 0,
                create_date: 0,
                mod_date: 0,
                // Incompressible-ish so Store really stores 40k.
                data_fork: (0..40_000u32).map(|i| (i % 251) as u8).collect(),
                resource_fork: Vec::new(),
            },
        ];
        let full = build_archive(&files, WriteMethod::Store).unwrap();

        // A complete archive must stay quiet.
        assert!(parse(&full).unwrap().truncated.is_none());

        // Chop mid-fork, the way filling a floppy does.
        let cut = full.len() - 10_000;
        let disk1 = full[..cut].to_vec();

        let archive = parse(&disk1).expect("disk 1 must still parse and list");
        assert_eq!(archive.entries.len(), 2, "both headers precede the cut");
        let t = archive.truncated.expect("truncation must be recorded");
        assert_eq!(t.declared, full.len() as u64);
        assert_eq!(t.available, cut as u64);
        assert_eq!(t.missing(), 10_000);

        // The entry before the cut still extracts...
        let e0 = &archive.entries[0];
        assert_eq!(
            decompress_fork(&disk1, e0.data.as_ref().unwrap()).unwrap(),
            files[0].data_fork
        );
        // ...and the one past it fails naming the real cause, not a bounds bug.
        let err = decompress_fork(&disk1, archive.entries[1].data.as_ref().unwrap())
            .unwrap_err()
            .to_string();
        assert!(err.contains("truncated"), "unhelpful message: {err}");
        assert!(err.contains("10000 missing"), "no shortfall in: {err}");
    }

    fn two_file_archive() -> (Vec<StuffItInput>, Vec<u8>) {
        let mk = |name: &str, body: Vec<u8>| StuffItInput {
            name: name.to_string(),
            type_code: *b"BINA",
            creator_code: *b"????",
            finder_flags: 0,
            create_date: 0,
            mod_date: 0,
            data_fork: body,
            resource_fork: Vec::new(),
        };
        let files = vec![
            mk("First", (0..3000u32).map(|i| (i % 253) as u8).collect()),
            mk("Second", b"after the gap".to_vec()),
        ];
        let bytes = build_archive(&files, WriteMethod::Store).unwrap();
        (files, bytes)
    }

    /// Splice `junk` in after the first entry's forks and fix the declared total
    /// to cover it, the shape of the #101 samples.
    fn splice_after_first(bytes: &[u8], junk: &[u8]) -> (Vec<u8>, usize) {
        let gap_at = ARCHIVE_HEADER_LEN + ENTRY_HEADER_LEN + 3000;
        let mut out = bytes[..gap_at].to_vec();
        out.extend_from_slice(junk);
        out.extend_from_slice(&bytes[gap_at..]);
        let total = out.len() as u32;
        BigEndian::write_u32(&mut out[6..10], total);
        (out, gap_at)
    }

    #[test]
    fn bytes_between_entries_are_skipped_and_reported() {
        // Issue #101: 149 stray bytes after the first entry. The rest must list and extract.
        let (files, bytes) = two_file_archive();
        let junk: Vec<u8> = (0..149u32).map(|i| (i * 7 + 3) as u8).collect();
        let (damaged, gap_at) = splice_after_first(&bytes, &junk);

        let archive = parse(&damaged).expect("damaged archive must still parse");
        assert_eq!(archive.entries.len(), 2);
        assert_eq!(archive.entries[1].name, "Second");
        assert_eq!(
            archive.damage,
            vec![SitDamage {
                offset: gap_at as u64,
                skipped: 149
            }]
        );
        assert!(archive.damage[0].describe().contains("149"));
        let second = decompress_fork(&damaged, archive.entries[1].data.as_ref().unwrap()).unwrap();
        assert_eq!(second, files[1].data_fork);
    }

    #[test]
    fn zero_block_is_not_an_entry() {
        // Poser 1.0.sit: the gap opens with 112 zero bytes, whose header CRC is also zero.
        let (_, bytes) = two_file_archive();
        let mut junk = vec![0u8; ENTRY_HEADER_LEN];
        junk.extend_from_slice(&[0x80, 0xff, 0x97, 0x05, 0x7f, 0xff, 0x3f, 0x00]);
        let (damaged, gap_at) = splice_after_first(&bytes, &junk);

        let archive = parse(&damaged).expect("damaged archive must still parse");
        let names: Vec<&str> = archive.entries.iter().map(|e| e.name.as_str()).collect();
        assert_eq!(names, ["First", "Second"]);
        assert_eq!(archive.damage.len(), 1);
        assert_eq!(archive.damage[0].offset, gap_at as u64);
        assert_eq!(archive.damage[0].skipped, junk.len() as u64);
    }

    #[test]
    fn bad_header_with_nothing_after_it_still_errors() {
        let (_, mut bytes) = two_file_archive();
        let second_hdr = ARCHIVE_HEADER_LEN + ENTRY_HEADER_LEN + 3000;
        bytes[second_hdr + 5] ^= 0xff;
        let err = parse(&bytes).unwrap_err().to_string();
        assert!(err.contains("CRC mismatch"), "{err}");
    }

    #[test]
    fn write_then_read_roundtrip() {
        let files = vec![
            StuffItInput {
                name: "Read Me".to_string(),
                type_code: *b"TEXT",
                creator_code: *b"ttxt",
                finder_flags: 0,
                create_date: 0xAABBCCDD,
                mod_date: 0x11223344,
                // Long runs so RLE actually engages.
                data_fork: b"Hello\r\rAAAAAAAAAAAAAAAAAAAA end.".to_vec(),
                resource_fork: vec![0u8; 200],
            },
            StuffItInput {
                name: "Empty Rsrc".to_string(),
                type_code: *b"BINA",
                creator_code: *b"????",
                finder_flags: 0x4000,
                create_date: 0,
                mod_date: 0,
                data_fork: b"just a data fork".to_vec(),
                resource_fork: Vec::new(),
            },
        ];

        for method in [WriteMethod::Store, WriteMethod::Rle] {
            let bytes = build_archive(&files, method).unwrap();
            assert!(is_stuffit(&bytes));
            let archive = parse(&bytes).expect("our writer must parse");
            assert_eq!(archive.entries.len(), 2);

            let e0 = &archive.entries[0];
            assert_eq!(e0.name, "Read Me");
            assert_eq!(&e0.type_code, b"TEXT");
            assert_eq!(e0.create_date, 0xAABBCCDD);
            // decompress_fork verifies the per-fork CRC internally.
            let data0 = decompress_fork(&bytes, e0.data.as_ref().unwrap()).unwrap();
            assert_eq!(data0, files[0].data_fork);
            let rsrc0 = decompress_fork(&bytes, e0.rsrc.as_ref().unwrap()).unwrap();
            assert_eq!(rsrc0, files[0].resource_fork);

            let e1 = &archive.entries[1];
            assert_eq!(e1.finder_flags, 0x4000);
            assert!(e1.rsrc.is_none());
            let data1 = decompress_fork(&bytes, e1.data.as_ref().unwrap()).unwrap();
            assert_eq!(data1, files[1].data_fork);
        }
    }

    fn make_file(name: &str, body: &[u8]) -> StuffItInputNode {
        StuffItInputNode::File(StuffItInput {
            name: name.to_string(),
            type_code: *b"TEXT",
            creator_code: *b"ttxt",
            finder_flags: 0,
            create_date: 0,
            mod_date: 0,
            data_fork: body.to_vec(),
            resource_fork: Vec::new(),
        })
    }

    fn make_folder(name: &str, children: Vec<StuffItInputNode>) -> StuffItInputNode {
        StuffItInputNode::Folder {
            name: name.to_string(),
            finder_flags: 0,
            create_date: 0,
            mod_date: 0,
            children,
        }
    }

    #[test]
    fn empty_folder_round_trips() {
        // An empty folder is two markers (start + end) and nothing in
        // between. The parser should surface a single dir entry.
        let tree = vec![make_folder("Apps", vec![])];
        let bytes = build_archive_tree(&tree, WriteMethod::Store).unwrap();
        let archive = parse(&bytes).expect("parse empty folder");

        assert_eq!(archive.entries.len(), 1);
        let only = &archive.entries[0];
        assert!(only.is_dir, "empty folder marker should be is_dir");
        assert_eq!(only.name, "Apps");
        assert_eq!(only.path, vec!["Apps".to_string()]);
    }

    #[test]
    fn folder_with_two_files_round_trips() {
        let tree = vec![make_folder(
            "Docs",
            vec![
                make_file("ReadMe", b"hello"),
                make_file("Notes", b"more text"),
            ],
        )];
        let bytes = build_archive_tree(&tree, WriteMethod::Store).unwrap();
        let archive = parse(&bytes).expect("parse folder with files");

        // 1 start marker + 2 files + (end marker is consumed silently).
        assert_eq!(archive.entries.len(), 3);
        assert!(archive.entries[0].is_dir);
        assert_eq!(archive.entries[0].name, "Docs");
        assert_eq!(archive.entries[1].name, "ReadMe");
        assert_eq!(archive.entries[1].path, vec!["Docs", "ReadMe"]);
        assert_eq!(archive.entries[2].name, "Notes");
        assert_eq!(archive.entries[2].path, vec!["Docs", "Notes"]);

        // Verify fork data round-trips for files inside the folder.
        let data = decompress_fork(&bytes, archive.entries[1].data.as_ref().unwrap()).unwrap();
        assert_eq!(data, b"hello");
    }

    #[test]
    fn deeply_nested_folders_preserve_paths() {
        // Apps/
        //   Word/
        //     Templates/
        //       Letter.txt
        let tree = vec![make_folder(
            "Apps",
            vec![make_folder(
                "Word",
                vec![make_folder(
                    "Templates",
                    vec![make_file("Letter.txt", b"Dear ___,")],
                )],
            )],
        )];
        let bytes = build_archive_tree(&tree, WriteMethod::Store).unwrap();
        let archive = parse(&bytes).expect("parse nested folders");

        // 3 start markers + 1 file (ends are silent).
        assert_eq!(archive.entries.len(), 4);
        assert_eq!(
            archive.entries[3].path,
            vec!["Apps", "Word", "Templates", "Letter.txt"]
        );
        let body = decompress_fork(&bytes, archive.entries[3].data.as_ref().unwrap()).unwrap();
        assert_eq!(body, b"Dear ___,");
    }

    #[test]
    fn top_level_files_after_folder_end_back_at_root() {
        // Mixing folders and top-level files exercises currdir popping
        // back to root after END_FOLDER.
        //   Folder1/
        //     Inner.txt
        //   TopLevel.txt
        let tree = vec![
            make_folder("Folder1", vec![make_file("Inner.txt", b"inside")]),
            make_file("TopLevel.txt", b"outside"),
        ];
        let bytes = build_archive_tree(&tree, WriteMethod::Store).unwrap();
        let archive = parse(&bytes).expect("parse mixed tree");

        // Folder start + Inner.txt + TopLevel.txt.
        assert_eq!(archive.entries.len(), 3);
        assert!(archive.entries[0].is_dir);
        assert_eq!(archive.entries[0].path, vec!["Folder1"]);
        assert_eq!(archive.entries[1].path, vec!["Folder1", "Inner.txt"]);
        // After the END_FOLDER, currdir is back at root.
        assert_eq!(archive.entries[2].path, vec!["TopLevel.txt"]);
    }

    #[test]
    fn flat_build_archive_still_works_after_refactor() {
        // The original flat-file build_archive now delegates to
        // build_archive_tree; confirm the existing call shape stays valid.
        let files = vec![StuffItInput {
            name: "Sole".to_string(),
            type_code: *b"TEXT",
            creator_code: *b"ttxt",
            finder_flags: 0,
            create_date: 0,
            mod_date: 0,
            data_fork: b"just one file".to_vec(),
            resource_fork: Vec::new(),
        }];
        let bytes = build_archive(&files, WriteMethod::Store).unwrap();
        let archive = parse(&bytes).expect("parse flat");
        assert_eq!(archive.entries.len(), 1);
        assert!(!archive.entries[0].is_dir);
        assert_eq!(archive.entries[0].path, vec!["Sole"]);
    }

    /// Parses real `.sit` samples if present (decoded from `.sit.hqx` on the
    /// fly). Validates the container parser + header CRCs end-to-end.
    #[test]
    fn parse_real_samples_if_present() {
        let dir = std::path::Path::new("/Users/dani/Downloads");
        if !dir.is_dir() {
            return;
        }
        let mut checked = 0;
        for entry in std::fs::read_dir(dir).unwrap().flatten() {
            let path = entry.path();
            let name = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
            if !name.to_ascii_lowercase().ends_with(".sit.hqx") {
                continue;
            }
            let bytes = match std::fs::read(&path) {
                Ok(b) => b,
                Err(_) => continue,
            };
            let bh = match binhex::parse_binhex(&bytes) {
                Ok(b) => b,
                Err(_) => continue,
            };
            // The .sit is the data fork of the BinHex file. Skip payloads that
            // aren't a classic StuffIt stream (e.g. the newer StuffIt 5 format,
            // which starts with "StuffIt (c)…" and is out of scope here).
            if find_sea_archive(&bh.data_fork).is_none() {
                eprintln!("{name}: skipped (not classic SIT!; likely StuffIt 5)");
                continue;
            }
            let archive = match parse(&bh.data_fork) {
                Ok(a) => a,
                Err(e) => panic!("parse failed for {name}: {e}"),
            };
            assert!(!archive.entries.is_empty(), "no entries parsed from {name}");
            for e in &archive.entries {
                assert!(!e.name.is_empty() || e.is_dir, "empty entry name in {name}");
            }
            // Actually decompress every supported fork; decompress_fork
            // verifies the per-fork CRC-16/ARC, so success means the codec
            // (including method 13 / LZ+Huffman) round-trips correctly.
            let mut ok = 0;
            let mut skipped = 0;
            for e in &archive.entries {
                for fork in [e.data.as_ref(), e.rsrc.as_ref()].into_iter().flatten() {
                    if fork.uncompressed_len == 0 {
                        continue;
                    }
                    match decompress_fork(&bh.data_fork, fork) {
                        Ok(_) => ok += 1,
                        Err(_) if matches!(fork.method & 0x0f, 2 | 3 | 5 | 6 | 8 | 14 | 15) => {
                            skipped += 1; // codec not implemented yet
                        }
                        Err(e) => panic!("{name}: decompress failed: {e}"),
                    }
                }
            }
            eprintln!(
                "{name}: {} entries, {ok} forks decompressed + CRC-verified, {skipped} unsupported-codec",
                archive.entries.len()
            );
            checked += 1;
            if checked >= 6 {
                break;
            }
        }
        eprintln!("validated {checked} real .sit samples");
    }
}