rush-shell 0.0.2

data/lib/rush/expansion/pipeline.rb

@@ -0,0 +1,124 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Orchestrates the ordered POSIX word expansion. Each segment expands itself
+    # to one or more parts ([text, splittable, break_before, quoted]); unquoted results
+    # undergo IFS field splitting and then pathname expansion. The one multi-field
+    # case is "$@"/$@, which yields one part per positional parameter with a
+    # forced field break between them ($* always joins to a scalar). Field
+    # splitting carries quote provenance into the pathname-expansion boundary.
+    class Pipeline
+      extend T::Sig
+
+      # Tilde expansion strategy per mode (its value is a word's segment list).
+      TILDE_EXPANDERS = { none: NoTilde, leading: TildeExpander, assignment: AssignmentTilde }.freeze
+
+      sig { params(executor: Executor).void }
+      def initialize(executor)
+        @executor = executor
+        @glob_expander = GlobExpander.new(executor)
+      end
+
+      # Argv expansion: expand each word to fields (splitting unquoted on the IFS
+      # value in force after that word's substitutions), then pathname-expand.
+      sig { params(words: T::Array[AST::Word]).returns(T::Array[String]) }
+      def expand(words)
+        expanded = T.let([], T::Array[String])
+        words.each { |word| append_word(word, expanded) }
+        expanded
+      end
+
+      # Assignment RHS / redirection target / operator word: one field, no split.
+      # Tilde expands at the leading position by default; assignment context also
+      # expands after colons, and arithmetic opts out (~ is bitwise not there).
+      sig { params(word: T.any(AST::Word, HereDoc), tilde: Symbol).returns(String) }
+      def expand_value(word, tilde: :leading)
+        collapse(expand_parts(word, tilde: tilde))
+      end
+
+      # Expand without splitting or globbing while retaining each segment's
+      # quote provenance for a surrounding ${...} operator word.
+      sig { params(word: T.any(AST::Word, HereDoc), tilde: Symbol).returns(T::Array[FieldPart]) }
+      def expand_parts(word, tilde: :leading)
+        expanded = T.let([], T::Array[FieldPart])
+        tilde_expand(word.segments, tilde).each { |segment| append_field_parts(segment, expanded) }
+        expanded
+      end
+
+      sig { params(expanded: T::Array[FieldPart]).returns(String) }
+      def collapse(expanded)
+        result = +''
+        separator = field_separator
+        expanded.each { |text, _splittable, brk, _quoted| result << (brk ? separator : '') << text }
+        result
+      end
+
+      # A case/removal pattern keeps quoting as backslash shielding so quoted
+      # metacharacters remain literal when ShellPattern compiles the result.
+      sig { params(pattern: AST::Word, tilde: Symbol).returns(String) }
+      def expand_pattern(pattern, tilde: :leading)
+        result = +''
+        tilde_expand(pattern.segments, tilde).each { |segment| result << expanded_pattern(segment) }
+        result
+      end
+
+      private
+
+      sig { params(segment: AST::WordSegment[T.untyped]).returns(String) }
+      def expanded_pattern(segment)
+        escape_if_quoted(segment, segment.expand(@executor))
+      end
+
+      sig { params(word: AST::Word, expanded: T::Array[String]).void }
+      def append_word(word, expanded)
+        parts = expand_parts(word)
+        FieldSplitter.new(ifs).split(parts).each { |field| @glob_expander.append(field, expanded) }
+      end
+
+      sig { params(segments: T::Array[AST::WordSegment[T.untyped]], mode: Symbol).returns(T::Array[AST::WordSegment[T.untyped]]) }
+      def tilde_expand(segments, mode)
+        TILDE_EXPANDERS.fetch(mode).new(@executor, segments).expand
+      end
+
+      sig { params(segment: AST::WordSegment[T.untyped], expanded: T::Array[FieldPart]).void }
+      def append_field_parts(segment, expanded)
+        return append_splat_parts(segment, expanded) if segment.splat?
+
+        segment.append_field_parts(@executor, expanded)
+      end
+
+      # Glob metacharacters in quoted text are escaped so they match literally;
+      # unquoted text keeps them active.
+      sig { params(segment: AST::WordSegment[T.untyped], text: String).returns(String) }
+      def escape_if_quoted(segment, text)
+        segment.quoted ? escape(text) : text
+      end
+
+      sig { params(text: String).returns(String) }
+      def escape(text)
+        text.gsub(/[\\*?\[\]\-!^]/) { |meta| "\\#{meta}" }
+      end
+
+      sig { params(segment: AST::WordSegment[T.untyped], expanded: T::Array[FieldPart]).void }
+      def append_splat_parts(segment, expanded)
+        quoted = segment.quoted
+        @executor.state.positional.to_a.each_with_index do |element, index|
+          expanded << [element, !quoted, index.positive?, quoted]
+        end
+      end
+
+      sig { returns(String) }
+      def field_separator
+        value = ifs
+        value ? (value.each_char.first || '') : ' '
+      end
+
+      sig { returns(T.nilable(String)) }
+      def ifs
+        @executor.state.variables.get('IFS')
+      end
+    end
+  end
+end

