csl-legacy 0.78.0

/*
SPDX-License-Identifier: MIT OR Apache-2.0
SPDX-FileCopyrightText: © 2023-2026 Bruce D'Arcus and Citum contributors
*/

//! CSL-JSON reference model.
//!
//! This module provides a CSL-JSON compatible reference model for parsing
//! existing bibliographic data in the legacy CSL-JSON format.
//!
//! Note: This is a legacy format with known limitations. The preferred format
//! for new data is the Citum InputReference model in citum_schema.

use serde::{Deserialize, Deserializer, Serialize};
use std::collections::{HashMap, HashSet};

/// Canonical CSL 1.0.2 item-type vocabulary.
///
/// Source: `schemas/styles/csl-types.rnc` at the tagged `v1.0.2` release of
/// the CSL schema repository
/// (<https://github.com/citation-style-language/schema/blob/v1.0.2/schemas/styles/csl-types.rnc>,
/// verified identical against `master` at time of writing). This is the
/// complete, closed set of `"type"` strings a conformant CSL 1.0.2 producer
/// may emit. It is the source of truth consumed by:
///
/// - the CSL-type routing table in
///   `citum_schema_data::reference::conversion` (every entry here must
///   have an explicit routing arm — see
///   `docs/specs/CSL_TYPE_CONVERSION_CONTRACT.md`);
/// - [`Reference::parse_note_field_hacks`], which validates `note:`-field
///   `type: X` overrides against this list (plus [`CSL_TYPE_EXTENSIONS`])
///   before applying them.
pub const CSL_TYPES: &[&str] = &[
    "article",
    "article-journal",
    "article-magazine",
    "article-newspaper",
    "bill",
    "book",
    "broadcast",
    "chapter",
    "classic",
    "collection",
    "dataset",
    "document",
    "entry",
    "entry-dictionary",
    "entry-encyclopedia",
    "event",
    "figure",
    "graphic",
    "hearing",
    "interview",
    "legal_case",
    "legislation",
    "manuscript",
    "map",
    "motion_picture",
    "musical_score",
    "pamphlet",
    "paper-conference",
    "patent",
    "performance",
    "periodical",
    "personal_communication",
    "post",
    "post-weblog",
    "regulation",
    "report",
    "review",
    "review-book",
    "software",
    "song",
    "speech",
    "standard",
    "thesis",
    "treaty",
    "webpage",
];

/// Non-CSL-1.0.2 `"type"` strings the legacy conversion layer also treats
/// as first-class inputs.
///
/// These spellings show up in real-world CSL-JSON exports (Zotero,
/// BibTeX/BibLaTeX round-trips, etc.) but are not part of the official CSL
/// 1.0.2 vocabulary in [`CSL_TYPES`]. They are accepted because
/// `citum_schema_data::reference::conversion`'s routing table has
/// historically routed them like a known type, not because a producer
/// following the CSL 1.0.2 spec would ever emit them. Listed here so
/// [`Reference::parse_note_field_hacks`] recognizes them too, and so the
/// conversion-layer contract test can distinguish "known extension" from
/// "unrecognized/typo".
pub const CSL_TYPE_EXTENSIONS: &[&str] = &[
    // Zotero/BibLaTeX "manual" export; routed like a technical manual.
    "manual",
    // Historical alias accepted alongside `speech`/`event`; routed to the
    // event converter.
    "presentation",
    // Hyphenated respelling of the CSL 1.0.2 `personal_communication` type.
    "personal-communication",
    // Hyphenated respelling of the CSL 1.0.2 `legal_case` type.
    "legal-case",
    // Not part of CSL 1.0.2 (`legislation` is the closed-vocabulary
    // equivalent); routed to the same statute converter as `legislation`.
    "statute",
];

/// A bibliographic reference item.
/// This is compatible with CSL-JSON format.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct Reference {
    /// Unique identifier for the reference.
    pub id: String,
    /// The type of reference (book, article-journal, etc.)
    #[serde(rename = "type")]
    pub ref_type: String,
    /// Authors
    #[serde(skip_serializing_if = "Option::is_none")]
    pub author: Option<Vec<Name>>,
    /// Editors
    #[serde(skip_serializing_if = "Option::is_none")]
    pub editor: Option<Vec<Name>>,
    /// Translators
    #[serde(skip_serializing_if = "Option::is_none")]
    pub translator: Option<Vec<Name>>,
    /// Recipient
    #[serde(skip_serializing_if = "Option::is_none")]
    pub recipient: Option<Vec<Name>>,
    /// Director
    #[serde(skip_serializing_if = "Option::is_none")]
    pub director: Option<Vec<Name>>,
    /// Generic contributors, such as cast members or performers.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub contributor: Option<Vec<Name>>,
    /// Interviewer
    #[serde(skip_serializing_if = "Option::is_none")]
    pub interviewer: Option<Vec<Name>>,
    /// Primary title
    #[serde(skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    /// Container title (journal, book, etc.)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub container_title: Option<String>,
    /// Collection title
    #[serde(skip_serializing_if = "Option::is_none")]
    pub collection_title: Option<String>,
    /// Collection number (series number)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub collection_number: Option<StringOrNumber>,
    /// Issued date
    #[serde(skip_serializing_if = "Option::is_none")]
    pub issued: Option<DateVariable>,
    /// Accessed date
    #[serde(skip_serializing_if = "Option::is_none")]
    pub accessed: Option<DateVariable>,
    /// Volume
    #[serde(skip_serializing_if = "Option::is_none")]
    pub volume: Option<StringOrNumber>,
    /// Issue
    #[serde(skip_serializing_if = "Option::is_none")]
    pub issue: Option<StringOrNumber>,
    /// Page or page range
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page: Option<String>,
    /// Edition
    #[serde(skip_serializing_if = "Option::is_none")]
    pub edition: Option<StringOrNumber>,
    /// DOI
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(rename = "DOI")]
    pub doi: Option<String>,
    /// URL
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(rename = "URL")]
    pub url: Option<String>,
    /// ISBN
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(rename = "ISBN")]
    pub isbn: Option<String>,
    /// ISSN
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(rename = "ISSN")]
    pub issn: Option<String>,
    /// Publisher
    #[serde(skip_serializing_if = "Option::is_none")]
    pub publisher: Option<String>,
    /// Publisher place
    #[serde(skip_serializing_if = "Option::is_none")]
    pub publisher_place: Option<String>,
    /// Authority
    #[serde(skip_serializing_if = "Option::is_none")]
    pub authority: Option<String>,
    /// Section
    #[serde(skip_serializing_if = "Option::is_none")]
    pub section: Option<String>,
    /// Event
    #[serde(skip_serializing_if = "Option::is_none")]
    pub event: Option<String>,
    /// Medium
    #[serde(skip_serializing_if = "Option::is_none")]
    pub medium: Option<String>,
    /// Physical dimensions, runtime, or other extent information.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub dimensions: Option<String>,
    /// Archive or repository name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub archive: Option<String>,
    /// Archive shelfmark, repository location, or call number.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(alias = "archive_location")]
    pub archive_location: Option<String>,
    /// Number
    #[serde(skip_serializing_if = "Option::is_none")]
    pub number: Option<String>,
    /// Chapter or session identifier used by some legal and legislative sources.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub chapter_number: Option<String>,
    /// Printing number (printing run identifier).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub printing_number: Option<String>,
    /// Genre
    #[serde(skip_serializing_if = "Option::is_none")]
    pub genre: Option<String>,
    /// Language (BCP 47)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub language: Option<String>,
    /// Original title in the source language.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub original_title: Option<String>,
    /// Abstract
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(rename = "abstract")]
    pub abstract_text: Option<String>,
    /// Note
    #[serde(skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// Number of pages
    #[serde(skip_serializing_if = "Option::is_none")]
    pub number_of_pages: Option<StringOrNumber>,
    /// Number of volumes
    #[serde(skip_serializing_if = "Option::is_none")]
    pub number_of_volumes: Option<StringOrNumber>,
    /// Additional fields not explicitly modeled
    #[serde(flatten)]
    pub extra: HashMap<String, serde_json::Value>,
}

