featurevisor 0.1.1

data/bin/cli.rb

@@ -0,0 +1,142 @@
+require "optparse"
+require "json"
+require_relative "commands"
+
+module FeaturevisorCLI
+  class Options
+    attr_accessor :command, :assertion_pattern, :context, :environment, :feature,
+                 :key_pattern, :n, :only_failures, :quiet, :variable, :variation,
+                 :verbose, :inflate, :show_datafile, :schema_version, :project_directory_path,
+                 :populate_uuid
+
+    def initialize
+      @n = 1000
+      @project_directory_path = Dir.pwd
+      @populate_uuid = []
+    end
+  end
+
+  class Parser
+    def self.parse(args)
+      options = Options.new
+
+      if args.empty?
+        return options
+      end
+
+      options.command = args[0]
+      remaining_args = args[1..-1]
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: featurevisor [command] [options]"
+
+        opts.on("--assertionPattern=PATTERN", "Assertion pattern") do |v|
+          options.assertion_pattern = v
+        end
+
+        opts.on("--context=CONTEXT", "Context JSON") do |v|
+          options.context = v
+        end
+
+        opts.on("--environment=ENV", "Environment (required for benchmark)") do |v|
+          options.environment = v
+        end
+
+        opts.on("--feature=FEATURE", "Feature key (required for benchmark)") do |v|
+          options.feature = v
+        end
+
+        opts.on("--keyPattern=PATTERN", "Key pattern") do |v|
+          options.key_pattern = v
+        end
+
+        opts.on("-n", "--iterations=N", "--n=N", Integer, "Number of iterations (default: 1000)") do |v|
+          options.n = v
+        end
+
+        opts.on("--onlyFailures", "Only show failures") do
+          options.only_failures = true
+        end
+
+        opts.on("--quiet", "Quiet mode") do
+          options.quiet = true
+        end
+
+        opts.on("--variable=VARIABLE", "Variable key") do |v|
+          options.variable = v
+        end
+
+        opts.on("--variation", "Variation mode") do
+          options.variation = true
+        end
+
+        opts.on("--verbose", "Verbose mode") do
+          options.verbose = true
+        end
+
+        opts.on("--inflate=N", Integer, "Inflate mode") do |v|
+          options.inflate = v
+        end
+
+        opts.on("--showDatafile", "Show datafile content for each test") do
+          options.show_datafile = true
+        end
+
+        opts.on("--schemaVersion=VERSION", "Schema version") do |v|
+          options.schema_version = v
+        end
+
+        opts.on("--projectDirectoryPath=PATH", "Project directory path") do |v|
+          options.project_directory_path = v
+        end
+
+        opts.on("--populateUuid=KEY", "Populate UUID for attribute key") do |v|
+          options.populate_uuid << v
+        end
+
+        opts.on("-h", "--help", "Show this help message") do
+          puts opts
+          exit
+        end
+      end.parse!(remaining_args)
+
+      options
+    end
+  end
+
+  def self.run(args)
+    options = Parser.parse(args)
+
+    case options.command
+    when "test"
+      Commands::Test.run(options)
+    when "benchmark"
+      Commands::Benchmark.run(options)
+    when "assess-distribution"
+      Commands::AssessDistribution.run(options)
+    else
+      show_help
+    end
+  end
+
+  def self.show_help
+    puts "Featurevisor Ruby SDK CLI"
+    puts ""
+    puts "Usage: featurevisor [command] [options]"
+    puts ""
+    puts "Commands:"
+    puts "  test                    Run tests for features and segments"
+    puts "  benchmark               Benchmark feature evaluation performance"
+    puts "  assess-distribution     Assess feature distribution across contexts"
+    puts ""
+    puts "Learn more at https://featurevisor.com/docs/sdks/ruby/"
+    puts ""
+    puts "Examples:"
+    puts "  featurevisor test"
+    puts "  featurevisor test --keyPattern=pattern"
+    puts "  featurevisor benchmark --feature=myFeature --environment=dev --n=10000"
+    puts "  featurevisor assess-distribution --feature=myFeature --n=10000"
+    puts ""
+    puts "Note: benchmark command requires --environment and --feature options"
+  end
+end

data/bin/commands/assess_distribution.rb

