const_conf 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b76ad430877943dee52a91ac10544d95e84ce65894b6b261fd00804c1a98bb8f
-  data.tar.gz: 93a117220a737ac347e37aa7c527aaa631119c68536ce773e69a6caea15c6402
+  metadata.gz: 733e481acb2879393f627bb74c310b0fd796471fb5c80c09bfb5c7e78fc961c8
+  data.tar.gz: 5870ede1708a4b3dd2e098f9086fa73d6b98783126368227e55c3ee583e94cb4
 SHA512:
-  metadata.gz: 16bad82d96bf596c527a06fb9b5e957586d2deed54f0ce6a4ed08c65cd9f2ab17364a47e98dad8f335cd43e07cd7899b75781338cd7e789d0174ad2fcbb93df9
-  data.tar.gz: cd453d85cb6c326264d038954ffd4f8d4b6baabb98e5658d36df533b12b956b2911c2e179dd5aef0bf8a2bb274ec5277d9c54770c232e768bac493baa54a37f6
+  metadata.gz: 240af1e8ed2bcc9ca5bee46abfd1f2124c4157ed7b613873dfe14b9d79f72392670bfa9176d6260a4616594fb78c34e40107a72d190b560eb2797e177047110a
+  data.tar.gz: 2ffdc43bba110607f565689e2c996431801102df9ea03cdba534288048b59545afc7f653ff94cd960a6b7972f9f76ce31b1674799b398facb705e60b6886aef1

data/CHANGES.md

@@ -1,5 +1,27 @@
 # Changes
 
+## 2026-07-20 v0.8.0
+
+### Changed
+
+- Enhanced `ConstConf::JSONPlugin` API:
+    - Overloaded `ConstConf::JSONPlugin#json` to function as both a file loader
+      and a decoder factory returning a lambda.
+    - Introduced `ConstConf::JSONPlugin::JSONConfig` to prevent arbitrary class
+      materialization by stripping `'json_class'` during serialization.
+- Updated documentation in `README.md` regarding the dual-mode behavior of
+  `JSONPlugin`.
+- Fixed documentation assertions in `spec/const_conf_spec.rb` for the header
+  `"## ConstConf settings via environment variables"`.
+- Reorganized tests in `spec/const_conf/json_plugin_spec.rb` into file and
+  string contexts to verify the new `#json` API.
+
+### Dependencies
+
+- Updated `simplecov` to **1.0**.
+- Updated `rubygems_version` to **4.0.16**.
+- Updated `gem_hadar` to **2.17.1**.
+
 ## 2026-01-28 v0.7.0
 
 - Updated documentation method to improve ConstConf settings output

data/README.md

@@ -290,17 +290,23 @@ end
 
 #### JSONPlugin
 
-Enables JSON-based configuration through the `json()` method:
+Enables JSON-based configuration through the `json()` method, which acts as
+both a file loader and a decoding factory.
 
 ```ruby
 CONFIG = set do
+  description 'JSON Configuration'
+  # Load from a JSON file as default
   default json('config.json')
-  # or with custom object class:
-  # default json('config.json', object_class: MyCustomClass)
-  …
+  
+  # Decode an environment variable JSON string into a stable object
+  decode json
 end
 ```
 
+The `json` method uses a custom `JSONConfig` class to ensure stability and
+prevent arbitrary Ruby class instantiation during deserialization.
+
 #### YAMLPlugin
 
 Enables YAML-based configuration through the `yaml()` method:
