amql_engine/

sync.rs

//! Incremental sync between source code changes and `.aqm` sidecar files.
//!
//! Given old XML content and new annotations (from extractors), produces a
//! minimal set of text edits. Only elements whose `bind` values changed are
//! touched — the rest of the XML is preserved byte-for-byte.

use crate::store::Annotation;
use crate::types::{Binding, TagName};
use quick_xml::events::Event;
use quick_xml::Reader;
use serde::Serialize;

/// A text edit to apply to an `.aqm` sidecar file.
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
pub struct SidecarEdit {
    /// Byte offset of the start of the region to replace.
    pub start_byte: usize,
    /// Byte offset of the end of the region to replace.
    pub end_byte: usize,
    /// Replacement text (empty string = deletion).
    pub new_text: String,
}

/// A located element in existing XML, with its byte span and identity.
struct LocatedElement {
    tag: TagName,
    binding: Binding,
    /// Byte offset in the original (unwrapped) XML where this element starts.
    start_byte: usize,
    /// Byte offset in the original (unwrapped) XML where this element ends.
    end_byte: usize,
}

/// Compute minimal edits to sync an `.aqm` sidecar with new annotations.
///
/// Matches elements by `bind` attribute. Produces edits for:
/// - Renamed bindings (bind attr value changed) — not applicable (bind is the key)
/// - Added annotations — appended at end
/// - Removed annotations — element deleted
/// - Attribute changes on existing elements — element replaced
///
/// Returns edits sorted by `start_byte` descending (apply back-to-front).
#[must_use = "sync result contains edits to apply"]
pub fn sync_sidecar(old_xml: &str, new_annotations: &[Annotation]) -> Vec<SidecarEdit> {
    let existing = locate_elements(old_xml);
    let mut edits = Vec::new();

    // Index existing elements by (tag, binding) for O(1) lookup
    let mut existing_by_key: rustc_hash::FxHashMap<(&str, &str), &LocatedElement> =
        rustc_hash::FxHashMap::default();
    for elem in &existing {
        existing_by_key.insert((elem.tag.as_ref(), elem.binding.as_ref()), elem);
    }

    // Track which existing elements are still present
    let mut matched_keys: rustc_hash::FxHashSet<(&str, &str)> = rustc_hash::FxHashSet::default();

    // Check each new annotation against existing
    let mut to_append = Vec::new();
    for ann in new_annotations {
        let key = (ann.tag.as_ref(), ann.binding.as_ref());
        if let Some(elem) = existing_by_key.get(&key) {
            matched_keys.insert(key);
            // Element exists — check if attributes changed
            let new_xml = serialize_annotation(ann);
            let old_text = &old_xml[elem.start_byte..elem.end_byte];
            if old_text.trim() != new_xml.trim() {
                edits.push(SidecarEdit {
                    start_byte: elem.start_byte,
                    end_byte: elem.end_byte,
                    new_text: new_xml,
                });
            }
        } else {
            // New annotation — append
            to_append.push(ann);
        }
    }

    // Remove annotations that no longer exist in source
    for elem in &existing {
        let key = (elem.tag.as_ref(), elem.binding.as_ref());
        // Skip elements with empty bindings — they're manual annotations, not extracted
        if elem.binding.is_empty() {
            continue;
        }
        if !matched_keys.contains(&key) {
            // Include trailing newline in deletion
            let end = skip_trailing_newline(old_xml, elem.end_byte);
            edits.push(SidecarEdit {
                start_byte: elem.start_byte,
                end_byte: end,
                new_text: String::new(),
            });
        }
    }

    // Append new annotations at end
    if !to_append.is_empty() {
        let insert_pos = old_xml.trim_end().len();
        let mut text = String::new();
        for ann in to_append {
            if insert_pos > 0 || !text.is_empty() {
                text.push('\n');
            }
            text.push_str(&serialize_annotation(ann));
        }
        text.push('\n');
        edits.push(SidecarEdit {
            start_byte: insert_pos,
            end_byte: insert_pos,
            new_text: text,
        });
    }

    // Sort descending by start_byte for back-to-front application
    edits.sort_by(|a, b| b.start_byte.cmp(&a.start_byte));
    edits
}

