gitlab_internal_events_cli 0.0.1

data/lib/gitlab_internal_events_cli/helpers/event_options.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Helpers related to listing existing event definitions
+module GitlabInternalEventsCli
+  module Helpers
+    module EventOptions
+      def get_event_options(events)
+        options = events.filter_map do |(path, event)|
+          next if duplicate_events?(event.action, events.values)
+
+          description = format_help(" - #{trim_description(event.description)}")
+
+          {
+            name: "#{format_event_name(event)}#{description}",
+            value: path
+          }
+        end
+
+        options.sort_by do |option|
+          category = events.dig(option[:value], 'category')
+          internal_events = events.dig(option[:value], 'internal_events')
+
+          event_sort_param(internal_events, category, option[:name])
+        end
+      end
+
+      def events_by_filepath(event_paths = [])
+        events = cli.global.events.to_h { |event| [event.file_path, event] }
+
+        return events if event_paths.none?
+
+        events.slice(*event_paths)
+      end
+
+      private
+
+      def trim_description(description)
+        return description if description.to_s.length < 50
+
+        "#{description[0, 50]}..."
+      end
+
+      def format_event_name(event)
+        if event.internal_events || event.category == 'default'
+          event.action
+        else
+          "#{event.category}:#{event.action}"
+        end
+      end
+
+      def event_sort_param(internal_events, category, name)
+        return "0#{name}" if internal_events
+        return "1#{name}" if category == 'default'
+
+        "2#{category}#{name}"
+      end
+
+      def duplicate_events?(action, events)
+        events.count { |event| action == event.action } > 1
+      end
+    end
+  end
+end

data/lib/gitlab_internal_events_cli/helpers/files.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Helpers related reading/writing definition files
+module GitlabInternalEventsCli
+  module Helpers
+    module Files
+      MAX_FILENAME_LENGTH = 100
+
+      def absolute_path(filepath)
+        GitlabInternalEventsCli.configuration.absolute_path(filepath)
+      end
+
+      def prompt_to_save_file(filepath, content)
+        full_path = absolute_path(filepath)
+
+        cli.say <<~TEXT.chomp
+          #{format_info('Preparing to generate definition with these attributes:')}
+          #{filepath}
+          #{content}
+        TEXT
+
+        if File.exist?(full_path)
+          cli.error("Oh no! This file already exists!\n")
+
+          return if cli.no?(format_prompt('Overwrite file?'))
+
+          write_to_file(filepath, content, 'update')
+        elsif cli.yes?(format_prompt('Create file?'))
+          write_to_file(filepath, content, 'create')
+        end
+      end
+
+      def file_saved_message(verb, filepath)
+        attributes = YAML.safe_load_file(absolute_path(filepath))
+
+        format_prefix '    ', [
+          file_saved_success_message(verb, filepath),
+          file_saved_context_message(attributes),
+          file_saved_validations_message(attributes)
+        ].compact.join("\n")
+      end
+
+      def write_to_file(filepath, content, verb)
+        full_path = absolute_path(filepath)
+        dir = File.dirname(full_path)
+        FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+        File.write(full_path, content)
+
+        file_saved_message(verb, filepath).tap do |_message|
+          cli.global.reload_definitions
+        end
+      end
+
+      private
+
+      def file_saved_success_message(verb, filepath)
+        "#{format_selection(verb)} #{filepath}"
+      end
+
+      def file_saved_context_message(_attributes)
+        # Override in definition class
+      end
+
+      def file_saved_validations_message(attributes)
+        schema = self.class.respond_to?(:schema) ? self.class.schema : nil
+        return '' unless schema
+
+        errors = schema.validate(attributes).to_a
+
+        return '' unless errors.any?
+
+        <<~TEXT
+
+          #{errors.map { |e| [format_warning('!! WARNING: '), JSONSchemer::Errors.pretty(e)].join }.join("\n")}
+
+          These errors will cause validation specs to fail and should be resolved before merging your changes.
+        TEXT
+      rescue StandardError
+        ''
+      end
+    end
+  end
+end

data/lib/gitlab_internal_events_cli/helpers/formatting.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+# Helpers related to visual formatting of outputs
+module GitlabInternalEventsCli
+  module Helpers
+    module Formatting
+      DEFAULT_WINDOW_WIDTH = 100
+      DEFAULT_WINDOW_HEIGHT = 30
+
+      # When to format as "info":
+      # - When a header is needed to organize contextual
+      #   information. These headers should always be all caps.
+      # - As a supplemental way to highlight the most important
+      #   text within a menu or informational text.
+      # - Optionally, for URLs
+      def format_info(string)
+        pastel.cyan(string)
+      end
+
+      # When to format as "warning":
+      # - To highlight the first sentence/phrase describing a
+      #   problem the user needs to address. Any further text
+      #   explantion should be left unformatted.
+      # - To highlight an explanation of why the user cannot take
+      #   a particular action.
+      def format_warning(string)
+        pastel.yellow(string)
+      end
+
+      # When to format as "selection":
+      # - As a supplemental way of indicating something was
+      #   selected or the current state of an interaction.
+      def format_selection(string)
+        pastel.green(string)
+      end
+
+      # When to format as "help":
+      # - To format supplemental information on how to interact
+      #   with prompts. This should always be in parenthesis.
+      # - To indicate disabled or unavailable menu options.
+      # - To indicate meta-information in menu options or
+      #   informational text.
+      def format_help(string)
+        pastel.bright_black(string)
+      end
+
+      # When to format as "prompt":
+      # - When we need the user to input information. The text
+      #   should describe the action the user should take to move
+      #   forward, like `Input text` or `Select one`
+      # - As header text on multi-screen steps in a flow. Always
+      #   include a counter when this is the case.
+      def format_prompt(string)
+        pastel.magenta(string)
+      end
+
+      # When to format as "error":
+      # - When the CLI encounters unexpected problems that may
+      #   require broader changes by the Analytics Instrumentation
+      #   Group or out of band configuration.
+      # - To highlight special characters used to symbolize that
+      #   there was an error or that an option is not available.
+      def format_error(string)
+        pastel.red(string)
+      end
+
+      # Strips all existing color/text style
+      def clear_format(string)
+        pastel.strip(string)
+      end
+
+      # When to format as "heading":
+      # - At the beginning or end of complete flows, to create
+      #   visual separation and indicate logical breakpoints.
+      def format_heading(string)
+        [divider, pastel.cyan(string), divider].join("\n")
+      end
+
+      # Used for grouping prompts that occur on the same screen
+      # or as part of the same step of a flow.
+      #
+      # Counter is exluded if total is 1.
+      # The subject's formatting is extended to the counter.
+      #
+      # @return [String] ex) -- EATING COOKIES (2/3): Chocolate Chip --
+      # @param subject [String] describes task generically ex) EATING COOKIES
+      # @param item [String] describes specific context ex) Chocolate Chip
+      # @param count [Integer] ex) 2
+      # @param total [Integer] ex) 3
+      def format_subheader(subject, item, count = 1, total = 1)
+        formatting_end = "\e[0m"
+        suffix = formatting_end if subject[-formatting_end.length..] == formatting_end
+
+        "-- #{[subject.chomp(formatting_end), counter(count, total)].compact.join(' ')}:#{suffix} #{item} --"
+      end
+
+      def format_prefix(prefix, string)
+        string.lines.map { |line| line.prepend(prefix) }.join
+      end
+
+      # When to use a divider:
+      # - As separation between whole flows or format the layout
+      #   of a screen or the layout of CLI outputs.
+      # - Dividers should not be used to differentiate between
+      #   prompts on the same screen.
+      def divider
+        '-' * window_size
+      end
+
+      # Prints a progress bar on the screen at the current location
+      # @param current_title [String] title to highlight
+      # @param titles [Array<String>] progression to follow;
+      #     -> first element is expected to be a title for the entire flow
+      def progress_bar(current_title, titles = [])
+        step = titles.index(current_title)
+        total = titles.length - 1
+
+        raise ArgumentError, "Invalid selection #{current_title} in progress bar" unless step
+
+        status = " Step #{step} / #{total} : #{titles.join(' > ')}"
+        status.gsub!(current_title, format_selection(current_title))
+
+        total_length = window_size - 4
+        step_length = step / total.to_f * total_length
+
+        incomplete = '-' * [(total_length - step_length - 1), 0].max
+        complete = '=' * [(step_length - 1), 0].max
+
+        "#{status}\n|==#{complete}>#{incomplete}|\n"
+      end
+
+      # Formats a counter if there's anything to count
+      #
+      # @return [String, nil] ex) "(3/4)""
+      def counter(idx, total)
+        "(#{idx + 1}/#{total})" if total > 1
+      end
+
+      private
+
+      def pastel
+        @pastel ||= Pastel.new
+      end
+
+      def window_size
+        Integer(fetch_window_size)
+      rescue StandardError
+        DEFAULT_WINDOW_WIDTH
+      end
+
+      def window_height
+        Integer(fetch_window_height)
+      rescue StandardError
+        DEFAULT_WINDOW_HEIGHT
+      end
+
+      def fetch_window_size
+        `tput cols`
+      end
+
+      def fetch_window_height
+        `tput lines`
+      end
+    end
+  end
+end