data/lib/rush/expansion/read_char.rb

@@ -0,0 +1,13 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # One annotated character of a line consumed by the `read` builtin, as
+    # [char, escaped]: the character itself and whether a backslash escaped it
+    # (an escaped character keeps its literal value and never acts as an IFS
+    # delimiter). A zero-width joint (['', true]) marks where a backslash-newline
+    # continuation joined two physical lines.
+    ReadChar = T.type_alias { [String, T::Boolean] }
+  end
+end

data/lib/rush/expansion/read_field_scanner.rb

@@ -0,0 +1,159 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # The count-limited, escape-aware field scanner behind ReadSplitter — a
+    # transcription of dash's ifsbreakup(maxargs): fields split off until the
+    # variable budget is spent; the delimiter that spends it starts the
+    # remainder, which accumulates verbatim with a cut mark (dash's `r`)
+    # tracking removable trailing IFS whitespace. Escaped characters are plain
+    # content: never delimiters, they end a whitespace run (dash's region
+    # boundary) and never touch the cut mark — reproducing dash's remainder
+    # edge cases exactly (see the unit spec).
+    class ReadFieldScanner
+      extend T::Sig
+
+      # The collected fields plus the field being built, carrying dash's `r`
+      # mark: the position from which the final field's trailing text is cut.
+      class Fields
+        extend T::Sig
+
+        sig { void }
+        def initialize
+          @done = T.let([], T::Array[String])
+          @text = T.let(+'', String)
+          @cut = T.let(nil, T.nilable(Integer))
+        end
+
+        sig { params(char: String).void }
+        def append(char)
+          @text << char
+        end
+
+        sig { returns(T::Boolean) }
+        def empty?
+          @text.empty?
+        end
+
+        sig { void }
+        def close
+          @done << @text
+          @text = +''
+        end
+
+        # Records the cut position — the start of removable trailing text
+        # (dash's `r`) — keeping the earliest one until uncut clears it.
+        sig { void }
+        def cut
+          @cut ||= @text.length
+        end
+
+        sig { void }
+        def uncut
+          @cut = nil
+        end
+
+        sig { returns(T::Array[String]) }
+        def result
+          cut = @cut
+          tail = cut ? T.must(@text[0, cut]) : @text
+          tail.empty? ? @done : @done + [tail]
+        end
+      end
+
+      sig { params(ifs: Ifs, count: Integer).void }
+      def initialize(ifs, count)
+        @ifs = ifs
+        @left = count
+        @fields = T.let(Fields.new, Fields)
+        @spaced = T.let(false, T::Boolean) # dash's ifsspc: in a whitespace-delimiter run
+      end
+
+      sig { params(chars: T::Array[ReadChar]).returns(T::Array[String]) }
+      def run(chars)
+        chars.each { |char, escaped| escaped ? shielded(char) : consume(char) }
+        @fields.result
+      end
+
+      private
+
+      sig { params(char: String).void }
+      def consume(char)
+        return tail(char) if @left.zero?
+        return absorb(char) if @spaced && ifs?(char)
+
+        head(char)
+      end
+
+      # A backslash-escaped character: plain content, never a delimiter. It
+      # ends any whitespace run (in dash a region boundary resets ifsspc) and
+      # leaves the cut mark alone (dash never scans the gap it sits in). The
+      # zero-width joint a line continuation leaves (['', true]) rides the same
+      # path: it only breaks the run.
+      sig { params(char: String).void }
+      def shielded(char)
+        @spaced = false
+        @fields.append(char)
+      end
+
+      # Inside a whitespace-delimiter run an IFS char joins the delimiter:
+      # more whitespace keeps the run open, one non-whitespace IFS character
+      # closes it.
+      sig { params(char: String).void }
+      def absorb(char)
+        @spaced = @ifs.whitespace?(char)
+      end
+
+      sig { params(char: String).void }
+      def head(char)
+        return delimiter(char) if ifs?(char)
+
+        @spaced = false
+        @fields.append(char)
+      end
+
+      # An unescaped IFS delimiter: whitespace before any field content is
+      # skipped; a delimiter splits a field while variables remain, and the
+      # one that spends the last variable opens the remainder.
+      sig { params(char: String).void }
+      def delimiter(char)
+        @spaced = @ifs.whitespace?(char)
+        return skip_leading if @spaced && @fields.empty?
+
+        (@left -= 1).zero? ? removable(char) : @fields.close
+      end
+
+      sig { void }
+      def skip_leading
+        @spaced = false
+      end
+
+      # Removable trailing text: the delimiter that spends the last variable
+      # (the remainder accumulates verbatim from it) and, later, IFS whitespace
+      # extending the trailing run — cut off unless real content follows.
+      sig { params(char: String).void }
+      def removable(char)
+        @fields.cut
+        @fields.append(char)
+      end
+
+      # Remainder mode (dash's exhausted maxargs): IFS whitespace extends the
+      # removable trailing run; anything else is content and clears the cut —
+      # except a single non-whitespace IFS char directly closing a run.
+      sig { params(char: String).void }
+      def tail(char)
+        return removable(char) if @ifs.whitespace?(char)
+
+        @fields.uncut unless @ifs.other?(char) && @spaced
+        @spaced = false
+        @fields.append(char)
+      end
+
+      sig { params(char: String).returns(T::Boolean) }
+      def ifs?(char)
+        @ifs.whitespace?(char) || @ifs.other?(char)
+      end
+    end
+  end
+end

