yardcheck 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 88750f901e803de9b757d1699df2284e811e1b46
+  data.tar.gz: 47016f5393d602d75bbaf3a736735b9d93680eb9
+SHA512:
+  metadata.gz: 688559a7d4caebc0218a1193ed67add77977e4c191e1f58767fa85e0120503a333d4146fe148d9f205c6940972f4d2451883e91fc21d244f3cc7575a3ac49b85
+  data.tar.gz: 3ae9fe9623004ec459faf4a1cfb475c7f60e7e4f2f47a177ae160360d92a5ef6c44a24fe3acd00c067fb09e0d9eb072be1dcae284dc7949fcb117731b760cdc6

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/test_app/.bundle/*

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require yardcheck
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,214 @@
+---
+inherit_from: .rubocop_todo.yml
+require:
+  - rubocop-rspec
+  - rubocop/devtools
+AllCops:
+  Exclude:
+  - 'test_app/**/*'
+  - 'tmp/**/*'
+  - vendor/**/*
+  DisplayCopNames: true
+  TargetRubyVersion: 2.3
+# This ends up being too spammy
+Style/Documentation:
+  Enabled: false
+Style/ExtraSpacing:
+  AllowForAlignment: true
+Metrics/LineLength:
+  Max: 100
+Metrics/BlockLength:
+  Exclude:
+  # Ignore RSpec DSL
+  - spec/**/*
+  # Ignore Rake task DSL
+  - Rakefile
+Style/IfUnlessModifier:
+  MaxLineLength: 100
+Style/Next:
+  EnforcedStyle: always
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%i': '[]'
+    '%I': '[]'
+    '%q': '{}'
+    '%Q': '{}'
+    '%r': '{}'
+    '%s': ()
+    '%w': '[]'
+    '%W': '[]'
+    '%x': ()
+Style/TrivialAccessors:
+  ExactNameMatch: false
+Style/SymbolArray:
+  Enabled: true
+Style/BarePercentLiterals:
+  EnforcedStyle: percent_q
+Style/CollectionMethods:
+  Enabled: true
+Style/Send:
+  Enabled: true
+Style/AutoResourceCleanup:
+  Enabled: true
+Style/FirstArrayElementLineBreak:
+  Enabled: true
+Style/FirstHashElementLineBreak:
+  Enabled: true
+Style/FirstMethodArgumentLineBreak:
+  Enabled: true
+Style/FirstMethodParameterLineBreak:
+  Enabled: true
+Style/MultilineArrayBraceLayout:
+  Enabled: true
+Style/MultilineAssignmentLayout:
+  EnforcedStyle: new_line
+  Enabled: true
+Style/MultilineHashBraceLayout:
+  Enabled: true
+Style/MultilineMethodCallBraceLayout:
+  Enabled: true
+Style/MultilineMethodDefinitionBraceLayout:
+  Enabled: true
+Style/OptionHash:
+  Enabled: true
+Style/StringMethods:
+  Enabled: true
+Style/IndentArray:
+  EnforcedStyle: consistent
+Style/IndentHash:
+  EnforcedStyle: consistent
+MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+Style/AlignHash:
+  EnforcedColonStyle: table
+Style/SignalException:
+  EnforcedStyle: semantic
+Style/SingleLineBlockParams:
+  Enabled: false
+# We prefer being able to write
+#
+#   foo(*%w[bar baz qux norf hello goodbye])
+#
+# over
+#
+#   foo('bar', 'baz', 'qux', 'norf', 'hello', 'goodbye')
+#
+# because
+#
+#   1. the `%w` signals that all elements are strings without interpolation
+#   2. the `%w` case is more compact
+#
+# The only exception is method invocations with a single argument. These
+# cases should be `foo('bar')` and never `foo(*%w[bar])`
+#
+Lint/UnneededSplatExpansion:
+  Enabled: false
+# We only use guard clauses when it guards two or more statements:
+#
+#    # bad
+#    def foo
+#      return if bar
+#
+#      baz
+#    end
+#
+#    # good
+#    def foo
+#      baz if bar
+#    end
+#
+# This includes conditionals with an `else` branch:
+#
+#    # bad
+#    def foo
+#      return qux if bar
+#
+#      baz
+#    end
+#
+#    # good
+#    def foo
+#      if bar
+#        qux
+#      else
+#        baz
+#      end
+#    end
+#
+# It is up to the author of the code in question if the condition concerns
+# exactly two statements
+#
+#    # ok
+#    def foo
+#      return if bar
+#
+#      baz
+#      qux
+#    end
+#
+#    # also ok
+#    def foo
+#      if bar
+#        baz
+#        qux
+#      end
+#    end
+#
+# Use a guard clause if more than two statements are being guarded by the conditional
+#
+#    # bad
+#    def foo
+#      if bar
+#        baz
+#        qux
+#        norf
+#      end
+#    end
+#
+#    # good
+#    def foo
+#      return if bar
+#
+#      baz
+#      qux
+#      norf
+#    end
+Style/GuardClause:
+  Enabled: false
+# Prefer writing an empty method on two lines
+#
+#    # good
+#    def foo
+#    end
+#
+#    # bar
+#    def foo; end
+#
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+# RuboCop disables end alignment by default. Explanation:
+#
+#     The end alignment cops are in the Lint category because the bad
+#     indentation could be something more serious than just a style issue.
+#     It could be a mistake in which keyword you think you're matching with the end.
+#     (ruby -w warns for these too, by the way.) So for this reason I don't think
+#     we can add auto-correct for these cops.
+#
+# From https://github.com/bbatsov/rubocop/pull/1789#issuecomment-92308357
+#
+# I think we have more than enough tools that sound the alarms if we have
+# such an obvious mistake like mismatched tokens.
+#
+#   - Our specs are likely to fail
+#   - RuboCop will flag it regardless, it just doesn't autocorrect it by default
+#   - Ruby will emit a warning which we configure to fail our specs
+#
+# So I think it is safe to enable autocorrect for end alignment cops because it
+# does not seem unsafe and it improves workflow to be able to autocorrect alignment
+Lint/DefEndAlignment:
+  AutoCorrect: true
+# See explanation for `Lint/DefEndAlignment`
+Lint/EndAlignment:
+  AutoCorrect: true

