rush-shell 0.0.2

data/lib/rush/shell_parameters.rb

@@ -0,0 +1,77 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Resolves shell parameters from the namespaces a shell exposes: ordinary
+  # variables, special parameters ($?, $#, $$, $0, $@/$*, $-, $!), and positional
+  # parameters ($1, $2, ...). $$ is the original shell pid stored in ShellState,
+  # so forked subshells and command substitutions preserve it like POSIX shells.
+  class ShellParameters
+    extend T::Sig
+
+    sig { params(state: T.untyped).void }
+    def initialize(state)
+      @state = state
+    end
+
+    sig { params(parameter: String).returns(T.nilable(String)) }
+    def resolve(parameter)
+      return @state.pids.shell.to_s if parameter == '$'
+
+      special = special_parameters.fetch(parameter, nil)
+      special ? special.call : ordinary_or_positional(parameter)
+    end
+
+    private
+
+    sig { returns(T::Hash[String, T.proc.returns(T.nilable(String))]) }
+    def special_parameters
+      { '?' => -> { status }, '#' => -> { count }, '0' => -> { @state.name },
+        '@' => -> { positional_all }, '*' => -> { positional_all }, '-' => -> { options },
+        '!' => -> { background } }
+    end
+
+    sig { returns(String) }
+    def status
+      @state.last_status.exitstatus.to_s
+    end
+
+    sig { returns(String) }
+    def count
+      @state.positional.size.to_s
+    end
+
+    sig { returns(String) }
+    def positional_all
+      @state.positional.join(separator)
+    end
+
+    sig { returns(String) }
+    def separator
+      ifs = @state.variables.get('IFS')
+      ifs ? (ifs.each_char.first || '') : ' '
+    end
+
+    sig { returns(String) }
+    def options
+      @state.options.letters
+    end
+
+    sig { returns(T.nilable(String)) }
+    def background
+      @state.last_background_pid&.to_s
+    end
+
+    sig { params(parameter: String).returns(T.nilable(String)) }
+    def ordinary_or_positional(parameter)
+      return positional(Integer(parameter, 10)) if parameter.match?(/\A\d+\z/)
+
+      @state.variables.get(parameter)
+    end
+
+    sig { params(index: Integer).returns(T.nilable(String)) }
+    def positional(index)
+      @state.positional[index - 1]
+    end
+  end
+end

data/lib/rush/shell_pattern.rb

@@ -0,0 +1,80 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # A shell `case`/parameter/pathname pattern. Ruby handles ordinary patterns;
+  # patterns containing POSIX bracket subforms are compiled to a Ruby regexp,
+  # while #glob_source broadens those brackets for Dir.glob candidate discovery.
+  # :reek:InstanceVariableAssumption -- @scanner is initialized by PatternScanner#initialize
+  class ShellPattern < PatternScanner
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :glob_source
+
+    sig { params(source: String).void }
+    def initialize(source)
+      @regexp = +''
+      @glob_source = +''
+      @extended = false
+      super
+    end
+
+    sig { returns(T::Boolean) }
+    def extended?
+      @extended
+    end
+
+    sig { params(text: String).returns(T::Boolean) }
+    def match?(text)
+      return File.fnmatch(@scanner.string, text, File::FNM_DOTMATCH) unless extended?
+
+      Regexp.new("\\A#{@regexp}\\z", Regexp::MULTILINE).match?(text)
+    rescue RegexpError
+      false
+    end
+
+    sig { params(text: String).returns(T::Boolean) }
+    def ===(text)
+      match?(text)
+    end
+
+    private
+
+    sig { void }
+    def append_escape
+      @scanner.getch
+      escaped = @scanner.getch
+      @glob_source << '\\' << escaped.to_s
+      @regexp << Regexp.escape(escaped || '\\')
+    end
+
+    sig { void }
+    def append_wildcard
+      char = @scanner.getch.to_s
+      @glob_source << char
+      @regexp << (char == '*' ? '.*' : '.')
+    end
+
+    sig { void }
+    def append_bracket
+      bracket = BracketExpression.parse(@scanner.string, @scanner.pos)
+      return append_literal unless bracket
+
+      append_expression(bracket)
+    end
+
+    sig { params(bracket: BracketExpression).void }
+    def append_expression(bracket)
+      bracket.append_to(@regexp, @glob_source, @scanner)
+      @extended = bracket.special? || @extended
+    end
+
+    sig { void }
+    def append_literal
+      char = @scanner.getch.to_s
+      @glob_source << char
+      @regexp << Regexp.escape(char)
+    end
+  end
+end

data/lib/rush/shell_state.rb

@@ -0,0 +1,163 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Original shell and parent process ids used for $$ and PPID.
+  ShellProcessIds = Data.define(:shell, :parent) do
+    extend T::Sig
+
+    sig { params(system: SystemCalls).returns(ShellProcessIds) }
+    def self.for(system)
+      new(system.pid, system.ppid)
+    end
+  end
+
+  # The mutable shell state threaded through execution: shell variables,
+  # the last command's status ($?, the one field with behaviour here), the shell
+  # name ($0), and the session sub-objects it bundles for the rest of the
+  # interpreter to drive directly — LoopNesting, Options, Positional, the
+  # function/alias/trap tables and the command-location cache.
+  class ShellState
+    extend T::Sig
+
+    sig { returns(FunctionTable) }
+    attr_reader :functions
+
+    sig { returns(TrapTable) }
+    attr_reader :traps
+
+    sig { returns(AliasTable) }
+    attr_reader :aliases
+
+    sig { returns(T::Hash[String, String]) }
+    attr_reader :command_hash
+
+    sig { returns(String) }
+    attr_reader :name
+
+    # $$ and PPID stay the original ids in forked children, like POSIX shells.
+    sig { returns(ShellProcessIds) }
+    attr_reader :pids
+
+    sig { returns(ShellVariables) }
+    attr_reader :variables
+
+    sig { returns(LoopNesting) }
+    attr_reader :loops
+
+    sig { returns(Options) }
+    attr_reader :options
+
+    sig { returns(Status) }
+    attr_reader :last_status
+
+    sig { returns(T.nilable(Integer)) }
+    attr_reader :last_background_pid
+
+    sig { returns(Positional) }
+    attr_reader :positional
+
+    sig { returns(GetoptsState) }
+    attr_reader :getopts
+
+    # The one wiring point for every shell sub-table. Thirteen tables put the
+    # ABC size at ~18 from breadth alone — 13 assignments and 13 constructor
+    # sends, zero branches — and going lower would mean bundling namespaces
+    # POSIX keeps distinct (aliases are pre-parse substitution, not command
+    # search), so the disable stays as the measured wiring floor.
+    # rubocop:disable Metrics/AbcSize
+    sig { params(environment: Environment, name: String, positional: T::Array[String], pids: ShellProcessIds).void }
+    def initialize(environment: Environment.new, name: 'rush', positional: [], pids: ShellProcessIds.new(0, 0))
+      @name = name
+      @pids = pids
+      @variables = ShellVariables.new(environment)
+      @traps = TrapTable.new
+      @last_status = Status.success
+      @last_background_pid = T.let(nil, T.nilable(Integer))
+      @loops = LoopNesting.new
+      @options = Options.new
+      @positional = Positional.new(positional)
+      @getopts = GetoptsState.new
+      @functions = FunctionTable.new
+      @aliases = AliasTable.new
+      @command_hash = {}
+      seed_variables
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # A stateless view over this state, built on demand like Executor#job_control.
+    sig { returns(ShellParameters) }
+    def parameters
+      ShellParameters.new(self)
+    end
+
+    sig do
+      type_parameters(:U)
+        .params(args: T::Array[String], blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def with_function_frame(args, &blk)
+      FunctionFrame.new(variables: @variables, loops: @loops, positional: @positional).call(args, &blk)
+    end
+
+    sig do
+      type_parameters(:U)
+        .params(blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def with_loop(&blk)
+      @loops.enter
+      yield
+    ensure
+      @loops.leave
+    end
+
+    sig do
+      type_parameters(:U)
+        .params(blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def preserve_status(&blk)
+      saved = @last_status
+      yield
+    ensure
+      @last_status = T.must(saved)
+    end
+
+    # Flip an ordinary shell option, keeping the side effects options carry in
+    # sync (allexport mirrors onto the variable table). Invocation also uses
+    # this before an executor exists; live :monitor changes instead belong to
+    # JobControl, which owns the signal/terminal/process-group side effects.
+    sig { params(option: Symbol, enabled: T::Boolean).void }
+    def set_option(option, enabled)
+      @options.set(option, enabled)
+      @variables.allexport = enabled if option == :allexport
+    end
+
+    # The last command's exit status ($?), recorded after each command runs.
+    sig { params(status: Status).returns(Status) }
+    def record_status(status)
+      @last_status = status
+    end
+
+    sig { params(pid: Integer).returns(Integer) }
+    def record_background_pid(pid)
+      @last_background_pid = pid
+    end
+
+    sig { params(line: Integer).void }
+    def record_lineno(line)
+      @variables.update_lineno(line)
+    end
+
+    private
+
+    # The variables a POSIX shell is born with: PPID (2.5.3) and getopts'
+    # OPTIND, initialized to 1 at shell startup.
+    sig { void }
+    def seed_variables
+      @variables.assign('PPID', @pids.parent.to_s)
+      @variables.assign('OPTIND', '1')
+    end
+  end
+end

data/lib/rush/shell_variables.rb

@@ -0,0 +1,67 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Rush
+  # Semantic facade for shell variables: ordinary get/assign/export/readonly
+  # operations plus dynamic local scopes and logical PWD tracking delegated to
+  # Scope. Environment and Scope remain storage details behind this API.
+  class ShellVariables
+    extend T::Sig
+    extend Forwardable
+
+    def_delegators :@environment, :get, :export, :readonly, :unset, :exported, :update_lineno, :with_temporary,
+                   :validate_assignment
+    def_delegators :@scope, :pwd, :move_to, :seed_pwd, :current_pwd,
+                   :begin_scope, :end_scope, :in_function?, :declare_local
+
+    sig { params(environment: Environment).void }
+    def initialize(environment)
+      @environment = environment
+      @scope = Scope.new(environment)
+      @assignments = Assignments.new(self)
+      @allexport = false
+    end
+
+    sig { params(enabled: T::Boolean).void }
+    def allexport=(enabled)
+      @allexport = enabled == true
+    end
+
+    sig { returns(T::Array[String]) }
+    def locale_settings
+      %w[LC_COLLATE LC_CTYPE].map { |category| locale(category) }
+    end
+
+    # The locale name for one category: a non-empty LC_ALL overrides the
+    # category-specific variable, then LANG, with the POSIX locale as default.
+    sig { params(category: String).returns(String) }
+    def locale(category)
+      names = ['LC_ALL', category, 'LANG']
+      names.filter_map { |name| get(name) }.reject(&:empty?).first || 'C'
+    end
+
+    sig { params(name: String, value: String).returns(String) }
+    def assign(name, value)
+      @environment.assign(name, value)
+      export(name) if @allexport
+      value
+    end
+
+    sig { params(text: String).void }
+    def export_operand(text)
+      export(@assignments.apply(text))
+    end
+
+    sig { params(text: String).void }
+    def readonly_operand(text)
+      readonly(@assignments.apply(text))
+    end
+
+    sig { params(text: String).void }
+    def declare_local_operand(text)
+      @assignments.apply_local(text)
+    end
+  end
+end

data/lib/rush/signal_report.rb

@@ -0,0 +1,41 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # dash's printsignal(): when a foreground wait reaps a child that died by a
+  # signal other than SIGINT/SIGPIPE, the shell writes the strsignal
+  # description — "Killed", "Terminated", " (core dumped)" suffixed when the
+  # OS recorded a dump — to the stderr in effect at that wait. The wait
+  # builtin reports the same for pid/%id operands; a bare `wait` never
+  # reports (probed, rush-hkp). Methods are explicit singletons, like
+  # Signals (module_function leaves unkillable instance-side copies).
+  module SignalReport
+    extend T::Sig
+
+    # dash's exclusions: SIGINT ends interactive commands routinely and
+    # SIGPIPE is the normal fate of a producer feeding a finished consumer.
+    SILENT = T.let([Signals.number('INT'), Signals.number('PIPE')].freeze, T::Array[Integer])
+
+    # Report onto err and hand the status back, so reap sites stay
+    # expressions. A closed stderr swallows the report, not the status.
+    sig { params(status: Status, err: T.untyped).returns(Status) }
+    def self.report(status, err)
+      err.puts(line(status)) if report?(status)
+      status
+    rescue Errno::EBADF
+      status
+    end
+
+    sig { params(status: Status).returns(T::Boolean) }
+    def self.report?(status)
+      signal = status.termsig
+      !!signal && !SILENT.include?(signal)
+    end
+
+    sig { params(status: Status).returns(String) }
+    def self.line(status)
+      description = Signals.description(T.must(status.termsig))
+      status.coredump? ? "#{description} (core dumped)" : description
+    end
+  end
+end

data/lib/rush/signals.rb

@@ -0,0 +1,68 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Resolves a trap signal spec to a single canonical name. Numbers map through
+  # the POSIX signal table, names match case-insensitively and without a "SIG"
+  # prefix, and 0/EXIT denote the pseudo-signal that fires when the shell exits.
+  # An unknown spec resolves to nil so `trap` can report "bad trap" (dash parity).
+  # Methods are explicit singletons: module_function would define a second,
+  # instance-side copy that callers never reach — dead weight mutant proved
+  # unkillable (journal, rush-211.8).
+  module Signals
+    extend T::Sig
+
+    EXIT = 'EXIT'
+    NUMBERS = {
+      0 => EXIT, 1 => 'HUP', 2 => 'INT', 3 => 'QUIT', 4 => 'ILL', 5 => 'TRAP',
+      6 => 'ABRT', 7 => 'BUS', 8 => 'FPE', 9 => 'KILL', 10 => 'USR1',
+      11 => 'SEGV', 12 => 'USR2', 13 => 'PIPE', 14 => 'ALRM', 15 => 'TERM',
+      17 => 'CHLD', 18 => 'CONT', 19 => 'STOP', 20 => 'TSTP', 21 => 'TTIN',
+      22 => 'TTOU', 23 => 'URG', 24 => 'XCPU', 25 => 'XFSZ', 26 => 'VTALRM',
+      27 => 'PROF', 28 => 'WINCH', 29 => 'IO', 30 => 'PWR', 31 => 'SYS'
+    }.freeze
+    NAMES = NUMBERS.invert.freeze
+
+    sig { params(spec: String).returns(T.nilable(String)) }
+    def self.decode(spec)
+      return NUMBERS.fetch(Integer(spec, 10), nil) if spec.match?(/\A\d+\z/)
+
+      name = spec.upcase
+      NAMES.key?(name) ? name : nil
+    end
+
+    sig { params(name: String).returns(Integer) }
+    def self.number(name)
+      NAMES.fetch(name)
+    end
+
+    # strsignal(3)-style descriptions, as dash's jobs listing prints for a
+    # signalled job ("Killed", "Terminated"). Only the common ones are
+    # spelled out; the rest fall back to the signal name.
+    DESCRIPTIONS = {
+      1 => 'Hangup', 2 => 'Interrupt', 3 => 'Quit', 4 => 'Illegal instruction',
+      5 => 'Trace/breakpoint trap', 6 => 'Aborted', 7 => 'Bus error',
+      8 => 'Floating point exception', 9 => 'Killed', 10 => 'User defined signal 1',
+      11 => 'Segmentation fault', 12 => 'User defined signal 2', 13 => 'Broken pipe',
+      14 => 'Alarm clock', 15 => 'Terminated'
+    }.freeze
+
+    sig { params(number: Integer).returns(String) }
+    def self.description(number)
+      DESCRIPTIONS.fetch(number) { NUMBERS.fetch(number, "Signal #{number}") }
+    end
+
+    # strsignal(3) again, for the stop signals as the jobs listing shows a
+    # Stopped entry: plain for ^Z's TSTP, qualified for the others (dash
+    # prints the same strings, probed).
+    STOPPED = {
+      19 => 'Stopped (signal)', 20 => 'Stopped',
+      21 => 'Stopped (tty input)', 22 => 'Stopped (tty output)'
+    }.freeze
+
+    sig { params(number: Integer).returns(String) }
+    def self.stop_description(number)
+      STOPPED.fetch(number, 'Stopped')
+    end
+  end
+end

data/lib/rush/source.rb

@@ -0,0 +1,82 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs non-interactive shell source from `-c`, a script file, or stdin,
+  # command by command. It owns the batch-mode error policy: fatal
+  # syntax/expansion/builtin errors publish status 2, run the EXIT trap, and
+  # stop the remaining input.
+  class Source < ProgramSession
+    extend T::Sig
+
+    sig { params(invocation: Invocation, system: SystemCalls, state: ShellState, startup: T.nilable(Startup)).void }
+    def initialize(invocation, system, state:, startup: nil)
+      @source = T.let(invocation.source, String)
+      super(system, state: state, startup: startup)
+    end
+
+    sig { returns(Integer) }
+    def run
+      super
+    rescue Error => e
+      handle_error(e)
+    end
+
+    private
+
+    sig { params(_continuation: T::Boolean).returns(T.nilable(String)) }
+    def next_line(_continuation)
+      source_line.tap { |line| echo_verbose(line) }
+    end
+
+    # Under `set -v` (verbose) each input line is written to stderr as it is read,
+    # before it runs, so a `set -v`/`set +v` toggles which later lines echo (POSIX).
+    sig { params(line: T.nilable(String)).void }
+    def echo_verbose(line)
+      system.stderr.print(line) if line && executor.state.options.on?(:verbose)
+    end
+
+    sig { returns(T.nilable(String)) }
+    def source_line
+      source_lines.next
+    rescue StopIteration
+      nil
+    end
+
+    sig { returns(Enumerator) }
+    def source_lines
+      @source_lines ||= source.each_line
+    end
+
+    # A `return` not caught by a function or dot script acts like `exit` with
+    # that code in a non-interactive shell (POSIX): re-raise as ExitSignal so it
+    # settles the status and fires the EXIT trap. A stray break/continue no longer
+    # reaches here — with no enclosing loop the builtin is a no-op.
+    sig { params(program: AST::List).void }
+    def execute(program)
+      super
+    rescue ReturnSignal => e
+      raise ExitSignal, e.code
+    end
+
+    sig { params(error: Error).returns(Integer) }
+    def handle_error(error)
+      decision = ErrorPolicy.decision(:batch, error)
+      return executor.trap_runner.run_exit_trap(130) if decision == :interrupt130
+      return abort_with(error) if decision == :abort2
+
+      raise error
+    end
+
+    # A fatal error (syntax/expansion/readonly): report it, publish 2 as $?, then
+    # fire the EXIT trap (which may override the code via `exit`) — like dash.
+    sig { params(error: StandardError).returns(Integer) }
+    def abort_with(error)
+      report(error)
+      executor.trap_runner.run_exit_trap(2)
+    end
+
+    sig { returns(String) }
+    attr_reader :source
+  end
+end

data/lib/rush/source_line_counter.rb

@@ -0,0 +1,41 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Tracks absolute source line numbers while ProgramReader buffers one complete
+  # program. Each Lexer sees only the current buffer, so the counter supplies the
+  # offset that makes word/source-line metadata absolute within the caller's
+  # source stream.
+  class SourceLineCounter
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @line_number = 0
+      @buffer_start = 1
+    end
+
+    sig { params(line: String).void }
+    def start(line)
+      @buffer_start = @line_number + 1
+      advance(line)
+    end
+
+    sig { params(line: String).void }
+    def continue(line)
+      advance(line)
+    end
+
+    sig { returns(Integer) }
+    def offset
+      @buffer_start - 1
+    end
+
+    private
+
+    sig { params(line: String).void }
+    def advance(line)
+      @line_number += line.each_line.count
+    end
+  end
+end

data/lib/rush/source_runner.rb

@@ -0,0 +1,47 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs shell text command by command in the current shell — the engine shared
+  # by `eval` and `.`. Reading and executing incrementally (via ProgramReader)
+  # lets each command shape how the next is parsed: an `alias` or function
+  # defined on one line takes effect on the following lines, and a syntax error
+  # only stops the commands after it (the earlier ones have already run), exactly
+  # as dash reads its input. The result starts at success and is updated by each
+  # non-empty command, so empty input is status 0 while $? stays live for the
+  # commands themselves (POSIX: eval and dot inherit the current $?).
+  class SourceRunner
+    extend T::Sig
+
+    sig { params(executor: Executor, text: String).void }
+    def initialize(executor, text)
+      @executor = executor
+      @lines = text.each_line.to_a
+      @reader = ProgramReader.new(aliases: executor.state.aliases) { @lines.shift }
+      @result = Status.success
+    end
+
+    sig { returns(Status) }
+    def run
+      loop { break if advance == :eof }
+      @result
+    end
+
+    private
+
+    # Read the next complete program and run it, returning it (or :eof) so `run`
+    # knows when the input is exhausted.
+    sig { returns(T.any(AST::List, Symbol)) }
+    def advance
+      program = @reader.next_program
+      execute(T.cast(program, AST::List)) unless program == :eof
+      program
+    end
+
+    sig { params(program: AST::List).void }
+    def execute(program)
+      @executor.run(program)
+      @result = @executor.state.last_status unless program.empty?
+    end
+  end
+end