ibex 0.1.0 → 0.2.0

data/lib/ibex/codegen/generated_action_abi.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "action_locations"
+
+module Ibex
+  module Codegen
+    # Selects the smallest generated semantic-action ABI that preserves the
+    # action's declared inputs.
+    # rubocop:disable Metrics/ModuleLength -- ABI proof and source rewriting must evolve together.
+    module GeneratedActionABI
+      LEGACY_PARAMETERS = %w[
+        _values
+        _ibex_locations
+        _ibex_location_stack
+        _ibex_location
+        _ibex_lookahead_location
+      ].freeze #: Array[String]
+      SIMPLE_POSITIONAL_READ = /(?<![.\w@$])val\[\s*(\d+)\s*\]/ #: Regexp
+      SIMPLE_POSITIONAL_UNSAFE = %r{['"`#%/\\]|<<} #: Regexp
+      private_constant :LEGACY_PARAMETERS
+      private_constant :SIMPLE_POSITIONAL_READ, :SIMPLE_POSITIONAL_UNSAFE
+
+      # Keeps semantic-action analysis local to one code-generation run.
+      class Cache
+        # @rbs @values_only: Hash[Integer, bool]
+        # @rbs @borrowed_values: Hash[Integer, bool]
+        # @rbs @positional_actions: Hash[Integer, String?]
+
+        # @rbs () -> void
+        def initialize
+          @values_only = {}
+          @borrowed_values = {}
+          @positional_actions = {}
+        end
+
+        # @rbs (IR::Production production) -> bool
+        def values_only?(production)
+          @values_only.fetch(production.id) do
+            @values_only[production.id] = GeneratedActionABI.values_only?(production)
+          end
+        end
+
+        # @rbs (IR::Production production) -> bool
+        def borrowed_values?(production)
+          @borrowed_values.fetch(production.id) do
+            @borrowed_values[production.id] =
+              GeneratedActionABI.borrowed_values?(production, analysis: self)
+          end
+        end
+
+        # @rbs (IR::Production production) -> String?
+        def positional_action_source(production)
+          @positional_actions.fetch(production.id) do
+            @positional_actions[production.id] =
+              GeneratedActionABI.positional_action_source(production, analysis: self)
+          end
+        end
+
+        # @rbs (IR::Production production) -> bool
+        def positional_values?(production)
+          !positional_action_source(production).nil?
+        end
+      end
+
+      module_function
+
+      # @rbs (IR::Production production) -> bool
+      def values_only?(production)
+        return false if production.action&.composition
+
+        action = production.action
+        return true unless action
+        return false if action.context_length.positive?
+
+        maximum = production.rhs.length
+        locations = ActionLocations.new(action.code, maximum: maximum, location: action.location)
+        !locations.references? && !references_legacy_parameter?(action.code)
+      end
+
+      # The direct runtime can share one reduction-values array with an action
+      # and a hook installed by that action only when the action cannot mutate
+      # or retain the array itself. Element reads and parallel assignment copy
+      # values out without exposing the container.
+      # @rbs (IR::Production production, ?analysis: singleton(GeneratedActionABI) | Cache) -> bool
+      def borrowed_values?(production, analysis: self)
+        return false unless analysis.values_only?(production)
+
+        action = production.action
+        return false unless action
+
+        maximum = production.rhs.length
+        source = ActionLocations.new(action.code, maximum: maximum, location: action.location).rewrite
+        return true if simple_indexed_values_action?(source)
+
+        require "ripper"
+        syntax = Object.const_get(:Ripper).__send__(:sexp, source)
+        !syntax.nil? && read_only_value_references?(syntax)
+      end
+
+      # Return semantic source rewritten for zero-to-four positional RHS
+      # arguments, or nil when the values container remains observable.
+      # @rbs (IR::Production production, ?analysis: singleton(GeneratedActionABI) | Cache) -> String?
+      def positional_action_source(production, analysis: self)
+        return nil unless analysis.values_only?(production)
+        return nil unless production.rhs.length <= 4
+
+        action = production.action
+        return "" unless action
+        return nil unless analysis.borrowed_values?(production)
+
+        parameters = Array.new(production.rhs.length) { |index| "v#{index}" }
+        return nil if action.named_refs.any? { |reference| parameters.include?(reference[:name]) }
+
+        maximum = production.rhs.length
+        source = ActionLocations.new(action.code, maximum: maximum, location: action.location).rewrite
+        simple = fast_positional_action_source(source, parameters)
+        return simple unless simple.nil?
+
+        require "ripper"
+        tokens = Object.const_get(:Ripper).__send__(:lex, source)
+        return nil unless tokens.map { |_position, _event, token, _state| token }.join == source
+
+        rewrite_positional_values(tokens, parameters)
+      end
+
+      # @rbs (String source, Array[String] parameters) -> String?
+      def fast_positional_action_source(source, parameters)
+        simple = simple_positional_action_source(source, parameters)
+        return simple unless simple.nil?
+
+        simple_indexed_positional_action_source(source, parameters)
+      end
+      private_class_method :fast_positional_action_source
+
+      # @rbs (IR::Production production) -> bool
+      def positional_values?(production)
+        !positional_action_source(production).nil?
+      end
+
+      # Avoid loading a Ruby parser for the overwhelmingly common generated
+      # action shape. This accepts only a single result assignment (or a bare
+      # expression), simple numeric val reads, and no further assignment.
+      # Anything less obvious falls back to Ripper below.
+      # @rbs (String source) -> bool
+      def simple_indexed_values_action?(source)
+        body = source.strip
+        assignment = /\Aresult\s*=\s*(.*)\z/m.match(body)
+        body = (assignment[1] || "").strip if assignment
+        return false if body.empty? || body.match?(/(?<![=!<>])=(?!=|>)/)
+
+        without_reads = body.gsub(/\bval\[\s*\d+\s*\]/, "")
+        without_reads != body && !without_reads.match?(/\bval\b/)
+      end
+      private_class_method :simple_indexed_values_action?
+
+      # Keep the most common identity action off the Ripper load path. The
+      # whole-source match excludes strings, comments, receivers, and compound
+      # expressions before replacing the one direct read.
+      # @rbs (String source, Array[String] parameters) -> String?
+      def simple_positional_action_source(source, parameters)
+        match = /\A\s*(?:result\s*=\s*)?val\[\s*(\d+)\s*\]\s*\z/.match(source)
+        return nil unless match
+
+        parameter = parameters[Integer(match[1] || "", 10)]
+        source.sub(/\bval\[\s*\d+\s*\]/, parameter) if parameter
+      end
+      private_class_method :simple_positional_action_source
+
+      # Rewrite the common string/comment/regexp-free action shape without
+      # loading Ripper. The borrowed-values proof has already rejected writes
+      # and escaping uses of the values container.
+      # @rbs (String source, Array[String] parameters) -> String?
+      def simple_indexed_positional_action_source(source, parameters)
+        return nil if source.match?(SIMPLE_POSITIONAL_UNSAFE)
+        return nil if parameters.any? { |parameter| source.match?(/\b#{Regexp.escape(parameter)}\b/) }
+
+        valid = true
+        rewritten = source.gsub(SIMPLE_POSITIONAL_READ) do
+          parameter = parameters.fetch(Integer(Regexp.last_match(1) || "", 10), nil)
+          valid = false unless parameter
+          parameter || Regexp.last_match(0)
+        end
+        return nil unless valid
+        return nil if rewritten.match?(/\bval\b/)
+
+        rewritten
+      end
+      private_class_method :simple_indexed_positional_action_source
+
+      # @rbs (Array[untyped] tokens, Array[String] parameters) -> String?
+      def rewrite_positional_values(tokens, parameters)
+        result = [] #: Array[String]
+        index = 0
+        while index < tokens.length
+          _position, event, token, _state = tokens[index]
+          return nil if event == :on_ident && parameters.include?(token)
+
+          unless event == :on_ident && token == "val"
+            result << token
+            index += 1
+            next
+          end
+
+          reference = positional_value_reference(tokens, index, parameters)
+          if reference
+            result << reference.fetch(0)
+            index = reference.fetch(1)
+          elsif receiver_before_value?(tokens, index) || parameters.empty?
+            return nil
+          else
+            # borrowed_values? has already proven that a bare `val` occurs
+            # only as the right-hand side of parallel assignment.
+            result << parameters.join(", ")
+            index += 1
+          end
+        end
+        result.join
+      end
+      private_class_method :rewrite_positional_values
+
+      # @rbs (Array[untyped] tokens, Integer index, Array[String] parameters) -> [String, Integer]?
+      def positional_value_reference(tokens, index, parameters)
+        return nil if receiver_before_value?(tokens, index)
+
+        reference = tokens.slice(index + 1, 3)
+        return nil unless reference
+        return nil unless reference.map { |entry| entry[1] } == %i[on_lbracket on_int on_rbracket]
+
+        parameter = parameters[Integer(reference.fetch(1).fetch(2), 10)]
+        [parameter, index + 4] if parameter
+      rescue ArgumentError
+        nil
+      end
+      private_class_method :positional_value_reference
+
+      # @rbs (Array[untyped] tokens, Integer index) -> bool
+      def receiver_before_value?(tokens, index)
+        previous = tokens.first(index).reverse.find do |entry|
+          !%i[on_sp on_nl on_ignored_nl on_comment].include?(entry[1])
+        end
+        return false unless previous
+
+        previous[1] == :on_period || (previous[1] == :on_op && %w[&. ::].include?(previous[2]))
+      end
+      private_class_method :receiver_before_value?
+
+      # @rbs (String source) -> bool
+      def references_legacy_parameter?(source)
+        return false unless LEGACY_PARAMETERS.any? { |parameter| source.include?(parameter) }
+
+        require "ripper"
+        tokens = Object.const_get(:Ripper).__send__(:lex, source.gsub(/@(?:\$|\d+)/) { |match| "_" * match.bytesize })
+        tokens.any? do |_position, type, token, _state|
+          type == :on_ident && LEGACY_PARAMETERS.include?(token)
+        end
+      end
+      private_class_method :references_legacy_parameter?
+
+      # @rbs (untyped node, ?untyped parent, ?Integer? child_index) -> bool
+      def read_only_value_references?(node, parent = nil, child_index = nil)
+        return true unless node.is_a?(Array)
+        return safe_value_reference?(parent, child_index) if value_reference?(node)
+
+        node.each_with_index.all? do |child, index|
+          read_only_value_references?(child, node, index)
+        end
+      end
+      private_class_method :read_only_value_references?
+
+      # @rbs (untyped node) -> bool
+      def value_reference?(node)
+        node[0] == :vcall && node.dig(1, 0) == :@ident && node.dig(1, 1) == "val"
+      end
+      private_class_method :value_reference?
+
+      # @rbs (untyped parent, Integer? child_index) -> bool
+      def safe_value_reference?(parent, child_index)
+        return false unless parent.is_a?(Array)
+
+        (parent[0] == :aref && child_index == 1) ||
+          (parent[0] == :massign && child_index == 2)
+      end
+      private_class_method :safe_value_reference?
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/ibex/codegen/html.rb

@@ -11,13 +11,23 @@ module Ibex
       #     Hash[Integer, String] labels) -> String
       #   private def self.state_sections: (IR::Automaton automaton, IR::Grammar grammar,
       #     Hash[Integer, String] labels) -> String
+      #   private def controls: (IR::Automaton automaton) -> String
+      #   private def self.controls: (IR::Automaton automaton) -> String
+      #   private def styles: () -> String
+      #   private def self.styles: () -> String
+      #   private def interaction_script: () -> String
+      #   private def self.interaction_script: () -> String
+      #   private def one_hop_neighbors: (IR::Automaton automaton, Integer state_id) -> Array[Integer]
+      #   private def self.one_hop_neighbors: (IR::Automaton automaton, Integer state_id) -> Array[Integer]
       #   private def item_html: (IR::AutomatonItem item, IR::Grammar grammar, Hash[Integer, String] labels) -> String
       #   private def self.item_html: (IR::AutomatonItem item, IR::Grammar grammar,
       #     Hash[Integer, String] labels) -> String
       #   private def rule_sections: (IR::Grammar grammar, Hash[Integer, String] labels) -> String
       #   private def self.rule_sections: (IR::Grammar grammar, Hash[Integer, String] labels) -> String
-      #   private def conflict_sections: (IR::Automaton automaton) -> String
-      #   private def self.conflict_sections: (IR::Automaton automaton) -> String
+      #   private def conflict_sections: (IR::Automaton automaton, IR::Grammar grammar,
+      #     Hash[Integer, String] labels) -> String
+      #   private def self.conflict_sections: (IR::Automaton automaton, IR::Grammar grammar,
+      #     Hash[Integer, String] labels) -> String
       #   private def escape: (String value) -> String
       #   private def self.escape: (String value) -> String
       #   private def symbol_name: (Hash[Integer, String] labels, Integer id) -> String
@@ -30,12 +40,14 @@ module Ibex
         <<~HTML
           <!doctype html>
           <html lang="en"><head><meta charset="utf-8"><title>Ibex automaton</title>
-          <style>body{font:14px system-ui;margin:2rem;max-width:90rem}code{white-space:pre-wrap}.state{border:1px solid #bbb;padding:1rem;margin:1rem 0}.conflict{color:#a00}a{color:#075985}</style>
+          #{styles}
           </head><body><h1>Ibex #{escape(automaton.algorithm)} automaton</h1>
           <nav><a href="#rules">Rules</a> · <a href="#conflicts">Conflicts</a></nav>
-          #{state_sections(automaton, grammar, labels)}
+          #{controls(automaton)}
+          <main id="states">#{state_sections(automaton, grammar, labels)}</main>
           <h2 id="rules">Rules</h2>#{rule_sections(grammar, labels)}
-          <h2 id="conflicts">Conflicts</h2>#{conflict_sections(automaton)}
+          <h2 id="conflicts">Conflicts</h2>#{conflict_sections(automaton, grammar, labels)}
+          #{interaction_script}
           </body></html>
         HTML
       end
@@ -44,6 +56,62 @@ module Ibex
       # @rbs skip
       private
 
+      # @rbs skip
+      def styles
+        <<~HTML
+          <style>
+          body{font:14px system-ui;margin:2rem;max-width:90rem}code{white-space:pre-wrap}
+          .controls{align-items:center;display:flex;flex-wrap:wrap;gap:1rem;margin:1rem 0}
+          .state{border:1px solid #bbb;padding:1rem;margin:1rem 0}.state[hidden]{display:none}
+          .conflict-state{background:#fff7f7;border:2px solid #b91c1c}.conflict{color:#a00}a{color:#075985}
+          </style>
+        HTML
+      end
+
+      # @rbs skip
+      def interaction_script
+        <<~HTML
+          <script>
+          (() => {
+            const search = document.getElementById("state-search");
+            const conflictOnly = document.getElementById("conflict-only");
+            const neighborhood = document.getElementById("conflict-neighborhood");
+            const states = Array.from(document.querySelectorAll(".state"));
+            const update = () => {
+              const query = search.value.trim().toLowerCase();
+              const focus = neighborhood.value;
+              states.forEach((state) => {
+                const matchesText = !query || state.textContent.toLowerCase().includes(query);
+                const matchesConflict = !conflictOnly.checked || state.classList.contains("conflict-state");
+                const nearby = !focus || state.dataset.neighbors.split(" ").includes(focus);
+                state.hidden = !(matchesText && matchesConflict && nearby);
+              });
+            };
+            search.addEventListener("input", update);
+            conflictOnly.addEventListener("change", update);
+            neighborhood.addEventListener("change", update);
+          })();
+          </script>
+        HTML
+      end
+
+      # @rbs skip
+      def controls(automaton)
+        options = automaton.states.filter_map do |state|
+          next if state.conflicts.empty?
+
+          %(<option value="#{state.id}">State #{state.id}</option>)
+        end.join
+        <<~HTML
+          <div class="controls">
+          <label>Search states <input id="state-search" type="search" aria-controls="states"></label>
+          <label><input id="conflict-only" type="checkbox"> Conflicts only</label>
+          <label>Conflict neighborhood
+          <select id="conflict-neighborhood"><option value="">All states</option>#{options}</select></label>
+          </div>
+        HTML
+      end
+
       # @rbs skip
       def state_sections(automaton, grammar, labels)
         automaton.states.map do |state|
@@ -52,13 +120,25 @@ module Ibex
             "<li>#{symbol} → <a href=\"#state-#{target}\">state #{target}</a></li>"
           end.join
           items = state.items.map { |item| item_html(item, grammar, labels) }.join
+          class_name = state.conflicts.empty? ? "state" : "state conflict-state"
+          neighbors = one_hop_neighbors(automaton, state.id).join(" ")
           <<~HTML
-            <section class="state" id="state-#{state.id}"><h2>State #{state.id}</h2>
+            <section class="#{class_name}" id="state-#{state.id}" data-state-id="#{state.id}" data-neighbors="#{neighbors}">
+            <h2>State #{state.id}</h2>
             <ul>#{transitions}</ul><ul>#{items}</ul></section>
           HTML
         end.join
       end
 
+      # @rbs skip
+      def one_hop_neighbors(automaton, state_id)
+        outgoing = automaton.states.fetch(state_id).transitions.values
+        incoming = automaton.states.filter_map do |state|
+          state.id if state.transitions.value?(state_id)
+        end
+        ([state_id] + outgoing + incoming).uniq.sort
+      end
+
       # @rbs skip
       def item_html(item, grammar, labels)
         return "<li><code>$accept</code></li>" if item.production.negative?
@@ -81,11 +161,13 @@ module Ibex
       end
 
       # @rbs skip
-      def conflict_sections(automaton)
+      def conflict_sections(automaton, grammar, labels)
         conflicts = automaton.states.flat_map do |state|
           state.conflicts.map do |conflict|
             link = "<a href=\"#state-#{state.id}\">state #{state.id}</a>"
-            "<li class=\"conflict\">#{link}: #{escape(conflict.inspect)}</li>"
+            symbol = grammar.symbol(conflict[:symbol])
+            displayed = symbol ? conflict.merge(symbol: symbol_name(labels, symbol.id)) : conflict
+            "<li class=\"conflict\">#{link}: #{escape(displayed.inspect)}</li>"
           end
         end
         conflicts.empty? ? "<p>None</p>" : "<ul>#{conflicts.join}</ul>"
@@ -100,10 +182,12 @@ module Ibex
       def symbol_name(labels, id)
         labels.fetch(id) { raise Ibex::Error, "missing grammar symbol id #{id}" }
       end
-      module_function :state_sections, :item_html, :rule_sections, :conflict_sections, :escape, :symbol_name
+      module_function :styles, :interaction_script, :controls, :state_sections, :one_hop_neighbors
+      module_function :item_html, :rule_sections, :conflict_sections, :escape, :symbol_name
 
       class << self
-        private :state_sections, :item_html, :rule_sections, :conflict_sections, :escape, :symbol_name
+        private :styles, :interaction_script, :controls, :state_sections, :one_hop_neighbors
+        private :item_html, :rule_sections, :conflict_sections, :escape, :symbol_name
       end
     end
   end

data/lib/ibex/codegen/mermaid.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "symbol_labels"
+
+module Ibex
+  module Codegen
+    # Renders an Automaton IR graph as a GitHub-compatible Mermaid flowchart.
+    module Mermaid
+      # @rbs (IR::Automaton automaton) -> String
+      def render(automaton)
+        labels = SymbolLabels.build(automaton.grammar)
+        lines = ["flowchart LR"]
+        automaton.states.each do |state|
+          lines << %(  state_#{state.id}["State #{state.id}"])
+          state.transitions.each do |symbol_id, target|
+            label = escape(labels.fetch(symbol_id) { raise Ibex::Error, "missing grammar symbol id #{symbol_id}" })
+            lines << "  state_#{state.id} -->|#{label}| state_#{target}"
+          end
+        end
+        conflicting = automaton.states.reject { |state| state.conflicts.empty? }
+        unless conflicting.empty?
+          lines << "  classDef conflict fill:#fee2e2,stroke:#b91c1c,stroke-width:2px"
+          conflicting.each { |state| lines << "  class state_#{state.id} conflict;" }
+        end
+        "#{lines.join("\n")}\n"
+      end
+      module_function :render
+
+      private
+
+      # @rbs (String value) -> String
+      def escape(value)
+        value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub("|", "&#124;")
+             .gsub('"', "&quot;").gsub(/\s+/, " ")
+      end
+      module_function :escape
+
+      class << self
+        private :escape
+      end
+    end
+  end
+end