alma 0.1.1

//! Validated UTF-8 byte stream storage and CRUD operations.

use bevy::prelude::Resource;
use std::{
    fmt::{Debug, Display, Formatter},
    ops::Range,
    str,
    sync::atomic::{AtomicU64, Ordering},
};

/// Process-local stream identity allocator.
static NEXT_STREAM_ID: AtomicU64 = AtomicU64::new(1);

/// Monotonic revision for a text stream snapshot.
#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct TextRevision(u64);

impl TextRevision {
    /// Initial stream revision.
    pub const ZERO: Self = Self(0);

    /// Returns the raw revision value for display or serialization.
    #[must_use]
    pub const fn get(self) -> u64 {
        self.0
    }

    /// Returns the next revision, failing closed at counter exhaustion.
    #[must_use]
    pub const fn next(self) -> Option<Self> {
        match self.0.checked_add(1) {
            Some(next) => Some(Self(next)),
            None => None,
        }
    }
}

impl Display for TextRevision {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        Display::fmt(&self.0, formatter)
    }
}

impl PartialEq<u64> for TextRevision {
    fn eq(&self, other: &u64) -> bool {
        self.0 == *other
    }
}

#[cfg(test)]
impl From<u64> for TextRevision {
    fn from(revision: u64) -> Self {
        Self(revision)
    }
}

/// Opaque identity for one text stream allocation.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub struct TextStreamId(u64);

impl TextStreamId {
    /// Allocates a fresh process-local stream identity.
    fn fresh() -> Self {
        Self(NEXT_STREAM_ID.fetch_add(1, Ordering::Relaxed))
    }
}

/// A validated UTF-8 byte stream used as the source of rendered text.
#[derive(Eq, Resource)]
pub struct TextByteStream {
    /// Text storage, kept as UTF-8 so Bevy can render it directly.
    text: String,
    /// Monotonic version counter for external caches and persistence.
    revision: TextRevision,
    /// Process-local identity used to scope validated range proofs.
    id: TextStreamId,
}

impl Debug for TextByteStream {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("TextByteStream")
            .field("shape", &TextByteStreamShape::from(self))
            .finish()
    }
}

impl Clone for TextByteStream {
    fn clone(&self) -> Self {
        Self {
            text: self.text.clone(),
            revision: self.revision,
            id: TextStreamId::fresh(),
        }
    }
}

impl Default for TextByteStream {
    fn default() -> Self {
        Self::new("")
    }
}

impl PartialEq for TextByteStream {
    fn eq(&self, other: &Self) -> bool {
        self.text == other.text && self.revision == other.revision
    }
}

/// Redacted stream diagnostic shape.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TextByteStreamShape {
    /// Stream length in bytes.
    byte_len: usize,
    /// Stream revision.
    revision: TextRevision,
    /// Process-local stream identity.
    id: TextStreamId,
}

impl TextByteStreamShape {
    /// Returns the stream byte length.
    #[must_use]
    pub const fn byte_len(self) -> usize {
        self.byte_len
    }

    /// Returns the stream revision.
    #[must_use]
    pub const fn revision(self) -> TextRevision {
        self.revision
    }

    /// Returns the stream identity.
    #[must_use]
    pub const fn id(self) -> TextStreamId {
        self.id
    }
}

impl From<&TextByteStream> for TextByteStreamShape {
    fn from(stream: &TextByteStream) -> Self {
        Self {
            byte_len: stream.as_bytes().len(),
            revision: stream.revision(),
            id: stream.id(),
        }
    }
}

/// An unvalidated byte range in editor text coordinates.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct TextRange {
    /// Start byte index.
    start: usize,
    /// End byte index.
    end: usize,
}

impl TextRange {
    /// Creates a byte range that still needs validation against concrete text.
    #[must_use]
    pub const fn new(start: usize, end: usize) -> Self {
        Self { start, end }
    }

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

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

    /// Converts this range into Rust's standard range shape.
    #[must_use]
    pub const fn as_range(self) -> Range<usize> {
        self.start..self.end
    }
}

impl From<Range<usize>> for TextRange {
    fn from(range: Range<usize>) -> Self {
        Self {
            start: range.start,
            end: range.end,
        }
    }
}

/// A byte range proven valid for a specific text stream snapshot.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ValidatedTextRange {
    /// Validated byte range.
    range: TextRange,
    /// Stream identity against which the range was validated.
    stream_id: TextStreamId,
    /// Stream revision against which the range was validated.
    revision: TextRevision,
}

