ibex-runtime 0.2.0 → 0.4.0

data/lib/ibex/runtime/event_sanitizer.rb

@@ -6,6 +6,10 @@ module Ibex
     # Converts application-owned values into bounded, data-only event summaries.
     # rubocop:disable Metrics/ModuleLength
     module EventSanitizer
+      # @rbs!
+      #   type json_value = String | Integer | Float | bool | nil | Array[json_value] | Hash[String, json_value]
+      #   type sanitized_value = untyped
+
       MAX_DEPTH = 3 #: Integer
       MAX_COLLECTION_ENTRIES = 16 #: Integer
       MAX_STRING_BYTES = 256 #: Integer
@@ -17,9 +21,9 @@ module Ibex
         # Copy a runtime payload into deeply frozen JSON data. Unknown objects are
         # summarized instead of being retained, so callers cannot smuggle mutable
         # application identities into an Event.
-        # @rbs (Hash[untyped, untyped] input) -> Hash[String, untyped]
+        # @rbs (Hash[sanitized_value, sanitized_value] input) -> Hash[String, json_value]
         def data(input)
-          result = {} #: Hash[String, untyped]
+          result = {} # @type var result: Hash[String, json_value]
           consumed = 0
           core_call(Hash, :each_pair, input) do |key, raw|
             break if consumed == MAX_COLLECTION_ENTRIES
@@ -32,14 +36,14 @@ module Ibex
           { "unavailable" => "event_data" }.freeze
         end
 
-        # @rbs (untyped input) -> untyped
+        # @rbs (sanitized_value input) -> json_value
         def value(input)
           summarize(input, depth: 0, seen: {})
         rescue StandardError
           unavailable("sanitization")
         end
 
-        # @rbs (untyped location) -> Hash[String, untyped]?
+        # @rbs (sanitized_value location) -> Hash[String, json_value]?
         def location(location)
           return nil unless location
 
@@ -55,7 +59,7 @@ module Ibex
           unavailable("location")
         end
 
-        # @rbs (untyped input) -> String
+        # @rbs (sanitized_value input) -> String
         def string(input)
           return "<unavailable>" unless core_type?(input, String)
 
@@ -78,7 +82,7 @@ module Ibex
           "<unavailable>"
         end
 
-        # @rbs (untyped input) -> String
+        # @rbs (sanitized_value input) -> String
         def class_name(input)
           klass = core_call(Object, :class, input)
           name = core_call(Module, :name, klass)
@@ -89,7 +93,7 @@ module Ibex
 
         private
 
-        # @rbs (untyped input, depth: Integer, seen: Hash[Integer, bool]) -> untyped
+        # @rbs (sanitized_value input, depth: Integer, seen: Hash[Integer, bool]) -> json_value
         def summarize(input, depth:, seen:)
           return input if primitive?(input)
           return bounded_integer(input) if core_type?(input, Integer)
@@ -102,7 +106,7 @@ module Ibex
           { "type" => "object", "class" => class_name(input) }.freeze
         end
 
-        # @rbs (untyped input, depth: Integer, seen: Hash[Integer, bool]) -> untyped
+        # @rbs (sanitized_value input, depth: Integer, seen: Hash[Integer, bool]) -> json_value
         def json_data(input, depth:, seen:)
           return unavailable("depth") if depth >= DATA_MAX_DEPTH
           return input if primitive?(input)
@@ -116,7 +120,7 @@ module Ibex
           { "type" => "object", "class" => class_name(input) }.freeze
         end
 
-        # @rbs (Array[untyped] input, depth: Integer, seen: Hash[Integer, bool]) -> untyped
+        # @rbs (Array[sanitized_value] input, depth: Integer, seen: Hash[Integer, bool]) -> json_value
         def summarize_array(input, depth:, seen:)
           return unavailable("depth") if depth >= MAX_DEPTH
 
@@ -125,7 +129,7 @@ module Ibex
           end
         end
 
