dotenv-merge 1.0.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/dotenv/merge/debug_logger.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # Debug logging support for dotenv-merge.
+    # Extends the base Ast::Merge::DebugLogger with dotenv-specific configuration.
+    #
+    # @example Enable debug logging
+    #   ENV["DOTENV_MERGE_DEBUG"] = "true"
+    #
+    # @example Direct usage
+    #   Dotenv::Merge::DebugLogger.debug("message", { key: "value" })
+    #
+    # @see Ast::Merge::DebugLogger
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      # Configure for dotenv-merge
+      self.env_var_name = "DOTENV_MERGE_DEBUG"
+      self.log_prefix = "[dotenv-merge]"
+    end
+  end
+end

data/lib/dotenv/merge/env_line.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # Represents a single line in a dotenv file.
+    # Parses and categorizes lines as assignments, comments, blank lines, or invalid.
+    #
+    # Inherits from Ast::Merge::AstNode for a normalized API across all ast-merge
+    # content nodes. This provides #slice, #location, #unwrap, and other standard methods.
+    #
+    # Dotenv files follow a simple format where each line is one of:
+    # - `KEY=value` - Environment variable assignment
+    # - `export KEY=value` - Assignment with export prefix
+    # - `# comment` - Comment line
+    # - Empty/whitespace - Blank line
+    #
+    # @example Parse a simple assignment
+    #   line = EnvLine.new("API_KEY=secret123", 1)
+    #   line.assignment? # => true
+    #   line.key         # => "API_KEY"
+    #   line.value       # => "secret123"
+    #
+    # @example Parse an export statement
+    #   line = EnvLine.new("export DATABASE_URL=postgres://localhost/db", 2)
+    #   line.assignment? # => true
+    #   line.export?     # => true
+    #   line.key         # => "DATABASE_URL"
+    #
+    # @example Parse a comment
+    #   line = EnvLine.new("# Database configuration", 3)
+    #   line.comment?    # => true
+    #   line.comment     # => "# Database configuration"
+    #
+    # @example Quoted values with escape sequences
+    #   line = EnvLine.new('MESSAGE="Hello\nWorld"', 4)
+    #   line.value       # => "Hello\nWorld" (with actual newline)
+    class EnvLine < Ast::Merge::AstNode
+      # Prefix for exported environment variables
+      # @return [String]
+      EXPORT_PREFIX = "export "
+
+      # @return [String] The original raw line content
+      attr_reader :raw
+
+      # @return [Integer] The 1-indexed line number in the source file
+      attr_reader :line_number
+
+      # @return [Symbol, nil] The line type (:assignment, :comment, :blank, :invalid)
+      attr_reader :type
+
+      # @return [String, nil] The environment variable key (for assignments)
+      attr_reader :key
+
+      # @return [String, nil] The environment variable value (for assignments)
+      attr_reader :value
+
+      # @return [Boolean] Whether the line has an export prefix
+      attr_reader :export
+
+      # Initialize a new EnvLine by parsing the raw content
+      #
+      # @param raw [String] The raw line content from the dotenv file
+      # @param line_number [Integer] The 1-indexed line number
+      def initialize(raw, line_number)
+        @raw = raw
+        @line_number = line_number
+        @type = nil
+        @key = nil
+        @value = nil
+        @export = false
+        parse!
+
+        location = Ast::Merge::AstNode::Location.new(
+          start_line: line_number,
+          end_line: line_number,
+          start_column: 0,
+          end_column: @raw.length,
+        )
+
+        super(slice: @raw, location: location)
+      end
+
+      # Generate a unique signature for this line (used for merge matching)
+      #
+      # @return [Array<Symbol, String>, nil] Signature array [:env, key] for assignments, nil otherwise
+      def signature
+        return unless @type == :assignment
+
+        [:env, @key]
+      end
+
+      # Check if this line is an environment variable assignment
+      #
+      # @return [Boolean] true if the line is a valid KEY=value assignment
+      def assignment?
+        @type == :assignment
+      end
+
+      # Check if this line is a comment
+      #
+      # @return [Boolean] true if the line starts with #
+      def comment?
+        @type == :comment
+      end
+
+      # Check if this line is blank (empty or whitespace only)
+      #
+      # @return [Boolean] true if the line is blank
+      def blank?
+        @type == :blank
+      end
+
+      # Check if this line is invalid (unparseable)
+      #
+      # @return [Boolean] true if the line could not be parsed
+      def invalid?
+        @type == :invalid
+      end
+
+      # Check if this line has the export prefix
+      #
+      # @return [Boolean] true if the line starts with "export "
+      def export?
+        @export
+      end
+
+      # Get the raw comment text (for comment lines only)
+      #
+      # @return [String, nil] The raw line content if this is a comment, nil otherwise
+      def comment
+        return @raw if comment?
+
+        nil
+      end
+
+      # Convert to string representation (returns raw content)
+      #
+      # @return [String] The original raw line content
+      def to_s
+        @raw
+      end
+
+      # Inspect for debugging
+      #
+      # @return [String] A debug representation of this EnvLine
+      def inspect
+        "#<#{self.class.name} line=#{@line_number} type=#{@type} key=#{@key.inspect}>"
+      end
+
+      private
+
+      # Parse the raw line content and set type, key, value, and export
+      #
+      # @return [void]
+      def parse!
+        stripped = @raw.strip
+        if stripped.empty?
+          @type = :blank
+        elsif stripped.start_with?("#")
+          @type = :comment
+        else
+          parse_assignment!(stripped)
+        end
+      end
+
+      # Parse a potential assignment line
+      #
+      # @param stripped [String] The stripped line content
+      # @return [void]
+      def parse_assignment!(stripped)
+        line = stripped
+        if line.start_with?(EXPORT_PREFIX)
+          @export = true
+          line = line[EXPORT_PREFIX.length..]
+        end
+
+        if line.include?("=")
+          key_part, value_part = line.split("=", 2)
+          key_part = key_part.strip
+          if valid_key?(key_part)
+            @type = :assignment
+            @key = key_part
+            @value = unquote(value_part || "")
+          else
+            @type = :invalid
+          end
+        else
+          @type = :invalid
+        end
+      end
+
+      # Validate an environment variable key
+      #
+      # @param key [String, nil] The key to validate
+      # @return [Boolean] true if the key is valid (starts with letter/underscore, contains only alphanumerics/underscores)
+      def valid_key?(key)
+        return false if key.nil? || key.empty?
+
+        key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+      end
+
+      # Remove quotes from a value and process escape sequences
+      #
+      # @param value [String] The raw value part after the =
+      # @return [String] The unquoted and processed value
+      def unquote(value)
+        value = value.strip
+
+        # Double-quoted: process escape sequences
+        if value.start_with?('"') && value.end_with?('"')
+          return process_escape_sequences(value[1..-2])
+        end
+
+        # Single-quoted: literal value, no escape processing
+        if value.start_with?("'") && value.end_with?("'")
+          return value[1..-2]
+        end
+
+        # Unquoted: strip inline comments
+        strip_inline_comment(value)
+      end
+
+      # Process escape sequences in double-quoted strings
+      #
+      # Handles: \n (newline), \t (tab), \r (carriage return), \" (quote), \\ (backslash)
+      #
+      # @param value [String] The value with escape sequences
+      # @return [String] The value with escape sequences converted
+      def process_escape_sequences(value)
+        value
+          .gsub('\n', "\n")
+          .gsub('\t', "\t")
+          .gsub('\r', "\r")
+          .gsub('\"', '"')
+          .gsub("\\\\", "\\")
+      end
+
+      # Strip inline comments from unquoted values
+      #
+      # @param value [String] The unquoted value
+      # @return [String] The value with inline comments removed
+      def strip_inline_comment(value)
+        # Find # that's preceded by whitespace and strip from there
+        if (match = value.match(/\s+#/))
+          value[0, match.begin(0)].strip
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/dotenv/merge/file_analysis.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # File analysis for dotenv files.
+    # Parses dotenv source and extracts environment variable assignments,
+    # comments, and freeze blocks.
+    #
+    # Dotenv files follow a simple format:
+    # - `KEY=value` - Environment variable assignment
+    # - `export KEY=value` - Assignment with export prefix
+    # - `# comment` - Comment line
+    # - Blank lines are preserved
+    #
+    # @example Basic usage
+    #   analysis = FileAnalysis.new(dotenv_source)
+    #   analysis.statements.each do |stmt|
+    #     puts stmt.class
+    #   end
+    #
+    # @example With custom freeze token
+    #   analysis = FileAnalysis.new(source, freeze_token: "my-merge")
+    #   # Looks for: # my-merge:freeze / # my-merge:unfreeze
+    class FileAnalysis
+      include Ast::Merge::FileAnalyzable
+
+      # Default freeze token for identifying freeze blocks
+      # @return [String]
+      DEFAULT_FREEZE_TOKEN = "dotenv-merge"
+
+      # Initialize file analysis with dotenv parser
+      #
+      # @param source [String] Dotenv source code to analyze
+      # @param freeze_token [String] Token for freeze block markers (default: "dotenv-merge")
+      # @param signature_generator [Proc, nil] Custom signature generator
+      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil)
+        @source = source
+        @freeze_token = freeze_token
+        @signature_generator = signature_generator
+
+        # Parse all lines
+        @lines = parse_lines(source)
+
+        # 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,
+        })
+      end
+
+      # Check if parse was successful (dotenv always succeeds, may have invalid lines)
+      # @return [Boolean]
+      def valid?
+        true
+      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 all assignment lines including those in freeze blocks
+      # @return [Array<EnvLine>]
+      def all_assignments
+        @lines.select(&:assignment?)
+      end
+
+      # Get a specific line (1-indexed)
+      # Override base to return EnvLine objects instead of raw strings
+      # @param line_number [Integer] Line number (1-indexed)
+      # @return [EnvLine, nil] The line object
+      def line_at(line_number)
+        return if line_number < 1
+
+        @lines[line_number - 1]
+      end
+
+      # Compute default signature for a node
+      # @param node [EnvLine, FreezeNode] The statement
+      # @return [Array, nil] Signature array
+      def compute_node_signature(node)
+        case node
+        when FreezeNode
+          node.signature
+        when EnvLine
+          node.signature
+        end
+      end
+
+      # 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.
+
+      # Get environment variable by key
+      # @param key [String] The environment variable key
+      # @return [EnvLine, nil] The assignment line or nil
+      def env_var(key)
+        @lines.find { |line| line.assignment? && line.key == key }
+      end
+
+      # Get all environment variable keys
+      # @return [Array<String>] List of keys
+      def keys
+        all_assignments.map(&:key)
+      end
+
+      private
+
+      # Parse source into EnvLine objects
+      # @param source [String] Source content
+      # @return [Array<EnvLine>]
+      def parse_lines(source)
+        source.lines.each_with_index.map do |line, index|
+          EnvLine.new(line.chomp, index + 1)
+        end
+      end
+
+      # Extract statements, integrating freeze blocks
+      # @return [Array<EnvLine, FreezeNode>]
+      def extract_and_integrate_statements
+        freeze_markers = find_freeze_markers
+        return @lines.dup if freeze_markers.empty?
+
+        # Build freeze blocks from markers
+        freeze_blocks = build_freeze_blocks(freeze_markers)
+
+        # Integrate: replace lines in freeze blocks with FreezeNode
+        integrate_freeze_blocks(freeze_blocks)
+      end
+
+      # Find all freeze markers in the source
+      # @return [Array<Hash>] Array of marker info hashes
+      def find_freeze_markers
+        markers = []
+        pattern = Ast::Merge::FreezeNodeBase.pattern_for(:hash_comment, @freeze_token)
+
+        @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?
+
+            markers << {
+              type: marker_type.to_sym,
+              line: line.line_number,
+              reason: reason,
+            }
+          end
+        end
+
+        markers
+      end
+
+      # Build FreezeNode objects from markers
+      # @param markers [Array<Hash>] Freeze markers
+      # @return [Array<FreezeNode>]
+      def build_freeze_blocks(markers)
+        blocks = []
+        open_marker = nil
+
+        markers.each do |marker|
+          case marker[:type]
+          when :freeze
+            if open_marker
+              DebugLogger.warning("Nested freeze block at line #{marker[:line]}, ignoring")
+            else
+              open_marker = marker
+            end
+          when :unfreeze
+            if open_marker
+              blocks << FreezeNode.new(
+                start_line: open_marker[:line],
+                end_line: marker[:line],
+                analysis: self,
+                reason: open_marker[:reason],
+              )
+              open_marker = nil
+            else
+              DebugLogger.warning("Unfreeze without freeze at line #{marker[:line]}, ignoring")
+            end
+          end
+        end
+
+        if open_marker
+          DebugLogger.warning("Unclosed freeze block starting at line #{open_marker[:line]}")
+        end
+
+        blocks
+      end
+
+      # Integrate freeze blocks into statement list
+      # @param freeze_blocks [Array<FreezeNode>]
+      # @return [Array<EnvLine, FreezeNode>]
+      def integrate_freeze_blocks(freeze_blocks)
+        return @lines.dup if freeze_blocks.empty?
+
+        # Build a set of line numbers covered by freeze blocks
+        frozen_lines = Set.new
+        freeze_blocks.each do |block|
+          (block.start_line..block.end_line).each { |ln| frozen_lines << ln }
+        end
+
+        result = []
+        freeze_block_starts = freeze_blocks.map(&:start_line).to_set
+
+        @lines.each do |line|
+          if frozen_lines.include?(line.line_number)
+            # If this is the start of a freeze block, add the FreezeNode
+            if freeze_block_starts.include?(line.line_number)
+              block = freeze_blocks.find { |b| b.start_line == line.line_number }
+              result << block if block
+            end
+            # Skip individual lines in freeze blocks
+          else
+            result << line
+          end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/dotenv/merge/freeze_node.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module Merge
+    # Represents a freeze block in a dotenv file.
+    # Freeze blocks protect sections from being overwritten during merge.
+    #
+    # @example Freeze block in dotenv file
+    #   # dotenv-merge:freeze Custom API settings
+    #   API_KEY=my_custom_key
+    #   API_SECRET=my_custom_secret
+    #   # dotenv-merge:unfreeze
+    #
+    # @see Ast::Merge::FreezeNodeBase
+    class FreezeNode < Ast::Merge::FreezeNodeBase
+      # Make InvalidStructureError available as Dotenv::Merge::FreezeNode::InvalidStructureError
+      InvalidStructureError = Ast::Merge::FreezeNodeBase::InvalidStructureError
+
+      # Make Location available as Dotenv::Merge::FreezeNode::Location
+      Location = Ast::Merge::FreezeNodeBase::Location
+
+      # Initialize a new FreezeNode for dotenv
+      #
+      # @param start_line [Integer] Starting line number (1-indexed)
+      # @param end_line [Integer] Ending line number (1-indexed)
+      # @param analysis [FileAnalysis] The file analysis
+      # @param reason [String, nil] Optional reason from freeze marker
+      def initialize(start_line:, end_line:, analysis:, reason: nil)
+        super(
+          start_line: start_line,
+          end_line: end_line,
+          analysis: analysis,
+          reason: reason
+        )
+      end
+
+      # Get the content of this freeze block
+      # @return [String] The content lines joined
+      def content
+        @lines&.map { |l| l.respond_to?(:raw) ? l.raw : l.to_s }&.join("\n")
+      end
+
+      # Get a signature for this freeze block
+      # @return [Array] Signature based on normalized content
+      def signature
+        [:FreezeNode, content.gsub(/\s+/, " ").strip]
+      end
+
+      # Get environment variable lines within the freeze block
+      # @return [Array<EnvLine>] Assignment lines only
+      def env_lines
+        @lines&.select { |l| l.respond_to?(:assignment?) && l.assignment? } || []
+      end
+
+      # String representation for debugging
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} lines=#{@start_line}..#{@end_line} env_vars=#{env_lines.size}>"
+      end
+    end
+  end
+end