puppet-strings 1.2.1 → 2.0.0

data/spec/spec_helper.rb

@@ -27,10 +27,13 @@ require 'puppet-strings/yard'
 PuppetStrings::Yard.setup!
 
 # Enable testing of Puppet functions if running against 4.1+
-TEST_PUPPET_FUNCTIONS = Gem::Dependency.new('', '>= 4.1.0').match?('', Puppet::PUPPETVERSION)
+TEST_PUPPET_FUNCTIONS = Puppet::Util::Package.versioncmp(Puppet.version, "4.1.0") >= 0
 
 # Enable testing of Puppet language functions declared with return type if running against 4.8+
-TEST_FUNCTION_RETURN_TYPE = Gem::Dependency.new('', '>= 4.8.0').match?('', Puppet::PUPPETVERSION)
+TEST_FUNCTION_RETURN_TYPE = Puppet::Util::Package.versioncmp(Puppet.version, "4.8.0") >= 0
+
+# Enable testing of Plans if Puppet version is greater than 5.0.0
+TEST_PUPPET_PLANS = Puppet::Util::Package.versioncmp(Puppet.version, "5.0.0") >= 0
 
 RSpec.configure do |config|
   config.mock_with :mocha

data/spec/unit/puppet-strings/json_spec.rb

@@ -19,6 +19,15 @@ class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {
 # @param param3 Third param.
 define dt(Integer $param1, $param2, String $param3 = hi) {
 }
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) if TEST_PUPPET_PLANS
+# A simple plan.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+plan plann(String $param1, $param2, Integer $param3 = 1) {
+}
 SOURCE
 
     # Only include Puppet functions for 4.1+
@@ -30,6 +39,31 @@ SOURCE
 # @return [Undef] Returns nothing.
 function func(Integer $param1, $param2, String $param3 = hi) {
 }
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :json)
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    },
+    "user": {
+      "description": "The user",
+      "type": "Optional[String[1]]"
+    },
+    "password": {
+      "description": "The password",
+      "type": "Optional[String[1]]"
+    },
+     "sql": {
+      "description": "Path to file you want backup to",
+      "type": "String[1]"
+    }
+  }
+}
 SOURCE
 
     YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
@@ -126,7 +160,7 @@ end
 
 Puppet::ResourceApi.register_type(
   name: 'apt_key',
-  desc: <<-EOS,
+  docs: <<-EOS,
 @summary Example resource type using the new API.
 @raise SomeError
 This type provides Puppet with the capabilities to manage GPG keys needed
@@ -166,7 +200,13 @@ path this type will autorequire that file.
 SOURCE
   end
 
-  let(:filename) { TEST_PUPPET_FUNCTIONS ? 'output.json' : 'output_without_puppet_function.json' }
+  let(:filename) do
+    if TEST_PUPPET_PLANS
+      'output_with_plan.json'
+    else
+      TEST_PUPPET_FUNCTIONS ? 'output.json' : 'output_without_puppet_function.json'
+    end
+  end
   let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/json/#{filename}") }
   let(:baseline) { File.read(baseline_path) }
 

data/spec/unit/puppet-strings/markdown_spec.rb

@@ -63,6 +63,39 @@ define klass::dt (
   Boolean $param4 = true
 ) {
 }
+SOURCE
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) if TEST_PUPPET_PLANS
+# A simple plan.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+plan plann(String $param1, $param2, Integer $param3 = 1) {
+}
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :json)
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    },
+    "user": {
+      "description": "The user",
+      "type": "Optional[String[1]]"
+    },
+    "password": {
+      "description": "The password",
+      "type": "Optional[String[1]]"
+    },
+     "sql": {
+      "description": "Path to file you want backup to",
+      "type": "String[1]"
+    }
+  }
+}
 SOURCE
 
     YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
@@ -187,7 +220,7 @@ end
 
 Puppet::ResourceApi.register_type(
   name: 'apt_key',
-  desc: <<-EOS,
+  docs: <<-EOS,
 @summary Example resource type using the new API.
 @raise SomeError
 This type provides Puppet with the capabilities to manage GPG keys needed
@@ -227,7 +260,13 @@ path this type will autorequire that file.
 SOURCE
   end
 
-  let(:filename) { 'output.md' }
+  let(:filename) do
+    if TEST_PUPPET_PLANS
+      'output_with_plan.md'
+    else
+      'output.md'
+    end
+  end
   let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/markdown/#{filename}") }
   let(:baseline) { File.read(baseline_path) }
 
@@ -239,10 +278,4 @@ SOURCE
       end
     end
   end
-
-  describe 'rendering markdown to stdout' do
-    it 'should output the expected markdown content' do
-      expect{ PuppetStrings::Markdown.render }.to output(baseline).to_stdout
-    end
-  end
 end

data/spec/unit/puppet-strings/yard/code_objects/task_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+require 'puppet-strings/yard/code_objects/task'
+require 'puppet-strings/yard/parsers/json/task_statement'
+
+describe PuppetStrings::Yard::CodeObjects::Task do
+  let(:source) { <<-SOURCE
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    },
+    "user": {
+      "description": "The user",
+      "type": "Optional[String[1]]"
+    },
+    "password": {
+      "description": "The password",
+      "type": "Optional[String[1]]"
+    },
+     "sql": {
+      "description": "Path to file you want backup to",
+      "type": "String[1]"
+    }
+  }
+}
+SOURCE
+  }
+  let(:json) { JSON.parse(source) }
+  let(:statement) { PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, source, "test.json") }
+  subject { PuppetStrings::Yard::CodeObjects::Task.new(statement) }
+
+  describe '#type' do
+    it 'returns the correct type' do
+      expect(subject.type).to eq(:puppet_task)
+    end
+  end
+
+  describe '#source' do
+    it 'returns the source' do
+      expect(subject.source).to eq(source)
+    end
+  end
+
+  describe '#to_hash' do
+    let(:expected) do
+      {
+        :name => "test",
+        :supports_noop => false,
+        :docstring => {
+          :text=>"Allows you to backup your database to local file.",
+          :tags=> [
+            {
+              :name=>"database",
+              :tag_name=>"param",
+              :text=>"Database to connect to",
+              :types=> ["Optional[String[1]]"]
+            },
+            {
+              :name=>"user",
+              :tag_name=>"param",
+              :text=>"The user",
+              :types=> ["Optional[String[1]]"]
+            },
+            {
+              :name=>"password",
+              :tag_name=>"param",
+              :text=>"The password",
+              :types=> ["Optional[String[1]]"]
+            },
+            {
+              :name=>"sql",
+              :tag_name=>"param",
+              :text=>"Path to file you want backup to",
+              :types=>["String[1]"]
+            }
+          ]
+        },
+        :file => "test.json",
+        :input_method => "stdin",
+        :line => 0,
+        :source => "{\n  \"description\": \"Allows you to backup your database to local file.\",\n  \"input_method\": \"stdin\",\n  \"parameters\": {\n    \"database\": {\n      \"description\": \"Database to connect to\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"user\": {\n      \"description\": \"The user\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"password\": {\n      \"description\": \"The password\",\n      \"type\": \"Optional[String[1]]\"\n    },\n     \"sql\": {\n      \"description\": \"Path to file you want backup to\",\n      \"type\": \"String[1]\"\n    }\n  }\n}\n"
+      }
+    end
+
+    it 'returns the correct hash' do
+      expect(subject.to_hash).to eq(expected)
+    end
+  end
+end

data/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb

@@ -0,0 +1,124 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Handlers::JSON::TaskHandler do
+  subject {
+    YARD::Parser::SourceParser.parse_string(source, :json)
+    YARD::Registry.all(:puppet_task)
+  }
+
+  describe 'parsing source without a task definition' do
+    let(:source) { 'notice hi' }
+
+    it 'no defined types should be in the registry' do
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing source with a syntax error' do
+    let(:source) { <<-SOURCE
+{
+  "input_method": "stdin",
+  "parameters":
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    }
+  }
+}
+SOURCE
+    }
+
+    it 'should log an error' do
+      expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\):/).to_stdout_from_any_process
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing a defined type with a missing docstring' do
+    let(:source) { <<-SOURCE
+{
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    },
+    "user": {
+      "description": "The user",
+      "type": "Optional[String[1]]"
+    },
+    "password": {
+      "description": "The password",
+      "type": "Optional[String[1]]"
+    },
+     "sql": {
+      "description": "Path to file you want backup to",
+      "type": "String[1]"
+    }
+  }
+}
+SOURCE
+    }
+
+    it 'should log a warning' do
+      expect{ subject }.to output(/\[warn\]: Missing a description for Puppet Task \(stdin\)/).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a defined type with a docstring' do
+    let(:source) { <<-SOURCE
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "description": "Database to connect to",
+      "type": "Optional[String[1]]"
+    },
+    "user": {
+      "description": "The user",
+      "type": "Optional[String[1]]"
+    },
+    "password": {
+      "description": "The password",
+      "type": "Optional[String[1]]"
+    },
+     "sql": {
+      "description": "Path to file you want backup to",
+      "type": "String[1]"
+    }
+  }
+}
+
+SOURCE
+    }
+
+    it 'should register a task object' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Task)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Tasks.instance)
+    end
+  end
+
+  describe 'parsing a Task with a missing parameter description' do
+    let(:source) { <<-SOURCE
+{
+  "description": "Allows you to backup your database to local file.",
+  "input_method": "stdin",
+  "parameters": {
+    "database": {
+      "type": "Optional[String[1]]"
+    }
+  }
+}
+SOURCE
+    }
+
+    it 'should output a warning' do
+      expect{ subject }.to output(/\[warn\]: Missing description for param 'database' in Puppet Task \(stdin\)/).to_stdout_from_any_process
+    end
+  end
+
+end

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

