dragnet 5.2.1

data/lib/dragnet/base_repository.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'errors/incompatible_repository_error'
+
+module Dragnet
+  # Base class for Dragnet's repository classes.
+  class BaseRepository
+    attr_reader :path
+
+    # @param [Pathname] path The path were the repository is located.
+    def initialize(path:)
+      @path = path
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def git
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def branch
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def branches
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def diff
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def head
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def remote_uri_path
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def repositories
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def branches_with(_commit)
+      incompatible_repository(__method__)
+    end
+
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    def branches_with_head
+      incompatible_repository(__method__)
+    end
+
+    private
+
+    # @param [String] message The message for the raised error.
+    # @raise [Dragnet::Errors::IncompatibleRepositoryError] Is always raised
+    #   with the given message.
+    def incompatible_repository(message)
+      raise Dragnet::Errors::IncompatibleRepositoryError, message
+    end
+  end
+end

data/lib/dragnet/cli/base.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/hash'
+require 'colorize'
+require 'thor'
+require 'yaml'
+
+require_relative 'logger'
+
+module Dragnet
+  module CLI
+    # Base class for all CLI classes.
+    class Base < Thor
+      include Thor::Actions
+
+      # Exit status codes
+      E_CONFIG_LOAD_ERROR = 1
+
+      attr_reader :configuration, :logger
+
+      class_option :configuration, aliases: :c, desc: 'Configuration file',
+                                   default: '.dragnet.yaml', required: true
+
+      class_option :quiet, aliases: :q, default: false, type: :boolean,
+                           desc: 'Suppresses all terminal output (except for critical errors)'
+
+      # Tells Thor to return an unsuccessful return code (different from 0) if
+      # an error is raised.
+      def self.exit_on_failure?
+        true
+      end
+
+      # Creates a new instance of the class. Called by Thor when a command is
+      # executed. Creates a logger for the class passing Thor's shell to it
+      # (Thor's shell handles the output to the console)
+      def initialize(*args)
+        super
+        @logger = Dragnet::CLI::Logger.new(shell)
+      end
+
+      private
+
+      # @return [String] Returns the name of the configuration file (passed via
+      #   the -c command line switch).
+      def configuration_file
+        @configuration_file ||= options[:configuration]
+      end
+
+      # Loads the configuration from the given configuration file. (This is a
+      # dumb loader, it basically loads the whole YAML file into a hash, no
+      # parsing, validation or checking takes place)
+      def load_configuration
+        logger.info "Loading configuration file #{configuration_file}..."
+        @configuration = YAML.safe_load(File.read(configuration_file)).deep_symbolize_keys
+      rescue StandardError => e
+        fatal_error("Unable to load the given configuration file: '#{configuration_file}'", e, E_CONFIG_LOAD_ERROR)
+      end
+
+      # Prints the given message alongside the message of the given exception
+      # and then terminates the process with the given exit code.
+      # @param [String] message The error message.
+      # @param [Exception] exception The exception that caused the fatal error.
+      # @param [exit_code] exit_code The exit code.
+      def fatal_error(message, exception, exit_code)
+        puts 'Error: '.colorize(:light_red) + message
+        puts "       #{exception.message}"
+        exit(exit_code)
+      end
+    end
+  end
+end

data/lib/dragnet/cli/logger.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'colorize'
+
+module Dragnet
+  module CLI
+    # A logger for the CLI. It uses the +say+ method in Thor's +Shell+ class to
+    # print the messages to the output, honoring the status of the +quiet+
+    # command line switch.
+    class Logger
+      attr_reader :shell, :log_level
+
+      LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+      DEFAULT_LOG_LEVEL = :info
+      PADDING_STRING = ' '
+      PADDING_WIDTH = 7
+
+      # Creates a new instance of the class.
+      # @param [Thor::Shell::Basic] shell A reference to Thor's +Shell+ this
+      #   will be used to send the output to the terminal in which Thor was
+      #   started.
+      # @param [Symbol] log_level The log level for the logger. The higher the
+      #   level the less output will be printed.
+      # @see LEVELS
+      def initialize(shell, log_level = DEFAULT_LOG_LEVEL)
+        raise ArgumentError, "Unknown logger level: #{log_level}" unless LEVELS.keys.include?(log_level)
+
+        @log_level = LEVELS[log_level]
+        @shell = shell
+      end
+
+      # Prints a message with log level +debug+
+      # @param [String] message The message to print
+      def debug(message)
+        output(:debug, :green, message)
+      end
+
+      # Prints a message with log level +info+
+      # @param [String] message The message to print
+      def info(message)
+        output(:info, :blue, message)
+      end
+
+      # Prints a message with log level +warn+
+      # @param [String] message The message to print
+      def warn(message)
+        output(:warn, :yellow, message)
+      end
+
+      # Prints a message with log level +error+
+      # @param [String] message The message to print
+      def error(message)
+        output(:error, :red, message)
+      end
+
+      private
+
+      # Prints the given message with the given level and text color (only the
+      # name of the level will be colored).
+      # @param [Symbol] level The log level
+      # @param [Symbol] color The color to use. One of the colors available for
+      #   the +#colorize+ method.
+      # @param [String] message The message to print.
+      # @see Colorize::InstanceMethods#colorize
+      def output(level, color, message)
+        return unless log_level <= LEVELS[level]
+
+        shell.say "#{level.to_s.capitalize}:".ljust(PADDING_WIDTH, PADDING_STRING).colorize(color) + message
+      end
+    end
+  end
+end

