The World’s Most Advanced Diffing System

Installation

// Add to Package.swift
dependencies: [
    .package(url: "https://github.com/AgentiLoop/AgentD1F.git", from: "1.0.15")
]

Basic Usage

import MultiLineDiff

// Create a diff between two strings
let source = "Hello, world!"
let destination = "Hello, Swift!"

let diff = MultiLineDiff.createDiff(
    source: source,
    destination: destination,
    algorithm: .flash  // Fastest algorithm
)

// Apply the diff
let result = try MultiLineDiff.applyDiff(to: source, diff: diff)
print(result) // "Hello, Swift!"

AI-Friendly ASCII Format

// Generate ASCII diff for AI
let asciiDiff = MultiLineDiff.createAndDisplayDiff(
    source: source,
    destination: destination,
    format: .ai
)

print(asciiDiff)
// Output:
// 📎 Hello, 
// ❌ world
// ✅ Swift
// 📎 !

Round-Trip Workflow

// Parse ASCII diff back to operations
let parsedDiff = try MultiLineDiff.parseDiffFromASCII(asciiDiff)

// Apply parsed diff
let finalResult = try MultiLineDiff.applyDiff(to: source, diff: parsedDiff)
// Result: 100% accuracy guaranteed!

Symbol Rules

IMPORTANT: All diff symbols are EXACTLY two characters:

• 📎 (Paperclip + space): Retained/unchanged lines
• ❌ (Red X + space): Lines to be removed
• ✅ (Green checkmark + space): Lines to be added

Visual Meaning

Real-World Example