@@ -0,0 +1,236 @@
+require "json"
+require "securerandom"
+require "open3"
+
+module FeaturevisorCLI
+  module Commands
+    class AssessDistribution
+      # UUID_LENGTHS matches the TypeScript implementation
+      UUID_LENGTHS = [4, 2, 2, 2, 6]
+
+      def self.run(options)
+        new(options).run
+      end
+
+      def initialize(options)
+        @options = options
+        @project_path = options.project_directory_path
+      end
+
+      def run
+        # Validate required options
+        unless @options.environment
+          puts "Error: --environment is required for assess-distribution command"
+          exit 1
+        end
+
+        unless @options.feature
+          puts "Error: --feature is required for assess-distribution command"
+          exit 1
+        end
+
+        puts ""
+        puts "Assessing distribution for feature: \"#{@options.feature}\"..."
+        puts ""
+
+        # Parse context if provided
+        context = parse_context
+
+        # Print context information
+        if @options.context
+          puts "Against context: #{@options.context}"
+        else
+          puts "Against context: {}"
+        end
+
+        puts "Running #{@options.n} times..."
+        puts ""
+
+        # Build datafile
+        datafile = build_datafile(@options.environment)
+
+        # Create SDK instance
+        instance = create_instance(datafile)
+
+        # Check if feature has variations
+        feature = instance.get_feature(@options.feature)
+        has_variations = feature && feature[:variations] && feature[:variations].length > 0
+
+        # Initialize evaluation counters
+        flag_evaluations = {
+          "enabled" => 0,
+          "disabled" => 0
+        }
+        variation_evaluations = {}
+
+        # Run evaluations
+        @options.n.times do |i|
+          # Create a copy of context for this iteration
+          context_copy = context.dup
+
+          # Populate UUIDs if requested
+          if @options.populate_uuid.any?
+            @options.populate_uuid.each do |key|
+              context_copy[key.to_sym] = generate_uuid
+            end
+          end
+
+          # Evaluate flag
+          flag_evaluation = instance.is_enabled(@options.feature, context_copy)
+          if flag_evaluation
+            flag_evaluations["enabled"] += 1
+          else
+            flag_evaluations["disabled"] += 1
+          end
+
+          # Evaluate variation if feature has variations
+          if has_variations
+            variation_evaluation = instance.get_variation(@options.feature, context_copy)
+            if variation_evaluation
+              variation_value = variation_evaluation
+              variation_evaluations[variation_value] ||= 0
+              variation_evaluations[variation_value] += 1
+            end
+          end
+        end
+
+        # Print results
+        puts "\nFlag evaluations:"
+        print_counts(flag_evaluations, @options.n, true)
+
+        if has_variations
+          puts "\nVariation evaluations:"
+          print_counts(variation_evaluations, @options.n, true)
+        end
+      end
+
+      private
+
+      def parse_context
+        if @options.context
+          begin
+            context = JSON.parse(@options.context)
+            # Convert string keys to symbols for the SDK
+            context.transform_keys(&:to_sym)
+          rescue JSON::ParserError => e
+            puts "Error: Invalid JSON context: #{e.message}"
+            exit 1
+          end
+        else
+          {}
+        end
+      end
+
+      def build_datafile(environment)
+        puts "Building datafile for environment: #{environment}..."
+
+        # Build the command similar to Go implementation
+        command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--json"]
+
+        if @options.schema_version
+          command_parts << "--schemaVersion=#{@options.schema_version}"
+        end
+
+        if @options.inflate
+          command_parts << "--inflate=#{@options.inflate}"
+        end
+
+        command = command_parts.join(" ")
+
+        stdout, stderr, exit_status = execute_command(command)
+
+        if exit_status != 0
+          puts "Error: Command failed with exit code #{exit_status}"
+          puts "Command: #{command}"
+          puts "Stderr: #{stderr}"
+          exit 1
+        end
+
+        begin
+          JSON.parse(stdout)
+        rescue JSON::ParserError => e
+          puts "Error: Failed to parse datafile JSON: #{e.message}"
+          exit 1
+        end
+      end
+
+      def execute_command(command)
+        stdout, stderr, exit_status = Open3.capture3(command)
+        [stdout, stderr, exit_status.exitstatus]
+      end
+
+      def create_instance(datafile)
+        # Convert datafile to proper format for the SDK
+        symbolized_datafile = symbolize_keys(datafile)
+
+        # Create SDK instance
+        Featurevisor.create_instance(
+          datafile: symbolized_datafile,
+          log_level: get_logger_level
+        )
+      end
+
+      def symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.transform_keys(&:to_sym).transform_values { |v| symbolize_keys(v) }
+        when Array
+          obj.map { |item| symbolize_keys(item) }
+        else
+          obj
+        end
+      end
+
+      def get_logger_level
+        if @options.verbose
+          "debug"
+        elsif @options.quiet
+          "error"
+        else
+          "warn"
+        end
+      end
+
+      # Generate UUID string matching the TypeScript format
+      def generate_uuid
+        parts = UUID_LENGTHS.map do |length|
+          SecureRandom.hex(length)
+        end
+        parts.join("-")
+      end
+
+      # Pretty number formatting (simple implementation)
+      def pretty_number(n)
+        n.to_s
+      end
+
+      # Pretty percentage formatting with 2 decimal places
+      def pretty_percentage(count, total)
+        if total == 0
+          "0.00%"
+        else
+          percentage = (count.to_f / total * 100).round(2)
+          "#{percentage}%"
+        end
+      end
+
+      # Print evaluation counts in the same format as TypeScript
+      def print_counts(evaluations, n, sort_results = true)
+        # Convert to entries for sorting
+        entries = evaluations.map { |value, count| { value: value, count: count } }
+
+        # Sort by count descending if requested
+        if sort_results
+          entries.sort_by! { |entry| -entry[:count] }
+        end
+
+        # Print each entry
+        entries.each do |entry|
+          value_str = entry[:value].to_s
+          count = entry[:count]
+          puts "  - #{value_str}: #{pretty_number(count)} #{pretty_percentage(count, n)}"
+        end
+      end
+    end
+  end
+end

