rubycc 1.0.0

data/lib/rubycc/preprocess/preprocessor.rb

@@ -0,0 +1,2020 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "scanner"
+require_relative "token_converter"
+require_relative "constant_expression"
+require_relative "glibc_version"
+require_relative "../front/constant_evaluator"
+require_relative "../compile_error"
+
+module Rubycc
+  module Preprocess
+    # Entry point for translation phases 1-4: source text in, a Front::Token
+    # stream out. It scans preprocessing tokens (line splicing and comment
+    # removal), executes directives, expands macros, and converts what remains
+    # into ordinary tokens.
+    #
+    # The macro table and the #include search path are instance state so an
+    # includee shares them with its includer: a translation unit is preprocessed
+    # as a single accumulating pass, with #include recursion feeding an includee's
+    # tokens through the same line-oriented loop. Conditional groups (#if and its
+    # kin) select which lines reach that loop. Both object-like and function-like
+    # macros are expanded (6.10.3), the latter gathering their arguments across
+    # line boundaries; the "#" (stringize) and "##" (paste) operators, the
+    # compiler-supplied macros (__FILE__ and kin), the __has_* queries and
+    # "#pragma once" complete the model.
+    class Preprocessor
+      # The compiler-supplied ("freestanding") headers rubycc ships in the gem's
+      # top-level include/ directory: stdarg.h, stddef.h and kin, which glibc
+      # does not provide because they are the compiler's responsibility. Resolved
+      # relative to this file so it works from a source checkout and an installed
+      # gem alike (preprocess -> rubycc -> lib -> gem root, then include/).
+      BUNDLED_INCLUDE_DIR = File.expand_path("../../../include", __dir__).freeze
+
+      # The bundled libc compatibility headers (R8): rubycc's own copies of the C
+      # library's headers (stdio.h, stdlib.h, string.h and kin), shipped so a
+      # hosted translation unit compiles on a host that lacks the system libc's
+      # development headers (the distroless target). They live in two layers under
+      # include/libc/: a common declaration layer (BUNDLED_LIBC_INCLUDE_DIR) and a
+      # target-specific layer that pins the type widths, struct layouts and macro
+      # values to one concrete libc-and-arch ABI. Two such layers ship today,
+      # glibc/x86-64 and glibc/aarch64; which one is on the search path is chosen
+      # per instance by the `libc_arch` keyword (see #initialize), so a cross
+      # compile reads the target's ABI rather than the host's. This constant names
+      # the x86-64 default's directory -- kept so the default path and the tests
+      # that pin its order can refer to it -- while #default_system_include_paths
+      # substitutes the instance's own arch directory (@libc_arch_include_dir). The
+      # arch layer is searched before the common layer so a same-named header in it
+      # (an ABI-specific override) wins over the shared declaration.
+      # The libc the headers describe is *not* a directory axis: both layers carry
+      # the glibc and the musl value of everything the two disagree on, selected
+      # by #if on LIBC_MUSL_MACRO (see LIBCS), so the directory names below still
+      # say "glibc" only because that is where the files have always lived.
+      BUNDLED_LIBC_ARCH_INCLUDE_DIR = File.expand_path("../../../include/libc/glibc/x86_64", __dir__).freeze
+      BUNDLED_LIBC_INCLUDE_DIR = File.expand_path("../../../include/libc", __dir__).freeze
+
+      # The bundled libc-and-arch layers that ship under include/libc/glibc/;
+      # `libc_arch` (see #initialize) must name one of them.
+      LIBC_ARCHS = %w[x86_64 aarch64].freeze
+
+      # The C libraries the bundled headers can be read under; `libc` (see
+      # #initialize) must name one of them. This is an axis of its own, at right
+      # angles to `libc_arch`: the two libcs disagree on a handful of ABI values
+      # (struct rusage's size, O_ACCMODE, the fast-integer widths, BUFSIZ and
+      # kin) on every machine alike, so the difference is expressed as #if
+      # branches inside the bundled headers rather than as another directory
+      # layer -- fifteen-odd divergences do not justify duplicating a hundred
+      # files whose remaining content is identical, and an #if keeps both
+      # measured values side by side where they can be audited (R8).
+      #
+      # The musl side is complete only for x86-64: the aarch64 arch layer's five
+      # ABI-switched headers carry glibc's values alone, because the musl
+      # figures were measured on x86-64 and an arch layer is exactly where a
+      # value may move between machines (each of those files says so in its own
+      # provenance note). An aarch64 musl target therefore reads musl's common
+      # layer and glibc's arch layer until an aarch64 musl run measures it.
+      LIBCS = %w[glibc musl].freeze
+
+      # The macro the bundled headers select their musl branch on. It is
+      # predefined (to 1) only when `libc` is "musl"; on glibc it stays
+      # undefined, so `#if defined(__RUBYCC_LIBC_MUSL__)` reads "the musl ABI"
+      # and its #else arm is the long-standing glibc one. Unlike the platform
+      # macros it is reserved on *both* settings (see #reject_reserved_name): it
+      # names which ABI the bundled headers were pinned to when the compiler was
+      # configured, so a translation unit that could -D it into existence, or
+      # -U it away, would get headers describing one libc and an object laid out
+      # for the other.
+      LIBC_MUSL_MACRO = "__RUBYCC_LIBC_MUSL__"
+
+      # The libc system header directories, in the order gcc reports them for
+      # angled includes. Only the C library's own directories are listed; the
+      # compiler's private include directory is deliberately absent, because
+      # BUNDLED_INCLUDE_DIR supplies those headers instead.
+      #
+      # The first entry is Debian's multiarch directory, which is named after the
+      # target: `/usr/include/x86_64-linux-gnu` holds the x86-64 `bits/`, and its
+      # AArch64 counterpart holds a different one. It therefore belongs to
+      # `libc_arch` exactly like the bundled arch layer does -- see
+      # LIBC_SYSTEM_INCLUDE_PATHS_FOR, which #libc_system_include_paths uses per
+      # instance. Naming one target here unconditionally was a real defect: an
+      # AArch64 host searched a directory that does not exist and never looked in
+      # its own (GAPS V).
+      LIBC_MULTIARCH_INCLUDE_DIRS = {
+        "x86_64" => "/usr/include/x86_64-linux-gnu",
+        "aarch64" => "/usr/include/aarch64-linux-gnu"
+      }.freeze
+
+      def self.libc_system_include_paths_for(libc_arch)
+        multiarch = LIBC_MULTIARCH_INCLUDE_DIRS.fetch(libc_arch) do
+          raise ArgumentError, "unsupported libc arch: #{libc_arch.inspect}"
+        end
+        [multiarch, "/usr/include"].freeze
+      end
+
+      # The x86-64 baseline, kept as a constant for the same reason
+      # DEFAULT_SYSTEM_INCLUDE_PATHS is: it is the shape every per-instance list
+      # takes, with its own arch in the multiarch slot.
+      LIBC_SYSTEM_INCLUDE_PATHS = libc_system_include_paths_for("x86_64")
+
+      # The default system include search path: the bundled freestanding headers
+      # first (so rubycc's stdarg.h/stddef.h win over any same-named file further
+      # down), then the bundled libc compatibility headers (arch layer before
+      # common layer), then the host libc directories. A bundled libc header thus
+      # wins over the host's same-named one, yet can still reach the host copy via
+      # #include_next, which resumes the search past whichever directory the
+      # bundled header was found in. The host directories stay on the path by
+      # default (they are only dropped in the distroless mode, where they are
+      # absent anyway); the whole default path is appended after the user's
+      # -I/-isystem directories, and suppressed entirely by -nostdinc.
+      #
+      # This is the x86-64 baseline: #default_system_include_paths builds the same
+      # list per instance, substituting the instance's own arch layer for the arch
+      # slot, so a cross compile's path is this shape with a different arch layer.
+      DEFAULT_SYSTEM_INCLUDE_PATHS = [
+        BUNDLED_INCLUDE_DIR,
+        BUNDLED_LIBC_ARCH_INCLUDE_DIR,
+        BUNDLED_LIBC_INCLUDE_DIR,
+        *LIBC_SYSTEM_INCLUDE_PATHS
+      ].freeze
+
+      # The hermetic-headers system search path: the bundled freestanding and
+      # bundled libc layers only, with the host libc directories dropped. Selected
+      # by RUBYCC_HERMETIC_HEADERS (see #default_system_include_paths) so a full
+      # `gem install` can be driven with rubycc's own headers exclusively -- the
+      # distroless posture -- without every conftest command having to pass
+      # -nostdinc explicitly. It is the same set the distroless ruby.h build uses,
+      # so if a translation unit reaches for a declaration only the host's real
+      # headers carry, it fails here the way it would on a headerless image
+      # instead of silently borrowing it from /usr/include. Like
+      # DEFAULT_SYSTEM_INCLUDE_PATHS this is the x86-64 baseline;
+      # #default_system_include_paths builds the per-instance equivalent with the
+      # instance's own arch layer.
+      HERMETIC_SYSTEM_INCLUDE_PATHS = [
+        BUNDLED_INCLUDE_DIR,
+        BUNDLED_LIBC_ARCH_INCLUDE_DIR,
+        BUNDLED_LIBC_INCLUDE_DIR
+      ].freeze
+
+      # The environment variable that switches the default system search path to
+      # the hermetic (bundled-only) set. Any non-empty value other than "0"
+      # enables it; the default (unset) keeps the host libc directories on the
+      # path, so existing behaviour is unchanged.
+      HERMETIC_HEADERS_ENV = "RUBYCC_HERMETIC_HEADERS"
+
+      # A guard against unbounded #include recursion (a header that includes
+      # itself); 200 is comfortably deeper than any sane header nesting.
+      INCLUDE_DEPTH_LIMIT = 200
+
+      # The cumulative ceiling on how many tokens macro expansion may process
+      # across a whole translation unit. Blue-painting (see #expand_tokens) stops
+      # self-reference and mutual recursion, but nothing otherwise bounds an
+      # exponentially expanding macro — the classic "#define B1 B0 B0 ... #define
+      # B40 B39 B39" doubles its output each level, so "B40" would materialize
+      # 2^40 tokens and exhaust CPU and memory long before finishing. Charging one
+      # unit per token pulled from the work queue and tripping this ceiling turns
+      # that runaway into a located CompileError. The bound is a whole-run
+      # cumulative budget (expand_tokens runs once per gathered line and once per
+      # #if condition, and recurses for each argument), so an expansion that
+      # explodes across many small calls is still caught. The real #include
+      # <ruby.h> header graph — the whole CRuby + libc header set, a worst-case
+      # legitimate input — consumes about 137k, so one million leaves a 7x margin
+      # while it never fires on real code. It is deliberately not larger: because
+      # a doubling macro is rejected only after the full budget is processed, the
+      # ceiling also caps the worst-case work a hostile input can force (about
+      # three seconds here), so raising it would trade rejection latency for
+      # headroom no real translation unit needs.
+      EXPANSION_TOKEN_LIMIT = 1_000_000
+
+      # The ceiling on conditional-directive nesting within a single file. A
+      # deeply nested tower of "#if"s is not a stack risk (the frames are held in
+      # a heap array, not on the Ruby stack), but capping it keeps a hostile
+      # source from building an arbitrarily large conditional stack; 256 is far
+      # beyond any real header's conditional nesting.
+      CONDITIONAL_NESTING_LIMIT = 256
+
+      # The ceiling on parenthesis nesting inside a function-like macro's argument
+      # list. #collect_arguments balances parentheses with a plain integer depth
+      # counter (no recursion, so this is not a stack guard), but bounding it
+      # rejects a pathological "M(((((...)))))" up front rather than scanning an
+      # unbounded run. It is generous — a macro argument is a full expression, and
+      # the parser re-checks nesting downstream — so this only trips on clearly
+      # abusive input.
+      MACRO_ARGUMENT_NESTING_LIMIT = 2000
+
+      # The directives that steer a conditional group (6.10.1). They are acted on
+      # whether or not the enclosing group is active, so nesting stays balanced
+      # inside a skipped region; every other directive is inert while skipping.
+      # Kept as a Hash (used only for membership) so the check is O(1).
+      CONDITIONAL_DIRECTIVES = %w[if ifdef ifndef elif else endif].to_h { |name| [name, true] }.freeze
+
+      # One nesting level of a conditional. `active` is whether this frame's
+      # current group is being emitted (its condition held and the frame itself
+      # is reachable); `taken` records whether any group of this #if has been
+      # selected yet, so a later #elif/#else knows to stay inert; `seen_else`
+      # guards against an #elif/#else after the #else; `parent_active` is whether
+      # the enclosing context was active when the #if opened, which freezes the
+      # whole conditional off when it was not. `token` is the opening directive,
+      # for an "unterminated conditional" diagnosed at end of file.
+      Frame = Struct.new(:active, :taken, :seen_else, :parent_active, :token)
+
+      # One entry of the macro table. `kind` is :object or :function; `params`
+      # is the ordered parameter-name list (empty for an object macro, and for a
+      # function macro it excludes any trailing "..."); `variadic` records that a
+      # variable part is present so the rest arguments are meaningful; `va_name`
+      # is the identifier that stands for the rest arguments in the replacement
+      # list -- "__VA_ARGS__" for the ISO bare-"..." form and the written name for
+      # the GNU "name..." form, nil when not variadic; `replacement` is the raw
+      # replacement-list tokens as written.
+      Macro = Struct.new(:kind, :params, :variadic, :replacement, :va_name)
+
+      # One function-like invocation's arguments. `raw` is each argument's
+      # unexpanded tokens (what "#" and "##" operate on), `commas` the top-level
+      # comma tokens between them (kept verbatim so #__VA_ARGS__ can reproduce the
+      # exact spacing), and `expanded` a per-argument memo of the fully expanded
+      # form, filled lazily so an argument used only by "#"/"##" is never expanded.
+      Invocation = Struct.new(:raw, :commas, :expanded)
+
+      # The macros the preprocessor supplies itself (6.10.8): each is expanded
+      # from the use site, so its value cannot be a fixed replacement list stored
+      # at definition time. __GNUC__ is deliberately absent (DESIGN R7), so a
+      # header cannot select a gcc-specific path. None may be redefined or undefined.
+      # Kept as a Hash (used only for membership) so the check is O(1).
+      BUILTIN_MACROS = %w[__FILE__ __LINE__ __STDC__ __STDC_VERSION__ __RUBYCC__].to_h { |name| [name, true] }.freeze
+
+      # The identifiers __has_builtin (6.10.1) answers true for: exactly the
+      # builtins rubycc's front end actually recognizes — the varargs intrinsics,
+      # the branch-prediction hint, the stack allocator, offsetof, the
+      # constant/choose folds, the count-leading/trailing-zero scans, the
+      # unreachable hint, memcpy, the three overflow-checked arithmetic forms,
+      # the nine __atomic_* forms and the ten legacy __sync_* forms. Every other
+      # builtin query is false, so a header that guards a fallback behind
+      # __has_builtin (e.g. json's bswap path) takes the fallback for one rubycc
+      # does not provide. Kept in sync with the parser's builtin keywords. Kept
+      # as a Hash (used only for membership) so the check is O(1).
+      KNOWN_BUILTINS = %w[__builtin_va_start __builtin_va_arg __builtin_va_end __builtin_va_copy
+                          __builtin_expect __builtin_alloca __builtin_offsetof
+                          __builtin_constant_p __builtin_choose_expr
+                          __builtin_ctz __builtin_ctzll __builtin_clz __builtin_clzll
+                          __builtin_unreachable __builtin_memcpy
+                          __builtin_add_overflow __builtin_sub_overflow
+                          __builtin_mul_overflow
+                          __atomic_load_n __atomic_store_n __atomic_exchange_n
+                          __atomic_compare_exchange_n
+                          __atomic_fetch_add __atomic_fetch_sub
+                          __atomic_add_fetch __atomic_sub_fetch
+                          __atomic_or_fetch __atomic_thread_fence
+                          __sync_fetch_and_add __sync_fetch_and_sub
+                          __sync_add_and_fetch __sync_sub_and_fetch
+                          __sync_or_and_fetch __sync_lock_test_and_set
+                          __sync_lock_release __sync_synchronize
+                          __sync_bool_compare_and_swap
+                          __sync_val_compare_and_swap].to_h { |name| [name, true] }.freeze
+
+      # The platform macros gcc keeps predefined even under strict ISO C
+      # (-std=c11): only the reserved forms (a leading underscore followed by
+      # another underscore or an uppercase letter, 7.1.3), so headers relying on
+      # "linux", "unix" or "i386" (the non-reserved spellings, gcc drops these
+      # under -std=c11) still see them undefined here. __GNUC__ is deliberately
+      # excluded (DESIGN R7): rubycc targets Linux/ELF LP64 only, so this fixed
+      # set is enough for glibc's own dispatch (e.g. gnu/stubs.h) to settle on
+      # the right branch, without claiming gcc compatibility beyond that. Unlike
+      # BUILTIN_MACROS these are ordinary #define'd entries in @macros, so a
+      # translation unit may #undef or redefine them (gcc allows this too).
+      #
+      # These are the macros every supported target shares; the CPU-identifying
+      # ones are per-target and arrive through `arch_macros` below.
+      PREDEFINED_PLATFORM_MACROS = %w[__linux__ __gnu_linux__ __unix__ __ELF__
+                                      __LP64__ _LP64 __STDC_HOSTED__].freeze
+
+      # The CPU-identifying macros for each target, the subset of gcc's that
+      # glibc's own headers dispatch on. Getting these from the target rather
+      # than fixing them was forced by the aarch64 backend: a unit compiled for
+      # aarch64 that asked `#ifdef __x86_64__` used to take the x86-64 branch,
+      # and the cross libc headers were being read under the wrong CPU identity.
+      X86_64_ARCH_MACROS = %w[__x86_64__ __amd64__].freeze
+      AARCH64_ARCH_MACROS = %w[__aarch64__ __AARCH64EL__].freeze
+
+      # The numeric macros gcc predefines: the limit/size ones describing the
+      # target's fundamental types, and the memory-order enumerators the
+      # __atomic_* builtins take as an argument (grouped here because they are
+      # the same kind of thing — a fixed integer replacement text a translation
+      # unit may #undef, not a use-site-computed BUILTIN_MACROS entry).
+      # glibc's headers reach for these directly when __GNUC__
+      # is absent (e.g. limits.h's __LONG_MAX__ via ruby's special_consts.h), so
+      # they must carry gcc's exact spellings — value base (hex vs decimal) and
+      # integer suffix — for a gcc-differential #if to agree. The right-hand sides
+      # are the verbatim replacement texts of `gcc -dM -E </dev/null` on this
+      # x86-64 LP64 target; they become ordinary object macros (a translation unit
+      # may #undef or redefine them). __WCHAR_MIN__'s value is a parenthesized
+      # expression referring to another of these, which expands recursively at the
+      # use site like any macro. Only the reserved "__X__" forms are provided;
+      # __GNUC__ and version macros stay absent (DESIGN R7). The replacement text
+      # is re-scanned into pp-tokens rather than hand-built, so multi-token values
+      # need no special casing.
+      PREDEFINED_NUMERIC_MACROS = {
+        "__CHAR_BIT__" => "8",
+        "__SCHAR_MAX__" => "0x7f",
+        "__SHRT_MAX__" => "0x7fff",
+        "__INT_MAX__" => "0x7fffffff",
+        "__LONG_MAX__" => "0x7fffffffffffffffL",
+        "__LONG_LONG_MAX__" => "0x7fffffffffffffffLL",
+        "__WCHAR_MAX__" => "0x7fffffff",
+        "__WCHAR_MIN__" => "(-__WCHAR_MAX__ - 1)",
+        "__WINT_MAX__" => "0xffffffffU",
+        "__WINT_MIN__" => "0U",
+        "__PTRDIFF_MAX__" => "0x7fffffffffffffffL",
+        "__SIZE_MAX__" => "0xffffffffffffffffUL",
+        "__INTMAX_MAX__" => "0x7fffffffffffffffL",
+        "__UINTMAX_MAX__" => "0xffffffffffffffffUL",
+        "__INTPTR_MAX__" => "0x7fffffffffffffffL",
+        "__UINTPTR_MAX__" => "0xffffffffffffffffUL",
+        "__SIZEOF_INT__" => "4",
+        "__SIZEOF_LONG__" => "8",
+        "__SIZEOF_LONG_LONG__" => "8",
+        "__SIZEOF_SHORT__" => "2",
+        "__SIZEOF_POINTER__" => "8",
+        "__SIZEOF_SIZE_T__" => "8",
+        "__SIZEOF_PTRDIFF_T__" => "8",
+        "__SIZEOF_FLOAT__" => "4",
+        "__SIZEOF_DOUBLE__" => "8",
+        "__SIZEOF_WCHAR_T__" => "4",
+        "__SIZEOF_WINT_T__" => "4",
+        # The memory-order arguments the __atomic_* builtins take (C11 7.17.3's
+        # memory_order enumerators, which gcc predefines under these spellings).
+        # The values are the verbatim ones `gcc -dM -E </dev/null` prints on this
+        # target, so a header comparing them (or building one out of another)
+        # agrees with a gcc build. rubycc implements every atomic operation at
+        # the strongest order regardless of which of these is passed — see
+        # IR::Generator#gen_builtin_atomic — but the constants must still carry
+        # gcc's values, because a caller may compute with them.
+        "__ATOMIC_RELAXED" => "0",
+        "__ATOMIC_CONSUME" => "1",
+        "__ATOMIC_ACQUIRE" => "2",
+        "__ATOMIC_RELEASE" => "3",
+        "__ATOMIC_ACQ_REL" => "4",
+        "__ATOMIC_SEQ_CST" => "5"
+      }.freeze
+
+      # The libc this host's C library is: "musl" or "glibc" (see LIBCS). Read
+      # from RbConfig's arch triplet, which is how MRI itself distinguishes a
+      # musl build ("x86_64-linux-musl") from a glibc one ("x86_64-linux") --
+      # the same source test/abi_harness/harness.rb's #host_libc and
+      # tools/verify_gem_tests.rb's environment_string read, so the compiler,
+      # the ABI harness and the verification records all agree on what "this
+      # environment" is. It is the default for `libc` below, which is what makes
+      # an unconfigured compile on a musl host read the musl branches; a cross
+      # compile passes the target's own.
+      def self.host_libc
+        RbConfig::CONFIG["arch"].to_s.include?("musl") ? "musl" : "glibc"
+      end
+
+      # The glibc version macros, predefined on a glibc target so the bundled
+      # <features.h> does not have to name a version it cannot know. __GLIBC__
+      # is a constant (glibc's major has been 2 since 1997); the minor is
+      # measured from the C library the compile will link against, because a
+      # single shipped header set otherwise reports one host's version on every
+      # host, and a version gate then selects a branch the local libc may not be
+      # able to back (docs/development/GAPS.md gap U).
+      GLIBC_MAJOR_MACRO = "__GLIBC__"
+      GLIBC_MINOR_MACRO = "__GLIBC_MINOR__"
+      GLIBC_MAJOR = 2
+
+      # The measured glibc minor version for the `libc_arch` target, or nil when
+      # this host offers nothing to measure (see GlibcVersion). nil is not an
+      # error and not a substitute value: the two macros are then left
+      # undefined, and the bundled <features.h> supplies its own fallback pair
+      # -- the reference platform's 2.39 -- exactly as it did before this was
+      # measured at all. Keeping the fallback in the header rather than
+      # repeating the number here also keeps a header read outside rubycc (or
+      # under -nostdinc with the host's own headers) on the same value.
+      def self.host_glibc_minor(libc_arch = "x86_64")
+        GlibcVersion.minor_for(libc_arch)
+      end
+
+      # `char_unsigned` says whether plain `char` is unsigned on the target being
+      # compiled for (it is under AAPCS64, and is not under the x86-64 System V
+      # psABI, hence the default). When it is, __CHAR_UNSIGNED__ joins the
+      # predefined macros with the value gcc gives it, so a header can select the
+      # same branch it would there — the bundled <limits.h> uses exactly that to
+      # pick CHAR_MIN/CHAR_MAX.
+      # `arch_macros` names the target's CPU-identifying macros (see
+      # X86_64_ARCH_MACROS); it defaults to x86-64's, the default target.
+      # `libc_arch` selects which bundled libc-and-arch header layer sits on the
+      # default search path ("x86_64" or "aarch64", see LIBC_ARCHS); it defaults to
+      # x86-64 so an unconfigured host compile is byte-for-byte unchanged, and a
+      # cross compile passes the target's own so its ABI headers (struct stat's
+      # 128-byte aarch64 layout, the narrower nlink_t/blksize_t, the unsigned
+      # WCHAR_MIN/MAX and kin) are read instead of the host's.
+      # `libc` selects which C library's ABI those bundled headers describe
+      # ("glibc" or "musl", see LIBCS); it defaults to the host's own (see
+      # .host_libc), and on "musl" it predefines LIBC_MUSL_MACRO so the headers
+      # take their musl branches.
+      # `glibc_minor` is the glibc minor version the version macros are to
+      # report on a glibc target; it defaults to the one measured from the C
+      # library that target links against (see .host_glibc_minor), and nil --
+      # which is also what an unmeasurable host yields -- leaves both macros
+      # undefined for the bundled <features.h> to fall back on. It is a keyword
+      # so a caller can pin a version deliberately (a cross compile against a
+      # sysroot this host cannot search, and the tests' fallback case). The
+      # default measures only on a glibc target: on "musl" the value is unused,
+      # and reading a C library to answer a question nobody asks would cost
+      # every musl translation unit a megabyte-scale read for nothing.
+      def initialize(char_unsigned: false, arch_macros: X86_64_ARCH_MACROS, libc_arch: "x86_64",
+                     libc: Preprocessor.host_libc,
+                     glibc_minor: (libc == "glibc" ? Preprocessor.host_glibc_minor(libc_arch) : nil))
+        unless LIBC_ARCHS.include?(libc_arch)
+          raise ArgumentError, "unsupported libc arch: #{libc_arch.inspect} (expected one of #{LIBC_ARCHS.join(", ")})"
+        end
+        unless LIBCS.include?(libc)
+          raise ArgumentError, "unsupported libc: #{libc.inspect} (expected one of #{LIBCS.join(", ")})"
+        end
+        unless glibc_minor.nil? || (glibc_minor.is_a?(Integer) && !glibc_minor.negative?)
+          raise ArgumentError, "glibc minor version must be a non-negative Integer or nil: #{glibc_minor.inspect}"
+        end
+
+        # The bundled libc arch layer this instance searches (see
+        # BUNDLED_LIBC_ARCH_INCLUDE_DIR). For the x86-64 default it equals that
+        # constant, so the default search path is identical to before.
+        @libc_arch_include_dir = File.expand_path("../../../include/libc/glibc/#{libc_arch}", __dir__)
+        # The host libc directories this instance searches. The multiarch slot
+        # follows the same `libc_arch` as the bundled layer above, so a compile
+        # never looks for another target's `bits/` (GAPS V).
+        @libc_system_include_paths = self.class.libc_system_include_paths_for(libc_arch)
+        # name (String) => Macro.
+        @macros = {}
+        (arch_macros + PREDEFINED_PLATFORM_MACROS).each { |name| @macros[name] = predefined_target_macro }
+        @macros["__CHAR_UNSIGNED__"] = predefined_target_macro if char_unsigned
+        @macros[LIBC_MUSL_MACRO] = predefined_target_macro if libc == "musl"
+        PREDEFINED_NUMERIC_MACROS.each { |name, text| @macros[name] = predefined_numeric_macro(text) }
+        # The glibc version pair, defined only on a glibc target and only when
+        # the version could be measured. They are ordinary numeric macros like
+        # the ones above (a translation unit may #undef or redefine them), and
+        # the bundled <features.h> defines each only when it is absent, so this
+        # is what makes a version gate agree with the host's own headers. On
+        # musl, and when nothing could be measured, nothing is defined here and
+        # <features.h> keeps supplying the reference platform's pair, which is
+        # what every compile did before the measurement existed.
+        if libc == "glibc" && glibc_minor
+          @macros[GLIBC_MAJOR_MACRO] = predefined_numeric_macro(GLIBC_MAJOR.to_s)
+          @macros[GLIBC_MINOR_MACRO] = predefined_numeric_macro(glibc_minor.to_s)
+        end
+        @include_depth = 0
+        # Absolute paths of files that asked (via "#pragma once") to be read at
+        # most once; a later #include resolving to one of them is skipped.
+        @pragma_once = {}
+        # Absolute path => index into @include_paths of the -I directory a file
+        # was found in. Only files resolved along the search path get an entry
+        # (the main source file and a quote-relative resolution beside its
+        # includer never do), which is exactly what #include_next needs to tell
+        # "resume the search past here" from "there is no here" (GNU extension).
+        @include_origin = {}
+        # Resolved include path (the exact spelling #include resolves to) =>
+        # that file's scanned pp-token array. Scanning (phases 2-3) is a pure
+        # function of the file's bytes — no macro state reaches it — and both
+        # PPToken and the directive walk are non-mutating (painting copies), so
+        # one scan per header serves every re-#include verbatim. This is where
+        # a real unit burns most of its time otherwise: ruby.h's include graph
+        # re-includes the same headers hundreds of times, and each guard-skipped
+        # body still had to be re-scanned to find its #endif (Step 108).
+        @scan_cache = {}
+        # Resolved include path => the file's include-guard macro name, or nil
+        # when its shape rules the optimization out (gcc's multiple-include
+        # optimization, Step 109). A header whose entire significant content is
+        # wrapped in one "#ifndef G ... #endif" (or "#if !defined(G)") behaves,
+        # when G is defined, exactly like an empty file: the walk would activate
+        # nothing and change no state. So a re-#include whose recorded guard is
+        # currently defined skips the directive walk outright. Detection is a
+        # pure function of the scanned tokens (see #detect_include_guard); the
+        # skip consults the live macro table, so an #undef of the guard makes
+        # the next #include process the file again.
+        @guard_cache = {}
+      end
+
+      def run(source, filename:, include_paths: [], defines: [], system_includes: true)
+        TokenConverter.new.convert(
+          preprocess(source, filename: filename, include_paths: include_paths,
+                             defines: defines, system_includes: system_includes)
+        )
+      end
+
+      # Runs translation phases 1-4 and returns the resulting preprocessing-token
+      # stream (terminated by the unit's :eof), before it is converted into
+      # Front tokens. It is what #run builds on, and what the `-E` driver mode
+      # re-spells into preprocessed text. `defines` is the ordered command-line
+      # `-D`/`-U` list (see #apply_command_line_definitions).
+      # `system_includes` (the default) appends the compiler-supplied and libc
+      # directories after the caller's -I/-isystem set, so an angled #include of
+      # <stdarg.h> or a libc header resolves with no explicit -I; the driver's
+      # -nostdinc passes it false to search only the caller's directories.
+      def preprocess(source, filename:, include_paths: [], defines: [], system_includes: true)
+        system_paths = system_includes ? default_system_include_paths : []
+        @system_include_paths = system_paths.map { |path| File.expand_path(path) }
+        @include_paths = include_paths + system_paths
+        # #resolve_include's cache keys a resolved path off @include_paths (and,
+        # for quote includes, the includer's directory), so it must start empty
+        # every run rather than survive across calls with a different search path.
+        @resolve_cache = {}
+        # The whole-run macro-expansion budget (see EXPANSION_TOKEN_LIMIT), reset
+        # here so every translation unit starts with a full allowance.
+        @expansion_tokens = 0
+        # The presumed-line state a #line directive sets (6.10.4): a delta added
+        # to a token's physical line for __LINE__, and a presumed file name for
+        # __FILE__ (nil = the token's own file). It is per-file, saved and
+        # restored across #include (see #process_include).
+        @presumed_line_delta = 0
+        @presumed_file = nil
+        apply_command_line_definitions(defines)
+        pp_tokens = Scanner.new(source, filename: filename).scan
+        output = []
+        process_lines(pp_tokens, filename, output)
+        # process_lines stops at the unit's end-of-file marker without emitting
+        # it; carry it through so the converter can terminate its stream.
+        output << pp_tokens.last
+        output
+      end
+
+      private
+
+      # The system search path appended after the caller's -I/-isystem set: the
+      # full default (bundled headers ahead of the host libc directories), or the
+      # hermetic bundled-only set when RUBYCC_HERMETIC_HEADERS selects it. The arch
+      # slot is this instance's @libc_arch_include_dir rather than the fixed
+      # constant, so a cross compile searches the target's ABI layer; for the
+      # x86-64 default the result equals DEFAULT_SYSTEM_INCLUDE_PATHS /
+      # HERMETIC_SYSTEM_INCLUDE_PATHS exactly. The environment is read per call
+      # rather than cached so a process can flip the mode between translation units
+      # (the mkmf conftest sequence does not, but a test driving several compiles
+      # in-process may).
+      def default_system_include_paths
+        bundled = [BUNDLED_INCLUDE_DIR, @libc_arch_include_dir, BUNDLED_LIBC_INCLUDE_DIR]
+        return bundled if hermetic_headers?
+
+        [*bundled, *@libc_system_include_paths]
+      end
+
+      def hermetic_headers?
+        value = ENV[HERMETIC_HEADERS_ENV]
+        !value.nil? && !value.empty? && value != "0"
+      end
+
+      # Applies the driver's command-line `-D`/`-U` requests before the source is
+      # read, in the order they were given (so a later `-U` undoes an earlier
+      # `-D`, as gcc does). Each is turned into the directive it stands for and
+      # run through the ordinary directive machinery — `-DNAME` into
+      # `#define NAME 1`, `-DNAME=VALUE` into `#define NAME VALUE` (the split on
+      # the first `=` keeps a function-like `-DF(x)=…` intact), and `-UNAME` into
+      # `#undef NAME` — so redefinition and validation behave exactly as an
+      # in-source directive would. Their (empty) output is discarded; only the
+      # effect on the shared macro table matters.
+      def apply_command_line_definitions(defines)
+        return if defines.empty?
+
+        preamble = defines.map { |op, arg| command_line_directive(op, arg) }.join("\n") + "\n"
+        tokens = Scanner.new(preamble, filename: "<command-line>").scan
+        process_lines(tokens, "<command-line>", [])
+      end
+
+      def command_line_directive(op, arg)
+        case op
+        when :define
+          name, value = arg.split("=", 2)
+          "#define #{name} #{value || "1"}"
+        when :undef
+          "#undef #{arg}"
+        end
+      end
+
+      # Walks one file's preprocessing tokens a logical line at a time. A line
+      # whose first token is "#" is a directive (6.10); every other line has its
+      # tokens macro-expanded into `output`, but only while every enclosing
+      # conditional is active. `stack` is this file's conditional nesting; a
+      # frame it opens must be closed in the same file (a #include appears only on
+      # an active line and runs with its own fresh stack), so any frame still open
+      # at end of file is an unterminated conditional.
+      #
+      # A function-like macro invocation may span several physical lines, so the
+      # tokens of a run of consecutive active non-directive lines (newlines and
+      # all) are gathered and expanded together. A directive line, an inactive
+      # region, or end of file ends the run: activeness only ever changes at a
+      # directive, so a run is uniformly active, and a call left open where a run
+      # ends is diagnosed there (a directive splitting an argument list is 6.10.3
+      # undefined behavior). Newlines are dropped by the expander, so the output
+      # stream stays free of them.
+      def process_lines(tokens, filename, output)
+        stack = []
+        index = 0
+        at_line_start = true
+        run = []
+        while index < tokens.length
+          tok = tokens[index]
+          break if tok.eof?
+
+          if tok.newline?
+            run << tok if active?(stack)
+            at_line_start = true
+            index += 1
+          elsif at_line_start && tok.punct?("#")
+            expand_run(run, output)
+            run = []
+            index = process_directive(tokens, index, filename, output, stack)
+            at_line_start = true
+          else
+            at_line_start = false
+            run << tok if active?(stack)
+            index += 1
+          end
+        end
+        expand_run(run, output)
+        raise_at(stack.last.token, "unterminated conditional directive") unless stack.empty?
+      end
+
+      def expand_run(run, output)
+        expand_tokens(run, output) unless run.empty?
+      end
+
+      # Whether output is currently being emitted: true unless some enclosing
+      # conditional selected against it. A frame's `active` already folds in its
+      # parents' state, so only the innermost need be consulted.
+      def active?(stack)
+        stack.empty? || stack.last.active
+      end
+
+      # Dispatches the directive that "#" at `hash_index` introduces and returns
+      # the index of the first token past its terminating newline. A conditional
+      # directive is always acted on (it may re-activate a skipped region or nest
+      # inside it); every other directive, and even a malformed one, is silently
+      # dropped while skipping, matching how gcc discards an excluded group whole.
+      # An empty directive line (just "#") is the null directive (6.10p2).
+      def process_directive(tokens, hash_index, filename, output, stack)
+        hash = tokens[hash_index]
+        args, next_index = collect_line(tokens, hash_index + 1)
+        return next_index if args.empty?
+
+        name = args[0]
+        body = args[1..]
+        if name.type == :identifier && CONDITIONAL_DIRECTIVES.key?(name.text)
+          dispatch_conditional(name, body, stack)
+          return next_index
+        end
+        return next_index unless active?(stack)
+
+        unless name.type == :identifier
+          raise_at(name, "invalid preprocessing directive '##{name.text}'")
+        end
+
+        case name.text
+        when "include"      then handle_include(hash, body, output, filename)
+        when "include_next" then handle_include_next(hash, body, output, filename)
+        when "define"       then handle_define(name, body)
+        when "undef"        then handle_undef(name, body)
+        when "line"         then handle_line(name, body)
+        when "error"        then handle_error(hash, body)
+        when "pragma"       then handle_pragma(body, filename)
+        else
+          raise_at(name, "invalid preprocessing directive '##{name.text}'")
+        end
+        next_index
+      end
+
+      # --- conditional inclusion (6.10.1) ----------------------------------------
+
+      def dispatch_conditional(name, body, stack)
+        case name.text
+        when "if"     then handle_if(name, body, stack, :if)
+        when "ifdef"  then handle_if(name, body, stack, :ifdef)
+        when "ifndef" then handle_if(name, body, stack, :ifndef)
+        when "elif"   then handle_elif(name, body, stack)
+        when "else"   then handle_else(name, stack)
+        when "endif"  then handle_endif(name, stack)
+        end
+      end
+
+      # Opens a new conditional frame. Its first group's condition is only
+      # evaluated when the enclosing context is active; inside a skipped region
+      # the frame is pushed inert (never taken, so no #elif/#else can revive it)
+      # and the condition is left unread, so an undefined name or bad expression
+      # there is not diagnosed (6.10.1p6, and matching gcc).
+      def handle_if(name, body, stack, kind)
+        if stack.length >= CONDITIONAL_NESTING_LIMIT
+          raise_at(name, "#{name.text} directives nested too deeply")
+        end
+
+        if active?(stack)
+          condition = evaluate_group(name, body, kind)
+          stack.push(Frame.new(condition, condition, false, true, name))
+        else
+          stack.push(Frame.new(false, true, false, false, name))
+        end
+      end
+
+      def evaluate_group(name, body, kind)
+        case kind
+        when :if     then evaluate_if_expression(name, body)
+        when :ifdef  then defined_condition(name, body, true)
+        when :ifndef then defined_condition(name, body, false)
+        end
+      end
+
+      def handle_elif(name, body, stack)
+        raise_at(name, "#elif without #if") if stack.empty?
+
+        frame = stack.last
+        raise_at(name, "#elif after #else") if frame.seen_else
+        # Only evaluate when the enclosing context is active and no earlier group
+        # of this #if was taken; otherwise this branch cannot win, so its
+        # expression is left unevaluated (and undiagnosed).
+        if frame.parent_active && !frame.taken
+          condition = evaluate_if_expression(name, body)
+          frame.active = condition
+          frame.taken = true if condition
+        else
+          frame.active = false
+        end
+      end
+
+      def handle_else(name, stack)
+        raise_at(name, "#else without #if") if stack.empty?
+
+        frame = stack.last
+        raise_at(name, "#else after #else") if frame.seen_else
+        frame.seen_else = true
+        # The else group is taken exactly when the context is active and nothing
+        # earlier was; either way no further group of this #if can be selected.
+        frame.active = frame.parent_active && !frame.taken
+        frame.taken = true
+      end
+
+      def handle_endif(name, stack)
+        raise_at(name, "#endif without #if") if stack.empty?
+
+        stack.pop
+      end
+
+      # #ifdef/#ifndef NAME: NAME must be a lone identifier, and the frame is
+      # active when the macro's presence in the table matches the sense wanted.
+      def defined_condition(name, body, want_defined)
+        raise_at(name, "no macro name given in ##{name.text} directive") if body.empty?
+
+        macro = body[0]
+        raise_at(macro, "macro names must be identifiers") unless macro.type == :identifier
+        raise_at(body[1], "extra tokens at end of ##{name.text} directive") if body.length > 1
+        # gcc makes "#ifdef" of the __has_* query operators true, and a header
+        # uses that to prefer the operator over a config.h fallback. They are
+        # safe to expose because each answers honestly — __has_builtin says 0
+        # for a builtin rubycc lacks, and a header __has_include reports present
+        # is one rubycc can now compile (the gcc alternate keywords the kernel
+        # UAPI headers lean on, "__signed__" and kin, are recognized).
+        defined_macro_name?(macro.text) == want_defined
+      end
+
+      # Whether `defined`/#ifdef/#ifndef sees NAME as a macro (6.10.8p1): an
+      # ordinary entry in the macro table, one of the self-supplied builtins
+      # (__FILE__ etc., 6.10.8.1) that never occupies a table slot because its
+      # value is computed at the use site, or a __has_* query operator (gcc
+      # extension both directives share, see query_operator_name?).
+      def defined_macro_name?(name)
+        @macros.key?(name) || BUILTIN_MACROS.key?(name) || query_operator_name?(name)
+      end
+
+      # Evaluates a #if/#elif controlling constant-expression (6.10.1) to a
+      # boolean. In order: fold each preprocessor operator (`defined` and the
+      # `__has_*` queries) to 1/0 with its operand unexpanded, macro-expand what
+      # remains, fold operators a second time (a header may hide a __has_* query
+      # behind a macro, e.g. RBIMPL_HAS_BUILTIN(x) -> __has_builtin(x), so the
+      # operator only surfaces after expansion; gcc likewise re-honors a
+      # macro-produced `defined`), then replace every surviving identifier with 0,
+      # convert to ordinary tokens, and evaluate the parsed expression with the
+      # shared constant evaluator. A non-zero result is true. One post-expansion
+      # pass suffices: fold_operators never expands its own operands, so a query
+      # it uncovers cannot itself reveal another.
+      def evaluate_if_expression(directive, body)
+        raise_at(directive, "##{directive.text} with no expression") if body.empty?
+
+        expanded = []
+        expand_tokens(fold_operators(body), expanded)
+        refolded = fold_operators(expanded)
+        neutral = refolded.map { |tok| tok.type == :identifier ? number_zero(tok) : tok }
+        tokens = to_front_tokens(neutral, directive)
+        node = ConstantExpressionParser.new(tokens, directive.text).parse
+        evaluate_constant(node)
+      end
+
+      # Converts the neutralized expression tokens to the Front::Token stream the
+      # expression parser consumes, terminating it with an :eof. A floating
+      # constant is not an integer constant-expression, so it is rejected here
+      # (6.10.1p1) before it can reach the evaluator.
+      def to_front_tokens(pp_tokens, directive)
+        tokens = TokenConverter.new.convert(pp_tokens)
+        floating = tokens.find { |tok| tok.type == :float }
+        raise_at_front(floating, "floating constant in preprocessor expression") if floating
+        tokens << Front::Token.new(type: :eof, value: nil, filename: directive.filename,
+                                   line: directive.line, column: directive.column,
+                                   source_line: directive.source_line)
+        tokens
+      end
+
+      def evaluate_constant(node)
+        Front::ConstantEvaluator.evaluate(node) != 0
+      rescue Front::ConstantEvaluator::DivisionByZero => e
+        raise_at_front(e.token, "division by zero in preprocessor expression")
+      rescue Front::ConstantEvaluator::NotConstant => e
+        raise_at_front(e.token, "token is not valid in preprocessor expressions")
+      end
+
+      # Rewrites each preprocessor operator in a #if expression to the pp-number 1
+      # or 0, its operand left unexpanded (6.10.1p1, p4): `defined` against the
+      # macro table, `__has_include` against the include search, `__has_attribute`
+      # true only for the layout attributes rubycc honors (aligned/packed), and
+      # `__has_builtin`
+      # true only for the varargs intrinsics. Any other token passes through to be
+      # macro-expanded (an unrecognized identifier later neutralizes to 0).
+      def fold_operators(body)
+        result = []
+        index = 0
+        while index < body.length
+          tok = body[index]
+          if tok.type == :identifier && (handler = PP_OPERATORS[tok.text])
+            value, index = send(handler, tok, body, index + 1)
+            result << number_flag(tok, value)
+          else
+            result << tok
+            index += 1
+          end
+        end
+        result
+      end
+
+      # Each #if operator's fold method, keyed by its spelling.
+      PP_OPERATORS = {
+        "defined" => :fold_defined, "__has_include" => :fold_has_include,
+        "__has_attribute" => :fold_has_attribute, "__has_builtin" => :fold_has_builtin
+      }.freeze
+
+      def fold_defined(operator, body, index)
+        name, index = read_defined_operand(operator, body, index)
+        [defined_macro_name?(name), index]
+      end
+
+      # gcc treats the __has_* query operators as satisfying `defined`, so
+      # `#if defined(__has_builtin)` is 1 there; a header uses that to prefer
+      # the operator over a config.h fallback (ruby/internal/has/builtin.h).
+      # The `defined` operator itself is not answered here (only the __has_*
+      # queries), so this excludes it from PP_OPERATORS.
+      def query_operator_name?(name)
+        PP_OPERATORS.key?(name) && name != "defined"
+      end
+
+      # __has_include ( "f" | <f> ): true when the header resolves like the same
+      # #include would (quote relative to this file, then the search path).
+      def fold_has_include(operator, body, index)
+        raise_at(operator, "missing '(' after '__has_include'") unless body[index]&.punct?("(")
+
+        close = closing_paren(operator, body, index)
+        kind, name = parse_header_name(operator, body[(index + 1)...close])
+        [include_exists?(kind, name, operator.filename), close + 1]
+      end
+
+      # The GNU attributes rubycc gives real semantics: the layout attributes the
+      # parser honors on a struct/union (Step 28), and the constructor/destructor
+      # attributes that register a function in .init_array / .fini_array (Step
+      # 155). Every other attribute is accepted and discarded, so __has_attribute
+      # answers true only for these. Kept as a Hash (used only for membership) so
+      # the check is O(1).
+      KNOWN_ATTRIBUTES = %w[aligned packed constructor destructor].to_h { |name| [name, true] }.freeze
+
+      # __has_attribute ( X ): true for the attributes rubycc actually acts on
+      # (in either the plain or the "__name__" spelling), false for every other
+      # name. The name is normalized the same way the parser normalizes an
+      # attribute token.
+      def fold_has_attribute(operator, body, index)
+        name, index = read_paren_identifier(operator, body, index, "__has_attribute")
+        [KNOWN_ATTRIBUTES.key?(normalize_attribute_name(name)), index]
+      end
+
+      # Collapses a "__name__" attribute spelling to "name" (a single leading and
+      # trailing "__" pair stripped when both are present), matching the parser's
+      # #normalize_attribute_name so "__aligned__" and "aligned" agree here too.
+      def normalize_attribute_name(name)
+        if name.start_with?("__") && name.end_with?("__") && name.length > 4
+          name[2..-3]
+        else
+          name
+        end
+      end
+
+      def fold_has_builtin(operator, body, index)
+        name, index = read_paren_identifier(operator, body, index, "__has_builtin")
+        [KNOWN_BUILTINS.key?(name), index]
+      end
+
+      # The index of the ")" that closes the "(" at `index`; the operand between
+      # them is a header name, which has no nested parentheses.
+      def closing_paren(operator, body, index)
+        close = index + 1
+        close += 1 until body[close].nil? || body[close].punct?(")")
+        raise_at(operator, "missing ')' after '#{operator.text}'") if body[close].nil?
+        close
+      end
+
+      # Reads a "( identifier )" operand for the __has_* attribute/builtin queries,
+      # returning [identifier-text, index-past-")"].
+      def read_paren_identifier(operator, body, index, what)
+        name = body[index + 1]
+        unless body[index]&.punct?("(") && name&.type == :identifier && body[index + 2]&.punct?(")")
+          raise_at(operator, "operator '#{what}' requires a parenthesized identifier")
+        end
+        [name.text, index + 3]
+      end
+
+      # Whether a header name resolves without reading it: quote form beside the
+      # querying file then along the search path, angled form only the latter.
+      def include_exists?(kind, name, includer)
+        directories = []
+        directories << File.dirname(includer) if kind == :quote
+        directories.concat(@include_paths)
+        directories.any? { |dir| File.file?(File.join(dir, name)) }
+      end
+
+      # Reads the operand of a `defined` operator starting at `index`, returning
+      # [macro-name, index-past-operand]. Accepts NAME or ( NAME ).
+      def read_defined_operand(directive, body, index)
+        if body[index]&.punct?("(")
+          name = body[index + 1]
+          unless name && name.type == :identifier && body[index + 2]&.punct?(")")
+            raise_at(directive, "operator 'defined' requires an identifier")
+          end
+          [name.text, index + 3]
+        else
+          name = body[index]
+          raise_at(directive, "operator 'defined' requires an identifier") unless name&.type == :identifier
+
+          [name.text, index + 1]
+        end
+      end
+
+      def number_flag(site, present)
+        number_token(site, present ? "1" : "0")
+      end
+
+      def number_zero(site)
+        number_token(site, "0")
+      end
+
+      def number_token(site, text)
+        PPToken.new(
+          type: :pp_number, text: text,
+          filename: site.filename, line: site.line, column: site.column,
+          source_line: site.source_line, space_before: site.space_before
+        )
+      end
+
+      # A PREDEFINED_TARGET_MACROS entry: an ordinary object macro whose sole
+      # replacement token is the pp-number "1". Its position ("<built-in>", line
+      # 0) is a placeholder that no diagnostic ever surfaces: #substitute always
+      # relocates a replacement token to the invocation site via #relocate
+      # before it can reach the token stream, so this position only ever exists
+      # transiently inside the macro table.
+      def predefined_target_macro
+        token = PPToken.new(
+          type: :pp_number, text: "1",
+          filename: "<built-in>", line: 0, column: 0, source_line: ""
+        )
+        Macro.new(:object, [], false, [token])
+      end
+
+      # A PREDEFINED_NUMERIC_MACROS entry: an ordinary object macro whose
+      # replacement is `text` re-scanned into pp-tokens, so a multi-token value
+      # (like __WCHAR_MIN__'s parenthesized expression) becomes a proper token
+      # list without hand-building each token. The scanner appends an :eof (and
+      # never a newline for a single line), dropped here. As with the target
+      # macros the tokens carry a placeholder "<built-in>" location that #relocate
+      # replaces with the use site before any diagnostic could reference it.
+      def predefined_numeric_macro(text)
+        tokens = Scanner.new(text, filename: "<built-in>").scan.reject(&:eof?)
+        Macro.new(:object, [], false, tokens)
+      end
+
+      # The tokens of the logical line starting at `start` (up to but excluding
+      # the newline), paired with the index just past that newline. A line ended
+      # by end-of-file yields the eof index so the caller's loop can stop there.
+      def collect_line(tokens, start)
+        stop = start
+        stop += 1 until tokens[stop].newline? || tokens[stop].eof?
+        rest = tokens[start...stop]
+        next_index = tokens[stop].newline? ? stop + 1 : stop
+        [rest, next_index]
+      end
+
+      # --- #include ----------------------------------------------------------
+
+      def handle_include(hash, body, output, includer)
+        kind, name = parse_include_name(hash, body)
+        path = resolve_include(kind, name, includer, hash)
+        process_include(hash, name, path, output)
+      end
+
+      # #include_next NAME (GNU extension): like #include, but the search for
+      # NAME resumes just past the -I directory `includer` itself was found in,
+      # rather than starting over from the front of the list. It exists so a
+      # header can shadow a same-named one further down the search path while
+      # still #including that later copy (gcc's fixinclude wrappers use it on
+      # limits.h and syslimits.h). Both "NAME" and <NAME> are accepted, but
+      # unlike a plain #include the quote form does not additionally search
+      # `includer`'s own directory (gcc's behavior).
+      def handle_include_next(hash, body, output, includer)
+        kind, name = parse_include_name(hash, body)
+        path = resolve_include_next(kind, name, includer, hash)
+        process_include(hash, name, path, output)
+      end
+
+      # Reads and processes the header resolved to `path`, shared by #include
+      # and #include_next once each has found its file.
+      def process_include(hash, name, path, output)
+        # A header that asked for "#pragma once" is read at most once per unit; a
+        # later #include resolving to the same file is silently skipped (6.10.6).
+        return if @pragma_once.key?(File.expand_path(path))
+
+        # A guarded header whose guard macro is currently defined would emit
+        # nothing and change nothing — skip its walk entirely (see @guard_cache).
+        guard = @guard_cache[path]
+        return if guard && @macros.key?(guard)
+
+        raise_at(hash, "#include nested too deeply") if @include_depth >= INCLUDE_DEPTH_LIMIT
+
+        @include_depth += 1
+        # A #line presumption is per-file (6.10.4): the includee starts with its
+        # own natural line/file numbering, and the includer's presumption resumes
+        # when the include returns.
+        saved_delta = @presumed_line_delta
+        saved_file = @presumed_file
+        @presumed_line_delta = 0
+        @presumed_file = nil
+        begin
+          # The includee's tokens carry its own filename and line numbers (N3), so
+          # a diagnostic raised inside it points at the header, not the includer.
+          # A header's scan is cached under its resolved spelling: the token
+          # array is reused read-only across re-#includes (see @scan_cache),
+          # while the directive walk below still runs each time so conditional
+          # inclusion sees the current macro state.
+          tokens = @scan_cache[path] ||=
+            Scanner.new(read_source(path, name, hash), filename: path).scan
+          process_lines(tokens, path, output)
+          # Analyze the guard shape once per file, after a successful walk.
+          @guard_cache[path] = detect_include_guard(tokens) unless @guard_cache.key?(path)
+        ensure
+          @presumed_line_delta = saved_delta
+          @presumed_file = saved_file
+          @include_depth -= 1
+        end
+      end
+
+      # Decides whether a scanned file has the classic include-guard shape: its
+      # first significant line opens "#ifndef G" (or "#if !defined(G)" /
+      # "#if !defined G") and the matching "#endif" is the last significant
+      # thing in the file. Returns G's name, or nil for any other shape. Two
+      # disqualifiers matter for correctness, not just fit: an #else/#elif on
+      # the guard level would make the file emit *different* content when the
+      # guard is defined (so skipping would be wrong), and tokens after the
+      # closing #endif would be lost by a skip. The C23 #elifdef/#elifndef
+      # spellings are rejected the same way, defensively — this compiler does
+      # not process them, but a guard analysis must not assume that. Purely
+      # syntactic over the token array: like the scan itself, the answer never
+      # depends on macro state, so it is computed once per file.
+      def detect_include_guard(tokens)
+        index = 0
+        index += 1 while tokens[index]&.newline?
+        return nil unless tokens[index]&.punct?("#")
+
+        args, index = collect_line(tokens, index + 1)
+        name = guard_macro_name(args)
+        return nil if name.nil?
+
+        depth = 1
+        at_line_start = true
+        while index < tokens.length
+          tok = tokens[index]
+          break if tok.eof?
+
+          if tok.newline?
+            at_line_start = true
+            index += 1
+          elsif at_line_start && tok.punct?("#")
+            args, index = collect_line(tokens, index + 1)
+            directive = args[0]
+            next unless directive&.type == :identifier
+
+            case directive.text
+            when "if", "ifdef", "ifndef"
+              depth += 1
+            when "elif", "else", "elifdef", "elifndef"
+              return nil if depth == 1
+            when "endif"
+              depth -= 1
+              if depth.zero?
+                index += 1 while tokens[index]&.newline?
+                return tokens[index].nil? || tokens[index].eof? ? name : nil
+              end
+            end
+          else
+            at_line_start = false
+            index += 1
+          end
+        end
+        # Ran out before the guard closed: malformed (or truncated) file; the
+        # directive walk owns the diagnostic, this is simply not a guard.
+        nil
+      end
+
+      # The macro a candidate guard line tests, or nil when the line is not one
+      # of the two recognized spellings.
+      def guard_macro_name(args)
+        directive = args[0]
+        return nil unless directive&.type == :identifier
+
+        if directive.text == "ifndef"
+          return args[1].text if args.length == 2 && args[1].type == :identifier
+        elsif directive.text == "if"
+          rest = args[1..]
+          bang = rest[0]&.punct?("!") && rest[1]&.type == :identifier && rest[1].text == "defined"
+          return nil unless bang
+          return rest[2].text if rest.length == 3 && rest[2].type == :identifier
+          if rest.length == 5 && rest[2].punct?("(") && rest[3].type == :identifier && rest[4].punct?(")")
+            return rest[3].text
+          end
+        end
+        nil
+      end
+
+      # Parses a #include/#include_next operand. A directly written header-name
+      # is already complete and is kept verbatim: in particular, identifiers
+      # inside `<...>` are not accidentally expanded. Otherwise the operand is
+      # macro-expanded and the resulting token sequence must form a header-name
+      # (6.10.2); this is what permits `#define H "extconf.h"` followed by
+      # `#include H`, as emitted by mkmf for pg.
+      def parse_include_name(hash, body)
+        return parse_header_name(hash, body) if direct_header_name?(body)
+
+        expanded = []
+        expand_tokens(body, expanded)
+        parse_header_name(hash, expanded)
+      end
+
+      # Whether `body` is already a complete quoted or angled header-name. The
+      # scanner does not treat header-names specially, so an angled form arrives
+      # as "<" ... ">". A malformed direct form is deliberately left for the
+      # macro-expansion path: a macro can legally supply the missing pieces.
+      def direct_header_name?(body)
+        return true if body.length == 1 && body[0].type == :string
+
+        return false unless body.first&.punct?("<")
+
+        body.index { |token| token.punct?(">") } == body.length - 1
+      end
+
+      # Reconstructs a header name from a complete token sequence. The
+      # characters are taken verbatim (6.10.2), never macro-expanded here; the
+      # caller has already decided whether expansion was needed.
+      def parse_header_name(hash, body)
+        raise_at(hash, "#include expects \"FILENAME\" or <FILENAME>") if body.empty?
+
+        first = body[0]
+        if first.type == :string
+          raise_at(body[1], "extra tokens at end of #include directive") if body.length > 1
+          [:quote, first.text[1..-2]]
+        elsif first.punct?("<")
+          close = body.index { |t| t.punct?(">") }
+          raise_at(first, "missing terminating > character") if close.nil?
+          if close < body.length - 1
+            raise_at(body[close + 1], "extra tokens at end of #include directive")
+          end
+          name = body[1...close].map(&:text).join
+          raise_at(first, "empty filename in #include directive") if name.empty?
+          [:angle, name]
+        else
+          raise_at(first, "#include expects \"FILENAME\" or <FILENAME>")
+        end
+      end
+
+      # Resolves a header name to a filesystem path. A quoted include is looked
+      # for first beside the file that names it, then along the search path; an
+      # angled include only along the search path (6.10.2p2-3). A match found
+      # along the search path records which directory it came from, so a later
+      # #include_next from this same file knows where to resume.
+      #
+      # The same header name is resolved over and over within one translation
+      # unit (each use site re-#includes it, guarded headers included, before
+      # Step 109's scan cache short-circuits their body), so successful lookups
+      # are memoized in @resolve_cache. A quote include's cache key carries the
+      # includer's directory since the "beside" candidate is includer-relative;
+      # an angle include's key is just the name, since it never consults the
+      # includer. A cache hit skips #record_include_origin: the first resolution
+      # already recorded whatever origin this same path implies.
+      def resolve_include(kind, name, includer, hash)
+        key = kind == :quote ? [File.dirname(includer), name] : name
+        cached = @resolve_cache[key]
+        return cached if cached
+
+        if kind == :quote
+          beside = File.join(File.dirname(includer), name)
+          if File.file?(beside)
+            @resolve_cache[key] = beside
+            return beside
+          end
+        end
+
+        index, path = search_include_paths(name, 0)
+        raise_at(hash, "#{name}: No such file or directory") unless path
+
+        record_include_origin(path, index)
+        @resolve_cache[key] = path
+        path
+      end
+
+      # Resolves a header name for #include_next: search resumes one directory
+      # past wherever `includer` itself was found along the search path. A file
+      # with no recorded origin (the main source file, or a quote-relative
+      # resolution beside its includer) has no "here" to resume past, so gcc
+      # falls back to plain #include semantics for it, which this does too.
+      def resolve_include_next(kind, name, includer, hash)
+        origin = @include_origin[File.expand_path(includer)]
+        return resolve_include(kind, name, includer, hash) unless origin
+
+        index, path = search_include_paths(name, origin + 1)
+        raise_at(hash, "#{name}: No such file or directory") unless path
+
+        record_include_origin(path, index)
+        path
+      end
+
+      # The first directory in @include_paths, starting the scan at `start`,
+      # holding `name`; returns [its index, the joined path] or [nil, nil].
+      def search_include_paths(name, start)
+        @include_paths.each_with_index do |dir, index|
+          next if index < start
+
+          candidate = File.join(dir, name)
+          return [index, candidate] if File.file?(candidate)
+        end
+        [nil, nil]
+      end
+
+      def record_include_origin(path, index)
+        @include_origin[File.expand_path(path)] = index
+      end
+
+      def read_source(path, name, hash)
+        File.read(path)
+      rescue SystemCallError
+        raise_at(hash, "#{name}: No such file or directory")
+      end
+
+      # --- #define / #undef ------------------------------------------------------
+
+      def handle_define(directive, body)
+        raise_at(directive, "no macro name given in #define directive") if body.empty?
+
+        name = body[0]
+        raise_at(name, "macro names must be identifiers") unless name.type == :identifier
+        reject_reserved_name(name, "define")
+
+        rest = body[1..]
+        first = rest[0]
+        # A "(" abutting the name with no separating space opens a parameter list
+        # (function-like); a space before it, or its absence, makes an object
+        # macro whose replacement merely begins with that token.
+        macro =
+          if first && first.punct?("(") && !first.space_before
+            parse_function_macro(name, rest)
+          else
+            Macro.new(:object, [], false, rest)
+          end
+        validate_replacement(macro)
+
+        existing = @macros[name.text]
+        if existing.nil?
+          @macros[name.text] = macro
+        elsif !identical_macro?(existing, macro) &&
+              !compatible_restrict_redefinition?(name.text, existing, macro) &&
+              !system_header_redefinition?(name)
+          # A benign redefinition (an identical definition) is allowed; a
+          # differing one is an error (6.10.3p2, simplified to token spellings).
+          raise_at(name, "macro '#{name.text}' redefined")
+        else
+          # Ruby's musl config.h and libpq's pg_config.h use the two reserved
+          # spellings of the same restrict qualifier. Keep the later spelling
+          # so subsequent expansion follows the header that most recently
+          # established the platform contract.
+          @macros[name.text] = macro
+        end
+      end
+
+      # GCC accepts the musl/Ruby and libpq pair of restrict definitions as a
+      # harmless portability difference: `__restrict__` and `__restrict` are
+      # both recognized by the front end as the same ignored qualifier. Do not
+      # weaken ordinary macro redefinition diagnostics for any other spelling.
+      def compatible_restrict_redefinition?(name, existing, replacement)
+        return false unless name == "restrict"
+        return false unless existing.kind == :object && replacement.kind == :object
+
+        spellings = ["__restrict", "__restrict__"]
+        [existing.replacement, replacement.replacement].all? do |tokens|
+          tokens.length == 1 && tokens.first.type == :identifier && spellings.include?(tokens.first.text)
+        end
+      end
+
+      # GCC diagnoses a conflicting redefinition from a system header as a
+      # warning, not a preprocessing error. Rubycc has no warning stream, so
+      # keep the header's later definition and continue; this is required by
+      # libffi, whose target header changes FFI_GO_CLOSURES after fiddle's local
+      # compatibility header intentionally set it to zero. User-source
+      # conflicts retain the strict diagnostic above.
+      def system_header_redefinition?(name)
+        filename = name.filename.to_s
+        return false if filename.empty? || filename.start_with?("<")
+
+        path = File.expand_path(filename)
+        @system_include_paths.any? { |root| path == root || path.start_with?("#{root}/") }
+      end
+
+      # Parses a function-like macro's parameter list, `rest` being the tokens
+      # after the macro name with rest[0] the opening "(". Returns the Macro, its
+      # `replacement` the tokens past the closing ")". The list is a comma-
+      # separated run of identifiers, optionally empty, optionally ending in a
+      # variable part: the ISO bare "..." (spelled "__VA_ARGS__" in the body, and
+      # "(...)" alone is allowed) or the GNU "name..." (a parameter name fused to
+      # "...", spelled by that name in the body).
+      def parse_function_macro(name, rest)
+        params = []
+        variadic = false
+        va_name = nil
+        index = 1
+        unless rest[index]&.punct?(")")
+          loop do
+            token = rest[index]
+            if token&.punct?("...")
+              variadic = true
+              va_name = "__VA_ARGS__"
+              index += 1
+              break
+            elsif token&.type == :identifier
+              raise_at(token, "duplicate macro parameter \"#{token.text}\"") if params.include?(token.text)
+
+              # A "name..." names the variable part; the name owns the rest
+              # arguments and no further parameters may follow it.
+              if rest[index + 1]&.punct?("...")
+                variadic = true
+                va_name = token.text
+                index += 2
+                break
+              end
+
+              params << token.text
+              index += 1
+            else
+              raise_at(token || name, "expected parameter name in macro parameter list")
+            end
+
+            separator = rest[index]
+            if separator&.punct?(",")
+              index += 1
+            elsif separator&.punct?(")")
+              break
+            else
+              raise_at(separator || name, "expected ',' or ')' in macro parameter list")
+            end
+          end
+          raise_at(rest[index] || name, "missing ')' in macro parameter list") unless rest[index]&.punct?(")")
+        end
+        Macro.new(:function, params, variadic, rest[(index + 1)..] || [], va_name)
+      end
+
+      # Checks a replacement list for well-formed "#" and "##" placement at
+      # definition time (6.10.3.2p1, 6.10.3.3p1). "##" may not sit at either end
+      # of any replacement list; in a function-like macro "#" must be followed by
+      # a parameter (or __VA_ARGS__), the only operands it can stringize. In an
+      # object-like macro "#" is an ordinary token, so it is left unexamined.
+      def validate_replacement(macro)
+        rep = macro.replacement
+        edge = rep.first if rep.first&.punct?("##")
+        edge ||= rep.last if rep.last&.punct?("##")
+        raise_at(edge, "'##' cannot appear at either end of a macro expansion") if edge
+
+        return unless macro.kind == :function
+
+        rep.each_with_index do |tok, index|
+          next unless tok.punct?("#")
+
+          operand = rep[index + 1]
+          raise_at(tok, "'#' is not followed by a macro parameter") unless parameter_ref?(macro, operand)
+        end
+      end
+
+      # Whether `tok` names one of `macro`'s parameters, counting the variable
+      # part's name (ISO "__VA_ARGS__" or the GNU "name...") as a parameter; the
+      # two spellings "#" and "##" may take.
+      def parameter_ref?(macro, tok)
+        return false unless tok&.type == :identifier
+
+        macro.params.include?(tok.text) || variadic_ref?(macro, tok)
+      end
+
+      # A macro name may not shadow a builtin (6.10.8.4) nor be the "defined"
+      # operator (6.10.1p4); both diagnose rather than silently redefine. The
+      # libc-selecting macro is refused the same way, on either libc setting: it
+      # records the ABI the bundled headers were pinned to at configuration
+      # time, so a unit that could define or undefine it would read one libc's
+      # headers while the rest of the compile assumed the other's.
+      def reject_reserved_name(name, verb)
+        if name.text == "defined"
+          raise_at(name, "\"defined\" cannot be used as a macro name")
+        elsif BUILTIN_MACROS.key?(name.text) || name.text == LIBC_MUSL_MACRO
+          verb = verb == "define" ? "define" : "undefine"
+          raise_at(name, "cannot #{verb} builtin macro \"#{name.text}\"")
+        end
+      end
+
+      def handle_undef(directive, body)
+        raise_at(directive, "no macro name given in #undef directive") if body.empty?
+
+        name = body[0]
+        raise_at(name, "macro names must be identifiers") unless name.type == :identifier
+        reject_reserved_name(name, "undef")
+        raise_at(body[1], "extra tokens at end of #undef directive") if body.length > 1
+        # Undefining a name that was never a macro is not an error (6.10.3.5p2).
+        @macros.delete(name.text)
+      end
+
+      # Two definitions are the same when their kind, parameter names, variadic
+      # flag, variable-part name and replacement-list spellings all agree
+      # (6.10.3p1-2); the name distinguishes an ISO from a GNU named variadic.
+      def identical_macro?(one, other)
+        one.kind == other.kind && one.variadic == other.variadic &&
+          one.va_name == other.va_name && one.params == other.params &&
+          identical_replacement?(one.replacement, other.replacement)
+      end
+
+      def identical_replacement?(one, other)
+        return false unless one.length == other.length
+
+        one.zip(other).all? { |a, b| a.type == b.type && a.text == b.text }
+      end
+
+      # --- #error ----------------------------------------------------------------
+
+      def handle_error(hash, body)
+        # The message is the directive's tokens spelled out and single-spaced; it
+        # is never macro-expanded (matching gcc).
+        message = body.map(&:text).join(" ")
+        raise_at(hash, message.empty? ? "#error" : message)
+      end
+
+      # --- #line -----------------------------------------------------------------
+
+      # Acts on a "#line" directive (6.10.4). Its arguments are macro-expanded
+      # first (6.10.4p5), then read as a digit sequence and an optional string:
+      # the *next* source line is presumed to be that line number, and the
+      # presumed file name is changed when a string is given (kept otherwise).
+      # Both feed __LINE__ / __FILE__ (see #expand_builtin) and diagnostic
+      # wording; the physical tokens keep their real positions, only the
+      # presumption changes. A file that generates code with #line markers (e.g.
+      # gperf's zonetab.h "#line 1 \"zonetab.list\"") relies on this being
+      # accepted rather than a hard error.
+      def handle_line(directive, body)
+        raise_at(directive, "#line directive requires a positive integer argument") if body.empty?
+
+        expanded = []
+        expand_tokens(body, expanded)
+
+        number = expanded[0]
+        unless number&.type == :pp_number && number.text.match?(/\A[0-9]+\z/)
+          raise_at(number || directive, "#line directive requires a positive integer argument")
+        end
+        line_no = number.text.to_i
+
+        presumed_file = @presumed_file
+        rest = expanded[1..]
+        unless rest.empty?
+          file = rest[0]
+          unless file.type == :string && file.text.start_with?('"')
+            raise_at(file, "invalid filename in #line directive")
+          end
+          raise_at(rest[1], "extra tokens at end of #line directive") if rest.length > 1
+          presumed_file = decode_line_filename(file.text)
+        end
+
+        # The next physical line (the directive's line + 1) is presumed to be
+        # `line_no`, so a token on physical line P presents as
+        # line_no + (P - (directive.line + 1)) = P + (line_no - directive.line - 1).
+        @presumed_line_delta = line_no - directive.line - 1
+        @presumed_file = presumed_file
+      end
+
+      # The raw name a #line filename string literal denotes: its surrounding
+      # quotes removed and its \" and \\ escapes resolved, so __FILE__ (which
+      # re-escapes a raw value) reproduces the original name.
+      def decode_line_filename(spelling)
+        spelling[1..-2].gsub(/\\(["\\])/, '\1')
+      end
+
+      # --- #pragma ---------------------------------------------------------------
+
+      # Acts on a "#pragma" (6.10.6). "#pragma once" records the current file so a
+      # future #include of it is skipped; every other pragma (including a bare
+      # one) is accepted and discarded. The "_Pragma" operator form (6.10.9) is
+      # handled during rescanning; see #consume_pragma_operator.
+      def handle_pragma(body, filename)
+        first = body[0]
+        return unless first&.type == :identifier && first.text == "once"
+
+        @pragma_once[File.expand_path(filename)] = true
+      end
+
+      # --- macro expansion -------------------------------------------------------
+
+      # Expands `tokens` into `output` by rescanning (6.10.3.4). The tokens are
+      # driven through a work queue: the head is examined and, when it names a
+      # macro it is not painted against, replaced in place by its (rescannable)
+      # substitution, which is pushed back on the front so the next turn sees it.
+      # Anything that is not an active macro name is emitted; newlines are the
+      # inter-line glue of a gathered run and never reach the output.
+      #
+      # Painting is per token: an object macro, and every literal token of a
+      # function macro's replacement, is painted with the macro's own name added
+      # to the token it came from, so that name cannot expand again through it
+      # (this alone halts self-reference and mutual recursion). Argument tokens
+      # keep their own painting untouched, which is what lets a macro name that
+      # arrives from an argument still expand in its new surroundings.
+      def expand_tokens(tokens, output)
+        queue = tokens.dup
+        until queue.empty?
+          tok = queue.shift
+          # Charge one unit of the whole-run expansion budget per token examined.
+          # A macro's substitution is pushed back onto the queue and re-examined,
+          # so an exponentially expanding macro is charged for every token it
+          # generates and trips this ceiling instead of running away.
+          @expansion_tokens += 1
+          if @expansion_tokens > EXPANSION_TOKEN_LIMIT
+            raise_at(tok, "macro expansion is too large (possible runaway or exponentially expanding macro)")
+          end
+          if pragma_operator?(tok)
+            consume_pragma_operator(tok, queue)
+          elsif expandable_builtin?(tok)
+            queue.unshift(*expand_builtin(tok))
+          elsif expandable_macro?(tok)
+            macro = @macros[tok.text]
+            if macro.kind == :object
+              queue.unshift(*substitute(tok, macro, nil))
+            else
+              expand_function_macro(tok, macro, queue, output)
+            end
+          elsif !tok.newline?
+            output << tok
+          end
+        end
+      end
+
+      # Whether `tok` should expand now: an identifier naming a macro that its own
+      # painting does not forbid (6.10.3.4).
+      def expandable_macro?(tok)
+        tok.type == :identifier && @macros.key?(tok.text) && !tok.suppress.include?(tok.text)
+      end
+
+      # Whether `tok` names a compiler-supplied macro (6.10.8). These cannot be
+      # redefined (rejected at #define), so the user table never hides one; and
+      # each expands to a non-identifier, so it can neither recurse nor need paint.
+      def expandable_builtin?(tok)
+        tok.type == :identifier && BUILTIN_MACROS.key?(tok.text)
+      end
+
+      # Whether `tok` is the "_Pragma" operator (6.10.9). It is handled during
+      # rescanning, not as a directive, so it works whether written literally or
+      # produced by macro expansion (Ruby's config.h defines its symbol-export
+      # markers as "_Pragma(...)"), which is exactly the case that must be
+      # accepted for <ruby.h> to preprocess.
+      def pragma_operator?(tok)
+        tok.type == :identifier && tok.text == "_Pragma"
+      end
+
+      # Consumes a "_Pragma ( string-literal )" operator and drops all four
+      # tokens. The operand would destringize into a #pragma line, but the only
+      # pragma this compiler acts on is "once", which is meaningless mid-file via
+      # _Pragma, so every operand is accepted and ignored (ROADMAP's "accept
+      # only"). Newlines between the tokens are inter-token whitespace. A "_Pragma"
+      # not followed by a parenthesized string literal is a hard error.
+      def consume_pragma_operator(operator, queue)
+        skip_queued_newlines(queue)
+        malformed_pragma(operator) unless queue.first&.punct?("(")
+        queue.shift # "("
+        skip_queued_newlines(queue)
+        malformed_pragma(operator) unless queue.first&.type == :string
+        queue.shift # the string literal (ignored)
+        skip_queued_newlines(queue)
+        malformed_pragma(operator) unless queue.first&.punct?(")")
+        queue.shift # ")"
+      end
+
+      def skip_queued_newlines(queue)
+        queue.shift while queue.first&.newline?
+      end
+
+      def malformed_pragma(operator)
+        raise_at(operator, "_Pragma takes a parenthesized string literal")
+      end
+
+      # The single token a builtin macro stands for at its use site: the current
+      # file and line (6.10.8.1), or a fixed conformance constant. __FILE__ is the
+      # source name as a string literal with " and \ escaped; __LINE__ the line as
+      # a preprocessing number.
+      def expand_builtin(tok)
+        token =
+          case tok.text
+          # __FILE__/__LINE__ honor any #line presumption in force (6.10.4): the
+          # presumed file overrides the token's own, and the presumed-line delta
+          # shifts its physical line. Both are the identity until a #line runs.
+          when "__FILE__"         then string_token(tok, @presumed_file || tok.filename)
+          when "__LINE__"         then number_token(tok, (tok.line + @presumed_line_delta).to_s)
+          when "__STDC__"         then number_token(tok, "1")
+          when "__STDC_VERSION__" then number_token(tok, "201112L")
+          when "__RUBYCC__"       then number_token(tok, "1")
+          end
+        [token]
+      end
+
+      # A string-literal preprocessing token whose spelling encodes `value`, its
+      # embedded " and \ escaped so the converter reads back the original text.
+      def string_token(site, value)
+        PPToken.new(
+          type: :string, text: quote(value),
+          filename: site.filename, line: site.line, column: site.column,
+          source_line: site.source_line, space_before: site.space_before
+        )
+      end
+
+      def quote(value)
+        "\"#{value.gsub(/["\\]/) { |ch| "\\#{ch}" }}\""
+      end
+
+      # Handles a function-like macro name pulled from the queue. A name not
+      # followed (across any newlines) by "(" is a plain identifier, not a call
+      # (6.10.3p10), so it is emitted as is. Otherwise the arguments up to the
+      # matching ")" are consumed and checked, then the painted substitution is
+      # pushed back on the queue for rescanning. Arguments are carried both raw
+      # (for "#"/"##") and, lazily, pre-expanded, so each is expanded at most once.
+      def expand_function_macro(tok, macro, queue, output)
+        unless call_follows?(queue)
+          output << tok
+          return
+        end
+
+        raw, commas = collect_arguments(tok, queue)
+        raw = match_arity(tok, macro, raw)
+        invocation = Invocation.new(raw, commas, Array.new(raw.length))
+        queue.unshift(*substitute(tok, macro, invocation))
+      end
+
+      # Whether the next non-newline token waiting in `queue` opens an argument
+      # list; a call may sit on a later line than its macro name.
+      def call_follows?(queue)
+        index = 0
+        index += 1 while queue[index]&.newline?
+        queue[index] ? queue[index].punct?("(") : false
+      end
+
+      # Consumes the argument list of a call: the leading newlines and "(" already
+      # confirmed by #call_follows?, then tokens up to the matching ")", split on
+      # top-level commas. Nested parentheses are balanced so a comma or ")" inside
+      # them belongs to an argument, and a newline is inter-token space that is
+      # dropped. Returns [arguments, commas]: the argument token lists and the
+      # separating comma tokens themselves (kept so #__VA_ARGS__ can reproduce the
+      # exact spelling). Running out of tokens is an unterminated invocation.
+      def collect_arguments(tok, queue)
+        queue.shift while queue.first&.newline?
+        queue.shift # the "("
+        arguments = []
+        commas = []
+        current = []
+        depth = 0
+        loop do
+          raise_at(tok, "unterminated function-like macro invocation") if queue.empty?
+
+          token = queue.shift
+          if token.newline?
+            next
+          elsif depth.zero? && token.punct?(")")
+            arguments << current
+            return [arguments, commas]
+          elsif depth.zero? && token.punct?(",")
+            arguments << current
+            commas << token
+            current = []
+          else
+            if token.punct?("(")
+              depth += 1
+              if depth > MACRO_ARGUMENT_NESTING_LIMIT
+                raise_at(token, "macro argument parentheses nested too deeply")
+              end
+            end
+            depth -= 1 if token.punct?(")")
+            current << token
+          end
+        end
+      end
+
+      # Checks a call's argument count against the macro and returns the argument
+      # list to substitute. A parameterless macro admits only "F()", which the
+      # collector reports as one empty argument and which is normalized to none. A
+      # variadic macro needs at least its named parameters, its variable part
+      # possibly empty; a plain one needs exactly its parameters.
+      def match_arity(tok, macro, arguments)
+        named = macro.params.length
+        if named.zero? && !macro.variadic
+          return [] if arguments.length == 1 && arguments[0].empty?
+
+          raise_at(tok, "macro \"#{tok.text}\" passed #{arguments.length} arguments, but takes just 0")
+        elsif macro.variadic
+          raise_at(tok, arity_message(tok, arguments.length, named, "at least")) if arguments.length < named
+        elsif arguments.length != named
+          raise_at(tok, arity_message(tok, arguments.length, named, "exactly"))
+        end
+        arguments
+      end
+
+      def arity_message(tok, given, wanted, qualifier)
+        "macro \"#{tok.text}\" requires #{qualifier} #{wanted} arguments, but #{given} given"
+      end
+
+      # Fully expands one argument's tokens in isolation (6.10.3.1) before it is
+      # substituted, reusing the same queue algorithm; the tokens keep their own
+      # painting, since the macro being called is not yet in play for them.
+      def expand_argument(argument)
+        expanded = []
+        expand_tokens(argument, expanded)
+        expanded
+      end
+
+      # Builds a macro's substitution by walking its replacement list once
+      # (6.10.3). `invocation` carries a function-like call's arguments, or is nil
+      # for an object-like macro. "#" stringizes the following parameter's raw
+      # argument; "##" pastes the token to its left onto the operand to its right;
+      # a plain parameter becomes its pre-expanded argument, unless it abuts a
+      # "##", where the raw argument is used instead (6.10.3.1p1); every other
+      # token is a literal relocated to the use site and painted with the macro's
+      # name. `span` tracks how many tokens the token just placed contributed, so
+      # a following "##" knows its left operand (0 marks a placemarker).
+      def substitute(tok, macro, invocation)
+        painted = paint(tok)
+        rep = macro.replacement
+        result = []
+        span = 0
+        index = 0
+        while index < rep.length
+          cur = rep[index]
+          following_paste = rep[index + 1]&.punct?("##")
+          if macro.kind == :function && cur.punct?("#")
+            result << stringize(cur, painted, raw_operand(macro, invocation, rep[index + 1]))
+            span = 1
+            index += 2
+          elsif cur.punct?("##")
+            operand = rep[index + 1]
+            if gnu_comma_paste?(macro, invocation, rep[index - 1], operand)
+              span = comma_paste(macro, invocation, result, tok, painted)
+            else
+              right = paste_operand(macro, invocation, operand, tok, painted)
+              span = paste(result, span, right, tok, painted)
+            end
+            index += 2
+          else
+            placed = replacement_tokens(macro, invocation, cur, tok, painted, raw: following_paste)
+            result.concat(placed)
+            span = placed.length
+            index += 1
+          end
+        end
+        result
+      end
+
+      # The tokens a plain (non-operator) replacement element expands to: a
+      # parameter's argument (raw when it abuts "##", else pre-expanded and
+      # memoized), the variable arguments for __VA_ARGS__, or the element itself
+      # relocated and painted.
+      def replacement_tokens(macro, invocation, rep, site, painted, raw:)
+        param = parameter_index(macro, rep)
+        if param
+          raw ? invocation.raw[param] : expanded_argument(invocation, param)
+        elsif variadic_ref?(macro, rep)
+          raw ? raw_variadic(macro, invocation) : variable_arguments(site, macro, invocation, painted)
+        else
+          [relocate(rep, site, painted)]
+        end
+      end
+
+      # The raw (unexpanded) tokens the "#"/"##" operand `operand` denotes: a
+      # parameter's argument or the reconstructed variable-argument sequence. The
+      # operand was checked at #define time to be a parameter or __VA_ARGS__.
+      def raw_operand(macro, invocation, operand)
+        param = parameter_index(macro, operand)
+        param ? invocation.raw[param] : raw_variadic(macro, invocation)
+      end
+
+      # The tokens forming the right side of a "##": a parameter's raw argument
+      # (possibly empty, i.e. a placemarker), or a single relocated literal.
+      def paste_operand(macro, invocation, operand, site, painted)
+        if invocation && parameter_ref?(macro, operand)
+          raw_operand(macro, invocation, operand)
+        else
+          [relocate(operand, site, painted)]
+        end
+      end
+
+      def parameter_index(macro, rep)
+        rep.type == :identifier ? macro.params.index(rep.text) : nil
+      end
+
+      # Whether `rep` is the identifier standing for the variable arguments: the
+      # macro's `va_name` (ISO "__VA_ARGS__" or the GNU written name). In a named
+      # form "__VA_ARGS__" is an ordinary identifier and does not match here.
+      def variadic_ref?(macro, rep)
+        macro.variadic && rep.type == :identifier && rep.text == macro.va_name
+      end
+
+      # One argument's fully expanded tokens, computed on first use and cached in
+      # the invocation so a parameter named several times expands only once.
+      def expanded_argument(invocation, index)
+        invocation.expanded[index] ||= expand_argument(invocation.raw[index])
+      end
+
+      # The tokens __VA_ARGS__ stands for in a plain position: the pre-expanded
+      # variable arguments (those past the named parameters) laid end to end,
+      # separated by comma tokens spelled at the call site and painted as literals.
+      def variable_arguments(site, macro, invocation, painted)
+        result = []
+        (macro.params.length...invocation.raw.length).each_with_index do |arg, position|
+          result << comma_token(site, painted) if position.positive?
+          result.concat(expanded_argument(invocation, arg))
+        end
+        result
+      end
+
+      # The raw variable-argument tokens for a "#"/"##" operand: the unexpanded
+      # arguments past the named parameters, rejoined by the very comma tokens the
+      # call used, so #__VA_ARGS__ reproduces the source spacing exactly.
+      def raw_variadic(macro, invocation)
+        named = macro.params.length
+        result = []
+        (named...invocation.raw.length).each do |arg|
+          result << invocation.commas[arg - 1] if arg > named
+          result.concat(invocation.raw[arg])
+        end
+        result
+      end
+
+      # Stringizes an operand's raw tokens into a string-literal token (6.10.3.2):
+      # the token spellings joined with a single space wherever the source had
+      # whitespace and none at the ends, with " and \ escaped inside string and
+      # character tokens. The result sits at the use site under the literal paint.
+      def stringize(hash, painted, tokens)
+        inner = +""
+        tokens.each_with_index do |t, index|
+          inner << " " if index.positive? && t.space_before
+          inner << stringized_spelling(t)
+        end
+        PPToken.new(
+          type: :string, text: "\"#{inner}\"",
+          filename: hash.filename, line: hash.line, column: hash.column,
+          source_line: hash.source_line, space_before: hash.space_before, suppress: painted
+        )
+      end
+
+      # A token's contribution to a stringized argument: verbatim, except inside a
+      # string literal or character constant, where each " and \ gains a backslash.
+      def stringized_spelling(token)
+        if token.type == :string || token.type == :char
+          token.text.gsub(/["\\]/) { |ch| "\\#{ch}" }
+        else
+          token.text
+        end
+      end
+
+      # Concatenates a "##"'s two operands (6.10.3.3). `left_span` is how many
+      # tokens the left operand placed; 0 means it was a placemarker, so the paste
+      # is just the right operand, and an empty right operand likewise leaves the
+      # left alone. Otherwise the left operand's last token and the right's first
+      # are spelled together and re-lexed into one token. Returns the new span so
+      # a chained "##" pastes onto this result. Left to right by construction.
+      def paste(result, left_span, right, site, painted)
+        return concat_span(result, right) if left_span.zero?
+        return left_span if right.empty?
+
+        left = result.pop
+        result << fuse(left, right.first, site, painted)
+        result.concat(right[1..])
+        right.length
+      end
+
+      def concat_span(result, tokens)
+        result.concat(tokens)
+        tokens.length
+      end
+
+      # Whether a "##" is the GNU comma-paste ", ## <variable-arguments>": a
+      # literal comma written immediately to its left and the variable-part name
+      # immediately to its right, inside a function-like call. Only this exact
+      # shape overrides the ordinary paste; every other "##" keeps its meaning.
+      def gnu_comma_paste?(macro, invocation, left, operand)
+        invocation && left&.punct?(",") && variadic_ref?(macro, operand)
+      end
+
+      # Carries out a GNU comma-paste. It is not a token paste: when the call
+      # supplies no variable arguments the preceding comma, already placed as the
+      # left operand, is dropped and nothing is spliced in. Otherwise the comma
+      # stays and the variable arguments are spliced in expanded, exactly as a
+      # plain use of the variable-part name would produce -- so an argument slot
+      # that is present but empty (a trailing comma) keeps the comma. Returns the
+      # new span.
+      def comma_paste(macro, invocation, result, site, painted)
+        if no_variable_arguments?(macro, invocation)
+          result.pop if result.last&.punct?(",")
+          0
+        else
+          args = variable_arguments(site, macro, invocation, painted)
+          concat_span(result, args)
+        end
+      end
+
+      # Whether the call supplied no variable arguments (so a GNU comma-paste
+      # drops its comma). That holds when nothing was written past the named
+      # parameters, and also -- matching gcc -- when the macro has no named
+      # parameters and the whole argument list is empty ("Z()" for "Z(...)"),
+      # which reads as zero variable arguments, not one empty one. A trailing
+      # comma with nothing after it ("F(a,)") does supply one empty argument.
+      def no_variable_arguments?(macro, invocation)
+        return true if invocation.raw.length <= macro.params.length
+
+        macro.params.empty? && invocation.raw.length == 1 && invocation.raw[0].empty?
+      end
+
+      # Fuses two tokens into one by re-lexing their joined spelling through the
+      # scanner (6.10.3.3p3): the result must be exactly one preprocessing token,
+      # or the paste is ill-formed. It takes the left token's leading space and
+      # the literal paint, and is located at the use site for rescanning.
+      def fuse(left, right, site, painted)
+        spelled = Scanner.new(left.text + right.text, filename: site.filename).scan.reject(&:eof?)
+        unless spelled.length == 1
+          raise_at(site, "pasting \"#{left.text}\" and \"#{right.text}\" does not give a valid preprocessing token")
+        end
+
+        fused = spelled.first
+        PPToken.new(
+          type: fused.type, text: fused.text,
+          filename: site.filename, line: site.line, column: site.column,
+          source_line: site.source_line, space_before: left.space_before, suppress: painted
+        )
+      end
+
+      # The painting a token produced by expanding `tok` carries: `tok`'s own
+      # suppression set plus the macro name now being expanded, frozen so the
+      # shared list is never mutated by a later token's painting.
+      def paint(tok)
+        (tok.suppress + [tok.text]).freeze
+      end
+
+      def comma_token(site, suppress)
+        PPToken.new(
+          type: :punct, text: ",",
+          filename: site.filename, line: site.line, column: site.column,
+          source_line: site.source_line, suppress: suppress
+        )
+      end
+
+      # A copy of a replacement token relocated to the invocation site (so tokens
+      # produced by expansion are diagnosed at the point of use, not at the
+      # #define that spelled them) and carrying its computed painting.
+      def relocate(rep, site, suppress)
+        PPToken.new(
+          type: rep.type, text: rep.text,
+          filename: site.filename, line: site.line, column: site.column,
+          source_line: site.source_line, space_before: rep.space_before, suppress: suppress
+        )
+      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
+
+      # As #raise_at, but for a Front::Token (produced during #if evaluation)
+      # rather than a preprocessing token; both expose the same location fields.
+      def raise_at_front(token, description)
+        raise CompileError.new(
+          description,
+          filename: token.filename, line: token.line, column: token.column,
+          source_line: token.source_line
+        )
+      end
+    end
+  end
+end