nokodiff 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec76ca57f4fd914bc778242d825a9a074dd39bff32b8467e4729592f31bfb0ab
-  data.tar.gz: 67de4318dc9d455b212a8199c2039acfbf63b2b078c90e06e26e0ac00a3f17ef
+  metadata.gz: e12bce0257af1ebff2c6de595dce5d68cefc73feb5ae4a419a98a81d9dbac212
+  data.tar.gz: 9479aa3c4ae7f3481a0a96baf002735fb02a4848530a9fc38565c72118e4a2eb
 SHA512:
-  metadata.gz: 7995f2fd1718a72f5288112d3dddc51c8305ba319b5ab383712ea484095b52083d6c40ee3738f2964456919fa634f2ea10119cae814665c947d24d28d2a7a638
-  data.tar.gz: a301b0efba48e0ce790b3743e8477dfaaca41e6c9e242f60cbd0d474acb51619eb44ec0f68bb7da00e8c5a0d73582080602d2823ab81bd4f7c686a51d6291f84
+  metadata.gz: 864f165ec8332dbcc0a61cffda45f6649ed00d5483e969ad7d55dc9af2e4acdbe202f54686424ff387f6f36ecd160b3834e89f4d1633a8bf311534b6c09eb0b3
+  data.tar.gz: f182809b76cf85e8ce23002575fb5c2708e527cd3659628d0ef248fdce79e1581ed6a551f99ca41a16dff7bacf9d67db87579185761052136e3f491d227f8bf6

data/README.md

@@ -1,7 +1,165 @@
 # Nokodiff
 
