abide_dev_utils 0.12.2 → 0.14.0

data/lib/abide_dev_utils/cem/validate/strings/base_validator.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative 'validation_finding'
+
+module AbideDevUtils
+  module CEM
+    module Validate
+      module Strings
+        # Base class for validating Puppet Strings objects. This class can be used directly, but it is
+        # recommended to use a subclass of this class to provide more specific validation logic. Each
+        # subclass should implement a `validate_<type>` method that will be called by the `validate` method
+        # of this class. The `validate_<type>` method should contain the validation logic for the
+        # corresponding type of Puppet Strings object.
+        class BaseValidator
+          SAFE_OBJECT_METHODS = %i[
+            type
+            name
+            file
+            line
+            docstring
+            tags
+            parameters
+            source
+          ].freeze
+          PDK_SUMMARY_REGEX = %r{^A short summary of the purpose.*}.freeze
+          PDK_DESCRIPTION_REGEX = %r{^A description of what this.*}.freeze
+
+          attr_reader :findings
+
+          def initialize(strings_object)
+            @object = strings_object
+            @findings = []
+            # Define instance methods for each of the SAFE_OBJECT_METHODS
+            SAFE_OBJECT_METHODS.each do |method|
+              define_singleton_method(method) { safe_method_call(@object, method) }
+            end
+          end
+
+          def errors
+            @findings.select { |f| f.type == :error }
+          end
+
+          def warnings
+            @findings.select { |f| f.type == :warning }
+          end
+
+          def errors?
+            !errors.empty?
+          end
+
+          def warnings?
+            !warnings.empty?
+          end
+
+          def find_tag_name(tag_name)
+            tags&.find { |t| t.tag_name == tag_name }
+          end
+
+          def select_tag_name(tag_name)
+            return [] if tags.nil?
+
+            tags.select { |t| t.tag_name == tag_name }
+          end
+
+          def find_parameter(param_name)
+            parameters&.find { |p| p[0] == param_name }
+          end
+
+          def validate
+            license_tag?
+            non_generic_summary?
+            non_generic_description?
+            send("validate_#{type}".to_sym) if respond_to?("validate_#{type}".to_sym)
+          end
+
+          # Checks if the object has a license tag and if it is formatted correctly.
+          # Comparison is not case sensitive.
+          def license_tag?
+            see_tags = select_tag_name('see')
+            if see_tags.empty? || see_tags.none? { |t| t.name.casecmp('LICENSE.pdf') && t.text.casecmp('for license') }
+              new_finding(
+                :error,
+                :no_license_tag,
+                remediation: 'Add "@see LICENSE.pdf for license" to the class documentation'
+              )
+              return false
+            end
+            true
+          end
+
+          # Checks if the summary is not the default PDK summary.
+          def non_generic_summary?
+            summary = find_tag_name('summary')&.text
+            return true if summary.nil?
+
+            if summary.match?(PDK_SUMMARY_REGEX)
+              new_finding(:warning, :generic_summary, remediation: 'Add a more descriptive summary')
+              return false
+            end
+            true
+          end
+
+          # Checks if the description is not the default PDK description.
+          def non_generic_description?
+            description = docstring
+            return true if description.nil?
+
+            if description.match?(PDK_DESCRIPTION_REGEX)
+              new_finding(:warning, :generic_description, remediation: 'Add a more descriptive description')
+              return false
+            end
+            true
+          end
+
+          private
+
+          def safe_method_call(obj, method, *args)
+            obj.send(method, *args)
+          rescue NoMethodError
+            nil
+          end
+
+          def new_finding(type, title, **data)
+            @findings << ValidationFinding.new(type, title.to_sym, data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/cem/validate/strings/puppet_class_validator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'base_validator'
+require_relative '../../../validate'
+
+module AbideDevUtils
+  module CEM
+    module Validate
+      module Strings
+        # Validates a Puppet Class from a Puppet Strings hash
+        class PuppetClassValidator < BaseValidator
+          def validate_puppet_class
+            check_text_or_summary
+            check_params
+          end
+
+          # @return [Hash] Hash of basic class data to be used in findings
+          def finding_data(**data)
+            data
+          end
+
+          private
+
+          # Checks if the class has a description or summary
+          def check_text_or_summary
+            valid_desc = AbideDevUtils::Validate.populated_string?(docstring)
+            valid_summary = AbideDevUtils::Validate.populated_string?(find_tag_name('summary')&.text)
+            return if valid_desc || valid_summary
+
+            new_finding(
+              :error,
+              :no_description_or_summary,
+              finding_data(valid_description: valid_desc, valid_summary: valid_summary),
+            )
+          end
+
+          # Checks if the class has parameters and if they are documented
+          def check_params
+            return if parameters.nil? || parameters.empty? # No params
+
+            param_tags = select_tag_name('param')
+            if param_tags.empty?
+              new_finding(:error, :no_parameter_documentation, finding_data(class_parameters: parameters))
+              return
+            end
+
+            parameters.each do |param|
+              param_name, def_val = param
+              check_param(param_name, def_val, param_tags)
+            end
+          end
+
+          # Checks if a parameter is documented properly and if it has a correct default value
+          def check_param(param_name, def_val = nil, param_tags = select_tag_name('param'))
+            param_tag = param_tags.find { |t| t.name == param_name }
+            return unless param_documented?(param_name, param_tag)
+
+            valid_param_description?(param_tag)
+            valid_param_types?(param_tag)
+            valid_param_default?(param_tag, def_val)
+          end
+
+          # Checks if a parameter is documented
+          def param_documented?(param_name, param_tag)
+            return true if param_tag
+
+            new_finding(:error, :param_not_documented, finding_data(param: param_name))
+            false
+          end
+
+          # Checks if a parameter has a description
+          def valid_param_description?(param)
+            return true if AbideDevUtils::Validate.populated_string?(param.text)
+
+            new_finding(:error, :param_missing_description, finding_data(param: param.name))
+            false
+          end
+
+          # Checks if a parameter is typed
+          def valid_param_types?(param)
+            unless param.types&.any?
+              new_finding(:error, :param_missing_types, finding_data(param: param.name))
+              return false
+            end
+            true
+          end
+
+          # Checks if a parameter has a default value and if it is correct for the type
+          def valid_param_default?(param, def_val)
+            return true if def_val.nil?
+
+            if param.types.first.start_with?('Optional[') && def_val != 'undef'
+              new_finding(:error, :param_optional_without_undef_default, param: param.name, default_value: def_val, name: name, file: file)
+              return false
+            end
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/cem/validate/strings/puppet_defined_type_validator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'puppet_class_validator'
+
+module AbideDevUtils
+  module CEM
+    module Validate
+      module Strings
+        # Validates Puppet Defined Type strings objects
+        class PuppetDefinedTypeValidator < PuppetClassValidator
+          def validate_puppet_defined_type
+            validate_puppet_class
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/cem/validate/strings/validation_finding.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AbideDevUtils
+  module CEM
+    module Validate
+      module Strings
+        # Represents a validation finding (warning or error)
+        class ValidationFinding
+          attr_reader :type, :title, :data
+
+          def initialize(type, title, data)
+            raise ArgumentError, 'type must be :error or :warning' unless %i[error warning].include?(type)
+
+            @type = type.to_sym
+            @title = title.to_sym
+            @data = data
+          end
+
+          def to_s
+            "#{@type}: #{@title}: #{@data}"
+          end
+
+          def to_hash
+            { type: @type, title: @title, data: @data }
+          end
+          alias to_h to_hash
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/cem/validate/strings.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative '../../ppt/strings'
+require_relative 'strings/puppet_class_validator'
+require_relative 'strings/puppet_defined_type_validator'
+
+module AbideDevUtils
+  module CEM
+    module Validate
+      # Validation objects and methods for Puppet Strings
+      module Strings
+        # Convenience method to validate Puppet Strings of current module
+        def self.validate(**opts)
+          output = Validator.new(nil, **opts).validate
+          output.transform_values do |results|
+            results.select { |r| r[:errors].any? || r[:warnings].any? }
+          end
+        end
+
+        # Holds various validation methods for a AbideDevUtils::Ppt::Strings object
+        class Validator
+          def initialize(puppet_strings = nil, **opts)
+            unless puppet_strings.nil? || puppet_strings.is_a?(AbideDevUtils::Ppt::Strings)
+              raise ArgumentError, 'If puppet_strings is supplied, it must be a AbideDevUtils::Ppt::Strings object'
+            end
+
+            puppet_strings = AbideDevUtils::Ppt::Strings.new(**opts) if puppet_strings.nil?
+            @puppet_strings = puppet_strings
+          end
+
+          # Associate validators with each Puppet Strings object and calls #validate on each
+          # @return [Hash] Hash of validation results
+          def validate
+            AbideDevUtils::Ppt::Strings::REGISTRY_TYPES.each_with_object({}) do |rtype, hsh|
+              next unless rtype.to_s.start_with?('puppet_') && @puppet_strings.respond_to?(rtype)
+
+              hsh[rtype] = @puppet_strings.send(rtype).map do |item|
+                item.validator = validator_for(item)
+                item.validate
+                validation_output(item)
+              end
+            end
+          end
+
+          private
+
+          # Returns the appropriate validator for a given Puppet Strings object
+          def validator_for(item)
+            case item.type
+            when :puppet_class
+              PuppetClassValidator.new(item)
+            when :puppet_defined_type
+              PuppetDefinedTypeValidator.new(item)
+            else
+              BaseValidator.new(item)
+            end
+          end
+
+          def validation_output(item)
+            {
+              name: item.name,
+              file: item.file,
+              line: item.line,
+              errors: item.errors,
+              warnings: item.warnings,
+            }
+          end
+
+          # Validate Puppet Class strings hashes.
+          # @return [Hash] Hash of class names and errors
+          def validate_classes!
+            @puppet_strings.puppet_classes.map! do |klass|
+              klass.validator = PuppetClassValidator.new(klass)
+              klass.validate
+              klass
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abide_dev_utils/cem/validate.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'abide_dev_utils/cem/validate/resource_data'
+require_relative 'validate/resource_data'
+require_relative 'validate/strings'
 
 module AbideDevUtils
   module CEM

data/lib/abide_dev_utils/cem.rb

@@ -2,6 +2,7 @@
 
 require 'abide_dev_utils/xccdf'
 require 'abide_dev_utils/cem/generate'
+require 'abide_dev_utils/cem/validate'
 
 module AbideDevUtils
   # Methods for working with Compliance Enforcement Modules (CEM)

data/lib/abide_dev_utils/cli/cem.rb

@@ -17,6 +17,7 @@ module Abide
         super(CMD_NAME, CMD_SHORT, CMD_LONG, takes_commands: true)
         add_command(CemGenerate.new)
         add_command(CemUpdateConfig.new)
+        add_command(CemValidate.new)
       end
     end
 
@@ -69,11 +70,11 @@ module Abide
         quiet = @data.fetch(:quiet, false)
         console = @data.fetch(:verbose, false) && !quiet
         generate_opts = {
-          benchmark: @data.fetch(:benchmark),
-          profile: @data.fetch(:profile),
-          level: @data.fetch(:level),
+          benchmark: @data[:benchmark],
+          profile: @data[:profile],
+          level: @data[:level],
           ignore_benchmark_errors: @data.fetch(:ignore_all, false),
-          xccdf_dir: @data.fetch(:xccdf_dir),
+          xccdf_dir: @data[:xccdf_dir],
         }
         AbideDevUtils::Output.simple('Generating coverage report...') unless quiet
         coverage = AbideDevUtils::CEM::Generate::CoverageReport.generate(format_func: :to_h, opts: generate_opts)
@@ -104,11 +105,14 @@ module Abide
           @data[:format] = f
         end
         options.on('-v', '--verbose', 'Verbose output') do
-          @data[:verbose] = true
+          @data[:debug] = true
         end
         options.on('-q', '--quiet', 'Quiet output') do
           @data[:quiet] = true
         end
+        options.on('-s', '--strict', 'Fails if there are any errors') do
+          @data[:strict] = true
+        end
       end
 
       def execute
@@ -167,5 +171,59 @@ module Abide
         AbideDevUtils::Output.simple(change_report) unless @data[:quiet]
       end
     end
+
+    class CemValidate < AbideCommand
+      CMD_NAME = 'validate'
+      CMD_SHORT = 'Validation commands for CEM modules'
+      CMD_LONG = 'Validation commands for CEM modules'
+      def initialize
+        super(CMD_NAME, CMD_SHORT, CMD_LONG, takes_commands: true)
+        add_command(CemValidatePuppetStrings.new)
+      end
+    end
+
+    class CemValidatePuppetStrings < AbideCommand
+      CMD_NAME = 'puppet-strings'
+      CMD_SHORT = 'Validates the Puppet Strings documentation'
+      CMD_LONG = 'Validates the Puppet Strings documentation'
+      def initialize
+        super(CMD_NAME, CMD_SHORT, CMD_LONG, takes_commands: false)
+        options.on('-v', '--verbose', 'Verbose output') do
+          @data[:verbose] = true
+        end
+        options.on('-q', '--quiet', 'Quiet output') do
+          @data[:quiet] = true
+        end
+        options.on('-f [FORMAT]', '--format [FORMAT]', 'Format for output (text, json, yaml)') do |f|
+          @data[:format] = f
+        end
+        options.on('-o [FILE]', '--out-file [FILE]', 'Path to save the updated config file') do |o|
+          @data[:out_file] = o
+        end
+        options.on('-s', '--strict', 'Exits with exit code 1 if there are any warnings') do
+          @data[:strict] = true
+        end
+      end
+
+      def execute
+        @data[:format] ||= 'text'
+        AbideDevUtils::Validate.puppet_module_directory
+        output = AbideDevUtils::CEM::Validate::Strings.validate(**@data)
+        has_errors = false
+        has_warnings = false
+        output.each do |_, i|
+          has_errors = true if i.any? { |j| j[:errors].any? }
+          has_warnings = true if i.any? { |j| j[:warnings].any? }
+        end
+        AbideDevUtils::Output.send(
+          @data[:format].to_sym,
+          output,
+          console: !@data[:quiet],
+          file: @data[:out_file],
+          stringify: true,
+        )
+        exit 1 if has_errors || (has_warnings && @data[:strict])
+      end
+    end
   end
 end

data/lib/abide_dev_utils/cli/jira.rb

@@ -123,8 +123,9 @@ module Abide
         super(CMD_NAME, takes_commands: false)
         short_desc(CMD_SHORT)
         long_desc(CMD_LONG)
-        argument_desc(PATH: 'An XCCDF file from the abide puppet ticket coverage command', PROJECT: 'A Jira project')
+        argument_desc(PATH: 'An XCCDF file', PROJECT: 'A Jira project')
         options.on('-d', '--dry-run', 'Print to console instead of saving objects') { |_| @data[:dry_run] = true }
+        options.on('-e [EPIC]', '--epic [EPIC]', 'If given, tasks will be created and assigned to this epic. Takes form <PROJECT>-<NUM>') { |e| @data[:epic] = e }
       end
 
       def execute(path, project)
@@ -132,7 +133,7 @@ module Abide
         @data[:dry_run] = false if @data[:dry_run].nil?
         client = JIRA.client(options: {})
         proj = JIRA.project(client, project)
-        JIRA.new_issues_from_xccdf(client, proj, path, dry_run: @data[:dry_run])
+        JIRA.new_issues_from_xccdf(client, proj, path, epic: @data[:epic], dry_run: @data[:dry_run])
       end
     end
   end

data/lib/abide_dev_utils/errors/jira.rb

@@ -9,6 +9,10 @@ module AbideDevUtils
         @default = 'Failed to create Jira issue:'
       end
 
+      class CreateEpicError < GenericError
+        @default = 'Failed to create Jira epic:'
+      end
+
       class CreateSubtaskError < GenericError
         @default = 'Failed to create Jira subtask for issue:'
       end