ibex 0.1.0 → 0.3.0

data/lib/ibex/cli/fix.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "optparse"
+require_relative "../fix"
+
+module Ibex
+  # CLI entry point for bounded conflict-repair proposals.
+  # rubocop:disable Metrics/ModuleLength -- CLI option wiring and output projections share one closed contract.
+  module CLIFix
+    # @rbs!
+    #   type fix_options = Hash[Symbol, untyped]
+    #   private def normalize_grammar_path: (String) -> IR::Grammar
+    #   private def activate_cli_feature: (Symbol) -> void
+    #   private def configuration_value: (String) -> untyped
+    #   private def set_configuration_option: (Symbol, Object?) -> void
+    #   private def local_configuration_value: (Hash[Symbol, Object?], String) -> Object?
+    #   private def set_local_configuration_option: (Hash[Symbol, Object?], Symbol, Object?) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_fix_command(arguments)
+      settings = fix_options(arguments)
+      if settings[:help]
+        @stdout.puts(settings.fetch(:help))
+        return 0
+      end
+      paths = settings.fetch(:paths)
+      raise Ibex::Error, "(fix):1:1: fix requires exactly one grammar source file" unless paths.length == 1
+
+      path = paths.fetch(0)
+      source, fixer = prepare_fixer(path, settings)
+      report = fixer.run
+      apply_fix!(path, source, report, fixer, settings.fetch(:apply)) if settings[:apply]
+      write_fix_report(report, settings.fetch(:format))
+      proposals = report.fetch(:proposals) #: Array[Hash[Symbol, untyped]]
+      proposals.empty? ? 1 : 0
+    rescue Fix::BudgetExceeded => e
+      report = { ibex_report: "fix", schema_version: Fix::SCHEMA_VERSION }.merge(e.details)
+      write_fix_report(report, settings&.fetch(:format) || "json")
+      2
+    end
+
+    # @rbs (String path, Hash[Symbol, untyped] settings) -> [String, Fix]
+    def prepare_fixer(path, settings)
+      source = File.binread(path)
+      if BisonImport.bison_source?(source)
+        imported = BisonImport::Importer.new(source, file: path).run
+        unless imported.structurally_complete?
+          names = imported.structural_unsupported.map(&:name).uniq.sort.join(", ")
+          raise Ibex::Error,
+                "(fix):1:1: Bison import is structurally incomplete due to: #{names}"
+        end
+        raise Ibex::Error,
+              "(fix):1:1: import Bison source to a canonical analysis file before requesting source repairs"
+      end
+      grammar = normalize_grammar_path(path)
+      grammar, algorithm, automaton = fixer_construction(grammar, settings)
+      message_file = settings[:messages]
+      messages = ErrorMessages.load(message_file) if message_file
+      mode = configuration_value("grammar.mode") #: Symbol
+      fixer = Fix.new(
+        source,
+        file: path, grammar: grammar, automaton: automaton,
+        algorithm: algorithm, mode: mode,
+        state: settings[:state], conflict_index: settings[:conflict_index],
+        max_candidates: settings.fetch(:max_candidates), max_builds: settings.fetch(:max_builds),
+        equiv_samples: settings.fetch(:equiv_samples),
+        equiv_max_tokens: settings.fetch(:equiv_max_tokens),
+        equiv_max_configurations: settings.fetch(:equiv_max_configurations),
+        verify_max_states: settings.fetch(:verify_max_states),
+        verify_max_items: settings.fetch(:verify_max_items),
+        messages: messages, message_file: message_file
+      )
+      [source, fixer]
+    end
+
+    # Keep command-local construction settings separate from reusable CLI state.
+    # @rbs (Array[String] arguments) -> Hash[Symbol, untyped]
+    def fix_options(arguments)
+      settings = {
+        paths: [], algorithm: Configuration::Registry.fetch("parser.algorithm").default,
+        mode: Configuration::Registry.fetch("grammar.mode").default, format: "json",
+        max_candidates: 32, max_builds: 32, equiv_samples: 100,
+        equiv_max_tokens: 8, equiv_max_configurations: 50_000,
+        verify_max_states: 100_000, verify_max_items: 1_000_000, configuration_explicit: []
+      } #: Hash[Symbol, untyped]
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: ibex fix [options] GRAMMAR"
+        add_fix_target_options(options, settings)
+        add_fix_budget_options(options, settings)
+        options.on("--algorithm=NAME", %w[slr lalr ielr lr1], "current construction algorithm") do |value|
+          set_local_configuration_option(settings, :algorithm, value.to_sym)
+        end
+        options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+          set_configuration_option(:mode, value.to_sym)
+        end
+        options.on("--apply[=ID]", "atomically apply one safe source proposal") do |value|
+          settings[:apply] = value || true
+        end
+        options.on("--messages=FILE", "measure effects on an error-message catalog") do |value|
+          settings[:messages] = value
+        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[:algorithm] = local_configuration_value(settings, "parser.algorithm")
+      settings
+    end
+
+    # @rbs (OptionParser options, Hash[Symbol, untyped] settings) -> void
+    def add_fix_target_options(options, settings)
+      options.on("--state=N", Integer, "target state (default first unresolved conflict)") do |value|
+        raise OptionParser::InvalidArgument, "--state must be nonnegative" if value.negative?
+
+        settings[:state] = value
+      end
+      options.on("--conflict-index=N", Integer, "target conflict index within the state") do |value|
+        raise OptionParser::InvalidArgument, "--conflict-index must be nonnegative" if value.negative?
+
+        settings[:conflict_index] = value
+      end
+    end
+
+    # @rbs (OptionParser options, Hash[Symbol, untyped] settings) -> void
+    def add_fix_budget_options(options, settings)
+      {
+        "max-candidates" => :max_candidates,
+        "max-builds" => :max_builds,
+        "equiv-samples" => :equiv_samples,
+        "equiv-max-tokens" => :equiv_max_tokens,
+        "equiv-max-configurations" => :equiv_max_configurations,
+        "verify-max-states" => :verify_max_states,
+        "verify-max-items" => :verify_max_items
+      }.each do |name, key|
+        options.on("--#{name}=N", Integer, "positive bounded-search limit") do |value|
+          raise OptionParser::InvalidArgument, "--#{name} must be positive" unless value.positive?
+
+          settings[key] = value
+        end
+      end
+    end
+
+    # @rbs (IR::Grammar grammar, Hash[Symbol, untyped] settings) -> [IR::Grammar, Symbol, IR::Automaton]
+    def fixer_construction(grammar, settings)
+      explicit_keys = settings.fetch(:configuration_explicit) & [:algorithm]
+      construct_analysis_automaton(grammar, { algorithm: settings.fetch(:algorithm) }, explicit_keys)
+    end
+
+    # @rbs!
+    #   private def construct_analysis_automaton: (IR::Grammar, Hash[Symbol, Object?], Array[Symbol]) ->
+    #     [IR::Grammar, Symbol, IR::Automaton]
+
+    # @rbs (String path, String original, Hash[Symbol, untyped] report, Fix fixer, String | true selector) -> void
+    def apply_fix!(path, original, report, fixer, selector)
+      proposal = selected_fix_proposal(report.fetch(:proposals), selector)
+      unless proposal.fetch(:applyable)
+        raise Ibex::Error, "(fix):1:1: proposal #{proposal.fetch(:id)} changes invocation options, not source"
+      end
+      if File.symlink?(path) || File.stat(path).nlink > 1
+        raise Ibex::Error, "(fix):1:1: --apply refuses symlink aliases and files with multiple hard links"
+      end
+
+      replacement = fixer.sources.fetch(proposal.fetch(:id))
+      activate_cli_feature(:CLIFormatting)
+      results = [{
+        path: path, label: path, source: original, formatted: replacement
+      }]
+      targets = send(:formatting_targets, results)
+      send(:transactionally_write_formatted, targets)
+      report[:applied] = proposal.fetch(:id)
+    end
+
+    # @rbs (Array[Hash[Symbol, untyped]] proposals, String | true selector) -> Hash[Symbol, untyped]
+    def selected_fix_proposal(proposals, selector)
+      proposal = if selector == true
+                   proposals.find { |entry| entry.fetch(:applyable) }
+                 else
+                   proposals.find { |entry| entry.fetch(:id) == selector }
+                 end
+      proposal || raise(Ibex::Error, "(fix):1:1: no matching applyable safe proposal")
+    end
+
+    # @rbs (Hash[Symbol, untyped] report, String format) -> void
+    def write_fix_report(report, format)
+      if format == "json"
+        @stdout.puts(JSON.pretty_generate(report))
+        return
+      end
+
+      @stdout.puts("result=#{report.fetch(:result)} proposals=#{report.fetch(:proposals, []).length}")
+      report.fetch(:proposals, []).each do |proposal|
+        @stdout.puts("#{proposal.fetch(:id)} #{proposal.fetch(:description)}")
+      end
+      @stdout.puts(report.fetch(:statement, Equiv::CAVEAT))
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/ibex/cli/formatting.rb

@@ -0,0 +1,387 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "optparse"
+require_relative "../frontend"
+
+module Ibex
+  # CLI coordination for deterministic, semantics-preserving grammar formatting.
+  # rubocop:disable Metrics/ModuleLength -- transaction lifecycle stays cohesive and auditable.
+  module CLIFormatting
+    # @rbs!
+    #   type formatting_settings = Hash[Symbol, untyped]
+    #   type formatting_result = {
+    #     path: String,
+    #     label: String,
+    #     source: String,
+    #     formatted: String
+    #   }
+    #   type formatting_target = {
+    #     path: String,
+    #     label: String,
+    #     target: String,
+    #     formatted: String,
+    #     mode: Integer,
+    #     directory: String,
+    #     basename: String,
+    #     changed: bool,
+    #     installed: bool,
+    #     ?stage: String,
+    #     ?backup: String
+    #   }
+    #   type formatting_cleanup_result = {
+    #     errors: Array[String],
+    #     remaining: Array[String]
+    #   }
+    #   private def local_configuration_value: (Hash[Symbol, Object?], String) -> Object?
+    #   private def set_local_configuration_option: (Hash[Symbol, Object?], Symbol, Object?) -> void
+
+    private
+
+    # @rbs (Array[String] arguments) -> Integer
+    def run_format_command(arguments)
+      settings = formatting_options(arguments)
+      if settings[:help]
+        @stdout.puts(formatting_option_parser(settings))
+        return 0
+      end
+
+      validate_formatting_settings!(settings)
+      results, failed = prepare_formatting_results(settings)
+      if settings.fetch(:check)
+        check_status = check_formatting_results(results)
+        return 1 if failed
+
+        return check_status
+      end
+      return 1 if failed
+      return write_formatting_results(results) if settings.fetch(:write)
+
+      @stdout.write(results.fetch(0).fetch(:formatted))
+      0
+    end
+
+    # @rbs (Array[String] arguments) -> formatting_settings
+    def formatting_options(arguments)
+      settings = {
+        paths: [], mode: Configuration::Registry.fetch("grammar.mode").default, check: false, write: false,
+        configuration_explicit: []
+      } #: formatting_settings
+      settings[:paths] = formatting_option_parser(settings).parse(arguments)
+      settings[:mode] = local_configuration_value(settings, "grammar.mode")
+      settings
+    end
+
+    # @rbs (formatting_settings settings) -> OptionParser
+    def formatting_option_parser(settings)
+      OptionParser.new do |options|
+        options.banner = "Usage: ibex fmt [--check | --write] [options] grammar.y [...]"
+        options.on("--check", "report files that need formatting") { settings[:check] = true }
+        options.on("--write", "atomically format files in place") { settings[:write] = true }
+        options.on("--mode=MODE", %w[default extended], "grammar mode") do |value|
+          set_local_configuration_option(settings, :mode, value.to_sym)
+        end
+        options.on("--stdin-filename=FILE", "diagnostic filename for standard input") do |value|
+          settings[:stdin_filename] = value
+        end
+        options.on("--help", "show help") { settings[:help] = true }
+      end
+    end
+
+    # @rbs (formatting_settings settings) -> void
+    def validate_formatting_settings!(settings)
+      paths = settings.fetch(:paths)
+      raise Ibex::Error, "(cli):1:1: fmt requires at least one grammar file" if paths.empty?
+
+      validate_formatting_operation!(settings, paths)
+      validate_formatting_stdin!(settings, paths)
+    end
+
+    # @rbs (formatting_settings settings, Array[String] paths) -> void
+    def validate_formatting_operation!(settings, paths)
+      if settings.fetch(:check) && settings.fetch(:write)
+        raise Ibex::Error, "(cli):1:1: fmt --check and --write cannot be combined"
+      end
+      return if settings.fetch(:check) || settings.fetch(:write) || paths.length == 1
+
+      raise Ibex::Error, "(cli):1:1: fmt writes to stdout only for exactly one input"
+    end
+
+    # @rbs (formatting_settings settings, Array[String] paths) -> void
+    def validate_formatting_stdin!(settings, paths)
+      raise Ibex::Error, "(cli):1:1: fmt standard input may be specified only once" if paths.count("-") > 1
+
+      if paths.include?("-") && (settings.fetch(:check) || settings.fetch(:write))
+        raise Ibex::Error, "(cli):1:1: fmt --check and --write require file inputs"
+      end
+      if settings[:stdin_filename] && formatting_control_bytes?(settings.fetch(:stdin_filename))
+        raise Ibex::Error, "(cli):1:1: --stdin-filename must not contain control characters"
+      end
+      return unless settings[:stdin_filename] && paths != ["-"]
+
+      raise Ibex::Error, "(cli):1:1: --stdin-filename requires fmt -"
+    end
+
+    # @rbs (formatting_settings settings) -> [Array[formatting_result], bool]
+    def prepare_formatting_results(settings)
+      failed = false
+      results = [] #: Array[formatting_result]
+      settings.fetch(:paths).each do |path|
+        source = path == "-" ? @stdin.read : File.binread(path)
+        label = path == "-" ? settings[:stdin_filename] || "(stdin)" : formatting_label(path)
+        formatted = Frontend::Formatter.format(source, file: label, mode: settings.fetch(:mode))
+        results << { path: path, label: label, source: source, formatted: formatted }
+      rescue Ibex::Error, SystemCallError => e
+        @stderr.puts(formatting_label(e.message))
+        failed = true
+      end
+      [results, failed]
+    end
+
+    # @rbs (Array[formatting_result] results) -> Integer
+    def check_formatting_results(results)
+      changed = results.reject { |result| result.fetch(:source) == result.fetch(:formatted) }
+      changed.each { |result| @stderr.puts("#{result.fetch(:label)}: needs formatting") }
+      changed.empty? ? 0 : 1
+    end
+
+    # @rbs (Array[formatting_result] results) -> Integer
+    def write_formatting_results(results)
+      targets = formatting_targets(results)
+      validate_unique_formatting_targets!(targets)
+      targets = targets.select { |target| target.fetch(:changed) }
+      return 0 if targets.empty?
+
+      transactionally_write_formatted(targets)
+      0
+    end
+
+    # @rbs (Array[formatting_result] results) -> Array[formatting_target]
+    def formatting_targets(results)
+      results.map do |result|
+        target = File.realpath(result.fetch(:path))
+        {
+          path: result.fetch(:path), label: result.fetch(:label), target: target,
+          formatted: result.fetch(:formatted), mode: File.stat(target).mode & 0o7777,
+          directory: File.dirname(target), basename: File.basename(target),
+          changed: result.fetch(:source) != result.fetch(:formatted), installed: false
+        }
+      end
+    rescue SystemCallError => e
+      raise Ibex::Error, formatting_label(e.message)
+    end
+
+    # @rbs (Array[formatting_target] targets) -> void
+    def validate_unique_formatting_targets!(targets)
+      collision = duplicate_formatting_target_pair(targets)
+      return unless collision
+
+      labels = collision.map { |target| target.fetch(:label) }
+      raise Ibex::Error, "(cli):1:1: fmt inputs resolve to the same target: #{labels.join(', ')}"
+    end
+
+    # @rbs (Array[formatting_target] targets) -> [formatting_target, formatting_target]?
+    def duplicate_formatting_target_pair(targets)
+      targets.each_with_index do |left, index|
+        targets.drop(index + 1).each do |right|
+          same_path = left.fetch(:target) == right.fetch(:target)
+          return [left, right] if same_path || File.identical?(left.fetch(:target), right.fetch(:target))
+        end
+      end
+      nil
+    end
+
+    # @rbs (Array[formatting_target] targets) -> void
+    def transactionally_write_formatted(targets)
+      begin
+        stage_formatting_targets(targets)
+        backup_formatting_targets(targets)
+        sync_formatting_directories!(targets)
+        install_formatting_targets(targets)
+        sync_formatting_directories!(targets)
+      rescue StandardError => e
+        rollback_errors = rollback_formatting_targets(targets)
+        cleanup = cleanup_formatting_artifacts(targets, preserve_installed_backups: true)
+        sync_errors = sync_formatting_directories_best_effort(targets)
+        raise formatting_transaction_error(e, rollback_errors, cleanup, sync_errors)
+      end
+
+      cleanup = cleanup_formatting_artifacts(targets, preserve_installed_backups: false)
+      sync_errors = sync_formatting_directories_best_effort(targets)
+      report_formatting_cleanup_warning(cleanup, sync_errors)
+    end
+
+    # @rbs (Array[formatting_target] targets) -> void
+    def stage_formatting_targets(targets)
+      targets.each do |target|
+        temporary = Tempfile.create(
+          [".ibex-fmt-", ".stage"], target.fetch(:directory)
+        )
+        target[:stage] = temporary.path.dup
+        temporary.binmode
+        temporary.write(target.fetch(:formatted))
+        temporary.flush
+        temporary.fsync
+        temporary.chmod(target.fetch(:mode))
+        temporary.fsync
+        temporary.close
+      rescue StandardError
+        begin
+          temporary&.close
+        rescue StandardError
+          nil
+        end
+        raise
+      end
+    end
+
+    # @rbs (Array[formatting_target] targets) -> void
+    def backup_formatting_targets(targets)
+      targets.each do |target|
+        backup = "#{target.fetch(:stage)}.backup"
+        target[:backup] = backup
+        File.link(target.fetch(:target), backup)
+      end
+    end
+
+    # @rbs (Array[formatting_target] targets) -> void
+    def install_formatting_targets(targets)
+      targets.each do |target|
+        File.rename(target.fetch(:stage), target.fetch(:target))
+        target[:installed] = true
+      end
+    end
+
+    # @rbs (Array[formatting_target] targets) -> Array[String]
+    def rollback_formatting_targets(targets)
+      errors = [] #: Array[String]
+      targets.reverse_each do |target|
+        next unless target.fetch(:installed)
+
+        File.rename(target.fetch(:backup), target.fetch(:target))
+        target[:installed] = false
+      rescue StandardError => e
+        errors << "#{target.fetch(:label)}: #{formatting_label(e.message)}"
+      end
+      errors
+    end
+
+    # @rbs (Array[formatting_target] targets, preserve_installed_backups: bool) ->
+    #   formatting_cleanup_result
+    def cleanup_formatting_artifacts(targets, preserve_installed_backups:)
+      errors = [] #: Array[String]
+      remaining = [] #: Array[String]
+      targets.each do |target|
+        artifacts = [target[:stage]] #: Array[String?]
+        backup = target[:backup]
+        if preserve_installed_backups && target.fetch(:installed) && backup
+          remaining << backup
+        else
+          artifacts << backup
+        end
+        artifacts.compact.each do |path|
+          error = remove_formatting_artifact(path)
+          next unless error
+
+          errors << error
+          remaining << path
+        end
+      end
+      { errors: errors, remaining: remaining }
+    end
+
+    # @rbs (String path) -> String?
+    def remove_formatting_artifact(path)
+      attempts = 0
+      begin
+        attempts += 1
+        File.unlink(path)
+        nil
+      rescue Errno::ENOENT
+        nil
+      rescue StandardError => e
+        retry if attempts < 2
+
+        "#{formatting_label(path)}: #{formatting_label(e.message)}"
+      end
+    end
+
+    # @rbs (StandardError error, Array[String] rollback_errors,
+    #   formatting_cleanup_result cleanup, Array[String] sync_errors) -> Ibex::Error
+    def formatting_transaction_error(error, rollback_errors, cleanup, sync_errors)
+      details = ["fmt write failed: #{formatting_label(error.message)}"] #: Array[String]
+      details << "rollback failed: #{rollback_errors.join('; ')}" unless rollback_errors.empty?
+      details << "cleanup failed: #{cleanup.fetch(:errors).join('; ')}" unless cleanup.fetch(:errors).empty?
+      unless cleanup.fetch(:remaining).empty?
+        paths = cleanup.fetch(:remaining).map { |path| formatting_label(path) }
+        details << "preserved artifacts: #{paths.join(', ')}"
+      end
+      details << "rollback directory sync failed: #{sync_errors.join('; ')}" unless sync_errors.empty?
+      Ibex::Error.new(details.join("; "))
+    end
+
+    # @rbs (formatting_cleanup_result cleanup, Array[String] sync_errors) -> void
+    def report_formatting_cleanup_warning(cleanup, sync_errors)
+      details = cleanup.fetch(:errors).dup
+      details.concat(sync_errors)
+      unless cleanup.fetch(:remaining).empty?
+        paths = cleanup.fetch(:remaining).map { |path| formatting_label(path) }
+        details << "remaining artifacts: #{paths.join(', ')}"
+      end
+      return if details.empty?
+
+      @stderr.puts("fmt cleanup warning (formatted targets committed): #{details.join('; ')}")
+    end
+
+    # @rbs (Array[formatting_target] targets) -> void
+    def sync_formatting_directories!(targets)
+      errors = sync_formatting_directories(targets)
+      return if errors.empty?
+
+      raise Ibex::Error, "directory sync failed: #{errors.join('; ')}"
+    end
+
+    # @rbs (Array[formatting_target] targets) -> Array[String]
+    def sync_formatting_directories_best_effort(targets)
+      sync_formatting_directories(targets)
+    end
+
+    # @rbs (Array[formatting_target] targets) -> Array[String]
+    def sync_formatting_directories(targets)
+      errors = [] #: Array[String]
+      targets.map { |target| target.fetch(:directory) }.uniq.each do |directory|
+        sync_formatting_directory(directory)
+      rescue SystemCallError, IOError => e
+        errors << "#{formatting_label(directory)}: #{formatting_label(e.message)}"
+      end
+      errors
+    end
+
+    # @rbs (String directory) -> void
+    def sync_formatting_directory(directory)
+      File.open(directory, File::RDONLY, &:fsync)
+    rescue Errno::EINVAL, Errno::ENOTSUP, Errno::EBADF
+      nil
+    end
+
+    # @rbs (String value) -> String
+    def formatting_label(value)
+      escaped = String.new(encoding: Encoding::BINARY)
+      value.b.each_byte do |byte|
+        escaped << (control_byte?(byte) ? format("\\x%02X", byte) : byte)
+      end
+      escaped.force_encoding(value.encoding)
+    end
+
+    # @rbs (String value) -> bool
+    def formatting_control_bytes?(value)
+      value.b.each_byte.any? { |byte| control_byte?(byte) }
+    end
+
+    # @rbs (Integer byte) -> bool
+    def control_byte?(byte)
+      byte < 0x20 || byte == 0x7f
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end