rush-shell 0.0.2

data/lib/rush/parser_support.rb

@@ -0,0 +1,112 @@
+# typed: false
+# frozen_string_literal: true
+
+module Rush
+  # The body of the racc-generated Rush::Parser (its `---- inner` block only
+  # `include`s this), kept in a normal linted/covered file. Rule actions call
+  # these factories; none contain node logic.
+  module ParserSupport
+    def initialize(lexer)
+      @lexer = lexer
+    end
+
+    def parse
+      do_parse
+    end
+
+    def next_token
+      @lexer.next_token
+    end
+
+    def on_error(token_id, value, _stack)
+      raise IncompleteInput, 'unexpected end of input' if value == false
+
+      near = value.is_a?(AST::Word) ? value.literal_text : value
+      raise ParseError, "syntax error at #{@lexer.location}: unexpected #{token_to_str(token_id)} `#{near}`"
+    end
+
+    private
+
+    def make_list(entries)
+      AST::List.new(entries.map { |and_or, sep| AST::ListEntry.new(and_or: and_or, async: sep == '&') })
+    end
+
+    def pending_entry(and_or)
+      [and_or, ';']
+    end
+
+    def terminate_list(entries, sep)
+      entries.last[1] = sep
+      entries
+    end
+
+    def append_and_or(entries, sep, and_or)
+      entries.last[1] = sep
+      entries << [and_or, ';']
+    end
+
+    def make_and_or(left, op, right)
+      AST::AndOr.new(left, op, right)
+    end
+
+    def make_pipeline(commands, negate)
+      AST::Pipeline.new(commands, negate)
+    end
+
+    def make_if(condition, consequent, alternative)
+      AST::If.new(condition, consequent, alternative)
+    end
+
+    def make_brace_group(body)
+      AST::BraceGroup.new(body)
+    end
+
+    def make_subshell(body)
+      AST::Subshell.new(body)
+    end
+
+    def make_redirected(command, redirects)
+      AST::Redirected.new(command, redirects)
+    end
+
+    def make_while(condition, body)
+      AST::While.new(condition, body)
+    end
+
+    def make_until(condition, body)
+      AST::Until.new(condition, body)
+    end
+
+    def make_for(name, words, body)
+      AST::For.new(name, words, body)
+    end
+
+    def make_case(word, items)
+      AST::Case.new(word, items)
+    end
+
+    def make_case_item(patterns, body)
+      AST::CaseItem.new(patterns: patterns, body: body)
+    end
+
+    def make_function(word, body)
+      AST::FunctionDef.new(word.literal_text, body)
+    end
+
+    def make_simple_command(prefix, word, suffix)
+      AST::SimpleCommand.new(prefix + [word].compact + suffix)
+    end
+
+    def make_redirect(kind, target)
+      AST::Redirect.new(kind: kind, target: target, io_number: nil)
+    end
+
+    def make_heredoc(holder)
+      AST::Redirect.new(kind: :heredoc, target: holder, io_number: nil)
+    end
+
+    def with_io_number(redirect, number)
+      redirect.with(io_number: number)
+    end
+  end
+end

data/lib/rush/pattern_scanner.rb

@@ -0,0 +1,35 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  # Shared left-to-right shell-pattern scanner. Concrete compilers implement
+  # the four append_* handlers; this class owns token dispatch and cursor
+  # progress so the Ruby fallback and native ERE translator cannot drift.
+  class PatternScanner
+    extend T::Sig
+
+    HANDLERS = { '\\' => :append_escape, '*' => :append_wildcard,
+                 '?' => :append_wildcard, '[' => :append_bracket }.freeze
+
+    sig { params(pattern: String).void }
+    def initialize(pattern)
+      @scanner = StringScanner.new(pattern)
+      scan
+    end
+
+    private
+
+    sig { void }
+    def scan
+      step until @scanner.eos?
+    end
+
+    sig { void }
+    def step
+      handler = HANDLERS.fetch(@scanner.peek(1), :append_literal)
+      send(handler)
+    end
+  end
+end

data/lib/rush/pending_signals.rb

