puppet-lint-param_comment-check 0.1.5 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 637cfc1953d7f93cd5a8d160e90d7abeaf93efd0a1eafbf651dca61259fb6668
-  data.tar.gz: 7d74686774590de42d926b2e1a952330a1613e2b3724a8aac531d5003d3916a8
+  metadata.gz: 1ecd8b3c79ba841bf497a02bf7c635255479ce777ccd1d74a02938a6aea16e56
+  data.tar.gz: 54fd7284713d765083cb0834a3ef42f44e149ebbb8c16753a9251369a96a298a
 SHA512:
-  metadata.gz: d67851be5623ec31c85ff025c13420e8535915d7f9df8d6e8c153df4e7f51c3874253a5dcdf87b30ccab4841a31501f91ab98989d40e30717ede4317dd55da18
-  data.tar.gz: f47b461b2b56d68e9792be6c8da580f4f4222960364ef165d72fe867007e0a2335adcffe5898b978c386141c0b374c10228f9a7257971fbd11374b765666f2f5
+  metadata.gz: 6a44d786af696714854f1252d8ec33a40682080becac84e5b3e1f7ab7cf78c7f14022f8096965a7df8c8c8bd841febcb9580f065258943fc45ee6ef7f493933b
+  data.tar.gz: 5f2bdc6cc3bd83d359f6b350c703897a3be79edb695ecaaacf44b4afb94cbda7427c0ed536834f45ee5f35f401cd9828b6612660815e16aa70f131105ec0c38f

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

@@ -1,15 +1,7 @@
 # frozen_string_literal: true
 
-require_relative '../../puppet-lint-param_comment-check/param_workflow'
 require_relative '../../puppet-lint-param_comment-check/param_comments'
-
-# The empty data of a parameter
-EMPTY_PARAM = {
-  name: '',
-  type: '',
-  has_default: false,
-  default: ''
-}.freeze
+require_relative '../../puppet-lint-param_comment-check/param'
 
 # Find the header comments for a class or a defined type
 #
@@ -28,44 +20,13 @@ def get_comments(tokens, token_start)
   comments.reject { |comment| comment.type == :NEWLINE }.reverse
 end
 
-# Analyze a parameter token
-#
-# @param token The token to analyze
-# @param current_param the data object for the currently analyzed parameter
-def analyze_param_token(token, current_param)
-  # noinspection RubyCaseWithoutElseBlockInspection
-  case token.type
-  when :VARIABLE
-    current_param[:name] = token.value
-  when :CLASSREF, :TYPE
-    current_param[:type] = token.value
-  when :EQUALS
-    current_param[:has_default] = true
-    current_param[:default] = token.next_token.value
-  end
-  current_param
-end
-
 # Analyze the parameters of a class or a defined type
 #
 # @param param_tokens The parameter tokens to analyze
-def analyze_params(param_tokens) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
-  params = []
-  current_param = EMPTY_PARAM.dup
-  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[:name] == ''
-  params
+def analyze_params(param_tokens)
+  param_workflow = Param.new
+  param_workflow.process(param_tokens)
+  param_workflow.params
 end
 
 # Find, which parameters in the long list are missing in the short list and return their names
@@ -143,10 +104,14 @@ PuppetLint.new_check(:param_comment) do # rubocop:disable Metrics/BlockLength
   end
 
   # Check class or defined type indexes
-  def check_indexes(indexes)
+  def check_indexes(indexes) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
     indexes.each do |index|
       comments = get_comments(tokens, index[:start])
