sidereon_core/

constellation.rs

//! GNSS constellation identity catalog and validation helpers.
//!
//! This is a data/catalog layer: it builds normalized satellite identity
//! records from public sources and compares those records with GNSS products.
//! It does not alter positioning solves or infer application-specific health
//! rules. It is deterministic and performs no network access; fetching the
//! source bytes is the caller's (binding's) job.
//!
//! GPS is supported first. CelesTrak `gps-ops` OMM/JSON is the base source for
//! current NORAD catalog ids and PRN assignments; the PRN is parsed from
//! `OBJECT_NAME` and rendered as the SP3/RINEX id (`"G13"`). NAVCEN's GPS
//! constellation status page can be parsed and merged as an optional overlay
//! for SVN and NANU usability details.
//!
//! The OMM input is the canonical [`Omm`](crate::astro::omm::Omm) produced by
//! the core OMM parser (`crate::astro::omm::{parse_json, parse_json_array}`):
//! this module does not re-parse OMM from scratch, it reads `OBJECT_NAME` and
//! `NORAD_CAT_ID` off already-parsed records.
//!
//! ```
//! use sidereon_core::constellation::{to_csv, BoolStyle, Record, RecordSource};
//! use sidereon_core::GnssSystem;
//!
//! let record = Record {
//!     system: GnssSystem::Gps,
//!     prn: 3,
//!     svn: None,
//!     norad_id: 40294,
//!     sp3_id: "G03".to_string(),
//!     active: true,
//!     usable: true,
//!     source: RecordSource::default(),
//! };
//! assert_eq!(
//!     to_csv(&[record], BoolStyle::Lower),
//!     "prn,norad_cat_id,active,sp3_id\n3,40294,true,G03\n"
//! );
//! ```

use crate::astro::omm::Omm;
use crate::ephemeris::Sp3;
use crate::id::GnssSystem;
use core::fmt;

const CELESTRAK_GPS_GROUP: &str = "gps-ops";

/// Failure modes of the constellation catalog builders.
///
/// Mirrors the typed error pattern used by the core parsers (for example
/// `astro::omm::OmmError`): a small enum with a `Display` and `std::error::Error`
/// implementation, never a panic on malformed input.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ConstellationError {
    /// A CelesTrak `OBJECT_NAME` did not contain a parseable `(PRN nn)` block,
    /// or the OMM carried no object name at all. Holds the offending name.
    MissingPrn(Option<String>),
    /// The NAVCEN status bytes were not valid UTF-8.
    NavcenNotUtf8,
    /// The NAVCEN status HTML contained no GPS constellation rows.
    NavcenNoRows,
    /// A required NAVCEN integer cell could not be parsed. Holds the field name
    /// and the offending text.
    NavcenBadField {
        /// The NAVCEN field whose cell failed to parse (for example `gps-prn`).
        field: &'static str,
        /// The raw cell text that failed to parse.
        value: String,
    },
    /// A catalog failed SP3 validation. Holds a description of the findings.
    Sp3Validation(String),
}

impl fmt::Display for ConstellationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            ConstellationError::MissingPrn(Some(name)) => {
                write!(f, "CelesTrak OBJECT_NAME has no PRN: {name:?}")
            }
            ConstellationError::MissingPrn(None) => {
                write!(f, "CelesTrak record has no OBJECT_NAME")
            }
            ConstellationError::NavcenNotUtf8 => write!(f, "NAVCEN bytes are not valid UTF-8"),
            ConstellationError::NavcenNoRows => write!(f, "NAVCEN HTML has no GPS rows"),
            ConstellationError::NavcenBadField { field, value } => {
                write!(f, "NAVCEN field {field} has invalid integer {value:?}")
            }
            ConstellationError::Sp3Validation(msg) => {
                write!(f, "GNSS catalog failed SP3 validation: {msg}")
            }
        }
    }
}

impl std::error::Error for ConstellationError {}

/// Per-source provenance kept on a [`Record`].
///
/// `active` in a record means the satellite is present in the base identity
/// source. `usable` is an advisory health flag; for the current GPS path it is
/// `true` unless a compatible merged NAVCEN row carries an active NANU that
/// marks the PRN unusable or decommissioned.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct RecordSource {
    /// CelesTrak `gps-ops` identity provenance.
    pub celestrak: Option<CelestrakSource>,
    /// NAVCEN overlay that was merged into this record.
    pub navcen: Option<NavcenSource>,
    /// A NAVCEN row that matched the PRN but was not merged because its block
    /// type was incompatible with the CelesTrak identity (a PRN transition).
    pub navcen_conflict: Option<NavcenSource>,
}

