houndstooth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0febf254b01185f48cc75c1fc717a524e90dedaebbcbf156b4db2da8f2c6cc4d
+  data.tar.gz: 7d553f1ad85674e0fd5286a9c0414c5c0dfd72ba8e6ae7a648ace0f2fe566222
+SHA512:
+  metadata.gz: bfd945c4d810464e80e389711cc7e8eb367688a7a76c6fd5db1da45e5a509163d3d7dbe1f54d97339913620205134848522304a8c21a19fe1c03dcc41f284cc0
+  data.tar.gz: abfb4d5da0b0232d2279b47d1be19dd4b4935a0f6949679e345f27eb06420eecbb1c26bf1af52ff58c9c8ff8d3254e99544d252ed4febc728d4bf25fc32ffa24

data/.gitignore

@@ -0,0 +1,5 @@
+playground
+fuzz/out
+coverage
+.DS_Store
+fuzz-out

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.0.3

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+gem 'parser'
+gem 'rspec'
+gem 'simplecov'
+gem 'rbs'
+gem 'optimist'
+
+group :development do
+    gem 'afl', git: 'https://github.com/richo/afl-ruby.git'
+end

data/Gemfile.lock

@@ -0,0 +1,49 @@
+GIT
+  remote: https://github.com/richo/afl-ruby.git
+  revision: cbaad7a5fadca7b1617a211d571f7badc80fec82
+  specs:
+    afl (0.0.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    optimist (3.0.1)
+    parser (3.1.0.0)
+      ast (~> 2.4.1)
+    rbs (2.1.0)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.2)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.3)
+
+PLATFORMS
+  arm64-darwin-21
+
+DEPENDENCIES
+  afl!
+  optimist
+  parser
+  rbs
+  rspec
+  simplecov
+
+BUNDLED WITH
+   2.2.22

data/README.md

