feat: Add JSON output format for machine-readable diffs (#60)

[houfu]

Summary

Adds JSON output format to make diff results easily parseable by AI agents and automation tools.

Closes #60

Changes

New API Method

from redlines import Redlines
import json

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

# Get JSON output
json_output = r.output_json(pretty=True)
data = json.loads(json_output)

# Access changes programmatically
for change in data["changes"]:
    if change["type"] == "replace":
        print(f"Changed '{change['source_text']}' to '{change['test_text']}'")

JSON Output Structure

The JSON includes complete diff information:

• Source and test texts - Original strings being compared
• Token arrays - How the text was parsed internally
• Changes array - All diff operations (equal, insert, delete, replace)
• Statistics - Change counts and summary

Hybrid Position System

Each change provides both position types for maximum flexibility:

• Character positions [start, end] - For direct string slicing (e.g., source[20:31])
• Token positions [start, end] - For understanding internal representation

This design allows users to choose the most convenient approach for their use case while maintaining full transparency into how Redlines processes
the text.

Example Output

  {
    "source": "The quick brown fox jumps over the lazy dog.",
    "test": "The quick brown fox walks past the lazy dog.",
    "source_tokens": ["The ", "quick ", "brown ", "fox ", "jumps ", "over ", "the ", "lazy ", "dog."],
    "test_tokens": ["The ", "quick ", "brown ", "fox ", "walks ", "past ", "the ", "lazy ", "dog."],
    "changes": [
      {
        "type": "equal",
        "text": "The quick brown fox ",
        "source_position": [0, 20],
        "test_position": [0, 20],
        "source_token_position": [0, 4],
        "test_token_position": [0, 4]
      },
      {
        "type": "replace",
        "source_text": "jumps over ",
        "test_text": "walks past ",
        "source_position": [20, 31],
        "test_position": [20, 31],
        "source_token_position": [4, 6],
        "test_token_position": [4, 6]
      },
      {
        "type": "equal",
        "text": "the lazy dog.",
        "source_position": [31, 44],
        "test_position": [31, 44],
        "source_token_position": [6, 9],
        "test_token_position": [6, 9]
      }
    ],
    "stats": {
      "deletions": 0,
      "insertions": 0,
      "replacements": 1,
      "unchanged": 2,
      "total_changes": 1
    }
  }

Design Decisions

1. Keep "replace" as single operation - Maintains semantic meaning rather than decomposing into delete+insert
2. Include "equal" operations - Provides complete diff representation, not just changes
3. Expose token lists - Full transparency into tokenization process
4. Hybrid positions - Both character (convenience) and token (internal representation) positions

Files Changed

• redlines/redlines.py - Added output_json() method with pretty-print support
• redlines/json_schema.json - JSON Schema Draft 7 specification
• tests/test_json_output.py - Comprehensive test suite (16 test cases)

Testing

• ✅ All 46 tests passing (16 new tests for JSON output)
• ✅ 96% code coverage on redlines.py
• ✅ mypy type checking passes
• ✅ Handles unicode, special characters, and edge cases
• ✅ Position accuracy verified for both character and token levels

Backwards Compatibility

This is a purely additive change - no existing functionality is modified. All existing tests continue to pass.