/// CelesTrak `gps-ops` provenance fields preserved on a record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CelestrakSource {
    /// CelesTrak GP group the record came from (`gps-ops`).
    pub group: String,
    /// The OMM `OBJECT_NAME`.
    pub object_name: Option<String>,
    /// The OMM `OBJECT_ID` (international designator).
    pub object_id: Option<String>,
    /// The OMM `EPOCH`, ISO-8601.
    pub epoch: Option<String>,
    /// Block type parsed from the object name (`IIF`, `IIR`, `IIR-M`, `III`).
    pub block_type: Option<String>,
}

/// NAVCEN status provenance fields preserved on a record or conflict.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NavcenSource {
    /// Space Vehicle Number.
    pub svn: Option<u16>,
    /// Block type as reported by NAVCEN.
    pub block_type: Option<String>,
    /// Orbital plane letter.
    pub plane: Option<String>,
    /// Slot within the plane.
    pub slot: Option<String>,
    /// Clock type.
    pub clock: Option<String>,
    /// NANU type code (for example `FCSTSUMM`, `UNUSABLE`, `DECOM`).
    pub nanu_type: Option<String>,
    /// NANU subject line.
    pub nanu_subject: Option<String>,
    /// Whether the row carried an active NANU.
    pub active_nanu: bool,
}

/// A normalized GNSS satellite identity record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Record {
    /// The constellation. GPS today; the type is system-tagged for extension.
    pub system: GnssSystem,
    /// The within-constellation PRN.
    pub prn: u16,
    /// Space Vehicle Number, when known (CelesTrak alone leaves this `None`).
    pub svn: Option<u16>,
    /// NORAD catalog id.
    pub norad_id: u32,
    /// Canonical SP3/RINEX satellite token (`G03`).
    pub sp3_id: String,
    /// Present in the base identity source.
    pub active: bool,
    /// Advisory usability flag.
    pub usable: bool,
    /// Source provenance.
    pub source: RecordSource,
}

/// A parsed row from NAVCEN's GPS constellation status table.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NavcenStatus {
    /// The constellation (GPS).
    pub system: GnssSystem,
    /// The within-constellation PRN.
    pub prn: u16,
    /// Space Vehicle Number, when present.
    pub svn: Option<u16>,
    /// Whether the satellite is usable per the active NANU (if any).
    pub usable: bool,
    /// Whether the row carried an active NANU.
    pub active_nanu: bool,
    /// NANU type code.
    pub nanu_type: Option<String>,
    /// NANU subject line.
    pub nanu_subject: Option<String>,
    /// Orbital plane letter.
    pub plane: Option<String>,
    /// Slot within the plane.
    pub slot: Option<String>,
    /// Block type.
    pub block_type: Option<String>,
    /// Clock type.
    pub clock: Option<String>,
}

/// Validation report for a constellation catalog.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Validation {
    /// Active+usable catalog SP3 ids absent from the compared product.
    pub missing_sp3_ids: Vec<String>,
    /// PRNs that appear in more than one record.
    pub duplicate_prns: Vec<u16>,
    /// NORAD ids that appear in more than one record.
    pub duplicate_norad_ids: Vec<u32>,
    /// PRNs that are inactive or unusable.
    pub inactive_unusable_prns: Vec<u16>,
    /// SP3 ids present in the product but absent from the active+usable catalog.
    pub extra_sp3_ids: Vec<String>,
}

/// A single field change on a PRN that exists in both diffed snapshots.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FieldChange<T> {
    /// The constellation.
    pub system: GnssSystem,
    /// The PRN.
    pub prn: u16,
    /// The value in the previous snapshot.
    pub from: T,
    /// The value in the current snapshot.
    pub to: T,
}

/// Change report between two catalog snapshots, keyed by `(system, prn)`.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Diff {
    /// PRNs present only in the current snapshot.
    pub added: Vec<Record>,
    /// PRNs present only in the previous snapshot.
    pub removed: Vec<Record>,
    /// NORAD id reassignments on a held PRN.
    pub norad_reassigned: Vec<FieldChange<u32>>,
    /// SP3 id changes on a held PRN.
    pub sp3_id_changed: Vec<FieldChange<String>>,
    /// SVN changes on a held PRN.
    pub svn_changed: Vec<FieldChange<Option<u16>>>,
    /// Activity flips on a held PRN.
    pub activity_changed: Vec<FieldChange<bool>>,
    /// Usability flips on a held PRN.
    pub usability_changed: Vec<FieldChange<bool>>,
}

