philiprehberger-env_diff 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 256215c35e39e22093122c4c9d2452e3298beb699cbb84189a14dbf88ce75dbb
-  data.tar.gz: ddada81c036244804246bd9e8c5c790778a9621bf412aef912cedf15ecd4e116
+  metadata.gz: cb5b721f4c0ca4625cc7065f8e443aeaeb069394759e21829141bc2e551180c4
+  data.tar.gz: 44866b77b4a8adeab0ac1550d1a53b995875cc444fc1fd67a7deb32bd1216035
 SHA512:
-  metadata.gz: ef02926fa7b051d80cde13876739650db6c3279a8f068836292ff2676633668cdabc6256e6c50ca82a37f4a806ed942deebdbecd703f210dcfcce14f0171db4e
-  data.tar.gz: 9d991cd745f294cb1d989144ba6136d6f64a52af32d7107d05d38193bca92a6740add34ad57e43dae9fa4103f1256f1d6852fbb87e56ca44d9cb371092b1a081
+  metadata.gz: 8e35a278641cbd4e7adaf9fe571e096a9ebd3a2521c56aed09750025e04265ddc743a8551d0efd94c5fb5b190b789fca7a9e995aad0deadef4dbffe973d5d04a
+  data.tar.gz: 606bed2477c6205c621a5e4e728eeb6f22d8dc3e6f671ac66d7d3077a1948aed414cda0570207b5b5019a32a94e14cb40b4aed48c4b940fd0f5f4f0b02c03e69

data/CHANGELOG.md

@@ -7,6 +7,14 @@ 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

data/README.md

@@ -82,6 +82,57 @@ 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
@@ -112,10 +163,13 @@ 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.from_system(target)` | Compare current `ENV` against a target hash or `.env` file path |
+| `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 |

data/lib/philiprehberger/env_diff/version.rb

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

data/lib/philiprehberger/env_diff.rb

@@ -12,36 +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)
+    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)
+      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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-04 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.