-A Ruby Gem to highlight additions, deletions and character level changes while preserving original HTML
+A Ruby Gem to highlight additions, deletions and character level changes while preserving original HTML.
+
+It includes functionality to:
+* Compare two HTML fragments and output diffs with semantic HTML
+* Inline character differences highlighting using `<strong>` tagging
+* Blocks of added or removed content wrapped in aria labelled `<ins>` and `<del>` tags
+* Optional CSS for styling the visual differences
+
+## Installation
+
+Install the gem:
+
+```
+gem install nokodiff
+```
+
+or add it to your Gemfile
+
+```
+gem "nokodiff"
+```
+
+## Usage
+
+In the controller:
+```ruby
+require 'nokodiff'
+
+before_html = < YOUR HTML >
+after_html = < YOUR HTML >
+
+@differ = Nokodiff.diff(before_html, after_html)
+```
+
+In the erb file:
+```erb
+<div>
+  <%= @differ %>
+</div>
+```
+
+### Including the CSS
+
+In your application.scss file include:
+```scss
+@import "nokodiff";
+```
+
+This will include the styling for `<del>`, `<ins>` and `<strong>` tags to allow colour coding, highlighting and underlining of changes.
+
+### More complex diffing with `data-diff-key`
+
+For more complex HTML structures, a standard diff can produce surprising or misleading results when elements are added, removed, or reordered. To get around this, add a `data-diff-key` attribute to elements you want compared in isolation.
+
+Each element with a unique `data-diff-key` value is diffed independently against its counterpart in the other HTML fragment. This prevents unrelated changes from affecting each other and produces more accurate, contextually meaningful output.
+
+The key value can be any unique string — it just needs to match between your `before` and `after` HTML for the elements you want paired together.
+
+#### Adding a new element
+
+When a `data-diff-key` element is present in `after` but not in `before`, its content is wrapped in an `<ins>` tag:
+
+```ruby
+before = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+  </div>
+HTML
+
+after = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+    <div data-diff-key="zm7q">
+      <p>Second paragraph</p>
+    </div>
+  </div>
+HTML
+
+Nokodiff.diff(before, after)
+```
+
+Output:
+
+```html
+<div>
+  <div data-diff-key="ixn4">
+    <p>First paragraph</p>
+  </div>
+  <div data-diff-key="zm7q">
+    <div class="diff">
+      <ins aria-label="added content"><p>Second paragraph</p></ins>
+    </div>
+  </div>
+</div>
+```
+
+![Adding a new element](docs/adding-a-new-element.png)
+
+#### Modifying an existing element
+
+When a `data-diff-key` element exists in both fragments but its content has changed, the element is diffed in isolation. Character-level changes are highlighted within `<del>` and `<ins>` tags:
+
+```ruby
+before = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+    <div data-diff-key="zm7q">
+      <p>Second paragraph</p>
+    </div>
+  </div>
+HTML
+
+after = <<~HTML
+  <div>
+    <div data-diff-key="ixn4">
+      <p>First paragraph</p>
+    </div>
+    <div data-diff-key="zm7q">
+      <p>New paragraph</p>
+    </div>
+  </div>
+HTML
+
+Nokodiff.diff(before, after)
+```
+
+Output:
+
+```html
+<div>
+  <div data-diff-key="ixn4"><p>First paragraph</p></div>
+  <div data-diff-key="zm7q">
+    <div class="diff">
+      <del aria-label="removed content"><p><strong>S</strong>e<strong>cond</strong> paragraph</p></del>
+    </div>
+    <div class="diff">
+      <ins aria-label="added content"><p><strong>N</strong>e<strong>w</strong> paragraph</p></ins>
+    </div>
+  </div>
+</div>
+```
+
+![Modifying an existing element](docs/modifying-an-existing-element.png)
+
+#### Unchanged elements
+
+If a `data-diff-key` element's content is identical in both fragments, no diff markup is added and the element is returned as-is.
+
+#### Limitations
+
+Currently, the gem does not support highlighting removed `data-diff-key` elements. If a keyed element is present in `before` but absent from `after`, it will not be marked as deleted in the output.
+
+Thanks to [HTML Diff](https://html-diff.lix.dev/index.html) for inspiring this approach!
 
 ## Licence
 
-The gem is available as open source under the terms of the [MIT License.](https://opensource.org/license/MIT)
+The gem is available as open source under the terms of the [MIT License.](https://opensource.org/license/MIT)

data/app/assets/stylesheets/nokodiff.scss

@@ -0,0 +1,75 @@
+// stylelint-disable selector-no-qualifying-type, max-nesting-depth
+// Diff of two editions
+$added-color: #e6fff3;
+$strong-added-color: #99ffcf;
+$removed-color: #fadede;
+$strong-removed-color: #f3aeac;
+$text-colour: #0b0c0c;
+$light-grey: #f3f2f1;
+$black: #0b0c0c;
+
+.compare-editions {
+  border: 1px solid $light-grey;
+  border-left: 40px solid $light-grey;
+  padding: 15px;
+
+  .diff {
+    margin: 0 -15px;
+    padding: 0 15px;
+    word-wrap: break-word;
+    margin-bottom: 10px;
+    position: relative;
+
+    del,
+    ins {
+      text-decoration: none;
+      display: block;
+      padding: 2px 4px;
+      border-radius: 3px;
+    }
+  }
+
+  del {
+    background-color: $removed-color;
+    padding-bottom: 2px;
+
+    strong {
+      font-weight: normal;
+      background-color: $strong-removed-color;
+      border-bottom: 2px dashed $black;
+    }
+  }
+
+  ins {
+    background-color: $added-color;
+    padding-bottom: 2px;
+
+    strong {
+      font-weight: normal;
+      background-color: $strong-added-color;
+      border-bottom: 2px dashed $black;
+    }
+  }
+
+  del::before,
+  ins::before {
+    position: absolute;
+    margin-left: -59px;
+    width: 40px;
+    text-align: center;
+    top: 0;
+    bottom: 0;
+  }
+
+  del::before {
+    color: $text-colour;
+    background-color: $strong-removed-color;
+    content: "−";
+  }
+
+  ins::before {
+    color: $text-colour;
+    background-color: $strong-added-color;
+    content: "+";
+  }
+}

data/lib/nokodiff/changes_in_fragments.rb

@@ -0,0 +1,67 @@
+module Nokodiff
+  class ChangesInFragments
+    include FormattingHelpers
+    def initialize(diff)
+      @diff = diff
+      @before_fragment = Nokogiri::HTML::DocumentFragment.parse("")
+      @after_fragment = Nokogiri::HTML::DocumentFragment.parse("")
+
+      @accumulated_before_text = ""
+      @accumulated_after_text = ""
+    end
+
+    def call
+      @diff.each do |change|
+        case change.action
+        when "="
+          no_change_emphasis(change)
+        when "!"
+          emphasise_change(change)
+        when "-"
+          emphasise_deletion(change)
+        when "+"
+          emphasise_addition(change)
+        end
+      end
+
+      append_accumulated_text(before_fragment, accumulated_before_text)
+      append_accumulated_text(after_fragment, accumulated_after_text)
+
+      [before_fragment, after_fragment]
+    end
+
+  private
+
+    attr_accessor :before_fragment, :after_fragment, :accumulated_before_text, :accumulated_after_text
+
+    def no_change_emphasis(change)
+      accumulated_before_text << change.old_element
+      accumulated_after_text << change.new_element
+    end
+
+    def emphasise_change(change)
+      append_accumulated_text(before_fragment, accumulated_before_text)
+      append_accumulated_text(after_fragment, accumulated_after_text)
+
+      before_fragment.add_child(wrap_in_strong(change.old_element, before_fragment))
+      after_fragment.add_child(wrap_in_strong(change.new_element, after_fragment))
+    end
+
+    def emphasise_deletion(change)
+      append_accumulated_text(before_fragment, accumulated_before_text)
+      before_fragment.add_child(wrap_in_strong(change.old_element, before_fragment))
+    end
+
+    def emphasise_addition(change)
+      append_accumulated_text(after_fragment, accumulated_after_text)
+      after_fragment.add_child(wrap_in_strong(change.new_element, after_fragment))
+    end
+
+    def append_accumulated_text(fragment, accumulated_text)
+      return if accumulated_text.empty?
+
+      fragment.add_child(Nokogiri::XML::Text.new(accumulated_text, fragment))
+      accumulated_text.clear
+    end
+  end
+end

data/lib/nokodiff/differ.rb

@@ -0,0 +1,103 @@
+module Nokodiff
+  class Differ
+    def initialize(before, after)
+      @before = before
+      @after = after
+    end
+
+    def to_html
+      compared_blocks.map { |diff|
+        case diff[:status]
+        when :unchanged
+          unchanged_block(diff[:before])
+        when :changed
+          deleted_block(char_diff_html(diff[:before], diff[:after]).first) + added_block(char_diff_html(diff[:before], diff[:after]).last)
+        when :deleted
+          deleted_block(diff[:before])
+        when :added
+          added_block(diff[:after])
+        end
+      }.join("\n")
+    end
+
+  private
+
+    def compared_blocks
+      before_nodes = @before.children.to_a
+      after_nodes = @after.children.to_a
+
+      max = [before_nodes.length, after_nodes.length].max
+
+      max.times.map do |i|
+        before_node = before_nodes[i]
+        after_node = after_nodes[i]
+
+        set_change_status(before_node, after_node)
+      end
+    end
+
+    def char_diff_html(before_html, after_html)
+      before_dup = before_html.dup
+      after_dup = after_html.dup
+
+      before_fragment, after_fragment = Nokodiff::TextNodeDiffs.new(before_dup, after_dup).call
+
+      merge_adjacent_strong_tags(before_fragment)
+      merge_adjacent_strong_tags(after_fragment)
+
+      [before_fragment.to_html, after_fragment.to_html]
+    end
+
+    def set_change_status(before_node, after_node)
+      if before_node && after_node
+        if before_node.to_html.strip == after_node.to_html.strip
+          { status: :unchanged, before: before_node, after: after_node }
+        else
+          { status: :changed, before: before_node, after: after_node }
+        end
+      elsif before_node
+        { status: :deleted, before: before_node, after: nil }
+      elsif after_node
+        { status: :added, before: nil, after: after_node }
+      end
+    end
+
+    def merge_adjacent_strong_tags(node)
+      return unless node.element?
+
+      node.children.each do |child|
+        merge_adjacent_strong_tags(child) if child.element?
+      end
+
+      node.children.each_cons(2) do |left, right|
+        next unless left.name == "strong" && right.name == "strong"
+
+        left.content = left.content + right.content
+        right.remove
+
+        merge_adjacent_strong_tags(node)
+        break
+      end
+    end
+
+    def unchanged_block(html)
+      html.to_s
+    end
+
+    def deleted_block(html)
+      %(
+        <div class="diff">
+           <del aria-label="removed content">#{html}</del>
+        </div>
+      )
+    end
+
+    def added_block(html)
+      %(
+        <div class="diff">
+           <ins aria-label="added content">#{html}</ins>
+        </div>
+      )
+    end
+  end
+end

data/lib/nokodiff/engine.rb

@@ -0,0 +1,7 @@
+return unless defined?(Rails)
+
+module Nokodiff
+  class Engine < ::Rails::Engine
+    isolate_namespace Nokodiff
+  end
+end

data/lib/nokodiff/formatting_helpers.rb

@@ -0,0 +1,11 @@
+module Nokodiff
+  module FormattingHelpers
+    def wrap_in_strong(char, fragment)
+      Nokogiri::XML::Node.new("strong", fragment.document).tap { |n| n.content = char }
+    end
+
+    def strong(text_node)
+      text_node.replace(wrap_in_strong(text_node.to_html, text_node.parent))
+    end
+  end
+end

data/lib/nokodiff/html_fragment.rb

@@ -0,0 +1,40 @@
+require "forwardable"
+
+module Nokodiff
+  class HTMLFragment
+    extend Forwardable
+
+    class InvalidHTMLError < StandardError; end
+
+    def initialize(html)
+      @fragment = Nokogiri::HTML.fragment(html)
+      validate!
+      remove_blank_nodes!
+      remove_comments!
+    end
+
+    def_delegators :@fragment, :children, :css, :at, :to_html
+
+  private
+
+    def validate!
+      invalid_text_nodes = @fragment.children.reject do |node|
+        node.element? || node.comment? || (node.text? && node.text.strip.empty?)
+      end
+
+      unless invalid_text_nodes.empty?
+        raise InvalidHTMLError, "Invalid HTML input: #{@fragment.to_html}"
+      end
+    end
+
+    def remove_blank_nodes!
+      @fragment.traverse do |node|
+        node.remove if node.blank?
+      end
+    end
+
+    def remove_comments!
+      @fragment.css("comment()").remove
+    end
+  end
+end

data/lib/nokodiff/text_node_diffs.rb

@@ -0,0 +1,56 @@
+module Nokodiff
+  class TextNodeDiffs
+    include FormattingHelpers
+    def initialize(before_fragment, after_fragment)
+      @before_fragment = before_fragment
+      @after_fragment = after_fragment
+    end
+
+    def call
+      diff_text_nodes(before_fragment, after_fragment)
+      [before_fragment, after_fragment]
+    end
+
+  private
+
+    attr_accessor :before_fragment, :after_fragment
+
+    def diff_text_nodes(before_node, after_node)
+      if before_node&.text? || after_node&.text?
+        diff_text_node_content(before_node, after_node)
+      elsif before_node&.element? || after_node&.element?
+        before_children = before_node ? before_node.children.to_a : []
+        after_children = after_node ? after_node.children.to_a : []
+
+        max_child_count = [before_children.length, after_children.length].max
+
+        (0..max_child_count).each do |i|
+          diff_text_nodes(before_children[i], after_children[i])
+        end
+      end
+    end
+
+    def diff_text_node_content(before_text_node, after_text_node)
+      return strong(before_text_node) if text_removed?(before_text_node, after_text_node)
+      return strong(after_text_node) if text_added?(before_text_node, after_text_node)
+
+      before_chars = before_text_node.text.chars
+      after_chars = after_text_node.text.chars
+
+      diff = Diff::LCS.sdiff(before_chars, after_chars)
+
+      before_fragment, after_fragment = Nokodiff::ChangesInFragments.new(diff).call
+
+      before_text_node.replace(before_fragment)
+      after_text_node.replace(after_fragment)
+    end
+
+    def text_removed?(before_node, after_node)
+      before_node && after_node.nil?
+    end
+
+    def text_added?(before_node, after_node)
+      before_node.nil? && after_node
+    end
+  end
+end

data/lib/nokodiff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Nokodiff
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/nokodiff.rb

@@ -1,8 +1,51 @@
 # frozen_string_literal: true
 
+require "nokogiri"
+require "diff-lcs"
+
+require_relative "nokodiff/formatting_helpers"
 require_relative "nokodiff/version"
+require_relative "nokodiff/differ"
+require_relative "nokodiff/engine"
+require_relative "nokodiff/text_node_diffs"
+require_relative "nokodiff/changes_in_fragments"
+require_relative "nokodiff/html_fragment"
 
 module Nokodiff
-  class Error < StandardError; end
-  # Your code goes here...
+  def self.diff(before_html, after_html)
+    before = Nokodiff::HTMLFragment.new(before_html)
+    after = Nokodiff::HTMLFragment.new(after_html)
+
+    before_nodes, after_nodes = nodes(before, after)
+    keys = (before_nodes.keys + after_nodes.keys).uniq
+
+    html = keys.any? ? diff_by_keys(after, keys, before_nodes, after_nodes) : Differ.new(before, after).to_html
+    safe_html(html)
+  end
+
+  def self.safe_html(html)
+    html.respond_to?(:html_safe) ? html.html_safe : html
+  end
+
+  private_class_method def self.nodes(before, after)
+    [
+      fetch_diff_nodes(before),
+      fetch_diff_nodes(after),
+    ]
+  end
+
+  private_class_method def self.fetch_diff_nodes(fragment)
+    fragment.css("[data-diff-key]").map { |node| [node["data-diff-key"], node] }.to_h
+  end
+
+  private_class_method def self.diff_by_keys(after, keys, before_nodes, after_nodes)
+    keys.each do |key|
+      diff = Differ.new(
+        before_nodes.fetch(key, Nokogiri::HTML.fragment("")),
+        after_nodes.fetch(key, Nokogiri::HTML.fragment("")),
+      ).to_html
+      after.at("[data-diff-key='#{key}']")&.inner_html = diff
+    end
+    after.to_html
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nokodiff
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - GOV.UK Dev
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -57,14 +71,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.1.20
+        version: 5.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 5.1.20
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -88,7 +102,7 @@ dependencies:
         version: '6'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 8.1.2
+        version: 8.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -98,21 +112,41 @@ dependencies:
         version: '6'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 8.1.2
+        version: 8.1.3
+- !ruby/object:Gem::Dependency
+  name: diff-lcs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: gds-api-adapters
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '101.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 101.0.0
+        version: '101.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '101.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 101.0.0
+        version: '101.3'
 - !ruby/object:Gem::Dependency
   name: govspeak
   requirement: !ruby/object:Gem::Requirement
@@ -136,7 +170,7 @@ dependencies:
         version: '6'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 8.1.2
+        version: 8.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -146,7 +180,7 @@ dependencies:
         version: '6'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 8.1.2
+        version: 8.1.3
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -169,7 +203,14 @@ extra_rdoc_files: []
 files:
 - LICENCE.txt
 - README.md
+- app/assets/stylesheets/nokodiff.scss
 - lib/nokodiff.rb
+- lib/nokodiff/changes_in_fragments.rb
+- lib/nokodiff/differ.rb
+- lib/nokodiff/engine.rb
+- lib/nokodiff/formatting_helpers.rb
+- lib/nokodiff/html_fragment.rb
+- lib/nokodiff/text_node_diffs.rb
 - lib/nokodiff/version.rb
 homepage: https://github.com/alphagov/nokodiff
 licenses:
@@ -189,7 +230,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.7
 specification_version: 4
 summary: A Ruby Gem to highlight additions, deletions and character level changes
   while preserving original HTML