emerge 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8b51ab2fab1683825f19ebb9be0eb07b7901cb49d194adcfcb3488ebf17440dd
+  data.tar.gz: cb8d2ead013d712c99e5213a7d4d39cac1b2ad67afa0d51aaed3b06e86a43605
+SHA512:
+  metadata.gz: 1360c8d0acde63b549d69c23468fdd24b7c4a37e399988faec47e88060d9edf7e9abf945657f6deaa4af052c9b9cc307b6f4cd2c5eefe741bc3e9cce4dbff1b0
+  data.tar.gz: 7c515b04f02ef2c28e9452f9edeb36d62bf4754fe52c0a78b727b202c233a1291d418cab3d341e2eab527afd7fd5ffc77726b2e7af85c46693538fc273cfd3c6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2024-XX-XX
+
+- Initial release

data/README.md

@@ -0,0 +1,94 @@
+# Emerge CLI
+
+The official CLI for Emerge Tools.
+
+[Emerge](https://emergetools.com) offers a suite of products to help optimize app size, performance, and quality by detecting regressions before they make it to production. This plugin provides a set of actions to interact with the Emerge API.
+
+## Installation
+
+This tool is packaged as a Ruby Gem which can be installed by:
+
+```
+gem install emerge
+```
+
+## API Key
+
+Follow our guide to obtain an [API key](https://docs.emergetools.com/docs/uploading-basics#obtain-an-api-key) for your organization. The API Token is used by the CLI to authenticate with the Emerge API. The CLI will automatically pick up the API key if configured as an `EMERGE_API_TOKEN` environment variable, or you can manually pass it into individual commands.
+
+## Snapshots
+
+Uploads a directory of images to be used in [Emerge Snapshot Testing](https://docs.emergetools.com/docs/snapshot-testing).
+
+Run `emerge upload snapshots -h` for a full list of supported options.
+
+Example:
+
+```shell
+emerge upload snapshots \
+  --name "AwesomeApp" \
+  --id "com.emerge.awesomeapp" \
+  --repo-name "EmergeTools/AwesomeApp" \
+  path/to/snapshot/images
+```
+
+### Git Configuration
+
+For CI diffs to work, Emerge needs the appropriate Git `sha` and `base_sha` values set on each build. Emerge will automatically compare a build at `sha` against the build we find matching the `base_sha` for a given application id. We also recommend setting `pr_number`, `branch`, and `repo_name` for the best experience.
+
+For example:
+
+- `sha`: `pr-branch-commit-1`
+- `base_sha`: `main-branch-commit-1`
+- `pr_number`: `42`
+- `branch`: `my-awesome-feature`
+- `repo_name`: `EmergeTools/hackernews`
+
+Will compare the snapshot diffs of your pull request changes.
+
+This plugin will automatically configure Git values for you assuming certain Github workflow triggers:
+
+```yaml
+on:
+  # Produce base builds with a 'sha' when commits are pushed to the main branch
+  push:
+    branches: [main]
+
+  # Produce branch comparison builds with `sha` and `base_sha` when commits are pushed
+  # to open pull requests
+  pull_request:
+    branches: [main]
+  ...
+```
+
+If this doesn't cover your use-case, manually set the `sha` and `base_sha` values when calling the Emerge plugin.
+
+### Using with swift-snapshot-testing
+
+Snapshots generated via [swift-snapshot-testing](https://github.com/pointfreeco/swift-snapshot-testing) are natively supported by the CLI by setting `--client-library swift-snapshot-testing` and a `--project-root` directory. This will scan your project for all images found in `__Snapshot__` directories.
+
+Example:
+
+```shell
+emerge upload snapshots \
+  --name "AwesomeApp swift-snapshot-testing" \
+  --id "com.emerge.awesomeapp.swift-snapshot-testing" \
+  --repo-name "EmergeTools/AwesomeApp" \
+  --client-library swift-snapshot-testing \
+  --project-root /my/awesomeapp/ios/repo
+```
+
+### Using with Paparazzi
+
+Snapshots generated via [Paparazzi](https://github.com/cashapp/paparazzi) are natively supported by the CLI by setting `--client-library paparazzi` and a `--project-root` directory. This will scan your project for all images found in `src/test/snapshots/images` directories.
+
+Example:
+
+```shell
+emerge upload snapshots \
+  --name "AwesomeApp Paparazzi" \
+  --id "com.emerge.awesomeapp.paparazzi" \
+  --repo-name "EmergeTools/AwesomeApp" \
+  --client-library paparazzi \
+  --project-root /my/awesomeapp/android/repo
+```

data/exe/emerge

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/emerge_cli'
+
+Dry::CLI.new(EmergeCLI).call

data/lib/commands/config/snapshots/snapshots_ios.rb

@@ -0,0 +1,235 @@
+require 'dry/cli'
+require 'json'
+require 'uri'
+require 'chunky_png'
+require 'async'
+require 'async/barrier'
+require 'async/semaphore'
+require 'async/http/internet/instance'
+require 'yaml'
+
+require 'tty-prompt'
+require 'tty-table'
+
+module EmergeCLI
+  module Commands
+    module Config
+      class SnapshotsIOS < EmergeCLI::Commands::GlobalOptions
+        desc 'Configure snapshot testing for iOS'
+
+        # Optional options
+        option :interactive, type: :boolean, required: false,
+                             desc: 'Run interactively'
+        option :clear, type: :boolean, required: false, desc: 'Clear existing configuration'
+        option :os_version, type: :string, required: true, desc: 'OS version'
+        option :launch_arguments, type: :array, required: false, desc: 'Launch arguments to set'
+        option :env_variables, type: :array, required: false, desc: 'Environment variables to set'
+        option :exact_match_excluded_previews, type: :array, required: false, desc: 'Exact match excluded previews'
+        option :regex_excluded_previews, type: :array, required: false, desc: 'Regex excluded previews'
+
+        # Constants
+        EXCLUDED_PREVIEW_PROMPT = 'Do you want to exclude any previews by exact match?'.freeze
+        EXCLUDED_PREVIEW_FINISH_PROMPT = 'Enter the previews you want to exclude (leave blank to finish)'.freeze
+        EXCLUDED_REGEX_PREVIEW_PROMPT = 'Do you want to exclude any previews by regex?'.freeze
+        EXCLUDED_REGEX_PREVIEW_FINISH_PROMPT = 'Enter the previews you want to exclude (leave blank to finish)'.freeze
+        ARGUMENTS_PROMPT = 'Do you want to set any arguments?'.freeze
+        ARGUMENTS_FINISH_PROMPT = 'Enter the argument you want to set (leave blank to finish)'.freeze
+        ENV_VARIABLES_PROMPT = 'Do you want to set any environment variables?'.freeze
+        ENV_VARIABLES_FINISH_PROMPT = "Enter the environment variable you want to set (leave blank to finish) with \
+format KEY=VALUE".freeze
+        AVAILABLE_OS_VERSIONS = ['17.2', '17.5', '18.0'].freeze
+
+        def initialize; end
+
+        def call(**options)
+          @options = options
+          before(options)
+
+          Sync do
+            validate_options
+
+            run_interactive_mode if @options[:interactive]
+
+            run_non_interactive_mode if !@options[:interactive]
+
+            Logger.warn 'Remember to copy `emerge_config.yml` to your project XCArchive before uploading it!'
+          end
+        end
+
+        private
+
+        def validate_options
+          if @options[:interactive] && (!@options[:os_version].nil? || !@options[:launch_arguments].nil? ||
+             !@options[:env_variables].nil? || !@options[:exact_match_excluded_previews].nil? ||
+             !@options[:regex_excluded_previews].nil?)
+            Logger.warn 'All options are ignored when using interactive mode'
+          end
+        end
+
+        def run_interactive_mode
+          prompt = TTY::Prompt.new
+
+          override_config = false
+          if File.exist?('emerge_config.yml')
+            Logger.warn 'There is already a emerge_config.yml file.'
+            prompt.yes?('Do you want to overwrite it?', default: false) do |answer|
+              override_config = true if answer
+            end
+          end
+
+          if !override_config && File.exist?('emerge_config.yml')
+            config = YAML.load_file('emerge_config.yml')
+            config['snapshots']['ios']['runSettings'] = []
+          else
+            config = {
+              'version' => 2.0,
+              'snapshots' => {
+                'ios' => {
+                  'runSettings' => []
+                }
+              }
+            }
+          end
+
+          Logger.info 'Creating a new config file'
+
+          end_config = false
+          loop do
+            os_version = get_os_version(prompt)
+
+            excluded_previews = get_array_from_user(prompt, EXCLUDED_PREVIEW_PROMPT, EXCLUDED_PREVIEW_FINISH_PROMPT)
+            excluded_regex_previews = get_array_from_user(prompt, EXCLUDED_REGEX_PREVIEW_PROMPT,
+                                                          EXCLUDED_REGEX_PREVIEW_FINISH_PROMPT)
+            arguments_array = get_array_from_user(prompt, ARGUMENTS_PROMPT, ARGUMENTS_FINISH_PROMPT)
+            env_variables_array = get_array_from_user(prompt, ENV_VARIABLES_PROMPT, ENV_VARIABLES_FINISH_PROMPT)
+
+            excluded = get_parsed_previews(excluded_previews, excluded_regex_previews)
+            env_variables = get_parsed_env_variables(env_variables_array)
+
+            os_settings = {
+              'osVersion' => os_version,
+              'excludedPreviews' => excluded,
+              'envVariables' => env_variables,
+              'arguments' => arguments_array
+            }
+            show_config(os_settings)
+            save = prompt.yes?('Do you want to save this setting?')
+            config['snapshots']['ios']['runSettings'].push(os_settings) if save
+
+            end_config = !prompt.yes?('Do you want to continue adding more settings?')
+            break if end_config
+          end
+
+          File.write('emerge_config.yml', config.to_yaml)
+          Logger.info 'Configuration file created successfully!'
+        end
+
+        def run_non_interactive_mode
+          config = {}
+          if File.exist?('emerge_config.yml')
+            config = YAML.load_file('emerge_config.yml')
+            if !@options[:clear] && !config['snapshots'].nil? && !config['snapshots']['ios'].nil? &&
+               !config['snapshots']['ios']['runSettings'].nil?
+              raise 'There is already a configuration file with settings. Use the --clear flag to overwrite it.'
+            end
+
+            config['snapshots']['ios']['runSettings'] = []
+
+          else
+            config = {
+              'version' => 2.0,
+              'snapshots' => {
+                'ios' => {
+                  'runSettings' => []
+                }
+              }
+            }
+          end
+
+          excluded_previews = get_parsed_previews(@options[:exact_match_excluded_previews] || [],
+                                                  @options[:regex_excluded_previews] || [])
+          env_variables = get_parsed_env_variables(@options[:env_variables] || [])
+
+          os_version = @options[:os_version]
+          if os_version.nil?
+            Logger.warn 'No OS version was provided, defaulting to 17.5'
+            os_version = '17.5'
+          end
+
+          os_settings = {
+            'osVersion' => os_version,
+            'excludedPreviews' => excluded_previews,
+            'envVariables' => env_variables,
+            'arguments' => @options[:launch_arguments] || []
+          }
+          config['snapshots']['ios']['runSettings'].push(os_settings)
+          File.write('emerge_config.yml', config.to_yaml)
+          Logger.info 'Configuration file created successfully!'
+          show_config(os_settings)
+        end
+
+        def get_os_version(prompt)
+          os_version = prompt.select('Select the OS version you want to run the tests on') do |answer|
+            AVAILABLE_OS_VERSIONS.each do |version|
+              answer.choice version, version.to_f
+            end
+            answer.choice 'Custom', 'custom'
+          end
+          os_version = prompt.ask('Enter the OS version you want to run the tests on') if os_version == 'custom'
+          os_version
+        end
+
+        def get_array_from_user(prompt, first_prompt_message, second_prompt_message)
+          continue = prompt.yes?(first_prompt_message)
+          return [] if !continue
+          array = []
+          loop do
+            item = prompt.ask(second_prompt_message)
+            if item == '' || item.nil?
+              continue = false
+            else
+              array.push(item)
+            end
+            break unless continue
+          end
+          array
+        end
+
+        def show_config(config)
+          table = TTY::Table.new(
+            header: %w[Key Value],
+            rows: config.to_a
+          )
+          puts table.render(:ascii)
+        end
+
+        def get_parsed_previews(previews_exact, previews_regex)
+          excluded = []
+          previews_exact.each do |preview|
+            excluded.push({
+                            'type' => 'exact',
+                            'value' => preview
+                          })
+          end
+          previews_regex.each do |preview|
+            excluded.push({
+                            'type' => 'regex',
+                            'value' => preview
+                          })
+          end
+          excluded
+        end
+
+        def get_parsed_env_variables(env_variables)
+          env_variables_array_fixed = []
+          env_variables.each do |env_variable|
+            key, value = env_variable.split('=')
+            env_variables_array_fixed.push({
+                                             'key' => key, 'value' => value
+                                           })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/commands/global_options.rb

@@ -0,0 +1,15 @@
+require 'dry/cli'
+require 'logger'
+
+module EmergeCLI
+  module Commands
+    class GlobalOptions < Dry::CLI::Command
+      option :debug, type: :boolean, default: false, desc: 'Enable debug logging'
+
+      def before(args)
+        log_level = args[:debug] ? ::Logger::DEBUG : ::Logger::INFO
+        EmergeCLI::Logger.configure(log_level)
+      end
+    end
+  end
+end

data/lib/commands/integrate/fastlane.rb

@@ -0,0 +1,124 @@
+require 'dry/cli'
+require 'fileutils'
+
+module EmergeCLI
+  module Commands
+    module Integrate
+      class Fastlane < EmergeCLI::Commands::GlobalOptions
+        desc 'Integrate Emerge into your iOS project via Fastlane'
+
+        argument :path, type: :string, required: false, default: '.',
+                        desc: 'Project path (defaults to current directory)'
+
+        def call(path: '.', **_options)
+          @project_path = File.expand_path(path)
+          Logger.info "Project path: #{@project_path}"
+
+          Logger.info '🔍 Detecting project type...'
+          detector = ProjectDetector.new(@project_path)
+
+          if detector.ios_project?
+            Logger.info '📱 iOS project detected!'
+            setup_ios
+          else
+            Logger.error "❌ Error: Could not detect project. Make sure you're in the root directory of an iOS project."
+            exit 1
+          end
+        end
+
+        private
+
+        def setup_ios
+          Logger.info 'Setting up Emerge Tools for iOS project using Fastlane...'
+
+          setup_gemfile
+          setup_fastfile
+
+          # Install Emerge Fastlane plugin
+          Logger.info 'Installing Emerge Fastlane plugin...'
+          system('fastlane add_plugin emerge')
+
+          print_ios_completion_message
+        end
+
+        def setup_gemfile
+          gemfile_path = File.join(@project_path, 'Gemfile')
+          if File.exist?(gemfile_path)
+            Logger.info 'Updating existing Gemfile...'
+            current_content = File.read(gemfile_path)
+            current_content << "\ngem 'fastlane'" unless current_content.include?('gem "fastlane"')
+            current_content << "\ngem 'xcpretty'" unless current_content.include?('gem "xcpretty"')
+            File.write(gemfile_path, current_content)
+          else
+            Logger.error 'No Gemfile found. Please follow the Fastlane setup instructions before running this.'
+            exit 1
+          end
+
+          Logger.info 'Installing gems...'
+          system('bundle install')
+        end
+
+        def setup_fastfile
+          fastfile_dir = File.join(@project_path, 'fastlane')
+          FileUtils.mkdir_p(fastfile_dir)
+          fastfile_path = File.join(fastfile_dir, 'Fastfile')
+
+          if File.exist?(fastfile_path)
+            Logger.info 'Updating existing Fastfile...'
+            update_existing_fastfile(fastfile_path)
+          else
+            Logger.error 'No Fastfile found. Please follow the Fastlane setup instructions before running this.'
+            exit 1
+          end
+        end
+
+        def update_existing_fastfile(fastfile_path)
+          current_content = File.read(fastfile_path)
+
+          # Add platform :ios block if not present
+          current_content += "\nplatform :ios do\nend\n" unless current_content.match?(/platform\s+:ios\s+do/)
+
+          # Add app_size lane if not present
+          unless current_content.match?(/^\s*lane\s*:app_size\s*do/)
+            app_size_lane = <<~'RUBY'.gsub(/^/, '  ')
+              lane :app_size do
+                # NOTE: If you already have a lane setup to build your app, then you can that instead of this and call emerge() after it.
+                build_app(scheme: ENV["SCHEME_NAME"], export_method: "development")
+                emerge(tag: ENV['EMERGE_BUILD_TYPE'] || "default")
+              end
+            RUBY
+            current_content.sub!(/platform\s+:ios\s+do.*$/) { |match| "#{match}\n#{app_size_lane}" }
+          end
+
+          # Add snapshots lane if not present
+          unless current_content.match?(/^\s*lane\s*:build_upload_emerge_snapshot\s*do/)
+            snapshot_lane = <<~'RUBY'.gsub(/^/, '  ')
+              desc 'Build and upload snapshot build to Emerge Tools'
+              lane :build_upload_emerge_snapshot do
+                emerge_snapshot(scheme: ENV["SCHEME_NAME"])
+              end
+            RUBY
+            current_content.sub!(/lane\s+:app_size\s+do.*?end/m) { |match| "#{match}\n\n#{snapshot_lane}" }
+          end
+
+          # Clean up any multiple blank lines
+          current_content.gsub!(/\n{3,}/, "\n\n")
+
+          File.write(fastfile_path, current_content)
+        end
+
+        def command_exists?(command)
+          system("which #{command} > /dev/null 2>&1")
+        end
+
+        def print_ios_completion_message
+          Logger.info "✅ iOS setup complete! Don't forget to:"
+          Logger.info '1. Set your EMERGE_API_TOKEN environment variable (both locally and in your CI/CD pipeline)'
+          Logger.info '2. Set your SCHEME_NAME environment variable'
+          Logger.info "3. Run 'fastlane app_size' to analyze your app"
+          Logger.info "4. Run 'fastlane build_upload_emerge_snapshot' to analyze your snapshots"
+        end
+      end
+    end
+  end
+end

data/lib/commands/upload/snapshots/client_libraries/default.rb

@@ -0,0 +1,26 @@
+module EmergeCLI
+  module Commands
+    module Upload
+      module ClientLibraries
+        class Default
+          def initialize(image_paths)
+            @image_paths = image_paths
+          end
+
+          def image_files
+            @image_paths.flat_map { |path| Dir.glob("#{path}/**/*.png") }
+          end
+
+          def parse_file_info(image_path)
+            file_name = File.basename(image_path)
+            {
+              file_name:,
+              group_name: File.basename(image_path, '.*'),
+              variant_name: nil
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/commands/upload/snapshots/client_libraries/paparazzi.rb

@@ -0,0 +1,29 @@
+module EmergeCLI
+  module Commands
+    module Upload
+      module ClientLibraries
+        class Paparazzi
+          def initialize(project_root)
+            @project_root = project_root
+          end
+
+          def image_files
+            # TODO: support "paparazzi.snapshot.dir" dynamic config
+            Dir.glob(File.join(@project_root, '**/src/test/snapshots/images/**/*.png'))
+          end
+
+          def parse_file_info(image_path)
+            file_name = image_path.split('src/test/snapshots/images/').last
+            test_class_name = File.basename(File.dirname(image_path))
+
+            {
+              file_name:,
+              group_name: test_class_name, # TODO: add support for nicer group names
+              variant_name: File.basename(file_name, '.*')
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/commands/upload/snapshots/client_libraries/swift_snapshot_testing.rb

@@ -0,0 +1,28 @@
+module EmergeCLI
+  module Commands
+    module Upload
+      module ClientLibraries
+        class SwiftSnapshotTesting
+          def initialize(project_root)
+            @project_root = project_root
+          end
+
+          def image_files
+            Dir.glob(File.join(@project_root, '**/__Snapshots__/**/*.png'))
+          end
+
+          def parse_file_info(image_path)
+            file_name = image_path.split('__Snapshots__/').last
+            test_class_name = File.basename(File.dirname(image_path))
+
+            {
+              file_name:,
+              group_name: test_class_name.sub(/Tests$/, ''),
+              variant_name: File.basename(file_name, '.*')
+            }
+          end
+        end
+      end
+    end
+  end
+end