rush-shell 0.0.2

data/lib/rush/exit_trap.rb

@@ -0,0 +1,109 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Owns the one-shot EXIT-trap lifecycle, terminating-status context and fatal
+  # error boundary. Ordinary delivered traps use TrapRunner's recoverable policy;
+  # EXIT runs at shell teardown and therefore converts fatal shell errors to 2.
+  class ExitTrap
+    extend T::Sig
+
+    # Trap source paired with the shell status being terminated.
+    Execution = Data.define(:source, :code)
+
+    sig { params(executor: Executor).void }
+    def initialize(executor)
+      @executor = executor
+      @state = executor.state
+      @exiting = T.let(nil, T.nilable(Integer))
+      @fired = false
+    end
+
+    sig { params(code: Integer).returns(Integer) }
+    def run(code)
+      action = claim_action
+      return code unless action
+
+      @state.record_status(Status.new(code))
+      fire(Execution.new(action, code))
+    end
+
+    sig { returns(Integer) }
+    def status
+      @exiting || @state.last_status.exitstatus
+    end
+
+    private
+
+    sig { returns(T.nilable(String)) }
+    def claim_action
+      return if @fired
+
+      @fired = true
+      @state.traps.action(Signals::EXIT)
+    end
+
+    sig { params(execution: Execution).returns(Integer) }
+    def fire(execution)
+      exit_result(execution)
+    rescue Error => e
+      raise unless decision(e) == :abort2
+
+      abort(e)
+    end
+
+    sig { params(execution: Execution).returns(Integer) }
+    def exit_result(execution)
+      control_result(execution)
+    rescue Error => e
+      return e.code if decision(e) == :override_code && e.is_a?(ExitSignal)
+
+      raise
+    end
+
+    sig { params(execution: Execution).returns(Integer) }
+    def control_result(execution)
+      run_execution(execution)
+    rescue Error => e
+      return execution.code if decision(e) == :preserve_code
+
+      raise
+    end
+
+    sig { params(execution: Execution).returns(Integer) }
+    def run_execution(execution)
+      source, code = execution.deconstruct
+      with_status(code) { evaluate(source) }
+      code
+    end
+
+    sig { params(error: Error).returns(Symbol) }
+    def decision(error)
+      ErrorPolicy.decision(:exit_trap, error)
+    end
+
+    sig { params(error: Error).returns(Integer) }
+    def abort(error)
+      @executor.system.stderr.puts("rush: #{error.message}")
+      @state.record_status(Status.new(2))
+      2
+    end
+
+    sig do
+      type_parameters(:U)
+        .params(code: Integer, blk: T.proc.returns(T.type_parameter(:U)))
+        .returns(T.type_parameter(:U))
+    end
+    def with_status(code, &blk)
+      @exiting = code
+      yield
+    ensure
+      @exiting = nil
+    end
+
+    sig { params(action: String).void }
+    def evaluate(action)
+      @executor.run(Parser.new(Lexer.new(action, aliases: @state.aliases)).parse)
+    end
+  end
+end

data/lib/rush/expansion/arithmetic/evaluator.rb

@@ -0,0 +1,43 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    module Arithmetic
+      # Evaluates an already parameter-expanded arithmetic string: tokenize,
+      # parse, walk the AST. A bare name resolves to its shell value parsed as an
+      # integer constant (unset or blank is 0); a non-numeric value is an error,
+      # as in dash. Recursion into a value as an *expression* is not done.
+      class Evaluator
+        extend T::Sig
+
+        sig { params(executor: Executor).void }
+        def initialize(executor)
+          @executor = executor
+        end
+
+        sig { params(source: String).returns(Integer) }
+        def evaluate(source)
+          Parser.new(Tokenizer.new(source).tokens).parse.result(self)
+        end
+
+        sig { params(name: String).returns(Integer) }
+        def resolve(name)
+          value = @executor.state.variables.get(name) || ''
+          return 0 if value.strip.empty?
+
+          Number.parse(value)
+        end
+
+        # `name op= value`: for a compound operator, combine with the current
+        # value first (`+=` -> `+`); store the wrapped result and return it.
+        sig { params(name: String, op: String, value: Integer).returns(Integer) }
+        def assign(name, op, value)
+          result = op == '=' ? value : Number.binary(op.chop, resolve(name), value)
+          @executor.state.variables.assign(name, result.to_s)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/rush/expansion/arithmetic/nodes.rb

