libmagic_rs/

build_helpers.rs

// Copyright (c) 2025-2026 the libmagic-rs contributors
// SPDX-License-Identifier: Apache-2.0

/// Build-time helpers for compiling magic rules.
///
/// This module contains functionality used by the build script to parse magic files
/// and generate Rust code for built-in rules. It is extracted into a library module
/// to enable comprehensive testing of the build process, including error cases.
///
/// Serialization logic is provided by [`crate::parser::codegen`], which is shared
/// with `build.rs` to avoid duplication.
use crate::error::ParseError;
use crate::parser::parse_text_magic_file;

// Re-export codegen functions used by tests
#[cfg(test)]
use crate::parser::codegen::{
    format_byte_vec, format_number, generate_builtin_rules, serialize_children,
    serialize_endianness, serialize_offset_spec, serialize_operator, serialize_type_kind,
    serialize_value,
};

/// Parses a magic file and generates Rust code for the built-in rules.
///
/// This function wraps the parsing and code generation steps, providing a testable
/// interface for the build script logic.
///
/// # Errors
///
/// Returns a `ParseError` if the magic file content is invalid or malformed.
pub fn parse_and_generate_builtin_rules(magic_content: &str) -> Result<String, ParseError> {
    let parsed = parse_text_magic_file(magic_content)?;
    Ok(crate::parser::codegen::generate_builtin_rules(
        &parsed.rules,
    ))
}