/// Machine-readable diagnostic produced while parsing Zotero Extra lines.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "code", rename_all = "kebab-case")]
pub enum NoteFieldDiagnostic {
    /// Conflicting values were supplied for one supplementary identifier.
    ConflictingSupplementaryIdentifier {
        /// CSL-JSON item identifier carrying the conflicting values.
        item_id: String,
        /// Canonical Citum supplementary-identifier name.
        identifier: String,
        /// Value retained after applying source precedence.
        kept: String,
        /// Distinct lower-precedence values that were ignored.
        ignored: Vec<String>,
    },
}

/// A name (person or organization).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct Name {
    /// Family name for a structured personal name.
    pub family: Option<String>,
    /// Given name for a structured personal name.
    pub given: Option<String>,
    /// Literal name (for organizations or single-field names)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub literal: Option<String>,
    /// Name suffix (Jr., III, etc.)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub suffix: Option<String>,
    /// Dropping particle (de, van, etc. that sorts with given name)
    #[serde(
        rename = "dropping-particle",
        alias = "dropping_particle",
        skip_serializing_if = "Option::is_none"
    )]
    pub dropping_particle: Option<String>,
    /// Non-dropping particle (de, van, etc. that sorts with family name)
    #[serde(
        rename = "non-dropping-particle",
        alias = "non_dropping_particle",
        skip_serializing_if = "Option::is_none"
    )]
    pub non_dropping_particle: Option<String>,
}

impl Name {
    /// Create a new structured name.
    #[must_use]
    pub fn new(family: &str, given: &str) -> Self {
        Self {
            family: Some(family.to_string()),
            given: Some(given.to_string()),
            ..Default::default()
        }
    }

    /// Create a literal name (organization or single-field).
    #[must_use]
    pub fn literal(name: &str) -> Self {
        Self {
            literal: Some(name.to_string()),
            ..Default::default()
        }
    }

    /// Get the family name or literal.
    #[must_use]
    pub fn family_or_literal(&self) -> &str {
        self.family
            .as_deref()
            .or(self.literal.as_deref())
            .unwrap_or("")
    }
}

/// A date variable (CSL-JSON format).
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
#[serde(rename_all = "kebab-case")]
pub struct DateVariable {
    /// Date parts: [[year, month, day], [`end_year`, `end_month`, `end_day`]]
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "deserialize_date_parts_opt"
    )]
    pub date_parts: Option<Vec<Vec<i32>>>,
    /// Literal date string
    #[serde(skip_serializing_if = "Option::is_none")]
    pub literal: Option<String>,
    /// Raw date string (for parsing)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub raw: Option<String>,
    /// Season (1-4)
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        deserialize_with = "deserialize_season_opt"
    )]
    pub season: Option<i32>,
    /// Circa (approximate date)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub circa: Option<bool>,
}

#[derive(Debug, Deserialize)]
#[serde(untagged)]
enum IntOrString {
    Int(i32),
    String(String),
}

fn deserialize_date_parts_opt<'de, D>(deserializer: D) -> Result<Option<Vec<Vec<i32>>>, D::Error>
where
    D: Deserializer<'de>,
{
    let raw = Option::<Vec<Vec<IntOrString>>>::deserialize(deserializer)?;
    raw.map(|rows| {
        rows.into_iter()
            .map(|row| {
                row.into_iter()
                    .map(|value| match value {
                        IntOrString::Int(n) => Ok(n),
                        IntOrString::String(text) => text.parse::<i32>().map_err(|_| {
                            serde::de::Error::custom(format!(
                                "invalid date-parts component {:?}: expected integer or integer-like string",
                                text
                            ))
                        }),
                    })
                    .collect::<Result<Vec<_>, D::Error>>()
            })
            .collect::<Result<Vec<_>, D::Error>>()
    })
    .transpose()
}