impl ValidatedTextRange {
    /// Creates a validated range after all stream invariants have been checked.
    const fn new(range: TextRange, stream_id: TextStreamId, revision: TextRevision) -> Self {
        Self {
            range,
            stream_id,
            revision,
        }
    }

    /// Returns the start byte index.
    #[must_use]
    pub const fn start(self) -> usize {
        self.range.start()
    }

    /// Returns the end byte index.
    #[must_use]
    pub const fn end(self) -> usize {
        self.range.end()
    }

    /// Returns the stream revision against which this range was validated.
    #[must_use]
    pub const fn revision(self) -> TextRevision {
        self.revision
    }

    /// Returns the stream identity against which this range was validated.
    #[must_use]
    pub const fn stream_id(self) -> TextStreamId {
        self.stream_id
    }

    /// Converts this range into Rust's standard range shape.
    #[must_use]
    pub const fn as_range(self) -> Range<usize> {
        self.range.as_range()
    }
}

impl TextByteStream {
    /// Creates a new text byte stream from valid UTF-8 text.
    #[must_use]
    pub fn new(text: impl Into<String>) -> Self {
        Self {
            text: text.into(),
            revision: TextRevision::ZERO,
            id: TextStreamId::fresh(),
        }
    }

    /// Creates a new text byte stream from raw UTF-8 bytes.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError::InvalidUtf8`] when `bytes` are not valid UTF-8.
    pub fn from_bytes(bytes: Vec<u8>) -> Result<Self, TextStreamError> {
        String::from_utf8(bytes)
            .map(Self::new)
            .map_err(|error| TextStreamError::InvalidUtf8 {
                valid_up_to: error.utf8_error().valid_up_to(),
            })
    }

