config_disassembler/xml/

cli.rs

//! Command-line interface for the xml-disassembler binary.
//!
//! Kept in the library crate so it can be exercised by unit tests and
//! the binary stays a thin shim.

use crate::xml::{
    DecomposeRule, DisassembleXmlFileHandler, MultiLevelRule, ReassembleXmlFileHandler, SidecarSpec,
};

/// Options parsed from disassemble CLI args.
pub struct DisassembleOpts<'a> {
    pub path: Option<&'a str>,
    pub unique_id_elements: Option<&'a str>,
    pub pre_purge: bool,
    pub post_purge: bool,
    /// Explicit `--ignore-path` value. `None` means the caller did not
    /// pass the flag and the runner should resolve a default (see
    /// [`crate::xml::ignore_file::resolve_xml_ignore_path`]).
    ///
    /// [`crate::xml::ignore_file::resolve_xml_ignore_path`]: crate::ignore_file::resolve_xml_ignore_path
    pub ignore_path: Option<&'a str>,
    pub format: &'a str,
    pub strategy: Option<&'a str>,
    pub multi_level: Option<String>,
    pub split_tags: Option<String>,
    /// Comma-separated `element:extension` pairs, e.g. `"schema:yaml"`.
    pub sidecar_elements: Option<String>,
}

/// Parse --split-tags spec for grouped-by-tag. Comma-separated rules; each rule:
/// `tag:mode:field` (path_segment defaults to tag) or `tag:path:mode:field`.
/// mode = "split" (one file per item) or "group" (group by field).
pub fn parse_decompose_spec(spec: &str) -> Vec<DecomposeRule> {
    let mut rules = Vec::new();
    for part in spec.split(',') {
        let part = part.trim();
        let segments: Vec<&str> = part.splitn(4, ':').collect();
        if segments.len() >= 3 {
            let tag = segments[0].to_string();
            let (path_segment, mode, field) = if segments.len() == 3 {
                (
                    tag.clone(),
                    segments[1].to_string(),
                    segments[2].to_string(),
                )
            } else {
                (
                    segments[1].to_string(),
                    segments[2].to_string(),
                    segments[3].to_string(),
                )
            };
            if !tag.is_empty() && !mode.is_empty() && !field.is_empty() {
                rules.push(DecomposeRule {
                    tag,
                    path_segment,
                    mode,
                    field,
                });
            }
        }
    }
    rules
}

/// Parse a single --multi-level spec: `file_pattern:root_to_strip:unique_id_elements`.
pub fn parse_multi_level_spec(spec: &str) -> Option<MultiLevelRule> {
    let parts: Vec<&str> = spec.splitn(3, ':').collect();
    if parts.len() != 3 {
        return None;
    }
    let (file_pattern, root_to_strip, unique_id_elements) = (parts[0], parts[1], parts[2]);
    if file_pattern.is_empty() || root_to_strip.is_empty() || unique_id_elements.is_empty() {
        return None;
    }
    let path_segment = crate::xml::path_segment_from_file_pattern(file_pattern);
    Some(MultiLevelRule {
        file_pattern: file_pattern.to_string(),
        root_to_strip: root_to_strip.to_string(),
        unique_id_elements: unique_id_elements.to_string(),
        path_segment: path_segment.clone(),
        wrap_root_element: root_to_strip.to_string(),
        wrap_xmlns: String::new(),
    })
}

/// Parse one or more --multi-level specs separated by `;`.
///
/// Each rule is `file_pattern:root_to_strip:unique_id_elements`; rules are joined by `;`
/// because the third part is itself a comma-separated list. Empty rules (e.g. trailing `;`)
/// are skipped silently. Malformed rules are dropped (the caller may warn separately if it
/// needs to surface that to the user).
pub fn parse_multi_level_specs(spec: &str) -> Vec<MultiLevelRule> {
    spec.split(';')
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .filter_map(parse_multi_level_spec)
        .collect()
}

