dotenv-merge 7.1.1 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fede421615f3ff3429b4cf53e1cc546ddc9baad1c8d45188568519d0b2d8e2d
-  data.tar.gz: 47d52ac38e22ea37ec80b688d754a56b6b35738272bedb09a874aaa3c5e43b89
+  metadata.gz: 46e142ff15dc1e96e72670426fb814afdef0bcc45ad9debb6053e0bec292470f
+  data.tar.gz: 74b5ab3adb662871181f0127296814062dcb8eb5754a26aeca939431439261c4
 SHA512:
-  metadata.gz: 9dbbb5092feeb59fbc406d3df3153258a5f17999ba51078c3d4e418fd4897d5e7bd92028b3bae6b10ec93f5b4941b225d46a017e83a57b9652e62a4ed9c04edb
-  data.tar.gz: 0a1e1f19518106ad1d08b2e0097a2fc0b3e928a0816db6fde0cd0abae13ed651f3422d9845464b65cee6b7f3ca3f0cbafdb90aca1970a4606c7a34bc1b1b38c6
+  metadata.gz: 0cb95e7ceb06abc054212ceb2889924fd7d7f922c58e06803dd1d2d2c15c08142bffb1172352397b3b5c0acf2e36dbcd4bf4101fa6212752bff6572a64c4023e
+  data.tar.gz: afaef8d76571e4c56f8479bb4d787e35a2fe5a9648bf5f77995ab11ea8823dface498f83431ee5617fc68d3fee19f54b7904da163e7b097dbe9e707bcebacce2

data/README.md

@@ -85,7 +85,7 @@ File.write("merged.env", result.to_s)
 
 ### Compatibility
 
-Compatible with MRI Ruby 4.0.0+, and concordant releases of JRuby, and TruffleRuby.
+Compatible with MRI Ruby 4.0.0+, JRuby, and TruffleRuby.
 CI workflows and Appraisals are generated for MRI Ruby 4.0.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
@@ -223,20 +223,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/dotenv/merge/file_analysis.rb

@@ -29,7 +29,7 @@ module Dotenv
       DEFAULT_FREEZE_TOKEN = 'dotenv-merge'
 
       # @return [CommentTracker] Comment tracker for this file
-      attr_reader :comment_tracker
+      attr_reader :comment_tracker, :structural_diagnostics
 
       # Initialize file analysis with dotenv parser
       #
@@ -41,6 +41,7 @@ module Dotenv
         @source = source
         @freeze_token = freeze_token
         @signature_generator = signature_generator
+        @structural_diagnostics = []
         # **options captures any additional parameters (e.g., node_typing) for forward compatibility
 
         # Parse all lines
@@ -285,6 +286,11 @@ module Dotenv
           case marker[:type]
           when :freeze
             if open_marker
+              @structural_diagnostics << {
+                category: :freeze_ambiguity,
+                line: marker[:line],
+                message: 'Nested freeze marker'
+              }.freeze
               DebugLogger.warning("Nested freeze block at line #{marker[:line]}, ignoring")
             else
               open_marker = marker
@@ -299,12 +305,24 @@ module Dotenv
               )
               open_marker = nil
             else
+              @structural_diagnostics << {
+                category: :freeze_ambiguity,
+                line: marker[:line],
+                message: 'Unfreeze marker without matching freeze marker'
+              }.freeze
               DebugLogger.warning("Unfreeze without freeze at line #{marker[:line]}, ignoring")
             end
           end
         end
 
-        DebugLogger.warning("Unclosed freeze block starting at line #{open_marker[:line]}") if open_marker
+        if open_marker
+          @structural_diagnostics << {
+            category: :freeze_ambiguity,
+            line: open_marker[:line],
+            message: 'Unclosed freeze marker'
+          }.freeze
+          DebugLogger.warning("Unclosed freeze block starting at line #{open_marker[:line]}")
+        end
 
         blocks
       end

data/lib/dotenv/merge/provider.rb

