marque_ism/

attrs.rs

//! `IsmAttributes` — the canonical in-memory representation of a classification marking.
//!
//! Mirrors the IC ISM XML attribute model. Every source format (free text, XML, web forms)
//! normalizes into this struct before rule validation.
//!
//! # Type design
//! Multi-value fields use `Box<[T]>` rather than `Vec<T>` to avoid over-allocation
//! after parsing. Most markings have 0–4 values per field.
//!
//! # Classification systems
//!
//! A marking carries exactly one classification system: US, FGI (non-US),
//! NATO, or JOINT. This is represented by [`MarkingClassification`]. Non-US
//! classifications start with `//` (the US classification slot is empty).
//!
//! When the parser encounters two classification systems in one marking
//! (e.g., `SECRET//NATO SECRET//NOFORN`), it resolves to
//! [`MarkingClassification::Conflict`] — US wins at the greater of the two
//! levels, and the foreign part is preserved for rule-generated fixes.
//!
//! # Code generation
//! CVE enum variants (`SciControl`, `DissemControl`, `DeclassExemption`, `SarIdentifier`)
//! are generated by `build.rs` from ODNI CVE XML files and re-exported from
//! `crate::generated::values`.

use crate::generated::values;
use crate::span::Span;

// Re-export generated enum types for convenience.
pub use values::{DeclassExemption, DissemControl, SarIdentifier, SciControl};

/// Canonical in-memory representation of a classification marking.
///
/// Produced by `marque-core::parser` from scanner candidates.
/// Consumed by `marque-rules::Rule` implementations for validation.
///
/// # Block ordering (CAPCO)
///
/// Fields are ordered per CAPCO block sequence:
/// Classification → SCI → SAR → FGI marker → Dissem (incl. REL TO)
#[non_exhaustive]
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct IsmAttributes {
    /// The marking's classification system and level.
    /// `None` means parsing failed to identify a classification.
    pub classification: Option<MarkingClassification>,

    /// SCI controls (e.g., SI, TK, HCS-P). Ordered per CAPCO block ordering.
    pub sci_controls: Box<[SciControl]>,

    /// Special Access Required identifiers.
    pub sar_identifiers: Box<[SarIdentifier]>,

    /// Atomic Energy Act markings (CAPCO Register §6).
    ///
    /// Includes RD, FRD, CNWDI, TFNI, SIGMA, and UCNI variants.
    /// Positioned between SAR and FGI in CAPCO block ordering.
    pub aea_markings: Box<[AeaMarking]>,

    /// FGI block in US-classified markings: `FGI` or `FGI [LIST]`.
    ///
    /// Present when a US-classified document references foreign government
    /// information. This is the *marker* in the banner/portion — distinct
    /// from [`MarkingClassification::Fgi`], which means the marking IS
    /// foreign-classified.
    ///
    /// `None` when no FGI marker is present.
    pub fgi_marker: Option<FgiMarker>,

    /// Dissemination controls (e.g., NOFORN, RELIDO, ORCON, FISA).
    pub dissem_controls: Box<[DissemControl]>,

    /// Non-IC dissemination controls (e.g., LIMDIS, SBU, LES, SSI).
    ///
    /// Separate authority framework (CAPCO Register §9), distinct from IC
    /// dissem controls. In classified documents these are generally portion-
    /// only and stripped from banners, but some values propagate to the
    /// classified banner; see [`NonIcDissem::propagates_to_classified_banner`]
    /// for the authoritative rule. On unclassified pages they propagate to
    /// the banner. LES-NF and SBU-NF carry NOFORN treatment even when
    /// stripped.
    pub non_ic_dissem: Box<[NonIcDissem]>,

    /// REL TO country trigraphs. USA must be present and first if non-empty.
    ///
    /// Structurally part of the dissem block (comma-delimited), but kept as
    /// a typed field for E002 and REL TO validation rules.
    pub rel_to: Box<[Trigraph]>,

    /// Declassification date from CAB (free text, e.g., "20331231").
    pub declassify_on: Option<Box<str>>,

    /// Free-text "Classified By" identifier from CAB.
    pub classified_by: Option<Box<str>>,

    /// Free-text "Derived From" source from CAB.
    pub derived_from: Option<Box<str>>,

    /// Declassification exemption code from CAB (e.g., 25X1, 50X1-HUM).
    pub declass_exemption: Option<DeclassExemption>,

    /// Per-token byte spans into the *original source buffer*, recorded by
    /// the parser as it walks the marking string. Phase 3 added this so
    /// rules can point at the exact offending byte range instead of the
    /// whole marking. Empty for CAB markings (CAB parsing is line-structured
    /// and doesn't go through the token-walking path).
    ///
    /// Indexing convention: `token_spans` is in document order. To find the
    /// span for the Nth `DissemControl`, walk the slice and pick the Nth
    /// entry whose `kind == TokenKind::DissemControl`.
    pub token_spans: Box<[TokenSpan]>,
}

