rush-shell 0.0.2

data/lib/rush/program_session.rb

@@ -0,0 +1,83 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Shared command-by-command session over ProgramReader. Subclasses provide the
+  # input source and tune error policy: batch source aborts on fatal errors,
+  # while the REPL reports recoverable errors and keeps reading.
+  class ProgramSession
+    extend T::Sig
+
+    sig { params(system: SystemCalls, state: ShellState, startup: T.nilable(Startup)).void }
+    def initialize(system, state: ShellState.new(pids: ShellProcessIds.for(system)), startup: nil)
+      @system = system
+      @startup = startup
+      @executor = Executor.new(system: system, state: state)
+      InteractiveSignals.install(@executor) if state.options.on?(:interactive)
+      @executor.job_control.startup
+      @reader = ProgramReader.new(aliases: executor.state.aliases) { |continuation| next_line(continuation) }
+    end
+
+    sig { returns(Integer) }
+    def run
+      executor.trap_runner.run_exit_trap(session)
+    rescue ExitSignal => e
+      executor.trap_runner.run_exit_trap(e.code)
+    end
+
+    private
+
+    sig { returns(SystemCalls) }
+    attr_reader :system
+
+    sig { returns(Executor) }
+    attr_reader :executor
+
+    sig { returns(ProgramReader) }
+    attr_reader :reader
+
+    sig { returns(Integer) }
+    def session
+      run_startup
+      run_loop
+      executor.state.last_status.exitstatus
+    end
+
+    # Login/ENV startup files run before the main input, inside the session's
+    # error policy: batch subclasses let fatal errors abort (Source#run), the
+    # REPL recovers (its override).
+    sig { void }
+    def run_startup
+      @startup&.run(executor)
+    end
+
+    sig { void }
+    def run_loop
+      until (program = read_program) == :eof
+        execute(T.cast(program, AST::List)) unless program == :error
+      end
+    end
+
+    sig { returns(T.any(AST::List, Symbol)) }
+    def read_program
+      reader.next_program
+    end
+
+    sig { params(_continuation: T::Boolean).returns(T.nilable(String)) }
+    def next_line(_continuation)
+      # :nocov:
+      raise NotImplementedError
+      # :nocov:
+    end
+
+    sig { params(program: AST::List).void }
+    def execute(program)
+      executor.run(program)
+    end
+
+    sig { params(error: StandardError).void }
+    def report(error)
+      system.stderr.puts("rush: #{error.message}")
+    end
+  end
+end

data/lib/rush/prompt.rb

@@ -0,0 +1,52 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The prompt strings (POSIX 2.5.3): PS1, PS2 and the PS4 trace prefix are
+  # re-read from the shell variables at every use — so assignments take effect
+  # mid-session — and subjected to parameter expansion ONLY (via ParamText),
+  # so a PS4 holding $(cmd) or backticks stays literal and tracing can never
+  # recurse into command execution (dash strips backticks unexecuted, errors
+  # $(cmd) back to the raw string, and expands only $((arith)) — POSIX's
+  # parameter-expansion-only text wins). Defaults:
+  # '$ ' ('# ' for a privileged shell), '> ' and '+ '. A malformed value
+  # (unterminated ${, a failing ${x?} form) falls back to the raw string: a
+  # prompt must never break the session.
+  class Prompt
+    extend T::Sig
+
+    sig { params(executor: Executor).void }
+    def initialize(executor)
+      @executor = executor
+    end
+
+    sig { returns(String) }
+    def primary
+      render('PS1', @executor.system.privileged? ? '# ' : '$ ')
+    end
+
+    sig { returns(String) }
+    def continuation
+      render('PS2', '> ')
+    end
+
+    sig { returns(String) }
+    def trace
+      render('PS4', '+ ')
+    end
+
+    private
+
+    sig { params(name: String, default: String).returns(String) }
+    def render(name, default)
+      expand(@executor.state.variables.get(name) || default)
+    end
+
+    sig { params(raw: String).returns(String) }
+    def expand(raw)
+      @executor.expander.expand_value(ParamText.new(raw).word, tilde: :none)
+    rescue ParseError, ExpansionError
+      raw
+    end
+  end
+end

data/lib/rush/redirect_scope.rb

