dotenv-merge 1.0.2 → 7.1.1

data/lib/dotenv/merge/smart_merger.rb

@@ -25,6 +25,11 @@ module Dotenv
     #     node_typing: { "EnvLine" => ->(n) { NodeTyping.with_merge_type(n, :secret) } },
     #     preference: { default: :destination, secret: :template })
     class SmartMerger < ::Ast::Merge::SmartMergerBase
+      include Ast::Merge::TrailingGroups::DestIterate
+      include Ast::Merge::CommentLayoutEmissionSupport
+
+      attr_reader :corruption_handling
+
       # Initialize a new SmartMerger
       #
       # @param template_content [String] Content of the template dotenv file
@@ -33,6 +38,10 @@ module Dotenv
       # @param preference [Symbol, Hash] :destination, :template, or per-type Hash
       # @param add_template_only_nodes [Boolean] Whether to add template-only env vars
       #   (default: false)
+      # @param remove_template_missing_nodes [Boolean] Whether to remove destination-only
+      #   env vars that do not exist in the template (default: false)
+      # @param corruption_handling [Symbol] How to handle detected historical
+      #   duplicate-prefix corruption (:heal, :warn, :error, :skip)
       # @param freeze_token [String] Token for freeze block markers
       #   (default: "dotenv-merge")
       # @param match_refiner [#call, nil] Match refiner for fuzzy matching
@@ -47,6 +56,8 @@ module Dotenv
         signature_generator: nil,
         preference: :destination,
         add_template_only_nodes: false,
+        remove_template_missing_nodes: false,
+        corruption_handling: :heal,
         freeze_token: nil,
         match_refiner: nil,
         regions: nil,
@@ -54,12 +65,16 @@ module Dotenv
         node_typing: nil,
         **options
       )
