ibex 0.2.0 → 0.3.0

data/lib/ibex/cli/reduce.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "shellwords"
+require_relative "../bounded_subprocess"
+require_relative "../delta_reducer"
+require_relative "reduce_reporting"
+
+module Ibex
+  # @rbs!
+  #   type reduction_bounds = {
+  #     max_trials: Integer,
+  #     timeout_seconds: Integer,
+  #     max_output_bytes: Integer,
+  #     max_input_bytes: Integer
+  #   }
+  #   type reduction_budget_details = {
+  #     kind: String,
+  #     message: String,
+  #     trials: Integer
+  #   }
+  #   type reduction_success_document = {
+  #     ibex_report: String,
+  #     schema_version: Integer,
+  #     result: String,
+  #     mode: Symbol,
+  #     original_size: Integer,
+  #     minimized_size: Integer,
+  #     trials: Integer,
+  #     complete: bool,
+  #     minimized: Array[String | Integer],
+  #     bounded: bool,
+  #     bounds: reduction_bounds
+  #   }
+  #   type reduction_budget_document = {
+  #     ibex_report: String,
+  #     schema_version: Integer,
+  #     result: String,
+  #     mode: Symbol,
+  #     bounded: bool,
+  #     bounds: reduction_bounds,
+  #     budget: reduction_budget_details
+  #   }
+
+  # CLI entry point for generic bounded delta debugging.
+  module CLIReduce
+    include CLIReduceReporting
+
+    DEFAULT_MAX_INPUT_BYTES = 10 * 1024 * 1024 #: Integer
+
+    class ReductionBudgetExceeded < Ibex::Error
+      attr_reader :details #: reduction_budget_details
+
+      # @rbs (reduction_budget_details details) -> void
+      def initialize(details)
+        @details = details
+        super("(reduce):1:1: configured resource budget was exhausted")
+      end
+    end
+
+    # @rbs @reduction_mode: Symbol
+    # @rbs @reduction_bounds: reduction_bounds
+    # @rbs @reduction_trials: Integer
+    # @rbs @reduction_subprocess: BoundedSubprocess
+
+    # @rbs!
+    #   private def print_help: (OptionParser) -> Integer
+    #   private def input_path: (Array[String]) -> String
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_reduce_command(arguments)
+      parser = reduce_option_parser
+      remaining = parser.parse(arguments)
+      return print_help(parser) if @options[:help]
+
+      path = input_path(remaining)
+      configured_command = @options[:reduce_command]
+      raise OptionParser::MissingArgument, "--command" unless configured_command
+
+      command = Shellwords.split(configured_command)
+      raise OptionParser::InvalidArgument, "--command must not be empty" if command.empty?
+
+      prepare_reduction_run
+      source = bounded_reduction_source(path)
+      items = reduction_items(source, @reduction_mode)
+      reducer = DeltaReducer.new(max_trials: @reduction_bounds.fetch(:max_trials))
+      result = reducer.minimize(items) { |candidate| reduction_failure?(command, candidate, @reduction_mode) }
+      write_reduction_success(reduction_success_report(result))
+      result.complete ? 0 : 2
+    rescue ReductionBudgetExceeded => e
+      write_reduction_budget(reduction_budget_report(e.details))
+      2
+    end
+
+    # @rbs () -> OptionParser
+    def reduce_option_parser
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex reduce --command=COMMAND [options] input"
+        options.on("--command=COMMAND", "nonzero exit means the failure persists") do |value|
+          @options[:reduce_command] = value
+        end
+        options.on("--mode=MODE", %w[tokens lines bytes], "tokens, lines, or bytes") do |value|
+          @options[:reduce_mode] = value.to_sym
+        end
+        options.on("--max-trials=N", Integer, "subprocess trial budget (default 1000)") do |value|
+          @options[:reduce_max_trials] = positive_reduce_option!("max-trials", value)
+        end
+        options.on("--timeout=SECONDS", Integer, "checker timeout per trial (default 10)") do |value|
+          @options[:reduce_timeout] = positive_reduce_option!("timeout", value)
+        end
+        options.on("--max-output-bytes=N", Integer, "checker stdout/stderr byte budget") do |value|
+          @options[:reduce_max_output_bytes] = positive_reduce_option!("max-output-bytes", value)
+        end
+        options.on("--max-input-bytes=N", Integer, "input byte budget (default 10485760)") do |value|
+          @options[:reduce_max_input_bytes] = positive_reduce_option!("max-input-bytes", value)
+        end
+        options.on("--format=FORMAT", %w[json text], "json or text (default json)") do |value|
+          @options[:reduce_format] = value
+        end
+        options.on("--help", "show help") { @options[:help] = true }
+      end
+    end
+
+    # @rbs () -> void
+    def prepare_reduction_run
+      @reduction_mode = @options.fetch(:reduce_mode, :tokens)
+      @reduction_bounds = {
+        max_trials: @options.fetch(:reduce_max_trials, 1_000),
+        timeout_seconds: @options.fetch(:reduce_timeout, BoundedSubprocess::DEFAULT_TIMEOUT_SECONDS),
+        max_output_bytes: @options.fetch(
+          :reduce_max_output_bytes, BoundedSubprocess::DEFAULT_MAX_OUTPUT_BYTES
+        ),
+        max_input_bytes: @options.fetch(:reduce_max_input_bytes, DEFAULT_MAX_INPUT_BYTES)
+      }
+      @reduction_trials = 0
+      @reduction_subprocess = BoundedSubprocess.new(
+        timeout_seconds: @reduction_bounds.fetch(:timeout_seconds),
+        max_output_bytes: @reduction_bounds.fetch(:max_output_bytes)
+      )
+    end
+
+    # @rbs (String path) -> String
+    def bounded_reduction_source(path)
+      maximum = @reduction_bounds.fetch(:max_input_bytes)
+      source = File.binread(path, maximum + 1)
+      return source if source.bytesize <= maximum
+
+      raise ReductionBudgetExceeded.new(
+        kind: "input_bytes", message: "input exceeds #{maximum} bytes", trials: 0
+      )
+    end
+
+    # @rbs (String source, Symbol mode) -> Array[String | Integer]
+    def reduction_items(source, mode)
+      case mode
+      when :tokens
+        parsed = JSON.parse(source)
+        raise Ibex::Error, "(reduce):1:1: token input must be a JSON array" unless parsed.is_a?(Array)
+        raise Ibex::Error, "(reduce):1:1: every token must be a string" unless parsed.all?(String)
+
+        parsed
+      when :lines then source.lines
+      when :bytes then source.bytes
+      else raise Ibex::Error, "(reduce):1:1: unknown reduction mode #{mode.inspect}"
+      end
+    rescue JSON::ParserError => e
+      raise Ibex::Error, "(reduce):1:1: invalid token JSON: #{e.message}"
+    end
+
+    # @rbs (Array[String] command, Array[String | Integer] candidate, Symbol mode) -> bool
+    def reduction_failure?(command, candidate, mode)
+      input = case mode
+              when :tokens then JSON.generate(candidate)
+              when :lines then candidate.join
+              when :bytes then candidate.pack("C*")
+              else raise Ibex::Error, "(reduce):1:1: unknown reduction mode #{mode.inspect}"
+              end
+      @reduction_trials += 1
+      result = @reduction_subprocess.run(command, input: input)
+      if result.timed_out || result.output_limited
+        kind = result.timed_out ? "subprocess_timeout" : "subprocess_output"
+        message = result.timed_out ? "checker timed out" : "checker exceeded its output byte budget"
+        raise ReductionBudgetExceeded.new(kind: kind, message: message, trials: @reduction_trials)
+      end
+      unless result.status.exited?
+        raise Ibex::Error, "(reduce):1:1: checker terminated by signal #{result.status.termsig}"
+      end
+
+      !result.status.success?
+    end
+
+    # @rbs (String name, Integer value) -> Integer
+    def positive_reduce_option!(name, value)
+      return value if value.positive?
+
+      raise OptionParser::InvalidArgument, "--#{name} must be positive"
+    end
+  end
+end