-        # @rbs (Hash[untyped, untyped] input, depth: Integer, seen: Hash[Integer, bool]) -> untyped
+        # @rbs (Hash[sanitized_value, sanitized_value] input, depth: Integer, seen: Hash[Integer, bool]) -> json_value
         def summarize_hash(input, depth:, seen:)
           return unavailable("depth") if depth >= MAX_DEPTH
 
@@ -133,7 +137,7 @@ module Ibex
           return { "cycle" => true }.freeze if seen[identity]
 
           nested = seen.merge(identity => true)
-          entries = [] #: Array[untyped]
+          entries = [] # @type var entries: Array[Array[json_value]]
           length = core_call(Hash, :length, input)
           core_call(Hash, :each_pair, input) do |key, child|
             break if entries.length == MAX_COLLECTION_ENTRIES
@@ -148,20 +152,20 @@ module Ibex
           summary.freeze
         end
 
-        # @rbs (Array[untyped] input, depth: Integer, seen: Hash[Integer, bool]) -> untyped
+        # @rbs (Array[sanitized_value] input, depth: Integer, seen: Hash[Integer, bool]) -> json_value
         def json_array(input, depth:, seen:)
           copy_array(input, seen: seen) do |child, nested|
             json_data(child, depth: depth + 1, seen: nested)
           end
         end
 
-        # @rbs (Hash[untyped, untyped] input, depth: Integer, seen: Hash[Integer, bool]) -> untyped
+        # @rbs (Hash[sanitized_value, sanitized_value] input, depth: Integer, seen: Hash[Integer, bool]) -> json_value
         def json_hash(input, depth:, seen:)
           identity = object_identity(input)
           return { "cycle" => true }.freeze if seen[identity]
 
           nested = seen.merge(identity => true)
-          result = {} #: Hash[String, untyped]
+          result = {} # @type var result: Hash[String, json_value]
           length = core_call(Hash, :length, input)
           consumed = 0
           core_call(Hash, :each_pair, input) do |key, child|
@@ -174,8 +178,8 @@ module Ibex
           result.freeze
         end
 
-        # @rbs (Array[untyped] input, seen: Hash[Integer, bool])
-        #   { (untyped, Hash[Integer, bool]) -> untyped } -> untyped
+        # @rbs (Array[sanitized_value] input, seen: Hash[Integer, bool])
+        #   { (sanitized_value, Hash[Integer, bool]) -> json_value } -> json_value
         def copy_array(input, seen:)
           identity = object_identity(input)
           return { "cycle" => true }.freeze if seen[identity]
@@ -191,14 +195,14 @@ module Ibex
           result.freeze
         end
 
-        # @rbs (untyped input) -> bool
+        # @rbs (sanitized_value input) -> bool
         def primitive?(input)
           core_type?(input, NilClass) ||
             core_type?(input, TrueClass) ||
             core_type?(input, FalseClass)
         end
 
-        # @rbs (Integer input) -> untyped
+        # @rbs (Integer input) -> json_value
         def bounded_integer(input)
           bits = core_call(Integer, :bit_length, input)
           return input if bits <= MAX_INTEGER_BITS
@@ -210,17 +214,17 @@ module Ibex
           }.freeze
         end
 
-        # @rbs (Float input) -> untyped
+        # @rbs (Float input) -> json_value
         def finite_float(input)
           core_call(Float, :finite?, input) ? input : string(core_call(Float, :to_s, input))
         end
 
-        # @rbs (untyped input, Module type) -> bool
+        # @rbs (sanitized_value input, Module type) -> bool
         def core_type?(input, type)
           core_call(Module, :===, type, input)
         end
 
-        # @rbs (untyped key) -> String
+        # @rbs (sanitized_value key) -> String
         def data_key(key)
           return string(key) if core_type?(key, String)
           return string(core_call(Symbol, :name, key)) if core_type?(key, Symbol)
@@ -237,12 +241,12 @@ module Ibex
           "#{prefix}\u2026".freeze
         end
 
-        # @rbs (untyped input) -> Integer
+        # @rbs (sanitized_value input) -> Integer
         def object_identity(input)
           core_call(BasicObject, :__id__, input)
         end
 
