ibex 0.1.0 → 0.2.0

data/examples/tiny_language.y

@@ -0,0 +1,75 @@
+class Examples::TinyLanguageParser
+pragma extended
+token IDENTIFIER NUMBER PRINT
+%test accept "value=1+2*3; print value;"
+%test accept "value=(8-2)/3;"
+%test reject "print ;"
+rule
+  program    : statements { result = val[0] }
+  statements : statements statement { result = val[0] + [val[1]] }
+             | { result = [] }
+  statement  : IDENTIFIER '=' expression ';' { result = [:assign, val[0], val[2]] }
+             | PRINT expression ';' { result = [:print, val[1]] }
+  expression : expression '+' term { result = [:add, val[0], val[2]] }
+             | expression '-' term { result = [:subtract, val[0], val[2]] }
+             | term { result = val[0] }
+  term       : term '*' factor { result = [:multiply, val[0], val[2]] }
+             | term '/' factor { result = [:divide, val[0], val[2]] }
+             | factor { result = val[0] }
+  factor     : NUMBER { result = [:number, val[0]] }
+             | IDENTIFIER { result = [:variable, val[0]] }
+             | '(' expression ')' { result = val[1] }
+end
+---- header
+require "strscan"
+---- inner
+def parse(source)
+  @scanner = StringScanner.new(source)
+  do_parse
+end
+
+def next_token
+  @scanner.skip(/\s+/)
+  return false if @scanner.eos?
+
+  if @scanner.scan(/print\b/)
+    [:PRINT, "print"]
+  elsif (identifier = @scanner.scan(/[A-Za-z_][A-Za-z0-9_]*/))
+    [:IDENTIFIER, identifier]
+  elsif (number = @scanner.scan(/\d+/))
+    [:NUMBER, Integer(number, 10)]
+  elsif (punctuation = @scanner.scan(/[=;()+*\/-]/))
+    [punctuation, nil]
+  else
+    raise ArgumentError, "unexpected language input at offset #{@scanner.pos}"
+  end
+end
+
+def execute(statements, output: $stdout)
+  environment = {}
+  statements.each do |statement|
+    case statement[0]
+    when :assign
+      environment[statement[1]] = evaluate_expression(statement[2], environment)
+    when :print
+      output.puts(evaluate_expression(statement[1], environment))
+    end
+  end
+  environment
+end
+
+def evaluate_expression(expression, environment)
+  case expression[0]
+  when :number then expression[1]
+  when :variable then environment.fetch(expression[1])
+  when :add then evaluate_expression(expression[1], environment) + evaluate_expression(expression[2], environment)
+  when :subtract then evaluate_expression(expression[1], environment) - evaluate_expression(expression[2], environment)
+  when :multiply then evaluate_expression(expression[1], environment) * evaluate_expression(expression[2], environment)
+  when :divide then evaluate_expression(expression[1], environment) / evaluate_expression(expression[2], environment)
+  end
+end
+---- footer
+if $PROGRAM_NAME == __FILE__
+  parser = Examples::TinyLanguageParser.new
+  parser.execute(parser.parse(ARGF.read))
+end

data/lib/ibex/analysis/sets.rb

@@ -104,11 +104,12 @@ module Ibex
 
       # @rbs () -> void
       def compute_follow
-        start_definition = @grammar.symbol(@grammar.start)
-        raise Ibex::Error, "(analysis):1:1: unknown start symbol #{@grammar.start}" unless start_definition
+        @grammar.starts.each do |name|
+          start_definition = @grammar.symbol(name)
+          raise Ibex::Error, "(analysis):1:1: unknown start symbol #{name}" unless start_definition
 
-        start_id = start_definition.id
-        @follow_bits[start_id] |= bit(0)
+          @follow_bits[start_definition.id] |= bit(0)
+        end
         dependencies = Array.new(@grammar.symbols.length) { [] }
         @grammar.productions.each { |production| initialize_follow(production, dependencies) }
         seeds = @grammar.nonterminals.filter_map { |symbol| symbol.id unless @follow_bits[symbol.id].zero? }