/// How the CSV `active` column renders booleans.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum BoolStyle {
    /// `true` / `false` (the conventional CSV form).
    #[default]
    Lower,
    /// `True` / `False` (for a consumer that reads Python booleans).
    Title,
}

/// Render the canonical SP3/RINEX satellite token for a GPS PRN (`7` -> `G07`).
#[must_use]
pub fn gps_sp3_id(prn: u16) -> String {
    format!("{}{prn:02}", GnssSystem::Gps.letter())
}

/// Build GPS records from already-parsed CelesTrak `gps-ops` OMM records.
///
/// CelesTrak does not publish SVN in this feed, so records built from this
/// source alone have `svn: None`. Records are returned sorted by PRN. Fails with
/// [`ConstellationError::MissingPrn`] when an `OBJECT_NAME` has no `(PRN nn)`.
pub fn from_celestrak_omm(omms: &[Omm]) -> Result<Vec<Record>, ConstellationError> {
    let mut records = Vec::with_capacity(omms.len());
    for omm in omms {
        records.push(record_from_omm(omm)?);
    }
    records.sort_by_key(|r| (r.system, r.prn));
    Ok(records)
}

fn record_from_omm(omm: &Omm) -> Result<Record, ConstellationError> {
    let object_name = omm.object_name.as_deref();
    let prn = prn_from_object_name(object_name)
        .ok_or_else(|| ConstellationError::MissingPrn(omm.object_name.clone()))?;

    Ok(Record {
        system: GnssSystem::Gps,
        prn,
        svn: None,
        norad_id: omm.norad_cat_id,
        sp3_id: gps_sp3_id(prn),
        active: true,
        usable: true,
        source: RecordSource {
            celestrak: Some(CelestrakSource {
                group: CELESTRAK_GPS_GROUP.to_string(),
                object_name: omm.object_name.clone(),
                object_id: omm.object_id.clone(),
                epoch: Some(epoch_iso8601(omm)),
                block_type: block_type_from_object_name(object_name),
            }),
            navcen: None,
            navcen_conflict: None,
        },
    })
}

fn epoch_iso8601(omm: &Omm) -> String {
    let e = &omm.epoch;
    format!(
        "{:04}-{:02}-{:02}T{:02}:{:02}:{:02}.{:06}",
        e.year, e.month, e.day, e.hour, e.minute, e.second, e.microsecond
    )
}

/// Parse `(PRN nn)` from a CelesTrak object name, stripping leading zeros.
///
/// Matches the reference regex `\(PRN\s*0*([0-9]{1,3})\)` (case-insensitive),
/// including its *search* semantics: every `(PRN` occurrence is tried, so a
/// later valid `(PRN nn)` is found even if an earlier `(PRN ...)` does not
/// parse. The PRN is up to three significant digits and must be positive.
fn prn_from_object_name(name: Option<&str>) -> Option<u16> {
    let name = name?;
    let mut from = 0;
    while let Some(rel) = find_ci(&name[from..], "(PRN") {
        let after = from + rel + "(PRN".len();
        if let Some(prn) = prn_at(&name[after..]) {
            return Some(prn);
        }
        from = after;
    }
    None
}

/// Parse `\s*0*([0-9]{1,3})\)` at the start of `rest`.
fn prn_at(rest: &str) -> Option<u16> {
    let rest = rest.trim_start();
    let bytes = rest.as_bytes();

    let mut i = 0;
    while i < bytes.len() && bytes[i] == b'0' {
        i += 1;
    }
    let digit_start = i;
    let mut count = 0;
    while i < bytes.len() && bytes[i].is_ascii_digit() && count < 3 {
        i += 1;
        count += 1;
    }
    if i >= bytes.len() || bytes[i] != b')' || digit_start == i {
        return None;
    }
    let value: u16 = rest[digit_start..i].parse().ok()?;
    (value > 0).then_some(value)
}

/// Parse the GPS block type from a CelesTrak object name token.
///
/// Mirrors the reference patterns, matched as whole words in the order
/// `IIR-M`, `III`, `IIF`, `IIR` so `BIIRM` is not caught by `BIIR`.
fn block_type_from_object_name(name: Option<&str>) -> Option<String> {
    let name = name?;
    if contains_word_ci(name, "BIIRM") || contains_word_ci(name, "BIIR-M") {
        Some("IIR-M".to_string())
    } else if contains_word_ci(name, "BIII") {
        Some("III".to_string())
    } else if contains_word_ci(name, "BIIF") {
        Some("IIF".to_string())
    } else if contains_word_ci(name, "BIIR") {
        Some("IIR".to_string())
    } else {
        None
    }
}