-        # @rbs (untyped location, Symbol field) -> untyped
+        # @rbs (sanitized_value location, Symbol field) -> sanitized_value
         def location_field(location, field)
           if core_type?(location, Hash)
             return core_call(Hash, :fetch, location, field) do
@@ -256,13 +260,15 @@ module Ibex
           nil
         end
 
-        # @rbs (String reason) -> Hash[String, untyped]
+        # @rbs (String reason) -> Hash[String, json_value]
         def unavailable(reason)
           { "unavailable" => reason.freeze }.freeze
         end
 
-        # @rbs (Module owner, Symbol method_name, untyped receiver, *untyped args, **untyped keywords)
-        #   ?{ (*untyped) -> untyped } -> untyped
+        # Reflection deliberately erases the receiver's method signature; callers validate
+        # returned values at each sanitization boundary.
+        # @rbs (Module owner, Symbol method_name, sanitized_value receiver, *sanitized_value, **sanitized_value)
+        #   ?{ (*sanitized_value) -> sanitized_value } -> sanitized_value
         def core_call(owner, method_name, receiver, ...)
           owner.instance_method(method_name).bind(receiver).call(...)
         end

data/lib/ibex/runtime/generated_lexer.rb

@@ -21,7 +21,7 @@ module Ibex
       # @rbs @lexer_byte_column: Integer
       # @rbs @lexer_byte_offset: Integer
       # @rbs @lexer_lexeme: String?
-      # @rbs @lexer_emission: Object | Array[untyped]
+      # @rbs @lexer_emission: Object | Array[Object?]
       # @rbs @lexer_skip_requested: bool
       # @rbs @lexer_pending_green_trivia: Array[CST::GreenTrivia]
       # @rbs @lexer_cst_trivia_policy: Symbol
@@ -47,8 +47,11 @@ module Ibex
         self
       end
 
-      # Lex and parse one String, IO, or Fiber source.
-      # @rbs (String | IO | Fiber source, ?file: String) -> untyped
+      # Lex and semantically parse one String, IO, or Fiber source.
+      # Parser and generated lexer actions execute. Loading the generated file
+      # may also execute user sections; this trusted application path is not a
+      # sandbox.
+      # @rbs (String | IO | Fiber source, ?file: String) -> Object?
       def parse(source, file: "(input)")
         lex(source, file: file)
         parser = self #: Parser
@@ -61,6 +64,8 @@ module Ibex
       end
 
       # Parse one generated-lexer source and return its semantic and syntax results.
+      # Parser and generated lexer actions execute. This trusted application
+      # path is not a sandbox.
       # @rbs (String | IO | Fiber source, ?file: String) -> CST::ParseResult
       def parse_with_syntax(source, file: "(input)")
         lex(source, file: file)
@@ -76,7 +81,9 @@ module Ibex
       end
 
       # Parse without executing parser production actions.
-      # Lexer actions still run because they define tokenization and lexer state.
+      # Generated lexer actions still run because they define tokenization and
+      # lexer state. Loading user sections and running lexer actions are trusted
+      # application boundaries, so this method is not a no-user-code sandbox.
       # @rbs (String source, ?file: String) -> CST::SyntaxResult
       def parse_syntax(source, file: "(input)")
         parse_syntax_with_cache(CST::SourceText.new(source, file: file), CST::NodeCache.new)
@@ -98,7 +105,7 @@ module Ibex
       end
 
       # Pull one token using longest match and declaration-order tie breaking.
-      # @rbs () -> [untyped, untyped, Hash[Symbol, untyped]]
+      # @rbs () -> [Object?, Object?, Hash[Symbol, Object?]]
       def next_token
         input = @lexer_input
         raise ParseError, "(lexer):1:1: call parse or lex before next_token" unless input
@@ -148,7 +155,7 @@ module Ibex
       # @rbs (CST::SourceText source_text, CST::NodeCache cache) -> CST::LexedSyntax
       def scan_syntax_with_cache(source_text, cache)
         lex(source_text.text, file: source_text.file || "(input)")