data/lib/rush/expansion/read_splitter.rb

@@ -0,0 +1,40 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Field splitting for the `read` builtin over an escape-annotated line:
+    # ReadFieldScanner splits on unescaped IFS delimiters into at most `count`
+    # fields (the last keeps the remainder verbatim, trailing IFS whitespace
+    # removed), and the result is padded with empty strings up to `count`.
+    # A null IFS does not split — the whole line is one field, untrimmed.
+    class ReadSplitter
+      extend T::Sig
+
+      sig { params(ifs: T.nilable(String), count: Integer).void }
+      def initialize(ifs, count)
+        @ifs = Ifs.new(ifs)
+        @count = count
+      end
+
+      sig { params(chars: T::Array[ReadChar]).returns(T::Array[String]) }
+      def split(chars)
+        return pad([text(chars)]) if @ifs.null?
+
+        pad(ReadFieldScanner.new(@ifs, @count).run(chars))
+      end
+
+      private
+
+      sig { params(chars: T::Array[ReadChar]).returns(String) }
+      def text(chars)
+        chars.map(&:first).join
+      end
+
+      sig { params(fields: T::Array[String]).returns(T::Array[String]) }
+      def pad(fields)
+        (fields.each + [''].cycle).take(@count)
+      end
+    end
+  end
+end

data/lib/rush/expansion/resolver.rb

@@ -0,0 +1,23 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Resolves a parameter name through ShellState's parameter namespace. The
+    # shell state owns variables, special parameters and positionals, including
+    # the original shell pid exposed through $$.
+    class Resolver
+      extend T::Sig
+
+      sig { params(executor: Executor).void }
+      def initialize(executor)
+        @executor = executor
+      end
+
+      sig { params(name: String).returns(T.nilable(String)) }
+      def resolve(name)
+        @executor.state.parameters.resolve(name)
+      end
+    end
+  end
+end

data/lib/rush/expansion/tilde_expander.rb