/// Parse NAVCEN's GPS constellation status HTML from raw bytes.
///
/// The parser targets the Drupal table-field classes NAVCEN's public GPS
/// constellation page uses, scanned without an HTML crate. Returns status rows
/// sorted by PRN; merge them into CelesTrak records with [`merge_navcen`].
pub fn parse_navcen(bytes: &[u8]) -> Result<Vec<NavcenStatus>, ConstellationError> {
    let html = core::str::from_utf8(bytes).map_err(|_| ConstellationError::NavcenNotUtf8)?;

    let mut statuses = Vec::new();
    for row in tr_blocks(html) {
        if find_ci(row, "views-field-field-gps-prn").is_none() || find_ci(row, "<td").is_none() {
            continue;
        }
        statuses.push(navcen_status_from_row(row)?);
    }

    if statuses.is_empty() {
        return Err(ConstellationError::NavcenNoRows);
    }
    statuses.sort_by_key(|s| s.prn);
    Ok(statuses)
}

fn navcen_status_from_row(row: &str) -> Result<NavcenStatus, ConstellationError> {
    let prn = navcen_required_int(row, "gps-prn")?;
    let svn = navcen_optional_int(row, "gps-svn")?;
    let nanu_type = navcen_text(row, "nanu-type");
    let active_nanu = navcen_active(row);
    let usable = !(active_nanu && unusable_nanu_type(nanu_type.as_deref()));

    Ok(NavcenStatus {
        system: GnssSystem::Gps,
        prn,
        svn,
        usable,
        active_nanu,
        nanu_type: blank_to_none(nanu_type),
        nanu_subject: blank_to_none(navcen_text(row, "nanu-subject")),
        plane: blank_to_none(navcen_text(row, "gps-con-plane")),
        slot: blank_to_none(navcen_text(row, "gps-con-slot")),
        block_type: blank_to_none(navcen_text(row, "gps-con-block-type")),
        clock: blank_to_none(navcen_text(row, "gps-con-clock")),
    })
}

fn navcen_required_int(row: &str, field: &'static str) -> Result<u16, ConstellationError> {
    let text = navcen_text(row, field);
    parse_positive_int(text.as_deref().unwrap_or(""), field)
}

fn navcen_optional_int(row: &str, field: &'static str) -> Result<Option<u16>, ConstellationError> {
    match navcen_text(row, field).as_deref() {
        None | Some("") => Ok(None),
        Some(text) => parse_positive_int(text, field).map(Some),
    }
}

fn parse_positive_int(text: &str, field: &'static str) -> Result<u16, ConstellationError> {
    let trimmed = text.trim();
    match trimmed.parse::<u16>() {
        Ok(value) if value > 0 => Ok(value),
        _ => Err(ConstellationError::NavcenBadField {
            field,
            value: trimmed.to_string(),
        }),
    }
}

fn navcen_text(row: &str, field: &str) -> Option<String> {
    let needle = format!("views-field-field-{field}");
    td_inner(row, &needle).map(clean_html)
}

fn navcen_active(row: &str) -> bool {
    td_inner(row, "nanu-active-check")
        .map(clean_html)
        .as_deref()
        == Some("1")
}

fn unusable_nanu_type(nanu_type: Option<&str>) -> bool {
    match nanu_type {
        None => false,
        Some(text) => {
            let upper = text.trim().to_ascii_uppercase();
            matches!(
                upper.as_str(),
                "UNUSABLE" | "DECOM" | "FCSTDV" | "FCSTMX" | "FCSTEXTD"
            )
        }
    }
}

/// Merge NAVCEN status rows into normalized records by PRN.
///
/// NAVCEN does not publish NORAD ids, so CelesTrak stays the identity base. When
/// a PRN exists in both sources and the block types are compatible, this fills
/// `svn`, updates `usable`, and records the NAVCEN provenance. A NAVCEN row that
/// matches the PRN but carries an incompatible block type (a PRN transition) is
/// recorded under `navcen_conflict` rather than merged. Returns records sorted
/// by PRN.
///
/// As in the reference (`Map.new(statuses, &{&1.prn, &1})`), at most one status
/// is kept per PRN; if the input carries duplicate PRNs the last one wins.
#[must_use]
pub fn merge_navcen(records: &[Record], statuses: &[NavcenStatus]) -> Vec<Record> {
    let mut by_prn: std::collections::HashMap<u16, &NavcenStatus> =
        std::collections::HashMap::with_capacity(statuses.len());
    for status in statuses {
        by_prn.insert(status.prn, status);
    }

    let mut merged: Vec<Record> = records
        .iter()
        .map(|record| match by_prn.get(&record.prn) {
            Some(status) => merge_status(record, status),
            None => record.clone(),
        })
        .collect();
    merged.sort_by_key(|r| r.prn);
    merged
}