@@ -0,0 +1,690 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Dotenv
+  module Merge
+    # Source-preserving, base-aware provider for dotenv assignment documents.
+    # rubocop:disable Metrics/AbcSize, Metrics/BlockLength, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- provider planning, rendering, and reporting form one boundary
+    class Provider
+      DEFAULT_PROFILE = :source_preserving
+      DIALECTS = %i[dotenv].freeze
+
+      Analysis = Data.define(:role, :source, :file, :lines, :assignments, :by_key, :unowned, :issues)
+      Decision = Data.define(:key, :base, :ours, :theirs, :selected_role, :classification, :conflict)
+
+      def provider_id = 'ruby.dotenv'
+      def family = 'dotenv'
+
+      def capabilities
+        {
+          operations: Ast::Merge::ProviderContract::OPERATIONS,
+          dialects: DIALECTS,
+          backends: [Dotenv::Merge::BACKEND_REFERENCE.id.to_sym],
+          profiles: [DEFAULT_PROFILE],
+          role: :workflow,
+          source_preservation: %i[exact_source assignment_fragments line_provenance reparse]
+        }.freeze
+      end
+
+      def analyze(request)
+        analysis = analyze_role(:source, request.fetch(:source))
+        result(
+          :analyze,
+          request,
+          analysis: analysis_payload(analysis),
+          diagnostics: diagnostics_for(analysis),
+          verification: { source_parsed: true, structurally_unambiguous: analysis.issues.empty? }
+        )
+      end
+
+      def diff2(request)
+        before = analyze_role(:before, request.fetch(:before_source))
+        after = analyze_role(:after, request.fetch(:after_source))
+        changes = assignment_changes(before, after)
+        result(
+          :diff2,
+          request,
+          diff: { before: analysis_payload(before), after: analysis_payload(after), changes: changes },
+          changes: changes,
+          diagnostics: diagnostics_for(before, after),
+          verification: { before_parsed: true, after_parsed: true }
+        )
+      end
+
+      def merge2(request)
+        incoming = request.fetch(:incoming_source)
+        current = request.fetch(:current_source)
+        inputs = [
+          analyze_role(:incoming, incoming),
+          analyze_role(:current, current)
+        ]
+        unsafe = inputs.reject { |analysis| analysis.issues.empty? }
+        unless unsafe.empty?
+          return unsafe_failure(
+            :merge2,
+            request,
+            unsafe,
+            message: 'dotenv merge2 input is structurally ambiguous'
+          )
+        end
+
+        merged = SmartMerger.new(incoming, current, add_template_only_nodes: true).merge.to_s
+        output = analyze_role(:output, merged)
+        unless output.issues.empty?
+          return unsafe_failure(
+            :merge2,
+            request,
+            [output],
+            message: 'dotenv merge2 output is structurally ambiguous'
+          )
+        end
+
+        result(
+          :merge2,
+          request,
+          output: merged,
+          render_report: { strategy: :dotenv_smart_merger, synthesis: :family_emission },
+          verification: { output_reparsed: true, ordered_assignments: semantic_assignments(output) }
+        )
+      rescue Dotenv::Merge::ParseError => e
+        failure(:merge2, request, category: :parse_error, message: e.message)
+      end
+
+      def merge3(request)
+        analyses = %i[base ours theirs].to_h do |role|
+          [role, analyze_role(role, request.fetch(:"#{role}_source"))]
+        end
+        exact_role = exact_revision_role(analyses)
+        if exact_role
+          winner = analyses.fetch(exact_role)
+          return unsafe_conflict(request, analyses, [winner]) unless winner.issues.empty?
+
+          return render_exact(request, analyses, exact_role)
+        end
+
+        unsafe = analyses.values.reject { |analysis| analysis.issues.empty? }
+        return unsafe_conflict(request, analyses, unsafe) unless unsafe.empty?
+        return unowned_conflict(request, analyses) unless unowned_unchanged?(analyses)
+
+        decisions = three_way_decisions(analyses)
+        conflicts = decisions.select(&:conflict)
+        return render_conflicts(request, analyses, decisions, conflicts) unless conflicts.empty?
+
+        render_composite(request, analyses, decisions)
+      end
+
+      private
+
+      def analyze_role(role, source)
+        file = FileAnalysis.new(source)
+        lines = source.lines.each_index.map { |index| file.line_at(index + 1) }
+        assignments = file.all_assignments
+        grouped = assignments.group_by(&:key)
+        issues = file.structural_diagnostics.dup
+        grouped.each do |key, values|
+          next if values.one?
+
+          issues << { category: :duplicate_key, key: key, message: "Duplicate dotenv key #{key}" }.freeze
+        end
+        lines.select(&:invalid?).each do |line|
+          issues << {
+            category: :invalid_line,
+            line: line.line_number,
+            message: "Invalid dotenv line #{line.line_number}"
+          }.freeze
+        end
+        if file.structural_owners.any? { |owner| owner.is_a?(FreezeNode) }
+          issues << { category: :freeze_block, message: 'Freeze blocks require an exact one-sided merge' }.freeze
+        end
+
+        Analysis.new(
+          role: role,
+          source: source,
+          file: file,
+          lines: lines.freeze,
+          assignments: assignments.freeze,
+          by_key: grouped.transform_values(&:first).freeze,
+          unowned: lines.reject(&:assignment?).map(&:raw).freeze,
+          issues: issues.freeze
+        )
+      end
+
+      def analysis_payload(analysis)
+        {
+          dialect: 'dotenv',
+          backend: Dotenv::Merge::BACKEND_REFERENCE.id,
+          assignments: semantic_assignments(analysis),
+          comment_capability: analysis.file.comment_capability.to_h,
+          comment_support_style: analysis.file.comment_support_style.to_h,
+          structurally_unambiguous: analysis.issues.empty?
+        }
+      end
+
+      def semantic_assignments(analysis)
+        analysis.assignments.map do |line|
+          { key: line.key, value: line.value, export: line.export? }.freeze
+        end.freeze
+      end
+
+      def line_state(line)
+        line && [line.key, line.value, line.export?, line.raw]
+      end
+
+      def exact_revision_role(analyses)
+        return :ours if analyses[:ours].source == analyses[:theirs].source
+        return :ours if analyses[:base].source == analyses[:theirs].source
+
+        :theirs if analyses[:base].source == analyses[:ours].source
+      end
+
+      def render_exact(request, analyses, role)
+        rendered = render_plan(request, [whole_source_fragment(role, analyses.fetch(role).source)])
+        verification = verify_output(rendered.content, analyses.fetch(role).assignments, role)
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          changes: assignment_changes(analyses[:base], analyses.fetch(role)),
+          diagnostics: diagnostics_for(*analyses.values),
+          render_report: render_report(rendered, :exact_revision),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def assignment_changes(before, after)
+        ordered_keys(before, after).filter_map do |key|
+          left = before.by_key[key]
+          right = after.by_key[key]
+          next if line_state(left) == line_state(right)
+
+          {
+            path: "/assignments/#{key}",
+            ours: :unchanged,
+            theirs: change_kind(left, right)
+          }.freeze
+        end.freeze
+      end
+
+      def ordered_keys(*analyses)
+        analyses.flat_map { |analysis| analysis.assignments.map(&:key) }.uniq
+      end
+
+      def change_kind(before, after)
+        return :added unless before
+        return :deleted unless after
+
+        :edited
+      end
+
+      def three_way_decisions(analyses)
+        ordered_keys(analyses[:ours], analyses[:theirs], analyses[:base]).map do |key|
+          base = analyses[:base].by_key[key]
+          ours = analyses[:ours].by_key[key]
+          theirs = analyses[:theirs].by_key[key]
+          base_semantic = line_state(base)
+          ours_semantic = line_state(ours)
+          theirs_semantic = line_state(theirs)
+          selected_role =
+            if ours_semantic == theirs_semantic
+              :ours
+            elsif ours_semantic == base_semantic
+              :theirs
+            elsif theirs_semantic == base_semantic
+              :ours
+            end
+          classification = {
+            path: "/assignments/#{key}",
+            ours: side_change(base, ours),
+            theirs: side_change(base, theirs)
+          }.freeze
+          Decision.new(
+            key: key,
+            base: base,
+            ours: ours,
+            theirs: theirs,
+            selected_role: selected_role,
+            classification: classification,
+            conflict: selected_role.nil?
+          )
+        end.freeze
+      end
+
+      def side_change(base, side)
+        return :unchanged if line_state(base) == line_state(side)
+
+        change_kind(base, side)
+      end
+
+      def unowned_unchanged?(analyses)
+        anchor_keys = analyses.values.map { |analysis| analysis.by_key.keys }.reduce(&:intersection)
+        signatures = analyses.transform_values { |analysis| unmanaged_signature(analysis, anchor_keys) }
+        signatures[:base] == signatures[:ours] && signatures[:base] == signatures[:theirs]
+      end
+
+      def unmanaged_signature(analysis, anchor_keys)
+        analysis.lines.filter_map do |line|
+          if line.assignment?
+            [:assignment, line.key] if anchor_keys.include?(line.key)
+          else
+            [:unmanaged, line.raw]
+          end
+        end
+      end
+
+      def render_composite(request, analyses, decisions)
+        by_key = decisions.to_h { |decision| [decision.key, decision] }
+        fragments = []
+        selected = []
+        analyses[:ours].lines.each do |line|
+          if line.assignment?
+            decision = by_key.fetch(line.key)
+            next unless decision.selected_role
+
+            selected_line = decision.public_send(decision.selected_role)
+            next unless selected_line
+
+            fragments << line_fragment(decision.selected_role, selected_line.line_number, decision.key)
+            selected << selected_assignment(decision, selected_line)
+          else
+            fragments << line_fragment(:ours, line.line_number)
+          end
+        end
+        decisions.each do |decision|
+          next if decision.ours || decision.selected_role != :theirs || !decision.theirs
+
+          fragments << line_fragment(:theirs, decision.theirs.line_number, decision.key)
+          selected << selected_assignment(decision, decision.theirs)
+        end
+
+        rendered = render_plan(request, line_bounded_fragments(fragments, analyses))
+        expected = selected.map { |item| item.fetch(:semantic) }
+        verification = verify_composite(rendered.content, expected, selected)
+        return verification_failure(request, rendered, decisions, verification) unless verification[:semantic_match]
+
+        result(
+          :merge3,
+          request,
+          output: rendered.content,
+          changes: decisions.map(&:classification),
+          render_report: render_report(rendered, :exact_assignment_composite),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def selected_assignment(decision, line)
+        {
+          key: decision.key,
+          source_role: decision.selected_role,
+          source_line: line.line_number,
+          source: line.raw,
+          semantic: { key: line.key, value: line.value, export: line.export? }.freeze
+        }.freeze
+      end
+
+      def fragment_content(fragment, analyses)
+        return fragment.content if fragment.is_a?(Ast::Merge::SourceRender::SynthesizedFragment)
+
+        analyses.fetch(fragment.revision).source.lines[fragment.start_line - 1].to_s
+      end
+
+      def line_bounded_fragments(fragments, analyses)
+        fragments.each_with_index.flat_map do |fragment, index|
+          next [fragment] if index == fragments.length - 1
+          next [fragment] if fragment.is_a?(Ast::Merge::SourceRender::ConflictFragment)
+          next [fragment] if fragment_content(fragment, analyses).end_with?("\n")
+
+          content = fragment_content(fragment, analyses)
+          [
+            Ast::Merge::SourceRender::SynthesizedFragment.new(
+              content: "#{content}\n",
+              reason: :assignment_separator,
+              producer: provider_id,
+              metadata: fragment.metadata.merge(copied_source: true)
+            )
+          ]
+        end
+      end
+
+      def verify_composite(output, expected, selected)
+        parsed = analyze_role(:output, output)
+        actual = semantic_assignments(parsed)
+        source_match = parsed.assignments.map(&:raw) == selected.map { |item| item.fetch(:source) }
+        {
+          output_reparsed: true,
+          semantic_match: parsed.issues.empty? && actual == expected && source_match,
+          source_match: source_match,
+          ordered_assignments: actual,
+          assignment_sources: selected.map { |item| item.except(:semantic, :source) }
+        }
+      end
+
+      def verify_output(output, expected_lines, role)
+        parsed = analyze_role(:output, output)
+        expected = expected_lines.map { |line| { key: line.key, value: line.value, export: line.export? }.freeze }
+        {
+          output_reparsed: true,
+          semantic_match: semantic_assignments(parsed) == expected,
+          structurally_unambiguous: parsed.issues.empty?,
+          ordered_assignments: semantic_assignments(parsed),
+          source_role: role
+        }
+      end
+
+      def render_conflicts(request, analyses, decisions, conflicts)
+        if conflicts.any? { |item| item.ours.nil? }
+          return full_file_conflict(
+            request,
+            analyses,
+            decisions,
+            conflicts,
+            :conflict_not_line_addressable
+          )
+        end
+
+        by_key = conflicts.to_h { |conflict| [conflict.key, conflict] }
+        fragments = analyses[:ours].lines.map do |line|
+          conflict = line.assignment? && by_key[line.key]
+          conflict ? conflict_fragment(request, conflict) : line_fragment(:ours, line.line_number)
+        end
+        rendered = render_plan(request, fragments)
+        conflict_failure(request, decisions, conflicts, rendered, :assignment_localized_conflict)
+      end
+
+      def conflict_fragment(request, decision)
+        Ast::Merge::SourceRender::ConflictFragment.new(
+          conflict_id: conflict_id(decision.key),
+          base: conflict_side(request, :base, decision.base),
+          ours: conflict_side(request, :ours, decision.ours),
+          theirs: conflict_side(request, :theirs, decision.theirs),
+          labels: request.fetch(:labels, {}),
+          marker_size: request.fetch(:conflict_marker_size, 7),
+          metadata: { path: decision.classification.fetch(:path), category: conflict_category(decision) }
+        )
+      end
+
+      def conflict_side(request, role, line)
+        return [] unless line
+
+        fragment = line_fragment(role, line.line_number, line.key)
+        source_line = request.fetch(:"#{role}_source").lines[line.line_number - 1].to_s
+        return [fragment] if source_line.end_with?("\n")
+
+        [
+          Ast::Merge::SourceRender::SynthesizedFragment.new(
+            content: "#{source_line}\n",
+            reason: :conflict_line_boundary,
+            producer: provider_id,
+            metadata: { source_role: role, assignment_key: line.key, copied_source: true }
+          )
+        ]
+      end
+
+      def conflict_category(decision)
+        return :delete_edit if decision.ours.nil? || decision.theirs.nil?
+
+        :edit_edit
+      end
+
+      def conflict_id(key)
+        "dotenv-assignment-#{Digest::SHA256.hexdigest(key)[0, 16]}"
+      end
+
+      def conflict_failure(request, decisions, conflicts, rendered, strategy)
+        failure(
+          :merge3,
+          request,
+          category: :merge_conflict,
+          message: 'Dotenv assignments changed incompatibly.',
+          changes: decisions.map(&:classification),
+          conflicts: conflicts.map do |decision|
+            {
+              conflict_id: conflict_id(decision.key),
+              category: conflict_category(decision),
+              path: decision.classification.fetch(:path),
+              change_classification: decision.classification
+            }.freeze
+          end,
+          conflicted_output: rendered.content,
+          conflicted_source: rendered.content,
+          render_report: render_report(rendered, strategy),
+          verification: { base_participated: true }
+        )
+      end
+
+      def unsafe_conflict(request, analyses, unsafe)
+        source_role = unsafe.first.role
+        diagnostics = [{
+          category: :parse_error,
+          severity: :error,
+          message: "#{source_role} structural parse is ambiguous.",
+          blocking: true,
+          source_role: source_role
+        }.freeze, *diagnostics_for(*unsafe)]
+        full_file_conflict(
+          request,
+          analyses,
+          three_way_decisions(analyses),
+          [],
+          :structural_ambiguity,
+          diagnostics: diagnostics
+        )
+      end
+
+      def unowned_conflict(request, analyses)
+        full_file_conflict(
+          request,
+          analyses,
+          three_way_decisions(analyses),
+          [],
+          :unmanaged_source_change,
+          diagnostics: [{
+            category: :unmanaged_source_change,
+            severity: :error,
+            message: 'Non-assignment dotenv source changed independently.',
+            blocking: true
+          }]
+        )
+      end
+
+      def full_file_conflict(request, analyses, decisions, conflicts, reason, diagnostics: nil)
+        conflict = {
+          conflict_id: 'dotenv-conflict-root',
+          category: reason,
+          path: '<unmanaged-source>'
+        }.freeze
+        rendered = render_plan(
+          request,
+          [
+            Ast::Merge::SourceRender::ConflictFragment.new(
+              conflict_id: conflict.fetch(:conflict_id),
+              base: conflict_source(:base, analyses[:base].source),
+              ours: conflict_source(:ours, analyses[:ours].source),
+              theirs: conflict_source(:theirs, analyses[:theirs].source),
+              labels: request.fetch(:labels, {}),
+              marker_size: request.fetch(:conflict_marker_size, 7),
+              metadata: { category: reason }
+            )
+          ]
+        )
+        failure(
+          :merge3,
+          request,
+          category: reason,
+          message: 'Dotenv source cannot be safely combined structurally.',
+          diagnostics: diagnostics,
+          changes: decisions.map(&:classification),
+          conflicts: conflicts.empty? ? [conflict] : conflicts.map { |item| conflict_payload(item) },
+          fallbacks: [{ from: :assignment_composite, to: :full_file_conflict, reason: reason }],
+          conflicted_output: rendered.content,
+          conflicted_source: rendered.content,
+          render_report: render_report(rendered, :full_file_conflict),
+          verification: { base_participated: true },
+          source_role: diagnostics&.first&.fetch(:source_role, nil)
+        )
+      end
+
+      def conflict_source(role, source)
+        return [] if source.empty?
+        return [whole_source_fragment(role, source)] if source.end_with?("\n")
+
+        [
+          Ast::Merge::SourceRender::SynthesizedFragment.new(
+            content: "#{source}\n",
+            reason: :conflict_line_boundary,
+            producer: provider_id,
+            metadata: { source_role: role, copied_source: true }
+          )
+        ]
+      end
+
+      def conflict_payload(decision)
+        return decision if decision.is_a?(Hash)
+
+        {
+          conflict_id: conflict_id(decision.key),
+          category: conflict_category(decision),
+          path: decision.classification.fetch(:path),
+          change_classification: decision.classification
+        }.freeze
+      end
+
+      def whole_source_fragment(role, source)
+        if source.empty?
+          return Ast::Merge::SourceRender::SynthesizedFragment.new(
+            content: '',
+            reason: :exact_empty_source,
+            producer: provider_id,
+            metadata: { source_role: role }
+          )
+        end
+
+        Ast::Merge::SourceRender::SourceFragment.new(
+          revision: role,
+          start_line: 1,
+          end_line: source.lines.length,
+          metadata: { source_role: role }
+        )
+      end
+
+      def line_fragment(role, line_number, key = nil)
+        Ast::Merge::SourceRender::SourceFragment.new(
+          revision: role,
+          start_line: line_number,
+          end_line: line_number,
+          metadata: { source_role: role, assignment_key: key }.compact
+        )
+      end
+
+      def render_plan(request, fragments)
+        Ast::Merge::SourceRender::Renderer.new.render(
+          Ast::Merge::SourceRender::Plan.new(
+            sources: {
+              base: request[:base_source].to_s,
+              ours: request[:ours_source].to_s,
+              theirs: request[:theirs_source].to_s
+            },
+            fragments: fragments,
+            metadata: { provider_id: provider_id }
+          )
+        )
+      end
+
+      def render_report(rendered, strategy)
+        {
+          strategy: strategy,
+          line_records: rendered.line_records,
+          synthesized_fragments: rendered.synthesized_fragments,
+          conflicts: rendered.conflicts,
+          verification_input: rendered.verification_input
+        }
+      end
+
+      def diagnostics_for(*analyses)
+        analyses.flat_map do |analysis|
+          analysis.issues.map do |issue|
+            issue.merge(
+              severity: :warning,
+              blocking: false,
+              source_role: analysis.role
+            ).freeze
+          end
+        end.freeze
+      end
+
+      def unsafe_failure(operation, request, analyses, message:)
+        failure(
+          operation,
+          request,
+          category: :structural_ambiguity,
+          message: message,
+          diagnostics: diagnostics_for(*analyses)
+        )
+      end
+
+      def verification_failure(request, rendered, decisions, verification)
+        failure(
+          :merge3,
+          request,
+          category: :verification_failure,
+          message: 'Rendered dotenv assignments did not match the planned ordered semantics.',
+          changes: decisions.map(&:classification),
+          render_report: render_report(rendered, :exact_assignment_composite),
+          verification: verification.merge(base_participated: true)
+        )
+      end
+
+      def result(operation, request, diagnostics: [], changes: [], conflicts: [], fallbacks: [],
+                 render_report: {}, verification: {}, **payload)
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: true,
+          envelope: envelope(
+            request,
+            diagnostics: diagnostics,
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            render_report: render_report,
+            verification: verification
+          ),
+          **payload
+        )
+      end
+
+      def failure(operation, request, category:, message:, diagnostics: nil, changes: [], conflicts: [],
+                  fallbacks: [], render_report: {}, verification: {}, **payload)
+        diagnostics ||= [{ category: category, severity: :error, message: message, blocking: true }]
+        Ast::Merge::ProviderResult.build(
+          operation: operation,
+          success: false,
+          envelope: envelope(
+            request,
+            diagnostics: diagnostics,
+            changes: changes,
+            conflicts: conflicts,
+            fallbacks: fallbacks,
+            render_report: render_report,
+            verification: verification
+          ),
+          **payload
+        )
+      end
+
+      def envelope(request, **fields)
+        {
+          provider: {
+            provider_id: provider_id,
+            family: family,
+            dialect: request[:dialect] || :dotenv,
+            backend: request[:backend] || Dotenv::Merge::BACKEND_REFERENCE.id,
+            package: 'dotenv-merge',
+            package_version: Dotenv::Merge::Version::VERSION
+          },
+          profile: { profile_id: request[:profile_id] || DEFAULT_PROFILE }
+        }.merge(fields)
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/BlockLength, Metrics/ClassLength, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity
+  end
+end

