featurevisor 3.0.0 → 4.0.0

data/bin/cli.rb

@@ -7,7 +7,9 @@ module FeaturevisorCLI
     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, :with_scopes, :with_tags, :targets
+                 :populate_uuid, :with_scopes, :with_tags, :targets, :entity_type, :set,
+                 :json, :pretty, :case_id, :coverage, :uncovered,
+                 :project_directory_path_explicit
 
     def initialize
       @n = 1000
@@ -26,12 +28,15 @@ module FeaturevisorCLI
       end
 
       options.command = args[0]
+      unless %w[test benchmark assess-distribution].include?(options.command)
+        raise ArgumentError, "Unknown command: #{options.command}"
+      end
       remaining_args = args[1..-1]
 
       OptionParser.new do |opts|
-        opts.banner = "Usage: featurevisor [command] [options]"
+        opts.banner = "Usage: featurevisor #{options.command} [options]"
 
-        opts.on("--assertionPattern=PATTERN", "Assertion pattern") do |v|
+        opts.on("--assertion-pattern=PATTERN", "--assertionPattern=PATTERN", "Assertion pattern") do |v|
           options.assertion_pattern = v
         end
 
@@ -39,23 +44,31 @@ module FeaturevisorCLI
           options.context = v
         end
 
-        opts.on("--environment=ENV", "Environment (required for benchmark)") do |v|
+        opts.on("--environment=ENV", "Configured environment (omit for flat projects)") do |v|
           options.environment = v
         end
 
         opts.on("--feature=FEATURE", "Feature key") do |v|
-          options.feature = v
+          options.feature = nonempty_value("--feature", v)
         end
 
