feat(ruby): add static type checking with Sorbet

.devcontainer/devcontainer.json

@@ -31,7 +31,8 @@
         "zhwu95.riscv",
         "mathematic.vscode-pdf",
         "CraigMaslowski.erb",
-        "HowerLimited.udb-extension-pack-vscode"
+        "HowerLimited.udb-extension-pack-vscode",
+        "sorbet.sorbet-vscode-extension"
       ]
     }
   },

.gitignore

@@ -21,3 +21,4 @@ __pycache__/
 .pytest_cache/
 *.bak
 *.log
+sorbet

.gitmodules

@@ -14,3 +14,6 @@
 [submodule "ext/riscv-tests"]
 	path = ext/riscv-tests
 	url = https://github.com/riscv-software-src/riscv-tests.git
+[submodule "ext/rbi-central"]
+	path = ext/rbi-central
+	url = https://github.com/Shopify/rbi-central

.pre-commit-config.yaml

@@ -119,6 +119,7 @@ repos:
     rev: v5.0.2
     hooks:
       - id: reuse-lint-file
+        exclude: COMMIT_EDITMSG
 
   - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
     rev: v9.22.0

.sorbet-config

@@ -0,0 +1,10 @@
+--dir
+lib
+--dir
+sorbet/rbi
+--file
+Rakefile
+--file
+backends/ext_pdf_doc/idl_lexer.rb
+--file
+backends/cpp_hart_gen/lib/template_helpers.rb

.tapioca-config.yml

@@ -0,0 +1,27 @@
+gem:
+  outdir: .home/.sorbet/rbi/gems
+  file_header: true
+  exclude:
+    [
+      rdoc,
+      asciidoctor-pdf,
+      solargraph,
+      webrick,
+      ttfunk,
+      tapioca,
+      rubocop,
+      rubocop-minitest,
+      spoom,
+      rdbg,
+      parser,
+    ]
+dsl:
+  outdir: .home/.sorbet/rbi/dsl
+  # Add your `dsl` command parameters here:
+  #
+  # exclude:
+  # - SomeGeneratorName
+  # workers: 5
+annotations:
+  sources:
+    - ext/rbi-central

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"
@@ -31,4 +32,7 @@ group :development do
   gem "ruby-prof"
   gem "ruby-prof-flamegraph", git: "https://github.com/oozou/ruby-prof-flamegraph.git", ref: "fc3c437", require: false
   gem "solargraph"
+  gem "sorbet"
+  gem "spoom"
+  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)
     nkf (0.2.0)
     nokogiri (1.18.6-aarch64-linux-gnu)
       racc (~> 1.4)
@@ -126,6 +128,7 @@ GEM
       pdf-reader (~> 2.0)
       prawn (~> 2.2)
     prettyprint (0.2.0)
+    prism (1.4.0)
     psych (5.2.3)
       date
       stringio
@@ -134,6 +137,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)
@@ -189,7 +196,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)
@@ -208,6 +239,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
@@ -234,6 +268,10 @@ DEPENDENCIES
   ruby-prof-flamegraph!
   ruby-progressbar (~> 1.13)
   solargraph
+  sorbet
+  sorbet-runtime
+  spoom
+  tapioca
   treetop (= 1.6.12)
   ttfunk (= 1.7)
   webrick

Rakefile

@@ -1,4 +1,9 @@
 # frozen_string_literal: true
+# typed: true
+
+require "sorbet-runtime"
+T.bind(self, T.all(Rake::DSL, Object))
+extend T::Sig
 
 Encoding.default_external = "UTF-8"
 
@@ -37,8 +42,8 @@ directory "#{$root}/.stamps"
 
 # @param config_locator [String or Pathname]
 # @return [ConfiguredArchitecture]
+sig { params(config_locator: T.any(String, Pathname)).returns(ConfiguredArchitecture) }
 def cfg_arch_for(config_locator)
-  raise ArgumentError, "expecting String or Pathname" unless config_locator.is_a?(String) || config_locator.is_a?(Pathname)
   config_locator = config_locator.to_s
 
   $cfg_archs ||= {}
@@ -163,6 +168,11 @@ namespace :serve do
   end
 end
 
+sig { params(test_files: T::Array[String]).returns(String) }
+def make_test_cmd(test_files)
+  "-Ilib:test -w -e 'require \"minitest/autorun\"; #{test_files.map{ |f| "require \"#{f}\""}.join("; ")}' --"
+end
+
 namespace :test do
 
   # "Run the cross-validation against LLVM"
@@ -175,18 +185,20 @@ namespace :test do
   end
   # "Run the IDL compiler test suite"
   task :idl_compiler do
-    t = Minitest::TestTask.new(:lib_test)
-    t.test_globs = ["#{$root}/lib/idl/tests/test_*.rb"]
-    t.process_env
-    ruby t.make_test_cmd
+    test_files = Dir["#{$root}/lib/idl/tests/test_*.rb"]
+    ruby make_test_cmd(test_files)
   end
 
   # "Run the Ruby library test suite"
   task :lib do
-    t = Minitest::TestTask.new(:lib_test)
-    t.test_globs = ["#{$root}/lib/test/test_*.rb"]
-    t.process_env
-    ruby t.make_test_cmd
+    test_files = Dir["#{$root}/lib/test/test_*.rb"]
+
+    ruby make_test_cmd(test_files)
+  end
+
+  desc "Type-check the Ruby library"
+  task :sorbet do
+    sh "srb tc @.sorbet-config"
   end
 end
 
