json_archive/

archive_reader.rs

// json-archive is a tool for tracking JSON file changes over time
// Copyright (C) 2025  Peoples Grocers LLC
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published
// by the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
// To purchase a license under different terms contact admin@peoplesgrocers.com
// To request changes, report bugs, or give user feedback contact
// marxism@peoplesgrocers.com
//

use serde_json::Value;
use std::collections::HashSet;
use std::io::BufRead;

use crate::diagnostics::{Diagnostic, DiagnosticCode, DiagnosticCollector, DiagnosticLevel};
use crate::event_deserialize::EventDeserializer;
use crate::events::{Event, Header};
use crate::pointer::JsonPointer;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReadMode {
    FullValidation,
    AppendSeek,
}

#[derive(Debug)]
pub struct ReadResult {
    pub header: Header,
    pub final_state: Value,
    pub diagnostics: DiagnosticCollector,
    pub observation_count: usize,
}

pub struct EventIterator<R: BufRead> {
    reader: R,
    pub diagnostics: DiagnosticCollector,
    pub header: Header,
    filename: String,
    line_number: usize,
}

impl<R: BufRead> Iterator for EventIterator<R> {
    type Item = Event;

    fn next(&mut self) -> Option<Self::Item> {
        let mut line = String::new();

        loop {
            line.clear();
            self.line_number += 1;

            match self.reader.read_line(&mut line) {
                Ok(0) => return None, // EOF
                Ok(_) => {
                    let trimmed = line.trim();

                    // Skip comments and blank lines
                    if trimmed.starts_with('#') || trimmed.is_empty() {
                        continue;
                    }

                    // Try to parse as event
                    let event_deserializer = match serde_json::from_str::<EventDeserializer>(&line)
                    {
                        Ok(d) => d,
                        Err(e) => {
                            self.diagnostics.add(
                                Diagnostic::fatal(
                                    DiagnosticCode::InvalidEventJson,
                                    format!("I couldn't parse this line as JSON: {}", e),
                                )
                                .with_location(self.filename.clone(), self.line_number)
                                .with_snippet(format!("{} | {}", self.line_number, line.trim()))
                                .with_advice(
                                    "Each line after the header must be either:\n\
                                     - A comment starting with #\n\
                                     - A valid JSON array representing an event\n\n\
                                     Check for missing commas, quotes, or brackets."
                                        .to_string(),
                                ),
                            );
                            continue;
                        }
                    };

                    // Add any diagnostics from deserialization
                    for diagnostic in event_deserializer.diagnostics {
                        self.diagnostics.add(
                            diagnostic
                                .with_location(self.filename.clone(), self.line_number)
                                .with_snippet(format!("{} | {}", self.line_number, line.trim())),
                        );
                    }

                    // Return event if we have one
                    if let Some(event) = event_deserializer.event {
                        return Some(event);
                    }

                    // If no event but had diagnostics, continue to next line
                    continue;
                }
                Err(e) if e.kind() == std::io::ErrorKind::InvalidData => {
                    self.diagnostics.add(
                        Diagnostic::fatal(
                            DiagnosticCode::InvalidUtf8,
                            format!("I found invalid UTF-8 bytes at line {}.", self.line_number)
                        )
                        .with_location(self.filename.clone(), self.line_number)
                        .with_advice(
                            "The JSON Archive format requires UTF-8 encoding. Make sure the file \
                             was saved with UTF-8 encoding, not Latin-1, Windows-1252, or another encoding."
                                .to_string()
                        )
                    );
                    return None;
                }
                Err(_) => return None,
            }
        }
    }
}

