gitlab_internal_events_cli 0.0.1

data/lib/gitlab_internal_events_cli/flows/event_definer.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+# Entrypoint for flow to create an event definition file
+module GitlabInternalEventsCli
+  module Flows
+    class EventDefiner
+      include Helpers
+      include Text::EventDefiner
+
+      def self.schema
+        @schema ||= Helpers::SchemaLoader.load(
+          GitlabInternalEventsCli.configuration.event_schema_url,
+          'event'
+        )
+      end
+
+      STEPS = [
+        'New Event',
+        'Description',
+        'Name',
+        'Context',
+        'URL',
+        'Group',
+        'Categories',
+        'Tiers',
+        'Classification',
+        'Save files'
+      ].freeze
+
+      IDENTIFIER_FORMATTING_BUFFER = "[#{IDENTIFIER_OPTIONS.keys.map { |k| k.join(', ') }.max_by(&:length)}]".length
+
+      attr_reader :cli, :event
+
+      def initialize(cli)
+        @cli = cli
+        @event = Event.new(milestone: milestone)
+      end
+
+      def run
+        prompt_for_description
+        prompt_for_action
+        prompt_for_context
+        prompt_for_url
+        prompt_for_product_group
+        prompt_for_product_categories
+        prompt_for_tier
+        prompt_for_classification
+
+        outcome = create_event_file
+        display_result(outcome)
+
+        prompt_for_next_steps
+      end
+
+      private
+
+      def prompt_for_description
+        new_page!(on_step: 'Description', steps: STEPS)
+        cli.say DESCRIPTION_INTRO
+
+        event.description = cli.ask("Describe what the event tracks: #{input_required_text}", **input_opts) do |q|
+          q.required true
+          q.modify :trim
+          q.messages[:required?] = DESCRIPTION_HELP
+        end
+      end
+
+      def prompt_for_action
+        new_page!(on_step: 'Name', steps: STEPS)
+        cli.say ACTION_INTRO
+
+        event.action = cli.ask("Define the event name: #{input_required_text}", **input_opts) do |q|
+          q.required true
+          q.validate ->(input) { input =~ NAME_REGEX && cli.global.events.map(&:action).none?(input) }
+          q.modify :trim
+          q.messages[:valid?] = format_warning(
+            'Invalid event name. Only lowercase/numbers/underscores allowed. ' \
+            'Ensure %<value>s is not an existing event.'
+          )
+          q.messages[:required?] = ACTION_HELP
+        end
+      end
+
+      def prompt_for_context
+        new_page!(on_step: 'Context', steps: STEPS)
+        cli.say format_prompt("EVENT CONTEXT #{counter(0, 2)}")
+        prompt_for_identifiers
+
+        new_page!(on_step: 'Context', steps: STEPS)
+        cli.say format_prompt("EVENT CONTEXT #{counter(1, 2)}")
+        prompt_for_additional_properties
+      end
+
+      def prompt_for_identifiers
+        cli.say IDENTIFIERS_INTRO % event.action
+
+        identifiers = prompt_for_array_selection(
+          'Which identifiers are available when the event occurs?',
+          IDENTIFIER_OPTIONS.keys,
+          per_page: IDENTIFIER_OPTIONS.length
+        ) { |choice| format_identifier_choice(choice) }
+
+        event.identifiers = identifiers if identifiers.any?
+      end
+
+      def format_identifier_choice(choice)
+        formatted_choice = choice.empty? ? 'None' : "[#{choice.sort.join(', ')}]"
+        buffer = IDENTIFIER_FORMATTING_BUFFER - formatted_choice.length
+
+        "#{formatted_choice}#{' ' * buffer} -- #{IDENTIFIER_OPTIONS[choice]}"
+      end
+
+      def prompt_for_additional_properties
+        cli.say ADDITIONAL_PROPERTIES_INTRO
+
+        available_props = %i[label property value add_extra_prop]
+
+        while available_props.any?
+          options = property_option_definitions(available_props)
+
+          selected_property = cli.select(
+            'Which additional property do you want to add to the event?',
+            options,
+            help: format_help('(will reprompt for multiple)'),
+            **select_opts,
+            &disabled_format_callback
+          )
+
+          if selected_property == :none
+            available_props.clear
+          elsif selected_property == :add_extra_prop
+            property_name = prompt_for_add_extra_properties
+            property_description = prompt_for_text('Describe what the field will include:')
+            assign_extra_properties(property_name, property_description)
+          else
+            available_props.delete(selected_property)
+            property_description = prompt_for_text('Describe what the field will include:')
+            assign_extra_properties(selected_property, property_description)
+          end
+        end
+      end
+
+      def property_option_definitions(available_props)
+        disabled = format_help('(already defined)')
+
+        [
+          { value: :none, name: 'None! Continue to next section!' },
+          disableable_option(
+            value: :label,
+            name: 'String 1 (attribute will be named `label`)',
+            disabled: disabled
+          ) { !available_props.include?(:label) },
+          disableable_option(
+            value: :property,
+            name: 'String 2 (attribute will be named `property`)',
+            disabled: disabled
+          ) { !available_props.include?(:property) },
+          disableable_option(
+            value: :value,
+            name: 'Number (attribute will be named `value`)',
+            disabled: disabled
+          ) { !available_props.include?(:value) },
+          { value: :add_extra_prop, name: 'Add extra property (attribute will be named the input custom name)' }
+        ]
+      end
+
+      def assign_extra_properties(property, description = nil)
+        event.additional_properties ||= {}
+        event.additional_properties[property.to_s] = {
+          'description' => description || 'TODO'
+        }
+      end
+
+      def prompt_for_add_extra_properties
+        primary_props = %w[label property value]
+
+        prompt_for_text('Define a name for the attribute:', **input_opts) do |q|
+          q.required true
+          q.validate ->(input) { input =~ NAME_REGEX && primary_props.none?(input) }
+          q.modify :trim
+          q.messages[:required?] = ADDITIONAL_PROPERTIES_ADD_MORE_HELP
+          q.messages[:valid?] = format_warning(
+            'Invalid property name. Only lowercase/numbers/underscores allowed. ' \
+            'Ensure %<value>s is not one of `property, label, value`.'
+          )
+        end
+      end
+
+      def prompt_for_url
+        new_page!(on_step: 'URL', steps: STEPS)
+
+        event.introduced_by_url = prompt_for_text('Which MR URL will merge the event definition?')
+      end
+
+      def prompt_for_product_group
+        new_page!(on_step: 'Group', steps: STEPS)
+
+        product_group = prompt_for_group_ownership('Which group will own the event?')
+
+        event.product_group = product_group
+      end
+
+      def prompt_for_product_categories
+        new_page!(on_step: 'Categories', steps: STEPS)
+        cli.say <<~TEXT
+          #{format_info('FEATURE CATEGORY')}
+          Refer to https://handbook.gitlab.com/handbook/product/categories for information on current product categories.
+
+        TEXT
+
+        event.product_categories = prompt_for_feature_categories(
+          'Which feature categories best fit this event?',
+          [event.product_group]
+        )
+      end
+
+      def prompt_for_tier
+        new_page!(on_step: 'Tiers', steps: STEPS)
+
+        event.tiers = prompt_for_array_selection(
+          'Which tiers will the event be recorded on?',
+          [%w[free premium ultimate], %w[premium ultimate], %w[ultimate]]
+        )
+      end
+
+      def prompt_for_classification
+        new_page!(on_step: 'Classification', steps: STEPS)
+
+        cli.say CLASSIFICATION_INTRO
+
+        classification_choice = cli.select(
+          'Should this event have "classification: duo"?',
+          **select_opts
+        ) do |menu|
+          menu.enum '.'
+          menu.choice 'Yes - this event is related to AI/Duo features', :duo
+          menu.choice 'No - this event is not related to AI/Duo features', :none
+        end
+
+        event.classification = 'duo' if classification_choice == :duo
+      end
+
+      def create_event_file
+        new_page!(on_step: 'Save files', steps: STEPS)
+
+        prompt_to_save_file(event.file_path, event.formatted_output)
+      end
+
+      def display_result(outcome)
+        new_page!
+
+        cli.say <<~TEXT
+          #{divider}
+          #{format_info('Done with event definition!')}
+
+          #{outcome || '  No files saved.'}
+
+          #{divider}
+
+            Do you need to create a metric? Probably!
+
+            Metrics are required to pull any usage data from self-managed instances or GitLab-Dedicated through Service Ping. Collected metric data can viewed in Tableau. Individual event details from GitLab.com can also be accessed through Snowflake.
+
+            Typical flow: Define event > Define metric > Instrument app code > Merge/Deploy MR > Verify data in Tableau/Snowflake
+
+        TEXT
+      end
+
+      def prompt_for_next_steps
+        next_step = cli.select('How would you like to proceed?', **select_opts) do |menu|
+          menu.enum '.'
+
+          menu.choice 'New Event -- define another event', :new_event
+
+          full_path = GitlabInternalEventsCli.configuration.absolute_path(event.file_path)
+          choice = if File.exist?(full_path)
+                     ["Create Metric -- define a new metric using #{event.action}.yml", :add_metric]
+                   else
+                     ["Save & Create Metric -- save #{event.action}.yml and define a matching metric", :save_and_add]
+                   end
+
+          menu.default choice[0]
+          menu.choice(*choice)
+
+          menu.choice "View Usage -- look at code examples for #{event.action}.yml", :view_usage
+          menu.choice 'Exit', :exit
+        end
+
+        case next_step
+        when :new_event
+          EventDefiner.new(cli).run
+        when :add_metric
+          MetricDefiner.new(cli, event.file_path).run
+        when :save_and_add
+          write_to_file(event.file_path, event.formatted_output, 'create')
+
+          MetricDefiner.new(cli, event.file_path).run
+        when :view_usage
+          UsageViewer.new(cli, event.file_path, event).run
+        when :exit
+          cli.say feedback_notice
+        end
+      end
+    end
+  end
+end

