quadlet-lens 0.1.13

//! Named document sets and exact native unit-reference resolution.

use std::collections::{BTreeMap, BTreeSet};
use std::{error::Error, fmt};

use crate::diagnostic::{Diagnostic, DiagnosticCode, Label, Severity};
use crate::source::{SourceId, SourceSpan};

use super::{QuadletDocument, QuadletUnitType, UnitReferenceKind, ValueKind};

const MISSING_REFERENCE: DiagnosticCode = DiagnosticCode::new("QLG0001");
const AMBIGUOUS_REFERENCE: DiagnosticCode = DiagnosticCode::new("QLG0002");
const DUPLICATE_UNIT_NAME: DiagnosticCode = DiagnosticCode::new("QLG0003");

/// Validated basename of one supported Quadlet unit file.
#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct UnitFileName {
    value: String,
    unit_type: QuadletUnitType,
}

impl UnitFileName {
    /// Validates a basename and infers its supported Quadlet unit type.
    ///
    /// # Errors
    ///
    /// Returns [`DocumentSetError::InvalidUnitFileName`] for an empty name, a path, or a missing
    /// stem/extension. Returns [`DocumentSetError::UnsupportedUnitFileExtension`] when the suffix
    /// is not part of the current typed model.
    pub fn new(value: impl Into<String>) -> Result<Self, DocumentSetError> {
        let value = value.into();
        if value.is_empty() || value.contains('/') || value.contains('\\') {
            return Err(DocumentSetError::InvalidUnitFileName(value));
        }
        let Some((stem, extension)) = value.rsplit_once('.') else {
            return Err(DocumentSetError::InvalidUnitFileName(value));
        };
        if stem.is_empty() || extension.is_empty() {
            return Err(DocumentSetError::InvalidUnitFileName(value));
        }
        let unit_type = QuadletUnitType::from_extension(extension)
            .ok_or_else(|| DocumentSetError::UnsupportedUnitFileExtension(value.clone()))?;
        Ok(Self { value, unit_type })
    }

    /// Returns the exact validated basename.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.value
    }

    /// Returns the unit type implied by the filename suffix.
    #[must_use]
    pub const fn unit_type(&self) -> QuadletUnitType {
        self.unit_type
    }
}

impl fmt::Display for UnitFileName {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(&self.value)
    }
}

/// One typed document paired with its unit-file basename.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct NamedQuadletDocument {
    name: UnitFileName,
    document: QuadletDocument,
}

impl NamedQuadletDocument {
    /// Validates that a filename and typed document describe the same unit type.
    ///
    /// # Errors
    ///
    /// Returns a [`DocumentSetError`] for invalid names, unsupported extensions, or a suffix that
    /// does not match the document's selected unit type.
    pub fn new(name: impl Into<String>, document: QuadletDocument) -> Result<Self, DocumentSetError> {
        let name = UnitFileName::new(name)?;
        if name.unit_type() != document.unit_type() {
            return Err(DocumentSetError::UnitTypeMismatch {
                name: name.as_str().to_owned(),
                filename_type: name.unit_type(),
                document_type: document.unit_type(),
            });
        }
        Ok(Self { name, document })
    }

    /// Returns the validated unit-file basename.
    #[must_use]
    pub const fn name(&self) -> &UnitFileName {
        &self.name
    }

    /// Returns the source-aware typed document.
    #[must_use]
    pub const fn document(&self) -> &QuadletDocument {
        &self.document
    }

    /// Decomposes the named document.
    #[must_use]
    pub fn into_parts(self) -> (UnitFileName, QuadletDocument) {
        (self.name, self.document)
    }
}

/// Resolution state of one authored native unit reference.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum ReferenceResolution {
    /// Exactly one document owns the referenced basename.
    Resolved {
        /// Index into [`QuadletDocumentSet::documents`].
        document_index: usize,
    },
    /// No document in the set owns the referenced basename.
    Missing,
    /// More than one document owns the referenced basename.
    Ambiguous {
        /// Number of candidate documents.
        candidates: usize,
    },
}

/// One authored reference and its exact document-set resolution.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct UnitReference {
    source_document: usize,
    target_name: String,
    kind: UnitReferenceKind,
    span: SourceSpan,
    resolution: ReferenceResolution,
}

impl UnitReference {
    /// Returns the index of the document containing the reference.
    #[must_use]
    pub const fn source_document(&self) -> usize {
        self.source_document
    }

