rush-shell 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac76c8cbacbecad88ea54c697d25de3b9b69bf3e5397e93990da08fa01151c32
+  data.tar.gz: 44e3a86f79287b401c83ee5f464b2a3480dc667a2bfe48577c944adb27de2d06
+SHA512:
+  metadata.gz: c2e1bfebaabe2a1645affc7ed369d929a5015ee3e1430548bf6f38db1a098ea0cd2bf73e8ff609b761e6750b860b48800ca3f8c417b9fcac1214550aec81f2b2
+  data.tar.gz: d0ce2156b115d6ebe7ec118723de1406598c3c61ec49f9e804568ab4870aa32825d44aa0aa26d66a078d8cd0b2cc43449e951f391f3b72d0bbd6ccc240f04816

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexey Nikitin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# rush
+
+[![CI](https://github.com/tank-bohr/rush/actions/workflows/ci.yml/badge.svg)](https://github.com/tank-bohr/rush/actions/workflows/ci.yml)
+[![Gem](https://img.shields.io/gem/v/rush-shell)](https://rubygems.org/gems/rush-shell)
+
+A **POSIX shell written in pure Ruby**. rush implements the POSIX.1-2017 *Shell
+Command Language* (IEEE Std 1003.1, §2) to the letter, with **dash** as its
+differential oracle: a large corpus of language tests verifies that rush and
+`dash -c` produce the same `[stdout, exit status]` byte for byte. Where dash
+itself diverges from the standard, the standard wins and the divergence is
+documented.
+
+## Install
+
+```sh
+gem install rush-shell
+```
+
+Ruby >= 4.0 is required — the floor is what CI actually proves. The gem is
+`rush-shell`; the executable is `rush`.
+
+## Use
+
+```sh
+rush                       # interactive shell
+rush -c 'echo hello'       # run a command string
+rush script.sh arg1 arg2   # run a script
+echo 'ls | wc -l' | rush   # read commands from stdin
+```
+
+rush accepts the standard `sh` invocation: `-c`, `-o option`/`+o option`, the
+`set`-builtin flag letters (`-e`, `-x`, `-u`, `-m`, …), `--` to end options,
+and behaves as a login shell when invoked with a leading-dash `argv[0]`.
+Interactive mode (auto-detected on a terminal) has Reline line editing and
+full job control: process groups, terminal handover, `Ctrl-Z`, `jobs`, `fg`,
+`bg`, and pre-prompt status change reports — matching dash's picture
+byte-for-byte in the pty smoke tests. Persistent history and the POSIX `fc`
+builtin are on the roadmap.
+
+The full §2 language is implemented: quoting, all parameter-expansion forms,
+command substitution, arithmetic expansion, field splitting, pathname
+expansion (including bracket expressions and locale collation via glibc),
+redirections and here-documents, pipelines and lists, compound commands,
+functions, traps, aliases, `getopts`, and the special builtins.
+
+## Why trust a shell?
+
+Correctness in rush is not a claim, it is machinery:
+
+- **Differential testing** — the language corpus runs every case against a
+  checksum-pinned dash 0.5.13.4 and compares `[stdout, exit status]`; CI
+  repeats this natively and inside a Docker oracle image.
+- **2831 examples, ~99.8% line / ~98.8% branch coverage** — irreducible
+  fork/exec paths are pinned by out-of-process differential tests instead.
+- **Mutation testing** — [mutant](https://github.com/mbj/mutant) over ~38,800
+  mutations gates CI at a ratcheted threshold.
+- **Two independent type systems** — inline Sorbet `sig {}` and RBS checked by
+  Steep, kept deliberately separate so each catches what the other misses.
+
+## Development
+
+```sh
+mise install         # Ruby from .tool-versions
+bundle install
+make install-hooks   # once per clone: Conventional Commits hook (cog)
+bundle exec rake     # the full parallel quality gate
+```
+
+`bundle exec rake` compiles the Racc parser from `grammar/shell.y`, then runs
+rubocop, reek, flay/flog, Steep, Sorbet and the sharded RSpec suite
+concurrently. `bin/test-in-docker` runs the same gate plus container-only
+smokes against the pinned oracle image. `lib/rush/parser.rb` is generated and
+committed; regenerate via `rake compile`, audit with `rake check_parser_drift`.
+
+The architecture is a unidirectional pipeline over shared shell state:
+
+```
+Source → Lexer → Racc Parser → AST → Expander → Executor
+```
+
+with one feedback wire (the parser nudges lexer state for POSIX grammar rules
+1–9) and all OS access funneled through one injectable port
+(`Rush::SystemCalls`). Design decisions and per-slice lessons live in
+[docs/architecture/](docs/architecture) and [docs/journal.md](docs/journal.md);
+agent/contributor workflow lives in [AGENTS.md](AGENTS.md). Notable research:
+[Steep vs Sorbet under extreme quality pressure](docs/steep-vs-sorbet.md).
+
+Releases are cut from the `live` branch: semantic-release computes the version
+from Conventional Commits and the gem is published to RubyGems via OIDC
+trusted publishing with sigstore attestations — no long-lived credentials.
+
+## License
+
+[MIT](LICENSE)

data/exe/rush

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# typed: true
+# frozen_string_literal: true
+
+require_relative '../lib/rush/runtime_type_checks'
+
+Rush::RuntimeTypeChecks.configure
+require_relative '../lib/rush'
+
+exit Rush::CLI.run(ARGV)

data/grammar/shell.y

@@ -0,0 +1,272 @@
+# rush — POSIX sh grammar (Racc), transcribed from POSIX.1-2017 §2.10.2.
+#
+# Phase 1: lists / and_or / pipelines (with ! negation) / simple commands with
+# assignments and file redirections / multi-stage pipes, the compound commands
+# (brace groups, subshells, if, while/until, for, case) and function
+# definitions. Action bodies are one-liners calling Rush::ParserSupport
+# factories; the grammar currently compiles with zero conflicts.
+
+class Rush::Parser
+
+token WORD ASSIGNMENT_WORD IO_NUMBER NEWLINE
+token AND_IF OR_IF
+token DGREAT LESSGREAT CLOBBER DLESS DLESSDASH GREATAND LESSAND
+token If Then Else Elif Fi Lbrace Rbrace Bang
+token While Until Do Done
+token For In NAME
+token Case Esac DSEMI
+
+start program
+
+rule
+
+  program
+    : linebreak                                   { result = make_list([]) }
+    | linebreak complete_commands linebreak       { result = make_list(val[1]) }
+    ;
+
+  complete_commands
+    : complete_command                            { result = val[0] }
+    | complete_commands newline_list complete_command { result = val[0] + val[2] }
+    ;
+
+  complete_command
+    : list separator_op                           { result = terminate_list(val[0], val[1]) }
+    | list                                        { result = terminate_list(val[0], ';') }
+    ;
+
+  list
+    : list separator_op and_or                    { result = append_and_or(val[0], val[1], val[2]) }
+    | and_or                                      { result = [pending_entry(val[0])] }
+    ;
+
+  and_or
+    : pipeline                                    { result = val[0] }
+    | and_or AND_IF linebreak pipeline            { result = make_and_or(val[0], :and, val[3]) }
+    | and_or OR_IF linebreak pipeline             { result = make_and_or(val[0], :or, val[3]) }
+    ;
+
+  pipeline
+    : pipe_sequence                               { result = make_pipeline(val[0], false) }
+    | Bang pipe_sequence                          { result = make_pipeline(val[1], true) }
+    ;
+
+  pipe_sequence
+    : command                                     { result = [val[0]] }
+    | pipe_sequence '|' linebreak command         { result = val[0] << val[3] }
+    ;
+
+  command
+    : simple_command                              { result = val[0] }
+    | compound_command                            { result = val[0] }
+    | compound_command redirect_list              { result = make_redirected(val[0], val[1]) }
+    | function_definition                         { result = val[0] }
+    ;
+
+  redirect_list
+    : io_redirect                                 { result = [val[0]] }
+    | redirect_list io_redirect                   { result = val[0] << val[1] }
+    ;
+
+  # fname '(' ')' — cmd_name vs fname is resolved by the LALR lookahead on '('
+  # (no '(' follows a command name), keeping the lexer unchanged. The body is a
+  # compound command per POSIX Rule 9.
+  function_definition
+    : WORD '(' ')' linebreak compound_command     { result = make_function(val[0], val[4]) }
+    ;
+
+  compound_command
+    : brace_group                                 { result = val[0] }
+    | subshell                                    { result = val[0] }
+    | if_clause                                   { result = val[0] }
+    | while_clause                                { result = val[0] }
+    | until_clause                                { result = val[0] }
+    | for_clause                                  { result = val[0] }
+    | case_clause                                 { result = val[0] }
+    ;
+
+  brace_group
+    : Lbrace compound_list Rbrace                 { result = make_brace_group(val[1]) }
+    ;
+
+  subshell
+    : '(' compound_list ')'                       { result = make_subshell(val[1]) }
+    ;
+
+  while_clause
+    : While compound_list do_group                { result = make_while(val[1], val[2]) }
+    ;
+
+  until_clause
+    : Until compound_list do_group                { result = make_until(val[1], val[2]) }
+    ;
+
+  do_group
+    : Do compound_list Done                       { result = val[1] }
+    ;
+
+  for_clause
+    : For name do_group                                      { result = make_for(val[1], nil, val[2]) }
+    | For name sequential_sep do_group                       { result = make_for(val[1], nil, val[3]) }
+    | For name linebreak In sequential_sep do_group          { result = make_for(val[1], [], val[5]) }
+    | For name linebreak In wordlist sequential_sep do_group { result = make_for(val[1], val[4], val[6]) }
+    ;
+
+  name
+    : NAME                                        { result = val[0].literal_text }
+    ;
+
+  wordlist
+    : WORD                                        { result = [val[0]] }
+    | wordlist WORD                               { result = val[0] << val[1] }
+    ;
+
+  sequential_sep
+    : ';' linebreak
+    | newline_list
+    ;
+
+  case_clause
+    : Case WORD linebreak In linebreak case_list Esac      { result = make_case(val[1], val[5]) }
+    | Case WORD linebreak In linebreak case_list_ns Esac   { result = make_case(val[1], val[5]) }
+    | Case WORD linebreak In linebreak Esac                { result = make_case(val[1], []) }
+    ;
+
+  case_list
+    : case_item                                   { result = [val[0]] }
+    | case_list case_item                         { result = val[0] << val[1] }
+    ;
+
+  /* POSIX 2.10.2: the last case item may omit its DSEMI (`ns` = no separator). */
+  case_list_ns
+    : case_item_ns                                { result = [val[0]] }
+    | case_list case_item_ns                      { result = val[0] << val[1] }
+    ;
+
+  case_item
+    : patterns ')' compound_list DSEMI linebreak      { result = make_case_item(val[0], val[2]) }
+    | patterns ')' linebreak DSEMI linebreak          { result = make_case_item(val[0], make_list([])) }
+    | '(' patterns ')' compound_list DSEMI linebreak  { result = make_case_item(val[1], val[3]) }
+    | '(' patterns ')' linebreak DSEMI linebreak      { result = make_case_item(val[1], make_list([])) }
+    ;
+
+  case_item_ns
+    : patterns ')' compound_list                  { result = make_case_item(val[0], val[2]) }
+    | patterns ')' linebreak                      { result = make_case_item(val[0], make_list([])) }
+    | '(' patterns ')' compound_list              { result = make_case_item(val[1], val[3]) }
+    | '(' patterns ')' linebreak                  { result = make_case_item(val[1], make_list([])) }
+    ;
+
+  patterns
+    : WORD                                        { result = [val[0]] }
+    | patterns '|' WORD                           { result = val[0] << val[2] }
+    ;
+
+  if_clause
+    : If compound_list Then compound_list else_part Fi { result = make_if(val[1], val[3], val[4]) }
+    | If compound_list Then compound_list Fi           { result = make_if(val[1], val[3], nil) }
+    ;
+
+  else_part
+    : Elif compound_list Then compound_list                { result = make_if(val[1], val[3], nil) }
+    | Elif compound_list Then compound_list else_part      { result = make_if(val[1], val[3], val[4]) }
+    | Else compound_list                                   { result = val[1] }
+    ;
+
+  compound_list
+    : linebreak term                              { result = make_list(val[1]) }
+    | linebreak term separator                    { result = make_list(terminate_list(val[1], val[2])) }
+    ;
+
+  term
+    : term separator and_or                       { result = append_and_or(val[0], val[1], val[2]) }
+    | and_or                                      { result = [pending_entry(val[0])] }
+    ;
+
+  separator
+    : separator_op linebreak                      { result = val[0] }
+    | newline_list                                { result = ';' }
+    ;
+
+  simple_command
+    : cmd_prefix cmd_word cmd_suffix              { result = make_simple_command(val[0], val[1], val[2]) }
+    | cmd_prefix cmd_word                         { result = make_simple_command(val[0], val[1], []) }
+    | cmd_prefix                                  { result = make_simple_command(val[0], nil, []) }
+    | cmd_name cmd_suffix                         { result = make_simple_command([], val[0], val[1]) }
+    | cmd_name                                    { result = make_simple_command([], val[0], []) }
+    ;
+
+  cmd_name
+    : WORD                                        { result = val[0] }
+    ;
+
+  cmd_word
+    : WORD                                        { result = val[0] }
+    ;
+
+  cmd_prefix
+    : io_redirect                                 { result = [val[0]] }
+    | cmd_prefix io_redirect                      { result = val[0] << val[1] }
+    | ASSIGNMENT_WORD                             { result = [val[0]] }
+    | cmd_prefix ASSIGNMENT_WORD                  { result = val[0] << val[1] }
+    ;
+
+  cmd_suffix
+    : io_redirect                                 { result = [val[0]] }
+    | cmd_suffix io_redirect                      { result = val[0] << val[1] }
+    | WORD                                        { result = [val[0]] }
+    | cmd_suffix WORD                             { result = val[0] << val[1] }
+    ;
+
+  io_redirect
+    : io_file                                     { result = val[0] }
+    | IO_NUMBER io_file                           { result = with_io_number(val[1], val[0]) }
+    | io_here                                     { result = val[0] }
+    | IO_NUMBER io_here                           { result = with_io_number(val[1], val[0]) }
+    ;
+
+  # The WORD after DLESS is the here-doc delimiter; the lexer has replaced it
+  # with the HereDoc holder whose body it fills at the following newline.
+  io_here
+    : DLESS WORD                                  { result = make_heredoc(val[1]) }
+    | DLESSDASH WORD                              { result = make_heredoc(val[1]) }
+    ;
+
+  io_file
+    : '<' filename                                { result = make_redirect(:in, val[1]) }
+    | '>' filename                                { result = make_redirect(:out, val[1]) }
+    | DGREAT filename                             { result = make_redirect(:append, val[1]) }
+    | LESSGREAT filename                          { result = make_redirect(:readwrite, val[1]) }
+    | CLOBBER filename                            { result = make_redirect(:clobber, val[1]) }
+    | GREATAND filename                           { result = make_redirect(:dup_out, val[1]) }
+    | LESSAND filename                            { result = make_redirect(:dup_in, val[1]) }
+    ;
+
+  filename
+    : WORD                                        { result = val[0] }
+    ;
+
+  separator_op
+    : '&'                                         { result = '&' }
+    | ';'                                         { result = ';' }
+    ;
+
+  newline_list
+    : NEWLINE
+    | newline_list NEWLINE
+    ;
+
+  linebreak
+    : newline_list
+    |   # empty
+    ;
+
+end
+
+---- header
+
+require_relative 'parser_support'
+
+---- inner
+
+include Rush::ParserSupport