rush-shell 0.0.2

data/lib/rush/function_runner.rb

@@ -0,0 +1,37 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Calls a shell function: bind the arguments as the positional parameters, run
+  # the body in the current shell, and restore the previous positionals. A scope
+  # is opened so `local` declarations are undone on return. `return` unwinds to
+  # here as a ReturnSignal.
+  class FunctionRunner
+    extend T::Sig
+
+    sig { params(executor: Executor, body: AST::Node, args: T::Array[String]).void }
+    def initialize(executor, body, args)
+      @executor = executor
+      @state = executor.state
+      @body = body
+      @args = args
+    end
+
+    # A function body runs inside a ShellState-owned function frame: locals are
+    # scoped, positionals are rebound, and loop depth is reset (POSIX 2.9.5).
+    sig { returns(Status) }
+    def call
+      @state.with_function_frame(@args) { invoke }
+    end
+
+    private
+
+    sig { returns(Status) }
+    def invoke
+      @executor.run(@body)
+      @state.last_status
+    rescue ReturnSignal => e
+      Status.new(e.code)
+    end
+  end
+end

data/lib/rush/function_table.rb

@@ -0,0 +1,35 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Name -> function body (an AST node), defined by function definitions and
+  # looked up during command dispatch.
+  class FunctionTable
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @functions = {}
+    end
+
+    sig { params(name: String, body: AST::Node).returns(AST::Node) }
+    def define(name, body)
+      @functions[name] = body
+    end
+
+    sig { params(name: String).returns(T.nilable(AST::Node)) }
+    def undefine(name)
+      @functions.delete(name)
+    end
+
+    sig { params(name: String).returns(AST::Node) }
+    def fetch(name)
+      @functions.fetch(name)
+    end
+
+    sig { params(name: String).returns(T::Boolean) }
+    def key?(name)
+      @functions.key?(name)
+    end
+  end
+end

data/lib/rush/getopts_parser.rb

