sevgi 0.95.0 → 1.0.0

data/lib/sevgi/binaries/sevgi.rb

@@ -1,30 +1,53 @@
 # frozen_string_literal: true
 
 require "sevgi"
+require "sevgi/skill"
 
 module Sevgi
   # Command-line entrypoint implementations shipped with Sevgi.
+  # @api private
   module Binaries
     # Implements the `sevgi` executable.
+    # @api private
     module Sevgi
       extend self
 
       # Executable name used in help output.
       PROGNAME = "sevgi"
 
+      # Logical source name used for standard input.
+      STDIN_NAME = "output.sevgi"
+
       # Error raised for invalid command-line usage.
       Error = Class.new(::Sevgi::Error)
 
+      FLAGS = {
+        "-x" => :vomit,
+        "--exception" => :vomit,
+        "-h" => :help,
+        "--help" => :help,
+        "--skill" => :skill,
+        "-v" => :version,
+        "--version" => :version
+      }.freeze
+
       # Parsed command-line options for the `sevgi` executable.
       # @api private
-      Options = Struct.new(:require, :nomain, :vomit, :help, :version) do
+      Options = Struct.new(:require, :vomit, :help, :skill, :version, :as) do
         # Parses command-line options and removes them from the argv array.
         # @param argv [Array<String>] mutable command-line argument array
         # @return [Sevgi::Binaries::Sevgi::Options] parsed options
-        # @raise [Sevgi::Binaries::Sevgi::Error] when an option is not recognized
+        # @raise [Sevgi::Binaries::Sevgi::Error] when an option is not recognized or a required value is missing
         def self.parse(argv)
           new.tap do |options|
-            argv.first.start_with?("-") ? option(argv, options) : break until argv.empty?
+            until argv.empty? || argv.first == "-" || !argv.first.start_with?("-")
+              if argv.first == "--"
+                argv.shift
+                break
+              end
+
+              option(argv, options)
+            end
           end
         end
 
@@ -32,18 +55,14 @@ module Sevgi
           private
 
           def option(argv, options)
-            case (arg = argv.shift)
-            when "-r", "--require"
-              options.require = argv.shift
-            when "-n", "--nomain"
-              options.nomain = true
-            when "-x", "--exception"
-              options.vomit = true
-
-            when "-h", "--help"
-              options.help = true
-            when "-v", "--version"
-              options.version = true
+            arg = argv.shift
+            if (flag = FLAGS[arg])
+              options[flag] = true
+            elsif ["-r", "--require"].include?(arg)
+              options.require = argv.shift || Error.("Option requires a library: #{arg}")
+            elsif arg == "--as"
+              options.as = argv.shift
+              Error.("Option requires a name: --as") if options.as.nil? || options.as.empty?
             else
               Error.("Not a valid option: #{arg}")
             end
@@ -51,64 +70,88 @@ module Sevgi
         end
       end
 
-      private_constant :Options
+      private_constant :FLAGS, :Options, :STDIN_NAME
 
       # Runs the `sevgi` command-line interface.
       # @param argv [Array<String>, String, nil] command-line arguments
       # @return [nil]
       # @raise [Sevgi::Executor::Error] when `--exception` or `SEVGI_VOMIT` requests raw executor errors
-      # @raise [SystemExit] when command-line usage or script execution aborts
+      # @raise [SystemExit] when argv does not match `[options...] [--] [file|-]` or script execution aborts
       def call(argv)
         return puts(help) if (options = Options.parse(argv = Array(argv))).help
+        return puts(Skill.path) if options.skill
         return puts(::Sevgi::VERSION) if options.version
 
-        file = argv.shift
-        handle(run(file, options), file, options)
+        file = operand(argv)
+        handle(run(file, options), options)
 
-      rescue Binaries::Sevgi::Error => e
+      rescue Skill::Error => e
         abort(e.message)
+      rescue Binaries::Sevgi::Error => e
+        abort("#{e.message}\n\n#{help}")
       end
 
       private
 
-      def die(error, _file)
-        warn(error.message)
-        warn("")
-        error.backtrace!.each { warn("  #{it}") }
-
+      def die(error)
+        message = error.message.empty? ? error.cause.class.to_s : error.message
+        warn(message, "", *error.load_backtrace.map { "  #{it}" })
         exit(1)
       end
 
