ruby-merge 7.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d9fb197110a8e0a388d9daf71e144696f7db240ff5f59bf9d6cecf10518950b
+  data.tar.gz: 01ea7a23152ec998ea17b1e4463a1ce7115e5b4463202c5ecd73ab1829a4a224
+SHA512:
+  metadata.gz: ab2fe88791d7ec23b4b9e1525a0726638e3afa01af7136e92e67b89eaa821f290187b11d96885caf44fb51adffdb12e9f6da01c25bc333e1f2358b8f84b756f2
+  data.tar.gz: 301910a3b44cf21892fb23b1c25106ca1ac82f53481121bb921d7978bab9efa9ba574bc8c6ba574fdb51cf7166d8a550abde90e4b9efae76f0c22219e3af8531

data/lib/ruby/merge/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Ruby
+  module Merge
+    module Version
+      VERSION = "7.0.0"
+    end
+
+    VERSION = Version::VERSION
+  end
+end

data/lib/ruby/merge.rb

@@ -0,0 +1,779 @@
+# frozen_string_literal: true
+
+require "tree_haver"
+require "ast/merge"
+
+module Ruby
+  module Merge
+    extend self
+
+    PACKAGE_NAME = "ruby-merge"
+    TREE_SITTER_BACKEND = TreeHaver::KREUZBERG_LANGUAGE_PACK_BACKEND
+    DESTINATION_WINS_ARRAY_POLICY = { surface: "array", name: "destination_wins_array" }.freeze
+    DIRECTIVE_LINE = /\A(?::nocov:|[\w-]+:(?:freeze|unfreeze))\z/
+    MAGIC_COMMENT_PREFIXES = %w[coding encoding frozen_string_literal shareable_constant_value typed warn_indent].freeze
+    REQUIRE_PATTERN = /^\s*require(?:_relative)?\s+["']([^"']+)["']/.freeze
+    DSL_CALL_PATTERN = /^(?<name>source|gemspec|git_source|gem|eval_gemfile|platform|group|desc|task)\b/.freeze
+    RAKEFILE_DEFAULT_TASK_COMMENT = "# Define a base default task early so other files can enhance it."
+    RAKEFILE_DEFAULT_TASK_DESC = 'desc "Default tasks aggregator"'
+    CLASS_PATTERN = /^\s*class\s+([A-Z]\w*(?:::\w+)*)/.freeze
+    MODULE_PATTERN = /^\s*module\s+([A-Z]\w*(?:::\w+)*)/.freeze
+    DEF_PATTERN = /^\s*def\s+(?:self\.)?([a-zA-Z_]\w*[!?=]?)/.freeze
+    EXAMPLE_TAG = /\A@example\b(?<rest>.*)\z/.freeze
+    TAG_PREFIX = /\A@[a-z_]+\b/.freeze
+
+    def ruby_feature_profile
+      {
+        family: "ruby",
+        supported_dialects: ["ruby"],
+        supported_policies: [DESTINATION_WINS_ARRAY_POLICY]
+      }
+    end
+
+    def available_ruby_backends
+      [TREE_SITTER_BACKEND]
+    end
+
+    def ruby_backend_feature_profile(backend: nil)
+      requested = backend.to_s.empty? ? TREE_SITTER_BACKEND.id : backend.to_s
+      return unsupported_feature_result("Unsupported Ruby backend #{requested}.") unless requested == TREE_SITTER_BACKEND.id
+
+      ruby_feature_profile.merge(
+        backend: requested,
+        backend_ref: TREE_SITTER_BACKEND.to_h,
+        supports_dialects: true
+      )
+    end
+
+    def ruby_plan_context(backend: nil)
+      profile = ruby_backend_feature_profile(backend: backend)
+      return profile if profile[:ok] == false
+
+      {
+        family_profile: ruby_feature_profile,
+        feature_profile: {
+          backend: profile[:backend],
+          supports_dialects: true,
+          supported_policies: profile[:supported_policies]
+        }
+      }
+    end
+
+    def parse_ruby(source, dialect, backend: nil)
+      requested = backend.to_s.empty? ? TREE_SITTER_BACKEND.id : backend.to_s
+      return unsupported_feature_result("Unsupported Ruby dialect #{dialect}.") unless dialect == "ruby"
+      return unsupported_feature_result("Unsupported Ruby backend #{requested}.") unless requested == TREE_SITTER_BACKEND.id
+
+      syntax = TreeHaver.parse_with_language_pack(
+        TreeHaver::ParserRequest.new(source: source, language: "ruby", dialect: dialect)
+      )
+      return { ok: false, diagnostics: syntax[:diagnostics], policies: [] } unless syntax[:ok]
+
+      {
+        ok: true,
+        diagnostics: [],
+        analysis: analyze_ruby_document(source),
+        policies: []
+      }
+    end
+
+    def match_ruby_owners(template, destination)
+      destination_paths = destination[:owners].to_h { |owner| [owner[:path], true] }
+      template_paths = template[:owners].to_h { |owner| [owner[:path], true] }
+      {
+        matched: template[:owners]
+          .filter { |owner| destination_paths[owner[:path]] }
+          .map { |owner| { template_path: owner[:path], destination_path: owner[:path] } },
+        unmatched_template: template[:owners].map { |owner| owner[:path] }.reject { |path| destination_paths[path] },
+        unmatched_destination: destination[:owners].map { |owner| owner[:path] }.reject { |path| template_paths[path] }
+      }
+    end
+
+    def merge_ruby(template_source, destination_source, dialect, merge_template_requires: false)
+      template = parse_ruby(template_source, dialect)
+      return template unless template[:ok]
+
+      destination = parse_ruby(destination_source, dialect)
+      unless destination[:ok]
+        return {
+          ok: false,
+          diagnostics: destination[:diagnostics].map do |diagnostic|
+            diagnostic[:category] == "parse_error" ? diagnostic.merge(category: "destination_parse_error") : diagnostic
+          end,
+          policies: []
+        }
+      end
+
+      destination_requires = collect_ruby_require_entries(destination.dig(:analysis, :source))
+      template_requires = collect_ruby_require_entries(template.dig(:analysis, :source))
+      destination_declarations = collect_ruby_declaration_entries(destination.dig(:analysis, :source))
+      template_declarations = collect_ruby_declaration_entries(template.dig(:analysis, :source))
+      destination_paths = destination_declarations.to_h { |entry| [entry[:path], true] }
+      destination_dsl = collect_top_level_dsl_entries(destination.dig(:analysis, :source))
+      template_dsl = collect_top_level_dsl_entries(template.dig(:analysis, :source))
+      sections = []
+      preamble = collect_ruby_preamble(destination.dig(:analysis, :source))
+      sections << preamble unless preamble.empty?
+      requires = merge_template_requires ? merge_ruby_requires(destination_requires, template_requires) : destination_requires
+      require_block = requires.map { |entry| entry[:text] }.join("\n").strip
+      sections << require_block unless require_block.empty?
+      sections.concat(merge_top_level_dsl_entries(destination_dsl, template_dsl).map { |entry| entry[:text] })
+      sections.concat(destination_declarations.map { |entry| entry[:text] })
+      sections.concat(
+        template_declarations.reject { |entry| destination_paths[entry[:path]] }.map { |entry| entry[:text] }
+      )
+
+      output = "#{sections.join("\n\n").strip}\n"
+
+      {
+        ok: true,
+        diagnostics: [],
+        output: normalize_rakefile_default_task_scaffold(output),
+        policies: [DESTINATION_WINS_ARRAY_POLICY]
+      }
+    end
+
+    def ruby_discovered_surfaces(analysis)
+      analysis[:discovered_surfaces] || []
+    end
+
+    def ruby_delegated_child_operations(analysis, parent_operation_id: "ruby-document-0")
+      surfaces = ruby_discovered_surfaces(analysis)
+      doc_operation_ids = {}
+      operations = []
+
+      surfaces.each_with_index do |surface, index|
+        next unless surface[:surface_kind] == "ruby_doc_comment"
+
+        operation_id = "ruby-doc-comment-#{index}"
+        doc_operation_ids[surface[:address]] = operation_id
+        operations << Ast::Merge.delegated_child_operation(
+          operation_id: operation_id,
+          parent_operation_id: parent_operation_id,
+          requested_strategy: "delegate_child_surface",
+          language_chain: ["ruby", surface[:effective_language]],
+          surface: surface
+        )
+      end
+
+      example_index = 0
+      surfaces.each do |surface|
+        next unless surface[:surface_kind] == "yard_example_block"
+
+        operations << Ast::Merge.delegated_child_operation(
+          operation_id: "yard-example-#{example_index}",
+          parent_operation_id: doc_operation_ids.fetch(surface[:parent_address], parent_operation_id),
+          requested_strategy: "delegate_child_surface",
+          language_chain: ["ruby", "yard", surface[:effective_language]],
+          surface: surface
+        )
+        example_index += 1
+      end
+
+      operations
+    end
+
+    def apply_ruby_delegated_child_outputs(source, delegated_operations, apply_plan, applied_children)
+      lines = normalize_source(source).split("\n")
+      operations_by_id = delegated_operations.to_h { |operation| [operation[:operation_id], operation] }
+      outputs_by_id = applied_children.to_h { |entry| [entry[:operation_id], entry[:output]] }
+
+      replacements = apply_plan[:entries].filter_map do |entry|
+        operation = operations_by_id[entry.dig(:delegated_group, :child_operation_id)]
+        output = outputs_by_id[entry.dig(:delegated_group, :child_operation_id)]
+        span = operation&.dig(:surface, :span)
+        next if operation.nil? || output.nil? || span.nil?
+
+        { start: span[:start_line] - 1, finish: span[:end_line] - 1, output: output }
+      end
+
+      replacements.sort_by { |entry| -entry[:start] }.each do |entry|
+        prefix = comment_prefix_for(lines[entry[:start]])
+        replacement_lines = entry[:output].empty? ? [] : entry[:output].sub(/\n\z/, "").split("\n").map { |line| "#{prefix}#{line}" }
+        lines[entry[:start]..entry[:finish]] = replacement_lines
+      end
+
+      {
+        ok: true,
+        diagnostics: [],
+        output: "#{lines.join("\n").sub(/\n+\z/, "")}\n",
+        policies: [DESTINATION_WINS_ARRAY_POLICY]
+      }
+    end
+
+    def merge_ruby_with_nested_outputs(template_source, destination_source, dialect, nested_outputs)
+      Ast::Merge.execute_nested_merge(
+        nested_outputs,
+        default_family: "ruby",
+        request_id_prefix: "nested_ruby_child",
+        merge_parent: -> { merge_ruby(template_source, destination_source, dialect) },
+        discover_operations: lambda { |merged_output|
+          analysis = parse_ruby(merged_output, dialect)
+          next { ok: false, diagnostics: analysis[:diagnostics] || [] } unless analysis[:ok]
+
+          {
+            ok: true,
+            diagnostics: [],
+            operations: ruby_delegated_child_operations(analysis[:analysis])
+          }
+        },
+        apply_resolved_outputs: lambda { |merged_output, operations, apply_plan, applied_children|
+          apply_ruby_delegated_child_outputs(
+            merged_output,
+            operations,
+            apply_plan,
+            applied_children
+          )
+        }
+      )
+    end
+
+    def merge_ruby_with_reviewed_nested_outputs(template_source, destination_source, dialect, review_state, applied_children)
+      Ast::Merge.execute_reviewed_nested_merge(
+        review_state,
+        "ruby",
+        applied_children,
+        merge_parent: -> { merge_ruby(template_source, destination_source, dialect) },
+        discover_operations: lambda { |merged_output|
+          analysis = parse_ruby(merged_output, dialect)
+          next({ ok: false, diagnostics: analysis[:diagnostics] || [] }) unless analysis[:ok]
+
+          {
+            ok: true,
+            diagnostics: [],
+            operations: ruby_delegated_child_operations(analysis[:analysis])
+          }
+        },
+        apply_resolved_outputs: lambda { |merged_output, operations, apply_plan, resolved_children|
+          apply_ruby_delegated_child_outputs(
+            merged_output,
+            operations,
+            apply_plan,
+            resolved_children
+          )
+        }
+      )
+    end
+
+    def merge_ruby_with_reviewed_nested_outputs_from_replay_bundle(template_source, destination_source, dialect, replay_bundle)
+      execution = Array(replay_bundle[:reviewed_nested_executions]).find { |entry| entry[:family] == "ruby" }
+      return { ok: false, diagnostics: [{ severity: "error", category: "configuration_error", message: "review replay bundle does not include a reviewed nested execution for ruby." }], policies: [] } unless execution
+
+      merge_ruby_with_reviewed_nested_outputs(
+        template_source,
+        destination_source,
+        dialect,
+        execution[:review_state],
+        execution[:applied_children]
+      )
+    end
+
+    def merge_ruby_with_reviewed_nested_outputs_from_review_state(template_source, destination_source, dialect, review_state)
+      execution = Array(review_state[:reviewed_nested_executions]).find { |entry| entry[:family] == "ruby" }
+      return { ok: false, diagnostics: [{ severity: "error", category: "configuration_error", message: "review state does not include a reviewed nested execution for ruby." }], policies: [] } unless execution
+
+      merge_ruby_with_reviewed_nested_outputs(
+        template_source,
+        destination_source,
+        dialect,
+        execution[:review_state],
+        execution[:applied_children]
+      )
+    end
+
+    def merge_ruby_with_reviewed_nested_outputs_from_replay_bundle_envelope(template_source, destination_source, dialect, envelope)
+      replay_bundle, import_error = Ast::Merge.import_review_replay_bundle_envelope(envelope)
+      return { ok: false, diagnostics: [{ severity: "error", category: import_error[:category], message: import_error[:message] }], policies: [] } if import_error
+
+      merge_ruby_with_reviewed_nested_outputs_from_replay_bundle(
+        template_source,
+        destination_source,
+        dialect,
+        replay_bundle
+      )
+    end
+
+    def merge_ruby_with_reviewed_nested_outputs_from_review_state_envelope(template_source, destination_source, dialect, envelope)
+      review_state, import_error = Ast::Merge.import_conformance_manifest_review_state_envelope(envelope)
+      return { ok: false, diagnostics: [{ severity: "error", category: import_error[:category], message: import_error[:message] }], policies: [] } if import_error
+
+      merge_ruby_with_reviewed_nested_outputs_from_review_state(
+        template_source,
+        destination_source,
+        dialect,
+        review_state
+      )
+    end
+
+    def analyze_ruby_document(source)
+      lines = normalize_source(source).split("\n", -1)
+      requires = []
+      declarations = []
+      discovered_surfaces = []
+      pending_comments = []
+
+      lines.each_with_index do |line, index|
+        line_number = index + 1
+        stripped = line.strip
+
+        if comment_line?(line)
+          pending_comments << { line: line_number, raw: line }
+          next
+        end
+
+        if stripped.empty?
+          pending_comments = []
+          next
+        end
+
+        if (match = REQUIRE_PATTERN.match(line))
+          requires << {
+            path: "/requires/#{requires.length}",
+            owner_kind: "require",
+            match_key: match[1]
+          }
+          pending_comments = []
+          next
+        end
+
+        declaration = declaration_for_line(line)
+        if declaration
+          declarations << {
+            path: "/declarations/#{declaration[:name]}",
+            owner_kind: "declaration",
+            match_key: declaration[:name]
+          }
+          surfaces = surfaces_for_owner(
+            owner_name: declaration[:name],
+            comment_entries: pending_comments
+          )
+          discovered_surfaces.concat(surfaces)
+          pending_comments = []
+          next
+        end
+
+        pending_comments = []
+      end
+
+      {
+        kind: "ruby",
+        dialect: "ruby",
+        root_kind: "document",
+        source: normalize_source(source),
+        owners: (requires + declarations).sort_by { |owner| owner[:path] },
+        discovered_surfaces: discovered_surfaces
+      }
+    end
+
+    def collect_ruby_require_entries(source)
+      normalize_source(source).split("\n").filter_map do |line|
+        match = REQUIRE_PATTERN.match(line)
+        next unless match
+
+        { path: "/requires/#{match[1]}", text: line.rstrip }
+      end
+    end
+
+    def collect_ruby_preamble(source)
+      lines = normalize_source(source).split("\n")
+      preamble = []
+      lines.each do |line|
+        break unless line.strip.empty? || comment_line?(line)
+
+        preamble << line.rstrip
+      end
+      preamble.join("\n").strip
+    end
+
+    def collect_top_level_dsl_entries(source)
+      lines = normalize_source(source).split("\n")
+      entries = []
+      pending_comments = []
+      index = 0
+
+      while index < lines.length
+        line = lines[index]
+        stripped = line.strip
+        if comment_line?(line)
+          pending_comments << index
+          index += 1
+          next
+        end
+        if stripped.empty?
+          pending_comments = []
+          index += 1
+          next
+        end
+        if REQUIRE_PATTERN.match?(line) || declaration_for_line(line)
+          pending_comments = []
+          index += 1
+          next
+        end
+
+        if line.match?(/\Abegin\b/)
+          start_index = pending_comments.first || index
+          finish_index = ruby_block_finish_index(lines, index)
+          text = lines[start_index..finish_index].join("\n").strip
+          signature = begin_block_signature(text)
+          entries << { path: "/dsl/#{signature}", name: "begin", signature: signature, text: text }
+          pending_comments = []
+          index = finish_index + 1
+          next
+        end
+
+        match = DSL_CALL_PATTERN.match(line)
+        unless match
+          pending_comments = []
+          index += 1
+          next
+        end
+
+        name = match[:name]
+        if name == "desc" && next_code_line_is_task?(lines, index + 1)
+          pending_comments << index
+          index += 1
+          next
+        end
+
+        start_index = pending_comments.first || index
+        finish_index = dsl_entry_finish_index(lines, index)
+        text = lines[start_index..finish_index].join("\n").strip
+        signature = dsl_entry_signature(name, line)
+        entries << { path: "/dsl/#{signature}", name: name, signature: signature, text: text } if signature
+        pending_comments = []
+        index = finish_index + 1
+      end
+
+      entries
+    end
+
+    def merge_top_level_dsl_entries(destination_entries, template_entries)
+      destination_by_signature = destination_entries.to_h { |entry| [entry[:signature], entry] }
+      template_singletons = template_entries.select { |entry| dsl_singleton_entry?(entry) }
+      template_singleton_signatures = template_singletons.map { |entry| entry[:signature] }.to_h { |signature| [signature, true] }
+      result = []
+      result.concat(template_singletons)
+      result.concat(destination_entries.reject { |entry| template_singleton_signatures[entry[:signature]] })
+      result.concat(
+        template_entries.reject do |entry|
+          dsl_singleton_entry?(entry) || destination_by_signature[entry[:signature]]
+        end
+      )
+      result
+    end
+
+    def merge_ruby_requires(destination_requires, template_requires)
+      destination_paths = destination_requires.to_h { |entry| [entry[:path], true] }
+      destination_requires + template_requires.reject { |entry| destination_paths[entry[:path]] }
+    end
+
+    def collect_ruby_declaration_entries(source)
+      lines = normalize_source(source).split("\n")
+      entries = []
+      pending_comments = []
+      index = 0
+
+      while index < lines.length
+        line = lines[index]
+        stripped = line.strip
+
+        if comment_line?(line)
+          pending_comments << index
+          index += 1
+          next
+        end
+
+        if stripped.empty?
+          pending_comments = []
+          index += 1
+          next
+        end
+
+        if REQUIRE_PATTERN.match?(line)
+          pending_comments = []
+          index += 1
+          next
+        end
+
+        declaration = declaration_for_line(line)
+        unless declaration
+          pending_comments = []
+          index += 1
+          next
+        end
+
+        start_index = pending_comments.first || index
+        depth = 1
+        cursor = index + 1
+        while cursor < lines.length
+          candidate = lines[cursor].strip
+          depth += 1 if declaration_for_line(candidate)
+          if candidate == "end"
+            depth -= 1
+            if depth.zero?
+              cursor += 1
+              break
+            end
+          end
+          cursor += 1
+        end
+
+        entries << {
+          path: "/declarations/#{declaration[:name]}",
+          text: lines[start_index...cursor].join("\n").strip
+        }
+        pending_comments = []
+        index = cursor
+      end
+
+      entries
+    end
+
+    def unsupported_feature_result(message)
+      {
+        ok: false,
+        diagnostics: [{ severity: "error", category: "unsupported_feature", message: message }],
+        policies: []
+      }
+    end
+
+    private
+
+    def comment_line?(line)
+      line.lstrip.start_with?("#")
+    end
+
+    def declaration_for_line(line)
+      if (match = CLASS_PATTERN.match(line))
+        { kind: "class", name: match[1] }
+      elsif (match = MODULE_PATTERN.match(line))
+        { kind: "module", name: match[1] }
+      elsif (match = DEF_PATTERN.match(line))
+        { kind: "def", name: match[1] }
+      end
+    end
+
+    def next_code_line_is_task?(lines, start_index)
+      lines[start_index..].to_a.each do |line|
+        next if line.strip.empty? || comment_line?(line)
+
+        match = DSL_CALL_PATTERN.match(line)
+        return match && match[:name] == "task"
+      end
+      false
+    end
+
+    def dsl_entry_finish_index(lines, start_index)
+      return start_index unless lines[start_index].match?(/\bdo\b/)
+
+      ruby_block_finish_index(lines, start_index)
+    end
+
+    def ruby_block_finish_index(lines, start_index)
+      depth = 0
+      cursor = start_index
+      while cursor < lines.length
+        stripped = lines[cursor].strip
+        depth += stripped.scan(/\bdo\b/).length
+        depth += 1 if declaration_for_line(stripped) || stripped.match?(/\A(begin|if|unless|case|while|until|for)\b/)
+        depth -= 1 if stripped == "end"
+        return cursor if depth <= 0 && cursor > start_index
+
+        cursor += 1
+      end
+      lines.length - 1
+    end
+
+    def begin_block_signature(text)
+      require_path = text[/^\s*require(?:_relative)?\s+["']([^"']+)["']/, 1]
+      return "begin:require:#{require_path}" if require_path
+
+      "begin:#{text.lines.first.to_s.strip}"
+    end
+
+    def dsl_entry_signature(name, line)
+      case name
+      when "source", "gemspec"
+        name
+      when "git_source", "gem", "eval_gemfile", "platform", "group", "task"
+        first_argument = line[/\b#{Regexp.escape(name)}\s*(?:\(|\s)\s*["']([^"']+)["']/, 1] ||
+          line[/\b#{Regexp.escape(name)}\s*(?:\(|\s)\s*:([a-zA-Z_]\w*[!?=]?)/, 1]
+        first_argument ? "#{name}:#{normalize_dsl_argument(name, first_argument)}" : "#{name}:#{line.strip}"
+      when "desc"
+        "desc:#{line.strip}"
+      end
+    end
+
+    def normalize_dsl_argument(name, argument)
+      return argument.gsub(%r{/r\d+/}, "/") if name == "eval_gemfile"
+
+      argument
+    end
+
+    def dsl_singleton_entry?(entry)
+      %w[source gemspec].include?(entry[:name])
+    end
+
+    def normalize_rakefile_default_task_scaffold(content)
+      lines = normalize_source(content).split("\n")
+      desc_index = lines.find_index { |line| line.strip == RAKEFILE_DEFAULT_TASK_DESC }
+      return content unless desc_index
+
+      comment_index = preceding_code_line_index(lines, desc_index - 1)
+      return content unless comment_index && lines[comment_index].strip == RAKEFILE_DEFAULT_TASK_COMMENT
+
+      next_code_index = next_code_line_index(lines, desc_index + 1)
+      return content if next_code_index && lines[next_code_index].match?(/\Atask\s+:default\b/)
+
+      task_index = lines.each_index.find { |index| lines[index].match?(/\Atask\s+:default\b/) }
+      return content unless task_index
+
+      finish_index = dsl_entry_finish_index(lines, task_index)
+      task_block = lines[task_index..finish_index]
+      lines[task_index..finish_index] = []
+      insertion_index = lines.find_index { |line| line.strip == RAKEFILE_DEFAULT_TASK_DESC } + 1
+      insertion = task_block.dup
+      insertion << "" unless lines[insertion_index].to_s.strip.empty?
+      lines.insert(insertion_index, *insertion)
+      "#{lines.join("\n").sub(/\n+\z/, "")}\n"
+    end
+
+    def preceding_code_line_index(lines, start_index)
+      start_index.downto(0) do |index|
+        next if lines[index].strip.empty?
+
+        return index
+      end
+      nil
+    end
+
+    def next_code_line_index(lines, start_index)
+      start_index.upto(lines.length - 1) do |index|
+        next if lines[index].strip.empty?
+
+        return index
+      end
+      nil
+    end
+
+    def surfaces_for_owner(owner_name:, comment_entries:)
+      filtered_entries = comment_entries.filter { |entry| doc_comment_content?(entry[:raw]) }
+      return [] if filtered_entries.empty?
+
+      start_line = filtered_entries.first[:line]
+      end_line = filtered_entries.last[:line]
+      doc_surface = Ast::Merge.discovered_surface(
+        surface_kind: "ruby_doc_comment",
+        declared_language: "yard",
+        effective_language: "yard",
+        address: "document[0] > ruby_doc_comment[#{owner_name}]",
+        parent_address: "document[0]",
+        owner: Ast::Merge.surface_owner_ref(kind: "owned_region", address: "/declarations/#{owner_name}"),
+        span: Ast::Merge.surface_span(start_line: start_line, end_line: end_line),
+        reconstruction_strategy: "rewrite_with_prefix_preservation",
+        metadata: {
+          owner_signature: owner_name,
+          comment_prefix: comment_prefix_for(filtered_entries.first[:raw]),
+          entries: filtered_entries.map { |entry| { line: entry[:line], raw: entry[:raw] } }
+        }
+      )
+
+      [doc_surface] + example_surfaces_for(doc_surface)
+    end
+
+    def example_surfaces_for(surface)
+      entries = Array(surface.dig(:metadata, :entries))
+      normalized = entries.map { |entry| normalize_comment_content(entry[:raw]) }
+
+      normalized.each_with_index.filter_map do |content, tag_index|
+        match = EXAMPLE_TAG.match(content)
+        next unless match
+
+        body_start = tag_index + 1
+        body_end = next_tag_index(normalized, body_start) || normalized.length
+        next if body_start >= body_end
+
+        body_entries = entries[body_start...body_end]
+        next if body_entries.nil? || body_entries.empty?
+
+        declared_language = declared_example_language(match[:rest]) || "ruby"
+        Ast::Merge.discovered_surface(
+          surface_kind: "yard_example_block",
+          declared_language: declared_language,
+          effective_language: declared_language,
+          address: "#{surface[:address]} > yard_example[#{tag_index}]",
+          parent_address: surface[:address],
+          owner: Ast::Merge.surface_owner_ref(kind: "owned_region", address: surface[:address]),
+          span: Ast::Merge.surface_span(start_line: body_entries.first[:line], end_line: body_entries.last[:line]),
+          reconstruction_strategy: "rewrite_with_prefix_preservation",
+          metadata: {
+            tag_kind: "example",
+            tag_index: tag_index,
+            tag_text: normalized[tag_index],
+            comment_prefix: surface.dig(:metadata, :comment_prefix)
+          }
+        )
+      end
+    end
+
+    def next_tag_index(normalized_lines, start_index)
+      normalized_lines.each_with_index do |content, index|
+        next if index < start_index
+        return index if TAG_PREFIX.match?(content)
+      end
+      nil
+    end
+
+    def normalize_source(source)
+      source.gsub(/\r\n?/, "\n")
+    end
+
+    def normalize_comment_content(raw)
+      raw.to_s.sub(/\A\s*#\s?/, "").strip
+    end
+
+    def doc_comment_content?(raw)
+      content = normalize_comment_content(raw)
+      return false if content.empty?
+      return false if DIRECTIVE_LINE.match?(content)
+      return false if MAGIC_COMMENT_PREFIXES.any? { |prefix| content.start_with?("#{prefix}:") }
+
+      true
+    end
+
+    def comment_prefix_for(raw)
+      raw.to_s[/\A\s*#\s*/] || "# "
+    end
+
+    def declared_example_language(rest)
+      match = rest.to_s.strip.match(/\A\[(?<language>[^\]]+)\]/)
+      language = match && match[:language]
+      return if language.nil? || language.empty?
+
+      language.downcase.tr("-", "_")
+    end
+
+    module_function(
+      :ruby_feature_profile,
+      :available_ruby_backends,
+      :ruby_backend_feature_profile,
+      :ruby_plan_context,
+      :parse_ruby,
+      :match_ruby_owners,
+      :merge_ruby,
+      :ruby_discovered_surfaces,
+      :ruby_delegated_child_operations,
+      :apply_ruby_delegated_child_outputs,
+      :merge_ruby_with_reviewed_nested_outputs,
+      :merge_ruby_with_reviewed_nested_outputs_from_replay_bundle,
+      :merge_ruby_with_reviewed_nested_outputs_from_replay_bundle_envelope,
+      :merge_ruby_with_reviewed_nested_outputs_from_review_state,
+      :merge_ruby_with_reviewed_nested_outputs_from_review_state_envelope,
+      :merge_ruby_with_nested_outputs,
+      :analyze_ruby_document,
+      :collect_ruby_require_entries,
+      :collect_ruby_declaration_entries,
+      :unsupported_feature_result
+    )
+  end
+end

data/lib/ruby-merge.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ruby/merge"

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: ruby-merge
+version: !ruby/object:Gem::Version
+  version: 7.0.0
+platform: ruby
+authors:
+- Peter H. Boling
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIEgDCCAuigAwIBAgIBATANBgkqhkiG9w0BAQsFADBDMRUwEwYDVQQDDAxwZXRl
+  ci5ib2xpbmcxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkW
+  A2NvbTAeFw0yNTA1MDQxNTMzMDlaFw00NTA0MjkxNTMzMDlaMEMxFTATBgNVBAMM
+  DHBldGVyLmJvbGluZzEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPy
+  LGQBGRYDY29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAruUoo0WA
+  uoNuq6puKWYeRYiZekz/nsDeK5x/0IEirzcCEvaHr3Bmz7rjo1I6On3gGKmiZs61
+  LRmQ3oxy77ydmkGTXBjruJB+pQEn7UfLSgQ0xa1/X3kdBZt6RmabFlBxnHkoaGY5
+  mZuZ5+Z7walmv6sFD9ajhzj+oIgwWfnEHkXYTR8I6VLN7MRRKGMPoZ/yvOmxb2DN
+  coEEHWKO9CvgYpW7asIihl/9GMpKiRkcYPm9dGQzZc6uTwom1COfW0+ZOFrDVBuV
+  FMQRPswZcY4Wlq0uEBLPU7hxnCL9nKK6Y9IhdDcz1mY6HZ91WImNslOSI0S8hRpj
+  yGOWxQIhBT3fqCBlRIqFQBudrnD9jSNpSGsFvbEijd5ns7Z9ZMehXkXDycpGAUj1
+  to/5cuTWWw1JqUWrKJYoifnVhtE1o1DZ+LkPtWxHtz5kjDG/zR3MG0Ula0UOavlD
+  qbnbcXPBnwXtTFeZ3C+yrWpE4pGnl3yGkZj9SMTlo9qnTMiPmuWKQDatAgMBAAGj
+  fzB9MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBQE8uWvNbPVNRXZ
+  HlgPbc2PCzC4bjAhBgNVHREEGjAYgRZwZXRlci5ib2xpbmdAZ21haWwuY29tMCEG
+  A1UdEgQaMBiBFnBldGVyLmJvbGluZ0BnbWFpbC5jb20wDQYJKoZIhvcNAQELBQAD
+  ggGBAJbnUwfJQFPkBgH9cL7hoBfRtmWiCvdqdjeTmi04u8zVNCUox0A4gT982DE9
+  wmuN12LpdajxZONqbXuzZvc+nb0StFwmFYZG6iDwaf4BPywm2e/Vmq0YG45vZXGR
+  L8yMDSK1cQXjmA+ZBKOHKWavxP6Vp7lWvjAhz8RFwqF9GuNIdhv9NpnCAWcMZtpm
+  GUPyIWw/Cw/2wZp74QzZj6Npx+LdXoLTF1HMSJXZ7/pkxLCsB8m4EFVdb/IrW/0k
+  kNSfjtAfBHO8nLGuqQZVH9IBD1i9K6aSs7pT6TW8itXUIlkIUI2tg5YzW6OFfPzq
+  QekSkX3lZfY+HTSp/o+YvKkqWLUV7PQ7xh1ZYDtocpaHwgxe/j3bBqHE+CUPH2vA
+  0V/FwdTRWcwsjVoOJTrYcff8pBZ8r2MvtAc54xfnnhGFzeRHfcltobgFxkAXdE6p
+  DVjBtqT23eugOqQ73umLcYDZkc36vnqGxUBSsXrzY9pzV5gGr2I8YUxMqf6ATrZt
+  L9nRqA==
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ast-merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+- !ruby/object:Gem::Dependency
+  name: tree_haver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 7.0.0
+description: Tree-sitter-backed Ruby family substrate for Structured Merge.
+email:
+- info@structuredmerge.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/ruby-merge.rb
+- lib/ruby/merge.rb
+- lib/ruby/merge/version.rb
+homepage: https://github.com/structuredmerge/structuredmerge-ruby
+licenses:
+- AGPL-3.0-only
+- PolyForm-Small-Business-1.0.0
+metadata:
+  homepage_uri: https://structuredmerge.org
+  source_code_uri: https://github.com/structuredmerge/structuredmerge-ruby/tree/v7.0.0
+  changelog_uri: https://github.com/structuredmerge/structuredmerge-ruby/blob/v7.0.0/CHANGELOG.md
+  bug_tracker_uri: https://github.com/structuredmerge/structuredmerge-ruby/issues
+  documentation_uri: https://www.rubydoc.info/gems/ruby-merge/7.0.0
+  funding_uri: https://github.com/sponsors/pboling
+  wiki_uri: https://github.com/structuredmerge/structuredmerge-ruby/wiki
+  discord_uri: https://discord.gg/3qme4XHNKN
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Structured Merge Ruby substrate analysis for Ruby
+test_files: []