config_disassembler/xml/handlers/

disassemble.rs

//! Disassemble XML file handler.

use crate::xml::builders::{build_disassembled_files_unified, build_xml_string};
use crate::xml::multi_level::{
    capture_xmlns_from_root, path_segment_from_file_pattern, save_multi_level_config,
    strip_root_and_build_xml,
};
use crate::xml::parsers::{extract_xml_declaration_from_raw, parse_xml, parse_xml_from_str};
use crate::xml::types::{
    BuildDisassembledFilesOptions, DecomposeRule, MultiLevelRule, SidecarSpec,
};
use crate::xml::utils::normalize_path_unix;
use ignore::gitignore::GitignoreBuilder;
use std::io::Write as _;
use std::path::Path;
use std::sync::Arc;
use tokio::fs;
use tokio::sync::Semaphore;
use tokio::task::JoinSet;

/// Upper bound on how many files inside one directory-mode `disassemble()` call are
/// processed concurrently. Each spawned task is real OS-thread parallelism (not just
/// cooperative async interleaving), so this also caps how many XML parses/serializations
/// run at once; bounded rather than unbounded so a directory with thousands of files
/// doesn't spawn thousands of tasks (and their file handles) simultaneously.
const DIRECTORY_CONCURRENCY: usize = 16;

pub struct DisassembleXmlFileHandler {
    ign: Option<ignore::gitignore::Gitignore>,
}

impl DisassembleXmlFileHandler {
    pub fn new() -> Self {
        Self { ign: None }
    }

    async fn load_ignore_rules(&mut self, ignore_path: &str) {
        let path = Path::new(ignore_path);
        let content = match fs::read_to_string(path).await {
            Ok(c) => c,
            Err(_) => return,
        };
        let root = path.parent().unwrap_or(Path::new("."));
        let mut builder = GitignoreBuilder::new(root);
        for line in content.lines() {
            let _ = builder.add_line(None, line);
        }
        // `GitignoreBuilder::build` only fails on unlikely I/O errors; treat as absent rules.
        self.ign = builder.build().ok();
    }

    fn posix_path(path: &str) -> String {
        path.replace('\\', "/")
    }

    fn is_xml_file(file_path: &str) -> bool {
        file_path.to_lowercase().ends_with(".xml")
    }

    /// True when a directory entry is both a regular file and an `.xml`.
    /// Pure helper extracted from `handle_directory` so the
    /// `is_file && is_xml_file` predicate can be exercised without a
    /// real filesystem entry.
    fn is_processable_xml_entry(is_file: bool, file_name: &str) -> bool {
        is_file && Self::is_xml_file(file_name)
    }

    /// True when the unified-build output directory should be purged
    /// before re-disassembling. Both the flag *and* the existence check
    /// must hold; `pre_purge=true` against a missing directory is a
    /// no-op rather than an error.
    fn should_pre_purge_output(pre_purge: bool, output_exists: bool) -> bool {
        pre_purge && output_exists
    }

    /// True when a file inside the disassembly tree should be
    /// considered by a multi-level rule: it must be `.xml` and either
    /// its bare name or its full path must contain the rule's pattern.
    fn file_matches_multi_level_rule(file_name: &str, full_path: &str, file_pattern: &str) -> bool {
        file_name.ends_with(".xml")
            && (file_name.contains(file_pattern) || full_path.contains(file_pattern))
    }

    /// True when the parsed XML document has the multi-level rule's
    /// `root_to_strip` either as its root element or as a direct child
    /// of its root element.
    fn has_element_to_strip(parsed: &serde_json::Value, root_to_strip: &str) -> bool {
        parsed
            .as_object()
            .and_then(|o| {
                let root_key = o.keys().find(|k| *k != "?xml")?;
                let root_val = o.get(root_key)?.as_object()?;
                Some(root_key == root_to_strip || root_val.contains_key(root_to_strip))
            })
            .unwrap_or(false)
    }

    /// Two multi-level rules share an "identity" — i.e. should be
    /// deduplicated in `.multi_level.json` — when both their
    /// `file_pattern` and their `root_to_strip` match. The other
    /// fields (`unique_id_elements`, `path_segment`, …) are derived
    /// per-file and may legitimately drift.
    fn rules_have_same_identity(a: &MultiLevelRule, b: &MultiLevelRule) -> bool {
        a.file_pattern == b.file_pattern && a.root_to_strip == b.root_to_strip
    }

    /// First non-`?xml` key of the parsed document, used as the
    /// `wrap_root_element` for a multi-level rule. Falls back to
    /// `fallback` when the parsed value is not an object or contains
    /// only the declaration.
    fn root_element_name_from_parsed(parsed: &serde_json::Value, fallback: &str) -> String {
        parsed
            .as_object()
            .and_then(|o| o.keys().find(|k| *k != "?xml").cloned())
            .unwrap_or_else(|| fallback.to_string())
    }

    fn is_ignored(&self, path: &str) -> bool {
        self.ign
            .as_ref()
            .map(|ign| ign.matched(path, false).is_ignore())
            .unwrap_or(false)
    }

    /// Derive the disassembled-output directory name from a file stem.
    ///
    /// We strip only the trailing extension-like segment (everything after the **last** `.`),
    /// so `HR_Admin.permissionset-meta` collapses to `HR_Admin` while
    /// `Account.MyApprovalProcess.approvalProcess-meta` collapses to `Account.MyApprovalProcess`.
    /// Splitting at the *first* dot — the previous behaviour — was lossy for metadata types
    /// whose fullName itself contains a dot (e.g. Salesforce approval processes, quick actions,
    /// custom-metadata records) because two files like `A.X.foo-meta.xml` and `A.Y.foo-meta.xml`
    /// both resolved to `A/`, silently merging unrelated components.
    fn output_dir_basename(file_stem: &str) -> &str {
        file_stem
            .rsplit_once('.')
            .map(|(prefix, _)| prefix)
            .unwrap_or(file_stem)
    }