@@ -0,0 +1,102 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Tilde expansion (step 1): a leading unquoted `~` or `~name` in a word's
+    # first literal segment becomes $HOME or the named user's home directory. It
+    # is left untouched when there is no such user, or when HOME is unset for a
+    # bare `~`. This base handles the leading form; AssignmentTilde extends it to
+    # also expand after each unquoted colon, and NoTilde disables it entirely.
+    class TildeExpander
+      extend T::Sig
+
+      sig { params(executor: Executor, segments: T::Array[AST::WordSegment[T.untyped]]).void }
+      def initialize(executor, segments)
+        @executor = executor
+        @segments = segments
+      end
+
+      sig { returns(T::Array[AST::WordSegment[T.untyped]]) }
+      def expand
+        head = @segments.first
+        return @segments unless head
+
+        text = head.literal_value
+        text ? replace_head(head, text) : @segments
+      end
+
+      private
+
+      sig { params(head: AST::WordSegment[T.untyped], text: String).returns(T::Array[AST::WordSegment[T.untyped]]) }
+      def replace_head(head, text)
+        rewritten = rewrite(text)
+        return @segments if rewritten == text
+
+        @segments.dup.tap { |segments| segments[0] = head.with_value(rewritten) }
+      end
+
+      sig { params(text: String).returns(String) }
+      def rewrite(text)
+        prefix(text)
+      end
+
+      sig { params(text: String).returns(String) }
+      def prefix(text)
+        return text unless text.start_with?('~')
+
+        name, rest = split(text.delete_prefix('~'))
+        home = resolve(name)
+        home ? home + rest : text
+      end
+
+      sig { params(body: String).returns([String, String]) }
+      def split(body)
+        name, slash, rest = body.partition('/')
+        slash.empty? ? [body, ''] : [name, slash + rest]
+      end
+
+      sig { params(name: String).returns(T.nilable(String)) }
+      def resolve(name)
+        return @executor.state.variables.get('HOME') if name.empty?
+
+        @executor.system.home_dir(name)
+      end
+    end
+
+    # Assignment context (PATH=~/bin:~root/x): the leading tilde plus one after
+    # each unquoted colon, so every colon-separated piece gets the ~ treatment.
+    class AssignmentTilde < TildeExpander
+      extend T::Sig
+
+      private
+
+      sig { params(text: String).returns(String) }
+      def rewrite(text)
+        return text unless expandable?(text)
+
+        text.split(':', -1).map { |piece| prefix(piece) }.join(':')
+      end
+
+      sig { params(text: String).returns(T::Boolean) }
+      def expandable?(text)
+        text.start_with?('~') || text.include?(':~')
+      end
+    end
+
+    # Tilde expansion disabled (e.g. arithmetic operands): segments pass through.
+    class NoTilde
+      extend T::Sig
+
+      sig { params(_executor: Executor, segments: T::Array[AST::WordSegment[T.untyped]]).void }
+      def initialize(_executor, segments)
+        @segments = segments
+      end
+
+      sig { returns(T::Array[AST::WordSegment[T.untyped]]) }
+      def expand
+        @segments
+      end
+    end
+  end
+end

data/lib/rush/external.rb

@@ -0,0 +1,75 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs an external program through the system port with the command's env and
+  # IoTable, translating the result: the OS exit/signal status, or POSIX 127
+  # (not found) / 126 (not executable).
+  class External
+    extend T::Sig
+
+    sig { params(executor: Executor, argv: T::Array[String], io: IoTable, env: T::Hash[String, String]).void }
+    def initialize(executor, argv, io, env)
+      @executor = executor
+      @argv = argv
+      @io = io
+      @env = env
+    end
+
+    # Under job control the spawned command has no child-side hook, so the
+    # foreground wrapper's parent-side give is what hands it the terminal —
+    # right after the spawn, before the wait. `text` is the job line a
+    # parked entry keeps, rendered pre-expansion by the caller (which holds
+    # the AST this class never sees). A signal death reports on the
+    # command's own stderr (dash applies simple-command redirects in the
+    # parent, so 2>/dev/null suppresses its printsignal there too — probed).
+    sig { params(text: T.nilable(String)).returns(Status) }
+    def call(text = nil)
+      call_file(T.must(@argv.first), text)
+    end
+
+    # Run a pre-resolved file in place of the $PATH search on argv[0] (plain
+    # #call passes the bare name, `command -p` its default-PATH resolution);
+    # argv[0] itself still names the child, like dash.
+    sig { params(path: String, text: T.nilable(String)).returns(Status) }
+    def call_file(path, text = nil)
+      pid = system.spawn(path, @env, @argv, spawn_options)
+      status = @executor.job_control.foreground([pid], text: text) { @executor.jobs.await(pid) }
+      SignalReport.report(status, @io.get(2))
+    rescue Errno::ENOENT, Errno::EACCES => e
+      error_status(e)
+    end
+
+    private
+
+    sig { returns(SystemCalls) }
+    def system
+      @executor.system
+    end
+
+    # close_others closes inherited fds >= 3 (e.g. pipeline pipe ends) in the
+    # child. Under job control the command is a job of its own: pgroup: true
+    # has the kernel start it as its own process-group leader — the spawn-path
+    # equivalent of the fork paths' double setpgid, with no race at all.
+    sig { returns(T::Hash[T.any(Integer, Symbol), T.untyped]) }
+    def spawn_options
+      base = @io.to_spawn_options.merge(close_others: true)
+      @executor.job_control.monitored? ? base.merge(pgroup: true) : base
+    end
+
+    sig { params(error: SystemCallError).returns(Status) }
+    def error_status(error)
+      code = error.is_a?(Errno::EACCES) ? 126 : 127
+      reason = code == 126 ? 'Permission denied' : 'not found'
+      report_error(reason)
+      Status.new(code)
+    end
+
+    sig { params(reason: String).void }
+    def report_error(reason)
+      @io.get(2).puts("rush: #{@argv.first}: #{reason}")
+    rescue Errno::EBADF
+      nil
+    end
+  end
+end

