aimx/aim/

journal.rs

//! Journal index for AIM version headers.
//!
//! Maintains `.jnl` sidecar files that map version headers in `.aim` files to
//! byte offsets, enabling direct seeks to specific workflow versions without
//! re-scanning the source.

use anyhow::{Result, anyhow};
use jiff::civil::DateTime;
use nom::{
    IResult, Parser, character::{char, complete::{digit1, multispace1}}, combinator::map_res,
    sequence::preceded,
};
use std::{
    fmt,
    fs::File,
    io::{BufRead, BufReader, Read, Write},
    path::{Path, PathBuf},
    sync::Arc,
};
use crate::{aim::{Writer, WriterLike, parse_version}, literals::parse_date};

/// Journal entry mapping a version to its byte offset within an `.aim` file.
#[derive(Debug, PartialEq, Copy, Clone)]
pub struct Journal {
    version: u32,
    position: u64,
    date: DateTime
}

impl Journal {
    /// Create a new entry.
    ///
    /// `version` is the workflow version epoch; `position` is the byte offset of its header.
    pub fn new(version: u32, position: u64, date: DateTime) -> Self {
        Self { version, position, date }
    }

    /// Version number for this entry.
    pub fn version(&self) -> u32 {
        self.version
    }

    /// Byte offset for this entry.
    pub fn position(&self) -> u64 {
        self.position
    }

    pub fn date(&self) -> DateTime {
        self.date
    }

    pub fn print(&self, writer: &mut Writer) {
        writer.write_unsigned(self.version);
        writer.write_char(',');
        writer.write_u64(self.position);
        writer.write_char(' ');
        writer.write_date(&self.date);
    }

    /// Return the formula-string representation (round-trippable by the parser).
    pub fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.print(&mut writer);
        writer.finish()
    }
}

impl WriterLike for Journal {
    fn write(&self, writer: &mut Writer) {
        self.print(writer);
    }
}

impl fmt::Display for Journal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.to_stringized())
    }
}

/// Build `.jnl` index for an `.aim` file.
///
/// Scans `aim_path` for complete version headers and writes non-partial entries
/// to the sidecar `.jnl`. Overwrites the provided `journals` with the result.
pub fn build_journal(journals: &mut Vec<Arc<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();
        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(Arc::new(Journal {
                            version: version.epoch(),
                            position: position,
                            date: version.date(),
                        }));
                    }
                }
                // Skip invalid version headers
                Err(_) => {}
            }
        }

        // Update position for next line
        position += bytes_read as u64;
    }

    // Save the journal to file
    save_journal(aim_path, journals)?;

    Ok(())
}

/// Save journal entries for `aim_path` to its `.jnl` file.
///
/// Writes each entry as `version,position` and truncates any existing journal.
pub fn save_journal(aim_path: &Path, journals: &Vec<Arc<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)?;
    }

    Ok(())
}

/// Derive `.jnl` path from an `.aim` file path.
///
/// Replaces the `.aim` extension with `.jnl`; fails if `aim_path` has no file name.
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 for journal fields.
fn parse_u32(input: &str) -> IResult<&str, u32> {
    map_res(digit1, |s: &str| s.parse::<u32>()).parse(input)
}

/// Parse an unsigned 64-bit integer for journal fields.
fn parse_u64(input: &str) -> IResult<&str, u64> {
    map_res(digit1, |s: &str| s.parse::<u64>()).parse(input)
}

/// Parse a single `version,position` line into a [`Journal`].
fn parse_journal_entry(input: &str) -> IResult<&str, Journal> {
    let (input, (version, position, date)) = (
        parse_u32,
        preceded(
            char(','),
            parse_u64
        ),
        preceded(
            multispace1,
            parse_date
        )
    ).parse(input)?;
    Ok((input, Journal { version, position, date }))
}

/// Parse newline-delimited `version,position` entries into `journals`.
fn parse_journal(journals: &mut Vec<Arc<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(Arc::new(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(())
}

/// Load journal entries for `aim_path`.
///
/// Reads the `.jnl` file into `journals`, or (if missing) regenerates it via
/// [`build_journal`] from the `.aim` source.
pub fn load_journal(journals: &mut Vec<Arc<Journal>>, aim_path: &Path) -> Result<()> {
    let jnl_path = to_journal_path(aim_path)?;
    // Check if file exists
    if !Path::new(&jnl_path).exists() {
        return build_journal(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)
}