rush-shell 0.0.2

data/lib/rush/environment.rb

@@ -0,0 +1,134 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Shell variables and the subset marked for export. The exported slice is what
+  # external children receive (see SystemCalls#spawn).
+  class Environment
+    extend T::Sig
+
+    VariableState = T.type_alias do
+      [T::Boolean, T.nilable(String), T::Boolean, T::Boolean]
+    end
+    DynamicState = T.type_alias { T.any(T::Boolean, Symbol) }
+    Snapshot = T.type_alias { [T::Hash[String, VariableState], DynamicState] }
+
+    sig { params(source: T::Hash[String, String]).void }
+    def initialize(source = ENV.to_h)
+      @vars = source.dup
+      @exported = source.keys.to_set
+      @readonly = Set.new
+      @dynamic_lineno = !@vars.key?('LINENO')
+    end
+
+    sig { params(name: String).returns(T.nilable(String)) }
+    def get(name)
+      @vars.fetch(name, nil)
+    end
+
+    sig { params(name: String, value: String).returns(String) }
+    def assign(name, value)
+      validate_assignment(name)
+      @dynamic_lineno &&= name != 'LINENO'
+      @vars[name] = value
+    end
+
+    sig { params(name: String).void }
+    def validate_assignment(name)
+      raise ReadonlyError, "#{name}: is read only" if @readonly.include?(name)
+    end
+
+    sig { params(name: String).void }
+    def export(name)
+      @exported.add(name)
+    end
+
+    sig { params(name: String).void }
+    def readonly(name)
+      @readonly.add(name)
+    end
+
+    sig { params(name: String).void }
+    def unset(name)
+      validate_assignment(name)
+      @dynamic_lineno &&= name != 'LINENO'
+      @vars.delete(name)
+      @exported.delete(name)
+    end
+
+    sig { params(line: Integer).returns(T.nilable(String)) }
+    def update_lineno(line)
+      @vars['LINENO'] = line.to_s if @dynamic_lineno
+    end
+
+    sig { returns(T::Hash[String, String]) }
+    def exported
+      # *@exported.to_a: splat needs an Array (Set splats via to_a at runtime, but
+      # the checker won't); slice keeps @vars's own order, so this is unchanged.
+      @vars.slice(*@exported.to_a)
+    end
+
+    # Prefix assignments on a regular builtin are visible/exported only for the
+    # invocation. Writes to those same names stay temporary; changes to every
+    # other shell variable remain live, matching a builtin's in-process effects.
+    sig do
+      params(values: T::Hash[String, String], blk: T.proc.returns(T.untyped)).returns(T.untyped)
+    end
+    def with_temporary(values, &blk)
+      saved = snapshot(values)
+      restore_after(saved) do
+        apply_temporary(values)
+        yield
+      end
+    end
+
+    private
+
+    sig { params(saved: Snapshot, blk: T.proc.returns(T.untyped)).returns(T.untyped) }
+    def restore_after(saved, &blk)
+      yield
+    ensure
+      restore_snapshot(saved)
+    end
+
+    sig { params(values: T::Hash[String, String]).returns(Snapshot) }
+    def snapshot(values)
+      states = values.keys.to_h { |name| [name, variable_state(name)] }
+      dynamic_lineno = values.key?('LINENO') ? @dynamic_lineno : :keep #: dynamic_state
+      [states, dynamic_lineno]
+    end
+
+    sig { params(name: String).returns(VariableState) }
+    def variable_state(name)
+      [@vars.key?(name), @vars.fetch(name, nil), @exported.include?(name), @readonly.include?(name)]
+    end
+
+    sig { params(values: T::Hash[String, String]).void }
+    def apply_temporary(values)
+      values.each { |name, value| assign(name, value).tap { export(name) } }
+    end
+
+    sig { params(saved: Snapshot).void }
+    def restore_snapshot(saved)
+      states, dynamic_lineno = saved
+      states.each { |name, state| restore_variable(name, state) }
+      restore_lineno(dynamic_lineno)
+    end
+
+    sig { params(dynamic_lineno: DynamicState).void }
+    def restore_lineno(dynamic_lineno)
+      return if dynamic_lineno == :keep
+
+      value = T.cast(dynamic_lineno, T::Boolean)
+      @dynamic_lineno = value
+    end
+
+    sig { params(name: String, state: VariableState).void }
+    def restore_variable(name, state)
+      present, value, exported, readonly = state
+      present ? @vars[name] = T.must(value) : @vars.delete(name)
+      exported ? @exported.add(name) : @exported.delete(name)
+      readonly ? @readonly.add(name) : @readonly.delete(name)
+    end
+  end
+end

