rush-shell 0.0.2

data/lib/rush/command_lookup.rb

@@ -0,0 +1,228 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Resolves a command name for `type` and `command -v`: a reserved word, a
+  # function, a special or regular builtin, or an executable file found by
+  # searching PATH (or used directly when the name contains a slash). #find runs
+  # an ordered list of resolvers and returns the first Match (Unknown if none).
+  # An explicit `path:` replaces $PATH for the file search — `command -p` passes
+  # the system default PATH through it.
+  class CommandLookup
+    extend T::Sig
+
+    KEYWORDS = %w[! { } case do done elif else esac fi for if in then until while].freeze
+    RESOLVERS = %i[as_keyword as_alias as_function as_special as_builtin as_file].freeze
+
+    # A resolved lookup result: it is "known", and subclasses render the line
+    # `type` (#describe) and `command -v` (#terse) print. Only an executable
+    # caches its own location; the others leave the cache untouched.
+    class Match
+      extend T::Sig
+
+      # name is nilable: `command -v` with no operand resolves the nil name, which
+      # flows through #find to Unknown.new(nil) (the Sorbet sig set tolerates this;
+      # the RBS keeps the narrower String — the two checkers are independent).
+      sig { params(name: T.nilable(String), detail: T.nilable(String)).void }
+      def initialize(name, detail = nil)
+        @name = name
+        @detail = detail
+      end
+
+      sig { returns(T::Boolean) }
+      def known?
+        true
+      end
+
+      sig { params(_cache: T::Hash[T.untyped, T.untyped]).void }
+      def cache_into(_cache)
+        nil
+      end
+
+      # describe/terse are the Match protocol #find's result is used through; the
+      # subclasses provide them (the base is never instantiated, like AST::Node).
+      sig { returns(T.nilable(String)) }
+      def describe
+        raise NotImplementedError
+      end
+
+      sig { returns(T.nilable(String)) }
+      def terse
+        raise NotImplementedError
+      end
+
+      private
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :name
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :detail
+    end
+
+    # An unresolved name: not known, and nothing to describe.
+    class Unknown < Match
+      extend T::Sig
+
+      sig { returns(T::Boolean) }
+      def known?
+        false
+      end
+
+      sig { returns(NilClass) }
+      def describe
+        nil
+      end
+    end
+
+    # A keyword / function / special / regular builtin, named by a fixed label.
+    class Labelled < Match
+      extend T::Sig
+
+      sig { returns(String) }
+      def describe
+        "#{name} is #{detail}"
+      end
+
+      sig { returns(String) }
+      def terse
+        T.must(name)
+      end
+    end
+
+    # A shell alias; `command -v` prints its definition.
+    class Aliased < Match
+      extend T::Sig
+
+      sig { returns(String) }
+      def describe
+        "#{name} is an alias for #{detail}"
+      end
+
+      sig { returns(String) }
+      def terse
+        "alias '#{"#{name}=#{detail}".gsub("'", %q('"'"'))}'"
+      end
+    end
+
+    # An external executable found on PATH (or used directly via a slash path).
+    class Executable < Match
+      extend T::Sig
+
+      sig { returns(String) }
+      def describe
+        "#{name} is #{detail}"
+      end
+
+      sig { returns(T.nilable(String)) }
+      def terse
+        detail
+      end
+
+      sig { params(cache: T::Hash[T.untyped, T.untyped]).void }
+      def cache_into(cache)
+        cache[name] = detail
+      end
+    end
+
+    sig { params(executor: Executor, path: T.nilable(String)).void }
+    def initialize(executor, path: nil)
+      @executor = executor
+      @path = path
+    end
+
+    # The Match for a name (Unknown if it resolves to nothing). An alias outranks
+    # a function/builtin but not a reserved word; a PATH/slash file is the last
+    # resort.
+    sig { params(name: T.nilable(String)).returns(Match) }
+    def find(name)
+      RESOLVERS.lazy.filter_map { |resolver| send(resolver, name) }.first || Unknown.new(name)
+    end
+
+    # The `type`/`command -V` description line for a name, or nil if unknown.
+    sig { params(name: T.nilable(String)).returns(T.nilable(String)) }
+    def describe(name)
+      find(name).describe
+    end
+
+    # The executable file for a name on the search path (the name itself when
+    # it contains a slash), or nil. Public as well as feeding #find's file
+    # resolver: `command -p` resolves an external through it without the
+    # keyword/function/builtin layers, which that builtin handles separately.
+    sig { params(name: String).returns(T.nilable(String)) }
+    def executable_path(name)
+      return name if name.include?('/') && executable?(name)
+      return if name.include?('/')
+
+      dirs.map { |dir| join(dir, name) }.find { |candidate| executable?(candidate) }
+    end
+
+    private
+
+    sig { params(name: T.nilable(String)).returns(T.nilable(Match)) }
+    def as_keyword(name)
+      name && KEYWORDS.include?(name) ? Labelled.new(name, 'a shell keyword') : nil
+    end
+
+    sig { params(name: T.nilable(String)).returns(T.nilable(Match)) }
+    def as_alias(name)
+      value = name && aliases.value(name)
+      value ? Aliased.new(name, value) : nil
+    end
+
+    sig { params(name: T.nilable(String)).returns(T.nilable(Match)) }
+    def as_function(name)
+      name && functions.key?(name) ? Labelled.new(name, 'a shell function') : nil
+    end
+
+    sig { params(name: T.nilable(String)).returns(T.nilable(Match)) }
+    def as_special(name)
+      return unless name && CommandResolution.special_builtin?(name, @executor.builtins)
+
+      Labelled.new(name, 'a special shell builtin')
+    end
+
+    sig { params(name: T.nilable(String)).returns(T.nilable(Match)) }
+    def as_builtin(name)
+      name && @executor.builtins.key?(name) ? Labelled.new(name, 'a shell builtin') : nil
+    end
+
+    sig { params(name: T.nilable(String)).returns(T.nilable(Match)) }
+    def as_file(name)
+      return unless name
+
+      path = executable_path(name)
+      path ? Executable.new(name, path) : nil
+    end
+
+    sig { returns(AliasTable) }
+    def aliases
+      @executor.state.aliases
+    end
+
+    sig { returns(FunctionTable) }
+    def functions
+      @executor.state.functions
+    end
+
+    sig { params(dir: String, name: String).returns(String) }
+    def join(dir, name)
+      dir.empty? ? name : "#{dir}/#{name}"
+    end
+
+    sig { params(path: String).returns(T::Boolean) }
+    def executable?(path)
+      @executor.system.file?(path) && @executor.system.executable?(path)
+    end
+
+    sig { returns(T::Array[String]) }
+    def dirs
+      search_path.split(':', -1)
+    end
+
+    sig { returns(String) }
+    def search_path
+      @path || @executor.state.variables.get('PATH') || ''
+    end
+  end
+end