/// Parse disassemble args: `<path> [options]`.
///
/// Iteration is driven by `args.iter()` rather than a manual `let mut i =
/// 0; while i < args.len()` cursor so that every option handler advances
/// the cursor by consuming the iterator. The previous index-based loop
/// scattered ~22 `i += 1` expressions across the body; every `+= -> -=`
/// or `+= -> *=` mutation on those lines produces an infinite loop (the
/// outer `while` never terminates because `i` either wraps around on
/// usize underflow or stays put), which `cargo-mutants` can only
/// classify as `timeout`. That added ~36 timeouts and ~36 minutes of
/// wall-clock to every full sweep with no actual signal. The iterator
/// form removes those mutation sites entirely; behavior is unchanged
/// and covered by the existing `parse_disassemble_args_*` tests.
pub fn parse_disassemble_args(args: &[String]) -> DisassembleOpts<'_> {
    let mut path = None;
    let mut unique_id_elements = None;
    let mut pre_purge = false;
    let mut post_purge = false;
    let mut ignore_path: Option<&str> = None;
    let mut format = "xml";
    let mut strategy = None;
    let mut multi_level = None;
    let mut split_tags = None;
    let mut sidecar_elements = None;

    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        if arg == "--postpurge" {
            post_purge = true;
        } else if arg == "--prepurge" {
            pre_purge = true;
        } else if let Some(rest) = arg.strip_prefix("--unique-id-elements=") {
            unique_id_elements = Some(rest);
        } else if arg == "--unique-id-elements" {
            if let Some(value) = iter.next() {
                unique_id_elements = Some(value.as_str());
            }
        } else if let Some(rest) = arg.strip_prefix("--ignore-path=") {
            ignore_path = Some(rest);
        } else if arg == "--ignore-path" {
            if let Some(value) = iter.next() {
                ignore_path = Some(value.as_str());
            }
        } else if let Some(rest) = arg.strip_prefix("--format=") {
            format = rest;
        } else if arg == "--format" {
            if let Some(value) = iter.next() {
                format = value.as_str();
            }
        } else if let Some(rest) = arg.strip_prefix("--strategy=") {
            strategy = Some(rest);
        } else if arg == "--strategy" {
            if let Some(value) = iter.next() {
                strategy = Some(value.as_str());
            }
        } else if let Some(rest) = arg.strip_prefix("--multi-level=") {
            multi_level = Some(rest.to_string());
        } else if arg == "--multi-level" {
            if let Some(value) = iter.next() {
                multi_level = Some(value.clone());
            }
        } else if let Some(rest) = arg.strip_prefix("--split-tags=") {
            split_tags = Some(rest.to_string());
        } else if arg == "--split-tags" || arg == "-p" {
            if let Some(value) = iter.next() {
                split_tags = Some(value.clone());
            }
        } else if let Some(rest) = arg.strip_prefix("--sidecar-elements=") {
            sidecar_elements = Some(rest.to_string());
        } else if arg == "--sidecar-elements" {
            if let Some(value) = iter.next() {
                sidecar_elements = Some(value.clone());
            }
        } else if arg.starts_with("--") {
            // Unknown long flag: silently skipped (matches the legacy
            // index-based parser, whose tests pin this behavior via
            // `parse_disassemble_args_unknown_long_flag_is_skipped`).
        } else if path.is_none() {
            path = Some(arg.as_str());
        }
        // Else: extra positional argument, dropped silently to match the
        // legacy parser (covered by
        // `parse_disassemble_args_trailing_extra_positional_ignored`).
    }

    DisassembleOpts {
        path,
        unique_id_elements,
        pre_purge,
        post_purge,
        ignore_path,
        format,
        strategy,
        multi_level,
        split_tags,
        sidecar_elements,
    }
}

/// Parse reassemble args: `<path> [extension] [--postpurge]`.
pub fn parse_reassemble_args(args: &[String]) -> (Option<&str>, Option<&str>, bool) {
    let mut path = None;
    let mut extension = None;
    let mut post_purge = false;
    for arg in args.iter() {
        if arg == "--postpurge" {
            post_purge = true;
        } else if path.is_none() {
            path = Some(arg.as_str());
        } else if extension.is_none() {
            extension = Some(arg.as_str());
        }
    }
    (path, extension, post_purge)
}

/// Parse a `--sidecar-elements` spec string into a list of [`SidecarSpec`]s.
///
/// Input format: comma-separated `element:extension` pairs, e.g.
/// `"schema:yaml"` or `"schema:yaml,wsdl:wsdl"`. Malformed pairs (missing
/// colon, empty element or extension) are silently dropped.
pub fn parse_sidecar_specs(spec: &str) -> Vec<SidecarSpec> {
    spec.split(',')
        .map(str::trim)
        .filter_map(|pair| {
            let (element, extension) = pair.split_once(':')?;
            let element = element.trim().to_string();
            let extension = extension.trim().to_string();
            if element.is_empty() || extension.is_empty() {
                return None;
            }
            Some(SidecarSpec { element, extension })
        })
        .collect()
}

/// Print CLI usage to stderr.
pub fn print_usage() {
    eprintln!("Usage: xml-disassembler <command> [options]");
    eprintln!("  disassemble <path> [options]     - Disassemble XML file or directory");
    eprintln!("    --postpurge                    - Delete original file/dir after disassembling (default: false)");
    eprintln!("    --prepurge                     - Remove existing disassembly output before running (default: false)");
    eprintln!(
        "    --unique-id-elements <list>    - Comma-separated element names for nested filenames"
    );
    eprintln!("    --ignore-path <path>           - Path to ignore file (default: .cdignore; falls back to .xmldisassemblerignore for backward compatibility)");
    eprintln!(
        "    --format <fmt>                 - Output format: xml, json, json5, yaml (default: xml)"
    );
    eprintln!(
        "    --strategy <name>              - unique-id or grouped-by-tag (default: unique-id)"
    );
    eprintln!("    --multi-level <spec>          - Further disassemble matching files: file_pattern:root_to_strip:unique_id_elements (multiple rules separated by ';')");
    eprintln!("    -p, --split-tags <spec>       - With grouped-by-tag: split/group nested tags (e.g. objectPermissions:split:object,fieldPermissions:group:field)");
    eprintln!("    --sidecar-elements <spec>     - Extract element text to companion files: element:extension (comma-separated, e.g. schema:yaml)");
    eprintln!("  reassemble <path> [extension] [--postpurge]  - Reassemble directory (default extension: xml); sidecar specs are auto-detected from .sidecars.json");
}

/// True when `args` only contains the program name (or is empty).
/// Pure helper extracted from `run` so the `args.len() < 2` guard
/// can be exercised at every boundary without spawning a process.
fn should_print_usage(args_len: usize) -> bool {
    args_len < 2
}

/// True when the user supplied a `--multi-level` spec that didn't
/// parse into any rules. Pure helper extracted from `run_disassemble`
/// so both legs of `spec.is_some() && parsed.is_empty()` are testable.
fn multi_level_spec_failed_to_parse(spec_present: bool, parsed_empty: bool) -> bool {
    spec_present && parsed_empty
}

/// True when the strategy is `grouped-by-tag` and decompose-spec
/// parsing should run. Extracting this guard avoids paying the cost
/// of parsing `--split-tags` (and triggering its destructive
/// behaviours under mutation testing) for any other strategy.
fn should_parse_decompose_rules(strategy: &str) -> bool {
    strategy == "grouped-by-tag"
}

/// Run the CLI with the given args. `args[0]` is expected to be the program name.
pub async fn run(args: Vec<String>) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    if should_print_usage(args.len()) {
        print_usage();
        return Ok(());
    }

    let command = &args[1];
    match command.as_str() {
        "disassemble" => run_disassemble(&args[2..]).await?,
        "reassemble" => run_reassemble(&args[2..]).await?,
        _ => {
            eprintln!("Unknown command: {}", command);
        }
    }

    Ok(())
}