@@ -877,6 +883,58 @@ AppConfig.view
 AppConfig::DATABASE_URL!.view
 ```
 
+## Automating Configuration Documentation
+
+Because `ConstConf` provides a comprehensive visual representation of your
+settings via `.view`, it is highly recommended to export this view to a
+markdown file and commit it to your repository. This ensures that all team
+members have an up-to-date reference of required environment variables without
+needing to run the application.
+
+### 1. Create a Rake Task
+
+First, define a rake task to export the configuration documentation. Replace
+`AppConfig` with the name of your configuration module and choose a destination
+path for the markdown file:
+
+```ruby
+# lib/tasks/doc.rake
+namespace :doc do
+  desc 'Generate ConstConf configuration documentation'
+  task :const_conf do
+    # This assumes AppConfig is your module including ConstConf
+    File.write('config/CONFIG_DOCS.md') do
+      AppConfig.view # or AppConfig.documentation if you have a helper method
+    end
+  end
+end
+```
+
+### 2. Automate with a Git Hook
+
+To ensure the documentation never goes stale, you can use a Git `pre-commit`
+hook to regenerate the file whenever your configuration definition changes.
+
+Add the following to `.git/hooks/pre-commit`:
+
+```bash
+#!/usr/bin/env bash
+
+# Regenerate config docs only if the configuration file changed
+if ! git diff --quiet HEAD -- config/app_config.rb
+then
+  echo "Configuration changed – regenerating documentation..."
+  bundle exec rake doc:const_conf
+  git add config/CONFIG_DOCS.md
+fi
+
+exit 0
+```
+
+This workflow transforms your configuration DSL into a living document,
+significantly reducing onboarding friction for new developers joining the
+project. ✨
+
 ## Download
 
 The homepage of this library is located at

data/Rakefile

@@ -38,7 +38,7 @@ GemHadar do
   development_dependency 'debug'
   development_dependency 'rspec',         '~> 3.13'
   development_dependency 'context_spook', '~> 0.4'
-  development_dependency 'simplecov',     '~> 0.22'
+  development_dependency 'simplecov',     '~> 1.0'
   development_dependency 'all_images',    '>= 0.12'
 
   licenses << 'MIT'

data/const_conf.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: const_conf 0.7.0 ruby lib
+# stub: const_conf 0.8.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "const_conf".freeze
-  s.version = "0.7.0".freeze
+  s.version = "0.8.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -17,17 +17,17 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "ConstConf - Clean DSL for config settings with validation and Rails integration".freeze, "--main".freeze, "README.md".freeze]
   s.required_ruby_version = Gem::Requirement.new(">= 3.2".freeze)
-  s.rubygems_version = "4.0.3".freeze
+  s.rubygems_version = "4.0.16".freeze
   s.summary = "Clean DSL for config settings with validation and Rails integration".freeze
   s.test_files = ["spec/const_conf/dir_plugin_spec.rb".freeze, "spec/const_conf/env_dir_extension_spec.rb".freeze, "spec/const_conf/file_plugin_spec.rb".freeze, "spec/const_conf/json_plugin_spec.rb".freeze, "spec/const_conf/setting_accessor_spec.rb".freeze, "spec/const_conf/setting_spec.rb".freeze, "spec/const_conf/tree_spec.rb".freeze, "spec/const_conf/yaml_plugin_spec.rb".freeze, "spec/const_conf_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.17.0".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.17.1".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<rspec>.freeze, ["~> 3.13".freeze])
   s.add_development_dependency(%q<context_spook>.freeze, ["~> 0.4".freeze])
-  s.add_development_dependency(%q<simplecov>.freeze, ["~> 0.22".freeze])
+  s.add_development_dependency(%q<simplecov>.freeze, ["~> 1.0".freeze])
   s.add_development_dependency(%q<all_images>.freeze, [">= 0.12".freeze])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.43".freeze])
   s.add_runtime_dependency(%q<json>.freeze, ["~> 2.0".freeze])

data/lib/const_conf/json_plugin.rb

@@ -1,37 +1,60 @@
 require 'json'
 
-# A module that provides functionality for reading and parsing JSON file
-# contents as configuration values.
+# A module that provides functionality for loading JSON files or parsing
+# JSON strings as configuration values.
 #
 # The JSONPlugin module extends the ConstConf::Setting class to enable
-# configuration settings that are sourced from JSON files. This allows for
-# structured configuration data to be loaded from files and used within the
-# application's configuration system, supporting both standard JSON parsing and
-# environment-specific configuration loading.
+# configuration settings that are either sourced from JSON files on disk
+# or decoded from JSON-formatted environment variables. It ensures a stable,
+# polymorphic representation by using the {ConstConf::JSONPlugin::JSONConfig}
+# class for all parsed objects.
 module ConstConf::JSONPlugin
-  # Reads and parses a JSON file, optionally with environment-specific loading
+  # JSONConfig - Custom JSON object class for config values
   #
-  # This method attempts to read and parse a JSON file at the specified path.
-  # It supports environment-specific configuration loading when the env
-  # parameter is provided. The method uses thread synchronization to ensure
-  # safe access to the ComplexConfig provider.
+  # Rejects 'json_class' during serialization to prevent forcing concrete
+  # class re-materialization on deserialization. Useful for polymorphic
+  # configuration handling.
+  class JSONConfig < JSON::GenericObject
+    # as_json - Serialize hash without metadata keys
+    # @return [Hash] Hash representation excluding json_class keys
+    def as_json(*a)
+      super.reject { _1 == 'json_class' }
+    end
+  end
+
+  # Provides JSON loading or decoding logic based on the presence of a path.
+  #
+  # === As a Loader (Path provided)
+  # When a +path+ is given, it reads the file from the filesystem and parses
+  # its content into a {JSONConfig} object.
+  #
+  # === As a Factory (No path provided)
+  # When called without arguments, it returns a Proc that can be used in
+  # a +decode+ block to parse JSON strings (e.g., from environment variables).
   #
-  # @param path [String] the filesystem path to the JSON file to be read
-  # @param required [Boolean] whether the file is required to exist, defaults to false
+  # @param path [String, nil] the filesystem path to the JSON file; if omitted,
+  #   a decoder Proc is returned instead.
+  # @param required [Boolean] whether the file must exist (only applicable
+  #   when +path+ is provided), defaults to false.
+  # @param object_class [Class] the class used for parsing JSON objects,
+  #   defaults to {ConstConf::JSONPlugin::JSONConfig}.
   #
-  # @return [Object, nil] the parsed JSON content as a Ruby object, or nil if
-  # the file doesn't exist and required is false
+  # @return [JSONConfig, Proc, nil] returns a parsed {JSONConfig} (or nil if
+  #   missing and not required) when +path+ is provided; otherwise, returns a
+  #   Proc for decoding.
   #
   # @raise [ConstConf::RequiredValueNotConfigured] if the file does not exist
-  # and required is true
-  # @raise [ConstConf::RequiredValueNotConfigured] if env is true and RAILS_ENV
-  # is not set and no explicit environment is provided
-  def json(path, required: false, object_class: JSON::GenericObject)
-    if File.exist?(path)
-      JSON.load_file(path, object_class:)
-    elsif required
-      raise ConstConf::RequiredValueNotConfigured,
-        "JSON file required at path #{path.to_s.inspect}"
+  #   and +required+ is true.
+  def json(path = nil, required: false, object_class: JSONConfig)
+    if path
+      if File.exist?(path)
+        JSON.load_file(path, object_class:)
+      elsif required
+        raise ConstConf::RequiredValueNotConfigured,
+          "JSON file required at path #{path.to_s.inspect}"
+      end
+    else
+      -> value { JSON.parse(value, object_class:) unless value.nil? }
     end
   end
 end

data/lib/const_conf/version.rb

@@ -1,6 +1,6 @@
 module ConstConf
   # ConstConf version
-  VERSION         = '0.7.0'
+  VERSION         = '0.8.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/spec/const_conf/json_plugin_spec.rb

@@ -1,63 +1,120 @@
 require 'spec_helper'
 
 describe ConstConf::JSONPlugin do
-  let(:json_file) { asset('config.json') }
+  context 'with file' do
+    let(:json_file) { asset('config.json') }
 
-  describe '#json' do
-    context 'when file exists' do
-      it 'reads and parses JSON content as a hash' do
-        instance = double('Config').extend(described_class)
-        result = instance.json(json_file)
-        expect(result.hello).to eq 'world'
+    describe '#json' do
+      context 'when file exists' do
+        it 'reads and parses JSON content as a hash' do
+          instance = double('Config').extend(described_class)
+          result = instance.json(json_file)
+          expect(result.hello).to eq 'world'
+        end
+
+        it 'handles JSON with custom object_class' do
+          instance = double('Config').extend(described_class)
+          foobar_class = Class.new(JSON::GenericObject)
+          result = instance.json(json_file, object_class: foobar_class)
+          expect(result).to be_a(foobar_class)
+        end
       end
 
-      it 'handles JSON with custom object_class' do
-        instance = double('Config').extend(described_class)
-        foobar_class = Class.new(JSON::GenericObject)
-        result = instance.json(json_file, object_class: foobar_class)
-        expect(result).to be_a(foobar_class)
+      context 'when file does not exist' do
+        let(:nonexistent_file) { asset('nonexistent.json') }
+
+        it 'returns nil when file does not exist and required is false' do
+          instance = double('Config').extend(described_class)
+          result = instance.json(nonexistent_file, required: false)
+          expect(result).to be_nil
+        end
+
+        it 'raises RequiredValueNotConfigured when file is required and does not exist' do
+          instance = double('Config').extend(described_class)
+          expect {
+            instance.json(nonexistent_file, required: true)
+          }.to raise_error(ConstConf::RequiredValueNotConfigured)
+        end
+      end
+
+      context 'with custom configuration module' do
+        before do
+          eval %{
+            if Object.const_defined?(:ConstConfTestModuleWithJSON)
+              Object.send(:remove_const, :ConstConfTestModuleWithJSON)
+            end
+            module ::ConstConfTestModuleWithJSON
+              include ConstConf
+              plugin ConstConf::JSONPlugin
+
+              description 'Module with JSONPlugin'
+
+              CONFIG_VALUE = set do
+                description 'Configuration from JSON file'
+                default json("#{json_file}")
+              end
+            end
+          }
+        end
+
+        it 'can be used in a ConstConf module' do
+          expect(ConstConfTestModuleWithJSON::CONFIG_VALUE.hello).to eq 'world'
+        end
       end
     end
+  end
+
+  context 'with string frome env var' do
+    describe '#json' do
+      let(:instance) { double('Config').extend(described_class) }
 
-    context 'when file does not exist' do
-      let(:nonexistent_file) { asset('nonexistent.json') }
+      it 'returns a lambda that parses JSON strings into JSONConfig objects' do
+        decoder = instance.json
+        expect(decoder).to be_a Proc
 
-      it 'returns nil when file does not exist and required is false' do
-        instance = double('Config').extend(described_class)
-        result = instance.json(nonexistent_file, required: false)
-        expect(result).to be_nil
+        json_string = '{"hello": "world"}'
+        result = decoder.(json_string)
+
+        expect(result).to be_a ConstConf::JSONPlugin::JSONConfig
+        expect(result.hello).to eq 'world'
       end
 
-      it 'raises RequiredValueNotConfigured when file is required and does not exist' do
-        instance = double('Config').extend(described_class)
-        expect {
-          instance.json(nonexistent_file, required: true)
-        }.to raise_error(ConstConf::RequiredValueNotConfigured)
+      it 'returns nil when the input value is nil' do
+        decoder = instance.json
+        expect(decoder.(nil)).to be_nil
       end
-    end
 
-    context 'with custom configuration module' do
-      before do
-        eval %{
-          if Object.const_defined?(:ConstConfTestModuleWithJSON)
-            Object.send(:remove_const, :ConstConfTestModuleWithJSON)
+      context 'integration with ConstConf settings' do
+        let :build_config do
+          eval %{
+          if Object.const_defined?(:ConstConfTestModuleWithJSONDecode)
+            Object.send(:remove_const, :ConstConfTestModuleWithJSONDecode)
           end
-          module ::ConstConfTestModuleWithJSON
+          module ::ConstConfTestModuleWithJSONDecode
             include ConstConf
             plugin ConstConf::JSONPlugin
+            prefix 'TEST'
+            description 'Test module for JSON decode'
 
-            description 'Module with JSONPlugin'
-
-            CONFIG_VALUE = set do
-              description 'Configuration from JSON file'
-              default json("#{json_file}")
+            JSON_SETTING = set do
+              description 'Setting decoded from JSON string'
+              default '{"foo": "bar"}'
+              decode json
             end
           end
-        }
-      end
+          }
+        end
+
+        it 'handles default JSON strings' do
+          build_config
+          expect(ConstConfTestModuleWithJSONDecode::JSON_SETTING.foo).to eq 'bar'
+        end
 
-      it 'can be used in a ConstConf module' do
-        expect(ConstConfTestModuleWithJSON::CONFIG_VALUE.hello).to eq 'world'
+        it 'handles environment variable overrides with JSON strings' do
+          ENV['TEST_JSON_SETTING'] = '{"foo": "env_value"}'
+          build_config
+          expect(ConstConfTestModuleWithJSONDecode::JSON_SETTING.foo).to eq 'env_value'
+        end
       end
     end
   end

data/spec/const_conf_spec.rb

@@ -271,7 +271,7 @@ describe ConstConf do
           it 'generates markdown documentation' do
             doc = TestConstConf.documentation
             expect(doc).to be_a String
-            expect(doc).to include('## Environment variables')
+            expect(doc).to include('## ConstConf settings via environment variables')
             expect(doc).to include('`TEST_CONST_CONF_TEST`')
             expect(doc).to match(/description.*?test/)
             expect(doc).to match(/default.*?bar/)
@@ -283,7 +283,7 @@ describe ConstConf do
 
             expect(result).to be_a StringIO
             doc = io.string
-            expect(doc).to include('## Environment variables')
+            expect(doc).to include('## ConstConf settings via environment variables')
             expect(doc).to include('`TEST_CONST_CONF_TEST`')
             expect(doc).to match(/description.*?test/)
             expect(doc).to match(/default.*?bar/)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: const_conf
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.17.0
+        version: 2.17.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.17.0
+        version: 2.17.1
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: all_images
   requirement: !ruby/object:Gem::Requirement
@@ -229,7 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Clean DSL for config settings with validation and Rails integration
 test_files: