contextual_config 0.1.0

data/lib/contextual_config/services/contextual_matcher.rb

@@ -0,0 +1,201 @@
+require 'date'
+
+module ContextualConfig
+  module Services
+    class ContextualMatcher
+      # --- Public Class Methods ---
+
+      # Finds the single best matching configuration record from a list of candidates.
+      # Candidates are expected to be pre-sorted by their 'priority' (higher priority first).
+      #
+      # @param candidates [ActiveRecord::Relation, Array<ActiveRecord::Base>] A collection of candidate configuration records.
+      # @param context [Hash] The current runtime context.
+      # @return [ActiveRecord::Base, nil] The best matching record, or nil if no suitable match.
+      def self.find_best_match(candidates:, context:)
+        log_matching_attempt('find_best_match', candidates.count, context)
+
+        best_match_record = nil
+        highest_specificity_score = -1 # Initialize with a value lower than any possible score
+
+        candidates.each do |candidate_record|
+          next unless candidate_record.respond_to?(:scoping_rules) # Ensure it's a configurable record
+
+          next unless matches_context?(candidate_record.scoping_rules, context)
+
+          current_specificity_score = calculate_specificity_score(candidate_record.scoping_rules, context)
+
+          # Higher specificity wins.
+          # If specificity is the same, the one encountered first wins due to pre-sorting by priority.
+          if current_specificity_score > highest_specificity_score
+            highest_specificity_score = current_specificity_score
+            best_match_record = candidate_record
+          elsif current_specificity_score == highest_specificity_score && best_match_record.nil?
+            # This case handles if the very first matching record has a specificity of 0 (e.g. global rule)
+            # and becomes the initial best_match_record.
+            best_match_record = candidate_record
+          end
+          # If current_specificity_score == highest_specificity_score and best_match_record is not nil,
+          # the existing best_match_record (which came earlier in the pre-sorted list,
+          # thus having higher or equal priority) is preferred.
+        end
+
+        log_matching_result('find_best_match', best_match_record)
+        best_match_record
+      end
+
+      # Finds all configuration records that match the given context.
+      #
+      # @param candidates [ActiveRecord::Relation, Array<ActiveRecord::Base>] A collection of candidate configuration records.
+      # @param context [Hash] The current runtime context.
+      # @return [Array<ActiveRecord::Base>] An array of all matching records, maintaining original sort order (priority).
+      def self.find_all_matches(candidates:, context:)
+        log_matching_attempt('find_all_matches', candidates.count, context)
+
+        matches = candidates.select do |candidate_record|
+          candidate_record.respond_to?(:scoping_rules) &&
+            matches_context?(candidate_record.scoping_rules, context)
+        end
+
+        log_matching_result('find_all_matches', matches)
+        matches
+      end
+
+      # --- Private Class Methods ---
+
+      # Checks if a given set of scoping_rules matches the provided context.
+      #
+      # @param scoping_rules [Hash, nil] The rules from a configuration record.
+      # @param context [Hash] The runtime context.
+      # @return [Boolean] True if all rules match or if rules are empty/nil, false otherwise.
+      def self.matches_context?(scoping_rules, context)
+        return true if scoping_rules.blank? # An empty rule set is a global match.
+
+        scoping_rules.all? do |dimension_key, rule_value|
+          dimension_sym = dimension_key.to_sym
+          context_value = context[dimension_sym]
+
+          # --- Special Handling for 'timing' Dimension ---
+          if dimension_sym == :timing
+            # Check if timing evaluation is enabled
+            if ContextualConfig.configuration.timing_evaluation_enabled?
+              evaluate_timing_rule(rule_value, context[:current_date])
+            else
+              true # Skip timing evaluation when disabled
+            end
+          # --- Add other special dimension handlers here as elif/else if ---
+          # Example:
+          # elsif dimension_sym == :employee_location_country
+          #   # Assuming rule_value is an array of allowed countries and context_value is the employee's country
+          #   evaluate_location_country_rule(rule_value, context_value)
+          else
+            # --- Default Generic Dimension Matching ---
+            # If the rule specifies a dimension, the context *must* have a value for that dimension,
+            # and the values must match.
+            # If you want to treat a missing key in context as "doesn't matter for this rule",
+            # this logic would need to change. Current logic: rule implies context must provide.
+            context.key?(dimension_sym) && context_value == rule_value
+          end
+        end
+      end
+
+      # Calculates a specificity score for a set of scoping_rules against a context.
+      # A simple score: the number of explicitly defined (and matching) dimensions in the rules.
+      #
+      # @param scoping_rules [Hash, nil] The rules from a configuration record.
+      # @param context [Hash] The runtime context (used here to ensure we only score dimensions that could match).
+      # @return [Integer] The specificity score.
+      def self.calculate_specificity_score(scoping_rules, context)
+        return 0 if scoping_rules.blank? # Global rules have the lowest specificity.
+
+        # Score is the number of rules that actively match a corresponding key in the context.
+        scoping_rules.count do |dimension_key, rule_value|
+          dimension_sym = dimension_key.to_sym
+          context_value = context[dimension_sym]
+
+          if dimension_sym == :timing
+            # Timing rule contributes to specificity if it's valid and matches
+            context.key?(:current_date) && evaluate_timing_rule(rule_value, context[:current_date])
+          else
+            # Other rules contribute if context has the key and values match
+            context.key?(dimension_sym) && context_value == rule_value
+          end
+        end
+      end
+
+      # Evaluates a 'timing' rule.
+      # Assumes rule_value is a hash like { "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD" }.
+      # Dates are inclusive. current_date must be provided in the context.
+      #
+      # @param timing_rule_value [Hash] The timing rule definition.
+      # @param current_date [Date, String, nil] The current date from the context.
+      # @return [Boolean] True if the current_date falls within the rule's range (or if range is unbounded appropriately).
+      def self.evaluate_timing_rule(timing_rule_value, current_date)
+        return false unless timing_rule_value.is_a?(Hash) # Rule must be a hash
+        return false if current_date.nil? # Context must provide current_date
+
+        begin
+          # Ensure current_date is a Date object
+          effective_current_date = current_date.is_a?(Date) ? current_date : Date.parse(current_date.to_s)
+
+          rule_start_date_str = timing_rule_value['start_date'] || timing_rule_value[:start_date]
+          rule_end_date_str   = timing_rule_value['end_date']   || timing_rule_value[:end_date]
+
+          # Parse rule dates if they exist
+          start_date = rule_start_date_str ? Date.parse(rule_start_date_str.to_s) : nil
+          end_date   = rule_end_date_str   ? Date.parse(rule_end_date_str.to_s)   : nil
+
+          # Perform checks
+          matches = true
+          matches &&= (effective_current_date >= start_date) if start_date
+          matches &&= (effective_current_date <= end_date)   if end_date
+          matches
+        rescue ArgumentError # Invalid date string
+          log_timing_error(timing_rule_value, current_date)
+          false
+        end
+      end
+
+      # Log matching attempt details
+      def self.log_matching_attempt(operation, candidate_count, context)
+        return unless ContextualConfig.configuration.enable_logging?
+
+        logger = ContextualConfig.configuration.effective_logger
+        logger.info(
+          "ContextualMatcher: #{operation} - Candidates: #{candidate_count}, Context: #{context}"
+        )
+      end
+
+      # Log matching results
+      def self.log_matching_result(operation, result)
+        return unless ContextualConfig.configuration.enable_logging?
+
+        logger = ContextualConfig.configuration.effective_logger
+        result_description = if result.is_a?(Array)
+                               "#{result.count} matches found"
+                             elsif result
+                               "Match found: #{result.key} (Priority: #{result.priority})"
+                             else
+                               'No match found'
+                             end
+
+        logger.info("ContextualMatcher: #{operation} - #{result_description}")
+      end
+
+      # Log timing rule evaluation errors
+      def self.log_timing_error(timing_rule_value, current_date)
+        return unless ContextualConfig.configuration.enable_logging?
+
+        logger = ContextualConfig.configuration.effective_logger
+        logger.warn(
+          "ContextualMatcher: Invalid date format in timing rule: #{timing_rule_value} or current_date: #{current_date}"
+        )
+      end
+
+      # Placeholder for other specific rule evaluators if needed
+      # def self.evaluate_location_country_rule(rule_value_array, context_value_string)
+      #   return false unless rule_value_array.is_a?(Array)
+      #   rule_value_array.include?(context_value_string)
+      # end
+    end
+  end
+end

