contextual_config 0.1.0

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/contextual_config.gemspec

@@ -0,0 +1,43 @@
+require_relative 'lib/contextual_config/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'contextual_config'
+  spec.version       = ContextualConfig::VERSION
+  spec.authors       = ['bazinga012']
+  spec.email         = ['vishal18593@gmail.com']
+
+  spec.summary       = 'A Ruby gem for context-aware configuration management'
+  spec.description   = 'ContextualConfig provides a flexible framework for managing configurations that can be applied based on contextual rules, priorities, and scoping. Perfect for complex applications requiring dynamic configuration resolution.'
+  spec.homepage      = 'https://github.com/bazinga012/contextual_config'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0' # rubocop:disable Gemspec/RequiredRubyVersion
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/bazinga012/contextual_config'
+  spec.metadata['changelog_uri'] = 'https://github.com/bazinga012/contextual_config/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Dependencies
+  spec.add_dependency('activerecord', '>= 6.0')
+  spec.add_dependency('activesupport', '>= 6.0')
+  spec.add_dependency('json-schema', '~> 5.1')
+
+  # Development dependencies
+  spec.add_development_dependency('rails', '>= 6.0')
+  spec.add_development_dependency('rspec', '~> 3.0')
+  spec.add_development_dependency('rubocop', '~> 1.0')
+  spec.add_development_dependency('rubocop-rails', '~> 2.0')
+  spec.add_development_dependency('rubocop-rspec', '~> 3.0')
+  spec.add_development_dependency('sqlite3', '>= 2.1')
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/contextual_config/concern/configurable.rb

@@ -0,0 +1,112 @@
+require 'active_support/concern'
+
+module ContextualConfig
+  module Concern
+    module Configurable
+      extend ActiveSupport::Concern
+
+      # --- Class Methods ---
+      included do
+        # --- Column Expectations ---
+        # This concern implicitly expects the including model's table to have columns like:
+        # - key:string
+        # - config_data:jsonb
+        # - scoping_rules:jsonb
+        # - priority:integer (default should be a higher number for lower priority)
+        # - is_active:boolean (default should be true)
+        # - type:string (if STI is to be used on the including model)
+        # - created_at:datetime
+        # - updated_at:datetime
+
+        # --- Validations ---
+        # Ensures that a 'key' is always present for any configuration.
+        validates :key, presence: true
+
+        # NOTE: Uniqueness validation for 'key' is often more complex.
+        # It might need to be scoped by 'type' (if using STI directly on the including model)
+        # or by other module-specific identifiers if this concern is used by various
+        # top-level configuration models in different tables.
+        # Example for STI:
+        #   validates :key, uniqueness: { scope: :type, message: "must be unique within its type" }
+        # This specific validation is commented out here as its exact nature depends on how
+        # the including model is structured (STI parent vs. standalone model).
+        # It's often better to add this uniqueness validation directly in the consuming model
+        # where the scope is clearer.
+
+        # Ensures 'is_active' is either true or false.
+        validates :is_active, inclusion: { in: [true, false], message: 'is not included in the list' }
+
+        # Ensures 'priority' is an integer.
+        validates :priority, numericality: { only_integer: true, message: 'is not a number' }
+
+        # --- Scopes ---
+
+        # Scope to retrieve only active configurations.
+        # Usage: YourModel.active
+        scope :active, -> { where(is_active: true) }
+
+        # Scope to order configurations by priority.
+        # Lower numbers indicate higher priority. Secondary sort by ID for deterministic ordering.
+        # Usage: YourModel.order_by_priority
+        scope :order_by_priority, -> { order(priority: :asc, id: :asc) } # 'asc' for priority means 1 is higher than 10
+
+        # --- Default Values ---
+        # It's generally recommended to set database-level defaults for `is_active` (true)
+        # and `priority` (e.g., a high number like 100 for low priority).
+        # If not set at DB level, you can use `after_initialize` here, but DB defaults are safer.
+        after_initialize :set_default_values, if: :new_record?
+      end
+
+      # --- Instance Methods ---
+
+      private
+
+      def set_default_values
+        # Only set defaults if the model is completely new (not loaded from DB and no explicit values set)
+        if new_record? && !attributes_before_type_cast.key?('is_active')
+          self.is_active = true
+        end
+        
+        # Override database default priority with module-specific priority if available
+        set_module_default_priority if should_use_module_default_priority?
+      end
+
+      # Check if we should use module default priority
+      def should_use_module_default_priority?
+        # Use module default if:
+        # 1. Priority is nil, OR
+        # 2. Priority equals the database default AND we have a module config with different default
+        return true if priority.nil?
+
+        db_default = self.class.column_defaults['priority']&.to_i
+        module_config = ContextualConfig.registry.configs_for_model(self.class).first
+
+        priority == db_default && module_config && module_config.default_priority != db_default
+      end
+
+      # Set priority from module configuration or global configuration
+      def set_module_default_priority
+        # Try to get priority from module registry
+        module_config = ContextualConfig.registry.configs_for_model(self.class).first
+        self.priority = if module_config
+                          module_config.default_priority
+                        else
+                          # Fall back to global configuration
+                          ContextualConfig.configuration.default_priority
+                        end
+      end
+
+      public
+
+      # Helper to quickly check if a configuration is currently active
+      def active?
+        is_active
+      end
+
+      # Get the module configuration for this model if available
+      def module_configuration
+        ContextualConfig.registry.configs_for_model(self.class).first
+      end
+    end
+  end
+end