/// Parse header and create event iterator from any BufRead source.
pub fn read_events<R: BufRead>(
    mut reader: R,
    filename: &str,
) -> Result<(Value, EventIterator<R>), Diagnostic> {
    let mut header_line = String::new();
    let mut line_number = 0;

    // Skip comment lines until we find the header
    loop {
        header_line.clear();
        line_number += 1;

        match reader.read_line(&mut header_line) {
            Ok(0) => {
                // Empty file or only comments
                return Err(Diagnostic::fatal(
                    DiagnosticCode::EmptyFile,
                    "I found an empty file (or only comments), but I need at least a header line."
                        .to_string(),
                )
                .with_location(filename.to_string(), line_number)
                .with_advice(
                    "See the file format specification for header structure.".to_string(),
                ));
            }
            Ok(_) => {}
            Err(e) if e.kind() == std::io::ErrorKind::InvalidData => {
                // UTF-8 error
                return Err(
                    Diagnostic::fatal(
                        DiagnosticCode::InvalidUtf8,
                        format!("I found invalid UTF-8 bytes at line {}.", line_number)
                    )
                    .with_location(filename.to_string(), line_number)
                    .with_advice(
                        "The JSON Archive format requires UTF-8 encoding. Make sure the file \
                         was saved with UTF-8 encoding, not Latin-1, Windows-1252, or another encoding."
                            .to_string()
                    )
                );
            }
            Err(e) => {
                return Err(Diagnostic::fatal(
                    DiagnosticCode::PathNotFound,
                    format!("I couldn't read from the archive: {}", e),
                )
                .with_location(filename.to_string(), line_number));
            }
        };

        // Skip comment lines (lines starting with #)
        let trimmed = header_line.trim_start();
        if !trimmed.starts_with('#') {
            break;
        }
    }

    let header = parse_header(filename, &header_line, line_number)?;

    let iterator = EventIterator {
        reader,
        diagnostics: DiagnosticCollector::new(),
        header: header.clone(),
        filename: filename.to_string(),
        line_number,
    };

    Ok((header.initial, iterator))
}

