aimx/aim/

journal.rs

//! Version journaling and persistence for AIM files
//!
//! This module provides functionality for managing journal files that track
//! version history in AIM workflows. Journal files (`.jnl`) map version numbers
//! to byte offsets in corresponding AIM files, enabling efficient random access
//! to specific versions without parsing the entire file.
//!
//! # Journal File Format
//!
//! Journal files store entries in the format `version,position` with one entry
//! per line:
//!
//! ```text
//! 1,0
//! 2,150
//! 3,320
//! ```
//!
//! # Workflow
//!
//! 1. When an AIM file is modified, version headers are parsed to create journal entries
//! 2. Journal entries are saved to a corresponding `.jnl` file
//! 3. When reading specific versions, the journal is used to seek directly to the offset
//!
//! # Examples
//!
//! ```no_run
//! use std::path::Path;
//! use aimx::aim::{Journal, journal_file, journal_load};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let mut journals = Vec::new();
//! let path = Path::new("workflow.aim");
//!
//! // Create or update journal file
//! journal_file(&mut journals, path)?;
//!
//! // Load existing journal entries
//! journal_load(&mut journals, path)?;
//! # Ok(())
//! # }
//! ```

use anyhow::{anyhow, Result};
use std::{
    fs::File,
    io::{BufRead, BufReader, Read, Write},
    path::{Path, PathBuf},
};
use crate::aim::parse_version;
use nom::{
    IResult, Parser,
    bytes::complete::tag,
    character::complete::digit1,
    combinator::map_res,
    sequence::separated_pair,
};

/// Represents a journal entry with version and file position.
///
/// A journal entry maps a specific version of an AIM file to its byte offset position
/// within that file. This enables efficient random access to specific versions without
/// having to parse the entire file.
///
/// # Examples
///
/// ```
/// use aimx::aim::Journal;
///
/// let journal = Journal::new(1, 100);
/// assert_eq!(journal.version(), 1);
/// assert_eq!(journal.position(), 100);
/// ```
#[derive(Debug, PartialEq, Copy, Clone)]
pub struct Journal {
    version: u32,
    position: u64,
}

impl Journal {
    /// Creates a new journal entry with the specified version and position.
    ///
    /// # Arguments
    ///
    /// * `version` - The version number this entry represents
    /// * `position` - The byte offset position in the file where this version starts
    ///
    /// # Returns
    ///
    /// A new `Journal` instance.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::aim::Journal;
    ///
    /// let journal = Journal::new(2, 150);
    /// assert_eq!(journal.version(), 2);
    /// assert_eq!(journal.position(), 150);
    /// ```
    pub fn new(version: u32, position: u64) -> Self {
        Self {
            version,
            position
        }
    }

    /// Returns the version number of this journal entry.
    ///
    /// # Returns
    ///
    /// The version number as a `u32`.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::aim::Journal;
    ///
    /// let journal = Journal::new(3, 200);
    /// assert_eq!(journal.version(), 3);
    /// ```
    pub fn version(&self) -> u32 {
        self.version
    }

    /// Returns the byte position of this journal entry.
    ///
    /// # Returns
    ///
    /// The byte offset position as a `u64`.
    ///
    /// # Examples
    ///
    /// ```
    /// use aimx::aim::Journal;
    ///
    /// let journal = Journal::new(1, 50);
    /// assert_eq!(journal.position(), 50);
    /// ```
    pub fn position(&self) -> u64 {
        self.position
    }
}

/// Journals version headers in an .aim file and saves the journal entries to a .jnl file.
///
/// This function scans through an AIM file, identifies version headers (lines starting with '['),
/// and creates journal entries for complete versions (those without partial components).
/// The resulting journal entries are saved to a corresponding .jnl file.
///
/// # Arguments
///
/// * `journals` - Vector to store the parsed journal entries
/// * `aim_path` - Path to the .aim file to journal
///
/// # Returns
///
/// * `Ok(())` on successful journal creation
/// * `Err` if the file cannot be read or parsed
///
/// # Examples
///
/// ```no_run
/// use std::path::Path;
/// use aimx::aim::{Journal, journal_file};
///
/// let mut journals = Vec::new();
/// let result = journal_file(&mut journals, Path::new("workflow.aim"));
/// ```
pub fn journal_file(journals: &mut Vec<Journal>, aim_path: &Path) -> Result<()> {
    // Check if file exists
    if !aim_path.exists() {
        return Err(anyhow!("Invalid filename: {}", aim_path.to_string_lossy()));
    }

    // Open file for reading
    let file = File::open(aim_path)?;

    // Clear previous journal entries
    journals.clear();
    
    // Create buffered reader
    let mut reader = BufReader::new(file);
    
    // Track position manually since BufReader doesn't provide seek position easily
    let mut position: u64 = 0;
    let mut line = String::new();
    
    // Iterate through lines
    loop {
        line.clear();
        //position = reader.stream_position()?;
        let bytes_read = reader.read_line(&mut line)?;
        
        // Break if we reached EOF
        if bytes_read == 0 {
            break;
        }
        
        // Check if line starts with '[' (after trimming whitespace)
        let trimmed_line = line.trim_start();
        if trimmed_line.starts_with('[') {
            // Try to parse as version header
            match parse_version(trimmed_line) {
                Ok(version) => {
                    // Only record if partial is 0 (e.g., [123] not [123:1])
                    if version.partial() == 0 {
                        journals.push(Journal {
                            version: version.epoc(),
                            position: position,
                        });
                    }
                }
                // Skip invalid version headers
                Err(_) => {}
            }
        }
        
        // Update position for next line
        position += bytes_read as u64;
    }
    
    // Save the journal to file
    journal_save(aim_path, journals)?;
    
    Ok(())
}

