philiprehberger-env_diff 0.1.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4594951e7754c86bb5d2793b74a3ab831e3de57174aafbad7478c2848cd9d3ae
-  data.tar.gz: e9540341ad4400e0a03f825693c21ad9f057ef20cff52e02082cd7f26fb6d787
+  metadata.gz: cb5b721f4c0ca4625cc7065f8e443aeaeb069394759e21829141bc2e551180c4
+  data.tar.gz: 44866b77b4a8adeab0ac1550d1a53b995875cc444fc1fd67a7deb32bd1216035
 SHA512:
-  metadata.gz: 5735362de38190a82ce601a78cb3dfddfdc51a9bddd74ef7f67f432acf9a275e82e2c6601d32534e1d5f6aae56911a08cb83ab7eb567e52bb589b9977be60433
-  data.tar.gz: 1bd5999f51acb2ea3930aa3d0ae7ec62884915c8715d1ea4bf5f78c430eb29314a705215fa062d8236f28a798734b92e13e6346419eb1ecc66a1c52a9019b15c
+  metadata.gz: 8e35a278641cbd4e7adaf9fe571e096a9ebd3a2521c56aed09750025e04265ddc743a8551d0efd94c5fb5b190b789fca7a9e995aad0deadef4dbffe973d5d04a
+  data.tar.gz: 606bed2477c6205c621a5e4e728eeb6f22d8dc3e6f671ac66d7d3077a1948aed414cda0570207b5b5019a32a94e14cb40b4aed48c4b940fd0f5f4f0b02c03e69

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-14
+
+### Added
+- `EnvDiff.validate(target, required:)` — check that all required keys exist in a target hash or .env file
+- `case_sensitive:` keyword on `compare`, `from_hash`, `from_env_file`, and `from_system` — normalize keys to uppercase when false
+- `EnvDiff.to_markdown(diff)` — format a diff result as a Markdown table string
+- `EnvDiff.to_html(diff)` — format a diff result as an HTML table string
+
+## [0.2.0] - 2026-04-03
+
+### Added
+- `Diff#summary(mask:)` — mask values for sensitive keys using string or regex patterns
+- `Diff#to_h` — structured hash output with added, removed, changed, and unchanged categories
+- `Diff#to_json` — JSON serialization of the structured hash
+- `Diff#filter(pattern:)` — return a new Diff containing only keys matching a regex pattern
+- `Diff#stats` — returns counts of added, removed, changed, unchanged, and total keys
+- `EnvDiff.from_system(target)` — compare current ENV against a target hash or .env file path
+
+## [0.1.8] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
 ## [0.1.7] - 2026-03-31
 
 ### Changed

data/README.md

@@ -46,6 +46,100 @@ puts diff.summary
 # ~ DATABASE_URL: "postgres://localhost/dev" -> "postgres://prod-host/app"
 ```
 
+### Masked summary
+
+Hide sensitive values in the summary output using exact strings or regex patterns:
+
+```ruby
+puts diff.summary(mask: ["SECRET", /PASSWORD|TOKEN/])
+# + NEW_KEY
+# - OLD_KEY
+# ~ SECRET: *** -> ***
+```
+
+### Structured output
+
+```ruby
+diff.to_h
+# => { added: { "NEW_KEY" => "added" }, removed: { "OLD_KEY" => "remove_me" },
+#      changed: { "DATABASE_URL" => { source: "postgres://localhost/dev", target: "postgres://prod-host/app" } },
+#      unchanged: { "SECRET" => "abc" } }
+
+diff.to_json  # => JSON string of the structured hash
+```
+
+### Filter by pattern
+
+```ruby
+db_diff = diff.filter(pattern: /^DATABASE/)
+db_diff.changed.keys  # => ["DATABASE_URL"]
+```
+
+### Stats
+
+```ruby
+diff.stats
+# => { added: 1, removed: 1, changed: 1, unchanged: 1, total: 4 }
+```
+
+### Validation
+
+Check that all required keys exist in a target hash or `.env` file:
+
+```ruby
+target = { 'DATABASE_URL' => 'postgres://localhost', 'PORT' => '3000' }
+result = Philiprehberger::EnvDiff.validate(target, required: %w[DATABASE_URL SECRET PORT])
+result[:valid]   # => false
+result[:missing] # => ["SECRET"]
+
+# Also works with .env file paths
+result = Philiprehberger::EnvDiff.validate(".env.production", required: %w[DATABASE_URL SECRET])
+```
+
+### Case-Insensitive Comparison
+
+Normalize keys to uppercase before comparing by passing `case_sensitive: false`:
+
+```ruby
+diff = Philiprehberger::EnvDiff.compare(
+  { "db_host" => "localhost" },
+  { "DB_HOST" => "localhost" },
+  case_sensitive: false
+)
+diff.changed? # => false
+diff.unchanged # => ["DB_HOST"]
+```
+
+### Export Formats
+
+Format a diff result as a Markdown or HTML table:
+
+```ruby
+diff = Philiprehberger::EnvDiff.compare(source, target)
+
+puts Philiprehberger::EnvDiff.to_markdown(diff)
+# | Key | Status | Source | Target |
+# | --- | ------ | ------ | ------ |
+# | NEW_KEY | added | | added |
+# | OLD_KEY | removed | remove_me | |
+# | DATABASE_URL | changed | postgres://localhost/dev | postgres://prod-host/app |
+# | SECRET | unchanged | abc | abc |
+
+puts Philiprehberger::EnvDiff.to_html(diff)
+# <table>
+#   <tr><th>Key</th><th>Status</th><th>Source</th><th>Target</th></tr>
+#   <tr><td>NEW_KEY</td><td>added</td><td></td><td>added</td></tr>
+#   ...
+# </table>
+```
+
+### Compare against system ENV
+
+```ruby
+diff = Philiprehberger::EnvDiff.from_system({ "APP_ENV" => "production" })
+diff = Philiprehberger::EnvDiff.from_system(".env.production")
+```
+
 ### Compare .env files
 
 ```ruby