fn deserialize_season_opt<'de, D>(deserializer: D) -> Result<Option<i32>, D::Error>
where
    D: Deserializer<'de>,
{
    let raw = Option::<IntOrString>::deserialize(deserializer)?;
    raw.map(|value| match value {
        IntOrString::Int(n) => Ok(n),
        IntOrString::String(text) => {
            let normalized = text.trim().to_ascii_lowercase();
            match normalized.as_str() {
                "spring" => Ok(1),
                "summer" => Ok(2),
                "fall" | "autumn" => Ok(3),
                "winter" => Ok(4),
                _ => text.parse::<i32>().map_err(|_| {
                    serde::de::Error::custom(format!(
                        "invalid season {:?}: expected integer, integer-like string, or named season",
                        text
                    ))
                }),
            }
        }
    })
    .transpose()
}

impl DateVariable {
    /// Create a date with year only.
    #[must_use]
    pub fn year(year: i32) -> Self {
        Self {
            date_parts: Some(vec![vec![year]]),
            ..Default::default()
        }
    }

    /// Create a date with year and month.
    #[must_use]
    pub fn year_month(year: i32, month: i32) -> Self {
        Self {
            date_parts: Some(vec![vec![year, month]]),
            ..Default::default()
        }
    }

    /// Create a full date.
    #[must_use]
    pub fn full(year: i32, month: i32, day: i32) -> Self {
        Self {
            date_parts: Some(vec![vec![year, month, day]]),
            ..Default::default()
        }
    }

    /// Get the year from the first date part.
    #[must_use]
    pub fn year_value(&self) -> Option<i32> {
        self.date_parts
            .as_ref()
            .and_then(|parts| parts.first())
            .and_then(|date| date.first())
            .copied()
    }

    /// Get the month from the first date part.
    #[must_use]
    pub fn month_value(&self) -> Option<i32> {
        self.date_parts
            .as_ref()
            .and_then(|parts| parts.first())
            .and_then(|date| date.get(1))
            .copied()
    }

    /// Get the day from the first date part.
    #[must_use]
    pub fn day_value(&self) -> Option<i32> {
        self.date_parts
            .as_ref()
            .and_then(|parts| parts.first())
            .and_then(|date| date.get(2))
            .copied()
    }
}

/// A value that can be either a string or number.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(untagged)]
pub enum StringOrNumber {
    /// A string value preserved as written in the source data.
    String(String),
    /// A numeric value preserved as an integer.
    Number(i64),
}

impl std::fmt::Display for StringOrNumber {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::String(s) => write!(f, "{s}"),
            Self::Number(n) => write!(f, "{n}"),
        }
    }
}

impl Reference {
    /// Parse structured CSL variables from the note field.
    ///
    /// Extracts key-value pairs from the Zotero "Extra" field (stored in `note`),
    /// following citeproc-js's `parseNoteFieldHacks` behavior. Lines contain
    /// `key: value` patterns where the key is a CSL variable name (e.g., `DOI`,
    /// `publisher`, `issued`). Type overrides are always applied; other fields
    /// only set if currently None. Only recognized keys are consumed; unrecognized
    /// `key: value` lines are left in `note` unchanged.
    ///
    /// # Algorithm
    /// 1. Skip if note is None or empty
    /// 2. Split by newline
    /// 3. For each line, parse `key: value` where key is alphabetic
    /// 4. Stop at first non-matching line (unless it's the first line)
    /// 5. Extract type, dates, names, and strings to appropriate fields
    /// 6. Rebuild note with only unrecognized/unparsed lines
    pub fn parse_note_field_hacks(&mut self) {
        let _ = self.parse_note_field_hacks_with_diagnostics();
    }