/// Apply edits to XML content. Edits must be sorted descending by `start_byte`.
#[must_use = "returns the modified XML content"]
pub fn apply_edits(xml: &str, edits: &[SidecarEdit]) -> String {
    let mut result = xml.to_string();
    for edit in edits {
        result.replace_range(edit.start_byte..edit.end_byte, &edit.new_text);
    }
    result
}

/// Locate all top-level XML elements with their byte spans in the original text.
fn locate_elements(xml: &str) -> Vec<LocatedElement> {
    let mut elements = Vec::new();
    let mut reader = Reader::from_str(xml);
    let mut buf = Vec::new();

    loop {
        let pos_before = reader.buffer_position();
        match reader.read_event_into(&mut buf) {
            Ok(Event::Empty(ref e)) => {
                let tag = crate::xml::element_name(e).unwrap_or_default();
                let binding = extract_bind_attr(e);
                let pos_after = reader.buffer_position();
                elements.push(LocatedElement {
                    tag: TagName::from(tag),
                    binding,
                    start_byte: pos_before as usize,
                    end_byte: pos_after as usize,
                });
            }
            Ok(Event::Start(ref e)) => {
                let tag = crate::xml::element_name(e).unwrap_or_default();
                let binding = extract_bind_attr(e);
                // Read until matching end tag
                let mut depth = 1u32;
                let mut inner_buf = Vec::new();
                loop {
                    match reader.read_event_into(&mut inner_buf) {
                        Ok(Event::Start(_)) => depth += 1,
                        Ok(Event::End(_)) => {
                            depth -= 1;
                            if depth == 0 {
                                break;
                            }
                        }
                        Ok(Event::Eof) => break,
                        Err(_) => break,
                        _ => {}
                    }
                    inner_buf.clear();
                }
                let pos_after = reader.buffer_position();
                elements.push(LocatedElement {
                    tag: TagName::from(tag),
                    binding,
                    start_byte: pos_before as usize,
                    end_byte: pos_after as usize,
                });
            }
            Ok(Event::Eof) => break,
            Err(_) => break,
            _ => {}
        }
        buf.clear();
    }

    elements
}

/// Extract the `bind` attribute value from an XML element.
fn extract_bind_attr(e: &quick_xml::events::BytesStart<'_>) -> Binding {
    let pairs = crate::xml::attr_map(e).unwrap_or_default();
    Binding::from(
        pairs
            .iter()
            .find(|(k, _)| k == "bind")
            .map(|(_, v)| v.as_str())
            .unwrap_or_default(),
    )
}

/// Serialize an annotation back to XML.
fn serialize_annotation(ann: &Annotation) -> String {
    let mut xml = format!("<{}", ann.tag);
    if !ann.binding.is_empty() {
        xml.push_str(&format!(" bind=\"{}\"", escape_attr(ann.binding.as_ref())));
    }
    // Sort attributes for deterministic output
    let mut attrs: Vec<_> = ann.attrs.iter().collect();
    attrs.sort_by_key(|(k, _)| (*k).clone());
    for (key, value) in &attrs {
        let val_str = match value {
            serde_json::Value::String(s) => s.clone(),
            serde_json::Value::Bool(b) => b.to_string(),
            serde_json::Value::Number(n) => n.to_string(),
            other => other.to_string(),
        };
        xml.push_str(&format!(" {}=\"{}\"", key.as_ref(), escape_attr(&val_str)));
    }
    if ann.children.is_empty() {
        xml.push_str(" />");
    } else {
        xml.push('>');
        for child in &ann.children {
            xml.push_str("\n  ");
            xml.push_str(&serialize_annotation(child));
        }
        xml.push_str(&format!("\n</{}>", ann.tag));
    }
    xml
}