data/lib/dragnet/cli/master.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative '../explorer'
+require_relative '../exporter'
+require_relative '../multi_repository'
+require_relative '../repository'
+require_relative '../validator'
+require_relative '../verifier'
+require_relative '../version'
+require_relative 'base'
+
+module Dragnet
+  module CLI
+    # Entry point class for the Dragnet CLI. Includes all the commands and
+    # sub-commands of the CLI.
+    #
+    # The class should not contain any logic, everything should be delegated to
+    # helper classes as soon as possible. Only exceptions are error handling and
+    # message printing.
+    class Master < Dragnet::CLI::Base
+      E_MISSING_PARAMETER_ERROR = 2
+      E_NO_MTR_FILES_FOUND = 3
+      E_GIT_ERROR = 4
+      E_EXPORT_ERROR = 5
+      E_INCOMPATIBLE_REPOSITORY = 6
+
+      E_ERRORS_DETECTED = 16
+      E_FAILED_TESTS = 32
+
+      map %w[--version -v] => :version
+
+      desc '--version', 'Prints the current version of the Gem'
+      def version
+        say "Dragnet #{Dragnet::VERSION}"
+        say "Copyright (c) #{Time.now.year} ESR Labs GmbH esrlabs.com"
+      end
+
+      desc 'check [PATH]', 'Executes the verification procedure. '\
+           'Loads the given configuration file and executes the verify procedure on the given path '\
+           '(defaults to the value of the "path" key in the configuration file or the current '\
+           'working directory if none of them is given)'
+      method_option :export,
+                    aliases: 'e', type: :string, repeatable: true,
+                    desc: 'If given, the results of the verification procedure will be exported to'\
+                    ' the given file. The format of the export will be deducted from the given'\
+                    " file's name"
+      method_option :'multi-repo',
+                    aliases: '-m', type: :boolean, default: false,
+                    desc: 'Enables the multi-repo compatibility mode. This prevents Dragnet from assuming'\
+                    ' that [PATH] refers to a Git repository allowing it to run even if that is not the case.'\
+                    " Using this option will cause Dragnet to raise an error if it finds a MTR which doesn't"\
+                    " have a 'repos' attribute"
+      def check(path = nil)
+        load_configuration
+        self.path = path
+
+        files = explore
+        test_records, errors = validate(files)
+        verify(test_records)
+
+        export(test_records, errors) if options[:export]
+
+        exit_code = 0
+        exit_code |= E_ERRORS_DETECTED if errors.any?
+        exit_code |= E_FAILED_TESTS unless test_records.all? { |test_record| test_record.verification_result.passed? }
+
+        exit(exit_code) if exit_code.positive? # doing exit(0) will stop RSpec execution.
+      end
+
+      private
+
+      # Runs the explorer on the given path.
+      # @return [Array<Pathname>] The array of found MTR files.
+      def explore
+        glob_patterns = configuration[:glob_patterns]
+
+        begin
+          explorer = Dragnet::Explorer.new(path: path, glob_patterns: glob_patterns, logger: logger)
+          explorer.files
+        rescue ArgumentError => e
+          fatal_error('Initialization error. Missing or malformed parameter.', e, E_MISSING_PARAMETER_ERROR)
+        rescue Dragnet::Errors::NoMTRFilesFoundError => e
+          fatal_error('No MTR Files found.', e, E_NO_MTR_FILES_FOUND)
+        end
+      end
+
+      # Executes the validator on the given MTR files.
+      # @param [Array<Pathname>] files The files to run the validator on.
+      # @return [Array (Array<Dragnet::TestRecord>, Array<Hash>)] An array.
+      #   - The first element is an array of +TestRecord+s with the MTR data.
+      #     One for each valid MTR file.
+      #   - The second element contains the errors occurred during the
+      #     validation process. Can be an empty array.
+      def validate(files)
+        validator = Dragnet::Validator.new(files: files, path: path, logger: logger)
+        [validator.validate, validator.errors]
+      end
+
+      # Executes the verification on the given MTRs
+      # @param [Array<Dragnet::TestRecord>] test_records The array of MTRs on
+      #   which the verification should be executed.
+      def verify(test_records)
+        verifier = Dragnet::Verifier.new(test_records: test_records, repository: repository, logger: logger)
+        verifier.verify
+      rescue ArgumentError => e
+        fatal_error("Could not open the specified path: #{path} as a Git Repository", e, E_GIT_ERROR)
+      rescue Dragnet::Errors::IncompatibleRepositoryError => e
+        incompatible_repository_error(e)
+      end
+
+      # Executes the export process.
+      # @param [Array<Dragnet::TestRecord>] test_records The validated and
+      #   verified test records.
+      # @param [Array<Hashes>] errors The array of Hashes with the MTR files
+      #   that didn't pass the validation process.
+      def export(test_records, errors)
+        exporter = Dragnet::Exporter.new(
+          test_records: test_records, errors: errors, repository: repository, targets: options[:export], logger: logger
+        )
+
+        exporter.export
+      rescue Dragnet::Errors::UnknownExportFormatError, Dragnet::Errors::UnableToWriteReportError => e
+        fatal_error('Export failed', e, E_EXPORT_ERROR)
+      rescue Dragnet::Errors::IncompatibleRepositoryError => e
+        incompatible_repository_error(e)
+      end
+
+      # @return [Pathname] The path of the directory where the verification
+      #   process should be executed.
+      def path
+        @path || set_fallback_path
+      end
+
+      # @param [Pathname, String] path The path of the directory where the
+      #   verification process should be executed.
+      def path=(path)
+        @path = path ? Pathname.new(path) : nil
+      end
+
+      # @raise [ArgumentError] If the given path is not a valid git repository.
+      # @return [Dragnet::Repository, Dragnet::MultiRepository] One of the
+      #   possible Repository objects.
+      def repository
+        @repository ||= create_repository
+      end
+
+      # Creates the appropriate Repository object in accordance to the status of
+      # the +multi-repo+ command line option.
+      # @return [Dragnet::MultiRepository] If +multi-repo+ was set to +true+
+      # @return [Dragnet::Repository] If +multi_repo+ was set to +false+
+      def create_repository
+        options[:'multi-repo'] ? Dragnet::MultiRepository.new(path: path) : Dragnet::Repository.new(path: path)
+      end
+
+      # Prints a message and exits with the proper error code when a
+      # +Dragnet::Errors::IncompatibleRepositoryError+ is raised.
+      # @param [Dragnet::Errors::IncompatibleRepositoryError] error The raised
+      #   error.
+      def incompatible_repository_error(error)
+        fatal_error('Incompatible git operation:', error, E_INCOMPATIBLE_REPOSITORY)
+      end
+
+      # Called when no path has been given by the user explicitly. The method
+      # uses the configured path or the current working directory as a fallback.
+      # @return [Pathname] The constructed fallback path.
+      def set_fallback_path
+        # The && causes Ruby to return the value of +@path+ AFTER it has been
+        # assigned (converted to a Pathname)
+        (self.path = configuration[:path] || Dir.pwd) && @path
+      end
+    end
+  end
+end