@@ -69,15 +163,23 @@ ENV
 
 | Method / Class | Description |
 |----------------|-------------|
-| `EnvDiff.compare(source, target)` | Compare two hashes and return a `Diff` |
-| `EnvDiff.from_hash(hash_a, hash_b)` | Alias for `compare` |
-| `EnvDiff.from_env_file(path_a, path_b)` | Parse two `.env` files and compare them |
+| `EnvDiff.compare(source, target, case_sensitive: true)` | Compare two hashes and return a `Diff` |
+| `EnvDiff.from_hash(hash_a, hash_b, case_sensitive: true)` | Alias for `compare` |
+| `EnvDiff.from_env_file(path_a, path_b, case_sensitive: true)` | Parse two `.env` files and compare them |
+| `EnvDiff.from_system(target, case_sensitive: true)` | Compare current `ENV` against a target hash or `.env` file path |
+| `EnvDiff.validate(target, required:)` | Check that all required keys exist in target; returns `{ valid:, missing: }` |
+| `EnvDiff.to_markdown(diff)` | Format a diff result as a Markdown table string |
+| `EnvDiff.to_html(diff)` | Format a diff result as an HTML table string |
 | `Diff#added` | Array of keys in target but not source |
 | `Diff#removed` | Array of keys in source but not target |
 | `Diff#changed` | Hash of keys with different values |
 | `Diff#unchanged` | Array of keys with identical values |
 | `Diff#changed?` | `true` if any differences exist |
-| `Diff#summary` | Human-readable multiline diff string |
+| `Diff#summary(mask: [])` | Human-readable multiline diff string with optional value masking |
+| `Diff#to_h` | Structured hash with `:added`, `:removed`, `:changed`, `:unchanged` |
+| `Diff#to_json` | JSON serialization of the structured hash |
+| `Diff#filter(pattern:)` | New `Diff` containing only keys matching the regex pattern |
+| `Diff#stats` | Hash of counts: `:added`, `:removed`, `:changed`, `:unchanged`, `:total` |
 | `Parser.parse(content)` | Parse `.env` string into a hash |
 | `Parser.parse_file(path:)` | Read and parse a `.env` file |
 

data/lib/philiprehberger/env_diff/diff.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Philiprehberger
   module EnvDiff
     # Represents the result of comparing two sets of environment variables.
@@ -21,6 +23,8 @@ module Philiprehberger
       # @param source [Hash] the baseline environment hash
       # @param target [Hash] the environment hash to compare against
       def initialize(source, target)
+        @source = source
+        @target = target
         @added = (target.keys - source.keys).sort
         @removed = (source.keys - target.keys).sort
         @changed = build_changed(source, target)
@@ -36,15 +40,58 @@ module Philiprehberger
 
       # Human-readable multiline summary of all differences.
       #
+      # @param mask [Array<String, Regexp>] patterns for keys whose values should be masked
       # @return [String] formatted summary
-      def summary
+      def summary(mask: [])
         lines = []