data/lib/ibex/artifact_set.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  # One fully rendered file in a parser generation.
+  class Artifact
+    attr_reader :kind #: Symbol
+    attr_reader :path #: String
+    attr_reader :content #: String
+    attr_reader :mode #: Integer?
+
+    # @rbs (kind: Symbol, path: String, content: String, ?mode: Integer?) -> void
+    def initialize(kind:, path:, content:, mode: nil)
+      raise ArgumentError, "artifact path must not be empty" if path.empty?
+
+      @kind = kind
+      @path = path.dup.freeze
+      @content = content.dup.freeze
+      @mode = mode
+      freeze
+    end
+  end
+
+  # A generation's rendered outputs before any target is changed.
+  class ArtifactSet
+    # @rbs! include Enumerable[Artifact]
+    # @rbs skip
+    include Enumerable
+
+    # @rbs () -> void
+    def initialize
+      @artifacts = [] #: Array[Artifact]
+    end
+
+    # @rbs (kind: Symbol, path: String, content: String, ?mode: Integer?) -> Artifact
+    def add(kind:, path:, content:, mode: nil)
+      artifact = Artifact.new(kind: kind, path: path, content: content, mode: mode)
+      @artifacts << artifact
+      artifact
+    end
+
+    # @rbs!
+    #   def each: () -> Enumerator[Artifact, ArtifactSet]
+    #           | () { (Artifact) -> void } -> ArtifactSet
+    # @rbs skip
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @artifacts.each(&block)
+      self
+    end
+
+    # @rbs () -> Array[Artifact]
+    def to_a
+      @artifacts.dup
+    end
+
+    # @rbs () -> bool
+    def empty?
+      @artifacts.empty?
+    end
+  end
+end

data/lib/ibex/cli/ambiguity.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../codegen/ambiguity"
+
+module Ibex
+  # Bounded grammar ambiguity checking for CI and human inspection.
+  module CLIAmbiguity
+    # @rbs!
+    #   private def print_help: (OptionParser) -> Integer
+    #   private def input_path: (Array[String]) -> String
+    #   private def positive_counterexample_limit: (Integer, String) -> Integer
+    #   private def normalize_grammar_path: (String) -> IR::Grammar
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_check_command(arguments)
+      parser = ambiguity_option_parser
+      remaining = parser.parse(arguments)
+      return print_help(parser) if @options[:help]
+      raise Ibex::Error, "(cli):1:1: check command requires --ambiguity" unless @options[:check_ambiguity]
+
+      grammar = normalize_grammar_path(input_path(remaining))
+      automaton = LALR::Builder.new(
+        grammar, algorithm: @options[:algorithm] || :lalr, entry_isolation: @options[:entry_isolation] == true
+      ).build
+      check = Codegen::Ambiguity.new(
+        automaton,
+        max_tokens: @options.fetch(:counterexample_max_tokens),
+        max_configurations: @options.fetch(:counterexample_max_configurations)
+      )
+      output = @options[:check_format] == "json" ? JSON.pretty_generate(check.to_h) : check.render_text
+      @stdout.puts(output)
+      check.exit_status
+    end
+
+    # @rbs () -> OptionParser
+    def ambiguity_option_parser
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex check --ambiguity [options] grammarfile"
+        options.on("--ambiguity", "search parser conflicts for ambiguous sentences") do
+          @options[:check_ambiguity] = true
+        end
+        options.on("--max-tokens=N", Integer, "maximum sentence length (default: 32)") do |value|
+          @options[:counterexample_max_tokens] = positive_counterexample_limit(value, "--max-tokens")
+        end
+        options.on("--max-configurations=N", Integer, "maximum configurations per conflict (default: 50000)") do |value|
+          @options[:counterexample_max_configurations] = positive_counterexample_limit(value, "--max-configurations")
+        end
+        options.on("--format=FORMAT", %w[text json], "text or json (default: text)") do |value|
+          @options[:check_format] = value
+        end
+        options.on("--algorithm=NAME", %w[slr lalr ielr lr1], "parser construction algorithm") do |value|
+          @options[:algorithm] = value.to_sym
+        end
+        options.on("--entry-isolation", "build independent state sets for each start symbol") do
+          @options[:entry_isolation] = true
+        end
+        options.on("--mode=MODE", %w[default extended], "grammar mode") { |value| @options[:mode] = value.to_sym }
+        options.on("--help", "show help") { @options[:help] = true }
+      end
+    end
+  end
+end