data/lib/dragnet/cli.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'cli/master.rb'
+
+module Dragnet
+  # Namespace for the Gem's CLI
+  module CLI; end
+end

data/lib/dragnet/errors/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Dragnet
+  module Errors
+    # Base class for all errors raised by the gem.
+    class Error < StandardError; end
+  end
+end

data/lib/dragnet/errors/file_not_found_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to be raised when one of the files referenced by a MTR File
+    # doesn't exist in the repository.
+    class FileNotFoundError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/incompatible_repository_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Dragnet
+  module Errors
+    # An error to be raised when an attempt is made to perform an action on a
+    # multi-repo set-up which can only be performed on a single-repo set-up.
+    # For example, trying to perform a +diff+ operation on the multi-repo root.
+    class IncompatibleRepositoryError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/missing_timestamp_attribute_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to be raised when an attempt is made to retrieve the runtime
+    # when one or more timestamp attributes are missing.
+    class MissingTimestampAttributeError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/no_mtr_files_found_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to be raised when the +Explorer+ is unable to locate MTR files
+    # with the given glob patterns inside the specified path.
+    class NoMTRFilesFoundError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/not_a_repository_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to be raised when the path of a repository entry in a MTR with
+    # multiple repositories doesn't point to an actual git repository.
+    class NotARepositoryError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/repo_path_not_found_error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to raise when the +path+ given for a +repos+ entry cannot be found.
+    class RepoPathNotFoundError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/unable_to_write_report_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to be raised when Dragnet cannot write to one of the given export
+    # files.
+    class UnableToWriteReportError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/unknown_export_format_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to be raised when an export target file is given for which the
+    # format is unknown (cannot be deduced from its extension).
+    class UnknownExportFormatError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/validation_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'error'
+
+module Dragnet
+  module Errors
+    # An error to be raised when an attempt is made to create an entity with
+    # invalid data.
+    class ValidationError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors/yaml_format_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Dragnet
+  module Errors
+    # An error to be raised when there is a formatting problem with a YAML file.
+    # For example a missing key. (This error doesn't cover Syntax Errors)
+    class YAMLFormatError < Dragnet::Errors::Error; end
+  end
+end