-      def handle(result, file, options)
+      def handle(result, options)
         return unless result&.error?
 
         raise result.error if options.vomit || ENV[ENVVOMIT]
 
-        die(result.error, file)
+        die(result.error)
       end
 
       def help
         <<~HELP
-          Usage: #{PROGNAME} [options...] <Sevgi file>
+          Usage: #{PROGNAME} [options...] [--] [Sevgi file|-]
 
           See documentation for detailed help.
 
           Options:
 
-          -n, --nomain          Do not modify main object
+              --as NAME         Evaluate input as NAME for implicit output names
           -r, --require LIB     Require Ruby LIB
+              --skill           Display the packaged agent skill path
           -x, --exception       Raise exception instead of abort
+              --                Stop option parsing
 
           -h, --help            Show this help
           -v, --version         Display version
         HELP
       end
 
+      def operand(argv)
+        file = argv.shift
+        Error.("Unexpected argument: #{argv.first}") unless argv.empty?
+
+        file unless file == "-"
+      end
+
+      def execute_file(file, options)
+        name = source_name(options.as) if options.as
+        ::Sevgi.execute_file(file, as: name, require: options.require, main: true)
+      end
+
       def run(file, options)
-        Error.("No sevgi file given.") unless file
+        return execute_file(file, options) if file
 
-        ::Sevgi.execute_file(file, require: options.require, receiver: options.nomain ? nil : TOPLEVEL_BINDING.receiver)
+        ::Sevgi.execute($stdin.read, file: source_name(options.as), require: options.require, main: true)
+      end
+
+      def source_name(name)
+        return STDIN_NAME unless name
+
+        Error.("Option requires a name, not a path: --as") unless ::File.basename(name) == name
+        F.subext(".sevgi", name)
       end
     end
   end
+
+  private_constant :Binaries
 end

data/lib/sevgi/executor/error.rb

@@ -3,48 +3,48 @@
 module Sevgi
   class Executor
     # Raised when a source attempts to load another source already active in the same scope.
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
     class CycleError < ::Sevgi::Error
     end
 
-    # Wraps an exception raised while executing Sevgi script source.
-    class Error < ::Sevgi::Error
-      # Returns the original script exception.
-      # @return [Exception]
-      attr_reader :error
-
-      # Returns the executor scope active when the error was captured.
-      # @return [Sevgi::Executor::Scope]
-      attr_reader :scope
+    # Raised when nested Sevgi loads exceed the executor's supported active-source depth.
+    #
+    # The limit is 128 active sources, including the entry source. It does not count Ruby stack frames
+    # or guarantee protection from stack exhaustion within scripts.
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
+    class LoadDepthError < ::Sevgi::Error
+    end
 
+    # Wraps an exception raised while executing Sevgi script source. Its visited source snapshot records every source in
+    # load order. It is not the active load stack at the instant of failure.
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
+    class Error < ::Sevgi::Error
       # Builds an executor error wrapper.
       # @param error [Exception] original exception
-      # @param scope [Sevgi::Executor::Scope] executor scope active at failure time
+      # @param stack [Array<String>] source file keys visited in load order. The Array and its String entries are copied
+      #   and frozen
       # @return [void]
-      def initialize(error, scope)
-        @error = error
-        @scope = scope
+      def initialize(error, stack)
+        @cause = error
+        @stack = stack.map { it.dup.freeze }.freeze
 
         super(error.message)
       end
 
-      # Returns backtrace entries that belong to the Sevgi load stack.
-      # @return [Array<String>] filtered backtrace lines relative to the current directory
-      def backtrace!
-        sources = stack.map { ::File.expand_path(it) }
+      # Returns backtrace entries that belong to the visited Sevgi source set.
+      # @return [Array<String>] filtered backtrace lines relative to the current directory, or an empty Array when the
+      #   original exception has no backtrace
+      def load_backtrace
+        sources = @stack.map { ::File.expand_path(it) }
 