    /// Reads the stream as renderable UTF-8 text.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.text
    }

    /// Reads the underlying UTF-8 bytes without allocation.
    #[must_use]
    pub const fn as_bytes(&self) -> &[u8] {
        self.text.as_bytes()
    }

    /// Returns the current stream revision.
    #[must_use]
    pub const fn revision(&self) -> TextRevision {
        self.revision
    }

    /// Returns this stream's opaque identity.
    #[must_use]
    pub const fn id(&self) -> TextStreamId {
        self.id
    }

    /// Replaces the entire stream with valid UTF-8 text.
    pub fn replace_all(&mut self, text: impl Into<String>) {
        self.text = text.into();
        self.bump_revision();
    }

    /// Replaces the entire stream with raw UTF-8 bytes.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError::InvalidUtf8`] when `bytes` are not valid UTF-8.
    pub fn replace_all_bytes(&mut self, bytes: Vec<u8>) -> Result<(), TextStreamError> {
        self.text = String::from_utf8(bytes).map_err(|error| TextStreamError::InvalidUtf8 {
            valid_up_to: error.utf8_error().valid_up_to(),
        })?;
        self.bump_revision();
        Ok(())
    }

    /// Inserts valid UTF-8 text at a byte index.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError`] when `byte_index` is out of bounds or not a UTF-8 character
    /// boundary.
    pub fn insert_str(&mut self, byte_index: usize, text: &str) -> Result<(), TextStreamError> {
        self.validate_boundary(byte_index)?;
        self.text.insert_str(byte_index, text);
        self.bump_revision();
        Ok(())
    }

    /// Inserts raw UTF-8 bytes at a byte index.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError::InvalidUtf8`] when `bytes` are invalid UTF-8, or another
    /// [`TextStreamError`] when `byte_index` is out of bounds or not a UTF-8 character boundary.
    pub fn insert_bytes(&mut self, byte_index: usize, bytes: &[u8]) -> Result<(), TextStreamError> {
        let text = str::from_utf8(bytes).map_err(|error| TextStreamError::InvalidUtf8 {
            valid_up_to: error.valid_up_to(),
        })?;
        self.insert_str(byte_index, text)
    }

    /// Replaces a byte range with valid UTF-8 text.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError`] when `range` is invalid, out of bounds, or not aligned to UTF-8
    /// character boundaries.
    pub fn replace_range(
        &mut self,
        range: Range<usize>,
        text: &str,
    ) -> Result<(), TextStreamError> {
        let range = self.validate_range(range)?;
        self.replace_validated_range(range, text)
    }

    /// Replaces a validated byte range with valid UTF-8 text.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError::StaleValidatedRange`] when the stream revision has changed since
    /// the range was validated.
    pub fn replace_validated_range(
        &mut self,
        range: ValidatedTextRange,
        text: &str,
    ) -> Result<(), TextStreamError> {
        self.validate_range_revision(range)?;
        self.text.replace_range(range.as_range(), text);
        self.bump_revision();
        Ok(())
    }

    /// Replaces a byte range with raw UTF-8 bytes.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError::InvalidUtf8`] when `bytes` are invalid UTF-8, or another
    /// [`TextStreamError`] when `range` is invalid, out of bounds, or not aligned to UTF-8
    /// character boundaries.
    pub fn replace_range_bytes(
        &mut self,
        range: Range<usize>,
        bytes: &[u8],
    ) -> Result<(), TextStreamError> {
        let text = str::from_utf8(bytes).map_err(|error| TextStreamError::InvalidUtf8 {
            valid_up_to: error.valid_up_to(),
        })?;
        self.replace_range(range, text)
    }

    /// Deletes a byte range.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError`] when `range` is invalid, out of bounds, or not aligned to UTF-8
    /// character boundaries.
    pub fn delete_range(&mut self, range: Range<usize>) -> Result<(), TextStreamError> {
        self.replace_range(range, "")
    }

    /// Deletes a validated byte range.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError::StaleValidatedRange`] when the stream revision has changed since
    /// the range was validated.
    pub fn delete_validated_range(
        &mut self,
        range: ValidatedTextRange,
    ) -> Result<(), TextStreamError> {
        self.replace_validated_range(range, "")
    }

    /// Clears the stream.
    pub fn clear(&mut self) {
        self.text.clear();
        self.bump_revision();
    }

    /// Advances the stream revision after a mutation.
    const fn bump_revision(&mut self) {
        self.revision = self
            .revision
            .next()
            .expect("text revision exhausted; refusing to wrap monotonic revision");
    }

    /// Validates one byte index against the current stream.
    fn validate_boundary(&self, index: usize) -> Result<(), TextStreamError> {
        if self.text.len() < index {
            return Err(TextStreamError::OutOfBounds {
                index,
                len: self.text.len(),
            });
        }

        if !self.text.is_char_boundary(index) {
            return Err(TextStreamError::NotCharBoundary { index });
        }

        Ok(())
    }

    /// Validates a byte range against the current stream.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError`] when `range` is invalid, out of bounds, or not aligned to UTF-8
    /// character boundaries.
    pub fn validate_range(
        &self,
        range: impl Into<TextRange>,
    ) -> Result<ValidatedTextRange, TextStreamError> {
        let range = range.into();
        if range.end() < range.start() {
            return Err(TextStreamError::InvalidRange {
                start: range.start(),
                end: range.end(),
            });
        }

        self.validate_boundary(range.start())?;
        self.validate_boundary(range.end())?;
        Ok(ValidatedTextRange::new(range, self.id(), self.revision()))
    }

    /// Validates that a previously proven range still belongs to this stream snapshot.
    ///
    /// # Errors
    ///
    /// Returns [`TextStreamError::WrongTextStream`] when the range was validated against a
    /// different stream, or [`TextStreamError::StaleValidatedRange`] when this stream has changed
    /// since validation.
    pub fn validate_validated_range(
        &self,
        range: ValidatedTextRange,
    ) -> Result<ValidatedTextRange, TextStreamError> {
        if range.stream_id() != self.id() {
            return Err(TextStreamError::WrongTextStream {
                validated_stream: range.stream_id(),
                current_stream: self.id(),
            });
        }

        if range.revision() != self.revision() {
            return Err(TextStreamError::StaleValidatedRange {
                validated_revision: range.revision(),
                current_revision: self.revision(),
            });
        }

        Ok(range)
    }

    /// Validates that a previously proven range still belongs to this stream revision.
    fn validate_range_revision(&self, range: ValidatedTextRange) -> Result<(), TextStreamError> {
        let _range = self.validate_validated_range(range)?;
        Ok(())
    }
}

/// Errors returned by [`TextByteStream`] mutations.
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[non_exhaustive]
pub enum TextStreamError {
    /// Raw bytes were not valid UTF-8.
    InvalidUtf8 {
        /// The byte index up to which the input was valid UTF-8.
        valid_up_to: usize,
    },
    /// A byte index exceeded the stream length.
    OutOfBounds {
        /// The rejected byte index.
        index: usize,
        /// The current stream length in bytes.
        len: usize,
    },
    /// A byte index split a UTF-8 scalar value.
    NotCharBoundary {
        /// The rejected byte index.
        index: usize,
    },
    /// A byte range had its end before its start.
    InvalidRange {
        /// The start byte index.
        start: usize,
        /// The end byte index.
        end: usize,
    },
    /// A validated range was reused after the stream changed.
    StaleValidatedRange {
        /// Revision recorded by the validated range.
        validated_revision: TextRevision,
        /// Current stream revision.
        current_revision: TextRevision,
    },
    /// A validated range was reused with a different text stream.
    WrongTextStream {
        /// Stream identity recorded by the validated range.
        validated_stream: TextStreamId,
        /// Current stream identity.
        current_stream: TextStreamId,
    },
}