impl IsmAttributes {
    /// Convenience accessor: returns the US classification level if this
    /// marking uses the US or Conflict classification system.
    ///
    /// Returns `None` for pure FGI, NATO, or JOINT markings (use
    /// `self.classification` directly for those).
    pub fn us_classification(&self) -> Option<Classification> {
        match self.classification {
            Some(MarkingClassification::Us(c)) => Some(c),
            Some(MarkingClassification::Conflict { us, .. }) => Some(us),
            _ => None,
        }
    }
}

/// One parser-recognized token plus its byte span in the original source.
///
/// Used by Phase 3 rules to surface byte-precise diagnostic spans without
/// re-parsing the source. The `text` field carries the literal token bytes
/// so rules that need the source content (E006, E007, E008 against migration
/// keys) can look up entries without threading `&[u8] source` through every
/// `Rule::check` signature.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TokenSpan {
    pub kind: TokenKind,
    pub span: Span,
    pub text: Box<str>,
}

/// Discriminant for `TokenSpan`. Phase 3 rules read these to filter
/// token-span lookups by category.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TokenKind {
    /// Classification level token (S, SECRET, TS, TOP SECRET, ...).
    Classification,
    /// SCI control token (SI, TK, HCS, ...).
    SciControl,
    /// SAR identifier token.
    SarIdentifier,
    /// Atomic Energy Act marking token (RD, FRD, CNWDI, TFNI, SIGMA ##, etc.).
    AeaMarking,
    /// FGI marker token (`FGI`, `FGI DEU`, `FGI DEU GBR`).
    FgiMarker,
    /// Dissemination control token (NOFORN, NF, ORCON, OC, RELIDO, ...).
    DissemControl,
    /// Non-IC dissemination control token (LIMDIS, DS, SBU, LES, SSI, ...).
    NonIcDissem,
    /// REL TO country trigraph (USA, GBR, AUS, ...). One per token, not the
    /// whole REL TO list.
    RelToTrigraph,
    /// The full `REL TO ...` block text. Recorded so E013 can inspect the
    /// raw source for delimiter errors (spaces instead of commas).
    RelToBlock,
    /// Declassification exemption code in CAB or banner (25X1, 50X1-HUM).
    DeclassExemption,
    /// Declassification date in CAB or banner (YYYYMMDD or YYYY).
    DeclassDate,
    /// `//` separator between blocks. Recorded so E004 can detect extra/
    /// missing separator runs.
    Separator,
    /// A non-empty block that did not match any known token kind. E008 fires
    /// one diagnostic per `Unknown` entry.
    Unknown,
}

// ===========================================================================
// Classification types
// ===========================================================================

/// The classification system and level for a marking.
///
/// A marking has exactly one classification system. When the parser finds
/// two (e.g., `SECRET//NATO SECRET//...`), it resolves to [`Conflict`](Self::Conflict).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MarkingClassification {
    /// US IC classification.
    Us(Classification),
    /// Non-US (FGI) classification: `//GBR S//...`
    Fgi(FgiClassification),
    /// NATO classification: `//NS//...`
    Nato(NatoClassification),
    /// JOINT classification (US co-owned): `//JOINT S USA GBR//...`
    Joint(JointClassification),
    /// Parser found two classification systems in one marking.
    ///
    /// US wins, upgraded to the greater of the two levels.
    /// The foreign part is preserved so rules can suggest the FGI fix.
    ///
    /// Example: `SECRET//COSMIC TOP SECRET//REL TO USA, NATO`
    /// → `us: TopSecret`, `foreign: Nato(CosmicTopSecret)`
    /// → fix: `TOP SECRET//FGI NATO//REL TO USA, NATO`
    Conflict {
        /// Resolved US classification (max of both levels).
        us: Classification,
        /// The foreign classification that should become an FGI marker.
        foreign: Box<ForeignClassification>,
    },
}

impl MarkingClassification {
    /// The effective classification level for ordering purposes, regardless of
    /// classification system.
    ///
    /// NATO levels are mapped to their US equivalents via
    /// [`NatoClassification::us_equivalent`]. All systems use the
    /// [`Classification`] ladder for comparison so that `Iterator::max()` on
    /// a mixed set of portions returns the most restrictive level overall.
    pub fn effective_level(&self) -> Classification {
        match self {
            Self::Us(c) => *c,
            Self::Fgi(f) => f.level,
            Self::Nato(n) => n.us_equivalent(),
            Self::Joint(j) => j.level,
            Self::Conflict { us, .. } => *us,
        }
    }
}

