Deep technical documentation for developers and advanced users.

1. Overview

This section provides detailed technical information about Canon’s internal algorithms, architectures, and extension points. Read this section if you:

  • Need to understand Canon’s implementation details

  • Want to contribute to Canon development

  • Are debugging complex comparison issues

  • Plan to extend Canon with custom comparators

2. What You’ll Learn

DOM Diff Internals

Deep dive into Canon’s default DOM diff algorithm: position-based matching, operation detection, and diff generation.

Semantic Tree Diff Internals

How the experimental semantic tree diff works: signature calculation, similarity matching, and operation classification.

Verbose Mode Architecture

The two-tier diff output system: normative vs informative diffs, and how verbose mode enriches output.

Diff Classification System

How Canon classifies differences as normative (structural) or informative (presentational).

Diff Pipeline Architecture

The six-layer technical pipeline from input to formatted output.

Extending Canon

How to create custom comparators, formatters, and match strategies.

3. Algorithm Deep Dives

3.1. DOM Diff Algorithm

The DOM diff algorithm is Canon’s stable, well-tested comparison strategy.

Key Components:

  • Position-based element matching

  • Line-by-line comparison

  • Context-aware grouping

  • Character-level visualization

When to use:

  • Similar documents with minor differences

  • Traditional diff output needed

  • Performance is critical

  • Stable, predictable behavior required

See DOM Diff Internals for implementation details.

3.2. Semantic Tree Diff Algorithm

The semantic tree diff is an experimental algorithm that understands document structure.

Key Components:

  • Signature-based node matching

  • Similarity scoring

  • Operation detection (INSERT, DELETE, UPDATE, MOVE)

  • Structural propagation

When to use:

  • Documents with significant restructuring

  • Move detection needed

  • Operation-based analysis desired

  • Willing to accept experimental status

See Semantic Tree Diff Internals for implementation details.

4. Architecture Patterns

4.1. The Orchestrator Pattern

Canon uses orchestrators to coordinate specialized workers:

class Comparison
  def self.compare(doc1, doc2, options = {})
    # Orchestrate: validation ā†’ parsing ā†’ matching ā†’ diffing
    validator.validate!(doc1, doc2)
    parsed1 = parser.parse(doc1)
    parsed2 = parser.parse(doc2)
    matcher.match(parsed1, parsed2, options)
  end
end

Benefits:

  • Clear separation of concerns

  • Easy to test individual components

  • Simple to add new formats or algorithms

4.2. The Adapter Pattern

Format-specific details are handled by adapters:

module TreeDiff
  module Adapters
    class XmlAdapter
      def create_tree_node(element)
        # XML-specific tree node creation
      end
    end

    class JsonAdapter
      def create_tree_node(object)
        # JSON-specific tree node creation
      end
    end
  end
end

See Extending Canon: Adapter Pattern for details.

5. Extension Points

Canon provides several extension points:

Custom Comparators

Implement format-specific comparison logic.

Custom Formatters

Create new output formats for diffs.

Custom Match Strategies

Define custom matching algorithms.

Custom Preprocessors

Add new preprocessing transformations.

See Extending Canon for implementation guides.

6. Performance Considerations

6.1. Algorithm Performance

DOM Diff:

  • Time complexity: O(n) for similar documents

  • Space complexity: O(n)

  • Best for: Documents with <10,000 nodes

Semantic Tree Diff:

  • Time complexity: O(nĀ²) in worst case

  • Space complexity: O(n)

  • Best for: Documents with <1,000 nodes

6.2. Optimization Strategies

  • Use size limits to prevent hangs

  • Enable preprocessing for normalized comparison

  • Choose appropriate diff algorithm

  • Configure context lines wisely

See Size Limits for configuration.

7. Debugging Canon

7.1. Enable Verbose Logging 

ENV['CANON_DEBUG'] = 'true'
result = Canon::Comparison.compare(doc1, doc2, verbose: true)

7.2. Inspect Internal Structures 

result = Canon::Comparison.compare(doc1, doc2)
puts result.operations  # For semantic diff
puts result.diff_report # Detailed report

7.3. Use Character Visualization 

result = Canon::Comparison.compare(doc1, doc2,
  verbose: true,
  visualize_whitespace: true
)

8. Next Steps

9. See Also