standard_health 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8542efb5b2511d31b4c9b3ef2a10f650ed342c1eeadc4aecaadef1476b82bc59
-  data.tar.gz: 8996c9e8f67904d842f589e60d880127680afa55365cb3be835260db9d36b3c1
+  metadata.gz: 73c1743f46e03601e44970d282ca02dd195b22e5f22fe502e20e8a45281e0d69
+  data.tar.gz: 507f8e5fda5420690b7146b0f6a9136561c0a1b61d6c567c5be3dcd5c250be61
 SHA512:
-  metadata.gz: b528859586bf219cab6b76902a230f3e660d36e4c108db6489ad1c4643fc19455c868bfa1fbe2b5fdc5291173aa04bfaa516ff322f44cecea41cd3cf5381b474
-  data.tar.gz: fe062a3ab494d205e3d436037a4ea42fbe3802043a7d8b3ee873ff4d5b6dd1ae7d1a7bd4659a3e4c533d92cfc035fa47d7c582801a418e4ba24b8943163ae5d5
+  metadata.gz: 38b527cf8973dc2557b1b8c13e40ace60f73efb78f1aab34100b4a51cf4f53069700c7ac0047f038a9bcf5fdcb9a1f3223fa92ddc653e1293f6c5d4b51f320ed
+  data.tar.gz: 3662477381f1149d26394ba63fc2380c2104d1cb78a65bf3d943681a907b591ad0e7e9a6f990c868cf48087306cf6cb845c399fd976a346858ba083647b6bc3e

data/CHANGELOG.md

@@ -7,6 +7,32 @@ 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
+
+- `if:` and `unless:` Proc predicates on `required` and `recommended`. Evaluated at audit time; when `unless:` returns truthy or `if:` returns falsy the entry is reported with `status: :not_applicable` and a `reason` field. Solves the MyInfo mock-mode case where `MYINFO_PRIVATE_JWKS` is only required outside mock mode.
+- `mode_alias` top-level DSL inside `EnvSpec.define`. Maps a Symbol to an `Array<String>` of `APP_ENVIRONMENT` values. `in:` now accepts a Symbol that is resolved against declared aliases at audit time; an undefined Symbol raises `StandardHealth::EnvSpec::UnknownModeAlias`.
+- `consumed_by:` keyword on `required`/`recommended`. Accepts a String or `Array<String>` pointing at where the env var is read in the host app; flows through to audit rows verbatim.
+- `group "Label" do ... end` block inside `EnvSpec.define`. Tags enclosed entries with a `group` field in their audit rows. Pure metadata for ops UX.
+- New `:not_applicable` value for the `status` field, used when an `if:`/`unless:` predicate suppresses an entry.
+
+### Changed
+
+- `EnvSpec` internals refactored: `Entry` struct extended with `consumed_by`, `if_predicate`, `unless_predicate`, and `group`. Backward-compatible — every 0.2.0 spec produces identical audit output (modulo `description` now appearing where it was previously suppressed and `group`/`consumed_by` appearing only when set).
+
 ## [0.2.0] - 2026-04-29
 
 ### Added

data/README.md

@@ -69,8 +69,10 @@ The DSL has two declarations:
 
 Both accept:
 
-- `in: %w[staging production]` — restricts the entry to those `APP_ENVIRONMENT` values; ignored otherwise
+- `in: %w[staging production]` — restricts the entry to those `APP_ENVIRONMENT` values; ignored otherwise. May also be a Symbol resolved via `mode_alias` (see below).
 - `description: "..."` — surfaced verbatim in the audit JSON
+- `consumed_by: "config/initializers/sentry.rb"` — pointer (or `Array<String>`) to where the value is read; surfaced verbatim
+- `if: -> { ... }` / `unless: -> { ... }` — Proc predicates evaluated at audit time. When `unless:` returns truthy or `if:` returns falsy, the entry is reported with `status: :not_applicable`
 
 Audit output (one row per applicable entry):
 