    /// Parse structured CSL variables and return any recoverable conflicts.
    ///
    /// In addition to ordinary citeproc-js note-field variables, this accepts
    /// the CSL-M `CSTR` and Zotero Better BibTeX `tex.cstr` spellings. Both are
    /// normalized into the canonical `CSTR` entry in [`Reference::extra`]. A
    /// direct `CSTR` value takes precedence over `tex.cstr`; identical values
    /// are accepted without a diagnostic.
    #[must_use]
    pub fn parse_note_field_hacks_with_diagnostics(&mut self) -> Vec<NoteFieldDiagnostic> {
        let (mut direct_cstr, mut tex_cstr) = take_cstr_extra_values(&mut self.extra);
        let note = match &self.note {
            Some(n) if !n.is_empty() => n.clone(),
            _ => {
                return finish_cstr_extraction(self, direct_cstr, tex_cstr);
            }
        };

        let lines: Vec<&str> = note.lines().collect();
        if lines.is_empty() {
            return finish_cstr_extraction(self, direct_cstr, tex_cstr);
        }

        let mut parsed_indices = HashSet::new();

        for (idx, line) in lines.iter().enumerate() {
            let trimmed = line.trim();

            // Skip blank lines
            if trimmed.is_empty() {
                continue;
            }

            if let Some((source, value)) = parse_cstr_key_value(trimmed) {
                if !value.is_empty() {
                    match source {
                        CstrSource::Direct => direct_cstr.push(value.to_string()),
                        CstrSource::Tex => tex_cstr.push(value.to_string()),
                    }
                }
                parsed_indices.insert(idx);
                continue;
            }

            // Parse key: value pattern; skip non-matching lines so recognized
            // pairs later in the note (after free-text) are still extracted.
            let Some((key, value)) = parse_key_value(trimmed) else {
                continue;
            };

            // Process the key-value pair; only mark as parsed when the key is recognized
            if key.eq_ignore_ascii_case("type") {
                // Only apply the override when `value` is a recognized CSL
                // type (1.0.2 or a known extension). An unrecognized value
                // (typo, or a vocabulary the current release doesn't know)
                // is left alone: the top-level `type` wins, and the line
                // stays in the rebuilt `note` rather than being silently
                // consumed. See docs/specs/CSL_TYPE_CONVERSION_CONTRACT.md.
                if CSL_TYPES.contains(&value) || CSL_TYPE_EXTENSIONS.contains(&value) {
                    self.ref_type = value.to_string();
                    parsed_indices.insert(idx);
                }
            } else if is_date_variable(key) {
                handle_date_variable(self, key, value);
                parsed_indices.insert(idx);
            } else if is_name_variable(key) {
                handle_name_variable(self, key, value);
                parsed_indices.insert(idx);
            } else if is_string_variable(key) {
                handle_string_variable(self, key, value);
                parsed_indices.insert(idx);
            }
        }

        // Rebuild note from unparsed lines
        let remaining_lines: Vec<&str> = lines
            .iter()
            .enumerate()
            .filter(|(idx, _)| !parsed_indices.contains(idx))
            .map(|(_, line)| *line)
            .collect();

        if remaining_lines.is_empty() {
            self.note = None;
        } else {
            self.note = Some(remaining_lines.join("\n"));
        }

        finish_cstr_extraction(self, direct_cstr, tex_cstr)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum CstrSource {
    Direct,
    Tex,
}

fn parse_cstr_key_value(line: &str) -> Option<(CstrSource, &str)> {
    let (key, value) = line.split_once(':')?;
    let source = if key.eq_ignore_ascii_case("CSTR") {
        CstrSource::Direct
    } else if key.eq_ignore_ascii_case("tex.cstr") {
        CstrSource::Tex
    } else {
        return None;
    };
    Some((source, value.trim()))
}

fn take_cstr_extra_values(
    extra: &mut HashMap<String, serde_json::Value>,
) -> (Vec<String>, Vec<String>) {
    let mut keys = extra
        .keys()
        .filter(|key| key.eq_ignore_ascii_case("CSTR") || key.eq_ignore_ascii_case("tex.cstr"))
        .cloned()
        .collect::<Vec<_>>();
    keys.sort_by_key(|key| {
        let precedence = if key == "CSTR" {
            0
        } else if key.eq_ignore_ascii_case("CSTR") {
            1
        } else {
            2
        };
        (precedence, key.clone())
    });

    let mut direct = Vec::new();
    let mut tex = Vec::new();
    for key in keys {
        let Some(value) = extra.remove(&key).and_then(|value| match value {
            serde_json::Value::String(value) => Some(value),
            _ => None,
        }) else {
            continue;
        };
        if value.trim().is_empty() {
            continue;
        }
        if key.eq_ignore_ascii_case("CSTR") {
            direct.push(value.trim().to_string());
        } else {
            tex.push(value.trim().to_string());
        }
    }
    (direct, tex)
}

fn finish_cstr_extraction(
    reference: &mut Reference,
    direct: Vec<String>,
    tex: Vec<String>,
) -> Vec<NoteFieldDiagnostic> {
    let Some(kept) = direct.first().or_else(|| tex.first()).cloned() else {
        return Vec::new();
    };
    reference
        .extra
        .insert("CSTR".to_string(), serde_json::Value::String(kept.clone()));

    let mut ignored = direct
        .iter()
        .chain(&tex)
        .filter(|value| *value != &kept)
        .cloned()
        .collect::<Vec<_>>();
    ignored.sort();
    ignored.dedup();
    if ignored.is_empty() {
        Vec::new()
    } else {
        vec![NoteFieldDiagnostic::ConflictingSupplementaryIdentifier {
            item_id: reference.id.clone(),
            identifier: "cstr".to_string(),
            kept,
            ignored,
        }]
    }
}

/// Parse a line into `(key, value)` if it matches `key: value` pattern.
/// Key must start with an ASCII letter and contain only word chars, hyphens,
/// underscores. Uppercase keys (e.g. `DOI`, `ISBN`, `URL`) are preserved
/// as-is so they can be matched by their canonical uppercase names downstream.
fn parse_key_value(line: &str) -> Option<(&str, &str)> {
    if line.is_empty() {
        return None;
    }

    let colon_pos = line.find(':')?;
    #[allow(
        clippy::string_slice,
        reason = "colon_pos is found via find(':'), which is a valid 1-byte ASCII boundary"
    )]
    let key = &line[..colon_pos];

    // Validate key: must start with an ASCII letter (upper or lower)
    let first_char = key.chars().next()?;
    if !first_char.is_ascii_alphabetic() {
        return None;
    }

    // Rest of key: word chars, hyphens, underscores
    if !key
        .chars()
        .skip(1)
        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
    {
        return None;
    }

    #[allow(
        clippy::string_slice,
        reason = "colon_pos + 1 is a valid boundary after ':' (1-byte ASCII)"
    )]
    let value = line[colon_pos + 1..].trim();
    Some((key, value))
}

/// Check if key is a date variable.
fn is_date_variable(key: &str) -> bool {
    matches!(
        key,
        "issued" | "event-date" | "original-date" | "available-date" | "accessed" | "submitted"
    )
}

/// Handle date variable extraction.
fn handle_date_variable(ref_obj: &mut Reference, key: &str, value: &str) {
    let date = parse_date_variable(value);

    match key {
        // A structured note-field interval is an explicit Zotero Extra
        // override. Prefer it over a single issued date, which can be a
        // lossy CSL export (for example a range end encoded as `season`).
        "issued" if ref_obj.issued.is_none() || is_date_range(&date) => {
            ref_obj.issued = Some(date);
        }
        // A raw (unparsed) override coexisting with an already-structured
        // issued date is a GB/T-style publication-year substitute
        // annotation layered on top of the structured date CSL already
        // exports (e.g. a printing year "1995印刷" or an estimated year
        // "1936~", GB/T 7714 §7.5.4.3). Preserve the raw text so downstream
        // conversion can interpret the substitute form; the structured
        // `issued` value is left untouched.
        "issued" if date.raw.is_some() => {
            if let Some(raw) = date.raw {
                ref_obj.extra.insert(
                    "issued-note-literal".to_string(),
                    serde_json::Value::String(raw),
                );
            }
        }
        "accessed" if ref_obj.accessed.is_none() => {
            ref_obj.accessed = Some(date);
        }
        "event-date" | "original-date" | "available-date" | "submitted" => {
            // Store in extra as JSON
            ref_obj.extra.insert(
                key.to_string(),
                serde_json::Value::String(value.to_string()),
            );
        }
        _ => {}
    }
}