-        raw_tokens = [] #: Array[Array[untyped]]
+        raw_tokens = [] #: Array[Array[Object?]]
         green_tokens = [] #: Array[CST::GreenToken]
         states = [] #: Array[Symbol]
         loop do
@@ -159,7 +166,7 @@ module Ibex
           raw_tokens << [external, value, location]
           green_tokens << green
           state = location[:ibex_lexer_start_state] if location.is_a?(Hash)
-          states << (state ? state.to_sym : :INITIAL)
+          states << (state ? state.to_s.to_sym : :INITIAL)
           break if token_id == Parser::EOF_TOKEN
         end
         offsets = [] #: Array[Integer]
@@ -172,7 +179,7 @@ module Ibex
         CST::LexedSyntax.new(raw_tokens: raw_tokens, memo: memo)
       end
 
-      # @rbs (Integer token_id, untyped value, untyped location, CST::NodeCache cache) -> CST::GreenToken
+      # @rbs (Integer token_id, Object? value, Object? location, CST::NodeCache cache) -> CST::GreenToken
       def scanned_green_token(token_id, value, location, cache)
         leading = scanned_green_trivia(location, :leading_trivia)
         text = if location.is_a?(Hash) && location[:ibex_cst_text].is_a?(String)
@@ -186,7 +193,7 @@ module Ibex
         cache.intern_token_fields(kind: token_id, text: text, leading: leading)
       end
 
-      # @rbs (Array[CST::GreenToken] tokens, untyped location, CST::NodeCache cache) -> void
+      # @rbs (Array[CST::GreenToken] tokens, Object? location, CST::NodeCache cache) -> void
       def replace_previous_scanned_trailing(tokens, location, cache)
         trailing = scanned_green_trivia(location, :cst_previous_trailing)
         previous = tokens.last
@@ -202,7 +209,7 @@ module Ibex
         )
       end
 
-      # @rbs (untyped location, Symbol key) -> Array[CST::GreenTrivia]
+      # @rbs (Object? location, Symbol key) -> Array[CST::GreenTrivia]
       def scanned_green_trivia(location, key)
         return [] unless location.is_a?(Hash)
 
@@ -275,8 +282,8 @@ module Ibex
         }
       end
 
-      # @rbs (Hash[Symbol, untyped] rule, String lexeme, Hash[Symbol, untyped] location) ->
-      #   [untyped, untyped, Hash[Symbol, untyped]]?
+      # @rbs (Hash[Symbol, untyped] rule, String lexeme, Hash[Symbol, Object?] location) ->
+      #   [Object?, Object?, Hash[Symbol, Object?]]?
       def apply_lexer_rule(rule, lexeme, location)
         @lexer_lexeme = lexeme
         @lexer_emission = NO_EMISSION
@@ -310,7 +317,7 @@ module Ibex
       end
 
       # Emit a token from a lexer action.
-      # @rbs (untyped token, ?untyped value) -> untyped
+      # @rbs (Object? token, ?Object? value) -> Object?
       def emit(token, value = NO_EMISSION)
         actual = value.equal?(NO_EMISSION) ? @lexer_lexeme : value
         @lexer_emission = [token, actual]
@@ -330,7 +337,7 @@ module Ibex
         @lexer_lexeme
       end
 
-      # @rbs (String text, Hash[Symbol, untyped] location) -> void
+      # @rbs (String text, Hash[Symbol, Object?] location) -> void
       def retain_cst_trivia(text, _location)
         return if cst_trivia_policy == :drop
 
@@ -344,7 +351,7 @@ module Ibex
         @lexer_pending_green_trivia << value
       end
 
-      # @rbs (Hash[Symbol, untyped] location) -> Hash[Symbol, untyped]
+      # @rbs (Hash[Symbol, Object?] location) -> Hash[Symbol, Object?]
       def attach_cst_trivia(location)
         policy = cst_trivia_policy
         trivia = @lexer_pending_green_trivia