-        error
-          .backtrace
+        Array(cause.backtrace)
           .select { sources.include?(::File.expand_path(it.split(":", 2).first)) }
           .map { |line| line.delete_prefix("#{::Dir.pwd}/") }
       end
 
       # Returns the original exception as the wrapped cause.
       # @return [Exception]
-      def cause = error
-
-      # Returns the script load stack active at failure time.
-      # @return [Array<String>] script file names in load order
-      def stack = scope.stack
+      attr_reader :cause
     end
   end
 end

data/lib/sevgi/executor/result.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Sevgi
+  class Executor
+    # Describes the outcome of one executor invocation.
+    #
+    # A successful result has a value and no error. A captured script, file, or
+    # library failure has an {Executor::Error} and can retain a value produced
+    # before the failure. The source stack is an immutable snapshot in load
+    # order. It is never shared with the executor's internal mutable state.
+    #
+    # @example Inspect successful execution
+    #   result = Sevgi.execute("6 * 7")
+    #   result.success? #=> true
+    #   result.value    #=> 42
+    #
+    # @example Inspect a captured failure
+    #   result = Sevgi.execute("missing", file: "drawing.sevgi")
+    #   result.error?       #=> true
+    #   result.error.cause  #=> #<NameError ...>
+    #   result.stack        #=> ["drawing.sevgi"]
+    #
+    # @see Sevgi.execute
+    # @see Sevgi.execute_file
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
+    Result = Data.define(:value, :error, :stack) do
+      # @!attribute [r] value
+      #   @return [Object, nil] last value produced, or nil when no value was produced
+      # @!attribute [r] error
+      #   @return [Sevgi::Executor::Error, nil] captured failure, or nil after successful execution
+      # @!attribute [r] stack
+      #   @return [Array<String>] frozen owned source-path snapshot in load order
+
+      # Creates an execution result.
+      # @param value [Object, nil] last value produced before execution finished
+      # @param error [Sevgi::Executor::Error, nil] captured execution failure
+      # @param stack [Array<String>] source files visited in load order
+      # @return [void]
+      def initialize(value:, error:, stack:)
+        super(value:, error:, stack: Array(stack).map { it.dup.freeze }.freeze)
+      end
+
+      private_class_method :[]
+
+      # Reports whether execution completed without a captured error.
+      # @return [Boolean] true when execution succeeded
+      def success? = error.nil?
+
+      # Reports whether execution captured an error.
+      # @return [Boolean] true when execution failed
+      def error? = !success?
+    end
+  end
+end

data/lib/sevgi/executor/scope.rb

@@ -8,12 +8,15 @@ module Sevgi
     # fiber's executor stack. They are not shared between concurrent executions.
     # @api private
     class Scope
+      MAX_LOAD_DEPTH = 128
+      private_constant :MAX_LOAD_DEPTH
+
       # @!attribute [r] scope
       #   @return [Module] isolated module where script source is evaluated
       # @!attribute [r] recent
       #   @return [Object, nil] last expression result from the executed source
       # @!attribute [r] error
-      #   @return [Sevgi::Executor::Error, nil] captured execution error
+      #   @return [Exception, nil] captured execution error
       attr_reader :scope, :recent, :error
 
       # Creates a script execution scope.
@@ -35,7 +38,7 @@ module Sevgi
 
       # Executes one source object in this scope.
       # @param source [Sevgi::Executor::Source] source to evaluate
-      # @param receiver [Object, nil] receiver used while booting the DSL
+      # @param receiver [Object, nil] explicit boot receiver, or nil to use the isolated scope module
       # @yield optional boot block that installs DSL methods before evaluation
       # @yieldreturn [void]
       # @return [Sevgi::Executor::Scope] self, with recent or error populated
@@ -54,7 +57,7 @@ module Sevgi
       # @api private
       def capture(source, error)
         push(source)
-        @error = Executor::Error.new(error, self)
+        @error = error
         self
       end
 
@@ -77,6 +80,16 @@ module Sevgi
       # @note The stack is owned by this scope and is not shared with concurrent executions.
       def stack = @stack.keys
 
