yard-virtus 0.0.4

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,67 @@
+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
+  include Virtus.model
+
+  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,71 @@
+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 # context "when namespace becomes virtus model via inheritance chain" do
+
+  it "parses default value when it is singleton" do
+    expect(YARD::Registry.at("Page#views")).to have_default_value(0)
+    expect(YARD::Registry.at("Page#published")).to have_default_value(false)
+  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,45 @@
+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
+
+RSpec::Matchers.define :have_default_value do |default_value|
+  match do |method_object|
+    expect(true).to be_true
+  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-virtus.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-virtus"
+  gem.version     = YARD::Virtus::VERSION
+  gem.authors     = ["Dmitry Dzema"]
+  gem.email       = ["dimad.ag@gmail.com"]
+  gem.homepage    = "https://github.com/DimaD/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",   "~> 0.8.7.4")
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: yard-virtus
+version: !ruby/object:Gem::Version
+  version: 0.0.4
+platform: ruby
+authors:
+- Dmitry Dzema
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: virtus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.7.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.7.4
+description: This library provides handlers to YARD so it can extract information
+  about Virtus attributes like types and visibility
+email:
+- dimad.ag@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- example/README.md
+- example/address.rb
+- example/city.rb
+- example/user.rb
+- lib/yard-virtus.rb
+- lib/yard/virtus/code_objects.rb
+- lib/yard/virtus/code_objects/attribute_reader.rb
+- lib/yard/virtus/code_objects/attribute_writer.rb
+- lib/yard/virtus/declarations.rb
+- lib/yard/virtus/declarations/options.rb
+- lib/yard/virtus/declarations/type.rb
+- lib/yard/virtus/declarations/virtus_attribute.rb
+- lib/yard/virtus/declarations/virtus_model.rb
+- lib/yard/virtus/handlers.rb
+- lib/yard/virtus/handlers/include_virtus_model.rb
+- lib/yard/virtus/handlers/virtus_attribute.rb
+- lib/yard/virtus/version.rb
+- spec/code_objects/attribute_reader_spec.rb
+- spec/code_objects/attribute_writer_spec.rb
+- spec/declarations/options_spec.rb
+- spec/declarations/type_spec.rb
+- spec/declarations/virtus_attribute_spec.rb
+- spec/declarations/virtus_model_spec.rb
+- spec/examples/include_virtus_model_001.rb.txt
+- spec/examples/virtus_attribute_001.rb.txt
+- spec/handlers/include_virtus_model_spec.rb
+- spec/handlers/virtus_attribute_spec.rb
+- spec/spec_helper.rb
+- spec/support/helpers/handler_helpers.rb
+- spec/support/helpers/parsing_helpers.rb
+- spec/support/matchers/attribute_matchers.rb
+- spec/support/matchers/method_type_matchers.rb
+- yard-virtus.gemspec
+homepage: https://github.com/DimaD/yard-virtus
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: This library provides handlers to YARD so it can extract information about
+  Virtus attributes like types and visibility
+test_files: []
+has_rdoc: