standard_health 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bc8cdc021df7485cb1443cf6902b6fee31627ad6135d9eef6f284cd5eed47e0
-  data.tar.gz: bfd4e8a50e602685430481b85a0ebf604d1e930db71ce47492036d772f4aa13c
+  metadata.gz: 73c1743f46e03601e44970d282ca02dd195b22e5f22fe502e20e8a45281e0d69
+  data.tar.gz: 507f8e5fda5420690b7146b0f6a9136561c0a1b61d6c567c5be3dcd5c250be61
 SHA512:
-  metadata.gz: 32ec724c45eb9899e4d241d5681d296e1ac5745c3ff1852b5a187dea1fcc2a6b7ff7a922c08f925f0b59189ca8523d11fd034a5743f394186d91c4c1f2d8596d
-  data.tar.gz: 4711ceae81d4b9d0c19b440cc62fe8b2677ce569661adf741775ecc7933ee93c68402c8141ca830e76a6a75aa023c3f7759ef4d68a175d38280a2d971e83b964
+  metadata.gz: 38b527cf8973dc2557b1b8c13e40ace60f73efb78f1aab34100b4a51cf4f53069700c7ac0047f038a9bcf5fdcb9a1f3223fa92ddc653e1293f6c5d4b51f320ed
+  data.tar.gz: 3662477381f1149d26394ba63fc2380c2104d1cb78a65bf3d943681a907b591ad0e7e9a6f990c868cf48087306cf6cb845c399fd976a346858ba083647b6bc3e

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-05
+
+### Added
+
+- Consumer-presence detection for `consumed_by:` paths. `audit()` accepts an optional `root:` keyword (host-app root). When given, each entry whose `consumed_by:` is set is checked against the host app's tree, producing a new `consumer:` field on the audit row: `:present` (file exists and references the var via `ENV[...]` or `ENV.fetch(...)`), `:file_missing` (path missing on disk), or `:not_referenced` (file exists but no `ENV` reference). Catches renamed/deleted consumer files, `consumed_by:` typos, and vars declared in env-spec but never actually `ENV.fetch`'d.
+- `DiagnosticsController#env` now passes `Rails.root` automatically, so host apps get the new `consumer:` field with no host-side change.
+- Deprecation metadata on `required` / `recommended`: `deprecated: true`, `sunset_on:` (target removal date), `replacement:` (what to use instead). Surfaced verbatim in audit rows. Lets vars be staged for removal with audit trail.
+
+### Changed
+
+- `Entry` struct extended with `deprecated`, `sunset_on`, `replacement`. Backward-compatible — every 0.3.0 spec produces identical audit output when the new opts aren't used and `root:` isn't passed.
+
 ## [0.3.0] - 2026-04-29
 
 ### Added

data/app/controllers/standard_health/diagnostics_controller.rb

@@ -19,8 +19,9 @@ module StandardHealth
     def env
       spec = StandardHealth.config.env_spec
       mode = ENV["APP_ENVIRONMENT"].to_s
+      root = defined?(Rails) ? Rails.root : nil
 
-      audit = spec ? spec.audit(ENV.to_h, mode: mode) : []
+      audit = spec ? spec.audit(ENV.to_h, mode: mode, root: root) : []
 
       render json: {
         mode: mode,

data/lib/standard_health/env_spec.rb

@@ -31,12 +31,22 @@ module StandardHealth
   #   - `description:` (String, optional) — human-readable hint surfaced
   #     verbatim by `/diagnostics/env`.
   #   - `consumed_by:` (String or Array<String>, optional) — pointer(s) to
-  #     where the value is read in the host app. Surfaced verbatim.
+  #     where the value is read in the host app. Surfaced verbatim. When
+  #     `audit` is called with `root:`, each path is checked for an
+  #     `ENV[...]` / `ENV.fetch(...)` reference to the var; the result is
+  #     reported as `consumer:` in the audit row
+  #     (`:present`, `:file_missing`, or `:not_referenced`).
   #   - `if:` / `unless:` (Proc, optional) — predicates evaluated at audit
   #     time. When `unless:` returns truthy or `if:` returns falsy the entry
   #     is reported with `status: :not_applicable`.
   #   - `group` (String, optional) — set implicitly by enclosing `group`
   #     block; surfaced verbatim.
+  #   - `deprecated:` (Boolean, optional) — flag for staged removal. When
+  #     true, the audit row includes `deprecated: true`.
+  #   - `sunset_on:` (String/Date, optional) — target removal date.
+  #     Surfaced verbatim in audit rows.
+  #   - `replacement:` (String, optional) — what to use instead. Surfaced
+  #     in audit rows.
   class EnvSpec
     # Raised when `in:` references a Symbol that hasn't been declared via
     # `mode_alias`.
@@ -53,6 +63,9 @@ module StandardHealth
       :if_predicate,
       :unless_predicate,
       :group,
+      :deprecated,
+      :sunset_on,
+      :replacement,
       keyword_init: true
     )
 