impl Default for MarkingClassification {
    fn default() -> Self {
        Self::Us(Classification::Unclassified)
    }
}

/// The non-US classification in a [`MarkingClassification::Conflict`].
///
/// Preserves enough information for rules to generate the FGI fix:
/// the foreign system, its level, and any associated countries.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ForeignClassification {
    Fgi(FgiClassification),
    Nato(NatoClassification),
    Joint(JointClassification),
}

// ---------------------------------------------------------------------------
// Classification level (US ladder + RESTRICTED for foreign interop)
// ---------------------------------------------------------------------------

/// Classification level. Ordered by restrictiveness: U < R < C < S < TS.
///
/// Includes `Restricted` for foreign-origin markings — many non-US
/// classification systems (and NATO) have a RESTRICTED level between
/// UNCLASSIFIED and CONFIDENTIAL.
///
/// The derived `Ord` reflects restrictiveness ordering so that
/// `Iterator::max()` returns the most restrictive level.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Classification {
    Unclassified,
    Restricted,
    Confidential,
    Secret,
    TopSecret,
}

impl Classification {
    /// Banner form (full words, no abbreviations).
    pub fn banner_str(self) -> &'static str {
        match self {
            Self::Unclassified => "UNCLASSIFIED",
            Self::Restricted => "RESTRICTED",
            Self::Confidential => "CONFIDENTIAL",
            Self::Secret => "SECRET",
            Self::TopSecret => "TOP SECRET",
        }
    }

    /// Portion form (abbreviation used in portion markings).
    pub fn portion_str(self) -> &'static str {
        match self {
            Self::Unclassified => "U",
            Self::Restricted => "R",
            Self::Confidential => "C",
            Self::Secret => "S",
            Self::TopSecret => "TS",
        }
    }
}

// ---------------------------------------------------------------------------
// FGI classification (non-US, country-prefixed)
// ---------------------------------------------------------------------------

/// Non-US (FGI) classification.
///
/// Two forms exist:
///
/// - **Source-acknowledged**: country trigraph(s) identify the originator.
///   `//GBR S//REL TO USA, GBR`
/// - **Source-concealed**: `FGI` replaces the country trigraph(s) when
///   the originating country is sensitive. `//FGI S//REL TO USA, GBR`
///   An empty `countries` list indicates source-concealed FGI.
///
/// Countries are space-delimited in the source marking.
///
/// # Banner aggregation
///
/// If a document contains **any** source-concealed FGI portions alongside
/// source-acknowledged FGI portions, the banner must use `FGI` without
/// country codes — revealing the country list would compromise the
/// concealed source. This rule is enforced at the `PageContext` level
/// during banner validation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FgiClassification {
    /// Originating countries (space-delimited in source).
    /// Empty for source-concealed FGI (`//FGI S//...`).
    pub countries: Box<[Trigraph]>,
    /// Classification level (includes RESTRICTED).
    pub level: Classification,
}

// ---------------------------------------------------------------------------
// NATO classification
// ---------------------------------------------------------------------------

/// NATO classification ladder with optional SAP designation.
///
/// NATO uses a separate classification system governed by treaty.
/// Not everyone with a US clearance is cleared for NATO; many US systems
/// are not approved for NATO information.
///
/// # NATO SAP markings
///
/// Three NATO SAP programs exist, each with specific constraints:
///
/// - **ATOMAL**: Applies to CTS, NS, and NC levels. Space-separated in
///   banner (`COSMIC TOP SECRET ATOMAL`). Portion marks: CTSA, NSAT, NCA.
///   Alternative portion forms CTS-A, NS-A, NC-A also appear in practice.
/// - **BOHEMIA**: CTS-only. Hyphenated (`COSMIC TOP SECRET-BOHEMIA` → `CTS-B`).
/// - **BALK**: CTS-only, exercise replacement for BOHEMIA.
///   Hyphenated (`COSMIC TOP SECRET-BALK` → `CTS-BALK`).
///
/// Per the CAPCO Register, bare `COSMIC TOP SECRET` requires either
/// BOHEMIA or BALK — standalone CTS without a SAP suffix is an error.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum NatoClassification {
    NatoUnclassified,       // NU
    NatoRestricted,         // NR
    NatoConfidential,       // NC
    NatoConfidentialAtomal, // NCA (alt: NC-A)
    NatoSecret,             // NS
    NatoSecretAtomal,       // NSAT (alt: NS-A)
    CosmicTopSecret,        // CTS (requires BOHEMIA or BALK)
    CosmicTopSecretAtomal,  // CTSA (alt: CTS-A)
    CosmicTopSecretBohemia, // CTS-B
    CosmicTopSecretBalk,    // CTS-BALK
}

impl NatoClassification {
    /// Banner form (full words, as used in banner marking lines).
    pub fn banner_str(self) -> &'static str {
        match self {
            Self::NatoUnclassified => "NATO UNCLASSIFIED",
            Self::NatoRestricted => "NATO RESTRICTED",
            Self::NatoConfidential => "NATO CONFIDENTIAL",
            Self::NatoConfidentialAtomal => "NATO CONFIDENTIAL ATOMAL",
            Self::NatoSecret => "NATO SECRET",
            Self::NatoSecretAtomal => "NATO SECRET ATOMAL",
            Self::CosmicTopSecret => "COSMIC TOP SECRET",
            Self::CosmicTopSecretAtomal => "COSMIC TOP SECRET ATOMAL",
            Self::CosmicTopSecretBohemia => "COSMIC TOP SECRET-BOHEMIA",
            Self::CosmicTopSecretBalk => "COSMIC TOP SECRET-BALK",
        }
    }

    /// Portion form (primary abbreviation from the CAPCO Register).
    pub fn portion_str(self) -> &'static str {
        match self {
            Self::NatoUnclassified => "NU",
            Self::NatoRestricted => "NR",
            Self::NatoConfidential => "NC",
            Self::NatoConfidentialAtomal => "NCA",
            Self::NatoSecret => "NS",
            Self::NatoSecretAtomal => "NSAT",
            Self::CosmicTopSecret => "CTS",
            Self::CosmicTopSecretAtomal => "CTSA",
            Self::CosmicTopSecretBohemia => "CTS-B",
            Self::CosmicTopSecretBalk => "CTS-BALK",
        }
    }

    /// The base classification level (without SAP), for ordering comparisons.
    pub fn base_level(self) -> NatoLevel {
        match self {
            Self::NatoUnclassified => NatoLevel::NatoUnclassified,
            Self::NatoRestricted => NatoLevel::NatoRestricted,
            Self::NatoConfidential | Self::NatoConfidentialAtomal => NatoLevel::NatoConfidential,
            Self::NatoSecret | Self::NatoSecretAtomal => NatoLevel::NatoSecret,
            Self::CosmicTopSecret
            | Self::CosmicTopSecretAtomal
            | Self::CosmicTopSecretBohemia
            | Self::CosmicTopSecretBalk => NatoLevel::CosmicTopSecret,
        }
    }

    /// Map the NATO level to the equivalent US classification for conflict
    /// resolution (US wins at the greater of the two).
    pub fn us_equivalent(self) -> Classification {
        match self.base_level() {
            NatoLevel::NatoUnclassified => Classification::Unclassified,
            NatoLevel::NatoRestricted => Classification::Restricted,
            NatoLevel::NatoConfidential => Classification::Confidential,
            NatoLevel::NatoSecret => Classification::Secret,
            NatoLevel::CosmicTopSecret => Classification::TopSecret,
        }
    }
}

/// NATO classification level without SAP, for ordering comparisons.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum NatoLevel {
    NatoUnclassified,
    NatoRestricted,
    NatoConfidential,
    NatoSecret,
    CosmicTopSecret,
}

// ---------------------------------------------------------------------------
// JOINT classification
// ---------------------------------------------------------------------------

/// JOINT classification: US is co-owner with other nations.
///
/// `//JOINT S USA GBR//REL TO USA, GBR`
///
/// Country list is space-delimited (NOT comma-delimited like REL TO).
/// Must include USA. All JOINT participants must also appear in REL TO.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JointClassification {
    /// Classification level (US ladder, includes RESTRICTED).
    pub level: Classification,
    /// Co-owning countries (space-delimited in source). Must include USA.
    pub countries: Box<[Trigraph]>,
}

// ---------------------------------------------------------------------------
// Atomic Energy Act markings
// ---------------------------------------------------------------------------

/// Atomic Energy Act information markings (CAPCO Register §6).
///
/// AEA markings appear as a single `//`-delimited block in the marking string,
/// using hyphen separators for compound forms:
/// - `SECRET//RD//NOFORN` — RD alone
/// - `SECRET//RD-CNWDI//NOFORN` — RD with CNWDI modifier
/// - `SECRET//RD-SIGMA 20//NOFORN` — RD with SIGMA compartment
/// - `SECRET//RD-SIGMA 18 20//NOFORN` — RD with multiple SIGMAs
/// - `SECRET//FRD//NOFORN` — FRD alone
/// - `SECRET//FRD-SIGMA 14//NOFORN` — FRD with SIGMA
///
/// Standalone (non-compound) markings:
/// - `UNCLASSIFIED//DOD UCNI` / `(U//DCNI)`
/// - `UNCLASSIFIED//DOE UCNI` / `(U//UCNI)`
/// - `SECRET//TFNI//NOFORN` / `(S//TFNI//NF)`
///
/// # Key rules (CAPCO-2016)
///
/// - RD and FRD always require NOFORN unless a sharing agreement exists
///   (default severity: Error, configurable to Warn via `.marque.toml`)
/// - CNWDI may only be used with TS or S RD (not standalone, not with FRD)
/// - SIGMA 14, 15, 18, 20 may only be used with TS or S RD or FRD
/// - RD takes precedence over FRD and TFNI in both banners and portions
/// - SIGMA numbers must be in numerical order, space-separated
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum AeaMarking {
    /// Compound RD block: `RD`, `RD-CNWDI`, `RD-SIGMA 20`, `RD-CNWDI-SIGMA 18 20`
    Rd(RdBlock),
    /// Compound FRD block: `FRD`, `FRD-SIGMA 14`
    Frd(FrdBlock),
    /// DOD UCNI / DCNI — standalone, unclassified only
    DodUcni,
    /// DOE UCNI / UCNI — standalone, unclassified only
    DoeUcni,
    /// TFNI — standalone
    Tfni,
}

/// Restricted Data block with optional modifiers.
///
/// Rendered as `RD`, `RD-CNWDI`, `RD-SIGMA 20`, or `RD-CNWDI-SIGMA 18 20`.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct RdBlock {
    /// Whether CNWDI is present. Only valid with TS or S classification.
    pub cnwdi: bool,
    /// SIGMA compartment numbers (14, 15, 18, 20). Must be in numerical order.
    /// Empty if no SIGMA designation.
    pub sigma: Box<[u8]>,
}

impl Default for RdBlock {
    fn default() -> Self {
        Self {
            cnwdi: false,
            sigma: Box::new([]),
        }
    }
}

/// Formerly Restricted Data block with optional SIGMA modifier.
///
/// Rendered as `FRD` or `FRD-SIGMA 14`.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct FrdBlock {
    /// SIGMA compartment numbers. Must be in numerical order.
    /// Empty if no SIGMA designation.
    pub sigma: Box<[u8]>,
}

impl Default for FrdBlock {
    fn default() -> Self {
        Self {
            sigma: Box::new([]),
        }
    }
}

impl AeaMarking {
    /// Banner-line form.
    pub fn banner_str(&self) -> String {
        match self {
            Self::Rd(rd) => {
                let mut s = "RD".to_owned();
                if rd.cnwdi {
                    s.push_str("-CNWDI");
                }
                if !rd.sigma.is_empty() {
                    s.push_str("-SIGMA ");
                    let nums: Vec<String> = rd.sigma.iter().map(|n| n.to_string()).collect();
                    s.push_str(&nums.join(" "));
                }
                s
            }
            Self::Frd(frd) => {
                let mut s = "FRD".to_owned();
                if !frd.sigma.is_empty() {
                    s.push_str("-SIGMA ");
                    let nums: Vec<String> = frd.sigma.iter().map(|n| n.to_string()).collect();
                    s.push_str(&nums.join(" "));
                }
                s
            }
            Self::DodUcni => "DOD UCNI".to_owned(),
            Self::DoeUcni => "DOE UCNI".to_owned(),
            Self::Tfni => "TFNI".to_owned(),
        }
    }

    /// Portion mark form.
    pub fn portion_str(&self) -> String {
        match self {
            Self::Rd(rd) => {
                let mut s = "RD".to_owned();
                if rd.cnwdi {
                    s.push_str("-CNWDI");
                }
                if !rd.sigma.is_empty() {
                    s.push_str("-SG ");
                    let nums: Vec<String> = rd.sigma.iter().map(|n| n.to_string()).collect();
                    s.push_str(&nums.join(" "));
                }
                s
            }
            Self::Frd(frd) => {
                let mut s = "FRD".to_owned();
                if !frd.sigma.is_empty() {
                    s.push_str("-SG ");
                    let nums: Vec<String> = frd.sigma.iter().map(|n| n.to_string()).collect();
                    s.push_str(&nums.join(" "));
                }
                s
            }
            Self::DodUcni => "DCNI".to_owned(),
            Self::DoeUcni => "UCNI".to_owned(),
            Self::Tfni => "TFNI".to_owned(),
        }
    }

    /// Parse a `//`-delimited AEA block from either banner or portion form.
    ///
    /// Handles compound tokens: `RD`, `RD-CNWDI`, `RD-SIGMA 20`,
    /// `RD-CNWDI-SIGMA 18 20`, `FRD`, `FRD-SIGMA 14`, etc.
    pub fn parse(s: &str) -> Option<Self> {
        // Standalone non-compound markings.
        match s {
            "DOD UCNI" | "DCNI" => return Some(Self::DodUcni),
            "DOE UCNI" | "UCNI" => return Some(Self::DoeUcni),
            "TFNI" | "TRANSCLASSIFIED FOREIGN NUCLEAR INFORMATION" => return Some(Self::Tfni),
            _ => {}
        }

        // RD compound block: RD, RD-CNWDI, RD-SIGMA ##, RD-CNWDI-SIGMA ##,
        // RESTRICTED DATA, RESTRICTED DATA-CNWDI, etc.
        if s == "RD" || s == "RESTRICTED DATA" {
            return Some(Self::Rd(RdBlock::default()));
        }
        if let Some(rest) = s
            .strip_prefix("RD-")
            .or_else(|| s.strip_prefix("RESTRICTED DATA-"))
        {
            return Self::parse_rd_modifiers(rest);
        }

        // FRD compound block: FRD, FRD-SIGMA ##,
        // FORMERLY RESTRICTED DATA, etc.
        if s == "FRD" || s == "FORMERLY RESTRICTED DATA" {
            return Some(Self::Frd(FrdBlock::default()));
        }
        if let Some(rest) = s
            .strip_prefix("FRD-")
            .or_else(|| s.strip_prefix("FORMERLY RESTRICTED DATA-"))
        {
            return Self::parse_frd_modifiers(rest);
        }

        None
    }

    /// Parse RD modifiers after the `RD-` prefix.
    /// Handles: `CNWDI`, `SIGMA ##`, `CNWDI-SIGMA ##`, `SG ##`, `CNWDI-SG ##`.
    fn parse_rd_modifiers(s: &str) -> Option<Self> {
        let mut cnwdi = false;
        let mut rest = s;

        // Check for CNWDI prefix.
        if let Some(after) = rest.strip_prefix("CNWDI") {
            cnwdi = true;
            rest = after.strip_prefix('-').unwrap_or(after);
        } else if rest == "N" {
            // DoD shorthand: RD-N means RD-CNWDI (per CAPCO-2016 §6)
            return Some(Self::Rd(RdBlock {
                cnwdi: true,
                sigma: Box::new([]),
            }));
        }

        // Check for SIGMA/SG.
        let sigma = parse_sigma_numbers(rest);

        if rest.is_empty() || !sigma.is_empty() {
            Some(Self::Rd(RdBlock {
                cnwdi,
                sigma: sigma.into(),
            }))
        } else {
            None
        }
    }

    /// Parse FRD modifiers after the `FRD-` prefix.
    /// Handles: `SIGMA ##`, `SG ##`.
    fn parse_frd_modifiers(s: &str) -> Option<Self> {
        let sigma = parse_sigma_numbers(s);
        if !sigma.is_empty() {
            Some(Self::Frd(FrdBlock {
                sigma: sigma.into(),
            }))
        } else {
            None
        }
    }
}

/// Parse SIGMA/SG numbers from a string like `SIGMA 18 20` or `SG 14`.
fn parse_sigma_numbers(s: &str) -> Vec<u8> {
    let rest = s
        .strip_prefix("SIGMA ")
        .or_else(|| s.strip_prefix("SG "))
        .unwrap_or("");
    if rest.is_empty() {
        return vec![];
    }
    rest.split_whitespace()
        .filter_map(|n| n.parse::<u8>().ok())
        .collect()
}

impl std::fmt::Display for AeaMarking {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.portion_str())
    }
}

// ---------------------------------------------------------------------------
// FGI marker (in US-classified markings)
// ---------------------------------------------------------------------------

/// FGI marker in a US-classified marking: `FGI` or `FGI [LIST]`.
///
/// Appears in the FGI block (after SAR, before dissem controls) when a
/// US-classified document references foreign government information.
///
/// This is NOT the same as [`FgiClassification`] — that represents a
/// marking where the classification itself IS foreign. This marker says
/// "this US-classified marking contains foreign government information."
///
/// An empty `countries` list represents source-concealed FGI (no country
/// attribution). If a document mixes source-concealed and source-acknowledged
/// FGI portions, the banner must use the bare `FGI` form without countries
/// to avoid compromising the concealed source.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FgiMarker {
    /// Countries (space-delimited in source).
    /// Empty for source-concealed FGI.
    pub countries: Box<[Trigraph]>,
}

// ===========================================================================
// Non-IC dissemination controls
// ===========================================================================

/// Non-Intelligence Community dissemination control markings (CAPCO Register §9).
///
/// These operate under a separate authority framework from IC dissem controls.
/// In classified documents, most non-IC dissem controls appear **only in portion
/// markings** — they are stripped from banners. However, some controls propagate
/// to classified banners: LIMDIS (NGA Title 10), LES, LES-NF, and SSI. See
/// [`NonIcDissem::propagates_to_classified_banner`] for the authoritative list.
/// When the page is **unclassified**, all non-IC dissem controls propagate to
/// the banner.
///
/// LES-NF and SBU-NF carry NOFORN treatment even when stripped from the banner.
///
/// # CUI note
///
/// CUI (Controlled Unclassified Information) is recognized but not validated.
/// Full CUI rule support is planned for a dedicated crate. The IC equivalent
/// (FOUO) remains in active use in the `DissemControl` enum.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum NonIcDissem {
    /// LIMITED DISTRIBUTION / LIMDIS / DS
    Limdis,
    /// EXCLUSIVE DISTRIBUTION / EXDIS / XD
    Exdis,
    /// NO DISTRIBUTION / NODIS / ND
    Nodis,
    /// SENSITIVE BUT UNCLASSIFIED / SBU / SBU
    Sbu,
    /// SENSITIVE BUT UNCLASSIFIED NOFORN / SBU NOFORN / SBU-NF
    /// Carries NOFORN treatment even when stripped from banner.
    SbuNf,
    /// LAW ENFORCEMENT SENSITIVE / LES / LES
    Les,
    /// LAW ENFORCEMENT SENSITIVE NOFORN / LES NOFORN / LES-NF
    /// Carries NOFORN treatment even when stripped from banner.
    LesNf,
    /// SENSITIVE SECURITY INFORMATION / SSI / SSI
    Ssi,
}

impl NonIcDissem {
    /// Banner-line abbreviation form.
    pub fn banner_str(self) -> &'static str {
        match self {
            Self::Limdis => "LIMDIS",
            Self::Exdis => "EXDIS",
            Self::Nodis => "NODIS",
            Self::Sbu => "SBU",
            Self::SbuNf => "SBU NOFORN",
            Self::Les => "LES",
            Self::LesNf => "LES NOFORN",
            Self::Ssi => "SSI",
        }
    }

    /// Portion mark abbreviation.
    pub fn portion_str(self) -> &'static str {
        match self {
            Self::Limdis => "DS",
            Self::Exdis => "XD",
            Self::Nodis => "ND",
            Self::Sbu => "SBU",
            Self::SbuNf => "SBU-NF",
            Self::Les => "LES",
            Self::LesNf => "LES-NF",
            Self::Ssi => "SSI",
        }
    }

    /// Parse from either banner or portion form.
    pub fn parse(s: &str) -> Option<Self> {
        match s {
            "LIMDIS" | "DS" => Some(Self::Limdis),
            "EXDIS" | "XD" => Some(Self::Exdis),
            "NODIS" | "ND" => Some(Self::Nodis),
            "SBU" => Some(Self::Sbu),
            "SBU NOFORN" | "SBU-NF" => Some(Self::SbuNf),
            "LES" => Some(Self::Les),
            "LES NOFORN" | "LES-NF" => Some(Self::LesNf),
            "SSI" => Some(Self::Ssi),
            _ => None,
        }
    }

    /// Returns true if this control carries NOFORN treatment.
    pub fn carries_noforn(self) -> bool {
        matches!(self, Self::SbuNf | Self::LesNf)
    }

    /// Returns true if this control propagates to classified banners.
    ///
    /// Most non-IC dissem controls are stripped from banners in classified
    /// documents. These exceptions propagate:
    /// - LIMDIS: NGA Title 10 marking, appears in classified banners
    /// - LES: propagates to banners; LES-NF propagates as NOFORN//LES
    /// - SSI: propagates to banners
    pub fn propagates_to_classified_banner(self) -> bool {
        matches!(self, Self::Limdis | Self::Les | Self::LesNf | Self::Ssi)
    }

    /// All valid values.
    pub const ALL: &[NonIcDissem] = &[
        Self::Limdis,
        Self::Exdis,
        Self::Nodis,
        Self::Sbu,
        Self::SbuNf,
        Self::Les,
        Self::LesNf,
        Self::Ssi,
    ];
}

impl std::fmt::Display for NonIcDissem {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.portion_str())
    }
}

// ===========================================================================
// Trigraph
// ===========================================================================

/// A 3-character country trigraph (e.g., USA, GBR, AUS).
/// Validated against CVE country code list at rule-check time.
///
/// The inner bytes are private; construction goes through [`Trigraph::try_new`]
/// which enforces ASCII-uppercase invariants so that [`Trigraph::as_str`] can
/// return a `&str` infallibly without panicking at runtime.
///
/// # Limitations
///
/// CAPCO also uses tetragraphs (NATO, FVEY, ACGU) and longer org codes
/// (AUSTRALIA_GROUP). These are present in the CVE TRIGRAPHS list but cannot
/// be represented by this type's 3-byte constraint. A broader `CountryCode`
/// type is planned for a future version.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Trigraph([u8; 3]);

impl Trigraph {
    /// The always-valid `USA` trigraph constant.
    pub const USA: Self = Self(*b"USA");

