scarpe 0.2.0 → 0.2.2

data/scarpe-components/lib/scarpe/components/segmented_file_loader.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "scarpe/components/file_helpers"
+
+module Scarpe::Components
+  class SegmentedFileLoader
+    include Scarpe::Components::FileHelpers
+
+    # Add a new segment type (e.g. "catscradle") with a different
+    # file handler.
+    #
+    # @param type [String] the new name for this segment type
+    # @param handler [Object] an object that will be called as obj.call(filename) - often a proc
+    # @return <void>
+    def add_segment_type(type, handler)
+      if segment_type_hash.key?(type)
+        raise "Segment type #{type.inspect} already exists!"
+      end
+
+      segment_type_hash[type] = handler
+    end
+
+    # Return an Array of segment type labels, such as "code" and "app_test".
+    #
+    # @return Array<String> the segment type labels
+    def segment_types
+      segment_type_hash.keys
+    end
+
+    # Load a .sca file with an optional YAML frontmatter prefix and
+    # multiple file sections which can be treated differently.
+    #
+    # The file loader acts like a proc, being called with .call()
+    # and returning true or false for whether it has handled the
+    # file load. This allows chaining loaders in order and the
+    # first loader to recognise a file will run it.
+    #
+    # @param path [String] the file or directory to treat as a Scarpe app
+    # @return [Boolean] return true if the file is loaded as a segmented Scarpe app file
+    def call(path)
+      return false unless path.end_with?(".scas")
+
+      file_load(path)
+      true
+    end
+
+    # Segment type handlers can call this to perform an operation after the load
+    # has completed. This is important for ordering, and because loading a Shoes
+    # app often doesn't return. So to have a later section (e.g. tests, additional
+    # data) do something that affects Shoes app loading (e.g. set an env var,
+    # affect the display service) it's important that app loading take place later
+    # in the sequence.
+    def after_load(&block)
+      @after_load ||= []
+      @after_load << block
+    end
+
+    private
+
+    def gen_name(segmap)
+      ctr = (1..10_000).detect { |i| !segmap.key?("%5d" % i) }
+      "%5d" % ctr
+    end
+
+    def tokenize_segments(contents)
+      require "yaml" # Only load when needed
+      require "English"
+
+      segments = contents.split(/\n-{5,}/)
+      front_matter = {}
+
+      # The very first segment can start with front matter, or with a divider, or with no divider.
+      if segments[0].start_with?("---\n") || segments[0] == "---"
+        # We have YAML front matter at the start. All later segments will have a divider.
+        front_matter = YAML.load segments[0]
+        front_matter ||= {} # If the front matter is just the three dashes it returns nil
+        segments = segments[1..-1]
+      elsif segments[0].start_with?("-----")
+        # We have a divider at the start. Great! We're already well set up for this case.
+      elsif segments.size == 1
+        # No front matter, no divider, a single unnamed segment. No more parsing needed.
+        return [{}, { "" => segments[0] }]
+      else
+        # No front matter, no divider before the first segment, multiple segments.
+        # We'll add an artificial divider to the first segment for uniformity.
+        segments = ["-----\n" + segments[0]] + segments[1..-1]
+      end
+
+      segmap = {}
+      segments.each do |segment|
+        if segment =~ /\A-* +(.*?)\n/
+          # named segment with separator
+          segmap[::Regexp.last_match(1)] = ::Regexp.last_match.post_match
+        elsif segment =~ /\A-* *\n/
+          # unnamed segment with separator
+          segmap[gen_name(segmap)] = ::Regexp.last_match.post_match
+        else
+          raise "Internal error when parsing segments in segmented app file! seg: #{segment.inspect}"
+        end
+      end
+
+      [front_matter, segmap]
+    end
+
+    def file_load(path)
+      contents = File.read(path)
+
+      front_matter, segmap = tokenize_segments(contents)
+
+      if segmap.empty?
+        raise "Illegal segmented Scarpe file: must have at least one code segment, not just front matter!"
+      end
+
+      if front_matter[:segments]
+        if front_matter[:segments].size != segmap.size
+          raise "Number of front matter :segments must equal number of file segments!"
+        end
+      else
+        if segmap.size > 2
+          raise "Segmented files with more than two segments have to specify what they're for!"
+        end
+
+        # Set to default of shoes code only or shoes code and app test code.
+        front_matter[:segments] = segmap.size == 2 ? ["shoes", "app_test"] : ["shoes"]
+      end
+
+      # Match up front_matter[:segments] with the segments, or use the default of shoes and app_test.
+
+      sth = segment_type_hash
+      sv = segmap.values
+
+      tf_specs = []
+      front_matter[:segments].each.with_index do |seg_type, idx|
+        unless sth.key?(seg_type)
+          raise "Unrecognized segment type #{seg_type.inspect}! No matching segment type available!"
+        end
+
+        tf_specs << ["scarpe_#{seg_type}_segment_contents", sv[idx]]
+      end
+
+      with_tempfiles(tf_specs) do |filenames|
+        filenames.each.with_index do |filename, idx|
+          seg_name = front_matter[:segments][idx]
+          sth[seg_name].call(filename)
+        end
+
+        # Need to call @after_load hooks while tempfiles still exist
+        if @after_load && !@after_load.empty?
+          @after_load.each(&:call)
+        end
+      end
+    end
+
+    # The hash of segment type labels mapped to handlers which will be called.
+    # Normal client code shouldn't ever call this.
+    #
+    # @return Hash<String, Object> the name/handler pairs
+    def segment_type_hash
+      @segment_handlers ||= {
+        "shoes" => proc { |seg_file| after_load { load seg_file } },
+        "app_test" => proc { |seg_file| ENV["SCARPE_APP_TEST"] = seg_file },
+      }
+    end
+  end
+end
+
+# You can add additional segment types to the segmented file loader
+# loader = Scarpe::Components::SegmentedFileLoader.new
+# loader.add_segment_type "capybara", proc { |seg_file| load_file_as_capybara(seg_file) }
+# Shoes.add_file_loader loader

data/scarpe-components/lib/scarpe/components/unit_test_helpers.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "json"
+require "fileutils"
+
+require "scarpe/components/file_helpers"
+
+module Scarpe::Test; end
+
+# We want test failures set up once *total*, not per Minitest::Test. So an instance var
+# doesn't do it.
+ALREADY_SET_UP_LOGGED_TEST_FAILURES = { setup: false }
+
+# General helpers for general usage.
+# Helpers here should *not* use Webview-specific functionality.
+# The intention is that these are helpers for various Scarpe display
+# services that do *not* necessarily use Webview.
+
+module Scarpe::Test::Helpers
+  # Very useful for tests
+  include Scarpe::Components::FileHelpers
+
+  # Temporarily set env vars for the block of code inside. The old environment
+  # variable values will be restored after the block finishes.
+  #
+  # @param envs [Hash<String,String>] A hash of environment variable names and values
+  def with_env_vars(envs)
+    old_env = {}
+    envs.each do |k, v|
+      old_env[k] = ENV[k]
+      ENV[k] = v
+    end
+    yield
+  ensure
+    old_env.each { |k, v| ENV[k] = v }
+  end
+end
+
+# This test will save extensive logs in case of test failure.
+# Note that it defines setup/teardown methods. If you want
+# multiple setup/teardowns from multiple places to happen you
+# may need to explictly call (e.g. with logged_test_setup/teardown)
+# to ensure everything you want happens.
+module Scarpe::Test::LoggedTest
+  def self.included(includer)
+    class << includer
+      attr_accessor :logger_dir
+    end
+  end
+
+  def file_id
+    "#{self.class.name}_#{self.name}"
+  end
+
+  # This should be called by the test during setup to make sure that
+  # failure logs will be saved if this test fails. It makes sure the
+  # log config will save all logs from all sources, but keeps a copy
+  # of the old log config to restore after the test is finished.
+  #
+  # @return [void]
+  def logged_test_setup
+    # Make sure test failures will be saved at the end of the run.
+    # Delete stale test failures and logging only the *first* time this is called.
+    set_up_test_failures
+
+    @normal_log_config = Shoes::Log.current_log_config
+    Shoes::Log.configure_logger(log_config_for_test)
+
+    Shoes::Log.logger("LoggedScarpeTest").info("Test: #{self.class.name}##{self.name}")
+  end
+
+  # If you include this module and don't override setup/teardown, everything will
+  # work fine. But if you need more setup/teardown steps, you can do that too.
+  #
+  # The setup method guarantees that just including this module will do setup
+  # automatically. If you override it, be sure to call `super` or `logged_test_setup`.
+  #
+  # @return [void]
+  def setup
+    logged_test_setup
+  end
+
+  # After the test has finished, this will restore the old log configuration.
+  # It will also save the logfiles, but only if the test failed, not if it
+  # succeeded or was skipped.
+  #
+  # @return [void]
+  def logged_test_teardown
+    # Restore previous log config
+    Shoes::Log.configure_logger(@normal_log_config)
+
+    if self.failure
+      save_failure_logs
+    else
+      remove_unsaved_logs
+    end
+  end
+
+  # Make sure that, by default, #logged_test_teardown will be called for teardown.
+  # If a class overrides teardown, it should also call `super` or `logged_test_teardown`
+  # to make sure this still happens.
+  #
+  # @return [void]
+  def teardown
+    logged_test_teardown
+  end
+
+  # Set additional LoggedTest configuration for specific logs to separate or save.
+  # This is normally going to be display-service-specific log components.
+  # Note that this only really works with the modular logger or another logger
+  # that does something useful with the log config. The simple print logger
+  # doesn't do a lot with it.
+  def extra_log_config=(additional_log_config)
+    @additional_log_config = additional_log_config
+  end
+
+  # This is the log config that LoggedTests use. It makes sure all components keep all
+  # logs, but also splits the logs into several different files for later ease of scanning.
+  #
+  # TODO: this shouldn't directly include any Webview entries like WebviewAPI or
+  #     CatsCradle. Those should be overridden in Webview.
+  #
+  # @return [Hash] the log config
+  def log_config_for_test
+    {
+      "default" => ["debug", "logger/test_failure_#{file_id}.log"],
+      "DisplayService" => ["debug", "logger/test_failure_events_#{file_id}.log"],
+    }.merge(@additional_log_config || {})
+  end
+
+  # The list of logfiles that should be saved. Normally this is called internally by the
+  # class, not externally from elsewhere.
+  #
+  # This could be a lot simpler except I want to only update the file list in one place,
+  # log_config_for_test(). Having a single spot should (I hope) make it a lot friendlier to
+  # add more logfiles for different components, logged API objects, etc.
+  def saved_log_files
+    lc = log_config_for_test
+    log_outfiles = lc.values.map { |_level, loc| loc }
+    log_outfiles.select { |s| s.start_with?("logger/") }.map { |s| s.delete_prefix("logger/") }
+  end
+
+  # Make sure that test failure logs will be noticed, and a message will be printed,
+  # if any logged tests fail. This needs to be called at least once in any Minitest-enabled
+  # process using logged tests.
+  #
+  # @return [void]
+  def set_up_test_failures
+    return if ALREADY_SET_UP_LOGGED_TEST_FAILURES[:setup]
+
+    log_dir = self.class.logger_dir
+    raise("Must set logger directory!") unless log_dir
+    raise("Can't find logger directory!") unless File.directory?(log_dir)
+
+    ALREADY_SET_UP_LOGGED_TEST_FAILURES[:setup] = true
+    # Delete stale test failures, if any, before starting the first failure-logged test
+    Dir["#{log_dir}/test_failure*.log"].each { |fn| File.unlink(fn) }
+
+    Minitest.after_run do
+      # Print test failure notice to console
+      unless Dir["#{log_dir}/test_failure*.out.log"].empty?
+        puts "Some tests have failed! See #{log_dir}/test_failure*.out.log for test logs!"
+      end
+
+      # Remove un-saved test logs
+      Dir["#{log_dir}/test_failure*.log"].each do |f|
+        next if f.include?(".out.log")
+
+        File.unlink(f) if File.exist?(f)
+      end
+    end
+  end
+
+  # Failure log output location for a given file path. This is normally used internally to this
+  # class, not externally.
+  #
+  # @return [String] the output path
+  def logfail_out_loc(filepath)
+    # Add a .out prefix before final .log
+    out_loc = filepath.gsub(%r{.log\Z}, ".out.log")
+
+    if out_loc == filepath
+      raise "Something is wrong! Could not figure out failure-log output path for #{filepath.inspect}!"
+    end
+
+    if File.exist?(out_loc)
+      raise "Duplicate test file #{out_loc.inspect}? This file should *not* already exist!"
+    end
+
+    out_loc
+  end
+
+  # Save the failure logs in the appropriate place(s). This is normally used internally, not externally.
+  #
+  # @return [void]
+  def save_failure_logs
+    saved_log_files.each do |log_file|
+      full_loc = File.expand_path("#{self.class.logger_dir}/#{log_file}")
+      # TODO: we'd like to skip 0-length logfiles. But also Logging doesn't flush. For now, ignore.
+      next unless File.exist?(full_loc)
+
+      FileUtils.mv full_loc, logfail_out_loc(full_loc)
+    end
+  end
+
+  # Remove unsaved failure logs. This is normally used internally, not externally.
+  #
+  # @return [void]
+  def remove_unsaved_logs
+    Dir["#{self.class.logger_dir}/test_failure*.log"].each do |f|
+      next if f.include?(".out.log") # Don't delete saved logs
+
+      File.unlink(f)
+    end
+  end
+end