data/bin/commands/benchmark.rb

@@ -0,0 +1,274 @@
+require "benchmark"
+require "json"
+require "time"
+require "open3"
+
+module FeaturevisorCLI
+  module Commands
+    class Benchmark
+      def self.run(options)
+        new(options).run
+      end
+
+      def initialize(options)
+        @options = options
+        @project_path = options.project_directory_path
+      end
+
+      def run
+        # Validate required options
+        unless @options.environment
+          puts "Error: --environment is required for benchmark command"
+          exit 1
+        end
+
+        unless @options.feature
+          puts "Error: --feature is required for benchmark command"
+          exit 1
+        end
+
+        puts ""
+        puts "Running benchmark for feature \"#{@options.feature}\"..."
+        puts ""
+
+        # Parse context if provided
+        context = parse_context
+
+        puts "Building datafile containing all features for \"#{@options.environment}\"..."
+        datafile_build_start = Time.now
+
+        # Build datafile by executing the featurevisor build command
+        datafile = build_datafile(@options.environment)
+        datafile_build_duration = Time.now - datafile_build_start
+        datafile_build_duration_ms = (datafile_build_duration * 1000).round
+
+        puts "Datafile build duration: #{datafile_build_duration_ms}ms"
+
+        # Calculate datafile size
+        datafile_size = datafile.to_json.bytesize
+        puts "Datafile size: #{(datafile_size / 1024.0).round(2)} kB"
+
+        # Create SDK instance with the datafile
+        instance = create_instance(datafile)
+        puts "...SDK initialized"
+
+        puts ""
+        puts "Against context: #{context.to_json}"
+
+        # Run the appropriate benchmark
+        if @options.variation
+          puts "Evaluating variation #{@options.n} times..."
+          output = benchmark_feature_variation(instance, @options.feature, context, @options.n)
+        elsif @options.variable
+          puts "Evaluating variable \"#{@options.variable}\" #{@options.n} times..."
+          output = benchmark_feature_variable(instance, @options.feature, @options.variable, context, @options.n)
+        else
+          puts "Evaluating flag #{@options.n} times..."
+          output = benchmark_feature_flag(instance, @options.feature, context, @options.n)
+        end
+
+        puts ""
+
+        # Format the value output to match Go behavior
+        value_output = format_value(output[:value])
+        puts "Evaluated value : #{value_output}"
+        puts "Total duration  : #{pretty_duration(output[:duration])}"
+        puts "Average duration: #{pretty_duration(output[:duration] / @options.n)}"
+      end
+
+      private
+
+      def parse_context
+        if @options.context
+          begin
+            context = JSON.parse(@options.context)
+            # Convert string keys to symbols for the SDK
+            context.transform_keys(&:to_sym)
+          rescue JSON::ParserError => e
+            puts "Error: Invalid JSON context: #{e.message}"
+            exit 1
+          end
+        else
+          {}
+        end
+      end
+
+      def build_datafile(environment)
+        puts "Building datafile for environment: #{environment}..."
+
+        # Build the command similar to Go implementation
+        command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--json"]
+
+        # Add schema version if specified
+        if @options.schema_version && !@options.schema_version.empty?
+          command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--schemaVersion=#{@options.schema_version}", "--json"]
+        end
+
+        # Add inflate if specified
+        if @options.inflate && @options.inflate > 0
+          if @options.schema_version && !@options.schema_version.empty?
+            command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--schemaVersion=#{@options.schema_version}", "--inflate=#{@options.inflate}", "--json"]
+          else
+            command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--inflate=#{@options.inflate}", "--json"]
+          end
+        end
+
+        command = command_parts.join(" ")
+
+        # Execute the command and capture output
+        datafile_output = execute_command(command)
+
+        # Parse the JSON output
+        begin
+          JSON.parse(datafile_output)
+        rescue JSON::ParserError => e
+          puts "Error: Failed to parse datafile JSON: #{e.message}"
+          puts "Command output: #{datafile_output}"
+          exit 1
+        end
+      end
+
+      def execute_command(command)
+        # Execute the command and capture stdout/stderr
+        stdout, stderr, status = Open3.capture3(command)
+
+        unless status.success?
+          puts "Error: Command failed with exit code #{status.exitstatus}"
+          puts "Command: #{command}"
+          puts "Stderr: #{stderr}" unless stderr.empty?
+          exit 1
+        end
+
+        stdout
+      end
+
+      def create_instance(datafile)
+        # Convert string keys to symbols for the SDK
+        symbolized_datafile = symbolize_keys(datafile)
+
+        # Create a real Featurevisor instance
+        instance = Featurevisor.create_instance(
+          log_level: get_logger_level
+        )
+
+        # Explicitly set the datafile
+        instance.set_datafile(symbolized_datafile)
+
+        instance
+      end
+
+      def get_logger_level
+        if @options.verbose
+          "debug"
+        elsif @options.quiet
+          "error"
+        else
+          "warn"
+        end
+      end
+
+      def symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.transform_keys(&:to_sym).transform_values { |v| symbolize_keys(v) }
+        when Array
+          obj.map { |item| symbolize_keys(item) }
+        else
+          obj
+        end
+      end
+
+      def benchmark_feature_flag(instance, feature_key, context, n)
+        start_time = Time.now
+
+        # Get the actual feature value from the SDK
+        value = instance.is_enabled(feature_key, context)
+
+        # Benchmark the evaluation
+        n.times do
+          instance.is_enabled(feature_key, context)
+        end
+
+        duration = Time.now - start_time
+
+        {
+          value: value,
+          duration: duration
+        }
+      end
+
+      def benchmark_feature_variation(instance, feature_key, context, n)
+        start_time = Time.now
+
+        # Get the actual feature variation from the SDK
+        value = instance.get_variation(feature_key, context)
+
+        # Benchmark the evaluation
+        n.times do
+          instance.get_variation(feature_key, context)
+        end
+
+        duration = Time.now - start_time
+
+        {
+          value: value,
+          duration: duration
+        }
+      end
+
+      def benchmark_feature_variable(instance, feature_key, variable_key, context, n)
+        start_time = Time.now
+
+        # Get the actual variable value from the SDK
+        value = instance.get_variable(feature_key, variable_key, context)
+
+        # Benchmark the evaluation
+        n.times do
+          instance.get_variable(feature_key, variable_key, context)
+        end
+
+        duration = Time.now - start_time
+
+        {
+          value: value,
+          duration: duration
+        }
+      end
+
+      def format_value(value)
+        if value.nil?
+          "null"
+        else
+          value.to_json
+        end
+      rescue JSON::GeneratorError
+        value.to_s
+      end
+
+      def pretty_duration(duration_seconds)
+        # Convert to milliseconds for consistency with Go implementation
+        ms = (duration_seconds * 1000).round
+
+        if ms == 0
+          return "0ms"
+        end
+
+        # Format like Go: hours, minutes, seconds, milliseconds
+        hours = ms / 3_600_000
+        ms = ms % 3_600_000
+        minutes = ms / 60_000
+        ms = ms % 60_000
+        seconds = ms / 1_000
+        ms = ms % 1_000
+
+        result = []
+        result << "#{hours}h" if hours > 0
+        result << "#{minutes}m" if minutes > 0
+        result << "#{seconds}s" if seconds > 0
+        result << "#{ms}ms" if ms > 0
+
+        result.join(" ")
+      end
+    end
+  end
+end