ephemeris_documents/

ownership.rs

//! Ownership declarations and the claims they make on key paths.

use std::fmt;
use std::str::FromStr;

use facet::Facet;
use facet_value::{VObject, Value};

use crate::error::OwnershipError;
use crate::path::{KeyPath, PathTokens};

/// A nonempty key path selected for management in a structured document.
#[derive(Debug, Clone, Facet, PartialEq, Eq)]
#[facet(proxy = Vec<String>)]
pub struct ManagedPath(Vec<String>);

impl ManagedPath {
    /// A path of one top-level key.
    #[must_use]
    pub fn single(key: String) -> Self {
        Self(vec![key])
    }

    /// The keys from the root down.
    #[must_use]
    pub fn segments(&self) -> &[String] {
        &self.0
    }

    /// `value` wrapped in one object per key of the path.
    pub(crate) fn nest(&self, value: Value) -> Value {
        self.0.iter().rev().fold(value, |inner, key| {
            let mut object = VObject::new();
            object.insert(key, inner);
            Value::from(object)
        })
    }
}

impl TryFrom<Vec<String>> for ManagedPath {
    type Error = OwnershipError;

    fn try_from(segments: Vec<String>) -> Result<Self, Self::Error> {
        if segments.is_empty() {
            Err(OwnershipError::PathEmpty)
        } else {
            Ok(Self(segments))
        }
    }
}

impl FromStr for ManagedPath {
    type Err = OwnershipError;

    fn from_str(text: &str) -> Result<Self, Self::Err> {
        Ok(Self(PathTokens::parse(text)?))
    }
}

impl fmt::Display for ManagedPath {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        KeyPath::from(self).fmt(f)
    }
}

impl From<&ManagedPath> for KeyPath {
    fn from(path: &ManagedPath) -> Self {
        Self::from(path.segments())
    }
}

impl From<&ManagedPath> for Vec<String> {
    fn from(path: &ManagedPath) -> Self {
        path.0.clone()
    }
}

/// Ownership mode shared by structured document formats.
#[derive(Debug, Clone, Facet, PartialEq, Eq)]
#[facet(tag = "type", deny_unknown_fields)]
#[repr(u8)]
pub enum DocumentOwnership {
    /// Manage the complete document, preserving only explicitly unmanaged
    /// paths.
    #[facet(rename = "whole")]
    Whole {
        /// Paths whose current values remain user-owned.
        #[facet(default)]
        unmanaged: Vec<ManagedPath>,
    },
    /// Manage only the explicitly selected paths.
    #[facet(rename = "selected")]
    Selected {
        /// Paths this contribution manages.
        owned: Vec<ManagedPath>,
    },
}

impl Default for DocumentOwnership {
    fn default() -> Self {
        Self::Whole {
            unmanaged: Vec::new(),
        }
    }
}

impl DocumentOwnership {
    /// Manage the whole document except the `unmanaged` paths.
    #[must_use]
    pub fn whole<I: IntoIterator<Item = ManagedPath>>(unmanaged: I) -> Self {
        Self::Whole {
            unmanaged: unmanaged.into_iter().collect(),
        }
    }

    /// Manage only the `owned` paths.
    #[must_use]
    pub fn selected<I: IntoIterator<Item = ManagedPath>>(owned: I) -> Self {
        Self::Selected {
            owned: owned.into_iter().collect(),
        }
    }

    /// Whether this ownership leaves any part of the document user-owned.
    pub(crate) const fn is_partial(&self) -> bool {
        match self {
            Self::Whole { unmanaged } => !unmanaged.is_empty(),
            Self::Selected { owned: _ } => true,
        }
    }
}

/// What a document owner holds at one path.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Claim {
    /// Ephemeris manages the path and everything below it.
    Owned,
    /// The user keeps the path and everything below it.
    Unmanaged,
    /// Both sides hold parts below the path.
    Mixed,
}

/// The claim held at every path no exception reaches.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum DefaultClaim {
    /// Ephemeris manages the path and everything below it.
    Owned,
    /// The user keeps the path and everything below it.
    Unmanaged,
}

impl DefaultClaim {
    pub(crate) const fn is_owned(self) -> bool {
        matches!(self, Self::Owned)
    }

    const fn opposite(self) -> Self {
        match self {
            Self::Owned => Self::Unmanaged,
            Self::Unmanaged => Self::Owned,
        }
    }

    const fn claim(self) -> Claim {
        match self {
            Self::Owned => Claim::Owned,
            Self::Unmanaged => Claim::Unmanaged,
        }
    }
}

/// Paths where no path is a prefix of another.
#[derive(Debug, Clone, PartialEq, Eq)]
struct PathSet(Vec<ManagedPath>);

impl TryFrom<&[ManagedPath]> for PathSet {
    type Error = OwnershipError;

    fn try_from(paths: &[ManagedPath]) -> Result<Self, Self::Error> {
        for (index, left) in paths.iter().enumerate() {
            if let Some(right) = paths
                .iter()
                .skip(index.saturating_add(1))
                .find(|right| left.0.starts_with(&right.0) || right.0.starts_with(&left.0))
            {
                return Err(OwnershipError::PathOverlap {
                    first: left.clone(),
                    second: right.clone(),
                });
            }
        }
        Ok(Self(paths.to_vec()))
    }
}

impl PathSet {
    /// Whether a member equals `path` or is a prefix of it.
    fn covers(&self, path: &[String]) -> bool {
        self.0
            .iter()
            .any(|member| path.starts_with(member.segments()))
    }

    /// Whether a member lies strictly below `path`.
    fn has_below(&self, path: &[String]) -> bool {
        self.0.iter().any(|member| {
            member.segments().len() > path.len() && member.segments().starts_with(path)
        })
    }
}

/// A validated ownership declaration: a default claim and the paths that
/// take the opposite claim.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct Ownership {
    default: DefaultClaim,
    exceptions: PathSet,
}

impl TryFrom<&DocumentOwnership> for Ownership {
    type Error = OwnershipError;

    fn try_from(ownership: &DocumentOwnership) -> Result<Self, Self::Error> {
        let (default, paths) = match ownership {
            DocumentOwnership::Whole { unmanaged } => (DefaultClaim::Owned, unmanaged),
            DocumentOwnership::Selected { owned } => (DefaultClaim::Unmanaged, owned),
        };
        Ok(Self {
            default,
            exceptions: PathSet::try_from(paths.as_slice())?,
        })
    }
}

impl Ownership {
    /// The claim at every path no exception reaches.
    pub(crate) const fn default_claim(&self) -> DefaultClaim {
        self.default
    }

    /// The claim at `path`.
    pub(crate) fn claim(&self, path: &[String]) -> Claim {
        if self.exceptions.covers(path) {
            self.default.opposite().claim()
        } else if self.exceptions.has_below(path) {
            Claim::Mixed
        } else {
            self.default.claim()
        }
    }
}

#[cfg(test)]
mod tests;