puppet-lint-optional_default-check 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0859f8a9068f1cb24f9add5622e123bdce3bd32bdf686c2445442806add79dad'
+  data.tar.gz: 212ef6664c4ad98b77160e490d72b69e2404c8c32cff3de0a4265e380579c1fe
+SHA512:
+  metadata.gz: 751ab59ba4cd193955767a5b6bc8090f871ef204a2c7ad52dc8b286936d443c775800b677723d85f4b0619bb164a5da58782dc0ee8c332090f589f6ac6b5c1c4
+  data.tar.gz: f24cb90b805fbc43e91de287a22ba7beefe578d5c0c82947526af5e56bf36cd286d94c3987d22d8886c7270bc04d6ff13b53c3c630abc86964c770620b1b9dd9

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Alexander Fisher
+
+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,68 @@
+puppet-lint-optional\_default-check
+===================================
+
+A puppet-lint plugin to check that `Optional` parameters don't default to something other than `undef`.
+
+## Installing
+
+### From the command line
+
+```shell
+$ gem install puppet-lint-optional_default-check
+```
+
+### In a Gemfile
+
+```ruby
+gem 'puppet-lint-optional_default-check', :require => false
+```
+
+## Checks
+
+### `Optional` parameter defaults to something other than `undef`
+
+An `Optional` parameter in Puppet is one where `undef` is an allowed value.
+
+It is normally a mistake to set the default of an `Optional` parameter to something other than `undef`.
+This is because it's not possible to 'pass' `undef` as the value to use for a parameter when declaring a class or defined type.
+When you try to set a parameter to `undef`, Puppet actually uses the class's default value for that parameter, not `undef` itself.
+
+(The caveat is that it is possible to use hiera to override a non `undef` default back to `undef`, but in practice, doing this is quite rare.)
+
+A **defined type** with an mandatory (no default), `Optional` parameter will raise a warning.
+
+The plugin will not raise a warning if a **class** `Optional` parameter doesn't have a default.
+Mandatory parameters can have defaults set in hiera, and several modules *do* use `~` for this.
+
+#### What you have done
+
+```puppet
+class foo (
+  Optional[Integer] $port = 8080,
+){
+}
+```
+
+#### What you should have done
+
+```puppet
+class foo (
+  Integer $port = 8080,
+){
+}
+```
+
+or
+
+```puppet
+class foo (
+  Optional[Integer] $port = undef,
+){
+}
+```
+
+# Copyright
+
+Copyright 2021 Alexander Fisher
+
+Licensed under the MIT License.

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+PuppetLint.new_check(:optional_default) do
+  def check
+    class_indexes.concat(defined_type_indexes).each do |idx|
+      params = extract_params(idx)
+      params.each do |param|
+        default_value = extract_default_value_tokens(param)
+        type = extract_type_tokens(param)
+
+        if type.size.positive? &&                                  # The parameter has a type
+           type[0].type == :TYPE && type[0].value == 'Optional' && # That type is Optional
+           default_value.size.positive? &&                         # There is a default set
+           (default_value.map(&:type) & %i[DOT LPAREN]).none? &&   # That default doesn't contain a call to a function
+           default_value[0].type != :UNDEF &&                      # It isn't undef
+           default_value[0].type != :VARIABLE                      # and it isn't a variable
+
+          notify(
+            :warning,
+            message: 'Optional parameter defaults to something other than undef',
+            line: param.line,
+            column: param.column
+          )
+        end
+
+        # If a defined type has an Optional parameter without a default, this is definately an issue as, unlike classes,
+        # the default can't actually be coming from hiera.
+        next unless idx[:type] == :DEFINE &&
+                    type.size.positive? &&
+                    type[0].type == :TYPE && type[0].value == 'Optional' &&
+                    default_value.size.zero?
+
+        notify(
+          :warning,
+          message: 'Optional defined type parameter doesn\'t have a default',
+          line: param.line,
+          column: param.column
+        )
+      end
+    end
+  end
+
+  private
+
+  # Returns an array of parameter tokens
+  def extract_params(idx)
+    params = []
+    return params if idx[:param_tokens].nil?
+
+    e = idx[:param_tokens].each
+    begin
+      while (ptok = e.next)
+        next unless ptok.type == :VARIABLE
+
+        params << ptok
+        nesting = 0
+        # skip to the next parameter to avoid finding default values of variables
+        loop do
+          ptok = e.next
+          case ptok.type
+          when :LPAREN, :LBRACK
+            nesting += 1
+          when :RPAREN, :RBRACK
+            nesting -= 1
+          when :COMMA
+            break unless nesting.positive?
+          end
+        end
+      end
+    rescue StopIteration; end # rubocop:disable Lint/SuppressedException
+    params
+  end
+
+  # Returns array of tokens that cover the value that the parameter token has as its default
+  # Search forward to find value assigned to this parameter
+  # We want to find the thing after `=` and before `,`
+  def extract_default_value_tokens(ptok)
+    value_tokens = []
+    token = ptok.next_code_token
+    nesting = 0
+    while token
+      case token.type
+      when :LPAREN, :LBRACK
+        nesting += 1
+      when :RBRACK
+        nesting -= 1
+      when :RPAREN
+        nesting -= 1
+        if nesting.negative?
+          # This is the RPAREN at the end of the parameters. There wasn't a COMMA
+          last_token = token.prev_code_token
+          break
+        end
+      when :EQUALS
+        first_token = token.next_code_token
+      when :COMMA
+        unless nesting.positive?
+          last_token = token.prev_code_token
+          break
+        end
+      end
+      token = token.next_token
+    end
+    value_tokens = tokens[tokens.find_index(first_token)..tokens.find_index(last_token)] if first_token && last_token
+    value_tokens
+  end
+
+  # Returns an array of tokens that cover the data type of the parameter ptok
+  # Search backwards until we either bump into a comma (whilst not nested), or reach the opening LPAREN
+  def extract_type_tokens(ptok)
+    type_tokens = []
+    token = ptok.prev_code_token
+    nesting = 0
+    while token
+      case token.type
+      when :LBRACK
+        nesting += 1
+      when :LPAREN
+        nesting += 1
+        if nesting.positive?
+          # This is the LPAREN at the start of the parameter list
+          first_token = token.next_code_token
+          last_token = ptok.prev_code_token
+          break
+        end
+      when :RBRACK, :RPAREN
+        nesting -= 1
+      when :COMMA
+        if nesting.zero?
+          first_token = token.next_code_token
+          last_token = ptok.prev_code_token
+          break
+        end
+      end
+
+      token = token.prev_code_token
+    end
+    type_tokens = tokens[tokens.find_index(first_token)..tokens.find_index(last_token)] if first_token && last_token
+    type_tokens
+  end
+end

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

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'optional_default' do
+  let(:msg) { 'Optional parameter defaults to something other than undef' }
+
+  %w[define class].each do |type|
+    context "#{type} with Optional parameter defaulting to string on single line" do
+      let(:code) { "#{type} test(Optional $foo = 'test') { }" }
+
+      it 'detects a single problem' do
+        expect(problems).to have(1).problem
+      end
+
+      col = (type == 'class' ? 21 : 22)
+      it 'creates a warning' do
+        expect(problems).to contain_warning(msg).on_line(1).in_column(col)
+      end
+
+      context 'with trailing comma' do
+        let(:code) { "#{type} test(Optional $foo = 'test',) { }" }
+
+        it 'detects a single problem' do
+          expect(problems).to have(1).problem
+        end
+
+        col = (type == 'class' ? 21 : 22)
+        it 'creates a warning' do
+          expect(problems).to contain_warning(msg).on_line(1).in_column(col)
+        end
+      end
+    end
+
+    context "#{type} with Optional parameter defaulting to string on multiple lines" do
+      let(:code) do
+        <<~CODE
+          #{type} test(
+            Optional $foo = 'test'
+          ){
+          }
+        CODE
+      end
+
+      it 'detects a single problem' do
+        expect(problems).to have(1).problem
+      end
+
+      it 'creates a warning' do
+        expect(problems).to contain_warning(msg).on_line(2).in_column(12)
+      end
+    end
+
+    context "#{type} with Optional parameter defaulting to undef on single line" do
+      let(:code) { "#{type} test(Optional $foo = undef) { }" }
+
+      it 'detects no problems' do
+        expect(problems).to have(0).problem
+      end
+
+      context 'with trailing comma' do
+        let(:code) { "#{type} test(Optional $foo = undef) { }" }
+
+        it 'detects no problems' do
+          expect(problems).to have(0).problem
+        end
+      end
+    end
+
+    context "#{type} with Optional[String[1]] parameter defaulting to string on single line" do
+      let(:code) { "#{type} test(Optional[String[1]] $foo = 'test') { }" }
+
+      it 'detects a single problem' do
+        expect(problems).to have(1).problem
+      end
+
+      col = (type == 'class' ? 32 : 33)
+      it 'creates a warning' do
+        expect(problems).to contain_warning(msg).on_line(1).in_column(col)
+      end
+    end
+
+    context "#{type} with a mandatory parameter followed by an Optional[Hash] parameter with a non undef default" do
+      let(:code) do
+        <<~CODE
+          #{type} test(
+            String         $foo,
+            Optional[Hash] $bar = {
+              'a' => 'b',
+              'c' => 'd'
+            },
+          ){
+          }
+        CODE
+      end
+
+      it 'detects a single problem' do
+        expect(problems).to have(1).problem
+      end
+
+      it 'creates a warning' do
+        expect(problems).to contain_warning(msg).on_line(3).in_column(18)
+      end
+    end
+
+    context "#{type} with a mandatory parameter followed by an Optional[Hash] parameter that default to the result of a function" do
+      let(:code) do
+        <<~CODE
+          #{type} test(
+            String         $foo,
+            Optional[Hash] $bar = some::func('foo'),
+          ){
+          }
+        CODE
+      end
+
+      it 'detects no problems' do
+        expect(problems).to have(0).problem
+      end
+    end
+
+    context "#{type} with a mandatory parameter followed by an Optional[Hash] parameter that default to the result of a function called with dot notation" do
+      let(:code) do
+        <<~CODE
+          #{type} test(
+            String         $foo,
+            Optional[Hash] $bar = 'foo'.func,
+          ){
+          }
+        CODE
+      end
+
+      it 'detects no problems' do
+        expect(problems).to have(0).problem
+      end
+    end
+
+    context "Complex #{type} with multiple issues and comments" do
+      let(:code) do
+        <<~CODE
+          #{type} test (
+            $a, # No type or default
+            String                  $b   = 'somestring',
+            Optional[String[1]]     $c   = 'foobar', # This should generate a warning
+            Optional[Enum[
+              'a',
+              'b',
+              ]
+            ]                       $fuz = 'a', # As should this
+            Optional                $d   = $foo::param::c,
+            Optional[Array[String]] $e   = [] # Another warning here (also note no trailing comma!)
+          ){
+            notice('test')
+          }
+        CODE
+      end
+
+      it 'detects 3 problems' do
+        expect(problems).to have(3).problem
+      end
+
+      it { expect(problems).to contain_warning(msg).on_line(4).in_column(27) }
+      it { expect(problems).to contain_warning(msg).on_line(9).in_column(27) }
+      it { expect(problems).to contain_warning(msg).on_line(11).in_column(27) }
+    end
+
+    context "#{type} with Optional parameter with array operation" do
+      let(:code) do
+        <<~CODE
+          #{type} test(
+            Optional[Array] $hostnames = ['foo.example.com', 'bar.example.com'] - $facts['fqdn'],
+          ){
+          }
+        CODE
+      end
+
+      it 'detects a single problem' do
+        expect(problems).to have(1).problem
+      end
+
+      it { expect(problems).to contain_warning(msg).on_line(2).in_column(19) }
+    end
+  end
+  context 'with class with Optional parameter with no apparent default' do
+    let(:code) { 'class test(Optional $foo) { }' }
+
+    # There's a good chance the parameter default is actually in hiera as `~`.
+    it 'detects no problems' do
+      expect(problems).to have(0).problem
+    end
+  end
+
+  context 'with defined type with Optional parameter with no default' do
+    let(:code) { 'define test(Optional $foo) { }' }
+
+    it 'detects a single problem' do
+      expect(problems).to have(1).problem
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'puppet-lint'
+
+PuppetLint::Plugins.load_spec_helper

metadata

@@ -0,0 +1,196 @@
+--- !ruby/object:Gem::Specification
+name: puppet-lint-optional_default-check
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alexander Fisher
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-04-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puppet-lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.11.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.2
+description: "    A puppet-lint plugin to check that Optional class/defined type parameters
+  don't default to anything other than `undef`.\n"
+email: alex@linfratech.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/puppet-lint/plugins/check_optional_default.rb
+- spec/puppet-lint/plugins/check_optional_default_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/alexjfisher/puppet-lint-optional_default-check
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: A puppet-lint plugin to check Optional parameters default to `undef`
+test_files:
+- spec/puppet-lint/plugins/check_optional_default_spec.rb
+- spec/spec_helper.rb