Add Ruby typechecking with Sorbet and Tapioca

Author: dhower-qc

Gemfile

@@ -16,6 +16,7 @@ gem "pygments.rb"
 gem "rake", "~> 13.0"
 gem "rouge"
 gem "ruby-progressbar", "~> 1.13"
+gem 'sorbet-runtime'
 gem "treetop", "1.6.12"
 gem "ttfunk", "1.7" # needed to avoid having asciidoctor-pdf dependencies pulling in a buggy version of ttunk (1.8)
 gem "webrick"
@@ -29,5 +30,7 @@ group :development do
   gem "rubocop-minitest"
   gem "ruby-prof"
   gem "ruby-prof-flamegraph", git: "https://github.com/oozou/ruby-prof-flamegraph.git", ref: "fc3c437", require: false
+  gem "sorbet"
   gem "solargraph"
+  gem 'tapioca', require: false
 end

Gemfile.lock

@@ -65,6 +65,7 @@ GEM
       reline (>= 0.3.8)
     diff-lcs (1.6.0)
     drb (2.2.1)
+    erubi (1.13.1)
     hana (1.3.7)
     hashery (2.1.2)
     i18n (1.14.7)
@@ -89,6 +90,7 @@ GEM
     logger (1.6.6)
     matrix (0.4.2)
     minitest (5.25.5)
+    netrc (0.11.0)
     nokogiri (1.18.6-aarch64-linux-gnu)
       racc (~> 1.4)
     nokogiri (1.18.6-x86_64-linux-gnu)
@@ -125,6 +127,7 @@ GEM
       pdf-reader (~> 2.0)
       prawn (~> 2.2)
     prettyprint (0.2.0)
+    prism (1.4.0)
     psych (5.2.3)
       date
       stringio
@@ -133,6 +136,10 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
+    rbi (0.3.1)
+      prism (~> 1.0)
+      rbs (>= 3.4.4)
+      sorbet-runtime (>= 0.5.9204)
     rbs (3.9.1)
       logger
     rdbg (0.1.0)
@@ -187,7 +194,31 @@ GEM
       tilt (~> 2.0)
       yard (~> 0.9, >= 0.9.24)
       yard-solargraph (~> 0.1)
+    sorbet (0.5.11966)
+      sorbet-static (= 0.5.11966)
+    sorbet-runtime (0.5.11966)
+    sorbet-static (0.5.11966-aarch64-linux)
+    sorbet-static (0.5.11966-x86_64-linux)
+    sorbet-static-and-runtime (0.5.11966)
+      sorbet (= 0.5.11966)
+      sorbet-runtime (= 0.5.11966)
+    spoom (1.6.1)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.2.3)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
     stringio (3.1.5)
+    tapioca (0.16.11)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
     thor (1.3.2)
     tilt (2.6.0)
     treetop (1.6.12)
@@ -203,6 +234,9 @@ GEM
     yard (0.9.37)
     yard-solargraph (0.1.0)
       yard (~> 0.9)
+    yard-sorbet (0.9.0)
+      sorbet-runtime
+      yard
 
 PLATFORMS
   aarch64-linux-gnu
@@ -229,6 +263,9 @@ DEPENDENCIES
   ruby-prof-flamegraph!
   ruby-progressbar (~> 1.13)
   solargraph
+  sorbet
+  sorbet-runtime
+  tapioca
   treetop (= 1.6.12)
   ttfunk (= 1.7)
   webrick

Rakefile

@@ -162,6 +162,11 @@ namespace :test do
     t.process_env
     ruby t.make_test_cmd
   end
+
+  desc "Type-check the Ruby library"
+  task :sorbet do
+    sh "srb tc --no-config @.sorbet-config"
+  end
 end
 
 desc "Clean up all generated files"
@@ -409,6 +414,7 @@ namespace :test do
   task :smoke do
     Rake::Task["test:idl_compiler"].invoke
     Rake::Task["test:lib"].invoke
+    Rake::Task["test:sorbet"].invoke
     Rake::Task["test:schema"].invoke
     Rake::Task["test:idl"].invoke
     Rake::Task["test:inst_encodings"].invoke

bin/tapioca

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+ROOT=$(dirname $(realpath ${BASH_SOURCE[0]}))
+source $ROOT/setup
+
+$BUNDLE exec tapioca "$@"

cfgs/config_validation.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative "obj"
 
@@ -176,7 +177,7 @@ def length(effective_xlen = nil)
     when Integer
       @data["length"]
     else
-      raise "Unexpected length field for #{csr.name}"
+      raise "Unexpected length field for #{name}"
     end
   end
 
@@ -210,7 +211,7 @@ def max_length
     when Integer
       @data["length"]
     else
-      raise "Unexpected length field for #{csr.name}"
+      raise "Unexpected length field for #{name}"
     end
   end
 
@@ -306,6 +307,7 @@ def possible_fields_for(effective_xlen)
 
   # @return [Array<CsrField>] All implemented fields for this CSR
   #                           Excluded any fields that are defined by unimplemented extensions
+  sig {returns(T::Array[CsrField])}
   def possible_fields
     @possible_fields ||= fields.select do |f|
       f.exists_in_cfg?(cfg_arch)