data/lib/dotenv/merge/version.rb

@@ -5,7 +5,7 @@ module Dotenv
     # 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/dotenv/merge.rb

@@ -69,12 +69,24 @@ module Dotenv
     autoload :FreezeNode, 'dotenv/merge/freeze_node'
     autoload :FileAnalysis, 'dotenv/merge/file_analysis'
     autoload :MergeResult, 'dotenv/merge/merge_result'
+    autoload :Provider, 'dotenv/merge/provider'
     autoload :SmartMerger, 'dotenv/merge/smart_merger'
+
+    module_function
+
+    def merge_provider
+      @merge_provider ||= Provider.new
+    end
+
+    def register_provider!(replace: false)
+      Ast::Merge.register_provider(merge_provider, replace: replace)
+    end
   end
 end
 
 require_relative 'merge/backend'
 Dotenv::Merge.register_backend!
+Dotenv::Merge.register_provider!
 
 # Register with ast-merge's MergeGemRegistry for RSpec dependency tags
 # Only register if MergeGemRegistry is loaded (i.e., in test environment)

data/sig/dotenv/merge.rbs

@@ -4,5 +4,24 @@ module Dotenv
       VERSION: String
     end
     VERSION: String
+
+    BACKEND_REFERENCE: untyped
+
+    def self.merge_provider: () -> Provider
+    def self.register_provider!: (?replace: bool) -> untyped
+
+    class Provider
+      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
+
+    class FileAnalysis
+      attr_reader structural_diagnostics: Array[Hash[Symbol, untyped]]
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dotenv-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: plain-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.17
+        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.17
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -196,7 +196,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 3.2.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -206,7 +206,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 3.2.2
 - !ruby/object:Gem::Dependency
   name: kettle-test
   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
@@ -320,6 +320,7 @@ files:
 - lib/dotenv/merge/file_analysis.rb
 - lib/dotenv/merge/freeze_node.rb
 - lib/dotenv/merge/merge_result.rb
+- lib/dotenv/merge/provider.rb
 - lib/dotenv/merge/smart_merger.rb
 - lib/dotenv/merge/version.rb
 - sig/dotenv/merge.rbs
@@ -329,10 +330,10 @@ licenses:
 - PolyForm-Small-Business-1.0.0
 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/dotenv-merge/7.1.1
+  documentation_uri: https://www.rubydoc.info/gems/dotenv-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/dotenv-merge