@@ -0,0 +1,195 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Normal vs silent getopts error-mode formatting for bad options and missing
+  # arguments.
+  class GetoptsErrorMode
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :missing_name
+
+    sig { params(mode: Symbol).void }
+    def initialize(mode)
+      @missing_name = mode == :silent ? ':' : '?'
+      @keep_optarg = mode == :silent
+      @diagnostic = mode == :normal
+    end
+
+    sig { params(value: String).returns(T.nilable(String)) }
+    def optarg(value)
+      value if @keep_optarg
+    end
+
+    sig { params(text: String).returns(T.nilable(String)) }
+    def message(text)
+      text if @diagnostic
+    end
+  end
+
+  # The getopts optstring operand (POSIX `getopts optstring name [arg...]`):
+  # a leading colon selects silent error reporting, then each option letter,
+  # `:`-suffixed when it requires an argument. Owns which letters are legal
+  # and which take arguments; the parser keeps the cursor choreography.
+  class Optstring
+    extend T::Sig
+
+    sig { returns(GetoptsErrorMode) }
+    attr_reader :error_mode
+
+    sig { params(text: String).void }
+    def initialize(text)
+      @error_mode = GetoptsErrorMode.new(text.start_with?(':') ? :silent : :normal)
+      @letters = text.delete_prefix(':')
+    end
+
+    sig { params(option: String).returns(T::Boolean) }
+    def valid?(option)
+      !!(option != ':' && index(option))
+    end
+
+    sig { params(option: String).returns(T::Boolean) }
+    def requires_argument?(option)
+      position = index(option)
+      !!(position && @letters[position + 1] == ':')
+    end
+
+    private
+
+    sig { params(option: String).returns(T.nilable(Integer)) }
+    def index(option)
+      @letters.index(option)
+    end
+  end
+
+  # Pure parser for one POSIX getopts step. It walks the argv words and the
+  # hidden cluster cursor against the Optstring's semantics; the builtin
+  # applies the returned variable updates.
+  class GetoptsParser
+    extend T::Sig
+
+    # Sentinel optarg: leave OPTARG untouched (a real optarg is always a
+    # String, so a Symbol can never collide with one).
+    KEEP = :keep
+    # The variable updates and status produced by one getopts step.
+    Result = Data.define(:name, :optarg, :optind, :message, :exitstatus)
+    # The option character plus the argv word it came from.
+    Option = Data.define(:argument, :name)
+
+    sig { params(state: GetoptsState, optstring: String, arguments: T::Array[String], optind: Integer).void }
+    def initialize(state:, optstring:, arguments:, optind:)
+      @state = state
+      @optstring = Optstring.new(optstring)
+      @error_mode = @optstring.error_mode
+      @arguments = arguments
+      @state.prepare(arguments, optind)
+    end
+
+    sig { returns(Result) }
+    def call
+      arg = @state.current(@arguments)
+      return finish if !arg || arg == '-' || !arg.start_with?('-')
+      return finish_double_dash if arg == '--'
+
+      dispatch(option(arg))
+    end
+
+    private
+
+    sig { params(option: Option).returns(Result) }
+    def dispatch(option)
+      name = option.name
+      return invalid(option) unless @optstring.valid?(name)
+      return argument_value(option) if @optstring.requires_argument?(name)
+
+      found(name, '')
+    end
+
+    sig { params(name: String, value: String).returns(Result) }
+    def found(name, value)
+      consume_found(value)
+      result(name, value, nil, 0)
+    end
+
+    sig { params(option: Option).returns(Result) }
+    def invalid(option)
+      name = option.name
+      @state.consume_option(option.argument)
+      error_result('?', name, "Illegal option -#{name}")
+    end
+
+    sig { params(option: Option).returns(Result) }
+    def missing(option)
+      consume_missing(option.argument)
+      error_result(@error_mode.missing_name, option.name, "No arg for -#{option.name} option")
+    end
+
+    sig { returns(Result) }
+    def finish
+      @state.finish
+      result('?', KEEP, nil, 1)
+    end
+
+    sig { returns(Result) }
+    def finish_double_dash
+      @state.finish_double_dash
+      result('?', KEEP, nil, 1)
+    end
+
+    sig { params(value: String).void }
+    def consume_found(value)
+      current = T.must(@state.current(@arguments))
+      return @state.consume_option(current) unless @optstring.requires_argument?(@state.option(current))
+
+      attached_value?(current, value) ? @state.consume_attached_argument : @state.consume_detached_argument
+    end
+
+    sig { params(_argument: String).void }
+    def consume_missing(_argument)
+      @state.consume_attached_argument
+    end
+
+    sig { params(option: Option).returns(Result) }
+    def argument_value(option)
+      return found(option.name, attached_argument(option.argument)) if attached?(option.argument)
+
+      next_argument ? found(option.name, T.must(next_argument)) : missing(option)
+    end
+
+    sig { params(name: String, silent_optarg: String, normal_message: String).returns(Result) }
+    def error_result(name, silent_optarg, normal_message)
+      result(name, @error_mode.optarg(silent_optarg), @error_mode.message(normal_message), 0)
+    end
+
+    sig { params(name: String, optarg: T.untyped, message: T.nilable(String), exitstatus: Integer).returns(Result) }
+    def result(name, optarg, message, exitstatus)
+      Result.new(name: name, optarg: optarg, optind: @state.optind, message: message, exitstatus: exitstatus)
+    end
+
+    sig { params(argument: String).returns(Option) }
+    def option(argument)
+      Option.new(argument: argument, name: @state.option(argument))
+    end
+
+    sig { params(argument: String).returns(String) }
+    def attached_argument(argument)
+      argument[(@state.cursor + 1)..].to_s
+    end
+
+    sig { params(argument: String, value: String).returns(T::Boolean) }
+    def attached_value?(argument, value)
+      !value.empty? && attached?(argument)
+    end
+
+    sig { params(argument: String).returns(T::Boolean) }
+    def attached?(argument)
+      @state.cursor < argument.length - 1
+    end
+
+    sig { returns(T.nilable(String)) }
+    def next_argument
+      @arguments[@state.current_index + 1]
+    end
+  end
+end

