dotenv-merge 1.0.0

data/lib/dotenv/merge/merge_result.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # Result container for dotenv file merge operations.
+    # Inherits from Ast::Merge::MergeResultBase for shared functionality.
+    #
+    # Tracks merged content, decisions made during merge, and provides
+    # methods to reconstruct the final merged dotenv file.
+    #
+    # @example Basic usage
+    #   result = MergeResult.new(template_analysis, dest_analysis)
+    #   result.add_from_template(0)
+    #   result.add_from_destination(1)
+    #   merged_content = result.to_s
+    #
+    # @see Ast::Merge::MergeResultBase
+    class MergeResult < Ast::Merge::MergeResultBase
+      # Decision indicating content was preserved from a freeze block
+      # @return [Symbol]
+      DECISION_FREEZE_BLOCK = :freeze_block
+
+      # Decision indicating content came from the template
+      # @return [Symbol]
+      DECISION_TEMPLATE = :template
+
+      # Decision indicating content came from the destination (customization preserved)
+      # @return [Symbol]
+      DECISION_DESTINATION = :destination
+
+      # Decision indicating content was added from template (new in template)
+      # @return [Symbol]
+      DECISION_ADDED = :added
+
+      # Initialize a new merge result
+      # @param template_analysis [FileAnalysis] Analysis of the template file
+      # @param dest_analysis [FileAnalysis] Analysis of the destination file
+      def initialize(template_analysis, dest_analysis)
+        super(template_analysis: template_analysis, dest_analysis: dest_analysis)
+      end
+
+      # Add content from the template at the given statement index
+      # @param index [Integer] Statement index in template
+      # @param decision [Symbol] Decision type (default: DECISION_TEMPLATE)
+      # @return [void]
+      def add_from_template(index, decision: DECISION_TEMPLATE)
+        statement = @template_analysis.statements[index]
+        return unless statement
+
+        lines = extract_lines(statement)
+        @lines.concat(lines)
+        @decisions << {decision: decision, source: :template, index: index, lines: lines.length}
+      end
+
+      # Add content from the destination at the given statement index
+      # @param index [Integer] Statement index in destination
+      # @param decision [Symbol] Decision type (default: DECISION_DESTINATION)
+      # @return [void]
+      def add_from_destination(index, decision: DECISION_DESTINATION)
+        statement = @dest_analysis.statements[index]
+        return unless statement
+
+        lines = extract_lines(statement)
+        @lines.concat(lines)
+        @decisions << {decision: decision, source: :destination, index: index, lines: lines.length}
+      end
+
+      # Add content from a freeze block
+      # @param freeze_node [FreezeNode] The freeze block to add
+      # @return [void]
+      def add_freeze_block(freeze_node)
+        lines = freeze_node.lines.map(&:raw)
+        @lines.concat(lines)
+        @decisions << {
+          decision: DECISION_FREEZE_BLOCK,
+          source: :destination,
+          start_line: freeze_node.start_line,
+          end_line: freeze_node.end_line,
+          lines: lines.length,
+        }
+      end
+
+      # Add raw content lines
+      # @param lines [Array<String>] Lines to add
+      # @param decision [Symbol] Decision type
+      # @return [void]
+      def add_raw(lines, decision:)
+        @lines.concat(lines)
+        @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?
+
+        # Join with newlines and ensure file ends with newline
+        result = @lines.join("\n")
+        result += "\n" unless result.end_with?("\n")
+        result
+      end
+
+      # Check if any content has been added
+      # @return [Boolean]
+      def empty?
+        @lines.empty?
+      end
+
+      # Get summary of merge decisions
+      # @return [Hash] Summary with counts by decision type
+      def summary
+        counts = @decisions.group_by { |d| d[:decision] }.transform_values(&:count)
+        {
+          total_decisions: @decisions.length,
+          total_lines: @lines.length,
+          by_decision: counts,
+        }
+      end
+
+      private
+
+      # Extract lines from a statement
+      # @param statement [EnvLine, FreezeNode] The statement
+      # @return [Array<String>]
+      def extract_lines(statement)
+        case statement
+        when FreezeNode
+          statement.lines.map(&:raw)
+        when EnvLine
+          [statement.raw]
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/dotenv/merge/smart_merger.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # Smart merger for dotenv files.
+    # Intelligently combines template and destination dotenv files by matching
+    # environment variable names and preserving customizations.
+    #
+    # @example Basic merge
+    #   merger = SmartMerger.new(template_content, dest_content)
+    #   result = merger.merge
+    #   puts result.to_s
+    #
+    # @example With options
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     preference: :template,
+    #     add_template_only_nodes: true,
+    #   )
+    #   result = merger.merge
+    class SmartMerger
+      # @return [FileAnalysis] Analysis of template file
+      attr_reader :template_analysis
+
+      # @return [FileAnalysis] Analysis of destination file
+      attr_reader :dest_analysis
+
+      # Initialize a new SmartMerger
+      #
+      # @param template_content [String] Content of the template dotenv file
+      # @param dest_content [String] Content of the destination dotenv file
+      # @param preference [Symbol] Which version to prefer on match
+      #   (:template or :destination, default: :destination)
+      # @param add_template_only_nodes [Boolean] Whether to add template-only env vars
+      #   (default: false)
+      # @param freeze_token [String] Token for freeze block markers
+      #   (default: "dotenv-merge")
+      # @param signature_generator [Proc, nil] Custom signature generator
+      def initialize(
+        template_content,
+        dest_content,
+        preference: :destination,
+        add_template_only_nodes: false,
+        freeze_token: FileAnalysis::DEFAULT_FREEZE_TOKEN,
+        signature_generator: nil
+      )
+        @preference = preference
+        @add_template_only_nodes = add_template_only_nodes
+
+        # Parse template
+        @template_analysis = FileAnalysis.new(
+          template_content,
+          freeze_token: freeze_token,
+          signature_generator: signature_generator,
+        )
+
+        # Parse destination
+        @dest_analysis = FileAnalysis.new(
+          dest_content,
+          freeze_token: freeze_token,
+          signature_generator: signature_generator,
+        )
+
+        @result = MergeResult.new(@template_analysis, @dest_analysis)
+      end
+
+      # Perform the merge operation
+      #
+      # @return [String] The merged content as a string
+      def merge
+        merge_result.to_s
+      end
+
+      # Perform the merge operation and return the full result object
+      #
+      # @return [MergeResult] The merge result containing merged content
+      def merge_result
+        return @merge_result if @merge_result
+
+        @merge_result = DebugLogger.time("SmartMerger#merge") do
+          alignment = align_statements
+
+          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 },
+          })
+
+          process_alignment(alignment)
+          @result
+        end
+      end
+
+      private
+
+      # 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
+          else
+            alignment << {
+              type: :template_only,
+              template_stmt: stmt,
+              template_index: t_idx,
+              signature: sig,
+            }
+          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),
+          }
+        end
+
+        # Sort by destination order (preserve dest structure), then template order for additions
+        sort_alignment(alignment, dest_stmts.size)
+      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
+        end
+      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
+        end
+      end
+
+      # Process a matched entry
+      # @param entry [Hash] Alignment entry
+      # @return [void]
+      def process_match(entry)
+        dest_stmt = entry[:dest_stmt]
+
+        # Freeze blocks always win
+        if dest_stmt.is_a?(FreezeNode)
+          @result.add_freeze_block(dest_stmt)
+          return
+        end
+
+        # Apply preference
+        case @preference
+        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)
+        else
+          @result.add_from_destination(entry[:dest_index], decision: MergeResult::DECISION_DESTINATION)
+        end
+      end
+
+      # Process a template-only entry
+      # @param entry [Hash] Alignment entry
+      # @return [void]
+      def process_template_only(entry)
+        return unless @add_template_only_nodes
+
+        # Skip comments and blank lines from template
+        stmt = entry[:template_stmt]
+        return if stmt.is_a?(EnvLine) && (stmt.comment? || stmt.blank?)
+
+        @result.add_from_template(entry[:template_index], decision: MergeResult::DECISION_ADDED)
+      end
+
+      # Process a destination-only entry
+      # @param entry [Hash] Alignment entry
+      # @return [void]
+      def process_dest_only(entry)
+        dest_stmt = entry[:dest_stmt]
+
+        if dest_stmt.is_a?(FreezeNode)
+          @result.add_freeze_block(dest_stmt)
+        else
+          @result.add_from_destination(entry[:dest_index], decision: MergeResult::DECISION_DESTINATION)
+        end
+      end
+    end
+  end
+end