impl Display for TextStreamError {
    fn fmt(&self, formatter: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::InvalidUtf8 { valid_up_to } => {
                write!(formatter, "invalid UTF-8 after byte {valid_up_to}")
            }
            Self::OutOfBounds { index, len } => {
                write!(
                    formatter,
                    "byte index {index} is outside stream length {len}"
                )
            }
            Self::NotCharBoundary { index } => {
                write!(
                    formatter,
                    "byte index {index} is not a UTF-8 character boundary"
                )
            }
            Self::InvalidRange { start, end } => {
                write!(formatter, "invalid byte range {start}..{end}")
            }
            Self::StaleValidatedRange {
                validated_revision,
                current_revision,
            } => write!(
                formatter,
                "validated range from revision {validated_revision} cannot be applied to revision {current_revision}"
            ),
            Self::WrongTextStream {
                validated_stream,
                current_stream,
            } => write!(
                formatter,
                "validated range from stream {validated_stream:?} cannot be applied to stream {current_stream:?}"
            ),
        }
    }
}

/// Property tests for UTF-8 byte-stream CRUD operations.
#[cfg(test)]
mod tests {
    use super::{TextByteStream, TextRange, TextStreamError};
    use proptest::{
        prelude::{Strategy, any, proptest},
        prop_assert_eq,
    };

    /// Generates Unicode scalar values that occupy more than one UTF-8 byte.
    fn multibyte_char() -> impl Strategy<Value = char> {
        any::<char>().prop_filter("character must use multiple UTF-8 bytes", |character| {
            1 < character.len_utf8()
        })
    }

    #[test]
    fn validated_ranges_encode_stream_byte_invariants() {
        let stream = TextByteStream::new("aλb");

        let range = stream
            .validate_range(TextRange::new(1, 3))
            .expect("lambda range should be valid");

        assert_eq!(range.start(), 1);
        assert_eq!(range.end(), 3);
        assert_eq!(range.stream_id(), stream.id());
        assert_eq!(range.revision(), 0);
        assert_eq!(range.as_range(), 1..3);
        assert_eq!(
            stream.validate_range(TextRange::new(2, 3)),
            Err(TextStreamError::NotCharBoundary { index: 2 })
        );
        assert_eq!(
            stream.validate_range(TextRange::new(4, 3)),
            Err(TextStreamError::InvalidRange { start: 4, end: 3 })
        );
    }

    #[test]
    fn validated_ranges_are_revision_scoped() {
        let mut stream = TextByteStream::new("abc");
        let range = stream
            .validate_range(TextRange::new(1, 2))
            .expect("range should validate");
        stream.replace_all("aλc");

        assert_eq!(
            stream.delete_validated_range(range),
            Err(TextStreamError::StaleValidatedRange {
                validated_revision: 0.into(),
                current_revision: 1.into(),
            })
        );
        assert_eq!(stream.as_str(), "aλc");
    }

    #[test]
    fn validated_ranges_are_stream_scoped() {
        let source = TextByteStream::new("abcdef");
        let mut target = TextByteStream::new("λ");
        let range = source
            .validate_range(TextRange::new(1, 4))
            .expect("source range should validate");

        assert_eq!(
            target.delete_validated_range(range),
            Err(TextStreamError::WrongTextStream {
                validated_stream: source.id(),
                current_stream: target.id(),
            })
        );
        assert_eq!(target.as_str(), "λ");
        assert_eq!(target.revision(), 0);
    }