data/lib/ibex/cli/reduce_reporting.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  # Versioned machine and terminal reports for bounded delta reduction.
+  module CLIReduceReporting
+    # @rbs @reduction_mode: Symbol
+    # @rbs @reduction_bounds: reduction_bounds
+
+    private
+
+    # @rbs (DeltaReducer::Result result) -> reduction_success_document
+    def reduction_success_report(result)
+      items = result.items #: Array[String | Integer]
+      {
+        ibex_report: "reduce", schema_version: 2,
+        result: result.complete ? "minimized" : "incomplete",
+        mode: @reduction_mode, original_size: result.original_size,
+        minimized_size: items.length, trials: result.trials,
+        complete: result.complete, minimized: items, bounded: true,
+        bounds: @reduction_bounds
+      }
+    end
+
+    # @rbs (reduction_budget_details details) -> reduction_budget_document
+    def reduction_budget_report(details)
+      {
+        ibex_report: "reduce", schema_version: 2, result: "budget_exhausted",
+        mode: @reduction_mode || @options.fetch(:reduce_mode, :tokens),
+        bounded: true, bounds: @reduction_bounds || default_reduction_bounds,
+        budget: details
+      }
+    end
+
+    # @rbs () -> reduction_bounds
+    def default_reduction_bounds
+      {
+        max_trials: @options.fetch(:reduce_max_trials, 1_000),
+        timeout_seconds: @options.fetch(:reduce_timeout, BoundedSubprocess::DEFAULT_TIMEOUT_SECONDS),
+        max_output_bytes: @options.fetch(
+          :reduce_max_output_bytes, BoundedSubprocess::DEFAULT_MAX_OUTPUT_BYTES
+        ),
+        max_input_bytes: @options.fetch(:reduce_max_input_bytes, CLIReduce::DEFAULT_MAX_INPUT_BYTES)
+      }
+    end
+
+    # @rbs (reduction_success_document report) -> void
+    def write_reduction_success(report)
+      if @options.fetch(:reduce_format, "json") == "json"
+        @stdout.puts JSON.pretty_generate(report)
+        return
+      end
+
+      @stdout.puts("result=#{report[:result]}")
+      @stdout.puts("mode=#{report[:mode]} original_size=#{report[:original_size]} " \
+                   "minimized_size=#{report[:minimized_size]} trials=#{report[:trials]}")
+      @stdout.puts("minimized=#{report[:minimized].inspect}")
+    end
+
+    # @rbs (reduction_budget_document report) -> void
+    def write_reduction_budget(report)
+      if @options.fetch(:reduce_format, "json") == "json"
+        @stdout.puts JSON.pretty_generate(report)
+        return
+      end
+
+      @stdout.puts("result=#{report[:result]}")
+      @stdout.puts("budget=#{report[:budget].inspect}")
+    end
+  end
+end

