yardcheck 0.0.1

data/lib/yardcheck/version.rb

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

data/lib/yardcheck/violation.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Yardcheck
+  class Violation
+    extend Color
+    include Color
+
+    def initialize(observation, test_locations = [observation.test_location])
+      @observation    = observation
+      @test_locations = test_locations.sort.uniq
+    end
+
+    def offense
+      indented_source = indent(observation.source_code)
+      source = "\n#{CodeRay.encode(indented_source, :ruby, :terminal)}\n"
+
+      location_hint = indent(grey("source: #{observation.source_location}"))
+      test_lines    = test_locations.map { |l| "  - #{l}" }.join("\n")
+      tests_block   = "tests:\n#{test_lines}"
+      test_hint     = indent(grey(tests_block))
+
+      "#{explanation}\n\n#{location_hint}\n#{test_hint}\n#{source}\n"
+    end
+
+    def combine(other)
+      fail 'Cannot combine' unless combine_with?(other)
+
+      with_tests(other.test_locations)
+    end
+
+    def combination_identifier
+      combine_requirements.map(&method(:__send__))
+    end
+
+    attr_reader :test_locations
+
+    private
+
+    attr_reader :observation
+
+    def combine_with?(other)
+      combination_identifier == other.combination_identifier
+    end
+
+    def with_tests(other_test_locations)
+      self.class.new(observation, test_locations + other_test_locations)
+    end
+
+    def indent(string)
+      string.gsub(/^/, '    ')
+    end
+
+    def shorthand
+      observation.method_shorthand
+    end
+
+    def signature
+      expected_type.signature
+    end
+
+    def observed_type
+      observed_value.type
+    end
+
+    class Return < self
+      include Equalizer.new(:observation)
+
+      FORMAT =
+        "Expected #{blue('%<shorthand>s')} to return " \
+        "#{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_return_type
+      end
+
+      private
+
+      def combine_requirements
+        %i[shorthand signature observed_type]
+      end
+
+      def expected_type
+        observation.documented_return_type
+      end
+    end # Return
+
+    class Param < self
+      include Equalizer.new(:name, :observation)
+
+      def initialize(name, observation, test_locations = [observation.test_location])
+        @name = name
+
+        super(observation, test_locations)
+      end
+
+      FORMAT =
+        "Expected #{blue('%<shorthand>s')} to " \
+        "receive #{yellow('%<signature>s')} for #{blue('%<name>s')} " \
+        "but observed #{red('%<test_value>s')}"
+
+      def explanation
+        format(
+          FORMAT,
+          shorthand:  shorthand,
+          signature:  signature,
+          name:       name,
+          test_value: observed_type
+        )
+      end
+
+      private
+
+      attr_reader :name
+
+      def observed_type
+        test_value.type
+      end
+
+      def combine_requirements
+        %i[name shorthand signature observed_type]
+      end
+
+      def with_tests(other_test_locations)
+        self.class.new(
+          name,
+          observation,
+          test_locations + other_test_locations
+        )
+      end
+
+      def test_value
+        observation.observed_param(name)
+      end
+
+      def expected_type
+        observation.documented_param(name)
+      end
+    end # Param
+  end # Violation
+end # Yardcheck

data/lib/yardcheck/warning.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Yardcheck
+  class Warning
+    extend Color
+    include Concord.new(:method_object, :typedef)
+
+    MSG = "#{red('WARNING:')} Unabled to resolve #{yellow('%<typedef>s')} for %<location>s"
+
+    def message
+      format(MSG, typedef: typedef.signature, location: method_object.location_pointer)
+    end
+  end # Warning
+end # Yardcheck

