puppet-lint-param_comment-check 0.1.1 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4b8ad42633483b29d912da99b108a9bcd277b7c6b1d21ebaeeedb4aa9634e12
-  data.tar.gz: 768790358859c7375df58da9fbbd2b932a94f606647d9f13e513fc119cbd29e3
+  metadata.gz: 760c2ecbb41952244ece53d7fddafcc91f322300b512a65dfc4d5ab7b5622636
+  data.tar.gz: 187d476c9e3418c03935d00ddf84fd9c9618cd8ac4a14a391e0046f68f92221f
 SHA512:
-  metadata.gz: eee0e509c76c55d1cc9b97ed444bdadbf1caa8a970e03e339618083d1e5019f0a18e70d627b4f691f1aa255a78a8240972db6a68d38b2a41c9f9993f3a3714e4
-  data.tar.gz: 6af8ad1b81d6d0b9f2e4d8cbf9cee33507e6813f025691187edab23adc9f0510372e4cd88362f614066904c32243bc3bc0a550fddfe238f9e5c250bfc897f592
+  metadata.gz: 8396f55b48c7cd1e82f66855eb950c2c1fd4e908423625a262e6ba11496d2cd3b9c90931c66deb97efba5d706502416e71ef4ae47f7d459b5c0fcf24d7b86ef4
+  data.tar.gz: '08c1d478a70c0a204805844aa0ad1724ee7a371852c3f7059596204d3c62f89d9044fa2cf44b26b6df2731331f371765b3cdf86de148ecf5cab88216336dea93'

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

@@ -35,7 +35,7 @@ def analyze_param_token(token, current_param)
   case token.type
   when :VARIABLE
     current_param[:name] = token.value
-  when :CLASSREF
+  when :CLASSREF, :TYPE
     current_param[:type] = token.value
   when :EQUALS
     current_param[:has_default] = true
@@ -47,17 +47,22 @@ end
 # Analyze the parameters of a class or a defined type
 #
 # @param param_tokens The parameter tokens to analyze
-def analyze_params(param_tokens)
+def analyze_params(param_tokens) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
   params = []
   current_param = EMPTY_PARAM.dup
-  param_tokens.reject { |token| %i[WHITESPACE NEWLINE].include? token.type }.each do |token|
+  brackets = 0
+  param_tokens.reject { |token| %i[WHITESPACE NEWLINE INDENT].include? token.type }.each do |token|
+    brackets += 1 if %i[LBRACK LBRACE].include? token.type
+    brackets -= 1 if %i[RBRACK RBRACE].include? token.type
+    next unless brackets.zero?
+
     current_param = analyze_param_token(token, current_param) unless token.type == :COMMA
     if token.type == :COMMA
       params.append(current_param)
       current_param = EMPTY_PARAM.dup
     end
   end
-  params.append(current_param) unless current_param == EMPTY_PARAM
+  params.append(current_param) unless current_param[:name] == ''
   params
 end
 
@@ -100,7 +105,7 @@ PuppetLint.new_check(:param_comment) do # rubocop:disable Metrics/BlockLength
       next unless comment.value.match?(/@param/) || comment.value.match?(/@option/)
       next if comment.value.strip.match?(REGEXP_PARAM_HEADER) || comment.value.strip.match?(REGEXP_OPTION_HEADER)
 
-      return warn('Invalid param or hash option header', comment.line, comment.column)
+      return warn("Invalid param or hash option header: #{comment.value.strip}", comment.line, comment.column)
     end
     true
   end
@@ -130,9 +135,9 @@ PuppetLint.new_check(:param_comment) do # rubocop:disable Metrics/BlockLength
   def check_comment_order(params)
     param_comments = @comment_engine.params
     param_comments.each_with_index do |param, index|
-      return false unless param[:name] == params[index][:name]
+      return param[:line] unless param[:name] == params[index][:name]
     end
-    true
+    -1
   end
 
   # Check class or defined type indexes
@@ -142,7 +147,9 @@ PuppetLint.new_check(:param_comment) do # rubocop:disable Metrics/BlockLength
       params = analyze_params(index[:param_tokens])
       return false unless check_comments(comments)
       return false unless check_parameters_count(params)