data/lib/ibex/cli/samples.rb

@@ -13,6 +13,7 @@ module Ibex
     #   private def handle_grammar_warnings: (IR::Grammar, String) -> void
     #   private def warning_categories: (String) -> Array[Symbol]
     #   private def normalize_grammar_path: (String) -> IR::Grammar
+    #   private def set_configuration_option: (Symbol, Object?) -> void
 
     private
 
@@ -30,7 +31,9 @@ module Ibex
         seed: @options.fetch(:sample_seed, 0),
         max_tokens: @options.fetch(:sample_max_tokens, 32),
         max_depth: @options.fetch(:sample_max_depth, 16),
-        max_expansions: @options.fetch(:sample_max_expansions, Samples::DEFAULT_MAX_EXPANSIONS)
+        max_expansions: @options.fetch(:sample_max_expansions, Samples::DEFAULT_MAX_EXPANSIONS),
+        strategy: @options.fetch(:sample_strategy, :random),
+        path_length: @options.fetch(:sample_path_length, 1)
       )
       generator.generate(count: @options.fetch(:sample_count, 5)).each do |sample|
         @stdout.puts(JSON.generate(sample))
@@ -42,32 +45,55 @@ module Ibex
     def samples_option_parser
       OptionParser.new do |options|
         options.banner = "Usage: ibex samples [options] grammarfile"
-        options.on("--count=N", Integer, "number of samples (default 5)") do |value|
-          @options[:sample_count] = positive_sample_option!("count", value)
-        end
-        options.on("--seed=N", Integer, "deterministic random seed (default 0)") do |value|
-          @options[:sample_seed] = value
-        end
-        options.on("--max-tokens=N", Integer, "maximum tokens per sample (default 32)") do |value|
-          @options[:sample_max_tokens] = positive_sample_option!("max-tokens", value)
-        end
-        options.on("--max-depth=N", Integer, "random expansion depth (default 16)") do |value|
-          @options[:sample_max_depth] = positive_sample_option!("max-depth", value)
-        end
-        options.on("--max-expansions=N", Integer, "total expansion steps (default 100000)") do |value|
-          @options[:sample_max_expansions] = positive_sample_option!("max-expansions", value)
-        end
-        options.on("--from=FORMAT", %w[grammar-ir automaton-ir], "read versioned IR JSON") do |value|
-          @options[:from] = value
-        end
-        options.on("--mode=MODE", %w[default extended], "grammar mode") { |value| @options[:mode] = value.to_sym }
-        options.on("--warnings=CATEGORIES", "all, error, all,error, or none") do |value|
-          @options[:warnings] = warning_categories(value)
-        end
+        add_sample_generation_options(options)
+        add_sample_input_options(options)
         options.on("--help", "show help") { @options[:help] = true }
       end
     end
 
+    # @rbs (OptionParser options) -> void
+    def add_sample_generation_options(options)
+      options.on("--count=N", Integer, "number of samples (default 5)") do |value|
+        @options[:sample_count] = positive_sample_option!("count", value)
+      end
+      options.on("--seed=N", Integer, "deterministic random seed (default 0)") do |value|
+        @options[:sample_seed] = value
+      end
+      options.on("--max-tokens=N", Integer, "maximum tokens per sample (default 32)") do |value|
+        @options[:sample_max_tokens] = positive_sample_option!("max-tokens", value)
+      end
+      options.on("--max-depth=N", Integer, "random expansion depth (default 16)") do |value|
+        @options[:sample_max_depth] = positive_sample_option!("max-depth", value)
+      end
+      options.on("--max-expansions=N", Integer, "total expansion steps (default 100000)") do |value|
+        @options[:sample_max_expansions] = positive_sample_option!("max-expansions", value)
+      end
+      options.on(
+        "--strategy=NAME", %w[random coverage],
+        "random or coverage-oriented production selection"
+      ) do |value|
+        @options[:sample_strategy] = value.to_sym
+      end
+      options.on("--path-length=N", Integer, "coverage path length: 1 or 2") do |value|
+        raise OptionParser::InvalidArgument, "--path-length must be 1 or 2" unless [1, 2].include?(value)
+
+        @options[:sample_path_length] = value
+      end
+    end
+
+    # @rbs (OptionParser options) -> void
+    def add_sample_input_options(options)
+      options.on("--from=FORMAT", %w[grammar-ir automaton-ir], "read current IR JSON") do |value|
+        @options[:from] = value
+      end
+      options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+        set_configuration_option(:mode, value.to_sym)
+      end
+      options.on("--warnings=CATEGORIES", "all, error, all,error, or none") do |value|
+        @options[:warnings] = warning_categories(value)
+      end
+    end
+
     # @rbs (String path) -> IR::Grammar
     def grammar_for_samples(path)
       return normalize_grammar_path(path) unless @options[:from]