data/spec/integration/yardcheck_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+RSpec.describe 'test app integration' do
+  let(:report) { remove_color(run_yardcheck) }
+
+  def run_yardcheck
+    Bundler.with_clean_env do
+      Dir.chdir('test_app') do
+        system("bundle install --gemfile=#{File.join(Dir.pwd, 'Gemfile')}")
+        system('bundle exec yardcheck --namespace TestApp --include lib --require test_app')
+      end
+    end
+  end
+
+  def system(command)
+    output = nil
+
+    Open3.popen3(command) do |_stdin, _stdout, stderr|
+      output = stderr.read
+    end
+
+    output
+  end
+
+  def expect_report(report_substring)
+    expect(report).to match(a_string_including(report_substring))
+  end
+
+  def remove_color(string)
+    string.gsub(/\e\[(?:1\;)?\d+m/, '')
+  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')
+  end
+
+  it 'reports expectations' do
+    aggregate_failures do
+      expect_report('Expected TestApp::Namespace#add to return String but observed Fixnum')
+      expect_report('Expected #<Class:TestApp::Namespace>#add to return String but observed Fixnum')
+      expect_report(
+        'Expected TestApp::Namespace#documents_relative ' \
+        'to return TestApp::Namespace::Child but observed String'
+      )
+      expect_report(
+        'Expected TestApp::Namespace#improperly_tested_with_instance_double ' \
+        'to receive String for value but observed Integer'
+      )
+      matches = report.scan(/^Expected .+ to return .+ but observed .+$/)
+      expect(matches.size).to be(3)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'bundler'
+require 'timeout'
+
+Bundler.with_clean_env { system('cd test_app && yard --no-cache --no-output > /dev/null') }
+
+begin
+  require 'mutest'
+
+  module Mutest
+    class Selector
+      class Expression < self
+        def call(_subject)
+          integration.all_tests
+        end
+      end # Expression
+    end # Selector
+  end # Mutest
+rescue LoadError
+end
+
+module YardcheckSpec
+  ROOT = Pathname.new(__dir__).parent
+  TEST_APP = ROOT.join('test_app')
+
+  Yardcheck::Documentation.load_yard
+  test_app_yardoc = TEST_APP.join('.yardoc')
+  YARD::Registry.load!(test_app_yardoc.to_s)
+  YARDOCS = YARD::Registry.all(:method)
+end # YardcheckSpec
+
+RSpec.configure do |config|
+  # Define metadata for all tests which live under spec/integration
+  config.define_derived_metadata(file_path: %r{\bspec/integration/}) do |metadata|
+    # Set the type of these tests as 'integration'
+    metadata[:type]   = :integration
+
+    # Define metadata for mutant so it knows to never run these tests
+    metadata[:mutest] = false
+  end
+
+  config.around(file_path: %r{\bspec/unit/}) do |example|
+    Timeout.timeout(0.1, &example)
+  end
+end
+
+$LOAD_PATH.unshift(YardcheckSpec::TEST_APP.join('lib').to_s)
+
+require 'test_app'

data/spec/unit/yardcheck/const_spec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+RSpec.describe Yardcheck::Const do
+  before do
+    stub_const('Foo', Module.new)
+
+    module Foo
+      module Bar
+        module Baz
+        end # Baz
+      end # Bar
+    end # Foo
+  end
+
+  it 'resolves top level constant' do
+    expect(described_class.resolve('Foo')).to eql(described_class.new(Foo))
+  end
+
+  it 'resolves namespaced constant with qualified top level parent' do
+    expect(described_class.resolve('Foo::Bar')).to eql(described_class.new(Foo::Bar))
+  end
+
+  it 'resolves nested constant from nested scope' do
+    expect(described_class.resolve('Bar', Foo)).to eql(described_class.new(Foo::Bar))
+  end
+
+  it 'resolves top parent constant from scope of nested constant' do
+    expect(described_class.resolve('Foo', Foo::Bar)).to eql(described_class.new(Foo))
+  end
+
+  it 'resolves nested constant form deeply nested scope' do
+    expect(described_class.resolve('Foo::Bar', Foo::Bar::Baz)).to eql(described_class.new(Foo::Bar))
+  end
+
+  it 'resolves top level stdlib constant from scope of nested constant' do
+    expect(described_class.resolve('String', Foo::Bar::Baz)).to eql(described_class.new(String))
+  end
+
+  it 'resolves the scope when given the scope name' do
+    expect(described_class.resolve('Bar', Foo::Bar)).to eql(described_class.new(Foo::Bar))
+  end
+
+  it 'returns an invalid const object when given an unresolveable reference' do
+    expect(described_class.resolve('What', Foo::Bar)).to eql(
+      described_class::Invalid.new(Foo::Bar, 'What')
+    )
+  end
+end

data/spec/unit/yardcheck/documentation_spec.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+require 'yard'
+
+RSpec.describe Yardcheck::Documentation do
+  def yardocs_for(title)
+    selection = YardcheckSpec::YARDOCS.select { |doc| doc.title == title }
+    fail "Unable to find doc with title #{title}" if selection.empty?
+    selection
+  end
+
+  def doc_for(title)
+    described_class.new(yardocs_for(title))
+  end
+
+  def method_object(title)
+    doc_for(title).method_objects.first
+  end
+
+  def literal(const)
+    Yardcheck::Typedef::Literal.new(const)
+  end
+
+  def typedef(*members)
+    Yardcheck::Typedef.new(members)
+  end
+
+  def const(constant)
+    Yardcheck::Const.new(constant)
+  end
+
+  let(:namespace_add) { method_object('TestApp::Namespace#add')                    }
+  let(:undocumented)  { method_object('TestApp::Namespace#undocumented')           }
+  let(:invalid)       { method_object('TestApp::Namespace#ignoring_invalid_types') }
+
+  it 'resolves constant' do
+    expect(namespace_add.namespace).to eql(TestApp::Namespace)
+  end
+
+  it 'resolves parameters' do
+    expect(namespace_add.params).to eql(
+      left:  typedef(literal(const(Integer))),
+      right: typedef(literal(const(Integer)))
+    )
+  end
+
+  it 'resolves return value' do
+    expect(namespace_add.return_type).to eql(typedef(literal(const(String))))
+  end
+
+  it 'labels instance scope' do
+    expect(namespace_add.scope).to be(:instance)
+  end
+
+  it 'exposes the selector' do
+    expect(namespace_add.selector).to be(:add)
+  end
+
+  it 'handles documented returns without types' do
+    expect(method_object('TestApp::Namespace#return_tag_without_type').return_type)
+      .to eql(typedef)
+  end
+
+  it 'handles returns with a literal nil' do
+    expect(method_object('TestApp::Namespace#return_nil').return_type)
+      .to eql(typedef(literal(const(NilClass))))
+  end
+
+  it 'handles methods that return instance of the class' do
+    expect(method_object('TestApp::Namespace#return_self').return_type)
+      .to eql(typedef(literal(const(TestApp::Namespace))))
+  end
+
+  it 'supports [undefined]' do
+    expect(method_object('TestApp::Namespace#undefined_return').return_type)
+      .to eql(typedef(Yardcheck::Typedef::Undefined.new))
+  end
+
+  it 'supports [Boolean]' do
+    expect(method_object('TestApp::Namespace#bool_return').return_type)
+      .to eql(typedef(literal(const(TrueClass)), literal(const(FalseClass))))
+  end
+
+  it 'supports [Array<String>]' do
+    expect(method_object('TestApp::Namespace#array_return').return_type).to eql(
+      typedef(Yardcheck::Typedef::Collection.new(const(Array), [literal(const(String))]))
+    )
+  end
+
+  it 'supports multiple @return' do
+    expect(method_object('TestApp::Namespace#multiple_returns').return_type)
+      .to eql(typedef(literal(const(String)), literal(const(NilClass))))
+  end
+
+  it 'ignores documented params without names' do
+    expect(method_object('TestApp::Namespace#param_without_name').params).to eql({})
+  end
+
+  it 'ignores invalid constant resolve' do
+    expect(method_object('TestApp::Namespace#ignoring_invalid_types').params).to be_empty
+  end
+
+  it 'produces warnings for unresolvable params and returns' do
+    expect(invalid.warnings).to eql([
+      Yardcheck::Warning.new(
+        invalid,
+        Yardcheck::Typedef::Parser.new('TestApp::Namespace', %w[What]).parse
+      ),
+      Yardcheck::Warning.new(
+        invalid,
+        Yardcheck::Typedef::Parser.new('TestApp::Namespace', %w[Wow]).parse
+      )
+    ])
+  end
+
+  it 'does not provide a return type when documentation is invalid' do
+    expect(invalid.return_type).to be(nil)
+  end
+
+  it 'does not produce warnings for normal methods' do
+    aggregate_failures do
+      expect(method_object('TestApp::Namespace#add').warnings).to eql([])
+      expect(undocumented.warnings).to eql([])
+    end
+  end
+
+  it 'exposes source' do
+    yardoc = yardocs_for('TestApp::Namespace#return_self').first
+
+    allow(yardoc).to receive(:file).and_wrap_original do |method|
+      File.join('./test_app', method.call).to_s
+    end
+
+    method_object = described_class::MethodObject.new(yardoc)
+    expect(method_object.source).to eql(<<~RUBY.chomp)
+      # @return [Namespace]
+      def return_self
+        self
+      end
+    RUBY
+  end
+
+  it 'return type of undocumented' do
+    expect(undocumented.return_type).to be(nil)
+  end
+end