rush-shell 0.0.2

data/lib/rush/expansion/command_substitution.rb

@@ -0,0 +1,87 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Runs $(...) / `...`: parse the body, run it in a forked subshell whose
+    # stdout is a pipe, read everything the child writes, wait for it, and strip
+    # trailing newlines (POSIX). spawn_child/run_child are the irreducible
+    # fork/exit wrapper; `capture` (the child-side run) is tested directly.
+    class CommandSubstitution
+      extend T::Sig
+
+      sig { params(executor: Executor, source: String).void }
+      def initialize(executor, source)
+        @executor = executor
+        @source = source
+      end
+
+      sig { returns(String) }
+      def expand
+        read, write = @executor.system.pipe
+        pid = spawn_child(write)
+        write.close
+        strip(read_output(read, pid))
+      end
+
+      sig { params(write: T.untyped).returns(Status) }
+      def capture(write)
+        @executor.with_io(@executor.io.with(1, write)) { run_isolated }
+      end
+
+      private
+
+      # The body runs in a fresh errexit context (a subshell): a `set -e` failure
+      # ends only this substitution, leaving its status for the enclosing command.
+      # exit, and an uncaught return, both end the substitution with their code.
+      sig { returns(Status) }
+      def run_isolated
+        @executor.enter_subshell
+        status = run_isolated_status
+        Status.new(@executor.trap_runner.run_exit_trap(status.exitstatus))
+      end
+
+      sig { returns(Status) }
+      def run_isolated_status
+        @executor.errexit.untested { @executor.run(parse) }
+      rescue ExitSignal, ReturnSignal => e
+        @executor.state.record_status(Status.new(e.code))
+      end
+
+      # A substitution child killed by a signal reports on the shell's
+      # stderr, like dash (probed: x=$(sh -c 'kill -KILL $$') prints Killed).
+      sig { params(read: T.untyped, pid: T.untyped).returns(String) }
+      def read_output(read, pid)
+        output = read.read
+        read.close
+        status = SignalReport.report(@executor.jobs.await(pid), @executor.io.get(2))
+        @executor.record_cmd_sub_status(status)
+        output
+      end
+
+      sig { params(output: String).returns(String) }
+      def strip(output)
+        output.sub(/\n+\z/, '')
+      end
+
+      sig { params(write: T.untyped).returns(T.untyped) }
+      def spawn_child(write)
+        # :nocov:
+        @executor.system.fork { run_child(write) }
+        # :nocov:
+      end
+
+      sig { params(write: T.untyped).returns(T.untyped) }
+      def run_child(write)
+        # :nocov:
+        @executor.system.exit!(capture(write).exitstatus)
+        # :nocov:
+      end
+
+      sig { returns(AST::Node) }
+      def parse
+        Parser.new(Lexer.new(@source, aliases: @executor.state.aliases)).parse
+      end
+    end
+  end
+end

data/lib/rush/expansion/field_part.rb

@@ -0,0 +1,12 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # One expanded fragment on its way to field splitting, as
+    # [text, splittable, break, quoted]: the text itself, whether IFS may split
+    # it, whether a new field opens before it regardless of IFS (the boundary
+    # between $@/$* elements), and whether glob metacharacters need shielding.
+    FieldPart = T.type_alias { [String, T::Boolean, T::Boolean, T::Boolean] }
+  end
+end

data/lib/rush/expansion/field_splitter.rb

@@ -0,0 +1,23 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Entry point for IFS field splitting: it hands the parts and the IFS
+    # delimiter sets (an Ifs value) to IfsScanner, which applies the three POSIX
+    # cases.
+    class FieldSplitter
+      extend T::Sig
+
+      sig { params(ifs: T.nilable(String)).void }
+      def initialize(ifs)
+        @ifs = Ifs.new(ifs)
+      end
+
+      sig { params(parts: T::Array[FieldPart]).returns(T::Array[IfsScanner::Field]) }
+      def split(parts)
+        IfsScanner.new(@ifs).run(parts)
+      end
+    end
+  end
+end

data/lib/rush/expansion/glob_expander.rb

