dragnet 5.2.1

data/lib/dragnet/repository.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+require_relative 'base_repository'
+
+module Dragnet
+  # A small wrapper around a Git Repository object. It provides some useful
+  # methods needed during the verify process as well as for reporting.
+  class Repository < Dragnet::BaseRepository
+    extend Forwardable
+
+    attr_reader :git
+
+    def_delegators :@git, :branch, :branches, :diff
+
+    # Creates a new instance of the class. Tries to open the given path as a Git
+    # repository.
+    # @param [Pathname] path The path where the root of the repository is located.
+    # @raise [ArgumentError] If the given path is not a valid git repository.
+    def initialize(path:)
+      super
+      @git = Git.open(path)
+    end
+
+    # @return [Git::Object::Commit] The +Commit+ object at the +HEAD+ of the
+    #   repository.
+    def head
+      @head ||= git.object('HEAD')
+    end
+
+    # Returns the URI path of the repository (extracted from its first remote
+    # [assumed to be the origin]). Example:
+    #
+    #   ssh://jenkins@gerrit.int.esrlabs.com:29418/tools/dragnet -> /tools/dragnet
+    #
+    # @return [String] The URI path of the repository
+    def remote_uri_path
+      URI.parse(git.remotes.first.url).path
+    end
+
+    # @return [FalseClass] It always returns false
+    def multi?
+      false
+    end
+
+    # Returns an array of all the branches that include the given commit.
+    # @param [String] commit The SHA1 of the commit to look for.
+    # @return [Array<Git::Branch>] An array with all the branches that contain
+    #   the given commit.
+    def branches_with(commit)
+      branches.select { |branch| branch.contains?(commit) }
+    end
+
+    # Returns an array of all the branches that include the current HEAD.
+    # @return [Array<Git::Branch>] An array with all the branches that contain
+    #   the current HEAD.
+    def branches_with_head
+      @branches_with_head ||= branches_with(head.sha)
+    end
+
+    private
+
+    # @param [Symbol] method_name The name of the method that was invoked.
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    #   with a description of the method that was invoked and a possible cause
+    #   for the failure.
+    def incompatible_repository(method_name)
+      super(
+        "Failed to perform the action '#{method_name}' on '#{path}'."\
+        ' The path was not set-up as a multi-repo path. If you are running'\
+        ' without the --multi-repo command line switch make sure that none of'\
+        " your MTRs have a 'repos' attribute or run with the --multi-repo switch"
+      )
+    end
+  end
+end

data/lib/dragnet/test_record.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'validators/entities/test_record_validator'
+
+module Dragnet
+  # Represents a Manual Test Record loaded from a MTR file.
+  class TestRecord
+    PASSED_RESULT = 'passed'
+    REVIEWED_STATUS = 'reviewed'
+    NO_FINDINGS = 'no findings'
+
+    # :reek:Attribute (This is an entity class)
+
+    attr_accessor :id, :result, :sha1, :name, :description, :files, :repos,
+                  :review_status, :review_comments, :findings, :test_method,
+                  :tc_derivation_method, :source_file, :verification_result
+
+    # rubocop:disable Metrics/AbcSize (There isn't much that can be done here,
+    #   those are the attributes an MTR has).
+    # :reek:FeatureEnvy (Refers to args as much as it refers to itself)
+
+    # Creates a new instance of the class.
+    # @param [Hash] args The data for the Manual Test Record
+    # @option args [String] :id The ID of the MTR
+    # @option args [String] :result The result of the Manual Test.
+    # @option args [String] :sha1 The SHA1 of the commit in which the Manual
+    #   Test was performed.
+    # @option args [String, Array<String>, nil] :name The name of the person who
+    #   performed the Manual Test.
+    # @option args [String, nil] :description The description of the Manual
+    #   Test, normally which actions were performed and what it was mean to
+    #   test.
+    # @option args [String, Array<String>, nil] :files The files involved in the
+    #   MTR, these are the files which will be checked for changes when
+    #   evaluating the validity of the MTR.
+    # @option args [Array<Hash>, nil] :repos An array of +Hash+es with the
+    #   information about the repositories that are involved in the MTR, these
+    #   repositories will be checked for changes during the evaluation of the
+    #   MTR.
+    # @option args [String, nil] :review_status or :reviewstatus The review
+    #   status of the MTR. (Normally changed when someone other than the tester
+    #   verifies the result of the Manual Test)
+    # @option args [String, nil] :review_comments or :reviewcomments The
+    #   comments left by the person who performed the review of the Manual Test.
+    # @option args [String, nil] :findings The findings that the reviewer
+    #   collected during the review process (if any).
+    # @option args [String, Array<String>, nil] :test_method The method(s) used
+    #   to carry out the test.
+    # @option args [String, Array<String>, nil] :tc_derivation_method: The
+    #   method(s) used to derive the test case,
+    # @note Either +:files+ or +:repos+ should be present, not both.
+    def initialize(args)
+      @id = args[:id]
+      @result = args[:result]
+      @sha1 = args[:sha1]
+      @name = args[:name]
+      @description = args[:description]
+      @files = args[:files]
+      @repos = args[:repos]
+      @review_status = args[:review_status] || args[:reviewstatus]
+      @review_comments = args[:review_comments] || args[:reviewcomments]
+      @findings = args[:findings]
+      @test_method = args[:test_method]
+      @tc_derivation_method = args[:tc_derivation_method]
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Validates the MTR's fields
+    # @raise [Dragnet::Errors::ValidationError] If the validation fails.
+    def validate
+      Dragnet::Validators::Entities::TestRecordValidator.new(self).validate
+    end
+
+    # @return [Boolean] True if the Manual Test passed, false otherwise.
+    def passed?
+      result == PASSED_RESULT
+    end
+
+    # @return [Boolean] True if the Manual Test Record has been reviewed, false
+    #   otherwise.
+    def reviewed?
+      review_status == REVIEWED_STATUS
+    end
+
+    # @return [Boolean] True if the Manual Test Record has findings (problems
+    #   annotated during the review), false otherwise.
+    def findings?
+      !(findings.nil? || findings.strip.empty? || findings.downcase == NO_FINDINGS)
+    end
+  end
+end

