philiprehberger-env_diff 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 256215c35e39e22093122c4c9d2452e3298beb699cbb84189a14dbf88ce75dbb
-  data.tar.gz: ddada81c036244804246bd9e8c5c790778a9621bf412aef912cedf15ecd4e116
+  metadata.gz: 5e512ec86bdcf2702d8c0d53552284aa43f5f51b6506e61d1275aad3af1e9dca
+  data.tar.gz: 7e65c48367a0e9d853c647e6339e40063ba23f8873f5e9668009a2c081cef5db
 SHA512:
-  metadata.gz: ef02926fa7b051d80cde13876739650db6c3279a8f068836292ff2676633668cdabc6256e6c50ca82a37f4a806ed942deebdbecd703f210dcfcce14f0171db4e
-  data.tar.gz: 9d991cd745f294cb1d989144ba6136d6f64a52af32d7107d05d38193bca92a6740add34ad57e43dae9fa4103f1256f1d6852fbb87e56ca44d9cb371092b1a081
+  metadata.gz: ec3677be78c8bc9df56fe6f2229fe625feae051ba6f6558f9d3bf0f033f0d575528a69ffe1c09642a6b8879bd01a363be75ef5a2524ddb46a19effe06fc59b1a
+  data.tar.gz: c79673bf83bfde8cd8aec1bcc824e08b6e82f7e39314d31c5a35fae8f87469f9398196d7dd04e92524550af9ac0a602152ed368cc27e22a8639f268c50085ec3

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-24
+
+### Added
+- `Diff#status_for(key)` — returns the status of a single key as a Symbol (`:added`, `:removed`, `:changed`, `:unchanged`), or `nil` if the key is absent from both sides
+
+## [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,67 @@ diff.stats
 # => { added: 1, removed: 1, changed: 1, unchanged: 1, total: 4 }
 ```
 
+### Per-key status
+
+```ruby
+diff.status_for("NEW_KEY")      # => :added
+diff.status_for("OLD_KEY")      # => :removed
+diff.status_for("DATABASE_URL") # => :changed
+diff.status_for("SECRET")       # => :unchanged
+diff.status_for("NOT_THERE")    # => nil
+```
+
+### 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 +173,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 |
@@ -126,6 +190,7 @@ ENV
 | `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` |
+| `Diff#status_for(key)` | Status of a single key as `:added`, `:removed`, `:changed`, `:unchanged`, or `nil` |
 | `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

@@ -92,6 +92,19 @@ module Philiprehberger
         }
       end
 
+      # Status of a single key in this diff.
+      #
+      # @param key [String] the key to look up
+      # @return [Symbol, nil] one of :added, :removed, :changed, :unchanged, or nil if absent from both sides
+      def status_for(key)
+        return :added if @added.include?(key)
+        return :removed if @removed.include?(key)
+        return :changed if @changed.key?(key)
+        return :unchanged if @unchanged.include?(key)
+
+        nil
+      end
+
       private
 
       def build_changed(source, target)

data/lib/philiprehberger/env_diff/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module EnvDiff
-    VERSION = '0.2.0'
+    VERSION = '0.4.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.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-24 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.