fn is_date_range(date: &DateVariable) -> bool {
    date.date_parts
        .as_ref()
        .is_some_and(|parts| parts.len() == 2)
}

/// Parse a date string into DateVariable.
/// Supports YYYY, YYYY-MM, YYYY-MM-DD, and ranges like YYYY/YYYY or YYYY–YYYY.
fn parse_date_variable(value: &str) -> DateVariable {
    let trimmed = value.trim();

    // Check for range: YYYY/YYYY or YYYY–YYYY
    let (sep_pos, sep_len) = if let Some(pos) = trimmed.find('/') {
        (Some(pos), 1)
    } else if let Some(pos) = trimmed.find('–') {
        (Some(pos), '–'.len_utf8())
    } else {
        (None, 0)
    };

    if let Some(pos) = sep_pos {
        #[allow(
            clippy::string_slice,
            reason = "pos is a valid byte boundary found via .find()"
        )]
        let start_str = trimmed[..pos].trim();
        #[allow(
            clippy::string_slice,
            reason = "pos + sep_len is a valid byte boundary for '/' or '–'"
        )]
        let end_str = trimmed[pos + sep_len..].trim();

        if let (Some(start_parts), Some(end_parts)) =
            (parse_date_parts(start_str), parse_date_parts(end_str))
        {
            return DateVariable {
                date_parts: Some(vec![start_parts, end_parts]),
                ..Default::default()
            };
        }
    }

    // Try to parse as YYYY-MM-DD, YYYY-MM, or YYYY
    if let Some(parts) = parse_date_parts(trimmed) {
        DateVariable {
            date_parts: Some(vec![parts]),
            ..Default::default()
        }
    } else {
        // Store as raw for downstream parsing
        DateVariable {
            raw: Some(trimmed.to_string()),
            ..Default::default()
        }
    }
}

/// Parse date parts from a string like "2020", "2020-03", or "2020-03-15".
fn parse_date_parts(s: &str) -> Option<Vec<i32>> {
    let parts: Vec<&str> = s.split('-').collect();
    if parts.is_empty() || parts.len() > 3 {
        return None;
    }

    let mut result = Vec::new();
    for part in parts {
        result.push(part.trim().parse::<i32>().ok()?);
    }

    Some(result)
}

/// Check if key is a name variable.
fn is_name_variable(key: &str) -> bool {
    matches!(
        key,
        "editor"
            | "translator"
            | "interviewer"
            | "director"
            | "contributor"
            | "recipient"
            | "author"
            | "collection-editor"
            | "container-author"
            | "editorial-director"
            | "illustrator"
            | "original-author"
            | "reviewed-author"
            | "composer"
            | "narrator"
            | "performer"
            | "producer"
            | "script-writer"
            | "compiler"
    )
}

/// Handle name variable extraction.
fn handle_name_variable(ref_obj: &mut Reference, key: &str, value: &str) {
    let name = parse_name_variable(value);

    match key {
        "author" if ref_obj.author.is_none() => {
            ref_obj.author = Some(vec![name]);
        }
        "editor" if ref_obj.editor.is_none() => {
            ref_obj.editor = Some(vec![name]);
        }
        "translator" if ref_obj.translator.is_none() => {
            ref_obj.translator = Some(vec![name]);
        }
        "interviewer" if ref_obj.interviewer.is_none() => {
            ref_obj.interviewer = Some(vec![name]);
        }
        "director" if ref_obj.director.is_none() => {
            ref_obj.director = Some(vec![name]);
        }
        "contributor" if ref_obj.contributor.is_none() => {
            ref_obj.contributor = Some(vec![name]);
        }
        "recipient" if ref_obj.recipient.is_none() => {
            ref_obj.recipient = Some(vec![name]);
        }
        // Fields not on Reference: store in extra as JSON
        "collection-editor" | "container-author" | "editorial-director" | "illustrator"
        | "original-author" | "reviewed-author" | "composer" | "narrator" | "performer"
        | "producer" | "script-writer" | "compiler" => {
            ref_obj.extra.insert(
                key.to_string(),
                serde_json::to_value(vec![name]).unwrap_or(serde_json::Value::Null),
            );
        }
        _ => {}
    }
}

/// Parse a name from a string.
/// Format: "family || given" for structured, otherwise literal.
fn parse_name_variable(value: &str) -> Name {
    let trimmed = value.trim();

    if let Some(sep_pos) = trimmed.find("||") {
        #[allow(
            clippy::string_slice,
            reason = "sep_pos is a valid byte boundary for '||'"
        )]
        let family = trimmed[..sep_pos].trim().to_string();
        #[allow(
            clippy::string_slice,
            reason = "sep_pos + 2 is a valid boundary after '||' (2-byte ASCII)"
        )]
        let given = trimmed[sep_pos + 2..].trim().to_string();

        Name {
            family: Some(family),
            given: Some(given),
            ..Default::default()
        }
    } else {
        Name {
            literal: Some(trimmed.to_string()),
            ..Default::default()
        }
    }
}

/// Check if key is a recognized string variable.
fn is_string_variable(key: &str) -> bool {
    matches!(
        key,
        "container-title"
            | "collection-title"
            | "volume-title"
            | "event-title"
            | "event-place"
            | "event-location"
            | "publisher"
            | "publisher-place"
            | "archive"
            | "archive-place"
            | "archive-location"
            | "archive-collection"
            | "archive_collection"
            | "genre"
            | "medium"
            | "dimensions"
            | "version"
            | "section"
            | "volume"
            | "issue"
            | "page"
            | "edition"
            | "number"
            | "number-of-volumes"
            | "number-of-pages"
            | "chapter-number"
            | "part-number"
            | "part-title"
            | "supplement-number"
            | "references"
            | "source"
            | "status"
            | "DOI"
            | "ISBN"
            | "ISSN"
            | "URL"
            | "original-title"
            | "reviewed-title"
            | "reviewed-genre"
            | "call-number"
            | "abstract"
            | "language"
            | "jurisdiction"
            | "authority"
            | "citation-number"
            | "citation-label"
            | "annote"
            | "keyword"
            | "title-short"
            | "collection-number"
    )
}