data/lib/dragnet/validator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'colorize'
+
+require_relative 'validators/data_validator'
+require_relative 'validators/files_validator'
+require_relative 'validators/repos_validator'
+
+module Dragnet
+  # Validates a set of Manual Test Record files. That means, checking that they
+  # can be read, that they are valid YAML files, that they have the expected
+  # keys and that these keys have sensible values.
+  class Validator
+    attr_reader :files, :path, :logger, :errors, :valid_files
+
+    # Creates a new instance of the class.
+    # @param [Array<Pathname>] files An array with the MTR files to validate.
+    # @param [Pathname] path The path where the MTR files are located.
+    # @param [#info, #error] logger A logger object to use for output.
+    def initialize(files:, path:, logger:)
+      @files = files
+      @path = path
+      @logger = logger
+    end
+
+    # Validates the given files.
+    # @return [Array<Dragnet::TestRecord>] An array of +TestRecord+s, one for
+    #   each valid MTR file (invalid files will be added to the +errors+ array).
+    #   The returned hash has the following structure:
+    def validate
+      logger.info('Validating MTR Files...')
+
+      @errors = []
+      @valid_files = files.map { |file| validate_file(file) }.compact
+    end
+
+    private
+
+    # Validates the given file
+    # @param [Pathname] file The file to be validated.
+    # @return [Dragnet::TestRecord, nil] A +TestRecord+ object or +nil+ if the
+    #   file is invalid.
+    # rubocop:disable Metrics/AbcSize (because of logging).
+    def validate_file(file)
+      logger.info "Validating #{file}..."
+      data = YAML.safe_load(File.read(file))
+      test_record = Dragnet::Validators::DataValidator.new(data, file).validate
+      Dragnet::Validators::FilesValidator.new(test_record, path).validate
+      Dragnet::Validators::ReposValidator.new(test_record, path).validate
+
+      logger.info "#{'✔ SUCCESS'.colorize(:light_green)} #{file} Successfully loaded"
+      test_record
+    rescue SystemCallError => e
+      push_error(file, 'IO Error: Cannot read the specified file', e)
+    rescue Psych::Exception => e
+      push_error(file, 'YAML Parsing Error', e)
+    rescue Dragnet::Errors::YAMLFormatError => e
+      push_error(file, 'YAML Formatting Error', e)
+    rescue Dragnet::Errors::FileNotFoundError => e
+      push_error(file, 'Referenced file not found in repository', e)
+    rescue Dragnet::Errors::RepoPathNotFoundError => e
+      push_error(file, 'Referenced repository not found', e)
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Pushes an entry into the +errors+ array.
+    # @param [Pathname] file The file that contains the error.
+    # @param [String] message A general description of the message.
+    # @param [Exception] exception The raised exception (through which the file
+    #   was branded invalid)
+    # @return [nil] Returns nil so that +validate_file+ can return nil for
+    #   invalid files.
+    def push_error(file, message, exception)
+      errors << { file: file, message: message, exception: exception }
+      logger.error "#{'✘ FAILED'.colorize(:light_red)} #{file} Failed: #{message} - #{exception.message}"
+      nil
+    end
+  end
+end