data/lib/rush/getopts_state.rb

@@ -0,0 +1,104 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Cursor state for POSIX getopts. OPTIND is public and 1-based, but while
+  # parsing an option cluster such as -ab dash already publishes OPTIND=2 after
+  # returning -a; the private cursor still points at b in argv[0]. This object
+  # keeps that hidden intra-argument cursor and resets it when OPTIND or the
+  # argument vector changes.
+  class GetoptsState
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :current_index, :cursor, :optind
+
+    sig { void }
+    def initialize
+      @signature = nil
+      @current_index = 0
+      @cursor = 1
+      @optind = 1
+    end
+
+    sig { params(arguments: T::Array[String], optind: Integer).void }
+    def prepare(arguments, optind)
+      signature = arguments.join("\0")
+      reset(signature, optind) if signature != @signature || optind != @optind
+    end
+
+    sig { params(arguments: T::Array[String]).returns(T.nilable(String)) }
+    def current(arguments)
+      arguments[@current_index]
+    end
+
+    sig { params(argument: String).returns(String) }
+    def option(argument)
+      T.must(argument[@cursor])
+    end
+
+    sig { params(argument: String).void }
+    def consume_option(argument)
+      cluster_remains?(argument) ? consume_cluster : consume_final_option
+    end
+
+    sig { params(argument: String).returns(T::Boolean) }
+    def cluster_remains?(argument)
+      @cursor < argument.length - 1
+    end
+
+    sig { void }
+    def consume_cluster
+      @cursor += 1
+      @optind = @current_index + 2
+    end
+
+    sig { void }
+    def consume_final_option
+      @current_index += 1
+      @cursor = 1
+      publish
+    end
+
+    sig { void }
+    def consume_attached_argument
+      @current_index += 1
+      @cursor = 1
+      publish
+    end
+
+    sig { void }
+    def consume_detached_argument
+      @current_index += 2
+      @cursor = 1
+      publish
+    end
+
+    sig { void }
+    def finish
+      @cursor = 1
+      publish
+    end
+
+    sig { void }
+    def finish_double_dash
+      @current_index += 1
+      finish
+    end
+
+    private
+
+    sig { params(signature: String, optind: Integer).void }
+    def reset(signature, optind)
+      @signature = signature
+      @current_index = [optind - 1, 0].max
+      @cursor = 1
+      publish
+    end
+
+    sig { void }
+    def publish
+      @optind = @current_index + 1
+    end
+  end
+end

data/lib/rush/here_doc.rb

@@ -0,0 +1,57 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # A here-document redirect target. The lexer creates it when it sees `<<word`
+  # (recording the delimiter, whether it was quoted, and the `<<-` tab strip),
+  # then fills #body — an AST::Word — once it collects the body lines at the next
+  # newline. It quacks like a Word (responds to #segments) so the expansion
+  # pipeline expands the body as a single field at execution time.
+  class HereDoc
+    extend T::Sig
+
+    # Immutable metadata captured from the delimiter token.
+    Definition = Data.define(:delimiter, :quoted, :strip, :source_line)
+
+    sig { returns(AST::Word) }
+    attr_reader :body
+
+    sig { params(delimiter: String, quoted: T::Boolean, strip: T::Boolean, source_line: Integer).void }
+    def initialize(delimiter:, quoted:, strip:, source_line: 1)
+      @definition = Definition.new(delimiter, quoted, strip, source_line)
+      @body = AST::Word.new([], source_line: source_line)
+    end
+
+    sig { returns(String) }
+    def delimiter
+      @definition.delimiter
+    end
+
+    sig { returns(T::Boolean) }
+    def quoted
+      @definition.quoted
+    end
+
+    sig { returns(T::Boolean) }
+    def strip
+      @definition.strip
+    end
+
+    sig { returns(Integer) }
+    def source_line
+      @definition.source_line
+    end
+
+    # The lexer fills the body — an AST::Word — once it has gathered the body
+    # lines at the next newline; it is the only writer, so #body stays read-only.
+    sig { params(body: AST::Word).void }
+    def fill(body)
+      @body = body
+    end
+
+    sig { returns(T::Array[AST::WordSegment[T.untyped]]) }
+    def segments
+      @body.segments
+    end
+  end
+end

data/lib/rush/interactive_signals.rb

@@ -0,0 +1,26 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The interactive shell's default signal dispositions (POSIX: "ignored in a
+  # manner that allows trap to work"; dash is the oracle): SIGINT interrupts
+  # the current line — its handler raises Interrupted, which the session turns
+  # into $?=130 and a fresh prompt — while SIGQUIT and SIGTERM are swallowed by
+  # no-op handlers. All three are handler blocks rather than SIG_IGN, so
+  # children spawned via exec revert to the OS defaults. `trap` overrides
+  # them; `trap -` and subshells restore through TrapRunner's base table.
+  class InteractiveSignals
+    extend T::Sig
+
+    # Non-lambda procs: Signal.trap calls handlers with the signal number, and
+    # a strict lambda would die on the extra argument.
+    sig { params(executor: Executor).void }
+    def self.install(executor)
+      executor.trap_runner.install_base(
+        'INT' => proc { raise Interrupted, 'interrupted' },
+        'QUIT' => proc {},
+        'TERM' => proc {}
+      )
+    end
+  end
+end

data/lib/rush/invocation.rb

@@ -0,0 +1,190 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Consumes the leading -/+ option clusters of an `sh` argv — the set-builtin
+  # letters plus -c, -i, -s and `-o name`, ending at `--` or the first operand —
+  # leaving the operands in place. Exposes the explicit option settings and
+  # whether -c was given.
+  class InvocationFlags
+    extend T::Sig
+
+    FLAGS = Options::LETTERS.merge('i' => :interactive, 's' => :stdin, 'l' => :login).freeze
+
+    sig { returns(T::Hash[Symbol, T::Boolean]) }
+    attr_reader :settings
+
+    sig { returns(T::Boolean) }
+    attr_reader :command
+
+    sig { params(argv: T::Array[String]).void }
+    def initialize(argv)
+      @argv = argv
+      @settings = T.let(
+        {}, #: Hash[Symbol, bool]
+        T::Hash[Symbol, T::Boolean]
+      )
+      @command = T.let(false, T::Boolean)
+      consume_clusters
+      # `--` or the obsolescent lone `-` ends the options and is consumed
+      # (POSIX sh synopsis; dash-verified: `sh -` reads stdin, `sh - file`
+      # runs the file, while a `-` after the -c string stays $0).
+      @argv.shift if ['--', '-'].include?(@argv.first)
+    end
+
+    private
+
+    sig { void }
+    def consume_clusters
+      while (cluster = OptionCluster.parse(@argv.first))
+        @argv.shift
+        apply_cluster(cluster)
+      end
+    end
+
+    sig { params(cluster: OptionCluster).void }
+    def apply_cluster(cluster)
+      cluster.each_letter { |letter, sign| apply_letter(letter, sign) }
+    end
+
+    sig { params(letter: String, sign: String).void }
+    def apply_letter(letter, sign)
+      case letter
+      when 'c' then enable_command(sign)
+      when 'o' then apply_long(sign, @argv.shift)
+      else apply_flag(letter, sign)
+      end
+    end
+
+    sig { params(sign: String).void }
+    def enable_command(sign)
+      raise InvocationError, "Illegal option #{sign}c" unless sign == '-'
+
+      @command = true
+    end
+
+    sig { params(sign: String, option_name: T.nilable(String)).void }
+    def apply_long(sign, option_name)
+      raise InvocationError, "#{sign}o requires an argument" unless option_name
+
+      option = Options::LONG.fetch(option_name) do
+        raise InvocationError, "Illegal option #{sign}o #{option_name}"
+      end
+      @settings[option] = sign == '-'
+    end
+
+    sig { params(letter: String, sign: String).void }
+    def apply_flag(letter, sign)
+      option = FLAGS.fetch(letter) { raise InvocationError, "Illegal option #{sign}#{letter}" }
+      @settings[option] = sign == '-'
+    end
+  end
+
+  # Parsed `sh` invocation: option flags (via InvocationFlags), then operands.
+  # Picks the program input — -c command string, script file, or stdin — and
+  # decides POSIX interactivity (-i, or no operands, no -c, and stdin and
+  # stderr both attached to a terminal), building the session it all implies.
+  class Invocation
+    extend T::Sig
+
+    sig { params(argv: T::Array[String], system: SystemCalls).void }
+    def initialize(argv, system)
+      @system = system
+      rest = argv.dup
+      @flags = T.let(InvocationFlags.new(rest), InvocationFlags)
+      @operands = T.let(rest, T::Array[String])
+      @input = T.let(build_input, T.any(CommandInput, ScriptInput, StdinInput))
+    end
+
+    # The session this invocation implies, wired to its shell state and
+    # startup files (login profiles, interactive ENV).
+    sig { returns(ProgramSession) }
+    def session
+      state = shell_state
+      return Repl.new(@system, state: state, startup: startup) if repl?
+
+      Source.new(self, @system, state: state, startup: startup)
+    end
+
+    sig { returns(T::Boolean) }
+    def repl?
+      interactive? && stdin_source?
+    end
+
+    sig { returns(T::Boolean) }
+    def interactive?
+      @flags.settings.fetch(:interactive) { auto_interactive? }
+    end
+
+    # A login shell: -l, or invoked with a leading '-' in the program name
+    # (how login(1) execs a shell). dash accepts -l the same way; POSIX leaves
+    # login files unspecified, so the oracle decides.
+    sig { returns(T::Boolean) }
+    def login?
+      @flags.settings.fetch(:login) { @system.program_name.start_with?('-') }
+    end
+
+    sig { returns(String) }
+    def name
+      @input.name
+    end
+
+    sig { returns(T::Array[String]) }
+    def positionals
+      @input.positionals
+    end
+
+    # The option flags the session starts with: the explicit -/+ settings plus
+    # the ones POSIX derives implicitly (s for a stdin source, i when
+    # interactive, and monitor defaulting to interactivity — dash's unset
+    # mflag resolves to iflag, probed: `dash -i` on a tty reports smi), so $-
+    # reports them like dash does.
+    sig { returns(T::Hash[Symbol, T::Boolean]) }
+    def shell_flags
+      { monitor: interactive? }.merge(@flags.settings).merge(stdin: stdin_source?, interactive: interactive?)
+    end
+
+    # The program text (read lazily: a REPL session never gets here).
+    sig { returns(String) }
+    def source
+      @input.source
+    end
+
+    private
+
+    sig { returns(T.any(CommandInput, ScriptInput, StdinInput)) }
+    def build_input
+      return CommandInput.new(@operands) if @flags.command
+      return StdinInput.new(@operands, @system) if stdin_source?
+
+      ScriptInput.new(@operands, @system)
+    end
+
+    sig { returns(ShellState) }
+    def shell_state
+      state = ShellState.new(name: name, positional: positionals, pids: ShellProcessIds.for(@system))
+      shell_flags.each { |option, enabled| state.set_option(option, enabled) }
+      state
+    end
+
+    sig { returns(Startup) }
+    def startup
+      Startup.new(login: login?, interactive: interactive?)
+    end
+
+    # POSIX sh: with no -i, interactive only when reading stdin implicitly on a
+    # terminal — no operands, and stdin and stderr both ttys. (-c with no
+    # command string never gets to run: #source rejects it first.)
+    sig { returns(T::Boolean) }
+    def auto_interactive?
+      @operands.empty? && @system.tty? && @system.stderr_tty?
+    end
+
+    sig { returns(T::Boolean) }
+    def stdin_source?
+      return false if @flags.command
+
+      @flags.settings.fetch(:stdin) { @operands.empty? }
+    end
+  end
+end