html-merge 7.1.1 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cb890950b99c62ec12767823ab88ab34b4410b9f4f84fb7d31e97700ee64ec0
-  data.tar.gz: 25226fc06808f7a1ff22b61abaf7da77fe65092389d83500cdb6a24f4d2a1821
+  metadata.gz: 7d1bb35ada60501d9b53cbe2ea82be771de26ad1df6b362625a4fbd2021588a8
+  data.tar.gz: 859dfb00db8875f6cbf69896c8a7a5f3ac09c6a3af6ced496917b739152baae6
 SHA512:
-  metadata.gz: b152307f494920e718a364fb0b0259eaf6e84837140bf12ed06e9e410209c2b1c31e0adbddd0c775ac27d0347df634aabb5fc98517601e5fbe95d4ca811d1171
-  data.tar.gz: ee0da4d4af6a087e5b0a24f2c864dc59ebb4ce6a87be14fb7985dbaed539d3334af5ac327762ff10cf0183b5fa43f0d5ed8ea2f36694b55cab07480eb7e63754
+  metadata.gz: 8550a9e66927c237939a08ef4cee2743760e4f988e4e68bc616252eff1ae536a446c6474c62f6fe462446d84311de45e943c9914ae04e32ddde2d73fe068a9f9
+  data.tar.gz: 0ee6b4338e14e874aaf6b9ace5642a5ddef88a82c01609f3c421be4e11c861c602a717c88175f4e08ec4942a2850ec610c42086c0414031c34ed55c6c317c5b9

data/README.md

@@ -21,6 +21,10 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
 
 ## 🌻 Synopsis <a href="https://discord.gg/3qme4XHNKN"><img alt="Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0" src="https://logos.galtzo.com/assets/images/galtzo-floss/avatar-128px.svg" width="8%" align="right"/></a> <a href="https://ruby-toolbox.com"><img alt="ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5" src="https://logos.galtzo.com/assets/images/ruby-lang/avatar-128px.svg" width="8%" align="right"/></a>
 
+Html::Merge provides TreeHaver-backed HTML parsing and structural analysis for
+the StructuredMerge Ruby family, including feature profiles and YARD content
+wrapper repair helpers.
+
 ## 💡 Info you can shake a stick at
 
 | Tokens to Remember | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace] |
@@ -36,7 +40,7 @@ I've summarized my thoughts in [this blog post](https://dev.to/galtzo/hostile-ta
 
 ### Compatibility
 
-Compatible with MRI Ruby 3.2.0+, and concordant releases of JRuby, and TruffleRuby.
+Compatible with MRI Ruby 3.2.0+, JRuby, and TruffleRuby.
 CI workflows and Appraisals are generated for MRI Ruby 3.2.0+.
 This test floor is configured by `ruby.test_minimum` in `.kettle-jem.yml` and
 may be higher than the gem's runtime compatibility floor when legacy Rubies are
@@ -78,9 +82,26 @@ gem install html-merge
 
 ## ⚙️ Configuration
 
+HTML parsing is registered through TreeHaver. The gem currently supports the
+HTML dialect and its configured Kreuzberg language-pack backend; inspect
+`Html::Merge.html_plan_context` before selecting a backend in a host merge
+pipeline. No global initializer is required.
+
 ## 🔧 Basic Usage
 
-TODO: Write usage instructions here
+Parse and inspect HTML through the module API:
+
+```ruby
+require "html/merge"
+
+result = Html::Merge.parse_html("<main><h1>Hello</h1></main>")
+raise result[:diagnostics].inspect unless result[:ok]
+
+puts result.dig(:analysis, :nodes)
+```
+
+Use `Html::Merge.html_plan_context` to advertise the available backend and
+`Html::Merge.ensure_yard_content_wrapper` when repairing YARD-generated HTML.
 
 ## 🔐 Security
 
@@ -89,20 +110,12 @@ See [SECURITY.md][🔐security].
 ## 🤝 Contributing
 
 If you need some ideas of where to help, you could work on adding more code coverage,