@@ -0,0 +1,57 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Coalesces caught signals until the evaluator reaches a safe command
+  # boundary. POSIX does not require multiple instances of one signal to queue;
+  # dash drains distinct pending signals in signal-number order.
+  class PendingSignals
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      @names = T.let(empty, T::Hash[String, T::Boolean])
+    end
+
+    # Called from Ruby's Signal.trap block: deliberately only one Hash write,
+    # with no parser, evaluator, mutex or user shell code in handler context.
+    sig { params(name: String).void }
+    def record(name)
+      @names[name] = true
+    end
+
+    sig { params(blk: T.proc.params(name: String).void).void }
+    def drain(&blk)
+      take.each(&blk) until @names.empty?
+    end
+
+    sig { returns(T.nilable(String)) }
+    def first
+      @names.keys.min_by { |name| Signals.number(name) }
+    end
+
+    sig { returns(T::Boolean) }
+    def any?
+      @names.any?
+    end
+
+    sig { void }
+    def clear
+      @names.clear
+    end
+
+    private
+
+    sig { returns(T::Array[String]) }
+    def take
+      names = @names
+      @names = empty
+      names.keys.sort_by { |name| Signals.number(name) }
+    end
+
+    sig { returns(T::Hash[String, T::Boolean]) }
+    def empty
+      {} #: Hash[String, bool]
+    end
+  end
+end

data/lib/rush/pipeline_runner.rb