    #[allow(clippy::too_many_arguments)]
    pub async fn disassemble(
        &mut self,
        file_path: &str,
        unique_id_elements: Option<&str>,
        strategy: Option<&str>,
        pre_purge: bool,
        post_purge: bool,
        ignore_path: &str,
        format: &str,
        multi_level_rules: Option<&[MultiLevelRule]>,
        decompose_rules: Option<&[DecomposeRule]>,
        sidecar_specs: Option<&[SidecarSpec]>,
        base_dir: Option<&str>,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        let strategy = strategy.unwrap_or("unique-id");
        let strategy = if ["unique-id", "grouped-by-tag"].contains(&strategy) {
            strategy
        } else {
            log::warn!(
                "Unsupported strategy \"{}\", defaulting to \"unique-id\".",
                strategy
            );
            "unique-id"
        };

        self.load_ignore_rules(ignore_path).await;

        let path = Path::new(file_path);
        let meta = fs::metadata(path).await?;
        let cwd = Self::resolve_base_dir(base_dir);
        let relative_path = path.strip_prefix(&cwd).unwrap_or(path).to_string_lossy();
        let relative_path = Self::posix_path(&relative_path);

        // Treat an empty rules slice as "no multi-level".
        let multi_level_rules = multi_level_rules.filter(|rules| !rules.is_empty());

        if meta.is_file() {
            self.handle_file(
                file_path,
                &relative_path,
                unique_id_elements,
                strategy,
                pre_purge,
                post_purge,
                format,
                multi_level_rules,
                decompose_rules,
                sidecar_specs,
            )
            .await?;
        } else {
            // Anything that isn't a regular file is treated as a directory; fs::metadata on
            // the caller already errored out if the path didn't exist.
            self.handle_directory(
                file_path,
                unique_id_elements,
                strategy,
                pre_purge,
                post_purge,
                format,
                multi_level_rules,
                decompose_rules,
                sidecar_specs,
                base_dir,
            )
            .await?;
        }

        Ok(())
    }

    /// Resolve the directory that ignore-matching paths are computed relative to.
    /// `Some(dir)` is used verbatim (the caller — e.g. Node bindings running
    /// inside a `worker_threads` pool, where `process.chdir()` is unavailable —
    /// already knows its project root); `None` falls back to the process's
    /// actual working directory, preserving the original CLI behavior.
    fn resolve_base_dir(base_dir: Option<&str>) -> std::path::PathBuf {
        match base_dir {
            Some(dir) => Path::new(dir).to_path_buf(),
            None => std::env::current_dir().unwrap_or_else(|_| Path::new(".").to_path_buf()),
        }
    }

    #[allow(clippy::too_many_arguments)]
    async fn handle_file(
        &self,
        file_path: &str,
        relative_path: &str,
        unique_id_elements: Option<&str>,
        strategy: &str,
        pre_purge: bool,
        post_purge: bool,
        format: &str,
        multi_level_rules: Option<&[MultiLevelRule]>,
        decompose_rules: Option<&[DecomposeRule]>,
        sidecar_specs: Option<&[SidecarSpec]>,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        let resolved = Path::new(file_path)
            .canonicalize()
            .unwrap_or_else(|_| Path::new(file_path).to_path_buf());
        let resolved_str = normalize_path_unix(&resolved.to_string_lossy());

        if !Self::is_xml_file(&resolved_str) {
            log::error!(
                "The file path provided is not an XML file: {}",
                resolved_str
            );
            return Ok(());
        }

        if self.is_ignored(relative_path) {
            log::warn!("File ignored by ignore rules: {}", resolved_str);
            return Ok(());
        }

        let dir_path = resolved.parent().unwrap_or(Path::new("."));
        let dir_path_str = normalize_path_unix(&dir_path.to_string_lossy());
        Self::process_file(
            dir_path_str,
            strategy.to_string(),
            resolved_str,
            unique_id_elements.map(str::to_string),
            pre_purge,
            post_purge,
            format.to_string(),
            multi_level_rules.map(<[MultiLevelRule]>::to_vec),
            decompose_rules.map(<[DecomposeRule]>::to_vec),
            sidecar_specs.map(<[SidecarSpec]>::to_vec),
        )
        .await
    }