📎 class UserManager {
📎     private var users: [String: User] = [:]
✅     private var userCount: Int = 0
📎     
❌     func addUser(name: String, email: String) -> Bool {
✅     func addUser(name: String, email: String, age: Int = 0) -> Result {
📎         guard !name.isEmpty && !email.isEmpty else {
❌             return false
✅             return .failure(.invalidInput)
📎         }
📎         
❌         let user = User(name: name, email: email)
✅         let user = User(id: UUID(), name: name, email: email, age: age)
📎         users[email] = user
❌         return true
✅         userCount += 1
✅         return .success(user)
📎     }
📎 }

AI Integration Benefits

• Human Readable: Instantly understand changes
• AI Parseable: Perfect for LLM integration
• Version Control: Git-friendly format
• Documentation: Self-documenting patches
• Debugging: Visual diff inspection

📖 View Complete ASCII Diff Documentation →

Performance Comparison

⚡ Flash Algorithm

The fastest diff algorithm using Swift's native string manipulation methods (commonPrefix, commonSuffix).

// Flash Algorithm Usage
let diff = MultiLineDiff.createDiff(
    source: "Hello, world!",
    destination: "Hello, Swift!",
    algorithm: .flash
)

// Flash identifies:
// Prefix: "Hello, " (7 chars) → RETAIN
// Middle: "world" → DELETE, "Swift" → INSERT  
// Suffix: "!" (1 char) → RETAIN

🤖 Optimus Algorithm

Combines the power of CollectionDifference with line-aware processing.

// Optimus Algorithm Usage
let diff = MultiLineDiff.createDiff(
    source: sourceCode,
    destination: modifiedCode,
    algorithm: .optimus
)

// Optimus Process:
// 1. Split text into lines preserving line endings
// 2. Use CollectionDifference to find line changes
// 3. Convert to character-based operations
// 4. Consolidate consecutive operations

Algorithm Selection Guide

📖 View Complete Algorithm Documentation →

New Features Added

• 📝 Source Content Capture: Reconstructs complete source text
• 📝 Destination Content Capture: Reconstructs complete destination text
• 📍 Preceding Context: Captures the first line of the source
• 📍 Following Context: Captures the last line of the source
• 🎯 Source Start Line: Identifies exactly where modifications begin
• 📊 Source Total Lines: Total number of lines in the source

Source Start Line Explanation

The sourceStartLine pinpoints exactly where modifications begin:

Line 1: 📎 class Calculator {        (retain)
Line 2: 📎     private var result... (retain)
Line 3: ❌     func add(_ value...   (delete) ← MODIFICATIONS START HERE
Line 4: ❌         result += value   (delete)
Line 5: ❌     }                     (delete)
       ✅     func add(_ value...   (insert)
       ✅         result += value   (insert)
       ✅         return result     (insert)
       ✅     }                     (insert)

// Result: sourceStartLine = 2 (0-indexed, displayed as Line 3)

Enhanced Metadata Structure

DiffMetadata(
    sourceStartLine: 2,                    // NEW: Where modifications begin
    sourceTotalLines: 9,                   // Total source lines
    precedingContext: "class Calculator {", // First line of source
    followingContext: "}",                 // Last line of source
    sourceContent: "class Calculator {\n...", // Complete source
    destinationContent: "class Calculator {\n...", // Complete destination
    algorithmUsed: .megatron,
    applicationType: .requiresFullSource
)

Practical Benefits

📖 View Complete Parser Documentation →

🚀 Revolutionary Breakthrough

MultiLineDiff isn't just another diff tool—it's a complete paradigm shift that makes Git diff, Myers algorithm, copy-paste, line-number edits, and search-replace look like stone-age tools.

🔮 Unique Innovations Not Found Anywhere Else

// Flash: 3 operations, 14.5ms
// Optimus: 1256 operations, 43.7ms  
// IDENTICAL RESULTS: 100% character-perfect match

let undoDiff = MultiLineDiff.createUndoDiff(from: originalDiff)
// Instant rollback capability with zero configuration

🏆 Superiority Over Existing Solutions

🎯 The Bottom Line

MultiLineDiff isn't just better than Git diff, Myers algorithm, copy-paste, line edits, or search-replace—it makes them obsolete.

This is the first and only diffing system that:

• ✅ Preserves every character perfectly
• ✅ Handles truncated patches intelligently
• ✅ Provides cryptographic verification
• ✅ Generates automatic undo operations
• ✅ Works seamlessly with AI systems
• ✅ Offers multiple algorithms for any need
• ✅ Supports all I/O formats
• ✅ Maintains complete metadata

📖 View Complete Features Documentation →

Core Methods

public static func createDiff(
    source: String,
    destination: String,
    algorithm: DiffAlgorithm = .megatron,
    includeMetadata: Bool = true,
    sourceStartLine: Int? = nil,
    destStartLine: Int? = nil
) -> DiffResult

public static func applyDiff(
    to source: String,
    diff: DiffResult
) throws -> String

public static func createAndDisplayDiff(
    source: String,
    destination: String,
    format: DiffDisplayFormat,
    algorithm: DiffAlgorithm = .megatron
) -> String

public static func parseDiffFromASCII(_ asciiDiff: String) throws -> DiffResult

Algorithms

public enum DiffAlgorithm {
    case flash      // ⚡ Fastest (14.5ms)
    case optimus    // 🤖 Line-aware CollectionDiff
    case megatron   // 🧠 Semantic analysis (default)
    case starscream // 🌟 Swift native line processing
    case zoom       // 🔍 Simple character-based
}

Display Formats

public enum DiffDisplayFormat {
    case terminal   // Colored terminal output with ANSI codes
    case ai         // Plain ASCII output for AI models
}

Encoding Formats

public enum DiffEncoding {
    case base64     // Base64 encoded string
    case jsonString // JSON string representation
    case jsonData   // JSON data object
}

Example Usage

import MultiLineDiff

// Basic diff creation
let diff = MultiLineDiff.createDiff(
    source: "Hello, world!",
    destination: "Hello, Swift!",
    algorithm: .flash
)

// Apply diff
let result = try MultiLineDiff.applyDiff(to: source, diff: diff)

// ASCII format for AI
let asciiDiff = MultiLineDiff.createAndDisplayDiff(
    source: source,
    destination: destination,
    format: .ai
)

// Parse ASCII diff
let parsedDiff = try MultiLineDiff.parseDiffFromASCII(asciiDiff)

// Base64 encoding
let base64Diff = try MultiLineDiff.createBase64Diff(
    source: source,
    destination: destination
)

📖 View Complete Source Code →