canon 0.1.3 → 0.1.5

data/lib/canon/diff/diff_context.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "diff_block"
+
+module Canon
+  module Diff
+    # Represents a context - a group of diff blocks with surrounding context lines
+    # A context is created by grouping nearby diff blocks and expanding with context lines
+    class DiffContext
+      attr_reader :start_idx, :end_idx, :blocks, :lines
+      attr_accessor :normative
+
+      def initialize(start_line: nil, end_line: nil, start_idx: nil,
+                     end_idx: nil, blocks: [], lines: [], normative: nil)
+        # Support both old (start_idx/end_idx) and new (start_line/end_line) signatures
+        @start_idx = start_line || start_idx
+        @end_idx = end_line || end_idx
+        @blocks = blocks
+        @lines = lines
+        @normative = normative
+      end
+
+      # @return [Boolean] true if this context contains normative diffs
+      def normative?
+        @normative == true
+      end
+
+      # @return [Boolean] true if this context contains only informative diffs
+      def informative?
+        @normative == false
+      end
+
+      # Number of lines in this context (including context lines)
+      def size
+        end_idx - start_idx + 1
+      end
+
+      # Number of diff blocks in this context
+      def block_count
+        blocks.length
+      end
+
+      # Check if this context contains changes of a specific type
+      def includes_type?(type)
+        blocks.any? { |block| block.includes_type?(type) }
+      end
+
+      # Calculate gap to another context
+      def gap_to(other_context)
+        return Float::INFINITY if other_context.nil?
+        return 0 if overlaps?(other_context)
+
+        if other_context.start_idx > end_idx
+          other_context.start_idx - end_idx - 1
+        elsif start_idx > other_context.end_idx
+          start_idx - other_context.end_idx - 1
+        else
+          0
+        end
+      end
+
+      # Check if this context overlaps with another
+      def overlaps?(other_context)
+        return false if other_context.nil?
+
+        !(end_idx < other_context.start_idx || start_idx > other_context.end_idx)
+      end
+
+      def to_h
+        {
+          start_idx: start_idx,
+          end_idx: end_idx,
+          blocks: blocks.map(&:to_h),
+        }
+      end
+
+      def ==(other)
+        other.is_a?(DiffContext) &&
+          start_idx == other.start_idx &&
+          end_idx == other.end_idx &&
+          blocks == other.blocks
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_context_builder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "diff_context"
+
+module Canon
+  module Diff
+    # Builds DiffContexts from DiffBlocks
+    # Groups nearby blocks and adds surrounding context lines
+    class DiffContextBuilder
+      # Build contexts from diff blocks
+      #
+      # @param diff_blocks [Array<DiffBlock>] The diff blocks to group
+      # @param all_lines [Array<DiffLine>] All diff lines (for context)
+      # @param context_lines [Integer] Number of context lines to show
+      # @param grouping_lines [Integer, nil] Max lines between blocks to group them
+      # @return [Array<DiffContext>] Grouped contexts with context lines
+      def self.build_contexts(diff_blocks, all_lines, context_lines: 3,
+grouping_lines: nil)
+        new(diff_blocks, all_lines, context_lines, grouping_lines).build
+      end
+
+      def initialize(diff_blocks, all_lines, context_lines, grouping_lines)
+        @diff_blocks = diff_blocks
+        @all_lines = all_lines
+        @context_lines = context_lines
+        @grouping_lines = grouping_lines
+      end
+
+      def build
+        return [] if @diff_blocks.empty?
+
+        # Group nearby blocks if grouping_lines is specified
+        grouped_blocks = if @grouping_lines
+                           group_nearby_blocks(@diff_blocks, @grouping_lines)
+                         else
+                           @diff_blocks.map { |block| [block] }
+                         end
+
+        # Create contexts with context lines
+        contexts = grouped_blocks.map do |block_group|
+          create_context_for_blocks(block_group)
+        end
+
+        # Filter out all-informative contexts if show_diffs was :normative
+        # Note: The filtering based on show_diffs happens at the block level
+        # in DiffBlockBuilder, so we don't need to re-filter here.
+        # However, we should filter out contexts that have NO blocks
+        # (which could happen if all blocks were filtered out)
+        contexts.reject { |ctx| ctx.blocks.empty? }
+      end
+
+      private
+
+      # Group blocks that are close together
+      def group_nearby_blocks(blocks, max_gap)
+        return [] if blocks.empty?
+
+        groups = []
+        current_group = [blocks.first]
+
+        blocks[1..].each do |block|
+          prev_block = current_group.last
+          gap = block.start_idx - prev_block.end_idx - 1
+
+          if gap <= max_gap
+            # Close enough, add to current group
+            current_group << block
+          else
+            # Too far apart, start new group
+            groups << current_group
+            current_group = [block]
+          end
+        end
+
+        # Don't forget the last group
+        groups << current_group unless current_group.empty?
+        groups
+      end
+
+      # Create a context for a group of blocks
+      def create_context_for_blocks(block_group)
+        first_block = block_group.first
+        last_block = block_group.last
+
+        # Calculate context range
+        context_start = [first_block.start_idx - @context_lines, 0].max
+        context_end = [last_block.end_idx + @context_lines,
+                       @all_lines.length - 1].min
+
+        # Extract lines for this context
+        context_lines = @all_lines[context_start..context_end]
+
+        # Determine if context is normative
+        # A context is normative if ANY of its blocks are normative
+        normative = block_group.any?(&:normative?)
+
+        DiffContext.new(
+          start_line: context_start,
+          end_line: context_end,
+          blocks: block_group,
+          lines: context_lines,
+          normative: normative,
+        )
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_line.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Represents a single line in the diff output
+    # Links textual representation to semantic DiffNode
+    class DiffLine
+      attr_reader :line_number, :content, :type, :diff_node
+
+      # @param line_number [Integer] The line number in the original text
+      # @param content [String] The text content of the line
+      # @param type [Symbol] The type of line (:unchanged, :added, :removed, :changed)
+      # @param diff_node [DiffNode, nil] The semantic diff node this line belongs to
+      def initialize(line_number:, content:, type:, diff_node: nil)
+        @line_number = line_number
+        @content = content
+        @type = type
+        @diff_node = diff_node
+      end
+
+      # @return [Boolean] true if this line represents a normative difference
+      # If diff_node is nil (not linked to any semantic difference), the line
+      # is considered informative (cosmetic/unchanged)
+      def normative?
+        return false if diff_node.nil?
+
+        diff_node.normative?
+      end
+
+      # @return [Boolean] true if this line represents an informative-only difference
+      # If diff_node is nil (not linked), it's not informative either (it's unchanged/cosmetic)
+      def informative?
+        return false if diff_node.nil?
+
+        diff_node.informative?
+      end
+
+      # @return [Boolean] true if this line is unchanged
+      def unchanged?
+        type == :unchanged
+      end
+
+      # @return [Boolean] true if this line was added
+      def added?
+        type == :added
+      end
+
+      # @return [Boolean] true if this line was removed
+      def removed?
+        type == :removed
+      end
+
+      # @return [Boolean] true if this line was changed
+      def changed?
+        type == :changed
+      end
+
+      def to_h
+        {
+          line_number: line_number,
+          content: content,
+          type: type,
+          diff_node: diff_node&.to_h,
+          normative: normative?,
+        }
+      end
+
+      def ==(other)
+        other.is_a?(DiffLine) &&
+          line_number == other.line_number &&
+          content == other.content &&
+          type == other.type &&
+          diff_node == other.diff_node
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_node.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Represents a semantic difference between two nodes in a comparison tree
+    # This is created during the Comparison Layer and carries information about
+    # which dimension caused the difference and whether it's normative or informative
+    class DiffNode
+      attr_reader :node1, :node2, :dimension, :reason
+      attr_accessor :normative
+
+      # @param node1 [Object] The first node being compared
+      # @param node2 [Object] The second node being compared
+      # @param dimension [Symbol] The match dimension that caused this diff
+      #   (e.g., :text_content, :attribute_whitespace, :structural_whitespace,
+      #   :comments, :key_order)
+      # @param reason [String] Human-readable explanation of the difference
+      def initialize(node1:, node2:, dimension:, reason:)
+        @node1 = node1
+        @node2 = node2
+        @dimension = dimension
+        @reason = reason
+        @normative = nil # Will be set by DiffClassifier
+      end
+
+      # @return [Boolean] true if this diff is normative (affects equivalence)
+      def normative?
+        @normative == true
+      end
+
+      # @return [Boolean] true if this diff is informative only (doesn't affect equivalence)
+      def informative?
+        @normative == false
+      end
+
+      def to_h
+        {
+          node1: node1,
+          node2: node2,
+          dimension: dimension,
+          reason: reason,
+          normative: normative,
+        }
+      end
+
+      def ==(other)
+        other.is_a?(DiffNode) &&
+          node1 == other.node1 &&
+          node2 == other.node2 &&
+          dimension == other.dimension &&
+          reason == other.reason &&
+          normative == other.normative
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_node_mapper.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "diff_line"
+
+module Canon
+  module Diff
+    # Maps semantic DiffNodes to textual DiffLines
+    # This is Layer 2 of the diff pipeline, bridging semantic differences
+    # (from comparators) to textual representation (for formatters)
+    class DiffNodeMapper
+      # Map diff nodes to diff lines
+      #
+      # @param diff_nodes [Array<DiffNode>] The semantic differences
+      # @param text1 [String] The first text being compared
+      # @param text2 [String] The second text being compared
+      # @param options [Hash] Mapping options
+      # @option options [Hash] :line_map1 Pre-built line range map for text1
+      # @option options [Hash] :line_map2 Pre-built line range map for text2
+      # @return [Array<DiffLine>] Diff lines with semantic linkage
+      def self.map(diff_nodes, text1, text2, options = {})
+        new(diff_nodes, text1, text2, options).map
+      end
+
+      def initialize(diff_nodes, text1, text2, options = {})
+        @diff_nodes = diff_nodes
+        @text1 = text1
+        @text2 = text2
+        @line_map1 = options[:line_map1]
+        @line_map2 = options[:line_map2]
+      end
+
+      def map
+        lines1 = @text1.split("\n")
+        lines2 = @text2.split("\n")
+
+        # Use LCS to get structural diff
+        require "diff/lcs"
+        lcs_diffs = ::Diff::LCS.sdiff(lines1, lines2)
+
+        # Check if ALL DiffNodes are informative
+        all_informative = @diff_nodes && !@diff_nodes.empty? &&
+          @diff_nodes.all?(&:informative?)
+
+        # Convert LCS diffs to DiffLines
+        # If all DiffNodes are informative, we create a single shared informative DiffNode
+        # for all changed lines (this avoids complex linking)
+        shared_informative_node = if all_informative
+                                    @diff_nodes.first # Use any informative node
+                                  end
+
+        diff_lines = []
+        line_num = 0
+
+        lcs_diffs.each do |change|
+          diff_line = case change.action
+                      when "="
+                        DiffLine.new(
+                          line_number: line_num,
+                          content: change.old_element,
+                          type: :unchanged,
+                          diff_node: nil,
+                        )
+                      when "-"
+                        DiffLine.new(
+                          line_number: line_num,
+                          content: change.old_element,
+                          type: :removed,
+                          diff_node: shared_informative_node || find_diff_node_for_line(
+                            line_num, lines1, :removed
+                          ),
+                        )
+                      when "+"
+                        DiffLine.new(
+                          line_number: line_num,
+                          content: change.new_element,
+                          type: :added,
+                          diff_node: shared_informative_node || find_diff_node_for_line(
+                            line_num, lines2, :added
+                          ),
+                        )
+                      when "!"
+                        DiffLine.new(
+                          line_number: line_num,
+                          content: change.new_element,
+                          type: :changed,
+                          diff_node: shared_informative_node || find_diff_node_for_line(
+                            line_num, lines2, :changed
+                          ),
+                        )
+                      end
+
+          diff_lines << diff_line
+          line_num += 1
+        end
+
+        diff_lines
+      end
+
+      private
+
+      # Find the DiffNode associated with a line
+      # Uses element name matching for precise line-level linking
+      def find_diff_node_for_line(line_num, lines, change_type)
+        return nil if @diff_nodes.nil? || @diff_nodes.empty?
+
+        line_content = lines[line_num]
+        return nil if line_content.nil?
+
+        # Extract element name from the line
+        line_element_name = extract_element_name(line_content)
+        return nil unless line_element_name
+
+        # Find DiffNode whose element name matches this line's element
+        @diff_nodes.find do |diff_node|
+          # For changed lines, we need to check BOTH nodes since the line
+          # could represent either the old or new content
+          nodes_to_check = case change_type
+                           when :removed
+                             [diff_node.node1]
+                           when :added
+                             [diff_node.node2]
+                           when :changed
+                             # Check both old and new - the line could be either
+                             [diff_node.node1, diff_node.node2]
+                           end
+
+          nodes_to_check.any? do |node|
+            next unless node.respond_to?(:name)
+
+            node.name == line_element_name
+          end
+        end
+      end
+
+      # Extract element name from an XML line
+      # Examples:
+      #   "<bibitem ...>" => "bibitem"
+      #   "</bibitem>" => "bibitem"
+      #   "<ns:element ...>" => "ns:element"
+      def extract_element_name(line)
+        # Match opening or closing tag: <element ...> or </element>
+        # Supports namespaces (e.g., ns:element)
+        match = line.match(/<\/?([a-zA-Z0-9_:-]+)/)
+        match[1] if match
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_report.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Represents a complete diff report containing multiple contexts
+    #
+    # A DiffReport is the top-level container for diff results between two
+    # documents. It contains multiple DiffContext objects, each representing
+    # a region with changes and surrounding context lines.
+    #
+    # @example Creating a diff report
+    #   report = DiffReport.new(
+    #     element_name: "root",
+    #     file1_name: "expected.xml",
+    #     file2_name: "actual.xml"
+    #   )
+    #   report.add_context(context1)
+    #   report.add_context(context2)
+    #
+    # @attr_reader element_name [String] name of the root element being compared
+    # @attr_reader file1_name [String] name/path of the first file
+    # @attr_reader file2_name [String] name/path of the second file
+    # @attr_reader contexts [Array<DiffContext>] array of diff contexts
+    class DiffReport
+      attr_reader :element_name, :file1_name, :file2_name, :contexts
+
+      # Initialize a new diff report
+      #
+      # @param element_name [String] name of the root element being compared
+      # @param file1_name [String, nil] name/path of the first file
+      # @param file2_name [String, nil] name/path of the second file
+      # @param contexts [Array<DiffContext>] initial array of contexts
+      def initialize(element_name:, file1_name: nil, file2_name: nil,
+                     contexts: [])
+        @element_name = element_name
+        @file1_name = file1_name
+        @file2_name = file2_name
+        @contexts = contexts
+      end
+
+      # Add a context to the report
+      #
+      # @param context [DiffContext] the context to add
+      # @return [self] returns self for method chaining
+      def add_context(context)
+        @contexts << context
+        self
+      end
+
+      # Get the total number of contexts in the report
+      #
+      # @return [Integer] number of contexts
+      def context_count
+        contexts.length
+      end
+
+      # Get the total number of diff blocks across all contexts
+      #
+      # @return [Integer] total number of blocks
+      def block_count
+        contexts.sum(&:block_count)
+      end
+
+      # Get the total number of changes (sum of all block sizes)
+      #
+      # @return [Integer] total number of changed lines
+      def change_count
+        contexts.sum do |context|
+          context.blocks.sum(&:size)
+        end
+      end
+
+      # Check if the report has any differences
+      #
+      # @return [Boolean] true if there are any contexts with differences
+      def has_differences?
+        !contexts.empty?
+      end
+
+      # Check if the report contains a specific change type
+      #
+      # @param type [String] the change type to check for ('+', '-', '!')
+      # @return [Boolean] true if any context includes this type
+      def includes_type?(type)
+        contexts.any? { |context| context.includes_type?(type) }
+      end
+
+      # Filter contexts by change type
+      #
+      # @param type [String] the change type to filter by ('+', '-', '!')
+      # @return [Array<DiffContext>] contexts that include the given type
+      def contexts_with_type(type)
+        contexts.select { |context| context.includes_type?(type) }
+      end
+
+      # Get summary statistics about the diff
+      #
+      # @return [Hash] hash with keys: :contexts, :blocks, :changes
+      def summary
+        {
+          contexts: context_count,
+          blocks: block_count,
+          changes: change_count,
+        }
+      end
+
+      # Convert to hash representation
+      #
+      # @return [Hash] hash representation of the report
+      def to_h
+        {
+          element_name: element_name,
+          file1_name: file1_name,
+          file2_name: file2_name,
+          contexts: contexts.map(&:to_h),
+          summary: summary,
+        }
+      end
+
+      # Compare equality with another report
+      #
+      # @param other [DiffReport] the report to compare with
+      # @return [Boolean] true if reports are equal
+      def ==(other)
+        other.is_a?(DiffReport) &&
+          element_name == other.element_name &&
+          file1_name == other.file1_name &&
+          file2_name == other.file2_name &&
+          contexts == other.contexts
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_report_builder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "diff_report"
+require_relative "diff_block_builder"
+require_relative "diff_context_builder"
+
+module Canon
+  module Diff
+    # Builds a complete DiffReport from DiffLines
+    # Orchestrates the pipeline: DiffLines → DiffBlocks → DiffContexts → DiffReport
+    class DiffReportBuilder
+      # Build a diff report from diff lines
+      #
+      # @param diff_lines [Array<DiffLine>] The diff lines to process
+      # @param options [Hash] Build options
+      # @option options [Symbol] :show_diffs (:all) Filter setting (:normative, :informative, :all)
+      # @option options [Integer] :context_lines (3) Number of context lines
+      # @option options [Integer, nil] :grouping_lines (nil) Max lines between blocks to group
+      # @option options [String] :element_name ("root") Name of element being compared
+      # @option options [String, nil] :file1_name (nil) Name of first file
+      # @option options [String, nil] :file2_name (nil) Name of second file
+      # @return [DiffReport] The complete diff report
+      def self.build(diff_lines, options = {})
+        new(diff_lines, options).build
+      end
+
+      def initialize(diff_lines, options = {})
+        @diff_lines = diff_lines
+        @show_diffs = options[:show_diffs] || :all
+        @context_lines = options[:context_lines] || 3
+        @grouping_lines = options[:grouping_lines]
+        @element_name = options[:element_name] || "root"
+        @file1_name = options[:file1_name]
+        @file2_name = options[:file2_name]
+      end
+
+      def build
+        # Step 1: Build blocks from lines (with filtering)
+        diff_blocks = DiffBlockBuilder.build_blocks(
+          @diff_lines,
+          show_diffs: @show_diffs,
+        )
+
+        # Step 2: Build contexts from blocks
+        diff_contexts = DiffContextBuilder.build_contexts(
+          diff_blocks,
+          @diff_lines,
+          context_lines: @context_lines,
+          grouping_lines: @grouping_lines,
+        )
+
+        # Step 3: Wrap in DiffReport
+        DiffReport.new(
+          element_name: @element_name,
+          file1_name: @file1_name,
+          file2_name: @file2_name,
+          contexts: diff_contexts,
+        )
+      end
+    end
+  end
+end