feat: Add programmatic diff access API with Redline dataclass

[houfu]

Summary

Adds a user-friendly programmatic API for accessing and filtering diff results without parsing output strings.

Resolves #58

New Features

🎯 Redline Dataclass

• Structured representation of changes (delete, insert, replace)
• Direct access to changed text via source_text and test_text
• Token position information via source_position and test_position
• Excludes "equal" operations (only actual changes)

📊 Properties

• r.changes - Returns list of Redline objects
• r.redlines - Alias for changes (more intuitive naming)
• Both exclude "equal" operations automatically

🔍 Filtering API

r.get_changes(operation="delete")    # Filter deletions
r.get_changes(operation="insert")    # Filter insertions
r.get_changes(operation="replace")   # Filter replacements
r.get_changes()                       # Get all changes

📈 Statistics API

stats = r.stats()
print(f"Total changes: {stats.total_changes}")
print(f"Deletions: {stats.deletions}")
print(f"Insertions: {stats.insertions}")
print(f"Replacements: {stats.replacements}")

⚠️ BREAKING CHANGES

The r.redlines property return type has changed:

• Before: Returned internal objects (included "equal" operations)
• After: Returns public Redline dataclass objects (only actual changes)

Impact: Minimal - r.redlines was primarily used internally. All rendering methods (output_markdown, output_rich) continue to work unchanged.

API Example

from redlines import Redlines, Redline, Stats

test = Redlines(
    "The quick brown fox jumps over the lazy dog.",
    "The quick brown fox walks past the lazy dog."
)

# Access changes
for redline in test.redlines:
    print(f"{redline.operation}: {redline.source_text} -> {redline.test_text}")
# Output: replace: jumps over  -> walks past 

# Filter changes
replacements = test.get_changes(operation="replace")

# Get statistics
stats = test.stats()
print(f"Total changes: {stats.total_changes}")  # 1

Testing

• ✅ Added 17 comprehensive tests in test_changes_api.py
• ✅ All 30 tests pass
• ✅ Covers replacements, insertions, deletions, filtering, stats, edge cases

Implementation Details

Internal Refactoring

• Renamed internal Redline class to DiffOperation (for rendering)
• Created public Redline class (user-facing API)
• Added r._diff_ops internal property for rendering code
• Maintains backward compatibility for all rendering methods

Improvements Over Original Proposal

1. ✅ Better naming: "Redline" instead of "Change" (matches library domain)
2. ✅ Separate source_text & test_text fields (more useful than single 'text')
3. ✅ Excludes "equal" operations (only actual changes)
4. ✅ Added r.redlines as intuitive primary property
5. ✅ Comprehensive documentation with code examples

🤖 Generated with Claude Code