yard-virtus2 0.0.5

data/spec/declarations/virtus_attribute_spec.rb

@@ -0,0 +1,73 @@
+require "spec_helper"
+
+describe YARD::Virtus::Declarations::VirtusAttribute do
+  let(:ast) { ruby_ast(declaration) }
+  let(:namespace) { YARD::CodeObjects::ClassObject.new(nil, "TemporarySpecClass") }
+  let(:subject) { described_class.new(ast) }
+
+  def self.example(src, &block)
+    c = context "'#{src}'"
+    c.let(:declaration) { src }
+    c.class_eval(&block)
+  end
+
+  example "attribute :title, String" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:title) }
+    it { expect(subject.type).to eq("String") }
+
+    it "produces reader method object" do
+      expect(subject.attribute_reader).to be_kind_of(YARD::Virtus::CodeObjects::AttributeReader)
+    end
+
+    it "produces writer method object" do
+      expect(subject.attribute_writer).to be_kind_of(YARD::Virtus::CodeObjects::AttributeWriter)
+    end
+  end
+
+  example "attribute :title, Namespaced::String" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:title) }
+    it { expect(subject.type).to eq("Namespaced::String") }
+  end
+
+  example "attribute :locations, Array[Address]" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:locations) }
+    it { expect(subject.type).to eq("Array<Address>") }
+  end
+
+  example "attribute :locations, Array[Array[Point]]" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:locations) }
+    it { expect(subject.type).to eq("Array<Array<Point>>") }
+  end
+
+  example "attribute :locations, Hash[Symbol => Address]" do
+    it { expect(subject).to be_readable }
+    it { expect(subject).to be_writable }
+
+    it { expect(subject.attr_name).to eq(:locations) }
+    it { expect(subject.type).to eq("Hash{Symbol => Address}") }
+  end
+
+  example "attribute :unique_id, String, :writer => :private" do
+    it { expect(subject).to have_private_writer }
+  end
+
+  example "attribute :unique_id, String, writer: :private" do
+    it { expect(subject).to have_private_writer }
+  end
+
+  example "attribute :unique_id, String, :writer => :private, :a => :b" do
+    it { expect(subject).to have_private_writer }
+  end
+end

data/spec/declarations/virtus_model_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+describe YARD::Virtus::Declarations::VirtusModel do
+  let(:ast) { ruby_ast(declaration) }
+  let(:namespace) { YARD::CodeObjects::ClassObject.new(nil, "TemporarySpecClass") }
+  let(:subject) { described_class.new(ast) }
+
+  context "when declaration is 'Virtus.model'" do
+    let(:declaration) { "Virtus.model" }
+
+    it "has one module proxy" do
+      expect(subject.module_proxies_in_ns(namespace)).to have(1).item
+    end
+
+    it "has module proxy for Virtus.model" do
+      expect(subject.module_proxies_in_ns(namespace)).to include(P("Virtus.model"))
+    end
+  end
+
+  context "when declaration is 'Virtus.value_object'" do
+    let(:declaration) { "Virtus.value_object" }
+
+    it "has module proxy for Virtus.value_object" do
+      expect(subject.module_proxies_in_ns(namespace)).to include(P("Virtus.value_object"))
+    end
+  end
+
+  context "when declaration is 'Virtus.model(mass_assignmet: false)'" do
+    let(:declaration) { "Virtus.model(mass_assignment: false)" }
+
+    it "has module proxy for Virtus.model" do
+      expect(subject.module_proxies_in_ns(namespace)).to include(P("Virtus.model"))
+    end
+  end
+end

data/spec/examples/include_virtus_model_001.rb.txt

@@ -0,0 +1,15 @@
+class A
+  include Model
+end
+
+class ModelA
+  include Virtus.model
+end
+
+class ModelB
+  include Virtus.value_object
+end
+
+class ModelC
+  include Virtus.model(mass_assignmet: false)
+end

data/spec/examples/virtus_attribute_001.rb.txt

@@ -0,0 +1,65 @@
+class Address
+  attribute :city, String
+end
+
+class User
+  include Virtus.model
+
+  attribute :name, String
+  attribute :age, Integer
+
+  attribute :friends, Array[User]
+  attribute :addresses, Hash[Symbol => Address]
+
+  attribute :unique_id, String, :writer => :private
+
+  # keeps extracted type if comment is present
+  attribute :email, Email
+
+  # preserves private attribute if comment is present
+  attribute :unique_uuid, String, :writer => :private
+end
+
+class Page
+  attribute :title, String
+
+  # default from a singleton value (integer in this case)
+  attribute :views, Integer, :default => 0
+
+  # default from a singleton value (boolean in this case)
+  attribute :published, Boolean, :default => false
+
+  # default from a callable object (proc in this case)
+  attribute :slug, String, :default => lambda { |page, attribute| page.title.downcase.gsub(' ', '-') }
+
+  # default from a method name as symbol
+  attribute :editor_title, String,  :default => :default_editor_title
+end
+
+class BaseVirtusModel
+  include Virtus.model
+end
+
+class City < BaseVirtusModel
+  attribute :name, String
+end
+
+# Mixin is not defined yet which can
+# happen in real world setup when files are
+# scanned in the order which does not match
+# their dependencies order.
+class District
+  include ModelMixin
+
+  attribute :city, City
+end
+
+module ModelMixin
+  include Virtus.model
+end
+
+class Country
+  include ModelMixin
+
+  attribute :cities, Array[City]
+end

