Trait SutureDriver 

pub trait SutureDriver: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn supported_extensions(&self) -> &[&str];
    fn diff(
        &self,
        base_content: Option<&str>,
        new_content: &str,
    ) -> Result<Vec<SemanticChange>, DriverError>;
    fn format_diff(
        &self,
        base_content: Option<&str>,
        new_content: &str,
    ) -> Result<String, DriverError>;

    // Provided methods
    fn merge(
        &self,
        _base: &str,
        _ours: &str,
        _theirs: &str,
    ) -> Result<Option<String>, DriverError> { ... }
    fn merge_raw(
        &self,
        base: &[u8],
        ours: &[u8],
        theirs: &[u8],
    ) -> Result<Option<Vec<u8>>, DriverError> { ... }
    fn diff_raw(
        &self,
        base: Option<&[u8]>,
        new_content: &[u8],
    ) -> Result<Vec<SemanticChange>, DriverError> { ... }
}

Format-specific driver for translating between file formats and Suture patches.

Implementations must be Send + Sync for concurrent use across threads. A driver understands the semantics of a file format — it knows that changing a key in a JSON object is a different operation than appending to an array.

Required Methods

fn name(&self) -> &str

Human-readable driver name (e.g., “JSON”, “OpenTimelineIO”, “CSV”).

fn supported_extensions(&self) -> &[&str]

File extensions this driver handles (e.g., [".json", ".jsonl"]).

fn diff( &self, base_content: Option<&str>, new_content: &str, ) -> Result<Vec<SemanticChange>, DriverError>

Parse a file and produce a semantic diff between it and an optional base.

If base_content is None, this is a new file — produce creation patches. If base_content is Some, produce patches representing the differences.

Each returned SemanticChange describes a meaningful semantic operation (e.g., “key users.2.email changed from old@example.com to new@example.com”).

fn format_diff( &self, base_content: Option<&str>, new_content: &str, ) -> Result<String, DriverError>

Produce a human-readable diff string between two versions of a file.

This is used by suture diff when a driver is available for the file type. The output should be more meaningful than raw line diffs — showing semantic operations like key changes, array insertions, etc.

Provided Methods

fn merge( &self, _base: &str, _ours: &str, _theirs: &str, ) -> Result<Option<String>, DriverError>

Perform a semantic three-way merge.

Given base, ours, and theirs content, produce a merged result. Returns None if the merge cannot be resolved automatically (conflict). Returns Some(merged_content) if the merge is clean.

fn merge_raw( &self, base: &[u8], ours: &[u8], theirs: &[u8], ) -> Result<Option<Vec<u8>>, DriverError>

Byte-level three-way merge for binary formats.

Like merge() but operates on raw bytes instead of &str. Binary drivers (DOCX, XLSX, PPTX, PDF, images) should override this to avoid unsafe { String::from_utf8_unchecked }. The default implementation converts to/from UTF-8 lossy and delegates to merge() — text drivers do not need to override this.

fn diff_raw( &self, base: Option<&[u8]>, new_content: &[u8], ) -> Result<Vec<SemanticChange>, DriverError>

Byte-level semantic diff for binary formats.

Like diff() but operates on raw bytes instead of &str. Binary drivers should override this to avoid unsafe conversions.

Implementors