-        opts.on("--keyPattern=PATTERN", "Key pattern") do |v|
+        opts.on("--key-pattern=PATTERN", "--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
+        opts.on("--entity-type=TYPE", "--entityType=TYPE", %w[feature segment variable scenario], "Filter tests by entity type") do |v|
+          options.entity_type = v
+        end
+
+        opts.on("--iterations=N", "--n=N", "Number of iterations (default: 1000)") do |v|
+          options.n = positive_iterations(v)
         end
 
-        opts.on("--onlyFailures", "Only show failures") do
+        opts.on("-n N", "Number of iterations (default: 1000)") do |v|
+          options.n = positive_iterations(v.delete_prefix("="))
+        end
+
+        opts.on("--only-failures", "--onlyFailures", "Only show failures") do
           options.only_failures = true
         end
 
@@ -64,7 +77,7 @@ module FeaturevisorCLI
         end
 
         opts.on("--variable=VARIABLE", "Variable key") do |v|
-          options.variable = v
+          options.variable = nonempty_value("--variable", v)
         end
 
         opts.on("--variation", "Variation mode") do
@@ -76,10 +89,11 @@ module FeaturevisorCLI
         end
 
         opts.on("--inflate=N", Integer, "Inflate mode") do |v|
+          raise OptionParser::InvalidArgument, "--inflate must be a positive integer" unless v.positive?
           options.inflate = v
         end
 
-        opts.on("--showDatafile", "Show datafile content for each test") do
+        opts.on("--show-datafile", "--showDatafile", "Show datafile content for each test") do
           options.show_datafile = true
         end
 
@@ -95,29 +109,79 @@ module FeaturevisorCLI
           options.with_tags = true
         end
 
-        opts.on("--projectDirectoryPath=PATH", "Project directory path") do |v|
-          options.project_directory_path = v
+        opts.on("--project-directory-path=PATH", "--projectDirectoryPath=PATH", "--root-directory-path=PATH", "--rootDirectoryPath=PATH", "Project directory path") do |v|
+          options.project_directory_path = nonempty_value("--project-directory-path", v)
+          options.project_directory_path_explicit = true
         end
 
-        opts.on("--populateUuid=KEY", "Populate UUID for attribute key") do |v|
-          options.populate_uuid << v
+        opts.on("--populate-uuid=KEY", "--populateUuid=KEY", "Populate UUID for attribute key") do |v|
+          options.populate_uuid << nonempty_value("--populate-uuid", v)
         end
 
         opts.on("--target=TARGET", "Target datafile; repeat for multiple targets") do |v|
+          v = nonempty_value("--target", v)
           options.targets << v unless options.targets.include?(v)
         end
 
+        opts.on("--set=SET", "Project set") do |v|
+          options.set = v
+        end
+
+        opts.on("--json", "Print a versioned JSON test report") do
+          options.json = true
+        end
+
+        opts.on("--pretty", "Pretty print JSON output") do
+          options.pretty = true
+        end
+
+        opts.on("--case=ID", "Run one exact expanded test case") do |v|
+          options.case_id = v
+        end
+
+        opts.on("--coverage", "Report observed rule and override selections") do
+          options.coverage = true
+        end
+
+        opts.on("--uncovered", "List features and variables without associated tests") do
+          options.uncovered = true
+        end
+
         opts.on("-h", "--help", "Show this help message") do
           puts opts
           exit
         end
       end.parse!(remaining_args)
 
+      unless remaining_args.empty?
+        raise OptionParser::InvalidArgument, "Unexpected arguments: #{remaining_args.join(' ')}"
+      end
+      unless options.context.nil?
+        context = JSON.parse(options.context)
+        raise ArgumentError, "--context must be a JSON object" unless context.is_a?(Hash)
+      end
       options
     end
+
+    def self.positive_iterations(value)
+      parsed = Integer(value, 10)
+      raise ArgumentError unless parsed.positive?
+      parsed
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "--n must be a positive integer"
+    end
+
+    def self.nonempty_value(name, value)
+      if value.empty? || value.start_with?("--")
+        raise OptionParser::InvalidArgument, "#{name} requires a nonempty value"
+      end
+      value
+    end
   end
 
   def self.run(args)
+    return show_help if args.empty? || args == ["--help"] || args == ["-h"]
+
     options = Parser.parse(args)
 
     case options.command
@@ -130,6 +194,9 @@ module FeaturevisorCLI
     else
       show_help
     end
+  rescue ArgumentError, OptionParser::ParseError, JSON::ParserError, SystemCallError => e
+    warn "Error: #{e.message}"
+    exit 1
   end
 
   def self.show_help
@@ -146,10 +213,10 @@ module FeaturevisorCLI
     puts ""
     puts "Examples:"
     puts "  featurevisor test"
-    puts "  featurevisor test --keyPattern=pattern"
+    puts "  featurevisor test --key-pattern=pattern"
     puts "  featurevisor benchmark --feature=myFeature --environment=dev --n=10000"
     puts "  featurevisor assess-distribution --feature=myFeature --n=10000"
     puts ""
-    puts "Note: benchmark requires --environment and either --feature or --variable"
+    puts "Note: benchmark requires --feature or --variable; --environment is required only when configured"
   end
 end

data/bin/commands/assess_distribution.rb

@@ -1,10 +1,12 @@
 require "json"
 require "securerandom"
 require "open3"
+require_relative "runtime_project"
 
 module FeaturevisorCLI
   module Commands
     class AssessDistribution
+      include RuntimeProject
       # UUID_LENGTHS matches the TypeScript implementation
       UUID_LENGTHS = [4, 2, 2, 2, 6]
 
@@ -19,11 +21,6 @@ module FeaturevisorCLI
 
       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
@@ -31,8 +28,10 @@ module FeaturevisorCLI
 
         context = parse_context
 
-        targets = resolve_targets
-        (targets.empty? ? [nil] : targets).each { |target| run_for_target(context, target) }
+        each_project do
+          targets = resolve_targets
+          (targets.empty? ? [nil] : targets).each { |target| run_for_target(context, target) }
+        end
       end
 
       private
@@ -40,7 +39,7 @@ module FeaturevisorCLI
       def run_for_target(context, target)
         puts "\nAssess Featurevisor distribution"
         puts "  Feature: #{@options.feature}"
-        puts "  Environment: #{@options.environment}"
+        puts "  Environment: #{@options.environment}" if @options.environment
         puts "  Target: #{target}" if target
         puts "  Iterations: #{@options.n}"
 
@@ -112,26 +111,12 @@ module FeaturevisorCLI
         end
       end
 
-      def resolve_targets
-        return [] if @options.targets.empty?
-        stdout, stderr, status = Open3.capture3("npx", "featurevisor", "list", "--targets", "--json", chdir: @project_path)
-        unless status.success?
-          puts stderr
-          exit 1
-        end
-        available = JSON.parse(stdout).map { |item| item.is_a?(Hash) ? (item["key"] || item["name"]) : item }
-        unknown = @options.targets.find { |target| !available.include?(target) }
-        if unknown
-          puts "Unknown target \"#{unknown}\". Available targets: #{available.empty? ? "none" : available.join(", ")}."
-          exit 1
-        end
-        @options.targets
-      end
 
       def parse_context
         if @options.context
           begin
             context = JSON.parse(@options.context)
+            raise ArgumentError, "--context must be a JSON object" unless context.is_a?(Hash)
             # Convert string keys to symbols for the SDK
             context.transform_keys(&:to_sym)
           rescue JSON::ParserError => e
@@ -143,38 +128,11 @@ module FeaturevisorCLI
         end
       end
 
-      def build_datafile(environment, target = nil)
-        puts "Building datafile for environment: #{environment}..."
-
-        # Build the command similar to Go implementation
-        command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--json"]
-        command_parts << "--target=#{target}" if target
-
-        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, symbolize_names: true)
-        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.force_encoding(Encoding::UTF_8)
+        stderr.force_encoding(Encoding::UTF_8)
         [stdout, stderr, exit_status.exitstatus]
       end
 