fn merge_status(record: &Record, status: &NavcenStatus) -> Record {
    let mut out = record.clone();
    if navcen_compatible(record, status) {
        out.svn = status.svn;
        out.usable = status.usable;
        out.source.navcen = Some(navcen_source(status));
    } else {
        out.source.navcen_conflict = Some(navcen_source(status));
    }
    out
}

fn navcen_source(status: &NavcenStatus) -> NavcenSource {
    NavcenSource {
        svn: status.svn,
        block_type: status.block_type.clone(),
        plane: status.plane.clone(),
        slot: status.slot.clone(),
        clock: status.clock.clone(),
        nanu_type: status.nanu_type.clone(),
        nanu_subject: status.nanu_subject.clone(),
        active_nanu: status.active_nanu,
    }
}

fn navcen_compatible(record: &Record, status: &NavcenStatus) -> bool {
    let celestrak_block = record
        .source
        .celestrak
        .as_ref()
        .and_then(|c| c.block_type.as_deref());
    let navcen_block = status
        .block_type
        .as_deref()
        .map(|b| b.trim().to_ascii_uppercase());

    match (celestrak_block, navcen_block) {
        (Some(a), Some(b)) => a == b,
        _ => true,
    }
}

/// Export records as the compact mapping CSV.
///
/// The header is `prn,norad_cat_id,active,sp3_id`. The `active` column is `true`
/// only when both `active` and `usable` hold. Records are sorted by PRN.
#[must_use]
pub fn to_csv(records: &[Record], booleans: BoolStyle) -> String {
    let mut sorted: Vec<&Record> = records.iter().collect();
    sorted.sort_by_key(|r| r.prn);

    let mut out = String::from("prn,norad_cat_id,active,sp3_id\n");
    for record in sorted {
        let active = format_bool(operational(record), booleans);
        out.push_str(&format!(
            "{},{},{},{}\n",
            record.prn, record.norad_id, active, record.sp3_id
        ));
    }
    out
}

fn format_bool(value: bool, style: BoolStyle) -> &'static str {
    match (style, value) {
        (BoolStyle::Lower, true) => "true",
        (BoolStyle::Lower, false) => "false",
        (BoolStyle::Title, true) => "True",
        (BoolStyle::Title, false) => "False",
    }
}

fn operational(record: &Record) -> bool {
    record.active && record.usable
}

/// Validate catalog identity without an SP3 product.
///
/// Reports duplicate PRNs, duplicate NORAD ids, and PRNs that are inactive or
/// unusable.
#[must_use]
pub fn validate(records: &[Record]) -> Validation {
    validation(records, None)
}

/// Validate catalog identity against a loaded SP3 product.
///
/// `missing_sp3_ids` reports active+usable catalog GPS ids absent from the
/// product; `extra_sp3_ids` reports GPS ids in the product absent from the
/// active+usable catalog.
#[must_use]
pub fn validate_against_sp3(records: &[Record], sp3: &Sp3) -> Validation {
    let ids: Vec<String> = sp3
        .header
        .satellites
        .iter()
        .map(ToString::to_string)
        .collect();
    validation(records, Some(&ids))
}

/// Validate catalog identity against a plain list of SP3/RINEX satellite tokens.
#[must_use]
pub fn validate_against_sp3_ids(records: &[Record], sp3_ids: &[&str]) -> Validation {
    let ids: Vec<String> = sp3_ids.iter().map(|id| (*id).to_string()).collect();
    validation(records, Some(&ids))
}