@@ -0,0 +1,180 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    module Arithmetic
+      # The arithmetic AST. Each node computes against an Evaluator (`ctx`), which
+      # resolves variable names. And/Or and the conditional short-circuit so a
+      # branch that is not taken never runs (matching dash, where `0 && 1/0` is 0).
+      #
+      # The node payloads are ordinary typed Ruby state rather than generated
+      # reader methods: both Steep (via RBS) and Sorbet (via inline sigs) can see
+      # the operator/name/child invariants carried through parser and evaluator.
+      Node = T.type_alias { T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign) }
+
+      # A literal integer.
+      class Num
+        extend T::Sig
+
+        sig { returns(Integer) }
+        attr_reader :value
+
+        sig { params(value: Integer).void }
+        def initialize(value)
+          @value = value
+        end
+
+        sig { params(_ctx: Evaluator).returns(Integer) }
+        def result(_ctx)
+          value
+        end
+      end
+
+      # A variable reference; resolves its name through the evaluator.
+      class Var
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :name
+
+        sig { params(name: String).void }
+        def initialize(name)
+          @name = name
+        end
+
+        sig { params(ctx: Evaluator).returns(Integer) }
+        def result(ctx)
+          ctx.resolve(name)
+        end
+      end
+
+      # A unary operation (+ - ! ~) on one operand.
+      class Unary
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :op
+
+        sig { returns(Node) }
+        attr_reader :operand
+
+        sig { params(op: String, operand: Node).void }
+        def initialize(op, operand)
+          @op = op
+          @operand = operand
+        end
+
+        sig { params(ctx: Evaluator).returns(Integer) }
+        def result(ctx)
+          Number.unary(op, operand.result(ctx))
+        end
+      end
+
+      # A binary arithmetic / bitwise / comparison operation on two operands.
+      class Binary
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :op
+
+        sig { returns(Node) }
+        attr_reader :left, :right
+
+        sig { params(op: String, left: Node, right: Node).void }
+        def initialize(op, left, right)
+          @op = op
+          @left = left
+          @right = right
+        end
+
+        sig { params(ctx: Evaluator).returns(Integer) }
+        def result(ctx)
+          Number.binary(op, left.result(ctx), right.result(ctx))
+        end
+      end
+
+      # Logical &&: short-circuits, so the right operand runs only when the left is non-zero.
+      class And
+        extend T::Sig
+
+        sig { returns(Node) }
+        attr_reader :left, :right
+
+        sig { params(left: Node, right: Node).void }
+        def initialize(left, right)
+          @left = left
+          @right = right
+        end
+
+        sig { params(ctx: Evaluator).returns(Integer) }
+        def result(ctx)
+          left.result(ctx).zero? ? 0 : Number.bool(!right.result(ctx).zero?)
+        end
+      end
+
+      # Logical ||: short-circuits, so the right operand runs only when the left is zero.
+      class Or
+        extend T::Sig
+
+        sig { returns(Node) }
+        attr_reader :left, :right
+
+        sig { params(left: Node, right: Node).void }
+        def initialize(left, right)
+          @left = left
+          @right = right
+        end
+
+        sig { params(ctx: Evaluator).returns(Integer) }
+        def result(ctx)
+          left.result(ctx).zero? ? Number.bool(!right.result(ctx).zero?) : 1
+        end
+      end
+
+      # The ?: conditional: only the taken branch is evaluated.
+      class Cond
+        extend T::Sig
+
+        sig { returns(Node) }
+        attr_reader :test, :truthy, :falsy
+
+        sig { params(test: Node, truthy: Node, falsy: Node).void }
+        def initialize(test, truthy, falsy)
+          @test = test
+          @truthy = truthy
+          @falsy = falsy
+        end
+
+        sig { params(ctx: Evaluator).returns(Integer) }
+        def result(ctx)
+          test.result(ctx).zero? ? falsy.result(ctx) : truthy.result(ctx)
+        end
+      end
+
+      # The right-hand side is evaluated before the target is read, so a nested
+      # assignment in the rhs (e.g. `a += a += 1`) takes effect first.
+      class Assign
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :name, :op
+
+        sig { returns(Node) }
+        attr_reader :rhs
+
+        sig { params(name: String, op: String, rhs: Node).void }
+        def initialize(name, op, rhs)
+          @name = name
+          @op = op
+          @rhs = rhs
+        end
+
+        sig { params(ctx: Evaluator).returns(Integer) }
+        def result(ctx)
+          ctx.assign(name, op, rhs.result(ctx))
+        end
+      end
+    end
+  end
+end

data/lib/rush/expansion/arithmetic/number.rb