-        append_added(lines)
-        append_removed(lines)
-        append_changed(lines)
+        append_added(lines, mask)
+        append_removed(lines, mask)
+        append_changed(lines, mask)
         lines.empty? ? 'No differences found.' : lines.join("\n")
       end
 
+      # Structured hash representation of the diff.
+      #
+      # @return [Hash] with :added, :removed, :changed, :unchanged keys
+      def to_h
+        {
+          added: @added.to_h { |k| [k, @target[k]] },
+          removed: @removed.to_h { |k| [k, @source[k]] },
+          changed: @changed.transform_values { |v| { source: v[:source], target: v[:target] } },
+          unchanged: @unchanged.to_h { |k| [k, @source[k]] }
+        }
+      end
+
+      # JSON serialization of the structured hash.
+      #
+      # @return [String] JSON string
+      def to_json(*_args)
+        JSON.generate(to_h)
+      end
+
+      # Return a new Diff containing only keys matching the given pattern.
+      #
+      # @param pattern [Regexp] regex pattern to match keys against
+      # @return [Diff] filtered diff
+      def filter(pattern:)
+        filtered_source = @source.select { |k, _| k.match?(pattern) }
+        filtered_target = @target.select { |k, _| k.match?(pattern) }
+        Diff.new(filtered_source, filtered_target)
+      end
+
+      # Statistics about the diff.
+      #
+      # @return [Hash] counts of added, removed, changed, unchanged, and total keys
+      def stats
+        {
+          added: @added.length,
+          removed: @removed.length,
+          changed: @changed.length,
+          unchanged: @unchanged.length,
+          total: @added.length + @removed.length + @changed.length + @unchanged.length
+        }
+      end
+
       private
 
       def build_changed(source, target)
@@ -61,17 +108,43 @@ module Philiprehberger
         common.select { |key| source[key] == target[key] }.sort
       end
 
-      def append_added(lines)
-        @added.each { |key| lines << "+ #{key}" }
+      def masked?(key, mask)
+        mask.any? do |pattern|
+          pattern.is_a?(Regexp) ? key.match?(pattern) : key == pattern
+        end
+      end
+
+      def mask_value(_value, key, mask)
+        masked?(key, mask) ? '***' : yield
       end
 
-      def append_removed(lines)
-        @removed.each { |key| lines << "- #{key}" }
+      def append_added(lines, mask)
+        @added.each do |key|
+          lines << if masked?(key, mask)
+                     "+ #{key}=***"
+                   else
+                     "+ #{key}"
+                   end
+        end
+      end
+
+      def append_removed(lines, mask)
+        @removed.each do |key|
+          lines << if masked?(key, mask)
+                     "- #{key}=***"
+                   else
+                     "- #{key}"
+                   end
+        end
       end
 
-      def append_changed(lines)
+      def append_changed(lines, mask)
         @changed.each do |key, vals|
-          lines << "~ #{key}: #{vals[:source].inspect} -> #{vals[:target].inspect}"
+          lines << if masked?(key, mask)
+                     "~ #{key}: *** -> ***"
+                   else
+                     "~ #{key}: #{vals[:source].inspect} -> #{vals[:target].inspect}"
+                   end
         end
       end
     end

data/lib/philiprehberger/env_diff/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module EnvDiff
-    VERSION = '0.1.7'
+    VERSION = '0.3.0'
   end
 end

data/lib/philiprehberger/env_diff.rb

@@ -12,27 +12,115 @@ module Philiprehberger
     #
     # @param source [Hash] the baseline environment hash
     # @param target [Hash] the environment hash to compare against
+    # @param case_sensitive [Boolean] whether key comparison is case-sensitive (default: true)
     # @return [Diff] the computed differences