@@ -83,7 +85,108 @@ Audit output (one row per applicable entry):
 }
 ```
 
-Possible `status` values are `ok`, `missing` (required + absent), and `should_set` (recommended + absent).
+Possible `status` values are `ok`, `missing` (required + absent), `should_set` (recommended + absent), and `not_applicable` (suppressed by an `if:`/`unless:` predicate).
+
+### Predicates: `if:` and `unless:`
+
+Use predicates when an env var is only meaningful under runtime conditions that aren't expressible as a fixed list of `APP_ENVIRONMENT` values — e.g. when a host app supports a "mock mode" toggle.
+
+```ruby
+required :MYINFO_PRIVATE_JWKS,
+  in: %w[production],
+  unless: -> { ENV["MYINFO_MOCK_MODE"].present? }
+
+recommended :SENTRY_DSN,
+  if: -> { ENV["SENTRY_DISABLED"].blank? }
+```
+
+A suppressed entry surfaces as:
+
+```json
+{
+  "name": "MYINFO_PRIVATE_JWKS",
+  "level": "required",
+  "status": "not_applicable",
+  "reason": "unless predicate matched",
+  "mode": "production"
+}
+```
+
+The `reason` is `"unless predicate matched"` or `"if predicate did not match"`. Both predicates may be combined; the entry only evaluates when `if:` is truthy and `unless:` is falsy.
+
+### Mode aliases: `mode_alias`
+
+Declare reusable groupings of `APP_ENVIRONMENT` values inside the `define` block, then reference them as Symbols in `in:`. Common patterns ship as conventions (not built-ins): `:deployed` for staging-and-up, `:live` for production-only.
+
+```ruby
+StandardHealth::EnvSpec.define do
+  mode_alias :deployed, %w[staging preview production]
+  mode_alias :live,     %w[production]
+
+  required :APP_ENVIRONMENT
+  required :SENTRY_DSN,       in: :deployed
+  required :STRIPE_LIVE_KEY,  in: :live
+end
+```
+
+`in:` accepts:
+
+- `nil` (omitted) — entry always applies
+- `Array<String>` — literal mode list (existing behaviour)
+- `Symbol` — resolved against `mode_alias` at audit time. An undeclared Symbol raises `StandardHealth::EnvSpec::UnknownModeAlias`.
+
+### `description:` and `consumed_by:`
+
+Both flow through to audit rows verbatim. `description:` is a human hint; `consumed_by:` points at the file(s) that read the value, which makes "what does this env var actually do" much faster to answer in incident response.
+
+```ruby
+required :APP_HOST,
+  in: :deployed,
+  description: "Canonical web host",
+  consumed_by: "config/initializers/sentry.rb"
+```
+
+```json
+{
+  "name": "APP_HOST",
+  "level": "required",
+  "status": "ok",
+  "mode": "production",
+  "description": "Canonical web host",
+  "consumed_by": "config/initializers/sentry.rb"
+}
+```
+
+`consumed_by:` may be a String or `Array<String>`; an Array is preserved as a JSON array.
+
+### Groups
+
+Wrap related declarations in a `group "Label" do ... end` block to tag them with a category. Groups are pure metadata — they don't affect applicability, status, or evaluation order. Nested `group` blocks are supported; the innermost label propagates to enclosed entries. Calling `group` without a block raises `ArgumentError`.
+
+```ruby
+StandardHealth::EnvSpec.define do
+  group "Singpass / MyInfo" do
+    required :MYINFO_CLIENT_ID
+    required :MYINFO_PRIVATE_JWKS, unless: -> { ENV["MYINFO_MOCK_MODE"].present? }
+  end
+
+  group "Database" do
+    required :DATABASE_URL, in: :deployed
+  end
+end
+```
+
+Audit rows for entries declared inside a `group` block carry a `group` key:
+
+```json
+{ "name": "MYINFO_CLIENT_ID", "level": "required", "status": "ok", "mode": "production", "group": "Singpass / MyInfo" }
+```
+
+Entries declared outside any `group` block omit the `group` key entirely.
+
+### Backward compatibility
+
+All v0.2.0 specs continue to produce identical audit output in v0.3.0. The new fields (`description`, `consumed_by`, `group`, `reason`) appear only when the corresponding feature is used; the new `:not_applicable` status only appears when a predicate suppresses an entry.
 
 ## Custom checks
 

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

@@ -6,32 +6,75 @@ module StandardHealth
   # Example:
   #
   #   StandardHealth::EnvSpec.define do
+  #     mode_alias :deployed, %w[staging preview production]
+  #     mode_alias :live, %w[production]
+  #
   #     required :SECRET_KEY_BASE
   #     required :APP_ENVIRONMENT, in: %w[staging production]
   #     recommended :SENTRY_DSN, description: "Error tracking DSN"
+  #
+  #     group "Singpass / MyInfo" do
+  #       required :MYINFO_CLIENT_ID
+  #       required :MYINFO_PRIVATE_JWKS,
+  #         in: :live,
+  #         unless: -> { ENV["MYINFO_MOCK_MODE"].present? }
+  #     end
   #   end
   #
   # Each entry has:
   #   - `name` (Symbol)
   #   - `level` (:required | :recommended)
-  #   - `modes` (Array<String>, optional) — when set, the entry only applies
-  #     while `APP_ENVIRONMENT` matches one of these modes. Otherwise it
-  #     applies to every mode.
-  #   - `description` (String, optional) — human-readable hint surfaced
+  #   - `in:` (Array<String>, Symbol, or nil) — when an Array, the entry only
+  #     applies while `APP_ENVIRONMENT` matches one of these modes. A Symbol
+  #     is resolved against `mode_alias` declarations at audit time. When
+  #     omitted, the entry applies to every mode.
+  #   - `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. 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
-    Entry = Struct.new(:name, :level, :modes, :description, keyword_init: true) do
-      # Whether this entry's audit applies under the given runtime mode.
-      # Entries without a `modes:` constraint always apply.
-      def applies_to?(mode)
-        return true if modes.nil? || modes.empty?
-        modes.include?(mode.to_s)
-      end
-    end
+    # Raised when `in:` references a Symbol that hasn't been declared via
+    # `mode_alias`.
+    class UnknownModeAlias < ArgumentError; end
+
+    # Internal entry record. `modes` may be an Array<String> or a Symbol
+    # alias that gets resolved at audit time.
+    Entry = Struct.new(
+      :name,
+      :level,
+      :modes,
+      :description,
+      :consumed_by,
+      :if_predicate,
+      :unless_predicate,
+      :group,
+      :deprecated,
+      :sunset_on,
+      :replacement,
+      keyword_init: true
+    )
 
     # @return [Array<Entry>]
     attr_reader :entries
 