data/.rubocop_todo.yml

@@ -0,0 +1,69 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2017-03-22 20:59:41 -0700 using RuboCop version 0.47.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
+Lint/HandleExceptions:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+# Offense count: 4
+Metrics/AbcSize:
+  Max: 22
+
+# Offense count: 1
+Metrics/CyclomaticComplexity:
+  Max: 8
+
+# Offense count: 5
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
+Metrics/LineLength:
+  Max: 138
+
+# Offense count: 3
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 27
+
+# Offense count: 1
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integration/yardcheck_spec.rb'
+
+# Offense count: 6
+# Configuration parameters: Max.
+RSpec/ExampleLength:
+  Exclude:
+    - 'spec/integration/yardcheck_spec.rb'
+    - 'spec/unit/yardcheck/documentation_spec.rb'
+    - 'spec/unit/yardcheck/method_tracer_spec.rb'
+    - 'spec/unit/yardcheck/typedef/parser_spec.rb'
+    - 'spec/unit/yardcheck/typedef_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: IgnoreSymbolicNames.
+RSpec/VerifiedDoubles:
+  Exclude:
+    - 'spec/unit/yardcheck/test_value_spec.rb'
+
+# Offense count: 1
+Style/MethodMissing:
+  Exclude:
+    - 'lib/yardcheck/proxy.rb'
+
+# Offense count: 6
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: separated, grouped
+Style/MixinGrouping:
+  Exclude:
+    - 'lib/yardcheck/documentation.rb'
+    - 'lib/yardcheck/documentation/method_object.rb'
+    - 'lib/yardcheck/method_tracer.rb'
+    - 'lib/yardcheck/runner.rb'
+    - 'lib/yardcheck/spec_observer.rb'
+    - 'lib/yardcheck/typedef/parser.rb'

data/.ruby-version

@@ -0,0 +1 @@
+2.3.3

