puppet-strings 0.4.0 → 0.99.0

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

@@ -0,0 +1,90 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Handlers::Ruby::ProviderHandler do
+  subject {
+    YARD::Parser::SourceParser.parse_string(source, :ruby)
+    YARD::Registry.all(:puppet_provider)
+  }
+
+  describe 'parsing source without a provider definition' do
+    let(:source) { 'puts "hi"' }
+
+    it 'no providers should be in the registry' do
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing a provider with a missing description' do
+    let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+end
+SOURCE
+    }
+
+    it 'should log a warning' do
+      expect{ subject }.to output(/\[warn\]: Missing a description for Puppet provider 'linux' \(resource type 'custom'\) at \(stdin\):1\./).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a provider with an invalid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+  @doc = 123
+end
+SOURCE
+    }
+
+    it 'should log an error' do
+      expect { subject }.to output(/Failed to parse docstring/).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a provider with a valid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+  @doc = 'An example provider on Linux.'
+end
+SOURCE
+    }
+
+    it 'should correctly detect the docstring' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.docstring).to eq('An example provider on Linux.')
+    end
+  end
+
+  describe 'parsing a provider definition' do
+    let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+  desc 'An example provider on Linux.'
+  confine kernel: 'Linux'
+  confine osfamily: 'RedHat'
+  defaultfor kernel: 'Linux'
+  has_feature :implements_some_feature
+  has_feature :some_other_feature
+  commands foo: /usr/bin/foo
+end
+SOURCE
+    }
+
+    it 'should register a provider object' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Provider)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Providers.instance('custom'))
+      expect(object.name).to eq(:linux)
+      expect(object.type_name).to eq('custom')
+      expect(object.docstring).to eq('An example provider on Linux.')
+      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.confines).to eq({ 'kernel' => 'Linux', 'osfamily' => 'RedHat'})
+      expect(object.defaults).to eq({ 'kernel' => 'Linux'})
+      expect(object.features).to eq(['implements_some_feature', 'some_other_feature'])
+      expect(object.commands).to eq({'foo' => '/usr/bin/foo'})
+    end
+  end
+end

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