data/lib/rush/command_resolution.rb

@@ -0,0 +1,115 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Classifies a command for ordinary execution and carries the policies that
+  # follow from that classification. This deliberately does not resolve aliases,
+  # keywords or PATH: `type`/`command -v`, `command`, and execution have distinct
+  # POSIX search modes and share only builtin metadata/vocabulary.
+  class CommandResolution
+    extend T::Sig
+
+    # Ordinary execution's four mutually exclusive target kinds.
+    class Kind < T::Enum
+      enums do
+        SPECIAL_BUILTIN = new('special_builtin')
+        FUNCTION = new('function')
+        BUILTIN = new('builtin')
+        EXTERNAL = new('external')
+      end
+    end
+
+    # How prefix assignments live for the selected target kind.
+    class AssignmentLifetime < T::Enum
+      enums do
+        PERSISTENT = new('persistent')
+        TEMPORARY = new('temporary')
+        ENVIRONMENT = new('environment')
+      end
+    end
+
+    # Whether redirect setup aborts the shell or fails only this command.
+    class RedirectFailure < T::Enum
+      enums do
+        FATAL = new('fatal')
+        ORDINARY = new('ordinary')
+      end
+    end
+
+    Policy = T.type_alias { [AssignmentLifetime, RedirectFailure] }
+    SPECIAL_BUILTINS = %w[: . break continue eval exec exit export readonly return set shift times trap unset].freeze
+    POLICIES = T.let(
+      {
+        Kind::SPECIAL_BUILTIN => [AssignmentLifetime::PERSISTENT, RedirectFailure::FATAL].freeze,
+        Kind::FUNCTION => [AssignmentLifetime::TEMPORARY, RedirectFailure::ORDINARY].freeze,
+        Kind::BUILTIN => [AssignmentLifetime::TEMPORARY, RedirectFailure::ORDINARY].freeze,
+        Kind::EXTERNAL => [AssignmentLifetime::ENVIRONMENT, RedirectFailure::ORDINARY].freeze
+      }.freeze,
+      T::Hash[Kind, Policy]
+    )
+
+    sig { returns(Kind) }
+    attr_reader :kind
+
+    sig { returns(AssignmentLifetime) }
+    attr_reader :assignment_lifetime
+
+    sig { returns(RedirectFailure) }
+    attr_reader :redirect_failure
+
+    sig { params(kind: Kind).void }
+    def initialize(kind)
+      @kind = kind
+      @assignment_lifetime, @redirect_failure = POLICIES.fetch(kind)
+    end
+    private :initialize
+
+    sig do
+      params(name: String, functions: FunctionTable, builtins: Builtins::Registry).returns(CommandResolution)
+    end
+    def self.for_execution(name, functions, builtins)
+      new(execution_kind(name, functions, builtins))
+    end
+
+    sig { params(name: String, builtins: Builtins::Registry).returns(T::Boolean) }
+    def self.special_builtin?(name, builtins)
+      SPECIAL_BUILTINS.include?(name) && builtins.key?(name)
+    end
+
+    sig { returns(T::Boolean) }
+    def builtin?
+      [Kind::SPECIAL_BUILTIN, Kind::BUILTIN].include?(kind)
+    end
+
+    sig { returns(T::Boolean) }
+    def function?
+      kind == Kind::FUNCTION
+    end
+
+    sig { returns(T::Boolean) }
+    def persistent_assignments?
+      assignment_lifetime == AssignmentLifetime::PERSISTENT
+    end
+
+    sig { returns(T::Boolean) }
+    def temporary_assignments?
+      assignment_lifetime == AssignmentLifetime::TEMPORARY
+    end
+
+    sig { returns(T::Boolean) }
+    def fatal_redirect?
+      redirect_failure == RedirectFailure::FATAL
+    end
+
+    sig do
+      params(name: String, functions: FunctionTable, builtins: Builtins::Registry).returns(Kind)
+    end
+    private_class_method def self.execution_kind(name, functions, builtins)
+      return Kind::SPECIAL_BUILTIN if special_builtin?(name, builtins)
+      return Kind::FUNCTION if functions.key?(name)
+      return Kind::BUILTIN if builtins.key?(name)
+
+      Kind::EXTERNAL
+    end
+  end
+end