/// Read all events and return final state.
pub fn read_archive<R: BufRead>(
    reader: R,
    filename: &str,
    mode: ReadMode,
) -> Result<ReadResult, Diagnostic> {
    let (initial_value, mut event_iter) = read_events(reader, filename)?;

    let header = Header::new(initial_value.clone(), None);
    let mut state = initial_value;
    let mut seen_observations: HashSet<String> = HashSet::new();
    let mut current_observation: Option<(String, usize, usize)> = None;
    let mut events_in_observation = 0;
    let mut observation_count = 0;

    // Process events from iterator
    while let Some(event) = event_iter.next() {
        let line_number = event_iter.line_number;

        match event {
            Event::Observe {
                observation_id,
                timestamp: _,
                change_count,
            } => {
                if let Some((_obs_id, obs_line, expected_count)) = &current_observation {
                    if events_in_observation != *expected_count {
                        event_iter.diagnostics.add(
                            Diagnostic::new(
                                DiagnosticLevel::Warning,
                                DiagnosticCode::ChangeCountMismatch,
                                format!(
                                    "The observe event at line {} declared {} changes, but I found {}.",
                                    obs_line, expected_count, events_in_observation
                                )
                            )
                            .with_location(filename.to_string(), *obs_line)
                            .with_advice(
                                "Make sure the change_count in the observe event matches the number of \
                                 add/change/remove/move events that follow it."
                                    .to_string()
                            )
                        );
                    }
                }

                if seen_observations.contains(&observation_id) {
                    event_iter.diagnostics.add(
                        Diagnostic::new(
                            DiagnosticLevel::Warning,
                            DiagnosticCode::DuplicateObservationId,
                            format!("I found a duplicate observation ID: '{}'", observation_id),
                        )
                        .with_location(filename.to_string(), line_number)
                        .with_advice(
                            "Each observation ID should be unique within the archive. \
                             Consider using UUIDs or timestamps to ensure uniqueness."
                                .to_string(),
                        ),
                    );
                }

                seen_observations.insert(observation_id.clone());
                current_observation = Some((observation_id, line_number, change_count));
                events_in_observation = 0;
                observation_count += 1;
            }

            Event::Add {
                path,
                value,
                observation_id,
            } => {
                events_in_observation += 1;

                if mode == ReadMode::FullValidation && !seen_observations.contains(&observation_id)
                {
                    event_iter.diagnostics.add(
                        Diagnostic::fatal(
                            DiagnosticCode::NonExistentObservationId,
                            format!("I found a reference to observation '{}', but I haven't seen an observe event with that ID yet.", observation_id)
                        )
                        .with_location(filename.to_string(), line_number)
                        .with_advice(
                            "Each add/change/remove/move event must reference an observation ID from a preceding observe event."
                                .to_string()
                        )
                    );
                    continue;
                }

                if let Err(diag) = apply_add(&mut state, &path, value) {
                    event_iter
                        .diagnostics
                        .add(diag.with_location(filename.to_string(), line_number));
                    continue;
                }
            }

            Event::Change {
                path,
                new_value,
                observation_id,
            } => {
                events_in_observation += 1;

                if mode == ReadMode::FullValidation && !seen_observations.contains(&observation_id)
                {
                    event_iter.diagnostics.add(
                        Diagnostic::fatal(
                            DiagnosticCode::NonExistentObservationId,
                            format!("I found a reference to observation '{}', but I haven't seen an observe event with that ID yet.", observation_id)
                        )
                        .with_location(filename.to_string(), line_number)
                    );
                    continue;
                }

                if let Err(diag) = apply_change(&mut state, &path, new_value) {
                    event_iter
                        .diagnostics
                        .add(diag.with_location(filename.to_string(), line_number));
                    continue;
                }
            }

            Event::Remove {
                path,
                observation_id,
            } => {
                events_in_observation += 1;

                if mode == ReadMode::FullValidation && !seen_observations.contains(&observation_id)
                {
                    event_iter.diagnostics.add(
                        Diagnostic::fatal(
                            DiagnosticCode::NonExistentObservationId,
                            format!("I found a reference to observation '{}', but I haven't seen an observe event with that ID yet.", observation_id)
                        )
                        .with_location(filename.to_string(), line_number)
                    );
                    continue;
                }

                if let Err(diag) = apply_remove(&mut state, &path) {
                    event_iter
                        .diagnostics
                        .add(diag.with_location(filename.to_string(), line_number));
                    continue;
                }
            }

            Event::Move {
                path,
                moves,
                observation_id,
            } => {
                events_in_observation += 1;

                if mode == ReadMode::FullValidation && !seen_observations.contains(&observation_id)
                {
                    event_iter.diagnostics.add(
                        Diagnostic::fatal(
                            DiagnosticCode::NonExistentObservationId,
                            format!("I found a reference to observation '{}', but I haven't seen an observe event with that ID yet.", observation_id)
                        )
                        .with_location(filename.to_string(), line_number)
                    );
                    continue;
                }

                if let Err(diag) = apply_move(&mut state, &path, moves) {
                    event_iter
                        .diagnostics
                        .add(diag.with_location(filename.to_string(), line_number));
                    continue;
                }
            }

            Event::Snapshot {
                observation_id: _,
                timestamp: _,
                object,
            } => {
                if mode == ReadMode::FullValidation && state != object {
                    event_iter.diagnostics.add(
                        Diagnostic::fatal(
                            DiagnosticCode::SnapshotStateMismatch,
                            "I found a snapshot whose state doesn't match the replayed state up to this point.".to_string()
                        )
                        .with_location(filename.to_string(), line_number)
                        .with_advice(
                            "This could indicate corruption or that events were applied incorrectly. \
                             The snapshot state should exactly match the result of replaying all events \
                             from the initial state."
                                .to_string()
                        )
                    );
                }

                state = object;
            }
        }
    }

    if let Some((_obs_id, obs_line, expected_count)) = &current_observation {
        if events_in_observation != *expected_count {
            event_iter.diagnostics.add(
                Diagnostic::new(
                    DiagnosticLevel::Warning,
                    DiagnosticCode::ChangeCountMismatch,
                    format!(
                        "The observe event at line {} declared {} changes, but I found {}.",
                        obs_line, expected_count, events_in_observation
                    ),
                )
                .with_location(filename.to_string(), *obs_line),
            );
        }
    }

    Ok(ReadResult {
        header,
        final_state: state,
        diagnostics: event_iter.diagnostics,
        observation_count,
    })
}