@@ -0,0 +1,104 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    module Arithmetic
+      # Pure 64-bit integer arithmetic for $(( )): two's-complement wrapping (so
+      # overflow matches dash), C-style truncated-toward-zero division/modulo,
+      # and the unary/binary operator tables the evaluator dispatches through.
+      # Comparison and logical results are 1 or 0. Never uses Kernel#eval.
+      module Number
+        extend T::Sig
+
+        module_function
+
+        LIMIT = 1 << 63
+
+        # Parse an integer constant (decimal, 0-octal or 0x-hex, optional sign and
+        # surrounding blanks), as both literals and variable values are read. The
+        # raising Integer() (not the exception:false form) lets the failure path
+        # translate to an ExpansionError; it also types cleanly under both checkers
+        # (Sorbet's RBI mistypes Integer(exception: false) as non-nil). Kernel.* so
+        # the bare Kernel calls resolve in this module_function module under Sorbet.
+        sig { params(text: String).returns(Integer) }
+        def parse(text)
+          Kernel.Integer(text)
+        rescue ArgumentError
+          Kernel.raise(ExpansionError, "arithmetic: invalid number #{text.inspect}")
+        end
+
+        # op is String here, the literal operator set ("+"|"-"|"!"|"~") in the RBS
+        # sig: Sorbet has no string-literal types, so String is the strongest it can
+        # say. Steep reaches the union because Parser#unary narrows the token via the
+        # typed UNARY table (Array[unary_op]) — a materialised drift, see number.rbs.
+        sig { params(op: String, value: Integer).returns(Integer) }
+        def unary(op, value)
+          wrap(UNARY.fetch(op).call(value))
+        end
+
+        sig { params(op: String, left: Integer, right: Integer).returns(Integer) }
+        def binary(op, left, right)
+          wrap(BINARY.fetch(op).call(left, right))
+        end
+
+        sig { params(num: Integer).returns(Integer) }
+        def wrap(num)
+          ((num + LIMIT) % (LIMIT << 1)) - LIMIT
+        end
+
+        sig { params(flag: T::Boolean).returns(Integer) }
+        def bool(flag)
+          flag ? 1 : 0
+        end
+
+        sig { params(left: Integer, right: Integer).returns(Integer) }
+        def divide(left, right)
+          Kernel.raise(ExpansionError, 'arithmetic: division by zero') if right.zero?
+
+          magnitude = left.abs / right.abs
+          left.negative? == right.negative? ? magnitude : -magnitude
+        end
+
+        sig { params(left: Integer, right: Integer).returns(Integer) }
+        def modulo(left, right)
+          left - (divide(left, right) * right)
+        end
+
+        # The #: comments type each lambda for Steep; the T.let around the whole
+        # table gives Sorbet the same proc shape without hiding the lambda from
+        # Steep's comment parser.
+        UNARY_PROC = T.type_alias { T.proc.params(value: Integer).returns(Integer) }
+        BINARY_PROC = T.type_alias { T.proc.params(left: Integer, right: Integer).returns(Integer) }
+
+        UNARY = T.let({
+          '+' => ->(value) { T.let(value, Integer) }, #: ^(Integer) -> Integer
+          '-' => ->(value) { -T.let(value, Integer) }, #: ^(Integer) -> Integer
+          '!' => ->(value) { bool(T.let(value, Integer).zero?) }, #: ^(Integer) -> Integer
+          '~' => ->(value) { ~T.let(value, Integer) } #: ^(Integer) -> Integer
+        }.freeze, T::Hash[String, UNARY_PROC])
+
+        BINARY = T.let({
+          '+' => ->(left, right) { T.let(left, Integer) + T.let(right, Integer) }, #: ^(Integer, Integer) -> Integer
+          '-' => ->(left, right) { T.let(left, Integer) - T.let(right, Integer) }, #: ^(Integer, Integer) -> Integer
+          '*' => ->(left, right) { T.let(left, Integer) * T.let(right, Integer) }, #: ^(Integer, Integer) -> Integer
+          '/' => ->(left, right) { divide(T.let(left, Integer), T.let(right, Integer)) }, #: ^(Integer, Integer) -> Integer
+          '%' => ->(left, right) { modulo(T.let(left, Integer), T.let(right, Integer)) }, #: ^(Integer, Integer) -> Integer
+          # Shift counts are masked to 6 bits, matching x86-64 (and so dash) for
+          # the out-of-range/negative counts that C leaves undefined.
+          '<<' => ->(left, right) { T.let(left, Integer) << (T.let(right, Integer) & 63) }, #: ^(Integer, Integer) -> Integer
+          '>>' => ->(left, right) { T.let(left, Integer) >> (T.let(right, Integer) & 63) }, #: ^(Integer, Integer) -> Integer
+          '&' => ->(left, right) { T.let(left, Integer) & T.let(right, Integer) }, #: ^(Integer, Integer) -> Integer
+          '|' => ->(left, right) { T.let(left, Integer) | T.let(right, Integer) }, #: ^(Integer, Integer) -> Integer
+          '^' => ->(left, right) { T.let(left, Integer) ^ T.let(right, Integer) }, #: ^(Integer, Integer) -> Integer
+          '<' => ->(left, right) { bool(T.let(left, Integer) < T.let(right, Integer)) }, #: ^(Integer, Integer) -> Integer
+          '<=' => ->(left, right) { bool(T.let(left, Integer) <= T.let(right, Integer)) }, #: ^(Integer, Integer) -> Integer
+          '>' => ->(left, right) { bool(T.let(left, Integer) > T.let(right, Integer)) }, #: ^(Integer, Integer) -> Integer
+          '>=' => ->(left, right) { bool(T.let(left, Integer) >= T.let(right, Integer)) }, #: ^(Integer, Integer) -> Integer
+          '==' => ->(left, right) { bool(T.let(left, Integer) == T.let(right, Integer)) }, #: ^(Integer, Integer) -> Integer
+          '!=' => ->(left, right) { bool(T.let(left, Integer) != T.let(right, Integer)) } #: ^(Integer, Integer) -> Integer
+        }.freeze, T::Hash[String, BINARY_PROC])
+      end
+    end
+  end
+end