async fn run_disassemble(args: &[String]) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let opts = parse_disassemble_args(args);
    let path = opts.path.unwrap_or(".");
    let strategy = opts.strategy.unwrap_or("unique-id");
    let multi_level_rules: Vec<MultiLevelRule> = opts
        .multi_level
        .as_deref()
        .map(parse_multi_level_specs)
        .unwrap_or_default();
    if multi_level_spec_failed_to_parse(opts.multi_level.is_some(), multi_level_rules.is_empty()) {
        eprintln!("Invalid --multi-level spec; use file_pattern:root_to_strip:unique_id_elements (multiple rules separated by ';')");
    }
    let decompose_rules: Vec<DecomposeRule> = if should_parse_decompose_rules(strategy) {
        opts.split_tags
            .as_ref()
            .map(|s| parse_decompose_spec(s))
            .unwrap_or_default()
    } else {
        Vec::new()
    };
    let decompose_rules_ref = if decompose_rules.is_empty() {
        None
    } else {
        Some(decompose_rules.as_slice())
    };
    let cwd = std::env::current_dir().unwrap_or_else(|_| std::path::Path::new(".").to_path_buf());
    let resolved_ignore = crate::ignore_file::resolve_xml_ignore_path(opts.ignore_path, &cwd);
    let multi_level_rules_ref = if multi_level_rules.is_empty() {
        None
    } else {
        Some(multi_level_rules.as_slice())
    };
    let sidecar_specs: Vec<SidecarSpec> = opts
        .sidecar_elements
        .as_deref()
        .map(parse_sidecar_specs)
        .unwrap_or_default();
    let sidecar_specs_ref = if sidecar_specs.is_empty() {
        None
    } else {
        Some(sidecar_specs.as_slice())
    };
    let mut handler = DisassembleXmlFileHandler::new();
    handler
        .disassemble(
            path,
            opts.unique_id_elements,
            Some(strategy),
            opts.pre_purge,
            opts.post_purge,
            &resolved_ignore,
            opts.format,
            multi_level_rules_ref,
            decompose_rules_ref,
            sidecar_specs_ref,
        )
        .await?;
    Ok(())
}

