standard_health 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8542efb5b2511d31b4c9b3ef2a10f650ed342c1eeadc4aecaadef1476b82bc59
-  data.tar.gz: 8996c9e8f67904d842f589e60d880127680afa55365cb3be835260db9d36b3c1
+  metadata.gz: 4bc8cdc021df7485cb1443cf6902b6fee31627ad6135d9eef6f284cd5eed47e0
+  data.tar.gz: bfd4e8a50e602685430481b85a0ebf604d1e930db71ce47492036d772f4aa13c
 SHA512:
-  metadata.gz: b528859586bf219cab6b76902a230f3e660d36e4c108db6489ad1c4643fc19455c868bfa1fbe2b5fdc5291173aa04bfaa516ff322f44cecea41cd3cf5381b474
-  data.tar.gz: fe062a3ab494d205e3d436037a4ea42fbe3802043a7d8b3ee873ff4d5b6dd1ae7d1a7bd4659a3e4c533d92cfc035fa47d7c582801a418e4ba24b8943163ae5d5
+  metadata.gz: 32ec724c45eb9899e4d241d5681d296e1ac5745c3ff1852b5a187dea1fcc2a6b7ff7a922c08f925f0b59189ca8523d11fd034a5743f394186d91c4c1f2d8596d
+  data.tar.gz: 4711ceae81d4b9d0c19b440cc62fe8b2677ce569661adf741775ecc7933ee93c68402c8141ca830e76a6a75aa023c3f7759ef4d68a175d38280a2d971e83b964

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/lib/standard_health/env_spec.rb

@@ -6,32 +6,62 @@ 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.
+  #   - `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.
   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,
+      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 +69,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 +119,105 @@ 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: }
+    # @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:)
       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
+
         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
       )
     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
+    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.3.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.3.0
 platform: ruby
 authors:
 - Jaryl Sim