data/lib/rush/expansion/arithmetic/parser.rb

@@ -0,0 +1,155 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Expansion
+    module Arithmetic
+      # A Pratt (precedence-climbing) parser turning the tokens into the AST.
+      # Binary precedence is table-driven; the conditional operator (?:) binds
+      # loosest and is right-associative. Malformed input or leftover tokens
+      # raise a syntax error (matching dash's "expecting primary"/"expecting EOF").
+      class Parser
+        extend T::Sig
+
+        PRECEDENCE = {
+          '||' => 1, '&&' => 2, '|' => 3, '^' => 4, '&' => 5,
+          '==' => 6, '!=' => 6, '<' => 7, '<=' => 7, '>' => 7, '>=' => 7,
+          '<<' => 8, '>>' => 8, '+' => 9, '-' => 9, '*' => 10, '/' => 10, '%' => 10
+        }.freeze
+        UNARY = %w[+ - ! ~].freeze
+        ASSIGN = ['=', '+=', '-=', '*=', '/=', '%=', '<<=', '>>=', '&=', '^=', '|='].freeze
+
+        sig { params(tokens: T::Array[[Symbol, String]]).void }
+        def initialize(tokens)
+          @tokens = tokens
+          @pos = 0
+        end
+
+        sig { returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign)) }
+        def parse
+          node = assignment
+          oops unless @pos == @tokens.size
+          node
+        end
+
+        private
+
+        # Assignment binds loosest and is right-associative; its target must be a
+        # bare name (an lvalue), so e.g. `5 = 3` is a syntax error.
+        sig { returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign)) }
+        def assignment
+          left = conditional
+          return left unless ASSIGN.include?(peek)
+
+          oops unless left.is_a?(Var)
+          Assign.new(left.name, advance, assignment)
+        end
+
+        sig { returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign)) }
+        def conditional
+          test = binary(1)
+          return test unless accept?('?')
+
+          branch = assignment
+          expect(':')
+          Cond.new(test, branch, conditional)
+        end
+
+        sig { params(min: Integer).returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign)) }
+        def binary(min)
+          left = unary
+          left = fold(left) while (tok = peek) && (power = PRECEDENCE.fetch(tok, nil)) && power >= min
+          left
+        end
+
+        sig do
+          params(left: T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign))
+            .returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign))
+        end
+        def fold(left)
+          op = advance
+          combine(op, left, binary(PRECEDENCE.fetch(op) + 1))
+        end
+
+        sig do
+          params(op: String,
+                 left: T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign),
+                 right: T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign))
+            .returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign))
+        end
+        def combine(op, left, right)
+          return And.new(left, right) if op == '&&'
+          return Or.new(left, right) if op == '||'
+
+          Binary.new(op, left, right)
+        end
+
+        sig { returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign)) }
+        def unary
+          # `find` (not `include?`) hands back the matching UNARY element, so under
+          # Steep — where UNARY is Array[unary_op] — `op` carries the literal
+          # operator type into Unary.new instead of a bare scanned String. This is
+          # the narrowing point that makes the RBS literal union reachable; Sorbet,
+          # with no string-literal types, still sees String. See docs/journal.md.
+          token = peek
+          op = UNARY.find { |candidate| candidate == token }
+          return primary unless op
+
+          advance
+          Unary.new(op, unary)
+        end
+
+        sig { returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign)) }
+        def primary
+          return grouped if accept?('(')
+
+          kind, text = take
+          return Num.new(Number.parse(text)) if kind == :num
+
+          kind == :name ? Var.new(text) : oops
+        end
+
+        sig { returns(T.any(Num, Var, Unary, Binary, And, Or, Cond, Assign)) }
+        def grouped
+          node = assignment
+          expect(')')
+          node
+        end
+
+        sig { returns(T.nilable(String)) }
+        def peek
+          @tokens[@pos]&.last
+        end
+
+        sig { returns(String) }
+        def advance
+          take.last
+        end
+
+        sig { returns([Symbol, String]) }
+        def take
+          oops if @pos >= @tokens.size
+          @tokens.fetch(@pos).tap { @pos += 1 }
+        end
+
+        sig { params(token: String).returns(T::Boolean) }
+        def accept?(token)
+          return false unless peek == token
+
+          @pos += 1
+          true
+        end
+
+        sig { params(token: String).void }
+        def expect(token)
+          accept?(token) || oops
+        end
+
+        sig { returns(T.noreturn) }
+        def oops
+          raise(ExpansionError, 'arithmetic: syntax error')
+        end
+      end
+    end
+  end
+end