+    # @return [Hash{Symbol => Array<String>}]
+    attr_reader :mode_aliases
+
     # Build a spec via the DSL.
     def self.define(&block)
       new.tap { |spec| spec.instance_eval(&block) if block }
@@ -39,13 +82,42 @@ module StandardHealth
 
     def initialize
       @entries = []
+      @mode_aliases = {}
+      @group_stack = []
+    end
+
+    # Declare a mode alias usable in `in:`. Re-declaring overrides the
+    # previous value (last writer wins) so layered specs are easy to compose.
+    #
+    # @param name [Symbol]
+    # @param modes [Array<String>]
+    def mode_alias(name, modes)
+      @mode_aliases[name.to_sym] = Array(modes).map(&:to_s)
+    end
+
+    # Group subsequent declarations under a label. Pure metadata —
+    # propagated to audit rows as `group:` and otherwise inert. Nested
+    # `group` blocks are supported; the innermost label is the one that
+    # propagates to enclosed entries.
+    #
+    # @param label [String]
+    def group(label, &block)
+      raise ArgumentError, "group requires a block" unless block
+
+      @group_stack.push(label.to_s)
+      block.call
+    ensure
+      @group_stack.pop
     end
 
     # Declare a required env var.
     #
     # @param name [Symbol, String]
-    # @param in [Array<String>, nil] limit applicability to these modes
+    # @param in [Array<String>, Symbol, nil] limit applicability to these modes
     # @param description [String, nil]