-      params = analyze_params(index[:param_tokens])
+      begin
+        params = analyze_params(index[:param_tokens])
+      rescue InvalidTokenForState, InvalidDefaultForOptional => e
+        return warn(e.message, e.token.line, e.token.column)
+      end
       return false unless check_comments(comments)
       return false unless check_parameters_count(params)
 

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'param_workflow'
+
+PARAM_TYPE_ENUM = {
+  mandatory: 1,
+  with_default: 2,
+  optional: 3
+}.freeze
+
+# The empty data of a parameter
+EMPTY_PARAM = {
+  name: '',
+  type: '',
+  default: [],
+  param_type: PARAM_TYPE_ENUM[:mandatory]
+}.freeze
+
+# Comment received in an invalid state
+class InvalidTokenForState < StandardError
+  def initialize(token, state)
+    @token = token
+    @state = state
+    super "Can not process the token '#{@token.value.strip}' in the state #{@state}"
+  end
+
+  attr_reader :token
+end
+
+# An optional parameter does not have "undef" as the default
+class InvalidDefaultForOptional < StandardError
+  def initialize(token, default_value)
+    @token = token
+    super "Invalid value '#{default_value}' for an parameter of type Optional. undef is required"
+  end
+
+  attr_reader :token
+end
+
+# A helper to analyze parameter comments using the ParamWorkflow fsm
+class Param
+  def initialize
+    @workflow = ParamWorkflow.new(self)
+
+    reset
+  end
+
+  def reset
+    @params = []
+    @in_default = false
+    @default_tokens = []
+    @in_type = false
+    @type_tokens = []
+    @current_param = EMPTY_PARAM.dup
+    @current_token = nil
+    @workflow.restore!(:start)
+  end
+
+  # Walk through every parameter and transition the workflow fsm accordingly
+  #
+  # @param tokens A list of parameter tokens
+  def process(tokens) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+    reset
+    brackets = 0
+    tokens.reject { |token| %i[NEWLINE INDENT].include? token.type }.each do |token| # rubocop:disable Metrics/BlockLength
+      @current_token = token
+      case token.type
+      when :TYPE
+        if @in_default
+          @default_tokens.append(token)
+          next
+        end
+        @workflow.got_type unless @in_type
+        @in_type = true
+        @type_tokens.append(token)
+      when :VARIABLE
+        @workflow.got_name(token, @type_tokens) unless @in_default
+        @in_type = false unless @in_default
+        @type_tokens = [] unless @in_default
+        @default_tokens.append(token) if @in_default
+      when :EQUALS
+        @in_default = true
+      when :COMMA
+        @workflow.got_end(@default_tokens) unless @in_type || brackets.positive?
+        @default_tokens = [] unless @in_type && brackets.positive?
+        @in_default = false unless @in_type && brackets.positive?
+        @type_tokens.append(token) if @in_type
+      when :LBRACE, :LBRACK, :LPAREN
+        brackets += 1
+        @type_tokens.append(token) if @in_type
+        @default_tokens.append(token) if @in_default
+      when :RBRACE, :RBRACK, :RPAREN
+        brackets -= 1
+        @type_tokens.append(token) if @in_type
+        @default_tokens.append(token) if @in_default
+      else
+        @type_tokens.append(token) if @in_type
+        @default_tokens.append(token) if @in_default
+      end
+    end
+    @workflow.got_end(@default_tokens) unless @workflow.current == :start
+  end
+
+  def got_name_trigger(_, token, type_tokens)
+    @current_param[:type] = type_tokens.map(&:value).join('')
+    if !@type_tokens.empty? && @type_tokens[0].value == 'OPTIONAL'
+      @current_param[:param_type] = PARAM_TYPE_ENUM[:optional]
+    end
+    @current_param[:name] = token.value
+  end
+
+  def got_end_trigger(_, default_tokens) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+    raise InvalidDefaultForOptional if @current_param[:param_type] == PARAM_TYPE_ENUM[:optional] &&
+                                       !default_tokens.empty? &&
+                                       default_tokens[0].value != 'undef'
+
+    @current_param[:default] = @default_tokens.map(&:value).join('') unless @default_tokens.empty?
+    @current_param[:param_type] = PARAM_TYPE_ENUM[:with_default] unless
+        @current_param[:param_type] == PARAM_TYPE_ENUM[:optional] || default_tokens.empty?
+    @params.append(@current_param)
+    @current_param = EMPTY_PARAM.dup
+    @in_default, @in_type = false
+  end
+
+  # Called when an invalid state transition would happen
+  def invalid_state
+    raise InvalidTokenForState.new(@current_token, @workflow.current)
+  end
+
+  # The list of analyzed parameters in the comments
+  attr_reader :params
+end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'param_comments_workflow'
+
 # The empty data of a parameter
 EMPTY_PARAM_COMMENT = {
   name: '',
@@ -56,7 +58,7 @@ end
 # A helper to analyze parameter comments using the ParamWorkflow fsm
 class ParamComments
   def initialize
-    @workflow = ParamWorkflow.new(self)
+    @workflow = ParamCommentsWorkflow.new(self)
 
     reset
   end
@@ -73,7 +75,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,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+  def process(comments) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize
     reset
     @current_comment = PuppetLint::Lexer::Token.new(:COMMENT, '', 1, 1)
     comments.each do |comment|

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'finite_machine'
+
+# A finite state machine working through the expected parameter comments
+class ParamCommentsWorkflow < FiniteMachine::Definition
+  initial :start
+
+  event :got_header, from: :start, to: :awaiting_description
+  event :got_header, from: :awaiting_header, to: :awaiting_description
+  event :got_description, from: :awaiting_description, to: :awaiting_separator
+  event :got_separator, from: :awaiting_separator, to: :awaiting_header
+
+  # for multi-line descriptions
+  event :got_description, from: :awaiting_separator, to: :awaiting_separator
+
+  # handling options
+  event :got_option_header, from: :awaiting_separator, to: :awaiting_option_description
+  event :got_option_description, from: :awaiting_option_description, to: :awaiting_separator
+
+  # for separators inside descriptions
+  event :got_description, from: :awaiting_header, to: :awaiting_separator
+  event :got_option_description, from: :awaiting_separator, to: :awaiting_separator
+
+  on_before(:got_header) { |event, comment| target.got_header_trigger(event, comment) }
+  on_before(:got_description) { |event, comment| target.got_description_trigger(event, comment) }
+  on_before(:got_option_description) { |event, comment| target.got_description_trigger(event, comment) }
+  on_before(:got_option_header) { |event, comment| target.got_option_header_trigger(event, comment) }
+
+  handle FiniteMachine::InvalidStateError, with: -> { target.invalid_state }
+end

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

@@ -2,30 +2,22 @@
 
 require 'finite_machine'
 
-# A finite state machine working through the expected parameter comments
+# A finite state machine working through the expected parameter tokens
 class ParamWorkflow < FiniteMachine::Definition
   initial :start
 
-  event :got_header, from: :start, to: :awaiting_description
-  event :got_header, from: :awaiting_header, to: :awaiting_description
-  event :got_description, from: :awaiting_description, to: :awaiting_separator
-  event :got_separator, from: :awaiting_separator, to: :awaiting_header
+  event :got_type, from: :start, to: :awaiting_name
+  event :got_name, from: :awaiting_name, to: :awaiting_default
 
-  # for multi-line descriptions
-  event :got_description, from: :awaiting_separator, to: :awaiting_separator
+  # For mandatory parameters
+  event :got_end, from: :awaiting_name, to: :start
+  event :got_end, from: :awaiting_default, to: :start
 
-  # handling options
-  event :got_option_header, from: :awaiting_separator, to: :awaiting_option_description
-  event :got_option_description, from: :awaiting_option_description, to: :awaiting_separator
+  # For typeless parameters
+  event :got_name, from: :start, to: :awaiting_default
 
-  # for separators inside descriptions
-  event :got_description, from: :awaiting_header, to: :awaiting_separator
-  event :got_option_description, from: :awaiting_separator, to: :awaiting_separator
-
-  on_before(:got_header) { |event, comment| target.got_header_trigger(event, comment) }
-  on_before(:got_description) { |event, comment| target.got_description_trigger(event, comment) }
-  on_before(:got_option_description) { |event, comment| target.got_description_trigger(event, comment) }
-  on_before(:got_option_header) { |event, comment| target.got_option_header_trigger(event, comment) }
+  on_before(:got_name) { |event, token, type_tokens| target.got_name_trigger(event, token, type_tokens) }
+  on_before(:got_end) { |event, default_tokens| target.got_end_trigger(event, default_tokens) }
 
   handle FiniteMachine::InvalidStateError, with: -> { target.invalid_state }
 end

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

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require 'spec_helper'
+require_relative '../../spec_helper'
 
+# rubocop:disable Metrics/BlockLength
 describe 'param_comment' do
   context 'valid code' do
     let(:code) do
@@ -153,6 +154,26 @@ describe 'param_comment' do
     end
   end
 
+  context 'valid code with parentheses in the parameters' do
+    let(:code) do
+      <<~CODE
+        # @summary
+        #   some class
+        #
+        # @param mandatory
+        #   A mandatory parameter
+        #   with two lines
+        class my_class (
+            String $mandatory = join([0,1,2], ','),
+        ) {}
+      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
@@ -255,9 +276,11 @@ describe 'param_comment' do
     end
 
     it 'should create a warning' do
-      expect(problems).to contain_warning('Can not process the comment \'@param withdefault\' in the state awaiting_separator')
-                            .on_line(3)
-                            .in_column(1)
+      expect(problems).to contain_warning(
+        'Can not process the comment \'@param withdefault\' in the state awaiting_separator'
+      )
+        .on_line(3)
+        .in_column(1)
     end
   end
 
@@ -276,9 +299,11 @@ describe 'param_comment' do
     end
 
     it 'should create a warning' do
-      expect(problems).to contain_warning('Invalid param or hash option header: @param mandatory A mandatory parameter')
-                            .on_line(1)
-                            .in_column(1)
+      expect(problems).to contain_warning(
+        'Invalid param or hash option header: @param mandatory A mandatory parameter'
+      )
+        .on_line(1)
+        .in_column(1)
     end
   end
 
@@ -321,9 +346,11 @@ describe 'param_comment' do
     end
 
     it 'should create a warning' do
-      expect(problems).to contain_warning('Option references wrong hash @option mandatry [Boolean] :some_option')
-                            .on_line(3)
-                            .in_column(1)
+      expect(problems).to contain_warning(
+        'Option references wrong hash @option mandatry [Boolean] :some_option'
+      )
+        .on_line(3)
+        .in_column(1)
     end
   end
 
@@ -347,10 +374,10 @@ describe 'param_comment' do
 
     it 'should create a warning' do
       expect(problems).to contain_warning(
-                            'Can not process the comment \'@option mandatory [Boolean] :some_option\' in the state awaiting_header'
-                          )
-                            .on_line(4)
-                            .in_column(1)
+        'Can not process the comment \'@option mandatory [Boolean] :some_option\' in the state awaiting_header'
+      )
+        .on_line(4)
+        .in_column(1)
     end
   end
 