@@ -0,0 +1,48 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Pathname expansion (step 3): a field is replaced by the sorted pathnames it
+    # matches; a field that matches nothing — or any field while `set -f`
+    # (noglob) is in effect — stays literal. IfsScanner::Field carries literal
+    # text separately from its lazily shielded pattern, so a data backslash is
+    # preserved when no pathname replaces the field.
+    class GlobExpander
+      extend T::Sig
+
+      PATHNAME_PATTERN = /(?<!\\)(?:\\\\)*(?:[*?]|\[(?:\\.|[^\\\]])*\])/
+
+      sig { params(executor: Executor).void }
+      def initialize(executor)
+        @executor = executor
+      end
+
+      sig { params(field: IfsScanner::Field, expanded: T::Array[String]).void }
+      def append(field, expanded)
+        pattern = field.pattern
+        return expanded << field.text unless expandable?(pattern)
+
+        append_matches(field, expanded, matches(pattern))
+      end
+
+      private
+
+      sig { params(pattern: String).returns(T::Boolean) }
+      def expandable?(pattern)
+        !@executor.state.options.on?(:noglob) && pattern.match?(PATHNAME_PATTERN)
+      end
+
+      sig { params(pattern: String).returns(T::Array[String]) }
+      def matches(pattern)
+        locale = @executor.state.variables.locale_settings
+        @executor.system.glob(pattern, locale: locale)
+      end
+
+      sig { params(field: IfsScanner::Field, expanded: T::Array[String], matches: T::Array[String]).void }
+      def append_matches(field, expanded, matches)
+        matches.empty? ? expanded << field.text : expanded.concat(matches)
+      end
+    end
+  end
+end

data/lib/rush/expansion/ifs.rb

@@ -0,0 +1,62 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # The IFS value, parsed once into its whitespace and non-whitespace delimiter
+    # sets for POSIX field splitting. Unset IFS (nil) defaults to the standard
+    # <space><tab><newline>; a null IFS (the empty string) leaves both sets empty,
+    # so no character delimits.
+    class Ifs
+      extend T::Sig
+
+      WHITESPACE = " \t\n"
+      DEFAULT_CHARS = WHITESPACE.chars.freeze
+      NO_CHARS = T.let(
+        [], #: Array[String]
+        T::Array[String]
+      ).freeze
+
+      sig { params(ifs: T.nilable(String)).void }
+      def initialize(ifs)
+        @ifs = ifs
+        @chars = ifs ? ifs.chars.uniq.freeze : DEFAULT_CHARS
+        @whitespace, @others = delimiter_sets
+      end
+
+      sig { returns(T::Boolean) }
+      def null?
+        @ifs == ''
+      end
+
+      sig { returns(T::Array[String]) }
+      attr_reader :whitespace, :others
+
+      sig { returns(T::Boolean) }
+      def preserve_empty_splat?
+        @chars.first == @others.first
+      end
+
+      sig { params(char: String).returns(T::Boolean) }
+      def whitespace?(char)
+        !!(@chars.include?(char) && WHITESPACE.include?(char))
+      end
+
+      sig { params(char: String).returns(T::Boolean) }
+      def other?(char)
+        !!(@chars.include?(char) && !WHITESPACE.include?(char))
+      end
+
+      private
+
+      sig { returns([T::Array[String], T::Array[String]]) }
+      def delimiter_sets
+        return [DEFAULT_CHARS, NO_CHARS] unless @ifs
+        return [NO_CHARS, NO_CHARS] if @chars.empty?
+
+        whitespace, others = @chars.partition { |char| WHITESPACE.include?(char) }
+        [whitespace.freeze, others.freeze]
+      end
+    end
+  end
+end

data/lib/rush/expansion/ifs_scanner.rb