    #[allow(clippy::too_many_arguments)]
    async fn handle_directory(
        &self,
        dir_path: &str,
        unique_id_elements: Option<&str>,
        strategy: &str,
        pre_purge: bool,
        post_purge: bool,
        format: &str,
        multi_level_rules: Option<&[MultiLevelRule]>,
        decompose_rules: Option<&[DecomposeRule]>,
        sidecar_specs: Option<&[SidecarSpec]>,
        base_dir: Option<&str>,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        let dir_path = normalize_path_unix(dir_path);
        let mut entries = fs::read_dir(&dir_path).await?;
        let cwd = Self::resolve_base_dir(base_dir);

        // Ignore-checking needs `&self`, so this discovery pass stays sequential; it's cheap
        // (just readdir + string matching, no XML parsing or file writes).
        let mut files_to_process: Vec<String> = Vec::new();
        while let Some(entry) = entries.next_entry().await? {
            let sub_path = entry.path();
            let sub_file_path = sub_path.to_string_lossy();
            let relative_sub = sub_path
                .strip_prefix(&cwd)
                .unwrap_or(&sub_path)
                .to_string_lossy();
            let relative_sub = Self::posix_path(&relative_sub);

            if !Self::is_processable_xml_entry(sub_path.is_file(), &sub_file_path) {
                continue;
            }
            if self.is_ignored(&relative_sub) {
                log::warn!("File ignored by ignore rules: {}", sub_file_path);
                continue;
            }
            files_to_process.push(normalize_path_unix(&sub_file_path));
        }

        // A directory with 0 or 1 processable files -- e.g. a bot/flow/custom-metadata
        // component folder holding a single record -- gets nothing from the concurrency
        // machinery below: there's no second file to overlap it against, only the fixed cost
        // of standing up a semaphore and JoinSet for one task. Skip straight to processing it
        // inline instead.
        if files_to_process.len() <= 1 {
            for file_path in files_to_process {
                Self::process_file(
                    dir_path.clone(),
                    strategy.to_string(),
                    file_path,
                    unique_id_elements.map(str::to_string),
                    pre_purge,
                    post_purge,
                    format.to_string(),
                    multi_level_rules.map(<[MultiLevelRule]>::to_vec),
                    decompose_rules.map(<[DecomposeRule]>::to_vec),
                    sidecar_specs.map(<[SidecarSpec]>::to_vec),
                )
                .await?;
            }
            return Ok(());
        }

        // Fan out across the shared multi-threaded tokio runtime instead of disassembling one
        // file at a time: this directory-mode call is the common case (a whole metadata type's
        // parent XML files in one call), so a plain sequential loop here left every core but one
        // idle no matter how many files there were. `process_file` needs no instance state, so
        // each task is spawned with owned copies of its inputs and runs fully independently;
        // bounded by a semaphore so a directory with thousands of files doesn't spawn thousands
        // of tasks (and open file handles) at once.
        let semaphore = Arc::new(Semaphore::new(DIRECTORY_CONCURRENCY));
        let mut join_set = JoinSet::new();
        for file_path in files_to_process {
            let dir_path = dir_path.clone();
            let strategy = strategy.to_string();
            let unique_id_elements = unique_id_elements.map(str::to_string);
            let format = format.to_string();
            let multi_level_rules = multi_level_rules.map(<[MultiLevelRule]>::to_vec);
            let decompose_rules = decompose_rules.map(<[DecomposeRule]>::to_vec);
            let sidecar_specs = sidecar_specs.map(<[SidecarSpec]>::to_vec);
            let semaphore = Arc::clone(&semaphore);

            join_set.spawn(async move {
                let _permit = semaphore.acquire_owned().await.expect("semaphore closed");
                Self::process_file(
                    dir_path,
                    strategy,
                    file_path,
                    unique_id_elements,
                    pre_purge,
                    post_purge,
                    format,
                    multi_level_rules,
                    decompose_rules,
                    sidecar_specs,
                )
                .await
            });
        }

        while let Some(joined) = join_set.join_next().await {
            joined.map_err(|e| Box::new(e) as Box<dyn std::error::Error + Send + Sync>)??;
        }

        Ok(())
    }

    #[allow(clippy::too_many_arguments)]
    async fn process_file(
        dir_path: String,
        strategy: String,
        file_path: String,
        unique_id_elements: Option<String>,
        pre_purge: bool,
        post_purge: bool,
        format: String,
        multi_level_rules: Option<Vec<MultiLevelRule>>,
        decompose_rules: Option<Vec<DecomposeRule>>,
        sidecar_specs: Option<Vec<SidecarSpec>>,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        // Owned params so this can be `tokio::spawn`ed from `handle_directory` (spawned
        // futures must be `'static`); shadow back to borrowed views under the same names
        // so the body below is unchanged from the pre-concurrency version.
        let dir_path = dir_path.as_str();
        let file_path = file_path.as_str();
        let strategy = strategy.as_str();
        let format = format.as_str();
        let unique_id_elements = unique_id_elements.as_deref();
        let multi_level_rules = multi_level_rules.as_deref();
        let decompose_rules = decompose_rules.as_deref();
        let sidecar_specs = sidecar_specs.as_deref();

        log::debug!("Parsing file to disassemble: {}", file_path);

        let file_name = Path::new(file_path)
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("output");
        let base_name = Self::output_dir_basename(file_name);
        let output_path = Path::new(dir_path).join(base_name);

        if Self::should_pre_purge_output(pre_purge, output_path.exists()) {
            fs::remove_dir_all(&output_path).await.ok();
        }

        // Capture root key order BEFORE sidecar extraction so the sidecar element
        // names appear at their original positions in .key_order.json.
        let pre_extraction_key_order: Option<Vec<String>> =
            if sidecar_specs.is_some_and(|s| !s.is_empty()) {
                parse_xml(file_path).await.and_then(|parsed| {
                    let obj = parsed.as_object()?;
                    let root_key = obj.keys().find(|k| *k != "?xml")?;
                    obj.get(root_key)?.as_object().map(|root_obj| {
                        root_obj
                            .keys()
                            .filter(|k| !k.starts_with('@'))
                            .cloned()
                            .collect()
                    })
                })
            } else {
                None
            };

        // Extract sidecar elements before normal disassembly so the disassembler
        // sees schema-free XML and does not try to shard the embedded blob.
        // The original file is never modified; stripped content is written to a
        // temp file that is deleted after disassembly. Sidecar files are written
        // into the output directory after disassembly creates it.
        let extraction_result = if let Some(specs) = sidecar_specs {
            if !specs.is_empty() {
                extract_sidecar_elements(file_path, specs).await?
            } else {
                None
            }
        } else {
            None
        };

        let temp_file: Option<tempfile::NamedTempFile>;
        let disassemble_path: &str;
        if let Some((xml, _)) = &extraction_result {
            let mut tmp = tempfile::Builder::new()
                .suffix(".xml")
                .tempfile_in(Path::new(file_path).parent().unwrap_or(Path::new(".")))?;
            tmp.write_all(xml.as_bytes())?;
            temp_file = Some(tmp);
            disassemble_path = temp_file
                .as_ref()
                .unwrap()
                .path()
                .to_str()
                .unwrap_or(file_path);
        } else {
            temp_file = None;
            disassemble_path = file_path;
        }

        build_disassembled_files_unified(BuildDisassembledFilesOptions {
            file_path: disassemble_path,
            disassembled_path: output_path.to_str().unwrap_or("."),
            base_name: file_name,
            post_purge,
            format,
            unique_id_elements,
            strategy,
            decompose_rules,
        })
        .await?;

        drop(temp_file); // deletes the temp file

        // Write sidecar files into the output directory, plus a .sidecars.json
        // metadata file so reassembly can auto-detect specs without CLI flags.
        if let Some((_, sidecars)) = &extraction_result {
            for (_, extension, content, _) in sidecars {
                let sidecar_path = output_path.join(format!("{}.{}", base_name, extension));
                fs::write(&sidecar_path, content).await?;
            }
            if let Some(specs) = sidecar_specs {
                // Enrich each spec with the original_format detected at extraction time
                // so reassembly can convert the sidecar content back to the correct format.
                let enriched: Vec<SidecarSpec> = specs
                    .iter()
                    .map(|spec| {
                        let original_format = sidecars
                            .iter()
                            .find(|(el, _, _, _)| el == &spec.element)
                            .and_then(|(_, _, _, fmt)| fmt.clone());
                        SidecarSpec {
                            element: spec.element.clone(),
                            extension: spec.extension.clone(),
                            original_format,
                        }
                    })
                    .collect();
                if let Ok(json) = serde_json::to_string(&enriched) {
                    let _ = fs::write(output_path.join(".sidecars.json"), json).await;
                }
            }
        }

        // Overwrite .key_order.json with the pre-extraction order so sidecar
        // element names appear at their original positions during reassembly.
        if let Some(full_order) = pre_extraction_key_order {
            let key_order_path = output_path.join(".key_order.json");
            if let Ok(json) = serde_json::to_string(&full_order) {
                let _ = fs::write(&key_order_path, json).await;
            }
        }

        // Apply each multi-level rule in order. Each rule walks the same disassembly tree
        // independently; rules are merged into the shared `.multi_level.json` so reassembly
        // can replay them in order.
        if let Some(rules) = multi_level_rules {
            for rule in rules {
                Self::recursively_disassemble_multi_level(&output_path, rule, format).await?;
            }
        }

        Ok(())
    }