-or if it is already 💯 (see [below](#code-coverage)) check [issues][🤝gh-issues] or [PRs][🤝gh-pulls],
-or use the gem and think about how it could be better.
+check [issues][🤝gh-issues] or [PRs][🤝gh-pulls], or use the gem and think about how it could be better.
 
 We [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] so if you make changes, remember to update it.
 
 See [CONTRIBUTING.md][🤝contributing] for more detailed instructions.
 
-### Code Coverage
-
-<details markdown="1">
-<summary>Coverage service badges</summary>
-
-</details>
-
 ## 📌 Versioning
 
 This library follows [![Semantic Versioning 2.0.0][📌semver-img]][📌semver] for its public API where practical.

data/lib/html/merge/file_analysis.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Html
+  module Merge
+    # One native parser pass proving HTML structure, explicit IDs, and safe source ranges.
+    class FileAnalysis
+      attr_reader :source, :root_node, :wrappers, :errors, :backend, :document_semantics, :issues
+
+      def initialize(source)
+        @source = source.to_s
+        @backend = BACKEND_REFERENCE.id.to_sym
+        @errors = []
+        parse!
+      rescue StandardError => e
+        @root_node = nil
+        @wrappers = [].freeze
+        @document_semantics = nil
+        @issues = [].freeze
+        @errors = [e].freeze
+      end
+
+      def valid? = errors.empty?
+
+      private
+
+      def parse!
+        Html::Merge.register_backend!
+        @root_node = TreeHaver.with_backend(backend) { TreeHaver.parser_for(:html).parse(source).root_node }
+        raise TreeHaver::NotAvailable, "HTML parse returned no root node" unless root_node
+        raise TreeHaver::NotAvailable, "HTML parse contains syntax errors" if root_node.has_error?
+
+        analyze_structure!
+      end
+
+      def analyze_structure!
+        all = []
+        collect_elements(root_node, all)
+        duplicate_ids = duplicate_ids(all)
+        @issues = duplicate_issues(duplicate_ids)
+        unique_ids = unique_id_wrappers(all, duplicate_ids)
+        owned = topmost_wrappers(unique_ids)
+        singletons = singleton_wrappers(all, owned)
+        @wrappers = (owned + singletons).sort_by(&:start_byte).freeze
+        @document_semantics = semantic_node(root_node)
+      end
+
+      def duplicate_ids(wrappers)
+        wrappers.group_by(&:explicit_id).reject { |id, matches| id.nil? || id == true || matches.one? }
+      end
+
+      def duplicate_issues(duplicates)
+        duplicates.keys.map do |id|
+          { category: :ambiguous_owner, identity: [:id, id],
+            message: "duplicate explicit HTML id #{id.inspect}" }.freeze
+        end.freeze
+      end
+
+      def unique_id_wrappers(wrappers, duplicates)
+        wrappers.select do |wrapper|
+          id = wrapper.explicit_id
+          id.is_a?(String) && !id.empty? && !duplicates.key?(id)
+        end
+      end
+
+      def topmost_wrappers(wrappers)
+        wrappers.reject do |wrapper|
+          wrappers.any? { |candidate| ancestor?(candidate.node, wrapper.node) }
+        end
+      end
+
+      def collect_elements(node, collection, parent = nil)
+        wrapper = NodeWrapper.new(node, source: source, parent: parent)
+        next_parent = parent
+        if wrapper.element?
+          collection << wrapper
+          next_parent = wrapper
+        end
+        node.children.each { |child| collect_elements(child, collection, next_parent) }
+      end
+
+      def singleton_wrappers(all, owned)
+        %w[title base].filter_map do |tag|
+          matches = all.select { |wrapper| wrapper.tag_name == tag }
+          next unless matches.one?
+          next if owned.include?(matches.first)
+          next if owned.any? { |owner| ancestor?(owner.node, matches.first.node) }
+
+          matches.first
+        end
+      end
+
+      def ancestor?(ancestor, descendant)
+        ancestor.start_byte < descendant.start_byte && ancestor.end_byte >= descendant.end_byte
+      end
+
+      def semantic_node(node)
+        children = node.children.select(&:structural?)
+        return [node.type, node.text.to_s] if children.empty?
+
+        [node.type, children.map { |child| semantic_node(child) }]
+      end
+    end
+  end
+end

data/lib/html/merge/node_wrapper.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Html
+  module Merge
+    # Parser-derived identity, attributes, semantics, and source range for an HTML element.
+    class NodeWrapper
+      ELEMENT_TYPES = %w[element script_element style_element].freeze
+
+      attr_reader :node, :source, :parent
+
+      def initialize(node, source:, parent: nil)
+        @node = node
+        @source = source
+        @parent = parent
+      end
+
+      def element? = ELEMENT_TYPES.include?(node.type)
+      def start_byte = node.start_byte
+
+      def end_byte
+        return start_node.end_byte if !explicit_end_tag? && start_node
+
+        node.end_byte
+      end
+
+      def source_text = source.byteslice(start_byte...end_byte).to_s
+      def tag_name = node_text(first_descendant(start_node, "tag_name"))&.downcase
+      def explicit_end_tag? = node.children.any? { |child| child.type == "end_tag" }
+      def self_closing? = start_node&.type == "self_closing_tag"
+
+      def attributes
+        return {} unless start_node
+
+        start_node.children.select { |child| child.type == "attribute" }.to_h do |attribute|
+          attribute_pair(attribute)
+        end.freeze
+      end
+
+      def explicit_id = attributes["id"]
+
+      def semantic_tree
+        semantic_node(node)
+      end
+
+      private
+
+      def start_node
+        node.children.find { |child| %w[start_tag self_closing_tag].include?(child.type) }
+      end
+
+      def attribute_pair(attribute)
+        name_node = attribute.children.find { |child| child.type == "attribute_name" }
+        value_node = first_descendant(attribute, "attribute_value")
+        [node_text(name_node).to_s.downcase, value_node ? node_text(value_node) : true]
+      end
+
+      def first_descendant(value, type)
+        return unless value
+        return value if value.type == type
+
+        value.children.each do |child|
+          found = first_descendant(child, type)
+          return found if found
+        end
+        nil
+      end
+
+      def node_text(value)
+        value&.text&.to_s
+      end
+
+      def semantic_node(value)
+        children = value.children.select(&:structural?)
+        return [value.type, node_text(value)] if children.empty?
+
+        [value.type, children.map { |child| semantic_node(child) }]
+      end
+    end
+  end
+end

data/lib/html/merge/provider.rb

@@ -0,0 +1,755 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require_relative "node_wrapper"
+require_relative "file_analysis"
+
+module Html
+  module Merge
+    # Conservative, base-aware HTML provider. Only parser-proven unique IDs and
+    # singleton head semantics become independently editable source owners.
+    # rubocop:disable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- ownership, rendering, and verification are one safety boundary
+    class Provider
+      DEFAULT_PROFILE = :source_preserving
+      VOID_ELEMENTS = %w[area base br col embed hr img input link meta param source track wbr].freeze
+      Owner = Data.define(:id, :signature, :fingerprint, :start_byte, :end_byte, :node_start, :node_end,
+                          :parent_key, :role, :source_text)
+      Document = Data.define(:source, :analysis, :owners, :by_id, :unmanaged_fingerprint, :parents)
+      ExactDocument = Data.define(:source, :analysis, :issues, :role)
+      Decision = Data.define(:changes, :conflicts, :choices)
+
+      def provider_id = "ruby.html"
+      def family = "html"
+
+      def capabilities
+        {
+          operations: Ast::Merge::ProviderContract::OPERATIONS,
+          dialects: %i[html],
+          backends: [BACKEND_REFERENCE.id.to_sym],
+          profiles: [DEFAULT_PROFILE],
+          role: :workflow,
+          ast_ownership: :unique_explicit_ids_and_safe_singletons,
+          source_preservation: %i[exact_source exact_fragments byte_provenance reparse semantic_verification]
+        }.freeze
+      end
+
+      def analyze(request)
+        document = parse_document(:analyze, request, :source)
+        return document if provider_failure?(document)
+
+        result(
+          :analyze,
+          request,
+          analysis: {
+            backend: BACKEND_REFERENCE.id,
+            valid: true,
+            owners: document.owners.map { |owner| owner_description(owner) }
+          },
+          diagnostics: nonblocking_issues(document.analysis, :source),
+          verification: { source_parsed: true, ast_attributes_verified: true }
+        )
+      end
+
+      def diff2(request)
+        before = parse_document(:diff2, request, :before)
+        return before if provider_failure?(before)
+
+        after = parse_document(:diff2, request, :after)
+        return after if provider_failure?(after)
+
+        changes = diff_documents(before, after)
+        result(
+          :diff2,
+          request,
+          diff: { changes: changes },
+          changes: changes,
+          verification: { before_parsed: true, after_parsed: true, ast_attributes_verified: true }
+        )
+      end
+
+      def merge2(request)
+        merged = merge3(
+          request.merge(
+            base_source: request.fetch(:current_source),
+            ours_source: request.fetch(:current_source),
+            theirs_source: request.fetch(:incoming_source)
+          )
+        )
+        merged.merge(operation: :merge2, verification: merged.fetch(:verification).except(:base_participated))
+      end
+
+      def merge3(request)
+        exact_role = exact_revision_role(request)
+        return merge3_exact(request, exact_role) if exact_role
+
+        documents = parse_merge3_documents(request)
+        return documents if provider_failure?(documents)
+
+        decision = decide(documents)
+        return render_conflicts(request, documents, decision) unless decision.conflicts.empty?
+
+        render_composite(request, documents, decision)
+      end
+
+      private
+
+      def parse_merge3_documents(request)
+        %i[base ours theirs].each_with_object({}) do |role, documents|
+          parsed = parse_source(request.fetch(:"#{role}_source"), role)
+          return unsafe_document_failure(request, role, parsed) if provider_failure?(parsed)
+
+          documents[role] = parsed
+        end
+      end
+
+      def parse_document(operation, request, role)
+        key = role == :source ? :source : :"#{role}_source"
+        parsed = parse_source(request.fetch(key), role)
+        return parse_failure(operation, request, role, parsed) if provider_failure?(parsed)
+
+        parsed
+      end
+
+      def parse_source(source, role)
+        analysis = FileAnalysis.new(source)
+        return { parse_error: analysis.errors.map(&:to_s).join("; "), source_role: role } unless analysis.valid?
+        return { ambiguous_owner: analysis.issues.first, source_role: role } unless analysis.issues.empty?
+
+        owners = analysis.wrappers.map do |wrapper|
+          return { unsafe_range: wrapper.tag_name, source_role: role } unless safe_wrapper?(wrapper, source)
+
+          start_byte, end_byte = expanded_range(source, wrapper.start_byte, wrapper.end_byte)
+          signature = owner_signature(wrapper)
+          Owner.new(
+            id: owner_id(signature),
+            signature: signature,
+            fingerprint: fingerprint(wrapper.semantic_tree),
+            start_byte: start_byte,
+            end_byte: end_byte,
+            node_start: wrapper.start_byte,
+            node_end: wrapper.end_byte,
+            parent_key: parent_key(wrapper),
+            role: role,
+            source_text: source.byteslice(start_byte...end_byte).to_s
+          )
+        end
+        duplicate = owners.group_by(&:id).find { |_id, matches| matches.length > 1 }
+        return { ambiguous_owner: duplicate.first, source_role: role } if duplicate
+        return { unsafe_range: :overlapping_owners, source_role: role } unless non_overlapping?(owners)
+
+        Document.new(
+          source: source,
+          analysis: analysis,
+          owners: owners.freeze,
+          by_id: owners.to_h { |owner| [owner.id, owner] }.freeze,
+          unmanaged_fingerprint: unmanaged_fingerprint(source, owners),
+          parents: parent_anchors(analysis, source).freeze
+        )
+      rescue StandardError => e
+        { parse_error: e.message, source_role: role }
+      end
+
+      def parse_exact_source(source, role)
+        analysis = FileAnalysis.new(source)
+        return { parse_error: analysis.errors.map(&:to_s).join("; "), source_role: role } unless analysis.valid?
+
+        ExactDocument.new(source: source, analysis: analysis, issues: analysis.issues, role: role)
+      rescue StandardError => e
+        { parse_error: e.message, source_role: role }
+      end
+
+      def owner_signature(wrapper)
+        id = wrapper.explicit_id
+        return [:id, id] if id.is_a?(String) && !id.empty?
+
+        [:singleton, wrapper.tag_name]
+      end
+
+      def owner_id(signature)
+        Digest::SHA256.hexdigest(JSON.generate(Ast::Merge.json_ready(signature)))
+      end
+
+      def fingerprint(value)
+        Digest::SHA256.hexdigest(JSON.generate(Ast::Merge.json_ready(value)))
+      end
+
+      def safe_wrapper?(wrapper, source)
+        return false unless wrapper.start_byte >= 0 && wrapper.end_byte <= source.bytesize
+        return false unless wrapper.end_byte > wrapper.start_byte
+
+        wrapper.self_closing? || wrapper.explicit_end_tag? || VOID_ELEMENTS.include?(wrapper.tag_name)
+      end
+
+      def expanded_range(source, start_byte, end_byte)
+        line_start = source.rindex("\n", [start_byte - 1, 0].max)
+        line_start = line_start ? line_start + 1 : 0
+        if end_byte.positive? && source.getbyte(end_byte - 1) == 10 &&
+           whitespace?(source.byteslice(line_start...start_byte).to_s)
+          return [line_start, end_byte]
+        end
+
+        line_end = source.index("\n", end_byte)
+        if whitespace?(source.byteslice(line_start...start_byte).to_s) &&
+           whitespace?(source.byteslice(end_byte...(line_end || source.bytesize)).to_s)
+          [line_start, line_end ? line_end + 1 : source.bytesize]
+        else
+          [start_byte, end_byte]
+        end
+      end
+
+      def whitespace?(value)
+        value.each_byte.all? { |byte| [9, 13, 32].include?(byte) }
+      end
+
+      def non_overlapping?(owners)
+        owners.each_cons(2).all? { |left, right| left.end_byte <= right.start_byte }
+      end
+
+      def unmanaged_fingerprint(source, owners)
+        output = source.dup
+        owners.reverse_each { |owner| output[owner.start_byte...owner.end_byte] = "" }
+        fingerprint(output)
+      end
+
+      def parent_key(wrapper)
+        current = wrapper.parent
+        while current
+          id = current.explicit_id
+          return [:id, id] if id.is_a?(String) && !id.empty?
+          return [:boundary, current.tag_name] if %w[html head body].include?(current.tag_name)
+
+          current = current.parent
+        end
+        [:document]
+      end
+
+      def parent_anchors(analysis, source)
+        anchors = { [:document] => source.bytesize }
+        walk = lambda do |node|
+          wrapper = NodeWrapper.new(node, source: source)
+          if wrapper.element?
+            id = wrapper.explicit_id
+            anchors[[:id, id]] = insertion_anchor(node) if id.is_a?(String) && !id.empty?
+            anchors[[:boundary, wrapper.tag_name]] = insertion_anchor(node) if %w[html head
+                                                                                  body].include?(wrapper.tag_name)
+          end
+          node.children.each { |child| walk.call(child) }
+        end
+        walk.call(analysis.root_node)
+        anchors.compact
+      end
+
+      def insertion_anchor(node)
+        node.children.find { |child| child.type == "end_tag" }&.start_byte
+      end
+
+      def diff_documents(before, after)
+        ordered_ids(before, after).filter_map do |id|
+          left = before.by_id[id]
+          right = after.by_id[id]
+          next if equivalent?(left, right)
+
+          {
+            path: owner_path(left || right),
+            before: change_side(left),
+            after: change_side(right),
+            change: change_kind(left, right)
+          }.freeze
+        end.freeze
+      end
+
+      def ordered_ids(*documents)
+        documents.flat_map { |document| document.owners.map(&:id) }.uniq
+      end
+
+      def equivalent?(left, right)
+        return true if left.nil? && right.nil?
+        return false unless left && right
+
+        left.fingerprint == right.fingerprint
+      end
+
+      def change_side(owner)
+        if owner
+          { present: true, source_role: owner.role,
+            byte_range: [owner.start_byte, owner.end_byte] }
+        else
+          { present: false }
+        end
+      end
+
+      def change_kind(before, after)
+        return :added unless before
+        return :deleted unless after
+
+        :edited
+      end
+
+      def decide(documents)
+        changes = []
+        conflicts = []
+        choices = {}
+        append_unmanaged_conflict(changes, conflicts, documents)
+        ordered_ids(*documents.values).each do |id|
+          base = documents.fetch(:base).by_id[id]
+          ours = documents.fetch(:ours).by_id[id]
+          theirs = documents.fetch(:theirs).by_id[id]
+          ours_change = side_change_kind(base, ours)
+          theirs_change = side_change_kind(base, theirs)
+          next choices[id] = :ours if ours_change == :unchanged && theirs_change == :unchanged
+
+          change = { path: owner_path(base || ours || theirs), ours: ours_change, theirs: theirs_change }.freeze
+          changes << change
+          choice = owner_choice(base, ours, theirs)
+          if choice == :conflict
+            conflicts << conflict_for(id, base, ours, theirs, change)
+          else
+            choices[id] = choice
+          end
+        end
+        Decision.new(changes: changes.freeze, conflicts: conflicts.freeze, choices: choices.freeze)
+      end
+
+      def append_unmanaged_conflict(changes, conflicts, documents)
+        base = documents.fetch(:base).unmanaged_fingerprint
+        ours = documents.fetch(:ours).unmanaged_fingerprint
+        theirs = documents.fetch(:theirs).unmanaged_fingerprint
+        return if ours == theirs
+
+        change = {
+          path: "<unmanaged-source>",
+          ours: base == ours ? :unchanged : :edited,
+          theirs: base == theirs ? :unchanged : :edited
+        }.freeze
+        changes << change
+        conflicts << {
+          conflict_id: "html-unmanaged-#{fingerprint([base, ours, theirs])[0, 16]}",
+          category: :unmanaged_source_change,
+          path: change.fetch(:path),
+          owner_id: nil,
+          change_classification: change
+        }.freeze
+      end
+
+      def side_change_kind(base, side)
+        return :unchanged if equivalent?(base, side)
+        return :added if !base && side
+        return :deleted if base && !side
+
+        :edited
+      end
+
+      def owner_choice(base, ours, theirs)
+        return :ours if equivalent?(ours, theirs)
+        return :theirs if equivalent?(base, ours)
+        return :ours if equivalent?(base, theirs)
+        return nil if ours.nil? && theirs.nil?
+
+        :conflict
+      end
+
+      def conflict_for(id, base, ours, theirs, change)
+        {
+          conflict_id: "html-owner-#{id[0, 16]}",
+          category: base && (!ours || !theirs) ? :delete_edit : :edit_edit,
+          path: change.fetch(:path),
+          owner_id: id,
+          base: owner_state(base),
+          ours: owner_state(ours),
+          theirs: owner_state(theirs),
+          change_classification: change
+        }.freeze
+      end
+
+      def owner_state(owner)
+        { present: !owner.nil?, fingerprint: owner&.fingerprint, source_role: owner&.role }
+      end
+
+      def exact_revision_role(request)
+        base = request.fetch(:base_source)
+        ours = request.fetch(:ours_source)
+        theirs = request.fetch(:theirs_source)
+        return :ours if ours == theirs || base == theirs
+
+        :theirs if base == ours
+      end
+
+      def merge3_exact(request, role)
+        documents = %i[base ours theirs].to_h do |source_role|
+          [source_role, parse_exact_source(request.fetch(:"#{source_role}_source"), source_role)]
+        end
+        winner = documents.fetch(role)
+        return parse_failure(:merge3, request, role, winner) if provider_failure?(winner)
+
+        output = request.fetch(:"#{role}_source")
+        verification = verify_exact(output, winner)
+        return render_failure(request, verification, :exact_revision) unless verification[:semantic_match]
+
+        result(
+          :merge3,
+          request,
+          output: output,
+          diagnostics: exact_diagnostics(documents),
+          render_report: exact_render_report(role, output),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def verify_exact(output, expected)
+        parsed = parse_exact_source(output, :output)
+        if provider_failure?(parsed)
+          return { output_reparsed: false, byte_exact: output == expected.source,
+                   semantic_match: false }
+        end
+
+        {
+          output_reparsed: true,
+          byte_exact: output == expected.source,
+          semantic_match: parsed.analysis.document_semantics == expected.analysis.document_semantics,
+          ordered_semantic_verified: true,
+          ast_attributes_verified: true,
+          source_role: expected.role
+        }
+      end
+
+      def exact_diagnostics(documents)
+        documents.flat_map do |role, document|
+          if provider_failure?(document)
+            [{ category: :parse_error, severity: :warning, message: "#{role} parse error", blocking: false,
+               source_role: role }]
+          else
+            nonblocking_issues(document.analysis, role)
+          end
+        end.freeze
+      end
+
+      def nonblocking_issues(analysis, role)
+        analysis.issues.map do |issue|
+          issue.merge(severity: :warning, blocking: false, source_role: role).freeze
+        end
+      end
+
+      def render_composite(request, documents, decision)
+        ours = documents.fetch(:ours)
+        edits = replacement_edits(documents, decision)
+        insertion_edits(documents, decision).each do |edit|
+          return unsafe_composite_failure(request, decision, :unproven_parent_insertion) unless edit[:start_byte]
+
+          edits << edit
+        end
+        output = apply_edits(ours.source, edits)
+        expected = expected_owner_states(documents, decision)
+        verification = verify_composite(output, expected)
+        unless verification[:semantic_match]
+          return render_failure(request, verification, :exact_html_composite,
+                                decision.changes)
+        end
+
+        result(
+          :merge3,
+          request,
+          output: output,
+          changes: decision.changes,
+          render_report: composite_render_report(edits, output),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def replacement_edits(documents, decision)
+        ours = documents.fetch(:ours)
+        decision.choices.filter_map do |id, role|
+          ours_owner = ours.by_id[id]
+          next unless ours_owner
+          next if role == :ours
+
+          chosen = role && documents.fetch(role).by_id[id]
+          {
+            start_byte: ours_owner.start_byte,
+            end_byte: ours_owner.end_byte,
+            content: chosen&.source_text.to_s,
+            source_role: role,
+            owner_id: id,
+            action: chosen ? :replace : :delete
+          }
+        end
+      end
+
+      def insertion_edits(documents, decision)
+        ours = documents.fetch(:ours)
+        additions = documents.fetch(:theirs).owners.select do |owner|
+          !ours.by_id.key?(owner.id) && decision.choices[owner.id] == :theirs
+        end
+        additions.group_by(&:parent_key).map do |parent_key, owners|
+          {
+            start_byte: ours.parents[parent_key],
+            end_byte: ours.parents[parent_key],
+            content: owners.map(&:source_text).join,
+            source_role: :theirs,
+            owner_id: owners.map(&:id),
+            action: :insert
+          }
+        end
+      end
+
+      def apply_edits(source, edits)
+        output = source.dup
+        edits.sort_by { |edit| [edit.fetch(:start_byte), edit.fetch(:end_byte)] }.reverse_each do |edit|
+          output[edit.fetch(:start_byte)...edit.fetch(:end_byte)] = edit.fetch(:content)
+        end
+        output
+      end
+
+      def expected_owner_states(documents, decision)
+        states = decision.choices.filter_map do |id, role|
+          owner = role && documents.fetch(role).by_id[id]
+          owner && [owner.signature, owner.fingerprint]
+        end
+        states.sort_by { |value| JSON.generate(Ast::Merge.json_ready(value.first)) }
+      end
+
+      def verify_composite(output, expected)
+        parsed = parse_source(output, :output)
+        if provider_failure?(parsed)
+          return { output_reparsed: false, semantic_match: false, parse_error: failure_detail(parsed) }
+        end
+
+        actual = parsed.owners.map { |owner| [owner.signature, owner.fingerprint] }
+                              .sort_by { |value| JSON.generate(Ast::Merge.json_ready(value.first)) }
+        {
+          output_reparsed: true,
+          semantic_match: actual == expected,
+          ordered_semantic_verified: true,
+          ast_attributes_verified: actual == expected,
+          planned_owner_count: expected.length,
+          output_owner_count: actual.length
+        }
+      end
+
+      def render_conflicts(request, documents, decision)
+        localized = localized_conflict_output(request, documents, decision)
+        return conflict_failure(request, decision, localized, :element_localized_conflict) if localized
+
+        conflict_failure(request, decision, whole_document_conflict(request), :full_file_conflict,
+                         [{ from: :element_localization, to: :full_file_conflict,
+                            reason: :source_ownership_unproven }])
+      end
+
+      def localized_conflict_output(request, documents, decision)
+        return if decision.conflicts.any? { |conflict| conflict[:owner_id].nil? }
+
+        ours = documents.fetch(:ours)
+        return unless decision.conflicts.all? { |conflict| ours.by_id.key?(conflict.fetch(:owner_id)) }
+
+        edits = decision.conflicts.map do |conflict|
+          owner = ours.by_id.fetch(conflict.fetch(:owner_id))
+          {
+            start_byte: owner.start_byte,
+            end_byte: owner.end_byte,
+            content: conflict_text(request, documents, conflict)
+          }
+        end
+        apply_edits(ours.source, edits)
+      end
+
+      def conflict_text(request, documents, conflict)
+        marker = request.fetch(:conflict_marker_size, 7).to_i
+        marker = 7 unless marker.positive?
+        labels = { ours: "ours", base: "base", theirs: "theirs" }.merge(request.fetch(:labels, {}))
+        sides = %i[ours base theirs].to_h do |role|
+          owner = documents.fetch(role).by_id[conflict.fetch(:owner_id)]
+          [role, owner&.source_text.to_s]
+        end
+        [
+          "#{"<" * marker} #{labels[:ours]}\n", sides[:ours],
+          "#{"|" * marker} #{labels[:base]}\n", sides[:base],
+          "#{"=" * marker}\n", sides[:theirs],
+          "#{">" * marker} #{labels[:theirs]}\n"
+        ].join
+      end
+
+      def whole_document_conflict(request)
+        marker = request.fetch(:conflict_marker_size, 7).to_i
+        marker = 7 unless marker.positive?
+        [
+          "#{"<" * marker} ours\n", request.fetch(:ours_source),
+          "#{"|" * marker} base\n", request.fetch(:base_source),
+          "#{"=" * marker}\n", request.fetch(:theirs_source),
+          "#{">" * marker} theirs\n"
+        ].join
+      end
+
+      def conflict_failure(request, decision, output, strategy, fallbacks = [])
+        failure(
+          :merge3,
+          request,
+          category: :merge_conflict,
+          message: "HTML owner changed incompatibly on both sides.",
+          changes: decision.changes,
+          conflicts: decision.conflicts,
+          conflicted_output: output,
+          fallbacks: fallbacks,
+          render_report: { strategy: strategy, provenance: :exact_source_bytes },
+          verification: { base_participated: true }
+        )
+      end
+
+      def unsafe_document_failure(request, role, parsed)
+        return parse_failure(:merge3, request, role, parsed) if parsed[:parse_error]
+
+        category = parsed[:ambiguous_owner] ? :ambiguous_owner : :unsafe_source_range
+        conflict = {
+          conflict_id: "html-unsafe-#{fingerprint([role, failure_detail(parsed)])[0, 16]}",
+          category: category,
+          path: "<document>",
+          owner_id: nil,
+          source_role: role
+        }
+        failure(
+          :merge3,
+          request,
+          category: category,
+          message: "#{role} HTML ownership is unsafe: #{failure_detail(parsed)}",
+          conflicts: [conflict],
+          conflicted_output: whole_document_conflict(request),
+          source_role: role,
+          render_report: { strategy: :full_file_conflict, provenance: :exact_source_bytes },
+          verification: { base_participated: true }
+        )
+      end
+
+      def unsafe_composite_failure(request, decision, reason)
+        failure(
+          :merge3,
+          request,
+          category: :unsafe_source_range,
+          message: "HTML composite insertion has no parser-proven parent closing boundary.",
+          changes: decision.changes,
+          conflicts: [{ conflict_id: "html-parent-#{reason}", category: reason, path: "<document>", owner_id: nil }],
+          conflicted_output: whole_document_conflict(request),
+          fallbacks: [{ from: :element_composite, to: :full_file_conflict, reason: reason }],
+          render_report: { strategy: :full_file_conflict, provenance: :exact_source_bytes },
+          verification: { base_participated: true }
+        )
+      end
+
+      def render_failure(request, verification, strategy, changes = [])
+        failure(
+          :merge3,
+          request,
+          category: :render_failure,
+          message: "HTML output failed native parser and ordered semantic verification.",
+          changes: changes,
+          render_report: { strategy: strategy },
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def exact_render_report(role, output)
+        {
+          strategy: :exact_revision,
+          provenance: [{ source_role: role, byte_range: [0, output.bytesize], copied_source: true }],
+          synthesized_fragments: []
+        }
+      end
+
+      def composite_render_report(edits, output)
+        {
+          strategy: :exact_html_composite,
+          provenance: edits.map { |edit| edit.slice(:source_role, :owner_id, :action, :start_byte, :end_byte) },
+          output_bytes: output.bytesize,
+          synthesized_fragments: []
+        }
+      end
+
+      def owner_path(owner)
+        owner ? owner.signature.inspect : "<document>"
+      end
+
+      def owner_description(owner)
+        {
+          path: owner_path(owner),
+          signature: owner.signature,
+          source_role: owner.role,
+          byte_range: [owner.start_byte, owner.end_byte],
+          parent: owner.parent_key
+        }
+      end
+
+      def parse_failure(operation, request, role, parsed)
+        category = if parsed[:parse_error]
+                     :parse_error
+                   else
+                     parsed[:ambiguous_owner] ? :ambiguous_owner : :unsafe_source_range
+                   end
+        failure(
+          operation,
+          request,
+          category: category,
+          message: "#{role} parse error: #{failure_detail(parsed)}",
+          source_role: role
+        )
+      end
+
+      def failure_detail(parsed)
+        return parsed[:parse_error] if parsed[:parse_error]
+        return parsed[:ambiguous_owner].inspect if parsed[:ambiguous_owner]
+
+        parsed[:unsafe_range].inspect
+      end
+
+      def provider_failure?(value)
+        value.is_a?(Hash) &&
+          (value[:ok] == false || value.key?(:parse_error) || value.key?(:ambiguous_owner) || value.key?(:unsafe_range))
+      end
+
+      def result(operation, request, changes: [], diagnostics: [], render_report: {}, verification: {}, **payload)
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: true,
+          envelope: envelope(
+            request,
+            changes: changes,
+            diagnostics: diagnostics,
+            render_report: render_report,
+            verification: verification
+          ),
+          **payload
+        )
+      end
+
+      def failure(operation, request, category:, message:, changes: [], conflicts: [], fallbacks: [],
+                  render_report: {}, verification: {}, **payload)
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: false,
+          envelope: envelope(
+            request,
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            diagnostics: [{ category: category, severity: :error, message: message, blocking: true }],
+            render_report: render_report,
+            verification: verification
+          ),
+          **payload
+        )
+      end
+
+      def envelope(request, **fields)
+        {
+          provider: {
+            provider_id: provider_id,
+            family: family,
+            dialect: request[:dialect] || :html,
+            backend: request[:backend] || BACKEND_REFERENCE.id.to_sym,
+            package: "html-merge",
+            package_version: Html::Merge::Version::VERSION
+          },
+          profile: { profile_id: request[:profile_id] || DEFAULT_PROFILE }
+        }.merge(fields)
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+  end
+end

data/lib/html/merge/version.rb

@@ -5,7 +5,7 @@ module Html
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "7.1.1"
+      VERSION = "7.1.3"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/html/merge.rb

@@ -16,6 +16,9 @@ module Html
     class ParseError < Ast::Merge::ParseError; end
 
     autoload :CrisprAdapter, "html/merge/crispr_adapter"
+    autoload :NodeWrapper, "html/merge/node_wrapper"
+    autoload :FileAnalysis, "html/merge/file_analysis"
+    autoload :Provider, "html/merge/provider"
 
     module_function
 
@@ -249,9 +252,22 @@ module Html
 
       actor.updated_content
     end
+
+    def merge_provider
+      @merge_provider ||= Provider.new
+    end
+
+    def register_provider!(replace: false)
+      return unless Ast::Merge.respond_to?(:register_provider)
+
+      Ast::Merge.register_provider(merge_provider, replace: replace)
+    end
   end
 end
 
 Html::Merge::Version.class_eval do
   extend VersionGem::Basic
 end
+
+Html::Merge.register_backend!
+Html::Merge.register_provider!

data/sig/html/merge.rbs

@@ -5,6 +5,47 @@ module Html
       VERSION: String
     end
 
+    class NodeWrapper
+      ELEMENT_TYPES: Array[String]
+      attr_reader node: untyped
+      attr_reader source: String
+      attr_reader parent: NodeWrapper?
+      def initialize: (untyped node, source: String, ?parent: NodeWrapper?) -> void
+      def element?: () -> bool
+      def start_byte: () -> Integer
+      def end_byte: () -> Integer
+      def source_text: () -> String
+      def tag_name: () -> String?
+      def explicit_end_tag?: () -> bool
+      def self_closing?: () -> bool
+      def attributes: () -> Hash[String, String | true]
+      def explicit_id: () -> (String | true)?
+      def semantic_tree: () -> untyped
+    end
+
+    class FileAnalysis
+      attr_reader source: String
+      attr_reader root_node: untyped
+      attr_reader wrappers: Array[NodeWrapper]
+      attr_reader errors: Array[untyped]
+      attr_reader backend: Symbol
+      attr_reader document_semantics: untyped
+      attr_reader issues: Array[Hash[Symbol, untyped]]
+      def initialize: (String source) -> void
+      def valid?: () -> bool
+    end
+
+    class Provider
+      DEFAULT_PROFILE: Symbol
+      def provider_id: () -> String
+      def family: () -> String
+      def capabilities: () -> Hash[Symbol, untyped]
+      def analyze: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+      def diff2: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+      def merge2: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+      def merge3: (Hash[Symbol, untyped] request) -> Hash[Symbol, untyped]
+    end
+
     def self.register_backend!: () -> nil
     def self.html_feature_profile: () -> Hash[Symbol, untyped]
     def self.available_html_backends: () -> Array[untyped]
@@ -14,5 +55,7 @@ module Html
     def self.document_context: (content: String, ?source_label: String) -> untyped
     def self.element_text_selector: (text: String, ?id: String?) -> untyped
     def self.ensure_yard_content_wrapper: (String source) -> String
+    def self.merge_provider: () -> Provider
+    def self.register_provider!: (?replace: bool) -> untyped
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: html-merge
 version: !ruby/object:Gem::Version
-  version: 7.1.1
+  version: 7.1.3
 platform: ruby
 authors:
 - Peter H. Boling
@@ -43,42 +43,42 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
 - !ruby/object:Gem::Dependency
   name: ast-merge
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
 - !ruby/object:Gem::Dependency
   name: tree_haver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 7.1.1
+        version: 7.1.3
 - !ruby/object:Gem::Dependency
   name: version_gem
   requirement: !ruby/object:Gem::Requirement
@@ -105,20 +105,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.5.24
+        version: 3.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.5.24
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -236,7 +236,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -246,7 +246,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.4
+        version: 3.2.5
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -313,6 +313,9 @@ files:
 - README.md
 - lib/html/merge.rb
 - lib/html/merge/crispr_adapter.rb
+- lib/html/merge/file_analysis.rb
+- lib/html/merge/node_wrapper.rb
+- lib/html/merge/provider.rb
 - lib/html/merge/version.rb
 - sig/html/merge.rbs
 homepage: https://github.com/structuredmerge/structuredmerge-ruby
@@ -320,10 +323,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://structuredmerge.org
-  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.1
-  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.1/CHANGELOG.md
+  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.1.3
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.1.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
-  documentation_uri: https://www.rubydoc.info/gems/html-merge/7.1.1
+  documentation_uri: https://www.rubydoc.info/gems/html-merge/7.1.3
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
   news_uri: https://www.railsbling.com/tags/html-merge