ultra_settings 2.8.0 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 846f2c54ef9d4019e4f97ad02dcc962813a29fccc6128fe1e18ef9f263c01c2e
-  data.tar.gz: 7d28f71ae610362fd8e2c4e0ffe2ae885d7b9f270fc0e942f41fd7e8daff18fc
+  metadata.gz: d6db7d9c5a607d4c0318190ba8357f0577f9d542d08fbc77e6253e3776372476
+  data.tar.gz: 52171f7843724be2e867f2cf3547b934a530249173f8f2c583548f442f9ceb22
 SHA512:
-  metadata.gz: 8829e070b1f37474fc6673804d219d1485b2cb36c5d81f9dcd4b88ff6623bd1f99a5a135adedf4cc2a2f1865ac27d74b8f405b01896aabc3da2b5e41226333f3
-  data.tar.gz: 0e906fddfea5764d653beb41c99d534c30b44974a83b8f7e3de1d76dd1656e367fe160743f4ac65ec422bf0e1c7d0c35b28ff2d5e3ce4252bf70d53d0f367709
+  metadata.gz: 660219db715918d464d403064ac96920dde3acf7be57e85b3de921ecc7fe4b3ef641f9ef8b386ea931a603ad7cfab5f4f9ddd9cbc4f151226e4d3359d5a25dce
+  data.tar.gz: b4b40f05c524a3bd75fbb237c631e4643f229c50134fadf819acd1dded92855ebb3070eeaa8ee508a36bdbb13ec759a3fd6eb9c140db90d092ebd649a88bb8cf

data/AGENTS.md