data/spec/handlers/include_virtus_model_spec.rb

@@ -0,0 +1,22 @@
+require "spec_helper"
+
+describe YARD::Virtus::Handlers::IncludeVirtusModel, type: :handler do
+  before(:all) { parse_file! :include_virtus_model_001 }
+
+  it "processes basic model declaration" do
+    expect(YARD::Registry.at(:ModelA).instance_mixins).to include(P("Virtus.model"))
+  end
+
+  it "processes value object delcaration" do
+    expect(YARD::Registry.at(:ModelB).instance_mixins).to include(P("Virtus.value_object"))
+  end
+
+  it "processes model declaration with parameters" do
+    expect(YARD::Registry.at(:ModelC).instance_mixins).to include(P("Virtus.model"))
+  end
+
+  it "marks model namespace as supporting virtus attributes" do
+    namespace = YARD::Registry.at(:ModelA)
+    expect(namespace[:supports_virtus_attributes]).to be_true
+  end
+end

data/spec/handlers/virtus_attribute_spec.rb

@@ -0,0 +1,67 @@
+require "spec_helper"
+
+describe YARD::Virtus::Handlers::VirtusAttribute, type: :handler do
+  before(:all) { parse_file! :virtus_attribute_001 }
+
+  it "does not parse attribute if namespace does not include Virtus declaration" do
+    expect(YARD::Registry.at(:Address)).not_to define_readable_attribute(:city)
+    expect(YARD::Registry.at(:Address)).not_to define_writable_attribute(:city)
+  end
+
+  it "parses attribute name" do
+    expect(YARD::Registry.at(:User)).to define_readable_attribute(:name)
+    expect(YARD::Registry.at(:User)).to define_writable_attribute(:name)
+  end
+
+  it "parses attribute with scalar type" do
+    expect(YARD::Registry.at("User#name")).to have_return_type("String")
+  end
+
+  it "parses attribute with collection type" do
+    expect(YARD::Registry.at("User#friends")).to have_return_type("Array<User>")
+  end
+
+  it "parses attribute with collection map type" do
+    expect(YARD::Registry.at("User#addresses")).to have_return_type("Hash{Symbol => Address}")
+  end
+
+  it "parses and marks attributes with private writers" do
+    expect(YARD::Registry.at("User#unique_id=")).to have_private_writer_api
+  end
+
+  it "parses type of attribute with attached docstring" do
+    expect(YARD::Registry.at("User#email")).to have_return_type("Email")
+  end
+
+  it "parses information about private writers with attached docstring" do
+    expect(YARD::Registry.at("User#unique_uuid=")).to have_private_writer_api
+  end
+
+
+  context "when namespace becomes virtus model via inheritance chain" do
+    context "from parent class" do
+      it "parses attribute declaration" do
+        expect(YARD::Registry.at(:City)).to define_readable_attribute(:name)
+        expect(YARD::Registry.at(:City)).to define_writable_attribute(:name)
+      end
+    end
+
+    context "from mixin" do
+      context "and mixin have already been defined when processing declaration" do
+        it "parses attribute declaration" do
+          expect(YARD::Registry.at(:Country)).to define_readable_attribute(:cities)
+          expect(YARD::Registry.at(:Country)).to define_writable_attribute(:cities)
+        end
+      end
+
+      context "and mixin have not been defined when processing delcaration" do
+        it "parses attribute declaration" do
+          pending
+
+          expect(YARD::Registry.at(:District)).to define_readable_attribute(:city)
+          expect(YARD::Registry.at(:District)).to define_writable_attribute(:city)
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,65 @@
+require "stringio"
+
+_dir = File.dirname(__FILE__)
+
+# Requires supporting ruby files with custom matchers and macros, etc,
+# in spec/support/ and its subdirectories.
+Dir[File.join(_dir, "support", "**", "*.rb")].each do |f|
+  require f
+end
+
+require File.join(_dir, "..", "lib", "yard-virtus")
+
+# Shortcut for creating a YARD::CodeObjects::Proxy via a path
+#
+# @see YARD::CodeObjects::Proxy
+# @see YARD::Registry.resolve
+def P(namespace, name = nil, type = nil)
+  namespace, name = nil, namespace if name.nil?
+  YARD::Registry.resolve(namespace, name, false, true, type)
+end
+
+RSpec.configure do |config|
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = "random"
+  config.color = true
+
+  config.include VirtusYARD::Spec::HandlerHelpers, :type => :handler
+  config.include VirtusYARD::Spec::ParsingHelpers
+
+  config.before(:all) { YARD::Logger.instance(StringIO.new) }
+end
+
+def parse_file!(file, thisfile = __FILE__, log_level = log.level, ext = '.rb.txt')
+  YARD::Registry.clear
+  path = File.join(File.dirname(thisfile), 'examples', file.to_s + ext)
+  YARD::Parser::SourceParser.parse(path, [], log_level)
+end
+
+class StubbedProcessor < YARD::Handlers::Processor
+  def process(statements)
+    statements.each_with_index do |stmt, index|
+      find_handlers(stmt).each do |handler|
+        handler.new(self, stmt).process
+      end
+    end
+  end
+end
+
+class StubbedSourceParser < YARD::Parser::SourceParser
+  StubbedSourceParser.parser_type = :ruby
+  def post_process
+    post = StubbedProcessor.new(self)
+    post.process(@parser.enumerator)
+  end
+end
+
+def with_parser(parser_type, &block)
+  tmp = StubbedSourceParser.parser_type
+  StubbedSourceParser.parser_type = parser_type
+  yield
+  StubbedSourceParser.parser_type = tmp
+end

