ruby_raider 4.1.0 → 4.2.0

data/lib/generators/templates/flows/run.tt

@@ -1,332 +0,0 @@
-# frozen_string_literal: true
-
-require 'English'
-require 'fileutils'
-require 'json'
-require 'time'
-require 'tmpdir'
-
-# One run of a flow: a per-flow lock, a results folder and one line in .raider/flows/<name>/runs.jsonl.
-# flows/flow_helper.rb starts it, so `raider flow run`, plain rspec, the desktop app and a schedule all
-# leave the same record. Generated by `raider flow init`.
-module RaiderFlows
-  module Run
-    NAME = /\A[a-z0-9_]{1,60}\z/.freeze
-    RESERVED = %w[env].freeze # .raider/flows/env is the secrets file, not a flow's log folder
-    INPUT = /\A[a-z][a-z0-9_]{0,39}\z/.freeze
-    ENV_KEY = /\A[A-Z_][A-Z0-9_]*\z/.freeze
-    RUN_ID = /\A[0-9a-f]{16}\z/.freeze
-    RESULTS_STAMP = /\A\d{8}T\d{6}Z(?:-\d+)?\z/.freeze
-    TRIGGERS = %w[manual schedule desktop].freeze
-    KEEP_LINES = 50
-    KEEP_RESULTS = 20
-    MAX_RUN_JSON_BYTES = 10 * 1024 * 1024
-    MAX_ENV_BYTES = 64 * 1024
-    MIN_SECRET = 4
-    ENV_FILE = '.raider/flows/env'
-    NOFOLLOW = defined?(File::NOFOLLOW) ? File::NOFOLLOW : 0
-    NONBLOCK = defined?(File::NONBLOCK) ? File::NONBLOCK : 0
-    ROOT = File.expand_path('../..', __dir__)
-
-    class << self
-      attr_reader :name, :results_dir
-
-      # At require time, before the driver or the reporter start. Exits 3 when the flow is already running.
-      def start!
-        # `rspec --dry-run` runs nothing, so it takes no lock and leaves no record
-        return if @name || RSpec.configuration.dry_run?
-
-        root = File.realpath(ROOT)
-        @name = flow_name
-        @root = root
-        @started_at = now
-        @secrets = []
-        busy! unless lock
-        stop_on_interrupt
-        # Registered as soon as the lock is held, so even a failure below leaves its line. It runs after
-        # RSpec and the reporter finished (run.json is written), whatever way the run ended.
-        at_exit { finish!(exit_status($ERROR_INFO)) }
-        @results_dir = new_results_dir
-        load_env_file
-        headless
-      end
-
-      # RSpec would finish the whole flow on a first Ctrl-C and exit! (no run log line) on a second. The first
-      # one ends the current step instead, so the run is recorded and spec_helper still quits the driver;
-      # a second one is ignored while that happens, and a third quits at once (no run log line).
-      def stop_on_interrupt
-        presses = 0
-        trap('INT') do
-          presses += 1
-          raise Interrupt, 'flow stopped' if presses == 1
-
-          presses == 2 ? say('stopping: press Ctrl-C again to quit at once') : exit!(130)
-        end
-      end
-
-      # RAIDER_FLOW_HEADED=1 drops a HEADLESS left in the shell; config.yml headless: true still wins
-      def headless
-        if ENV['RAIDER_FLOW_HEADED'] == '1'
-          ENV.delete('HEADLESS')
-        else
-          ENV['HEADLESS'] ||= 'true'
-        end
-      end
-
-      # Flow results go to flow-results/<name>/<UTC stamp>, never raider-results, and are never cleaned
-      def configure_reporter
-        return unless defined?(RaiderReporter)
-
-        RaiderReporter.configure do |reporter|
-          reporter.output_dir = results_dir || (@fallback_dir ||= Dir.mktmpdir('raider-flow-'))
-          reporter.clean_output_dir = false
-        end
-      end
-
-      def steps_started!
-        @steps_started = true
-      end
-
-      def finish!(code)
-        return unless @lock
-
-        append(record(code))
-        prune
-      rescue StandardError => e
-        say("could not write the run log: #{e.class}")
-      ensure
-        release
-      end
-
-      private
-
-      def now
-        Time.now.utc
-      end
-
-      def say(message)
-        $stderr.puts("[raider flow] #{message}") # rubocop:disable Style/StderrPuts -- -W0 must not hide these
-      end
-
-      def flow_name
-        flows = RSpec.configuration.files_to_run.select { |file| file.end_with?('_flow.rb') }
-        raise ArgumentError, 'run one flow at a time: rspec flows/<name>_flow.rb' unless flows.one?
-
-        name = File.basename(flows.first, '_flow.rb')
-        raise ArgumentError, "invalid flow name #{name.inspect}" unless NAME.match?(name) && !RESERVED.include?(name)
-
-        wanted = ENV.fetch('RAIDER_FLOW_NAME', name)
-        raise ArgumentError, "RAIDER_FLOW_NAME is #{wanted.inspect} but the flow is #{name.inspect}" unless wanted == name
-
-        name
-      end
-
-      def lock
-        file = File.join(private_dir('.raider/flows'), "#{name}.lock")
-        handle = File.open(file, File::RDWR | File::CREAT | NOFOLLOW, 0o600)
-        return @lock = handle if handle.flock(File::LOCK_EX | File::LOCK_NB)
-
-        handle.close
-        nil
-      end
-
-      def release
-        @lock&.close
-        @lock = nil
-      end
-
-      def busy!
-        append(base_line.merge(finished_at: iso(now), status: 'busy', results_dir: nil))
-        say("#{name} is already running")
-        exit 3
-      end
-
-      # A 0700 folder inside the project that is not a link
-      def private_dir(relative)
-        dir = File.join(@root, relative)
-        FileUtils.mkdir_p(dir)
-        raise IOError, "#{relative} must be a folder, not a link" unless File.lstat(dir).directory?
-
-        File.chmod(0o700, dir)
-        dir
-      end
-
-      def new_results_dir
-        base = File.join(@root, 'flow-results', name, now.strftime('%Y%m%dT%H%M%SZ'))
-        dir = base
-        suffix = 1
-        dir = "#{base}-#{suffix += 1}" while File.exist?(dir)
-        FileUtils.mkdir_p(dir)
-        dir
-      end
-
-      # KEY=value lines, # comments, no interpolation. Loaded only from a regular file you own with mode 600.
-      # RAIDER_FLOW_* keys are the wrapper's, so the file can't set them.
-      def load_env_file
-        content = read_env_file
-        return unless content
-
-        content.each_line.with_index(1) do |raw, number|
-          line = raw.dup.force_encoding(Encoding::UTF_8)
-          line = line.valid_encoding? ? line.strip : nil
-          next if line&.empty? || line&.start_with?('#')
-
-          key, value = line&.split('=', 2)&.map(&:strip)
-          unless value && ENV_KEY.match?(key.to_s) && !key.to_s.start_with?('RAIDER_FLOW_')
-            say("#{ENV_FILE} line #{number} ignored: expected KEY=value")
-            next
-          end
-          set_env(key.to_s, unquote(value))
-        end
-      end
-
-      def read_env_file
-        File.open(File.join(@root, ENV_FILE), File::RDONLY | NONBLOCK | NOFOLLOW) do |file|
-          stat = file.stat
-          return say("ignored #{ENV_FILE}: it must be a regular file you own") unless owned_file?(stat)
-          return say("ignored #{ENV_FILE}: permissions must be 600") unless private_mode?(stat)
-
-          file.read(MAX_ENV_BYTES).to_s
-        end
-      rescue Errno::ENOENT
-        nil
-      rescue SystemCallError
-        say("ignored #{ENV_FILE}: it must be a regular file you own")
-      end
-
-      # Windows has no POSIX owner or mode bits, so there the folder's ACLs decide who can read the file:
-      # keep the project under your user profile, or restrict the file with icacls
-      def owned_file?(stat)
-        stat.file? && (Gem.win_platform? || stat.uid == Process.uid)
-      end
-
-      def private_mode?(stat)
-        Gem.win_platform? || (stat.mode & 0o077).zero?
-      end
-
-      # A value already in the environment wins; both are kept out of the run log
-      def set_env(key, value)
-        ENV[key] = value unless ENV.key?(key)
-        [value, ENV.fetch(key)].each { |secret| @secrets << secret if secret.length >= MIN_SECRET }
-      end
-
-      def unquote(value)
-        quoted = value.length >= 2 && value[0] == value[-1] && ['"', "'"].include?(value[0])
-        quoted ? value[1...-1].to_s : value
-      end
-
-      def exit_status(error)
-        case error
-        when nil then 0
-        when SystemExit then error.status
-        else 1
-        end
-      end
-
-      def base_line
-        {
-          started_at: iso(@started_at),
-          attempt: [Integer(ENV.fetch('RAIDER_FLOW_ATTEMPT', '1'), 10, exception: false) || 1, 1].max,
-          trigger: TRIGGERS.include?(ENV.fetch('RAIDER_FLOW_TRIGGER', nil)) ? ENV.fetch('RAIDER_FLOW_TRIGGER') : 'manual',
-          run_id: RUN_ID.match?(ENV.fetch('RAIDER_FLOW_RUN_ID', '')) ? ENV.fetch('RAIDER_FLOW_RUN_ID') : nil
-        }.compact
-      end
-
-      def record(code)
-        status = outcome(code)
-        line = base_line.merge(finished_at: iso(now), status: status, results_dir: relative(results_dir))
-        line[:failed_step] = failed_step if status == 'failed'
-        line
-      end
-
-      def outcome(code)
-        statuses = RSpec.world.all_examples.map { |example| example.execution_result.status }
-        return 'completed' if code.zero? && statuses.include?(:passed) && !statuses.include?(:failed)
-        return 'failed' if @steps_started && statuses.include?(:failed)
-
-        'setup_error'
-      end
-
-      # The first failed example: its line in the flow file and the recorded step, when the desktop's sidecar named it
-      def failed_step
-        example = RSpec.world.all_examples.find { |each| each.execution_result.status == :failed }
-        return nil unless example
-
-        number, title = recorded_step(example)
-        { number: number, title: redact(title || example.description), line: flow_line(example) }.compact
-      end
-
-      def flow_line(example)
-        file = example.metadata[:absolute_file_path].to_s
-        frame = Array(example.exception&.backtrace).find { |each| each.start_with?("#{file}:") }
-        frame && frame.delete_prefix("#{file}:").to_i
-      end
-
-      def recorded_step(example)
-        return nil unless results_dir
-
-        report = File.join(results_dir, 'run.json')
-        return nil unless File.file?(report) && File.size(report) <= MAX_RUN_JSON_BYTES
-
-        file = example.metadata[:file_path].to_s.delete_prefix('./')
-        result = JSON.parse(File.read(report)).fetch('results', []).find do |each|
-          each['file_path'] == file && each['status'] == 'failed' && each['steps'].is_a?(Hash)
-        end
-        index = result&.dig('steps', 'failed')
-        return nil unless index.is_a?(Integer)
-
-        [index + 1, result.dig('steps', 'items', index, 'title')]
-      rescue StandardError
-        nil
-      end
-
-      def redact(text)
-        @secrets.uniq.sort_by { |secret| -secret.length }.reduce(text.to_s) { |result, secret| result.gsub(secret, '[secret]') }
-      end
-
-      def append(line)
-        File.open(log_file, File::WRONLY | File::APPEND | File::CREAT | NOFOLLOW, 0o600) do |file|
-          file.flock(File::LOCK_EX)
-          file.write("#{JSON.generate(line)}\n")
-        end
-      end
-
-      def prune
-        File.open(log_file, File::RDWR | NOFOLLOW) do |file|
-          file.flock(File::LOCK_EX)
-          lines = file.read.lines
-          if lines.size > KEEP_LINES
-            file.rewind
-            file.truncate(0)
-            file.write(lines.last(KEEP_LINES).join)
-          end
-        end
-        prune_results
-      end
-
-      # Only stamp-named folders directly under flow-results/<name>, and never this run's
-      def prune_results
-        dir = File.join(@root, 'flow-results', name)
-        return unless File.directory?(dir) && File.realpath(dir) == dir
-
-        runs = Dir.children(dir).select do |child|
-          RESULTS_STAMP.match?(child) && File.lstat(File.join(dir, child)).directory?
-        end
-        old = runs.sort - runs.sort.last(KEEP_RESULTS) - [results_dir && File.basename(results_dir)]
-        old.each { |child| FileUtils.rm_rf(File.join(dir, child)) }
-      end
-
-      def log_file
-        File.join(private_dir(".raider/flows/#{name}"), 'runs.jsonl')
-      end
-
-      def relative(path)
-        path&.delete_prefix("#{@root}/")
-      end
-
-      def iso(time)
-        time.iso8601(3)
-      end
-    end
-  end
-end

