amql_engine/

transact.rs

//! Declarative multi-file transactional mutations.
//!
//! All operations are applied to an in-memory buffer. On success the buffer is
//! flushed to disk. On any error nothing is written — the transaction rolls back.

use crate::error::AqlError;
use crate::types::{ProjectRoot, RelativePath};
use amql_mutate::{insert_source, remove_node, replace_node, InsertPosition, NodeRef};
use rustc_hash::FxHashMap;
use serde::{Deserialize, Serialize};

/// A condition evaluated against the in-memory buffer during a transaction.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum TransactionCondition {
    /// True if the node's current source text contains `text` as a substring.
    ReadContains { node: NodeRef, text: String },
}

/// A single operation within a transaction.
///
/// Ops are applied sequentially to an in-memory buffer. When mutating the
/// same file multiple times, order ops by descending `start_byte` to avoid
/// byte-offset drift.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "jsonschema", derive(schemars::JsonSchema))]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum TransactionOp {
    /// Replace a node's source text.
    Replace { node: NodeRef, source: String },
    /// Insert source text relative to a target node.
    Insert {
        /// The node to insert relative to.
        target: NodeRef,
        /// Where to insert: `before`, `after`, or `into`.
        position: InsertPosition,
        /// Source text to insert.
        source: String,
    },
    /// Remove a node.
    Remove { node: NodeRef },
    /// Execute `then` if `condition` holds against the current buffer, else `else`.
    If {
        /// Condition to evaluate against the current in-memory buffer.
        condition: TransactionCondition,
        /// Ops to run if the condition is true.
        then: Vec<TransactionOp>,
        /// Ops to run if the condition is false. Empty means no-op.
        #[serde(default, rename = "else")]
        else_: Vec<TransactionOp>,
    },
}

/// Result of a successfully committed transaction.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TransactionResult {
    /// Files written to disk.
    pub files_modified: Vec<RelativePath>,
    /// Total mutation operations applied (excluding `If` branch nodes themselves).
    pub ops_applied: usize,
}

/// Reject any `RelativePath` that could escape the project root.
fn validate_path(file: &RelativePath) -> Result<(), AqlError> {
    let s: &str = file;
    if s.contains("..") || std::path::Path::new(s).is_absolute() {
        return Err(AqlError::new(format!(
            "Path '{s}' is not allowed: must be relative and must not contain '..'"
        )));
    }
    Ok(())
}

/// Execute a declarative transaction: apply `ops` to an in-memory buffer, then
/// flush to disk only if all ops succeed. On error nothing is written.
///
/// Note: the atomicity guarantee covers the mutation phase (buffer). The write
/// phase flushes files one at a time — a disk failure mid-flush leaves some
/// files written and some not. Use the WAL-backed variant for full crash safety.
pub fn execute_transaction(
    root: &ProjectRoot,
    ops: Vec<TransactionOp>,
) -> Result<TransactionResult, AqlError> {
    validate_ops(&ops)?;
    let mut buffer: FxHashMap<RelativePath, String> = FxHashMap::default();
    let mut ops_applied: usize = 0;
    run_ops(root, &ops, &mut buffer, &mut ops_applied)?;

    let mut files_modified: Vec<RelativePath> = Vec::new();
    for (file, content) in &buffer {
        let path = root.join(AsRef::<std::path::Path>::as_ref(file));
        std::fs::write(&path, content)
            .map_err(|e| AqlError::new(format!("Failed to write {}: {e}", path.display())))?;
        files_modified.push(file.clone());
    }
    files_modified.sort_by(|a, b| {
        let a_str: &str = a;
        let b_str: &str = b;
        a_str.cmp(b_str)
    });

    Ok(TransactionResult {
        files_modified,
        ops_applied,
    })
}

/// Validate all file paths in the op tree before execution begins.
fn validate_ops(ops: &[TransactionOp]) -> Result<(), AqlError> {
    for op in ops {
        match op {
            TransactionOp::Replace { node, .. } => validate_path(&node.file)?,
            TransactionOp::Insert { target, .. } => validate_path(&target.file)?,
            TransactionOp::Remove { node } => validate_path(&node.file)?,
            TransactionOp::If {
                condition,
                then,
                else_,
            } => {
                match condition {
                    TransactionCondition::ReadContains { node, .. } => validate_path(&node.file)?,
                }
                validate_ops(then)?;
                validate_ops(else_)?;
            }
        }
    }
    Ok(())
}

fn read_from_buffer(
    root: &ProjectRoot,
    buffer: &FxHashMap<RelativePath, String>,
    file: &RelativePath,
) -> Result<String, AqlError> {
    if let Some(s) = buffer.get(file) {
        return Ok(s.clone());
    }
    let path = root.join(AsRef::<std::path::Path>::as_ref(file));
    std::fs::read_to_string(&path)
        .map_err(|e| AqlError::new(format!("Failed to read {}: {e}", path.display())))
}