data/lib/contextual_config/concern/lookupable.rb

@@ -0,0 +1,129 @@
+require 'active_support/concern'
+require 'digest'
+
+module ContextualConfig
+  module Concern
+    module Lookupable
+      extend ActiveSupport::Concern
+
+      # --- Class Methods ---
+      module ClassMethods
+        # Finds the single most applicable configuration based on a key and context.
+        #
+        # @param key [String, Symbol] The specific key of the configuration to look for.
+        # @param context [Hash] A hash representing the current context (e.g., { employee_id: 'x', current_date: Date.today }).
+        # @param fetch_all_of_key [Boolean] If true, fetches all configs with the given key before matching.
+        #                                   If false (default), assumes key is unique within the relevant scope (e.g., STI type)
+        #                                   and fetches only those.
+        # @return [ActiveRecord::Base, nil] The instance of the best matching configuration, or nil if no match.
+        def find_applicable_config(key:, context:, fetch_all_of_key: false) # rubocop:disable Lint/UnusedMethodArgument
+          # Check cache first if enabled
+          if ContextualConfig.configuration.cache_enabled?
+            begin
+              cache_key = generate_cache_key(key, context)
+              cached_result = ContextualConfig.configuration.cache_store.read(cache_key)
+              if cached_result
+                log_lookup_attempt(key, context, 'cache_hit')
+                return cached_result
+              end
+            rescue => e
+              # Log cache error but continue with database lookup
+              log_cache_error('read', e)
+            end
+          end
+
+          # `self` here refers to the specific class this method is called on
+          # (e.g., Finance::TaxConfig or a more generic YourTeam::Configuration).
+
+          # Start with active configurations, ordered by priority (higher priority first).
+          # The `Configurable` concern is expected to provide `active` and `order_by_priority` scopes.
+          unless self.respond_to?(:active) && self.respond_to?(:order_by_priority)
+            raise(NoMethodError, "#{self.name} must include ContextualConfig::Concern::Configurable to use Lookupable.")
+          end
+
+          log_lookup_attempt(key, context, 'database_lookup')
+
+          candidates = self.active.where(key: key.to_s).order_by_priority
+
+          # Delegate to the ContextualMatcher service to find the best match from the candidates.
+          # The service will handle the logic of iterating through candidates, evaluating scoping_rules,
+          # calculating specificity, and applying priority rules.
+          result = ContextualConfig::Services::ContextualMatcher.find_best_match(
+            candidates: candidates,
+            context: context
+          )
+
+          # Cache the result if caching is enabled
+          if ContextualConfig.configuration.cache_enabled? && result
+            begin
+              cache_key = generate_cache_key(key, context)
+              ContextualConfig.configuration.cache_store.write(
+                cache_key,
+                result,
+                expires_in: ContextualConfig.configuration.cache_ttl
+              )
+              log_lookup_attempt(key, context, 'cache_stored')
+            rescue => e
+              # Log cache error but don't fail the operation
+              log_cache_error('write', e)
+            end
+          end
+
+          result
+          # Return the full record, the caller can decide to use .config_data or other attributes
+        end
+
+        # Finds all configurations that apply to a given context, without filtering by a specific key.
+        # Useful if multiple configurations of the same type (but different keys or scopes) can apply simultaneously,
+        # or if you want to see all potentially relevant configurations.
+        #
+        # @param context [Hash] A hash representing the current context.
+        # @return [Array<ActiveRecord::Base>] An array of all matching configuration instances, ordered by priority.
+        def find_all_applicable_configs(context:)
+          unless self.respond_to?(:active) && self.respond_to?(:order_by_priority)
+            raise(NoMethodError, "#{self.name} must include ContextualConfig::Concern::Configurable to use Lookupable.")
+          end
+
+          log_lookup_attempt('all_configs', context, 'all_configs_lookup')
+
+          # Fetch all active configurations of this type, ordered by priority.
+          all_candidates = self.active.order_by_priority
+
+          # Delegate to the ContextualMatcher service.
+          ContextualConfig::Services::ContextualMatcher.find_all_matches(
+            candidates: all_candidates,
+            context: context
+          )
+        end
+
+        private
+
+        # Generate cache key for configuration lookup
+        def generate_cache_key(key, context)
+          context_hash = context.is_a?(Hash) ? context.sort.to_h : context
+          "contextual_config:#{self.name}:#{key}:#{Digest::MD5.hexdigest(context_hash.to_s)}"
+        end
+
+        # Log configuration lookup attempts
+        def log_lookup_attempt(key, context, operation)
+          return unless ContextualConfig.configuration.enable_logging?
+
+          logger = ContextualConfig.configuration.effective_logger
+          logger.info(
+            "ContextualConfig::Lookupable: #{operation} for #{self.name} - Key: #{key}, Context: #{context}"
+          )
+        end
+
+        # Log cache errors
+        def log_cache_error(operation, error)
+          return unless ContextualConfig.configuration.enable_logging?
+
+          logger = ContextualConfig.configuration.effective_logger
+          logger.warn(
+            "ContextualConfig::Lookupable: Cache #{operation} error - #{error.class}: #{error.message}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/contextual_config/concern/schema_driven_validation.rb

@@ -0,0 +1,152 @@
+require 'active_support/concern'
+require 'json-schema'
+
+module ContextualConfig
+  module Concern
+    module SchemaDrivenValidation
+      extend ActiveSupport::Concern
+
+      included do
+        # --- Validation Hooks ---
+        # These methods will be called during the ActiveRecord validation lifecycle (e.g., on save, valid?).
+        validate :validate_against_config_data_schema, if: -> { config_data.present? }
+        validate :validate_against_scoping_rules_schema, if: -> { scoping_rules.present? }
+        # We only run validation if the respective JSONB field has data.
+        # If it's blank/nil, we assume it's intentionally so, and schema validation isn't applicable,
+        # unless the schema itself marks the root object as required with specific properties.
+      end
+
+      # --- Instance Methods for Validation ---
+
+      private
+
+      # Validates the `config_data` attribute against its resolved JSON schema.
+      def validate_against_config_data_schema
+        # Check if validation is enabled for this model's module(s)
+        return unless validation_enabled_for_model?
+
+        schema = self.class.resolve_config_data_schema(self) # Pass instance if schema depends on instance state
+
+        # Try to get schema from module registry if not provided by class
+        if schema.nil?
+          module_config = find_module_config_for_model
+          schema = module_config&.load_schema
+        end
+
+        # If no schema is defined for this specific class/instance, we can choose to:
+        # 1. Silently skip validation (as done here by returning if schema is nil).
+        # 2. Raise an error indicating a missing schema definition.
+        # 3. Add a model error.
+        # Skipping allows for flexibility where some types might not require strict schema validation.
+        return unless schema
+
+        begin
+          # Using fully_validate to get an array of all errors.
+          errors_found = JSON::Validator.fully_validate(schema, self.config_data, strict: false, insert_defaults: false)
+          if errors_found.any?
+            errors_found.each do |error_message|
+              # Add a somewhat generic error. More specific parsing of error_message could provide better field-level errors.
+              errors.add(:config_data, "is invalid - #{error_message}")
+            end
+            # Log validation failures
+            log_schema_error('config_data', "Validation failed: #{errors_found.join('; ')}")
+          end
+        rescue JSON::Schema::SchemaError => e
+          # This rescue is for when the schema itself is invalid, which is a development-time problem.
+          errors.add(:base, "Config data JSON schema for #{self.class.name} is invalid: #{e.message}")
+          log_schema_error('config_data', e.message)
+        end
+      end
+
+      # Validates the `scoping_rules` attribute against its resolved JSON schema.
+      def validate_against_scoping_rules_schema
+        # Check if validation is enabled for this model's module(s)
+        return unless validation_enabled_for_model?
+
+        schema = self.class.resolve_scoping_rules_schema(self) # Pass instance
+        return unless schema # Skip if no schema defined
+
+        begin
+          errors_found = JSON::Validator.fully_validate(schema, self.scoping_rules, strict: false, insert_defaults: false)
+          if errors_found.any?
+            errors_found.each do |error_message|
+              errors.add(:scoping_rules, "is invalid - #{error_message}")
+            end
+          end
+        rescue JSON::Schema::SchemaError => e
+          errors.add(:base, "Scoping rules JSON schema for #{self.class.name} is invalid: #{e.message}")
+          log_schema_error('scoping_rules', e.message)
+        end
+      end
+
+      # Check if validation is enabled for this model in any registered module
+      def validation_enabled_for_model?
+        # Check module-specific validation settings first
+        module_config = find_module_config_for_model
+        return module_config.validation_enabled? if module_config
+
+        # Default to enabled if no module configuration found
+        true
+      end
+
+      # Find module configuration for this model
+      def find_module_config_for_model
+        ContextualConfig.registry.configs_for_model(self.class).first
+      end
+
+      # Log schema validation errors using configuration logger
+      def log_schema_error(field_name, error_message)
+        return unless ContextualConfig.configuration.enable_logging?
+
+        logger = ContextualConfig.configuration.effective_logger
+        logger.error("JSON Schema Error for #{self.class.name} (#{field_name}): #{error_message}")
+      end
+
+      # --- Class Methods for Schema Resolution ---
+      module ClassMethods
+        # These methods are expected to be implemented by any class that includes
+        # this concern (e.g., a team's base configuration model or an STI subclass).
+        # They are responsible for loading and returning the appropriate JSON schema
+        # for `config_data` and `scoping_rules` for instances of that class.
+        #
+        # The `instance` parameter is optional but can be useful if the schema
+        # itself needs to vary based on some attribute of the specific instance
+        # being validated (though this is a more advanced use case).
+
+        # @param instance [ActiveRecord::Base, nil] The instance being validated (optional).
+        # @return [Hash, nil] The JSON schema for config_data, or nil if no schema.
+        def resolve_config_data_schema(_instance = nil)
+          # Try to get schema from module registry first
+          module_config = ContextualConfig.registry.configs_for_model(self).first
+          schema = module_config&.load_schema if module_config
+          return schema if schema
+
+          # Default implementation: logs a warning and returns nil (no validation).
+          # Consuming classes (or their STI parents/children) MUST override this
+          # to provide their specific schemas.
+          # Example override in consuming class:
+          #   @_config_data_schema ||= JSON.parse(File.read(Rails.root.join('config/schemas/my_model/config_data.json')))
+          log_missing_schema_warning('config_data')
+          nil
+        end
+
+        # @param instance [ActiveRecord::Base, nil] The instance being validated (optional).
+        # @return [Hash, nil] The JSON schema for scoping_rules, or nil if no schema.
+        def resolve_scoping_rules_schema(_instance = nil)
+          log_missing_schema_warning('scoping_rules')
+          nil
+        end
+
+        private
+
+        # Log missing schema warnings using configuration logger
+        def log_missing_schema_warning(field_name)
+          return unless ContextualConfig.configuration.enable_logging?
+
+          logger = ContextualConfig.configuration.effective_logger
+          logger.warn("WARN: JSON schema for :#{field_name} not defined for #{name}. Skipping validation.")
+        end
+      end
+    end
+  end
+end

data/lib/contextual_config/configuration.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module ContextualConfig
+  # Configuration class for gem-wide settings
+  class Configuration
+    attr_accessor :cache_enabled, :cache_ttl, :cache_store, :default_priority,
+                  :enable_logging, :logger, :timing_evaluation_enabled
+
+    def initialize
+      @cache_enabled = false
+      @cache_ttl = 300 # 5 minutes in seconds
+      @cache_store = nil
+      @default_priority = 100
+      @enable_logging = false
+      @logger = nil
+      @timing_evaluation_enabled = true
+    end
+
+    # Cache configuration
+    def cache_enabled?
+      @cache_enabled && cache_store_available?
+    end
+
+    def cache_store_available?
+      @cache_store.respond_to?(:read) && @cache_store.respond_to?(:write)
+    end
+
+    # Logging configuration
+    def enable_logging?
+      @enable_logging && logger_available?
+    end
+
+    def logger_available?
+      @logger.respond_to?(:info) && @logger.respond_to?(:error)
+    end
+
+    # Get effective logger
+    def effective_logger
+      return @logger if logger_available?
+      return Rails.logger if defined?(Rails) && Rails.logger
+
+      Logger.new($stdout)
+    end
+
+    # Timing evaluation configuration
+    def timing_evaluation_enabled?
+      @timing_evaluation_enabled
+    end
+
+    # Validate configuration
+    def validate!
+      if @cache_enabled && !cache_store_available?
+        raise(ConfigurationError, 'Cache is enabled but cache_store is not properly configured')
+      end
+
+      if cache_ttl <= 0
+        raise(ConfigurationError, 'cache_ttl must be a positive number')
+      end
+
+      if default_priority.negative?
+        raise(ConfigurationError, 'default_priority must be non-negative')
+      end
+
+      true
+    end
+
+    # Reset to defaults
+    def reset!
+      initialize
+    end
+  end
+
+  # Configuration-specific error
+  class ConfigurationError < Error; end
+end

data/lib/contextual_config/generators.rb

@@ -0,0 +1,4 @@
+require 'rails/generators'
+
+# Load all generators
+Dir[File.expand_path('generators/**/*_generator.rb', __dir__)].each { |f| require f }

data/lib/contextual_config/module_registry.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ContextualConfig
+  # Registry for managing different modules that use ContextualConfig
+  class ModuleRegistry
+    def initialize
+      @modules = {}
+    end
+
+    # Register a module with its configuration
+    def register(module_name, &block)
+      module_sym = module_name.to_sym
+      config = @modules[module_sym] || ModuleConfig.new(module_name)
+      yield(config) if block_given?
+      @modules[module_sym] = config
+      config
+    end
+
+    # Get a registered module configuration
+    def get(module_name)
+      @modules[module_name.to_sym]
+    end
+
+    # Get all registered modules
+    def all
+      @modules.dup
+    end
+
+    # Check if a module is registered
+    def registered?(module_name)
+      @modules.key?(module_name.to_sym)
+    end
+
+    # Unregister a module
+    def unregister(module_name)
+      @modules.delete(module_name.to_sym)
+    end
+
+    # Clear all registrations
+    def clear!
+      @modules.clear
+    end
+
+    # Get all module names
+    def module_names
+      @modules.keys
+    end
+
+    # Get configurations for a specific model class
+    def configs_for_model(model_class)
+      @modules.values.select { |config| config.model_class == model_class }
+    end
+
+    # Get configurations with a specific key prefix
+    def configs_with_key_prefix(prefix)
+      @modules.values.select { |config| config.key_prefix == prefix }
+    end
+  end
+
+  # Configuration for individual modules
+  class ModuleConfig
+    attr_accessor :model_class, :default_priority, :schema_file, :key_prefix,
+                  :description, :enabled, :cache_enabled, :validation_enabled
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name.to_sym
+      @model_class = nil
+      @default_priority = ContextualConfig.configuration.default_priority
+      @schema_file = nil
+      @key_prefix = name.to_s
+      @description = nil
+      @enabled = true
+      @cache_enabled = false
+      @validation_enabled = true
+    end
+
+    # Check if module is enabled
+    def enabled?
+      @enabled
+    end
+
+    # Check if validation is enabled for this module
+    def validation_enabled?
+      @validation_enabled
+    end
+
+    # Check if caching is enabled for this module
+    def cache_enabled?
+      @cache_enabled && ContextualConfig.configuration.cache_enabled?
+    end
+
+    # Load schema from file if specified
+    def load_schema
+      return nil unless schema_file && File.exist?(schema_file)
+
+      JSON.parse(File.read(schema_file))
+    rescue JSON::ParserError => e
+      raise(ConfigurationError, "Invalid JSON schema file for module #{name}: #{e.message}")
+    end
+
+    # Generate default key for this module
+    def default_key(suffix = nil)
+      parts = [key_prefix]
+      parts << suffix if suffix
+      parts.join('.')
+    end
+
+    # Validate module configuration
+    def validate!
+      if model_class && !model_class.is_a?(Class)
+        raise(ConfigurationError, "model_class must be a Class for module #{name}")
+      end
+
+      if schema_file && !File.exist?(schema_file)
+        raise(ConfigurationError, "Schema file does not exist for module #{name}: #{schema_file}")
+      end
+
+      if default_priority.negative?
+        raise(ConfigurationError, "default_priority must be non-negative for module #{name}")
+      end
+
+      true
+    end
+
+    # Convert to hash for serialization
+    def to_h
+      {
+        name: name,
+        model_class: model_class&.name,
+        default_priority: default_priority,
+        schema_file: schema_file,
+        key_prefix: key_prefix,
+        description: description,
+        enabled: enabled?,
+        cache_enabled: cache_enabled?,
+        validation_enabled: validation_enabled?
+      }
+    end
+  end
+end