dotenv-merge 1.0.3 → 7.1.3

data/lib/dotenv/merge/backend.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Dotenv
+  # StructuredMerge dotenv assignment and comment merge behavior.
+  module Merge
+    BACKEND_REFERENCE = TreeHaver::BackendReference.new(id: 'dotenv-line', family: 'line')
+
+    module Backend
+      # TreeHaver language wrapper for dotenv files parsed through the line
+      # substrate supplied by plain-merge.
+      class Language < TreeHaver::Base::Language
+        def initialize(name = :dotenv)
+          super(name, backend: :line, options: {})
+        end
+
+        def self.dotenv
+          new(:dotenv)
+        end
+
+        def self.env
+          new(:env)
+        end
+      end
+
+      # Parser adapter that exposes Dotenv::Merge::FileAnalysis via
+      # TreeHaver.parser_for(:dotenv, backend_type: :line).
+      class Parser < TreeHaver::Base::Parser
+        def parse(source)
+          raise 'Language not set' unless language
+
+          attach_line_analysis(Dotenv::Merge::FileAnalysis.new(source), source)
+        end
+
+        def parse_string(_old_tree, source)
+          parse(source)
+        end
+
+        private
+
+        def attach_line_analysis(analysis, source)
+          analysis.instance_variable_set(:@line_analysis, plain_line_analysis(source))
+          analysis.define_singleton_method(:line_analysis) { @line_analysis }
+          analysis
+        end
+
+        def plain_line_analysis(source)
+          Plain::Merge.analyze_text(source)
+        end
+      end
+    end
+
+    def self.register_backend!
+      TreeHaver::BackendRegistry.register(BACKEND_REFERENCE)
+      %i[dotenv env].each do |language_name|
+        register_language!(language_name)
+      end
+      nil
+    end
+
+    def self.register_language!(language_name)
+      TreeHaver.register_language(
+        language_name,
+        backend_module: Backend,
+        backend_type: :line,
+        gem_name: 'dotenv-merge',
+        contract: :line
+      )
+    end
+  end
+end

data/lib/dotenv/merge/comment_tracker.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # Extracts and tracks dotenv comments with their line numbers from source.
+    #
+    # Inherits shared lookup, query, region-building, and attachment API from
+    # +Ast::Merge::Comment::HashTrackerBase+. Only format-specific comment
+    # extraction and owner resolution are overridden here.
+    #
+    # Dotenv supports hash-style comments as either:
+    # - full-line comments (`# comment`)
+    # - safe inline comments on unquoted assignments (`KEY=value # comment`)
+    #
+    # This adapter intentionally stays conservative around quoted values. `#`
+    # inside quoted values is not treated as a comment, and quoted assignments
+    # with trailing comment-like text remain literal value content. That is a
+    # deliberate parser boundary for dotenv-merge, not a pending comment-matrix
+    # bug to "fix" later without an explicit product decision.
+    class CommentTracker < Ast::Merge::Comment::HashTrackerBase
+      def initialize(source_or_lines)
+        @line_objects = normalize_line_objects(source_or_lines)
+        @line_parser = Ast::Merge::Comment::QuotedHashLineParser.new
+        super(@line_objects.map(&:raw))
+      end
+
+      def augment(owners: [], **options)
+        Ast::Merge::Comment::Augmenter.new(
+          lines: @lines,
+          comments: @comments,
+          owners: owners,
+          style: :hash_comment,
+          total_comment_count: @comments.size,
+          inline_comment_count: @comments.count { |comment| !comment[:full_line] },
+          **options
+        )
+      end
+
+      private
+
+      def normalize_line_objects(source_or_lines)
+        case source_or_lines
+        when String
+          source_or_lines.lines.each_with_index.map do |line, index|
+            EnvLine.new(line.chomp, index + 1)
+          end
+        else
+          Array(source_or_lines)
+        end
+      end
+
+      def extract_comments
+        @line_objects.filter_map do |line|
+          if line.comment?
+            build_full_line_comment(line)
+          elsif line.assignment?
+            build_inline_comment(line)
+          end
+        end
+      end
+
+      def build_full_line_comment(line)
+        match = line.raw.match(FULL_LINE_COMMENT_REGEX)
+        return unless match
+
+        {
+          line: line.line_number,
+          indent: match[:indent].length,
+          text: match[:text].to_s,
+          full_line: true,
+          raw: line.raw
+        }
+      end
+
+      def build_inline_comment(line)
+        value_part = raw_value_part(line)
+        return if value_part.nil?
+
+        stripped_value = value_part.lstrip
+        return if stripped_value.start_with?('"', "'")
+
+        parsed = @line_parser.parse(value_part)
+        return unless parsed&.inline?
+
+        {
+          line: line.line_number,
+          indent: leading_indent(line.raw),
+          text: parsed.text,
+          full_line: false,
+          raw: parsed.raw
+        }
+      end
+
+      def raw_value_part(line)
+        raw = line.raw.sub(/\A\s*export\s+/, '')
+        _key_part, value_part = raw.split('=', 2)
+        value_part
+      end
+
+      def leading_indent(raw)
+        raw[/\A\s*/].to_s.length
+      end
+
+      def owner_line_num(owner)
+        return owner.start_line if owner.respond_to?(:start_line) && owner.start_line
+        return owner.line_number if owner.respond_to?(:line_number)
+
+        nil
+      end
+    end
+  end
+end