fn parse_header(filename: &str, line: &str, line_number: usize) -> Result<Header, Diagnostic> {
    let value: Value = serde_json::from_str(line).map_err(|e| {
        Diagnostic::fatal(
            DiagnosticCode::MissingHeader,
            format!("I couldn't parse the header as JSON: {}", e),
        )
        .with_location(filename.to_string(), line_number)
        .with_snippet(format!("{} | {}", line_number, line))
        .with_advice(
            "The first line must be a JSON object containing the archive header.\n\
             Required fields: type, version, created, initial"
                .to_string(),
        )
    })?;

    let header = serde_json::from_value::<Header>(value).map_err(|e| {
        Diagnostic::fatal(
            DiagnosticCode::MissingHeaderField,
            format!("I couldn't parse the header: {}", e),
        )
        .with_location(filename.to_string(), line_number)
        .with_snippet(format!("{} | {}", line_number, line))
        .with_advice(
            "The header must contain:\n\
             - type: \"@peoplesgrocers/json-archive\"\n\
             - version: 1\n\
             - created: an ISO-8601 timestamp\n\
             - initial: the initial state object"
                .to_string(),
        )
    })?;

    if header.version != 1 {
        return Err(Diagnostic::fatal(
            DiagnosticCode::UnsupportedVersion,
            format!(
                "I found version {}, but I only support version 1.",
                header.version
            ),
        )
        .with_location(filename.to_string(), line_number)
        .with_advice(
            "This archive was created with a newer or older version of the format. \
                 You may need to upgrade your tools or convert the archive."
                .to_string(),
        ));
    }

    Ok(header)
}

pub fn apply_add(state: &mut Value, path: &str, value: Value) -> Result<(), Diagnostic> {
    let pointer = JsonPointer::new(path).map_err(|diag| {
        diag.with_advice(
            "JSON Pointer paths must start with '/' and use '/' to separate segments.\n\
             Special characters: use ~0 for ~ and ~1 for /"
                .to_string(),
        )
    })?;

    pointer.set(state, value).map_err(|diag| {
        diag.with_advice(
            "For add operations, the parent path must exist. \
             For example, to add /a/b/c, the paths /a and /a/b must already exist."
                .to_string(),
        )
    })
}

pub fn apply_change(state: &mut Value, path: &str, new_value: Value) -> Result<(), Diagnostic> {
    let pointer = JsonPointer::new(path)?;
    pointer.set(state, new_value)?;
    Ok(())
}

pub fn apply_remove(state: &mut Value, path: &str) -> Result<(), Diagnostic> {
    let pointer = JsonPointer::new(path)?;
    pointer.remove(state)?;
    Ok(())
}