@@ -0,0 +1,191 @@
+# UltraSettings AI Coding Agent Instructions
+
+## Project Overview
+UltraSettings is a Ruby gem for managing application configuration from multiple sources (environment variables, runtime settings, YAML files) with built-in type safety, validation, and a web UI for documentation.
+
+## Core Architecture
+
+### Configuration Classes (Singleton Pattern)
+- All configuration classes extend `UltraSettings::Configuration` and use Ruby's `Singleton` module
+- Each configuration class has one instance accessible via `.instance`
+- Register configurations globally: `UltraSettings.add(:test)` creates `UltraSettings.test` accessor
+- Configuration classes support inheritance; subclasses maintain separate singleton instances
+
+### Field Definition DSL
+Fields are defined using the `field` class method with extensive options:
+```ruby
+field :timeout, type: :float, default: 1.0, 
+      default_if: ->(val) { val <= 0 },
+      description: "Network timeout in seconds",
+      secret: false
+```
+
+### Multi-Source Value Resolution (Precedence Order)
+1. **Environment Variables** - Highest priority (e.g., `MY_SERVICE_TIMEOUT`)
+2. **Runtime Settings** - Dynamic configuration from external stores (e.g., Redis, `super_settings` gem)
+3. **YAML Files** - File-based defaults with ERB support
+4. **Default Values** - Fallback specified in field definition
+
+### Type System
+Supported types: `:string` (default), `:symbol`, `:integer`, `:float`, `:boolean`, `:datetime`, `:array`
+- Boolean fields auto-generate `?` predicate methods (e.g., `enabled?`)
+- Array type parses CSV strings from env vars, supports proper arrays from YAML
+- Empty strings coerce to `nil` across all sources
+
+## Key Conventions
+
+### Naming Patterns
+- **Configuration class names**: Must end in `Configuration` (e.g., `MyServiceConfiguration`)
+- **Field names**: Match `/\A[a-z_][a-zA-Z0-9_]*\z/` pattern (snake_case)
+- **Environment variable defaults**: `MY_SERVICE_FOO` for `MyServiceConfiguration#foo`
+- **Runtime setting defaults**: `my_service.foo` (lowercase with dots)
+- **YAML keys**: Match field name by default
+
+### Customization Attributes
+Set on configuration classes to override defaults:
+- `env_var_prefix`, `env_var_delimiter`, `env_var_upcase` - Control environment variable naming
+- `runtime_setting_prefix`, `runtime_setting_delimiter`, `runtime_setting_upcase` - Control runtime setting naming
+- `configuration_file` - Specify explicit YAML file path
+- `fields_secret_by_default` - Default secret status (true by default for security)
+- Disable sources entirely: `environment_variables_disabled`, `runtime_settings_disabled`, `yaml_config_disabled`
+
+### Thread Safety
+- All memoized values protected by `Mutex`
+- Override values are thread-local (keyed by `Thread.current.object_id`)
+- Static fields are cached permanently after first access
+
+## Testing Patterns
+
+### Test Setup (spec/spec_helper.rb)
+```ruby
+# Configure YAML path and environment
+UltraSettings.yaml_config_path = Pathname.new(__dir__) + "config"
+UltraSettings.yaml_config_env = "test"
+
+# Register configurations
+UltraSettings.add(:test)
+```
+
+### Overriding Configuration Values
+Use `override!` method for temporary value changes in tests:
+```ruby
+# Via UltraSettings module
+UltraSettings.override!(test: {foo: "bar"}) { ... }
+
+# Via configuration class
+TestConfiguration.override!(foo: "bar") { ... }
+
+# Via configuration instance
+TestConfiguration.instance.override!(foo: "bar") { ... }
+```
+
+### RSpec Integration Example
+```ruby
+RSpec.configure do |config|
+  config.around do |example|
+    if example.metadata[:ultra_settings]
+      UltraSettings.override!(example.metadata[:ultra_settings]) do
+        example.run
+      end
+    end
+  end
+end
+```
+
+### Climate Control for Environment Variables
+Uses `climate_control` gem to safely modify environment variables in tests:
+```ruby
+RSpec.describe "config", env: {TIMEOUT: "5"} do
+  # Test with environment variable set
+end
+```
+
+## Web UI Features
+
+### Mounting the Rack App
+```ruby
+# config.ru or Rails routes
+mount UltraSettings::RackApp.new(color_scheme: :system), at: "/settings"
+```
+
+### Key Capabilities
+- Displays all registered configurations with descriptions
+- Shows field metadata: type, description, sources, but **NOT actual values**
+- Respects secret field marking (values hidden)
+- Includes links to edit runtime settings via `UltraSettings.runtime_settings_url`
+- Views in `lib/ultra_settings/*_view.rb` use ERB templates from `app/` directory
+
+## Common Development Workflows
+
+### Running Tests
+```bash
+bundle exec rake spec  # Default task runs all specs
+bundle exec rspec spec/ultra_settings/configuration_spec.rb  # Specific file
+```
+
+### Checking Code Style
+Uses Standard Ruby style guide (testdouble/standard):
+```bash
+bundle exec standardrb --fix
+```
+
+### Release Process
+- Can only release from `main` branch (enforced in Rakefile)
+- Version stored in `VERSION` file (no hardcoded version in gemspec)
+
+## Special Features
+
+### Static Fields
+- Marked with `static: true`, values never change after first access
+- Cannot be set from runtime settings (initialization-time only)
+- Use for settings referenced during app boot
+
+### Secret Fields
+- All fields secret by default unless `fields_secret_by_default = false`
+- Masked in `__to_hash__` output
+- Runtime settings disabled on secret fields unless `UltraSettings.runtime_settings_secure = true`
+- Secret status can be dynamic via Proc
+
+### Conditional Defaults
+Use `default_if` with Proc or method name to apply defaults based on loaded value:
+```ruby
+field :timeout, default: 1.0, default_if: ->(val) { val <= 0 }
+```
+
+### Introspection Methods
+- `__source__(name)` - Returns which source provided the value (`:env`, `:runtime`, `:yaml`, `:default`)
+- `__value_from_source__(name, source)` - Fetch value from specific source
+- `__to_hash__` - Serialize current configuration as hash (secrets masked)
+
+## Important Implementation Details
+
+### Dynamic Method Generation
+Fields create getter methods via `class_eval` for performance (avoids `method_missing`)
+
+### YAML Configuration
+- Supports environment-specific sections (e.g., `development`, `test`, `production`)
+- Special `shared` section merged with environment-specific config
+- ERB templates evaluated before YAML parsing
+- Files searched in `UltraSettings.yaml_config_path`
+
+### Runtime Settings Integration
+- Must implement `[]` method accepting string argument
+- Optional `array` method for native array support
+- Use `UninitializedRuntimeSettings` during boot to catch premature access
+- `super_settings` gem is recommended companion implementation
+
+## File Organization
+
+- `lib/ultra_settings/configuration.rb` - Core configuration class (630 lines)
+- `lib/ultra_settings/field.rb` - Field metadata and resolution logic
+- `lib/ultra_settings/coerce.rb` - Type coercion utilities
+- `lib/ultra_settings/*.rb` - Supporting classes for web UI, YAML, helpers
+- `spec/test_configs/` - Example configuration classes for testing
+- `spec/config/` - YAML configuration files for tests
+- `app/` - ERB templates and assets for web UI
+
+## Key Dependencies
+- Ruby >= 2.5
+- Development: `rspec`, `climate_control`, `nokogiri`, `bundler`
+- Optional: `super_settings` gem for runtime settings store
+- Rails integration via `railtie.rb` when Rails is detected