@@ -0,0 +1,168 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # The POSIX §2.6.5 field-splitting state machine. It runs once, left to right,
+    # over the expanded parts ([text, splittable, break, quoted]) so a delimiter that
+    # spans two adjacent unquoted expansions still yields the right (possibly
+    # empty) fields. IFS whitespace coalesces and is stripped at the ends; each
+    # non-whitespace IFS character delimits a field (so adjacent ones generate
+    # empty fields), while a single trailing delimiter is absorbed. Quoted text
+    # and a break-flagged part (the elements of $@/$*) anchor or force a field
+    # regardless of IFS. A trailing empty, non-anchored field is dropped.
+    #
+    # The field being built is held in @current (always present, by construction),
+    # with completed fields in @done — so the "there is always a current field"
+    # invariant is structural, not a runtime fact the reader/checker must infer.
+    class IfsScanner
+      extend T::Sig
+
+      # One output field under construction. Alongside its literal text it lazily
+      # records a distinct pathname pattern only when quoted metacharacters need
+      # shielding; a data backslash stays in both forms and is never stripped as
+      # if it were synthetic quote provenance.
+      class Field
+        extend T::Sig
+
+        QUOTED_PATTERN = /[\\*?\[\]\-!^]/
+        PATTERNS = { true => QUOTED_PATTERN, false => nil }.freeze
+
+        sig { returns(String) }
+        attr_reader :text
+
+        sig { void }
+        def initialize
+          @text = +''
+          @pattern = T.let(nil, T.nilable(String))
+          @real = false
+        end
+
+        sig { params(text: String, quoted: T::Boolean).void }
+        def append(text, quoted)
+          fragment = pattern_fragment(text, quoted)
+          @pattern = @text.dup if !@pattern && !fragment.equal?(text)
+          @pattern&.concat(fragment)
+          @text << text
+        end
+
+        sig { returns(String) }
+        def pattern
+          @pattern || @text
+        end
+
+        sig { void }
+        def mark_real
+          @real = true
+        end
+
+        sig { returns(T::Boolean) }
+        def empty_unreal?
+          @text.empty? && !@real
+        end
+
+        private
+
+        sig { params(text: String, quoted: T::Boolean).returns(String) }
+        def pattern_fragment(text, quoted)
+          pattern = PATTERNS.fetch(quoted)
+          return text unless pattern && text.match?(pattern)
+
+          text.gsub(pattern) { |meta| "\\#{meta}" }
+        end
+      end
+
+      sig { params(ifs: Ifs).void }
+      def initialize(ifs)
+        @ws = ifs.whitespace
+        @others = ifs.others
+        @preserve_empty_splat = ifs.preserve_empty_splat?
+        @done = T.let([], T::Array[Field])
+        @current = Field.new
+        @pending = false
+        @skip = true
+      end
+
+      sig { params(parts: T::Array[FieldPart]).returns(T::Array[Field]) }
+      def run(parts)
+        parts.each { |part| consume(part) }
+        result
+      end
+
+      private
+
+      sig { params(part: FieldPart).void }
+      def consume(part)
+        text, splittable, brk, quoted = part
+        break_field if brk
+        splittable ? text.each_char { |char| step(char) } : literal(text, quoted)
+      end
+
+      sig { params(char: String).void }
+      def step(char)
+        return pend if @ws.include?(char)
+        return open_field if @others.include?(char)
+
+        ordinary(char)
+      end
+
+      sig { void }
+      def pend
+        (@pending = true unless @skip)
+      end
+
+      sig { params(char: String).void }
+      def ordinary(char)
+        flush
+        @current.append(char, false)
+        @skip = false
+      end
+
+      sig { params(text: String, quoted: T::Boolean).void }
+      def literal(text, quoted)
+        flush
+        @current.append(text, quoted)
+        @current.mark_real
+        @skip = false
+      end
+
+      sig { void }
+      def flush
+        (open_field if @pending)
+      end
+
+      # An unquoted null $@/$* element disappears when the first IFS character
+      # is whitespace; otherwise its forced boundary remains an empty field.
+      sig { void }
+      def break_field
+        return reset_field if !@preserve_empty_splat && @current.empty_unreal?
+
+        open_field
+      end
+
+      sig { void }
+      def open_field
+        @done << @current
+        reset_field
+      end
+
+      sig { void }
+      def reset_field
+        @pending = false
+        @current = Field.new
+        @skip = true
+      end
+
+      sig { returns(T::Array[Field]) }
+      def result
+        @done << @current unless drop_last?
+        @done
+      end
+
+      sig { returns(T::Boolean) }
+      def drop_last?
+        @current.empty_unreal?
+      end
+    end
+  end
+end

data/lib/rush/expansion/parameter_expander.rb