data/lib/contextual_config/version.rb

@@ -0,0 +1,3 @@
+module ContextualConfig
+  VERSION = '0.1.0'.freeze
+end

data/lib/contextual_config.rb

@@ -0,0 +1,71 @@
+require_relative 'contextual_config/version'
+require 'active_support'
+require 'active_record'
+
+module ContextualConfig
+  class Error < StandardError; end
+
+  # Autoload concerns
+  autoload :Configurable, 'contextual_config/concern/configurable'
+  autoload :Lookupable, 'contextual_config/concern/lookupable'
+  autoload :SchemaDrivenValidation, 'contextual_config/concern/schema_driven_validation'
+
+  # Autoload services
+  autoload :ContextualMatcher, 'contextual_config/services/contextual_matcher'
+
+  # Autoload configuration classes
+  autoload :Configuration, 'contextual_config/configuration'
+  autoload :ModuleRegistry, 'contextual_config/module_registry'
+
+  module Concern
+    autoload :Configurable, 'contextual_config/concern/configurable'
+    autoload :Lookupable, 'contextual_config/concern/lookupable'
+    autoload :SchemaDrivenValidation, 'contextual_config/concern/schema_driven_validation'
+  end
+
+  module Services
+    autoload :ContextualMatcher, 'contextual_config/services/contextual_matcher'
+  end
+
+  class << self
+    # Global configuration for the gem
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the gem
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    # Reset configuration (useful for testing)
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Module registry access
+    def registry
+      @registry ||= ModuleRegistry.new
+    end
+
+    # Register a module
+    def register_module(module_name, &block)
+      registry.register(module_name, &block)
+    end
+
+    # Get a registered module
+    def get_module(module_name)
+      registry.get(module_name)
+    end
+
+    # Get all registered modules
+    def registered_modules
+      registry.all
+    end
+  end
+end
+
+# Load Rails generators if Rails is available
+if defined?(Rails)
+  require 'contextual_config/generators'
+end