-    def self.compare(source, target)
-      Diff.new(source, target)
+    def self.compare(source, target, case_sensitive: true)
+      if case_sensitive
+        Diff.new(source, target)
+      else
+        normalized_source = source.transform_keys(&:upcase)
+        normalized_target = target.transform_keys(&:upcase)
+        Diff.new(normalized_source, normalized_target)
+      end
+    end
+
+    # Validate that all required keys exist in target.
+    #
+    # @param target [Hash, String] a hash of target variables or a path to a .env file
+    # @param required [Array<String>] list of required key names
+    # @return [Hash] with :valid (Boolean) and :missing (Array<String>)
+    def self.validate(target, required:)
+      target_hash = target.is_a?(String) ? Parser.parse_file(path: target) : target
+      missing = required.reject { |key| target_hash.key?(key) }
+      { valid: missing.empty?, missing: missing }
+    end
+
+    # Format a diff result as a Markdown table string.
+    #
+    # @param diff [Diff] the diff to format
+    # @return [String] Markdown table
+    def self.to_markdown(diff)
+      lines = []
+      lines << '| Key | Status | Source | Target |'
+      lines << '| --- | ------ | ------ | ------ |'
+
+      diff.added.each do |key|
+        lines << "| #{key} | added | | #{diff.to_h[:added][key]} |"
+      end
+
+      diff.removed.each do |key|
+        lines << "| #{key} | removed | #{diff.to_h[:removed][key]} | |"
+      end
+
+      diff.changed.each do |key, vals|
+        lines << "| #{key} | changed | #{vals[:source]} | #{vals[:target]} |"
+      end
+
+      diff.unchanged.each do |key|
+        lines << "| #{key} | unchanged | #{diff.to_h[:unchanged][key]} | #{diff.to_h[:unchanged][key]} |"
+      end
+
+      lines.join("\n")
+    end
+
+    # Format a diff result as an HTML table string.
+    #
+    # @param diff [Diff] the diff to format
+    # @return [String] HTML table
+    def self.to_html(diff)
+      rows = diff.added.map do |key|
+        "  <tr><td>#{key}</td><td>added</td><td></td><td>#{diff.to_h[:added][key]}</td></tr>"
+      end
+
+      diff.removed.each do |key|
+        rows << "  <tr><td>#{key}</td><td>removed</td><td>#{diff.to_h[:removed][key]}</td><td></td></tr>"
+      end
+
+      diff.changed.each do |key, vals|
+        rows << "  <tr><td>#{key}</td><td>changed</td><td>#{vals[:source]}</td><td>#{vals[:target]}</td></tr>"
+      end
+
+      diff.unchanged.each do |key|
+        val = diff.to_h[:unchanged][key]
+        rows << "  <tr><td>#{key}</td><td>unchanged</td><td>#{val}</td><td>#{val}</td></tr>"
+      end
+
+      lines = []
+      lines << '<table>'
+      lines << '  <tr><th>Key</th><th>Status</th><th>Source</th><th>Target</th></tr>'
+      lines.concat(rows)
+      lines << '</table>'
+      lines.join("\n")
     end
 
     # Alias for compare — compare two hashes.
     #
     # @param hash_a [Hash] the baseline environment hash
     # @param hash_b [Hash] the environment hash to compare against
+    # @param case_sensitive [Boolean] whether key comparison is case-sensitive (default: true)
     # @return [Diff] the computed differences
-    def self.from_hash(hash_a, hash_b)
-      compare(hash_a, hash_b)
+    def self.from_hash(hash_a, hash_b, case_sensitive: true)
+      compare(hash_a, hash_b, case_sensitive: case_sensitive)
     end
 
     # Parse two .env files and compare them.
     #
     # @param path_a [String] path to the source .env file
     # @param path_b [String] path to the target .env file
+    # @param case_sensitive [Boolean] whether key comparison is case-sensitive (default: true)
     # @return [Diff] the computed differences
-    def self.from_env_file(path_a, path_b)
-      compare(Parser.parse_file(path: path_a), Parser.parse_file(path: path_b))
+    def self.from_env_file(path_a, path_b, case_sensitive: true)
+      compare(Parser.parse_file(path: path_a), Parser.parse_file(path: path_b), case_sensitive: case_sensitive)
+    end
+
+    # Compare the current system ENV against a target hash or .env file path.
+    #
+    # @param target [Hash, String] a hash of target variables or a path to a .env file
+    # @param case_sensitive [Boolean] whether key comparison is case-sensitive (default: true)
+    # @return [Diff] the computed differences between ENV and target
+    def self.from_system(target, case_sensitive: true)
+      target_hash = target.is_a?(String) ? Parser.parse_file(path: target) : target
+      compare(ENV.to_h, target_hash, case_sensitive: case_sensitive)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-env_diff
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-15 00:00:00.000000000 Z
 dependencies: []
 description: Parse .env files or environment hashes, compare them, and get a clear
   report of added, removed, changed, and unchanged variables.
@@ -25,11 +25,11 @@ files:
 - lib/philiprehberger/env_diff/diff.rb
 - lib/philiprehberger/env_diff/parser.rb
 - lib/philiprehberger/env_diff/version.rb
-homepage: https://github.com/philiprehberger/rb-env-diff
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-env_diff
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-env-diff
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-env_diff
   source_code_uri: https://github.com/philiprehberger/rb-env-diff
   changelog_uri: https://github.com/philiprehberger/rb-env-diff/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-env-diff/issues