@@ -0,0 +1,99 @@
+# Houndstooth
+
+Houndstooth is a **highly-experimental Ruby static type checker**, which is uniquely
+**metaprogramming-aware**.
+
+Houndstooth was created for my final-year project at the University of York. It is far from
+production-ready, and should be treated here as a proof-of-concept!
+
+Here's an annotated example of what this enables you to do:
+
+```ruby
+#!var @name String
+#!var @graduate Boolean
+class Student
+    #!arg String
+    attr_reader :name
+
+    # Now we'd like to define an accessor for our boolean variable, @graduate. But we usually like
+    # methods returning a boolean to end in ?, so we can't use `attr_accessor`.
+    # Instead, let's define our own helper, `bool_accessor`
+
+    #: (Symbol) -> void
+    #!const required
+    #  ^ This special annotation means, "hey, type checker - you need to check out what this does!"
+    def self.bool_accessor(name)
+        # Define our method #<name>?
+        #!arg Boolean
+        attr_reader "#{name}?".to_sym
+
+        # ...and also define a normal writer, #<name>=
+        #!arg Boolean
+        attr_writer name
+    end
+
+    # Now use our neat new helper
+    bool_accessor :graduate
+
+    #: (String) -> void
+    def initialize(name)
+        @name = name
+        @graduate = false
+    end
+end
+
+# The type checker sees those `graduate?` and `graduate=` definitions, even though they were
+# dynamic!
+s = Student.new("Aaron")
+s.graduate? # => false
+s.graduate = true
+s.graduate? # => true
+```
+
+It even understands control flow such as loops:
+
+```ruby
+class Adder
+    1000.times do |i,|
+        #!arg Integer
+        #!arg Integer
+        #  ^ These annotations are the parameter type (first one) and return type (second one)
+        define_method :"add_#{i}" do |input,|
+            i + input
+        end
+    end
+end
+
+# Now we can add to our heart's content
+a = Adder.new
+x = a.add_123(a.add_5(3))
+```
+
+Houndstooth includes a minimal Ruby interpreter capable of evaluating a pure and deterministic
+subset of the language. Using this, it executes portions of your codebase to discover methods which
+will be dynamically defined at runtime.
+
+All methods can optionally be tagged, either as:
+
+- _const_, which means they _can_ be executed by the interpreter. Such methods include `Integer#+`,
+  `Array#each`, and `String#length`.
+- _const-internal_, which means they **must** be executed by the interpreter wherever they appear
+  in your codebase. These are your metaprogramming methods, like `define_method` and `attr_reader`.
+
+The strict requirements of const-internal mean that Houndstooth's interpreter is guaranteed to
+discover any invocations of metaprogramming, and therefore knows about the entire environment of
+your program. 
+
+Thanks to this tagging mechanism, it becomes a type error to write definitions which are not
+guaranteed to exist at runtime, or depend on non-deterministic data:
+
+```ruby
+class A
+    # This is a type error!
+    # Cannot call non-const method `rand` on `#<interpreter object: <Eigen:Kernel>>` from const context
+    if Kernel.rand > 0.5
+        #: () -> void
+        def x; end
+    end
+end
+```

data/bin/houndstooth.rb

@@ -0,0 +1,183 @@
+require 'optimist'
+require 'afl'
+require_relative '../lib/houndstooth'
+
+options = Optimist::options do
+    banner "Houndstooth: A Ruby type checker"
+
+    opt :file, "file to type check", type: :string, short: :f
+    opt :code, "code string to type check", type: :string, short: :e
+
+    opt :no_stdlib, "don't load stdlib types (for debugging - almost guaranteed to cause weird problems!)", short: :s
+    opt :fatal_interpreter, "exit on first interpreter error, and print internal backtrace", short: :x
+
+    opt :debug_nodes, "print parsed node tree", short: :none
+    opt :debug_environment, "print known types and methods", short: :none
+    opt :debug_instructions, "print generated instructions", short: :none
+    opt :debug_type_changes, "print instructions after type changes", short: :none
+    opt :verbose_instructions, "show more detail in instruction debug views", short: :none
+
+    opt :instrument, "AFL instrumentation", short: :none
+end
+
+def main(options)
+    $cli_options = options
+    # Checks if there are any errors. If so, prints them and aborts.
+    def abort_on_error!
+        if Houndstooth::Errors.errors.any?
+            Houndstooth::Errors.errors.each do |error|
+                puts error.format
+                puts
+            end
+
+            # The fuzzer will view an abort as a crash, so if we're running under instrumentation,
+            # exit gracefully here
+            l = Houndstooth::Errors.errors.length
+            if $cli_options[:instrument]
+                puts "Exiting with #{l} error#{l == 1 ? '' : 's'}."
+                puts "Running with instrumentation, so exit is just a jump."
+                puts "THIS WILL NOT RESULT IN AN ERROR EXIT CODE."
+                throw :afl_exit
+            else
+                abort "Exiting with #{l} error#{l == 1 ? '' : 's'}."
+            end
+        end
+    end 
+
+    # Create an environment with stdlib types
+    env = Houndstooth::Environment.new
+
+    # Load and parse code from file
+    if options[:file]
+        unless File.exist?(options[:file])
+            Houndstooth::Errors::Error.new("File '#{options[:file]}' does not exist", []).push
+            abort_on_error!
+        end
+
+        begin
+            code = File.read(options[:file])
+        rescue => e
+            Houndstooth::Errors::Error.new("Error reading file: #{e}", []).push
+            abort_on_error!
+        end
+    elsif options[:code]
+        code = options[:code]
+    else
+        puts "
+███████▖  ▀██ 
+████████▙▖  ▜ 
+██████▌▜██▄           HOUNDSTOOTH
+██████▌ ▝▜██▖     A Ruby type checker
+▝██▙▖         
+  ▀██▙           -f/--file: Check file
+▙  ▝▜█▌         -e/--code: Check string
+██▄  ▝▌       
+"
+        exit 1
+    end
+
+    if options[:no_stdlib]
+        htt_files = []
+    else
+        htt_files = [["stdlib.htt", File.read(File.join(__dir__, '..', 'types', 'stdlib.htt'))]]
+    end
+
+    # Parse and run builder over all files
+    all_nodes = [[options[:file] || 'inline code', code], *htt_files].map do |name, contents|
+        Houndstooth.process_file(name, contents, env) 
+    end
+    node = all_nodes[0]
+    abort_on_error!
+
+    if options[:debug_nodes]
+        puts "------ Nodes ------"
+        pp node
+        puts "-------------------"
+    end
+
+    # Resolve environment
+    env.resolve_all_pending_types
+    abort_on_error!
+
+    if options[:debug_environment]
+        puts "--- Environment ---"
+        env.types.each do |_, t|
+            puts t.path
+            if t.type_instance_variables.any?
+                puts "  Vars:"
+                t.type_instance_variables.each do |k, v|
+                    puts "    #{k}: #{v.rbs}"
+                end
+            end
+            t.instance_methods.each do |m|
+                puts "  #{m.name}"
+                # Don't try to print special `new`
+                if m.is_a?(Houndstooth::Environment::SpecialConstructorMethod)
+                    puts "    <special constructor>"
+                else
+                    m.signatures.each do |s|
+                        puts "    #{s.rbs}"
+                    end
+                end
+            end
+            puts
+        end
+        puts "-------------------"
+    end
+
+    # Create a new instruction block and populate it
+    # TODO: this is probably not how it'll be done in the final thing - we need to do this to individual
+    # methods, probably, or just ignore definitions? Don't know!
+    block = Houndstooth::Instructions::InstructionBlock.new(has_scope: true, parent: nil)
+    node.to_instructions(block)
+    env.types["__HoundstoothMain"] = Houndstooth::Environment::DefinedType.new(path: "__HoundstoothMain")
+    abort_on_error!
+
+    if options[:debug_instructions]
+        puts "-- Instructions ---"
+        puts block.to_assembly
+        puts "-------------------"
+    end
+
+    # Run the interpreter
+    runtime = Houndstooth::Interpreter::Runtime.new(env: env)
+    runtime.execute_from_top_level(block)
+    abort_on_error!
+
+    # That could have printed due to const-internal `puts` etc - if it did, print a divider
+    puts "--- end of const stdout ---" if $const_printed
+
+    # Type check the instruction block
+    checker = Houndstooth::TypeChecker.new(env)
+    checker.process_block(
+        block,
+        lexical_context: Houndstooth::Environment::BaseDefinedType.new,
+        self_type: env.types["__HoundstoothMain"],
+        const_context: false,
+        type_parameters: [],
+    )
+    
+    if options[:debug_type_changes]
+        puts "--- Inst. Types ---"
+        puts block.to_assembly
+        puts "-------------------"
+    end
+    abort_on_error!
+
+    # Yay!
+    puts "All good!"
+end
+
+if options[:instrument]
+    puts "== Instrumentation enabled =="
+    AFL.init
+    AFL.with_logging_to_file("/tmp/houndstooth-afl") do
+        catch :afl_exit do
+            AFL.with_exceptions_as_crashes do
+                main(options)
+            end
+        end
+    end
+else
+    main(options)
+end

data/fuzz/cases/x.rb

@@ -0,0 +1,8 @@
+class X
+    #: () -> String
+    def name
+        "Aaron"
+    end
+end
+
+X.new.name

data/fuzz/cases/y.rb

@@ -0,0 +1,8 @@
+class Y
+    #: () -> Integer
+    def y
+        3
+    end
+end
+
+Y.new.y

data/fuzz/cases/z.rb

@@ -0,0 +1,22 @@
+
+class Translator
+    #: (String, String) -> String
+    def translate(text, language)
+        "#{text} in #{language} is..."
+    end
+
+    #!arg String
+    [
+        "english", "french", "german", "japanese",
+        "spanish", "urdu", "korean", "hungarian",
+    ].each do |lang,|
+        #!arg String
+        #!arg String
+        define_method(:"to_#{lang}") do |s,|
+            translate(s, lang)
+        end
+    end
+end
+
+t = Translator.new
+x = t.to_german("Hello")

data/fuzz/ruby.dict

@@ -0,0 +1,64 @@
+# Derived from the Sorbet fuzzer dictionary, with modifications to use Houndstooth type syntax
+
+# keywords
+"begin"
+"end"
+"def"
+"class"
+"module"
+"do"
+"if"
+"else"
+"elsif"
+"until"
+"unless"
+"for"
+"while"
+"rescue"
+"case"
+"when"
+"yield"
+"next"
+"break"
+"return"
+"super"
+"ensure"
+"in"
+"redo"
+"retry"
+
+
+# common values
+"true"
+"false"
+"Integer"
+"String"
+"Array"
+"Numeric"
+"Object"
+"BasicObject"
+"nil"
+
+
+# types
+"self"
+"instance"
+"void"
+"untyped"
+
+
+# interesting stuff
+"new"
+"extend"
+"include"
+"is_a?"
+"self"
+"raise"
+"initialize"
+"&&"
+"||"
+
+
+# Metaprogramming
+"define_method"
+"attr_accessor"

data/fuzz/run

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -e
+
+SCRIPTPATH="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"
+if [ -d "$SCRIPTPATH/out/latest" ]
+then
+    echo "out/latest directory already exists!"
+    echo "Delete it to perform another fuzzer run."
+    exit 1
+fi
+
+# gitignored, so a fresh clone won't have this
+mkdir -p "$SCRIPTPATH/out"
+
+AFL_NO_FORKSRV=1 AFL_SKIP_BIN_CHECK=1 \
+    bundle exec afl-fuzz \
+    -i "$SCRIPTPATH/cases" \
+    -o "$SCRIPTPATH/out/latest" \
+    -m 5000 \
+    -x "$SCRIPTPATH/ruby.dict" \
+    -- ruby bin/houndstooth.rb --instrument -f @@