rubycc 1.0.0

data/lib/rubycc/compile_error.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rubycc
+  # Base error class (also defined in rubycc.rb; reopened here so this file can
+  # be required standalone).
+  class Error < StandardError; end
+
+  # A diagnostic raised for any user-facing compilation failure (lexing,
+  # parsing, ...). Carries enough source location information (N3) to render a
+  # gcc-style message with a caret pointing at the offending column.
+  class CompileError < Error
+    attr_reader :description, :filename, :line, :column, :source_line
+
+    # description:: the short error text, e.g. "expected ';'"
+    # filename::    the source file name for the message header
+    # line::        1-based line number
+    # column::      1-based column number
+    # source_line:: the full text of the offending source line (no newline)
+    def initialize(description, filename:, line:, column:, source_line:)
+      @description = description
+      @filename = filename
+      @line = line
+      @column = column
+      @source_line = source_line
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      header = "#{filename}:#{line}:#{column}: error: #{description}"
+      caret = "#{" " * (column - 1)}^"
+      "#{header}\n#{source_line}\n#{caret}"
+    end
+  end
+end

data/lib/rubycc/compiler.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "compile_error"
+require_relative "preprocess/preprocessor"
+require_relative "front/parser"
+require_relative "ir/generator"
+require_relative "backend/x86_64"
+require_relative "backend/aarch64"
+require_relative "objfile/elf_writer"
+
+module Rubycc
+  # Orchestrates every compilation stage: source -> tokens -> AST -> IR ->
+  # machine code -> ELF relocatable object.
+  class Compiler
+    # The backend dispatch table: a normalized target name selects the code
+    # generator that lowers IR to that machine's instructions, the ELF machine
+    # description (e_machine value + relocation-type table) the object writer
+    # emits under, and the one ABI trait the machine-independent front end has to
+    # know about — whether plain `char` is signed. That last entry is what makes
+    # the front end target-aware at all: the signedness of plain `char` is
+    # implementation-defined (6.2.5p15) and each ABI pins it, signed under the
+    # x86-64 System V psABI and unsigned under AAPCS64, so it has to reach type
+    # resolution rather than being decided once for the whole compiler. The
+    # `arch_macros` entry is the same idea one stage earlier: the CPU-identifying
+    # predefined macros a translation unit (and the libc headers it includes)
+    # dispatches on. `unnamed_bitfields_align` is a third: the ABIs disagree on
+    # whether an unnamed bit-field's type raises its aggregate's alignment, so
+    # sizeof and _Alignof of such a struct are target-dependent (see
+    # StructType#define). `libc_arch` is a fourth: it names the bundled
+    # libc-and-arch header layer the preprocessor puts on its default search path,
+    # so a cross compile reads the target's ABI headers (struct stat, nlink_t,
+    # WCHAR_* and kin) rather than the host's. Apart from those four every entry
+    # shares the orchestration logic below unchanged.
+    #
+    # Which C library those headers describe is deliberately *not* in this table:
+    # the machine and the libc are independent axes (either arch runs either
+    # libc), so it is #compile's own `libc` keyword instead.
+    TARGETS = {
+      "x86_64" => { backend: Backend::X86_64, machine: ObjFile::ELFWriter::X86_64,
+                    char_signed: true,
+                    arch_macros: Preprocess::Preprocessor::X86_64_ARCH_MACROS,
+                    libc_arch: "x86_64",
+                    unnamed_bitfields_align: false,
+                    convention: IR::CallConvention::SYSTEM_V_AMD64 },
+      "aarch64" => { backend: Backend::AArch64, machine: ObjFile::ELFWriter::AARCH64,
+                     char_signed: false,
+                     arch_macros: Preprocess::Preprocessor::AARCH64_ARCH_MACROS,
+                     libc_arch: "aarch64",
+                     unnamed_bitfields_align: true,
+                     convention: IR::CallConvention::AAPCS64 }
+    }.freeze
+
+    # Compiles C source into an ELF64 relocatable object, returned as an
+    # ASCII-8BIT String. Raises Rubycc::CompileError on user errors. `target`
+    # names the machine to generate code for (see TARGETS); it defaults to
+    # x86_64 and an unknown value is a caller error. `libc` names the C library
+    # whose ABI the bundled headers are to describe ("glibc" or "musl"); it
+    # defaults to the host's own, so an unconfigured compile on a musl host
+    # reads the musl branches, and an unknown value is a caller error too (the
+    # preprocessor raises it).
+    def compile(source, filename:, include_paths: [], pic: false, defines: [], system_includes: true,
+                target: "x86_64", libc: Preprocess::Preprocessor.host_libc,
+                default_visibility: :default)
+      entry = TARGETS.fetch(target) { raise ArgumentError, "unsupported target: #{target.inspect}" }
+      # The target's plain-`char` type, threaded through every stage that builds
+      # or reasons about one: the preprocessor (which predefines
+      # __CHAR_UNSIGNED__ when it is unsigned), the parser (which resolves the
+      # `char` type-specifier to it) and the generator (which types a string
+      # literal's elements with it).
+      plain_char = Type.plain_char(entry[:char_signed])
+      tokens = Preprocess::Preprocessor.new(char_unsigned: plain_char.unsigned?,
+                                            arch_macros: entry[:arch_macros],
+                                            libc_arch: entry[:libc_arch],
+                                            libc: libc)
+                                       .run(source, filename: filename,
+                                            include_paths: include_paths, defines: defines,
+                                            system_includes: system_includes)
+      program = Front::Parser.new(tokens, plain_char: plain_char,
+                                          unnamed_bitfields_align: entry[:unnamed_bitfields_align],
+                                          builtin_va_list: entry[:convention].va_list_type).parse
+      ir_program = IR::Generator.new(plain_char: plain_char,
+                                     convention: entry[:convention]).generate(program, pic: pic)
+
+      backend = entry[:backend].new
+      writer = ObjFile::ELFWriter.new(machine: entry[:machine])
+      writer.add_file_symbol(File.basename(filename))
+
+      # Lay out the translation unit's string pool as .rodata: each interned
+      # string in id order, NUL-terminated. `string_offsets[id]` is the byte
+      # offset of string `id` within the section.
+      rodata = +"".b
+      string_offsets = []
+      ir_program.strings.each do |bytes|
+        string_offsets << rodata.bytesize
+        rodata << bytes << "\0".b
+      end
+
+      # Lay out the file-scope variables: initialized ones into .data (their
+      # values packed little-endian at the declared width) and zero-initialized
+      # ones into .bss (space reserved only). Each is placed at its type's
+      # alignment and registered as a global STT_OBJECT symbol; the section
+      # alignment is the widest member's.
+      data = +"".b
+      data_align = 1
+      bss_size = 0
+      bss_align = 1
+      # Symbols a .data pointer slot resolves against (a "&global", a decayed
+      # global array, or a function address in a function-pointer global). A
+      # reference to a function defined elsewhere must be registered as an
+      # undefined symbol, but only once the set of locally defined functions is
+      # known (after the text is compiled), so the names are collected here.
+      data_symbol_refs = []
+      ir_program.globals.each do |global|
+        # A `static` global gets an internal-linkage (STB_LOCAL) object symbol,
+        # an ordinary one a global (STB_GLOBAL) symbol; both are laid out into
+        # .data/.bss identically.
+        internal = global.linkage == :internal
+        if global.init.nil?
+          bss_align = [bss_align, global.align].max
+          bss_size = align_up(bss_size, global.align)
+          add_object_symbol(writer, internal, global.name, :bss, bss_size, global.size,
+                            visibility: ir_program.visibility.fetch(global.name, default_visibility))
+          bss_size += global.size
+        else
+          data_align = [data_align, global.align].max
+          offset = align_up(data.bytesize, global.align)
+          data << ("\0".b * (offset - data.bytesize))
+          add_object_symbol(writer, internal, global.name, :data, offset, global.size,
+                            visibility: ir_program.visibility.fetch(global.name, default_visibility))
+          data << global.init.bytes
+          # Each pointer slot in the image is patched by a .data relocation,
+          # its .text-relative offset (within the global) biased by where the
+          # global itself landed in .data.
+          global.init.relocations.each do |reloc|
+            register_data_relocation(writer, reloc, offset, string_offsets)
+            data_symbol_refs << reloc.symbol if reloc.kind == :symbol
+          end
+        end
+      end
+      writer.set_data(data, align: data_align) unless data.empty?
+      writer.set_bss(bss_size, align: bss_align) if bss_size.positive?
+
+      text = +"".b
+      # A defined function's name is only ever tested for membership below
+      # (never iterated in order), so a Set keeps that check O(1) instead of
+      # the O(n) linear scan an Array would need per relocation.
+      defined_names = Set.new
+      relocations = []
+      ir_program.functions.each do |ir_func|
+        result = backend.compile(ir_func)
+        # Align each function to 16 bytes with the target's NOP filler, keeping
+        # the output deterministic and every entry point aligned.
+        pad_to_alignment(text, 16, entry[:machine].text_padding)
+        base = text.bytesize
+        text << result.bytes
+        result.symbols.each do |sym|
+          # A `static` function is a file-local (STB_LOCAL) symbol; an ordinary
+          # one is global. Either way it is a defined name a same-object
+          # reference resolves against, never an undefined external.
+          if ir_func.linkage == :internal
+            writer.add_local_func(sym[:name], base + sym[:offset], sym[:size])
+          else
+            writer.add_global_func(
+              sym[:name], base + sym[:offset], sym[:size],
+              visibility: ir_program.visibility.fetch(ir_func.name, default_visibility)
+            )
+          end
+          defined_names << sym[:name]
+        end
+        result.relocations.each do |reloc|
+          relocations << reloc.merge(offset: base + reloc[:offset])
+        end
+      end
+
+      # A function-pointer global that names a function defined elsewhere leaves
+      # an undefined symbol for the linker; one that names a local function or
+      # another global is already in the symbol table. Like `defined_names`,
+      # this is only ever queried for membership, so it stays a Set.
+      known_names = defined_names | ir_program.globals.map(&:name)
+      data_symbol_refs.each do |symbol|
+        writer.add_undefined_symbol(symbol) unless known_names.include?(symbol)
+      end
+
+      relocations.each do |reloc|
+        case reloc[:kind]
+        when :call, :func
+          # A call, or a taken function address, whose target is not defined in
+          # this translation unit becomes an undefined symbol for the linker to
+          # resolve (e.g. libc's abs). The two are recorded as distinct kinds
+          # because they only coincide on some targets: x86_64 resolves both with
+          # the same PC-relative PLT32, while aarch64 needs a `bl`'s CALL26 for
+          # one and an address-forming instruction pair for the other.
+          writer.add_undefined_symbol(reloc[:symbol]) unless defined_names.include?(reloc[:symbol])
+          if reloc[:kind] == :call
+            writer.add_text_relocation(offset: reloc[:offset], symbol: reloc[:symbol])
+          else
+            writer.add_func_relocation(offset: reloc[:offset], symbol: reloc[:symbol])
+          end
+        when :string
+          # A reference from .text into .rodata, resolved against the .rodata
+          # section symbol and displaced by the string's byte offset within the
+          # pool. The offset is passed unbiased: whatever a target's own field
+          # placement demands on top of it belongs to its machine description,
+          # not to this machine-independent layer.
+          writer.add_rodata_relocation(offset: reloc[:offset],
+                                       addend: string_offsets[reloc[:string_id]])
+        when :global
+          # A reference from .text addressing a file-scope variable, resolved
+          # against that variable's own object symbol. A variable only declared
+          # `extern` in this unit (referenced but never defined here) has no
+          # local object symbol, so it becomes an undefined symbol for the
+          # linker, just like an undefined call target.
+          writer.add_undefined_symbol(reloc[:symbol]) unless known_names.include?(reloc[:symbol])
+          writer.add_global_relocation(offset: reloc[:offset], symbol: reloc[:symbol])
+        when :got
+          # A PIC access (-fPIC) through the Global Offset Table: a load of the
+          # address of a symbol this unit does not define — an extern file-scope
+          # object, or an external function whose address is taken — from that
+          # symbol's GOT slot. The symbol becomes an undefined symbol for the
+          # linker to bind (unless another part of this unit defines it); which
+          # relocation addresses the slot is the machine description's business.
+          writer.add_undefined_symbol(reloc[:symbol]) unless known_names.include?(reloc[:symbol])
+          writer.add_got_relocation(offset: reloc[:offset], symbol: reloc[:symbol])
+        end
+      end
+
+      # A `__attribute__((constructor))` / `((destructor))` function becomes a
+      # slot in this object's .init_array / .fini_array pointing at its own text
+      # symbol. Registered after the text loop, so every function symbol the
+      # slots resolve against is already in the symbol table.
+      ir_program.array_entries.each do |entry|
+        writer.add_array_entry(kind: entry.kind, priority: entry.priority, symbol: entry.symbol)
+      end
+
+      writer.set_rodata(rodata) unless rodata.empty?
+      writer.add_text_section(text)
+      writer.to_binary
+    end
+
+    private
+
+    # Pads `buffer` with repetitions of the target's NOP encoding until its
+    # length is a multiple of `alignment`. `filler` may be several bytes wide
+    # (aarch64's NOP is a whole 32-bit word), so the gap is filled in whole
+    # units; a gap that is not a multiple of the filler width cannot arise
+    # because the alignment is a multiple of the instruction size.
+    def pad_to_alignment(buffer, alignment, filler)
+      remainder = buffer.bytesize % alignment
+      return unless remainder.positive?
+
+      buffer << (filler * ((alignment - remainder) / filler.bytesize))
+    end
+
+    # Rounds `value` up to the next multiple of `alignment`.
+    def align_up(value, alignment)
+      (value + alignment - 1) / alignment * alignment
+    end
+
+    # Registers a file-scope object's symbol, choosing the internal-linkage
+    # (STB_LOCAL) writer entry for a `static` object and the global one
+    # otherwise.
+    def add_object_symbol(writer, internal, name, section, offset, size, visibility: :default)
+      if internal
+        writer.add_local_object(name, section, offset, size)
+      else
+        writer.add_global_object(name, section, offset, size, visibility: visibility)
+      end
+    end
+
+    # Registers one global-image relocation with the ELF writer, translating a
+    # within-global slot offset into a .data-section offset. A :symbol reloc
+    # points at another object's symbol (an absolute 64-bit address, plus the
+    # relocation's own byte displacement for a computed "&arr[i]"); a :string
+    # reloc points into .rodata, its addend the interned string's byte offset
+    # plus that same displacement.
+    def register_data_relocation(writer, reloc, global_offset, string_offsets)
+      case reloc.kind
+      when :symbol
+        writer.add_data_relocation(offset: global_offset + reloc.offset,
+                                   symbol: reloc.symbol, addend: reloc.addend)
+      when :string
+        writer.add_data_rodata_relocation(offset: global_offset + reloc.offset,
+                                          addend: string_offsets[reloc.string_id] + reloc.addend)
+      end
+    end
+
+    public
+
+    # Convenience: read `input_path`, compile it and write the object to
+    # `output_path`.
+    def self.compile_file(input_path, output_path, include_paths: [], pic: false, defines: [],
+                          system_includes: true, target: "x86_64",
+                          libc: Preprocess::Preprocessor.host_libc,
+                          default_visibility: :default)
+      source = File.read(input_path)
+      binary = new.compile(source, filename: input_path, include_paths: include_paths,
+                                   pic: pic, defines: defines, system_includes: system_includes,
+                                   target: target, libc: libc,
+                                   default_visibility: default_visibility)
+      File.binwrite(output_path, binary)
+      output_path
+    end
+  end
+end