data/lib/dragnet/validators/data_validator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/hash/keys'
+
+require_relative '../test_record'
+require_relative 'validator'
+
+module Dragnet
+  module Validators
+    # Validates the data (key-value pairs) inside an MTR file. Verifies the
+    # structure, the required keys and their types.
+    class DataValidator < Dragnet::Validators::Validator
+      attr_reader :data, :source_file
+
+      # Creates a new instance of the class
+      # @param [Hash] data The data inside the YAML (after parsing)
+      # @param [Pathname] source_file The path to the file from which the MTR
+      #   data was loaded.
+      def initialize(data, source_file)
+        @data = data
+        @source_file = source_file
+      end
+
+      # Validates the given data
+      # @return [Dragnet::TestRecord] A +TestRecord+ object created
+      #   from the given data (if the data was valid).
+      # @raise [Dragnet::Errors::YAMLFormatError] If the data is invalid. The
+      #   raised exceptions contains a message specifying why the data is
+      #   invalid.
+      def validate
+        yaml_format_error("Incompatible data structure. Expecting a Hash, got a #{data.class}") unless data.is_a?(Hash)
+        data.deep_symbolize_keys!
+
+        # A call to chomp for strings is needed because the following YAML
+        # syntax:
+        #
+        # findings: >
+        #      no findings
+        #
+        # causes the string values to end with a newline ("\n"):
+        data.transform_values! { |value| value.is_a?(String) ? value.chomp : value }
+        test_record = create_mtr(data)
+        validate_mtr(test_record)
+      end
+
+      private
+
+      # @param [Hash] data A hash with the data for the +TestRecord+
+      # @see Dragnet::TestRecord#initialize
+      def create_mtr(data)
+        Dragnet::TestRecord.new(data).tap do |test_record|
+          test_record.source_file = source_file
+        end
+      end
+
+      # Creates a +Dragnet::TestRecord+ with the given data and runs its
+      # validation. If the validation is successful the +TestRecord+
+      # object is returned, if the validation fails an error is raised.
+      # @param [Dragnet::TestRecord] test_record The +TestRecord+ object to
+      #   validate.
+      # @return [Dragnet::TestRecord] The given +TestRecord+ object if the
+      #   validation passed.
+      # @raise [Dragnet::Errors::YAMLFormatError] If the data is invalid. The
+      #   raised exceptions contains a message specifying why the data is
+      #   invalid.
+      def validate_mtr(test_record)
+        test_record.validate
+        test_record
+      rescue Dragnet::Errors::ValidationError => e
+        yaml_format_error(e.message)
+      end
+    end
+  end
+end