/// Handle string variable extraction.
#[allow(
    clippy::too_many_lines,
    clippy::cognitive_complexity,
    reason = "match statement for all CSL string variable mappings"
)]
fn handle_string_variable(ref_obj: &mut Reference, key: &str, value: &str) {
    let trimmed = value.trim();

    match key {
        "container-title" if ref_obj.container_title.is_none() => {
            ref_obj.container_title = Some(trimmed.to_string());
        }
        "collection-title" if ref_obj.collection_title.is_none() => {
            ref_obj.collection_title = Some(trimmed.to_string());
        }
        "collection-number" if ref_obj.collection_number.is_none() => {
            ref_obj.collection_number = Some(StringOrNumber::String(trimmed.to_string()));
        }
        "part-title" => {
            ref_obj.extra.insert(
                key.to_string(),
                serde_json::Value::String(trimmed.to_string()),
            );
        }
        "publisher-place" if ref_obj.publisher_place.is_none() => {
            ref_obj.publisher_place = Some(trimmed.to_string());
        }
        "publisher" if ref_obj.publisher.is_none() => {
            ref_obj.publisher = Some(trimmed.to_string());
        }
        "archive-location" if ref_obj.archive_location.is_none() => {
            ref_obj.archive_location = Some(trimmed.to_string());
        }
        // Distinct from `archive-location` (the shelfmark/call number within
        // the archive): this is the archive's own geographic place (收藏地).
        // Stored in `extra` rather than a dedicated field so downstream
        // consumers (`archive_info_from_legacy_flat`) can assemble it into
        // `ArchiveInfo::place` alongside the archive name.
        "archive-place" => {
            ref_obj
                .extra
                .entry(key.to_string())
                .or_insert_with(|| serde_json::Value::String(trimmed.to_string()));
        }
        "archive" if ref_obj.archive.is_none() => {
            ref_obj.archive = Some(trimmed.to_string());
        }
        "volume" if ref_obj.volume.is_none() => {
            ref_obj.volume = Some(StringOrNumber::String(trimmed.to_string()));
        }
        "issue" if ref_obj.issue.is_none() => {
            ref_obj.issue = Some(StringOrNumber::String(trimmed.to_string()));
        }
        "page" if ref_obj.page.is_none() => {
            ref_obj.page = Some(trimmed.to_string());
        }
        "edition" if ref_obj.edition.is_none() => {
            ref_obj.edition = Some(StringOrNumber::String(trimmed.to_string()));
        }
        "number-of-pages" if ref_obj.number_of_pages.is_none() => {
            ref_obj.number_of_pages = Some(StringOrNumber::String(trimmed.to_string()));
        }
        "number-of-volumes" if ref_obj.number_of_volumes.is_none() => {
            ref_obj.number_of_volumes = Some(StringOrNumber::String(trimmed.to_string()));
        }
        "chapter-number" if ref_obj.chapter_number.is_none() => {
            ref_obj.chapter_number = Some(trimmed.to_string());
        }
        "genre" if ref_obj.genre.is_none() => {
            ref_obj.genre = Some(trimmed.to_string());
        }
        "medium" if ref_obj.medium.is_none() => {
            ref_obj.medium = Some(trimmed.to_string());
        }
        "language" if ref_obj.language.is_none() => {
            ref_obj.language = Some(trimmed.to_string());
        }
        "original-title" if ref_obj.original_title.is_none() => {
            ref_obj.original_title = Some(trimmed.to_string());
        }
        "abstract" if ref_obj.abstract_text.is_none() => {
            ref_obj.abstract_text = Some(trimmed.to_string());
        }
        "DOI" if ref_obj.doi.is_none() => {
            ref_obj.doi = Some(trimmed.to_string());
        }
        "ISBN" if ref_obj.isbn.is_none() => {
            ref_obj.isbn = Some(trimmed.to_string());
        }
        "ISSN" if ref_obj.issn.is_none() => {
            ref_obj.issn = Some(trimmed.to_string());
        }
        "URL" if ref_obj.url.is_none() => {
            ref_obj.url = Some(trimmed.to_string());
        }
        "authority" if ref_obj.authority.is_none() => {
            ref_obj.authority = Some(trimmed.to_string());
        }
        "section" if ref_obj.section.is_none() => {
            ref_obj.section = Some(trimmed.to_string());
        }
        "number" if ref_obj.number.is_none() => {
            ref_obj.number = Some(trimmed.to_string());
        }
        // Fields not on Reference: store in extra as JSON
        "volume-title" | "event-title" | "event-place" | "event-location"
        | "archive-collection" | "archive_collection" | "dimensions" | "part-number"
        | "supplement-number" | "references" | "source" | "status" | "reviewed-title"
        | "reviewed-genre" | "call-number" | "jurisdiction" | "citation-number"
        | "citation-label" | "annote" | "keyword" | "title-short" | "version" => {
            let key_to_store = match key {
                "archive_collection" => "archive-collection",
                "event-location" => "event-place",
                _ => key,
            };
            ref_obj.extra.insert(
                key_to_store.to_string(),
                serde_json::Value::String(trimmed.to_string()),
            );
        }
        _ => {}
    }
}

/// A bibliography is a collection of references keyed by ID.
/// Uses `IndexMap` to preserve insertion order for numeric citation styles.
pub type Bibliography = indexmap::IndexMap<String, Reference>;

