rush-shell 0.0.2

data/lib/rush/ast/while_node.rb

@@ -0,0 +1,18 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module AST
+    # `while cond; do body; done` — runs the body while the condition succeeds.
+    class While < ConditionLoop
+      extend T::Sig
+
+      private
+
+      sig { returns(Symbol) }
+      def kind
+        :while
+      end
+    end
+  end
+end

data/lib/rush/ast/word.rb

@@ -0,0 +1,44 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module AST
+    # An unexpanded word: an ordered list of typed segments. The expander turns
+    # the segments into fields; `literal_text` is the simple concatenation used
+    # for error messages and (unquoted) assignment-name detection.
+    class Word < Node
+      extend T::Sig
+
+      attr_reader :segments, :source_line
+
+      sig { params(segments: T::Array[WordSegment[T.untyped]], source_line: Integer).void }
+      def initialize(segments, source_line: 1)
+        @segments = segments
+        @source_line = source_line
+      end
+
+      sig { params(text: String, source_line: Integer).returns(Word) }
+      def self.literal(text, source_line: 1)
+        new([LiteralSegment.new(text, false)], source_line: source_line)
+      end
+
+      sig { returns(String) }
+      def literal_text
+        segments.map(&:value).join
+      end
+
+      # The text when this word is a bare name — one unquoted literal segment, no
+      # quoting or substitution — else nil. Used for reserved words, NAME=, and
+      # alias substitution, all of which only apply to a plain literal word.
+      sig { returns(T.nilable(String)) }
+      def literal_name
+        (segments.first.literal_value if segments.one?)
+      end
+
+      sig { returns(T.nilable(String)) }
+      def first_literal_value
+        segments.fetch(0).literal_value
+      end
+    end
+  end
+end

data/lib/rush/ast/word_segment.rb