    /// Attempt to construct a trigraph from 3 bytes.
    ///
    /// Returns `None` unless every byte is an ASCII uppercase letter
    /// (`A`–`Z`), which is the invariant enforced by CAPCO for all valid
    /// country/entity codes.
    #[inline]
    pub const fn try_new(bytes: [u8; 3]) -> Option<Self> {
        let mut i = 0;
        while i < 3 {
            if !bytes[i].is_ascii_uppercase() {
                return None;
            }
            i += 1;
        }
        Some(Self(bytes))
    }

    /// Return the trigraph as a string slice.
    ///
    /// Infallible because construction via [`Trigraph::try_new`] (or the
    /// [`Trigraph::USA`] constant) guarantees ASCII-uppercase bytes, which
    /// are always valid UTF-8.
    #[inline]
    pub fn as_str(&self) -> &str {
        // SAFETY: `Trigraph` can only be constructed via `try_new` or the
        // `USA` constant, both of which require ASCII uppercase letters.
        // ASCII is a subset of valid UTF-8.
        unsafe { std::str::from_utf8_unchecked(&self.0) }
    }
}

impl std::fmt::Display for Trigraph {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

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

    #[test]
    fn trigraph_usa_constant_is_valid() {
        assert_eq!(Trigraph::USA.as_str(), "USA");
    }

    #[test]
    fn trigraph_try_new_accepts_uppercase() {
        let t = Trigraph::try_new(*b"GBR").unwrap();
        assert_eq!(t.as_str(), "GBR");
    }

    #[test]
    fn trigraph_try_new_rejects_lowercase() {
        assert!(Trigraph::try_new(*b"usa").is_none());
    }

    #[test]
    fn trigraph_try_new_rejects_digits() {
        assert!(Trigraph::try_new(*b"US1").is_none());
    }

    #[test]
    fn trigraph_try_new_rejects_high_bytes() {
        assert!(Trigraph::try_new([0xFF, 0xFF, 0xFF]).is_none());
    }

    #[test]
    fn classification_ord_is_restrictiveness() {
        assert!(Classification::Unclassified < Classification::Restricted);
        assert!(Classification::Restricted < Classification::Confidential);
        assert!(Classification::Confidential < Classification::Secret);
        assert!(Classification::Secret < Classification::TopSecret);
    }

    #[test]
    fn classification_banner_portion_round_trip() {
        for c in [
            Classification::Unclassified,
            Classification::Restricted,
            Classification::Confidential,
            Classification::Secret,
            Classification::TopSecret,
        ] {
            assert!(!c.banner_str().is_empty());
            assert!(!c.portion_str().is_empty());
        }
    }

    #[test]
    fn nato_us_equivalent_mapping() {
        assert_eq!(
            NatoClassification::CosmicTopSecret.us_equivalent(),
            Classification::TopSecret,
        );
        assert_eq!(
            NatoClassification::NatoSecret.us_equivalent(),
            Classification::Secret,
        );
        assert_eq!(
            NatoClassification::NatoRestricted.us_equivalent(),
            Classification::Restricted,
        );
    }

    #[test]
    fn nato_banner_portion_round_trip() {
        for n in [
            NatoClassification::NatoUnclassified,
            NatoClassification::NatoRestricted,
            NatoClassification::NatoConfidential,
            NatoClassification::NatoConfidentialAtomal,
            NatoClassification::NatoSecret,
            NatoClassification::NatoSecretAtomal,
            NatoClassification::CosmicTopSecret,
            NatoClassification::CosmicTopSecretAtomal,
            NatoClassification::CosmicTopSecretBohemia,
            NatoClassification::CosmicTopSecretBalk,
        ] {
            assert!(!n.banner_str().is_empty());
            assert!(!n.portion_str().is_empty());
        }
    }

    #[test]
    fn us_classification_convenience_returns_us() {
        let attrs = IsmAttributes {
            classification: Some(MarkingClassification::Us(Classification::Secret)),
            ..Default::default()
        };
        assert_eq!(attrs.us_classification(), Some(Classification::Secret));
    }

    #[test]
    fn us_classification_convenience_returns_none_for_nato() {
        let attrs = IsmAttributes {
            classification: Some(MarkingClassification::Nato(NatoClassification::NatoSecret)),
            ..Default::default()
        };
        assert_eq!(attrs.us_classification(), None);
    }

    #[test]
    fn us_classification_convenience_returns_resolved_for_conflict() {
        let attrs = IsmAttributes {
            classification: Some(MarkingClassification::Conflict {
                us: Classification::TopSecret,
                foreign: Box::new(ForeignClassification::Nato(
                    NatoClassification::CosmicTopSecret,
                )),
            }),
            ..Default::default()
        };
        assert_eq!(attrs.us_classification(), Some(Classification::TopSecret));
    }
}