data/lib/generators/contextual_config/configurable_table/USAGE

@@ -0,0 +1,33 @@
+Description:
+    Generates a migration file for a table that's compatible with ContextualConfig concerns.
+    The table includes all necessary columns for storing contextual configurations including
+    key, config_data (JSONB), scoping_rules (JSONB), priority, is_active, and type (for STI).
+
+Example:
+    ```rails generate contextual_config:configurable_table YourModel```
+
+    This will create:
+        db/migrate/create_your_models.rb
+
+Options:
+    --table-name=TABLE_NAME    # Override the default table name
+                               # Default: pluralized, underscored version of the model name
+
+Examples:
+    rails generate contextual_config:configurable_table Finance::Configuration
+    rails generate contextual_config:configurable_table UserPreference --table-name=user_prefs
+    rails generate contextual_config:configurable_table PayrollConfig
+
+The generated migration creates a table with:
+    - key (string): Identifier for the configuration
+    - config_data (jsonb): Main configuration payload
+    - scoping_rules (jsonb): Rules for when configuration applies
+    - priority (integer): Priority for conflict resolution
+    - is_active (boolean): Enable/disable configurations
+    - description (text): Human-readable description
+    - type (string): For Single Table Inheritance
+    - timestamps: created_at and updated_at
+
+Indexes are automatically created for:
+    - [type, key] (unique)
+    - [is_active, priority] (for efficient querying)

data/lib/generators/contextual_config/configurable_table/configurable_table_generator.rb

@@ -0,0 +1,68 @@
+require 'rails/generators/active_record'
+
+module ContextualConfig
+  module Generators
+    # Generates a migration to create a table suitable for models
+    # that will include ContextualConfig's concerns.
+    #
+    # To run this generator:
+    #   rails generate contextual_config:configurable_table YourModelName
+    #   rails generate contextual_config:configurable_table Namespace::YourModelName
+    #   rails generate contextual_config:configurable_table UserPreference --table-name user_prefs
+    #
+    class ConfigurableTableGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration # Provides #migration_template
+
+      # Thor class options
+      class_option :table_name, type: :string, desc: 'Specify the table name directly, overriding the default.'
+
+      # Define where to find generator templates (e.g., migration.rb.tt)
+      source_root File.expand_path('templates', __dir__)
+
+      # The main method executed by the generator
+      def create_migration_file
+        # migration_template will copy the template file to the application's db/migrate directory.
+        # It automatically handles the timestamp for the migration filename.
+        # Instance variables set here (like @migration_table_name) are available in the template.
+        @migration_table_name = determine_table_name_for_migration
+
+        migration_template('migration.rb.tt', # Template file name
+                           "db/migrate/create_#{@migration_table_name}.rb", # Destination path
+                           migration_version: migration_version_string) # For Rails 5+ migration versions
+      end
+
+      # Required by ActiveRecord::Generators::Migration to create timestamped migration filenames.
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      private
+
+      # Determines the actual table name to be used in the migration.
+      # Uses the --table-name option if provided, otherwise derives from the generator's 'name' argument.
+      def determine_table_name_for_migration
+        # `name` is the original argument to the generator (e.g., "Finance::Configuration" or "UserPreference")
+        # `table_name` is a helper from NamedBase (e.g., "user_preferences" for "UserPreference")
+        custom_name = options[:table_name]
+        return custom_name.underscore if custom_name.present?
+
+        # For namespaced models like "Finance::Configuration", `name.underscore` gives "finance/configuration".
+        # We want "finance_configurations" as the table name.
+        name.underscore.tr('/', '_').pluralize
+      end
+
+      # Provides the Rails migration version string, e.g., "[7.0]".
+      def migration_version_string
+        "[#{ActiveRecord::Migration.current_version}]" if ActiveRecord::Migration.respond_to?(:current_version)
+      end
+
+      # Helper method accessible in the ERB template to form the migration class name.
+      # e.g., CreateFinanceConfigurations
+      public
+
+      def migration_class_name
+        "Create#{determine_table_name_for_migration.camelize}"
+      end
+    end
+  end
+end