@@ -372,10 +399,10 @@ describe 'param_comment' do
 
     it 'should create a warning' do
       expect(problems).to contain_warning(
-                            'Invalid param or hash option header: @option mandatory [Boolean] :some_option An option'
-                          )
-                            .on_line(3)
-                            .in_column(1)
+        'Invalid param or hash option header: @option mandatory [Boolean] :some_option An option'
+      )
+        .on_line(3)
+        .in_column(1)
     end
   end
 
@@ -401,10 +428,10 @@ describe 'param_comment' do
 
     it 'should create a warning' do
       expect(problems).to contain_warning(
-                            'Can not process the comment \'@param second\' in the state awaiting_separator'
-                          )
-                            .on_line(5)
-                            .in_column(1)
+        'Can not process the comment \'@param second\' in the state awaiting_separator'
+      )
+        .on_line(5)
+        .in_column(1)
     end
   end
 
@@ -426,3 +453,4 @@ describe 'param_comment' do
     end
   end
 end
+# rubocop:enable Metrics/BlockLength

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puppet-lint-param_comment-check
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.8
 platform: ruby
 authors:
 - Dennis Ploeger
@@ -131,7 +131,9 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- lib/puppet-lint-param_comment-check/param.rb
 - lib/puppet-lint-param_comment-check/param_comments.rb
+- lib/puppet-lint-param_comment-check/param_comments_workflow.rb
 - lib/puppet-lint-param_comment-check/param_workflow.rb
 - lib/puppet-lint/plugins/check_param_comment.rb
 - spec/puppet-lint/plugins/check_param_comment_spec.rb