data/spec/support/helpers/handler_helpers.rb

@@ -0,0 +1,9 @@
+module VirtusYARD
+  module Spec
+    module HandlerHelpers
+      def r(key)
+        YARD::P(key)
+      end
+    end
+  end
+end

data/spec/support/helpers/parsing_helpers.rb

@@ -0,0 +1,13 @@
+module VirtusYARD
+  module Spec
+    module ParsingHelpers
+      def parser_for(code)
+        YARD::Parser::Ruby::RubyParser.new(code, "virtus-yard-spec.rb")
+      end
+
+      def ruby_ast(statement)
+        parser_for(statement).parse.ast[0]
+      end
+    end
+  end
+end

data/spec/support/matchers/attribute_matchers.rb

@@ -0,0 +1,39 @@
+RSpec::Matchers.define :define_readable_attribute do |attr_name|
+  match do |namespace|
+    expect(namespace).to be_kind_of(YARD::CodeObjects::NamespaceObject)
+
+    rname = namespace.to_s + "#" + attr_name.to_s
+    reader_object  = YARD::Registry.at(rname)
+    attributes_map = namespace.attributes[:instance][attr_name]
+
+    expect(reader_object).to be_instance_of(YARD::CodeObjects::MethodObject)
+    expect(attributes_map[:read]).to eq(reader_object)
+  end
+
+  description do |attr_name|
+    "define readable attribute #{attr_name} in #{namespace.source}"
+  end
+end
+
+RSpec::Matchers.define :define_writable_attribute do |attr_name|
+  match do |namespace|
+    expect(namespace).to be_kind_of(YARD::CodeObjects::NamespaceObject)
+
+    wname = namespace.to_s + "#" + attr_name.to_s + "="
+    writer_object  = YARD::Registry.at(wname)
+    attributes_map = namespace.attributes[:instance][attr_name]
+
+    expect(writer_object).to be_instance_of(YARD::CodeObjects::MethodObject)
+    expect(attributes_map[:write]).to eq(writer_object)
+  end
+
+  description do
+    "define writable attribute #{attr_name}"
+  end
+end
+
+RSpec::Matchers.define :have_private_writer_api do
+  match do |method_object|
+    expect(method_object.tags(:private).size).to be > 0
+  end
+end

data/spec/support/matchers/method_type_matchers.rb

@@ -0,0 +1,11 @@
+# @example
+#   expect(YARD::Registry.at("User#friends")).to have_return_type("Array<User>")
+RSpec::Matchers.define :have_return_type do |yard_type_string|
+  match do |method_object|
+    return_tags = method_object.tags(:return)
+
+    expect(return_tags.size).to be > 0
+
+    expect(return_tags.any? { |tag| tag.types.include?(yard_type_string) }).to be_true
+  end
+end

data/yard-virtus2.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+
+require File.expand_path("../lib/yard/virtus/version", __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name        = "yard-virtus2"
+  gem.version     = YARD::Virtus::VERSION
+  gem.authors     = ["Dmitry Dzema", "Daniel Orner"]
+  gem.email       = ["dimad.ag@gmail.com", "dmorner@gmail.com"]
+  gem.homepage    = "https://github.com/dorner/yard-virtus"
+  gem.summary     = "This library provides handlers to YARD so it can extract information about Virtus attributes like types and visibility"
+  gem.description = gem.summary
+  gem.license     = "MIT"
+
+  gem.require_paths = ["lib"]
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {spec}/*`.split("\n")
+  gem.extra_rdoc_files = %w[LICENSE.txt README.md]
+
+  gem.add_dependency("virtus", "= 1.0.2")
+  gem.add_dependency("yard")
+end