data/bin/commands/benchmark.rb

@@ -2,10 +2,12 @@ require "benchmark"
 require "json"
 require "time"
 require "open3"
+require_relative "runtime_project"
 
 module FeaturevisorCLI
   module Commands
     class Benchmark
+      include RuntimeProject
       def self.run(options)
         new(options).run
       end
@@ -17,19 +19,16 @@ module FeaturevisorCLI
 
       def run
         # Validate required options
-        unless @options.environment
-          puts "Error: --environment is required for benchmark command"
-          exit 1
-        end
-
         unless @options.feature || @options.variable
           puts "Error: --feature or --variable is required for benchmark command"
           exit 1
         end
 
         context = parse_context
-        targets = resolve_targets
-        (targets.empty? ? [nil] : targets).each { |target| run_for_target(context, target) }
+        each_project do
+          targets = resolve_targets
+          (targets.empty? ? [nil] : targets).each { |target| run_for_target(context, target) }
+        end
       end
 
       private
@@ -43,7 +42,7 @@ module FeaturevisorCLI
         puts "\nBenchmark Featurevisor feature"
         puts "  Feature: #{@options.feature}" if @options.feature
         puts "  Global variable: #{@options.variable}" if @options.variable && !@options.feature
-        puts "  Environment: #{@options.environment}"
+        puts "  Environment: #{@options.environment}" if @options.environment
         puts "  Target: #{target}" if target
         puts "  Iterations: #{@options.n}"
         puts "  Build duration: #{datafile_build_duration_ms}ms"
@@ -85,26 +84,12 @@ module FeaturevisorCLI
         puts "Maximum duration: #{format_duration_ms(output[:max_duration])}"
       end
 
-      def resolve_targets
-        return [] if @options.targets.empty?
-        stdout, stderr, status = Open3.capture3("npx", "featurevisor", "list", "--targets", "--json", chdir: @project_path)
-        unless status.success?
-          puts stderr
-          exit 1
-        end
-        available = JSON.parse(stdout).map { |target| target.is_a?(Hash) ? (target["key"] || target["name"]) : target }
-        unknown = @options.targets.find { |target| !available.include?(target) }
-        if unknown
-          puts "Unknown target \"#{unknown}\". Available targets: #{available.empty? ? "none" : available.join(", ")}."
-          exit 1
-        end
-        @options.targets
-      end
 
       def parse_context
         if @options.context
           begin
             context = JSON.parse(@options.context)
+            raise ArgumentError, "--context must be a JSON object" unless context.is_a?(Hash)
             # Convert string keys to symbols for the SDK
             context.transform_keys(&:to_sym)
           rescue JSON::ParserError => e
@@ -116,35 +101,12 @@ module FeaturevisorCLI
         end
       end
 