    /// Returns the exact referenced unit-file basename.
    #[must_use]
    pub fn target_name(&self) -> &str {
        &self.target_name
    }

    /// Returns the native reference kind inferred from the authored value.
    #[must_use]
    pub const fn kind(&self) -> UnitReferenceKind {
        self.kind
    }

    /// Returns the authored value span containing the reference.
    #[must_use]
    pub const fn span(&self) -> SourceSpan {
        self.span
    }

    /// Returns whether the reference resolved exactly, was missing, or was ambiguous.
    #[must_use]
    pub const fn resolution(&self) -> ReferenceResolution {
        self.resolution
    }
}

/// One resolved dependency edge between two documents.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct DependencyEdge {
    source_document: usize,
    target_document: usize,
    kind: UnitReferenceKind,
    span: SourceSpan,
}

impl DependencyEdge {
    /// Returns the referencing document index.
    #[must_use]
    pub const fn source_document(self) -> usize {
        self.source_document
    }

    /// Returns the referenced document index.
    #[must_use]
    pub const fn target_document(self) -> usize {
        self.target_document
    }

    /// Returns the native relationship kind.
    #[must_use]
    pub const fn kind(self) -> UnitReferenceKind {
        self.kind
    }

    /// Returns the source span that created this edge.
    #[must_use]
    pub const fn span(self) -> SourceSpan {
        self.span
    }
}

/// Exact reference inventory and resolved dependency edges for a document set.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct DependencyGraph {
    references: Vec<UnitReference>,
    edges: Vec<DependencyEdge>,
}

impl DependencyGraph {
    /// Returns every native reference, including missing and ambiguous references.
    #[must_use]
    pub fn references(&self) -> &[UnitReference] {
        &self.references
    }

    /// Returns only references that resolve to exactly one document.
    #[must_use]
    pub fn edges(&self) -> &[DependencyEdge] {
        &self.edges
    }

    /// Returns whether every reference resolves to exactly one document.
    #[must_use]
    pub fn is_complete(&self) -> bool {
        self.references
            .iter()
            .all(|reference| matches!(reference.resolution, ReferenceResolution::Resolved { .. }))
    }
}

/// Named Quadlet documents plus their exact native dependency graph.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct QuadletDocumentSet {
    documents: Vec<NamedQuadletDocument>,
    graph: DependencyGraph,
    diagnostics: Vec<Diagnostic>,
}

impl QuadletDocumentSet {
    /// Builds an exact-name index and resolves every native unit reference.
    ///
    /// Duplicate unit basenames remain in the set so references can be reported as ambiguous.
    ///
    /// # Errors
    ///
    /// Returns [`DocumentSetError::DuplicateSourceId`] because source identities must be unique for
    /// unambiguous source-labelled diagnostics.
    pub fn new(documents: impl IntoIterator<Item = NamedQuadletDocument>) -> Result<Self, DocumentSetError> {
        let documents: Vec<_> = documents.into_iter().collect();
        ensure_unique_source_ids(&documents)?;

        let mut by_name: BTreeMap<String, Vec<usize>> = BTreeMap::new();
        for (index, document) in documents.iter().enumerate() {
            by_name
                .entry(document.name().as_str().to_owned())
                .or_default()
                .push(index);
        }

        let mut diagnostics = duplicate_name_diagnostics(&documents, &by_name);
        let mut references = Vec::new();
        let mut edges = Vec::new();
        for (source_document, named_document) in documents.iter().enumerate() {
            for entry in named_document.document().entries() {
                let ValueKind::UnitReference(kind) = entry.value_kind() else {
                    continue;
                };
                let Some(target_name) = entry.unit_reference_name() else {
                    continue;
                };
                let candidates = by_name.get(target_name).map_or(&[][..], Vec::as_slice);
                let resolution = match candidates {
                    [] => {
                        diagnostics.push(Diagnostic::new(
                            MISSING_REFERENCE,
                            Severity::Error,
                            "Quadlet unit reference has no matching document",
                            Label::new(
                                entry.value().primary().span(),
                                "add the referenced unit file to this document set",
                            ),
                        ));
                        ReferenceResolution::Missing
                    }
                    [target_document] => {
                        edges.push(DependencyEdge {
                            source_document,
                            target_document: *target_document,
                            kind,
                            span: entry.value().primary().span(),
                        });
                        ReferenceResolution::Resolved {
                            document_index: *target_document,
                        }
                    }
                    multiple => {
                        diagnostics.push(Diagnostic::new(
                            AMBIGUOUS_REFERENCE,
                            Severity::Error,
                            "Quadlet unit reference matches multiple documents",
                            Label::new(
                                entry.value().primary().span(),
                                "make unit-file basenames unique in this document set",
                            ),
                        ));
                        ReferenceResolution::Ambiguous {
                            candidates: multiple.len(),
                        }
                    }
                };
                references.push(UnitReference {
                    source_document,
                    target_name: target_name.to_owned(),
                    kind,
                    span: entry.value().primary().span(),
                    resolution,
                });
            }
        }

        Ok(Self {
            documents,
            graph: DependencyGraph { references, edges },
            diagnostics,
        })
    }