data/lib/rush/errexit_context.rb

@@ -0,0 +1,68 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Tracks whether a command is executing in a POSIX "tested" context where
+  # errexit is suppressed, and performs the leaf `set -e` abort check.
+  class ErrexitContext
+    extend T::Sig
+
+    sig { params(state: ShellState).void }
+    def initialize(state)
+      @state = state
+      @tested = false
+    end
+
+    # Run the block in a "tested" context (errexit suppressed): the condition of
+    # if/while/until, the non-final part of an && / || list, a negated pipeline,
+    # and an async (&) command. Restores on exit, so the flag follows the call tree.
+    sig do
+      type_parameters(:U)
+        .params(blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def tested(&blk)
+      scoped(true, &blk)
+    end
+
+    # The inverse: a fresh untested context regardless of the caller's, the way
+    # command substitution starts one.
+    sig do
+      type_parameters(:U)
+        .params(blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def untested(&blk)
+      scoped(false, &blk)
+    end
+
+    # The errexit leaf check (POSIX 2.8.1): under `set -e`, a command failing
+    # outside a tested context aborts the shell with that status.
+    sig { params(status: Status).returns(Status) }
+    def exit_on_error(status)
+      raise ExitSignal, status.exitstatus if abort_on?(status)
+
+      status
+    end
+
+    private
+
+    sig do
+      type_parameters(:U)
+        .params(value: T::Boolean, blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def scoped(value, &blk)
+      previous = @tested
+      @tested = value
+      yield
+    ensure
+      @tested = previous
+    end
+
+    sig { params(status: Status).returns(T::Boolean) }
+    def abort_on?(status)
+      !!(@state.options.on?(:errexit) && !@tested && !status.success?)
+    end
+  end
+end

data/lib/rush/error_policy.rb

@@ -0,0 +1,64 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Pure classification table for Rush::Error at runtime boundaries. The table
+  # deliberately owns no reporting, status mutation, I/O, or EXIT lifecycle;
+  # each boundary applies the decision in its own environment.
+  class ErrorPolicy
+    extend T::Sig
+
+    CONTEXTS = %i[batch interactive subshell command signal_trap exit_trap].freeze
+    DIAGNOSTIC_DECISIONS = %i[abort2 recover2 demote2].freeze
+
+    OPERATIONAL = {
+      batch: :abort2, interactive: :recover2, subshell: :abort2,
+      command: :demote2, signal_trap: :ignore, exit_trap: :abort2
+    }.freeze
+    OWNED = {
+      batch: :propagate, interactive: :propagate, subshell: :abort2,
+      command: :propagate, signal_trap: :propagate, exit_trap: :propagate
+    }.freeze
+    INTERRUPT = {
+      batch: :interrupt130, interactive: :recover130, subshell: :abort2,
+      command: :propagate, signal_trap: :propagate, exit_trap: :propagate
+    }.freeze
+    EXIT = {
+      batch: :propagate, interactive: :propagate, subshell: :return_code,
+      command: :propagate, signal_trap: :propagate, exit_trap: :override_code
+    }.freeze
+    RETURN = {
+      batch: :propagate, interactive: :ignore, subshell: :return_code,
+      command: :propagate, signal_trap: :ignore, exit_trap: :preserve_code
+    }.freeze
+    LOOP = {
+      batch: :propagate, interactive: :propagate, subshell: :last_status,
+      command: :propagate, signal_trap: :ignore, exit_trap: :preserve_code
+    }.freeze
+    BUILTIN = OPERATIONAL.merge(signal_trap: :propagate).freeze
+
+    MATRIX = {
+      Error => OWNED,
+      ParseError => OPERATIONAL,
+      IncompleteInput => OPERATIONAL,
+      ExpansionError => OPERATIONAL,
+      InvocationError => OWNED,
+      Interrupted => INTERRUPT,
+      TestError => OWNED,
+      ReadonlyError => OPERATIONAL,
+      BuiltinError => BUILTIN,
+      RedirectError => OWNED,
+      JobError => OWNED,
+      ExitSignal => EXIT,
+      LoopControl => LOOP,
+      BreakSignal => LOOP,
+      ContinueSignal => LOOP,
+      ReturnSignal => RETURN
+    }.freeze
+
+    sig { params(context: Symbol, error: Error).returns(Symbol) }
+    def self.decision(context, error)
+      MATRIX.fetch(error.class).fetch(context)
+    end
+  end
+end

data/lib/rush/errors.rb

@@ -0,0 +1,100 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Base class for every error rush raises.
+  class Error < StandardError; end
+
+  # Raised by the parser on a syntax error (carries a human-readable location).
+  class ParseError < Error; end
+
+  # Parsing hit end of input mid-construct (an unfinished quote, compound
+  # command or here-document). A ParseError subclass, so batch callers still
+  # treat it as a syntax error; the REPL catches it to read another line.
+  class IncompleteInput < ParseError; end
+
+  # Raised during word expansion (e.g. ${x:?msg}, bad substitution).
+  class ExpansionError < Error; end
+
+  # A malformed command line at shell startup (unknown option, a missing -c/-o
+  # argument, an unreadable script file): reported on stderr and the process
+  # exits with status 2, matching dash.
+  class InvocationError < Error; end
+
+  # SIGINT in an interactive shell: the installed handler raises this at the
+  # next safe point, unwinding the current line back to the session, which
+  # publishes 130 (128+SIGINT) as $? and re-prompts — dash behaviour. Batch
+  # shells never install the handler and die with the OS default.
+  class Interrupted < Error; end
+
+  # Raised by the `test`/`[` builtin on a malformed expression (mapped to exit 2).
+  class TestError < Error; end
+
+  # Raised when assigning to or unsetting a readonly variable; like dash, this
+  # aborts the script (or just the subshell) with exit status 2.
+  class ReadonlyError < Error; end
+
+  # A special builtin used incorrectly (e.g. a non-numeric operand to
+  # exit/return). POSIX 2.8.1: such an error aborts a non-interactive shell with
+  # status 2; interactively it is reported and the shell carries on.
+  class BuiltinError < Error; end
+
+  # A redirection that fails at runtime (e.g. `n>&m` duplicating a fd that is not
+  # open): the command is not run and fails with status 2, but — unlike a
+  # special-builtin error — the shell carries on.
+  class RedirectError < Error; end
+
+  # A %job_id operand that resolves to no job (No such job / No current job /
+  # No previous job, dash's messages). The consuming builtin — jobs, wait,
+  # kill, fg, bg — prefixes its name, reports on stderr and fails with 2; the
+  # shell carries on.
+  class JobError < Error; end
+
+  # Control-flow signal: `exit` unwinds to the top level carrying a status code.
+  class ExitSignal < Error
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :code
+
+    sig { params(code: Integer).void }
+    def initialize(code)
+      @code = code
+      super("exit #{code}")
+    end
+  end
+
+  # Loop control: `break`/`continue` unwind to the enclosing loop, carrying the
+  # number of loop levels to act on.
+  class LoopControl < Error
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :count
+
+    sig { params(count: Integer).void }
+    def initialize(count)
+      @count = count
+      super('loop control')
+    end
+  end
+
+  # `break N`: unwind out of N enclosing loop levels.
+  class BreakSignal < LoopControl; end
+  # `continue N`: resume the Nth enclosing loop's next iteration.
+  class ContinueSignal < LoopControl; end
+
+  # Control-flow signal: `return` unwinds to the enclosing function call.
+  class ReturnSignal < Error
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :code
+
+    sig { params(code: Integer).void }
+    def initialize(code)
+      @code = code
+      super("return #{code}")
+    end
+  end
+end

data/lib/rush/escape_table.rb

@@ -0,0 +1,22 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Renders backslash escapes from a small table. Missing trailing characters
+  # become a literal backslash; unknown escapes keep the backslash plus character.
+  class EscapeTable
+    extend T::Sig
+
+    sig { params(table: T::Hash[String, String]).void }
+    def initialize(table)
+      @table = table
+    end
+
+    sig { params(char: T.nilable(String)).returns(String) }
+    def escape(char)
+      return '\\' unless char
+
+      @table.fetch(char) { "\\#{char}" }
+    end
+  end
+end

data/lib/rush/escaped_bracket.rb

@@ -0,0 +1,49 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Converts shell-backslash-quoted bracket members to positions where a POSIX
+  # ERE bracket treats them literally. Kept separate from PosixPattern because
+  # this is a small stateful bracket normalization, not scanner policy.
+  class EscapedBracket
+    extend T::Sig
+
+    SPECIAL = [']', '-', '^', '['].freeze
+
+    sig { params(source: String).void }
+    def initialize(source)
+      @negated = source.start_with?('[^')
+      @body = T.must(source[(@negated ? 2 : 1)...-1])
+      @literals = T.let(
+        {}, #: Hash[String, String]
+        T::Hash[String, String]
+      )
+      SPECIAL.each { |char| extract(char) }
+    end
+
+    sig { returns(String) }
+    def source
+      body = @body.gsub(/\\(.)/m, '\\1')
+      "#{prefix}#{literal(']')}#{body}#{literal('^')}#{literal('[')}#{literal('-')}]"
+    end
+
+    private
+
+    sig { returns(String) }
+    def prefix
+      @negated ? '[^' : '['
+    end
+
+    sig { params(char: String).returns(String) }
+    def literal(char)
+      @literals.fetch(char, '')
+    end
+
+    sig { params(char: String).void }
+    def extract(char)
+      escaped = "\\#{char}"
+      @literals[char] = char if @body.include?(escaped)
+      @body = @body.gsub(escaped, '')
+    end
+  end
+end

data/lib/rush/executor.rb

@@ -0,0 +1,164 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Walks the AST by polymorphic dispatch (node.execute(self)) over shared shell
+  # state, with all OS access funneled through the injected SystemCalls port. The
+  # base IoTable, builtin registry, redirection registry and expander hang off it;
+  # redirect cleanup, errexit state, signal and trap handling live in collaborators.
+  class Executor
+    extend T::Sig
+
+    sig { returns(SystemCalls) }
+    attr_reader :system
+
+    sig { returns(ShellState) }
+    attr_reader :state
+
+    sig { returns(Builtins::Registry) }
+    attr_reader :builtins
+
+    sig { returns(Redirection::Registry) }
+    attr_reader :redirections
+
+    sig { returns(Expansion::Pipeline) }
+    attr_reader :expander
+
+    sig { returns(IoTable) }
+    attr_reader :io
+
+    sig { returns(Status) }
+    attr_reader :cmd_sub_status
+
+    sig { returns(TrapRunner) }
+    attr_reader :trap_runner
+
+    sig { returns(JobTable) }
+    attr_reader :jobs
+
+    sig { returns(RedirectScope) }
+    attr_reader :redirect_scope
+
+    sig { returns(ErrexitContext) }
+    attr_reader :errexit
+
+    sig { params(system: SystemCalls, state: ShellState, builtins: Builtins::Registry).void }
+    def initialize(system:, state:, builtins: Builtins.default_registry)
+      @system = system
+      @state = state
+      @builtins = builtins
+      @redirections = Redirection.default_registry(@state.options)
+      @expander = Expansion::Pipeline.new(self)
+      @io = IoTable.standard(@system)
+      @redirect_scope = RedirectScope.new(self)
+      @errexit = ErrexitContext.new(@state)
+      @trap_runner = TrapRunner.new(self)
+      @jobs = JobTable.new(@system)
+      @state.variables.seed_pwd(@system.pwd)
+    end
+
+    # The job-control policy over this executor: a stateless view, so it is
+    # built on demand — the one durable bit (root shell or forked child) lives
+    # with the job table, which already tracks subshell entry.
+    sig { returns(JobControl) }
+    def job_control
+      JobControl.new(self)
+    end
+
+    # A redirect that fails at runtime (n>&m to a fd that is not open) leaves the
+    # command unrun with status 2; the shell carries on (RedirectError). Noexec
+    # still parses every program but suppresses its execution in batch shells;
+    # POSIX permits an interactive shell to ignore -n, which rush does.
+    sig { params(node: AST::Node).returns(Status) }
+    def run(node)
+      return @state.last_status if noexec?
+
+      @trap_runner.run_pending
+      @trap_runner.complete(node.execute(self))
+    rescue RedirectError
+      @trap_runner.complete(Status.new(2))
+    end
+
+    sig { returns(T::Boolean) }
+    def noexec?
+      @state.options.on?(:noexec) && !@state.options.on?(:interactive)
+    end
+
+    sig { params(node: AST::Node).returns(Status) }
+    def run_async(node)
+      return @state.last_status if noexec?
+
+      @state.record_status(BackgroundRunner.new(self, node).call)
+    end
+
+    # Entering a forked child environment (subshell, pipeline stage, async
+    # list, command substitution): caught traps reset (POSIX 2.11), and the
+    # job table becomes a display copy — the duplicate environment keeps the
+    # async-pid knowledge for jobs/jobs -p (POSIX 2.12, the seam that makes
+    # `wait $(jobs -p)` work in the parent), while the parent's jobs are not
+    # this environment's children: wait on them reports 127, a %id reports
+    # No such job, and $! itself survives — which also switches job-control
+    # machinery off (dash: root shell only).
+    sig { void }
+    def enter_subshell
+      @trap_runner.reset_caught_for_subshell
+      @jobs.enter_subshell
+    end
+
+    # Permanently rebind the base IoTable (the `exec` redirection-only form),
+    # unlike with_io which restores afterwards.
+    sig { params(table: IoTable).void }
+    def replace_io(table)
+      @io = table
+    end
+
+    sig { params(command: AST::SimpleCommand).returns(Status) }
+    def run_simple(command)
+      CommandRunner.new(self, command).call
+    end
+
+    # Run a compound command with its redirects bound for the whole body.
+    sig { params(command: AST::Node, redirects: T::Array[AST::Redirect]).returns(Status) }
+    def run_redirected(command, redirects)
+      @redirect_scope.with_redirects(redirects) { |io| with_io(io) { run(command) } }
+    end
+
+    # The exit status of the last command substitution performed while a simple
+    # command is being built. Reset to success at the start of each command so a
+    # no-command-word command (only assignments/redirections) reports 0 unless a
+    # substitution sets it (POSIX 2.9.1: such a command takes the status of the
+    # last command substitution). Kept off last_status so a later $? in the same
+    # command still sees the previous command's status, as dash does.
+    sig { void }
+    def reset_cmd_sub_status
+      record_cmd_sub_status(Status.success)
+    end
+
+    sig { params(status: Status).void }
+    def record_cmd_sub_status(status)
+      @cmd_sub_status = status
+    end
+
+    # Run a block with a different base IoTable (command substitution / future
+    # `exec`), restoring the previous one afterwards.
+    sig do
+      type_parameters(:U)
+        .params(io: IoTable, blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def with_io(io, &blk)
+      previous = @io
+      @io = io
+      yield
+    ensure
+      @io = previous
+    end
+
+    # Evaluate an if/while/until condition: run the command in a tested context
+    # (so a failing condition never trips errexit) and report whether it succeeded.
+    sig { params(command: AST::Node).returns(T::Boolean) }
+    def succeeds?(command)
+      @errexit.tested { run(command) }.success?
+    end
+  end
+end