fn validation(records: &[Record], sp3_ids: Option<&[String]>) -> Validation {
    let mut report = Validation {
        missing_sp3_ids: Vec::new(),
        duplicate_prns: duplicates(records.iter().map(|r| r.prn)),
        duplicate_norad_ids: duplicates(records.iter().map(|r| r.norad_id)),
        inactive_unusable_prns: inactive_unusable_prns(records),
        extra_sp3_ids: Vec::new(),
    };

    if let Some(sp3_ids) = sp3_ids {
        let catalog: Vec<String> = records
            .iter()
            .filter(|r| operational(r))
            .map(|r| r.sp3_id.to_ascii_uppercase())
            .collect();
        let product: Vec<String> = sp3_ids
            .iter()
            .map(|id| id.to_ascii_uppercase())
            .filter(|id| id.starts_with('G'))
            .collect();

        report.missing_sp3_ids = set_difference(&catalog, &product);
        report.extra_sp3_ids = set_difference(&product, &catalog);
    }

    report
}

fn duplicates<T>(values: impl Iterator<Item = T>) -> Vec<T>
where
    T: Ord + Copy,
{
    let mut seen: Vec<T> = values.collect();
    seen.sort_unstable();
    let mut out = Vec::new();
    let mut i = 0;
    while i < seen.len() {
        let mut j = i + 1;
        while j < seen.len() && seen[j] == seen[i] {
            j += 1;
        }
        if j - i > 1 {
            out.push(seen[i]);
        }
        i = j;
    }
    out
}

fn inactive_unusable_prns(records: &[Record]) -> Vec<u16> {
    let mut prns: Vec<u16> = records
        .iter()
        .filter(|r| !operational(r))
        .map(|r| r.prn)
        .collect();
    prns.sort_unstable();
    prns.dedup();
    prns
}

fn set_difference(left: &[String], right: &[String]) -> Vec<String> {
    let mut out: Vec<String> = left
        .iter()
        .filter(|id| !right.contains(id))
        .cloned()
        .collect();
    out.sort();
    out.dedup();
    out
}

/// Returns `true` when a validation report has no findings.
#[must_use]
pub fn is_valid(report: &Validation) -> bool {
    report.missing_sp3_ids.is_empty()
        && report.duplicate_prns.is_empty()
        && report.duplicate_norad_ids.is_empty()
        && report.inactive_unusable_prns.is_empty()
        && report.extra_sp3_ids.is_empty()
}

/// Validate against a plain SP3 id list and fail unless the catalog is clean.
///
/// A build-time gate: returns `Ok(())` when the report has no findings, otherwise
/// [`ConstellationError::Sp3Validation`] describing them.
pub fn validate_against_sp3_ids_strict(
    records: &[Record],
    sp3_ids: &[&str],
) -> Result<(), ConstellationError> {
    let report = validate_against_sp3_ids(records, sp3_ids);
    if is_valid(&report) {
        Ok(())
    } else {
        Err(ConstellationError::Sp3Validation(describe_findings(
            &report,
        )))
    }
}

fn describe_findings(report: &Validation) -> String {
    let mut parts = Vec::new();
    if !report.missing_sp3_ids.is_empty() {
        parts.push(format!("missing_sp3_ids: {:?}", report.missing_sp3_ids));
    }
    if !report.extra_sp3_ids.is_empty() {
        parts.push(format!("extra_sp3_ids: {:?}", report.extra_sp3_ids));
    }
    if !report.duplicate_prns.is_empty() {
        parts.push(format!("duplicate_prns: {:?}", report.duplicate_prns));
    }
    if !report.duplicate_norad_ids.is_empty() {
        parts.push(format!(
            "duplicate_norad_ids: {:?}",
            report.duplicate_norad_ids
        ));
    }
    if !report.inactive_unusable_prns.is_empty() {
        parts.push(format!(
            "inactive_unusable_prns: {:?}",
            report.inactive_unusable_prns
        ));
    }
    parts.join("; ")
}

/// Compare two catalog snapshots by `(system, prn)` identity.
///
/// Assumes each input has at most one record per `(system, prn)`; run
/// [`validate`] first on hand-edited catalogs and treat duplicate findings as
/// malformed input rather than a constellation change.
#[must_use]
pub fn diff(previous: &[Record], current: &[Record]) -> Diff {
    let key = |r: &Record| (r.system, r.prn);

    let added: Vec<Record> = current
        .iter()
        .filter(|c| !previous.iter().any(|p| key(p) == key(c)))
        .cloned()
        .collect();
    let removed: Vec<Record> = previous
        .iter()
        .filter(|p| !current.iter().any(|c| key(c) == key(p)))
        .cloned()
        .collect();

    let mut added = added;
    let mut removed = removed;
    added.sort_by_key(|r| (r.system, r.prn));
    removed.sort_by_key(|r| (r.system, r.prn));

    let mut common: Vec<(GnssSystem, u16)> = previous
        .iter()
        .filter_map(|p| current.iter().find(|c| key(c) == key(p)).map(|_| key(p)))
        .collect();
    common.sort_unstable();

    let pairs: Vec<(&Record, &Record)> = common
        .iter()
        .map(|k| {
            let p = previous.iter().find(|r| key(r) == *k).expect("common key");
            let c = current.iter().find(|r| key(r) == *k).expect("common key");
            (p, c)
        })
        .collect();

    Diff {
        added,
        removed,
        norad_reassigned: changes(&pairs, |r| r.norad_id),
        sp3_id_changed: changes(&pairs, |r| r.sp3_id.clone()),
        svn_changed: changes(&pairs, |r| r.svn),
        activity_changed: changes(&pairs, |r| r.active),
        usability_changed: changes(&pairs, |r| r.usable),
    }
}

