puppet-strings 2.2.0 → 2.3.0

data/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Handlers::Puppet::DataTypeAliasHandler, if: TEST_PUPPET_DATATYPES do
+  subject {
+    YARD::Parser::SourceParser.parse_string(source, :puppet)
+    YARD::Registry.all(:puppet_data_type_alias)
+  }
+
+  describe 'parsing source without a type alias definition' do
+    let(:source) { 'notice hi' }
+
+    it 'no aliases should be in the registry' do
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing source with a syntax error' do
+    let(:source) { 'type Testype =' }
+
+    it 'should log an error' do
+      expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of (file|input)/).to_stdout_from_any_process
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing a data type alias with a missing docstring' do
+    let(:source) { 'type Testype = String[1]' }
+
+    it 'should log a warning' do
+      expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet type alias 'Testype' at \(stdin\):1\./).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a data type alias with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+  # A simple foo type.
+  # @summary A short summary.
+  type Testype = String[1]
+  SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+  # A simple foo type.
+  # @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
+  type Testype = String[1]
+  SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_data_type_alias 'Testype' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
+end

data/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb

@@ -44,7 +44,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+    SOURCE
     }
     it 'does not output a warning for title/name' do
       expect{ subject }.not_to output(/\[warn\].*(name|title).*/).to_stdout_from_any_process
@@ -92,7 +92,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+    SOURCE
     }
 
     it 'should output a warning' do
@@ -110,7 +110,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+    SOURCE
     }
 
     it 'should output a warning' do
@@ -129,7 +129,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+    SOURCE
     }
 
     it 'should respect the type that was documented' do
@@ -152,7 +152,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+    SOURCE
     }
 
     it 'should output a warning' do
@@ -171,7 +171,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+    SOURCE
     }
 
     it 'should respect the type that was documented' do
@@ -197,7 +197,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+      SOURCE
       }
 
       it 'should parse the summary' do
@@ -220,7 +220,7 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
     ensure => present
   }
 }
-SOURCE
+      SOURCE
       }
 
       it 'should log a warning' do

data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb

@@ -44,7 +44,7 @@ function foo(Integer $param1, $param2, String $param3 = hi) {
   notice 'hello world'
   undef
 }
-SOURCE
+    SOURCE
     }
 
     it 'should register a function object' do
