puppet-lint-param_comment-check 0.1.2 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57edfb5e9c1716c1bfb583619d1a36bf57f7f4492af64f33a828dba5f4b1eec2
-  data.tar.gz: 3350c35a78495a1d4de4f25567af5da91cbed2601c25e3fe8e13e273e31e8f09
+  metadata.gz: 637cfc1953d7f93cd5a8d160e90d7abeaf93efd0a1eafbf651dca61259fb6668
+  data.tar.gz: 7d74686774590de42d926b2e1a952330a1613e2b3724a8aac531d5003d3916a8
 SHA512:
-  metadata.gz: 0e58accb1fe706bb94f24ccbe8ed80f50aee634f942360f4b29c203a206c84a7196fc0bda9c882561f7d2b9420919d703fb7444a41ac47da9d3c4a998d54ae48
-  data.tar.gz: 10e7eef3b38f933c9f871e727d912c88e1fc76193158dd909c6c99e9d084dd585dce554dc5573d7eb206170b2d07c7fbe530a888903e3ca15446d9fbb29fbdd7
+  metadata.gz: d67851be5623ec31c85ff025c13420e8535915d7f9df8d6e8c153df4e7f51c3874253a5dcdf87b30ccab4841a31501f91ab98989d40e30717ede4317dd55da18
+  data.tar.gz: f47b461b2b56d68e9792be6c8da580f4f4222960364ef165d72fe867007e0a2335adcffe5898b978c386141c0b374c10228f9a7257971fbd11374b765666f2f5

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

@@ -18,12 +18,14 @@ EMPTY_PARAM = {
 # @return The head comments
 def get_comments(tokens, token_start)
   comments = []
-  token_pointer = token_start
+  token_pointer = token_start - 1
   while token_pointer >= 0
-    comments.append(tokens[token_pointer]) if tokens[token_pointer].type == :COMMENT
+    break unless %i[COMMENT NEWLINE].include? tokens[token_pointer].type
+
+    comments.append(tokens[token_pointer])
     token_pointer -= 1
   end
-  comments.reverse
+  comments.reject { |comment| comment.type == :NEWLINE }.reverse
 end
 
 # Analyze a parameter token
@@ -50,11 +52,11 @@ end
 def analyze_params(param_tokens) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
   params = []
   current_param = EMPTY_PARAM.dup
-  in_brackets = false
-  param_tokens.reject { |token| %i[WHITESPACE NEWLINE].include? token.type }.each do |token|
-    in_brackets = true if token.type == :LBRACK
-    in_brackets = false if token.type == :RBRACK
-    next if in_brackets
+  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
@@ -62,7 +64,7 @@ def analyze_params(param_tokens) # rubocop:disable Metrics/AbcSize,Metrics/Cyclo
       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
 
@@ -135,9 +137,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
@@ -147,7 +149,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
@@ -56,17 +58,23 @@ class ParamComments
   def initialize
     @workflow = ParamWorkflow.new(self)
 
+    reset
+  end
+
+  def reset
     @current_param = nil
     @current_option = nil
     @in_option = false
     @params_have_started = false
     @params = []
+    @workflow.restore!(:start)
   end
 
   # 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
+    reset
     @current_comment = PuppetLint::Lexer::Token.new(:COMMENT, '', 1, 1)
     comments.each do |comment|
       @current_comment = comment
@@ -87,7 +95,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 +104,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 +129,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

@@ -53,6 +53,106 @@ describe 'param_comment' do
     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 'valid code with multiple classes' do
+    let(:code) do
+      <<~CODE
+        # @summary
+        #   some class
+        #
+        # @param mandatory
+        #   A mandatory parameter
+        #   with two lines
+        class my_class (
+            String $mandatory,
+        ) {}
+
+        # @summary
+        #   some other class
+        #
+        # @see something
+        #
+        # @param mandatory
+        #   A mandatory parameter
+        #   with two lines
+        class my_other_class (
+            String $mandatory,
+        ) {}
+      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
@@ -106,15 +206,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,
@@ -128,7 +227,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
 
@@ -156,7 +255,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
@@ -177,7 +276,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
@@ -248,7 +347,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)
@@ -273,7 +372,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)
@@ -302,10 +401,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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-lint-param_comment-check
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.5
 platform: ruby
 authors:
 - Dennis Ploeger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-31 00:00:00.000000000 Z
+date: 2022-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: finite_machine