yardcheck 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88750f901e803de9b757d1699df2284e811e1b46
-  data.tar.gz: 47016f5393d602d75bbaf3a736735b9d93680eb9
+  metadata.gz: b594df9271ab2ef4f110b5fdaf97a44fc3e633a8
+  data.tar.gz: be08bcfad68850ed0adca3b1dba4e38562de2840
 SHA512:
-  metadata.gz: 688559a7d4caebc0218a1193ed67add77977e4c191e1f58767fa85e0120503a333d4146fe148d9f205c6940972f4d2451883e91fc21d244f3cc7575a3ac49b85
-  data.tar.gz: 3ae9fe9623004ec459faf4a1cfb475c7f60e7e4f2f47a177ae160360d92a5ef6c44a24fe3acd00c067fb09e0d9eb072be1dcae284dc7949fcb117731b760cdc6
+  metadata.gz: 5406813ffe5bda64d642a76cf9e6aab7c54fa0953e7bd693d5b98044048702cee8860c1af011fb48eb671a353d95b06e229b2996259180ac07e8ffb1cda68377
+  data.tar.gz: afc03fd46651422fbef24949eb940b175b4c6d62fb532c790b893482be060449d032c2202d02663c5f47f9dc2682069205da7cc5e403badaf66257ed78645bba

data/.buildkite/hooks/pre-command

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+docker pull backus/ruby-matrix

data/.buildkite/pipeline.yml

@@ -0,0 +1,10 @@
+steps:
+  - command: "build/run 2.3.3 'rspec'"
+    label: ":rspec: RSpec"
+    agents:
+      - queue=elastic
+
+  - name: ':rubocop: Rubocop'
+    command: build/run 2.3.3 rubocop
+    agents:
+      - queue=elastic

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "build"]
+	path = build
+	url = https://github.com/backus/buildkite-ruby-matrix.git

data/.rubocop.yml

@@ -13,7 +13,7 @@ AllCops:
 # This ends up being too spammy
 Style/Documentation:
   Enabled: false
-Style/ExtraSpacing:
+Layout/ExtraSpacing:
   AllowForAlignment: true
 Metrics/LineLength:
   Max: 100
@@ -50,38 +50,38 @@ Style/Send:
   Enabled: true
 Style/AutoResourceCleanup:
   Enabled: true
-Style/FirstArrayElementLineBreak:
+Layout/FirstArrayElementLineBreak:
   Enabled: true
-Style/FirstHashElementLineBreak:
+Layout/FirstHashElementLineBreak:
   Enabled: true
-Style/FirstMethodArgumentLineBreak:
+Layout/FirstMethodArgumentLineBreak:
   Enabled: true
-Style/FirstMethodParameterLineBreak:
+Layout/FirstMethodParameterLineBreak:
   Enabled: true
-Style/MultilineArrayBraceLayout:
+Layout/MultilineArrayBraceLayout:
   Enabled: true
-Style/MultilineAssignmentLayout:
+Layout/MultilineAssignmentLayout:
   EnforcedStyle: new_line
   Enabled: true
-Style/MultilineHashBraceLayout:
+Layout/MultilineHashBraceLayout:
   Enabled: true
-Style/MultilineMethodCallBraceLayout:
+Layout/MultilineMethodCallBraceLayout:
   Enabled: true
-Style/MultilineMethodDefinitionBraceLayout:
+Layout/MultilineMethodDefinitionBraceLayout:
   Enabled: true
 Style/OptionHash:
   Enabled: true
 Style/StringMethods:
   Enabled: true
-Style/IndentArray:
+Layout/IndentArray:
   EnforcedStyle: consistent
-Style/IndentHash:
+Layout/IndentHash:
   EnforcedStyle: consistent
 MultilineMethodCallIndentation:
   EnforcedStyle: indented
 Style/Alias:
   EnforcedStyle: prefer_alias_method
-Style/AlignHash:
+Layout/AlignHash:
   EnforcedColonStyle: table
 Style/SignalException:
   EnforcedStyle: semantic
@@ -212,3 +212,5 @@ Lint/DefEndAlignment:
 # See explanation for `Lint/DefEndAlignment`
 Lint/EndAlignment:
   AutoCorrect: true