data/lib/dotenv/merge/debug_logger.rb

@@ -16,8 +16,8 @@ module Dotenv
       extend Ast::Merge::DebugLogger
 
       # Configure for dotenv-merge
-      self.env_var_name = "DOTENV_MERGE_DEBUG"
-      self.log_prefix = "[dotenv-merge]"
+      self.env_var_name = 'DOTENV_MERGE_DEBUG'
+      self.log_prefix = '[dotenv-merge]'
     end
   end
 end

data/lib/dotenv/merge/env_line.rb

@@ -38,7 +38,7 @@ module Dotenv
     class EnvLine < Ast::Merge::AstNode
       # Prefix for exported environment variables
       # @return [String]
-      EXPORT_PREFIX = "export "
+      EXPORT_PREFIX = 'export '
 
       # @return [String] The original raw line content
       attr_reader :raw
@@ -75,7 +75,7 @@ module Dotenv
           start_line: line_number,
           end_line: line_number,
           start_column: 0,
-          end_column: @raw.length,
+          end_column: @raw.length
         )
 
         super(slice: @raw, location: location)
@@ -84,7 +84,7 @@ module Dotenv
       # TreeHaver::Node protocol: type
       # @return [String] "env_line"
       def type
-        "env_line"
+        'env_line'
       end
 
       # Generate a unique signature for this line (used for merge matching)
@@ -163,7 +163,7 @@ module Dotenv
         stripped = @raw.strip
         if stripped.empty?
           @line_type = :blank
-        elsif stripped.start_with?("#")
+        elsif stripped.start_with?('#')
           @line_type = :comment
         else
           parse_assignment!(stripped)
@@ -181,13 +181,13 @@ module Dotenv
           line = line[EXPORT_PREFIX.length..]
         end
 
-        if line.include?("=")
-          key_part, value_part = line.split("=", 2)
+        if line.include?('=')
+          key_part, value_part = line.split('=', 2)
           key_part = key_part.strip
           if valid_key?(key_part)
             @line_type = :assignment
             @key = key_part
-            @value = unquote(value_part || "")
+            @value = unquote(value_part || '')
           else
             @line_type = :invalid
           end
@@ -214,14 +214,10 @@ module Dotenv
         value = value.strip
 
         # Double-quoted: process escape sequences
-        if value.start_with?('"') && value.end_with?('"')
-          return process_escape_sequences(value[1..-2])
-        end
+        return process_escape_sequences(value[1..-2]) if value.start_with?('"') && value.end_with?('"')
 
         # Single-quoted: literal value, no escape processing
-        if value.start_with?("'") && value.end_with?("'")
-          return value[1..-2]
-        end
+        return value[1..-2] if value.start_with?("'") && value.end_with?("'")
 
         # Unquoted: strip inline comments
         strip_inline_comment(value)
@@ -239,7 +235,7 @@ module Dotenv
           .gsub('\t', "\t")
           .gsub('\r', "\r")
           .gsub('\"', '"')
-          .gsub("\\\\", "\\")
+          .gsub('\\\\', '\\')
       end
 
       # Strip inline comments from unquoted values

data/lib/dotenv/merge/file_analysis.rb

@@ -26,7 +26,10 @@ module Dotenv
 
       # Default freeze token for identifying freeze blocks
       # @return [String]
-      DEFAULT_FREEZE_TOKEN = "dotenv-merge"
+      DEFAULT_FREEZE_TOKEN = 'dotenv-merge'
+
+      # @return [CommentTracker] Comment tracker for this file
+      attr_reader :comment_tracker, :structural_diagnostics
 
       # Initialize file analysis with dotenv parser
       #
