abide_dev_utils 0.13.0 → 0.14.1

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/markdown.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'tempfile'
+require 'fileutils'
+
 module AbideDevUtils
   # Formats text for output in markdown
   class Markdown
@@ -14,11 +17,17 @@ module AbideDevUtils
     def to_markdown
       toc = @toc.join("\n")
       body = @body.join("\n")
-      "#{@title}\n#{toc}\n\n#{body}"
+      "#{@title}\n#{toc}\n\n#{body}".encode(universal_newline: true)
     end
+    alias to_s to_markdown
 
     def to_file
-      File.write(@file, to_markdown)
+      this_markdown = to_markdown
+      Tempfile.create('markdown') do |f|
+        f.write(this_markdown)
+        check_file_content(f.path, this_markdown)
+        FileUtils.mv(f.path, @file)
+      end
     end
 
     def method_missing(name, *args, &block)
@@ -49,6 +58,10 @@ module AbideDevUtils
       "#### #{text}\n"
     end
 
+    def paragraph(text)
+      "#{text}\n"
+    end
+
     def ul(text, indent: 0)
       indented_text = []
       indent.times { indented_text << '  ' } if indent.positive?
@@ -84,6 +97,14 @@ module AbideDevUtils
 
     private
 
+    def check_file_content(file, content)
+      raise "File #{file} not found! Not saving to #{@file}" unless File.exist?(file)
+      raise "File #{file} is empty! Not saving to #{@file}" if File.zero?(file)
+      return if File.read(file).include?(content)
+
+      raise "File #{file} does not contain correct content! Not saving to #{@file}"
+    end
+
     def add(type, text, *args, **kwargs)
       @toc << ul(link(text, text, anchor: true), indent: 0) if @with_toc && type == :h1
 

data/lib/abide_dev_utils/output.rb

@@ -10,30 +10,44 @@ require 'abide_dev_utils/files'
 module AbideDevUtils
   module Output
     FWRITER = AbideDevUtils::Files::Writer.new
-    def self.simple(msg, stream: $stdout)
-      stream.puts msg
+    def self.simple(msg, stream: $stdout, **_)
+      case msg
+      when Hash
+        stream.puts JSON.pretty_generate(msg)
+      else
+        stream.puts msg
+      end
     end
 
-    def self.json(in_obj, console: false, file: nil, pretty: true)
+    def self.text(msg, console: false, file: nil, **_)
+      simple(msg) if console
+      FWRITER.write_text(msg, file: file) unless file.nil?
+    end
+
+    def self.json(in_obj, console: false, file: nil, pretty: true, **_)
       AbideDevUtils::Validate.hashable(in_obj)
       json_out = pretty ? JSON.pretty_generate(in_obj) : JSON.generate(in_obj)
       simple(json_out) if console
       FWRITER.write_json(json_out, file: file) unless file.nil?
     end
 
-    def self.yaml(in_obj, console: false, file: nil)
+    def self.yaml(in_obj, console: false, file: nil, stringify: false, **_)
       yaml_out = if in_obj.is_a? String
                    in_obj
                  else
                    AbideDevUtils::Validate.hashable(in_obj)
-                   # Use object's #to_yaml method if it exists, convert to hash if not
-                   in_obj.respond_to?(:to_yaml) ? in_obj.to_yaml : in_obj.to_h.to_yaml
+                   if stringify
+                     JSON.parse(JSON.generate(in_obj)).to_yaml
+                   else
+                     # Use object's #to_yaml method if it exists, convert to hash if not
+                     in_obj.respond_to?(:to_yaml) ? in_obj.to_yaml : in_obj.to_h.to_yaml
+                   end
                  end
       simple(yaml_out) if console
       FWRITER.write_yaml(yaml_out, file: file) unless file.nil?
     end
 
-    def self.yml(in_obj, console: false, file: nil)
+    def self.yml(in_obj, console: false, file: nil, **_)
       AbideDevUtils::Validate.hashable(in_obj)
       # Use object's #to_yaml method if it exists, convert to hash if not
       yml_out = in_obj.respond_to?(:to_yaml) ? in_obj.to_yaml : in_obj.to_h.to_yaml
@@ -41,7 +55,7 @@ module AbideDevUtils
       FWRITER.write_yml(yml_out, file: file) unless file.nil?
     end
 
-    def self.progress(title: 'Progress', start: 0, total: 100, format: nil)
+    def self.progress(title: 'Progress', start: 0, total: 100, format: nil, **_)
       ProgressBar.create(title: title, starting_at: start, total: total, format: format)
     end
   end

data/lib/abide_dev_utils/ppt/code_introspection.rb

@@ -10,17 +10,30 @@ module AbideDevUtils
         attr_reader :manifest_file
 
         def initialize(manifest_file)
+          @compiler = Puppet::Pal::Compiler.new(nil)
           @manifest_file = File.expand_path(manifest_file)
           raise ArgumentError, "File #{@manifest_file} is not a file" unless File.file?(@manifest_file)
         end
 
         def ast
-          @ast ||= Puppet::Pal::Compiler.new(nil).parse_file(manifest_file)
+          @ast ||= non_validating_parse_file(manifest_file)
         end
 
         def declaration
           @declaration ||= Declaration.new(ast)
         end
+
+        private
+
+        # This method gets around the normal validation performed by the regular
+        # Puppet::Pal::Compiler#parse_file method. This is necessary because, with
+        # validation enabled, the parser will raise errors during parsing if the
+        # file contains any calls to Facter. This is due to facter being disallowed
+        # in Puppet when evaluating the code in a scripting context instead of catalog
+        # compilation, which is what we are doing here.
+        def non_validating_parse_file(file)
+          @compiler.send(:internal_evaluator).parser.parse_file(file)&.model
+        end
       end
 
       class Declaration