data/lib/rubycc/doctor/builder.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "open3"
+require "fileutils"
+require "timeout"
+require "tmpdir"
+
+require_relative "fetcher"
+
+module Rubycc
+  module Doctor
+    # The on-the-fly build a gem gets when it is not in the verified database: the
+    # same path RubyGems takes for a `gem install`, driven by hand so each stage's
+    # outcome can be reported separately.
+    #
+    # Per gem: fetch the .gem, read its real extensions list; with none it needs
+    # no C toolchain (no_ext). For each extension, run its extconf.rb with the
+    # mkmf_shim loaded (so mkmf's conftests and the Makefile it writes route to
+    # rubycc), then build the generated Makefile with rmake (which always
+    # substitutes rubycc for the compiler/linker). On success the freshly built
+    # .so is required in a child process to prove its Init function dlopens.
+    #
+    # A failure is pinned to a stage — extconf, compile, link, require or the
+    # per-gem timeout — with a short summary of the tool's stderr.
+    class Builder
+      # Repository lib/ (this file lives at lib/rubycc/doctor/) and the executables
+      # the build shells out to.
+      REPO_LIB   = File.expand_path("../..", __dir__)
+      REPO_ROOT  = File.expand_path("../../..", __dir__)
+      RMAKE_EXE  = File.join(REPO_ROOT, "exe", "rmake")
+      MKMF_SHIM_REQUIRE = "-rrubycc/mkmf_shim"
+
+      # The outcome of building one gem.
+      #   status  : :no_ext | :built | :failed | :unknown
+      #   stage   : nil, or the failing stage (:extconf/:compile/:link/:require/:timeout)
+      #   reason  : short human-readable explanation (stderr summary etc.)
+      #   sos     : produced .so paths (on :built)
+      #   require_ok : whether the require smoke check passed (:built only; a
+      #                failed require does not demote the build — the .so was made —
+      #                but is noted)
+      Result = Struct.new(:status, :stage, :reason, :sos, :require_ok, keyword_init: true)
+
+      # +timeout+ is the per-gem ceiling in seconds. +out+ receives progress lines.
+      def initialize(cache_dir:, timeout: 300, out: nil)
+        @cache_dir = cache_dir
+        @timeout = timeout
+        @out = out
+      end
+
+      # Build +entry+ (a Gemfile::Entry). Returns a Result. Never raises: every
+      # failure mode is folded into a Result the CLI can print.
+      def build(entry)
+        fetcher = Fetcher.new(@cache_dir)
+        version = entry.version || fetcher.latest_version(entry.name)
+        return Result.new(status: :unknown, reason: "could not resolve a version") unless version
+
+        gem_path =
+          begin
+            fetcher.download(entry.name, version)
+          rescue Fetcher::FetchError => e
+            return Result.new(status: :unknown, reason: "fetch failed (offline?): #{e.message}")
+          end
+
+        spec = fetcher.spec(gem_path)
+        return Result.new(status: :no_ext) if spec.extensions.empty?
+
+        Timeout.timeout(@timeout) { build_extensions(entry.name, version, gem_path, spec) }
+      rescue Timeout::Error
+        Result.new(status: :failed, stage: :timeout, reason: "exceeded #{@timeout}s")
+      rescue StandardError => e
+        Result.new(status: :failed, stage: :internal, reason: "#{e.class}: #{e.message}")
+      end
+
+      private
+
+      # Unpack the gem and drive extconf -> rmake -> require for each extension.
+      def build_extensions(name, version, gem_path, spec)
+        dir = File.join(@cache_dir, "#{name}-#{version}")
+        FileUtils.rm_rf(dir)
+        FileUtils.mkdir_p(dir)
+        Gem::Package.new(gem_path).extract_files(dir)
+
+        sos = []
+        spec.extensions.each do |ext_rel|
+          ext_dir = File.join(dir, File.dirname(ext_rel))
+          extconf = File.basename(ext_rel)
+
+          result = build_one(ext_dir, extconf)
+          return result unless result.status == :built
+
+          sos.concat(result.sos)
+        end
+
+        require_ok = sos.all? { |so| require_check(so) }
+        Result.new(status: :built, sos: sos, require_ok: require_ok,
+                   reason: require_ok ? nil : "built, but the require smoke check failed")
+      end
+
+      # extconf -> rmake -> locate .so for a single extension directory.
+      def build_one(ext_dir, extconf)
+        log("extconf: #{ext_dir}/#{extconf}")
+        out, ok = run(RbConfig.ruby, "-I#{REPO_LIB}", MKMF_SHIM_REQUIRE, extconf, chdir: ext_dir)
+        unless ok && File.file?(File.join(ext_dir, "Makefile"))
+          return Result.new(status: :failed, stage: :extconf, reason: summarize(out))
+        end
+
+        log("rmake: #{ext_dir}")
+        out, ok = run(RbConfig.ruby, RMAKE_EXE, chdir: ext_dir)
+        unless ok
+          stage = Dir.glob(File.join(ext_dir, "**", "*.o")).empty? ? :compile : :link
+          return Result.new(status: :failed, stage: stage, reason: summarize(out))
+        end
+
+        sos = Dir.glob(File.join(ext_dir, "**", "*.so"))
+        return Result.new(status: :failed, stage: :link, reason: "rmake reported success but produced no .so") if sos.empty?
+
+        Result.new(status: :built, sos: sos)
+      end
+
+      # Prove the built object dlopens and its Init function runs, in a child
+      # process so a crash cannot take the doctor down. Requiring a .so by absolute
+      # path invokes Init_<basename>, which is the load we want to confirm.
+      def require_check(so)
+        _out, ok = run(RbConfig.ruby, "-e", "require #{so.dump}")
+        ok
+      end
+
+      # Run a command with the build environment, returning [combined_output, ok?].
+      def run(*cmd, chdir: nil)
+        env = { "RUBYLIB" => [REPO_LIB, ENV["RUBYLIB"]].compact.join(File::PATH_SEPARATOR) }
+        opts = {}
+        opts[:chdir] = chdir if chdir
+        out, status = Open3.capture2e(env, *cmd, **opts)
+        [out, status.success?]
+      rescue StandardError => e
+        ["#{e.class}: #{e.message}", false]
+      end
+
+      # The last few non-empty lines of a tool's output — enough to name the error
+      # without dumping a whole build log into the report.
+      def summarize(output)
+        lines = output.to_s.lines.map(&:chomp).reject(&:empty?)
+        lines.last(8).join("\n")
+      end
+
+      def log(msg)
+        @out&.puts("    #{msg}")
+      end
+    end
+  end
+end