data/lib/dragnet/validators/entities/repo_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../fields/sha1_validator'
+require_relative '../fields/files_validator'
+require_relative '../fields/path_validator'
+
+module Dragnet
+  module Validators
+    module Entities
+      # Validates a +Dragnet::Repo+ object, by checking its attributes.
+      class RepoValidator
+        attr_reader :repo
+
+        # @param [Dragnet::Repo] repo An instance of +Dragnet::Repo+ to validate.
+        def initialize(repo)
+          @repo = repo
+        end
+
+        # Validates the instance of the +Dragnet::Repo+ object by checking each
+        # of its attributes.
+        # @raise [Dragnet::Errors::ValidationError] If any of the fields in the
+        #   given +Dragnet::Repo+ object fails the validation.
+        def validate
+          Dragnet::Validators::Fields::SHA1Validator.new.validate('repos[sha1]', repo.sha1)
+          Dragnet::Validators::Fields::PathValidator.new.validate('repos[path]', repo.path)
+          repo.files = Dragnet::Validators::Fields::FilesValidator.new.validate('repos[files]', repo.files)
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/entities/test_record_validator.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../fields/description_validator'
+require_relative '../fields/files_validator'
+require_relative '../fields/id_validator'
+require_relative '../fields/meta_data_field_validator'
+require_relative '../fields/repos_validator'
+require_relative '../fields/result_validator'
+require_relative '../fields/sha1_validator'
+
+require_relative '../../errors/validation_error'
+
+module Dragnet
+  module Validators
+    module Entities
+      # Validates a MTR object
+      class TestRecordValidator
+        attr_reader :test_record
+
+        # Creates a new instance of the class.
+        # @param [Dragnet::TestRecord] test_record The test record to validate.
+        def initialize(test_record)
+          @test_record = test_record
+        end
+
+        # Validates the given test record
+        # @raise [Dragnet::Errors::ValidationError] If the validation fails.
+        def validate
+          repos_xor_files
+          repos_xor_sha1
+
+          Dragnet::Validators::Fields::IDValidator.new.validate('id', test_record.id)
+          Dragnet::Validators::Fields::DescriptionValidator.new.validate('description', test_record.description)
+          validate_meta_data_fields
+
+          test_record.files = Dragnet::Validators::Fields::FilesValidator.new.validate('files', test_record.files)
+          test_record.result = Dragnet::Validators::Fields::ResultValidator.new.validate('result', test_record.result)
+        end
+
+        private
+
+        # @raise [Dragnet::Errors::ValidationError] If the MTR has both a
+        #   +files+ and a +repos+ attribute.
+        def repos_xor_files
+          return unless test_record.files && test_record.repos
+
+          raise Dragnet::Errors::ValidationError,
+                "Invalid MTR: #{test_record.id}. Either 'files' or 'repos' should be provided, not both"
+        end
+
+        # Executes the validation over the +repos+ attribute and then verifies
+        # if the +sha1+ attribute was also given. If it was, an error is
+        # raised. If +repos+ is not present, then the +sha1+ attribute is
+        # validated.
+        #
+        # This happens in this order to leverage the fact that the
+        # +ReposValidator+ returns +nil+ for empty +Array+s. So if +repos+ is
+        # given as en empty +Array+ the MTR will still be considered valid
+        # (provided it has a SHA1).
+        #
+        # @raise [Dragnet::Errors::ValidationError] If the validation of the
+        #   +repos+ attribute fails, if both +repos+ and +sha1+ are present or
+        #   if the validation of the +sha1+ attribute fails.
+        def repos_xor_sha1
+          test_record.repos = Dragnet::Validators::Fields::ReposValidator.new.validate('repos', test_record.repos)
+
+          unless test_record.repos
+            Dragnet::Validators::Fields::SHA1Validator.new.validate('sha1', test_record.sha1)
+            return
+          end
+
+          return unless test_record.sha1
+
+          raise Dragnet::Errors::ValidationError,
+                "Invalid MTR: #{test_record.id}. Either 'repos' or 'sha1' should be provided, not both"
+        end
+
+        # Validates the meta-data fields of the Test Record.
+        # @raise [Dragnet::Errors::ValidationError] If any of the meta-data
+        #   fields fail the validation.
+        def validate_meta_data_fields
+          meta_data_validator = Dragnet::Validators::Fields::MetaDataFieldValidator.new
+
+          test_record.name = meta_data_validator.validate('name', test_record.name)
+          test_record.test_method = meta_data_validator.validate('test_method', test_record.test_method)
+          test_record.tc_derivation_method = meta_data_validator.validate(
+            'tc_derivation_method', test_record.tc_derivation_method
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/entities.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'entities/repo_validator'
+require_relative 'entities/test_record_validator'
+
+module Dragnet
+  module Validators
+    # Namespace for Dragnet's Entity Validators (validators that deal with data
+    # objects / models).
+    module Entities; end
+  end
+end

data/lib/dragnet/validators/fields/description_validator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'field_validator'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Validates the +description+ field for a MTR.
+      class DescriptionValidator < Dragnet::Validators::Fields::FieldValidator
+        # Validates a MTR's description
+        # @param [String] key The name of the key
+        # @param [Object] value The value of the key
+        # @raise [Dragnet::Errors::ValidationError] If the description contains
+        #   anything but a +String+ or +nil+.
+        # :reek:NilCheck (Only +nil+ is allowed, +false+ should be considered invalid).
+        def validate(key, value)
+          return if value.nil?
+
+          validate_type(key, value, String)
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields/field_validator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative '../../errors/validation_error'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Base class for all the validators used to validate individual fields
+      # inside entities.
+      class FieldValidator
+        def validate(_key, _value)
+          raise NotImplementedError, "#validate method not implemented in #{self.class}"
+        end
+
+        private
+
+        # Validates the presence of a value
+        # @param [String, Symbol] key The key associated with the value.
+        # @param [Object] value The value to validate.
+        # @raise [Dragnet::Errors::ValidationError] If the given value is not
+        #   present (i.e. is +nil+)
+        def validate_presence(key, value)
+          validation_error("Missing required key: #{key}") if value.nil?
+        end
+
+        # Validates the type of the given value.
+        # @param [String, Symbol] key The key associated with the value.
+        # @param [Object] value The value to validate.
+        # @param [Array<Class>] expected_types The allowed types for the given
+        #   value.
+        # @raise [Dragnet::Errors::ValidationError] If the given value has a type
+        #   which is not in the given array of expected types.
+        def validate_type(key, value, *expected_types)
+          return if expected_types.include?(value.class)
+
+          validation_error(
+            "Incompatible type for key #{key}: "\
+            "Expected #{expected_types.join(', ')} got #{value.class} instead"
+          )
+        end
+
+        # Raises a +Dragnet::Errors::ValidationError+ with the given message.
+        # @param [String] message The message for the error.
+        # @raise [Dragnet::Errors::ValidationError] Is always raised.
+        def validation_error(message)
+          raise Dragnet::Errors::ValidationError, message
+        end
+
+        # Validates that all elements inside the given array are of the
+        # expected type
+        # @param [String, Symbol] key The key associated with the array.
+        # @param [Array] array The array whose types should be checked.
+        # @param [Class] expected_type The type the elements inside the array
+        #   should have.
+        # @raise [Dragnet::Errors::ValidationError] If any of the elements inside
+        #   the given array is of a different type.
+        def validate_array_types(key, array, expected_type)
+          incompatible_value = array.find { |val| !val.is_a?(expected_type) }
+          return unless incompatible_value
+
+          validation_error(
+            "Incompatible type for key #{key}: Expected a Array<#{expected_type}>. "\
+            "Found a(n) #{incompatible_value.class} inside the array"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields/files_validator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'field_validator'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Validates the files field on a Manual Test Record
+      class FilesValidator < Dragnet::Validators::Fields::FieldValidator
+        # Validates the MTR's +files+ array.
+        # @param [String] key The name of the key
+        # @param [Object] value The value of the key
+        # @return [Array<String>, nil] If +files+ is an Array or a String then
+        #   an array is returned, if +files+ is +nil+ then +nil+ is returned.
+        # @raise [Dragnet::Errors::ValidationError] If the +files+ key is not a
+        #   +String+ or an +Array+ of +String+s.
+        def validate(key, value)
+          return unless value
+
+          validate_type(key, value, String, Array)
+          value = *value
+          validate_array_types(key, value, String)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields/id_validator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'field_validator'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Validates the ID Field for Manual Test Records
+      class IDValidator < Dragnet::Validators::Fields::FieldValidator
+        # Validates the Requirement ID(s) of the MTR
+        # @param [String] key The name of the key
+        # @param [Object] value The value of the key
+        # @raise [Dragnet::Errors::ValidationError] If the Requirement ID(s) are
+        #   missing, they are not a String or an Array of Strings if they contain
+        #   a disallowed character or (in the case of an Array) any of its
+        #   elements is not a String.
+        def validate(key, value)
+          validate_presence(key, value)
+          validate_type(key, value, String, Array)
+
+          if value.is_a?(String)
+            match = value.match(/,|\s/)
+            return unless match
+
+            validation_error(
+              "Disallowed character '#{match}' found in the value for key #{key}. "\
+              'To use multiple requirement IDs please put them into an array'
+            )
+          else
+            validate_array_types(key, value, String)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields/meta_data_field_validator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'field_validator'
+require_relative '../../errors/validation_error'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Base class to validate the fields that are part of the meta-data group.
+      # This means: Either +String+ +Array<String>+ or +nil+ as value.
+      class MetaDataFieldValidator < Dragnet::Validators::Fields::FieldValidator
+        # Validates the specified attribute as a meta-data field.
+        # @param [String] key The name of the key
+        # @param [Object] value The value of the key
+        # @raise [Dragnet::Errors::ValidationError] If the attribute fails the
+        #   validation.
+        # @return [nil] If +value+ is +nil+ or an empty array.
+        # @return [Array<String>] If +value+ is a +String+ or an +Arry<String>+
+        def validate(key, value)
+          return unless value
+
+          validate_type(key, value, String, Array)
+
+          if value.is_a?(Array)
+            return if value.empty?
+
+            validate_array_types(key, value, String)
+            value
+          else
+            [value]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dragnet/validators/fields/path_validator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'field_validator'
+
+module Dragnet
+  module Validators
+    module Fields
+      # Validates the +path+ attribute of a +Repo+ object.
+      class PathValidator < Dragnet::Validators::Fields::FieldValidator
+        # Validates the Path of the repository.
+        # @param [String] key The name of the key
+        # @param [Object] value The value of the key
+        # @raise [Dragnet::Errors::ValidationError] If the path is missing, or
+        #   it isn't a String.
+        def validate(key, value)
+          validate_presence(key, value)
+          validate_type(key, value, String)
+        end
+      end
+    end
+  end
+end