    proptest! {
        /// Replacing the whole stream round-trips arbitrary valid Unicode.
        #[test]
        fn replace_all_round_trips_arbitrary_unicode(input in any::<String>()) {
            let mut stream = TextByteStream::default();

            stream.replace_all(input.clone());

            prop_assert_eq!(stream.as_str(), input.as_str());
            prop_assert_eq!(stream.as_bytes(), input.as_bytes());
            prop_assert_eq!(stream.revision(), 1);
        }

        /// Creating from valid UTF-8 bytes round-trips arbitrary Unicode.
        #[test]
        fn from_bytes_accepts_valid_utf8(input in any::<String>()) {
            let stream = TextByteStream::from_bytes(input.clone().into_bytes());

            prop_assert_eq!(stream, Ok(TextByteStream::new(input)));
        }

        /// Inserting at a UTF-8 character boundary matches Rust's `String` model.
        #[test]
        fn insert_str_matches_string_model(
            prefix in any::<String>(),
            inserted in any::<String>(),
            suffix in any::<String>(),
        ) {
            let original = format!("{prefix}{suffix}");
            let expected = format!("{prefix}{inserted}{suffix}");
            let mut stream = TextByteStream::new(original);

            prop_assert_eq!(stream.insert_str(prefix.len(), inserted.as_str()), Ok(()));
            prop_assert_eq!(stream.as_str(), expected.as_str());
            prop_assert_eq!(stream.revision(), 1);
        }

        /// Replacing a UTF-8-aligned byte range matches Rust's `String` model.
        #[test]
        fn replace_range_matches_string_model(
            prefix in any::<String>(),
            removed in any::<String>(),
            suffix in any::<String>(),
            replacement in any::<String>(),
        ) {
            let original = format!("{prefix}{removed}{suffix}");
            let expected = format!("{prefix}{replacement}{suffix}");
            let range = prefix.len()..prefix.len() + removed.len();
            let mut stream = TextByteStream::new(original);

            prop_assert_eq!(stream.replace_range(range, replacement.as_str()), Ok(()));
            prop_assert_eq!(stream.as_str(), expected.as_str());
            prop_assert_eq!(stream.revision(), 1);
        }

        /// Deleting a UTF-8-aligned byte range matches Rust's `String` model.
        #[test]
        fn delete_range_matches_string_model(
            prefix in any::<String>(),
            removed in any::<String>(),
            suffix in any::<String>(),
        ) {
            let original = format!("{prefix}{removed}{suffix}");
            let expected = format!("{prefix}{suffix}");
            let range = prefix.len()..prefix.len() + removed.len();
            let mut stream = TextByteStream::new(original);

            prop_assert_eq!(stream.delete_range(range), Ok(()));
            prop_assert_eq!(stream.as_str(), expected.as_str());
            prop_assert_eq!(stream.revision(), 1);
        }

        /// Byte-range edits reject indices that split a Unicode scalar.
        #[test]
        fn delete_range_rejects_split_scalar(
            prefix in any::<String>(),
            character in multibyte_char(),
        ) {
            let mut stream = TextByteStream::new(format!("{prefix}{character}"));
            let split_index = prefix.len() + 1;

            prop_assert_eq!(
                stream.delete_range(split_index..split_index),
                Err(TextStreamError::NotCharBoundary { index: split_index }),
            );
            prop_assert_eq!(stream.revision(), 0);
        }

        /// Raw byte insertion matches string insertion when bytes are valid UTF-8.
        #[test]
        fn insert_bytes_matches_string_model(
            prefix in any::<String>(),
            inserted in any::<String>(),
            suffix in any::<String>(),
        ) {
            let original = format!("{prefix}{suffix}");
            let expected = format!("{prefix}{inserted}{suffix}");
            let mut stream = TextByteStream::new(original);

            prop_assert_eq!(stream.insert_bytes(prefix.len(), inserted.as_bytes()), Ok(()));
            prop_assert_eq!(stream.as_str(), expected.as_str());
        }
    }

    /// Creating a stream from invalid bytes fails without lossy conversion.
    #[test]
    fn from_bytes_rejects_invalid_utf8() {
        assert_eq!(
            TextByteStream::from_bytes(vec![0x66, 0x80]),
            Err(TextStreamError::InvalidUtf8 { valid_up_to: 1 })
        );
    }

    #[test]
    fn debug_output_redacts_stream_text() {
        let stream = TextByteStream::new("secret buffer text");
        let debug = format!("{stream:?}");

        assert!(debug.contains("TextByteStream"));
        assert!(debug.contains("byte_len"));
        assert!(!debug.contains("secret"));
        assert!(!debug.contains("buffer text"));
    }

    /// Newline bytes remain literal stream data for Bevy layout.
    #[test]
    fn newline_remains_layout_data() {
        let mut stream = TextByteStream::new("ALMA");

        assert_eq!(stream.insert_str(4, "\nΑλμα"), Ok(()));
        assert_eq!(stream.as_str(), "ALMA\nΑλμα");
    }
}