data/lib/rubycc/doctor/cli.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "../version"
+
+require_relative "gemfile"
+require_relative "verified_gems"
+require_relative "builder"
+
+module Rubycc
+  module Doctor
+    # `rubycc doctor` — tells a Ruby application developer whether rubycc can
+    # build the C extensions their app depends on.
+    #
+    # It reads the app's Gemfile.lock (or Gemfile), and for each gem: reports it
+    # verified when the shipped build-verified database (data/verified_gems.json)
+    # already covers that name+version; otherwise fetches and builds it on the
+    # spot through the same extconf -> rmake -> rubycc path a real install takes,
+    # reporting exactly where any failure occurred. Gems with no C extension need
+    # rubycc at all and are marked as such.
+    #
+    # The verified check is offline and instant; only unverified gems reach the
+    # network. The bottom line is an adoption verdict and an exit code (0 when
+    # every C-extension gem is verified or built, 1 otherwise).
+    class CLI
+      # Per-status display: symbol + label. Ordering of keys is the report legend.
+      STATUS = {
+        verified:       ["✔", "verified"],
+        built:          ["✔", "built on the spot"],
+        no_ext:         ["-", "no C extension"],
+        failed:         ["✘", "FAILED"],
+        unknown:        ["?", "unknown"],
+        local:          ["-", "local/vcs source (skipped)"],
+        skipped_budget: ["?", "skipped (build budget reached)"]
+      }.freeze
+
+      def self.run(argv, out: $stdout, err: $stderr, verified: nil, builder: nil)
+        new(out: out, err: err, verified: verified, builder: builder).run(argv)
+      end
+
+      def initialize(out:, err:, verified: nil, builder: nil)
+        @out = out
+        @err = err
+        @verified = verified
+        @builder = builder
+      end
+
+      def run(argv)
+        options = parse(argv)
+        return 0 if options[:help]
+
+        result = Gemfile.load(options[:gemfile])
+        unless result
+          @err.puts("rubycc doctor: no Gemfile.lock or Gemfile found at #{options[:gemfile]}")
+          return 2
+        end
+
+        verified = @verified || VerifiedGems.load
+        rows = evaluate(result, verified, options)
+        report(result, rows)
+        exit_code(rows)
+      rescue OptionParser::ParseError => e
+        @err.puts("rubycc doctor: #{e.message}")
+        2
+      end
+
+      private
+
+      # A row of the report: the gem, its resolved status and an optional note.
+      Row = Struct.new(:name, :version, :status, :note, keyword_init: true)
+
+      def parse(argv)
+        options = { gemfile: File.expand_path("Gemfile"), timeout: 300, max_builds: nil }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: rubycc-doctor [options]"
+          # OptionParser answers --version itself, but only once it has been given
+          # one; without this it prints its "version unknown" fallback, which is a
+          # poor answer from a command that does know its version.
+          o.version = Rubycc::VERSION
+          o.on("--gemfile PATH", "Gemfile path (default ./Gemfile; .lock preferred)") { |v| options[:gemfile] = File.expand_path(v) }
+          o.on("--timeout SECONDS", Integer, "Per-gem build timeout (default 300)") { |v| options[:timeout] = v }
+          o.on("--max-builds N", Integer, "Cap the number of on-the-spot builds") { |v| options[:max_builds] = v }
+          o.on("--data PATH", "verified_gems.json path (default: bundled)") { |v| options[:data] = File.expand_path(v) }
+          o.on("-h", "--help", "Show this help") { @out.puts(o); options[:help] = true }
+        end
+        parser.parse(argv)
+        @verified ||= VerifiedGems.load(options[:data]) if options[:data]
+        options
+      end
+
+      # Walk every gem and resolve its status, honouring the build budget.
+      def evaluate(result, verified, options)
+        builder = @builder || Builder.new(cache_dir: build_cache, timeout: options[:timeout], out: @out)
+        builds_done = 0
+
+        result.entries.map do |entry|
+          if entry.source != :gem
+            next Row.new(name: entry.name, version: entry.version, status: :local)
+          end
+
+          # A gem may be verified in more than one environment, so name every
+          # environment that actually covers this version (and the newest date
+          # among them) instead of a single entry-level pair. A non-empty result
+          # is exactly what #match calls verified.
+          hits = verified.matching_verifications(entry.name, entry.version)
+          unless hits.empty?
+            note = "verified #{hits.map(&:verified_at).max} (#{hits.map(&:environment).join('; ')})"
+            next Row.new(name: entry.name, version: entry.version, status: :verified, note: note)
+          end
+
+          if options[:max_builds] && builds_done >= options[:max_builds]
+            next Row.new(name: entry.name, version: entry.version, status: :skipped_budget)
+          end
+
+          @out.puts("  building #{entry.name} #{entry.version}...") if @out
+          bresult = builder.build(entry)
+          builds_done += 1 unless bresult.status == :no_ext
+          Row.new(name: entry.name, version: entry.version, status: bresult.status, note: note_for(bresult))
+        end
+      end
+
+      # The note column for a build result.
+      def note_for(bresult)
+        case bresult.status
+        when :failed  then "#{bresult.stage}: #{bresult.reason}"
+        when :built   then bresult.require_ok ? "require OK" : bresult.reason
+        when :unknown then bresult.reason
+        end
+      end
+
+      def report(result, rows)
+        if result.origin == :gemfile
+          @out.puts("Note: no Gemfile.lock found; parsed #{result.path} for direct gems only " \
+                    "(versions may be missing, dependency closure not resolved).")
+          @out.puts
+        end
+
+        width = rows.map { |r| "#{r.name} #{r.version}".length }.max || 0
+        rows.each do |row|
+          symbol, label = STATUS[row.status]
+          line = format("  %s  %-#{width}s  %s", symbol, "#{row.name} #{row.version}".strip, label)
+          line += "  (#{row.note})" if row.note && !row.note.empty?
+          @out.puts(line)
+        end
+
+        summary(rows)
+      end
+
+      # The adoption verdict: over the gems that actually have C extensions, are
+      # they all handled (verified or built)?
+      def summary(rows)
+        cext = rows.reject { |r| %i[no_ext local].include?(r.status) }
+        failed = cext.count { |r| r.status == :failed }
+        # A gem skipped for the build budget was never checked, so it is
+        # undetermined for adoption purposes, exactly like an offline "unknown".
+        unknown = cext.count { |r| %i[unknown skipped_budget].include?(r.status) }
+        ok = cext.count { |r| %i[verified built].include?(r.status) }
+
+        @out.puts
+        @out.puts("C-extension gems: #{cext.size}  (verified/built #{ok}, failed #{failed}, unknown #{unknown})")
+        @out.puts(
+          if cext.empty?
+            "Verdict: no C-extension gems to build — rubycc is not required."
+          elsif failed.zero? && unknown.zero?
+            "Verdict: ADOPTABLE — every C-extension gem is verified or builds with rubycc."
+          else
+            parts = []
+            parts << "#{failed} to address" if failed.positive?
+            parts << "#{unknown} undetermined" if unknown.positive?
+            "Verdict: NEEDS ATTENTION — #{parts.join(', ')}."
+          end
+        )
+      end
+
+      # Exit 0 only when every C-extension gem is verified or built.
+      def exit_code(rows)
+        cext = rows.reject { |r| %i[no_ext local].include?(r.status) }
+        cext.all? { |r| %i[verified built].include?(r.status) } ? 0 : 1
+      end
+
+      def build_cache
+        require "tmpdir"
+        dir = File.join(Dir.tmpdir, "rubycc-doctor")
+        FileUtils.mkdir_p(dir)
+        dir
+      end
+    end
+  end
+end