+        @remove_template_missing_nodes = remove_template_missing_nodes
+        @corruption_handling = ::Ast::Merge::Healer.normalize_mode(corruption_handling)
+
         super(
           template_content,
           dest_content,
           signature_generator: signature_generator,
           preference: preference,
           add_template_only_nodes: add_template_only_nodes,
+          remove_template_missing_nodes: remove_template_missing_nodes,
           freeze_token: freeze_token,
           match_refiner: match_refiner,
           regions: regions,
@@ -78,7 +93,7 @@ module Dotenv
 
       # @return [String] The default freeze token
       def default_freeze_token
-        "dotenv-merge"
+        'dotenv-merge'
       end
 
       # @return [Class, nil] No separate resolver class for dotenv
@@ -106,151 +121,112 @@ module Dotenv
         ParseError
       end
 
-      # Perform the dotenv-specific merge with custom alignment logic
+      # Perform the dotenv-specific merge with structural-owner alignment.
       #
       # @return [MergeResult] The merge result
       def perform_merge
-        alignment = align_statements
+        template_nodes = @template_analysis.structural_owners
+        dest_nodes = @dest_analysis.structural_owners
+
+        emit_root_boundary(:preamble)
+
+        template_index = build_match_index(template_nodes, @template_analysis)
+        dest_sigs = destination_signature_set(dest_nodes, @dest_analysis)
+        trailing_groups, matched_indices = build_dest_iterate_trailing_groups(
+          template_nodes: template_nodes,
+          dest_sigs: dest_sigs,
+          signature_for: ->(node) { freeze_node?(node) ? nil : @template_analysis.generate_signature(node) },
+          add_template_only_nodes: @add_template_only_nodes
+        )
 
-        DebugLogger.debug("Alignment complete", {
-          total_entries: alignment.size,
-          matches: alignment.count { |e| e[:type] == :match },
-          template_only: alignment.count { |e| e[:type] == :template_only },
-          dest_only: alignment.count { |e| e[:type] == :dest_only },
-        })
+        matched_template_indices = Set.new
+        consumed_indices = Set.new
 
-        process_alignment(alignment)
-        @result
-      end
+        emit_prefix_trailing_group(trailing_groups, consumed_indices) do |info|
+          add_template_only_node(info[:node], template_nodes.index(info[:node]))
+        end
 
-      private
+        dest_nodes.each do |dest_node|
+          if freeze_node?(dest_node)
+            @result.add_freeze_block(dest_node)
+            next
+          end
 
-      # Align statements between template and destination
-      # @return [Array<Hash>] Alignment entries
-      def align_statements
-        template_stmts = @template_analysis.statements
-        dest_stmts = @dest_analysis.statements
-
-        # Build signature maps
-        _template_sigs = build_signature_map(template_stmts, @template_analysis)
-        dest_sigs = build_signature_map(dest_stmts, @dest_analysis)
-
-        alignment = []
-        matched_dest_indices = Set.new
-
-        # First pass: find matches for template statements
-        template_stmts.each_with_index do |stmt, t_idx|
-          sig = @template_analysis.generate_signature(stmt)
-
-          if sig && dest_sigs.key?(sig)
-            d_idx = dest_sigs[sig]
-            alignment << {
-              type: :match,
-              template_stmt: stmt,
-              dest_stmt: dest_stmts[d_idx],
-              template_index: t_idx,
-              dest_index: d_idx,
-              signature: sig,
-            }
-            matched_dest_indices << d_idx
+          match_key = @dest_analysis.generate_signature(dest_node)
+          template_match = find_unmatched(template_index[match_key], matched_template_indices)
+
+          if template_match
+            matched_template_indices << template_match[:index]
+            consumed_indices << template_match[:index]
+            process_match(template_match[:node], dest_node)
+            flush_ready_trailing_groups(
+              trailing_groups: trailing_groups,
+              matched_indices: matched_indices,
+              consumed_indices: consumed_indices
+            ) do |info|
+              add_template_only_node(info[:node], info[:index])
+            end
           else
-            alignment << {
-              type: :template_only,
-              template_stmt: stmt,
-              template_index: t_idx,
-              signature: sig,
-            }
+            process_dest_only(dest_node, dest_nodes.index(dest_node))
           end
         end
 
-        # Second pass: add destination-only statements
-        dest_stmts.each_with_index do |stmt, d_idx|
-          next if matched_dest_indices.include?(d_idx)
-
-          alignment << {
-            type: :dest_only,
-            dest_stmt: stmt,
-            dest_index: d_idx,
-            signature: @dest_analysis.generate_signature(stmt),
-          }
+        emit_remaining_trailing_groups(
+          trailing_groups: trailing_groups,
+          consumed_indices: consumed_indices
+        ) do |info|
+          add_template_only_node(info[:node], info[:index])
         end
 
-        # Sort by destination order (preserve dest structure), then template order for additions
-        sort_alignment(alignment, dest_stmts.size)
+        emit_root_boundary(:postlude)
+
+        merged_content = @result.to_s
+        healed_content = collapse_cross_source_preamble_prefixes(merged_content)
+        update_result_content(@result, healed_content) if healed_content != merged_content
+
+        @result
       end
 
-      # Build a map of signature => statement index
-      # @param statements [Array] Statements
-      # @param analysis [FileAnalysis] Analysis for signature generation
-      # @return [Hash]
-      def build_signature_map(statements, analysis)
-        map = {}
-        statements.each_with_index do |stmt, idx|
-          sig = analysis.generate_signature(stmt)
-          # First occurrence wins
-          map[sig] ||= idx if sig
-        end
-        map
-      end
-
-      # Sort alignment entries for output
-      # @param alignment [Array<Hash>] Alignment entries
-      # @param dest_size [Integer] Number of destination statements
-      # @return [Array<Hash>]
-      def sort_alignment(alignment, dest_size)
-        alignment.sort_by do |entry|
-          case entry[:type]
-          when :match
-            # Matches: use destination position
-            [entry[:dest_index], 0]
-          when :dest_only
-            # Destination-only: use destination position
-            [entry[:dest_index], 0]
-          when :template_only
-            # Template-only: add at end, in template order
-            [dest_size + entry[:template_index], 1]
-          end
+      private
+
+      def build_match_index(nodes, analysis)
+        index = Hash.new { |h, k| h[k] = [] }
+        nodes.each_with_index do |node, idx|
+          next if freeze_node?(node)
+
+          key = analysis.generate_signature(node)
+          index[key] << { node: node, index: idx }
         end
+        index
       end
 
-      # Process alignment entries and build result
-      # @param alignment [Array<Hash>] Alignment entries
-      # @return [void]
-      def process_alignment(alignment)
-        alignment.each do |entry|
-          case entry[:type]
-          when :match
-            process_match(entry)
-          when :template_only
-            process_template_only(entry)
-          when :dest_only
-            process_dest_only(entry)
-          end
+      def destination_signature_set(nodes, analysis)
+        nodes.each_with_object(Set.new) do |node, signatures|
+          next if freeze_node?(node)
+
+          signatures << analysis.generate_signature(node)
         end
       end
 
-      # Process a matched entry
-      # @param entry [Hash] Alignment entry
-      # @return [void]
-      def process_match(entry)
-        dest_stmt = entry[:dest_stmt]
+      def find_unmatched(entries, matched_indices)
+        return unless entries
 
-        # Freeze blocks always win
-        if dest_stmt.is_a?(FreezeNode)
-          @result.add_freeze_block(dest_stmt)
-          return
-        end
+        entries.find { |entry| !matched_indices.include?(entry[:index]) }
+      end
+
+      def trailing_group_node_matched?(node, _signature)
+        freeze_node?(node)
+      end
 
-        # Resolve preference (handles both Symbol and Hash preferences)
-        resolved_pref = resolve_preference(entry[:template_stmt], entry[:dest_stmt])
+      def process_match(template_stmt, dest_stmt)
+        resolved_pref = resolve_preference(template_stmt, dest_stmt)
 
         case resolved_pref
         when :template
-          @result.add_from_template(entry[:template_index], decision: MergeResult::DECISION_TEMPLATE)
-        when :destination
-          @result.add_from_destination(entry[:dest_index], decision: MergeResult::DECISION_DESTINATION)
+          emit_template_preferred_match(template_stmt, dest_stmt)
         else
-          @result.add_from_destination(entry[:dest_index], decision: MergeResult::DECISION_DESTINATION)
+          add_retained_leading_gap(dest_stmt, @dest_analysis, decision: MergeResult::DECISION_DESTINATION)
+          @result.add_raw(node_lines_for(dest_stmt, @dest_analysis), decision: MergeResult::DECISION_DESTINATION)
         end
       end
 
@@ -288,37 +264,284 @@ module Dotenv
         return stmt unless stmt
 
         # Check by class name
-        type_key = stmt.class.name&.split("::")&.last
+        type_key = stmt.class.name&.split('::')&.last
         callable = @node_typing[type_key] || @node_typing[type_key&.to_sym]
         return callable.call(stmt) if callable
 
         stmt
       end
 
-      # Process a template-only entry
-      # @param entry [Hash] Alignment entry
-      # @return [void]
-      def process_template_only(entry)
+      def add_template_only_node(stmt, _index)
         return unless @add_template_only_nodes
+        return if freeze_node?(stmt)
+
+        # Intentional product behavior: template-only dotenv additions do not
+        # import surrounding template comment context. The matrix marks those
+        # comment-bearing template-only cases as out of scope unless this policy
+        # is changed deliberately.
+        @result.add_raw(
+          node_lines_for(
+            stmt,
+            @template_analysis,
+            include_leading_segment: false,
+            include_interstitial_trailing_segment: false
+          ),
+          decision: MergeResult::DECISION_ADDED
+        )
+      end
 
-        # Skip comments and blank lines from template
-        stmt = entry[:template_stmt]
-        return if stmt.is_a?(EnvLine) && (stmt.comment? || stmt.blank?)
+      def process_dest_only(dest_stmt, _dest_index)
+        if remove_destination_only_assignment?(dest_stmt)
+          lines = removed_destination_comment_lines_for(dest_stmt)
+          @result.add_raw(lines, decision: MergeResult::DECISION_DESTINATION) if lines.any?
+        else
+          @result.add_raw(node_lines_for(dest_stmt, @dest_analysis), decision: MergeResult::DECISION_DESTINATION)
+        end
+      end
 
-        @result.add_from_template(entry[:template_index], decision: MergeResult::DECISION_ADDED)
+      def emit_template_preferred_match(template_stmt, dest_stmt)
+        comment_source_node, comment_source_analysis = preferred_comment_source_for(template_stmt, dest_stmt)
+        inline_comment = preferred_inline_comment_for(template_stmt, dest_stmt)
+        add_retained_leading_gap(dest_stmt, @dest_analysis, decision: MergeResult::DECISION_DESTINATION)
+        @result.add_raw(
+          node_lines_for(
+            template_stmt,
+            @template_analysis,
+            comment_source_node: comment_source_node,
+            comment_source_analysis: comment_source_analysis,
+            inline_comment: inline_comment
+          ),
+          decision: MergeResult::DECISION_TEMPLATE
+        )
       end
 
-      # Process a destination-only entry
-      # @param entry [Hash] Alignment entry
-      # @return [void]
-      def process_dest_only(entry)
-        dest_stmt = entry[:dest_stmt]
+      def preferred_comment_source_for(template_stmt, dest_stmt)
+        return [dest_stmt, @dest_analysis] if node_has_leading_comments?(dest_stmt, @dest_analysis)
+        return [template_stmt, @template_analysis] if node_has_leading_comments?(template_stmt, @template_analysis)
 
-        if dest_stmt.is_a?(FreezeNode)
-          @result.add_freeze_block(dest_stmt)
-        else
-          @result.add_from_destination(entry[:dest_index], decision: MergeResult::DECISION_DESTINATION)
+        [template_stmt, @template_analysis]
+      end
+
+      def node_has_leading_comments?(node, analysis)
+        leading_segment_lines_for(node, analysis).any? { |line| !line.to_s.strip.empty? }
+      end
+
+      def preferred_inline_comment_for(template_stmt, dest_stmt)
+        return unless preserve_destination_inline_comment_for_template_match?(template_stmt, dest_stmt)
+
+        destination_inline_comment_for(dest_stmt)
+      end
+
+      def preserve_destination_inline_comment_for_template_match?(template_stmt, dest_stmt)
+        return false unless template_stmt.is_a?(EnvLine) && dest_stmt.is_a?(EnvLine)
+        return false unless template_stmt.assignment? && dest_stmt.assignment?
+        return false unless destination_inline_comment_for(dest_stmt)
+
+        template_inline_comment_for(template_stmt).nil?
+      end
+
+      def remove_destination_only_assignment?(stmt)
+        @remove_template_missing_nodes && stmt.is_a?(EnvLine) && stmt.assignment?
+      end
+
+      def destination_inline_comment_for(stmt)
+        @dest_analysis.comment_tracker.inline_comment_at(stmt.line_number)
+      end
+
+      def template_inline_comment_for(stmt)
+        @template_analysis.comment_tracker.inline_comment_at(stmt.line_number)
+      end
+
+      def freeze_node?(node)
+        node.is_a?(FreezeNode) || (node.respond_to?(:is_a?) && node.is_a?(Ast::Merge::Freezable))
+      end
+
+      def emit_root_boundary(kind)
+        lines = root_boundary_lines_for(kind, @dest_analysis)
+        return if lines.empty?
+
+        decision = MergeResult::DECISION_DESTINATION
+        @result.add_raw(lines, decision: decision)
+      end
+
+      def root_boundary_lines_for(kind, analysis)
+        super(kind, analysis, owners: analysis.structural_owners, fallback_to_owner_bounds: true)
+      end
+
+      def emission_start_line_for(node, analysis)
+        region_start = region_start_line(leading_region_for(node, analysis))
+        preamble_start = analysis.comment_augmenter.preamble_region&.start_line if first_structural_owner?(node,
+                                                                                                           analysis)
+        preceding_blank_line_start(region_start || preamble_start || node.start_line, analysis)
+      end
+
+      def root_boundary_owner_start_line_for(node, analysis)
+        emission_start_line_for(node, analysis)
+      end
+
+      def first_structural_owner?(node, analysis)
+        Array(analysis.structural_owners).first.equal?(node)
+      end
+
+      def node_lines_for(
+        node,
+        analysis,
+        comment_source_node: node,
+        comment_source_analysis: analysis,
+        inline_comment: nil,
+        include_leading_segment: true,
+        include_interstitial_trailing_segment: true
+      )
+        return freeze_block_lines_for(node) if freeze_node?(node)
+
+        leading_lines = if include_leading_segment
+                          leading_segment_lines_for(comment_source_node,
+                                                    comment_source_analysis)
+                        else
+                          []
+                        end
+        node_lines = (node.start_line..node.end_line).filter_map { |line_number| raw_line_at(analysis, line_number) }
+        trailing_lines = if include_interstitial_trailing_segment
+                           interstitial_trailing_segment_lines_for(node,
+                                                                   analysis)
+                         else
+                           []
+                         end
+        leading_lines + apply_inline_comment(node_lines, inline_comment) + trailing_lines
+      end
+
+      def add_retained_leading_gap(node, analysis, decision:)
+        lines = retained_owner_leading_gap_lines_for(node, analysis, owners: analysis.structural_owners)
+        return if lines.empty?
+
+        @result.add_raw(lines, decision: decision)
+      end
+
+      def removed_destination_comment_lines_for(node)
+        inline_lines = []
+
+        if (inline_comment = destination_inline_comment_for(node))
+          inline_lines << promoted_inline_comment_line_for(node, @dest_analysis, inline_comment)
         end
+
+        removed_owner_preserved_lines_for(
+          node,
+          @dest_analysis,
+          owners: @dest_analysis.structural_owners,
+          inline_lines: inline_lines
+        )
+      end
+
+      def interstitial_trailing_segment_lines_for(node, analysis)
+        interstitial_trailing_region_lines_for(node, analysis, owners: analysis.structural_owners)
+      end
+
+      def next_structural_owner_for(node, analysis)
+        owners = Array(analysis.structural_owners)
+        index = owners.index(node)
+        return unless index
+
+        owners[index + 1]
+      end
+
+      def apply_inline_comment(lines, inline_comment)
+        return lines if inline_comment.nil? || lines.empty?
+
+        updated_lines = lines.dup
+        updated_lines[-1] = "#{updated_lines[-1].rstrip} #{inline_comment[:raw].sub(/\A\s+/, '')}"
+        updated_lines
+      end
+
+      def promoted_inline_comment_line_for(node, analysis, inline_comment)
+        raw_line = raw_line_at(analysis, node.start_line)
+        return unless raw_line
+
+        "#{raw_line[/\A\s*/]}#{inline_comment[:raw].sub(/\A\s+/, '')}"
+      end
+
+      def freeze_block_lines_for(node)
+        node.lines.map { |line| line.respond_to?(:raw) ? line.raw : line.to_s }
+      end
+
+      STANDALONE_DOTENV_COMMENT_LINE_RE = /\A\s*#.*\z/
+      private_constant :STANDALONE_DOTENV_COMMENT_LINE_RE
+
+      def collapse_cross_source_preamble_prefixes(content)
+        template_comments, = leading_standalone_comment_run(@template_content.to_s)
+        return content if template_comments.empty?
+
+        merged_comments, remainder = leading_standalone_comment_run(content)
+        return content if merged_comments.empty?
+
+        template_tally = template_comments.tally
+        merged_tally = merged_comments.tally
+        duplicated_template_prefix = template_tally.any? do |line, count|
+          merged_tally.fetch(line, 0) > count
+        end
+        return content unless duplicated_template_prefix
+
+        destination_specific_comments = merged_comments.reject { |line| template_comments.include?(line) }
+        return content if destination_specific_comments.empty?
+
+        should_heal = ::Ast::Merge::Healer.handle(
+          mode: @corruption_handling,
+          kind: :duplicate_template_preamble_prefix,
+          message: 'merged dotenv preamble begins with duplicated template-owned comment lines',
+          prefix: '[dotenv-merge]',
+          error_class: Dotenv::Merge::CorruptionDetectedError,
+          warner: lambda { |formatted|
+            DebugLogger.debug_warning(formatted, {
+                                        template_comment_lines: template_comments.length,
+                                        merged_comment_lines: merged_comments.length,
+                                        destination_specific_comment_lines: destination_specific_comments.length
+                                      })
+          }
+        )
+        return content unless should_heal
+
+        remainder = remainder.sub(/\A(?:\s*\n)+/, '')
+        rebuilt = destination_specific_comments.join("\n")
+        return rebuilt if remainder.empty?
+
+        "#{rebuilt}\n\n#{remainder}"
+      end
+
+      def leading_standalone_comment_run(text)
+        lines = text.to_s.split("\n", -1)
+        comment_lines = []
+        index = 0
+
+        while index < lines.length
+          line = lines[index]
+          if line.strip.empty?
+            comment_lines << line if comment_lines.any?
+            index += 1
+            next
+          end
+
+          break unless STANDALONE_DOTENV_COMMENT_LINE_RE.match?(line)
+
+          comment_lines << line
+          index += 1
+        end
+
+        [comment_lines, lines.drop(index).join("\n")]
+      end
+
+      def raw_line_at(analysis, line_number)
+        line = analysis.line_at(line_number)
+        line.respond_to?(:raw) ? line.raw : line
+      end
+
+      def leading_segment_anchor_line_for(node, analysis, owners: nil, leading_region: nil)
+        region_start = super(node, analysis, owners: owners || analysis.structural_owners, leading_region: leading_region)
+        preamble_start = analysis.comment_augmenter.preamble_region&.start_line if first_structural_owner?(node,
+                                                                                                           analysis)
+        region_start || preamble_start
+      end
+
+      def source_line_at(analysis, line_number)
+        raw_line_at(analysis, line_number)
       end
     end
   end

data/lib/dotenv/merge/version.rb

@@ -2,11 +2,12 @@
 
 module Dotenv
   module Merge
-    # Version information for Dotenv::Merge
+    # Version namespace for this gem.
     module Version
-      # Current version of the dotenv-merge gem
-      VERSION = "1.0.2"
+      # Current gem version.
+      VERSION = '7.1.1'
     end
-    VERSION = Version::VERSION # traditional location
+    # Current gem version exposed at the traditional constant location.
+    VERSION = Version::VERSION # Traditional Constant Location
   end
 end

data/lib/dotenv/merge.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 # External gems
-require "version_gem"
-require "set"
 
 # Shared merge infrastructure
-require "ast/merge"
+require 'ast/merge'
+require 'plain/merge'
+require 'tree_haver'
+require_relative 'merge/version'
 
 # This gem
-require_relative "merge/version"
 
 module Dotenv
   module Merge
@@ -59,27 +59,31 @@ module Dotenv
     #   end
     class DestinationParseError < ParseError; end
 
-    autoload :DebugLogger, "dotenv/merge/debug_logger"
-    autoload :EnvLine, "dotenv/merge/env_line"
-    autoload :FreezeNode, "dotenv/merge/freeze_node"
-    autoload :FileAnalysis, "dotenv/merge/file_analysis"
-    autoload :MergeResult, "dotenv/merge/merge_result"
-    autoload :SmartMerger, "dotenv/merge/smart_merger"
+    # Raised when merge-time corruption detection is configured to error.
+    class CorruptionDetectedError < Error; end
+
+    autoload :DebugLogger, 'dotenv/merge/debug_logger'
+    autoload :Backend, 'dotenv/merge/backend'
+    autoload :CommentTracker, 'dotenv/merge/comment_tracker'
+    autoload :EnvLine, 'dotenv/merge/env_line'
+    autoload :FreezeNode, 'dotenv/merge/freeze_node'
+    autoload :FileAnalysis, 'dotenv/merge/file_analysis'
+    autoload :MergeResult, 'dotenv/merge/merge_result'
+    autoload :SmartMerger, 'dotenv/merge/smart_merger'
   end
 end
 
+require_relative 'merge/backend'
+Dotenv::Merge.register_backend!
+
 # Register with ast-merge's MergeGemRegistry for RSpec dependency tags
 # Only register if MergeGemRegistry is loaded (i.e., in test environment)
 if defined?(Ast::Merge::RSpec::MergeGemRegistry)
   Ast::Merge::RSpec::MergeGemRegistry.register(
     :dotenv_merge,
-    require_path: "dotenv/merge",
-    merger_class: "Dotenv::Merge::SmartMerger",
-    test_source: "KEY=value",
-    category: :config,
+    require_path: 'dotenv/merge',
+    merger_class: 'Dotenv::Merge::SmartMerger',
+    test_source: 'KEY=value',
+    category: :config
   )
 end
-
-Dotenv::Merge::Version.class_eval do
-  extend VersionGem::Basic
-end