@@ -321,6 +323,7 @@ def fields
 
   # @return [Array<CsrField>] All known fields of this CSR when XLEN == +effective_xlen+
   # equivalent to {#fields} if +effective_xlen+ is nil
+  sig {params(effective_xlen: T.nilable(Integer)).returns(T::Array[CsrField])}
   def fields_for(effective_xlen)
     fields.select { |f| effective_xlen.nil? || !f.key?("base") || f.base == effective_xlen }
   end
@@ -518,7 +521,7 @@ def wavedrom_desc(cfg_arch, effective_xlen, exclude_unimplemented: false, option
       else
         desc["reg"] << { "bits" => field.location(effective_xlen).size, "name" => field.name, type: 3 }
       end
-      last_idx = field.location(effective_xlen).max
+      last_idx = T.cast(field.location(effective_xlen).max, Integer)
     end
     if !field_list.empty? && (field_list.last.location(effective_xlen).max != (length(effective_xlen) - 1))
       # reserved space at the end

lib/arch_obj_models/csr.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
+# typed: true
+
+require "sorbet-runtime"
 
 require_relative "obj"
 
 require_relative "../idl/passes/gen_option_adoc"
 
 # A CSR field object
 class CsrField < DatabaseObject
+  extend T::Sig;
+
   # @return [Csr] The Csr that defines this field
   attr_reader :parent
 
@@ -67,7 +72,7 @@ def optional_in_cfg?(cfg_arch)
   #                   This does not take the parent CSR into account, i.e., a field can be unaffected
   #                   by ext_ver even if the parent CSR is affected
   def affected_by?(ext_ver)
-    @data["definedBy"].nil? ? false : defined_by_condition.possibly_satisfied_by?(version)
+    @data["definedBy"].nil? ? false : defined_by_condition.possibly_satisfied_by?(ext_ver)
   end
 
   # @return [Idl::FunctionBodyAst] Abstract syntax tree of the type() function
@@ -168,6 +173,7 @@ def type(effective_xlen = nil)
     @type ||= { 32 => nil, 64 => nil }
     return @type[effective_xlen] unless @type[effective_xlen].nil?
 
+    type = T.let(nil, T.untyped)
     type =
       if @data.key?("type")
         @data["type"]
@@ -223,7 +229,7 @@ def type(effective_xlen = nil)
   def type_pretty(effective_xlen = nil)
     raise ArgumentError, "Expecting Integer" unless effective_xlen.nil? || effective_xlen.is_a?(Integer)
 
-    str = nil
+    str = T.let(nil, T.nilable(String))
     value_result = Idl::AstNode.value_try do
       str = type(effective_xlen)
     end
@@ -241,7 +247,7 @@ def alias
     if @data.key?("alias")
       raise "Can't parse alias" unless data["alias"] =~ /^[a-z][a-z0-9]+\.[A-Z0-9]+(\[([0-9]+)(:[0-9]+)?\])?$/
 
-      csr_name = Regexp.last_match(1)
+      csr_name = T.must(Regexp.last_match(1))
       csr_field = Regexp.last_match(2)
       range = Regexp.last_match(3)
       range_start = Regexp.last_match(4)
@@ -250,7 +256,7 @@ def alias
       csr_field = cfg_arch.csr(csr_name).field(csr_field)
       range =
         if range.nil?
-          field.location
+          csr_field.location
         elsif range_end.nil?
           (range_start.to_i..range_start.to_i)
         else
@@ -374,7 +380,7 @@ def reset_value
       else
         ast = pruned_reset_value_ast
         symtab = fill_symtab_for_reset(ast)
-        val = nil
+        val = T.let(nil, T.untyped)
         value_result = Idl::AstNode.value_try do
           val = ast.return_value(symtab)
         end
@@ -398,7 +404,7 @@ def dynamic_reset_value?
   end
 
   def reset_value_pretty
-    str = nil
+    str = T.let(nil, T.nilable(String))
     value_result = Idl::AstNode.value_try do
       str = reset_value
     end
@@ -591,6 +597,7 @@ def pruned_sw_write_ast(effective_xlen)
   # @param cfg_arch [ConfiguredArchitecture] A config. May be nil if the location is not configturation-dependent
   # @param effective_xlen [Integer] The effective xlen, needed since some fields change location with XLEN. If the field location is not determined by XLEN, then this parameter can be nil
   # @return [Range] the location within the CSR as a range (single bit fields will be a range of size 1)
+  sig { params(effective_xlen: T.nilable(Integer)).returns(T::Range[Integer]) }
   def location(effective_xlen = nil)
     key =
       if @data.key?("location")
@@ -615,7 +622,9 @@ def location(effective_xlen = nil)
       end
 
       @data[key]..@data[key]
-    elsif @data[key].is_a?(String)
+    else
+      raise "Unexpected location field" unless @data[key].is_a?(String)
+
       e, s = @data[key].split("-").map(&:to_i)
       raise "Invalid location" if s > e
 

lib/arch_obj_models/csr_field.rb

@@ -2,6 +2,7 @@
 
 require_relative "obj"
 require_relative "schema"
+require_relative "req_expression"
 require_relative "../version"
 
 # A parameter (AKA option, AKA implementation-defined value) supported by an extension