featurevisor 0.1.1

data/bin/commands.rb

@@ -0,0 +1,10 @@
+require_relative "commands/test"
+require_relative "commands/benchmark"
+require_relative "commands/assess_distribution"
+
+module FeaturevisorCLI
+  module Commands
+    # This module serves as a namespace for all CLI commands
+    # Individual command classes are defined in separate files
+  end
+end

data/bin/featurevisor

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+# CLI for the featurevisor gem
+# Usage: featurevisor [command] [options]
+
+# Add the lib directory to the load path so we can require the featurevisor gem
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
+
+require "featurevisor"
+require_relative "cli"
+
+if ARGV.empty?
+  FeaturevisorCLI.show_help
+  exit 0
+end
+
+# Run the CLI with the provided arguments
+FeaturevisorCLI.run(ARGV)

data/lib/featurevisor/bucketer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Featurevisor
+  # Bucketer module for handling feature flag bucketing
+  module Bucketer
+    # Maximum bucketed number (100% * 1000 to include three decimal places)
+    MAX_BUCKETED_NUMBER = 100_000
+
+    # Hash seed for consistent bucketing
+    HASH_SEED = 1
+
+    # Maximum hash value for 32-bit integers
+    MAX_HASH_VALUE = 2**32
+
+    # Default separator for bucket keys
+    DEFAULT_BUCKET_KEY_SEPARATOR = "."
+
+    # Get bucketed number from a bucket key
+    # @param bucket_key [String] The bucket key to hash
+    # @return [Integer] Bucket value between 0 and 100000
+    def self.get_bucketed_number(bucket_key)
+      hash_value = Featurevisor.murmur_hash_v3(bucket_key, HASH_SEED)
+      ratio = hash_value.to_f / MAX_HASH_VALUE
+
+      (ratio * MAX_BUCKETED_NUMBER).floor
+    end
+
+    # Get bucket key from feature configuration and context
+    # @param options [Hash] Options hash containing:
+    #   - feature_key [String] The feature key
+    #   - bucket_by [String, Array<String>, Hash] Bucketing strategy
+    #   - context [Hash] User context
+    #   - logger [Logger] Logger instance
+    # @return [String] The bucket key
+    # @raise [StandardError] If bucket_by is invalid
+    def self.get_bucket_key(options)
+      feature_key = options[:feature_key]
+      bucket_by = options[:bucket_by]
+      context = options[:context]
+      logger = options[:logger]
+
+      type, attribute_keys = parse_bucket_by(bucket_by, logger, feature_key)
+
+      bucket_key = build_bucket_key(attribute_keys, context, type, feature_key)
+
+      bucket_key.join(DEFAULT_BUCKET_KEY_SEPARATOR)
+    end
+
+    private
+
+    # Parse bucket_by configuration to determine type and attribute keys
+    # @param bucket_by [String, Array<String>, Hash] Bucketing strategy
+    # @param logger [Logger] Logger instance
+    # @param feature_key [String] Feature key for error logging
+    # @return [Array] Tuple of [type, attribute_keys]
+    def self.parse_bucket_by(bucket_by, logger, feature_key)
+      if bucket_by.is_a?(String)
+        ["plain", [bucket_by]]
+      elsif bucket_by.is_a?(Array)
+        ["and", bucket_by]
+      elsif bucket_by.is_a?(Hash) && bucket_by[:or].is_a?(Array)
+        ["or", bucket_by[:or]]
+      else
+        logger.error("invalid bucketBy", { feature_key: feature_key, bucket_by: bucket_by })
+        raise StandardError, "invalid bucketBy"
+      end
+    end
+
+    # Build bucket key array from attribute keys and context
+    # @param attribute_keys [Array<String>] Array of attribute keys
+    # @param context [Hash] User context
+    # @param type [String] Bucketing type ("plain", "and", "or")
+    # @param feature_key [String] Feature key to append
+    # @return [Array] Array of bucket key components
+    def self.build_bucket_key(attribute_keys, context, type, feature_key)
+      bucket_key = []
+
+      attribute_keys.each do |attribute_key|
+        attribute_value = Featurevisor::Conditions.get_value_from_context(context, attribute_key)
+
+        next if attribute_value.nil?
+
+        if type == "plain" || type == "and"
+          bucket_key << attribute_value
+        elsif type == "or" && bucket_key.empty?
+          # For "or" type, only take the first available value
+          bucket_key << attribute_value
+        end
+      end
+
+      bucket_key << feature_key
+      bucket_key
+    end
+  end
+end