@@ -119,12 +132,20 @@ module StandardHealth
     #
     # @param env_hash [Hash{String, Symbol => String}] e.g. ENV.to_h
     # @param mode [String, Symbol] current APP_ENVIRONMENT value
+    # @param root [String, Pathname, nil] host app root for resolving
+    #   `consumed_by` paths. When given, each row gains a `consumer:` field:
+    #   `:present` (file exists and references the var),
+    #   `:file_missing` (path does not exist),
+    #   `:not_referenced` (file exists but no `ENV[...]` / `ENV.fetch(...)`
+    #   match for the var). When the entry has no `consumed_by` or `root`
+    #   is nil, the field is omitted.
     # @return [Array<Hash>] one row per applicable entry. Each row has at
     #   least `name`, `level`, `status`, `mode`. When an entry is suppressed
     #   by an `if:`/`unless:` predicate, `status` is `:not_applicable` and a
-    #   `reason` field explains why. `description`, `consumed_by`, and
-    #   `group` are included when set on the entry.
-    def audit(env_hash, mode:)
+    #   `reason` field explains why. `description`, `consumed_by`, `group`,
+    #   `deprecated`, `sunset_on`, `replacement`, and `consumer` are
+    #   included when set on the entry / computed during audit.
+    def audit(env_hash, mode:, root: nil)
       mode_str = mode.to_s
       env = stringify(env_hash)
 
@@ -142,6 +163,9 @@ module StandardHealth
           row[:status] = classify(entry, value)
         end
 
+        consumer_status = consumer_state(entry, root)
+        row[:consumer] = consumer_status if consumer_status
+
         out << row
       end
     end
@@ -158,7 +182,10 @@ module StandardHealth
         consumed_by: normalize_consumed_by(opts[:consumed_by]),
         if_predicate: opts[:if],
         unless_predicate: opts[:unless],
-        group: @group_stack.last
+        group: @group_stack.last,
+        deprecated: opts[:deprecated] ? true : nil,
+        sunset_on: opts[:sunset_on],
+        replacement: opts[:replacement]
       )
     end
 
@@ -211,9 +238,47 @@ module StandardHealth
       row[:description] = entry.description if entry.description
       row[:consumed_by] = serialize_consumed_by(entry.consumed_by) if entry.consumed_by
       row[:group] = entry.group if entry.group
+      row[:deprecated] = true if entry.deprecated
+      row[:sunset_on] = entry.sunset_on.to_s if entry.sunset_on
+      row[:replacement] = entry.replacement if entry.replacement
       row
     end
 
+    # Resolve the consumer-presence state for an entry. Returns nil when
+    # we have nothing to check (no root, no consumed_by). Otherwise:
+    #
+    #   :present        — at least one consumed_by path exists AND mentions
+    #                     ENV["VAR"] or ENV.fetch("VAR", ...).
+    #   :file_missing   — every consumed_by path is missing on disk.
+    #   :not_referenced — at least one path exists, but none reference the
+    #                     env var.
+    def consumer_state(entry, root)
+      return nil if root.nil? || entry.consumed_by.nil?
+
+      pattern = env_reference_pattern(entry.name)
+      any_file_present = false
+      any_referenced = false
+
+      entry.consumed_by.each do |relative|
+        path = File.join(root.to_s, relative)
+        next unless File.file?(path)
+
+        any_file_present = true
+        any_referenced = true if File.read(path).match?(pattern)
+      end
+
+      return :file_missing unless any_file_present
+      any_referenced ? :present : :not_referenced
+    end
+
+    # Match ENV["VAR"], ENV['VAR'], ENV[:VAR], ENV.fetch("VAR", ...),
+    # ENV.fetch('VAR', ...), ENV.fetch(:VAR, ...). Word-boundary on the
+    # right so VAR_PREFIX doesn't accidentally match VAR.
+    def env_reference_pattern(name)
+      escaped = Regexp.escape(name.to_s)
+      /ENV(?:\.fetch)?\s*[\[(]\s*[:'"]?#{escaped}\b/
+    end
+
     def serialize_consumed_by(value)
       value.length == 1 ? value.first : value
     end

data/lib/standard_health/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StandardHealth
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_health
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim