ultra_settings 2.7.0 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f70521135220d74fe5ef4fbc6261c9d5b8a93f200f898af0fead2ebb7d31cbfd
-  data.tar.gz: 42330a1a294bee7ab53c61f37b56cd0b5b6f309326f1809bfd012cbfcd67fa58
+  metadata.gz: d6db7d9c5a607d4c0318190ba8357f0577f9d542d08fbc77e6253e3776372476
+  data.tar.gz: 52171f7843724be2e867f2cf3547b934a530249173f8f2c583548f442f9ceb22
 SHA512:
-  metadata.gz: aab2c06121a67e227f1628d1dd3a22590e0bb174f132506840112278a5c09484e57dd6bc176ddbb35d576388c29bb5f6da462473f1c5ebf76724fe8677312ed2
-  data.tar.gz: f7e9bd08a2958def30780e0ef966d8b90321d3f9c1bf469677b7c51ab8b512e867bf0e1fc1d910d72f24c9f71818a34050b3a2dbfdc2c5adb9afa4a3e048948a
+  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,28 @@ 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
+
+- Added support for setting a description on configuration classes. The class description can serve to document the purpose of the configuration and will be shown in the web UI.
+- Improved menu for selecting configuration classes in the web UI by adding a search box to filter the list of configurations.
+
+### Fixed
+
+- Fixed filtering of data sources for configuration classes in the web UI.
+  - The YAML source will not be shown if the configuration file is set to nil or false.
+  - The runtime settings source will not be shown if the runtime settings engine is not set up.
+  - Fields that override the class default for a data source will now correctly show that source.
+
 ## 2.7.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

@@ -424,7 +424,7 @@ If you prefer to embed the settings view directly into your own admin tools or d
 ```erb
 <h1>Configuration</h1>
 
-<%= UltraSettings::ApplicationView.new.render(select_class: "form-select") %>
+<%= UltraSettings::ApplicationView.new.render %>
 ```
 
 This approach allows for seamless integration of the settings UI into your application's admin interface, leveraging your existing authentication and authorization mechanisms. The settings are rendered with navigation handled by an HTML select element. You can specify the CSS classes for the select element to match your own application styles..
@@ -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.7.0
+2.8.1

data/app/_config_description.html.erb

@@ -0,0 +1,30 @@
+<% config_class = configuration.class
+  has_config_file = config_class.configuration_file.is_a?(Pathname) && config_class.fields.any?(&:yaml_key) %>
+
+<% if config_class.description || has_config_file %>
+  <div class="ultra-settings-description-container">
+    <% if config_class.description %>
+      <div class="ultra-settings-description">
+        <%= html_escape(config_class.description).gsub("\n", "<br>") %>
+      </div>
+    <% end %>
+
+    <% if has_config_file %>
+      <div class="ultra-settings-description">
+        <span class="ultra-settings-config-file-label">
+          Configuration file:
+        </span>
+
+        <code class="ultra-settings-config-file-path">
+          <%= html_escape(relative_path(configuration.class.configuration_file)) %>
+        </code>
+
+        <% unless configuration.class.configuration_file&.exist? %>
+          <span class="ultra-settings-file-not-found">
+            (file does not exist)
+          </span>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+<% end %>

data/app/_config_list.html.erb

@@ -0,0 +1,14 @@
+<div class="ultra-settings-configuration-list" style="display:none;">
+  <% configurations.each do |configuration| %>
+    <div class="ultra-settings-configuration-summary">
+      <a
+        href="#<%= html_escape(configuration.class.name) %>"
+        class="ultra-settings-configuration-title"
+      >
+        <%= html_escape(configuration.class.name) %>
+      </a>
+
+      <p><%= html_escape(configuration.class.description) %></p>
+    </div>
+  <% end %>
+</div>

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/_select_menu.html.erb

@@ -0,0 +1,53 @@
+<div class="ultra-settings-dropdown" id="config-dropdown">
+  <button
+    type="button"
+    class="ultra-settings-dropdown-button"
+    id="config-dropdown-button"
+  >
+    Select Configuration
+  </button>
+
+  <div
+    class="ultra-settings-dropdown-menu"
+    id="config-dropdown-menu"
+    style="display: none;"
+  >
+    <div class="ultra-settings-search-container">
+      <input
+        type="text"
+        id="config-search"
+        placeholder="Search..."
+        autocomplete="off"
+      >
+    </div>
+
+    <ul class="ultra-settings-dropdown-list" id="config-list">
+      <% configurations.each do |config| %>
+        <% config_text = [
+            config.class.name,
+            config.class.description
+          ]
+          config.class.fields.each do |field|
+            config_text << field.name
+            config_text << field.description
+            config_text << field.env_var
+            config_text << field.runtime_setting
+          end
+          search_text = config_text.compact.join(" ").downcase %>
+
+        <li
+          class="ultra-settings-dropdown-item"
+          data-value="config-<%= html_escape(config.class.name) %>"
+          data-label="<%= html_escape(config.class.name) %>"
+          data-search="<%= html_escape(search_text) %>"
+        >
+          <span class="ultra-settings-check-icon"></span>
+
+          <span class="ultra-settings-config-name">
+            <%= html_escape(config.class.name) %>
+          </span>
+        </li>
+      <% end %>
+    </ul>
+  </div>
+</div>