+    # @param consumed_by [String, Array<String>, nil]
+    # @param if [Proc, nil]
+    # @param unless [Proc, nil]
     def required(name, **opts)
       add(:required, name, **opts)
     end
@@ -60,41 +132,157 @@ module StandardHealth
     #
     # @param env_hash [Hash{String, Symbol => String}] e.g. ENV.to_h
     # @param mode [String, Symbol] current APP_ENVIRONMENT value
-    # @return [Array<Hash>] one row per applicable entry, each shaped like:
-    #   { name:, level:, status: :ok | :missing | :should_set, mode: }
-    def audit(env_hash, mode:)
+    # @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`, `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)
 
       @entries.each_with_object([]) do |entry, out|
-        next unless entry.applies_to?(mode_str)
-
-        value = env[entry.name.to_s]
-        status = classify(entry, value)
-
-        row = {
-          name: entry.name,
-          level: entry.level,
-          status: status,
-          mode: mode_str
-        }
-        row[:description] = entry.description if entry.description
+        next unless mode_applies?(entry, mode_str)
+
+        row = base_row(entry, mode_str)
+
+        suppression = predicate_suppression(entry)
+        if suppression
+          row[:status] = :not_applicable
+          row[:reason] = suppression
+        else
+          value = env[entry.name.to_s]
+          row[:status] = classify(entry, value)
+        end
+
+        consumer_status = consumer_state(entry, root)
+        row[:consumer] = consumer_status if consumer_status
+
         out << row
       end
     end
 
     private
 
-    def add(level, name, in: nil, description: nil)
-      modes = binding.local_variable_get(:in)
+    def add(level, name, **opts)
+      modes_opt = opts[:in]
       @entries << Entry.new(
         name: name.to_sym,
         level: level,
-        modes: modes ? Array(modes).map(&:to_s) : nil,
-        description: description
+        modes: normalize_modes(modes_opt),
+        description: opts[:description],
+        consumed_by: normalize_consumed_by(opts[:consumed_by]),
+        if_predicate: opts[:if],
+        unless_predicate: opts[:unless],
+        group: @group_stack.last,
+        deprecated: opts[:deprecated] ? true : nil,
+        sunset_on: opts[:sunset_on],
+        replacement: opts[:replacement]
       )
     end
 
+    def normalize_modes(modes_opt)
+      return nil if modes_opt.nil?
+      return modes_opt if modes_opt.is_a?(Symbol)
+      Array(modes_opt).map(&:to_s)
+    end
+
+    def normalize_consumed_by(value)
+      return nil if value.nil?
+      array = Array(value).map(&:to_s)
+      array.empty? ? nil : array
+    end
+
+    def mode_applies?(entry, mode_str)
+      modes = resolve_modes(entry.modes)
+      return true if modes.nil? || modes.empty?
+      modes.include?(mode_str)
+    end
+
+    def resolve_modes(modes)
+      return nil if modes.nil?
+      if modes.is_a?(Symbol)
+        unless @mode_aliases.key?(modes)
+          raise UnknownModeAlias, "Unknown mode alias: #{modes.inspect}"
+        end
+        @mode_aliases[modes]
+      else
+        modes
+      end
+    end
+
+    def predicate_suppression(entry)
+      if entry.unless_predicate && entry.unless_predicate.call
+        return "unless predicate matched"
+      end
+      if entry.if_predicate && !entry.if_predicate.call
+        return "if predicate did not match"
+      end
+      nil
+    end
+
+    # Builds the metadata-only portion of an audit row. The caller is
+    # responsible for setting `:status` (and optionally `:reason`) — keeping
+    # status off the base intentionally so a future code path that forgets
+    # to set it produces a missing-key error instead of a silent `nil`.
+    def base_row(entry, mode_str)
+      row = { name: entry.name, level: entry.level, mode: mode_str }
+      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
+
     def classify(entry, value)
       present = !value.nil? && !value.to_s.empty?
       return :ok if present

data/lib/standard_health/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StandardHealth
-  VERSION = "0.2.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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim