ibex 0.2.0 → 0.4.0

data/lib/ibex/generation_manifest.rb

@@ -6,7 +6,11 @@ require "json"
 
 module Ibex
   # Deterministic description of one published parser generation.
+  # rubocop:disable Metrics/ModuleLength -- manifest schema validation is kept in one auditable unit.
   module GenerationManifest
+    # @rbs!
+    #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+
     SCHEMA_VERSION = 1 #: Integer
     IDENTIFIER = "generation" #: String
     ROOT_KEYS = %w[ibex_manifest schema_version input options artifacts].freeze #: Array[String]
@@ -16,7 +20,7 @@ module Ibex
 
     module_function
 
-    # @rbs (ArtifactSet artifacts, source_records: Array[GenerationInput], options: Hash[String, untyped]) -> String
+    # @rbs (ArtifactSet artifacts, source_records: Array[GenerationInput], options: Hash[String, Object?]) -> String
     def render(artifacts, source_records:, options:)
       files = source_records.map(&:to_h)
       document = {
@@ -34,24 +38,26 @@ module Ibex
     end
 
     # Validate the manifest shape and, by default, every published artifact digest.
-    # @rbs (String source, ?verify_artifacts: bool) -> Hash[String, untyped]
+    # @rbs (String source, ?verify_artifacts: bool) -> Hash[String, json_value]
     def validate(source, verify_artifacts: true)
-      document = JSON.parse(source)
+      document = JSON.parse(source) #: Object?
       validate_document(document)
-      verify_entries(document.fetch("artifacts")) if verify_artifacts
-      document
+      document_hash = document #: Hash[String, json_value]
+      artifacts = document_hash.fetch("artifacts") #: Array[Object?]
+      verify_entries(artifacts) if verify_artifacts
+      document_hash
     rescue JSON::ParserError, KeyError, TypeError, ArgumentError => e
       raise Ibex::Error, "(manifest):1:1: invalid generation manifest: #{e.message}"
     end
 
-    # @rbs (String path, ?verify_artifacts: bool) -> Hash[String, untyped]
+    # @rbs (String path, ?verify_artifacts: bool) -> Hash[String, json_value]
     def validate_file(path, verify_artifacts: true)
       validate(File.binread(path), verify_artifacts: verify_artifacts)
     rescue SystemCallError, ArgumentError => e
       raise Ibex::Error, "#{path}:1:1: cannot read generation manifest: #{e.message}"
     end
 
-    # @rbs (Artifact artifact) -> Hash[String, untyped]
+    # @rbs (Artifact artifact) -> Hash[String, json_value]
     def artifact_entry(artifact)
       {
         "kind" => artifact.kind.to_s,
@@ -62,19 +68,20 @@ module Ibex
     end
     private_class_method :artifact_entry
 
-    # @rbs (Array[Hash[String, untyped]] files) -> String
+    # @rbs (Array[Hash[String, json_value]] files) -> String
     def input_digest(files)
       digest = Digest::SHA256.new
       files.each do |entry|
-        digest << entry.fetch("path") << "\0"
-        digest << entry.fetch("sha256") << "\0"
-        digest << entry.fetch("bytesize").to_s << "\0"
+        path = entry.fetch("path") # @type var path: String
+        sha256 = entry.fetch("sha256") # @type var sha256: String
+        bytesize = entry.fetch("bytesize") # @type var bytesize: Integer
+        digest << path << "\0" << sha256 << "\0" << bytesize.to_s << "\0"
       end
       digest.hexdigest
     end
     private_class_method :input_digest
 
-    # @rbs (Hash[String, untyped] value) -> Hash[String, untyped]
+    # @rbs (Hash[String, Object?] value) -> Hash[String, Object?]
     def sorted_hash(value)
       value.keys.sort.to_h do |key|
         child = value.fetch(key)
@@ -84,7 +91,7 @@ module Ibex
     end
     private_class_method :sorted_hash
 
-    # @rbs (untyped document) -> void
+    # @rbs (Object? document) -> void
     def validate_document(document)
       raise TypeError, "document must be an object" unless document.is_a?(Hash)
 
@@ -100,14 +107,14 @@ module Ibex
     end
     private_class_method :validate_document
 
-    # @rbs (Hash[untyped, untyped] document) -> void
+    # @rbs (Hash[Object?, Object?] document) -> void
     def validate_identity(document)
       raise TypeError, "unsupported manifest identifier" unless document["ibex_manifest"] == IDENTIFIER
       raise TypeError, "unsupported schema_version" unless document["schema_version"] == SCHEMA_VERSION
     end
     private_class_method :validate_identity
 
-    # @rbs (untyped input) -> void
+    # @rbs (Object? input) -> void
     def validate_input(input)
       raise TypeError, "input must be an object" unless input.is_a?(Hash)
 
@@ -125,13 +132,13 @@ module Ibex
     end
     private_class_method :validate_input
 
-    # @rbs (Array[untyped] entries, String label, ?require_kind: bool) -> void
+    # @rbs (Array[Object?] entries, String label, ?require_kind: bool) -> void
     def validate_entries(entries, label, require_kind: false)
       entries.each { |entry| validate_entry(entry, label, require_kind) }
     end
     private_class_method :validate_entries
 
-    # @rbs (untyped entry, String label, bool require_kind) -> void
+    # @rbs (Object? entry, String label, bool require_kind) -> void
     def validate_entry(entry, label, require_kind)
       raise TypeError, "#{label} must be an object" unless entry.is_a?(Hash)
 
@@ -146,7 +153,7 @@ module Ibex
     end
     private_class_method :validate_entry
 
-    # @rbs (untyped path, String label) -> void
+    # @rbs (Object? path, String label) -> void
     def validate_path(path, label)
       raise TypeError, "#{label} path must be a non-empty string" unless path.is_a?(String) && !path.empty?
       return unless path.include?("\0") || path.match?(/[[:cntrl:]]/)
@@ -155,7 +162,7 @@ module Ibex
     end
     private_class_method :validate_path
 
-    # @rbs (untyped kind, String label) -> void
+    # @rbs (Object? kind, String label) -> void
     def validate_kind(kind, label)
       return if kind.is_a?(String) && !kind.empty?
 
@@ -163,7 +170,7 @@ module Ibex
     end
     private_class_method :validate_kind
 
-    # @rbs (untyped digest, String label) -> void
+    # @rbs (Object? digest, String label) -> void
     def validate_digest(digest, label)
       return if digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
 
@@ -171,7 +178,7 @@ module Ibex
     end
     private_class_method :validate_digest
 
-    # @rbs (Hash[untyped, untyped] value, Array[String] expected, String label) -> void
+    # @rbs (Hash[Object?, Object?] value, Array[String] expected, String label) -> void
     def exact_keys!(value, expected, label)
       keys = value.keys
       raise TypeError, "#{label} keys must be strings" unless keys.all?(String)
@@ -183,18 +190,22 @@ module Ibex
     end
     private_class_method :exact_keys!
 
-    # @rbs (Array[untyped] entries) -> void
+    # @rbs (Array[Object?] entries) -> void
     def verify_entries(entries)
       entries.each do |entry|
-        path = entry.fetch("path")
+        entry_hash = entry #: Hash[String, json_value]
+        path = entry_hash.fetch("path") #: String
         source = File.binread(path)
-        raise TypeError, "artifact bytesize mismatch for #{path}" unless source.bytesize == entry.fetch("bytesize")
+        bytesize = entry_hash.fetch("bytesize") #: Integer
+        sha256 = entry_hash.fetch("sha256") #: String
+        raise TypeError, "artifact bytesize mismatch for #{path}" unless source.bytesize == bytesize
         raise TypeError, "artifact digest mismatch for #{path}" unless
-          Digest::SHA256.hexdigest(source) == entry.fetch("sha256")
+          Digest::SHA256.hexdigest(source) == sha256
       end
     rescue SystemCallError => e
       raise TypeError, "cannot read artifact: #{e.message}"
     end
     private_class_method :verify_entries
   end
+  # rubocop:enable Metrics/ModuleLength
 end

data/lib/ibex/generation_transaction.rb

@@ -37,7 +37,7 @@ module Ibex
       @lock_sleeper = lock_sleeper
       @locks = [] #: Array[File]
       @locked_paths = [] #: Array[String]
-      @records = [] #: Array[Hash[Symbol, untyped]]
+      @records = [] #: Array[Hash[Symbol, Object?]]
       @committed = false
       @temporary_sequence = 0
     end

data/lib/ibex/generation_transaction_recovery.rb

@@ -57,14 +57,14 @@ module Ibex
       failures
     end
 
-    # @rbs (Hash[Symbol, untyped] record) -> void
+    # @rbs (Hash[Symbol, Object?] record) -> void
     def rollback_record(record)
-      target = record.fetch(:target)
+      target = record.fetch(:target) #: String
       if record.fetch(:backed_up)
         if record.fetch(:installed)
-          File.rename(record.fetch(:backup), target)
+          File.rename(record.fetch(:backup).to_s, target)
         else
-          File.unlink(record.fetch(:backup))
+          File.unlink(record.fetch(:backup).to_s)
         end
         record[:backup] = nil
         record[:backed_up] = false

data/lib/ibex/generation_transaction_validation.rb

@@ -170,9 +170,9 @@ module Ibex
             "(generation):1:1: cannot revalidate artifact target #{phase}: #{e.message}"
     end
 
-    # @rbs (Hash[Symbol, untyped] record, Array[String] sources, String phase) -> void
+    # @rbs (Hash[Symbol, Object?] record, Array[String] sources, String phase) -> void
     def validate_current_target!(record, sources, phase)
-      artifact = record.fetch(:artifact)
+      artifact = record.fetch(:artifact) #: Artifact
       current = resolved_target(artifact.path, validate_links: false)
       unless current == record.fetch(:target)
         raise GenerationTransaction::SourceChanged,

data/lib/ibex/grammar_tests.rb

@@ -182,7 +182,7 @@ module Ibex
         raise Ibex::Error, "(test):1:1: invalid grammar test process result: #{e.message}"
       end
 
-      # @rbs (IR::grammar_test test, untyped document) -> Result
+      # @rbs (IR::grammar_test test, Object? document) -> Result
       def build_result(test, document)
         unless document.is_a?(Hash) && %w[accept reject error].include?(document["actual"])
           raise Ibex::Error, "(test):1:1: grammar test process returned an invalid case result"

data/lib/ibex/impact/action_impact.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Impact
+    # Checks only structured action metadata; action source remains opaque.
+    class ActionImpact
+      # @rbs @before: IR::Grammar
+      # @rbs @after: IR::Grammar
+      # @rbs @affected_names: Array[String]?
+      attr_reader :findings #: Array[Hash[Symbol, Object?]]
+
+      # @rbs (IR::Grammar before, IR::Grammar after, ?affected_names: Array[String]?) -> void
+      def initialize(before, after, affected_names: nil)
+        @before = before
+        @after = after
+        @affected_names = affected_names
+        @findings = compare
+        freeze
+      end
+
+      # @rbs () -> Array[Hash[Symbol, Object?]]
+      def to_a
+        @findings
+      end
+
+      private
+
+      # @rbs () -> Array[Hash[Symbol, Object?]]
+      def compare
+        names = @after.nonterminals.map(&:name)
+        names &= @affected_names if @affected_names
+        names.sort.flat_map { |name| compare_rule(name) }.sort_by { |finding| finding.fetch(:production) }
+      end
+
+      # @rbs (String name) -> Array[Hash[Symbol, Object?]]
+      def compare_rule(name)
+        before = productions_for(@before, name)
+        after = productions_for(@after, name)
+        pair_productions(before, after).filter_map do |previous, production|
+          next if previous.rhs.length == production.rhs.length
+
+          finding_for(previous, production)
+        end
+      end
+
+      # @rbs (Array[IR::Production] before, Array[IR::Production] after) -> Array[[IR::Production, IR::Production]]
+      def pair_productions(before, after)
+        unmatched = before.dup
+        pairs = pair_exact_productions(unmatched, after)
+        pair_by_location(unmatched, after, pairs)
+      end
+
+      # @rbs (Array[IR::Production] unmatched, Array[IR::Production] after) -> Array[[IR::Production, IR::Production]]
+      def pair_exact_productions(unmatched, after)
+        pairs = [] #: Array[[IR::Production, IR::Production]]
+
+        after.each do |production|
+          index = unmatched.index do |candidate|
+            production_signature(@before, candidate) == production_signature(@after, production)
+          end
+          next unless index
+
+          pairs << [unmatched.delete_at(index), production]
+        end
+
+        pairs
+      end
+
+      # @rbs (Array[IR::Production] unmatched, Array[IR::Production] after,
+      #   Array[[IR::Production, IR::Production]]) -> Array[[IR::Production, IR::Production]]
+      def pair_by_location(unmatched, after, pairs)
+        after.each do |production|
+          next if pairs.any? { |_, candidate| candidate.equal?(production) }
+
+          index = unmatched.index do |candidate|
+            location = action_location_identity(production)
+            location && location == action_location_identity(candidate)
+          end
+          next unless index
+
+          pairs << [unmatched.delete_at(index), production]
+        end
+
+        pairs
+      end
+
+      # @rbs (IR::Grammar grammar, String name) -> Array[IR::Production]
+      def productions_for(grammar, name)
+        lhs = grammar.symbol(name)&.id
+        return [] unless lhs
+
+        grammar.productions.select { |production| production.lhs == lhs }
+      end
+
+      # @rbs (IR::Grammar grammar, IR::Production production) -> [Array[String], String?]
+      def production_signature(grammar, production)
+        rhs = production.rhs.map { |id| grammar.symbol_by_id(id)&.name || id.to_s }
+        precedence = grammar.symbol_by_id(production.precedence_override)&.name
+        [rhs, precedence]
+      end
+
+      # @rbs (IR::Production production) -> [Integer, Integer]?
+      def action_location_identity(production)
+        location = production.origin[:loc] || production.action&.location #: IR::location?
+        return unless location
+
+        line = location[:line]
+        column = location[:column]
+        return unless line && column
+
+        [line, column]
+      end
+
+      # @rbs (IR::Production before, IR::Production after) -> Hash[Symbol, Object?]
+      def finding_for(before, after)
+        action = after.action
+        reason, severity = finding_reason(action, before.rhs.length, after.rhs.length)
+        {
+          production: production_name(@after, after), severity: severity,
+          reason: reason,
+          context_length: { before: before.rhs.length, after: after.rhs.length },
+          loc: after.action&.location || after.origin[:loc]
+        }
+      end
+
+      # @rbs (IR::Action?, Integer, Integer) -> [String, String]
+      def finding_reason(action, before_length, after_length)
+        return %w[named_ref_index_out_of_range high] if out_of_range?(action, after_length)
+        return %w[context_length_stale high] if action&.context_length == before_length
+
+        %w[rhs_length_changed medium]
+      end
+
+      # @rbs (IR::Action?, Integer) -> bool
+      def out_of_range?(action, length)
+        action&.named_refs&.any? { |reference| reference.fetch(:index) >= length } || false
+      end
+
+      # @rbs (IR::Grammar grammar, IR::Production production) -> String
+      def production_name(grammar, production)
+        lhs = grammar.symbol_by_id(production.lhs)&.name || production.lhs.to_s
+        rhs = production.rhs.map { |id| grammar.symbol_by_id(id)&.name || id.to_s }
+        "#{lhs} -> #{rhs.join(' ')}"
+      end
+    end
+  end
+end

data/lib/ibex/impact/automaton_impact.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Impact
+    # Maps propagated grammar symbols to parser states and conflict changes.
+    class AutomatonImpact
+      # @rbs @automaton: IR::Automaton
+      # @rbs @symbol_ids: Array[Integer]
+      # @rbs @production_ids: Array[Integer]
+      attr_reader :affected_states #: Array[Integer]
+      attr_reader :production_ids #: Array[Integer]
+      attr_reader :conflict_states #: Array[Integer]
+
+      # @rbs (IR::Automaton automaton, Array[Integer]) -> void
+      def initialize(automaton, symbol_ids)
+        @automaton = automaton
+        @symbol_ids = symbol_ids.uniq.sort #: Array[Integer]
+        @production_ids = affected_productions
+        @affected_states = affected_state_ids
+        @conflict_states = conflict_state_ids
+        freeze
+      end
+
+      # @rbs (Hash[Symbol, Object?] diff) -> Hash[Symbol, Object?]
+      def conflict_changes(diff)
+        diff.fetch(:conflicts) #: Hash[Symbol, Object?]
+      end
+
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
+        { states: @affected_states, productions: @production_ids, conflict_states: @conflict_states }
+      end
+
+      private
+
+      # @rbs () -> Array[Integer]
+      def affected_productions
+        @automaton.grammar.productions.filter_map do |production|
+          production.id if @symbol_ids.include?(production.lhs) || production.rhs.any? { |id| @symbol_ids.include?(id) }
+        end.sort
+      end
+
+      # @rbs () -> Array[Integer]
+      def affected_state_ids
+        @automaton.states.filter_map do |state|
+          state.id if state.items.any? { |item| @production_ids.include?(item.production) }
+        end.sort
+      end
+
+      # @rbs () -> Array[Integer]
+      def conflict_state_ids
+        @automaton.states.filter_map { |state| state.id unless state.conflicts.empty? }.sort
+      end
+    end
+  end
+end

data/lib/ibex/impact/coverage_impact.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ibex
+  module Impact
+    # Selects separated runtime coverage reports for affected productions.
+    class CoverageImpact
+      attr_reader :status #: String
+      attr_reader :reports #: Array[Hash[Symbol, Object?]]
+      attr_reader :warnings #: Array[String]
+
+      # @rbs (IR::Automaton automaton, Array[Integer], Array[[String, Coverage::Report]]) -> void
+      def initialize(automaton, production_ids, reports)
+        @automaton = automaton
+        @production_ids = production_ids.sort
+        @warnings = []
+        @reports = select_reports(reports)
+        @status = coverage_status(reports)
+        freeze
+      end
+
+      # @rbs () -> Hash[Symbol, Object?]
+      def to_h
+        { status: @status, reports: @reports }
+      end
+
+      private
+
+      # @rbs (Array[[String, Coverage::Report]]) -> Array[Hash[Symbol, Object?]]
+      def select_reports(reports)
+        selected = reports.filter_map do |path, report|
+          unless report.grammar_digest == @automaton.grammar_digest
+            @warnings << "#{path}: coverage grammar digest does not match the analysis input; report ignored"
+            next
+          end
+
+          hits = report.production_hits.keys & @production_ids
+          next if hits.empty?
+
+          { path: path, productions: hits.sort }
+        end
+        selected.sort_by { |entry| entry.fetch(:path) }
+      end
+
+      # @rbs (Array[[String, Coverage::Report]]) -> String
+      def coverage_status(reports)
+        return "not_requested" if reports.empty?
+
+        @reports.empty? ? "unmatched" : "matched"
+      end
+    end
+  end
+end

data/lib/ibex/impact/graph.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "../analysis"
+
+module Ibex
+  module Impact
+    # A grammar dependency edge with enough origin information for a witness.
+    class Edge
+      attr_reader :source #: Integer
+      attr_reader :target #: Integer
+      attr_reader :kind #: Symbol
+      attr_reader :production #: Integer?
+      attr_reader :position #: Integer?
+
+      # @rbs (source: Integer, target: Integer, kind: Symbol, production: Integer?, position: Integer?) -> void
+      def initialize(source:, target:, kind:, production: nil, position: nil)
+        @source = source
+        @target = target
+        @kind = kind.to_sym
+        @production = production
+        @position = position
+        freeze
+      end
+
+      # @rbs () -> Array[Integer | Symbol | nil]
+      def sort_key
+        [@source, @target, @production || -1, @position || -1, @kind]
+      end
+    end
+
+    # Combines reference, FIRST, and FOLLOW propagation dependencies.
+    class Graph
+      EDGE_KINDS = %i[reference first follow_lhs follow_first].freeze #: Array[Symbol]
+      KIND_ALIASES = {
+        all: EDGE_KINDS, reference: [:reference], first: [:first], follow: %i[follow_lhs follow_first],
+        follow_lhs: [:follow_lhs], follow_first: [:follow_first]
+      }.freeze #: Hash[Symbol, Array[Symbol]]
+
+      attr_reader :grammar #: IR::Grammar
+      attr_reader :sets #: Analysis::Sets
+
+      # @rbs (IR::Grammar grammar, ?sets: Analysis::Sets) -> void
+      def initialize(grammar, sets: nil)
+        @grammar = grammar
+        @sets = sets || Analysis::Sets.new(grammar)
+        @edges = build_edges
+        freeze_edges
+      end
+
+      # @rbs (?Symbol kind) -> untyped
+      def edges(kind = :all)
+        selected = KIND_ALIASES.fetch(kind.to_sym) { raise ArgumentError, "unknown impact edge kind #{kind}" }
+        return selected.flat_map { |name| @edges.fetch(name) }.sort_by(&:sort_key) if selected.length > 1
+
+        @edges.fetch(selected.fetch(0))
+      end
+
+      # @rbs (Symbol kind) -> Array[Array[Integer]]
+      def adjacency(kind)
+        result = Array.new(@grammar.symbols.length) { [] }
+        edges(kind).each { |edge| result[edge.source] << edge.target }
+        result.each(&:uniq!)
+        result
+      end
+
+      private
+
+      # @rbs () -> Hash[Symbol, Array[Edge]]
+      def build_edges
+        result = EDGE_KINDS.to_h { |kind| [kind, []] }
+        @grammar.productions.each do |production|
+          add_production_edges(result, production)
+        end
+        result.each_value { |edges| edges.sort_by!(&:sort_key) }
+        result
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production) -> void
+      def add_production_edges(result, production)
+        production.rhs.each_with_index do |symbol_id, position|
+          next unless @grammar.symbol_by_id(symbol_id)&.nonterminal?
+
+          result[:reference] << edge(symbol_id, production.lhs, :reference, production, position)
+          add_first_edge(result, production, symbol_id, position)
+          add_follow_edges(result, production, symbol_id, position)
+        end
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production, Integer, Integer) -> void
+      def add_first_edge(result, production, symbol_id, position)
+        prefix = production.rhs[0...position] || []
+        return unless @sets.sequence_nullable?(prefix)
+        return unless @sets.first_dependencies.fetch(symbol_id).include?(production.lhs)
+
+        result[:first] << edge(symbol_id, production.lhs, :first, production, position)
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production, Integer, Integer) -> void
+      def add_follow_edges(result, production, symbol_id, position)
+        suffix = production.rhs[(position + 1)..] || []
+        if @sets.sequence_nullable?(suffix) && @sets.follow_dependencies.fetch(production.lhs).include?(symbol_id)
+          result[:follow_lhs] << edge(production.lhs, symbol_id, :follow_lhs, production, position)
+        end
+        add_follow_first_edges(result, production, symbol_id, position)
+      end
+
+      # @rbs (Hash[Symbol, Array[Edge]], IR::Production, Integer, Integer) -> void
+      def add_follow_first_edges(result, production, symbol_id, position)
+        suffix = production.rhs[(position + 1)..] || []
+        suffix.each_with_index do |candidate, offset|
+          candidate_prefix = suffix[0...offset] || []
+          break unless @sets.sequence_nullable?(candidate_prefix)
+          break unless @grammar.symbol_by_id(candidate)&.nonterminal?
+
+          result[:follow_first] << edge(candidate, symbol_id, :follow_first, production, position + 1 + offset)
+        end
+      end
+
+      # @rbs (Integer source, Integer target, Symbol kind, IR::Production production, Integer position) -> Edge
+      def edge(source, target, kind, production, position)
+        Edge.new(source: source, target: target, kind: kind, production: production.id, position: position)
+      end
+
+      # @rbs () -> void
+      def freeze_edges
+        @edges.each_value(&:freeze)
+        @edges.freeze
+      end
+    end
+  end
+end