data/lib/dotenv/merge/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # Version information for Dotenv::Merge
+    module Version
+      # Current version of the dotenv-merge gem
+      VERSION = "1.0.0"
+    end
+    VERSION = Version::VERSION # traditional location
+  end
+end

data/lib/dotenv/merge.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# External gems
+require "version_gem"
+require "set"
+
+# Shared merge infrastructure
+require "ast/merge"
+
+# This gem
+require_relative "merge/version"
+
+module Dotenv
+  module Merge
+    # Base error class for dotenv-merge
+    # Inherits from Ast::Merge::Error for consistency across merge gems.
+    class Error < Ast::Merge::Error; end
+
+    # Raised when a dotenv file has parsing errors.
+    # Inherits from Ast::Merge::ParseError for consistency across merge gems.
+    #
+    # @example Handling parse errors
+    #   begin
+    #     analysis = FileAnalysis.new(env_content)
+    #   rescue ParseError => e
+    #     puts "Dotenv syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error}" }
+    #   end
+    class ParseError < Ast::Merge::ParseError
+      # @param message [String, nil] Error message (auto-generated if nil)
+      # @param content [String, nil] The dotenv source that failed to parse
+      # @param errors [Array] Parse errors
+      def initialize(message = nil, content: nil, errors: [])
+        super(message, errors: errors, content: content)
+      end
+    end
+
+    # Raised when the template file cannot be parsed.
+    #
+    # @example Handling template parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue TemplateParseError => e
+    #     puts "Template syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error.message}" }
+    #   end
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination file cannot be parsed.
+    #
+    # @example Handling destination parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue DestinationParseError => e
+    #     puts "Destination syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error.message}" }
+    #   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"
+  end
+end
+
+Dotenv::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/dotenv-merge.rb

@@ -0,0 +1,4 @@
+# For technical reasons, if we move to Zeitwerk, this cannot be require_relative.
+#   See: https://github.com/fxn/zeitwerk#for_gem_extension
+# Hook for other libraries to load this library (e.g. via bundler)
+require "dotenv/merge"

data/sig/dotenv/merge/env_line.rbs

@@ -0,0 +1,90 @@
+module Dotenv
+  module Merge
+    # Represents a single line in a dotenv file.
+    # Parses and categorizes lines as assignments, comments, blank lines, or invalid.
+    class EnvLine
+      # Prefix for exported environment variables
+      EXPORT_PREFIX: String
+
+      # Location struct for compatibility with AST nodes
+      class Location < Struct[Integer]
+        attr_accessor start_line: Integer
+        attr_accessor end_line: Integer
+
+        # Check if a line number falls within this location
+        def cover?: (Integer line_number) -> bool
+      end
+
+      # The original raw line content
+      attr_reader raw: String
+
+      # The 1-indexed line number in the source file
+      attr_reader line_number: Integer
+
+      # The line type (:assignment, :comment, :blank, :invalid)
+      attr_reader type: Symbol?
+
+      # The environment variable key (for assignments)
+      attr_reader key: String?
+
+      # The environment variable value (for assignments)
+      attr_reader value: String?
+
+      # Whether the line has an export prefix
+      attr_reader export: bool
+
+      # Initialize a new EnvLine by parsing the raw content
+      def initialize: (String raw, Integer line_number) -> void
+
+      # Generate a unique signature for this line (used for merge matching)
+      def signature: () -> Array[Symbol | String]?
+
+      # Get a location object for this line
+      def location: () -> Location
+
+      # Check if this line is an environment variable assignment
+      def assignment?: () -> bool
+
+      # Check if this line is a comment
+      def comment?: () -> bool
+
+      # Check if this line is blank (empty or whitespace only)
+      def blank?: () -> bool
+
+      # Check if this line is invalid (unparseable)
+      def invalid?: () -> bool
+
+      # Check if this line has the export prefix
+      def export?: () -> bool
+
+      # Get the raw comment text (for comment lines only)
+      def comment: () -> String?
+
+      # Convert to string representation (returns raw content)
+      def to_s: () -> String
+
+      # Inspect for debugging
+      def inspect: () -> String
+
+      private
+
+      # Parse the raw line content and set type, key, value, and export
+      def parse!: () -> void
+
+      # Parse a potential assignment line
+      def parse_assignment!: (String stripped) -> void
+
+      # Validate an environment variable key
+      def valid_key?: (String? key) -> bool
+
+      # Remove quotes from a value and process escape sequences
+      def unquote: (String value) -> String
+
+      # Process escape sequences in double-quoted strings
+      def process_escape_sequences: (String value) -> String
+
+      # Strip inline comments from unquoted values
+      def strip_inline_comment: (String value) -> String
+    end
+  end
+end