@@ -34,25 +37,29 @@ module Dotenv
       # @param freeze_token [String] Token for freeze block markers (default: "dotenv-merge")
       # @param signature_generator [Proc, nil] Custom signature generator
       # @param options [Hash] Additional options (forward compatibility - ignored by FileAnalysis)
-      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil, **options)
+      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil, **_options)
         @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
         @lines = parse_lines(source)
 
+        # Initialize comment tracking before freeze block integration
+        @comment_tracker = CommentTracker.new(@lines)
+
         # Extract and integrate freeze blocks
         @statements = extract_and_integrate_statements
 
-        DebugLogger.debug("FileAnalysis initialized", {
-          signature_generator: signature_generator ? "custom" : "default",
-          lines_count: @lines.size,
-          statements_count: @statements.size,
-          freeze_blocks: freeze_blocks.size,
-          assignments: assignment_lines.size,
-        })
+        DebugLogger.debug('FileAnalysis initialized', {
+                            signature_generator: signature_generator ? 'custom' : 'default',
+                            lines_count: @lines.size,
+                            statements_count: @statements.size,
+                            freeze_blocks: freeze_blocks.size,
+                            assignments: assignment_lines.size
+                          })
       end
 
       # Check if parse was successful (dotenv always succeeds, may have invalid lines)
@@ -61,12 +68,115 @@ module Dotenv
         true
       end
 
+      # Get shared comment capability information for this analysis.
+      #
+      # @return [Ast::Merge::Comment::Capability]
+      def comment_capability
+        @comment_capability ||= comment_tracker.augment(owners: []).capability
+      end
+
+      # Describe how dotenv merges currently own and emit comments.
+      #
+      # Dotenv comment handling is source-augmented and emitted through the
+      # synthetic merge layer.
+      #
+      # @return [Ast::Merge::Comment::SupportStyle]
+      def comment_support_style
+        @comment_support_style ||= shared_comment_support_style(
+          source: :dotenv_source,
+          style: :hash_comment,
+          read_strategy: :source_augmented_portable_write
+        )
+      end
+
+      # Get all tracked comments converted to shared Ast::Merge comment nodes.
+      #
+      # @return [Array<Ast::Merge::Comment::Line>]
+      def comment_nodes
+        comment_tracker.comment_nodes
+      end
+
+      # Get a shared Ast::Merge comment node at a specific line.
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Ast::Merge::Comment::Line, nil]
+      def comment_node_at(line_num)
+        comment_tracker.comment_node_at(line_num)
+      end
+
+      # Get comments in a line range converted to a shared comment region.
+      #
+      # @param range [Range] Range of 1-based line numbers
+      # @param kind [Symbol] Region kind (:leading, :inline, :orphan, etc.)
+      # @param full_line_only [Boolean] Whether to keep only full-line comments
+      # @return [Ast::Merge::Comment::Region]
+      def comment_region_for_range(range, kind:, full_line_only: false)
+        comment_tracker.comment_region_for_range(
+          range,
+          kind: kind,
+          full_line_only: full_line_only
+        )
+      end
+
+      # Build a passive shared comment augmenter for this analysis.
+      #
+      # @param owners [Array<#start_line,#end_line>, nil] Owners used for attachment inference
+      # @param options [Hash] Additional augmenter options
+      # @return [Ast::Merge::Comment::Augmenter]
+      def comment_augmenter(owners: nil, **options)
+        comment_tracker.augment(
+          owners: owners || comment_augmenter_default_owners,
+          **options
+        )
+      end
+
+      # Build a passive shared comment attachment for an owner.
+      #
+      # @param owner [Object] Structural owner for the attachment
+      # @param options [Hash] Additional metadata / lookup overrides
+      # @return [Ast::Merge::Comment::Attachment]
+      def comment_attachment_for(owner, **options)
+        shared_comment_attachment_for(
+          owner,
+          tracker_attachment: comment_augmenter(**options).attachment_for(owner),
+          **options
+        )
+      end
+
+      # @return [Symbol]
+      def comment_attachment_strategy
+        :tracker_layout_merge
+      end
+
+      def ruleset_owner_selector
+        :assignment_lines_plus_freeze_blocks
+      end
+
+      def ruleset_match_key
+        :env_key
+      end
+
+      def ruleset_render_family
+        :dotenv_assignments
+      end
+
       # Get assignment lines (not in freeze blocks)
       # @return [Array<EnvLine>]
       def assignment_lines
         @statements.select { |stmt| stmt.is_a?(EnvLine) && stmt.assignment? }
       end
 