data/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.8.1
+
+### Added
+
+- Improved web UI indication for which data sources on fields have been overridden by data sources with higher precedence.
+- Added rake tasks for auditing configuration data sources.
+- A companion gem `yard-ultra_settings` is now available to provide YARD integration for documenting UltraSettings configuration classes. See the [yard-ultra_settings](https://github.com/bdurand/ultra_settings/yard_plugin) gem for more information.
+
 ## 2.8.0
 
 ### Added

data/MIT-LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright 2023 Brian Durand
+Copyright 2026 Brian Durand
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -520,6 +520,74 @@ class MyServiceConfiguration < UltraSettings::Configuration
 end
 ```
 
+### Rails Tasks
+
+You can audit your configuration data sources with rake tasks to identify potential optimizations with these rake tasks:
+
+```bash
+# Output showing environment variables that are set, but which do not need to be set
+# since they match the default values.
+bundle exec rails ultra_settings:unnecessary_env_vars
+
+# Output showing runtime settings that are set, but which do not need to be set
+# since they match the default values.
+bundle exec rails ultra_settings:unnecessary_runtime_settings
+
+# Output showing environment variables that are set but which could be loaded from
+# runtime settings instead.
+bundle exec rails ultra_settings:env_vars_can_be_runtime_setting
+
+# Output showing environment variables that are set that could be candidates for
+# adding default values to the configuration fields.
+bundle exec rails ultra_settings:env_vars_without_default
+```
+
+## Generating Documentation
+
+### YARD Plugin
+
+For projects using [YARD](https://yardoc.org/) for documentation, there is a companion plugin gem that automatically generates documentation for configuration fields.
+
+Add to your Gemfile:
+
+```ruby
+group :development, :test do
+  gem 'yard-ultra_settings'
+end
+```
+
+Then add the following to your `.yardopts` file:
+
+```
+--plugin ultra_settings
+```
+
+Once configured, the plugin automatically enhances YARD documentation for any classes that inherit from `UltraSettings::Configuration`. Field definitions will automatically generate method documentation with proper types and return values.
+
+See the [yard-ultra_settings](https://github.com/bdurand/ultra_settings/tree/main/yard_plugin) gem for more details.
+
+### Using YARD Macros
+
+If you prefer not to install the plugin gem, you can use YARD's built-in macro feature by adding documentation comments before field definitions:
+
+```ruby
+class MyServiceConfiguration < UltraSettings::Configuration
+  self.fields_secret_by_default = false
+
+  # @!method host
+  #   The hostname for the service
+  #   @return [String, nil]
+  field :host, type: :string
+
+  # @!method port
+  #   The port for the service
+  #   @return [Integer]
+  field :port, type: :integer, default: 80
+end
+```
+
+This approach gives you full control over the documentation but requires more manual effort for each field.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-2.8.0
+2.8.1

data/app/_data_source.html.erb

@@ -0,0 +1,39 @@
+<% source_value = configuration.__value_from_source__(field.name, source) %>
+<% overridden_by = source_overridden_by(source, current_source) %>
+<div class="ultra-settings-source <%= 'ultra-settings-source-active' if current_source == source %> <%= 'ultra-settings-source-overridden' if overridden_by && !source_value.nil? %>">
+  <span class="ultra-settings-source-type">
+    <%= source_type %>
+  </span>
+
+  <div class="ultra-settings-source-value-container">
+    <% if source_name %>
+      <code class="ultra-settings-source-value">
+        <%= source_name %>
+      </code>
+    <% end %>
+
+    <%= show_defined_value(source_name, source_value, field.secret?) %>
+  </div>
+
+  <% if current_source == source %>
+    <span class="ultra-settings-source-indicator">
+      Currently active
+    </span>
+  <% elsif overridden_by && !source_value.nil? %>
+    <%= override_indicator(overridden_by) %>
+  <% end %>
+
+  <% if source == :settings %>
+    <% edit_url = UltraSettings.runtime_settings_url(name: field.runtime_setting, type: field.type, description: field.description) %>
+
+    <% if edit_url %>
+      <a
+        href="<%= html_escape(edit_url) %>"
+        class="ultra-settings-edit-link"
+        title="Edit <%= html_escape(field.runtime_setting) %>"
+      >
+        <%= edit_icon %>
+      </a>
+    <% end %>
+  <% end %>
+</div>

data/app/application.css

@@ -132,6 +132,10 @@ code.ultra-settings-field-data-value {
   gap: 0.5rem;
 }
 
+.ultra-settings-field-description svg {
+  margin-top: 0.125rem;
+}
+
 .ultra-settings-description-text {
   flex: 1;
 }
@@ -166,13 +170,19 @@ code.ultra-settings-field-data-value {
   min-width: 120px;
 }
 
+.ultra-settings-source-value-container {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex: 1;
+  margin: 0 0.75rem;
+}
+
 .ultra-settings-source-value {
   font-family: monospace;
   font-size: 0.875rem;
   color: var(--source-value-color);
   font-weight: 550;
-  flex: 1;
-  margin: 0 0.75rem;
   word-break: break-all;
 }
 
@@ -189,19 +199,95 @@ code.ultra-settings-field-data-value {
   font-size: 1rem;
 }
 
+.ultra-settings-source-overridden {
+  background-color: var(--source-overridden-bg-color);
+  border-color: var(--source-overridden-border-color);
+}
+
+.ultra-settings-source-overridden .ultra-settings-source-type {
+  color: var(--source-overridden-type-color);
+}
+
+.ultra-settings-source-overridden .ultra-settings-source-value-container .ultra-settings-source-value {
+  color: var(--source-overridden-value-color);
+}
+
+.ultra-settings-source-override {
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--source-overridden-warning-color);
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.ultra-settings-source-override svg {
+  flex-shrink: 0;
+}
+
+.ultra-settings-source-override-text {
+  text-transform: uppercase;
+  letter-spacing: 0.025em;
+}
+
 .ultra-settings-icon-info {
   color: var(--info-color);
   cursor: pointer;
+  padding: 0.25rem;
+  border-radius: 0.25rem;
+  transition: all 0.15s ease;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.ultra-settings-icon-info:hover {
+  background-color: var(--source-bg-color);
+  transform: scale(1.15);
+}
+
+.ultra-settings-icon-info:active {
+  transform: scale(1.05);
 }
 
 .ultra-settings-icon-not-set {
   color: var(--warning-color);
   cursor: pointer;
+  padding: 0.25rem;
+  border-radius: 0.25rem;
+  transition: all 0.15s ease;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.ultra-settings-icon-not-set:hover {
+  background-color: var(--source-bg-color);
+  transform: scale(1.15);
+}
+
+.ultra-settings-icon-not-set:active {
+  transform: scale(1.05);
 }
 
 .ultra-settings-icon-secret {
   color: var(--disabled-color);
   cursor: pointer;
+  padding: 0.25rem;
+  border-radius: 0.25rem;
+  transition: all 0.15s ease;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.ultra-settings-icon-secret:hover {
+  background-color: var(--source-bg-color);
+  transform: scale(1.15);
+}
+
+.ultra-settings-icon-secret:active {
+  transform: scale(1.05);
 }
 
 .ultra-settings-edit-link {
@@ -219,25 +305,54 @@ code.ultra-settings-field-data-value {
 }
 
 .ultra-settings-dialog {
-  min-width: 20rem;
+  min-width: 24rem;
+  max-width: 90vw;
   padding: 0;
-  border: 1px solid var(--field-border-color);
-  border-radius: 0.375rem;
+  border: none;
+  border-radius: 0.5rem;
+  box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
+  animation: ultra-settings-dialog-show 0.2s ease-out;
+}
+
+.ultra-settings-dialog::backdrop {
+  background-color: rgba(0, 0, 0, 0.5);
+  animation: ultra-settings-backdrop-show 0.2s ease-out;
+}
+
+@keyframes ultra-settings-dialog-show {
+  from {
+    opacity: 0;
+    transform: scale(0.95) translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+
+@keyframes ultra-settings-backdrop-show {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
 }
 
 .ultra-settings-dialog-header {
-  padding: 0.5rem;
+  padding: 1rem 1.25rem;
   background-color: var(--field-header-bg-color);
   color: var(--field-header-text-color);
   font-size: 1rem;
   display: flex;
-  align-items: top;
+  align-items: center;
+  border-bottom: 1px solid var(--field-border-color);
 }
 
 .ultra-settings-dialog-title {
   flex: 1;
-  text-align: center;
-  font-weight: 550;
+  font-weight: 600;
+  font-size: 1.125rem;
 }
 
 .ultra-settings-dialog-close {
@@ -246,12 +361,37 @@ code.ultra-settings-field-data-value {
   color: var(--field-header-text-color);
   cursor: pointer;
   padding: 0.25rem;
+  border-radius: 0.25rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background-color 0.15s ease;
+  margin-left: 0.5rem;
+}
+
+.ultra-settings-dialog-close:hover {
+  background-color: var(--source-bg-color);
+}
+
+.ultra-settings-dialog-close:active {
+  transform: scale(0.95);
 }
 
 .ultra-settings-dialog-body {
-  padding: 1rem;
+  padding: 1.5rem;
   background-color: var(--background-color);
   color: var(--text-color);
+  max-height: 60vh;
+  overflow-y: auto;
+}
+
+.ultra-settings-dialog-body .ultra-settings-field-data-value {
+  display: block;
+  word-break: break-all;
+  white-space: pre-wrap;
+  font-size: 0.9375rem;
+  line-height: 1.6;
+  padding: 0.75rem 1rem;
 }
 
 /* Dropdown Styles */

data/app/application_vars.css.erb

@@ -28,6 +28,11 @@
     --source-border-color: #e9ecef;
     --source-active-bg-color: #e7f3ff;
     --source-active-border-color: #0d6efd;
+    --source-overridden-bg-color: #fff3cd;
+    --source-overridden-border-color: #ffc107;
+    --source-overridden-type-color: #4d4d4d;
+    --source-overridden-value-color: #2b2b2b;
+    --source-overridden-warning-color: #996900;
     --source-type-color: #666666;
     --source-value-color: #444444;
     --source-indicator-color: #0d6efd;
@@ -77,6 +82,11 @@
     --source-border-color: #444444;
     --source-active-bg-color: #1a3a52;
     --source-active-border-color: #0d6efd;
+    --source-overridden-bg-color: #3d3416;
+    --source-overridden-border-color: #997404;
+    --source-overridden-type-color: #d4d4d4;
+    --source-overridden-value-color: #e8e8e8;
+    --source-overridden-warning-color: #ffb84d;
     --source-type-color: #adb5bd;
     --source-value-color: #ced4da;
     --source-indicator-color: #6ea8fe;

data/app/configuration.html.erb

@@ -55,83 +55,28 @@
         <div class="ultra-settings-field-sources">
           <% sources = configuration.__available_sources__(field.name) %>
           <% if sources.include?(:env) %>
-            <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :env %>">
-              <span class="ultra-settings-source-type">
-                Environment Variable
-              </span>
-
-              <code class="ultra-settings-source-value">
-                <%= field.env_var %>
-                <%= show_defined_value(field.env_var, configuration.__value_from_source__(field.name, :env), field.secret?) %>
-              </code>
-
-              <% if source == :env %>
-                <span class="ultra-settings-source-indicator">
-                  Currently active
-                </span>
-              <% end %>
-            </div>
+            <%= render_partial "data_source", configuration: configuration, field: field, source: :env, current_source: source, source_type: "Environment Variable", source_name: field.env_var %>
           <% end %>
 
           <% if sources.include?(:settings) %>
-            <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :settings %>">
-              <span class="ultra-settings-source-type">Runtime Setting</span>
-
-              <code class="ultra-settings-source-value">
-                <%= field.runtime_setting %>
-                <%= show_defined_value(field.runtime_setting, configuration.__value_from_source__(field.name, :settings), field.secret?) %>
-              </code>
-
-              <% if source == :settings %>
-                <span class="ultra-settings-source-indicator">
-                  Currently active
-                </span>
-              <% end %>
-
-              <% edit_url = UltraSettings.runtime_settings_url(name: field.runtime_setting, type: field.type, description: field.description) %>
-
-              <% if edit_url %>
-                <a
-                  href="<%= html_escape(edit_url) %>"
-                  class="ultra-settings-edit-link"
-                  title="Edit <%= html_escape(field.runtime_setting) %>"
-                >
-                  <%= edit_icon %>
-                </a>
-              <% end %>
-            </div>
+            <%= render_partial "data_source", configuration: configuration, field: field, source: :settings, current_source: source, source_type: "Runtime Setting", source_name: field.runtime_setting %>
           <% end %>
 
           <% if sources.include?(:yaml) %>
-            <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :yaml %>">
-              <span class="ultra-settings-source-type">Configuration File</span>
-
-              <code class="ultra-settings-source-value">
-                <%= field.yaml_key %>
-                <%= show_defined_value(field.yaml_key, configuration.__value_from_source__(field.name, :yaml), field.secret?) %>
-              </code>
-
-              <% if source == :yaml %>
-                <span class="ultra-settings-source-indicator">
-                  Currently active
-                </span>
-              <% end %>
-            </div>
+            <%= render_partial "data_source", configuration: configuration, field: field, source: :yaml, current_source: source, source_type: "Configuration File", source_name: field.yaml_key %>
           <% end %>
 
-          <% if sources.include?(:default) || source == :default %>
-            <div class="ultra-settings-source <%= 'ultra-settings-source-active' if source == :default %>">
-              <span class="ultra-settings-source-type">Default Value</span>
+          <% if sources.include?(:default) %>
+            <%= render_partial "data_source", configuration: configuration, field: field, source: :default, current_source: source, source_type: "Default Value", source_name: nil %>
+          <% end %>
 
-              <code class="ultra-settings-source-value">
-                <%= show_defined_value("Default Value", field.default, field.secret?) %>
-              </code>
+          <% if source == :default && configuration[field.name].nil? %>
+            <div class="ultra-settings-source ultra-settings-source-active">
+              <span class="ultra-settings-source-type">Not Set</span>
 
-              <% if source == :default %>
-                <span class="ultra-settings-source-indicator">
-                  Currently active
-                </span>
-              <% end %>
+              <span class="ultra-settings-source-indicator">
+                Currently active
+              </span>
             </div>
           <% end %>
         </div>

data/lib/ultra_settings/audit_data_sources.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  class AuditDataSources
+    class << self
+      # Find environment variables that are set but have the same value as their default.
+      # These environment variables could potentially be removed since they're not changing behavior.
+      #
+      # @return [Array<Array<(String, Object)>>] An array of tuples containing environment variable names and their default values
+      def unnecessary_env_vars
+        env_vars_at_default = []
+        each_configuration do |config|
+          each_field_using_source(config, :env) do |field|
+            value = config[field.name]
+            default_value = default_config_value(config, field)
+            env_vars_at_default << [field.env_var, default_value] if default_value == value
+          end
+        end
+        env_vars_at_default
+      end
+
+      # Find runtime settings that are set but have the same value as their default.
+      # These runtime settings could potentially be removed since they're not changing behavior.
+      #
+      # @return [Array<Array<(String, Object)>>] An array of tuples containing runtime setting names and their default values
+      def unnecessary_runtime_settings
+        unnecessary_runtime_settings = []
+        each_configuration do |config|
+          each_field_using_source(config, :settings) do |field|
+            value = config[field.name]
+            default_value = default_config_value(config, field)
+            unnecessary_runtime_settings << [field.runtime_setting, default_value] if default_value == value
+          end
+        end
+        unnecessary_runtime_settings
+      end
+
+      # Find environment variables that could be moved to runtime settings.
+      # These are non-default environment variable values where a runtime setting is also available.
+      #
+      # @return [Array<Array<(String, String, Object)>>] An array of tuples containing environment variable name, runtime setting name, and current value
+      def env_vars_can_be_runtime_setting
+        env_vars_can_be_runtime = []
+        each_configuration do |config|
+          each_field_using_source(config, :env) do |field|
+            value = config[field.name]
+            default_value = default_config_value(config, field)
+            next unless field.runtime_setting && value != default_value
+
+            env_vars_can_be_runtime << [field.env_var, field.runtime_setting, value]
+          end
+        end
+        env_vars_can_be_runtime
+      end
+
+      # Find environment variables being used that don't have default values defined.
+      # These configurations require an environment variable to be set.
+      #
+      # @return [Array<Array<(String, Symbol, String, Object)>>] An array of tuples containing class name, field name, environment variable name, and current value
+      def env_vars_without_default
+        no_default_env_var_fields = []
+        each_configuration do |config|
+          each_field_using_source(config, :env) do |field|
+            value = default_config_value(config, field)
+            if value.nil?
+              no_default_env_var_fields << [config.class.name, field.name, field.env_var, config[field.name]]
+            end
+          end
+        end
+        no_default_env_var_fields
+      end
+
+      private
+
+      def each_configuration(&_block)
+        UltraSettings::Configuration.descendant_configurations.each do |config_class|
+          config = config_class.instance
+          yield config
+        end
+      end
+
+      def each_field_using_source(config, source, &_block)
+        config.class.fields.each do |field|
+          next if field.secret?
+          next unless config.__source__(field.name) == source
+
+          yield field
+        end
+      end
+
+      def default_config_value(config, field)
+        yaml_value = config.__value_from_source__(field.name, :yaml)
+        default_value = config.__value_from_source__(field.name, :default)
+        yaml_value || default_value
+      end
+    end
+  end
+end

data/lib/ultra_settings/configuration.rb

@@ -10,6 +10,7 @@ module UltraSettings
     @env_var_prefix = nil
     @runtime_setting_prefix = nil
     @description = nil
+    @descendants = []
 
     class << self
       # Set a description for the configuration. This is optional. It will be displayed
@@ -84,7 +85,8 @@ module UltraSettings
           secret: secret
         )
 
-        class_eval <<~RUBY, __FILE__, __LINE__ + 1 # rubocop:disable Security/Eval
+        caller_location = caller_locations(1, 1).first
+        class_eval <<~RUBY, caller_location.path, caller_location.lineno # rubocop:disable Security/Eval, Style/EvalWithLocation
           def #{name}
             __get_value__(#{name.inspect})
           end
@@ -110,7 +112,7 @@ module UltraSettings
         name = name.to_s
         return true if defined_fields.include?(name)
 
-        if superclass <= Configuration
+        if superclass < Configuration
           superclass.include_field?(name)
         else
           false
@@ -369,12 +371,30 @@ module UltraSettings
         YamlConfig.new(configuration_file, yaml_config_env).to_h
       end
 
+      # Get all descendant configuration classes (subclasses and their subclasses, recursively).
+      #
+      # @return [Array<Class>] All classes that inherit from this class.
+      def descendant_configurations
+        @descendants ||= []
+        @descendants.flat_map { |subclass| [subclass] + subclass.descendant_configurations }
+      end
+
       private
 
+      # Hook called when this class is inherited. Tracks all descendant classes.
+      #
+      # @param subclass [Class] The subclass that is inheriting from this class.
+      # @return [void]
+      def inherited(subclass)
+        super
+        @descendants ||= []
+        @descendants << subclass
+      end
+
       def defined_fields
         unless defined?(@defined_fields)
           fields = {}
-          if superclass <= Configuration
+          if superclass < Configuration
             fields = superclass.send(:defined_fields).dup
           end
           @defined_fields = fields

data/lib/ultra_settings/configuration_view.rb

@@ -153,5 +153,44 @@ module UltraSettings
         this.closest('.ultra-settings-configuration').querySelector('.ultra-settings-dialog-close').blur();
       JAVASCRIPT
     end
+
+    def source_priority
+      [:env, :settings, :yaml, :default]
+    end
+
+    def source_overridden_by(current_source, active_source)
+      return nil if current_source == active_source
+
+      current_index = source_priority.index(current_source)
+      active_index = source_priority.index(active_source)
+
+      return nil if current_index.nil? || active_index.nil?
+      return nil if current_index < active_index
+
+      active_source
+    end
+
+    def override_indicator(overridden_by_source)
+      source_names = {
+        env: "environment variable",
+        settings: "runtime setting",
+        yaml: "configuration file",
+        default: "default value"
+      }
+      <<~HTML
+        <span class="ultra-settings-source-override" title="Overridden by #{source_names[overridden_by_source]}">
+          #{warning_icon(14)}
+          <span class="ultra-settings-source-override-text">Overridden by #{source_names[overridden_by_source]}</span>
+        </span>
+      HTML
+    end
+
+    def warning_icon(size = 16)
+      <<~HTML
+        <svg width="#{size}" height="#{size}" fill="currentColor" viewBox="0 0 16 16">
+          <path d="M8.982 1.566a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 5.995A.905.905 0 0 1 8 5m.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2"/>
+        </svg>
+      HTML
+    end
   end
 end

data/lib/ultra_settings/railtie.rb

@@ -23,6 +23,8 @@ module UltraSettings
 
         app_config_dir = Rails.root.join(directory)
         app_config_dir.glob("**/*_configuration.rb").each do |file_path|
+          next unless file_path.file? && file_path.readable?
+
           relative_path = file_path.relative_path_from(app_config_dir).to_s
           class_name = relative_path.chomp(".rb").classify
           unless UltraSettings.added?(class_name)
@@ -32,5 +34,11 @@ module UltraSettings
         end
       end
     end
+
+    rake_tasks do
+      Dir.glob(File.expand_path("tasks/*.rake", __dir__)).each do |rake_file|
+        load rake_file
+      end
+    end
   end
 end

data/lib/ultra_settings/tasks/audit_data_sources.rake

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+namespace :ultra_settings do
+  desc <<~DOC
+    Generates a report of environment variables used in configurations that are set to their default values.
+    This report can help identify environment variables that are superfluous and can be removed. It skips any
+    environment variables that are used for secrets.
+  DOC
+  task unnecessary_env_vars: :environment do
+    require_relative "utils"
+    require_relative "../audit_data_sources"
+
+    UltraSettings::Tasks::Utils.eager_load!
+    env_vars_at_default = UltraSettings::AuditDataSources.unnecessary_env_vars
+
+    output = env_vars_at_default.collect do |env_var, value|
+      "Environment variable #{env_var} is set to its default value: #{value.inspect}"
+    end
+    puts output
+  end
+
+  desc <<~DOC
+    Generates a report of runtime settings used in configurations that are set to their default values.
+    This report can help identify runtime settings that are superfluous and can be removed. It skips any
+    runtime settings that are used for secrets.
+  DOC
+  task unnecessary_runtime_settings: :environment do
+    require_relative "utils"
+    require_relative "../audit_data_sources"
+
+    UltraSettings::Tasks::Utils.eager_load!
+    unnecessary_runtime_settings = UltraSettings::AuditDataSources.unnecessary_runtime_settings
+
+    output = unnecessary_runtime_settings.collect do |runtime_setting, value|
+      "Runtime setting #{runtime_setting} is set to its default value: #{value.inspect}"
+    end
+    puts output
+  end
+
+  desc <<~DOC
+    Generates a report of environment variables used in configurations that can be converted to runtime settings.
+    This report can help identify environment variables that can be removed if the corresponding runtime settings
+    are set. It skips any environment variables that are used for secrets.
+  DOC
+  task env_vars_can_be_runtime_setting: :environment do
+    require_relative "utils"
+    require_relative "../audit_data_sources"
+
+    UltraSettings::Tasks::Utils.eager_load!
+    env_vars_can_be_runtime = UltraSettings::AuditDataSources.env_vars_can_be_runtime_setting
+
+    output = env_vars_can_be_runtime.collect do |env_var, runtime_setting, value|
+      "Environment variable #{env_var} can be converted to runtime setting #{runtime_setting} with value: #{value.inspect}"
+    end
+    puts output
+  end
+
+  desc <<~DOC
+    Generates a report of environment variables used in configurations that do not have a default value.
+    This report can help identify settings that could be set in YAML or with a default value rather than via
+    environment variables. If these changes are made, then the environment variables could be removed.
+    It skips any environment variables that are used for secrets.
+  DOC
+  task env_vars_without_default: :environment do
+    require_relative "utils"
+    require_relative "../audit_data_sources"
+
+    UltraSettings::Tasks::Utils.eager_load!
+    env_vars_without_default = UltraSettings::AuditDataSources.env_vars_without_default
+
+    output = env_vars_without_default.collect do |config, field, env_var, value|
+      "Environment variable #{env_var} used by #{config}##{field} does not have a default value (current value: #{value.inspect})"
+    end
+    puts output
+  end
+end

data/lib/ultra_settings/tasks/utils.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module UltraSettings
+  module Tasks
+    module Utils
+      class << self
+        # Helper for eager loading a Rails application.
+        def eager_load!
+          return unless defined?(Rails.application.config.eager_load)
+          return if Rails.application.config.eager_load
+
+          if defined?(Rails.application.eager_load!)
+            Rails.application.eager_load!
+          elsif defined?(Rails.autoloaders.zeitwerk_enabled?) && Rails.autoloaders.zeitwerk_enabled?
+            Rails.autoloaders.each(&:eager_load)
+          else
+            raise "Failed to eager load application."
+          end
+        end
+      end
+    end
+  end
+end

data/ultra_settings.gemspec

@@ -28,6 +28,8 @@ Gem::Specification.new do |spec|
     bin/
     gemfiles/
     spec/
+    test_app/
+    yard_plugin/
   ]
   spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ultra_settings
 version: !ruby/object:Gem::Version
-  version: 2.8.0
+  version: 2.8.1
 platform: ruby
 authors:
 - Brian Durand
@@ -29,6 +29,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE.txt
@@ -36,6 +37,7 @@ files:
 - VERSION
 - app/_config_description.html.erb
 - app/_config_list.html.erb
+- app/_data_source.html.erb
 - app/_select_menu.html.erb
 - app/application.css
 - app/application.js
@@ -47,6 +49,7 @@ files:
 - app/layout_vars.css.erb
 - lib/ultra_settings.rb
 - lib/ultra_settings/application_view.rb
+- lib/ultra_settings/audit_data_sources.rb
 - lib/ultra_settings/coerce.rb
 - lib/ultra_settings/config_helper.rb
 - lib/ultra_settings/configuration.rb
@@ -55,6 +58,8 @@ files:
 - lib/ultra_settings/rack_app.rb
 - lib/ultra_settings/railtie.rb
 - lib/ultra_settings/render_helper.rb
+- lib/ultra_settings/tasks/audit_data_sources.rake
+- lib/ultra_settings/tasks/utils.rb
 - lib/ultra_settings/uninitialized_runtime_settings.rb
 - lib/ultra_settings/version.rb
 - lib/ultra_settings/view_helper.rb
@@ -82,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: UltraSettings is a Ruby gem that provides a flexible and documented approach
   to managing application configurations from multiple sources, including environment