rush-shell 0.0.2

data/lib/rush/lexer/paren_reader.rb

@@ -0,0 +1,113 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Reads the body of a $( ... ) after the consumed `$(`, up to the closing
+    # `)` (POSIX 2.6.3: any valid shell script may appear inside). Plain
+    # parentheses nest; quoted strings, backslash escapes, backticks, ${...}
+    # references and `#` comments are skipped whole (ParenRegions); and a
+    # `case` pattern's unbalanced `)` (CaseTracker) does not count. The body
+    # keeps its raw spelling — it is re-parsed at expansion time.
+    class ParenReader
+      extend T::Sig
+      include ParenRegions
+
+      # The longest run with no syntactic weight for paren matching.
+      PLAIN = /[^\s()'"\\`;&|<>#$]+/
+
+      # Which CaseTracker event each operator character raises.
+      OPERATORS = {
+        '&' => :separator, '|' => :separator, "\n" => :newline,
+        '<' => :redirect, '>' => :redirect
+      }.freeze
+
+      sig { params(scanner: StringScanner).void }
+      def initialize(scanner)
+        @scanner = scanner
+        @tracker = T.let(CaseTracker.new, CaseTracker)
+        @word_start = T.let(true, T::Boolean)
+      end
+
+      sig { returns(String) }
+      def read
+        body = +''
+        body << step while @tracker.open?
+        body
+      end
+
+      private
+
+      sig { returns(String) }
+      def step
+        blank || word || region || punct || closer
+      end
+
+      sig { returns(T.nilable(String)) }
+      def blank
+        text = @scanner.scan(/[^\S\n]+/)
+        @word_start = true if text
+        text
+      end
+
+      sig { returns(T.nilable(String)) }
+      def word
+        text = @scanner.scan(PLAIN)
+        return unless text
+
+        @tracker.word(@word_start ? text : '')
+        @word_start = false
+        text
+      end
+
+      sig { returns(T.nilable(String)) }
+      def punct
+        semi || operator || open_paren
+      end
+
+      sig { returns(T.nilable(String)) }
+      def semi
+        return unless @scanner.scan(';')
+
+        @word_start = true
+        return dsemi if @scanner.scan(';')
+
+        @tracker.separator
+        ';'
+      end
+
+      sig { returns(String) }
+      def dsemi
+        @tracker.dsemi
+        ';;'
+      end
+
+      sig { returns(T.nilable(String)) }
+      def operator
+        char = @scanner.scan(/[&|<>\n]/)
+        return unless char
+
+        @tracker.public_send(OPERATORS.fetch(char))
+        @word_start = true
+        char
+      end
+
+      sig { returns(T.nilable(String)) }
+      def open_paren
+        return unless @scanner.scan('(')
+
+        @tracker.open_paren
+        @word_start = true
+        '('
+      end
+
+      sig { returns(String) }
+      def closer
+        raise IncompleteInput, 'unterminated $(' unless @scanner.scan(')')
+
+        @word_start = true
+        @tracker.close_paren? ? ')' : ''
+      end
+    end
+  end
+end

data/lib/rush/lexer/paren_regions.rb

@@ -0,0 +1,74 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # The skip-whole regions of a $( ... ) body (ParenReader's mixin): quoted
+    # strings, backslash escapes, backticks, ${...} references, and `#`
+    # comments. A region reads as one ordinary — never keyword — word to the
+    # CaseTracker, and its text returns with the delimiters so the body keeps
+    # its raw spelling for the expansion-time re-parse.
+    module ParenRegions
+      extend T::Sig
+      include QuoteSkips
+
+      private
+
+      sig { returns(T.nilable(String)) }
+      def region
+        squote || dquote || backtick || escape || dollar || comment
+      end
+
+      sig { returns(T.nilable(String)) }
+      def squote
+        skipped(single) if @scanner.scan("'")
+      end
+
+      sig { returns(T.nilable(String)) }
+      def dquote
+        skipped(double) if @scanner.scan('"')
+      end
+
+      sig { returns(T.nilable(String)) }
+      def backtick
+        skipped("`#{SubstitutionReader.new(@scanner).backticks}`") if @scanner.scan('`')
+      end
+
+      sig { returns(T.nilable(String)) }
+      def escape
+        skipped("\\#{must_char}") if @scanner.scan('\\')
+      end
+
+      sig { returns(T.nilable(String)) }
+      def dollar
+        return unless @scanner.scan('$')
+        return skipped('$') unless @scanner.scan('{')
+
+        skipped("${#{braced}}")
+      end
+
+      sig { returns(String) }
+      def braced
+        BracedReader.new(@scanner, error: IncompleteInput, quoted: false).read
+      end
+
+      # A `#` at the start of a word begins a comment running to the line
+      # end (kept raw, so a `)` inside it does not count); mid-word it is an
+      # ordinary character.
+      sig { returns(T.nilable(String)) }
+      def comment
+        return unless peek?('#')
+        return skipped(must_char) unless @word_start
+
+        @scanner.scan(/#[^\n]*/)
+      end
+
+      sig { params(text: String).returns(String) }
+      def skipped(text)
+        @tracker.word('')
+        @word_start = false
+        text
+      end
+    end
+  end
+end

data/lib/rush/lexer/quote_skips.rb

@@ -0,0 +1,77 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Quote-region skipping shared by the readers that must find a closing
+    # delimiter in raw source (BracedReader's `}`, ParenReader's `)`). Each
+    # helper consumes one region after its opening character and returns it
+    # with its delimiters, so the body keeps its raw spelling; a backslash
+    # always protects exactly the next character. Includers provide @scanner
+    # and may override #error_class to raise their configured error.
+    module QuoteSkips
+      extend T::Sig
+      include Kernel
+      include ScannerPredicates
+
+      private
+
+      # The error for unterminated input; an unfinished region can continue
+      # on the next interactive line.
+      sig { overridable.returns(T.class_of(ParseError)) }
+      def error_class
+        IncompleteInput
+      end
+
+      sig { returns(String) }
+      def must_char
+        @scanner.getch || raise(error_class, 'unterminated escape')
+      end
+
+      sig { returns(String) }
+      def single
+        body = @scanner.scan(/[^']*/)
+        raise error_class, 'unterminated single quote' unless @scanner.scan("'")
+
+        "'#{body}'"
+      end
+
+      sig { returns(String) }
+      def double
+        body = +'"'
+        body << double_chunk until peek?('"')
+        @scanner.getch
+        body << '"'
+      end
+
+      sig { returns(String) }
+      def double_chunk
+        @scanner.scan(/[^"\\$`]+/) || double_special
+      end
+
+      # `\`, `$` and backticks stay live inside double quotes: an embedded
+      # $( ... ) or ${ ... } is skipped whole, so its `)` and `}` never count.
+      sig { returns(String) }
+      def double_special
+        return "\\#{must_char}" if @scanner.scan('\\')
+        return "`#{SubstitutionReader.new(@scanner).backticks}`" if @scanner.scan('`')
+
+        double_dollar
+      end
+
+      sig { returns(String) }
+      def double_dollar
+        raise error_class, 'unterminated double quote' unless @scanner.scan('$')
+        return "${#{quoted_braced}}" if @scanner.scan('{')
+        return '$' unless @scanner.scan('(')
+
+        "$(#{SubstitutionReader.new(@scanner).parens})"
+      end
+
+      sig { returns(String) }
+      def quoted_braced
+        BracedReader.new(@scanner, error: error_class, quoted: true).read
+      end
+    end
+  end
+end

data/lib/rush/lexer/quoted_word.rb

@@ -0,0 +1,67 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  class Lexer
+    # Scans the operator word of a ${...} that appeared in a quoted context
+    # (double quotes or a here-doc body) into an AST::Word, following dash:
+    # $ and ` stay live, a backslash escapes " \ $ ` and the } it protected
+    # from closing the reference, embedded double quotes are removed (their
+    # content was already quoted), and single quotes are ordinary characters.
+    class QuotedWord
+      extend T::Sig
+      include ScannerPredicates
+
+      ESCAPES = { '"' => '"', '\\' => '\\', '$' => '$', '`' => '`', '}' => '}' }.freeze
+      ESCAPE_TABLE = EscapeTable.new(ESCAPES).freeze
+      DISPATCH = { '$' => :dollar, '`' => :backtick, '\\' => :escape }.freeze
+
+      sig { params(text: String).void }
+      def initialize(text)
+        @scanner = StringScanner.new(text)
+        @buffer = SegmentBuffer.new
+      end
+
+      sig { returns(AST::Word) }
+      def word
+        step until @scanner.eos?
+        @buffer.word
+      end
+
+      private
+
+      sig { void }
+      def step
+        char = T.must(@scanner.getch)
+        return if char == '"'
+
+        handler = DISPATCH.fetch(char, nil)
+        handler ? send(handler) : (@buffer << char)
+      end
+
+      # A lone `$` that begins no valid reference stays a literal dollar.
+      sig { void }
+      def dollar
+        @scanner.unscan
+        segment = DollarScanner.new(@scanner).read(quoted: true)
+        segment ? @buffer.push(segment) : (@buffer << '$')
+      end
+
+      sig { void }
+      def backtick
+        @scanner.unscan
+        @buffer.push(DollarScanner.new(@scanner).read_backtick(quoted: true))
+      end
+
+      sig { void }
+      def escape
+        char = @scanner.getch
+        return if char == "\n" # line continuation, as inside double quotes
+
+        @buffer << ESCAPE_TABLE.escape(char)
+      end
+    end
+  end
+end

data/lib/rush/lexer/scanner_predicates.rb

@@ -0,0 +1,20 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Small typed adapter for the StringScanner one-character lookahead pattern
+    # shared by the shell word scanners. StringScanner#peek is a library boundary;
+    # callers use this predicate instead of repeating the comparison everywhere.
+    module ScannerPredicates
+      extend T::Sig
+
+      private
+
+      sig { params(char: String).returns(T::Boolean) }
+      def peek?(char)
+        @scanner.peek(1) == char
+      end
+    end
+  end
+end

data/lib/rush/lexer/source_lines.rb

@@ -0,0 +1,43 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Tracks source line numbers for tokens produced from a StringScanner. The
+    # lexer itself owns tokenization; this helper only maps consumed scanner text
+    # to absolute source lines.
+    class SourceLines
+      extend T::Sig
+
+      sig { params(scanner: StringScanner, offset: Integer).void }
+      def initialize(scanner, offset)
+        @scanner = scanner
+        @line = offset + 1
+      end
+
+      sig { params(blk: T.proc.returns(AST::Word)).returns(AST::Word) }
+      def word(&blk)
+        line = @line
+        start = @scanner.pos
+        yield.tap { count_newlines_since(start) }.then { |word| AST::Word.new(word.segments, source_line: line) }
+      end
+
+      sig { params(start: Integer).void }
+      def heredoc_newline(start)
+        @line += consumed_since(start).count("\n") + 1
+      end
+
+      private
+
+      sig { params(start: Integer).void }
+      def count_newlines_since(start)
+        @line += consumed_since(start).count("\n")
+      end
+
+      sig { params(start: Integer).returns(String) }
+      def consumed_since(start)
+        @scanner.string[start...@scanner.pos].to_s
+      end
+    end
+  end
+end

data/lib/rush/lexer/substitution_reader.rb

@@ -0,0 +1,77 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Reads the raw body of a command substitution from the shared scanner:
+    # $( ... ) up to the matching quote-aware `)` (via ParenReader), or
+    # ` ... ` up to the next backtick. The body is re-parsed and executed at
+    # expansion time.
+    class SubstitutionReader
+      extend T::Sig
+
+      DEPTH_DELTA = { '(' => 1, ')' => -1 }.freeze
+
+      sig { params(scanner: StringScanner).void }
+      def initialize(scanner)
+        @scanner = scanner
+        @depth = 0
+      end
+
+      sig { returns(String) }
+      def parens
+        ParenReader.new(@scanner).read
+      end
+
+      sig { returns(String) }
+      def backticks
+        body = @scanner.scan(/[^`]*/) || ''
+        raise IncompleteInput, 'unterminated `' unless @scanner.scan('`')
+
+        body
+      end
+
+      # Read the body of $(( ... )) after the leading `((`, up to the matching
+      # `))`, allowing balanced inner parentheses.
+      sig { returns(String) }
+      def arithmetic
+        @depth = 0
+        collect(+'')
+      end
+
+      private
+
+      sig { params(body: String).returns(String) }
+      def collect(body)
+        piece = arith_char
+        return body unless piece
+
+        collect(body << piece)
+      end
+
+      sig { returns(T.nilable(String)) }
+      def arith_char
+        raise IncompleteInput, 'unterminated $((' if @scanner.eos?
+
+        adjust_arithmetic(@scanner.getch)
+      end
+
+      sig { params(token: T.nilable(String)).returns(T.nilable(String)) }
+      def adjust_arithmetic(token)
+        delta = DEPTH_DELTA.fetch(token, 0)
+        return arith_close if delta.negative?
+
+        @depth += delta
+        token
+      end
+
+      sig { returns(T.nilable(String)) }
+      def arith_close
+        return ')'.tap { @depth -= 1 } if @depth.nonzero?
+        raise(ParseError, 'arithmetic: malformed') unless @scanner.scan(')')
+
+        nil
+      end
+    end
+  end
+end

data/lib/rush/lexer/token_classifier.rb

@@ -0,0 +1,144 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Classifies a scanned word given the lexer state: a reserved word (only an
+    # unquoted single-literal word in command position), an ASSIGNMENT_WORD (an
+    # unquoted NAME= prefix), or a plain WORD. The assignment value keeps its
+    # quoted segments (x="a b").
+    class TokenClassifier
+      extend T::Sig
+
+      # The assignment-name capture plus the literal segment it came from.
+      class AssignmentHead
+        extend T::Sig
+
+        sig { returns(String) }
+        attr_reader :name, :literal
+
+        sig { params(name: String, literal: String, source_line: Integer).void }
+        def initialize(name, literal, source_line)
+          @name = name
+          @literal = literal
+          @source_line = source_line
+        end
+
+        sig { params(tail: T::Array[AST::WordSegment[T.untyped]]).returns(AST::Assignment) }
+        def assignment(tail)
+          AST::Assignment.new(name: name, value: word(tail))
+        end
+
+        private
+
+        sig { params(tail: T::Array[AST::WordSegment[T.untyped]]).returns(AST::Word) }
+        def word(tail)
+          remainder = AST::LiteralSegment.new(literal.delete_prefix("#{name}="), false)
+          AST::Word.new([remainder] + tail, source_line: @source_line)
+        end
+      end
+
+      NAME = /\A([a-zA-Z_]\w*)=/
+      # `esac` is a reserved word in command position (POSIX 2.4): it closes a
+      # case item whose last list omits `;;`, and is a syntax error elsewhere.
+      RESERVED = {
+        'if' => :If, 'then' => :Then, 'else' => :Else, 'elif' => :Elif, 'fi' => :Fi,
+        'while' => :While, 'until' => :Until, 'do' => :Do, 'done' => :Done,
+        'for' => :For, 'case' => :Case, 'esac' => :Esac,
+        '{' => :Lbrace, '}' => :Rbrace, '!' => :Bang
+      }.freeze
+      FOR_IN = { 'in' => :In, 'do' => :Do }.freeze
+
+      sig { params(word: AST::Word, state: LexState).void }
+      def initialize(word, state)
+        @word = word
+        @state = state
+      end
+
+      sig { returns([Symbol, T.untyped]) }
+      def call
+        state_token || classify
+      end
+
+      private
+
+      sig { returns(T.nilable([Symbol, T.untyped])) }
+      def state_token
+        forced || header_token
+      end
+
+      sig { returns(T.nilable([Symbol, T.untyped])) }
+      def forced
+        return [:NAME, @word] if @state.for_name?
+        return [arm_token, @word] if @state.case_arm?
+
+        [:WORD, @word] if @state.case_subject? || @state.case_pat?
+      end
+
+      sig { returns(T.nilable([Symbol, T.untyped])) }
+      def header_token
+        keyword = for_header
+        return [keyword, @word] if @state.for_in? && keyword
+
+        [:In, @word] if @state.case_in? && @word.literal_name == 'in'
+      end
+
+      sig { returns(Symbol) }
+      def arm_token
+        @word.literal_name == 'esac' ? :Esac : :WORD
+      end
+
+      sig { returns([Symbol, T.untyped]) }
+      def classify
+        keyword = reserved
+        return [keyword, @word] if keyword
+
+        head = assignment_head
+        head ? assignment_token(head) : [:WORD, @word]
+      end
+
+      sig { returns(T.nilable(Symbol)) }
+      def for_header
+        lookup(FOR_IN)
+      end
+
+      sig { returns(T.nilable(Symbol)) }
+      def reserved
+        lookup(RESERVED) if @state.expects_command?
+      end
+
+      sig { params(table: T::Hash[String, Symbol]).returns(T.nilable(Symbol)) }
+      def lookup(table)
+        name = @word.literal_name
+        name ? table.fetch(name, nil) : nil
+      end
+
+      sig { returns(T.nilable(AssignmentHead)) }
+      def assignment_head
+        return unless @state.expects_command?
+
+        literal = assignment_literal
+        return unless literal
+
+        name = capture(literal)
+        name ? AssignmentHead.new(name, literal, @word.source_line) : nil
+      end
+
+      sig { returns(T.nilable(String)) }
+      def assignment_literal
+        @word.first_literal_value
+      end
+
+      sig { params(value: String).returns(T.nilable(String)) }
+      def capture(value)
+        match = NAME.match(value)
+        match && match[1]
+      end
+
+      sig { params(head: AssignmentHead).returns([Symbol, T.untyped]) }
+      def assignment_token(head)
+        [:ASSIGNMENT_WORD, head.assignment(@word.segments.drop(1))]
+      end
+    end
+  end
+end

data/lib/rush/lexer/token_predicates.rb

@@ -0,0 +1,23 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Typed token-shape predicates for the raw [kind, value] tuples returned to
+    # Racc. Keeping them here avoids repeating untyped tuple discriminator checks
+    # in the lexer hot path.
+    module TokenPredicates
+      extend T::Sig
+
+      private
+
+      sig { params(token: [T.untyped, T.untyped]).returns(T::Boolean) }
+      def word_token?(token)
+        case token.first
+        when :WORD then true
+        else false
+        end
+      end
+    end
+  end
+end