@@ -208,13 +220,13 @@ namespace :test do
 
     cfg_arch = cfg_arch_for("_")
     insts = cfg_arch.instructions
-    failed = false
+    failed = T.let(false, T::Boolean)
     insts.each_with_index do |inst, idx|
       [32, 64].each do |xlen|
         next unless inst.defined_in_base?(xlen)
 
         (idx...insts.size).each do |other_idx|
-          other_inst = insts[other_idx]
+          other_inst = T.must(insts[other_idx])
           next unless other_inst.defined_in_base?(xlen)
           next if other_inst == inst
 
@@ -236,13 +248,13 @@ namespace :test do
 
     cfg_arch = cfg_arch_for("_")
     csrs = cfg_arch.csrs
-    failed = false
+    failed = T.let(false, T::Boolean)
     csrs.each_with_index do |csr, idx|
       [32, 64].each do |xlen|
         next unless csr.defined_in_base?(xlen)
 
         (idx...csrs.size).each do |other_idx|
-          other_csr = csrs[other_idx]
+          other_csr = T.must(csrs[other_idx])
           next unless other_csr.defined_in_base?(xlen)
           next if other_csr == csr
 
@@ -287,7 +299,6 @@ def insert_warning(str, from)
   first_line = lines.shift
   lines.unshift(first_line, "\n# WARNING: This file is auto-generated from #{Pathname.new(from).relative_path_from($root)}").join("")
 end
-private :insert_warning
 
 (3..31).each do |hpm_num|
   file "#{$root}/arch/csr/Zihpm/mhpmcounter#{hpm_num}.yaml" => [
@@ -440,6 +451,8 @@ namespace :test do
     Rake::Task["test:idl_compiler"].invoke
     $logger.info "Running test:lib"
     Rake::Task["test:lib"].invoke
+    $logger.info "UPDATE: Running test:sorbet"
+    Rake::Task["test:sorbet"].invoke
     $logger.info "Running test:schema"
     Rake::Task["test:schema"].invoke
     $logger.info "Running test:idl"

backends/cpp_hart_gen/templates/csrs_impl.hxx.erb

@@ -56,11 +56,7 @@ void <%= name_of(:csr_field, cfg_arch, csr.name, field.name) %><SocType>::reset(
   <%- end -%>
   <%- else -%>
   auto val_fn = [this]() ->
-    <%- if field.could_be_undefined? -%>
     PossiblyUnknownBits<<%= max_width + 1 %>>
-    <%- else -%>
-    Bits<<%= max_width + 1 %>>
-    <%- end -%>
   {
     <%= ast.gen_cpp(cfg_arch.symtab, 8) %>
   };

backends/ext_pdf_doc/tasks.rake

@@ -2,9 +2,6 @@
 
 require "pathname"
 
-require "asciidoctor-pdf"
-require "asciidoctor-diagram"
-
 require_relative "#{$lib}/idl/passes/gen_adoc"
 
 EXT_PDF_DOC_DIR = Pathname.new "#{$root}/backends/ext_pdf_doc"

backends/portfolio/tasks.rake

@@ -3,8 +3,6 @@
 # Contains common methods called from portfolio-based tasks.rake files.
 
 require "pathname"
-require "asciidoctor-pdf"
-require "asciidoctor-diagram"
 require_relative "#{$lib}/idl/passes/gen_adoc"
 
 # @return [Architecture]

backends/proc_cert/tasks.rake

@@ -3,8 +3,6 @@
 # Contains common methods called from certification backend tasks.rake files.
 
 require "pathname"
-require "asciidoctor-pdf"
-require "asciidoctor-diagram"
 
 # @param erb_template_pname [String] Path to ERB template file
 # @param target_pname [String] Full name of adoc file being generated

bin/clobber

@@ -2,4 +2,11 @@
 
 ROOT=$(dirname $(dirname $(realpath ${BASH_SOURCE[0]})))
 
-rm -rf ${ROOT}/.stamps ${ROOT}/.home ${ROOT}/.bundle ${ROOT}/.singularity ${ROOT}/gen ${ROOT}/node_modules
+rm -rf                 \
+  ${ROOT}/.stamps      \
+  ${ROOT}/.home        \
+  ${ROOT}/.bundle      \
+  ${ROOT}/.singularity \
+  ${ROOT}/gen          \
+  ${ROOT}/node_modules \
+  ${ROOT}/sorbet

bin/setup

@@ -144,6 +144,23 @@ if [ ! -d $ROOT/.home/.gems ]; then
     cd $OLDDIR
 fi
 
+if [ ! -f $ROOT/ext/rbi-central/README.md ]; then
+    git submodule update --init ext/rbi-central
+fi
+
+if [ ! -d $ROOT/.home/.sorbet ]; then
+    mkdir .home/.sorbet
+    ln -s .home/.sorbet sorbet
+    cd .home/.sorbet
+    ln -s ../../.sorbet-config config
+    cd $ROOT
+    ${RUN} bundle exec tapioca init -c ${ROOT}/.tapioca-config.yml
+    ${RUN} bundle exec tapioca dsl -c ${ROOT}/.tapioca-config.yml
+    cd .home/.sorbet/rbi/dsl
+    ln -s ${ROOT}/lib/architecture.rbi
+    cd $ROOT
+fi
+
 if [ ! -d $ROOT/.home/.venv ]; then
     ${RUN} /usr/bin/python3 -m venv ${ROOT}/.home/.venv
 fi

bin/tapioca

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby3.2
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tapioca", "tapioca")