+Style/MixinGrouping:
+  EnforcedStyle: grouped

data/Gemfile

@@ -11,9 +11,10 @@ group :test do
 end
 
 group :lint do
-  gem 'rubocop',          git: 'https://github.com/bbatsov/rubocop.git'
+  gem 'rake' # sickill/rainbow#44
+  gem 'rubocop', '~> 0.49.1'
   gem 'rubocop-devtools', git: 'https://github.com/backus/rubocop-devtools.git'
-  gem 'rubocop-rspec',    git: 'https://github.com/backus/rubocop-rspec.git'
+  gem 'rubocop-rspec'
 end
 
 gem 'guard'

data/README.md

@@ -14,9 +14,9 @@ When you write documentation like this
 # @param user [User]
 #
 # @return [true,false]
-# def valid?(user)
-# ...
-# end
+def valid?(user)
+  # ...
+end
 ```
 
 You are saying that you are always going to be passing in a `User` instance and the method will always returns `true` or `false`.
@@ -74,10 +74,25 @@ Yardcheck is doing some cool things here:
 
 In this case I would update the documentation to be `@param [#call, nil] block`
 
-# Is this ready?
+## Is this ready?
 
 Kind of.
 
 It is not ready to be run in CI to check your documentation and it may never be since tracing method calls is fairly slow. We also sometimes mess up. For example, if another method raises an error then all of the methods that bubble up that error without rescuing it will be marked as returning `nil`. This seems like a limitation of ruby's `TracePoint` right now.
 
 It is very helpful though. It will find a lot of cases where your documentation isn't quite right and the output is clear. Install it and give it a try.
+
+## Install
+
+You probably could have guessed this, but to install just run
+
+```
+$ gem install yardcheck
+```
+
+Or add this to your Gemfile
+
+```
+gem 'yardcheck'
+```
+

data/lib/yardcheck/const.rb

@@ -4,14 +4,33 @@ module Yardcheck
   class Const
     include Concord::Public.new(:constant)
 
+    SPECIAL_CASES = [
+      Hash,
+      Array
+    ].map { |const| [const.name, const] }.to_h
+
     def self.resolve(constant_name, scope = Object)
-      return new(scope.const_get(constant_name)) if scope.const_defined?(constant_name)
+      if (const = direct_resolve(constant_name, scope))
+        const
+      else
+        resolve_parent(constant_name, scope)
+      end
+    end
 
+    def self.resolve_parent(constant_name, scope)
       parent = parent_namespace(scope)
       from_parent = resolve(constant_name, parent.constant) if parent.valid?
       from_parent && from_parent.valid? ? from_parent : Invalid.new(scope, constant_name)
     end
 
+    def self.direct_resolve(constant_name, scope)
+      if scope.equal?(Object) && constant_name.empty?
+        new(Object)
+      elsif scope.const_defined?(constant_name)
+        new(const_lookup(scope, constant_name))
+      end
+    end
+
     def self.parent_namespace(scope)
       parent_name = scope.name.split('::').slice(0...-1).join('::')
 
@@ -22,6 +41,13 @@ module Yardcheck
       end
     end
 
+    def self.const_lookup(scope, name)
+      SPECIAL_CASES.fetch(name) do
+        scope.const_get(name) if scope.const_defined?(name)
+      end
+    end
+    private_class_method :const_lookup
+
     def valid?
       true
     end

data/lib/yardcheck/documentation/method_object.rb

@@ -23,6 +23,10 @@ module Yardcheck
         return_typedef unless return_typedef&.invalid_const?
       end
 
+      def raise_type
+        raise_typedef unless raise_typedef&.invalid_const?
+      end
+
       def singleton?
         scope.equal?(:class)
       end
@@ -58,15 +62,29 @@ module Yardcheck
         [*param_warnings, *return_warning].map { |warning| Warning.new(self, warning) }
       end
 
+      def predicate_method?
+        selector.to_s.end_with?('?')
+      end
+
+      def processed_source
+        ProcessedSource.new(yardoc.source)
+      end
+      memoize :processed_source
+
       private
 
       def return_typedef
-        return_tag.map(&method(:typedefs)).reduce(:+)
+        aggregate_tags(:return)
       end
       memoize :return_typedef
 
-      def return_tag
-        tags(:return)
+      def raise_typedef
+        aggregate_tags(:raise)
+      end
+      memoize :raise_typedef
+
+      def aggregate_tags(name)
+        tags(name).map(&method(:typedefs)).reduce(:+)
       end
 
       def param_typedefs

data/lib/yardcheck/method_call.rb

@@ -2,25 +2,21 @@
 
 module Yardcheck
   class MethodCall
-    include Anima.new(
+    include AbstractType, Anima.new(
       :scope,
       :selector,
       :namespace,
       :params,
-      :example_location,
-      :return_value,
-      :error_raised
+      :example_location
     )
 
-    def self.process(params:, return_value:, **attributes)
+    def self.process(params:, **attributes)
       params =
         params.map do |key, value|
           [key, TestValue.process(value)]
         end.to_h
 
-      return_value = TestValue.process(return_value)
-
-      new(params: params, return_value: return_value, **attributes)
+      new(params: params, **attributes)
     end
 
     def method_identifier
@@ -31,8 +27,39 @@ module Yardcheck
       selector == :initialize && scope == :instance
     end
 
-    def raised?
-      error_raised
+    def raise?
+      false
+    end
+
+    def return?
+      false
     end
+
+    class Return < self
+      include anima.add(:return_value)
+
+      def self.process(return_value:, **kwargs)
+        super(return_value: TestValue.process(return_value), **kwargs)
+      end
+
+      def return?
+        true
+      end
+    end # Return
+
+    class Raise < self
+      include anima.add(:exception)
+
+      def self.process(exception:, **kwargs)
+        super(exception: TestValue.process(exception), **kwargs)
+      end
+
+      def raise?
+        true
+      end
+    end # Raise
+
+    class Jump < self
+    end # Jump
   end # MethodCall
 end # Yardcheck

data/lib/yardcheck/method_tracer.rb

@@ -6,6 +6,17 @@ module Yardcheck
 
     def initialize(namespace)
       super(namespace, [], [])
+
+      # When an exception is raised it isn't clear when it has been eventually rescued.
+      # We set `@current_exception` to `true` when we have observed an exception
+      # and have not seen a non `nil` return.
+      @current_exception = nil
+
+      # A block passed from one method down to another method can trigger a return of the
+      # originating method. This triggers a waterfall of `nil` returns because each method
+      # shortcircuits. Similar to `current_exception` we need to also track jumps triggered
+      # by block returns
+      @block_jump = false
     end
 
     def trace(&block)
@@ -18,8 +29,10 @@ module Yardcheck
 
     private
 
+    attr_reader :current_exception, :block_jump
+
     def tracer
-      TracePoint.new(:call, :return, :raise) do |event|
+      TracePoint.new(:call, :return, :raise, :b_return) do |event|
         tracer.disable do
           process(event) if target?(event.defined_class)
         end
@@ -29,13 +42,18 @@ module Yardcheck
 
     def process(trace_event)
       case trace_event.event
-      when :call   then process_call(trace_event)
-      when :return then process_return(trace_event)
-      when :raise  then process_raise
+      when :call     then process_call(trace_event)
+      when :return   then process_return(trace_event)
+      when :raise    then process_raise(trace_event)
+      when :b_return then process_block_return
       end
     end
 
     def process_call(trace_event)
+      # If we observe a method call then we are certainly no longer inside of a
+      # bubbling up of early returns
+      @block_jump = false
+
       parameter_names =
         trace_event
           .defined_class
@@ -54,13 +72,35 @@ module Yardcheck
     end
 
     def process_return(trace_event)
-      seen << MethodCall.process(
-        call_stack.pop.merge(return_value: trace_event.return_value)
-      )
+      return_value = trace_event.return_value
+
+      # If we observe a non `nil` return value then it is no longer possible that we are observing
+      # "fake returns" caused by either an exception being raised or a block being executed
+      # that invoked `return` and caused other methods to return early
+      unless nil.equal?(return_value)
+        @current_exception = nil
+        @block_jump        = false
+      end
+
+      frame = call_stack.pop
+      method_call =
+        if @current_exception
+          MethodCall::Raise.process(frame.merge(exception: @current_exception))
+        elsif @block_jump
+          MethodCall::Jump.process(frame)
+        else
+          MethodCall::Return.process(frame.merge(return_value: return_value))
+        end
+
+      seen << method_call
+    end
+
+    def process_raise(trace_event)
+      @current_exception = trace_event.raised_exception
     end
 
-    def process_raise
-      call_stack.last[:error_raised] = true
+    def process_block_return
+      @block_jump = true
     end
 
     def event_details(event)
@@ -68,8 +108,7 @@ module Yardcheck
         scope:            event.defined_class.__send__(:singleton_class?) ? :class : :instance,
         selector:         event.method_id,
         namespace:        event.defined_class,
-        example_location: RSpec.current_example.location,
-        error_raised:     false
+        example_location: RSpec.current_example.location
       }
     end
 

data/lib/yardcheck/observation.rb

@@ -5,7 +5,7 @@ module Yardcheck
     include Concord.new(:documentation, :event)
 
     def violations
-      param_violations + return_violations
+      param_violations + return_violations + raise_violations
     end
 
     def source_code
@@ -36,10 +36,18 @@ module Yardcheck
       documentation.return_type
     end
 
+    def documented_raise_type
+      documentation.raise_type
+    end
+
     def actual_return_type
       event.return_value.type
     end
 
+    def actual_raise_type
+      event.exception.type
+    end
+
     def documentation_warnings
       documentation.warnings
     end
@@ -59,14 +67,32 @@ module Yardcheck
     end
 
     def return_violations
-      invalid_return_type? ? [Violation::Return.new(self)] : []
+      invalid_return? ? [Violation::Return.new(self)] : []
+    end
+
+    def raise_violations
+      invalid_raise? ? [Violation::Raise.new(self)] : []
     end
 
-    def invalid_return_type?
-      documentation.return_type &&
+    def invalid_raise?
+      documentation.raise_type &&
+        event.raise?           &&
+        !documentation.raise_type.match?(event.exception)
+    end
+
+    def invalid_return?
+      documentation.return_type                               &&
+        event.return?                                         &&
         !documentation.return_type.match?(event.return_value) &&
-        !event.raised? &&
-        !event.initialize?
+        !event.initialize?                                    &&
+        !documentation.predicate_method?                      &&
+        !possible_tracepoint_bug?
+    end
+
+    def possible_tracepoint_bug?
+      return false unless event.return_value.is?(nil)
+
+      documentation.processed_source.tracepoint_bug_candidate?
     end
   end # Observation
 end # Yardcheck

data/lib/yardcheck/processed_source.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Yardcheck
+  class ProcessedSource
+    include Concord.new(:raw_source), Adamantium::Flat
+
+    # @see https://bugs.ruby-lang.org/issues/13369
+    def tracepoint_bug_candidate?
+      resbodies = find_resbodies
+      resbodies.any? do |node|
+        find_type(node, :return).any?
+      end
+    end
+
+    private
+
+    def find_resbodies(node = ast)
+      find_type(node, :resbody)
+    end
+
+    def find_type(node, type)
+      return nil unless node.is_a?(Parser::AST::Node)
+      return [node] if node.type == type
+
+      node.children.map { |child| find_type(child, type) }.flatten.compact
+    end
+
+    def ast
+      Parser::CurrentRuby.parse(raw_source)
+    end
+  end # ProcessedSource
+end # Yardcheck

data/lib/yardcheck/runner.rb

@@ -53,6 +53,12 @@ module Yardcheck
     def check
       warn_all(warnings)
       warn_all(offenses)
+
+      if offenses.any?
+        Kernel.exit(1)
+      else
+        Kernel.exit(0)
+      end
     end
 
     private

data/lib/yardcheck/typedef/parser.rb

@@ -76,7 +76,7 @@ module Yardcheck
         def signature
           type
         end
-      end
+      end # Invalid
     end # Parser
   end # Typedef
 end # Yardcheck

data/lib/yardcheck/typedef.rb

@@ -5,7 +5,9 @@ module Yardcheck
     include Concord.new(:types)
 
     def self.parse(types)
-      if types.include?(:undefined)
+      if types.empty?
+        Unspecified.new
+      elsif types.include?(:undefined)
         fail 'Cannot combined [undefined] with other types' unless types.one?
         Undefined.new
       elsif types.grep(Parser::Invalid).any?
@@ -33,6 +35,18 @@ module Yardcheck
       types.any?(&:invalid_const?)
     end
 
+    class Unspecified < self
+      include Concord.new
+
+      def signature
+        '(Unspecified type)'
+      end
+
+      def invalid_const?
+        true
+      end
+    end # Unspecified
+
     class Literal < self
       include Concord.new(:const)
 
@@ -117,6 +131,6 @@ module Yardcheck
       def invalid_const?
         true
       end
-    end
+    end # Invalid
   end # Typedef
 end # Yardcheck

data/lib/yardcheck/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yardcheck
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end # Yardcheck

data/lib/yardcheck/violation.rb

@@ -152,5 +152,43 @@ module Yardcheck
         observation.documented_param(name)
       end
     end # Param
+
+    class Raise < self
+      include Equalizer.new(:observation)
+
+      FORMAT =
+        "Expected #{blue('%<shorthand>s')} to raise " \
+        "#{yellow('%<signature>s')} but observed " \
+        "#{red('%<observed_type>s')}"
+
+      def initialize(observation, test_locations = [observation.test_location])
+        super
+      end
+
+      def explanation
+        format(
+          FORMAT,
+          shorthand:     shorthand,
+          signature:     signature,
+          observed_type: observed_type
+        )
+      end
+
+      protected
+
+      def observed_type
+        observation.actual_raise_type
+      end
+
+      private
+
+      def combine_requirements
+        %i[shorthand signature observed_type]
+      end
+
+      def expected_type
+        observation.documented_raise_type
+      end
+    end # Raise
   end # Violation
 end # Yardcheck

data/lib/yardcheck.rb

@@ -5,6 +5,7 @@ require 'concord'
 require 'yard'
 require 'rspec'
 require 'coderay'
+require 'parser/current'
 
 require 'yardcheck/version'
 require 'yardcheck/runner'
@@ -24,3 +25,4 @@ require 'yardcheck/color'
 require 'yardcheck/violation'
 require 'yardcheck/warning'
 require 'yardcheck/source_lines'
+require 'yardcheck/processed_source'

data/spec/integration/yardcheck_spec.rb

@@ -33,9 +33,11 @@ RSpec.describe 'test app integration' do
   end
 
   it 'generates a warning for invalid constant' do
-    expect_report('WARNING: Unabled to resolve "What" for lib/test_app.rb:37')
-    expect_report('WARNING: Unabled to resolve "Wow" for lib/test_app.rb:37')
-    expect_report('WARNING: Unabled to resolve :foo for lib/test_app.rb:109')
+    expect_report('WARNING: Unabled to resolve "What" for lib/test_app.rb:43')
+    expect_report('WARNING: Unabled to resolve "Wow" for lib/test_app.rb:43')
+    expect_report('WARNING: Unabled to resolve (Unspecified type) for lib/test_app.rb:58')
+    expect_report('WARNING: Unabled to resolve (Unspecified type) for lib/test_app.rb:58')
+    expect_report('WARNING: Unabled to resolve :foo for lib/test_app.rb:122')
   end
 
   it 'reports expectations' do
@@ -50,6 +52,10 @@ RSpec.describe 'test app integration' do
         'Expected TestApp::Namespace#improperly_tested_with_instance_double ' \
         'to receive String for value but observed Integer'
       )
+      expect_report(
+        'Expected TestApp::Namespace#invalid_raise_documentation to raise ' \
+        'TestApp::Namespace::AppError but observed KeyError'
+      )
       matches = report.scan(/^Expected .+ to return .+ but observed .+$/)
       expect(matches.size).to be(3)
     end

data/spec/spec_helper.rb

@@ -4,7 +4,11 @@ require 'pathname'
 require 'bundler'
 require 'timeout'
 
-Bundler.with_clean_env { system('cd test_app && yard --no-cache --no-output > /dev/null') }
+Bundler.with_clean_env do
+  Dir.chdir('test_app') do
+    YARD::CLI::Yardoc.run(*%w[--no-cache --no-output --no-stats --quiet --no-progress .])
+  end
+end
 
 begin
   require 'mutest'