@@ -19,7 +19,7 @@ describe PuppetStrings::Yard::Handlers::Puppet::ClassHandler do
     let(:source) { 'class foo{' }
 
     it 'should log an error' do
-      expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of file/).to_stdout_from_any_process
+      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

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

@@ -19,7 +19,7 @@ describe PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler do
     let(:source) { 'define foo{' }
 
     it 'should log an error' do
-      expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of file/).to_stdout_from_any_process
+      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
@@ -35,6 +35,7 @@ describe PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler do
   describe 'parsing a defined type with a docstring' do
     let(:source) { <<-SOURCE
 # A simple foo defined type.
+# @param name The type name.
 # @param param1 First param.
 # @param param2 Second param.
 # @param param3 Third param.
@@ -45,6 +46,9 @@ define foo(Integer $param1, $param2, String $param3 = hi) {
 }
 SOURCE
     }
+    it 'does not output a warning for title/name' do
+      expect{ subject }.not_to output(/\[warn\].*(name|title).*/).to_stdout_from_any_process
+    end
 
     it 'should register a defined type object' do
       expect(subject.size).to eq(1)
@@ -55,18 +59,21 @@ SOURCE
       expect(object.statement).not_to eq(nil)
       expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'hi']])
       expect(object.docstring).to eq('A simple foo defined type.')
-      expect(object.docstring.tags.size).to eq(4)
+      expect(object.docstring.tags.size).to eq(5)
       tags = object.docstring.tags(:param)
-      expect(tags.size).to eq(3)
-      expect(tags[0].name).to eq('param1')
-      expect(tags[0].text).to eq('First param.')
-      expect(tags[0].types).to eq(['Integer'])
-      expect(tags[1].name).to eq('param2')
-      expect(tags[1].text).to eq('Second param.')
-      expect(tags[1].types).to eq(['Any'])
-      expect(tags[2].name).to eq('param3')
-      expect(tags[2].text).to eq('Third param.')
-      expect(tags[2].types).to eq(['String'])
+      expect(tags.size).to eq(4)
+      expect(tags[0].name).to eq('name')
+      expect(tags[0].text).to eq('The type name.')
+      expect(tags[0].types).to eq(nil)
+      expect(tags[1].name).to eq('param1')
+      expect(tags[1].text).to eq('First param.')
+      expect(tags[1].types).to eq(['Integer'])
+      expect(tags[2].name).to eq('param2')
+      expect(tags[2].text).to eq('Second param.')
+      expect(tags[2].types).to eq(['Any'])
+      expect(tags[3].name).to eq('param3')
+      expect(tags[3].text).to eq('Third param.')
+      expect(tags[3].types).to eq(['String'])
       tags = object.docstring.tags(:api)
       expect(tags.size).to eq(1)
       expect(tags[0].text).to eq('public')

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

@@ -267,6 +267,39 @@ SOURCE
       end
     end
 
+    describe 'parsing a function using only return_type' do
+      let(:source) { <<-SOURCE
+# An example 4.x function.
+Puppet::Functions.create_function(:foo) do
+  # @param param1 The first parameter.
+  # @param param2 The second parameter.
+  # @param param3 The third parameter.
+  dispatch :foo do
+    param          'Integer',       :param1
+    param          'Any',           :param2
+    optional_param 'Array[String]', :param3
+    return_type 'String'
+  end
+
+  def foo(param1, param2, param3 = nil)
+    "Bar"
+  end
+end
+SOURCE
+      }
+
+      it 'does not throw an error with no @return' do
+        expect { subject }.not_to raise_error NoMethodError
+      end
+
+      it 'contains a return data type' do
+        tags = subject.first.docstring.tags(:return)
+        expect(tags.size).to eq(1)
+        expect(tags[0].name).to be_nil
+        expect(tags[0].types).to eq(['String'])
+      end
+    end
+
     describe 'parsing a function with various dispatch parameters.' do
       let(:source) { <<-SOURCE
 # An example 4.x function.