fn changes<T, F>(pairs: &[(&Record, &Record)], field: F) -> Vec<FieldChange<T>>
where
    T: PartialEq,
    F: Fn(&Record) -> T,
{
    pairs
        .iter()
        .filter_map(|(p, c)| {
            let from = field(p);
            let to = field(c);
            if from == to {
                None
            } else {
                Some(FieldChange {
                    system: p.system,
                    prn: p.prn,
                    from,
                    to,
                })
            }
        })
        .collect()
}

/// Returns `true` when a diff has any findings.
#[must_use]
pub fn changed(diff: &Diff) -> bool {
    !diff.added.is_empty()
        || !diff.removed.is_empty()
        || !diff.norad_reassigned.is_empty()
        || !diff.sp3_id_changed.is_empty()
        || !diff.svn_changed.is_empty()
        || !diff.activity_changed.is_empty()
        || !diff.usability_changed.is_empty()
}

// ── HTML/text scanning helpers (dependency-light) ────────────────────────────

fn blank_to_none(value: Option<String>) -> Option<String> {
    value.filter(|v| !v.is_empty())
}

/// Case-insensitive ASCII substring search returning the byte offset.
fn find_ci(haystack: &str, needle: &str) -> Option<usize> {
    let hay = haystack.as_bytes();
    let need = needle.as_bytes();
    if need.is_empty() {
        return Some(0);
    }
    if hay.len() < need.len() {
        return None;
    }
    (0..=hay.len() - need.len()).find(|&i| {
        hay[i..i + need.len()]
            .iter()
            .zip(need)
            .all(|(a, b)| a.eq_ignore_ascii_case(b))
    })
}

fn is_word_byte(b: u8) -> bool {
    b.is_ascii_alphanumeric() || b == b'_'
}

/// Case-insensitive whole-word match, mirroring regex `\bword\b` boundaries.
fn contains_word_ci(haystack: &str, word: &str) -> bool {
    let hay = haystack.as_bytes();
    let need = word.as_bytes();
    let n = need.len();
    if n == 0 || hay.len() < n {
        return false;
    }
    (0..=hay.len() - n).any(|i| {
        let matched = hay[i..i + n]
            .iter()
            .zip(need)
            .all(|(a, b)| a.eq_ignore_ascii_case(b));
        if !matched {
            return false;
        }
        let left_ok = i == 0 || !is_word_byte(hay[i - 1]);
        let right_ok = i + n == hay.len() || !is_word_byte(hay[i + n]);
        left_ok && right_ok
    })
}

/// Split HTML into the inner text of each `<tr>...</tr>` block.
fn tr_blocks(html: &str) -> Vec<&str> {
    let mut out = Vec::new();
    let mut rest = html;
    while let Some(start) = find_ci(rest, "<tr") {
        let Some(gt) = rest[start..].find('>') else {
            break;
        };
        let content_start = start + gt + 1;
        let Some(close) = find_ci(&rest[content_start..], "</tr>") else {
            break;
        };
        out.push(&rest[content_start..content_start + close]);
        rest = &rest[content_start + close + "</tr>".len()..];
    }
    out
}

/// Inner text of the first `<td>` whose attributes contain `class_needle`.
fn td_inner<'a>(row: &'a str, class_needle: &str) -> Option<&'a str> {
    let mut rest = row;
    loop {
        let start = find_ci(rest, "<td")?;
        let gt = rest[start..].find('>')?;
        let attrs = &rest[start..start + gt];
        let content_start = start + gt + 1;
        let close = find_ci(&rest[content_start..], "</td>")?;
        let inner = &rest[content_start..content_start + close];
        if find_ci(attrs, class_needle).is_some() {
            return Some(inner);
        }
        rest = &rest[content_start + close + "</td>".len()..];
    }
}