data/lib/ibex/cli/verify.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "optparse"
+require_relative "../verify"
+require_relative "../ir"
+
+module Ibex
+  # CLI entry point for bounded, independent Automaton IR verification.
+  module CLIVerify
+    # @rbs!
+    #   type verify_options = {
+    #     paths: Array[String],
+    #     strict: bool,
+    #     max_states: Integer,
+    #     max_items: Integer,
+    #     ?grammar: String,
+    #     format: String,
+    #     ?help: String
+    #   }
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_verify_command(arguments)
+      settings = verify_options(arguments)
+      if settings[:help]
+        @stdout.puts(settings.fetch(:help))
+        return 0
+      end
+      operands = settings.fetch(:paths)
+      raise Ibex::Error, "(verify):1:1: verify requires exactly one Automaton IR file" unless operands.length == 1
+
+      automaton = load_verify_automaton(operands.fetch(0))
+      verify_supplied_grammar!(automaton, settings[:grammar]) if settings[:grammar]
+      result = Verify::Verifier.new(
+        automaton,
+        strict: settings.fetch(:strict),
+        max_states: settings.fetch(:max_states),
+        max_items: settings.fetch(:max_items)
+      ).verify
+      write_verify_result(result, settings.fetch(:format))
+      result.valid? ? 0 : 1
+    rescue Verify::BudgetExceeded => e
+      violations = [] #: Array[Verify::Violation]
+      report = {
+        ibex_report: "verify", schema_version: 1, result: "budget_exhausted",
+        strict: settings&.fetch(:strict, false), bounds: e.bounds, violations: violations
+      }
+      @stdout.puts(JSON.pretty_generate(report))
+      2
+    end
+
+    # @rbs (Array[String] arguments) -> verify_options
+    def verify_options(arguments)
+      settings = {
+        paths: [], strict: false, max_states: 100_000, max_items: 1_000_000, format: "json"
+      } #: verify_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex verify [options] AUTOMATON.json"
+        options.on("--strict", "include completeness and table-bisimulation checks") { settings[:strict] = true }
+        options.on("--grammar=GRAMMAR", "require an exact embedded Grammar IR match") do |value|
+          settings[:grammar] = value
+        end
+        options.on("--max-states=N", Integer, "maximum independently derived states") do |value|
+          settings[:max_states] = positive_verify_budget(value, "max-states")
+        end
+        options.on("--max-items=N", Integer, "maximum independently derived items") do |value|
+          settings[:max_items] = positive_verify_budget(value, "max-items")
+        end
+        options.on("--format=FORMAT", %w[json text], "json or text") { |value| settings[:format] = value }
+        options.on("--help", "show help") { settings[:help] = options.to_s }
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings
+    end
+
+    # @rbs (String path) -> IR::Automaton
+    def load_verify_automaton(path)
+      value = IR::Validator.validate(File.binread(path))
+      return value if value.is_a?(IR::Automaton)
+
+      raise Ibex::Error, "#{path}:1:1: verify requires Automaton IR"
+    end
+
+    # @rbs (IR::Automaton automaton, String path) -> void
+    def verify_supplied_grammar!(automaton, path)
+      value = IR::Validator.validate(File.binread(path))
+      raise Ibex::Error, "#{path}:1:1: --grammar requires Grammar IR" unless value.is_a?(IR::Grammar)
+      return if IR::Serialize.dump(value) == IR::Serialize.dump(automaton.grammar)
+
+      raise Ibex::Error, "#{path}:1:1: Grammar IR does not match the automaton's embedded grammar"
+    end
+
+    # @rbs (Verify::Result result, String format) -> void
+    def write_verify_result(result, format)
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(result.to_h))
+        return
+      end
+
+      @stdout.puts("result=#{result.valid? ? 'valid' : 'invalid'} algorithm=#{result.algorithm}")
+      result.violations.each do |violation|
+        @stdout.puts("#{violation.id} #{violation.location}: #{violation.message}")
+      end
+    end
+
+    # @rbs (Integer value, String name) -> Integer
+    def positive_verify_budget(value, name)
+      return value if value.positive?
+
+      raise OptionParser::InvalidArgument, "--#{name} must be positive"
+    end
+  end
+end

data/lib/ibex/cli/watch.rb

@@ -70,20 +70,21 @@ module Ibex
       @defer_generation_publication = false
     end
 
-    # @rbs (Build build, Watch::SourceSnapshot snapshot, ^() -> bool continue) -> void
+    # @rbs (Watch::_BuildResult build, Watch::SourceSnapshot snapshot, ^() -> bool continue) -> void
     def publish_watch_generation(build, snapshot, continue)
+      typed_build = build #: Build
       stable = lambda do
-        continue.call && build.source_records.all?(&:current?) &&
+        continue.call && typed_build.source_records.all?(&:current?) &&
           Watch::SourceSnapshot.new(snapshot.paths) == snapshot
       end
       GenerationTransaction.new(
-        build.artifacts,
+        typed_build.artifacts,
         warning: ->(message) { @stderr.puts("ibex: warning: #{message}") },
         stability_check: stable,
-        source_records: build.source_records,
+        source_records: typed_build.source_records,
         lock_sleeper: @watch_sleeper
       ).commit
-      build.statuses.each { |message| report_status(message) }
+      typed_build.statuses.each { |message| report_status(message) }
     end
 
     # @rbs (String path) -> Array[String]