rubycc 1.0.0

data/lib/rubycc/preprocess/scanner.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+require_relative "pp_token"
+require_relative "../front/lexeme_reader"
+require_relative "../compile_error"
+
+module Rubycc
+  module Preprocess
+    # Turns raw source into a stream of preprocessing tokens, carrying out
+    # translation phases 2 and 3: backslash-newline line splicing and the
+    # replacement of comments by whitespace. Newlines survive as explicit tokens
+    # so the directive layer (added later) stays line-oriented, and every token
+    # keeps the physical location of its first character.
+    #
+    # Splicing works by deleting every backslash-newline pair up front and
+    # remembering where each deletion happened (@splice_points): tokens are then
+    # matched over the spliced text with StringScanner-driven regexps — one
+    # match per token instead of a method call per character, which is what
+    # makes the preprocessor's dominant cost scale. A token's physical
+    # line/column stays truthful because the recorded splice points replay the
+    # deleted line breaks: everything at or past a splice point is located on
+    # the following physical line (see #sync). Positions are byte offsets
+    # (StringScanner's native unit); columns are converted back to character
+    # counts only when a token is actually made, and only for non-ASCII source.
+    class Scanner
+      # Two- and one-character punctuators gain the preprocessor-only "##" and
+      # "#" over the shared punctuator tables; the three-character set is unchanged.
+      PP_PUNCTUATORS_3 = Front::LexemeReader::PUNCTUATORS_3
+      PP_PUNCTUATORS_2 = (Front::LexemeReader::PUNCTUATORS_2 + ["##"]).freeze
+      PP_PUNCTUATORS_1 = (Front::LexemeReader::PUNCTUATORS_1 + ["#"]).freeze
+
+      # Longest alternative first, so one anchored attempt is a longest match.
+      PUNCTUATOR_RE = Regexp.union(PP_PUNCTUATORS_3 + PP_PUNCTUATORS_2 + PP_PUNCTUATORS_1)
+
+      HORIZONTAL_WS_RE = /[ \t\r\v\f]+/
+      # A // comment runs to (but not over) the end of the physical line; a
+      # trailing backslash-newline was already spliced away, so the comment
+      # continues onto the next line just as it does under gcc.
+      LINE_COMMENT_RE = %r{//[^\n]*}
+      BLOCK_OPEN_RE = %r{/\*}
+      BLOCK_CLOSE_RE = %r{\*/}
+      NEWLINE_RE = /\n/
+
+      IDENTIFIER_RE = /[A-Za-z_][A-Za-z0-9_]*/
+      # A preprocessing number (6.4.8): a digit, or a "." then a digit, and then
+      # digits, identifier characters, ".", and a sign immediately after an
+      # 'e'/'E'/'p'/'P'. Whether the run is a valid C constant is decided later,
+      # at conversion time.
+      PP_NUMBER_RE = /(?:[0-9]|\.[0-9])(?:[eEpP][+-]|[0-9A-Za-z_.])*/
+
+      # A string literal or character constant, kept verbatim (quotes and
+      # escapes included). Only the boundary is recognized here, matching the
+      # streaming lexer: a backslash shields the following character so an
+      # escaped quote does not close the literal. An unterminated literal keeps
+      # whatever was read (the trailing `("|\)?` picks up a lone backslash cut
+      # off by end-of-line or end-of-file); the converter re-scans it and raises
+      # the positioned error.
+      STRING_RE = /"(?:[^"\\\n]|\\[^\n])*(?:"|\\)?/
+      CHAR_RE = /'(?:[^'\\\n]|\\[^\n])*(?:'|\\)?/
+      # A wide character constant L'c' or wide string literal L"..." (6.4.4.4,
+      # 6.4.5): recognized only when the "L" abuts the quote, so an identifier
+      # named "L" is unaffected. The "L" is kept in the spelling so the converter
+      # can tell a wide literal from a plain one; it decides a wide character's
+      # value (int here, as for a plain constant) and rejects a wide string. The
+      # u/U/u8 prefixes are out of scope, so they still scan as an identifier.
+      WIDE_CHAR_RE = /L'(?:[^'\\\n]|\\[^\n])*(?:'|\\)?/
+      WIDE_STRING_RE = /L"(?:[^"\\\n]|\\[^\n])*(?:"|\\)?/
+
+      def initialize(source, filename:)
+        @filename = filename
+        # -1 keeps a trailing empty field so line numbers map 1:1 to entries.
+        @lines = source.split("\n", -1)
+        splice(source)
+        @scanner = StringScanner.new(@spliced)
+        @ascii_only = @spliced.ascii_only?
+        @line = 1
+        # Byte offset in @spliced where the current physical line starts; a
+        # column is the distance from here (plus one). @column_pos/@column_chars
+        # are the incremental cursor #column_at advances (see there); they are
+        # only meaningful for non-ASCII source, and reset_line_start resets all
+        # three together so they can never drift apart.
+        reset_line_start(0)
+        # Index into @splice_points of the first point not yet replayed.
+        @next_splice = 0
+      end
+
+      def scan
+        tokens = []
+        ss = @scanner
+        loop do
+          before = ss.pos
+          skip_whitespace_and_comments(ss, tokens)
+          # Whether any whitespace or comment separated this token from the
+          # previous one on the same logical line. The directive layer needs it
+          # to tell "#define F(x)" (function-like) from "#define F (x)" (an
+          # object macro whose replacement begins with a parenthesis).
+          space_before = ss.pos != before
+          break if ss.eos?
+
+          start = ss.pos
+          sync(start)
+          if ss.skip(NEWLINE_RE)
+            tokens << make_token(:newline, "\n", @line, column_at(start), space_before)
+            @line += 1
+            reset_line_start(ss.pos)
+          else
+            tokens << scan_token(ss, @line, column_at(start), space_before)
+          end
+        end
+        sync(@spliced.bytesize)
+        tokens << make_token(:eof, nil, @line, column_at(@spliced.bytesize))
+        tokens
+      end
+
+      private
+
+      # Translation phase 2: delete every backslash-newline pair, recording for
+      # each deletion the byte offset (in the spliced text) where the next
+      # physical line begins. Two adjacent continuations record the same offset
+      # twice — each still advances the line counter once when replayed. A
+      # source with no continuations (the common case) is shared, not copied.
+      def splice(source)
+        @splice_points = []
+        unless source.include?("\\\n")
+          @spliced = source
+          return
+        end
+        spliced = +""
+        pos = 0
+        while (idx = source.index("\\\n", pos))
+          spliced << source[pos...idx]
+          @splice_points << spliced.bytesize
+          pos = idx + 2
+        end
+        spliced << source[pos..]
+        @spliced = spliced
+      end
+
+      # Replays every splice point at or before byte offset `pos`: each one
+      # marks a physical line break the deletion hid, so the line counter
+      # advances and the line start moves to the point itself (its first
+      # character is column 1 of the continued-onto line). Called with a token's
+      # start offset before its location is read, and with interior offsets by
+      # the block-comment walk; a point strictly inside a token is replayed when
+      # the next token is located, which yields the same stream (a token is
+      # located only by its first character).
+      def sync(pos)
+        points = @splice_points
+        while @next_splice < points.length && points[@next_splice] <= pos
+          @line += 1
+          reset_line_start(points[@next_splice])
+          @next_splice += 1
+        end
+      end
+
+      # Moves the current physical line's start to byte offset `pos`. Every
+      # assignment to @line_start goes through here so the column cursor is
+      # rebased at the same time — a missed reset would not crash, it would
+      # silently report wrong columns (N3).
+      def reset_line_start(pos)
+        @line_start = pos
+        @column_pos = pos
+        @column_chars = 0
+      end
+
+      # The 1-based column of byte offset `pos`, counted in characters from the
+      # current physical line's start. Byte arithmetic serves ASCII source
+      # directly; non-ASCII source has to count characters, and must count them
+      # *incrementally*: measuring the whole @line_start..pos span per token
+      # costs O(line length) each time, so a single long line of L tokens costs
+      # O(L^2) — and one non-ASCII byte anywhere in the file (a comment in
+      # Japanese, a UTF-8 BOM) is enough to switch @ascii_only off for all of
+      # it. Tokens are located left to right, so keeping the last (byte offset,
+      # column) pair as a cursor and counting only the span since then makes a
+      # line cost O(line length) in total. Should a caller ever ask for an
+      # offset behind the cursor, the count restarts from the line start, so the
+      # answer stays right even if that monotonicity is lost.
+      def column_at(pos)
+        return pos - @line_start + 1 if @ascii_only
+
+        if pos < @column_pos
+          @column_pos = @line_start
+          @column_chars = 0
+        end
+        if pos > @column_pos
+          @column_chars += @spliced.byteslice(@column_pos, pos - @column_pos).length
+          @column_pos = pos
+        end
+        @column_chars + 1
+      end
+
+      # Skips horizontal whitespace and comments (translation phase 3). Newlines
+      # are left for the caller so they become tokens; a newline retained inside
+      # a block comment is emitted here directly, keeping the logical line count
+      # exact for later directive processing.
+      def skip_whitespace_and_comments(ss, tokens)
+        loop do
+          next if ss.skip(HORIZONTAL_WS_RE)
+          next if ss.skip(LINE_COMMENT_RE)
+          return unless ss.match?(BLOCK_OPEN_RE)
+
+          skip_block_comment(ss, tokens)
+        end
+      end
+
+      # A /* */ comment, which may span physical lines. Each retained newline it
+      # crosses is emitted as a token so the line count stays consistent; a
+      # spliced-away continuation inside it adds no token, only a line. An
+      # unterminated comment is a hard error, positioned at the opening "/*".
+      def skip_block_comment(ss, tokens)
+        sync(ss.pos)
+        start_line = @line
+        start_column = column_at(ss.pos)
+        ss.skip(BLOCK_OPEN_RE)
+        body = ss.scan_until(BLOCK_CLOSE_RE)
+        raise_error("unterminated block comment", start_line, start_column) if body.nil?
+
+        base = ss.pos - body.bytesize
+        from = 0
+        while (idx = body.byteindex("\n", from))
+          at = base + idx
+          sync(at)
+          tokens << make_token(:newline, "\n", @line, column_at(at))
+          @line += 1
+          reset_line_start(at + 1)
+          from = idx + 1
+        end
+      end
+
+      # Scans a single preprocessing token (never a newline or whitespace),
+      # tagged with the physical location of its first character. One anchored
+      # regexp attempt per candidate class, ordered so a prefix can never steal
+      # a longer token: a pp-number before "." the punctuator, a wide literal
+      # before the identifier "L".
+      def scan_token(ss, line, column, space_before)
+        if (text = ss.scan(PP_NUMBER_RE))
+          type = :pp_number
+        elsif (text = ss.scan(IDENTIFIER_RE))
+          type = :identifier
+          # An "L" abutting a quote is a wide literal, not an identifier.
+          if text == "L" && (quoted = ss.scan(CHAR_RE) || ss.scan(STRING_RE))
+            type = quoted.start_with?("'") ? :char : :string
+            text = "L" + quoted
+          end
+        elsif (text = ss.scan(CHAR_RE))
+          type = :char
+        elsif (text = ss.scan(STRING_RE))
+          type = :string
+        elsif (text = ss.scan(PUNCTUATOR_RE))
+          type = :punct
+        else
+          # Anything that matches nothing above becomes a single-character
+          # :other token (6.4p1), deferring the decision of whether it is an
+          # error to a later phase.
+          type = :other
+          text = ss.getch
+        end
+        make_token(type, text, line, column, space_before)
+      end
+
+      def make_token(type, text, line, column, space_before = false)
+        PPToken.new(
+          type: type,
+          text: text,
+          filename: @filename,
+          line: line,
+          column: column,
+          source_line: source_line_for(line),
+          space_before: space_before
+        )
+      end
+
+      def source_line_for(line)
+        @lines[line - 1] || ""
+      end
+
+      def raise_error(description, line, column)
+        raise CompileError.new(
+          description,
+          filename: @filename,
+          line: line,
+          column: column,
+          source_line: source_line_for(line)
+        )
+      end
+    end
+  end
+end

data/lib/rubycc/preprocess/token_converter.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "pp_token"
+require_relative "../front/token"
+require_relative "../front/lexeme_reader"
+require_relative "../compile_error"
+
+module Rubycc
+  module Preprocess
+    # Ends translation phase 4 by turning preprocessing tokens into the
+    # Front::Token stream the parser consumes. Numbers are folded, string and
+    # character literals decoded, and identifiers classified as keywords, all via
+    # the shared LexemeReader so the result matches the streaming lexer exactly.
+    # Newlines are dropped here; a "#"/"##" that survives to this point is a
+    # stray operator with no macro meaning (directive lines are diagnosed
+    # earlier), so it is rejected.
+    #
+    # This is where translation phases 5-7 sit in this pipeline, so adjacent
+    # string-literal concatenation (phase 6, ISO C 6.4.5p5) happens here: a run
+    # of neighbouring string tokens folds into one, its bytes the per-literal
+    # decodings laid end to end. The streaming Front::Lexer takes the direct path
+    # and does not concatenate — nothing but this converter ever feeds the
+    # parser in the real compile pipeline (which always runs through the
+    # preprocessor), so the lexer's simpler single-literal path serves its
+    # unit-test-only role without the phase-6 fold.
+    class TokenConverter
+      def convert(pp_tokens)
+        tokens = []
+        index = 0
+        while index < pp_tokens.length
+          pp = pp_tokens[index]
+          case pp.type
+          when :newline
+            index += 1
+          when :eof
+            tokens << front_token(pp, :eof, nil)
+            index += 1
+          when :identifier
+            spelling = Front::LexemeReader.keyword_spelling(pp.text)
+            tokens << front_token(pp, spelling ? :keyword : :ident, spelling || pp.text)
+            index += 1
+          when :pp_number
+            tokens << convert_number(pp)
+            index += 1
+          when :string
+            value, index = concatenate_strings(pp_tokens, index)
+            tokens << front_token(pp, :string, value)
+          when :char
+            tokens << num_token(pp, decode_char(pp), 10, "")
+            index += 1
+          when :punct
+            if pp.text == "#" || pp.text == "##"
+              raise_at(pp, "stray '#' in program")
+            end
+            tokens << front_token(pp, :punct, pp.text)
+            index += 1
+          when :other
+            raise_at(pp, "unexpected character #{pp.text.inspect}")
+          end
+        end
+        tokens
+      end
+
+      private
+
+      # Folds the maximal run of adjacent string-literal tokens starting at
+      # `index` into a single value (translation phase 6). Each literal is decoded
+      # on its own, so an escape resolves within the literal that spells it —
+      # "\x41" "1" is the two bytes 'A' and '1', never one "\x411" digit run
+      # (6.4.5p4) — and the decoded bytes are concatenated. Intervening newline
+      # tokens are inter-token whitespace and do not break adjacency; in the
+      # compile pipeline the expander has already dropped them, so consecutive
+      # string tokens simply abut. Returns [concatenated-bytes, index-past-run].
+      def concatenate_strings(pp_tokens, index)
+        bytes = decode_string(pp_tokens[index])
+        index += 1
+        loop do
+          nxt = index
+          nxt += 1 while pp_tokens[nxt]&.type == :newline
+          break unless pp_tokens[nxt]&.type == :string
+
+          bytes += decode_string(pp_tokens[nxt])
+          index = nxt + 1
+        end
+        [bytes, index]
+      end
+
+      # The escape-resolved bytes of one string literal. A wide string literal
+      # (an "L" prefix) has element type wchar_t, which this subset cannot
+      # represent, so it is rejected rather than silently narrowed.
+      def decode_string(pp)
+        raise_at(pp, "wide string literals are not supported") if pp.text.start_with?("L")
+
+        decode(pp, pp.text) { |reader| reader.read_string }.value
+      end
+
+      # A character constant's integer value. A wide character constant L'c' has
+      # type wchar_t (int on this target); for the single-byte characters this
+      # subset lexes its value equals the plain constant's, so the "L" prefix is
+      # dropped and the remainder decoded like an ordinary 'c'.
+      def decode_char(pp)
+        spelling = pp.text.start_with?("L") ? pp.text[1..] : pp.text
+        decode(pp, spelling) { |reader| reader.read_char }.value
+      end
+
+      # Folds a preprocessing number into a :num or :float token. A pp-number is
+      # broader than a C constant, so an ill-formed one (e.g. "12abc", "1.2.3")
+      # is rejected here rather than at scan time.
+      def convert_number(pp)
+        result = decode(pp, pp.text) { |reader| reader.read_number }
+        if result.type == :float
+          Front::Token.new(
+            type: :float, value: result.value,
+            filename: pp.filename, line: pp.line, column: pp.column,
+            source_line: pp.source_line, suffix: result.suffix
+          )
+        else
+          num_token(pp, result.value, result.base, result.suffix)
+        end
+      end
+
+      # Runs a LexemeReader over `spelling` (the token's own text, or that text
+      # with a wide-literal "L" prefix already stripped), mapping any LexError
+      # onto the token's start position. A lexeme spliced across a line
+      # continuation is reported at its start, matching where it begins in source.
+      def decode(pp, spelling)
+        yield Front::LexemeReader.new(spelling)
+      rescue Front::LexError => e
+        raise_at(pp, e.message)
+      end
+
+      def front_token(pp, type, value)
+        Front::Token.new(
+          type: type, value: value,
+          filename: pp.filename, line: pp.line, column: pp.column,
+          source_line: pp.source_line
+        )
+      end
+
+      def num_token(pp, value, base, suffix)
+        Front::Token.new(
+          type: :num, value: value,
+          filename: pp.filename, line: pp.line, column: pp.column,
+          source_line: pp.source_line, base: base, suffix: suffix
+        )
+      end
+
+      def raise_at(pp, description)
+        raise CompileError.new(
+          description,
+          filename: pp.filename, line: pp.line, column: pp.column,
+          source_line: pp.source_line
+        )
+      end
+    end
+  end
+end

data/lib/rubycc/rmake/cli.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "makefile"
+
+module Rubycc
+  module Rmake
+    # The command-line front end to rmake (M3 / ROADMAP §6 B6). It exists so
+    # RubyGems can drive rubycc's builds by setting `ENV["MAKE"]` to this program:
+    # Gem::Ext::Builder invokes `$(MAKE)` as three separate processes shaped like
+    #
+    #   rmake DESTDIR= sitearchdir=<tmp> sitelibdir=<tmp> clean
+    #   rmake DESTDIR= sitearchdir=<tmp> sitelibdir=<tmp>          (default goal)
+    #   rmake DESTDIR= sitearchdir=<tmp> sitelibdir=<tmp> install
+    #
+    # so the argument grammar it must accept is: command-line variable definitions
+    # (`VAR=value`, which override the Makefile's own assignments), zero or more
+    # target names (an absent target builds the default goal) and, though RubyGems
+    # does not pass them, the `-j`/`-f` options make users expect. Because rmake is
+    # rubycc's build-only make, tool substitution (`$(CC)`/`$(LDSHARED)` routed to
+    # rubycc's Driver) is always on — a `CC = gcc` left in the Makefile is still
+    # built by rubycc.
+    #
+    # It is a plain method object rather than an OptionParser front end: the mkmf
+    # invocation shape is fixed and narrow, so hand-parsing keeps the accepted
+    # grammar explicit (and the "everything routes to rubycc" contract obvious).
+    class CLI
+      DEFAULT_MAKEFILE = "Makefile"
+
+      # Run rmake with +argv+ in +dir+, returning the process exit status
+      # (0 success, 2 for any make-level failure — the code GNU make uses). +out+
+      # and +err+ are injectable so the CLI can be exercised without spawning.
+      def self.run(argv, dir: Dir.pwd, out: $stdout, err: $stderr)
+        new(dir: dir, out: out, err: err).run(argv)
+      end
+
+      def initialize(dir:, out:, err:)
+        @dir = dir
+        @out = out
+        @err = err
+      end
+
+      def run(argv)
+        options = parse_argv(argv)
+
+        makefile_path = File.expand_path(options[:file] || DEFAULT_MAKEFILE, @dir)
+        unless File.file?(makefile_path)
+          @err.puts("rmake: #{options[:file] || DEFAULT_MAKEFILE}: No such file")
+          return 2
+        end
+
+        mk = Makefile.parse(File.read(makefile_path), dir: @dir, overrides: options[:overrides],
+                             defaults: { "MAKE" => make_default })
+        goals = options[:targets].empty? ? [nil] : options[:targets]
+        # Tool substitution is always on: rmake is rubycc's build CLI, so the
+        # compiler/linker words in every recipe are handed to rubycc's Driver.
+        goals.each { |goal| mk.run(goal, out: @out, err: @err, tools: :rubycc, jobs: options[:jobs]) }
+        0
+      rescue RmakeError => e
+        @err.puts("rmake: #{e.message}")
+        2
+      end
+
+      private
+
+      # Split +argv+ into { overrides:, targets:, jobs:, file: }. Anything that is
+      # not a recognised option or a `VAR=value` definition is a target name.
+      def parse_argv(argv)
+        overrides = {}
+        targets = []
+        # Default to all cores: rmake is invoked by `gem install` as a plain
+        # `make`, so a serial default would leave multi-file extensions
+        # building one recipe at a time (H5). The scheduler's dependency DAG
+        # is unaffected, and each step's output is buffered and flushed whole
+        # (like `-O`), so parallel output never interleaves and the built
+        # artifacts match a serial run; an explicit `-j1` still gets the old
+        # serial behaviour.
+        jobs = processor_count
+        file = nil
+
+        i = 0
+        while i < argv.length
+          arg = argv[i]
+          case arg
+          when "-f", "--file", "--makefile"
+            file = argv[i + 1]
+            i += 1
+          when /\A-f(.+)\z/, /\A--file=(.+)\z/, /\A--makefile=(.+)\z/
+            file = Regexp.last_match(1)
+          when "-j", "--jobs"
+            # A bare -j (its argument omitted, as make allows) means "as many as
+            # possible"; approximate that with the processor count.
+            if (nxt = argv[i + 1]) && nxt =~ /\A\d+\z/
+              jobs = nxt.to_i
+              i += 1
+            else
+              jobs = processor_count
+            end
+          when /\A-j(\d+)\z/, /\A--jobs=(\d+)\z/
+            jobs = Regexp.last_match(1).to_i
+          when /\A([A-Za-z_][A-Za-z0-9_]*)=(.*)\z/m
+            overrides[Regexp.last_match(1)] = Regexp.last_match(2)
+          when /\A-/
+            # An unrecognised option: rmake is a narrow make, so ignore flags it
+            # does not model rather than abort a build over an option that does
+            # not change what gets built.
+          else
+            targets << arg
+          end
+          i += 1
+        end
+
+        { overrides: overrides, targets: targets, jobs: [jobs, 1].max, file: file }
+      end
+
+      def processor_count
+        require "etc"
+        Etc.nprocessors
+      rescue StandardError
+        1
+      end
+
+      # POSIX requires make to define `MAKE` built in, so `$(MAKE)` in a recipe
+      # (a recursive-make invocation, e.g. `cd sub && $(MAKE)`) expands to
+      # something runnable rather than the empty string a silently-undefined
+      # variable would give — which would collapse the recipe line to `cd sub &&`
+      # and turn a recursive build into a no-op. The value is an absolute path to
+      # this very program, so the recursive invocation is rmake again, never a
+      # bare "make" that would hand the recursive build to a host GNU make (or
+      # fail outright) instead of rubycc.
+      #
+      # `ENV["MAKE"]` is honoured first because RubyGems' rubygems_plugin sets it
+      # to rmake before invoking `$(MAKE)` at the top level, and that value must
+      # propagate unchanged into any recipe this run itself expands.
+      def make_default
+        env_make = ENV["MAKE"]
+        return env_make if env_make && !env_make.empty?
+
+        File.expand_path($PROGRAM_NAME)
+      end
+    end
+  end
+end

data/lib/rubycc/rmake/errors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Rubycc
+  # The base error is normally provided by lib/rubycc.rb. rmake is loadable on
+  # its own (B1 ships no CLI wiring), so define a stand-in only when the full
+  # library has not been required yet.
+  Error = Class.new(StandardError) unless defined?(Error)
+
+  module Rmake
+    # Raised for a defect in the Makefile the user handed us: a syntax rmake's
+    # mkmf-subset does not accept, or a runaway variable expansion. rmake never
+    # parses C, so this is deliberately distinct from CompileError; it names the
+    # make-level construct at fault so the failure points back at the Makefile.
+    class RmakeError < Rubycc::Error; end
+
+    # A line the parser cannot classify as an assignment, a rule, a recipe, or a
+    # directive that mkmf is known to emit. Carries the 1-based source line so
+    # the offending text can be located in the generated Makefile.
+    class ParseError < RmakeError
+      attr_reader :line_number
+
+      def initialize(message, line_number:)
+        @line_number = line_number
+        super("Makefile:#{line_number}: #{message}")
+      end
+    end
+
+    # Raised when variable expansion exceeds its depth budget, which in practice
+    # means a reference cycle (`A = $(B)` / `B = $(A)`). It is a DoS fail-safe,
+    # not a diagnosis of the exact cycle — the budget stops unbounded recursion
+    # before it can exhaust the Ruby stack.
+    class ExpansionError < RmakeError; end
+
+    # Base for a failure that happens while *running* a plan (as opposed to
+    # parsing or planning it). It always names the target whose recipe was
+    # executing and the exact expanded recipe line at fault, so a build failure
+    # points back at "which command of which target" the way make's own
+    # `*** [target] Error` line does (N3).
+    class ExecutionError < RmakeError
+      attr_reader :target, :command
+
+      def initialize(message, target:, command:)
+        @target = target
+        @command = command
+        super("#{target}: #{message}: #{command.inspect}")
+      end
+    end
+
+    # A recipe command exited non-zero (or an internal utility reported failure)
+    # and the line was not marked to ignore errors (`-`). Carries the exit reason
+    # when one is known (a missing external tool, a utility's own message).
+    class CommandFailedError < ExecutionError
+      def initialize(target:, command:, reason: nil)
+        super(reason ? "recipe command failed (#{reason})" : "recipe command failed",
+              target: target, command: command)
+      end
+    end
+
+    # The shell-less runner met a construct it does not interpret (a pipe,
+    # background `&`, command substitution, an unterminated quote, ...). Since
+    # rubycc runs recipes without /bin/sh, an unhandled construct must fail
+    # loudly with the offending target and line rather than be silently dropped —
+    # this is the signal that a gem's recipe needs to be added to the runner's
+    # scope or the gem listed as unsupported (ROADMAP §6 B2).
+    class UnsupportedRecipeError < ExecutionError
+      def initialize(construct, target:, command:)
+        super("unsupported shell construct (#{construct})", target: target, command: command)
+      end
+    end
+  end
+end