    /// Recursively walk the disassembly output; for XML files matching the rule's file_pattern,
    /// strip the root and re-disassemble with the rule's unique_id_elements.
    async fn recursively_disassemble_multi_level(
        dir_path: &Path,
        rule: &MultiLevelRule,
        format: &str,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        let mut config = crate::xml::multi_level::load_multi_level_config(dir_path)
            .await
            .unwrap_or_default();

        let mut stack = vec![dir_path.to_path_buf()];
        while let Some(current) = stack.pop() {
            let mut entries = Vec::new();
            let mut read_dir = fs::read_dir(&current).await?;
            while let Some(entry) = read_dir.next_entry().await? {
                entries.push(entry);
            }

            for entry in entries {
                let path = entry.path();
                let path_str = path.to_string_lossy().to_string();

                if path.is_dir() {
                    stack.push(path);
                    continue;
                }
                // Anything not a directory is processed as a regular file below.
                {
                    let name = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
                    let path_str_check = path.to_string_lossy();
                    if !Self::file_matches_multi_level_rule(
                        name,
                        &path_str_check,
                        &rule.file_pattern,
                    ) {
                        continue;
                    }

                    let parsed = match parse_xml(&path_str).await {
                        Some(p) => p,
                        None => continue,
                    };
                    if !Self::has_element_to_strip(&parsed, &rule.root_to_strip) {
                        continue;
                    }

                    let wrap_xmlns = capture_xmlns_from_root(&parsed).unwrap_or_default();

                    let stripped_xml = match strip_root_and_build_xml(&parsed, &rule.root_to_strip)
                    {
                        Some(xml) => xml,
                        None => continue,
                    };

                    fs::write(&path, stripped_xml).await?;

                    let file_stem = path
                        .file_stem()
                        .and_then(|s| s.to_str())
                        .unwrap_or("output");
                    let output_dir_name = Self::output_dir_basename(file_stem);
                    let parent = path.parent().unwrap_or(dir_path);
                    let second_level_output = parent.join(output_dir_name);

                    build_disassembled_files_unified(BuildDisassembledFilesOptions {
                        file_path: &path_str,
                        disassembled_path: second_level_output.to_str().unwrap_or("."),
                        base_name: output_dir_name,
                        post_purge: true,
                        format,
                        unique_id_elements: Some(&rule.unique_id_elements),
                        strategy: "unique-id",
                        decompose_rules: None,
                    })
                    .await?;

                    // Find an existing entry for this rule by (file_pattern, root_to_strip).
                    // Multiple rules may co-exist in `.multi_level.json` (one per logical
                    // segment); per-rule deduplication keeps each one a singleton.
                    let existing_idx = config
                        .rules
                        .iter()
                        .position(|r| Self::rules_have_same_identity(r, rule));
                    match existing_idx {
                        None => {
                            let wrap_root = Self::root_element_name_from_parsed(
                                &parsed,
                                &rule.wrap_root_element,
                            );
                            let path_segment = if rule.path_segment.is_empty() {
                                path_segment_from_file_pattern(&rule.file_pattern)
                            } else {
                                rule.path_segment.clone()
                            };
                            let stored_xmlns = if rule.wrap_xmlns.is_empty() {
                                wrap_xmlns
                            } else {
                                rule.wrap_xmlns.clone()
                            };
                            config.rules.push(MultiLevelRule {
                                file_pattern: rule.file_pattern.clone(),
                                root_to_strip: rule.root_to_strip.clone(),
                                unique_id_elements: rule.unique_id_elements.clone(),
                                path_segment,
                                // Persist document root (e.g. LoyaltyProgramSetup) so reassembly uses it
                                // as root with xmlns; path_segment is the inner wrapper in each file.
                                wrap_root_element: wrap_root,
                                wrap_xmlns: stored_xmlns,
                            });
                        }
                        Some(idx) => {
                            // Backfill xmlns from the source if we didn't have one yet; otherwise
                            // leave the existing entry alone (the first observed file wins).
                            if config.rules[idx].wrap_xmlns.is_empty() {
                                config.rules[idx].wrap_xmlns = wrap_xmlns;
                            }
                        }
                    }
                }
            }
        }

        if !config.rules.is_empty() {
            save_multi_level_config(dir_path, &config).await?;
        }

        Ok(())
    }
}