data/scarpe-components/lib/scarpe/components/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Scarpe
+  module Components
+    VERSION = "0.2.2"
+  end
+end

data/scarpe-components/scarpe-components.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/scarpe/components/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "scarpe-components"
+  spec.version = Scarpe::Components::VERSION
+  spec.authors = ["Marco Concetto Rudilosso", "Noah Gibbs"]
+  spec.email = ["marcoc.r@outlook.com", "the.codefolio.guy@gmail.com"]
+
+  spec.summary = "Reusable components for Scarpe display libraries"
+  spec.homepage = "https://github.com/scarpe-team/scarpe"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/scarpe-team/scarpe"
+  spec.metadata["changelog_uri"] = "https://github.com/scarpe-team/scarpe/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Scarpe-Components should add *no* runtime dependencies. Since each component
+  # is optional, the display library should add dependencies relevant to only
+  # the components it directly uses and no others.
+
+  #spec.add_dependency ""
+end

data/scarpe-components/test/test_components.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class TestScarpeComponents < Minitest::Test
+  def test_truth
+    assert_equal true, true
+  end
+end

data/scarpe-components/test/test_helper.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "shoes"
+
+require "minitest/autorun"
+
+require "minitest/reporters"
+Minitest::Reporters.use! [Minitest::Reporters::SpecReporter.new]
+
+# For tests, default to simple print logger
+# TODO: switch to modular logger and failure-logged tests?
+require "shoes/log"
+require "scarpe/components/print_logger"
+Shoes::Log.instance = Scarpe::Components::PrintLogImpl.new
+Shoes::Log.configure_logger(Shoes::Log::DEFAULT_LOG_CONFIG)
+
+require "scarpe/components/unit_test_helpers"
+
+class Minitest::Test
+  include Scarpe::Test::Helpers
+end