puppet-lint-param_comment-check 0.1.4 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 760c2ecbb41952244ece53d7fddafcc91f322300b512a65dfc4d5ab7b5622636
-  data.tar.gz: 187d476c9e3418c03935d00ddf84fd9c9618cd8ac4a14a391e0046f68f92221f
+  metadata.gz: 8c928aed3decd05d2876d4b37ecd564e069317d4b918bf49c36561bac2aa8878
+  data.tar.gz: 7122d1353312ff519d240c89e9e6e538cc7cd6453451ba8fa8c3cc2a90b86e64
 SHA512:
-  metadata.gz: 8396f55b48c7cd1e82f66855eb950c2c1fd4e908423625a262e6ba11496d2cd3b9c90931c66deb97efba5d706502416e71ef4ae47f7d459b5c0fcf24d7b86ef4
-  data.tar.gz: '08c1d478a70c0a204805844aa0ad1724ee7a371852c3f7059596204d3c62f89d9044fa2cf44b26b6df2731331f371765b3cdf86de148ecf5cab88216336dea93'
+  metadata.gz: 883d3841875fb24bc60cdf566a22e917a0a42c9f127739d82c22923eb092b39dbd3e804ec8d6392a04102b9f114142c48f9d98093f24d807c8177f3689b909c5
+  data.tar.gz: 4d76a9e6d9a79ed2989495a47456a8148661b3363cbf5d6c590e0f5ec028d8156995165f7991b5b21f5305441bdfd3e1d698bbe5c315ea64eeffeb03ef35b32a

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative '../../puppet-lint-param_comment-check/param_workflow'
 require_relative '../../puppet-lint-param_comment-check/param_comments'
+require_relative '../../puppet-lint-param_comment-check/param'
 
 # The empty data of a parameter
 EMPTY_PARAM = {
@@ -18,52 +18,23 @@ 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
-    token_pointer -= 1
-  end
-  comments.reverse
-end
+    break unless %i[COMMENT NEWLINE].include? tokens[token_pointer].type
 
-# 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
+    comments.append(tokens[token_pointer])
+    token_pointer -= 1
   end
-  current_param
+  comments.reject { |comment| comment.type == :NEWLINE }.reverse
 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
@@ -141,10 +112,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
+        brackets += 1
+        @type_tokens.append(token) if @in_type
+        @default_tokens.append(token) if @in_default
+      when :RBRACE, :RBRACK
+        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,19 +58,25 @@ 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
 
+  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,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|
       @current_comment = 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
@@ -121,6 +122,38 @@ describe 'param_comment' do
     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
@@ -223,9 +256,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
 
@@ -244,9 +279,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
 
@@ -289,9 +326,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
 
@@ -315,10 +354,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
 
@@ -340,10 +379,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
 
@@ -369,10 +408,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
 
@@ -394,3 +433,4 @@ describe 'param_comment' do
     end
   end
 end
+# rubocop:enable Metrics/BlockLength

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-lint-param_comment-check
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.7
 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
@@ -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