impl Default for DisassembleXmlFileHandler {
    fn default() -> Self {
        Self::new()
    }
}

/// Extract the text content of named XML elements in memory and return the
/// stripped XML plus the sidecar payloads. The caller is responsible for
/// writing sidecar files; the original file on disk is never modified.
///
/// Returns `None` when no matching element was found.
/// Returns `Some((stripped_xml, sidecars))` where each sidecar entry is
/// `(element, extension, content, original_format)`.
///
/// Quick-xml's parser automatically unescapes entity references in text
/// content, so the sidecar receives the raw, unescaped bytes of the embedded
/// document — exactly what you'd write by hand.
async fn extract_sidecar_elements(
    file_path: &str,
    specs: &[SidecarSpec],
) -> Result<
    Option<(String, Vec<(String, String, String, Option<String>)>)>,
    Box<dyn std::error::Error + Send + Sync>,
> {
    let raw = fs::read_to_string(file_path).await?;
    let Some(mut parsed) = parse_xml_from_str(&raw, file_path) else {
        return Ok(None);
    };

    // parse_xml_cdata drops the XML declaration; recover it from the raw bytes and
    // re-inject so build_xml_string emits it in the temp file. Without this the
    // shards produced by build_disassembled_files_unified lack the declaration and
    // the reassembler falls back to a synthetic default instead of the original.
    if let (Some(obj), Some(decl)) = (
        parsed.as_object_mut(),
        extract_xml_declaration_from_raw(&raw),
    ) {
        obj.insert("?xml".to_string(), decl);
    }

    let root_key = parsed
        .as_object()
        .and_then(|o| o.keys().find(|k| *k != "?xml").cloned());
    let Some(root_key) = root_key else {
        return Ok(None);
    };

    // (element, extension, content, original_format)
    let mut sidecars: Vec<(String, String, String, Option<String>)> = Vec::new();
    if let Some(root_val) = parsed.as_object_mut().and_then(|o| o.get_mut(&root_key)) {
        if let Some(root_obj) = root_val.as_object_mut() {
            for spec in specs {
                let Some(elem_val) = root_obj.remove(&spec.element) else {
                    continue;
                };
                // The XML parser always yields Value::Object for element values;
                // non-Object shapes are unexpected — restore and skip to preserve data.
                let text = match &elem_val {
                    serde_json::Value::Object(obj) => obj
                        .get("#text")
                        .and_then(|v| v.as_str())
                        .unwrap_or("")
                        .to_string(),
                    _ => {
                        root_obj.insert(spec.element.clone(), elem_val);
                        continue;
                    }
                };
                let original_format = detect_content_format(&text);
                sidecars.push((
                    spec.element.clone(),
                    spec.extension.clone(),
                    convert_sidecar_content(&text, &spec.extension),
                    original_format,
                ));
            }
        }
    }

    if sidecars.is_empty() {
        Ok(None)
    } else {
        Ok(Some((build_xml_string(&parsed), sidecars)))
    }
}

/// Detect whether `text` is JSON or YAML. Returns `Some("json")`, `Some("yaml")`,
/// or `None` for content that cannot be parsed as either.
fn detect_content_format(text: &str) -> Option<String> {
    if serde_json::from_str::<serde_json::Value>(text).is_ok() {
        Some("json".to_string())
    } else if serde_saphyr::from_str::<serde_json::Value>(text).is_ok() {
        Some("yaml".to_string())
    } else {
        None
    }
}