data/Gemfile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+ruby File.read('.ruby-version').chomp
+
+gemspec
+
+group :test do
+  gem 'rspec', '~> 3.5'
+end
+
+group :lint do
+  gem 'rubocop',          git: 'https://github.com/bbatsov/rubocop.git'
+  gem 'rubocop-devtools', git: 'https://github.com/backus/rubocop-devtools.git'
+  gem 'rubocop-rspec',    git: 'https://github.com/backus/rubocop-rspec.git'
+end
+
+gem 'guard'
+gem 'guard-rspec'
+gem 'mutest', '0.0.6'
+gem 'mutest-rspec'

data/Guardfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(/.+\.rb/) { %w[spec/unit] }
+end

data/README.md

@@ -0,0 +1,83 @@
+# Yardcheck
+
+Check whether your YARD types are correct by running your test suite. Take a look!
+
+![yardcheck](https://cloud.githubusercontent.com/assets/2085622/24262402/211ecfbe-0fb7-11e7-86f7-1b287298339f.gif)
+
+## What is this?
+
+When you write documentation like this
+
+```ruby
+# Validates the user
+#
+# @param user [User]
+#
+# @return [true,false]
+# 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`.
+
+`yardcheck` traces method invocations to observe the parameters and return values in your application while running your test suite. When your test suite finishes running we compare the observed types found while running your tests against the types in your documentation.
+
+For example, here is part of the output from the demo gif at the top of the README:
+
+> Expected `Dry::Types::Array::Member#try` to receive `an object responding to #call` for `block` but observed `NilClass`
+>
+> ```
+> source: lib/dry/types/array/member.rb:35
+> tests:
+>   - ./spec/dry/types/compiler_spec.rb:184
+>   - ./spec/dry/types/sum_spec.rb:47
+>   - ./spec/dry/types/sum_spec.rb:60
+>   - ./spec/dry/types/types/form_spec.rb:235
+>   - ./spec/dry/types/types/form_spec.rb:240
+>   - ./spec/dry/types/types/form_spec.rb:245
+>   - ./spec/dry/types/types/form_spec.rb:250
+>   - ./spec/dry/types/types/json_spec.rb:69
+> ```
+>
+>
+> ```ruby
+> # @param [Array, Object] input
+> # @param [#call] block
+> # @yieldparam [Failure] failure
+> # @yieldreturn [Result]
+> # @return [Result]
+> def try(input, &block)
+>   if input.is_a?(::Array)
+>     result = call(input, :try)
+>     output = result.map(&:input)
+>
+>     if result.all?(&:success?)
+>       success(output)
+>     else
+>       failure = failure(output, result.select(&:failure?))
+>       block ? yield(failure) : failure
+>     end
+>   else
+>     failure = failure(input, "#{input} is not an array")
+>     block ? yield(failure) : failure
+>   end
+> end
+> ```
+
+Yardcheck is doing some cool things here:
+
+1. It outputs the offending method and documentation to give you immediate context. It also gives you the path and line number if you want to open up that file.
+2. It understands that the YARD documentation `@param [#call]` means a duck typed object that responds to the method `#call`.
+3. It tells you that it actually observed cases where the param was `nil` which does not respond to `#call`.
+4. It lists all of the tests that observed a `nil` block param.
+
+In this case I would update the documentation to be `@param [#call, nil] block`
+
+# 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.

data/bin/yardcheck

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'yardcheck'
+
+Yardcheck::Runner.run(ARGV).check

data/lib/yardcheck.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'anima'
+require 'concord'
+require 'yard'
+require 'rspec'
+require 'coderay'
+
+require 'yardcheck/version'
+require 'yardcheck/runner'
+require 'yardcheck/method_tracer'
+require 'yardcheck/method_call'
+require 'yardcheck/proxy'
+require 'yardcheck/test_value'
+require 'yardcheck/test_runner'
+require 'yardcheck/const'
+require 'yardcheck/documentation'
+require 'yardcheck/documentation/method_object'
+require 'yardcheck/typedef'
+require 'yardcheck/typedef/parser'
+require 'yardcheck/observation'
+require 'yardcheck/spec_observer'
+require 'yardcheck/color'
+require 'yardcheck/violation'
+require 'yardcheck/warning'
+require 'yardcheck/source_lines'