/// Formats a parse error for display in build script output.
///
/// This function converts a `ParseError` into a human-readable message suitable
/// for display when the build script fails.
#[must_use]
pub fn format_parse_error(error: &ParseError) -> String {
    match error {
        ParseError::InvalidSyntax { line, message } => {
            format!("Error parsing builtin_rules.magic at line {line}: {message}")
        }
        ParseError::UnsupportedFeature { line, feature } => {
            format!("Error parsing builtin_rules.magic at line {line}: {feature}")
        }
        ParseError::InvalidOffset { line, offset } => {
            format!("Error parsing builtin_rules.magic at line {line}: {offset}")
        }
        ParseError::InvalidType { line, type_spec } => {
            format!("Error parsing builtin_rules.magic at line {line}: {type_spec}")
        }
        ParseError::InvalidOperator { line, operator } => {
            format!("Error parsing builtin_rules.magic at line {line}: {operator}")
        }
        ParseError::InvalidValue { line, value } => {
            format!("Error parsing builtin_rules.magic at line {line}: {value}")
        }
        ParseError::UnsupportedFormat {
            line,
            format_type,
            message,
        } => format!("Error parsing builtin_rules.magic at line {line}: {format_type} {message}"),
        ParseError::IoError(err) => {
            format!("Error parsing builtin_rules.magic: I/O error: {err}")
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::parser::ast::{
        Endianness, IndirectAdjustmentOp, MagicRule, OffsetSpec, Operator, SearchFlags,
        StringFlags, TypeKind, Value,
    };
    use crate::parser::codegen::format_string_literal;

    #[test]
    fn test_format_parse_error_invalid_syntax() {
        let error = ParseError::InvalidSyntax {
            line: 42,
            message: "expected offset".to_string(),
        };
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("line 42"));
        assert!(formatted.contains("expected offset"));
        assert!(formatted.contains("builtin_rules.magic"));
    }

    #[test]
    fn test_format_parse_error_unsupported_feature() {
        let error = ParseError::UnsupportedFeature {
            line: 10,
            feature: "regex patterns".to_string(),
        };
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("line 10"));
        assert!(formatted.contains("regex patterns"));
    }

    #[test]
    fn test_format_parse_error_invalid_offset() {
        let error = ParseError::InvalidOffset {
            line: 5,
            offset: "invalid offset spec".to_string(),
        };
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("line 5"));
        assert!(formatted.contains("invalid offset spec"));
    }

    #[test]
    fn test_format_parse_error_invalid_type() {
        let error = ParseError::InvalidType {
            line: 7,
            type_spec: "unknown type".to_string(),
        };
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("line 7"));
        assert!(formatted.contains("unknown type"));
    }

    #[test]
    fn test_format_parse_error_invalid_operator() {
        let error = ParseError::InvalidOperator {
            line: 12,
            operator: "bad operator".to_string(),
        };
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("line 12"));
        assert!(formatted.contains("bad operator"));
    }

    #[test]
    fn test_format_parse_error_invalid_value() {
        let error = ParseError::InvalidValue {
            line: 15,
            value: "malformed value".to_string(),
        };
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("line 15"));
        assert!(formatted.contains("malformed value"));
    }

    #[test]
    fn test_serialize_offset_spec_absolute() {
        let offset = OffsetSpec::Absolute(42);
        let serialized = serialize_offset_spec(&offset);
        assert_eq!(serialized, "OffsetSpec::Absolute(42)");
    }

    #[test]
    fn test_serialize_offset_spec_relative() {
        let offset = OffsetSpec::Relative(-10);
        let serialized = serialize_offset_spec(&offset);
        assert_eq!(serialized, "OffsetSpec::Relative(-10)");
    }

    #[test]
    fn test_serialize_offset_spec_from_end() {
        let offset = OffsetSpec::FromEnd(-16);
        let serialized = serialize_offset_spec(&offset);
        assert_eq!(serialized, "OffsetSpec::FromEnd(-16)");
    }

    #[test]
    fn test_serialize_type_kind_byte() {
        let signed = TypeKind::Byte { signed: true };
        assert_eq!(
            serialize_type_kind(&signed),
            "TypeKind::Byte { signed: true }"
        );
        let unsigned = TypeKind::Byte { signed: false };
        assert_eq!(
            serialize_type_kind(&unsigned),
            "TypeKind::Byte { signed: false }"
        );
    }

    #[test]
    fn test_serialize_type_kind_short() {
        let typ = TypeKind::Short {
            endian: Endianness::Little,
            signed: false,
        };
        let serialized = serialize_type_kind(&typ);
        assert!(serialized.contains("TypeKind::Short"));
        assert!(serialized.contains("Endianness::Little"));
        assert!(serialized.contains("signed: false"));
    }

    #[test]
    fn test_serialize_type_kind_long() {
        let typ = TypeKind::Long {
            endian: Endianness::Big,
            signed: true,
        };
        let serialized = serialize_type_kind(&typ);
        assert!(serialized.contains("TypeKind::Long"));
        assert!(serialized.contains("Endianness::Big"));
        assert!(serialized.contains("signed: true"));
    }

    #[test]
    fn test_serialize_type_kind_quad() {
        let typ = TypeKind::Quad {
            endian: Endianness::Little,
            signed: true,
        };
        let serialized = serialize_type_kind(&typ);
        assert!(serialized.contains("TypeKind::Quad"));
        assert!(serialized.contains("Endianness::Little"));
        assert!(serialized.contains("signed: true"));

        let typ2 = TypeKind::Quad {
            endian: Endianness::Big,
            signed: false,
        };
        let serialized2 = serialize_type_kind(&typ2);
        assert!(serialized2.contains("TypeKind::Quad"));
        assert!(serialized2.contains("Endianness::Big"));
        assert!(serialized2.contains("signed: false"));
    }

    #[test]
    fn test_serialize_type_kind_id3() {
        let cases = [
            (
                TypeKind::Id3 {
                    endian: Endianness::Little,
                },
                "TypeKind::Id3 { endian: Endianness::Little }",
            ),
            (
                TypeKind::Id3 {
                    endian: Endianness::Big,
                },
                "TypeKind::Id3 { endian: Endianness::Big }",
            ),
        ];
        for (typ, expected) in &cases {
            assert_eq!(serialize_type_kind(typ), *expected);
        }

        // audio:308's `(6.I+10)` pointer, as build-time codegen emits it.
        let spec = OffsetSpec::Indirect {
            base_offset: 6,
            base_relative: false,
            pointer_type: TypeKind::Id3 {
                endian: Endianness::Big,
            },
            adjustment: 10,
            adjustment_op: IndirectAdjustmentOp::Add,
            result_relative: false,
            endian: Endianness::Big,
        };
        assert_eq!(
            serialize_offset_spec(&spec),
            "OffsetSpec::Indirect { base_offset: 6, base_relative: false, \
             pointer_type: TypeKind::Id3 { endian: Endianness::Big }, adjustment: 10, \
             adjustment_op: IndirectAdjustmentOp::Add, result_relative: false, \
             endian: Endianness::Big }"
        );
    }

    #[test]
    fn test_serialize_type_kind_float() {
        let cases = [
            (
                TypeKind::Float {
                    endian: Endianness::Native,
                },
                "TypeKind::Float { endian: Endianness::Native }",
            ),
            (
                TypeKind::Float {
                    endian: Endianness::Little,
                },
                "TypeKind::Float { endian: Endianness::Little }",
            ),
            (
                TypeKind::Float {
                    endian: Endianness::Big,
                },
                "TypeKind::Float { endian: Endianness::Big }",
            ),
        ];
        for (typ, expected) in &cases {
            assert_eq!(serialize_type_kind(typ), *expected);
        }
    }

    #[test]
    fn test_serialize_type_kind_double() {
        let cases = [
            (
                TypeKind::Double {
                    endian: Endianness::Native,
                },
                "TypeKind::Double { endian: Endianness::Native }",
            ),
            (
                TypeKind::Double {
                    endian: Endianness::Little,
                },
                "TypeKind::Double { endian: Endianness::Little }",
            ),
            (
                TypeKind::Double {
                    endian: Endianness::Big,
                },
                "TypeKind::Double { endian: Endianness::Big }",
            ),
        ];
        for (typ, expected) in &cases {
            assert_eq!(serialize_type_kind(typ), *expected);
        }
    }

    #[test]
    fn test_serialize_value_float() {
        // Positive finite literal
        let serialized = serialize_value(&Value::Float(3.125));
        assert_eq!(serialized, "Value::Float(3.125)");

        // Negative finite literal
        let serialized = serialize_value(&Value::Float(-1.0));
        assert_eq!(serialized, "Value::Float(-1.0)");

        // Non-finite values produce valid Rust expressions
        assert_eq!(
            serialize_value(&Value::Float(f64::NAN)),
            "Value::Float(f64::NAN)"
        );
        assert_eq!(
            serialize_value(&Value::Float(f64::INFINITY)),
            "Value::Float(f64::INFINITY)"
        );
        assert_eq!(
            serialize_value(&Value::Float(f64::NEG_INFINITY)),
            "Value::Float(f64::NEG_INFINITY)"
        );
    }

    #[test]
    fn test_serialize_type_kind_string() {
        let typ1 = TypeKind::String {
            max_length: None,
            flags: StringFlags::default(),
        };
        let serialized1 = serialize_type_kind(&typ1);
        assert_eq!(
            serialized1,
            "TypeKind::String { max_length: None, flags: crate::parser::ast::StringFlags::default() }"
        );

        let typ2 = TypeKind::String {
            max_length: Some(256),
            flags: StringFlags::default(),
        };
        let serialized2 = serialize_type_kind(&typ2);
        assert_eq!(
            serialized2,
            "TypeKind::String { max_length: Some(256), flags: crate::parser::ast::StringFlags::default() }"
        );

        // Non-default flags emit the builder chain.
        let typ3 = TypeKind::String {
            max_length: None,
            flags: StringFlags::default().with_ignore_lowercase(true),
        };
        let serialized3 = serialize_type_kind(&typ3);
        assert_eq!(
            serialized3,
            "TypeKind::String { max_length: None, flags: crate::parser::ast::StringFlags::default().with_ignore_lowercase(true) }"
        );
    }

    #[test]
    fn test_serialize_type_kind_pstring() {
        use crate::parser::ast::PStringLengthWidth;
        let typ1 = TypeKind::PString {
            max_length: None,
            length_width: PStringLengthWidth::OneByte,
            length_includes_itself: false,
        };
        let serialized1 = serialize_type_kind(&typ1);
        assert_eq!(
            serialized1,
            "TypeKind::PString { max_length: None, length_width: PStringLengthWidth::OneByte, length_includes_itself: false }"
        );

        let typ2 = TypeKind::PString {
            max_length: Some(128),
            length_width: PStringLengthWidth::FourByteLE,
            length_includes_itself: false,
        };
        let serialized2 = serialize_type_kind(&typ2);
        assert_eq!(
            serialized2,
            "TypeKind::PString { max_length: Some(128), length_width: PStringLengthWidth::FourByteLE, length_includes_itself: false }"
        );
    }

    #[test]
    fn test_serialize_operator() {
        assert_eq!(serialize_operator(&Operator::Equal), "Operator::Equal");
        assert_eq!(
            serialize_operator(&Operator::NotEqual),
            "Operator::NotEqual"
        );
        assert_eq!(
            serialize_operator(&Operator::LessThan),
            "Operator::LessThan"
        );
        assert_eq!(
            serialize_operator(&Operator::GreaterThan),
            "Operator::GreaterThan"
        );
        assert_eq!(
            serialize_operator(&Operator::LessEqual),
            "Operator::LessEqual"
        );
        assert_eq!(
            serialize_operator(&Operator::GreaterEqual),
            "Operator::GreaterEqual"
        );
        assert_eq!(
            serialize_operator(&Operator::BitwiseAnd),
            "Operator::BitwiseAnd"
        );
        assert_eq!(
            serialize_operator(&Operator::BitwiseAndMask(0xFF)),
            "Operator::BitwiseAndMask(255)"
        );
    }

    #[test]
    fn test_serialize_value_uint() {
        let value = Value::Uint(12345);
        let serialized = serialize_value(&value);
        assert_eq!(serialized, "Value::Uint(12_345)");
    }

    #[test]
    fn test_serialize_value_int() {
        let value = Value::Int(-100);
        let serialized = serialize_value(&value);
        assert!(serialized.contains("Value::Int"));
    }

    #[test]
    fn test_serialize_value_bytes() {
        let value = Value::Bytes(vec![0x7F, 0x45, 0x4C, 0x46]);
        let serialized = serialize_value(&value);
        assert_eq!(serialized, "Value::Bytes(vec![0x7f, 0x45, 0x4c, 0x46])");
    }

    #[test]
    fn test_serialize_value_string() {
        let value = Value::String("test".to_string());
        let serialized = serialize_value(&value);
        assert!(serialized.contains("Value::String"));
        assert!(serialized.contains("test"));
    }

    #[test]
    fn test_format_number_small() {
        assert_eq!(format_number(42), "42");
        assert_eq!(format_number(999), "999");
        assert_eq!(format_number(9999), "9999");
    }

    #[test]
    fn test_format_number_large() {
        assert_eq!(format_number(10000), "10_000");
        assert_eq!(format_number(123_456), "123_456");
        assert_eq!(format_number(1_234_567_890), "1_234_567_890");
    }

    #[test]
    fn test_serialize_endianness() {
        assert_eq!(
            serialize_endianness(Endianness::Little),
            "Endianness::Little"
        );
        assert_eq!(serialize_endianness(Endianness::Big), "Endianness::Big");
        assert_eq!(
            serialize_endianness(Endianness::Native),
            "Endianness::Native"
        );
    }

    #[test]
    fn test_format_byte_vec_empty() {
        let result = format_byte_vec(&[]);
        assert_eq!(result, "vec![]");
    }

    #[test]
    fn test_format_byte_vec_single() {
        let result = format_byte_vec(&[0x42]);
        assert_eq!(result, "vec![0x42]");
    }

    #[test]
    fn test_format_byte_vec_multiple() {
        let result = format_byte_vec(&[0x12, 0x34, 0x56]);
        assert_eq!(result, "vec![0x12, 0x34, 0x56]");
    }

    #[test]
    fn test_format_string_literal() {
        assert_eq!(format_string_literal("hello"), "\"hello\"");
        assert_eq!(format_string_literal("test\n"), "\"test\\n\"");
        assert_eq!(format_string_literal("quote\"here"), "\"quote\\\"here\"");
    }

    #[test]
    fn test_generate_builtin_rules_empty() {
        let rules: Vec<MagicRule> = vec![];
        let generated = generate_builtin_rules(&rules);

        assert!(generated.contains("LazyLock<Vec<MagicRule>>"));
        assert!(generated.contains("vec![]") || generated.contains("vec!["));
        assert!(generated.contains("use crate::parser::ast"));
        assert!(generated.contains("use std::sync::LazyLock"));
    }

    #[test]
    fn test_generate_builtin_rules_single_rule() {
        let rule = MagicRule {
            offset: OffsetSpec::Absolute(0),
            typ: TypeKind::Byte { signed: true },
            op: Operator::Equal,
            value: Value::Uint(0x7F),
            message: "test".to_string(),
            children: vec![],
            level: 0,
            strength_modifier: None,
            value_transform: None,
        };

        let generated = generate_builtin_rules(&[rule]);

        assert!(generated.contains("OffsetSpec::Absolute(0)"));
        assert!(generated.contains("TypeKind::Byte { signed: true }"));
        assert!(generated.contains("Operator::Equal"));
        assert!(generated.contains("Value::Uint(127)"));
        assert!(generated.contains("test"));
        assert!(generated.contains("level: 0"));
    }

    #[test]
    fn test_serialize_children_empty() {
        let result = serialize_children(&[], 4);
        assert_eq!(result, "Vec::new()");
    }

    #[test]
    fn test_serialize_children_with_nested_rule() {
        let child = MagicRule {
            offset: OffsetSpec::Absolute(4),
            typ: TypeKind::Byte { signed: true },
            op: Operator::Equal,
            value: Value::Uint(1),
            message: "child".to_string(),
            children: vec![],
            level: 1,
            strength_modifier: None,
            value_transform: None,
        };

        let result = serialize_children(&[child], 4);

        assert!(result.contains("vec!["));
        assert!(result.contains("OffsetSpec::Absolute(4)"));
        assert!(result.contains("level: 1"));
        assert!(result.contains("child"));
    }

    // Tests for invalid magic file parsing failure path
    #[test]
    fn test_parse_and_generate_invalid_syntax() {
        let invalid_magic = "this is not valid magic syntax";
        let result = parse_and_generate_builtin_rules(invalid_magic);

        assert!(result.is_err());
        let error = result.unwrap_err();
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("builtin_rules.magic"));
    }

    #[test]
    fn test_parse_and_generate_invalid_offset() {
        let invalid_magic = "999999999999999999999 byte =0x7F ELF";
        let result = parse_and_generate_builtin_rules(invalid_magic);

        assert!(result.is_err());
        let error = result.unwrap_err();
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("builtin_rules.magic"));
    }

    #[test]
    fn test_parse_and_generate_invalid_type() {
        let invalid_magic = "0 invalidtype =0x7F test";
        let result = parse_and_generate_builtin_rules(invalid_magic);

        assert!(result.is_err());
        let error = result.unwrap_err();
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("builtin_rules.magic"));
    }

    #[test]
    fn test_parse_and_generate_empty_input() {
        let empty_magic = "";
        let result = parse_and_generate_builtin_rules(empty_magic);

        // Empty input should succeed with no rules
        assert!(result.is_ok());
        let generated = result.unwrap();
        assert!(generated.contains("vec![]") || generated.contains("vec!["));
    }

    #[test]
    fn test_parse_and_generate_valid_magic() {
        let valid_magic = "0 byte =0x7F ELF executable";
        let result = parse_and_generate_builtin_rules(valid_magic);

        assert!(result.is_ok());
        let generated = result.unwrap();
        assert!(generated.contains("OffsetSpec::Absolute(0)"));
        assert!(generated.contains("TypeKind::Byte { signed: true }"));
        assert!(generated.contains("Value::Uint(127)"));
        assert!(generated.contains("ELF executable"));
    }

    #[test]
    fn test_parse_and_generate_malformed_value() {
        let invalid_magic = "0 byte =notahexvalue test";
        let result = parse_and_generate_builtin_rules(invalid_magic);

        assert!(result.is_err());
        let error = result.unwrap_err();
        let formatted = format_parse_error(&error);
        assert!(formatted.contains("builtin_rules.magic"));
    }

    /// Regression test for PR #215 Copilot review comment: the codegen
    /// for `TypeKind::Regex` and `TypeKind::Search` must NOT emit
    /// `.expect("nonzero")` (a panic marker banned by AGENTS.md for
    /// library code, which is what the generated `builtin_rules.rs`
    /// becomes). Instead it must emit
    /// `.unwrap_or(NonZero::<..>::MIN)`, which preserves the invariant
    /// expression without introducing a panic path.
    #[test]
    fn test_serialize_regex_codegen_has_no_expect_panic_marker() {
        use crate::parser::ast::{RegexCount, RegexFlags};
        use std::num::NonZeroU32;

        let cases = [
            TypeKind::Regex {
                flags: RegexFlags::default(),
                count: RegexCount::Bytes(NonZeroU32::new(256).unwrap()),
            },
            TypeKind::Regex {
                flags: RegexFlags::default(),
                count: RegexCount::Lines(Some(NonZeroU32::new(3).unwrap())),
            },
        ];
        for typ in &cases {
            let generated = serialize_type_kind(typ);
            assert!(
                !generated.contains(".expect("),
                "serialize_type_kind must not emit .expect() (AGENTS.md panic-marker ban); got:\n{generated}"
            );
            assert!(
                generated.contains(".unwrap_or(::std::num::NonZeroU32::MIN)"),
                "serialize_type_kind must emit .unwrap_or(NonZeroU32::MIN); got:\n{generated}"
            );
        }
    }

    #[test]
    fn test_serialize_search_codegen_has_no_expect_panic_marker() {
        use std::num::NonZeroUsize;

        // Bounded `search/512`: `range` is `Option<NonZeroUsize>`, so
        // `NonZeroUsize::new(512)` already yields `Some(_)` -- no panicking
        // conversion and no `.unwrap_or` fallback is needed (the old
        // `NonZeroUsize`-typed field required `.unwrap_or(MIN)`; the Option
        // field does not).
        let typ = TypeKind::Search {
            range: NonZeroUsize::new(512),
            flags: SearchFlags::default(),
        };
        let generated = serialize_type_kind(&typ);
        assert!(
            !generated.contains(".expect(") && !generated.contains(".unwrap()"),
            "serialize_type_kind must not emit a panic marker (AGENTS.md ban); got:\n{generated}"
        );
        assert!(
            generated.contains("range: ::std::num::NonZeroUsize::new(512)"),
            "bounded search must serialize range as NonZeroUsize::new(N) (an Option); got:\n{generated}"
        );

        // Bare `search` (`range: None`) must serialize as a literal `None`.
        let bare = TypeKind::Search {
            range: None,
            flags: SearchFlags::default(),
        };
        let bare_gen = serialize_type_kind(&bare);
        assert!(
            bare_gen.contains("range: None"),
            "bare search must serialize range as None (scan-to-EOF); got:\n{bare_gen}"
        );
    }

    /// Round-trip: a `TypeKind::Search` with default flags must emit a
    /// fully-explicit `SearchFlags { ... }` struct literal in which every
    /// field is set to `false`. U4 requirement: no `..Default::default()`
    /// because the generated `builtin_rules.rs` is compiled by a separate
    /// build-script compilation unit that does not import `Default`.
    #[test]
    fn test_serialize_type_kind_search_default_flags() {
        use std::num::NonZeroUsize;

        let typ = TypeKind::Search {
            range: NonZeroUsize::new(256),
            flags: SearchFlags::default(),
        };
        let generated = serialize_type_kind(&typ);

        // Every field must appear explicitly with `false`.
        for field in [
            "compact_whitespace: false",
            "compact_optional_whitespace: false",
            "ignore_lowercase: false",
            "ignore_uppercase: false",
            "text_test: false",
            "trim: false",
            "bin_test: false",
            "full_word: false",
            "start_anchor: false",
        ] {
            assert!(
                generated.contains(field),
                "generated codegen missing `{field}` field; got:\n{generated}"
            );
        }

        // No `..Default::default()` shortcut allowed.
        assert!(
            !generated.contains("..Default::default()"),
            "generated codegen must not use `..Default::default()`; got:\n{generated}"
        );

        // Fully-qualified path so the build script does not need an import.
        assert!(
            generated.contains("crate::parser::ast::SearchFlags"),
            "generated codegen must use fully-qualified path; got:\n{generated}"
        );
    }

    /// Round-trip: a `TypeKind::Search` with non-default flags must emit
    /// the corresponding `true` values for the set fields and `false` for
    /// the rest. Exercises `start_anchor` (search-only `/s`) and
    /// `ignore_lowercase` (`/c`) together.
    #[test]
    fn test_serialize_type_kind_search_with_flags() {
        use std::num::NonZeroUsize;

        let typ = TypeKind::Search {
            range: NonZeroUsize::new(1024),
            flags: SearchFlags::default()
                .with_start_anchor(true)
                .with_ignore_lowercase(true),
        };
        let generated = serialize_type_kind(&typ);

        assert!(
            generated.contains("start_anchor: true"),
            "expected start_anchor: true; got:\n{generated}"
        );
        assert!(
            generated.contains("ignore_lowercase: true"),
            "expected ignore_lowercase: true; got:\n{generated}"
        );

        // Unset flags must still appear with `false`.
        for field in [
            "compact_whitespace: false",
            "compact_optional_whitespace: false",
            "ignore_uppercase: false",
            "text_test: false",
            "trim: false",
            "bin_test: false",
            "full_word: false",
        ] {
            assert!(
                generated.contains(field),
                "expected `{field}` in codegen; got:\n{generated}"
            );
        }

        // Range value must still round-trip.
        assert!(
            generated.contains("1024"),
            "expected range literal 1024; got:\n{generated}"
        );
    }

    /// Verify the emitted codegen has no panic markers across every
    /// `SearchFlags` permutation that combines default and non-default
    /// flags. Extends the original `_default_only` regression test from
    /// U1's placeholder pass to cover non-default flags too.
    #[test]
    fn test_search_codegen_has_no_panic_markers() {
        use std::num::NonZeroUsize;

        let cases = [
            SearchFlags::default(),
            SearchFlags::default().with_start_anchor(true),
            SearchFlags::default().with_ignore_lowercase(true),
            SearchFlags::default()
                .with_compact_whitespace(true)
                .with_full_word(true),
            SearchFlags::default()
                .with_start_anchor(true)
                .with_ignore_lowercase(true)
                .with_ignore_uppercase(true)
                .with_compact_whitespace(true)
                .with_compact_optional_whitespace(true)
                .with_text_test(true)
                .with_trim(true)
                .with_bin_test(true)
                .with_full_word(true),
        ];

        for flags in cases {
            let typ = TypeKind::Search {
                range: NonZeroUsize::new(64),
                flags,
            };
            let generated = serialize_type_kind(&typ);

            for forbidden in [".unwrap()", ".expect(", "panic!(", "unreachable!", "todo!"] {
                assert!(
                    !generated.contains(forbidden),
                    "emitted codegen contains forbidden panic marker `{forbidden}`; got:\n{generated}"
                );
            }

            // `range` is now `Option<NonZeroUsize>`, so `NonZeroUsize::new(64)`
            // already yields `Some(_)` -- no `.unwrap_or(MIN)` fallback is
            // needed (or emitted) any more. The panic-marker checks above are
            // the real safety property.
            assert!(
                generated.contains("range: ::std::num::NonZeroUsize::new(64)"),
                "bounded search must serialize range as an Option-yielding NonZeroUsize::new(N); got:\n{generated}"
            );
        }
    }
}