puppet-lint-param-docs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5b51934ae6df0b664bc963b8366a37b7e6ec3a4f
+  data.tar.gz: ad409a86b6778a747ea42cfa6ec1dc50172aba27
+SHA512:
+  metadata.gz: 07878556ff5e6f8a738115afa9b274561114624c29a85ccb48061f21a50531667fc7ab0e3dcc6c67167e30851a41a681dcc2344826d02d865de6d3b5ec4ce1c1
+  data.tar.gz: c931d62386aa49bb75c57862c321d953b5e64823ebac846b48a9c088d5551a5eecd136c8fcda6dcd3a8fc64f769af8f545ccc30e3453a7cad90794bc9d41d67b

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Tim Sharpe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,31 @@
+# puppet-lint parameter documentation check
+
+Adds a new puppet-lint check to verify all class parameters have been
+documented.
+
+Particularly useful with [kafo](https://github.com/theforeman/kafo), as its
+default behaviour is to throw an error when a parameter is undocumented.
+
+## Installation
+
+To use this plugin, add the following like to the Gemfile in your Puppet code
+base and run `bundle install`.
+
+```ruby
+gem 'puppet-lint-param-docs'
+```
+
+## Usage
+
+This plugin provides a new check to `puppet-lint`.
+
+### parameter_documentation
+
+**--fix support: No**
+
+This check will raise a warning for any class parameters that don't have an
+RDoc description.
+
+```
+WARNING: missing documentation for class parameter foo::bar
+```

data/lib/puppet-lint/plugins/check_parameter_documentation.rb

@@ -0,0 +1,41 @@
+PuppetLint.new_check(:parameter_documentation) do
+  def check
+    class_indexes.each do |klass|
+      next if klass[:param_tokens].nil?
+
+      doc_params = []
+      tokens[0..klass[:start]].reverse_each do |dtok|
+        next if [:CLASS, :NEWLINE, :WHITESPACE, :INDENT].include?(dtok.type)
+        if [:COMMENT, :MLCOMMENT, :SLASH_COMMENT].include?(dtok.type)
+          doc_params << $1 if dtok.value =~ /\A\s*\$([a-zA-Z0-9_]+)::/
+        else
+          break
+        end
+      end
+
+      params = []
+      e = klass[:param_tokens].each
+      e.each do |ptok|
+        params << ptok if ptok.type == :VARIABLE
+        # skip to the next parameter to avoid finding default values of variables
+        begin
+          while true
+            ptok = e.next
+            break if ptok == :COMMA
+          end
+        rescue StopIteration
+          break
+        end
+      end
+
+      params.each do |p|
+        next if doc_params.include? p.value
+        notify :warning, {
+          :message => "missing documentation for class parameter #{klass[:name_token].value}::#{p.value}",
+          :line    => p.line,
+          :column  => p.column,
+        }
+      end
+    end
+  end
+end

data/spec/puppet-lint/plugins/check_parameter_documentation_spec.rb

@@ -0,0 +1,86 @@
+require 'spec_helper'
+
+describe 'parameter_documentation' do
+  let(:msg) { 'missing documentation for class parameter example::foo' }
+
+  context 'class missing any documentation' do
+    let(:code) { 'class example($foo) { }' }
+
+    it 'should detect a single problem' do
+      expect(problems).to have(1).problem
+    end
+
+    it 'should create a warning' do
+      expect(problems).to contain_warning(msg).on_line(1).in_column(15)
+    end
+  end
+
+  context 'class with param defaults' do
+    let(:code) { 'class example($foo = $example::params::foo) { }' }
+
+    it 'should detect a single problem' do
+      expect(problems).to have(1).problem
+    end
+
+    it 'should create a warning' do
+      expect(problems).to contain_warning(msg).on_line(1).in_column(15)
+    end
+  end
+
+  context 'class missing documentation for a parameter' do
+    let(:code) do
+      <<-EOS
+      # Example class
+      #
+      # === Parameters:
+      #
+      # $bar:: example
+      #
+      class example($foo, $bar) { }
+      EOS
+    end
+
+    it 'should detect a single problem' do
+      expect(problems).to have(1).problem
+    end
+
+    it 'should create a warning' do
+      # column looks wrong, maybe the parser's out
+      expect(problems).to contain_warning(msg).on_line(7).in_column(21)
+    end
+  end
+
+  context 'class with all parameters documented' do
+    let(:code) do
+      <<-EOS
+      # Example class
+      #
+      # === Parameters:
+      #
+      # $foo:: example
+      #
+      class example($foo) { }
+      EOS
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'class without parameters' do
+    let(:code) { 'class example { }' }
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'class without parameters and a function call' do
+    let(:code) { 'class example { a($foo::bar) }' }
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'puppet-lint'
+
+PuppetLint::Plugins.load_spec_helper

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: puppet-lint-param-docs
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Dominic Cleal
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puppet-lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-collection_matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      A new check for puppet-lint that validates all class parameters are
+      documented.
+email: dcleal@redhat.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/puppet-lint/plugins/check_parameter_documentation.rb
+- spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/domcleal/puppet-lint-param-docs
+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: puppet-lint check to validate all parameters are documented
+test_files:
+- spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
+- spec/spec_helper.rb