data/lib/dragnet/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'errors/not_a_repository_error'
+require_relative 'errors/repo_path_not_found_error'
+
+module Dragnet
+  # Namespace to house all the error classes for the gem.
+  module Errors; end
+end

data/lib/dragnet/explorer.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative 'errors/no_mtr_files_found_error'
+
+module Dragnet
+  # This class searches for Manual Test Record files inside a given path by
+  # using the given Glob patterns.
+  class Explorer
+    attr_reader :path, :glob_patterns, :logger
+
+    # Creates a new instance of the class.
+    # @param [Pathname] path The path that should be explored.
+    # @param [String, Array<String>] glob_patterns The glob pattern or glob
+    #   patterns to use when exploring the specified path.
+    # @param [#info] logger A logger object to use for output.
+    # @raise [ArgumentError] If +path+ or +glob_patterns+ are +nil+ or if they
+    #   don't have one of the expected types.
+    def initialize(path:, glob_patterns:, logger:)
+      validate_path(path)
+      validate_patterns(glob_patterns)
+
+      @path = path
+      @glob_patterns = *glob_patterns
+      @logger = logger
+    end
+
+    # Performs the search for MTR files and returns an array with the found
+    #   files.
+    # @return [Array<Pathname>] The array of found MTR files.
+    # @raise [Dragnet::Errors::NoMTRFilesFoundError] If no MTR files are found.
+    def files
+      @files ||= find_files
+    end
+
+    private
+
+    # Raises an +ArgumentError+ with the appropriate message.
+    # @param [String] name The name of the missing parameter.
+    # @raise [ArgumentError] Is always raised with the appropriate message.
+    def missing_parameter(name)
+      raise ArgumentError, "Missing required parameter #{name}"
+    end
+
+    # Raises an +ArgumentError+ with the appropriate message.
+    # @param [String] name The name of the parameter with an incompatible type.
+    # @param [String, Class] expected The expected parameter type.
+    # @param [String, Class] given The given parameter type.
+    # @raise [ArgumentError] Is always raised with the appropriate message.
+    def incompatible_parameter(name, expected, given)
+      raise ArgumentError, "Incompatible parameter type #{name}. Expected: #{expected}, given: #{given}"
+    end
+
+    # Validates the given path
+    # @param [Object] path The path to validate
+    # @raise [ArgumentError] If the given path is nil or is not a +Pathname+.
+    def validate_path(path)
+      missing_parameter('path') unless path
+      return if path.is_a?(Pathname)
+
+      incompatible_parameter('path', Pathname, path.class)
+    end
+
+    # Validates the given glob patterns
+    # @param [String, Array<String>] glob_patterns The glob patterns
+    # @raise [ArgumentError] If +glob_patterns+ is +nil+ or it isn't an array
+    #   of strings.
+    def validate_patterns(glob_patterns)
+      missing_parameter('glob_patterns') unless glob_patterns
+
+      return if glob_patterns.is_a?(String)
+      return if glob_patterns.is_a?(Array) && glob_patterns.all? { |value| value.is_a?(String) }
+
+      incompatible_parameter('glob_patterns', 'String or Array<String>', glob_patterns.class)
+    end
+
+    # Logs the MTR files that were found.
+    # @param [Array<Pathname>] files The found MTR files.
+    # @return [Array<Pathname>] The same array given in +files+.
+    def log_found_files(files)
+      files.each { |file| logger.info("Found MTR file: #{file}") }
+    end
+
+    # Searches the +path+ for MTR files using the +glob_patterns+
+    # @return [Array<Pathname>] The array of found MTR files.
+    # @raise [Dragnet::Errors::NoMTRFilesFoundError] If no MTR files are found.
+    def find_files
+      logger.info 'Searching for Manual Test Records...'
+
+      files = []
+
+      glob_patterns.each do |glob_pattern|
+        logger.info "Globbing #{path} with #{glob_pattern}..."
+
+        files += log_found_files(path.glob(glob_pattern))
+      end
+
+      return files if files.any?
+
+      raise Dragnet::Errors::NoMTRFilesFoundError,
+            "No MTR Files found in #{path} with the following glob patterns: #{glob_patterns.join(', ')}"
+    end
+  end
+end