@@ -481,7 +488,7 @@ module Ibex
         }
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def lexer_zero_width_location
         position = lexer_position
         {

data/lib/ibex/runtime/lexer_input.rb

@@ -78,7 +78,7 @@ module Ibex
         append(text)
       end
 
-      # @rbs (Fiber source) -> untyped
+      # @rbs (Fiber source) -> Object?
       def resume_fiber(source)
         supports_alive = source.respond_to?(:alive?)
         if supports_alive && !source.alive?

data/lib/ibex/runtime/location_span.rb

@@ -9,10 +9,10 @@ module Ibex
     # supplied by the lexer. A reduction wraps the outer boundaries in this
     # immutable value so actions can distinguish synthesized spans.
     class LocationSpan
-      attr_reader :start #: untyped
-      attr_reader :finish #: untyped
+      attr_reader :start #: Object?
+      attr_reader :finish #: Object?
 
-      # @rbs (start: untyped, finish: untyped, ?empty: bool) -> void
+      # @rbs (start: Object?, finish: Object?, ?empty: bool) -> void
       def initialize(start:, finish:, empty: false)
         @start = start
         @finish = finish
@@ -23,7 +23,7 @@ module Ibex
       # Build a span for an LR reduction. Nonempty reductions cover the first
       # through last located RHS entry. Empty reductions are zero-width at the
       # current lookahead location.
-      # @rbs (Array[untyped] locations, lookahead: untyped) -> LocationSpan?
+      # @rbs (Array[Object?] locations, lookahead: Object?) -> LocationSpan?
       def self.for_reduction(locations, lookahead:)
         if locations.empty?
           return unless lookahead
@@ -44,40 +44,40 @@ module Ibex
         @empty
       end
 
-      # @rbs () -> untyped
+      # @rbs () -> Object?
       def file = location_value(@start, :file)
 
-      # @rbs () -> untyped
+      # @rbs () -> Object?
       def line = location_value(@start, :line)
 
-      # @rbs () -> untyped
+      # @rbs () -> Object?
       def column = location_value(@start, :column)
 
-      # @rbs () -> untyped
+      # @rbs () -> Object?
       def source_line = location_value(@start, :source_line)
 
-      # @rbs () -> untyped
+      # @rbs () -> Object?
       def end_file
         return file if empty?
 
         location_value(@finish, :end_file) || location_value(@finish, :file)
       end
 
-      # @rbs () -> untyped
+      # @rbs () -> Object?
       def end_line
         return line if empty?
 
         location_value(@finish, :end_line) || location_value(@finish, :line)
       end
 
-      # @rbs () -> untyped
+      # @rbs () -> Object?
       def end_column
         return column if empty?
 
         location_value(@finish, :end_column) || location_value(@finish, :column)
       end
 
-      # @rbs () -> Hash[Symbol, untyped]
+      # @rbs () -> Hash[Symbol, Object?]
       def to_h
         {
           file: file, line: line, column: column,
@@ -89,12 +89,12 @@ module Ibex
       class << self
         private
 
-        # @rbs (untyped location) -> untyped
+        # @rbs (Object? location) -> Object?
         def boundary_start(location)
           location.is_a?(LocationSpan) ? location.start : location
         end
 
-        # @rbs (untyped location) -> untyped
+        # @rbs (Object? location) -> Object?
         def boundary_finish(location)
           location.is_a?(LocationSpan) ? location.finish : location
         end
@@ -102,7 +102,7 @@ module Ibex
 
       private
 
-      # @rbs (untyped location, Symbol key) -> untyped
+      # @rbs (Object? location, Symbol key) -> Object?
       def location_value(location, key)
         return location.public_send(key) if location.respond_to?(key)
         return location[key] || location[key.to_s] if location.is_a?(Hash)

data/lib/ibex/runtime/observation.rb

@@ -57,7 +57,7 @@ module Ibex
 
       private
 
-      # @rbs (Symbol type, Hash[untyped, untyped] data, ?observers: Array[Proc]?) -> void
+      # @rbs (Symbol type, Hash[Object?, Object?] data, ?observers: Array[Proc]?) -> void
       def emit_runtime_event(type, data, observers: runtime_observer_snapshot)
         return unless observers