@@ -0,0 +1,214 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Handlers::Ruby::TypeHandler do
+  subject {
+    YARD::Parser::SourceParser.parse_string(source, :ruby)
+    YARD::Registry.all(:puppet_type)
+  }
+
+  describe 'parsing source without a type definition' do
+    let(:source) { 'puts "hi"' }
+
+    it 'no types should be in the registry' do
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing a type with a missing description' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+end
+SOURCE
+    }
+
+    it 'should log a warning' do
+      expect{ subject }.to output(/\[warn\]: Missing a description for Puppet resource type 'database' at \(stdin\):1\./).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a type with an invalid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  @doc = 123
+end
+SOURCE
+    }
+
+    it 'should log an error' do
+      expect { subject }.to output(/Failed to parse docstring/).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a type with a valid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  @doc = 'An example database server resource type.'
+end
+SOURCE
+    }
+
+    it 'should correctly detect the docstring' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.docstring).to eq('An example database server resource type.')
+    end
+  end
+
+  describe 'parsing a type definition' do
+    let(:source) { <<-SOURCE
+# @!puppet.type.param [value1, value2] dynamic_param Documentation for a dynamic parameter.
+# @!puppet.type.property [foo, bar] dynamic_prop Documentation for a dynamic property.
+Puppet::Type.newtype(:database) do
+  desc 'An example database server resource type.'
+  feature :encryption, 'The provider supports encryption.', methods: [:encrypt]
+  ensurable do
+    desc 'What state the database should be in.'
+    defaultvalues
+    aliasvalue(:up, :present)
+    aliasvalue(:down, :absent)
+    defaultto :up
+  end
+
+  newparam(:address) do
+    isnamevar
+    desc 'The database server name.'
+  end
+
+  newparam(:encryption_key, required_features: :encryption) do
+    desc 'The encryption key to use.'
+  end
+
+  newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do
+    desc 'Whether or not to encrypt the database.'
+    defaultto false
+  end
+
+  newparam(:backup) do
+      desc 'How often to backup the database.'
+      defaultto :never
+      newvalues(:daily, :monthly, :never)
+  end
+
+  newproperty(:file) do
+    desc 'The database file to use.'
+  end
+
+  newproperty(:log_level) do
+    desc 'The log level to use.'
+    newvalue(:debug)
+    newvalue(:warn)
+    newvalue(:error)
+    defaultto 'warn'
+  end
+end
+SOURCE
+    }
+
+    it 'should register a type object' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Type)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Types.instance)
+      expect(object.name).to eq(:database)
+      expect(object.docstring).to eq('An example database server resource type.')
+      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.properties.size).to eq(4)
+      expect(object.properties[0].name).to eq('dynamic_prop')
+      expect(object.properties[0].docstring).to eq('Documentation for a dynamic property.')
+      expect(object.properties[0].isnamevar).to eq(false)
+      expect(object.properties[0].values).to eq(%w(foo bar))
+      expect(object.properties[1].name).to eq('ensure')
+      expect(object.properties[1].docstring).to eq('What state the database should be in.')
+      expect(object.properties[1].isnamevar).to eq(false)
+      expect(object.properties[1].default).to eq('up')
+      expect(object.properties[1].values).to eq(%w(present absent up down))
+      expect(object.properties[1].aliases).to eq({ 'down' => 'absent', 'up' => 'present' })
+      expect(object.properties[2].name).to eq('file')
+      expect(object.properties[2].docstring).to eq('The database file to use.')
+      expect(object.properties[2].isnamevar).to eq(false)
+      expect(object.properties[2].default).to be_nil
+      expect(object.properties[2].values).to eq([])
+      expect(object.properties[2].aliases).to eq({})
+      expect(object.properties[3].name).to eq('log_level')
+      expect(object.properties[3].docstring).to eq('The log level to use.')
+      expect(object.properties[3].isnamevar).to eq(false)
+      expect(object.properties[3].default).to eq('warn')
+      expect(object.properties[3].values).to eq(%w(debug warn error))
+      expect(object.properties[3].aliases).to eq({})
+      expect(object.parameters.size).to eq(5)
+      expect(object.parameters[0].name).to eq('dynamic_param')
+      expect(object.parameters[0].docstring).to eq('Documentation for a dynamic parameter.')
+      expect(object.parameters[0].isnamevar).to eq(false)
+      expect(object.parameters[0].values).to eq(%w(value1 value2))
+      expect(object.parameters[1].name).to eq('address')
+      expect(object.parameters[1].docstring).to eq('The database server name.')
+      expect(object.parameters[1].isnamevar).to eq(true)
+      expect(object.parameters[1].default).to be_nil
+      expect(object.parameters[1].values).to eq([])
+      expect(object.parameters[1].aliases).to eq({})
+      expect(object.parameters[2].name).to eq('encryption_key')
+      expect(object.parameters[2].docstring).to eq('The encryption key to use.')
+      expect(object.parameters[2].isnamevar).to eq(false)
+      expect(object.parameters[2].default).to be_nil
+      expect(object.parameters[2].values).to eq([])
+      expect(object.parameters[2].aliases).to eq({})
+      expect(object.parameters[3].name).to eq('encrypt')
+      expect(object.parameters[3].docstring).to eq('Whether or not to encrypt the database.')
+      expect(object.parameters[3].isnamevar).to eq(false)
+      expect(object.parameters[3].default).to eq('false')
+      expect(object.parameters[3].values).to eq(%w(true false yes no))
+      expect(object.parameters[3].aliases).to eq({})
+      expect(object.parameters[4].name).to eq('backup')
+      expect(object.parameters[4].docstring).to eq('How often to backup the database.')
+      expect(object.parameters[4].isnamevar).to eq(false)
+      expect(object.parameters[4].default).to eq('never')
+      expect(object.parameters[4].values).to eq(%w(daily monthly never))
+      expect(object.features.size).to eq(1)
+      expect(object.features[0].name).to eq('encryption')
+      expect(object.features[0].docstring).to eq('The provider supports encryption.')
+    end
+  end
+
+  describe 'parsing an ensurable type with default ensure values' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  desc 'An example database server resource type.'
+  ensurable
+end
+SOURCE
+    }
+
+    it 'should register a type object with default ensure values' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.properties[0].name).to eq('ensure')
+      expect(object.properties[0].docstring).to eq('The basic property that the resource should be in.')
+      expect(object.properties[0].default).to eq('present')
+      expect(object.properties[0].values).to eq(%w(present absent))
+    end
+  end
+
+  describe 'parsing a type with a parameter with the name of "name"' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  desc 'An example database server resource type.'
+  newparam(:name) do
+    desc 'The database server name.'
+  end
+end
+SOURCE
+    }
+
+    it 'should register a type object with the "name" parameter as the namevar' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.parameters.size).to eq(1)
+      expect(object.parameters[0].name).to eq('name')
+      expect(object.parameters[0].isnamevar).to eq(true)
+    end
+  end
+end

data/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb

@@ -0,0 +1,171 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Parsers::Puppet::Parser do
+  subject { PuppetStrings::Yard::Parsers::Puppet::Parser.new(source, file) }
+  let(:file) { 'test.pp' }
+
+  describe 'initialization of the parser' do
+    let(:source) { 'notice hi' }
+
+    it 'should store the original source' do
+      expect(subject.source).to eq(source)
+    end
+
+    it 'should store the original file name' do
+      expect(subject.file).to eq(file)
+    end
+
+    it 'should have no relevant statements' do
+      subject.parse
+      expect(subject.enumerator.empty?).to be_truthy
+    end
+  end
+
+  describe 'parsing invalid Puppet source code' do
+    let(:source) { <<SOURCE
+class foo {
+SOURCE
+    }
+
+    it 'should raise an exception' do
+      expect{ subject.parse }.to output(/\[error\]: Failed to parse test.pp: Syntax error at end of file/).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing class definitions' do
+    let(:source) { <<SOURCE
+notice hello
+# A simple foo class.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {
+  file { '/tmp/foo':
+    ensure => present
+  }
+}
+SOURCE
+    }
+
+    it 'should only return the class statement' do
+      subject.parse
+      expect(subject.enumerator.size).to eq(1)
+      statement = subject.enumerator.first
+      expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::ClassStatement)
+      expect(statement.source).to eq("class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n  file { '/tmp/foo':\n    ensure => present\n  }\n}")
+      expect(statement.file).to eq(file)
+      expect(statement.line).to eq(6)
+      expect(statement.docstring).to eq('A simple foo class.')
+      expect(statement.name).to eq('foo')
+      expect(statement.parent_class).to eq('foo::bar')
+      expect(statement.parameters.size).to eq(3)
+      expect(statement.parameters[0].name).to eq('param1')
+      expect(statement.parameters[0].type).to eq('Integer')
+      expect(statement.parameters[0].value).to be_nil
+      expect(statement.parameters[1].name).to eq('param2')
+      expect(statement.parameters[1].type).to be_nil
+      expect(statement.parameters[1].value).to be_nil
+      expect(statement.parameters[2].name).to eq('param3')
+      expect(statement.parameters[2].type).to eq('String')
+      expect(statement.parameters[2].value).to eq('hi')
+    end
+  end
+
+  describe 'parsing nested class definitions' do
+    let(:source) { <<SOURCE
+class foo {
+  class bar {
+  }
+}
+SOURCE
+    }
+
+    it 'should parse both class statements' do
+      subject.parse
+      expect(subject.enumerator.size).to eq(2)
+      statement = subject.enumerator[0]
+      expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::ClassStatement)
+      expect(statement.name).to eq('foo::bar')
+      expect(statement.parameters.size).to eq(0)
+      statement = subject.enumerator[1]
+      expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::ClassStatement)
+      expect(statement.name).to eq('foo')
+      expect(statement.parameters.size).to eq(0)
+    end
+  end
+
+  describe 'parsing defined types' do
+    let(:source) { <<SOURCE
+notice hello
+# A simple foo defined type.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+define foo(Integer $param1, $param2, String $param3 = hi) {
+  file { '/tmp/foo':
+    ensure => present
+  }
+}
+SOURCE
+    }
+
+    it 'should parse the defined type statement' do
+      subject.parse
+      expect(subject.enumerator.size).to eq(1)
+      statement = subject.enumerator.first
+      expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::DefinedTypeStatement)
+      expect(statement.name).to eq('foo')
+      expect(statement.source).to eq("define foo(Integer $param1, $param2, String $param3 = hi) {\n  file { '/tmp/foo':\n    ensure => present\n  }\n}")
+      expect(statement.file).to eq(file)
+      expect(statement.line).to eq(6)
+      expect(statement.docstring).to eq('A simple foo defined type.')
+      expect(statement.parameters.size).to eq(3)
+      expect(statement.parameters[0].name).to eq('param1')
+      expect(statement.parameters[0].type).to eq('Integer')
+      expect(statement.parameters[0].value).to be_nil
+      expect(statement.parameters[1].name).to eq('param2')
+      expect(statement.parameters[1].type).to be_nil
+      expect(statement.parameters[1].value).to be_nil
+      expect(statement.parameters[2].name).to eq('param3')
+      expect(statement.parameters[2].type).to eq('String')
+      expect(statement.parameters[2].value).to eq('hi')
+    end
+  end
+
+  describe 'parsing puppet functions', if: TEST_PUPPET_FUNCTIONS do
+    let(:source) { <<SOURCE
+notice hello
+# A simple foo function.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+function foo(Integer $param1, $param2, String $param3 = hi) {
+  notice world
+}
+SOURCE
+    }
+
+    it 'should parse the puppet function statement' do
+      subject.parse
+      expect(subject.enumerator.size).to eq(1)
+      statement = subject.enumerator.first
+      expect(statement).to be_a(PuppetStrings::Yard::Parsers::Puppet::FunctionStatement)
+      expect(statement.name).to eq('foo')
+      expect(statement.source).to eq("function foo(Integer $param1, $param2, String $param3 = hi) {\n  notice world\n}")
+      expect(statement.file).to eq(file)
+      expect(statement.line).to eq(6)
+      expect(statement.docstring).to eq('A simple foo function.')
+      expect(statement.parameters.size).to eq(3)
+      expect(statement.parameters[0].name).to eq('param1')
+      expect(statement.parameters[0].type).to eq('Integer')
+      expect(statement.parameters[0].value).to be_nil
+      expect(statement.parameters[1].name).to eq('param2')
+      expect(statement.parameters[1].type).to be_nil
+      expect(statement.parameters[1].value).to be_nil
+      expect(statement.parameters[2].name).to eq('param3')
+      expect(statement.parameters[2].type).to eq('String')
+      expect(statement.parameters[2].value).to eq('hi')
+    end
+  end
+end