data/lib/ibex/cli/counterexample_options.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../lalr/conflict_search_limits"
+
 module Ibex
   # Counterexample report limits and their command-line validation.
   module CLICounterexampleOptions
+    # @rbs @options: cli_options
+
     DEFAULTS = {
-      counterexample_max_tokens: LALR::Counterexample::DEFAULT_MAX_TOKENS,
-      counterexample_max_configurations: LALR::Counterexample::DEFAULT_MAX_CONFIGURATIONS
+      counterexample_max_tokens: LALR::ConflictSearchLimits::DEFAULT_MAX_TOKENS,
+      counterexample_max_configurations: LALR::ConflictSearchLimits::DEFAULT_MAX_CONFIGURATIONS
     }.freeze #: Hash[Symbol, Integer]
 
     private

data/lib/ibex/cli/coverage.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "tempfile"
+require_relative "../coverage"
+
+module Ibex
+  # CLI collection, merge, and threshold checks for runtime coverage.
+  module CLICoverage
+    # @rbs!
+    #   private def same_file_target?: (String left, String right) -> bool
+    #
+    #   type coverage_output_options = {
+    #     paths: Array[String],
+    #     ?output: String
+    #   }
+    #   type coverage_check_options = {
+    #     paths: Array[String],
+    #     min_states: Float,
+    #     min_productions: Float
+    #   }
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_command(arguments)
+      operation = arguments.shift
+      case operation
+      when "collect" then run_coverage_collect(arguments)
+      when "merge" then run_coverage_merge(arguments)
+      when "check" then run_coverage_check(arguments)
+      else
+        raise Ibex::Error, "(cli):1:1: coverage requires collect, merge, or check"
+      end
+    end
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_collect(arguments)
+      settings = coverage_output_options(arguments, "collect", "INPUT")
+      input = single_coverage_path(settings.fetch(:paths), "coverage collect")
+      reject_coverage_output_collision([input], settings[:output])
+      report = Coverage::Collector.collect_file(input)
+      write_coverage_report(report, settings[:output])
+      0
+    end
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_merge(arguments)
+      settings = coverage_output_options(arguments, "merge", "INPUT...")
+      inputs = settings.fetch(:paths)
+      raise Ibex::Error, "(cli):1:1: coverage merge requires at least one input" if inputs.empty?
+
+      reject_coverage_output_collision(inputs, settings[:output])
+      reports = inputs.map { |path| Coverage::Report.load_file(path) }
+      report = Coverage::Report.merge(reports)
+      write_coverage_report(report, settings[:output])
+      0
+    rescue ArgumentError => e
+      raise Ibex::Error, "(coverage):1:1: #{e.message}"
+    end
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_coverage_check(arguments)
+      settings = coverage_check_options(arguments)
+      path = single_coverage_path(settings.fetch(:paths), "coverage check")
+      report = Coverage::Report.load_file(path)
+      state_percentage = coverage_percentage(report.state_hits.length, report.state_count)
+      production_percentage = coverage_percentage(report.production_hits.length, report.production_count)
+      passed = state_percentage >= settings.fetch(:min_states) &&
+               production_percentage >= settings.fetch(:min_productions)
+      summary = format(
+        "coverage %<status>s: states %<states>.2f%% (%<state_hits>d/%<state_total>d), " \
+        "productions %<productions>.2f%% (%<production_hits>d/%<production_total>d)",
+        status: passed ? "ok" : "failed",
+        states: state_percentage,
+        state_hits: report.state_hits.length,
+        state_total: report.state_count,
+        productions: production_percentage,
+        production_hits: report.production_hits.length,
+        production_total: report.production_count
+      )
+      (passed ? @stdout : @stderr).puts(summary)
+      passed ? 0 : 1
+    end
+
+    # @rbs (Array[String] arguments, String command, String operands) -> coverage_output_options
+    def coverage_output_options(arguments, command, operands)
+      settings = { paths: [] } #: coverage_output_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex coverage #{command} #{operands} [-o FILE]"
+        options.on("-o FILE", "--output=FILE", "write atomically to FILE") { |value| settings[:output] = value }
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings
+    end
+
+    # @rbs (Array[String] arguments) -> coverage_check_options
+    def coverage_check_options(arguments)
+      settings = { paths: [], min_states: 0.0, min_productions: 0.0 } #: coverage_check_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex coverage check REPORT [thresholds]"
+        options.on("--min-states=PERCENT", Float, "minimum visited states") do |value|
+          settings[:min_states] = coverage_threshold(value, "min-states")
+        end
+        options.on("--min-productions=PERCENT", Float, "minimum reduced productions") do |value|
+          settings[:min_productions] = coverage_threshold(value, "min-productions")
+        end
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings
+    end
+
+    # @rbs (Float value, String name) -> Float
+    def coverage_threshold(value, name)
+      return value if value.finite? && value >= 0.0 && value <= 100.0
+
+      raise OptionParser::InvalidArgument, "--#{name} must be between 0 and 100"
+    end
+
+    # @rbs (Integer covered, Integer total) -> Float
+    def coverage_percentage(covered, total)
+      return 100.0 if total.zero?
+
+      covered.fdiv(total) * 100.0
+    end
+
+    # @rbs (Array[String] arguments, String command) -> String
+    def single_coverage_path(arguments, command)
+      return arguments.first if arguments.length == 1
+
+      raise Ibex::Error, "(cli):1:1: #{command} requires exactly one input"
+    end
+
+    # @rbs (Array[String] inputs, String? output) -> void
+    def reject_coverage_output_collision(inputs, output)
+      return unless output
+      return unless inputs.any? { |input| same_file_target?(input, output) }
+
+      raise Ibex::Error, "(cli):1:1: coverage input and output paths must be distinct"
+    end
+
+    # @rbs (Coverage::Report report, String? output) -> void
+    def write_coverage_report(report, output)
+      source = report.to_json
+      return @stdout.write(source) unless output
+
+      atomic_write_coverage(output, source)
+    end
+
+    # @rbs (String path, String source) -> void
+    def atomic_write_coverage(path, source)
+      target_path = File.symlink?(path) ? File.realpath(path) : path
+      directory = File.dirname(File.expand_path(target_path))
+      basename = File.basename(target_path)
+      Tempfile.create([".#{basename}.", ".tmp"], directory) do |temporary|
+        temporary.binmode
+        temporary.write(source)
+        temporary.flush
+        temporary.fsync
+        temporary.chmod(coverage_file_mode(target_path))
+        temporary.close
+        File.rename(temporary.path, target_path)
+      end
+    end
+
+    # @rbs (String path) -> Integer
+    def coverage_file_mode(path)
+      return File.stat(path).mode & 0o777 if File.exist?(path)
+
+      0o666 & ~File.umask
+    end
+  end
+end