@@ -0,0 +1,203 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module AST
+    # A typed piece of a word. Subclasses know how to expand themselves (the
+    # segment-level counterpart of a command node's #execute), so there is no
+    # `kind` to dispatch on: `quoted` records whether it came from a quoted
+    # context (which governs field splitting and pathname expansion), `value` is
+    # the kind-specific payload (literal text, a ParamRef, or substitution
+    # source). literal_value is the text when the segment can stand in as a bare
+    # name; splittable?/splat? are its field-splitting roles.
+    class WordSegment
+      extend T::Sig
+      extend T::Generic
+
+      Value = type_member
+
+      sig { returns(Value) }
+      attr_reader :value
+
+      sig { returns(T::Boolean) }
+      attr_reader :quoted
+
+      sig { params(value: Value, quoted: T::Boolean).void }
+      def initialize(value, quoted)
+        @value = value
+        @quoted = quoted
+      end
+
+      # Each concrete segment expands itself to a string (the segment-level
+      # counterpart of a command node's #execute); the base is abstract.
+      sig { params(_executor: Executor).returns(String) }
+      def expand(_executor)
+        raise NotImplementedError
+      end
+
+      sig { returns(T.nilable(String)) }
+      # mutant:disable -- `nil` is the default "not a literal" value; an empty
+      # method body has the same public semantics for this abstract fallback.
+      def literal_value
+        nil
+      end
+
+      # This segment as dash's canonical job text prints it (CommandText):
+      # each kind re-spells itself; the base is abstract.
+      sig { returns(String) }
+      def canon
+        raise NotImplementedError
+      end
+
+      sig { returns(T::Boolean) }
+      def splittable?
+        false
+      end
+
+      sig { returns(T::Boolean) }
+      def splat?
+        false
+      end
+
+      sig { params(executor: Executor, parts: T::Array[Expansion::FieldPart]).void }
+      def append_field_parts(executor, parts)
+        parts << [expand(executor), splittable?, false, quoted]
+      end
+
+      # A copy with a rewritten value (e.g. after tilde expansion).
+      sig { params(new_value: Value).returns(WordSegment[Value]) }
+      def with_value(new_value)
+        self.class.new(new_value, quoted)
+      end
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.instance_of?(self.class)
+        return false unless equality_value.eql?(other.equality_value)
+        return false unless quoted.eql?(other.quoted)
+
+        true
+      end
+
+      alias eql? ==
+
+      sig { returns(T.untyped) }
+      def equality_value
+        value
+      end
+
+      sig { returns(Integer) }
+      def hash
+        [self.class, value, quoted].hash
+      end
+    end
+
+    # Literal text. It expands to itself, can act as a bare name when unquoted,
+    # and is never field-split.
+    class LiteralSegment < WordSegment
+      extend T::Sig
+      extend T::Generic
+
+      Value = type_member { { fixed: String } }
+
+      # dash escapes \ " $ ` inside the double quotes a quoted run gets.
+      CANON_ESCAPES = T.let(/[\\"$`]/, Regexp)
+
+      sig { params(_executor: Executor).returns(String) }
+      def expand(_executor)
+        value
+      end
+
+      sig { returns(T.nilable(String)) }
+      def literal_value
+        (value unless quoted)
+      end
+
+      sig { returns(String) }
+      def canon
+        quoted ? value.gsub(CANON_ESCAPES) { |char| "\\#{char}" } : value
+      end
+    end
+
+    # A segment substituted at expansion time (param / command / arithmetic): its
+    # unquoted result undergoes field splitting.
+    class DynamicSegment < WordSegment
+      extend T::Sig
+      extend T::Generic
+
+      Value = type_member
+
+      sig { returns(T::Boolean) }
+      def splittable?
+        !quoted
+      end
+    end
+
+    # $name / ${...}: value is the ParamRef.
+    class ParamSegment < DynamicSegment
+      extend T::Sig
+      extend T::Generic
+
+      Value = type_member { { fixed: ParamRef } }
+
+      sig { params(executor: Executor).returns(String) }
+      def expand(executor)
+        Expansion::ParameterExpander.new(executor, value, quoted: quoted).expand
+      end
+
+      # $@ (always) and unquoted $* expand to one field per positional parameter.
+      sig { returns(T::Boolean) }
+      def splat?
+        !value.op && (value.name == '@' || (value.name == '*' && !quoted))
+      end
+
+      sig { params(executor: Executor, parts: T::Array[Expansion::FieldPart]).void }
+      def append_field_parts(executor, parts)
+        parts.concat(Expansion::ParameterExpander.new(executor, value, quoted: quoted).expand_parts)
+      end
+
+      sig { returns(String) }
+      def canon
+        value.canon
+      end
+    end
+
+    # $(...) / `...`: value is the command-substitution source.
+    class CommandSegment < DynamicSegment
+      extend T::Sig
+      extend T::Generic
+
+      Value = type_member { { fixed: String } }
+
+      sig { params(executor: Executor).returns(String) }
+      def expand(executor)
+        Expansion::CommandSubstitution.new(executor, value).expand
+      end
+
+      # dash elides a command substitution's body from the job text.
+      sig { returns(String) }
+      def canon
+        '$(...)'
+      end
+    end
+
+    # $((...)): value is the arithmetic source.
+    class ArithSegment < DynamicSegment
+      extend T::Sig
+      extend T::Generic
+
+      Value = type_member { { fixed: String } }
+
+      sig { params(executor: Executor).returns(String) }
+      def expand(executor)
+        Expansion::ArithmeticExpander.new(executor, value).expand
+      end
+
+      # An arithmetic expansion keeps its raw source in the job text.
+      sig { returns(String) }
+      def canon
+        "$((#{value}))"
+      end
+    end
+  end
+end

data/lib/rush/background_runner.rb

@@ -0,0 +1,68 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs an asynchronous list entry in a forked subshell. The parent records
+  # the child pid for $! and in the job table (where the wait builtin finds
+  # it) and immediately returns success (launch semantics); the child
+  # isolates itself per POSIX (stdin from /dev/null, SIGINT/SIGQUIT ignored)
+  # and resolves shell-control exceptions to an exit status like a subshell.
+  class BackgroundRunner
+    extend T::Sig
+
+    sig { params(executor: Executor, body: AST::Node).void }
+    def initialize(executor, body)
+      @executor = executor
+      @body = body
+    end
+
+    sig { returns(Status) }
+    def call
+      pid = @executor.job_control.launch_background { run_child }
+      @executor.state.record_background_pid(pid)
+      @executor.jobs.record(pid, text: @executor.job_control.job_text(@body))
+      Status.success
+    end
+
+    sig { returns(Status) }
+    def run_body
+      isolate
+      SubshellRunner.new(@executor, @body).run_body
+    end
+
+    private
+
+    # POSIX 2.9.3.1 / 2.11 with job control disabled: an async child reads
+    # stdin from /dev/null (its own redirections may rebind it) and starts
+    # with SIGINT/SIGQUIT ignored. Both apply ONLY without job control — under
+    # set -m the job sits in its own process group, so POSIX (and dash,
+    # probed) leave stdin and SIGINT alone; monitored? is read before
+    # enter_subshell switches the machinery off for this child. The subshell
+    # entry (trap reset + job-table clear) must run first — an interactive
+    # session's base handlers reinstall OS defaults as they drop, which would
+    # undo the ignores. The immediate repeat inside SubshellRunner#run_body is
+    # harmless because isolation creates no reset-sensitive shell state between
+    # entries: no body, child job, pending signal, caught trap or EXIT action.
+    # Raw dispositions and stdin are deliberately installed there, and the
+    # second entry does not reset them. This is not general idempotence. The
+    # ignores are a real SIG_IGN, kept off the trap table: they
+    # survive exec and nested subshells, while `trap` overrides them and
+    # `trap - INT` restores the OS default (dash-verified).
+    sig { void }
+    def isolate
+      monitored = @executor.job_control.monitored?
+      @executor.enter_subshell
+      return if monitored
+
+      %w[INT QUIT].each { |name| @executor.system.trap_signal(name, 'IGNORE') { nil } }
+      @executor.replace_io(@executor.io.with(0, @executor.system.open_file(File::NULL, 'r')))
+    end
+
+    sig { returns(T.noreturn) }
+    def run_child
+      # :nocov:
+      @executor.system.exit!(run_body.exitstatus)
+      # :nocov:
+    end
+  end
+end

data/lib/rush/bracket_expression.rb

@@ -0,0 +1,107 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  # One shell-pattern bracket expression. It recognizes the nested POSIX
+  # character-class, equivalence-class and collating-symbol delimiters so their
+  # inner `]` does not terminate the outer expression.
+  class BracketExpression
+    extend T::Sig
+
+    CLASS_NAMES = %w[alnum alpha blank cntrl digit graph lower print punct space upper xdigit].freeze
+
+    sig { returns(String) }
+    attr_reader :source
+
+    sig { returns(Integer) }
+    attr_reader :finish
+
+    sig { params(pattern: String, start: Integer).returns(T.nilable(BracketExpression)) }
+    def self.parse(pattern, start)
+      finish, special = BracketScanner.new(pattern, start).call
+      return new(T.must(pattern[start...finish]), finish, special, true) if finish
+
+      new(T.must(pattern[start..]), pattern.length, true, false) if special
+    end
+
+    sig { params(source: String, finish: Integer, special: T::Boolean, closed: T::Boolean).void }
+    def initialize(source, finish, special, closed)
+      @source = source
+      @finish = finish
+      @special = special
+      @closed = closed
+    end
+
+    sig { returns(T::Boolean) }
+    def special?
+      @special
+    end
+
+    sig { returns(String) }
+    def glob_source
+      special? ? '?' : source
+    end
+
+    sig { params(regexp: String, glob: String, scanner: StringScanner).void }
+    def append_to(regexp, glob, scanner)
+      regexp << regex
+      glob << glob_source
+      scanner.pos = finish
+    end
+
+    # Ruby regexp supports the twelve required POSIX named classes. The two
+    # collation forms have a portable one-character meaning in the POSIX locale;
+    # multi-character locale collation is deliberately left invalid here.
+    sig { returns(String) }
+    def regex
+      raise RegexpError unless @closed
+
+      "[#{regexp_body}]"
+    rescue RegexpError
+      '(?!)'
+    end
+
+    private
+
+    sig { returns(String) }
+    def regexp_body
+      body = collating(classes(negation(source.delete_prefix('[').delete_suffix(']'))))
+      escape_brackets(body)
+    end
+
+    sig { params(body: String).returns(String) }
+    def escape_brackets(body)
+      body = body.sub(/\A(\^?)\]/) { "#{Regexp.last_match(1)}\\]" }
+      body.gsub(/(?<!\\)\[(?!:)/, '\\\\[')
+    end
+
+    sig { params(body: String).returns(String) }
+    def negation(body)
+      body.sub(/\A[!^]/, '^')
+    end
+
+    sig { params(body: String).returns(String) }
+    def classes(body)
+      body.gsub(/\[:([a-z]+):\]/) do
+        name = Regexp.last_match(1)
+        raise RegexpError unless CLASS_NAMES.include?(name)
+
+        "[:#{name}:]"
+      end
+    end
+
+    sig { params(body: String).returns(String) }
+    def collating(body)
+      body.gsub(/\[([=.])(.*?)\1\]/) { collating_element(T.must(Regexp.last_match(2))) }
+    end
+
+    sig { params(element: String).returns(String) }
+    def collating_element(element)
+      raise RegexpError unless element.each_char.one?
+
+      Regexp.escape(element)
+    end
+  end
+end

data/lib/rush/bracket_scanner.rb

@@ -0,0 +1,64 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Finds the outer close of a shell bracket expression without mistaking the
+  # `]` inside POSIX `[:class:]`, `[=equiv=]` or `[.collating.]` for it.
+  class BracketScanner
+    extend T::Sig
+
+    TOKEN_ENDS = { ':' => ':]', '=' => '=]', '.' => '.]' }.freeze
+
+    sig { params(pattern: String, start: Integer).void }
+    def initialize(pattern, start)
+      @pattern = pattern
+      @index = first_index(start)
+      @special = false
+    end
+
+    sig { returns([T.nilable(Integer), T::Boolean]) }
+    def call
+      advance until complete?
+      [finish, @special]
+    end
+
+    private
+
+    sig { params(start: Integer).returns(Integer) }
+    def first_index(start)
+      index = start + 1
+      index += 1 if %w[! ^].include?(@pattern[index])
+      @pattern[index] == ']' ? index + 1 : index
+    end
+
+    sig { returns(T::Boolean) }
+    def complete?
+      current = @pattern[@index]
+      !current || current == ']'
+    end
+
+    sig { void }
+    def advance
+      token_finish = nested_finish
+      @special = true if token_finish
+      @index = token_finish || escaped_finish || (@index + 1)
+    end
+
+    sig { returns(T.nilable(Integer)) }
+    def escaped_finish
+      @index + 2 if @pattern[@index] == '\\' && @pattern[@index + 1]
+    end
+
+    sig { returns(T.nilable(Integer)) }
+    def nested_finish
+      ending = TOKEN_ENDS[@pattern[@index + 1].to_s] if @pattern[@index] == '['
+      found = @pattern.index(ending, @index + 2) if ending
+      found + 2 if found
+    end
+
+    sig { returns(T.nilable(Integer)) }
+    def finish
+      @index + 1 if @index < @pattern.length
+    end
+  end
+end

data/lib/rush/builtins/alias_.rb

@@ -0,0 +1,74 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `alias [name[=value]...]` defines or prints aliases. With no operands it
+    # lists every alias as a single-quoted `name=value` on stdout. An operand
+    # containing `=` past its first character defines (the name is everything
+    # before that `=`); a bare name prints that alias, or reports `alias: NAME not
+    # found` on stderr and yields status 1 while still processing the rest.
+    class Alias < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        if operands.empty?
+          list
+        else
+          operands.reduce(success) { |status, operand| keep(status, handle(operand)) }
+        end
+      end
+
+      private
+
+      sig { params(operand: String).returns(Status) }
+      def handle(operand)
+        name, sep, value = operand.partition('=')
+        sep.empty? || name.empty? ? query(operand) : define(name, value)
+      end
+
+      sig { params(name: String, value: String).returns(Status) }
+      def define(name, value)
+        aliases.define(name, value)
+        success
+      end
+
+      sig { params(name: String).returns(Status) }
+      def query(name)
+        value = aliases.value(name)
+        return show(name, value) if value
+
+        stderr.puts("alias: #{name} not found")
+        failure
+      end
+
+      sig { returns(Status) }
+      def list
+        aliases.listing.each { |name, value| show(name, value) }
+        success
+      end
+
+      sig { params(name: String, value: String).returns(Status) }
+      def show(name, value)
+        stdout.puts(single_quote("#{name}=#{value}"))
+        success
+      end
+
+      sig { params(text: String).returns(String) }
+      def single_quote(text)
+        "'#{text.gsub("'", %q('"'"'))}'"
+      end
+
+      sig { params(status: Status, result: Status).returns(Status) }
+      def keep(status, result)
+        status.success? ? result : status
+      end
+
+      sig { returns(AliasTable) }
+      def aliases
+        executor.state.aliases
+      end
+    end
+  end
+end

data/lib/rush/builtins/base.rb

@@ -0,0 +1,96 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # Base for builtins. Subclasses implement #call returning a Status. Streams
+    # come from the per-command IoTable so redirections apply to builtins too.
+    class Base
+      extend T::Sig
+
+      # A signed decimal integer (surrounding blanks allowed); the caller's min
+      # enforces whether negative or zero values are valid for this operand. dash
+      # parses it into a C int, so a value past INT_MAX overflows and is rejected
+      # like a non-numeric one.
+      NUMERIC_OPERAND = /\A\s*[+-]?\d+\s*\z/
+      INT_MAX = 2_147_483_647
+
+      sig do
+        params(executor: Executor, argv: T::Array[String], io: IoTable,
+               environment: T.nilable(T::Hash[String, String])).void
+      end
+      def initialize(executor, argv, io, environment = nil)
+        @executor = executor
+        @argv = argv
+        @io = io
+        @environment = environment
+      end
+
+      sig { returns(Status) }
+      def call
+        raise NotImplementedError
+      end
+
+      private
+
+      sig { returns(Executor) }
+      attr_reader :executor
+
+      sig { returns(T::Array[String]) }
+      attr_reader :argv
+
+      sig { returns(IoTable) }
+      attr_reader :io
+
+      # The exported environment assembled for this simple-command invocation,
+      # including temporary prefix assignments. Most builtins do not consume it;
+      # `command` forwards it when its nested target is external.
+      sig { returns(T::Hash[String, String]) }
+      def command_environment
+        @environment || executor.state.variables.exported
+      end
+
+      sig { returns(T::Array[String]) }
+      def operands
+        argv.drop(1)
+      end
+
+      sig { returns(T.untyped) }
+      def stdout
+        io.get(1)
+      end
+
+      sig { returns(T.untyped) }
+      def stderr
+        io.get(2)
+      end
+
+      sig { returns(Status) }
+      def success
+        Status.success
+      end
+
+      sig { params(code: Integer).returns(Status) }
+      def failure(code = 1)
+        Status.failure(code)
+      end
+
+      # Parse a numeric operand for a special builtin: an exit code for
+      # exit/return (min 0), or a loop level for break/continue (min 1). dash
+      # rejects a non-numeric, too-small or out-of-range value with a
+      # special-builtin error (which aborts a non-interactive shell).
+      sig { params(text: String, min: Integer).returns(Integer) }
+      def numeric_operand(text, min: 0)
+        value = Integer(text, 10) if text.match?(NUMERIC_OPERAND)
+        return T.must(value) if legal_operand?(value, min)
+
+        raise BuiltinError, "#{argv.first}: Illegal number: #{text}"
+      end
+
+      sig { params(value: T.nilable(Integer), min: Integer).returns(T::Boolean) }
+      def legal_operand?(value, min)
+        !!value&.between?(min, INT_MAX)
+      end
+    end
+  end
+end

data/lib/rush/builtins/break_.rb

@@ -0,0 +1,19 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `break [n]` — exit the n-th enclosing loop (default 1); the shared
+    # POSIX 2.9.5 semantics live in LoopJump.
+    class Break < LoopJump
+      extend T::Sig
+
+      private
+
+      sig { returns(T.class_of(LoopControl)) }
+      def signal
+        BreakSignal
+      end
+    end
+  end
+end