rush-shell 0.0.2

data/lib/rush/lexer/word_scanner.rb

@@ -0,0 +1,134 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  class Lexer
+    # Scans one word from the shared StringScanner into an AST::Word of typed
+    # segments: literal runs (quote-removed, with a `quoted` flag) and :param
+    # segments for $name / ${...}. Handles the three quoting forms; command
+    # substitution and arithmetic arrive in later slices.
+    class WordScanner
+      extend T::Sig
+      include ScannerPredicates
+
+      TERMINATOR = /[ \t\n;&|<>()]/
+      DISPATCH = {
+        "'" => :single_quote, '"' => :double_quote, '\\' => :escape,
+        '$' => :dollar, '`' => :backtick
+      }.freeze
+
+      # Scan the next shell word from a live lexer scanner, stopping at the first
+      # unquoted terminator (blank / operator). `interactive` mirrors the lexer:
+      # an accumulating parse may ask for more input, the final one may not.
+      sig { params(scanner: StringScanner, interactive: T::Boolean).returns(AST::Word) }
+      def self.next_word(scanner, interactive:)
+        new(scanner, terminator: TERMINATOR, interactive: interactive).scan
+      end
+
+      # Scan a complete, already-delimited string (a ${...} operator word or
+      # arithmetic source) as one word: no terminators apply (blanks/operators
+      # are literal), only quote / $ / ` stay special.
+      sig { params(text: String).returns(AST::Word) }
+      def self.entire(text)
+        new(StringScanner.new(text), terminator: nil, interactive: false).scan
+      end
+
+      # terminator: the character class that ends a word, or nil in whole mode.
+      sig { params(scanner: StringScanner, terminator: T.nilable(Regexp), interactive: T::Boolean).void }
+      def initialize(scanner, terminator:, interactive:)
+        @scanner = scanner
+        @terminator = terminator
+        @interactive = interactive
+        @buffer = SegmentBuffer.new
+      end
+
+      sig { returns(AST::Word) }
+      def scan
+        loop do
+          char = @scanner.getch or return @buffer.word
+          return rewind_then_build if terminates?(char)
+
+          step(char)
+        end
+      end
+
+      private
+
+      sig { params(char: String).returns(T::Boolean) }
+      def terminates?(char)
+        terminator = @terminator
+        terminator ? char.match?(terminator) : false
+      end
+
+      sig { returns(AST::Word) }
+      def rewind_then_build
+        @scanner.unscan
+        @buffer.word
+      end
+
+      sig { params(char: String).void }
+      def step(char)
+        handler = DISPATCH.fetch(char, nil)
+        handler ? send(handler) : (@buffer << char)
+      end
+
+      sig { void }
+      def single_quote
+        content = @scanner.scan(/[^']*/)
+        raise IncompleteInput, 'unterminated single quote' unless @scanner.scan("'")
+
+        push(content, quoted: true)
+      end
+
+      sig { void }
+      def double_quote
+        DoubleQuoteScanner.new(@scanner, @buffer, -> { continuation }).scan
+      end
+
+      # Line continuation (POSIX 2.2.1): the backslash-newline pair vanishes.
+      # When the newline ends an accumulating (interactive) buffer, the logical
+      # line continues on input the lexer does not have yet, so ask the reader
+      # for the next line. The final parse at end of input — and `entire` mode,
+      # whose text is already complete — just drops the pair, like dash.
+      sig { void }
+      def continuation
+        @scanner.skip(/\n/)
+        raise IncompleteInput, 'line continuation' if @interactive && @terminator && @scanner.eos?
+      end
+
+      # A lone `$` that begins no valid reference stays a literal dollar: merged
+      # into the current literal run when bare, a quoted literal segment in "...".
+      sig { void }
+      def dollar
+        @scanner.unscan
+        segment = DollarScanner.new(@scanner).read(quoted: false)
+        segment ? @buffer.push(segment) : (@buffer << '$')
+      end
+
+      sig { void }
+      def backtick
+        @scanner.unscan
+        @buffer.push(DollarScanner.new(@scanner).read_backtick(quoted: false))
+      end
+
+      sig { void }
+      def escape
+        char = @scanner.getch or return trailing_backslash
+        char == "\n" ? continuation : push(char, quoted: true)
+      end
+
+      # A backslash that ends the input stays literal, like dash.
+      sig { void }
+      def trailing_backslash
+        @buffer << '\\'
+      end
+
+      sig { params(value: T.untyped, quoted: T::Boolean).void }
+      def push(value, quoted:)
+        @buffer.push(AST::LiteralSegment.new(value, quoted))
+      end
+    end
+  end
+end

data/lib/rush/lexer.rb

@@ -0,0 +1,174 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+require_relative 'lexer/operator_table'
+require_relative 'lexer/lex_state'
+require_relative 'lexer/source_lines'
+require_relative 'lexer/scanner_predicates'
+require_relative 'lexer/token_predicates'
+require_relative 'lexer/quote_skips'
+require_relative 'lexer/case_frame'
+require_relative 'lexer/case_tracker'
+require_relative 'lexer/paren_regions'
+require_relative 'lexer/paren_reader'
+require_relative 'lexer/substitution_reader'
+require_relative 'lexer/braced_reader'
+require_relative 'lexer/param_scanner'
+require_relative 'lexer/quoted_word'
+require_relative 'lexer/dollar_scanner'
+require_relative 'lexer/double_quote_scanner'
+require_relative 'lexer/word_scanner'
+require_relative 'lexer/heredoc_body'
+require_relative 'lexer/heredoc_reader'
+require_relative 'lexer/token_classifier'
+require_relative 'lexer/alias_expander'
+
+module Rush
+  # StringScanner pump that yields [symbol, value] pairs for racc. It skips
+  # blanks and comments, then emits NEWLINE, an IO_NUMBER, an operator, or a
+  # WORD/ASSIGNMENT_WORD (classified against LexState, which advances after each
+  # token to track command position — the seed of POSIX Grammar Rules 1-9).
+  class Lexer
+    extend T::Sig
+    include TokenPredicates
+
+    # Between tokens, blanks, comments and backslash-newline continuations
+    # (POSIX 2.2.1) are all insignificant. A continuation at the buffer's very
+    # end is left for the word scanner, which asks for the next line instead
+    # of ending the token stream.
+    INSIGNIFICANT = /(?:[ \t]+|#[^\n]*|\\\n(?=.))+/m
+    # "Immediately before < or >" sees through spliced continuations, like the
+    # operator matcher: dash-verified, `2\<newline>>f` redirects fd 2.
+    IO_NUMBER = /\d+(?=(?:\\\n)*[<>])/
+    HEREDOC_OPS = { DLESS: :plain, DLESSDASH: :strip }.freeze
+
+    sig { params(source: String, interactive: T::Boolean, aliases: T.nilable(AliasTable), line_offset: Integer).void }
+    def initialize(source, interactive: false, aliases: nil, line_offset: 0)
+      @scanner = StringScanner.new(source)
+      @aliases = AliasExpander.new(aliases)
+      @interactive = interactive
+      @state = LexState.new
+      @lines = SourceLines.new(@scanner, line_offset)
+      @awaiting = nil
+      @heredocs = []
+    end
+
+    sig { returns(Integer) }
+    def location
+      @scanner.charpos
+    end
+
+    sig { returns([T.untyped, T.untyped]) }
+    def next_token
+      drain
+      return [false, false] if @scanner.eos?
+
+      token = scan_token
+      token ? emit(token) : next_token
+    end
+
+    private
+
+    sig { params(token: [T.untyped, T.untyped]).returns([T.untyped, T.untyped]) }
+    def emit(token)
+      @state.advance(token.first)
+      @aliases.spend
+      token
+    end
+
+    # Skip blanks and comments; when the current frame is an exhausted alias
+    # replacement, restore the input beneath it and keep skipping.
+    sig { void }
+    def drain
+      skip_insignificant
+      return unless @scanner.eos? && @aliases.nested?
+
+      @scanner = @aliases.pop
+      drain
+    end
+
+    sig { void }
+    def skip_insignificant
+      @scanner.skip(INSIGNIFICANT)
+    end
+
+    sig { returns(T.nilable([T.untyped, T.untyped])) }
+    def scan_token
+      return heredoc_newline if @scanner.scan("\n")
+
+      io_number || operator || word
+    end
+
+    sig { returns(T.nilable([T.untyped, T.untyped])) }
+    def io_number
+      digits = @scanner.scan(IO_NUMBER)
+      digits ? [:IO_NUMBER, Integer(digits, 10)] : nil
+    end
+
+    sig { returns(T.nilable([T.untyped, T.untyped])) }
+    def operator
+      matched = @scanner.scan(OperatorTable::PATTERN)
+      matched ? operator_token(matched) : nil
+    end
+
+    # The match may carry line continuations between its characters (see
+    # OperatorTable::PATTERN); splicing them out recovers the operator.
+    sig { params(matched: String).returns([T.untyped, T.untyped]) }
+    def operator_token(matched)
+      operator = matched.gsub(OperatorTable::CONTINUATION, '')
+      symbol = OperatorTable::OPERATORS.fetch(operator)
+      @awaiting = HEREDOC_OPS.fetch(symbol, nil)
+      [symbol, operator]
+    end
+
+    # A word awaited as a here-document delimiter is taken raw — never
+    # classified, aliased or reserved. Otherwise classify it, then (only a
+    # plain WORD) splice its alias replacement in its place; a splice returns
+    # nil so next_token re-reads from the new frame.
+    sig { returns(T.nilable([T.untyped, T.untyped])) }
+    def word
+      scanned = @lines.word { WordScanner.next_word(@scanner, interactive: @interactive) }
+      return delimiter(scanned) if @awaiting
+
+      token = TokenClassifier.new(scanned, @state).call
+      replacement = alias_for(token, scanned)
+      replacement ? splice(replacement) : token
+    end
+
+    sig { params(token: [T.untyped, T.untyped], word: AST::Word).returns(T.nilable(AliasExpander::Replacement)) }
+    def alias_for(token, word)
+      return if !word_token?(token) || !@state.command_mode?
+
+      @aliases.expand(word, @state.expects_command?)
+    end
+
+    sig { params(replacement: AliasExpander::Replacement).returns(NilClass) }
+    def splice(replacement)
+      @aliases.push(replacement, @scanner)
+      @scanner = StringScanner.new(replacement.value)
+      nil
+    end
+
+    sig { params(word: AST::Word).returns([T.untyped, T.untyped]) }
+    def delimiter(word)
+      holder = HereDoc.new(delimiter: word.segments.map(&:value).join,
+                           quoted: word.segments.any?(&:quoted), strip: @awaiting == :strip,
+                           source_line: word.source_line)
+      @awaiting = nil
+      @heredocs << holder
+      [:WORD, holder]
+    end
+
+    # On the newline that ends the command line, drain the pending here-docs:
+    # read each body from the lines that follow, in the order the `<<`s appeared.
+    sig { returns([T.untyped, T.untyped]) }
+    def heredoc_newline
+      start = @scanner.pos
+      HeredocReader.new(@scanner, interactive: @interactive).fill(@heredocs)
+      @heredocs = []
+      @lines.heredoc_newline(start)
+      [:NEWLINE, "\n"]
+    end
+  end
+end

data/lib/rush/loop_control_handling.rb

@@ -0,0 +1,29 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Shared break/continue handling for the loop runners. A multi-level signal is
+  # re-raised with one fewer level so the next enclosing loop handles it; a
+  # single-level signal stops here and yields the last command status. Hosts must
+  # expose @executor.
+  module LoopControlHandling
+    extend T::Sig
+
+    private
+
+    sig { params(signal: LoopControl).returns(Status) }
+    def unwind(signal)
+      relayed = relay(signal)
+      # Kernel.raise (not bare raise): in this mixin Sorbet can't resolve a bare
+      # raise on the module's self.
+      Kernel.raise relayed if relayed
+
+      @executor.state.last_status
+    end
+
+    sig { params(signal: LoopControl).returns(T.nilable(LoopControl)) }
+    def relay(signal)
+      signal.class.new(signal.count - 1) if signal.count > 1
+    end
+  end
+end

data/lib/rush/loop_nesting.rb

@@ -0,0 +1,50 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Lexical loop nesting for break/continue: the count of for/while/until loops
+  # enclosing the current command in the same execution environment. A function
+  # call or subshell starts fresh (#without), so a break inside a function cannot
+  # reach the caller's loop, while dot/eval/group bodies run inline and keep the
+  # count. break/continue read #depth to clamp their level and #any? to no-op
+  # when there is no enclosing loop.
+  class LoopNesting
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :depth
+
+    sig { void }
+    def initialize
+      @depth = 0
+    end
+
+    sig { void }
+    def enter
+      @depth += 1
+    end
+
+    sig { void }
+    def leave
+      @depth -= 1
+    end
+
+    sig { returns(T::Boolean) }
+    def any?
+      @depth.positive?
+    end
+
+    sig do
+      type_parameters(:U)
+        .params(blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def without(&blk)
+      saved = T.let(@depth, Integer)
+      @depth = 0
+      yield
+    ensure
+      @depth = T.must(saved)
+    end
+  end
+end

data/lib/rush/loop_runner.rb

@@ -0,0 +1,55 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs a while/until loop, catching break/continue at the loop boundary (see
+  # LoopControlHandling). The loop's status is the last body status (0 if the
+  # body never runs).
+  class LoopRunner
+    extend T::Sig
+
+    include LoopControlHandling
+
+    sig { params(executor: Executor, condition: AST::Node, body: AST::Node, sense: Symbol).void }
+    def initialize(executor, condition, body, sense)
+      @executor = executor
+      @condition = condition
+      @body = body
+      @sense = sense
+    end
+
+    # Bracket the loop so break/continue see the right nesting depth; leave runs
+    # even when break unwinds.
+    sig { returns(Status) }
+    def call
+      @executor.state.with_loop { run_loop }
+    end
+
+    private
+
+    sig { returns(Status) }
+    def run_loop
+      # T.let pins the loop variable's type: Status.success is now sig'd (Status),
+      # but #iterate is unsig'd (untyped), and Sorbet forbids a variable changing
+      # type across a loop (srb.help/7001). Steep ignores T.let (see sorbet_dsl.rbs).
+      status = T.let(Status.success, Status)
+      status = iterate while proceed?
+      status
+    rescue BreakSignal => e
+      unwind(e)
+    end
+
+    sig { returns(T::Boolean) }
+    def proceed?
+      met = @executor.succeeds?(@condition)
+      @sense == :while ? met : !met
+    end
+
+    sig { returns(Status) }
+    def iterate
+      @executor.run(@body)
+    rescue ContinueSignal => e
+      unwind(e)
+    end
+  end
+end

data/lib/rush/option_cluster.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # A `-abc` / `+abc` cluster of single-letter options, the shape POSIX shares
+  # between the set builtin and the sh invocation line (XCU set / sh): the
+  # leading sign and the letters after it. parse answers nil for anything
+  # else — `--`, a lone dash or plus, or a plain operand.
+  class OptionCluster
+    extend T::Sig
+
+    sig { returns(String) }
+    attr_reader :sign
+
+    sig { returns(T::Array[String]) }
+    attr_reader :letters
+
+    sig { params(arg: T.nilable(String)).returns(T.nilable(OptionCluster)) }
+    def self.parse(arg)
+      return unless arg.is_a?(String) && arg.length > 1 && arg != '--' && arg.start_with?('-', '+')
+
+      new(arg)
+    end
+
+    sig { params(flag: String).void }
+    def initialize(flag)
+      sign, *letters = flag.chars
+      @sign = T.must(sign)
+      @letters = T.let(letters, T::Array[String])
+    end
+
+    # Yield each option letter with the cluster's sign, the shape both
+    # consumers toggle by.
+    sig { params(blk: T.proc.params(letter: String, sign: String).void).void }
+    def each_letter(&blk)
+      letters.each { |letter| yield(letter, sign) }
+    end
+  end
+end

data/lib/rush/options.rb

@@ -0,0 +1,76 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The shell options toggled by `set -[+]o name` / `set -[+]x` and friends
+  # (:errexit, :nounset, :noexec, :xtrace, :noglob, :verbose, :pipefail), plus the
+  # invocation-only :interactive (-i) and :stdin (-s) flags: the set of those
+  # currently on, with #set to flip one, #on? to query it, #letters to
+  # render $-, and the bare `set -o`/`set +o` listings. The letter/name
+  # tables live here so the set builtin and Invocation share one vocabulary.
+  class Options
+    extend T::Sig
+
+    LETTERS = { 'a' => :allexport, 'C' => :noclobber, 'e' => :errexit, 'u' => :nounset,
+                'x' => :xtrace, 'f' => :noglob, 'v' => :verbose, 'm' => :monitor,
+                'n' => :noexec }.freeze
+    # Every long name in dash's listing order — the bare `set -o`/`set +o`
+    # output shows the invocation-only flags too, like dash does.
+    NAMES = { 'errexit' => :errexit, 'noglob' => :noglob, 'interactive' => :interactive,
+              'monitor' => :monitor, 'noexec' => :noexec, 'stdin' => :stdin, 'xtrace' => :xtrace,
+              'verbose' => :verbose, 'noclobber' => :noclobber, 'allexport' => :allexport,
+              'nounset' => :nounset, 'pipefail' => :pipefail }.freeze
+    # The names `set -o name` accepts: everything listable minus the flags
+    # only invocation can set.
+    LONG = NAMES.except('interactive', 'stdin').freeze
+    # $- renders enabled flags in dash's order (its option list, reversed), so
+    # differential corpus lines printing $- compare equal against the oracle.
+    DASH_ORDER = T.let([[:nounset, 'u'], [:allexport, 'a'], [:noclobber, 'C'], [:verbose, 'v'],
+                        [:xtrace, 'x'], [:stdin, 's'], [:noexec, 'n'], [:monitor, 'm'], [:interactive, 'i'],
+                        [:noglob, 'f'], [:errexit, 'e']].freeze, T::Array[[Symbol, String]])
+
+    sig { void }
+    def initialize
+      @enabled = Set.new
+    end
+
+    sig { params(name: Symbol, enabled: T::Boolean).void }
+    def set(name, enabled)
+      enabled ? @enabled.add(name) : @enabled.delete(name)
+    end
+
+    sig { params(name: Symbol).returns(T::Boolean) }
+    def on?(name)
+      @enabled.include?(name)
+    end
+
+    # The current option flags as the $- special parameter renders them.
+    sig { returns(String) }
+    def letters
+      DASH_ORDER.filter_map { |option, letter| letter if on?(option) }.join
+    end
+
+    # The bare `set -o` table rows in dash's format: the name padded to 16
+    # columns, then on/off.
+    sig { returns(T::Array[String]) }
+    def settings_rows
+      render_settings('%<name>-16son', '%<name>-16soff')
+    end
+
+    # The bare `set +o` output: `set -o name` / `set +o name` lines that
+    # reproduce the current settings when re-input (POSIX XCU set).
+    sig { returns(T::Array[String]) }
+    def reinput_lines
+      render_settings('set -o %<name>s', 'set +o %<name>s')
+    end
+
+    private
+
+    # One rendered line per long option name: the on form when the option is
+    # enabled, the off form otherwise.
+    sig { params(on_form: String, off_form: String).returns(T::Array[String]) }
+    def render_settings(on_form, off_form)
+      NAMES.map { |name, option| format(on?(option) ? on_form : off_form, name: name) }
+    end
+  end
+end

data/lib/rush/param_text.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # A runtime string subjected to parameter expansion ONLY — the treatment
+  # POSIX gives PS1/PS2 prompts and the ENV pathname: $name and ${...} become
+  # ParamSegments via the shared ParamScanner; any other character — including
+  # command substitution, backticks and backslashes — is literal text. #word
+  # yields the segments for Expansion::Pipeline#expand_value.
+  class ParamText
+    extend T::Sig
+
+    sig { params(text: String).void }
+    def initialize(text)
+      @scanner = StringScanner.new(text)
+      @buffer = SegmentBuffer.new
+    end
+
+    sig { returns(AST::Word) }
+    def word
+      step until @scanner.eos?
+      @buffer.word
+    end
+
+    private
+
+    sig { void }
+    def step
+      char = T.must(@scanner.getch)
+      char == '$' ? dollar : @buffer << char
+    end
+
+    sig { void }
+    def dollar
+      ref = Lexer::ParamScanner.new(@scanner, quoted: false).read
+      ref ? @buffer.push(AST::ParamSegment.new(ref, false)) : @buffer << '$'
+    end
+  end
+end