-      return warn('Parameters sorted wrong') unless check_comment_order(params)
+
+      comment_order_line = check_comment_order(params)
+      return warn('Parameters sorted wrong', comment_order_line) unless comment_order_line == -1
     end
     true
   end

data/lib/puppet-lint-param_comment-check/param_comments.rb

@@ -4,28 +4,30 @@
 EMPTY_PARAM_COMMENT = {
   name: '',
   description: '',
-  options: []
+  options: [],
+  line: -1
 }.freeze
 
 # The empty data of a hash option
 EMPTY_OPTION_COMMENT = {
   name: '',
   type: '',
-  description: ''
+  description: '',
+  line: -1
 }.freeze
 
 # A regular expression describing a parameter header
 REGEXP_PARAM_HEADER = /^@param (?<name>[^ ]+)$/.freeze
 
 # A regular expression describing a hash option header
-REGEXP_OPTION_HEADER = /^@option (?<hash_name>[^ ]+) \[(?<type>[^\]]+)\] :(?<name>[^ ]+)$/.freeze
+REGEXP_OPTION_HEADER = /^@option (?<hash_name>[^ ]+) \[(?<type>.+)\] :(?<name>[^ ]+)$/.freeze
 
 # Comment received in an invalid state
 class InvalidCommentForState < StandardError
   def initialize(comment, state)
     @comment = comment
     @state = state
-    super "Invalid state #{@state} for comment #{@comment.value.strip}"
+    super "Can not process the comment '#{@comment.value.strip}' in the state #{@state}"
   end
 
   attr_reader :comment
@@ -66,7 +68,7 @@ class ParamComments
   # Walk through every comment and transition the workflow fsm accordingly
   #
   # @param comments A list of Comment tokens appearing before the class/defined type header
-  def process(comments) # rubocop:disable Metrics/MethodLength
+  def process(comments) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
     @current_comment = PuppetLint::Lexer::Token.new(:COMMENT, '', 1, 1)
     comments.each do |comment|
       @current_comment = comment
@@ -87,7 +89,7 @@ class ParamComments
   end
 
   # Called before the got_header event. Interpret the parameter header comment
-  def got_header_trigger(_, comment)
+  def got_header_trigger(_, comment) # rubocop:disable Metrics/AbcSize
     @params_have_started = true
     @current_param[:options].append(@current_option) if @in_option && !@current_option.nil?
     @params.append(@current_param) unless @current_param.nil?
@@ -96,6 +98,7 @@ class ParamComments
     @in_option = false
     comment.value.strip.match(REGEXP_PARAM_HEADER) do |match|
       @current_param[:name] = match.named_captures['name'].strip
+      @current_param[:line] = comment.line
     end
   end
 
@@ -120,6 +123,7 @@ class ParamComments
 
       @current_option[:name] = match.named_captures['name']
       @current_option[:type] = match.named_captures['type']
+      @current_param[:line] = comment.line
     end
   end
 

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

@@ -34,6 +34,93 @@ describe 'param_comment' do
     end
   end
 
+  context 'valid code with spaces in the type' do
+    let(:code) do
+      <<~CODE
+        # @summary
+        #   some class
+        #
+        # @param ensure
+        #   Ensure it
+        class my_class (
+            Enum['present', 'absent'] $ensure = 'present'
+        ) {}
+      CODE
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'valid code with complex type definition' do
+    let(:code) do
+      <<~CODE
+        # @summary
+        #   some class
+        #
+        # @param optional
+        #   Complicated
+        class my_class (
+            Optional[Hash[
+              String,
+              Struct[{
+                test => Optional[Boolean]
+              }]
+            ]] $optional = undef
+        ) {}
+      CODE
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'valid code with hash default' do
+    let(:code) do
+      <<~CODE
+        # @summary
+        #   some class
+        #
+        # @param hashparam
+        #   A hash
+        class my_class (
+            Hash $hashparam = {
+              somekey => "value"
+            }
+        ) {}
+      CODE
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'valid code with hash default with an enclosed hash' do
+    let(:code) do
+      <<~CODE
+        # @summary
+        #   some class
+        #
+        # @param hashparam
+        #   A hash
+        class my_class (
+            Hash $hashparam = {
+              'anotherhash' => {
+                somekey => "value"
+              },
+            },
+        ) {}
+      CODE
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
   context 'code with missing parameter comment' do
     let(:code) do
       <<~CODE