data/lib/rush/expansion/arithmetic/tokenizer.rb

@@ -0,0 +1,56 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  module Expansion
+    module Arithmetic
+      # Splits an arithmetic expression into [kind, text] tokens (:num, :name,
+      # :op), skipping blanks. Operators are listed longest-first so multi-byte
+      # ones win over their prefixes; any other leftover character is an error.
+      class Tokenizer
+        extend T::Sig
+
+        OPERATORS = [
+          '<<=', '>>=',
+          '<<', '>>', '<=', '>=', '==', '!=', '&&', '||', '+=', '-=', '*=', '/=', '%=', '&=', '^=', '|=',
+          '+', '-', '*', '/', '%', '<', '>', '&', '^', '|', '~', '!', '(', ')', '?', ':', '='
+        ].freeze
+        OPERATOR = Regexp.union(OPERATORS)
+        NUMBER = /0[xX][0-9a-fA-F]+|\d+/
+        NAME = /[A-Za-z_]\w*/
+        TOKENS = { num: NUMBER, name: NAME, op: OPERATOR }.freeze
+
+        sig { params(source: String).void }
+        def initialize(source)
+          @scanner = StringScanner.new(source)
+        end
+
+        sig { returns(T::Array[[Symbol, String]]) }
+        def tokens
+          result = [] #: Array[[Symbol, String]]
+          result << next_token while at_token?
+          result
+        end
+
+        private
+
+        sig { returns(T::Boolean) }
+        def at_token?
+          @scanner.skip(/\s+/)
+          !@scanner.eos?
+        end
+
+        sig { returns([Symbol, String]) }
+        def next_token
+          TOKENS.lazy
+                .map { |kind, pattern| [kind, @scanner.scan(pattern)] }
+                .find(
+                  -> { raise ExpansionError, "arithmetic: unexpected #{@scanner.rest.inspect}" }
+                ) { |_kind, found| found }
+        end
+      end
+    end
+  end
+end

data/lib/rush/expansion/arithmetic_expander.rb

@@ -0,0 +1,38 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  module Expansion
+    # Expands $(( ... )): first apply parameter expansion and command
+    # substitution to the raw text (POSIX treats it like a double-quoted word),
+    # then evaluate the result as an integer arithmetic expression.
+    class ArithmeticExpander
+      extend T::Sig
+
+      sig { params(executor: Executor, source: String).void }
+      def initialize(executor, source)
+        @executor = executor
+        @source = source
+      end
+
+      sig { returns(String) }
+      def expand
+        Arithmetic::Evaluator.new(@executor).evaluate(expanded).to_s
+      end
+
+      private
+
+      sig { returns(String) }
+      def expanded
+        @executor.expander.expand_value(scanned, tilde: :none)
+      end
+
+      sig { returns(AST::Word) }
+      def scanned
+        Lexer::WordScanner.entire(@source)
+      end
+    end
+  end
+end