@@ -90,7 +90,7 @@ SOURCE
 function foo(Integer $param1, $param2, String $param3 = hi) {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should output a warning' do
@@ -107,7 +107,7 @@ SOURCE
 function foo(Integer $param1, $param2, String $param3 = hi) {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should output a warning' do
@@ -125,7 +125,7 @@ SOURCE
 function foo(Integer $param1, $param2, String $param3 = hi) {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should respect the type that was documented' do
@@ -147,7 +147,7 @@ SOURCE
 function foo(Integer $param1, $param2, String $param3 = hi) {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should output a warning' do
@@ -165,7 +165,7 @@ SOURCE
 function foo(Integer $param1, $param2, String $param3 = hi) {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should respect the type that was documented' do
@@ -186,7 +186,7 @@ SOURCE
 function foo(Integer $param1, $param2, String $param3 = hi) {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should output a warning' do
@@ -200,7 +200,7 @@ SOURCE
 function foo() >> String {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should register a function object with the correct return type' do
@@ -223,7 +223,7 @@ SOURCE
 function foo() >> String {
   notice 'hi there'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should not output a warning if return types match' do
@@ -238,7 +238,7 @@ SOURCE
 function foo() >> Struct[{'a' => Integer[1, 10]}] {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should prefer the return type from the function definition' do
@@ -260,7 +260,7 @@ SOURCE
 function foo() {
   notice 'hello world'
 }
-SOURCE
+    SOURCE
     }
 
     it 'should add a return tag with a default type value of Any' do
@@ -285,7 +285,7 @@ SOURCE
 function foo() {
   notice 'hello world'
 }
-SOURCE
+      SOURCE
       }
 
       it 'should parse the summary' do
@@ -304,7 +304,7 @@ function foo() {
   notice 'hello world'
 }
 
-SOURCE
+      SOURCE
       }
 
       it 'should log a warning' do

data/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb

@@ -0,0 +1,232 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler, if: TEST_PUPPET_DATATYPES do
+  subject {
+    YARD::Parser::SourceParser.parse_string(source, :ruby)
+    YARD::Registry.all(:puppet_data_type)
+  }
+
+  before(:each) do
+    # Tests may suppress logging to make it easier to read results,
+    # so remember the logging object prior to running the test
+    @original_yard_logging_object = YARD::Logger.instance.io
+  end
+
+  after(:each) do
+    # Restore the original logging IO object
+    YARD::Logger.instance.io = @original_yard_logging_object
+  end
+
+  def suppress_yard_logging
+    YARD::Logger.instance.io = nil
+  end
+
+  describe 'parsing source without a data type definition' do
+    let(:source) { 'puts "hi"' }
+
+    it 'no data types should be in the registry' do
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing an empty data type definition' do
+    let(:source) { <<-SOURCE
+Puppet::DataTypes.create_type('RubyDataType') do
+end
+SOURCE
+    }
+
+    it 'should register a data type object with no param tags' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
+      expect(object.name).to eq(:RubyDataType)
+      expect(object.docstring).to eq('')
+      expect(object.docstring.tags.size).to eq(1)
+      tags = object.docstring.tags(:api)
+      expect(tags.size).to eq(1)
+      expect(tags[0].text).to eq('public')
+
+      expect(object.parameters.size).to eq(0)
+    end
+  end
+
+  describe 'parsing a data type definition with missing param tags' do
+    let(:source) { <<-SOURCE
+# An example Puppet Data Type in Ruby.
+Puppet::DataTypes.create_type('RubyDataType') do
+  interface <<-PUPPET
+    attributes => {
+      msg => String[1],
+    }
+    PUPPET
+end
+SOURCE
+    }
+
+    it 'should output a warning' do
+      expect{ subject }.to output(/\[warn\]: Missing @param tag for attribute 'msg' near \(stdin\):2/).to_stdout_from_any_process
+    end
+
+    it 'should register a data type object with all param tags' do
+      suppress_yard_logging
+
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
+      expect(object.name).to eq(:RubyDataType)
+      expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
+      expect(object.docstring.tags.size).to eq(2)
+      tags = object.docstring.tags(:api)
+      expect(tags.size).to eq(1)
+      expect(tags[0].text).to eq('public')
+
+      # Check that the param tags are created
+      tags = object.docstring.tags(:param)
+      expect(tags.size).to eq(1)
+      expect(tags[0].name).to eq('msg')
+      expect(tags[0].text).to eq('')
+      expect(tags[0].types).to eq(['String[1]'])
+
+      # Check for default values for parameters
+      expect(object.parameters.size).to eq(1)
+      expect(object.parameters[0]).to eq(['msg', nil])
+    end
+  end
+
+  describe 'parsing a data type definition with extra param tags' do
+    let(:source) { <<-SOURCE
+# An example Puppet Data Type in Ruby.
+# @param msg A message parameter.
+# @param arg1 Optional String parameter. Defaults to 'param'.
+Puppet::DataTypes.create_type('RubyDataType') do
+  interface <<-PUPPET
+    attributes => {
+      msg => Numeric,
+    }
+    PUPPET
+end
+SOURCE
+    }
+
+    it 'should output a warning' do
+      expect{ subject }.to output(/\[warn\]: The @param tag for 'arg1' has no matching attribute near \(stdin\):4/).to_stdout_from_any_process
+    end
+
+    it 'should register a data type object with extra param tags removed' do
+      suppress_yard_logging
+
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
+      expect(object.name).to eq(:RubyDataType)
+      expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
+      expect(object.docstring.tags.size).to eq(2)
+      tags = object.docstring.tags(:api)
+      expect(tags.size).to eq(1)
+      expect(tags[0].text).to eq('public')
+
+      # Check that the param tags are removed
+      tags = object.docstring.tags(:param)
+      expect(tags.size).to eq(1)
+      expect(tags[0].name).to eq('msg')
+      expect(tags[0].text).to eq('A message parameter.')
+      expect(tags[0].types).to eq(['Numeric'])
+
+      # Check that only the actual attributes appear
+      expect(object.parameters.size).to eq(1)
+      expect(object.parameters[0]).to eq(['msg', nil])
+    end
+  end
+
+  describe 'parsing a valid data type definition' do
+    let(:source) { <<-SOURCE
+# An example Puppet Data Type in Ruby.
+#
+# @param msg A message parameter5.
+# @param arg1 Optional String parameter5. Defaults to 'param'.
+Puppet::DataTypes.create_type('RubyDataType') do
+  interface <<-PUPPET
+    attributes => {
+      msg   => Variant[Numeric, String[1,2]],
+      arg1  => { type => Optional[String[1]], value => "param" }
+    }
+    PUPPET
+end
+SOURCE
+    }
+
+    it 'should register a data type object' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
+      expect(object.name).to eq(:RubyDataType)
+      expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
+      expect(object.docstring.tags.size).to eq(3)
+      tags = object.docstring.tags(:api)
+      expect(tags.size).to eq(1)
+      expect(tags[0].text).to eq('public')
+
+      # Check that the param tags are removed
+      tags = object.docstring.tags(:param)
+      expect(tags.size).to eq(2)
+      expect(tags[0].name).to eq('msg')
+      expect(tags[0].text).to eq('A message parameter5.')
+      expect(tags[0].types).to eq(['Variant[Numeric, String[1,2]]'])
+      expect(tags[1].name).to eq('arg1')
+      expect(tags[1].text).to eq('Optional String parameter5. Defaults to \'param\'.')
+      expect(tags[1].types).to eq(['Optional[String[1]]'])
+
+      # Check for default values
+      expect(object.parameters.size).to eq(2)
+      expect(object.parameters[0]).to eq(['msg', nil])
+      expect(object.parameters[1]).to eq(['arg1', 'param'])
+    end
+  end
+
+  describe 'parsing a data type with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+# An example Puppet Data Type in Ruby.
+#
+# @summary A short summary.
+Puppet::DataTypes.create_type('RubyDataType') do
+  interface <<-PUPPET
+    attributes => { }
+    PUPPET
+end
+SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+# An example Puppet Data Type in Ruby.
+#
+# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
+Puppet::DataTypes.create_type('RubyDataType') do
+  interface <<-PUPPET
+    attributes => { }
+    PUPPET
+end
+SOURCE
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_data_type 'RubyDataType' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
+end