@@ -0,0 +1,64 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Applies command redirects on top of an IoTable and owns cleanup of streams
+  # opened by those redirects. Redirect-only exec is detected by comparing the
+  # yielded table with the executor's current base table after the block returns.
+  class RedirectScope
+    extend T::Sig
+
+    sig { params(executor: T.untyped).void }
+    def initialize(executor)
+      @executor = executor
+    end
+
+    # Apply the redirects on top of a base IoTable (the executor's current one
+    # by default), yield the result, then flush+close the files those redirects
+    # opened (POSIX: a later command in the same shell sees the data). Only the
+    # streams this command opened are closed — the diff against the base leaves
+    # inherited streams and pipe ends untouched. Exception: redirect-only `exec`
+    # commits the table as the shell's base (replace_io), so it now equals that
+    # base — leave those files open so they persist for the rest of the shell
+    # rather than closing them out from under it.
+    sig do
+      type_parameters(:U)
+        .params(redirects: T::Array[AST::Redirect], base: IoTable,
+                blk: T.proc.params(io: IoTable).returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def with_redirects(redirects, base = @executor.io, &blk)
+      opened = T.let([], T::Array[FdEntry])
+      io = apply_redirects(redirects, base, opened)
+      yield io
+    ensure
+      close_redirect_io(T.must(opened), io || base)
+    end
+
+    private
+
+    sig { params(redirects: T::Array[AST::Redirect], base: IoTable, opened: T::Array[FdEntry]).returns(IoTable) }
+    def apply_redirects(redirects, base, opened)
+      redirects.reduce(base) { |io, redirect| apply_redirect(redirect, io, opened) }
+    end
+
+    sig { params(redirect: AST::Redirect, io: IoTable, opened: T::Array[FdEntry]).returns(IoTable) }
+    def apply_redirect(redirect, io, opened)
+      redirected = redirect_into(redirect, io)
+      opened.concat(redirected.opened_over(io))
+      redirected
+    end
+
+    sig { params(opened: T::Array[FdEntry], io: IoTable).void }
+    def close_redirect_io(opened, io)
+      entries = io.equal?(@executor.io) ? opened - io.entries : opened
+      IoTable.close_entries(entries, @executor.system)
+    end
+
+    sig { params(redirect: AST::Redirect, io: IoTable).returns(IoTable) }
+    def redirect_into(redirect, io)
+      target = @executor.expander.expand_value(redirect.target)
+      @executor.redirections.fetch(redirect.kind).apply(redirect, target, io, @executor.system)
+    end
+  end
+end

data/lib/rush/redirection/dup_redirect.rb

@@ -0,0 +1,58 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Redirection
+    # n>&m / n<&m — make fd n a duplicate of fd m by binding it to m's stream
+    # (the left-to-right fold means it copies whatever m points at right now),
+    # n>&- / n<&- — close fd n. The default fd is 1 for >& and 0 for <&. A target
+    # that is neither a number nor `-`, or a number whose fd is not open, is a
+    # "bad fd number" — a special-builtin error that aborts the shell with 2.
+    class DupRedirect
+      extend T::Sig
+
+      FD_TARGET = /\A\d+\z/
+
+      sig { params(default_fd: Integer).void }
+      def initialize(default_fd)
+        @default_fd = default_fd
+      end
+
+      sig { params(redirect: AST::Redirect, target: String, io: IoTable, system: SystemCalls).returns(IoTable) }
+      def apply(redirect, target, io, system)
+        fd = redirect.io_number || @default_fd
+        target == '-' ? io.with_closed(fd) : io.with_entry(fd, source(io, target, system))
+      end
+
+      private
+
+      # A number whose fd is open duplicates it; a number whose fd is not open
+      # (unset, or already closed by an earlier n>&-) is a non-fatal redirect
+      # error (status 2, shell continues); a non-number is a special-builtin
+      # error (aborts the shell).
+      sig { params(io: IoTable, target: String, system: SystemCalls).returns(FdEntry) }
+      def source(io, target, system)
+        fd = numeric(target)
+        entry = io.entry(fd)
+        raise RedirectError, "#{target}: fd not open" if entry&.closed?
+
+        return entry if entry
+
+        inherited_entry(system, fd) || raise(RedirectError, "#{target}: fd not open")
+      end
+
+      sig { params(system: SystemCalls, fd: Integer).returns(T.nilable(FdEntry)) }
+      def inherited_entry(system, fd)
+        stream = system.inherited_fd(fd)
+        FdEntry.borrowed(stream) if stream
+      end
+
+      sig { params(target: String).returns(Integer) }
+      def numeric(target)
+        raise BuiltinError, "Bad fd number: #{target}" unless target.match?(FD_TARGET)
+
+        Integer(target, 10)
+      end
+    end
+  end
+end

data/lib/rush/redirection/file_redirect.rb

@@ -0,0 +1,50 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Redirection
+    # Opens the (already-expanded) target file and binds it to the redirection's
+    # fd, returning a new IoTable. Covers <, >, >>, <> and >|, which differ only
+    # in open mode and default fd.
+    class FileRedirect
+      extend T::Sig
+
+      EXCLUSIVE = T.let(File::WRONLY | File::CREAT | File::EXCL, Integer)
+
+      sig do
+        params(mode: T.any(String, Integer), default_fd: Integer,
+               options: T.nilable(Options), protection: T.nilable(Symbol)).void
+      end
+      def initialize(mode, default_fd, options: nil, protection: nil)
+        @mode = mode
+        @default_fd = default_fd
+        @options = options
+        @protection = protection
+      end
+
+      # A failure to open the target (missing directory, permission denied, a
+      # directory where a file is expected) is a redirection error: the command
+      # is left unrun with status 2 (RedirectError), or — on a special builtin —
+      # aborts the shell, the escalation being handled one level up in
+      # CommandRunner where the command word is known.
+      sig { params(redirect: AST::Redirect, target: String, io: IoTable, system: SystemCalls).returns(IoTable) }
+      def apply(redirect, target, io, system)
+        io.with_owned(redirect.io_number || @default_fd, system.open_file(target, open_mode))
+      rescue SystemCallError
+        raise RedirectError, "#{target}: cannot redirect"
+      end
+
+      private
+
+      sig { returns(T.any(String, Integer)) }
+      def open_mode
+        noclobber? ? EXCLUSIVE : @mode
+      end
+
+      sig { returns(T::Boolean) }
+      def noclobber?
+        @protection == :noclobber && @options&.on?(:noclobber) == true
+      end
+    end
+  end
+end

data/lib/rush/redirection/here_doc_redirect.rb

@@ -0,0 +1,17 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Redirection
+    # Binds a here-document's (already-expanded) body to the redirection's fd —
+    # fd 0 by default — as a readable stream supplied by the SystemCalls port.
+    class HereDocRedirect
+      extend T::Sig
+
+      sig { params(redirect: AST::Redirect, body: String, io: IoTable, system: SystemCalls).returns(IoTable) }
+      def apply(redirect, body, io, system)
+        io.with_owned(redirect.io_number || 0, system.here_doc(body))
+      end
+    end
+  end
+end

data/lib/rush/redirection/registry.rb

@@ -0,0 +1,53 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # I/O redirection: the per-kind appliers and the registry that dispatches to them.
+  module Redirection
+    extend T::Sig
+
+    # O(1) redirection-kind -> applier lookup, populated by default_registry.
+    class Registry
+      extend T::Sig
+
+      sig { void }
+      def initialize
+        @appliers = {}
+      end
+
+      sig { params(kind: Symbol, applier: T.untyped).void }
+      def register(kind, applier)
+        @appliers[kind] = applier
+      end
+
+      sig { params(kind: Symbol).returns(T.untyped) }
+      def fetch(kind)
+        @appliers.fetch(kind)
+      end
+    end
+
+    # <> opens read-write and creates the file (POSIX), unlike the string modes.
+    DEFAULTS = {
+      in: ['r', 0, nil], out: ['w', 1, :noclobber], append: ['a', 1, nil],
+      readwrite: [File::RDWR | File::CREAT, 0, nil], clobber: ['w', 1, nil]
+    }.freeze
+
+    # Default fd for the dup operators: 1 for >&, 0 for <&.
+    DUPS = { dup_out: 1, dup_in: 0 }.freeze
+
+    sig { params(options: T.nilable(Options)).returns(Registry) }
+    def self.default_registry(options = nil)
+      Registry.new.tap do |registry|
+        DEFAULTS.each { |kind, spec| register_file(registry, kind, spec, options) }
+        DUPS.each { |kind, fd| registry.register(kind, DupRedirect.new(fd)) }
+        registry.register(:heredoc, HereDocRedirect.new)
+      end
+    end
+
+    sig { params(registry: Registry, kind: Symbol, spec: T::Array[T.untyped], options: T.nilable(Options)).void }
+    def self.register_file(registry, kind, spec, options)
+      redirect = FileRedirect.new(spec.fetch(0), spec.fetch(1), options: options, protection: spec.fetch(2))
+      registry.register(kind, redirect)
+    end
+  end
+end

data/lib/rush/repl.rb

@@ -0,0 +1,133 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # A simple interactive read-eval-print loop over the shared ProgramReader: each
+  # turn reads a complete command (continuation lines prompted with PS2) and runs
+  # it against one persistent ShellState, so variables and functions survive
+  # across lines. Prompts come from the PS1/PS2 shell variables (see Prompt) and
+  # go to stderr; `exit` and end-of-input (Ctrl-D) end the loop; errors and
+  # SIGINT are reported without ending the session (see #survive). Line
+  # editing/history and job control are deferred to later slices.
+  class Repl < ProgramSession
+    extend T::Sig
+
+    private
+
+    # A startup-file error (broken ~/.profile or ENV file) reports and keeps
+    # the interactive session alive, where a batch shell would abort.
+    sig { void }
+    def run_startup
+      survive(nil) { super }
+    end
+
+    # A real syntax error reports and resumes the session; the next turn starts
+    # fresh at PS1 (the reader discards the broken buffer per next_program call).
+    sig { returns(T.any(AST::List, Symbol)) }
+    def read_program
+      survive(:error) { super }
+    end
+
+    sig { params(continuation: T::Boolean).returns(T.nilable(String)) }
+    def next_line(continuation)
+      prompt_line(continuation)
+    end
+
+    sig { params(continuation: T::Boolean).returns(T.nilable(String)) }
+    def prompt_line(continuation)
+      text = continuation ? prompt.continuation : primary_prompt
+      system.tty? ? edited_line(text) : plain_line(text)
+    end
+
+    sig { returns(String) }
+    def primary_prompt
+      executor.trap_runner.run_pending
+      announce_jobs
+      prompt.primary
+    end
+
+    # dash's cmdloop showjobs(SHOW_CHANGED): before each PS1 under monitor
+    # mode, report every job whose state changed since it was last shown,
+    # freeing the finished ones (probed: set +m silences the reports, and
+    # the lines go to stderr with the prompts).
+    sig { void }
+    def announce_jobs
+      jobs = executor.jobs
+      jobs.announce_changed(system.stderr) if jobs.control.monitor?
+    end
+
+    # A terminal gets Reline: line editing and in-memory history, prompt drawn
+    # by the editor. Reline strips the newline the reader needs to keep lines
+    # apart, so it is restored here.
+    sig { params(text: String).returns(T.nilable(String)) }
+    def edited_line(text)
+      line = system.edit_line(text)
+      return unless line
+
+      "#{line}\n"
+    end
+
+    sig { params(text: String).returns(T.nilable(String)) }
+    def plain_line(text)
+      system.stderr.print(text)
+      system.read_line
+    end
+
+    sig { returns(Prompt) }
+    def prompt
+      @prompt ||= T.let(Prompt.new(executor), T.nilable(Prompt))
+    end
+
+    # Each interactive turn ticks the stopped-jobs exit warning (dash's
+    # cmdloop decrements job_warning per iteration): a refused exit repeated
+    # as the very next command goes through, anything later re-arms it.
+    sig { params(program: AST::List).void }
+    def execute(program)
+      executor.jobs.control.tick_warning
+      survive(nil) { super }
+    end
+
+    # The interactive survival policy: a recoverable error or a SIGINT reports,
+    # publishes its status as $?, and hands `fallback` back so the session
+    # carries on where a batch shell would abort.
+    sig do
+      type_parameters(:U)
+        .params(fallback: T.type_parameter(:U), blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def survive(fallback, &blk)
+      yield
+    rescue Error => e
+      recover(e)
+      fallback
+    end
+
+    # POSIX 2.8.1: where a non-interactive shell would exit (status 2, per
+    # Source#abort_with), the interactive shell reports the diagnostic,
+    # publishes the same status as $?, and returns to the prompt. A SIGINT
+    # publishes 130 instead, with a fresh line and no diagnostic.
+    sig { params(error: Error).void }
+    def recover(error)
+      decision = ErrorPolicy.decision(:interactive, error)
+      return interrupt if decision == :recover130
+      return recover_operational(error) if decision == :recover2
+      return if decision == :ignore
+
+      raise error
+    end
+
+    sig { params(error: Error).void }
+    def recover_operational(error)
+      report(error)
+      executor.state.record_status(Status.failure(2))
+    end
+
+    # ^C: a fresh line, $? = 130 (128+SIGINT), back to the prompt (dash
+    # behaviour whether the signal arrived at the prompt or mid-command).
+    sig { void }
+    def interrupt
+      system.stderr.puts
+      executor.state.record_status(Status.failure(130))
+    end
+  end
+end

data/lib/rush/runtime_type_checks.rb

@@ -0,0 +1,16 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module Rush
+  # Production policy for Sorbet's runtime method wrappers. This bootstrapping
+  # method deliberately has no runtime sig: its body must run before any sig
+  # block evaluates. Static Sorbet and Steep still check this source normally.
+  module RuntimeTypeChecks
+    def self.configure
+      level = ENV.fetch('RUSH_RUNTIME_TYPECHECKS', nil) == '1' ? :always : :never
+      T::Configuration.default_checked_level = level
+    end
+  end
+end

data/lib/rush/scope.rb

@@ -0,0 +1,79 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Dynamic variable scope and logical working directory for ShellVariables,
+  # layered over one Environment: `local` frames snapshot variables restored when
+  # a function returns, and logical PWD is mirrored into $PWD/$OLDPWD.
+  class Scope
+    extend T::Sig
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :pwd
+
+    sig { params(environment: Environment).void }
+    def initialize(environment)
+      @environment = environment
+      @frames = []
+      @pwd = environment.get('PWD')
+    end
+
+    # Change the logical working directory, keeping $OLDPWD (the directory we
+    # left) and $PWD (the one we entered) in step — the invariant cd relies on.
+    sig { params(pwd: String).void }
+    def move_to(pwd)
+      @environment.assign('OLDPWD', current_pwd)
+      @pwd = pwd
+      @environment.assign('PWD', pwd)
+    end
+
+    # Seed the logical pwd from the OS at startup when $PWD was unset; unlike
+    # #move_to this records no $OLDPWD/$PWD — there is no directory we came from.
+    sig { params(path: String).void }
+    def seed_pwd(path)
+      return if @pwd
+
+      @pwd = path
+    end
+
+    sig { returns(String) }
+    def current_pwd
+      @pwd || raise(Error, 'internal invariant: PWD not seeded')
+    end
+
+    # A function call brackets its body with begin/end_scope; declare_local
+    # snapshots a variable so end_scope restores its prior value (or unsets it
+    # when it had none).
+    sig { void }
+    def begin_scope
+      @frames.push({})
+    end
+
+    sig { void }
+    def end_scope
+      # pop is non-nil here (paired with begin_scope); .to_a pins its type to an
+      # array of pairs for the checker without changing behaviour on that path.
+      @frames.pop.to_a.each { |name, value| restore(name, value) }
+    end
+
+    sig { returns(T::Boolean) }
+    def in_function?
+      @frames.any?
+    end
+
+    sig { params(name: String).void }
+    def declare_local(name)
+      # last frame is non-nil here (only called inside a function); fetch(-1) pins
+      # its type to Hash for the checker and keeps the crash-if-empty invariant.
+      frame = @frames.fetch(-1)
+      frame[name] = @environment.get(name) unless frame.key?(name)
+    end
+
+    private
+
+    sig { params(name: String, value: T.nilable(String)).void }
+    def restore(name, value)
+      value ? @environment.assign(name, value) : @environment.unset(name)
+    end
+  end
+end

data/lib/rush/segment_buffer.rb

@@ -0,0 +1,47 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Accumulates a word's segments during scanning: literal characters gather
+  # into a pending run, #push closes that run as an unquoted LiteralSegment
+  # before appending a structured segment, and #word closes it once more to
+  # build the finished AST::Word. Shared by the scanners that assemble words
+  # character by character (WordScanner, HeredocBody, ParamText).
+  class SegmentBuffer
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @segments = T.let([], T::Array[AST::WordSegment[T.untyped]])
+      @literal = +''
+    end
+
+    sig { params(text: String).returns(T.self_type) }
+    def <<(text)
+      @literal << text
+      self
+    end
+
+    sig { params(segment: AST::WordSegment[T.untyped]).void }
+    def push(segment)
+      flush
+      @segments << segment
+    end
+
+    sig { returns(AST::Word) }
+    def word
+      flush
+      AST::Word.new(@segments)
+    end
+
+    private
+
+    sig { void }
+    def flush
+      return if @literal.empty?
+
+      @segments << AST::LiteralSegment.new(@literal, false)
+      @literal = +''
+    end
+  end
+end