data/lib/gitlab_internal_events_cli/flows/flow_advisor.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# Entrypoint for help flow, which directs the user to the
+# correct flow or documentation based on their goal
+module GitlabInternalEventsCli
+  module Flows
+    class FlowAdvisor
+      include Helpers
+      include Text::FlowAdvisor
+
+      attr_reader :cli
+
+      def initialize(cli)
+        @cli = cli
+      end
+
+      def run
+        return use_case_error unless goal_is_tracking_usage?
+        return use_case_error unless usage_trackable_with_internal_events?
+
+        event_already_tracked? ? proceed_to_metric_definition : proceed_to_event_definition
+      end
+
+      private
+
+      def goal_is_tracking_usage?
+        new_page!
+
+        cli.say format_info("First, let's check your objective.\n")
+
+        cli.yes?('Are you trying to track customer usage of a GitLab feature?', **yes_no_opts)
+      end
+
+      def usage_trackable_with_internal_events?
+        new_page!
+
+        cli.say format_info("Excellent! Let's check that this tool will fit your needs.\n")
+        cli.say EVENT_TRACKING_EXAMPLES
+
+        cli.yes?(
+          'Can usage for the feature be measured with a count of specific user actions or events? ' \
+          'Or counting a set of events?',
+          **yes_no_opts
+        )
+      end
+
+      def event_already_tracked?
+        new_page!
+
+        cli.say format_info("Super! Let's figure out if the event is already tracked & usable.\n")
+        cli.say EVENT_EXISTENCE_CHECK_INSTRUCTIONS
+
+        cli.yes?('Is the event already tracked?', **yes_no_opts)
+      end
+
+      def use_case_error
+        new_page!
+
+        cli.error("Oh no! This probably isn't the tool you need!\n")
+        cli.say ALTERNATE_RESOURCES_NOTICE
+        cli.say feedback_notice
+      end
+
+      def proceed_to_metric_definition
+        new_page!
+
+        cli.say format_info("Amazing! The next step is adding a new metric! (~8-15 min)\n")
+
+        return not_ready_error('New Metric') unless cli.yes?(format_prompt('Ready to start?'))
+
+        MetricDefiner.new(cli).run
+      end
+
+      def proceed_to_event_definition
+        new_page!
+
+        cli.say format_info("Okay! The next step is adding a new event! (~5-10 min)\n")
+
+        return not_ready_error('New Event') unless cli.yes?(format_prompt('Ready to start?'))
+
+        EventDefiner.new(cli).run
+      end
+
+      def not_ready_error(description)
+        cli.say "\nNo problem! When you're ready, run the CLI & select '#{description}'\n"
+        cli.say feedback_notice
+      end
+    end
+  end
+end