/// Convert raw text extracted from an XML element to the format implied by `extension`.
///
/// - `json` → parse as YAML (superset of JSON) then re-emit as pretty JSON
/// - `yaml` / `yml` → convert only when source is strict JSON; YAML content passes through
///   unchanged so quote style, indentation, and formatting are preserved on round-trip
/// - anything else → pass through unchanged
///
/// Falls back to raw text with a warning when the content cannot be parsed.
fn convert_sidecar_content(text: &str, extension: &str) -> String {
    match extension.to_ascii_lowercase().as_str() {
        "json" => match serde_saphyr::from_str::<serde_json::Value>(text) {
            // Serializing a serde_json::Value cannot fail.
            Ok(val) => serde_json::to_string_pretty(&val).unwrap_or_else(|_| text.to_string()),
            Err(e) => {
                log::warn!(
                    "sidecar: could not parse content for JSON conversion ({e}); using raw text"
                );
                text.to_string()
            }
        },
        "yaml" | "yml" => {
            // Only convert when the source is strict JSON — YAML content passes through
            // unchanged to avoid re-serialization changing quote style or formatting.
            if serde_json::from_str::<serde_json::Value>(text).is_ok() {
                match serde_json::from_str::<serde_json::Value>(text)
                    .ok()
                    .and_then(|v| serde_saphyr::to_string(&v).ok())
                {
                    Some(yaml) => yaml,
                    None => {
                        log::warn!("sidecar: YAML serialization failed; using raw text");
                        text.to_string()
                    }
                }
            } else {
                text.to_string()
            }
        }
        _ => text.to_string(),
    }
}

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

    #[test]
    #[allow(clippy::default_constructed_unit_structs)]
    fn disassemble_handler_default_equals_new() {
        let _ = DisassembleXmlFileHandler::default();
    }

    #[test]
    fn is_xml_file_matches_case_insensitively() {
        assert!(DisassembleXmlFileHandler::is_xml_file("foo.xml"));
        assert!(DisassembleXmlFileHandler::is_xml_file("BAR.XML"));
        assert!(!DisassembleXmlFileHandler::is_xml_file("foo.txt"));
    }

    #[test]
    fn posix_path_converts_backslashes() {
        assert_eq!(
            DisassembleXmlFileHandler::posix_path(r"C:\Users\name\file.xml"),
            "C:/Users/name/file.xml"
        );
    }

    #[tokio::test]
    async fn load_ignore_rules_noop_when_path_missing() {
        let mut handler = DisassembleXmlFileHandler::new();
        handler
            .load_ignore_rules("/definitely/does/not/exist/.ignore")
            .await;
        assert!(handler.ign.is_none());
    }

    #[tokio::test]
    async fn load_ignore_rules_builds_matcher() {
        let temp = tempfile::tempdir().unwrap();
        let path = temp.path().join(".ignore");
        tokio::fs::write(&path, "*.xml\n").await.unwrap();
        let mut handler = DisassembleXmlFileHandler::new();
        handler.load_ignore_rules(path.to_str().unwrap()).await;
        assert!(handler.ign.is_some());
        assert!(handler.is_ignored("file.xml"));
        assert!(!handler.is_ignored("file.txt"));
    }

    #[test]
    fn is_ignored_default_false_without_rules() {
        let handler = DisassembleXmlFileHandler::new();
        assert!(!handler.is_ignored("some/path.xml"));
    }

    #[test]
    fn output_dir_basename_strips_only_last_dot_segment() {
        // Plain Salesforce-style metadata: strip the `.<suffix>-meta` tail.
        assert_eq!(
            DisassembleXmlFileHandler::output_dir_basename("HR_Admin.permissionset-meta"),
            "HR_Admin"
        );
        assert_eq!(
            DisassembleXmlFileHandler::output_dir_basename("Get_Info.flow-meta"),
            "Get_Info"
        );
    }

    #[test]
    fn output_dir_basename_preserves_dotted_full_names() {
        // Approval processes are named `<sobject>.<process>` which yields a stem containing
        // *two* dots. The old `split('.').next()` returned just `<sobject>`, causing
        // distinct processes for the same sobject to land in the same output directory and
        // silently merge during reassembly. The new behaviour keeps the dotted fullName.
        assert_eq!(
            DisassembleXmlFileHandler::output_dir_basename(
                "Account_Merge__c.New_Account_Merges_2.approvalProcess-meta"
            ),
            "Account_Merge__c.New_Account_Merges_2"
        );
        assert_eq!(
            DisassembleXmlFileHandler::output_dir_basename(
                "Account_Merge__c.New_Account_Merges_3.approvalProcess-meta"
            ),
            "Account_Merge__c.New_Account_Merges_3"
        );
        // Quick actions follow the same `<sobject>.<action>` pattern.
        assert_eq!(
            DisassembleXmlFileHandler::output_dir_basename("Case.LogACall.quickAction-meta"),
            "Case.LogACall"
        );
    }

    #[test]
    fn is_processable_xml_entry_true_only_for_regular_xml_files() {
        // Pin both the `is_file && is_xml_file` conjunction and the
        // outer `!` at the call site. All four quadrants of
        // (is_file, is_xml) are covered.
        assert!(DisassembleXmlFileHandler::is_processable_xml_entry(
            true, "foo.xml"
        ));
        assert!(!DisassembleXmlFileHandler::is_processable_xml_entry(
            false, "foo.xml"
        ));
        assert!(!DisassembleXmlFileHandler::is_processable_xml_entry(
            true, "foo.txt"
        ));
        assert!(!DisassembleXmlFileHandler::is_processable_xml_entry(
            false, "foo.txt"
        ));
    }

    #[test]
    fn should_pre_purge_output_requires_both_flag_and_existing_dir() {
        // `pre_purge=true` alone must not delete a missing directory
        // (that's a benign no-op, not an error); an existing directory
        // alone must not be deleted unless the caller asked for purge.
        assert!(DisassembleXmlFileHandler::should_pre_purge_output(
            true, true
        ));
        assert!(!DisassembleXmlFileHandler::should_pre_purge_output(
            true, false
        ));
        assert!(!DisassembleXmlFileHandler::should_pre_purge_output(
            false, true
        ));
        assert!(!DisassembleXmlFileHandler::should_pre_purge_output(
            false, false
        ));
    }

    #[test]
    fn file_matches_multi_level_rule_requires_xml_extension() {
        // Non-`.xml` files are skipped regardless of pattern membership.
        assert!(!DisassembleXmlFileHandler::file_matches_multi_level_rule(
            "Foo.txt",
            "/dir/Foo.txt",
            "Foo"
        ));
    }

    #[test]
    fn file_matches_multi_level_rule_when_filename_contains_pattern() {
        assert!(DisassembleXmlFileHandler::file_matches_multi_level_rule(
            "MyPattern.xml",
            "/dir/MyPattern.xml",
            "MyPattern"
        ));
    }

    #[test]
    fn file_matches_multi_level_rule_when_only_full_path_contains_pattern() {
        // The pattern may live in a parent directory name even if the
        // bare file name is something generic like `meta.xml`.
        assert!(DisassembleXmlFileHandler::file_matches_multi_level_rule(
            "child.xml",
            "/parentPattern/child.xml",
            "parentPattern"
        ));
    }

    #[test]
    fn file_matches_multi_level_rule_false_when_pattern_absent_everywhere() {
        assert!(!DisassembleXmlFileHandler::file_matches_multi_level_rule(
            "Foo.xml",
            "/dir/Foo.xml",
            "MissingPattern"
        ));
    }

    #[test]
    fn has_element_to_strip_when_root_key_matches() {
        let parsed = serde_json::json!({"Foo": {"a": "b"}});
        assert!(DisassembleXmlFileHandler::has_element_to_strip(
            &parsed, "Foo"
        ));
    }

    #[test]
    fn has_element_to_strip_when_root_contains_target_child() {
        let parsed = serde_json::json!({"Foo": {"Bar": {"a": "b"}}});
        assert!(DisassembleXmlFileHandler::has_element_to_strip(
            &parsed, "Bar"
        ));
    }

    #[test]
    fn has_element_to_strip_false_when_target_absent() {
        let parsed = serde_json::json!({"Foo": {"a": "b"}});
        assert!(!DisassembleXmlFileHandler::has_element_to_strip(
            &parsed, "Missing"
        ));
    }

    #[test]
    fn has_element_to_strip_false_for_non_object_or_decl_only() {
        assert!(!DisassembleXmlFileHandler::has_element_to_strip(
            &serde_json::json!("primitive"),
            "Foo"
        ));
        assert!(!DisassembleXmlFileHandler::has_element_to_strip(
            &serde_json::json!({"?xml": {}}),
            "Foo"
        ));
    }

    fn rule(pattern: &str, root: &str) -> MultiLevelRule {
        MultiLevelRule {
            file_pattern: pattern.to_string(),
            root_to_strip: root.to_string(),
            unique_id_elements: String::new(),
            path_segment: String::new(),
            wrap_root_element: String::new(),
            wrap_xmlns: String::new(),
        }
    }

    #[test]
    fn rules_share_identity_when_pattern_and_root_match() {
        assert!(DisassembleXmlFileHandler::rules_have_same_identity(
            &rule("p", "R"),
            &rule("p", "R"),
        ));
    }

    #[test]
    fn rules_differ_when_file_pattern_differs() {
        assert!(!DisassembleXmlFileHandler::rules_have_same_identity(
            &rule("p1", "R"),
            &rule("p2", "R"),
        ));
    }

    #[test]
    fn rules_differ_when_root_to_strip_differs() {
        assert!(!DisassembleXmlFileHandler::rules_have_same_identity(
            &rule("p", "R1"),
            &rule("p", "R2"),
        ));
    }

    #[test]
    fn root_element_name_finds_first_non_declaration_key() {
        let parsed = serde_json::json!({"?xml": {}, "MyRoot": {"a": "b"}});
        assert_eq!(
            DisassembleXmlFileHandler::root_element_name_from_parsed(&parsed, "fallback"),
            "MyRoot"
        );
    }

    #[test]
    fn root_element_name_falls_back_when_only_declaration_present() {
        let parsed = serde_json::json!({"?xml": {}});
        assert_eq!(
            DisassembleXmlFileHandler::root_element_name_from_parsed(&parsed, "FallbackRoot"),
            "FallbackRoot"
        );
    }

    #[test]
    fn root_element_name_falls_back_for_non_object() {
        let parsed = serde_json::json!("primitive");
        assert_eq!(
            DisassembleXmlFileHandler::root_element_name_from_parsed(&parsed, "Fb"),
            "Fb"
        );
    }

    #[test]
    fn output_dir_basename_no_dot_returns_stem_unchanged() {
        // Stems without any dot are passed through verbatim (no extension to strip).
        assert_eq!(DisassembleXmlFileHandler::output_dir_basename("Foo"), "Foo");
        assert_eq!(DisassembleXmlFileHandler::output_dir_basename(""), "");
    }

    #[test]
    fn convert_sidecar_content_yaml_to_json() {
        // Uses nested YAML matching the fixture shape (quoted strings, string-keyed
        // mappings, dotted version strings) to catch YAML→serde_json
        // numeric type failures that affect simple-key tests but not complex YAML.
        let yaml = "openapi: 3.0.1\ninfo:\n  title: \"@AuraEnabled Apex method APIs\"\n  version: 1.0.0\npaths:\n  /uploadFile:\n    post:\n      operationId: uploadFile\n      responses:\n        \"200\":\n          description: OK\n";
        let out = convert_sidecar_content(yaml, "json");
        let val: serde_json::Value = serde_json::from_str(&out).expect("output must be valid JSON");
        assert_eq!(val["openapi"], "3.0.1");
        assert_eq!(val["info"]["title"], "@AuraEnabled Apex method APIs");
        assert_eq!(val["info"]["version"], "1.0.0");
        assert_eq!(
            val["paths"]["/uploadFile"]["post"]["operationId"],
            "uploadFile"
        );
    }

    #[test]
    fn convert_sidecar_content_json_to_yaml() {
        let json = r#"{"key":"value","num":42}"#;
        let out = convert_sidecar_content(json, "yaml");
        // Output must be YAML, not raw JSON — if the yaml arm were deleted, the `_ =>` fallback
        // would return the original JSON string, which is also parseable as YAML and would fool
        // a parse-only assertion. Asserting strict-JSON parse fails pins the arm deletion mutant.
        assert!(
            serde_json::from_str::<serde_json::Value>(&out).is_err(),
            "output must be YAML format, not raw JSON: {out}"
        );
        let val: serde_json::Value =
            serde_saphyr::from_str(&out).expect("output must be valid YAML");
        assert_eq!(val["key"], "value");
        assert_eq!(val["num"], 42);
    }

    #[test]
    fn convert_sidecar_content_json_to_json_prettifies() {
        let compact = r#"{"a":1}"#;
        let out = convert_sidecar_content(compact, "json");
        // Pretty JSON has newlines and indentation.
        assert!(out.contains('\n'), "expected pretty JSON, got: {out}");
        let val: serde_json::Value = serde_json::from_str(&out).unwrap();
        assert_eq!(val["a"], 1);
    }

    #[test]
    fn convert_sidecar_content_unknown_extension_passes_through() {
        let raw = "arbitrary: content: here";
        assert_eq!(convert_sidecar_content(raw, "txt"), raw);
        assert_eq!(convert_sidecar_content(raw, ""), raw);
    }

    #[test]
    fn convert_sidecar_content_malformed_falls_back_to_raw() {
        // Tabs inside a YAML flow scalar make it unparseable as YAML/JSON.
        let bad = "{{{{ not valid json or yaml at all >>>>>";
        assert_eq!(convert_sidecar_content(bad, "json"), bad);
        assert_eq!(convert_sidecar_content(bad, "yaml"), bad);
    }

    #[test]
    fn convert_sidecar_content_yml_extension_same_as_yaml() {
        let json = r#"{"x":true}"#;
        let out = convert_sidecar_content(json, "yml");
        let val: serde_json::Value = serde_saphyr::from_str(&out).unwrap();
        assert_eq!(val["x"], true);
    }

    #[test]
    fn convert_sidecar_content_yaml_passes_through_unchanged() {
        // YAML content with a yaml extension must NOT be re-serialized — re-serializing changes
        // double quotes to single quotes, breaking byte-for-byte round-trip assertions.
        let yaml = "title: \"@AuraEnabled Apex method APIs\"\nversion: 1.0.0\n";
        assert_eq!(convert_sidecar_content(yaml, "yaml"), yaml);
        assert_eq!(convert_sidecar_content(yaml, "yml"), yaml);
    }

    #[test]
    fn detect_content_format_recognizes_json_yaml_and_neither() {
        assert_eq!(
            detect_content_format(r#"{"a":1}"#),
            Some("json".to_string())
        );
        assert_eq!(
            detect_content_format("a: 1\nb: 2\n"),
            Some("yaml".to_string())
        );
        // Tabs are illegal for indentation in both JSON and (this construct) YAML.
        assert_eq!(detect_content_format("\tnot: \tvalid: \tanything"), None);
    }

    #[test]
    fn convert_sidecar_content_non_string_key_falls_back_to_raw() {
        // YAML permits compound (sequence) mapping keys via explicit-key
        // syntax; JSON object keys must be strings, so parsing this into a
        // serde_json::Value fails and the raw text must be returned unchanged.
        let yaml_with_sequence_key = "? [a, b]\n: value\n";
        assert_eq!(
            convert_sidecar_content(yaml_with_sequence_key, "json"),
            yaml_with_sequence_key
        );
    }

    #[tokio::test]
    async fn extract_sidecar_elements_returns_none_for_unparseable_xml() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("bad.xml");
        tokio::fs::write(&path, "<<not xml").await.unwrap();
        let specs = [SidecarSpec {
            element: "schema".to_string(),
            extension: "yaml".to_string(),
            original_format: None,
        }];
        let result = extract_sidecar_elements(path.to_str().unwrap(), &specs)
            .await
            .unwrap();
        assert!(result.is_none());
    }

    #[tokio::test]
    async fn extract_sidecar_elements_returns_none_when_no_root_element() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("decl_only.xml");
        tokio::fs::write(&path, r#"<?xml version="1.0" encoding="UTF-8"?>"#)
            .await
            .unwrap();
        let specs = [SidecarSpec {
            element: "schema".to_string(),
            extension: "yaml".to_string(),
            original_format: None,
        }];
        let result = extract_sidecar_elements(path.to_str().unwrap(), &specs)
            .await
            .unwrap();
        assert!(result.is_none());
    }

    #[tokio::test]
    async fn extract_sidecar_elements_returns_none_when_no_spec_element_present() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("no_match.xml");
        tokio::fs::write(
            &path,
            r#"<?xml version="1.0" encoding="UTF-8"?><Root><child>value</child></Root>"#,
        )
        .await
        .unwrap();
        let specs = [SidecarSpec {
            element: "schema".to_string(),
            extension: "yaml".to_string(),
            original_format: None,
        }];
        let result = extract_sidecar_elements(path.to_str().unwrap(), &specs)
            .await
            .unwrap();
        assert!(result.is_none());
    }

    #[tokio::test]
    async fn extract_sidecar_elements_extracts_matching_element() {
        let tmp = tempfile::tempdir().unwrap();
        let path = tmp.path().join("match.xml");
        tokio::fs::write(
            &path,
            r#"<?xml version="1.0" encoding="UTF-8"?><Root><schema>openapi: 3.0.1</schema><child>value</child></Root>"#,
        )
        .await
        .unwrap();
        let specs = [SidecarSpec {
            element: "schema".to_string(),
            extension: "yaml".to_string(),
            original_format: None,
        }];
        let (stripped, sidecars) = extract_sidecar_elements(path.to_str().unwrap(), &specs)
            .await
            .unwrap()
            .expect("schema element should be extracted");
        assert!(!stripped.contains("<schema>"));
        assert_eq!(sidecars.len(), 1);
        assert_eq!(sidecars[0].0, "schema");
    }
}