/// Strip tags, unescape entities, and collapse whitespace, matching the
/// reference `clean_html`.
fn clean_html(text: &str) -> String {
    let mut stripped = String::with_capacity(text.len());
    let mut in_tag = false;
    for c in text.chars() {
        match c {
            '<' => in_tag = true,
            '>' => in_tag = false,
            _ if !in_tag => stripped.push(c),
            _ => {}
        }
    }
    let unescaped = html_unescape(&stripped);
    unescaped.split_whitespace().collect::<Vec<_>>().join(" ")
}

/// Decode HTML entities: the named set the reference handles plus numeric
/// character references (`&#160;`, `&#xA0;`). Numeric decoding is a superset of
/// the reference's named-only set, so it never changes a reference-covered case
/// but keeps generated markup (numeric `&nbsp;`, `&apos;`) from leaking literal
/// `&#160;` into a cell and breaking, for example, optional-integer parsing.
fn html_unescape(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    let mut rest = text;
    while let Some(amp) = rest.find('&') {
        out.push_str(&rest[..amp]);
        let tail = &rest[amp..];
        if let Some((decoded, consumed)) = decode_entity(tail) {
            out.push(decoded);
            rest = &tail[consumed..];
        } else {
            out.push('&');
            rest = &tail[1..];
        }
    }
    out.push_str(rest);
    out
}

/// Decode a single entity at the start of `s` (which begins with `&`), returning
/// the decoded char and the number of bytes consumed, or `None` if `s` does not
/// start with a recognized entity.
fn decode_entity(s: &str) -> Option<(char, usize)> {
    for (entity, decoded) in [
        ("&amp;", '&'),
        ("&lt;", '<'),
        ("&gt;", '>'),
        ("&quot;", '"'),
        ("&#39;", '\''),
        ("&apos;", '\''),
        ("&nbsp;", ' '),
    ] {
        if s.starts_with(entity) {
            return Some((decoded, entity.len()));
        }
    }

    // Numeric character reference: &#DDD; or &#xHHH;
    let body = s.strip_prefix("&#")?;
    let semi = body.find(';')?;
    let (digits, radix) = match body.strip_prefix(['x', 'X']) {
        Some(hex) => (&hex[..semi - 1], 16),
        None => (&body[..semi], 10),
    };
    if digits.is_empty() {
        return None;
    }
    let code = u32::from_str_radix(digits, radix).ok()?;
    let decoded = char::from_u32(code)?;
    Some((decoded, "&#".len() + semi + 1))
}

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

    #[test]
    fn prn_parses_padded_and_multi_digit() {
        assert_eq!(prn_from_object_name(Some("GPS BIIF-8  (PRN 03)")), Some(3));
        assert_eq!(prn_from_object_name(Some("GPS BIII-10 (PRN 13)")), Some(13));
        assert_eq!(prn_from_object_name(Some("X (PRN 003)")), Some(3));
    }

    #[test]
    fn prn_search_skips_unparseable_earlier_occurrence() {
        // A leading "(PRN ...)" that does not parse must not block a later valid
        // one, matching the reference regex's search semantics.
        assert_eq!(
            prn_from_object_name(Some("GPS (PRN X) BIIF (PRN 07)")),
            Some(7)
        );
        assert_eq!(prn_from_object_name(Some("GPS WITHOUT PRN")), None);
        assert_eq!(prn_from_object_name(Some("(PRN 000)")), None);
    }

    #[test]
    fn html_unescape_decodes_named_and_numeric_entities() {
        assert_eq!(html_unescape("a &amp; b"), "a & b");
        assert_eq!(html_unescape("&#39;x&#39;"), "'x'");
        // Numeric references for NBSP (decimal and hex) decode to spaces.
        assert_eq!(html_unescape("&#160;"), "\u{a0}");
        assert_eq!(html_unescape("&#xA0;"), "\u{a0}");
        // An unrecognized "&" is left literal rather than dropped.
        assert_eq!(html_unescape("AT&T"), "AT&T");
    }

    #[test]
    fn optional_int_treats_numeric_nbsp_cell_as_blank() {
        // A cell whose only content is a numeric NBSP cleans to whitespace and
        // collapses to "", so it is absent rather than a parse error.
        let row = r#"<td class="views-field-field-gps-svn">&#160;</td>"#;
        assert_eq!(navcen_optional_int(row, "gps-svn"), Ok(None));
    }
}