data/lib/utilities/flows/project.rb

@@ -1,170 +0,0 @@
-# frozen_string_literal: true
-
-require 'erb'
-require 'fileutils'
-
-module RubyRaider
-  module Flows
-    NAME = /\A[a-z0-9_]{1,60}\z/
-    # .raider/flows/env is the secrets file, so no flow may log to .raider/flows/env/
-    RESERVED = %w[env].freeze
-
-    def self.valid_name?(name) = NAME.match?(name.to_s) && !RESERVED.include?(name.to_s)
-
-    # Text from a run log, safe to print: page text in a step title can't move the cursor or forge lines
-    def self.printable(text) = text.to_s.gsub(/[[:cntrl:]]/, '?')
-
-    # A problem that stops a flow command; exit_code follows `raider flow run` (2 = setup failed).
-    class Error < StandardError
-      attr_reader :exit_code
-
-      def initialize(message, exit_code: 2)
-        super(message)
-        @exit_code = exit_code
-      end
-    end
-
-    # A Ruby Raider project that holds flows in flows/<name>_flow.rb.
-    class Project
-      UNSUPPORTED = 'Flows need a Selenium web project made with Ruby Raider 4.0 or later'
-      GITIGNORE_LINES = %w[flow-results/ .raider/flows/].freeze
-      TEMPLATES = {
-        'flows/flow_helper.rb' => 'flow_helper.tt',
-        'flows/support/run.rb' => 'run.tt'
-      }.freeze
-      # gem 'ruby_raider', '~> 4.0' (any quotes); captures the major and minor
-      PIN = /^(\s*gem\s+(["'])ruby_raider\2\s*,\s*(["']))~>\s*(\d+)\.(\d+)(?:\.\d+)?(\3)/
-      FLOWS_PIN = [4, 1].freeze
-
-      attr_reader :root
-
-      def initialize(path)
-        @root = File.realpath(path)
-      rescue SystemCallError
-        raise Error, "Project folder not found: #{path}"
-      end
-
-      def path(relative) = File.join(root, relative)
-
-      # The flow file for a name, realpath-checked inside the project.
-      def flow_file(name)
-        raise Error, "Invalid flow name #{name.inspect}: use 1 to 60 of a-z, 0-9 and _ (not env)" unless Flows.valid_name?(name)
-
-        file = path("flows/#{name}_flow.rb")
-        raise Error, "No flow #{name}: flows/#{name}_flow.rb not found" unless File.file?(file)
-
-        real = File.realpath(file)
-        raise Error, "flows/#{name}_flow.rb points outside the project" unless real.start_with?("#{root}#{File::SEPARATOR}")
-
-        real
-      end
-
-      def flow_names
-        Dir.glob(path('flows/*_flow.rb')).map { |file| File.basename(file, '_flow.rb') }.select { |name| Flows.valid_name?(name) }.sort
-      end
-
-      def set_up? = TEMPLATES.keys.all? { |file| File.file?(path(file)) }
-
-      # nil when flows can be added, otherwise why not
-      def unsupported_reason
-        gemfile = read('Gemfile')
-        return UNSUPPORTED unless gemfile && selenium?(gemfile) && runtime?
-        return UNSUPPORTED if old_pin?(gemfile)
-
-        nil
-      end
-
-      # Returns the exit code: 0 done (or already done), 2 refused.
-      def init(out: $stdout, err: $stderr)
-        reason = unsupported_reason
-        if reason
-          err.puts(reason)
-          return 2
-        end
-
-        created = write_templates
-        updated = add_gitignore_lines
-        pinned = pin_gem
-        updated << 'Gemfile' if pinned
-        report(out, created, updated, pinned)
-        warn_unknown_pin(err)
-        0
-      end
-
-      private
-
-      def template_dir = File.expand_path('../../generators/templates/flows', __dir__)
-
-      def read(relative)
-        file = path(relative)
-        File.file?(file) ? File.read(file) : nil
-      end
-
-      def selenium?(gemfile)
-        gemfile.match?(/["']selenium-webdriver["']/) && !gemfile.match?(/["']appium_lib["']/)
-      end
-
-      # 4.0 projects load the runtime from the driver helper; 3.x ones used WaitHelper
-      def runtime?
-        read('helpers/driver_helper.rb').to_s.include?("require 'ruby_raider/runtime'")
-      end
-
-      def old_pin?(gemfile)
-        match = gemfile.match(PIN)
-        match ? match[4].to_i < FLOWS_PIN.first : false
-      end
-
-      def write_templates
-        TEMPLATES.filter_map do |relative, template|
-          file = path(relative)
-          next if File.exist?(file)
-
-          FileUtils.mkdir_p(File.dirname(file))
-          File.write(file, ERB.new(File.read(File.join(template_dir, template)), trim_mode: '-').result)
-          relative
-        end
-      end
-
-      def add_gitignore_lines
-        file = path('.gitignore')
-        content = File.file?(file) ? File.read(file) : ''
-        missing = GITIGNORE_LINES - content.lines.map(&:strip)
-        return [] if missing.empty?
-
-        prefix = content.empty? || content.end_with?("\n") ? '' : "\n"
-        File.write(file, "#{content}#{prefix}#{missing.join("\n")}\n")
-        ['.gitignore']
-      end
-
-      # Raises a ~> 4.0 pin to ~> 4.1 so `bundle exec raider flow` runs a gem that has flows.
-      def pin_gem
-        gemfile = read('Gemfile').to_s
-        match = gemfile.match(PIN)
-        return false unless match && ([match[4].to_i, match[5].to_i] <=> FLOWS_PIN).negative?
-
-        File.write(path('Gemfile'), gemfile.sub(PIN) { "#{match[1]}~> #{FLOWS_PIN.join('.')}#{match[6]}" })
-        true
-      end
-
-      # gem 'ruby_raider', '4.0.1' or path: ... isn't raised here, and an old gem has no `raider flow`
-      def warn_unknown_pin(err)
-        gemfile = read('Gemfile').to_s
-        return if gemfile.match?(PIN) || !gemfile.match?(/^\s*gem\s+["']ruby_raider["']/)
-
-        err.puts("Check that the ruby_raider line in your Gemfile allows #{FLOWS_PIN.join('.')} or later, then run bundle install")
-      end
-
-      def report(out, created, updated, pinned)
-        if created.empty? && updated.empty?
-          out.puts('Flows already set up')
-          return
-        end
-
-        created.each { |file| out.puts("Created #{file}") }
-        updated.each { |file| out.puts("Updated #{file}") }
-        out.puts('Run bundle install') if pinned
-        out.puts('Write a flow in flows/<name>_flow.rb, then run it with: raider flow run <name>')
-      end
-    end
-  end
-end

data/lib/utilities/flows/run_log.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-
-module RubyRaider
-  module Flows
-    # Reads .raider/flows/<name>/runs.jsonl, which the project's flows/support/run.rb appends to.
-    class RunLog
-      MAX_BYTES = 1024 * 1024
-      NOFOLLOW = defined?(File::NOFOLLOW) ? File::NOFOLLOW : 0
-      NONBLOCK = defined?(File::NONBLOCK) ? File::NONBLOCK : 0
-      SUMMARY = %w[status finished_at failed_step results_dir].freeze
-
-      # [{name, file, last: {status, finished_at, failed_step, results_dir} | nil}], the shape `raider flow list --json` prints
-      def self.summaries(project)
-        project.flow_names.map do |name|
-          last = new(project, name).last_result
-          { 'name' => name, 'file' => "flows/#{name}_flow.rb", 'last' => last && SUMMARY.to_h { |key| [key, last[key]] } }
-        end
-      end
-
-      def initialize(project, name)
-        @file = project.path(".raider/flows/#{name}/runs.jsonl")
-      end
-
-      # Every readable line in the last MAX_BYTES, oldest first; a broken line is skipped
-      def lines
-        tail.lines.filter_map do |line|
-          parsed = JSON.parse(line)
-          parsed if parsed.is_a?(Hash)
-        rescue JSON::ParserError
-          nil
-        end
-      end
-
-      def last = lines.last
-
-      # The last run that ran: a busy line only says another run held the lock
-      def last_result = lines.reverse.find { |line| line['status'] != 'busy' }
-
-      def find(run_id) = lines.reverse.find { |line| line['run_id'] == run_id }
-
-      private
-
-      # Read through one handle that is not a link, so the checks and the read see the same file
-      def tail
-        File.open(@file, File::RDONLY | NONBLOCK | NOFOLLOW) do |file|
-          stat = file.stat
-          return '' unless stat.file?
-
-          skip = [stat.size - MAX_BYTES, 0].max
-          file.seek(skip)
-          text = file.read.to_s.force_encoding(Encoding::UTF_8)
-          skip.positive? ? text.partition("\n").last : text
-        end
-      rescue SystemCallError
-        ''
-      end
-    end
-  end
-end