    /// Returns named documents in caller-provided order.
    #[must_use]
    pub fn documents(&self) -> &[NamedQuadletDocument] {
        &self.documents
    }

    /// Returns the native reference inventory and resolved edges.
    #[must_use]
    pub const fn graph(&self) -> &DependencyGraph {
        &self.graph
    }

    /// Returns duplicate-name and reference-resolution diagnostics.
    #[must_use]
    pub fn diagnostics(&self) -> &[Diagnostic] {
        &self.diagnostics
    }

    /// Returns whether every unit filename is unique and every reference resolves exactly once.
    #[must_use]
    pub fn is_valid(&self) -> bool {
        self.graph.is_complete()
            && self
                .diagnostics
                .iter()
                .all(|diagnostic| diagnostic.severity() != Severity::Error)
    }

    /// Returns the uniquely named document, or `None` when the name is missing or ambiguous.
    #[must_use]
    pub fn document(&self, name: &str) -> Option<&NamedQuadletDocument> {
        let mut matching = self
            .documents
            .iter()
            .filter(|document| document.name().as_str() == name);
        let first = matching.next()?;
        matching.next().is_none().then_some(first)
    }
}

/// Invalid filename/document metadata that prevents safe document-set construction.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum DocumentSetError {
    /// A unit name is empty, contains path separators, or lacks a complete suffix.
    InvalidUnitFileName(String),
    /// A unit suffix is outside the current typed-model surface.
    UnsupportedUnitFileExtension(String),
    /// The filename suffix and selected typed document kind differ.
    UnitTypeMismatch {
        /// Authored unit-file basename.
        name: String,
        /// Unit type inferred from the filename.
        filename_type: QuadletUnitType,
        /// Unit type selected while parsing the document.
        document_type: QuadletUnitType,
    },
    /// Two documents use the same caller-owned source identity.
    DuplicateSourceId(SourceId),
}

impl fmt::Display for DocumentSetError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::InvalidUnitFileName(name) => write!(formatter, "invalid Quadlet unit-file basename `{name}`"),
            Self::UnsupportedUnitFileExtension(name) => {
                write!(formatter, "unsupported Quadlet unit-file extension in `{name}`")
            }
            Self::UnitTypeMismatch {
                name,
                filename_type,
                document_type,
            } => write!(
                formatter,
                "Quadlet filename `{name}` implies {filename_type:?}, but the document is {document_type:?}"
            ),
            Self::DuplicateSourceId(source_id) => {
                write!(formatter, "duplicate Quadlet source identity {}", source_id.get())
            }
        }
    }
}

impl Error for DocumentSetError {}

fn ensure_unique_source_ids(documents: &[NamedQuadletDocument]) -> Result<(), DocumentSetError> {
    let mut source_ids = BTreeSet::new();
    for document in documents {
        let source_id = document.document().source_id();
        if !source_ids.insert(source_id) {
            return Err(DocumentSetError::DuplicateSourceId(source_id));
        }
    }
    Ok(())
}

fn duplicate_name_diagnostics(
    documents: &[NamedQuadletDocument],
    by_name: &BTreeMap<String, Vec<usize>>,
) -> Vec<Diagnostic> {
    let mut diagnostics = Vec::new();
    for indexes in by_name.values().filter(|indexes| indexes.len() > 1) {
        for index in indexes.iter().skip(1) {
            let document = &documents[*index];
            diagnostics.push(Diagnostic::new(
                DUPLICATE_UNIT_NAME,
                Severity::Error,
                "document set contains a duplicate Quadlet unit-file basename",
                Label::new(
                    document.document().source_span(),
                    "give this document a unique unit-file basename",
                ),
            ));
        }
    }
    diagnostics
}