rush-shell 0.0.2

data/lib/rush/job_table/job.rb

@@ -0,0 +1,181 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class JobTable
+    # One job. Identity holds what never changes: the [n] number, the member
+    # pids (a pipeline's group leader first — fg/bg and group kills need them
+    # all), and the rendered command text — nil outside job control, exactly
+    # dash's model, where cmdtext is kept only for jobctl jobs and that
+    # absence IS the fg/bg "not created under job control" refusal.
+    # State is the Status of the last decisive wait: nothing while running, a
+    # stop-carrying Status while parked (^Z — re-waitable, answering
+    # 128+stopsig until fg/bg's SIGCONT), a final one once done; `changed`
+    # tracks whether the latest transition has been reported (the pre-prompt
+    # notification, or the jobs listing itself).
+    class Job
+      extend T::Sig
+
+      # The creation-time facts, bundled so the mutable state stays apart.
+      class Identity
+        extend T::Sig
+
+        sig { returns(Integer) }
+        attr_reader :number
+
+        sig { returns(T::Array[Integer]) }
+        attr_reader :members
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :text
+
+        sig { params(number: Integer, members: T::Array[Integer], text: T.nilable(String)).void }
+        def initialize(number, members, text)
+          @number = number
+          @members = members
+          @text = text
+        end
+      end
+
+      sig { returns(T::Boolean) }
+      attr_reader :changed
+
+      sig { params(number: Integer, pid: Integer, members: T::Array[Integer], text: T.nilable(String)).void }
+      extend Forwardable
+
+      def initialize(number, pid, members: [pid], text: nil)
+        @identity = T.let(Identity.new(number, members, text), Identity)
+        @result = T.let(nil, T.nilable(Status))
+        @changed = T.let(false, T::Boolean)
+        @inherited = T.let(false, T::Boolean)
+      end
+
+      def_delegators :@identity, :number, :members
+
+      sig { returns(Integer) }
+      def pid
+        members.fetch(0)
+      end
+
+      # The rendered command line ('' outside job control, where dash keeps
+      # no text either).
+      sig { returns(String) }
+      def text
+        @identity.text.to_s
+      end
+
+      # Created under monitor mode, so fg/bg may resume it (dash refuses
+      # "not created under job control" for the rest, whatever mflag says
+      # now — probed): the kept command text is the stamp.
+      sig { returns(T::Boolean) }
+      def controlled?
+        !!@identity.text
+      end
+
+      # A fork demotes the entry to a POSIX 2.12 display copy: the subshell
+      # environment duplicates the async-pid knowledge (jobs listing,
+      # jobs -p), but the process is no child of this environment — wait
+      # and %id resolution refuse it (dash-probed in real forked children).
+      sig { void }
+      def inherit
+        @inherited = true
+      end
+
+      sig { returns(T::Boolean) }
+      def inherited?
+        @inherited
+      end
+
+      # File a reaped wait result: a stop parks the job (still alive, still
+      # re-waitable), anything else settles it for good; answers the filed
+      # Status (never nil — JobTable#store leans on that).
+      sig { params(raw: Process::Status).returns(Status) }
+      def finish(raw)
+        @changed = true
+        @result = Status.of(raw)
+      end
+
+      sig { params(stopsig: Integer).void }
+      def stop(stopsig)
+        @changed = true
+        @result = Status.stopped(stopsig)
+      end
+
+      # fg/bg's SIGCONT: a stopped job runs again — its own announcement, no
+      # notification owed.
+      sig { void }
+      def resume
+        return unless stopped?
+
+        @result = nil
+        @changed = false
+      end
+
+      # The whole fg/bg resume move: mark the job running again and SIGCONT
+      # its process group (the leader pid is the group under job control); a
+      # group already gone is settled — the memory answers.
+      sig { params(system: SystemCalls).void }
+      def continue(system)
+        resume
+        system.kill('CONT', -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      # A state change was displayed (jobs listing or pre-prompt
+      # notification): nothing further to announce.
+      sig { void }
+      def reported
+        @changed = false
+      end
+
+      # One pre-prompt notification: print this job's change and settle the
+      # report — a finished entry leaves the table (dash's showjob + free).
+      sig { params(table: JobTable, out: T.untyped).void }
+      def report(table, out)
+        out.puts(JobReport.line(table, self))
+        reported
+        table.forget(self) if finished?
+      end
+
+      # Reap once: a settled job answers from memory (dash never frees an
+      # entry on wait), a stopped one answers 128+stopsig immediately and
+      # repeatably (dash-probed), and a running one blocks in the supplied
+      # wait — which may itself park the job. A fork-inherited display copy
+      # is never reapable: it answers nil, the callers' unknown-job path.
+      sig { params(blk: T.proc.returns(T.any(Process::Status, Status))).returns(T.nilable(Status)) }
+      def harvest(&blk)
+        return if inherited?
+        return status unless running?
+
+        result = yield
+        result.is_a?(Status) ? result : finish(result)
+      end
+
+      sig { returns(T::Boolean) }
+      def running?
+        !@result
+      end
+
+      sig { returns(T::Boolean) }
+      def stopped?
+        !!@result&.stopped?
+      end
+
+      sig { returns(T::Boolean) }
+      def finished?
+        !running? && !stopped?
+      end
+
+      sig { returns(T.nilable(Integer)) }
+      def stopsig
+        @result&.stopsig
+      end
+
+      sig { returns(Status) }
+      def status
+        T.must(@result)
+      end
+    end
+  end
+end

data/lib/rush/job_table.rb

@@ -0,0 +1,194 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  # The shell's asynchronous jobs, and the single owner of child reaping (the
+  # design risk epic rush-mv8 recorded): every synchronous wait routes through
+  # #await, so no two waits can steal each other's statuses. While no
+  # background job is running an await targets its pid directly; once an
+  # asynchronous list has launched, it reaps whichever child exits next and
+  # files foreign statuses — a background job's on its entry (where the wait
+  # builtin finds it), a sibling foreground child's in a stash its own await
+  # consults first. A reaped job's status stays remembered until the jobs
+  # builtin displays it (dash frees reported entries); forked child
+  # environments keep the entries only as unwaitable display copies
+  # (POSIX 2.12 — see #enter_subshell).
+  class JobTable
+    extend T::Sig
+
+    sig { params(system: SystemCalls).void }
+    def initialize(system)
+      @system = system
+      @jobs = T.let(
+        {}, #: Hash[Integer, Job]
+        T::Hash[Integer, Job]
+      )
+      @stash = T.let(
+        {}, #: Hash[Integer, Process::Status]
+        T::Hash[Integer, Process::Status]
+      )
+      @control = T.let(Control.new, Control)
+    end
+
+    # The durable job-control environment (root-shell bit, acquired
+    # terminal): JobControl's state, kept here because it lives and dies
+    # with the table — a forked child drops both together.
+    sig { returns(Control) }
+    attr_reader :control
+
+    # A background launch: the pid becomes job [n] — the lowest free number,
+    # as dash numbers slots. Fake fork ports return no child pid (mapped to
+    # 0); a real parent always records a positive one.
+    sig { params(pid: Integer, text: T.nilable(String)).void }
+    def record(pid, text: nil)
+      @jobs[pid] = Job.new(free_number, pid, text: text) if pid.positive?
+    end
+
+    # A foreground job a WUNTRACED wait handed back as stopped (^Z): it
+    # becomes a job-table entry — number, the group leader as its pid, every
+    # pipeline member listed — parked Stopped, where jobs/wait/kill/%ids
+    # find it (dash keeps its jobtab entry; rush creates one on the spot).
+    sig { params(pids: T::Array[Integer], stopsig: Integer, text: T.nilable(String)).void }
+    def adopt_stopped(pids, stopsig, text = nil)
+      leader = pids.fetch(0)
+      (@jobs[leader] ||= Job.new(free_number, leader, members: pids, text: text)).stop(stopsig) if leader.positive?
+    end
+
+    # Newest first: the jobs builtin's display order, and what makes the
+    # first entry the current job (+) and the second the previous one (-).
+    sig { returns(T::Array[Job]) }
+    def ordered
+      @jobs.values.reverse
+    end
+
+    sig { returns(T.nilable(Job)) }
+    def current
+      ordered.first
+    end
+
+    sig { returns(T.nilable(Job)) }
+    def previous
+      ordered.fetch(1, nil)
+    end
+
+    sig { params(number: Integer).returns(T.nilable(Job)) }
+    def numbered(number)
+      @jobs.each_value.find { |job| job.number == number }
+    end
+
+    # Blocking wait for a foreground child's status. ECHILD is a defensive
+    # guard: entries never outlive their environment (forked children clear
+    # the table), so a wait on a vanished child answers success rather than
+    # crashing.
+    sig { params(pid: Integer).returns(Status) }
+    def await(pid)
+      Status.of(settle(pid))
+    rescue Errno::ECHILD
+      Status.success
+    end
+
+    # The wait builtin, one pid: a remembered status, a blocking wait on a
+    # live job, or nil when the pid is not a waitable job here — unknown,
+    # or a fork-inherited display copy (POSIX: 127).
+    sig { params(pid: Integer).returns(T.nilable(Status)) }
+    def wait_for(pid)
+      @jobs[pid]&.harvest { settle(pid) }
+    rescue Errno::ECHILD
+      Status.success
+    end
+
+    # A forked child environment is a duplicate of the shell environment
+    # (POSIX 2.12), async pids included: the entries stay for display —
+    # jobs, jobs -p, and through them the standard-blessed `wait $(jobs -p)`
+    # in the parent — but demoted to inherited copies, since the parent's
+    # children are not waitable here: wait by pid reports 127 and a %id
+    # reports No such job, as dash does in a real (non-tail-optimized)
+    # forked child. It is no root shell either (see #root?).
+    sig { void }
+    def enter_subshell
+      @jobs.each_value(&:inherit)
+      @stash.clear
+      @control.fork_child
+    end
+
+    # The jobs builtin, after displaying a finished entry: dash frees
+    # reported jobs, so a later wait or %id no longer knows them.
+    sig { params(job: Job).void }
+    def forget(job)
+      @jobs.delete(job.pid)
+    end
+
+    # Opportunistic non-blocking reap, so the jobs builtin sees a child that
+    # finished — or, under monitor mode, stopped — since the last
+    # synchronous wait.
+    sig { void }
+    def poll
+      while (reaped = @control.monitor? ? @system.poll_stopped : @system.poll_child)
+        store(reaped.fetch(0), reaped.fetch(1))
+      end
+    rescue Errno::ECHILD
+      nil
+    end
+
+    # fg's wait (rush-mv8.5): every member — the leader through its entry,
+    # the rest through the stash-aware await — the verdict carrying any
+    # stop, exactly like a fresh foreground pipeline's.
+    sig { params(job: Job).returns(Status) }
+    def settle_members(job)
+      PipelineStatuses.new(job.members.map { |pid| wait_for(pid) || await(pid) }).verdict
+    end
+
+    # dash's cmdloop showjobs(SHOW_CHANGED): the Repl calls this before
+    # each PS1 under monitor mode.
+    sig { params(out: T.untyped).void }
+    def announce_changed(out)
+      poll
+      ordered.select(&:changed).each { |job| job.report(self, out) }
+    end
+
+    private
+
+    sig { params(pid: Integer).returns(Process::Status) }
+    def settle(pid)
+      @stash.delete(pid) || reap_raw(pid)
+    end
+
+    # The lowest free job number, as dash fills slots: the range up to
+    # size+1 always contains one.
+    sig { returns(Integer) }
+    def free_number
+      ((1..(@jobs.size + 1)).to_a - @jobs.each_value.map(&:number)).fetch(0)
+    end
+
+    # A relayed stop (StopRelay: armed stage, stopped target) re-raises
+    # onto this process and, after SIGCONT, re-waits the same target.
+    sig { params(target: Integer).returns(Process::Status) }
+    def reap_raw(target)
+      loop do
+        pid, status = reap_one(target)
+        return status if pid == target && !StopRelay.relay?(@control, status)
+
+        pid == target ? StopRelay.raise_onto_self(@system, status) : store(pid, status)
+      end
+    end
+
+    # waitpid(-1) only when a background job could change state meanwhile —
+    # a stopped job still counts, its death arrives asynchronously, but an
+    # inherited display copy never does (not this environment's child) —
+    # since the direct form cannot reap a foreign child; the plain
+    # foreground path stays byte-identical to the pre-table behaviour.
+    # Monitor mode and an armed stage relay wait WUNTRACED (dash: mflag),
+    # so a stop answers instead of hanging the shell.
+    sig { params(target: Integer).returns([Integer, Process::Status]) }
+    def reap_one(target)
+      pid = @jobs.each_value.any? { |job| !job.finished? && !job.inherited? } ? -1 : target
+      @control.stoppable_waits? ? @system.wait_stoppable(pid) : @system.waitpid2(pid)
+    end
+
+    # Job#finish answers non-nil, so a known pid never falls to the stash.
+    sig { params(pid: Integer, status: Process::Status).void }
+    def store(pid, status)
+      @jobs[pid]&.finish(status) || (@stash[pid] = status)
+    end
+  end
+end

data/lib/rush/lexer/alias_expander.rb

@@ -0,0 +1,129 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # POSIX 2.3.1 alias substitution at lex time. Decides whether a word scanned
+    # in command position is an alias to splice, guarding against re-expanding an
+    # alias within its own replacement (recursion), and tracking the trailing
+    # <blank> rule: a replacement ending in a blank makes the *next* word eligible
+    # too, even though it sits in argument position. Eligibility carries into the
+    # first word of a replacement, so `b` -> `hello` -> `world` chains. It also
+    # owns the stack of input scanners pushed beneath the replacements being read.
+    class AliasExpander
+      extend T::Sig
+
+      # A resolved alias replacement ready to splice into the scanner.
+      class Replacement
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :name, :value
+
+        sig { params(name: String, value: String).void }
+        def initialize(name, value)
+          @name = name
+          @value = value
+        end
+
+        sig { params(parent: StringScanner).returns(Frame) }
+        def frame(parent)
+          Frame.new(name, value, parent)
+        end
+      end
+
+      # One active replacement and the scanner it temporarily covers.
+      class Frame
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :name, :value
+
+        sig { returns(StringScanner) }
+        attr_reader :parent
+
+        sig { params(name: String, value: String, parent: StringScanner).void }
+        def initialize(name, value, parent)
+          @name = name
+          @value = value
+          @parent = parent
+        end
+
+        sig { returns(T::Boolean) }
+        def trailing_blank?
+          value.end_with?(' ', "\t")
+        end
+      end
+
+      sig { params(table: T.nilable(AliasTable)).void }
+      def initialize(table)
+        @table = table
+        @frames = []
+        @check_next = false
+      end
+
+      # The replacement text when `word` is an alias eligible to expand here, else
+      # nil. Eligible means command position or a pending trailing-blank carry.
+      sig { params(word: AST::Word, command_position: T::Boolean).returns(T.nilable(Replacement)) }
+      def expand(word, command_position)
+        name = word.literal_name
+        return unless name && eligible?(command_position)
+
+        table = @table
+        return unless table
+
+        enter(table, name)
+      end
+
+      # Stash the scanner a replacement was spliced over; restore it once the
+      # replacement is fully read, dropping the alias from the active set and, if
+      # its value ended in a blank, marking the following word eligible too (OR so
+      # an inner blank-ending alias still chains past an outer one).
+      sig { params(replacement: Replacement, scanner: StringScanner).void }
+      def push(replacement, scanner)
+        @frames.push(replacement.frame(scanner))
+      end
+
+      sig { returns(T::Boolean) }
+      def nested?
+        @frames.any?
+      end
+
+      sig { returns(T.nilable(StringScanner)) }
+      def pop
+        frame = @frames.fetch(-1)
+        @frames.pop
+        @check_next = true if frame.trailing_blank?
+        frame.parent
+      end
+
+      # A real (non-spliced) token was emitted: spend the one-shot carry.
+      sig { void }
+      def spend
+        @check_next = false
+      end
+
+      private
+
+      # Eligible position: aliases are defined and the word sits in command
+      # position, or a pending trailing-blank carry makes it eligible here.
+      sig { params(command_position: T::Boolean).returns(T::Boolean) }
+      def eligible?(command_position)
+        command_position || @check_next
+      end
+
+      sig { params(table: AliasTable, name: String).returns(T.nilable(Replacement)) }
+      def enter(table, name)
+        value = table.value(name)
+        return if !value || active?(name)
+
+        Replacement.new(name, value)
+      end
+
+      sig { params(name: String).returns(T::Boolean) }
+      def active?(name)
+        @frames.any? { |frame| frame.name == name }
+      end
+    end
+  end
+end

data/lib/rush/lexer/braced_reader.rb

@@ -0,0 +1,86 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Reads the body of a ${...} after the consumed `${`, up to the matching
+    # `}` (POSIX 2.6.2): a nested `${` opens a level (read recursively), a
+    # backslash escapes the next character, and quoted strings / command and
+    # arithmetic substitutions are skipped whole. `quoted` follows dash: inside
+    # double quotes and here-doc bodies a single quote is an ordinary
+    # character; outside them it quotes a region. The body keeps its raw
+    # spelling — the operator word is re-scanned at expansion time.
+    class BracedReader
+      extend T::Sig
+      include QuoteSkips
+
+      # The literal run per context: a quoted ${...} keeps ' ordinary.
+      PLAIN = { false => /[^}$\\'"`]+/, true => /[^}$\\"`]+/ }.freeze
+
+      sig { params(scanner: StringScanner, error: T.class_of(ParseError), quoted: T::Boolean).void }
+      def initialize(scanner, error:, quoted:)
+        @scanner = scanner
+        @error = error
+        @quoted = quoted
+      end
+
+      sig { returns(String) }
+      def read
+        body = +''
+        body << step until peek?('}')
+        @scanner.getch
+        body
+      end
+
+      private
+
+      sig { returns(String) }
+      def step
+        @scanner.scan(PLAIN.fetch(@quoted)) || special
+      end
+
+      sig { returns(String) }
+      def special
+        return "\\#{must_char}" if @scanner.scan('\\')
+        return single if @scanner.scan("'")
+        return double if @scanner.scan('"')
+        return "`#{SubstitutionReader.new(@scanner).backticks}`" if @scanner.scan('`')
+
+        dollar
+      end
+
+      # The unterminated-input error the call site configured.
+      sig { override.returns(T.class_of(ParseError)) }
+      def error_class
+        @error
+      end
+
+      # The only characters that reach here are `$` and end of input. After a
+      # live `$`: `${` opens a nested reference, `$(` a substitution; a `$`
+      # that begins neither stays literal (its name is a plain run).
+      sig { returns(String) }
+      def dollar
+        raise @error, 'unterminated ${' unless @scanner.scan('$')
+        return "${#{nested}}" if @scanner.scan('{')
+        return '$' unless @scanner.scan('(')
+
+        substitution
+      end
+
+      sig { returns(String) }
+      def nested
+        BracedReader.new(@scanner, error: @error, quoted: @quoted).read
+      end
+
+      # `$((` is arithmetic, a lone `$(` is command substitution (as
+      # DollarScanner disambiguates).
+      sig { returns(String) }
+      def substitution
+        reader = SubstitutionReader.new(@scanner)
+        return "$(#{reader.parens})" unless @scanner.scan('(')
+
+        "$((#{reader.arithmetic}))"
+      end
+    end
+  end
+end

data/lib/rush/lexer/case_frame.rb

@@ -0,0 +1,114 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # One open `case` construct inside a $( ... ) body: the paren depth it
+    # opened at, its position in the grammar — :case_word (subject expected),
+    # :await_in (the `in` word expected), :pattern, :body — and whether the
+    # current pattern opened with the optional `(` group, whose balanced
+    # close also enters the item's body.
+    class CaseFrame
+      extend T::Sig
+
+      # The per-state handler for a word before the construct's first body.
+      FRAME_WORDS = { case_word: :subject_word, await_in: :in_word, pattern: :pattern_word }.freeze
+      # Only the word `in` moves a subject to its first pattern.
+      AFTER_SUBJECT = { 'in' => :pattern }.freeze
+      # `esac` in pattern position asks the tracker to pop the construct.
+      POPS = { 'esac' => :pop }.freeze
+
+      sig { returns(Symbol) }
+      attr_reader :state
+
+      sig { params(base: Integer).void }
+      def initialize(base)
+        @base = base
+        @state = T.let(:case_word, Symbol)
+        @marked = T.let(false, T::Boolean)
+        @grouped = T.let(false, T::Boolean)
+      end
+
+      sig { params(depth: Integer).returns(T::Boolean) }
+      def at?(depth)
+        @base == depth
+      end
+
+      # The directive (:pop or :none) for a word seen before the body state.
+      sig { params(text: String).returns(Symbol) }
+      def word(text)
+        send(FRAME_WORDS.fetch(@state), text)
+      end
+
+      sig { void }
+      def body
+        @state = :body
+      end
+
+      # A `(` before any pattern word opens the grouped `(pattern)` form.
+      sig { params(depth: Integer).void }
+      def group(depth)
+        @grouped = true if pattern_start?(depth)
+      end
+
+      sig { params(depth: Integer).returns(T::Boolean) }
+      def pattern?(depth)
+        @state == :pattern && at?(depth)
+      end
+
+      # A pattern that already has words: a newline here is dash's parse error.
+      sig { params(depth: Integer).returns(T::Boolean) }
+      def marked_pattern?(depth)
+        @marked && pattern?(depth)
+      end
+
+      sig { params(depth: Integer).returns(T::Boolean) }
+      def grouped?(depth)
+        @grouped && pattern?(depth)
+      end
+
+      # `;;` reopens pattern position for the next case item.
+      sig { params(depth: Integer).void }
+      def reopen(depth)
+        return unless body_at?(depth)
+
+        @state = :pattern
+        @marked = false
+        @grouped = false
+      end
+
+      private
+
+      # The word after `case` is its subject, whatever it spells.
+      sig { params(_text: String).returns(Symbol) }
+      def subject_word(_text)
+        @state = :await_in
+        :none
+      end
+
+      sig { params(text: String).returns(Symbol) }
+      def in_word(text)
+        @state = AFTER_SUBJECT.fetch(text, :await_in)
+        :none
+      end
+
+      # A pattern word was seen: a following `(` is no longer the group form.
+      sig { params(text: String).returns(Symbol) }
+      def pattern_word(text)
+        action = POPS.fetch(text, :none)
+        @marked = true unless action == :pop
+        action
+      end
+
+      sig { params(depth: Integer).returns(T::Boolean) }
+      def body_at?(depth)
+        @state == :body && at?(depth)
+      end
+
+      sig { params(depth: Integer).returns(T::Boolean) }
+      def pattern_start?(depth)
+        pattern?(depth) && !@marked
+      end
+    end
+  end
+end