data/lib/ibex/cli/debug.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "optparse"
+require_relative "../table_simulation"
+
+module Ibex
+  # Safe parser-table simulation subcommand.
+  module CLIDebug
+    # @rbs!
+    #   type debug_options = {
+    #     paths: Array[String],
+    #     format: String,
+    #     max_steps: Integer,
+    #     max_stack: Integer
+    #   }
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_debug_command(arguments)
+      settings = debug_options(arguments)
+      operands = settings.fetch(:paths)
+      raise Ibex::Error, "(cli):1:1: debug requires an Automaton IR file" if operands.empty?
+
+      path = operands.first
+      value = IR::Validator.validate(File.read(path))
+      raise Ibex::Error, "#{path}:1:1: debug requires Automaton IR" unless value.is_a?(IR::Automaton)
+
+      simulator = TableSimulation::Simulator.new(
+        value,
+        max_steps: settings.fetch(:max_steps),
+        max_stack: settings.fetch(:max_stack)
+      )
+      tokens = operands.drop(1)
+      interactive = tokens.empty?
+      format = settings.fetch(:format)
+      result = interactive ? simulate_debug_input(simulator, format) : simulator.simulate(tokens)
+      write_debug_result(result, format, steps_written: interactive && format == "text")
+      result.status == :accepted ? 0 : 1
+    rescue ArgumentError => e
+      raise Ibex::Error, "(debug):1:1: #{e.message}"
+    end
+
+    # @rbs (Array[String] arguments) -> debug_options
+    def debug_options(arguments)
+      settings = {
+        paths: [],
+        format: "text",
+        max_steps: TableSimulation::Simulator::DEFAULT_MAX_STEPS,
+        max_stack: TableSimulation::Simulator::DEFAULT_MAX_STACK
+      } #: debug_options
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex debug AUTOMATON.json [TOKEN...]"
+        options.on("--format=FORMAT", %w[text json], "text or json") { |value| settings[:format] = value }
+        options.on("--max-steps=N", Integer, "maximum simulated actions") do |value|
+          settings[:max_steps] = positive_debug_budget(value, "max-steps")
+        end
+        options.on("--max-stack=N", Integer, "maximum simulated state stack depth") do |value|
+          settings[:max_stack] = positive_debug_budget(value, "max-stack")
+        end
+      end
+      settings[:paths] = parser.parse(arguments)
+      settings
+    end
+
+    # @rbs (Integer value, String name) -> Integer
+    def positive_debug_budget(value, name)
+      return value if value.positive?
+
+      raise OptionParser::InvalidArgument, "--#{name} must be positive"
+    end
+
+    # @rbs (TableSimulation::Simulator simulator, String format) -> TableSimulation::Result
+    def simulate_debug_input(simulator, format)
+      session = simulator.start
+      while (line = @stdin.gets)
+        spelling = line.strip
+        break if spelling.empty?
+
+        steps = session.push(spelling)
+        write_debug_steps(steps) if format == "text"
+        break if session.status
+      end
+      written = session.steps.length
+      result = session.finish
+      write_debug_steps(result.steps.drop(written)) if format == "text"
+      result
+    end
+
+    # @rbs (TableSimulation::Result result, String format, steps_written: bool) -> void
+    def write_debug_result(result, format, steps_written:)
+      if format == "json"
+        @stdout.write(result.to_json)
+      else
+        write_debug_steps(result.steps) unless steps_written
+        @stdout.puts("status=#{result.status}")
+      end
+    end
+
+    # @rbs (Array[TableSimulation::Step] steps) -> void
+    def write_debug_steps(steps)
+      steps.each { |step| @stdout.puts(TableSimulation::Text.render_step(step)) }
+    end
+  end
+end

