sevgi-showcase 0.94.0 → 0.98.2

data/README.md

@@ -1,6 +1,6 @@
 # Sevgi Showcase
 
-Executable examples, rendered outputs, and documentation-site support.
+Sevgi Showcase packages the executable examples, their SVG output, and support code for the documentation site.
 
 ## Install
 
@@ -8,22 +8,14 @@ Executable examples, rendered outputs, and documentation-site support.
 gem install sevgi-showcase
 ```
 
-## Require
+## Contents
 
-```ruby
-require "sevgi/showcase"
-```
-
-## Example
-
-```ruby
-suite = Sevgi::Test::Suite.new("srv")
-suite.valids.map(&:name)
-```
+The gem is an asset package rather than a runtime API. It contains the executable `.sevgi` examples, their expected
+SVG output, and private build support used by the documentation site.
 
 ## Ruby compatibility
 
-Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.
 
 ## Native prerequisites
 
@@ -47,7 +39,7 @@ gem install cairo rsvg2 hexapdf
 
 ## Links
 
-- Documentation: https://sevgi.roktas.dev
-- API documentation: https://www.rubydoc.info/gems/sevgi-showcase
-- Source: https://github.com/roktas/sevgi/tree/main/showcase
-- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md
+- Documentation: <https://sevgi.roktas.dev>
+- API documentation: <https://www.rubydoc.info/gems/sevgi-showcase>
+- Source: <https://github.com/roktas/sevgi/tree/main/showcase>
+- Changelog: <https://github.com/roktas/sevgi/blob/main/CHANGELOG.md>

data/lib/sevgi/showcase/dark.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../showcase"
+
 module Sevgi
   module Showcase
     # Applies dark-theme color mappings to showcase source files.
@@ -60,5 +62,7 @@ module Sevgi
         end
       end
     end
+
+    private_constant :Dark
   end
 end

data/lib/sevgi/showcase/minitest/script.rb

@@ -1,78 +1,80 @@
 # frozen_string_literal: true
 
 module Sevgi
-  # Minitest helpers used by the showcase component.
-  # @api private
-  module Test
-    # Executable showcase script descriptor.
+  module Showcase
+    # Minitest helpers used by the showcase component.
     # @api private
-    class Script
-      # @return [String] absolute script path
-      attr_reader :file
+    module Test
+      # Executable showcase script descriptor.
+      # @api private
+      class Script
+        # @return [String] absolute script path
+        attr_reader :file
 
-      # Creates a script descriptor.
-      # @param file [String] executable .sevgi file
-      # @return [void]
-      # @raise [Sevgi::ArgumentError] when the file is missing or not executable
-      def initialize(file) = @file = ::File.expand_path(sanitize(file))
+        # Creates a script descriptor.
+        # @param file [String] executable .sevgi file
+        # @return [void]
+        # @raise [Sevgi::ArgumentError] when the file is missing or not executable
+        def initialize(file) = @file = ::File.expand_path(sanitize(file))
 
-      # Returns the script directory.
-      # @return [String]
-      def dir = @dir ||= ::File.dirname(file)
+        # Returns the script directory.
+        # @return [String]
+        def dir = @dir ||= ::File.dirname(file)
 
-      # Returns the script basename.
-      # @return [String]
-      def file! = ::File.basename(file)
+        # Returns the script basename.
+        # @return [String]
+        def file! = ::File.basename(file)
 
-      # Returns the script name without extension.
-      # @return [String]
-      def name = @name ||= ::File.basename(file, ".*")
+        # Returns the script name without extension.
+        # @return [String]
+        def name = @name ||= ::File.basename(file, ".*")
 
-      # @overload run(*args)
-      #   Runs the script directly.
-      #   @param args [Array<String>] extra command arguments
-      #   @return [Sevgi::Test::Shell::Result]
-      def run(*) = Shell.run(file, *)
+        # @overload run(*args)
+        #   Runs the script directly.
+        #   @param args [Array<String>] extra command arguments
+        #   @return [Sevgi::Showcase::Test::Shell::Result]
+        def run(*) = Shell.run(file, *)
 
-      # Returns the script suite name.
-      # @return [String]
-      def suite = @suite ||= ::File.basename(dir)
+        # Returns the script suite name.
+        # @return [String]
+        def suite = @suite ||= ::File.basename(dir)
 
-      # Reports whether the expected SVG output exists.
-      # @return [Boolean]
-      def svg? = ::File.exist?(svg)
+        # Reports whether the expected SVG output exists.
+        # @return [Boolean]
+        def svg? = ::File.exist?(svg)
 
-      # Returns the expected SVG output path.
-      # @return [String]
-      def svg = @svg ||= ::File.expand_path("#{dir}/#{name}.svg")
+        # Returns the expected SVG output path.
+        # @return [String]
+        def svg = @svg ||= ::File.expand_path("#{dir}/#{name}.svg")
 
-      # Returns the expected SVG output basename.
-      # @return [String]
-      def svg! = ::File.basename(svg)
+        # Returns the expected SVG output basename.
+        # @return [String]
+        def svg! = ::File.basename(svg)
 
-      # Returns the optional YAML metadata path.
-      # @return [String]
-      def yml = @yml ||= ::File.expand_path("#{dir}/#{name}.yml")
+        # Returns the optional YAML metadata path.
+        # @return [String]
+        def yml = @yml ||= ::File.expand_path("#{dir}/#{name}.yml")
 
-      # Returns the optional YAML metadata basename.
-      # @return [String]
-      def yml! = ::File.basename(yml)
+        # Returns the optional YAML metadata basename.
+        # @return [String]
+        def yml! = ::File.basename(yml)
 
-      # @overload run_passive(*args)
-      #   Runs the script without writing Save output to files.
-      #   @param args [Array<String>] extra command arguments
-      #   @return [Sevgi::Test::Shell::Result]
-      def run_passive(*)
-        warn("...#{name}")
-        Shell.run("sevgi", "-r", "sevgi/showcase/passive", file, *)
-      end
+        # @overload run_passive(*args)
+        #   Runs the script without writing Save output to files.
+        #   @param args [Array<String>] extra command arguments
+        #   @return [Sevgi::Showcase::Test::Shell::Result]
+        def run_passive(*)
+          warn("...#{name}")
+          Shell.run("sevgi", "-r", "sevgi/showcase/passive", file, *)
+        end
 
-      private
+        private
 
-      def sanitize(file)
-        file.tap do
-          ArgumentError.("No such file: #{file}") unless ::File.exist?(file)
-          ArgumentError.("Not an executable: #{file}") unless ::File.executable?(file)
+        def sanitize(file)
+          file.tap do
+            ArgumentError.("No such file: #{file}") unless ::File.exist?(file)
+            ArgumentError.("Not an executable: #{file}") unless ::File.executable?(file)
+          end
         end
       end
     end

data/lib/sevgi/showcase/minitest/shell.rb

@@ -1,147 +1,170 @@
 # frozen_string_literal: true
 
 require "open3"
+require "sevgi/function"
 
 module Sevgi
-  # Minitest helpers used by the showcase component.
-  # @api private
-  module Test
-    # Shell runner helpers for showcase tests.
+  module Showcase
+    # Minitest helpers used by the showcase component.
     # @api private
-    module Shell
-      # Shell command result.
+    module Test
+      # Shell runner helpers for showcase tests.
       # @api private
-      Result = Data.define(:args, :out, :err, :exit_code) do
-        # Returns the command string.
-        # @return [String]
-        def cmd = args.join(" ")
-
-        # Reports whether the command failed.
-        # @return [Boolean]
-        def notok? = !ok?
-
-        # Reports whether the command exited successfully.
-        # @return [Boolean]
-        def ok? = exit_code&.zero?
-
-        # Returns the first stdout line.
-        # @return [String, nil]
-        def outline = out.first
-
-        # Returns stdout as a newline-joined string.
-        # @return [String]
-        def to_s = out.join("\n")
-      end
+      module Shell
+        # Shared process-global SIGINT state.
+        # @api private
+        Signals = ::Sevgi::Function::Shell.const_get(:Signals, false)
 
-      # Adapted to popen3 from github.com/mina-deploy/mina
-      # Shell command runner.
-      # @api private
-      class Runner
-        # Creates a runner.
-        # @return [void]
-        def initialize
-          @coathooks = 0
+        private_constant :Signals
+
+        # Shell command result.
+        # @api private
+        Result = Data.define(:args, :out, :err, :exit_code) do
+          private_class_method :[]
+
+          # Returns the command string.
+          # @return [String]
+          def cmd = args.join(" ")
+
+          # Reports whether the command failed.
+          # @return [Boolean]
+          def notok? = !ok?
+
+          # Reports whether the command exited successfully.
+          # @return [Boolean]
+          def ok? = exit_code&.zero?
+
+          # Returns the first stdout line.
+          # @return [String, nil]
+          def outline = out.first
+
+          # Returns stdout as a newline-joined string.
+          # @return [String]
+          def to_s = out.join("\n")
         end
 
-        # Runs a command and captures stdout, stderr, and exit status.
-        # @param args [Array<String>] command and arguments
-        # @yield optional stdin writer evaluated with stdin as receiver
-        # @yieldreturn [Object]
-        # @return [Sevgi::Test::Shell::Result]
-        # @raise [StandardError] when the input block raises; the child is terminated and reaped before propagation
-        def run(*args, &block)
-          out, err, status = Open3.popen3(*args) do |stdin, stdout, stderr, thread|
-            capture(stdin, stdout, stderr, thread, &block)
+        # Adapted to popen3 from github.com/mina-deploy/mina
+        # Shell command runner.
+        # @api private
+        class Runner
+          # Creates a runner.
+          # @return [void]
+          def initialize
+            @coathooks = 0
           end
 
-          Result[args, out, err, status.exitstatus]
-        end
+          # Runs a command and captures stdout, stderr, and exit status.
+          # @param args [Array<String>] command and arguments
+          # @yield optional stdin writer evaluated with stdin as receiver
+          # @yieldreturn [Object]
+          # @return [Sevgi::Showcase::Test::Shell::Result]
+          # @raise [StandardError] when the input block raises; the child is terminated and reaped before propagation
+          # @note The first SIGINT sends TERM and the second sends KILL outside trap context. The handler is restored after
+          #   the last active run.
+          def run(*args, &block)
+            @coathooks = 0
+            out, err, status = Open3.popen3(*args) do |stdin, stdout, stderr, thread|
+              capture(stdin, stdout, stderr, thread, &block)
+            end
+
+            Result.new(args:, out:, err:, exit_code: status.exitstatus)
+          end
 
-        private
+          private
 
-        # rubocop:disable Lint/RescueException
-        def capture(stdin, stdout, stderr, thread, &block)
-          trap = trap("INT") { handle_sigint(thread.pid) }
-          readers = outputs(stdout, stderr)
+          # rubocop:disable Lint/RescueException
+          def capture(stdin, stdout, stderr, thread, &block)
+            register_capture(thread)
+            registered = true
+            readers = outputs(stdout, stderr)
 
-          collect_capture(stdin, thread, readers, &block)
-        rescue Exception
-          cleanup_failed_capture(stdin, thread, readers)
-          raise
-        ensure
-          close_input(stdin)
-          trap("INT", trap) if trap
-        end
-        # rubocop:enable Lint/RescueException
+            collect_capture(stdin, thread, readers, &block)
+          rescue Exception
+            cleanup_failed_capture(stdin, thread, readers)
+            raise
+          ensure
+            finish_capture(stdin, registered)
+          end
+          # rubocop:enable Lint/RescueException
 
-        def cleanup_failed_capture(stdin, thread, readers)
-          close_input(stdin)
-          stop_process(thread)
-          Array(readers).each(&:join)
-        end
+          def finish_capture(stdin, registered)
+            close_input(stdin)
+            Signals.unregister(self) if registered
+          end
 
-        def close_input(stdin)
-          stdin.close unless stdin.closed?
-        rescue IOError
-          nil
-        end
+          def register_capture(thread)
+            Signals.register(self, thread.pid)
+          end
 
-        def collect_capture(stdin, thread, readers, &block)
-          inputs(stdin, thread, &block)
-          close_input(stdin)
+          def cleanup_failed_capture(stdin, thread, readers)
+            close_input(stdin)
+            stop_process(thread)
+            Array(readers).each(&:join)
+          end
 
-          [readers[0].value, readers[1].value, thread.value]
-        end
+          def close_input(stdin)
+            stdin.close unless stdin.closed?
+          rescue IOError
+            nil
+          end
+
+          def collect_capture(stdin, thread, readers, &block)
+            inputs(stdin, thread, &block)
+            close_input(stdin)
 
-        def handle_sigint(pid)
-          message, signal = if @coathooks > 1
-            ["SIGINT received again. Force quitting...", "KILL"]
-          else
-            ["SIGINT received.", "TERM"]
+            [readers[0].value, readers[1].value, thread.value]
           end
 
-          warn("\n#{message}")
-          ::Process.kill(signal, pid)
-          @coathooks += 1
-        rescue Errno::ESRCH
-          warn("No process to kill.")
-        end
+          def handle_sigint(pid)
+            @coathooks += 1
+            message, signal = if @coathooks > 1
+              ["SIGINT received again. Force quitting...", "KILL"]
+            else
+              ["SIGINT received.", "TERM"]
+            end
+
+            warn("\n#{message}")
+            ::Process.kill(signal, pid)
+          rescue Errno::ESRCH
+            warn("No process to kill.")
+          end
 
-        def inputs(stdin, thread, &block)
-          stdin.instance_exec(thread, &block) if block
-        end
+          def inputs(stdin, thread, &block)
+            stdin.instance_exec(thread, &block) if block
+          end
 
-        def kill_process(signal, pid)
-          ::Process.kill(signal, pid)
-        rescue Errno::ESRCH
-          nil
-        end
+          def kill_process(signal, pid)
+            ::Process.kill(signal, pid)
+          rescue Errno::ESRCH
+            nil
+          end
 
-        def outputs(stdout, stderr)
-          [
-            Thread.new { stdout.readlines.map(&:chomp) },
-            Thread.new { stderr.readlines.map(&:chomp) }
-          ]
-        end
+          def outputs(stdout, stderr)
+            [
+              Thread.new { stdout.readlines.map(&:chomp) },
+              Thread.new { stderr.readlines.map(&:chomp) }
+            ]
+          end
 
-        def stop_process(thread)
-          return unless thread&.alive?
+          def stop_process(thread)
+            return unless thread&.alive?
 
-          kill_process("TERM", thread.pid)
-          return if thread.join(1)
+            kill_process("TERM", thread.pid)
+            return if thread.join(1)
 
-          kill_process("KILL", thread.pid)
-          thread.join
+            kill_process("KILL", thread.pid)
+            thread.join
+          end
         end
-      end
 
-      extend self
+        extend self
 
-      # @overload run(*args)
-      #   Runs a command through a fresh runner.
-      #   @param args [Array<String>] command and arguments
-      #   @return [Sevgi::Test::Shell::Result]
-      def run(...) = Runner.new.run(...)
+        # @overload run(*args)
+        #   Runs a command through a fresh runner.
+        #   @param args [Array<String>] command and arguments
+        #   @return [Sevgi::Showcase::Test::Shell::Result]
+        def run(...) = Runner.new.run(...)
+      end
     end
   end
 end

data/lib/sevgi/showcase/minitest/suite.rb

@@ -1,53 +1,55 @@
 # frozen_string_literal: true
 
 module Sevgi
-  # Minitest helpers used by the showcase component.
-  # @api private
-  module Test
-    # Showcase script suite collection.
+  module Showcase
+    # Minitest helpers used by the showcase component.
     # @api private
-    class Suite
-      # Creates a suite from a showcase root directory.
-      # @param rootdir [String] showcase root directory
-      # @return [void]
-      def initialize(rootdir)
-        @scripts = load(rootdir)
-      end
-
-      # Returns scripts belonging to a suite.
-      # @param suite [String, Symbol] suite name
-      # @return [Array<Sevgi::Test::Script>]
-      def [](suite)
-        (@cache ||= {})[suite] ||= @scripts.select { |script| script.suite == suite.to_s }
-      end
-
-      # Returns all suite names.
-      # @return [Array<String>]
-      def suites
-        @suites ||= @scripts.map(&:suite).uniq
-      end
-
-      # Suite names that are expected to be invalid examples.
-      NON_VALIDS = ["gotcha"].freeze
-
-      # Returns scripts expected to be invalid.
-      # @return [Array<Sevgi::Test::Script>]
-      def non_valids
-        NON_VALIDS.map { self[it] }.flatten
-      end
-
-      # Returns scripts expected to render successfully.
-      # @return [Array<Sevgi::Test::Script>]
-      def valids
-        suites.reject { NON_VALIDS.include?(it) }.map { self[it] }.flatten
-      end
-
-      alias to_a valids
-
-      private
-
-      def load(rootdir)
-        ::Dir["#{rootdir}/**/*.sevgi"].grep_v(%r{(/_|/lib/|/library/)}).map { Script.new(it) }
+    module Test
+      # Showcase script suite collection.
+      # @api private
+      class Suite
+        # Creates a suite from a showcase root directory.
+        # @param rootdir [String] showcase root directory
+        # @return [void]
+        def initialize(rootdir)
+          @scripts = load(rootdir)
+        end
+
+        # Returns scripts belonging to a suite.
+        # @param suite [String, Symbol] suite name
+        # @return [Array<Sevgi::Showcase::Test::Script>]
+        def [](suite)
+          (@cache ||= {})[suite] ||= @scripts.select { |script| script.suite == suite.to_s }
+        end
+
+        # Returns all suite names.
+        # @return [Array<String>]
+        def suites
+          @suites ||= @scripts.map(&:suite).uniq
+        end
+
+        # Suite names that are expected to be invalid examples.
+        NON_VALIDS = ["gotcha"].freeze
+
+        # Returns scripts expected to be invalid.
+        # @return [Array<Sevgi::Showcase::Test::Script>]
+        def non_valids
+          NON_VALIDS.map { self[it] }.flatten
+        end
+
+        # Returns scripts expected to render successfully.
+        # @return [Array<Sevgi::Showcase::Test::Script>]
+        def valids
+          suites.reject { NON_VALIDS.include?(it) }.map { self[it] }.flatten
+        end
+
+        alias to_a valids
+
+        private
+
+        def load(rootdir)
+          ::Dir["#{rootdir}/**/*.sevgi"].grep_v(%r{(/_|/lib/|/library/)}).map { Script.new(it) }
+        end
       end
     end
   end

data/lib/sevgi/showcase/minitest.rb

@@ -3,3 +3,9 @@
 require_relative "minitest/script"
 require_relative "minitest/shell"
 require_relative "minitest/suite"
+
+module Sevgi
+  module Showcase
+    private_constant :Test
+  end
+end

data/lib/sevgi/showcase/version.rb

@@ -4,6 +4,6 @@ module Sevgi
   # Showcase component namespace.
   module Showcase
     # Current showcase component version.
-    VERSION = "0.94.0"
+    VERSION = "0.98.2"
   end
 end

data/lib/sevgi/showcase.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "showcase/dark"
-require_relative "showcase/minitest"
+require "sevgi"
 
 require_relative "showcase/version"