#[cfg(test)]
#[allow(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::panic,
    clippy::indexing_slicing,
    clippy::todo,
    clippy::unimplemented,
    clippy::unreachable,
    clippy::get_unwrap,
    reason = "Panicking is acceptable and often desired in tests."
)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_csl_json() {
        let json = r#"{
            "id": "kuhn1962",
            "type": "book",
            "author": [{"family": "Kuhn", "given": "Thomas S."}],
            "title": "The Structure of Scientific Revolutions",
            "issued": {"date-parts": [[1962]]},
            "publisher": "University of Chicago Press",
            "publisher-place": "Chicago"
        }"#;

        let reference: Reference = serde_json::from_str(json).unwrap();
        assert_eq!(reference.id, "kuhn1962");
        assert_eq!(reference.ref_type, "book");
        assert_eq!(
            reference.author.as_ref().unwrap()[0].family,
            Some("Kuhn".to_string())
        );
        assert_eq!(reference.issued.as_ref().unwrap().year_value(), Some(1962));
    }

    #[test]
    fn test_date_variable() {
        let date = DateVariable::year(2023);
        assert_eq!(date.year_value(), Some(2023));
        assert_eq!(date.month_value(), None);

        let date = DateVariable::year_month(2023, 6);
        assert_eq!(date.year_value(), Some(2023));
        assert_eq!(date.month_value(), Some(6));
    }

    #[test]
    fn note_field_issued_range_overrides_lossy_top_level_date() {
        let mut ref_obj = Reference {
            id: "periodical-range".to_string(),
            ref_type: "book".to_string(),
            issued: Some(DateVariable::year(1957)),
            note: Some("issued: 1957/1990".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();

        assert_eq!(
            ref_obj.issued.and_then(|date| date.date_parts),
            Some(vec![vec![1957], vec![1990]])
        );
    }

    #[test]
    fn note_field_issued_literal_preserved_alongside_structured_date() {
        // GB/T 7714 §7.5.4.3 publication-year substitute annotations
        // ("1995印刷" printing year, "1936~" estimated year) don't parse as
        // structured dates and shouldn't overwrite an already-structured
        // `issued`; preserve the raw text for downstream interpretation.
        let mut ref_obj = Reference {
            id: "printing-year".to_string(),
            ref_type: "book".to_string(),
            issued: Some(DateVariable::year(1995)),
            note: Some("issued: 1995印刷".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();

        assert_eq!(
            ref_obj.issued.and_then(|date| date.date_parts),
            Some(vec![vec![1995]])
        );
        assert_eq!(
            ref_obj.extra.get("issued-note-literal"),
            Some(&serde_json::Value::String("1995印刷".to_string()))
        );
    }

    #[test]
    fn test_parse_note_field_type_override() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("type: article-journal".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.ref_type, "article-journal");
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_type_override_recognizes_extension_spelling() {
        // "legal-case" is not itself in CSL_TYPES (the CSL 1.0.2 spelling
        // is "legal_case"), but it is a known CSL_TYPE_EXTENSIONS entry,
        // so the override must still apply.
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "document".to_string(),
            note: Some("type: legal-case".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.ref_type, "legal-case");
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_unrecognized_type_override_is_ignored() {
        // "colection" is a typo (missing an "l") and matches neither
        // CSL_TYPES nor CSL_TYPE_EXTENSIONS. The top-level type must win,
        // and the unrecognized line stays in the rebuilt note instead of
        // being silently consumed. See
        // docs/specs/CSL_TYPE_CONVERSION_CONTRACT.md.
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("type: colection".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.ref_type, "book");
        assert_eq!(ref_obj.note, Some("type: colection".to_string()));
    }

    #[test]
    fn test_parse_note_field_string_variable() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("genre: H.R.\nstatus: enacted".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.genre, Some("H.R.".to_string()));
        assert!(ref_obj.extra.contains_key("status"));
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_date() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("issued: 2020-03-15".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert!(ref_obj.issued.is_some());
        let issued = ref_obj.issued.unwrap();
        assert_eq!(issued.year_value(), Some(2020));
        assert_eq!(issued.month_value(), Some(3));
        assert_eq!(issued.day_value(), Some(15));
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_name() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("editor: Smith || John".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert!(ref_obj.editor.is_some());
        let editors = ref_obj.editor.unwrap();
        assert_eq!(editors.len(), 1);
        assert_eq!(editors[0].family, Some("Smith".to_string()));
        assert_eq!(editors[0].given, Some("John".to_string()));
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_preserves_existing() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            publisher: Some("OldPub".to_string()),
            note: Some("publisher: NewPub".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.publisher, Some("OldPub".to_string()));
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_strips_parsed() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("genre: H.R.\nThis is an extra note line".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.genre, Some("H.R.".to_string()));
        assert_eq!(ref_obj.note, Some("This is an extra note line".to_string()));
    }

    #[test]
    fn test_parse_note_field_empty() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: None,
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_first_line_free_text() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("This is free text on first line\ngenre: H.R.\nstatus: enacted".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.genre, Some("H.R.".to_string()));
        assert!(ref_obj.extra.contains_key("status"));
        assert_eq!(
            ref_obj.note,
            Some("This is free text on first line".to_string())
        );
    }

    #[test]
    fn test_parse_note_field_date_range() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("issued: 2020/2021".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert!(ref_obj.issued.is_some());
        let issued = ref_obj.issued.unwrap();
        assert!(issued.date_parts.is_some());
        let parts = issued.date_parts.unwrap();
        assert_eq!(parts.len(), 2);
        assert_eq!(parts[0][0], 2020);
        assert_eq!(parts[1][0], 2021);
    }

    #[test]
    fn test_parse_note_field_name_literal() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("author: United Nations".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert!(ref_obj.author.is_some());
        let authors = ref_obj.author.unwrap();
        assert_eq!(authors.len(), 1);
        assert_eq!(authors[0].literal, Some("United Nations".to_string()));
    }

    #[test]
    fn test_parse_note_field_uppercase_keys() {
        // DOI, ISBN, ISSN, URL are uppercase in CSL/Zotero Extra
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "article-journal".to_string(),
            note: Some(
                "DOI: 10.1000/xyz123\nISBN: 978-3-16-148410-0\nURL: https://example.org"
                    .to_string(),
            ),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.doi, Some("10.1000/xyz123".to_string()));
        assert_eq!(ref_obj.isbn, Some("978-3-16-148410-0".to_string()));
        assert_eq!(ref_obj.url, Some("https://example.org".to_string()));
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_unknown_key_preserved() {
        // Unrecognized keys must not be silently stripped from note; the loop
        // continues past them (it only stops on lines that cannot be parsed as
        // `key: value` at all), so subsequent recognized keys are still applied.
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("genre: memoir\nfoo: bar\npublisher: MIT Press".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(ref_obj.genre, Some("memoir".to_string()));
        assert_eq!(ref_obj.publisher, Some("MIT Press".to_string()));
        // "foo: bar" is unrecognized — it stays in note unchanged
        assert_eq!(ref_obj.note, Some("foo: bar".to_string()));
    }

    #[test]
    fn test_parse_note_field_archive_location() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "book".to_string(),
            note: Some("archive-location: Box 5, Folder 3".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(
            ref_obj.archive_location,
            Some("Box 5, Folder 3".to_string())
        );
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_part_title_stored_in_extra() {
        let mut ref_obj = Reference {
            id: "test".to_string(),
            ref_type: "webpage".to_string(),
            note: Some("part-title: Part title".to_string()),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();
        assert_eq!(
            ref_obj.extra.get("part-title"),
            Some(&serde_json::Value::String("Part title".to_string()))
        );
        assert_eq!(ref_obj.note, None);
    }

    #[test]
    fn test_parse_note_field_recognized_keys_after_free_text() {
        // A free-text line in the middle must not stop extraction of later key:value pairs.
        let mut ref_obj = Reference {
            id: "broadcast-test".to_string(),
            ref_type: "broadcast".to_string(),
            note: Some(
                "Some free-form description with no colon\ngenre: Documentary\nevent-place: United States".to_string(),
            ),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();

        assert_eq!(ref_obj.genre, Some("Documentary".to_string()));
        assert_eq!(
            ref_obj
                .extra
                .get("event-place")
                .map(|v| v.as_str().unwrap_or("")),
            Some("United States"),
        );
        // The free-text line should remain in the note.
        assert!(
            ref_obj
                .note
                .as_deref()
                .unwrap_or("")
                .contains("Some free-form description")
        );
    }

    #[test]
    fn test_parse_note_field_recognized_keys_after_midnote_free_text() {
        // Recognized pairs both before and after a free-text line are extracted.
        let mut ref_obj = Reference {
            id: "bill-test".to_string(),
            ref_type: "bill".to_string(),
            note: Some(
                "genre: H.R.\nsome unrecognized prose line here\nstatus: enacted".to_string(),
            ),
            ..Default::default()
        };

        ref_obj.parse_note_field_hacks();

        assert_eq!(ref_obj.genre, Some("H.R.".to_string()));
        assert!(ref_obj.extra.contains_key("status"));
        assert_eq!(
            ref_obj.extra.get("status").and_then(|v| v.as_str()),
            Some("enacted"),
        );
        assert!(
            ref_obj
                .note
                .as_deref()
                .unwrap_or("")
                .contains("some unrecognized prose line")
        );
    }

    #[test]
    fn cstr_note_field_prefers_direct_value_and_reports_conflict() {
        let mut reference = Reference {
            id: "preprint-1".to_string(),
            ref_type: "article".to_string(),
            note: Some("tex.cstr: 32012.legacy\nCSTR: 32012.direct\nfree-form note".to_string()),
            ..Default::default()
        };

        let diagnostics = reference.parse_note_field_hacks_with_diagnostics();

        assert_eq!(
            reference
                .extra
                .get("CSTR")
                .and_then(serde_json::Value::as_str),
            Some("32012.direct")
        );
        assert_eq!(reference.note.as_deref(), Some("free-form note"));
        assert_eq!(
            diagnostics,
            vec![NoteFieldDiagnostic::ConflictingSupplementaryIdentifier {
                item_id: "preprint-1".to_string(),
                identifier: "cstr".to_string(),
                kept: "32012.direct".to_string(),
                ignored: vec!["32012.legacy".to_string()],
            }]
        );
    }

    #[test]
    fn tex_cstr_note_field_is_case_insensitive_and_canonicalized() {
        let mut reference = Reference {
            id: "preprint-2".to_string(),
            ref_type: "article".to_string(),
            note: Some("TeX.CsTr: 32012.tex".to_string()),
            ..Default::default()
        };

        let diagnostics = reference.parse_note_field_hacks_with_diagnostics();

        assert!(diagnostics.is_empty());
        assert_eq!(
            reference
                .extra
                .get("CSTR")
                .and_then(serde_json::Value::as_str),
            Some("32012.tex")
        );
        assert!(reference.note.is_none());
    }

    #[test]
    fn identical_cstr_spellings_are_quiet() {
        let mut reference = Reference {
            id: "preprint-3".to_string(),
            ref_type: "article".to_string(),
            note: Some("cstr: 32012.same\nTEX.CSTR: 32012.same".to_string()),
            ..Default::default()
        };

        let diagnostics = reference.parse_note_field_hacks_with_diagnostics();

        assert!(diagnostics.is_empty());
        assert_eq!(
            reference
                .extra
                .get("CSTR")
                .and_then(serde_json::Value::as_str),
            Some("32012.same")
        );
    }

    #[test]
    fn unknown_dotted_extra_key_and_note_text_are_preserved() {
        let mut reference = Reference {
            id: "preprint-4".to_string(),
            ref_type: "article".to_string(),
            note: Some("custom.code: keep-me\nordinary note".to_string()),
            ..Default::default()
        };

        reference.parse_note_field_hacks();

        assert_eq!(
            reference.note.as_deref(),
            Some("custom.code: keep-me\nordinary note")
        );
        assert!(!reference.extra.contains_key("CSTR"));
    }
}