data/lib/ibex/cli/diagnostics.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../frontend"
+
+module Ibex
+  # Batch frontend diagnostics subcommand.
+  module CLIDiagnostics
+    DIAGNOSTICS_SCHEMA_VERSION = 1 #: Integer
+    DEFAULT_MAX_DIAGNOSTICS = 20 #: Integer
+
+    # @rbs!
+    #   type diagnostic_settings = {
+    #     format: String,
+    #     max_diagnostics: Integer,
+    #     mode: Symbol,
+    #     ?help: bool
+    #   }
+    #
+    #   private def input_path: (Array[String]) -> String
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_diagnose_command(arguments)
+      settings = {
+        format: "text", max_diagnostics: DEFAULT_MAX_DIAGNOSTICS, mode: :default
+      } #: diagnostic_settings
+      parser = diagnostics_option_parser(settings)
+      remaining = parser.parse(arguments)
+      if settings[:help]
+        @stdout.puts(parser)
+        return 0
+      end
+
+      path = input_path(remaining)
+      result = Frontend::Parser.new(File.binread(path), file: path, mode: settings.fetch(:mode))
+                               .parse_with_diagnostics(max_diagnostics: settings.fetch(:max_diagnostics))
+      result = resolve_diagnostic_result(result, path, settings.fetch(:mode)) if result.success?
+      write_diagnostics(result, format: settings.fetch(:format))
+      result.success? ? 0 : 1
+    end
+
+    # Cross-file recovery is deliberately bounded to the first resolver error.
+    # @rbs (Frontend::ParseResult result, String path, Symbol mode) -> Frontend::ParseResult
+    def resolve_diagnostic_result(result, path, mode)
+      Frontend::Resolver.new(path, mode: mode).resolve
+      result
+    rescue Frontend::ResolutionIOError
+      raise
+    rescue Ibex::Error => e
+      Frontend::ParseResult.new(diagnostics: [resolution_diagnostic(e, path)], ast: nil, document: nil)
+    end
+
+    # @rbs (Ibex::Error error, String fallback_file) -> Frontend::Diagnostic
+    def resolution_diagnostic(error, fallback_file)
+      match = error.message.match(/\A(.+):(\d+):(\d+): (.*)\z/m)
+      location = if match
+                   Frontend::Location.new(
+                     file: match[1].to_s, line: Integer(match[2].to_s), column: Integer(match[3].to_s)
+                   )
+                 else
+                   Frontend::Location.new(file: fallback_file, line: 1, column: 1)
+                 end
+      message = match ? match[4].to_s : error.message
+      Frontend::Diagnostic.new(
+        code: "frontend.resolution_error", phase: :syntax, message: message,
+        location: location, rendered: error.message
+      )
+    end
+
+    # @rbs (diagnostic_settings settings) -> OptionParser
+    def diagnostics_option_parser(settings)
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex diagnose [options] grammarfile"
+        options.on("--format=FORMAT", %w[text json], "text or json") { |value| settings[:format] = value }
+        options.on("--max-diagnostics=N", "positive diagnostic limit") do |value|
+          settings[:max_diagnostics] = positive_diagnostic_limit(value)
+        end
+        options.on("--mode=MODE", %w[default extended], "grammar mode") { |value| settings[:mode] = value.to_sym }
+        options.on("--help", "show help") { settings[:help] = true }
+      end
+    end
+
+    # @rbs (String value) -> Integer
+    def positive_diagnostic_limit(value)
+      limit = Integer(value, 10)
+      return limit if limit.positive?
+
+      raise OptionParser::InvalidArgument, "max diagnostics must be positive"
+    rescue ArgumentError
+      raise OptionParser::InvalidArgument, "max diagnostics must be a positive integer"
+    end
+
+    # @rbs (Frontend::ParseResult result, format: String) -> void
+    def write_diagnostics(result, format:)
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(diagnostics_document(result)))
+      else
+        result.diagnostics.each { |diagnostic| @stdout.puts(diagnostic.to_s) }
+      end
+    end
+
+    # @rbs (Frontend::ParseResult result) -> Hash[String, untyped]
+    def diagnostics_document(result)
+      {
+        "ibex_diagnostics" => "frontend",
+        "schema_version" => DIAGNOSTICS_SCHEMA_VERSION,
+        "success" => result.success?,
+        "ast_available" => !result.ast.nil?,
+        "diagnostics" => result.diagnostics.map(&:to_h)
+      }
+    end
+  end
+end