@@ -87,15 +174,14 @@ describe 'param_comment' do
   context 'code with wrongly sorted parameter comments' do
     let(:code) do
       <<~CODE
-        # @param withdefault
-        #   A parameter with a default value
-        #
         # @param mandatory
         #   A mandatory parameter
         #
         # @param optional
         #   An optional parameter
-
+        #
+        # @param withdefault
+        #   A parameter with a default value
         class my_class (
             String $mandatory,
             Boolean $withdefault = false,
@@ -109,7 +195,7 @@ describe 'param_comment' do
     end
 
     it 'should create a warning' do
-      expect(problems).to contain_warning('Parameters sorted wrong').on_line(1).in_column(1)
+      expect(problems).to contain_warning('Parameters sorted wrong').on_line(4).in_column(1)
     end
   end
 
@@ -137,7 +223,7 @@ describe 'param_comment' do
     end
 
     it 'should create a warning' do
-      expect(problems).to contain_warning('Invalid state awaiting_separator for comment @param withdefault')
+      expect(problems).to contain_warning('Can not process the comment \'@param withdefault\' in the state awaiting_separator')
                             .on_line(3)
                             .in_column(1)
     end
@@ -158,7 +244,7 @@ describe 'param_comment' do
     end
 
     it 'should create a warning' do
-      expect(problems).to contain_warning('Invalid param or hash option header')
+      expect(problems).to contain_warning('Invalid param or hash option header: @param mandatory A mandatory parameter')
                             .on_line(1)
                             .in_column(1)
     end
@@ -229,7 +315,7 @@ describe 'param_comment' do
 
     it 'should create a warning' do
       expect(problems).to contain_warning(
-                            'Invalid state awaiting_header for comment @option mandatory [Boolean] :some_option'
+                            'Can not process the comment \'@option mandatory [Boolean] :some_option\' in the state awaiting_header'
                           )
                             .on_line(4)
                             .in_column(1)
@@ -254,7 +340,7 @@ describe 'param_comment' do
 
     it 'should create a warning' do
       expect(problems).to contain_warning(
-                            'Invalid param or hash option header'
+                            'Invalid param or hash option header: @option mandatory [Boolean] :some_option An option'
                           )
                             .on_line(3)
                             .in_column(1)
@@ -283,10 +369,28 @@ describe 'param_comment' do
 
     it 'should create a warning' do
       expect(problems).to contain_warning(
-                            'Invalid state awaiting_separator for comment @param second'
+                            'Can not process the comment \'@param second\' in the state awaiting_separator'
                           )
                             .on_line(5)
                             .in_column(1)
     end
   end
+
+  context 'valid code with complex hash option type' do
+    let(:code) do
+      <<~CODE
+        # @param mandatory
+        #   A mandatory parameter
+        # @option mandatory [Optional[String]] :some_option
+        #   An option
+        class my_class (
+            Hash $mandatory,
+        ) {}
+      CODE
+    end
+
+    it 'should detect exactly one problem' do
+      expect(problems).to have(0).problems
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puppet-lint-param_comment-check
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.4
 platform: ruby
 authors:
 - Dennis Ploeger
@@ -10,6 +10,20 @@ bindir: bin
 cert_chain: []
 date: 2022-05-31 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: finite_machine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: puppet-lint
   requirement: !ruby/object:Gem::Requirement
@@ -25,13 +39,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: finite_machine
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -53,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: rspec-its
+  name: rspec-collection_matchers
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -67,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: rspec-collection_matchers
+  name: rspec-its
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -80,20 +94,6 @@ dependencies:
     - - "~>"
       - !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: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -158,8 +158,7 @@ requirements: []
 rubygems_version: 3.0.3.1
 signing_key: 
 specification_version: 4
-summary: '["A puppet-lint plugin to check @param comments", "    A puppet-lint plugin
-  to check that manifest files contain properly formatted @param comments.\n"]'
+summary: A puppet-lint plugin to check @param comments
 test_files:
 - spec/spec_helper.rb
 - spec/puppet-lint/plugins/check_param_comment_spec.rb