data/lib/rush/command_runner.rb

@@ -0,0 +1,152 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Runs a SimpleCommand: expand argv, classify it for ordinary execution,
+  # evaluate redirections into a per-command IoTable, then apply the resolution's
+  # assignment and redirect policies while dispatching the selected command kind.
+  class CommandRunner
+    extend T::Sig
+
+    sig { params(executor: Executor, command: AST::SimpleCommand, base_io: IoTable).void }
+    def initialize(executor, command, base_io = executor.io)
+      @executor = executor
+      @command = command
+      @base_io = base_io
+      @assignments = CommandAssignments.new(command.assignments, executor.expander)
+    end
+
+    sig { returns(Status) }
+    def call
+      @executor.reset_cmd_sub_status
+      argv = @executor.expander.expand(@command.words)
+      return run_bare if argv.empty?
+
+      trace(argv)
+      run_command(argv)
+    end
+
+    private
+
+    # POSIX 2.5.3: each xtrace line goes to stderr prefixed with the expanded
+    # PS4 (parameter expansion only — see Prompt). The standard repeats PS4's
+    # first character per level of indirection; rush's tracer has no nesting
+    # depth (and dash never repeats), so a single prefix is correct here.
+    sig { params(argv: T::Array[String]).void }
+    def trace(argv)
+      return unless @executor.state.options.on?(:xtrace)
+
+      @executor.io.get(2).puts("#{Prompt.new(@executor).trace}#{argv.join(' ')}")
+    end
+
+    # No command word: perform redirections then assignments (POSIX order), and
+    # take the status of the last command substitution either ran (Status.success
+    # when none did), as published via the executor's cmd-sub channel.
+    # with_redirects opens/truncates the targets for their side effects, then
+    # flushes+closes them after the assignments so a later command sees the data.
+    sig { returns(Status) }
+    def run_bare
+      @executor.redirect_scope.with_redirects(@command.redirects, @base_io) { |io| persist_assignments(io) }
+    end
+
+    sig { params(io: IoTable).returns(Status) }
+    def persist_assignments(io)
+      @executor.with_io(io) do
+        @assignments.persist_to(@executor.state.variables)
+        @executor.cmd_sub_status
+      end
+    end
+
+    # POSIX command search: special builtin, then function (so a function may
+    # override a regular builtin), then regular builtin, then PATH. A redirect
+    # error leaves a regular command unrun with status 2 (RedirectError reaches
+    # Executor#run), but on a special builtin it aborts the shell (POSIX 2.8.1),
+    # so it is re-raised as a fatal BuiltinError.
+    sig { params(argv: T::Array[String]).returns(Status) }
+    def run_command(argv)
+      resolution = CommandResolution.for_execution(argv.fetch(0), @executor.state.functions, @executor.builtins)
+      dispatch_with_redirects(resolution, argv)
+    end
+
+    sig { params(resolution: CommandResolution, argv: T::Array[String]).returns(Status) }
+    def dispatch_with_redirects(resolution, argv)
+      @executor.redirect_scope.with_redirects(@command.redirects, @base_io) { |io| dispatch(resolution, argv, io) }
+    rescue RedirectError => e
+      raise unless resolution.fatal_redirect?
+
+      raise BuiltinError, e.message
+    end
+
+    sig { params(resolution: CommandResolution, argv: T::Array[String], io: IoTable).returns(Status) }
+    def dispatch(resolution, argv, io)
+      environment = command_env(io)
+      apply_assignment_policy(resolution, argv, io, environment)
+    end
+
+    sig do
+      params(resolution: CommandResolution, argv: T::Array[String], io: IoTable,
+             environment: T::Hash[String, String]).returns(Status)
+    end
+    def apply_assignment_policy(resolution, argv, io, environment)
+      return persistent_dispatch(argv, io, environment) if resolution.persistent_assignments?
+      return temporary_dispatch(resolution, argv, io, environment) if resolution.temporary_assignments?
+
+      external(argv, io, environment)
+    end
+
+    sig { params(argv: T::Array[String], io: IoTable, environment: T::Hash[String, String]).returns(Status) }
+    def persistent_dispatch(argv, io, environment)
+      @assignments.persist_environment(environment, @executor.state.variables)
+      invoke_builtin(argv, io, environment)
+    end
+
+    sig do
+      params(resolution: CommandResolution, argv: T::Array[String], io: IoTable,
+             environment: T::Hash[String, String]).returns(Status)
+    end
+    def temporary_dispatch(resolution, argv, io, environment)
+      values = @assignments.temporary_environment(environment)
+      @executor.state.variables.with_temporary(values) { invoke_temporary(resolution, argv, io, environment) }
+    end
+
+    sig do
+      params(resolution: CommandResolution, argv: T::Array[String], io: IoTable,
+             environment: T::Hash[String, String]).returns(Status)
+    end
+    def invoke_temporary(resolution, argv, io, environment)
+      resolution.function? ? invoke_function(argv, io) : invoke_builtin(argv, io, environment)
+    end
+
+    sig { params(argv: T::Array[String], io: IoTable, environment: T::Hash[String, String]).returns(Status) }
+    def external(argv, io, environment)
+      @assignments.validate(@executor.state.variables)
+      External.new(@executor, argv, io, environment).call(@executor.job_control.job_text(@command))
+    end
+
+    sig { params(argv: T::Array[String], io: IoTable, environment: T::Hash[String, String]).returns(Status) }
+    # A builtin reading from or writing to a fd closed by n>&- raises EBADF; like
+    # dash, that fails the command (status 1) without killing the shell.
+    def invoke_builtin(argv, io, environment)
+      @executor.builtins.fetch(argv.fetch(0)).new(@executor, argv, io, environment).call
+    rescue Errno::EBADF
+      Status.new(1)
+    end
+
+    # A function runs in the current shell, not a subshell. The call's redirects
+    # (if any) bind the whole body and are torn down when it returns — even an
+    # `exec` inside is scoped to them, as dash does. With no redirects the body
+    # shares the shell's io table so an `exec` inside *persists*, so wrap in
+    # with_io only when a redirect actually layered a new table over the base.
+    sig { params(argv: T::Array[String], io: IoTable).returns(Status) }
+    def invoke_function(argv, io)
+      body = @executor.state.functions.fetch(argv.fetch(0))
+      run = -> { FunctionRunner.new(@executor, body, argv.drop(1)).call }
+      io.equal?(@executor.io) ? run.call : @executor.with_io(io, &run)
+    end
+
+    sig { params(io: IoTable).returns(T::Hash[String, String]) }
+    def command_env(io)
+      @executor.with_io(io) { @assignments.environment_for(@executor.state.variables) }
+    end
+  end
+end

