gitlab_support_readiness 1.0.11 → 1.0.13

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

data/lib/support_readiness/repos/automations.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# Defines the module Readiness.
+module Readiness
+  # Defines the module Repos
+  module Repos
+    ##
+    # Defines the class Automations within the module {Readiness::Repos}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.12
+    class Automations < Readiness::Client
+      ##
+      # Compares the repo automation files to the Zendesk instance automations
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param zendesk_client [Object] An instance of {Readiness::Zendesk::Client}
+      # @param location [String] The location (relative or absolute) of the repo's data folder
+      # @param verbose [Boolean] Whether you want a detailed report or not
+      # @return [Hash]
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   diffs = Readiness::Repos::Automations.compare(client, 'automations/data', false)
+      #   pp diffs[:updates.count]
+      #   # => 5
+      # @example
+      #   require 'support_readiness'
+      #   config = Readiness::Zendesk::Configuration.new
+      #   config.username = 'alice@example.com'
+      #   config.token = 'test123abc'
+      #   config.url = 'https://example.zendesk.com/api/v2'
+      #   client = Readiness::Zendesk::Client.new(config)
+      #   diffs = Readiness::Repos::Automations.compare(client, 'automations/data', true)
+      #   # => Detailed diff of Status::Close::Close solved tickets after 7 days
+      #   # => - @default Repo:
+      #   # => false
+      #   # =>   @default Zendesk:
+      #   # => true
+      #   # => Compare report:
+      #   # => - Creates: 0
+      #   # => - Updates: 1
+      #   pp diffs[:updates.count]
+      #   # => 1
+      def self.compare(zendesk_client, location = 'data', verbose = false)
+        diffs = {
+          updates: [],
+          creates: []
+        }
+        from_repo = gather(location)
+        from_zendesk = Zendesk::Automations.list(zendesk_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)
+            puts "- #{v} Repo:"
+            pp repo.instance_variable_get(v)
+            puts "  #{v} Zendesk:"
+            pp zendesk.instance_variable_get(v)
+          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 automation files
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param location [String] The location (relative or absolute) of the repo's data folder
+      # @return [Array]
+      # @example
+      #   require 'support_readiness'
+      #   repo = Readiness::Repos::Automations.gather('automations/data')
+      #   pp repo.count
+      #   # => 35
+      def self.gather(location = 'data')
+        @errors = []
+        @location = location
+        array = []
+        Dir["#{@location}/**/*.yaml"].each do |f|
+          object = YAML.safe_load_file(f)
+          object = convert_managed_content(object) if object['contains_managed_content']
+          object = convert_managed_webhook(object) if object['contains_managed_webhook']
+          validity_check(f, object)
+          object['id'] = nil
+          array.push(Zendesk::Automations.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 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 automation in active folder: #{file}") if folder == 'active' && !object['active']
+        @errors.push("Active automation in inactive folder: #{file}") if folder == 'inactive' && object['active']
+      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 conversions for a repo file if using managed content
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param object [Hash] The Hash derived from parsing a YAML file
+      def self.convert_managed_content(object)
+        path = "#{@location}/managed_content/#{object['title']}.md"
+        handle_request_error(1, 'Repos', 404, { action: 'Get managed content', id: object['title'] }) unless File.exist?(path)
+        object['actions'].each_with_index do |action, index|
+          if action['value'].is_a?(String)
+            if action['value'] =~ /MANAGED_CONTENT/
+              if action['value'] == 'MANAGED_CONTENT'
+                object['actions'][index]['value'] = action['value'].gsub('MANAGED_CONTENT', File.read(path).chomp)
+              else
+                object['actions'][index]['value'] = action['value'].gsub('MANAGED_CONTENT', File.read(path).chomp.gsub("\n", '\\n'))
+              end
+            end
+          elsif action['value'].is_a?(Array)
+            action['value'].each_with_index do |value, sub_index|
+              if value =~ /MANAGED_CONTENT/
+                if value == 'MANAGED_CONTENT'
+                  object['actions'][index]['value'][sub_index] = value.gsub('MANAGED_CONTENT', File.read(path).chomp)
+                else
+                  object['actions'][index]['value'][sub_index] = value.gsub('MANAGED_CONTENT', File.read(path).chomp.gsub("\n", '\\n'))
+                end
+              end
+            end
+          end
+        end
+        object
+      end
+
+      ##
+      # Performs conversions for a repo file if using managed webhooks
+      #
+      # @author Jason Colyer
+      # @since 1.0.12
+      # @param object [Hash] The Hash derived from parsing a YAML file
+      def self.convert_managed_webhook(object)
+        path = "#{@location}/managed_content/#{object['title']}.webhook"
+        handle_request_error(1, 'Repos', 404, { action: 'Get managed webhook', id: object['title'] }) unless File.exist?(path)
+        object['actions'].each_with_index do |action, index|
+          next unless action['value'].is_a?(Array)
+
+          action['value'].each_with_index do |value, sub_index|
+            next unless value == 'MANAGED_WEBHOOK'
+
+            object['actions'][index]['value'][sub_index] = JSON.parse(File.read(path))
+          end
+        end
+        object
+      end
+    end
+  end
+end