gitlab_support_readiness 1.0.11 → 1.0.12

data/lib/support_readiness/pagerduty/users.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# Defines the module Readiness.
+module Readiness
+  # Defines the module Pagerduty
+  module Pagerduty
+    ##
+    # Defines the class Users within the module {Readiness::Pagerduty}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.12
+    class Users < Readiness::Client
+      attr_accessor :avatar_url, :color, :contact_methods, :description, :email, :html_url, :id, :invitation_sent, :job_title, :license, :name, :notification_rules, :role, :self, :summary, :teams, :time_zone, :type
+
+      ##
+      # Creates a new {Readiness::Pagerduty::Users} instance
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param object [Object] An instance of {Readiness::Pagerduty::Users}
+      # @example
+      #   require 'support_readiness'
+      #   Readiness::Pagerduty::Users.new
+      def initialize(object = {})
+        @avatar_url = object['avatar_url']
+        @color = object['color']
+        @contact_methods = object['contact_methods']
+        @description = object['description']
+        @email = object['email']
+        @html_url = object['html_url']
+        @id = object['id']
+        @invitation_sent = object['invitation_sent']
+        @job_title = object['job_title']
+        @license = object['license']
+        @name = object['name']
+        @notification_rules = object['notification_rules']
+        @role = object['role']
+        @self = object['self']
+        @summary = object['summary']
+        @teams = object['teams']
+        @time_zone = object['time_zone']
+        @type = object['type']
+      end
+
+      ##
+      # Lists users within Pagerduty
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param client [Object] An instance of {Readiness::Pagerduty::Client}
+      # @return [Array]
+      # @see https://developer.pagerduty.com/api-reference/c96e889522dd6-list-users Pagerduty API > Users > List users
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Pagerduty::Configuration.new
+      #   config.token = 'abc123'
+      #   client = Readiness::Pagerduty::Client.new(config)
+      #   users = Readiness::Pagerduty::Users.list(client)
+      #   pp users.count
+      #   # => 436
+      def self.list(client)
+        array = []
+        offset = 0
+        loop do
+          response = client.connection.get "users?limit=100&offset=#{offset}"
+          body = Oj.load(response.body)
+          array += body['users'].map { |u| Users.new(u) }
+          break unless body['more']
+
+          offset += 100
+        end
+        array.uniq
+      end
+
+      ##
+      # Shows info of a Pagerduty user. This will not exit on error (except for Auth errors)
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param client [Object] An instance of {Readiness::Pagerduty::Client}
+      # @see https://developer.pagerduty.com/api-reference/2395ca1feb25e-get-a-user Pagerduty API > Users > Get a user
+      # @param uid [String] The user ID to look for
+      # @return [Hash]
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Pagerduty::Configuration.new
+      #   config.token = 'abc123'
+      #   client = Readiness::Pagerduty::Client.new(config)
+      #   user = Readiness::Pagerduty::Users.find(client, 'ABC123')
+      #   pp user.name
+      #   # => "Alice Example"
+      def self.find(client, uid)
+        response = client.connection.get("users/#{uid}")
+        handle_request_error(0, 'Pagerduty', response.status,  { action: 'get', id: uid }) unless response.status == 200
+        return Users.new(Oj.load(response.body)['user']) if response.status == 200
+
+        Oj.load(response.body)
+      end
+
+      ##
+      # Shows info of a Pagerduty user. This will exit on error
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param client [Object] An instance of {Readiness::Pagerduty::Client}
+      # @param uid [String] The user ID to look for
+      # @return [Object] An instance of {Readiness::Pagerduty::Users}
+      # @see https://developer.pagerduty.com/api-reference/2395ca1feb25e-get-a-user Pagerduty API > Users > Get a user
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Pagerduty::Configuration.new
+      #   config.token = 'abc123'
+      #   client = Readiness::Pagerduty::Client.new(config)
+      #   user = Readiness::Pagerduty::Users.find!(client, 'ABC123')
+      #   pp user.name
+      #   # => "Alice Example"
+      def self.find!(client, uid)
+        response = client.connection.get("users/#{uid}")
+        handle_request_error(1, 'Pagerduty', response.status, { action: 'Find user', id: uid }) unless response.status == 200
+        Users.new(Oj.load(response.body)['user'])
+      end
+
+      ##
+      # Shows info of a Pagerduty user using their email to find them. This will not exit on error (except Auth errors)
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param client [Object] An instance of {Readiness::Pagerduty::Client}
+      # @param email [String] The email to look for
+      # @return [Object] An instance of {Readiness::Pagerduty::Users}
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Pagerduty::Configuration.new
+      #   config.token = 'abc123'
+      #   client = Readiness::Pagerduty::Client.new(config)
+      #   user = Readiness::Pagerduty::Users.find_by_email(client, 'alice@example.com')
+      #   pp user.name
+      #   # => "Alice Example"
+      def self.find_by_email(client, email)
+        list(client).detect { |u| u.email == email }
+      end
+
+      ##
+      # Shows info of a Pagerduty user using their email to find them. This will exit on error
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param client [Object] An instance of {Readiness::Pagerduty::Client}
+      # @param email [String] The email to look for
+      # @return [Object] An instance of {Readiness::Pagerduty::Users}
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Pagerduty::Configuration.new
+      #   config.token = 'abc123'
+      #   client = Readiness::Pagerduty::Client.new(config)
+      #   user = Readiness::Pagerduty::Users.find_by_email!(client, 'alice@example.com')
+      #   pp user.name
+      #   # => "Alice Example"
+      def self.find_by_email!(client, email)
+        response = list(client).detect { |u| u.email == email }
+        handle_request_error(1, 'Pagerduty', 404, { action: 'Find user by email', id: email }) if response.nil?
+
+        response
+      end
+
+      ##
+      # Creates a user within Pagerduty. This will exit on error
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param client [Object] An instance of {Readiness::Pagerduty::Client}
+      # @param user [Object] An instance of {Readiness::Pagerduty::Users}
+      # @return [Object] An instance of {Readiness::Pagerduty::Users}
+      # @see https://developer.pagerduty.com/api-reference/4cb4fd0f5444a-create-a-user Pagerduty API > Users > Create a user
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Pagerduty::Configuration.new
+      #   config.token = 'abc123'
+      #   client = Readiness::Pagerduty::Client.new(config)
+      #   user = Readiness::Pagerduty::Users.new
+      #   user.name = 'Alice Example'
+      #   user.email = 'alice@example.com'
+      #   user.license = {
+      #     id: 'P1C3FWI',
+      #     type: 'license_reference'
+      #   }
+      #   create = Readiness::Pagerduty::Users.create!(client, user)
+      #   pp create.id
+      #   # => "ABC123"
+      def self.create!(client, user)
+        response = client.connection.post 'users', to_clean_json_with_key(user, 'user')
+        handle_request_error(1, 'Pagerduty', response.status, { action: 'Create user', id: user.email }) unless response.status == 201
+        Users.new(Oj.load(response.body)['user'])
+      end
+    end
+  end
+end