data/lib/rush/fd_entry.rb

@@ -0,0 +1,60 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # One binding in the shell's logical fd table. It records the stream currently
+  # bound to a descriptor plus ownership: redirections that open files/heredocs
+  # are owned and closed after the command, while stdio, pipes and future
+  # inherited descriptors are borrowed. A closed entry models `n>&-` / `n<&-`.
+  class FdEntry
+    extend T::Sig
+
+    sig { params(stream: T.untyped).returns(FdEntry) }
+    def self.borrowed(stream)
+      new(stream, :borrowed)
+    end
+
+    sig { params(stream: T.untyped).returns(FdEntry) }
+    def self.owned(stream)
+      new(stream, :owned)
+    end
+
+    sig { returns(FdEntry) }
+    def self.closed
+      new(nil, :closed)
+    end
+
+    sig { params(stream: T.untyped, state: Symbol).void }
+    def initialize(stream, state)
+      @stream = stream
+      @state = state
+    end
+
+    sig { returns(T::Boolean) }
+    def owned?
+      @state == :owned
+    end
+
+    sig { returns(T::Boolean) }
+    def closed?
+      @state == :closed
+    end
+
+    sig { returns(T.untyped) }
+    def stream
+      raise Errno::EBADF if closed?
+
+      T.must(@stream)
+    end
+
+    sig { returns(T.untyped) }
+    def to_spawn_option
+      closed? ? :close : stream
+    end
+
+    sig { params(system: SystemCalls).void }
+    def close_redirect(system)
+      system.close_redirect(stream) if owned? && !closed?
+    end
+  end
+end

data/lib/rush/for_runner.rb

@@ -0,0 +1,50 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs a for loop: assign the variable to each value in turn and run the body,
+  # catching break/continue at the loop boundary (see LoopControlHandling). The
+  # loop's status is the last body status (0 if the value list is empty).
+  class ForRunner
+    extend T::Sig
+
+    include LoopControlHandling
+
+    sig { params(executor: Executor, name: String, values: T::Array[String], body: AST::Node).void }
+    def initialize(executor, name, values, body)
+      @executor = executor
+      @name = name
+      @values = values
+      @body = body
+    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 (see LoopRunner#run_loop): Sorbet forbids
+      # a variable changing type across a block (srb.help/7001) and the sig'd
+      # Status.success / unsig'd #iterate would. Steep ignores T.let (sorbet_dsl.rbs).
+      status = T.let(Status.success, Status)
+      @values.each { |value| status = iterate(value) }
+      status
+    rescue BreakSignal => e
+      unwind(e)
+    end
+
+    sig { params(value: String).returns(Status) }
+    def iterate(value)
+      @executor.state.variables.assign(@name, value)
+      @executor.run(@body)
+    rescue ContinueSignal => e
+      unwind(e)
+    end
+  end
+end

data/lib/rush/function_frame.rb

@@ -0,0 +1,30 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Brackets a shell-function invocation: open a local-variable scope, reset loop
+  # nesting so break/continue cannot escape to the caller, bind positional
+  # parameters to the function arguments, then restore all three on return.
+  class FunctionFrame
+    extend T::Sig
+
+    sig { params(variables: ShellVariables, loops: LoopNesting, positional: Positional).void }
+    def initialize(variables:, loops:, positional:)
+      @variables = variables
+      @loops = loops
+      @positional = positional
+    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 call(args, &blk)
+      @variables.begin_scope
+      @loops.without { @positional.with(args, &blk) }
+    ensure
+      @variables.end_scope
+    end
+  end
+end