fn run_ops(
    root: &ProjectRoot,
    ops: &[TransactionOp],
    buffer: &mut FxHashMap<RelativePath, String>,
    ops_applied: &mut usize,
) -> Result<(), AqlError> {
    for op in ops {
        match op {
            TransactionOp::Replace { node, source } => {
                let current = read_from_buffer(root, buffer, &node.file)?;
                let result =
                    replace_node(&current, &node.file, node, source).map_err(AqlError::from)?;
                buffer.insert(node.file.clone(), result.source);
                *ops_applied += 1;
            }
            TransactionOp::Insert {
                target,
                position,
                source,
            } => {
                let current = read_from_buffer(root, buffer, &target.file)?;
                let result = insert_source(&current, &target.file, target, *position, source)
                    .map_err(AqlError::from)?;
                buffer.insert(target.file.clone(), result.source);
                *ops_applied += 1;
            }
            TransactionOp::Remove { node } => {
                let current = read_from_buffer(root, buffer, &node.file)?;
                let removal = remove_node(&current, node).map_err(AqlError::from)?;
                buffer.insert(node.file.clone(), removal.result.source);
                *ops_applied += 1;
            }
            TransactionOp::If {
                condition,
                then,
                else_,
            } => {
                let branch_taken = eval_condition(root, buffer, condition)?;
                let branch = if branch_taken { then } else { else_ };
                run_ops(root, branch, buffer, ops_applied)?;
            }
        }
    }
    Ok(())
}

fn eval_condition(
    root: &ProjectRoot,
    buffer: &FxHashMap<RelativePath, String>,
    condition: &TransactionCondition,
) -> Result<bool, AqlError> {
    match condition {
        TransactionCondition::ReadContains { node, text } => {
            let source = read_from_buffer(root, buffer, &node.file)?;
            let node_text = source.get(node.start_byte..node.end_byte).ok_or_else(|| {
                AqlError::new(format!(
                    "Byte range {}..{} out of bounds for {}",
                    node.start_byte, node.end_byte, node.file
                ))
            })?;
            Ok(node_text.contains(text.as_str()))
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Write as _;
    use tempfile::TempDir;

    fn setup(content: &str) -> (TempDir, ProjectRoot, RelativePath) {
        let dir = TempDir::new().unwrap();
        let file_path = dir.path().join("test.ts");
        let mut f = std::fs::File::create(&file_path).unwrap();
        f.write_all(content.as_bytes()).unwrap();
        let root = ProjectRoot::from(dir.path());
        let rel = RelativePath::from("test.ts");
        (dir, root, rel)
    }

    fn node_for_range(file: &RelativePath, start: usize, end: usize) -> NodeRef {
        // line/column are metadata only; mutation ops use start_byte/end_byte exclusively.
        NodeRef {
            file: file.clone(),
            start_byte: start,
            end_byte: end,
            kind: "identifier".into(),
            line: 1,
            column: 0,
            end_line: 1,
            end_column: 0,
        }
    }

    #[test]
    fn commits_replace_to_disk() {
        // Arrange
        let (_dir, root, rel) = setup("hello world");
        let node = node_for_range(&rel, 6, 11);
        let ops = vec![TransactionOp::Replace {
            node,
            source: "AQL".to_string(),
        }];

        // Act
        let result = execute_transaction(&root, ops).unwrap();

        // Assert
        let on_disk = std::fs::read_to_string(root.join(std::path::Path::new("test.ts"))).unwrap();
        assert_eq!(on_disk, "hello AQL", "file should be rewritten");
        assert_eq!(result.ops_applied, 1, "one op applied");
        assert_eq!(result.files_modified, vec![rel], "one file modified");
    }

    #[test]
    fn rolls_back_on_bad_range() {
        // Arrange
        let (_dir, root, rel) = setup("hello");
        let node = node_for_range(&rel, 100, 200); // out of bounds
        let ops = vec![TransactionOp::Replace {
            node,
            source: "x".to_string(),
        }];

        // Act
        let err = execute_transaction(&root, ops);

        // Assert
        assert!(err.is_err(), "should fail on bad range");
        let on_disk = std::fs::read_to_string(root.join(std::path::Path::new("test.ts"))).unwrap();
        assert_eq!(on_disk, "hello", "file must be unchanged after rollback");
    }

    #[test]
    fn if_condition_branches_correctly() {
        // Arrange
        let (_dir, root, rel) = setup("fn foo() {}");
        let node = node_for_range(&rel, 0, 11);
        let ops = vec![TransactionOp::If {
            condition: TransactionCondition::ReadContains {
                node: node.clone(),
                text: "foo".to_string(),
            },
            then: vec![TransactionOp::Replace {
                node,
                source: "fn bar() {}".to_string(),
            }],
            else_: vec![],
        }];

        // Act
        let result = execute_transaction(&root, ops).unwrap();

        // Assert
        let on_disk = std::fs::read_to_string(root.join(std::path::Path::new("test.ts"))).unwrap();
        assert_eq!(on_disk, "fn bar() {}", "then branch should have been taken");
        assert_eq!(result.ops_applied, 1, "one mutation applied");
    }
}