pub fn apply_move(
    state: &mut Value,
    path: &str,
    moves: Vec<(usize, usize)>,
) -> Result<(), Diagnostic> {
    let pointer = JsonPointer::new(path)?;

    let array = pointer.get_mut(state)?;

    if !array.is_array() {
        return Err(Diagnostic::fatal(
            DiagnosticCode::MoveOnNonArray,
            format!(
                "I can't apply move operations to '{}' because it's not an array.",
                path
            ),
        )
        .with_advice(
            "Move operations can only reorder elements within an array. \
                 The path must point to an array value."
                .to_string(),
        ));
    }

    let arr = array.as_array_mut().unwrap();

    // Validate all moves upfront before mutating
    for (from_idx, to_idx) in &moves {
        if *from_idx >= arr.len() {
            return Err(Diagnostic::fatal(
                DiagnosticCode::MoveIndexOutOfBounds,
                format!(
                    "The 'from' index {} is out of bounds (array length is {}).",
                    from_idx,
                    arr.len()
                ),
            ));
        }

        if *to_idx > arr.len() {
            return Err(Diagnostic::fatal(
                DiagnosticCode::MoveIndexOutOfBounds,
                format!(
                    "The 'to' index {} is out of bounds (array length is {}).",
                    to_idx,
                    arr.len()
                ),
            ));
        }
    }

    // Apply moves now that we know they're all valid
    for (from_idx, to_idx) in moves {
        let element = arr.remove(from_idx);
        let insert_idx = if to_idx > from_idx {
            to_idx - 1
        } else {
            to_idx
        };
        arr.insert(insert_idx, element);
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use std::fs::File;
    use std::io::{BufReader, Write};
    use tempfile::NamedTempFile;

    #[test]
    fn test_read_valid_archive() {
        let mut temp_file = NamedTempFile::new().unwrap();

        let header = Header::new(json!({"count": 0}), Some("test".to_string()));
        writeln!(temp_file, "{}", serde_json::to_string(&header).unwrap()).unwrap();
        writeln!(
            temp_file,
            r#"["observe", "obs-1", "2025-01-01T00:00:00Z", 1]"#
        )
        .unwrap();
        writeln!(temp_file, r#"["change", "/count", 1, "obs-1"]"#).unwrap();

        let file = File::open(temp_file.path()).unwrap();
        let reader = BufReader::new(file);
        let result = read_archive(
            reader,
            &temp_file.path().display().to_string(),
            ReadMode::FullValidation,
        )
        .unwrap();

        assert_eq!(result.final_state, json!({"count": 1}));
        assert_eq!(result.observation_count, 1);
        assert!(!result.diagnostics.has_fatal());
    }

    #[test]
    fn test_empty_file() {
        let temp_file = NamedTempFile::new().unwrap();

        let file = File::open(temp_file.path()).unwrap();
        let reader = BufReader::new(file);
        let result = read_archive(
            reader,
            &temp_file.path().display().to_string(),
            ReadMode::FullValidation,
        );

        assert!(result.is_err());
    }

    #[test]
    fn test_non_existent_observation_id() {
        let mut temp_file = NamedTempFile::new().unwrap();

        let header = Header::new(json!({"count": 0}), None);
        writeln!(temp_file, "{}", serde_json::to_string(&header).unwrap()).unwrap();
        writeln!(temp_file, r#"["change", "/count", 1, "obs-999"]"#).unwrap();

        let file = File::open(temp_file.path()).unwrap();
        let reader = BufReader::new(file);
        let result = read_archive(
            reader,
            &temp_file.path().display().to_string(),
            ReadMode::FullValidation,
        )
        .unwrap();

        assert!(result.diagnostics.has_fatal());
    }

    #[test]
    fn test_append_mode_ignores_observation_id() {
        let mut temp_file = NamedTempFile::new().unwrap();

        let header = Header::new(json!({"count": 0}), None);
        writeln!(temp_file, "{}", serde_json::to_string(&header).unwrap()).unwrap();
        writeln!(temp_file, r#"["change", "/count", 1, "obs-999"]"#).unwrap();

        let file = File::open(temp_file.path()).unwrap();
        let reader = BufReader::new(file);
        let result = read_archive(
            reader,
            &temp_file.path().display().to_string(),
            ReadMode::AppendSeek,
        )
        .unwrap();

        assert!(!result.diagnostics.has_fatal());
        assert_eq!(result.final_state, json!({"count": 1}));
    }

    #[test]
    fn test_change_count_mismatch() {
        let mut temp_file = NamedTempFile::new().unwrap();

        let header = Header::new(json!({"count": 0}), None);
        writeln!(temp_file, "{}", serde_json::to_string(&header).unwrap()).unwrap();
        writeln!(
            temp_file,
            r#"["observe", "obs-1", "2025-01-01T00:00:00Z", 2]"#
        )
        .unwrap();
        writeln!(temp_file, r#"["change", "/count", 1, "obs-1"]"#).unwrap();

        let file = File::open(temp_file.path()).unwrap();
        let reader = BufReader::new(file);
        let result = read_archive(
            reader,
            &temp_file.path().display().to_string(),
            ReadMode::FullValidation,
        )
        .unwrap();

        let warnings: Vec<_> = result
            .diagnostics
            .diagnostics()
            .iter()
            .filter(|d| d.level == DiagnosticLevel::Warning)
            .collect();

        assert_eq!(warnings.len(), 1);
    }

    #[test]
    fn test_simple_change() {
        let mut temp_file = NamedTempFile::new().unwrap();

        let header = Header::new(json!({"count": 5}), None);
        writeln!(temp_file, "{}", serde_json::to_string(&header).unwrap()).unwrap();
        writeln!(
            temp_file,
            r#"["observe", "obs-1", "2025-01-01T00:00:00Z", 1]"#
        )
        .unwrap();
        writeln!(temp_file, r#"["change", "/count", 1, "obs-1"]"#).unwrap();

        let file = File::open(temp_file.path()).unwrap();
        let reader = BufReader::new(file);
        let result = read_archive(
            reader,
            &temp_file.path().display().to_string(),
            ReadMode::FullValidation,
        )
        .unwrap();

        assert!(!result.diagnostics.has_fatal());
        assert_eq!(result.final_state, json!({"count": 1}));
    }
}