data/lib/support_readiness/pagerduty.rb

@@ -12,5 +12,6 @@ module Readiness
     require "#{__dir__}/pagerduty/escalation_policies"
     require "#{__dir__}/pagerduty/schedules"
     require "#{__dir__}/pagerduty/services"
+    require "#{__dir__}/pagerduty/users"
   end
 end

data/lib/support_readiness/repos/articles.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+# Defines the module Readiness.
+module Readiness
+  # Defines the module Repos
+  module Repos
+    ##
+    # Defines the class Articles within the module {Readiness::Repos}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.12
+    class Articles < Readiness::Client
+      def self.compare(zd_client, gl_client, instance, location = 'data', verbose = false)
+        diffs = {
+          updates: [],
+          creates: []
+        }
+        from_repo = gather(gl_client, instance, location)
+        from_zendesk = Zendesk::Articles.list(zd_client)
+        from_repo.each do |repo|
+          zd = from_zendesk.detect { |z| z.title == repo.title }
+          if zd.nil?
+            diffs[:creates].push(repo)
+          else
+            comparable = zd.dup
+            comparable.id = nil
+            diffs[:updates].push(update_object(repo, zd)) if to_clean_json(repo) != to_clean_json(comparable)
+            detailed_diff(repo, comparable) if verbose && to_clean_json(repo) != to_clean_json(comparable)
+          end
+        end
+        report_diffs(diffs) if verbose
+        diffs
+      end
+
+      ##
+      # Outputs a comparison report
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param diffs [Hash] The returned value of {compare}
+      def self.report_diffs(diffs)
+        puts 'Compare report:'
+        puts "- Creates: #{diffs[:creates].count}"
+        puts "- Updates: #{diffs[:updates].count}"
+      end
+
+      ##
+      # Outputs a comparison report
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param repo [Object] An instance of {Readiness::Zendesk::Automations}
+      # @param zendesk [Object] An instance of {Readiness::Zendesk::Automations}
+      def self.detailed_diff(repo, zendesk)
+        puts "Detailed diff of #{repo.title}"
+        repo.instance_variables.each do |v|
+          next if v == :@id
+
+          if repo.instance_variable_get(v) != zendesk.instance_variable_get(v)
+            if v == :@body
+              puts "- #{v} Repo and #{v} Zendesk differ"
+            else
+              puts "- #{v} Repo:"
+              pp repo.instance_variable_get(v)
+              puts "  #{v} Zendesk:"
+              pp zendesk.instance_variable_get(v)
+            end
+          end
+        end
+      end
+
+      ##
+      # Creates an instance of {Readiness::Zendesk::Automations} to use for updates
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param repo [Object] An instance of {Readiness::Zendesk::Automations}
+      # @param zendesk [Object] An instance of {Readiness::Zendesk::Automations}
+      # @return [Object]
+      def self.update_object(repo, zendesk)
+        object = repo
+        object.id = zendesk.id
+        object
+      end
+
+      ##
+      # Parses repo article files
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param gl_client [Object] An instance of {Readiness::GitLab::Client}
+      # @param instance [String] The Zendesk instance being worked with. Accepted values are:
+      #   - Global
+      #   - Global Sandbox
+      #   - US Government
+      #   - US Government Sandbox
+      # @param location [String] The location (relative or absolute) of the repo's data folder
+      # @return [Array]
+      # @example
+      #   require 'support_readiness'
+      #   gl_config = Readiness::GitLab::Configuration.new
+      #   gl_config.token = ENV.fetch('GL_TOKEN')
+      #   gl_client = Readiness::GitLab::Client.new(gl_config)
+      #   repo = Readiness::Repos::Articles.gather(gl_client, 'Global', 'automations/data')
+      #   pp repo.count
+      #   # => 15
+      def self.gather(gl_client, instance = 'Global', location = 'data')
+        @errors = []
+        @gl_client = gl_client
+        @instance = instance
+        @location = location
+        array = []
+        Dir["#{@location}/articles/**/*.yaml"].each do |f|
+          object = YAML.safe_load_file(f)
+          object['body'] = full_conversion(object)
+          validity_check(f, object)
+          object['id'] = nil
+          array.push(Zendesk::Articles.new(object))
+        end
+        repo_check(array)
+        report_errors unless @errors.count.zero?
+        array
+      end
+
+      ##
+      # Outputs an error report and exits with a status code of 1
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      def self.report_errors
+        puts 'The following errors were found in the repo files:'
+        @errors.each do |e|
+          puts "- #{e}"
+        end
+        puts 'Rectify the errors and retry. We cannot proceed with those errors occurring.'
+        exit 1
+      end
+
+      ##
+      # Performs basic checks on the repo
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param objects [Array] The Array of Hashes derived from parsing the repo files
+      def self.repo_check(objects)
+        duplicate_names = objects.group_by { |o| o.title }.select { |k, v| v.size > 1 }.map(&:first)
+        unless duplicate_names.count.zero?
+          duplicate_names.each do |d|
+            @errors.push("The title '#{d}' is used in multiple files")
+          end
+        end
+      end
+
+      ##
+      # Performs a full conversion on the article's body
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param object [Hash]
+      # @return [String]
+      def self.full_conversion(object)
+        html = markdown_to_html(object)
+        @doc = Nokogiri::HTML.fragment(html)
+        rearrange_anchors
+        replace_modifiers
+        @doc.to_html
+      end
+
+      ##
+      # Converts the manasged content file's markdown to html
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param object [Hash]
+      # @return [String]
+      def self.markdown_to_html(object)
+        markdown = File.readlines("#{@location}/managed_content/pages/#{object['content_path']}")
+        body = replace_internal_links(markdown, object)
+        html = Readiness::GitLab::Markdown.convert(@gl_client, body, true, 'gitlab-com/support/support-pages' )
+        data_object_dom(object) + html
+      end
+
+      ##
+      # Returns the data_object_dom String
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param object [Hash]
+      # @return [String]
+      def self.data_object_dom(object)
+        <<~STRING
+          <p id="data_object_dom" style="display: none;" data-path="pages/#{object['content_path']}">&nbsp;</p>
+        STRING
+      end
+
+      ##
+      # Replaces internal links with their external values
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param object [Hash]
+      # @return [String]
+      def self.replace_internal_links(lines, object)
+        lines.each_with_index do |line, index|
+          line.scan(/{{LINK:\ ([^}]+)}}/).each do |matches|
+            matches.each do |m|
+              parts = m.split('#')
+              anchor = determine_anchor(parts)
+              lines[index] = line.gsub("{{LINK: #{m}}}", support_url("#{find_file(parts.first)['id']}#{anchor}", object))
+            end
+          end
+        end
+        lines.join
+      end
+
+      ##
+      # Locates the correct YAML content
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param path [String]
+      # @return [Hash]
+      def self.find_file(path)
+        raw_yaml.detect { |y| y['content_path'] =~ /#{path}/ }
+      end
+
+      ##
+      # Determiens the correct anchor for a String
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param parts [Array]
+      # @return [String]
+      def self.determine_anchor(parts)
+        return '' if parts.count == 1
+
+        "##{parts.last}"
+      end
+
+      ##
+      # Placeholder functiont to set the global variable @raw_yaml
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @return [Array]
+      def self.raw_yaml
+        @raw_yaml ||= determine_raw_yaml
+      end
+
+      ##
+      # Function to set the default value for the @raw_yaml global variable
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @return [Array]
+      def self.determine_raw_yaml
+        array = []
+        Dir["#{@location}/articles/**/*.yaml"].each do |f|
+          array.push(YAML.safe_load_file(f))
+        end
+        array
+      end
+
+      ##
+      # Returns the external URL for a link
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param endpoint [String]
+      # @param yaml [Hash]
+      # @return [String]
+      def self.support_url(endpoint, yaml)
+        return "##{endpoint.split('#').last}" if endpoint.split('#').first.to_i == yaml['id'].to_i
+        return "https://support.gitlab.com/hc/en-us/articles/#{endpoint}" if @instance == 'Global'
+        return "https://gitlab1707170878.zendesk.com/hc/en-us/articles/#{endpoint}" if @instance == 'Global Sandbox'
+        return "https://federal-support.gitlab.com/hc/en-us/articles/#{endpoint}" if @instance == 'US Government'
+        return "https://gitlabfederalsupport1585318082.zendesk.com/hc/en-us/articles/#{endpoint}" if @instance == 'US Government Sandbox'
+
+        handle_request_error(1, 'Zendesk', 404, { action: 'Find ZD instance', id: @instance })
+      end
+
+      ##
+      # Rearranges anchors into the correct format
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      def self.rearrange_anchors
+        %w[h1 h2 h3 h4 h5 h6].each do |h|
+          headers = @doc.css(h)
+          next if headers.count.zero?
+
+          headers.each do |header|
+            anchor = header.children.at_css '.anchor'
+            anchor['name'] = anchor['href'].gsub('#', '')
+            text = header.children.last
+            text.add_next_sibling(anchor)
+          end
+        end
+      end
+
+      ##
+      # Replaces internal modifiers with their external values
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      def self.replace_modifiers
+        @doc.children.each do |children|
+          next unless children.to_s =~ /{{([^}]+)}}/
+
+          children.each do |child|
+            current = child.parent.get_attribute('class').to_s.split
+            current.push(child.to_s[/{{([^}]+)}}/, 1])
+            child.parent.set_attribute('class', current.join(' '))
+            child.content = child.to_s.gsub(/{{([^}]+)}}/, '')
+          end
+        end
+      end
+
+      ##
+      # Performs basic checks on a repo file
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param file [String] The path to the repo file
+      # @param object [Hash] The Hash derived from parsing a YAML file
+      def self.validity_check(file, object)
+        folder = file.split("#{@location}/").last.split('/').first
+        @errors.push("Missing position: #{file}") if object['position'].nil?
+        @errors.push("Missing title: #{file}") if object['title'].nil?
+        @errors.push("Inactive article in active folder: #{file}") if folder == 'active' && object['draft']
+        @errors.push("Active article in inactive folder: #{file}") if folder == 'inactive' && !object['draft']
+      end
+    end
+  end
+end