data/lib/rush/command_text.rb

@@ -0,0 +1,140 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # Renders an AST back into dash's canonical job text — the command column
+  # of the jobs listing, fg's echoed line and bg's "[n] ..." (dash's cmdtxt,
+  # probed shape by shape off-tty): words re-quoted with double quotes when
+  # they carried quoting ($ escaped as \$), parameter expansions always
+  # braced (${T}, "${@}", ${T:-9} with the raw default), command
+  # substitutions and here-document bodies elided to $(...) and <<...,
+  # redirect fds explicit (1>/dev/null, 0<f), assignments dropped from a
+  # command that has words — an assignment-only command renders as `set`, a
+  # dash quirk kept for parity — group braces dropped, elif spelled as a
+  # nested else-if, a negated pipeline prefixed with a spaceless !, and the
+  # implicit for-loop list spelled out as in "${@}".
+  module CommandText
+    extend T::Sig
+
+    TABLE = T.let({
+      AST::List => :list, AST::AndOr => :and_or, AST::Pipeline => :pipeline,
+      AST::SimpleCommand => :simple, AST::Subshell => :subshell, AST::BraceGroup => :group,
+      AST::If => :if_node, AST::While => :while_node, AST::Until => :until_node,
+      AST::For => :for_node, AST::Case => :case_node, AST::FunctionDef => :function_def,
+      AST::Redirected => :redirected
+    }.freeze, T::Hash[T.untyped, Symbol])
+
+    sig { params(node: AST::Node).returns(String) }
+    def self.render(node)
+      method(TABLE.fetch(node.class)).call(node)
+    end
+
+    sig { params(node: AST::List).returns(String) }
+    def self.list(node)
+      node.entries.map { |entry| "#{render(entry.and_or)}#{entry.async ? ' &' : ';'}" }
+                  .join(' ').delete_suffix(';')
+    end
+
+    sig { params(node: AST::AndOr).returns(String) }
+    def self.and_or(node)
+      "#{render(node.left)} #{node.op == :and ? '&&' : '||'} #{render(node.right)}"
+    end
+
+    sig { params(node: AST::Pipeline).returns(String) }
+    def self.pipeline(node)
+      "#{'!' if node.negate}#{stages(node.commands)}"
+    end
+
+    # A pipeline's stages, also reachable for PipelineRunner's already-split
+    # command list (the adopted-job text of a stopped foreground pipeline).
+    sig { params(commands: T::Array[AST::Node]).returns(String) }
+    def self.stages(commands)
+      commands.map { |command| render(command) }.join(' | ')
+    end
+
+    sig { params(node: AST::SimpleCommand).returns(String) }
+    def self.simple(node)
+      words = node.words.map { |word| word(word) }
+      words = ['set'] if words.empty?
+      (words + node.redirects.map { |redirect| redirect(redirect) }).join(' ')
+    end
+
+    sig { params(node: AST::Subshell).returns(String) }
+    def self.subshell(node)
+      "(#{render(node.body)})"
+    end
+
+    sig { params(node: AST::BraceGroup).returns(String) }
+    def self.group(node)
+      render(node.body)
+    end
+
+    sig { params(node: AST::If).returns(String) }
+    def self.if_node(node)
+      tail = node.alternative ? " else #{render(T.must(node.alternative))};" : ''
+      "if #{render(node.condition)}; then #{render(node.consequent)};#{tail} fi"
+    end
+
+    sig { params(node: AST::While).returns(String) }
+    def self.while_node(node)
+      "while #{render(node.condition)}; do #{render(node.body)}; done"
+    end
+
+    sig { params(node: AST::Until).returns(String) }
+    def self.until_node(node)
+      "until #{render(node.condition)}; do #{render(node.body)}; done"
+    end
+
+    sig { params(node: AST::For).returns(String) }
+    def self.for_node(node)
+      list = node.words ? T.must(node.words).map { |word| word(word) }.join(' ') : '"${@}"'
+      "for #{node.name} in #{list}; do #{render(node.body)}; done"
+    end
+
+    sig { params(node: AST::Case).returns(String) }
+    def self.case_node(node)
+      items = node.items.map { |item| "#{word(item.patterns.fetch(0))}) #{render(item.body)};;" }
+      "case #{word(node.word)} in #{items.join(' ')} esac"
+    end
+
+    sig { params(node: AST::FunctionDef).returns(String) }
+    def self.function_def(node)
+      "#{node.name}() { #{render(node.body)}; }"
+    end
+
+    sig { params(node: AST::Redirected).returns(String) }
+    def self.redirected(node)
+      ([render(node.command)] + node.redirects.map { |redirect| redirect(redirect) }).join(' ')
+    end
+
+    # dash prints every fd explicitly (1>/dev/null, 0<f, 2>&1) and elides a
+    # here-document to <<... .
+    sig { params(redirect: AST::Redirect).returns(String) }
+    def self.redirect(redirect)
+      return '<<...' if redirect.kind == :heredoc
+
+      op, fd = T.must(OPERATORS[redirect.kind])
+      "#{redirect.io_number || fd}#{op}#{word(T.cast(redirect.target, AST::Word))}"
+    end
+
+    OPERATORS = T.let({
+      in: ['<', 0], out: ['>', 1], append: ['>>', 1], clobber: ['>|', 1],
+      readwrite: ['<>', 0], dup_out: ['>&', 1], dup_in: ['<&', 0]
+    }.freeze, T::Hash[Symbol, [String, Integer]])
+
+    # Consecutive quoted segments share one pair of double quotes (dash
+    # renders "x$T.y" as one quoted run); each segment canonicalises itself
+    # (WordSegment#canon).
+    sig { params(word: AST::Word).returns(String) }
+    def self.word(word)
+      runs = word.segments.chunk_while { |left, right| left.quoted == right.quoted }
+      runs.map { |run| run_text(run) }.join
+    end
+
+    sig { params(run: T::Array[AST::WordSegment[T.untyped]]).returns(String) }
+    def self.run_text(run)
+      body = run.map(&:canon).join
+      T.must(run.fetch(0)).quoted ? "\"#{body}\"" : body
+    end
+  end
+end