philiprehberger-env_diff 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4594951e7754c86bb5d2793b74a3ab831e3de57174aafbad7478c2848cd9d3ae
-  data.tar.gz: e9540341ad4400e0a03f825693c21ad9f057ef20cff52e02082cd7f26fb6d787
+  metadata.gz: 256215c35e39e22093122c4c9d2452e3298beb699cbb84189a14dbf88ce75dbb
+  data.tar.gz: ddada81c036244804246bd9e8c5c790778a9621bf412aef912cedf15ecd4e116
 SHA512:
-  metadata.gz: 5735362de38190a82ce601a78cb3dfddfdc51a9bddd74ef7f67f432acf9a275e82e2c6601d32534e1d5f6aae56911a08cb83ab7eb567e52bb589b9977be60433
-  data.tar.gz: 1bd5999f51acb2ea3930aa3d0ae7ec62884915c8715d1ea4bf5f78c430eb29314a705215fa062d8236f28a798734b92e13e6346419eb1ecc66a1c52a9019b15c
+  metadata.gz: ef02926fa7b051d80cde13876739650db6c3279a8f068836292ff2676633668cdabc6256e6c50ca82a37f4a806ed942deebdbecd703f210dcfcce14f0171db4e
+  data.tar.gz: 9d991cd745f294cb1d989144ba6136d6f64a52af32d7107d05d38193bca92a6740add34ad57e43dae9fa4103f1256f1d6852fbb87e56ca44d9cb371092b1a081

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,49 @@ 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 }
+```
+
+### Compare against system ENV
+
+```ruby
+diff = Philiprehberger::EnvDiff.from_system({ "APP_ENV" => "production" })
+diff = Philiprehberger::EnvDiff.from_system(".env.production")
+```
+
 ### Compare .env files
 
 ```ruby
@@ -72,12 +115,17 @@ ENV
 | `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 |
 | `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.2.0'
   end
 end

data/lib/philiprehberger/env_diff.rb

@@ -34,5 +34,14 @@ module Philiprehberger
     def self.from_env_file(path_a, path_b)
       compare(Parser.parse_file(path: path_a), Parser.parse_file(path: path_b))
     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
+    # @return [Diff] the computed differences between ENV and target
+    def self.from_system(target)
+      target_hash = target.is_a?(String) ? Parser.parse_file(path: target) : target
+      compare(ENV.to_h, target_hash)
+    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.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-04 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