typeguard 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9e491b4197296ce89855941107dd841b9210d0a225b38d2981ebb69fc10f315d
+  data.tar.gz: 63abb9ec3829ca2e248ad24ac064f0be3db448353c7f89fade79a971d1064d15
+SHA512:
+  metadata.gz: bfa33482c19eac191c3a8135df68b23d2258fbd9ca82c568234991a3168fa41213f2d13a50241beb7dab0a6d1866e41d2a78ba629027f80886c5114e05c9c98b
+  data.tar.gz: 11f22232e0a28552f52af7bd84a5c27c687496312375f741ac5b3c1b9dfc20bcfe26159519374e445f58503520752d196813813529052b991a81324df9a65e05

data/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+indent_style = space
+indent_size = 2

data/.rubocop.yml

@@ -0,0 +1,25 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.1
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false

data/.rubocop_todo.yml

@@ -0,0 +1,89 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config --exclude-limit 30`
+# on 2025-03-27 09:25:41 UTC using RuboCop version 1.71.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Lint/BooleanSymbol:
+  Exclude:
+    - 'test/typeguard/type_model/test_parser.rb'
+
+# Offense count: 8
+# Configuration parameters: AllowedParentClasses.
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/typeguard/types.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect, AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/typeguard/types.rb'
+
+# Offense count: 8
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 9
+
+# Offense count: 5
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/typeguard/type_model/parser.rb'
+    - 'lib/typeguard/example.rb'
+
+# Offense count: 7
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: nested, compact
+Style/ClassAndModuleChildren:
+  Exclude:
+    - 'lib/typeguard/validator.rb'
+    - 'lib/typeguard/main.rb'
+
+# Offense count: 34
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/typeguard/type_model/builder.rb'
+    - 'lib/typeguard/type_model/definitions.rb'
+    - 'lib/typeguard/type_model/parser.rb'
+    - 'lib/typeguard/validator.rb'
+    - 'lib/typeguard/configuration.rb'
+    - 'lib/typeguard/example.rb'
+    - 'lib/typeguard/main.rb'
+    - 'lib/typeguard/metrics.rb'
+    - 'lib/typeguard/resolver.rb'
+    - 'lib/typeguard/types.rb'
+    - 'lib/typeguard/validator.rb'
+    - 'lib/typeguard/wrapper.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AutoCorrect, EnforcedStyle.
+# SupportedStyles: compact, expanded
+Style/EmptyMethod:
+  Exclude:
+    - 'test/typeguard/test_validator.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+Style/IfUnlessModifier:
+  Exclude:
+    - 'lib/typeguard/validator.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 228

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in typeguard.gemspec
+gemspec
+
+group :developement, :test do
+  gem 'rake', '~> 13.0'
+
+  gem 'minitest', '~> 5.0'
+
+  gem 'rubocop'
+
+  gem 'bundler-audit'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tesorion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,42 @@
+# Typeguard
+
+Runtime type checking for Ruby type signatures. Currently supports YARD and a subset of RBS.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add typeguard
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install typeguard
+
+## Usage
+Call `configure` and `process!` at the end of the original code to add type checking to it.
+
+```ruby
+require 'typeguard'
+
+Typeguard.configure do |config|
+  config.enabled = true                                  # does nothing if false
+  config.source = :yard                                  # :yard or :rbs
+  config.target = ['bin/example.rb']                     # signatures file/dir
+  config.reparse = true                                  # reparse YARD sigs
+  config.at_exit_report = true                           # print findings
+  config.resolution.raise_on_name_error = false          # undefined constants
+  config.wrapping.raise_on_unexpected_arity = false      # amount of parameters
+  config.wrapping.raise_on_unexpected_visibility = false # scope (public/private/..)
+  config.validation.raise_on_unexpected_argument = false # type check args
+  config.validation.raise_on_unexpected_return = false   # type check return
+end.process!
+```
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tesorion/typeguard.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/test_*.rb']
+end
+
+task default: :test

data/lib/typeguard/configuration.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'dry-configurable'
+
+module Typeguard
+  extend Dry::Configurable
+
+  SUPPORTED_SOURCES = %i[yard rbs].freeze
+
+  def self.setting_bool(target = self, name, default: false)
+    target.setting name, default: default, reader: true, constructor: proc { |value|
+      raise "Config '#{name}' must be true or false" unless value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+      value
+    }
+  end
+
+  setting_bool :enabled
+  setting_bool :reparse
+  setting_bool :at_exit_report
+
+  setting :target, reader: true
+  setting :source, default: :yard, reader: true, constructor: proc { |value|
+    raise "Config source must be one of #{SUPPORTED_SOURCES}" unless SUPPORTED_SOURCES.include?(value)
+
+    value
+  }
+
+  setting :resolution, reader: true do
+    Typeguard.setting_bool self, :raise_on_name_error
+  end
+
+  setting :wrapping, reader: true do
+    Typeguard.setting_bool self, :raise_on_unexpected_arity
+    Typeguard.setting_bool self, :raise_on_unexpected_visibility
+  end
+
+  setting :validation, reader: true do
+    Typeguard.setting_bool self, :raise_on_unexpected_argument
+    Typeguard.setting_bool self, :raise_on_unexpected_return
+  end
+
+  def self.process!
+    unless config.enabled
+      puts 'WARNING: typeguard disabled'
+      return
+    end
+
+    Typeguard::Metrics.config(config.validation)
+    Typeguard::TypeModel::Builder.send(config.source)
+    builder = TypeModel::Builder::IMPLEMENTATION.new(config.target, config.reparse)
+    definitions = builder.build
+    Typeguard::Resolution::Resolver.new(definitions, config.resolution).resolve!
+    Typeguard::Validation::Wrapper.new(definitions, config.wrapping).wrap!
+    at_exit { Typeguard::Metrics.flush } if config.at_exit_report
+  end
+end

data/lib/typeguard/metrics.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Typeguard
+  module Metrics
+    Log = Struct.new(:module, :definition, :type, :error, :expected, :actual, :source, :caller, keyword_init: true)
+
+    @raise_on_unexpected_argument = false
+    @raise_on_unexpected_return = false
+    @logs = []
+
+    def self.config(validation)
+      @raise_on_unexpected_argument = validation.raise_on_unexpected_argument
+      @raise_on_unexpected_return = validation.raise_on_unexpected_return
+    end
+
+    def self.format_log(log)
+      <<~MESSAGE
+        - #{log.error.upcase} - Expected #{log.expected} for #{log.type} but received incompatible \
+        #{log.actual} in '#{log.module}##{log.definition}' defined in #{log.source} \
+        and called from #{log.caller}
+      MESSAGE
+    end
+
+    def self.flush
+      new_line = "\n" unless @logs.empty?
+      puts "\ntypeguard errors [start]: #{@logs.length} #{new_line}\n"
+      @logs.each { |log| puts format_log(log) }
+      puts "\ntypeguard errors [end]: #{@logs.length} #{new_line}"
+      @logs.clear
+    end
+
+    def self.report(mod, definition, error, expected, actual)
+      caller = caller_locations(1, 1).first
+      caller_string = caller.label.split('::').last
+      module_name = mod.name.to_sym
+      type = definition.class.name.split('::').last.gsub('Definition', '').to_sym
+      source = definition.source
+      log = Log.new(module: module_name, definition: definition.name, type: type, error: error,
+                    expected: expected, actual: actual, source: source,
+                    caller: caller_string)
+      @logs << log
+      log
+    end
+
+    def self.report_unexpected_return(sig, return_object, result, mod_name)
+      caller = caller_locations(2, 1).first
+      caller_string = "#{caller.path}:#{caller.lineno}"
+      source = sig.returns.source
+      log = Log.new(module: mod_name, definition: sig.name, type: :Return,
+                    error: :unexpected_return, source: source, caller: caller_string,
+                    expected: return_object, actual: result.class.to_s)
+      @logs << log
+      raise TypeError, format_log(log) if @raise_on_unexpected_return
+
+      log
+    end
+
+    def self.report_unexpected_argument(sig, expected, actual, mod_name, parameter)
+      caller = caller_locations(4, 1).first
+      caller_string = "#{caller.path}:#{caller.lineno}"
+      method_name = sig.name
+      parameter_name = parameter.name
+      source = parameter.source
+      log = Log.new(module: mod_name, definition: method_name, type: parameter_name,
+                    error: :unexpected_argument, source: source, caller: caller_string,
+                    expected: expected, actual: actual.class.to_s)
+      @logs << log
+      raise TypeError, format_log(log) if @raise_on_unexpected_argument
+
+      log
+    end
+  end
+end

data/lib/typeguard/resolver.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Typeguard
+  module Resolution
+    class Resolver
+      include Typeguard::TypeModel::Definitions
+
+      def initialize(definitions, config)
+        @definitions = definitions
+        @config = config
+      end
+
+      def resolve!
+        if @config.raise_on_name_error
+          @definitions.each do |definition|
+            resolve_definition(definition)
+          rescue NameError => e
+            raise(e.class,
+                  Metrics.format_log(Metrics.report(Object, definition, :unresolved, 'resolution', e.message)),
+                  [])
+          end
+        else
+          # Create compact array of resolved definitions
+          resolve_prune_definitions!
+        end
+      end
+
+      def resolve_definition(definition)
+        case definition
+        when ModuleDefinition, ClassDefinition
+          Object.const_get(definition.name.to_s, true)
+          definition.children.each { |child| resolve_definition(child) }
+        when MethodDefinition
+          definition.parameters.each { |param| param.types.each { |node| resolve_type(node) } }
+          return if definition.name == :initialize # Ignore YARD default tag
+
+          definition.returns.types.each { |node| resolve_type(node) }
+        else raise "Unexpected definition for '#{definition}'"
+        end
+      end
+
+      def resolve_prune_definitions!(definitions = @definitions, parent = Object)
+        definitions.grep_v(MethodDefinition) do |definition|
+          definition.children = resolve_prune_definitions!(definition.children, definition)
+        end
+        definitions.reject do |definition|
+          case definition
+          when ModuleDefinition, ClassDefinition
+            Object.const_get(definition.name.to_s, true)
+          when MethodDefinition
+            definition.parameters.each { |param| param.types.each { |node| resolve_type(node) } }
+            next if definition.name == :initialize # Ignore YARD default tag
+
+            definition.returns.types.each { |node| resolve_type(node) }
+          end
+          false
+        rescue NameError => e
+          Metrics.report(parent, definition, :unresolved, 'resolution', e)
+          true
+        end
+      end
+
+      # Raises a NameError if module names are not found
+      def resolve_type(node)
+        case node.shape
+        when :basic
+          node.metadata[:const] ||= Object.const_get(node.kind.to_s, true)
+        when :generic, :fixed
+          node.metadata[:const] ||= Object.const_get(node.kind.to_s, true)
+          node.children.each { |child_node| resolve_type(child_node) }
+        when :hash, :fixed_hash
+          node.metadata[:const] ||= Object.const_get(node.kind.to_s, true)
+          node.children.flatten.each { |child_node| resolve_type(child_node) }
+        when :union
+          node.children.each { |child_node| resolve_type(child_node) }
+        when :literal
+          # The mapper has already rejected invalid literals,
+        when :duck
+          # Resolving duck-types at this point is unreliable
+          # and slow, leaving it up to runtime checks
+        when :untyped
+          # Always correct
+        else raise "Unknown node shape: #{node.shape}"
+        end
+      end
+    end
+  end
+end

data/lib/typeguard/type_model/builder/rbs_builder.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'rbs'
+
+module Typeguard
+  module TypeModel
+    module Builder
+      # Takes RBS signatures and returns a generic type model
+      class RBSBuilder
+        include Typeguard::TypeModel::Definitions
+
+        attr_reader :rbs_env
+
+        # @return [Typeguard::Initializer::RBSInitalizer] initializer for RBS signatures
+        def initialize(target, _reparse)
+          rbs_loader = RBS::EnvironmentLoader.new(core_root: nil)
+          rbs_loader.add(path: Pathname(target))
+          @rbs_env = RBS::Environment.from_loader(rbs_loader).resolve_type_names
+          return unless @rbs_env.declarations.empty?
+
+          puts "WARNING: could not find RBS signatures for target directory '#{target}'. " \
+          'Confirm that the directory exists and/or that it contains .rbs files.'
+        end
+
+        #  ruby -e "require 'rbs';loader=RBS::EnvironmentLoader.new(core_root: nil);loader.add(path:Pathname('sig'));environment=RBS::Environment.from_loader(loader);environment.declarations.each{|cls,entries|pp cls;pp entries}"
+        def build
+          @rbs_env.declarations.map { |decl| build_object(decl) }.compact
+        end
+
+        def build_object(object)
+          case object
+          when RBS::AST::Declarations::Class
+            children = object.members.map { |child| build_object(child) }.compact
+            ClassDefinition.new(
+              name: object.name.relative!.to_s,
+              source: build_source(object),
+              parent: object.super_class&.to_s,
+              type_parameters: object.type_params.map(&:name),
+              children: children
+            )
+          when RBS::AST::Declarations::Module
+            children = object.members.map { |child| build_object(child) }.compact
+            ModuleDefinition.new(
+              name: object.name.relative!.to_s,
+              source: build_source(object),
+              type_parameters: object.type_params.map(&:name),
+              children: children
+            )
+          when RBS::AST::Members::MethodDefinition
+            # NOTE: Currently only looking at first overload and
+            # only at required positionals.
+            sig = object.overloads.first.method_type.type
+            parameters = sig.required_positionals.map do |param|
+              ParameterDefinition.new(
+                name: param.name,
+                source: build_source(param),
+                types: build_types(param.type),
+                types_string: param.type.to_s
+              )
+            end
+            return_sig = sig.return_type
+            returns = ReturnDefinition.new(
+              source: build_source(return_sig),
+              types: build_types(return_sig),
+              types_string: return_sig.to_s
+            )
+            MethodDefinition.new(
+              name: object.name,
+              source: build_source(object),
+              scope: object.kind,
+              visibility: object.visibility,
+              parameters: parameters,
+              returns: returns
+            )
+          else raise "Unsupported RBS declaration #{object.class}"
+          end
+        end
+
+        def build_types(rbs_type)
+          if rbs_type
+            [Typeguard::TypeModel::Mapper::RBSMapper.parse_map(rbs_type)]
+          else
+            [TypeNode.new(
+              kind: :untyped,
+              shape: :untyped,
+              children: [],
+              metadata: { note: 'RBS type not provided' }
+            )]
+          end
+        end
+
+        def build_source(object)
+          location = object.location
+          "#{location.buffer.name}:#{location.start_line}"
+        end
+      end
+    end
+  end
+end