+      # Get merge-relevant structural owners in source order.
+      # For dotenv this means assignment lines plus integrated freeze blocks,
+      # excluding standalone comments, blanks, and invalid lines.
+      #
+      # @return [Array<EnvLine, FreezeNode>]
+      def structural_owners
+        @structural_owners ||= @statements.select do |stmt|
+          stmt.is_a?(FreezeNode) || (stmt.is_a?(EnvLine) && stmt.assignment?)
+        end
+      end
+
       # Get all assignment lines including those in freeze blocks
       # @return [Array<EnvLine>]
       def all_assignments
@@ -95,7 +205,7 @@ module Dotenv
         end
       end
 
-      # Note: fallthrough_node? is inherited from FileAnalyzable.
+      # NOTE: fallthrough_node? is inherited from FileAnalyzable.
       # EnvLine inherits from AstNode and FreezeNode inherits from FreezeNodeBase,
       # both of which are recognized by the base implementation.
 
@@ -114,6 +224,10 @@ module Dotenv
 
       private
 
+      def comment_augmenter_default_owners
+        structural_owners
+      end
+
       # Parse source into EnvLine objects
       # @param source [String] Source content
       # @return [Array<EnvLine>]
@@ -145,17 +259,17 @@ module Dotenv
         @lines.each do |line|
           next unless line.comment?
 
-          if line.raw =~ pattern
-            marker_type = ::Regexp.last_match(1) # 'freeze' or 'unfreeze'
-            reason = ::Regexp.last_match(2)&.strip
-            reason = nil if reason&.empty?
+          next unless line.raw =~ pattern
 
-            markers << {
-              type: marker_type.to_sym,
-              line: line.line_number,
-              reason: reason,
-            }
-          end
+          marker_type = ::Regexp.last_match(1) # 'freeze' or 'unfreeze'
+          reason = ::Regexp.last_match(2)&.strip
+          reason = nil if reason && reason.empty?
+
+          markers << {
+            type: marker_type.to_sym,
+            line: line.line_number,
+            reason: reason
+          }
         end
 
         markers
@@ -172,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
@@ -182,16 +301,26 @@ module Dotenv
                 start_line: open_marker[:line],
                 end_line: marker[:line],
                 analysis: self,
-                reason: open_marker[:reason],
+                reason: open_marker[:reason]
               )
               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
 
         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
 

data/lib/dotenv/merge/freeze_node.rb

@@ -43,7 +43,7 @@ module Dotenv
       # Get a signature for this freeze block
       # @return [Array] Signature based on normalized content
       def signature
-        [:FreezeNode, content.gsub(/\s+/, " ").strip]
+        [:FreezeNode, content.gsub(/\s+/, ' ').strip]
       end
 
       # Get environment variable lines within the freeze block

data/lib/dotenv/merge/merge_result.rb

@@ -50,7 +50,7 @@ module Dotenv
 
         lines = extract_lines(statement)
         @lines.concat(lines)
-        @decisions << {decision: decision, source: :template, index: index, lines: lines.length}
+        @decisions << { decision: decision, source: :template, index: index, lines: lines.length }
       end
 
       # Add content from the destination at the given statement index
@@ -63,7 +63,7 @@ module Dotenv
 
         lines = extract_lines(statement)
         @lines.concat(lines)
-        @decisions << {decision: decision, source: :destination, index: index, lines: lines.length}
+        @decisions << { decision: decision, source: :destination, index: index, lines: lines.length }
       end
 
       # Add content from a freeze block
@@ -77,7 +77,7 @@ module Dotenv
           source: :destination,
           start_line: freeze_node.start_line,
           end_line: freeze_node.end_line,
-          lines: lines.length,
+          lines: lines.length
         }
       end
 
@@ -87,13 +87,13 @@ module Dotenv
       # @return [void]
       def add_raw(lines, decision:)
         @lines.concat(lines)
-        @decisions << {decision: decision, source: :raw, lines: lines.length}
+        @decisions << { decision: decision, source: :raw, lines: lines.length }
       end
 
       # Convert the merged result to a string
       # @return [String] The merged dotenv content
       def to_s
-        return "" if @lines.empty?
+        return '' if @lines.empty?
 
         # Join with newlines and ensure file ends with newline
         result = @lines.join("\n")
@@ -114,7 +114,7 @@ module Dotenv
         {
           total_decisions: @decisions.length,
           total_lines: @lines.length,
-          by_decision: counts,
+          by_decision: counts
         }
       end