data/lib/gitlab_internal_events_cli/helpers/group_ownership.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# Helpers related to Stage/Section/Group ownership
+module GitlabInternalEventsCli
+  module Helpers
+    module GroupOwnership
+      def known_categories
+        @known_categories ||= load_known_categories
+      end
+
+      def prompt_for_group_ownership(message, defaults = {})
+        if available_groups.any?
+          prompt_for_ownership_from_ssot(message, defaults)
+        else
+          prompt_for_ownership_manually(message, defaults)
+        end
+      end
+
+      def prompt_for_feature_categories(message, groups, default = nil)
+        choices = category_choices(groups)
+        valid_defaults = Array(default).compact & known_categories
+
+        categories = cli.multi_select(
+          message,
+          choices,
+          **multiselect_opts,
+          **filter_opts(header_size: 10)
+        ) do |menu|
+          menu.default(*valid_defaults) if valid_defaults.any?
+          format_disabled_options_as_dividers(menu)
+        end
+
+        categories.sort if categories.any?
+      end
+
+      def find_stage(group)
+        available_groups[group]&.fetch(:stage)
+      end
+
+      def find_section(group)
+        available_groups[group]&.fetch(:section)
+      end
+
+      def find_categories(group)
+        available_groups[group]&.fetch(:categories)
+      end
+
+      private
+
+      def load_known_categories
+        # Try local file first, fall back to remote
+        path = GitlabInternalEventsCli.configuration.absolute_path(
+          GitlabInternalEventsCli.configuration.feature_categories_path
+        )
+        return YAML.load_file(path) if File.exist?(path)
+
+        # Fall back to fetching from remote
+        fetch_remote_categories
+      rescue StandardError
+        []
+      end
+
+      def fetch_remote_categories
+        url = GitlabInternalEventsCli.configuration.feature_categories_url
+        response = HttpCache.get(url)
+        return [] unless response
+
+        YAML.safe_load(response)
+      rescue StandardError
+        []
+      end
+
+      def prompt_for_ownership_from_ssot(prompt, defaults)
+        sorted_defaults = defaults.values_at(:section, :stage, :product_group)
+        group = sorted_defaults.last
+        default = sorted_defaults.compact.join(':') # compact because not all groups have a section
+
+        cli.select(prompt, group_choices, **select_opts, **filter_opts) do |menu|
+          if group
+            if available_groups[group]
+              # We have a complete group selection -> set as default in menu
+              menu.default(default)
+            else
+              cli.error format_error(">>> Failed to find group matching #{group}. Select another.\n")
+            end
+          elsif default
+            # We have a section and/or stage in common
+            menu.instance_variable_set(:@filter, default.chars)
+          end
+        end
+      end
+
+      def prompt_for_ownership_manually(message, defaults)
+        prompt_for_text(message, defaults[:product_group])
+      end
+
+      # @return Array[<Hash - matches #prompt_for_ownership_manually output format>]
+      def group_choices
+        available_groups.map do |group, ownership|
+          {
+            name: ownership.values_at(:section, :stage, :group).compact.join(':'),
+            value: group
+          }
+        end
+      end
+
+      # Returns the list of product category options for use in
+      # select menu. Prioritizes categories from related groups.
+      def category_choices(groups)
+        options = []
+
+        # List likeliest categories for group as the first options
+        Array(groups).compact.uniq.each do |group|
+          divider = select_option_divider("Categories for #{group}")
+          categories = (find_categories(group) || []) & known_categories
+
+          options.push(divider, *categories.sort) if categories.any?
+        end
+
+        divider = select_option_divider('All categories')
+        none_option = { name: 'N/A (this definition does not correspond to any product categories)', value: nil }
+
+        options.push(divider) if options.any?
+        options.concat(known_categories)
+        options.push(none_option)
+        options.uniq
+      end
+
+      # Output looks like:
+      #   {
+      #     "import" => { stage: "manage", section: "dev", group: "import" },
+      #     ...
+      #   }
+      def available_groups
+        return @available_groups if defined?(@available_groups)
+
+        response = HttpCache.get(GitlabInternalEventsCli.configuration.stages_url)
+        return @available_groups = {} unless response
+
+        data = YAML.safe_load(response)
+
+        @available_groups = data['stages'].flat_map do |stage_name, stage_data|
+          stage_data['groups'].map do |group_name, group_data|
+            [
+              group_name,
+              {
+                group: group_name,
+                stage: stage_name,
+                section: stage_data['section'],
+                categories: group_data['categories']
+              }
+            ]
+          end
+        end.to_h
+      rescue StandardError
+        @available_groups = {}
+      end
+    end
+  end
+end