data/lib/featurevisor/child_instance.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+module Featurevisor
+  # Child instance class for managing child contexts and sticky features
+  class ChildInstance
+    attr_reader :parent, :context, :sticky, :emitter
+
+    # Initialize a new child instance
+    # @param options [Hash] Child instance options
+    # @option options [Instance] :parent Parent instance
+    # @option options [Hash] :context Child context
+    # @option options [Hash] :sticky Child sticky features
+    def initialize(options)
+      @parent = options[:parent]
+      @context = options[:context] || {}
+      @sticky = options[:sticky] || {}
+      @emitter = Featurevisor::Emitter.new
+    end
+
+    # Subscribe to an event
+    # @param event_name [String] Event name
+    # @param callback [Proc] Callback function
+    # @return [Proc] Unsubscribe function
+    def on(event_name, callback = nil, &block)
+      callback = block if block_given?
+      
+      if event_name == "context_set" || event_name == "sticky_set"
+        @emitter.on(event_name, callback)
+      else
+        @parent.on(event_name, callback)
+      end
+    end
+
+    # Close the child instance
+    def close
+      @emitter.clear_all
+    end
+
+    # Set context
+    # @param context [Hash] Context to set
+    # @param replace [Boolean] Whether to replace existing context
+    def set_context(context, replace = false)
+      if replace
+        @context = context
+      else
+        @context = { **@context, **context }
+      end
+
+      @emitter.trigger("context_set", {
+        context: @context,
+        replaced: replace
+      })
+    end
+
+    # Get context
+    # @param context [Hash, nil] Additional context to merge
+    # @return [Hash] Merged context
+    def get_context(context = nil)
+      @parent.get_context({
+        **@context,
+        **(context || {})
+      })
+    end
+
+    # Set sticky features
+    # @param sticky [Hash] Sticky features
+    # @param replace [Boolean] Whether to replace existing sticky features
+    def set_sticky(sticky, replace = false)
+      previous_sticky_features = @sticky || {}
+
+      if replace
+        @sticky = sticky
+      else
+        @sticky = {
+          **@sticky,
+          **sticky
+        }
+      end
+
+      params = Featurevisor::Events.get_params_for_sticky_set_event(previous_sticky_features, @sticky, replace)
+      @emitter.trigger("sticky_set", params)
+    end
+
+    # Check if a feature is enabled
+    # @param feature_key [String] Feature key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Boolean] True if feature is enabled
+    def is_enabled(feature_key, context = {}, options = {})
+      @parent.is_enabled(
+        feature_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variation value
+    # @param feature_key [String] Feature key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [String, nil] Variation value or nil
+    def get_variation(feature_key, context = {}, options = {})
+      @parent.get_variation(
+        feature_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable value
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Object, nil] Variable value or nil
+    def get_variable(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable as boolean
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Boolean, nil] Boolean value or nil
+    def get_variable_boolean(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable_boolean(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable as string
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [String, nil] String value or nil
+    def get_variable_string(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable_string(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable as integer
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Integer, nil] Integer value or nil
+    def get_variable_integer(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable_integer(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable as double
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Float, nil] Float value or nil
+    def get_variable_double(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable_double(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable as array
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Array, nil] Array value or nil
+    def get_variable_array(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable_array(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable as object
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Hash, nil] Object value or nil
+    def get_variable_object(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable_object(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get variable as JSON
+    # @param feature_key [String] Feature key
+    # @param variable_key [String] Variable key
+    # @param context [Hash] Context
+    # @param options [Hash] Override options
+    # @return [Object, nil] JSON value or nil
+    def get_variable_json(feature_key, variable_key, context = {}, options = {})
+      @parent.get_variable_json(
+        feature_key,
+        variable_key,
+        {
+          **@context,
+          **context
+        },
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    # Get all evaluations
+    # @param context [Hash] Context
+    # @param feature_keys [Array<String>] Feature keys to evaluate
+    # @param options [Hash] Override options
+    # @return [Hash] All evaluations
+    def get_all_evaluations(context = {}, feature_keys = [], options = {})
+      @parent.get_all_evaluations(
+        {
+          **@context,
+          **context
+        },
+        feature_keys,
+        {
+          sticky: @sticky,
+          **options
+        }
+      )
+    end
+
+    private
+  end
+end

data/lib/featurevisor/compare_versions.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Featurevisor
+  # Semantic version comparison functionality
+  # Original: https://github.com/omichelsen/compare-versions
+  # Ported from TypeScript to Ruby
+
+  # Regular expression for semantic version parsing
+  SEMVER_REGEX = /^[v^~<>=]*?(\d+)(?:\.([x*]|\d+)(?:\.([x*]|\d+)(?:\.([x*]|\d+))?(?:-([\da-z\-]+(?:\.[\da-z\-]+)*))?(?:\+[\da-z\-]+(?:\.[\da-z\-]+)*)?)?)?$/i
+
+  # Validates and parses a version string
+  # @param version [String] Version string to validate and parse
+  # @return [Array<String>] Array of version segments
+  # @raise [TypeError] If version is not a string
+  # @raise [ArgumentError] If version is not valid semver
+  def self.validate_and_parse(version)
+    unless version.is_a?(String)
+      raise TypeError, "Invalid argument expected string"
+    end
+
+    match = version.match(SEMVER_REGEX)
+    unless match
+      raise ArgumentError, "Invalid argument not valid semver ('#{version}' received)"
+    end
+
+    # Remove the first element (full match) and return the rest
+    match.to_a[1..-1]
+  end
+
+  # Checks if a string is a wildcard
+  # @param s [String] String to check
+  # @return [Boolean] True if wildcard
+  def self.wildcard?(s)
+    s == "*" || s.downcase == "x"
+  end
+
+  # Forces types to be the same for comparison
+  # @param a [String, Integer] First value
+  # @param b [String, Integer] Second value
+  # @return [Array] Array with both values converted to same type
+  def self.force_type(a, b)
+    if a.is_a?(Integer) != b.is_a?(Integer)
+      [a.to_s, b.to_s]
+    else
+      [a, b]
+    end
+  end
+
+  # Tries to parse a string as an integer
+  # @param v [String] String to parse
+  # @return [Integer, String] Parsed integer or original string
+  def self.try_parse(v)
+    Integer(v, 10)
+  rescue ArgumentError
+    v
+  end
+
+  # Compares two strings for version comparison
+  # @param a [String] First string
+  # @param b [String] Second string
+  # @return [Integer] -1 if a < b, 0 if equal, 1 if a > b
+  def self.compare_strings(a, b)
+    return 0 if wildcard?(a) || wildcard?(b)
+
+    ap, bp = force_type(try_parse(a), try_parse(b))
+
+    if ap > bp
+      1
+    elsif ap < bp
+      -1
+    else
+      0
+    end
+  end
+
+  # Compares version segments
+  # @param a [Array<String>, MatchData] First version segments
+  # @param b [Array<String>, MatchData] Second version segments
+  # @return [Integer] -1 if a < b, 0 if equal, 1 if a > b
+  def self.compare_segments(a, b)
+    # Convert to arrays if needed
+    a_array = a.is_a?(MatchData) ? a.to_a[1..-1] : a.to_a
+    b_array = b.is_a?(MatchData) ? b.to_a[1..-1] : b.to_a
+
+    max_length = [a_array.length, b_array.length].max
+
+    (0...max_length).each do |i|
+      a_val = a_array[i] || "0"
+      b_val = b_array[i] || "0"
+
+      result = compare_strings(a_val, b_val)
+      return result unless result == 0
+    end
+
+    0
+  end
+
+  # Compares two version strings
+  # @param v1 [String] First version string
+  # @param v2 [String] Second version string
+  # @return [Integer] -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+  # @raise [TypeError] If either version is not a string
+  # @raise [ArgumentError] If either version is not valid semver
+  def self.compare_versions(v1, v2)
+    # Validate input and split into segments
+    n1 = validate_and_parse(v1)
+    n2 = validate_and_parse(v2)
+
+    # Pop off the patch
+    p1 = n1.pop
+    p2 = n2.pop
+
+    # Validate numbers
+    r = compare_segments(n1, n2)
+    return r unless r == 0
+
+    # Validate pre-release
+    if p1 && p2
+      compare_segments(p1.split("."), p2.split("."))
+    elsif p1 || p2
+      p1 ? -1 : 1
+    else
+      0
+    end
+  end
+end