-      def build_datafile(environment, target = nil)
-        puts "Building datafile for environment: #{environment}..."
-
-        command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--json"]
-        command_parts << "--target=#{target}" if target
-
-        # Add inflate if specified
-        if @options.inflate && @options.inflate > 0
-          command_parts << "--inflate=#{@options.inflate}"
-        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, symbolize_names: true)
-        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)
+        stdout.force_encoding(Encoding::UTF_8)
+        stderr.force_encoding(Encoding::UTF_8)
 
         unless status.success?
           puts "Error: Command failed with exit code #{status.exitstatus}"

data/bin/commands/node_cli.rb

@@ -0,0 +1,20 @@
+module FeaturevisorCLI
+  # Runs the project's own Node based Featurevisor CLI.
+  #
+  # Node starts the local package entry directly, with an argument list and a
+  # working directory, so no shell quoting is involved on any platform. Without a
+  # local package, npx resolves the CLI as before, through npx.cmd on Windows.
+  module NodeCli
+    def self.command(project_path)
+      directory = File.expand_path(project_path)
+      loop do
+        entry = File.join(directory, "node_modules", "@featurevisor", "cli", "bin.js")
+        return ["node", entry] if File.file?(entry)
+        parent = File.dirname(directory)
+        break if parent == directory
+        directory = parent
+      end
+      [Gem.win_platform? ? "npx.cmd" : "npx", "featurevisor"]
+    end
+  end
+end

data/bin/commands/runtime_project.rb

@@ -0,0 +1,63 @@
+require "json"
+require "open3"
+
+module FeaturevisorCLI
+  module Commands
+    module RuntimeProject
+      def each_project
+        raise ArgumentError, "--n must be a positive integer" unless @options.n.positive?
+        if @options.variation && @options.variable
+          raise ArgumentError, "--variation and --variable cannot be combined"
+        end
+        config = project_json("config", "--json", include_set: false)
+        environments = config["environments"]
+        if environments.is_a?(Array)
+          raise ArgumentError, "Pass --environment=<environment> when selecting one datafile." unless @options.environment
+          unless environments.include?(@options.environment)
+            raise ArgumentError, "Unknown environment #{@options.environment.inspect}. Available environments: #{environments.join(', ')}."
+          end
+        elsif @options.environment
+          raise ArgumentError, "This project does not configure environments. Omit --environment."
+        end
+        sets = [@options.set]
+        if config["sets"] && !@options.set
+          directory = File.expand_path(config["setsDirectoryPath"] || "sets", @project_path)
+          sets = Dir.children(directory).select { |entry| File.directory?(File.join(directory, entry)) }.sort
+          raise ArgumentError, "No sets found in #{directory}." if sets.empty?
+        end
+        sets.each do |set|
+          @active_set = set
+          puts "Set #{set.inspect}" if set
+          yield
+        end
+      end
+
+      def project_json(*args, include_set: true)
+        args << "--set=#{@active_set || @options.set}" if include_set && (@active_set || @options.set)
+        stdout, stderr, status = Open3.capture3(*FeaturevisorCLI::NodeCli.command(@project_path), *args, chdir: @project_path)
+        stdout.force_encoding(Encoding::UTF_8)
+        stderr.force_encoding(Encoding::UTF_8)
+        raise ArgumentError, stderr.empty? ? "Node CLI failed with exit code #{status.exitstatus}" : stderr unless status.success?
+        warn stderr unless stderr.empty?
+        JSON.parse(stdout)
+      end
+
+      def resolve_targets
+        return [] if @options.targets.empty?
+        available = project_json("list", "--targets", "--json").map { |target| target.is_a?(Hash) ? (target["key"] || target["name"]) : target }
+        unknown = @options.targets.find { |target| !available.include?(target) }
+        raise ArgumentError, "Unknown target #{unknown.inspect}. Available targets: #{available.join(', ')}." if unknown
+        @options.targets
+      end
+
+      def build_datafile(environment, target = nil)
+        args = ["build", "--json"]
+        args << "--environment=#{environment}" if environment
+        args << "--target=#{target}" if target
+        args << "--inflate=#{@options.inflate}" if @options.inflate && @options.inflate.positive?
+        # Symbol keys are the native SDK datafile representation.
+        JSON.parse(JSON.generate(project_json(*args)), symbolize_names: true)
+      end
+    end
+  end
+end