@@ -0,0 +1,173 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs a multi-stage pipeline: a pipe between each pair of stages, every stage
+  # forked (so they run concurrently and never deadlock on a full pipe buffer),
+  # the parent's pipe ends closed, then waitpid for all. The pipeline's status is
+  # normally the last stage's, or the rightmost non-zero stage's under pipefail.
+  # A stage is an arbitrary command — a simple command, but
+  # also a group/subshell/if/while/for/case or a function call — so it is run via
+  # the executor with the stage's pipe ends bound as the base IoTable. Each stage
+  # is a subshell environment (POSIX 2.12): exit/return end only the stage, loop
+  # control is inert, traps reset, and a fatal error aborts just that stage —
+  # SubshellRunner#run_body is exactly that resolution, so stages run through it.
+  # `start_stage` is the one irreducible fork/exit wrapper; the child-side
+  # `run_stage` (and its fd setup) is tested directly.
+  class PipelineRunner
+    extend T::Sig
+
+    # One stage of the pipeline: its position plus the shared pipe array and the
+    # stage count. The fd topology — which pipe end feeds this stage (input) and
+    # which it feeds (output), and so which ends to keep open (ends) — derives
+    # from all three, so the runner threads a single Stage rather than the
+    # (index, pipes) pair through every per-stage step.
+    class Stage
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :index, :count
+
+      sig { returns(T::Array[[IO, IO]]) }
+      attr_reader :pipes
+
+      sig { params(index: Integer, pipes: T::Array[[IO, IO]], count: Integer).void }
+      def initialize(index, pipes, count)
+        @index = index
+        @pipes = pipes
+        @count = count
+      end
+
+      sig { returns(T::Boolean) }
+      def last?
+        index == count - 1
+      end
+
+      sig { returns(T.nilable(IO)) }
+      def input
+        index.positive? ? pipes.fetch(index - 1).first : nil
+      end
+
+      sig { returns(T.nilable(IO)) }
+      def output
+        last? ? nil : pipes.fetch(index).last
+      end
+
+      sig { returns(T::Array[IO]) }
+      def ends
+        [input, output].compact
+      end
+
+      # Layer this stage's pipe ends over the base IoTable: stdin from the
+      # previous pipe (unless first), stdout to the next pipe (unless last).
+      sig { params(base: IoTable).returns(IoTable) }
+      def io(base)
+        base = base.with(0, input) if input
+        output ? base.with(1, output) : base
+      end
+
+      sig { void }
+      def close_unused
+        keep = ends
+        pipes.each { |pipe| close_unkept(pipe, keep) }
+      end
+
+      private
+
+      sig { params(pipe: [IO, IO], keep: T::Array[IO]).void }
+      def close_unkept(pipe, keep)
+        pipe.each { |io| io.close unless keep.include?(io) }
+      end
+    end
+
+    sig { params(executor: Executor, commands: T::Array[AST::Node]).void }
+    def initialize(executor, commands)
+      @executor = executor
+      @commands = commands
+    end
+
+    # The whole pipeline is one job: under job control its group (led by the
+    # first stage) owns the terminal until every stage has settled, so the
+    # reclaim wraps the full wait, not each stage's — and a ^Z parks all of
+    # it as one Stopped entry.
+    sig { returns(Status) }
+    def call
+      pipes = build_pipes
+      pids = start_stages(pipes)
+      close_all(pipes)
+      @executor.job_control.foreground(pids, text: text) { wait(pids) }
+    end
+
+    private
+
+    # The adopted-job text of a ^Z-parked pipeline (nil without job control).
+    sig { returns(T.nilable(String)) }
+    def text
+      CommandText.stages(@commands) if @executor.job_control.monitored?
+    end
+
+    sig { returns(T::Array[[IO, IO]]) }
+    def build_pipes
+      Array.new(@commands.size - 1) { @executor.system.pipe }
+    end
+
+    # Stages fork sequentially, each joining the first stage's process group
+    # under job control (dash: one group per pipeline, first process is the
+    # leader). Because stage 0's group is settled — parent-side setpgid —
+    # before stage 1 is even forked, later members can never race the group
+    # into existence.
+    sig { params(pipes: T::Array[[IO, IO]]).returns(T::Array[Integer]) }
+    def start_stages(pipes)
+      @commands.each_index.with_object([]) do |index, pids|
+        pids << start_stage(Stage.new(index, pipes, @commands.size), pids.first)
+      end
+    end
+
+    sig { params(stage: Stage, leader: T.nilable(Integer)).returns(Integer) }
+    def start_stage(stage, leader)
+      @executor.job_control.launch(leader: leader) { @executor.system.exit!(run_stage(stage).exitstatus) }
+    end
+
+    # Child-side. The relay is armed before the body (and its subshell
+    # reset) runs: a stage of a monitor-mode job propagates a member's
+    # stop upward instead of blocking on it (rush-l4o).
+    sig { params(stage: Stage).returns(Status) }
+    def run_stage(stage)
+      close_unused(stage)
+      @executor.jobs.control.arm_stage_relay
+      body = @commands.fetch(stage.index)
+      @executor.with_io(stage.io(@executor.io)) { SubshellRunner.new(@executor, body).run_body }
+    end
+
+    sig { params(stage: Stage).void }
+    def close_unused(stage)
+      stage.close_unused
+    end
+
+    sig { params(pipes: T::Array[[IO, IO]]).void }
+    def close_all(pipes)
+      pipes.each { |pipe| pipe.each(&:close) }
+    end
+
+    sig { params(pids: T::Array[Integer]).returns(Status) }
+    def wait(pids)
+      statuses = PipelineStatuses.new(pids.map { |pid| wait_status(pid) })
+      pipefail? ? statuses.pipefail_verdict : statuses.verdict
+    end
+
+    # A directly-killed stage reports on the shell's stderr, like dash's
+    # per-stage printsignal (probed: two killed stages print two lines, in
+    # stage order, unmoved by the stages' own redirects). The common case —
+    # an external dying inside the stage — reports from the stage
+    # supervisor's own External instead.
+    sig { params(pid: Integer).returns(Status) }
+    def wait_status(pid)
+      SignalReport.report(@executor.jobs.await(pid), @executor.io.get(2))
+    end
+
+    sig { returns(T::Boolean) }
+    def pipefail?
+      @executor.state.options.on?(:pipefail)
+    end
+  end
+end

data/lib/rush/pipeline_statuses.rb

@@ -0,0 +1,45 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Chooses the observable status for a settled multi-stage pipeline: the
+  # last stage's (or, under pipefail, the rightmost failure), with any
+  # stage's stop signal riding along — a ^Z parks the whole job even when
+  # the final stage had already exited (Status#with_stop, dash-probed).
+  class PipelineStatuses
+    extend T::Sig
+
+    sig { params(entries: T::Array[Status]).void }
+    def initialize(entries)
+      @entries = entries
+    end
+
+    sig { returns(Status) }
+    def verdict
+      last_stage.with_stop(job_stopsig)
+    end
+
+    sig { returns(Status) }
+    def pipefail_verdict
+      pipefail.with_stop(job_stopsig)
+    end
+
+    sig { returns(Status) }
+    def last_stage
+      @entries.fetch(-1)
+    end
+
+    sig { returns(Status) }
+    def pipefail
+      @entries.reverse_each { |status| return status unless status.success? }
+      Status.success
+    end
+
+    private
+
+    sig { returns(T.nilable(Integer)) }
+    def job_stopsig
+      @entries.filter_map(&:stopsig).first
+    end
+  end
+end