@@ -0,0 +1,204 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  module Expansion
+    # Builds scalar and operator-word parts without discarding quote provenance.
+    class ParameterParts
+      extend T::Sig
+
+      sig { params(executor: Executor, quoted: T::Boolean).void }
+      def initialize(executor, quoted)
+        @executor = executor
+        @quoted = quoted
+      end
+
+      sig { params(text: String).returns(T::Array[FieldPart]) }
+      def scalar(text)
+        [[text, !@quoted, false, @quoted]]
+      end
+
+      sig { params(text: String).returns(T::Array[FieldPart]) }
+      def operator(text)
+        operator_word = word(text)
+        expanded = @executor.expander.expand_parts(operator_word, tilde: tilde_mode)
+        normalized(preserve_empty_at(expanded, operator_word))
+      end
+
+      sig { params(parts: T::Array[FieldPart]).returns(String) }
+      def collapse(parts)
+        @executor.expander.collapse(parts)
+      end
+
+      sig { params(text: String).returns(String) }
+      def pattern(text)
+        @executor.expander.expand_pattern(word(text), tilde: tilde_mode)
+      end
+
+      private
+
+      sig { params(expanded: T::Array[FieldPart], operator_word: AST::Word).returns(T::Array[FieldPart]) }
+      def preserve_empty_at(expanded, operator_word)
+        return expanded unless expanded.empty? && operator_word.segments.any?(&:quoted)
+
+        [['', false, false, true]]
+      end
+
+      sig { params(expanded: T::Array[FieldPart]).returns(T::Array[FieldPart]) }
+      def normalized(expanded)
+        expanded.map do |value, _splittable, brk, quoted|
+          protected = @quoted || quoted
+          [value, !protected, brk, protected]
+        end
+      end
+
+      sig { params(text: String).returns(AST::Word) }
+      def word(text)
+        @quoted ? Lexer::QuotedWord.new(text).word : Lexer::WordScanner.entire(text)
+      end
+
+      sig { returns(Symbol) }
+      def tilde_mode
+        @quoted ? :none : :leading
+      end
+    end
+
+    # Expands one ParamRef to quote-aware field parts: resolves the base value,
+    # then applies the operator form (if any). The operator word is itself expanded (so
+    # ${x:-$y} works) by re-scanning it into a Word and running it back through
+    # the expansion pipeline. `quoted` picks the word's re-scan rules: a ${...}
+    # inside double quotes or a here-doc keeps single quotes ordinary and
+    # skips tilde expansion, as dash does.
+    class ParameterExpander
+      extend T::Sig
+
+      # Operators handled here rather than by the FORMS lambdas: the ${#p} length
+      # and the # ## % %% pattern-removal forms.
+      PATTERN_REMOVAL = ['#', '##', '%', '%%'].freeze
+
+      sig { params(executor: Executor, ref: AST::ParamRef, quoted: T::Boolean).void }
+      def initialize(executor, ref, quoted:)
+        @executor = executor
+        @ref = ref
+        @quoted = quoted
+        @parts = ParameterParts.new(executor, quoted)
+      end
+
+      sig { returns(String) }
+      def expand
+        @parts.collapse(expand_parts)
+      end
+
+      sig { returns(T::Array[FieldPart]) }
+      def expand_parts
+        op = @ref.op
+        return @parts.scalar(plain) unless op
+        return @parts.scalar(length) if op == '#len'
+        return @parts.scalar(strip(op)) if PATTERN_REMOVAL.include?(op)
+
+        Parameter::FORMS.fetch(op.delete_prefix(':')).call(self)
+      end
+
+      # A bare $x / ${x}: under `set -u` an unset ordinary name or positional is
+      # an error (special parameters like $@ are exempt).
+      sig { returns(String) }
+      def plain
+        current = value
+        raise(ExpansionError, "#{@ref.name}: parameter not set") if !current && unbound?
+
+        current || ''
+      end
+
+      sig { returns(T.nilable(String)) }
+      def value
+        Resolver.new(@executor).resolve(@ref.name)
+      end
+
+      sig { returns(String) }
+      def value_text
+        value || ''
+      end
+
+      sig { returns(T::Boolean) }
+      def unset_or_null?
+        case value
+        in nil then true
+        in '' then colon?
+        else false
+        end
+      end
+
+      sig { returns(String) }
+      def arg
+        @parts.collapse(arg_parts)
+      end
+
+      sig { returns(T::Array[FieldPart]) }
+      def arg_parts
+        @parts.operator(argument)
+      end
+
+      sig { returns(T::Array[FieldPart]) }
+      def value_parts
+        @parts.scalar(value_text)
+      end
+
+      sig { returns(T::Array[FieldPart]) }
+      def empty_parts
+        @parts.scalar('')
+      end
+
+      sig { returns(T::Array[FieldPart]) }
+      def assign_parts
+        text = @parts.collapse(arg_parts)
+        @executor.state.variables.assign(@ref.name, text)
+        @parts.scalar(text)
+      end
+
+      sig { returns(T.noreturn) }
+      def raise_unset
+        raise(ExpansionError, "#{@ref.name}: #{message}")
+      end
+
+      private
+
+      sig { returns(String) }
+      def length
+        value_text.length.to_s
+      end
+
+      sig { params(op: String).returns(String) }
+      def strip(op)
+        PatternRemoval.new(@executor, op, value_text, pattern_arg).call
+      end
+
+      sig { returns(String) }
+      def pattern_arg
+        @parts.pattern(argument)
+      end
+
+      sig { returns(T::Boolean) }
+      def unbound?
+        @executor.state.options.on?(:nounset) && @ref.name.match?(/\A([a-zA-Z_]\w*|[1-9]\d*)\z/)
+      end
+
+      sig { returns(T::Boolean) }
+      def colon?
+        op = @ref.op
+        !!(op && op.start_with?(':'))
+      end
+
+      sig { returns(String) }
+      def message
+        argument.empty? ? 'parameter null or not set' : arg
+      end
+
+      sig { returns(String) }
+      def argument
+        @ref.arg || ''
+      end
+    end
+  end
+end