/// Saves the journal vector to a .jnl file for the corresponding .aim file.
///
/// This function takes a vector of journal entries and writes them to a .jnl file
/// that corresponds to the provided .aim file path. Each entry is written as
/// "version,position" on a separate line.
///
/// # Arguments
///
/// * `aim_path` - Path to the .aim file (used to derive the .jnl filename)
/// * `journals` - Vector of journal entries to save
///
/// # Returns
///
/// * `Ok(())` on successful save
/// * `Err` if the file cannot be created or written to
///
/// # Examples
///
/// ```no_run
/// use std::path::Path;
/// use aimx::aim::{Journal, journal_save};
///
/// let journals = vec![Journal::new(1, 0), Journal::new(2, 100)];
/// let result = journal_save(Path::new("workflow.aim"), &journals);
/// ```
pub fn journal_save(aim_path: &Path, journals: &Vec<Journal>) -> Result<()> {
    let jnl_path = to_journal_path(aim_path)?;

    // Create a new file or truncate an existing one
    let mut file = File::create(&jnl_path)?;
    
    for journal in journals {
        writeln!(file, "{},{}", journal.version, journal.position)?;
    }
    
    Ok(())
}

/// Converts an .aim file path to the corresponding .jnl file path.
///
/// This function takes an AIM file path and returns the corresponding journal file path
/// by replacing the .aim extension with .jnl.
///
/// # Arguments
///
/// * `aim_path` - Path to the .aim file
///
/// # Returns
///
/// * `Ok(PathBuf)` with the corresponding .jnl file path
/// * `Err` if the file path is invalid
///
/// # Examples
///
/// ```
/// use std::path::Path;
/// use aimx::aim::to_journal_path;
///
/// let jnl_path = to_journal_path(Path::new("examples/workflow.aim")).unwrap();
/// assert_eq!(jnl_path, Path::new("examples/workflow.jnl"));
/// ```
pub fn to_journal_path(aim_path: &Path) -> Result<PathBuf> {
    let stem = aim_path.file_stem().ok_or_else(||
        anyhow!("Invalid filename: {}", aim_path.to_string_lossy()))?;
    let parent = aim_path.parent().unwrap_or_else(|| Path::new(""));
    
    let mut jnl_path = parent.to_path_buf();
    jnl_path.push(format!("{}.jnl", stem.to_string_lossy()));
    
    Ok(jnl_path)
}

/// Parse an unsigned 32-bit integer.
///
/// This is a helper function for parsing journal entries.
fn parse_u32(input: &str) -> IResult<&str, u32> {
    map_res(digit1, |s: &str| s.parse::<u32>()).parse(input)
}

/// Parse an unsigned 64-bit integer.
///
/// This is a helper function for parsing journal entries.
fn parse_u64(input: &str) -> IResult<&str, u64> {
    map_res(digit1, |s: &str| s.parse::<u64>()).parse(input)
}

/// Parse a single journal entry (version,position).
///
/// This is a helper function that parses a single line from a .jnl file
/// in the format "version,position" and returns a Journal struct.
fn parse_journal_entry(input: &str) -> IResult<&str, Journal> {
    let (input, (version, position)) = separated_pair(
        parse_u32,
        tag(","),
        parse_u64,
    ).parse(input)?;
    
    Ok((input, Journal { version, position }))
}

/// Parse an entire .jnl file's contents.
///
/// This function parses the contents of a journal file, where each line
/// represents a journal entry in the format "version,position".
///
/// # Arguments
///
/// * `journals` - Vector to store the parsed journal entries
/// * `input` - String content of the .jnl file
///
/// # Returns
///
/// * `Ok(())` on successful parsing
/// * `Err` if there's a parse error
fn parse_journal(journals: &mut Vec<Journal>, input: &str) -> Result<()> {
    let lines: Vec<&str> = input.lines().collect();
    // Clear previous journal entries
    journals.clear();
    for line in lines {
        match parse_journal_entry(line) {
            Ok((_, journal)) => journals.push(journal),
            Err(nom::Err::Error(e)) |
            Err(nom::Err::Failure(e)) => return Err(anyhow!("Parse error: {}", e)),
            Err(nom::Err::Incomplete(_)) => return Err(anyhow!("Incomplete input")),
        }
    }
    Ok(())
}

/// Loads journal entries from a .jnl file.
///
/// This function loads journal entries from a .jnl file. If the .jnl file doesn't
/// exist, it will attempt to create it by scanning the corresponding .aim file.
///
/// # Arguments
///
/// * `journals` - Vector to store the loaded journal entries
/// * `aim_path` - Path to the .aim file to load the journal for
///
/// # Returns
///
/// * `Ok(())` on successful load
/// * `Err` if the file cannot be read or parsed
///
/// # Examples
///
/// ```no_run
/// use std::path::Path;
/// use aimx::aim::{Journal, journal_load};
///
/// let mut journals = Vec::new();
/// let result = journal_load(&mut journals, Path::new("workflow.aim"));
/// ```
pub fn journal_load(journals: &mut Vec<Journal>, aim_path: &Path) -> Result<()> {
    let jnl_path = to_journal_path(aim_path)?;
    // Check if file exists
    if !Path::new(&jnl_path).exists() {
        return journal_file(journals, aim_path);
    }

    // Read the entire file
    let mut file = File::open(jnl_path)?;
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    
    // Parse the contents
    parse_journal(journals, &contents)
}