data/lib/rush/positional.rb

@@ -0,0 +1,45 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Rush
+  # The positional parameters $1..$n: a list of strings that `set` replaces,
+  # `shift` drops the front of, and a function call brackets with #with so the
+  # caller's are restored on return. Reads ($1, $#, $@, the for-loop word list)
+  # delegate to the underlying array.
+  class Positional
+    extend T::Sig
+    extend Forwardable
+
+    def_delegators :@values, :==, :[], :size, :empty?, :join, :map, :each, :to_a
+
+    sig { params(values: T::Array[String]).void }
+    def initialize(values = [])
+      @values = values
+    end
+
+    sig { params(values: T::Array[String]).void }
+    def replace(values)
+      @values = values
+    end
+
+    sig { params(count: Integer).void }
+    def shift(count)
+      @values = @values.drop(count)
+    end
+
+    sig do
+      type_parameters(:U)
+        .params(values: T::Array[String], blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def with(values, &blk)
+      saved = T.let(@values, T::Array[String])
+      @values = values
+      yield
+    ensure
+      @values = T.must(saved)
+    end
+  end
+end

data/lib/rush/posix_pattern.rb

@@ -0,0 +1,78 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Translates one shell pattern into a POSIX extended regular expression. The
+  # libc regex engine then supplies LC_COLLATE equivalence classes, collating
+  # symbols and locale ranges that Ruby's regexp/fnmatch APIs do not expose.
+  # :reek:InstanceVariableAssumption -- @scanner is initialized by PatternScanner#initialize
+  class PosixPattern < PatternScanner
+    extend T::Sig
+
+    ERE_SPECIAL = /[.\^$+(){}|\[\]*?\\]/
+    RUBY_GLOB_SPECIAL = %w[{ }].freeze
+
+    sig { returns(String) }
+    attr_reader :source, :glob_source
+
+    sig { params(pattern: String).void }
+    def initialize(pattern)
+      @source = +'^'
+      @glob_source = +''
+      super
+      @source << '$'
+    end
+
+    private
+
+    sig { void }
+    def append_escape
+      @scanner.getch
+      escaped = @scanner.getch || '\\'
+      @glob_source << '\\' << escaped
+      append_ere_literal(escaped)
+    end
+
+    sig { void }
+    def append_wildcard
+      char = @scanner.getch.to_s
+      append_discovery(char)
+      @source << (char == '*' ? '.*' : '.')
+    end
+
+    sig { void }
+    def append_bracket
+      bracket = BracketExpression.parse(@scanner.string, @scanner.pos)
+      return append_literal unless bracket
+
+      @source << bracket_source(bracket)
+      append_discovery('*')
+      @scanner.pos = bracket.finish
+    end
+
+    sig { params(bracket: BracketExpression).returns(String) }
+    def bracket_source(bracket)
+      source = bracket.source.sub(/\A\[!/, '[^')
+      source.include?('\\') ? EscapedBracket.new(source).source : source
+    end
+
+    sig { void }
+    def append_literal
+      char = @scanner.getch.to_s
+      append_discovery(char)
+      append_ere_literal(char)
+    end
+
+    sig { params(char: String).void }
+    def append_discovery(char)
+      return if char == '*' && @glob_source.end_with?('*')
+
+      @glob_source << (RUBY_GLOB_SPECIAL.include?(char) ? "\\#{char}" : char)
+    end
+
+    sig { params(char: String).void }
+    def append_ere_literal(char)
+      @source << (char.match?(ERE_SPECIAL) ? "\\#{char}" : char)
+    end
+  end
+end

data/lib/rush/program_input.rb

@@ -0,0 +1,89 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The program text and shell parameters implied by
+  # `-c command_string [command_name [argument...]]`.
+  class CommandInput
+    extend T::Sig
+
+    sig { params(operands: T::Array[String]).void }
+    def initialize(operands)
+      @operands = operands
+    end
+
+    sig { returns(String) }
+    def name
+      @operands.fetch(1, 'rush')
+    end
+
+    sig { returns(T::Array[String]) }
+    def positionals
+      @operands.drop(2)
+    end
+
+    sig { returns(String) }
+    def source
+      @operands.fetch(0) { raise InvocationError, '-c requires an argument' }
+    end
+  end
+
+  # The program text and shell parameters implied by a script-file operand:
+  # the path becomes $0, later operands the positional parameters, and the
+  # file is read lazily — unreadable files are an invocation error (status 2,
+  # like dash).
+  class ScriptInput
+    extend T::Sig
+
+    sig { params(operands: T::Array[String], system: SystemCalls).void }
+    def initialize(operands, system)
+      @operands = operands
+      @system = system
+    end
+
+    sig { returns(String) }
+    def name
+      @operands.fetch(0)
+    end
+
+    sig { returns(T::Array[String]) }
+    def positionals
+      @operands.drop(1)
+    end
+
+    sig { returns(String) }
+    def source
+      @system.read_file(name)
+    rescue SystemCallError => e
+      raise InvocationError, "cannot open #{name}: #{e.message}"
+    end
+  end
+
+  # The program text and shell parameters implied by reading stdin (implicitly
+  # or via -s): the operands become the positional parameters and $0 stays the
+  # shell name.
+  class StdinInput
+    extend T::Sig
+
+    sig { params(operands: T::Array[String], system: SystemCalls).void }
+    def initialize(operands, system)
+      @operands = operands
+      @system = system
+    end
+
+    sig { returns(String) }
+    def name
+      'rush'
+    end
+
+    sig { returns(T::Array[String]) }
+    def positionals
+      @operands
+    end
+
+    sig { returns(String) }
+    def source
+      @system.stdin.read
+    end
+  end
+end

data/lib/rush/program_reader.rb

@@ -0,0 +1,69 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Reads a shell source one line at a time, accumulating until the buffer parses
+  # to a complete program. POSIX reads and executes command by command, so an
+  # earlier command (a function definition, a future `alias`) can shape later
+  # input and a syntax error only stops the commands that follow it — the ones
+  # before it have already run. IncompleteInput means "the construct is
+  # unfinished": pull another line (multi-line here-documents included). At end of
+  # input a pending buffer gets one final, non-interactive parse so an
+  # unterminated here-document still runs with the body so far, exactly like dash.
+  class ProgramReader
+    extend T::Sig
+
+    sig do
+      params(aliases: AliasTable,
+             next_line: T.proc.params(buffered: T::Boolean).returns(T.nilable(String))).void
+    end
+    def initialize(aliases: AliasTable.new, &next_line)
+      @next_line = next_line
+      @aliases = aliases
+      @buffer = +''
+      @lines = SourceLineCounter.new
+    end
+
+    # The next complete program, or :eof. Raises ParseError on a real syntax
+    # error, so the caller decides policy: batch aborts, the REPL reports and
+    # resumes.
+    sig { returns(T.any(AST::List, Symbol)) }
+    def next_program
+      @buffer = +''
+      loop do
+        outcome = read_more
+        return outcome unless outcome == :more
+      end
+    end
+
+    private
+
+    sig { returns(T.any(AST::List, Symbol)) }
+    def read_more
+      line = @next_line.call(!@buffer.empty?)
+      return finish unless line
+
+      record_line(line)
+      attempt(@buffer << line)
+    end
+
+    sig { params(line: String).void }
+    def record_line(line)
+      @buffer.empty? ? @lines.start(line) : @lines.continue(line)
+    end
+
+    sig { params(source: String).returns(T.any(AST::List, Symbol)) }
+    def attempt(source)
+      Parser.new(Lexer.new(source, interactive: true, aliases: @aliases, line_offset: @lines.offset)).parse
+    rescue IncompleteInput
+      :more
+    end
+
+    sig { returns(T.any(AST::List, Symbol)) }
+    def finish
+      return :eof if @buffer.empty?
+
+      Parser.new(Lexer.new(@buffer, interactive: false, aliases: @aliases, line_offset: @lines.offset)).parse
+    end
+  end
+end