async fn run_reassemble(args: &[String]) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let (path, extension, post_purge) = parse_reassemble_args(args);
    let path = path.unwrap_or(".");
    let handler = ReassembleXmlFileHandler::new();
    handler
        .reassemble(path, extension.or(Some("xml")), post_purge, None)
        .await?;
    Ok(())
}

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

    fn sv(s: &str) -> String {
        s.to_string()
    }

    #[test]
    fn parse_decompose_spec_three_segments_defaults_path_segment_to_tag() {
        let rules = parse_decompose_spec("objectPermissions:split:object");
        assert_eq!(rules.len(), 1);
        let r = &rules[0];
        assert_eq!(r.tag, "objectPermissions");
        assert_eq!(r.path_segment, "objectPermissions");
        assert_eq!(r.mode, "split");
        assert_eq!(r.field, "object");
    }

    #[test]
    fn parse_decompose_spec_four_segments_uses_explicit_path_segment() {
        let rules = parse_decompose_spec("fieldPermissions:fieldPerms:group:field");
        assert_eq!(rules.len(), 1);
        let r = &rules[0];
        assert_eq!(r.tag, "fieldPermissions");
        assert_eq!(r.path_segment, "fieldPerms");
        assert_eq!(r.mode, "group");
        assert_eq!(r.field, "field");
    }

    #[test]
    fn parse_decompose_spec_comma_separated_rules_trims_whitespace() {
        let rules = parse_decompose_spec("a:split:f, b:group:g , c:x:split:y");
        assert_eq!(rules.len(), 3);
        assert_eq!(rules[0].tag, "a");
        assert_eq!(rules[1].tag, "b");
        assert_eq!(rules[2].tag, "c");
        assert_eq!(rules[2].path_segment, "x");
    }

    #[test]
    fn parse_decompose_spec_rejects_empty_segments() {
        // Too few segments
        assert!(parse_decompose_spec("only:two").is_empty());
        // Empty tag, mode, or field are filtered
        assert!(parse_decompose_spec(":split:field").is_empty());
        assert!(parse_decompose_spec("tag::field").is_empty());
        assert!(parse_decompose_spec("tag:split:").is_empty());
    }

    #[test]
    fn parse_multi_level_spec_valid_returns_rule() {
        let rule = parse_multi_level_spec(
            "programProcesses-meta:LoyaltyProgramSetup:parameterName,ruleName",
        )
        .unwrap();
        assert_eq!(rule.file_pattern, "programProcesses-meta");
        assert_eq!(rule.root_to_strip, "LoyaltyProgramSetup");
        assert_eq!(rule.unique_id_elements, "parameterName,ruleName");
        assert_eq!(rule.path_segment, "programProcesses");
        assert_eq!(rule.wrap_root_element, "LoyaltyProgramSetup");
        assert!(rule.wrap_xmlns.is_empty());
    }

    #[test]
    fn parse_multi_level_spec_rejects_wrong_parts() {
        assert!(parse_multi_level_spec("only:two").is_none());
        assert!(parse_multi_level_spec(":Root:ids").is_none());
        assert!(parse_multi_level_spec("file::ids").is_none());
        assert!(parse_multi_level_spec("file:Root:").is_none());
    }

    #[test]
    fn parse_multi_level_specs_single_rule_returns_one() {
        let rules = parse_multi_level_specs("a-meta:Root:id");
        assert_eq!(rules.len(), 1);
        assert_eq!(rules[0].file_pattern, "a-meta");
    }

    #[test]
    fn parse_multi_level_specs_semicolon_separates_rules() {
        let rules =
            parse_multi_level_specs("a-meta:RootA:id1,id2; b-meta:RootB:other ; c-meta:RootC:k");
        assert_eq!(rules.len(), 3);
        assert_eq!(rules[0].file_pattern, "a-meta");
        assert_eq!(rules[0].unique_id_elements, "id1,id2");
        assert_eq!(rules[1].file_pattern, "b-meta");
        assert_eq!(rules[1].root_to_strip, "RootB");
        assert_eq!(rules[2].file_pattern, "c-meta");
    }

    #[test]
    fn parse_multi_level_specs_skips_empty_and_malformed() {
        // Trailing semicolons and malformed rules are dropped without aborting the rest.
        let rules = parse_multi_level_specs("a:R:id; ; bad ; b:R:id;");
        assert_eq!(rules.len(), 2);
        assert_eq!(rules[0].file_pattern, "a");
        assert_eq!(rules[1].file_pattern, "b");
    }

    #[test]
    fn parse_multi_level_specs_empty_string_returns_empty() {
        assert!(parse_multi_level_specs("").is_empty());
        assert!(parse_multi_level_specs(" ; ;").is_empty());
    }

    #[test]
    fn parse_disassemble_args_handles_flags_and_eq_forms() {
        let args = [
            "path/to/file.xml",
            "--postpurge",
            "--prepurge",
            "--unique-id-elements=name,id",
            "--ignore-path=.foo",
            "--format=json",
            "--strategy=grouped-by-tag",
            "--multi-level=pattern:Root:ids",
            "--split-tags=a:split:b",
        ]
        .iter()
        .map(|s| sv(s))
        .collect::<Vec<_>>();
        let opts = parse_disassemble_args(&args);
        assert_eq!(opts.path, Some("path/to/file.xml"));
        assert!(opts.pre_purge);
        assert!(opts.post_purge);
        assert_eq!(opts.unique_id_elements, Some("name,id"));
        assert_eq!(opts.ignore_path, Some(".foo"));
        assert_eq!(opts.format, "json");
        assert_eq!(opts.strategy, Some("grouped-by-tag"));
        assert_eq!(opts.multi_level.as_deref(), Some("pattern:Root:ids"));
        assert_eq!(opts.split_tags.as_deref(), Some("a:split:b"));
    }

    #[test]
    fn parse_disassemble_args_handles_space_separated_forms() {
        let args = [
            "file.xml",
            "--unique-id-elements",
            "name",
            "--ignore-path",
            ".gitignore",
            "--format",
            "yaml",
            "--strategy",
            "unique-id",
            "--multi-level",
            "p:R:ids",
            "--split-tags",
            "t:split:f",
        ]
        .iter()
        .map(|s| sv(s))
        .collect::<Vec<_>>();
        let opts = parse_disassemble_args(&args);
        assert_eq!(opts.path, Some("file.xml"));
        assert_eq!(opts.unique_id_elements, Some("name"));
        assert_eq!(opts.ignore_path, Some(".gitignore"));
        assert_eq!(opts.format, "yaml");
        assert_eq!(opts.strategy, Some("unique-id"));
        assert_eq!(opts.multi_level.as_deref(), Some("p:R:ids"));
        assert_eq!(opts.split_tags.as_deref(), Some("t:split:f"));
    }

    #[test]
    fn parse_disassemble_args_space_form_value_is_not_misread_as_positional_path() {
        // For every option that accepts a value in separated form, when the option
        // is the leading argument and no positional path precedes it, the captured
        // value must not be re-treated as the positional path. This pins down the
        // `i += 1` advance after a value is consumed (regression: a missed advance
        // would cause the parser to revisit the value on the next iteration and
        // store it in `path`).
        let cases: &[(&[&str], &str)] = &[
            (&["--unique-id-elements", "name"], "name"),
            (&["--ignore-path", ".foo"], ".foo"),
            (&["--format", "yaml"], "yaml"),
            (&["--strategy", "grouped-by-tag"], "grouped-by-tag"),
            (&["--multi-level", "p:R:ids"], "p:R:ids"),
            (&["--split-tags", "t:split:f"], "t:split:f"),
            (&["-p", "t:split:f"], "t:split:f"),
        ];
        for (args, expected_value) in cases {
            let owned: Vec<String> = args.iter().map(|s| sv(s)).collect();
            let opts = parse_disassemble_args(&owned);
            assert!(
                opts.path.is_none(),
                "args {args:?}: value `{expected_value}` was incorrectly captured as path"
            );
        }
    }

    #[test]
    fn parse_disassemble_args_space_form_value_missing_does_not_panic() {
        // When a value-consuming option is the last arg with no following value,
        // the bounds check (`if i < args.len()`) must prevent an out-of-bounds
        // read. Each of these inputs would panic if the bounds check is mutated
        // from `<` to `<=`.
        let options = [
            "--unique-id-elements",
            "--ignore-path",
            "--format",
            "--strategy",
            "--multi-level",
            "--split-tags",
            "-p",
        ];
        for opt in options {
            let args = [opt].iter().map(|s| sv(s)).collect::<Vec<_>>();
            let opts = parse_disassemble_args(&args);
            // The defaults assertion is incidental; the real assertion is that
            // the call above does not panic.
            assert!(opts.path.is_none(), "bare option `{opt}` set a path");
        }
    }

    #[test]
    fn parse_disassemble_args_p_alias_for_split_tags() {
        let args = ["file.xml", "-p", "a:split:b"]
            .iter()
            .map(|s| sv(s))
            .collect::<Vec<_>>();
        let opts = parse_disassemble_args(&args);
        assert_eq!(opts.split_tags.as_deref(), Some("a:split:b"));
    }

    #[test]
    fn parse_disassemble_args_unknown_long_flag_is_skipped() {
        let args = ["file.xml", "--unknown"]
            .iter()
            .map(|s| sv(s))
            .collect::<Vec<_>>();
        let opts = parse_disassemble_args(&args);
        assert_eq!(opts.path, Some("file.xml"));
    }

    #[test]
    fn parse_disassemble_args_defaults_when_empty() {
        let opts = parse_disassemble_args(&[]);
        assert!(opts.path.is_none());
        assert!(opts.strategy.is_none());
        assert!(opts.unique_id_elements.is_none());
        assert!(!opts.pre_purge);
        assert!(!opts.post_purge);
        assert!(
            opts.ignore_path.is_none(),
            "default is `None` so the runner can pick the right filename"
        );
        assert_eq!(opts.format, "xml");
    }

    #[test]
    fn parse_disassemble_args_space_forms_without_value_leave_default() {
        let args = ["--unique-id-elements"]
            .iter()
            .map(|s| sv(s))
            .collect::<Vec<_>>();
        let opts = parse_disassemble_args(&args);
        assert!(opts.unique_id_elements.is_none());
    }

    #[test]
    fn parse_disassemble_args_trailing_extra_positional_ignored() {
        let args = ["first.xml", "second.xml"]
            .iter()
            .map(|s| sv(s))
            .collect::<Vec<_>>();
        let opts = parse_disassemble_args(&args);
        assert_eq!(opts.path, Some("first.xml"));
    }

    #[test]
    fn parse_reassemble_args_picks_path_extension_and_flag() {
        let args = ["some/dir", "json", "--postpurge"]
            .iter()
            .map(|s| sv(s))
            .collect::<Vec<_>>();
        let (path, ext, purge) = parse_reassemble_args(&args);
        assert_eq!(path, Some("some/dir"));
        assert_eq!(ext, Some("json"));
        assert!(purge);
    }

    #[test]
    fn parse_reassemble_args_defaults_and_extra_args_ignored() {
        let (p, e, purge) = parse_reassemble_args(&[]);
        assert!(p.is_none());
        assert!(e.is_none());
        assert!(!purge);

        let args = ["dir", "xml", "extra"]
            .iter()
            .map(|s| sv(s))
            .collect::<Vec<_>>();
        let (p, e, _) = parse_reassemble_args(&args);
        assert_eq!(p, Some("dir"));
        assert_eq!(e, Some("xml"));
    }

    #[tokio::test]
    async fn run_no_args_prints_usage_and_succeeds() {
        run(vec![sv("xml-disassembler")]).await.unwrap();
    }

    #[tokio::test]
    async fn run_unknown_command_is_not_an_error() {
        run(vec![sv("xml-disassembler"), sv("unknown")])
            .await
            .unwrap();
    }

    #[tokio::test]
    async fn run_reassemble_missing_path_returns_err() {
        // Missing directory path propagates an error from fs::metadata.
        let err = run(vec![
            sv("xml-disassembler"),
            sv("reassemble"),
            sv("/definitely/not/here/xyz"),
        ])
        .await;
        assert!(err.is_err());
    }

    #[tokio::test]
    async fn run_disassemble_writes_expected_output() {
        let dir = tempfile::tempdir().unwrap();
        let xml_path = dir.path().join("sample.xml");
        let xml = r#"<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns="http://example.com">
  <child><name>one</name></child>
  <child><name>two</name></child>
</Root>"#;
        std::fs::write(&xml_path, xml).unwrap();
        run(vec![
            sv("xml-disassembler"),
            sv("disassemble"),
            xml_path.to_string_lossy().to_string(),
        ])
        .await
        .unwrap();
        assert!(dir.path().join("sample").exists());
    }

    #[tokio::test]
    async fn run_disassemble_with_invalid_multi_level_spec_warns_and_continues() {
        let dir = tempfile::tempdir().unwrap();
        let xml_path = dir.path().join("sample.xml");
        let xml =
            r#"<?xml version="1.0" encoding="UTF-8"?><Root><child><name>a</name></child></Root>"#;
        std::fs::write(&xml_path, xml).unwrap();
        run(vec![
            sv("xml-disassembler"),
            sv("disassemble"),
            xml_path.to_string_lossy().to_string(),
            sv("--multi-level=bad-spec"),
        ])
        .await
        .unwrap();
    }

    #[tokio::test]
    async fn run_reassemble_on_existing_directory_succeeds() {
        // Disassemble then reassemble via the CLI to cover the success path end-to-end.
        let dir = tempfile::tempdir().unwrap();
        let xml_path = dir.path().join("reasm.xml");
        let xml = r#"<?xml version="1.0" encoding="UTF-8"?>
<Root><child><name>one</name></child><child><name>two</name></child></Root>"#;
        std::fs::write(&xml_path, xml).unwrap();
        run(vec![
            sv("xml-disassembler"),
            sv("disassemble"),
            xml_path.to_string_lossy().to_string(),
        ])
        .await
        .unwrap();
        let disassembled_dir = dir.path().join("reasm");
        assert!(disassembled_dir.exists());
        run(vec![
            sv("xml-disassembler"),
            sv("reassemble"),
            disassembled_dir.to_string_lossy().to_string(),
        ])
        .await
        .unwrap();
    }

    #[tokio::test]
    async fn run_disassemble_with_grouped_by_tag_no_split_tags_uses_empty_decompose_rules() {
        // grouped-by-tag with no --split-tags: decompose_rules falls back to Vec::new()
        // via `unwrap_or_default()` and decompose_rules_ref becomes None.
        let dir = tempfile::tempdir().unwrap();
        let xml_path = dir.path().join("sample.xml");
        let xml =
            r#"<?xml version="1.0" encoding="UTF-8"?><Root><a><n>1</n></a><b><n>2</n></b></Root>"#;
        std::fs::write(&xml_path, xml).unwrap();
        run(vec![
            sv("xml-disassembler"),
            sv("disassemble"),
            xml_path.to_string_lossy().to_string(),
            sv("--strategy=grouped-by-tag"),
        ])
        .await
        .unwrap();
    }

    #[tokio::test]
    async fn run_disassemble_with_grouped_by_tag_split_tags_runs() {
        let dir = tempfile::tempdir().unwrap();
        let xml_path = dir.path().join("perms.xml");
        let xml = r#"<?xml version="1.0" encoding="UTF-8"?>
<Root>
  <objectPermissions><object>A</object><allowRead>true</allowRead></objectPermissions>
  <objectPermissions><object>B</object><allowRead>false</allowRead></objectPermissions>
</Root>"#;
        std::fs::write(&xml_path, xml).unwrap();
        run(vec![
            sv("xml-disassembler"),
            sv("disassemble"),
            xml_path.to_string_lossy().to_string(),
            sv("--strategy=grouped-by-tag"),
            sv("-p"),
            sv("objectPermissions:split:object"),
        ])
        .await
        .unwrap();
    }

    #[test]
    fn should_print_usage_only_for_fewer_than_two_args() {
        // Pins each `<` mutant: `<=` would also trigger on len=2,
        // `==` would miss len=0, `>` would invert the polarity.
        assert!(should_print_usage(0));
        assert!(should_print_usage(1));
        assert!(!should_print_usage(2));
        assert!(!should_print_usage(3));
    }

    #[test]
    fn multi_level_spec_failed_to_parse_requires_both_conditions() {
        // The warning must fire only when a spec was *provided* and
        // parsing returned no rules — every other quadrant is silent.
        assert!(multi_level_spec_failed_to_parse(true, true));
        assert!(!multi_level_spec_failed_to_parse(true, false));
        assert!(!multi_level_spec_failed_to_parse(false, true));
        assert!(!multi_level_spec_failed_to_parse(false, false));
    }

    #[test]
    fn should_parse_decompose_rules_only_for_grouped_by_tag() {
        // Decompose rules are exclusive to `grouped-by-tag`. Mutating
        // the original `==` to `!=` would forward decompose specs to
        // the `unique-id` strategy and trigger downstream work that
        // times out under cargo-mutants — testing the helper directly
        // pins the operator without involving the async pipeline.
        assert!(should_parse_decompose_rules("grouped-by-tag"));
        assert!(!should_parse_decompose_rules("unique-id"));
        assert!(!should_parse_decompose_rules(""));
        assert!(!should_parse_decompose_rules("Grouped-By-Tag"));
    }

    #[tokio::test]
    async fn run_disassemble_with_valid_multi_level_spec_passes_rules_slice() {
        // A syntactically valid --multi-level spec causes multi_level_rules_ref to be
        // Some(slice) (line 299 in run_disassemble), covering that branch.
        let dir = tempfile::tempdir().unwrap();
        let xml_path = dir.path().join("sample.xml");
        let xml =
            r#"<?xml version="1.0" encoding="UTF-8"?><Root><child><name>a</name></child></Root>"#;
        std::fs::write(&xml_path, xml).unwrap();
        run(vec![
            sv("xml-disassembler"),
            sv("disassemble"),
            xml_path.to_string_lossy().to_string(),
            sv("--multi-level=child:Root:name"),
        ])
        .await
        .unwrap();
    }

    #[test]
    fn parse_sidecar_specs_empty_element_is_dropped() {
        // `:yaml` — element part is empty; must not produce a spec.
        let specs = parse_sidecar_specs(":yaml");
        assert!(specs.is_empty(), "expected no specs, got: {specs:?}");
    }

    #[test]
    fn parse_sidecar_specs_empty_extension_is_dropped() {
        // `schema:` — extension part is empty; must not produce a spec.
        let specs = parse_sidecar_specs("schema:");
        assert!(specs.is_empty(), "expected no specs, got: {specs:?}");
    }
}