+      # Builds the immutable public result for this scope.
+      # @return [Sevgi::Executor::Result] execution result snapshot
+      # @api private
+      def result
+        sources = stack.freeze
+        error = Executor::Error.new(@error, sources) if @error
+
+        Result.new(value: recent, error:, stack: sources)
+      end
+
       # Returns the most recently pushed source.
       # @return [Sevgi::Executor::Source, nil] most recent source object
       # @api private
@@ -87,7 +100,8 @@ module Sevgi
       def boot(receiver, &boot)
         return unless boot
 
-        (receiver ||= scope).public_send(receiver.is_a?(::Module) ? :module_exec : :instance_exec, &boot)
+        receiver = scope if receiver.nil?
+        receiver.public_send(receiver.is_a?(::Module) ? :module_exec : :instance_exec, &boot)
       end
 
       def evaluate(source)
@@ -104,8 +118,13 @@ module Sevgi
       end
 
       def enter(source)
-        if @active.key?(source.identity)
-          raise Executor::CycleError, "Recursive Sevgi load: #{source.file}"
+        raise Executor::CycleError, "Recursive Sevgi load: #{source.file}" if @active.key?(source.identity)
+
+        if @active.size >= MAX_LOAD_DEPTH
+          raise(
+            Executor::LoadDepthError,
+            "Sevgi load nesting too deep (maximum #{MAX_LOAD_DEPTH} active sources): #{source.file}"
+          )
         end
 
         @active[source.identity] = source
@@ -121,11 +140,10 @@ module Sevgi
       def execute(source, receiver, &boot)
         active = enter(source)
         @recent = run(source, receiver, &boot)
-        # rubocop:disable Lint/RescueException
+        # rubocop:disable-next Lint/RescueException
       rescue Exception => e
-        @error = Executor::Error.new(e, self)
+        @error = e
         throw(:result, self)
-        # rubocop:enable Lint/RescueException
       ensure
         leave(active)
       end

data/lib/sevgi/executor/source.rb

@@ -4,38 +4,47 @@ module Sevgi
   class Executor
     # Describes Ruby source evaluated by the Sevgi executor.
     # @api private
-    Source = Data.define(:string, :file, :line) do
-      # @overload call(string:, file: nil, line: nil)
+    Source = Data.define(:string, :file, :line, :origin) do
+      # @overload call(string:, file: nil, line: nil, origin: nil)
       #   Builds a source object.
       #   @param string [String] Ruby source string
       #   @param file [String, nil] source file name for diagnostics
       #   @param line [Integer, nil] starting source line for diagnostics
+      #   @param origin [String, nil] physical source path used for load-cycle identity
       #   @return [Sevgi::Executor::Source] source object
       def self.call(...) = new(...)
 
       # Builds a source object from a file.
       # @param file [String] source file to read
+      # @param as [String, nil] logical source name used for evaluation and diagnostics
       # @return [Sevgi::Executor::Source] source object with file contents
       # @raise [Errno::ENOENT] when the file cannot be read
-      def self.load(file) = new(string: ::File.read(file), file: file, line: 1)
+      def self.load(file, as: nil) = new(string: ::File.read(file), file: as || file, line: 1, origin: file)
 
       # Creates a source object.
       # @param string [String] Ruby source string
       # @param file [String, nil] source file name for diagnostics
       # @param line [Integer, nil] starting source line for diagnostics
+      # @param origin [String, nil] physical source path used for load-cycle identity
       # @return [void]
-      def initialize(string:, file: nil, line: nil) = super(string:, file: file || "sevgi", line: line || 1)
+      def initialize(string:, file: nil, line: nil, origin: nil)
+        super(string:, file: file || "sevgi", line: line || 1, origin:)
+      end
+
+      private_class_method :[]
 
       # Returns the stack key used for this source.
       # @return [String] source file name
       def key = file
 
       # Returns the canonical identity used for active-load cycle detection.
-      # @return [String] canonical source identity
+      # @return [Integer, String] object identity for inline source, or canonical physical identity for loaded source
       def identity
-        ::File.realpath(file)
+        return object_id unless origin
+
+        ::File.realpath(origin)
       rescue ::SystemCallError
-        ::File.expand_path(file)
+        ::File.expand_path(origin)
       end
     end
   end