data/lib/rush/expansion/parameter_forms.rb

@@ -0,0 +1,22 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Registry of ${} operator forms keyed by the operator character. Each form
+    # is given a ParameterExpander and returns quote-aware field parts. The ':'
+    # variants treat a null value like an unset one (ParameterExpander#unset_or_null?).
+    module Parameter
+      # '-' use default · '=' assign default · '?' error if unset · '+' use alternative
+      # The #: types each lambda's parameter: Steep does not propagate a frozen
+      # hash's declared value type into bare `->(param)` literals (it would for an
+      # un-frozen literal), so the param stays untyped without the annotation.
+      FORMS = {
+        '-' => ->(param) { param.unset_or_null? ? param.arg_parts : param.value_parts }, #: ^(ParameterExpander) -> Array[FieldPart]
+        '=' => ->(param) { param.unset_or_null? ? param.assign_parts : param.value_parts }, #: ^(ParameterExpander) -> Array[FieldPart]
+        '?' => ->(param) { param.unset_or_null? ? param.raise_unset : param.value_parts }, #: ^(ParameterExpander) -> Array[FieldPart]
+        '+' => ->(param) { param.unset_or_null? ? param.empty_parts : param.arg_parts } #: ^(ParameterExpander) -> Array[FieldPart]
+      }.freeze
+    end
+  end
+end

data/lib/rush/expansion/pattern_removal.rb

@@ -0,0 +1,63 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    # Implements ${p#pat} ${p##pat} ${p%pat} ${p%%pat}: remove from the value the
+    # smallest (#/%) or largest (##/%%) prefix (#) or suffix (%) that matches the
+    # glob pattern, leaving the value unchanged when nothing matches.
+    class PatternRemoval
+      extend T::Sig
+
+      sig { params(executor: Executor, op: String, value: String, pattern: String).void }
+      def initialize(executor, op, value, pattern)
+        @executor = executor
+        @op = op
+        @value = value
+        @pattern = pattern
+      end
+
+      sig { returns(String) }
+      def call
+        @op.start_with?('#') ? strip_prefix : strip_suffix
+      end
+
+      private
+
+      sig { returns(String) }
+      def strip_prefix
+        hit = order(prefixes).find { |part| match?(part) }
+        hit ? @value.delete_prefix(hit) : @value
+      end
+
+      sig { returns(String) }
+      def strip_suffix
+        hit = order(suffixes).find { |part| match?(part) }
+        hit ? @value.delete_suffix(hit) : @value
+      end
+
+      sig { returns(T::Array[String]) }
+      def prefixes
+        current = +''
+        @value.each_char.with_object(['']) { |char, result| result << (current += char) }
+      end
+
+      sig { returns(T::Array[String]) }
+      def suffixes
+        current = +''
+        @value.each_char.reverse_each.with_object(['']) { |char, result| result << (current = char + current) }
+      end
+
+      sig { params(list: T::Array[String]).returns(T::Array[String]) }
+      def order(list)
+        @op.length == 2 ? list.reverse : list
+      end
+
+      sig { params(part: String).returns(T::Boolean) }
+      def match?(part)
+        locale = @executor.state.variables.locale_settings
+        @executor.system.fnmatch?(@pattern, part, locale: locale)
+      end
+    end
+  end
+end