/// Escape XML attribute value characters.
fn escape_attr(s: &str) -> String {
    s.replace('&', "&amp;")
        .replace('"', "&quot;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}

/// Skip trailing whitespace and at most one newline after an element end.
fn skip_trailing_newline(xml: &str, pos: usize) -> usize {
    let bytes = xml.as_bytes();
    let mut i = pos;
    // Skip spaces/tabs
    while i < bytes.len() && (bytes[i] == b' ' || bytes[i] == b'\t') {
        i += 1;
    }
    // Skip one newline
    if i < bytes.len() && bytes[i] == b'\n' {
        i += 1;
    } else if i < bytes.len() && bytes[i] == b'\r' {
        i += 1;
        if i < bytes.len() && bytes[i] == b'\n' {
            i += 1;
        }
    }
    i
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::{AttrName, RelativePath};
    use rustc_hash::FxHashMap;
    use serde_json::Value as JsonValue;

    fn ann(tag: &str, bind: &str, attrs: Vec<(&str, &str)>) -> Annotation {
        let mut attr_map = FxHashMap::default();
        for (k, v) in attrs {
            attr_map.insert(AttrName::from(k), JsonValue::String(v.to_string()));
        }
        Annotation {
            tag: TagName::from(tag),
            binding: Binding::from(bind),
            attrs: attr_map,
            file: RelativePath::from("test.ts"),
            children: vec![],
        }
    }

    #[test]
    fn no_changes_produces_no_edits() {
        // Arrange
        let xml = r#"<controller bind="handle_create" method="POST" />"#;
        let annotations = vec![ann("controller", "handle_create", vec![("method", "POST")])];

        // Act
        let edits = sync_sidecar(xml, &annotations);

        // Assert
        assert!(
            edits.is_empty(),
            "identical content should produce no edits"
        );
    }

    #[test]
    fn added_annotation_appended() {
        // Arrange
        let xml = r#"<controller bind="handle_create" method="POST" />"#;
        let annotations = vec![
            ann("controller", "handle_create", vec![("method", "POST")]),
            ann("controller", "handle_delete", vec![("method", "DELETE")]),
        ];

        // Act
        let edits = sync_sidecar(xml, &annotations);

        // Assert
        assert_eq!(edits.len(), 1, "should have one append edit");
        assert!(
            edits[0].new_text.contains("handle_delete"),
            "appended text should contain new binding"
        );
    }

    #[test]
    fn removed_annotation_deleted() {
        // Arrange
        let xml = "<controller bind=\"handle_create\" method=\"POST\" />\n<controller bind=\"handle_delete\" method=\"DELETE\" />\n";
        let annotations = vec![ann("controller", "handle_create", vec![("method", "POST")])];

        // Act
        let edits = sync_sidecar(xml, &annotations);

        // Assert
        assert_eq!(edits.len(), 1, "should have one deletion edit");
        assert!(
            edits[0].new_text.is_empty(),
            "deletion edit should have empty replacement"
        );
    }

    #[test]
    fn changed_attribute_produces_replacement() {
        // Arrange
        let xml = r#"<controller bind="handle_create" method="POST" />"#;
        let annotations = vec![ann("controller", "handle_create", vec![("method", "PUT")])];

        // Act
        let edits = sync_sidecar(xml, &annotations);

        // Assert
        assert_eq!(edits.len(), 1, "should have one replacement edit");
        assert!(
            edits[0].new_text.contains("PUT"),
            "replacement should contain updated attribute"
        );
    }

    #[test]
    fn apply_edits_produces_correct_output() {
        // Arrange
        let xml = "<controller bind=\"handle_create\" method=\"POST\" />\n<controller bind=\"handle_delete\" method=\"DELETE\" />\n";
        let annotations = vec![ann("controller", "handle_create", vec![("method", "PUT")])];

        // Act
        let edits = sync_sidecar(xml, &annotations);
        let result = apply_edits(xml, &edits);

        // Assert
        assert!(
            result.contains("PUT"),
            "result should contain updated attribute"
        );
        assert!(
            !result.contains("handle_delete"),
            "result should not contain removed annotation"
        );
    }

    #[test]
    fn empty_binding_elements_preserved() {
        // Arrange
        let xml = "<meta version=\"1\" />\n<controller bind=\"handle_create\" method=\"POST\" />\n";
        let annotations = vec![ann("controller", "handle_create", vec![("method", "POST")])];

        // Act
        let edits = sync_sidecar(xml, &annotations);

        // Assert
        assert!(
            edits.is_empty(),
            "elements without bind should not be touched"
        );
    }
}