data/lib/generators/contextual_config/configurable_table/templates/migration.rb.tt

@@ -0,0 +1,52 @@
+# This file is a template used by the ContextualConfig::ConfigurableTableGenerator.
+# It will be processed to create a migration file in your application's db/migrate directory.
+
+class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version_string %>
+  def change
+    create_table :<%= @migration_table_name %> do |t|
+      # --- Standard columns for ContextualConfig ---
+      # 'key' uniquely identifies a configuration entry within its type/scope.
+      t.string :key, null: false
+
+      # 'config_data' stores the main JSON payload of the configuration.
+      t.jsonb :config_data, null: false, default: {}
+
+      # 'scoping_rules' stores the JSON defining when this configuration is applicable.
+      t.jsonb :scoping_rules, null: false, default: {}
+
+      # 'priority' helps resolve conflicts if multiple configurations match.
+      # Lower numbers generally indicate higher priority.
+      t.integer :priority, null: false, default: 100
+
+      # 'is_active' allows for soft-deleting or disabling configurations.
+      t.boolean :is_active, null: false, default: true
+
+      # 'description' provides a human-readable summary of the configuration's purpose.
+      t.text :description
+
+      # 'type' column is standard for Single Table Inheritance (STI).
+      # Include this if the model using this table (e.g., Finance::Configuration)
+      # will itself be a parent class for more specific configuration types
+      # (e.g., Finance::TaxConfig, Finance::ReportConfig).
+      t.string :type
+
+      t.timestamps null: false
+      # --- End of standard columns ---
+    end
+
+    # --- Recommended Indexes ---
+    # Index for typical lookups by key, potentially scoped by STI type.
+    # Using a unique name for the index to avoid conflicts if multiple tables are generated.
+    add_index :<%= @migration_table_name %>, [:type, :key], unique: true, name: 'idx_<%= @migration_table_name.first(40) %>_on_type_and_key'
+    # Note: If 'type' is not used or key should be globally unique for this table,
+    # a simpler index might be `add_index :<%= @migration_table_name %>, :key, unique: true`
+
+    # Index to efficiently query active configurations by priority.
+    add_index :<%= @migration_table_name %>, [:is_active, :priority], name: 'idx_<%= @migration_table_name.first(40) %>_on_active_priority'
+
+    # Optional: GIN indexes for jsonb columns if you frequently query directly into them.
+    # These can be large and have write performance implications, so add if needed.
+    # add_index :<%= @migration_table_name %>, :config_data, using: :gin, name: 'idx_<%= @migration_table_name.first(40) %>_on_config_data'
+    # add_index :<%= @migration_table_name %>, :scoping_rules, using: :gin, name: 'idx_<%= @migration_table_name.first(40) %>_on_scoping_rules'
+  end
+end

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: contextual_config
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- bazinga012
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+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.
+email:
+- vishal18593@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/settings.local.json"
+- ".rspec"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- contextual_config.gemspec
+- lib/contextual_config.rb
+- lib/contextual_config/concern/configurable.rb
+- lib/contextual_config/concern/lookupable.rb
+- lib/contextual_config/concern/schema_driven_validation.rb
+- lib/contextual_config/configuration.rb
+- lib/contextual_config/generators.rb
+- lib/contextual_config/module_registry.rb
+- lib/contextual_config/services/contextual_matcher.rb
+- lib/contextual_config/version.rb
+- lib/generators/contextual_config/configurable_table/USAGE
+- lib/generators/contextual_config/configurable_table/configurable_table_generator.rb
+- lib/generators/contextual_config/configurable_table/templates/migration.rb.tt
+homepage: https://github.com/bazinga012/contextual_config
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/bazinga012/contextual_config
+  source_code_uri: https://github.com/bazinga012/contextual_config
+  changelog_uri: https://github.com/bazinga012/contextual_config/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A Ruby gem for context-aware configuration management
+test_files: []