hecks 1.2.0 → 1.4.0

data/lib/hecks/codemod.rb

@@ -1,49 +1,50 @@
 require_relative "bluebook/meta_validator"
+require_relative "corpus"
 
 module Hecks
-  # SHARED MACHINERY for a codemod that migrates real `.bluebook` source
+  # Shared machinery for a codemod that migrates real `.bluebook` source
   # once a DSL builder change makes some previously-required declaration
   # optional/redundant — pulled out of `bin/codemod_implicit_append_fields`
   # (the first one built), which needed three real, hard-won fixes before
   # it could be trusted: a process-lifetime AST cache with no
   # invalidation, a batch-revert granularity that let one unsafe
   # candidate sink every other safe one sharing its boot, and (in the
-  # SPINE the codemod migrates FOR, not here) an append-at-end insertion
+  # spine the codemod migrates for, not here) an append-at-end insertion
   # that only round-tripped correctly for whichever field happened to be
   # last. None of those are guessable in advance; they only surface by
   # actually running a real edit against real self-hosted code. This
-  # module is that lesson, kept — the NEXT codemod plugs in two rule-
+  # module is that lesson, kept — the next codemod plugs in two rule-
   # specific procs (`find_candidates`, `apply_candidate`) and inherits
   # the boot/safety-net machinery rather than rediscovering it.
   #
-  # A CODEMOD IS NOT PATTERN-MATCHING ALONE. Deciding "is this line safe
-  # to delete" means knowing what the RUNTIME would resolve it to — so
+  # **A codemod is not pattern-matching alone**. Deciding "is this line safe
+  # to delete" means knowing what the runtime would resolve it to — so
   # every codemod built on this module follows the same three steps:
   #   1. Boot the real domain (or the self-hosted meta-domain) and read
-  #      its IR to find CANDIDATES — provided by the caller's own
+  #      its IR to find candidates — provided by the caller's own
   #      `find_candidates`, since the actual redundancy rule is specific
   #      to whichever spine change this migration serves.
   #   2. Locate and remove each candidate's own source text — the
   #      caller's own `apply_candidate`.
   #   3. Re-boot from the edited text and diff the full IR export
   #      against the pre-edit export. Byte-identical -> keep. Anything
-  #      else (including a RAISED exception — the self-hosted
-  #      meta-domain DISPATCHES itself into being, S14, so a bad edit
+  #      else (including a raised exception — the self-hosted
+  #      meta-domain dispatches itself into being, S14, so a bad edit
   #      can surface as a runtime refusal, not just a differing export)
-  #      -> revert and report SKIPPED, never silently guessed past.
+  #      -> revert and report skipped, never silently guessed past.
   #
-  # DESIGN-TIME CHECKLIST for the SPINE change a future codemod migrates
-  # corpus text for — both items below are real bugs THIS module's own
+  # Design-time checklist for the spine change a future codemod migrates
+  # corpus text for — both items below are real bugs this module's own
   # first use found, not hypothetical:
-  #   - Does the resolved value get inserted into an ORDER-SENSITIVE
+  #   - Does the resolved value get inserted into an order-sensitive
   #     list (the exported IR is array-order-sensitive throughout)? If
-  #     so, the spine's own insertion must preserve the ORIGINAL
+  #     so, the spine's own insertion must preserve the original
   #     position, not just append — an append-at-end insertion only
   #     round-trips correctly for a value that already happened to be
   #     last.
-  #   - Does resolution depend on ANOTHER construct already being
+  #   - Does resolution depend on another construct already being
   #     declared (the aggregate/entity a `sets`/`append:` field resolves
-  #     against)? If a creator command can be declared BEFORE the
+  #     against)? If a creator command can be declared before the
   #     construct it creates (real, live: `command "Handler"` before
   #     `entity "Handler"`, one file down), one-pass resolution
   #     genuinely cannot see it yet — not a codemod bug, a structural
@@ -51,16 +52,16 @@ module Hecks
   module Codemod
     ROOT = File.expand_path("../..", __dir__)
 
-    EXAMPLE_ROOTS = Dir.glob(File.join(ROOT, "examples", "*")).select { |p| File.directory?(p) }.sort
+    EXAMPLE_ROOTS = Corpus.members(:example, root: ROOT).map(&:path)
     META_FILES    = (Dir.glob(File.join(ROOT, "lib/hecks/grammar/*.bluebook")) +
                       Dir.glob(File.join(ROOT, "lib/hecks/framework/bluebook/*.bluebook")) +
                       Dir.glob(File.join(ROOT, "lib/hecks/language/bluebook/**/*.bluebook"))).sort
 
-    # THE SAME LIGHTWEIGHT PATH `spec/spec_helper.rb`'s own
+    # The same lightweight path `spec/spec_helper.rb`'s own
     # `boot_in_memory` uses — `Hecks.with_registry` satisfies
     # `Hecks.bluebook`'s own `collect`'s "loaded outside a boot" check
     # without `Hecks.boot`'s full era-check/adapter-wiring path, which
-    # needs a LIVE Postgres connection for `compliance` and would make
+    # needs a live Postgres connection for `compliance` and would make
     # every codemod depend on a database it has no reason to touch — a
     # codemod only ever reads a chapter's own declared IR, never a
     # stored record.
@@ -72,11 +73,11 @@ module Hecks
     def self.export_json(registry) = Hecks::Projector::Exporter.json(registry)
 
     # `Hecks::Adapters::Prism` caches a file's parsed AST for the
-    # life of the PROCESS, keyed by path — fine for every existing
+    # life of the process, keyed by path — fine for every existing
     # caller (a file loads once per process: one `bin/ir` run, one
-    # rspec worker), but a codemod legitimately reloads the SAME path
+    # rspec worker), but a codemod legitimately reloads the same path
     # after editing it, and a stale cached tree reports a
-    # `given`/`ensures` block at its OLD line number, which no longer
+    # `given`/`ensures` block at its old line number, which no longer
     # matches the freshly re-executed file's own `block.source_location`
     # — surfacing as "did not survive extraction" on a perfectly valid
     # file. `Prism.forget` is the real invalidation API this module's
@@ -104,10 +105,10 @@ module Hecks
       registry
     end
 
-    # `forget_all`, not a single `forget` — the meta-domain is NINE
+    # `forget_all`, not a single `forget` — the meta-domain is nine
     # files (`MetaValidator::GRAMMAR_FILES`) merged into one registry,
     # and a caller here (the codemod runner) doesn't generally know in
-    # advance which ONE it just edited.
+    # advance which one it just edited.
     def self.boot_meta
       Hecks::Adapters::Prism.forget_all
       Hecks::Bluebook::MetaValidator.instance_variable_set(:@grammar_registry, nil)
@@ -123,7 +124,7 @@ module Hecks
     # Walks every aggregate (and every nested entity, recursively)
     # across every chapter in a booted registry, yielding [owning
     # construct, command] pairs — `construct` is whichever
-    # Aggregate/Entity actually OWNS the command, the same distinction
+    # Aggregate/Entity actually owns the command, the same distinction
     # `AggregateBuilder#command` vs `EntityBuilder#command` already
     # draws. Generic enough for any rule that needs to walk real
     # commands, not specific to the attribute-redundancy rule.
@@ -143,7 +144,7 @@ module Hecks
       construct.attributes.find { |attr| attr.name.to_s == name.to_s }
     end
 
-    # A LIST attribute's own element construct — the value object or
+    # A list attribute's own element construct — the value object or
     # entity `list_of(...)` names, resolved by `hecks_name` the same way
     # `AttributeCollector#resolve_identity_field!` already does. Shared
     # because "what does this list actually hold" is a question any
@@ -157,7 +158,7 @@ module Hecks
       pool.find { |c| c.hecks_name.to_s == list_attr.type.to_s }
     end
 
-    # Either a raised exception OR a differing export counts as unsafe
+    # Either a raised exception or a differing export counts as unsafe
     # — see the module header on why the meta-domain specifically can
     # raise. Returns [value_or_nil, error_message_or_nil].
     def self.safely
@@ -166,11 +167,11 @@ module Hecks
       [nil, "#{e.class}: #{e.message}"]
     end
 
-    # THE REUSABLE RUNNER — every real bug fix this module carries lives
+    # **The reusable runner** — every real bug fix this module carries lives
     # here, not in a caller's own script. A caller supplies:
     #
     #   find_candidates: ->(registry) { [...] }
-    #     Given a booted registry, return every CANDIDATE this rule
+    #     Given a booted registry, return every candidate this rule
     #     could migrate. A candidate is whatever shape the caller wants
     #     — `apply_candidate` is the only other thing that reads it.
     #
@@ -178,7 +179,7 @@ module Hecks
     #     Given one file's current text and one candidate, return the
     #     edited text and whether a match was actually found/removed —
     #     `false` (text unchanged) when the candidate doesn't apply to
-    #     THIS file, which is how the meta-domain's multi-file search
+    #     this file, which is how the meta-domain's multi-file search
     #     below finds the right one without the caller needing to know
     #     which file a candidate lives in ahead of time.
     #
@@ -279,10 +280,10 @@ module Hecks
         end
       end
 
-      # PER-CANDIDATE, not one batched write-then-verify — the
-      # meta-domain is ONE shared registry (SyntaxBoot DISPATCHES it
+      # Per-candidate, not one batched write-then-verify — the
+      # meta-domain is one shared registry (SyntaxBoot dispatches it
       # into itself, S14), so a single unsafe candidate among many would
-      # otherwise sink every OTHER, genuinely safe candidate in the same
+      # otherwise sink every other, genuinely safe candidate in the same
       # run: this module's first real run found exactly that (25
       # candidates, one dispatch-time break, all 25 reverted as a batch
       # before this per-candidate loop existed). `before_meta` stays the
@@ -291,8 +292,8 @@ module Hecks
       # still equal the pristine original after each kept edit, by
       # definition, no moving target needed.
       # Same shape and same reason as run_example_domains just above (see
-      # its own comment) — the write/verify/revert sequence, PER
-      # CANDIDATE (this method's own comment explains why it cannot
+      # its own comment) — the write/verify/revert sequence, per
+      # candidate (this method's own comment explains why it cannot
       # batch), is one coherent unit; splitting it would scatter
       # before_meta/live_meta/applied_by_file state across methods for
       # no gain.
@@ -323,7 +324,7 @@ module Hecks
           live_meta[target_file] = text
           Codemod::META_FILES.each { |f| File.write(f, live_meta[f]) }
 
-          # DRY RUN STILL VERIFIES — see run_example_domains' own
+          # **Dry run still verifies** — see run_example_domains' own
           # comment; the edit is always written and rebooted for real,
           # then always reverted afterward when dry-run (whether or not
           # it was safe) so the next candidate is judged against the

data/lib/hecks/construct.rb

@@ -1,14 +1,14 @@
 module Hecks
   # The invisible field a built construct carries.
   #
-  # A construct is a RECORD WITH AN OWNER CHAIN — the chapter (Bluebook)
+  # A construct is a record with an owner chain — the chapter (Bluebook)
   # owns its aggregates, an aggregate owns everything declared on it — and the
   # bluebook identity is carried in its own field, under a `hecks_` prefix that
   # no domain attribute can collide with. Invisible means exactly that: not an
   # attribute, not a key in `to_h`, not a reader on instances. Framework
   # metadata about the construct, not part of the domain it describes.
   #
-  # The identity is COMPUTED by walking owners rather than stamped, so nothing
+  # The identity is computed by walking owners rather than stamped, so nothing
   # has to be re-stamped when a chapter is assembled after its aggregates:
   #
   #     Pizzas                     the chapter — no owner
@@ -17,7 +17,7 @@ module Hecks
   #
   # That spelling is not invented here. It is the id `MetaValidator::Judge`
   # already mints in `#identify`, so a construct and the meta-domain's
-  # record OF that construct carry the same identity, and there is no
+  # record of that construct carry the same identity, and there is no
   # translation table between them to be quietly wrong in.
   #
   # Usage:
@@ -37,7 +37,7 @@ module Hecks
     attr_writer :hecks_name
 
     # A chapter is the only construct that legitimately has no owner. Everything
-    # else is DECLARED IN something, so a missing owner is an unstamped construct
+    # else is declared in something, so a missing owner is an unstamped construct
     # rather than a top — see hecks_fqn.
     attr_writer :hecks_root
 
@@ -47,11 +47,11 @@ module Hecks
     def hecks_name = @hecks_name
 
     # How this construct joins its owner. An aggregate is a member of its
-    # chapter's namespace (`::`) ; everything else is declared ON its owner
+    # chapter's namespace (`::`) ; everything else is declared on its owner
     # (`.`). Overridden by Aggregate, defaulted here for every other construct.
     def hecks_separator = "."
 
-    # REFUSES rather than guesses. A construct with no owner and no claim to be a
+    # Refuses rather than guesses. A construct with no owner and no claim to be a
     # chapter has simply not been stamped yet — entity commands are in that state
     # while entities are still IR objects — and answering the bare name would be a
     # plausible half-truth that no test would notice. That shape of falsehood is

data/lib/hecks/corpus.rb

@@ -0,0 +1,317 @@
+require_relative "fuzzing/target_capabilities"
+
+module Hecks
+  # **The corpus, discovered** — every place in this repo that holds a real
+  # domain, named once.
+  #
+  # This used to be spelled out separately by every consumer that walks
+  # it — spec/corpus_spec.rb, spec/model_check_spec.rb, bin/model_check,
+  # spec/parser_parity_spec.rb, bin/fuzz, Fuzzing::CombinationMiner — and
+  # the copies had already drifted: only the model checker saw
+  # `qa/bluebook`, only parser parity saw `spec/fixtures`, and nothing but
+  # bin/fuzz's own sweep ever saw `qa/stress_domains`. One table here, and
+  # each consumer names the KINDS it walks rather than re-deriving where
+  # those kinds live.
+  #
+  # Plain Dir/File only — bin/ scripts require this before (or without)
+  # booting anything.
+  module Corpus
+    ROOT = File.expand_path("../..", __dir__).freeze
+
+    Member = Struct.new(:stem, :kind, :path)
+
+    # **One domain per directory** — its bluebooks sit in `<dir>/bluebook/`
+    # or directly in `<dir>` (see `bluebook_files`). Stemmed by directory.
+    DIRECTORY_KINDS = {
+      example:   "examples/*",
+      stress:    "qa/stress_domains/*",
+      semantics: "spec/corpus/semantics/domains/*"
+    }.freeze
+
+    # **One chapter per file**. Stemmed by the path below the glob's fixed
+    # prefix, so a nested fixture keeps its subdirectory (`eras/base`)
+    # and never collides with a same-named file elsewhere in the kind.
+    FILE_KINDS = {
+      grammar:   "lib/hecks/grammar/*.bluebook",
+      framework: "lib/hecks/framework/bluebook/*.bluebook",
+      qa:        "qa/bluebook/*.bluebook",
+      language:  "lib/hecks/language/**/*.bluebook",
+      deploy:    "lib/hecks/deploy/bluebook/*.bluebook",
+      fixture:   "spec/fixtures/**/*.bluebook"
+    }.freeze
+
+    KINDS = (DIRECTORY_KINDS.keys + FILE_KINDS.keys).freeze
+
+    # Where a bluebook the sweep does not boot goes instead. Not a filter:
+    # nothing leaves `sweepable_domains` without naming the check that owns
+    # it, and spec/corpus_accounting_spec.rb proves each destination exists
+    # and actually exercises what is routed to it.
+    #
+    #   check: :named_in   — `destination` names every routed file
+    #                        (`names: :each_file`) or the given text
+    #   check: :gitignored — `destination` holds the ignore rule `names`,
+    #                        and nothing matching is committed
+    #   check: :gap        — no check exercises these yet. Listed so the
+    #                        gap is visible; the accounting spec keeps it
+    #                        pending and fails the moment one appears.
+    #
+    # Ordered — a bluebook belongs to the first route it matches, so a
+    # specific destination sits above the catch-all for its shape.
+    Route = Struct.new(:pattern, :check, :destination, :names, :why)
+
+    ROUTES = [
+      Route.new(%r{\Atmp/}, :gitignored, ".gitignore", "tmp/",
+                "scratch output — generated and mined candidate domains, fuzz failures — never committed"),
+      Route.new(%r{/\.aws-sam/}, :gitignored, ".gitignore", ".aws-sam/",
+                "SAM build output — a vendored copy of real sources, never committed"),
+      Route.new(%r{/data/eras/}, :gitignored, ".gitignore", "**/data/eras/",
+                "era snapshots a file adapter writes at runtime, never committed"),
+      Route.new(%r{\Arust/}, :named_in, "rust/parser/tests/gates.rs", :each_file,
+                "the Rust parser's own fixtures, each loaded by its gate tests"),
+      Route.new(%r{/translations/}, :named_in, "spec/translation/committed_edges_spec.rb", "bluebook/translations",
+                "translation edges, not chapters; each must load, chain era to era, and end at the storage " \
+                "shape its bluebook declares today"),
+      Route.new(%r{\Alib/hecks/forms/examples/}, :named_in, "spec/forms/app_spec.rb", :each_file,
+                "a Forms presentation config wearing the .bluebook extension"),
+      Route.new(%r{\Aspec/fixtures/eras/}, :named_in, "spec/runtime/storage_shape_spec.rb", "fixtures/eras",
+                "deliberately conflicting versions of one domain; each must classify as the verdict " \
+                "its filename declares (bump_* / same_*)"),
+      Route.new(%r{\Aspec/fixtures/model_check/}, :named_in, "spec/model_check_spec.rb", :each_file,
+                "domains broken on purpose; each must produce exactly the finding kinds it is built to trigger"),
+      # bin/fuzz sweeps it too, once Fuzzing::Replay coerces value-object
+      # args before recomputing givens — today its oracle reads raw args
+      # while dispatch coerces, so checkout_fixture's VO-reading given
+      # reads as wrongly admitted.
+      Route.new(%r{\Aspec/fixtures/rust_host/}, :named_in, "rust/host/src/web.rs", "checkout_fixture",
+                "the Rust host's checkout fixture, pinned by its web and /api tests")
+    ].freeze
+
+    module_function
+
+    def members(*kinds, root: ROOT)
+      kinds = KINDS if kinds.empty?
+      kinds.flat_map do |kind|
+        if (glob = DIRECTORY_KINDS[kind])
+          Dir.glob(File.join(root, glob)).select { |path| File.directory?(path) }.sort
+             .map { |dir| Member.new(File.basename(dir), kind, dir) }
+        elsif (glob = FILE_KINDS[kind])
+          prefix = File.join(root, glob[/\A[^*]*/].chomp("/"))
+          Dir.glob(File.join(root, glob))
+             .map { |file| Member.new(file.delete_prefix("#{prefix}/").delete_suffix(".bluebook"), kind, file) }
+        else
+          raise ArgumentError, "unknown corpus kind #{kind.inspect} — known: #{KINDS.join(', ')}"
+        end
+      end
+    end
+
+    # What a boot loads for a member: a directory kind's bluebook
+    # directory, a file kind's own file. `nil` for a directory holding no
+    # bluebook at all.
+    def source_of(member)
+      DIRECTORY_KINDS.key?(member.kind) ? bluebook_dir(member.path) : member.path
+    end
+
+    # Where a domain path keeps its bluebooks — `<domain>/bluebook/*.bluebook`
+    # (every example and stress domain), or the directory itself
+    # (`qa/bluebook`). `nil` when neither holds a bluebook.
+    def bluebook_files(domain_path)
+      [File.join(domain_path, "bluebook"), domain_path].each do |dir|
+        files = Dir[File.join(dir, "*.bluebook")]
+        return files unless files.empty?
+      end
+      nil
+    end
+
+    def bluebook_dir(domain_path)
+      files = bluebook_files(domain_path)
+      files && File.dirname(files.first)
+    end
+
+    # The route a repo-relative path takes instead of the sweep — the
+    # first one it matches — or `nil` when the sweep boots it.
+    def route_for(relative_path)
+      ROUTES.find { |route| route.pattern.match?(relative_path) }
+    end
+
+    # What bin/model_check and spec/model_check_spec.rb walk — every kind,
+    # less the language (examined as one judged chapter, not file by file)
+    # and deploy chapters (the SAM projector's own inputs), and less any
+    # member a route already sends to a destination of its own: the
+    # broken-on-purpose model_check fixtures must produce their findings
+    # there, so a clean-corpus gate here would be the wrong check for them.
+    MODEL_CHECK_KINDS = %i[example grammar framework qa stress fixture].freeze
+
+    def model_check_members(root: ROOT)
+      members(*MODEL_CHECK_KINDS, root: root).reject { |member| route_for(member.path.delete_prefix("#{root}/")) }
+    end
+
+    # **The ledger sweeps itself** — its own chapter is a domain like any
+    # other, and the one rotation member that is neither an example nor a
+    # stress domain.
+    ROTATION_LEDGER = { "quality_control" => "qa/bluebook" }.freeze
+
+    # What the QA rotation is made of — every example and stress domain
+    # this repository owns, plus the ledger, as `reference => repo-relative
+    # path`: exactly the shape `Target.path` is stored in.
+    #
+    # Derived, because the hand-kept version silently went stale.
+    # `bin/qa_seed_targets` carried a literal list naming three of the
+    # thirteen stress domains; the other ten were authored, argued for in
+    # their own NOTES.md, several promoted by `bin/qa_generated_domains
+    # --promote` — and never swept once, because a `Target` row is what
+    # puts a domain in the rotation and nothing tied that list to the
+    # corpus. Promotion only ever printed the `target.identify` line for a
+    # human to run.
+    def rotation_targets(root: ROOT)
+      members(:example, :stress, root: root)
+        .to_h { |member| [member.stem, member.path.delete_prefix("#{root}/")] }
+        .merge(ROTATION_LEDGER)
+    end
+
+    # Every bootable domain in the project, not a hand-kept list — any
+    # directory holding a `.bluebook` no route sends elsewhere, a
+    # `bluebook/` folder standing for the domain directory around it.
+    def sweepable_domains(root = ROOT)
+      Dir.chdir(root) do
+        Dir.glob("**/*.bluebook")
+           .reject { |path| route_for(path) }
+           .map { |path| File.dirname(path) }
+           .map { |dir| File.basename(dir) == "bluebook" ? File.dirname(dir) : dir }
+           .uniq.sort
+           .map { |dir| File.join(root, dir) }
+      end
+    end
+
+    # The domain directory a member stands for, spelled the way
+    # `sweepable_domains` spells it: a `bluebook/` folder is its parent.
+    def domain_dir_of(member)
+      dir = File.directory?(member.path) ? member.path : File.dirname(member.path)
+      File.basename(dir) == "bluebook" ? File.dirname(dir) : dir
+    end
+
+    # ── The Rust-facing corpus ─────────────────────────────────────────
+    #
+    # Every Rust-facing list (the fuzz bridge, the codegen drift check,
+    # rust coverage, codegen parity) used to be typed out by hand, and
+    # each had drifted from `rust/Cargo.toml`'s `[features]`: fuzzing saw
+    # 8 of 20 features. These read the one source instead. The
+    # `rust/src/generated/` modules split into buckets, and
+    # spec/corpus_rust_spec.rb proves every Cargo feature and every
+    # generated module lands in exactly one of them:
+    #
+    #   rust_domains       an in-repo domain directory with a Cargo feature
+    #                      of its own: fuzzed, regenerated, coverage- and
+    #                      parity-checked
+    #   framework chapters no feature and no merged.rs; written as a side
+    #                      effect of every `uses_framework` domain's regen
+    #   RUST_ELSEWHERE     a feature with no in-repo domain directory, and
+    #                      the check that owns it instead
+    GENERATED_DIR = "rust/src/generated".freeze
+    RUST_DOMAIN_KINDS = %i[example stress fixture].freeze
+
+    RustDomain = Struct.new(:feature, :dir, :kind)
+
+    # `check: :named_in` — `destination` must name `names`.
+    # `check: :external` — no in-repo domain directory may carry the name;
+    #                      the day one does, it belongs in rust_domains.
+    Elsewhere = Struct.new(:check, :destination, :names, :why)
+
+    RUST_ELSEWHERE = {
+      "meta"       => Elsewhere.new(:named_in, "spec/codegen_parity_spec.rb", "bluebook_language",
+                                    "the self-hosted grammar (lib/hecks/language), not a domain directory — every " \
+                                    "bin/project_rust run rewrites it (so the drift check diffs it), codegen parity " \
+                                    "checks it as bluebook_language, and there is no directory to fuzz"),
+      "embryonaut" => Elsewhere.new(:external, "~/Projects/embryonautfoundersapp", "embryonaut",
+                                    "an external product's domain — its bluebook, regeneration and parity are owed " \
+                                    "by its own repo; here bin/rust_coverage checks only the committed snapshot")
+    }.freeze
+
+    # **Shrink-only**. A generated module `bin/rust_coverage` still reports a
+    # gap for. `bin/corpus --rust-coverage` requires each of these to
+    # still fail, so an entry that starts passing breaks the build until
+    # it is deleted here.
+    RUST_COVERAGE_PENDING = {}.freeze
+
+    def cargo_features_table(root: ROOT)
+      File.read(File.join(root, "rust/Cargo.toml"))[Fuzzing::TargetCapabilities::FEATURES_TABLE] || ""
+    end
+
+    def cargo_features(root: ROOT)
+      cargo_features_table(root: root).scan(/^(\w+)\s*=\s*\[\]/).flatten
+    end
+
+    # The feature `bin/project_rust` last wrote as Cargo's `default`.
+    def cargo_default(root: ROOT)
+      cargo_features_table(root: root)[/^default\s*=\s*\["(\w+)"\]/, 1]
+    end
+
+    # Every in-repo domain directory whose name is a Cargo feature, sorted
+    # by path. When the module is already generated, its metadata.rs stamp
+    # decides which directory it came from — a directory name alone is not
+    # enough: spec/fixtures/qa_discover_external_domains vendors a second
+    # `examples/pizzas` that no Cargo feature was ever generated from.
+    def rust_domains(root: ROOT)
+      features = cargo_features(root: root)
+      members(*RUST_DOMAIN_KINDS, root: root)
+        .map { |member| [domain_dir_of(member), member.kind] }
+        .uniq(&:first)
+        .select { |dir, _| rust_domain_dir?(dir, features, root) }
+        .sort_by(&:first)
+        .map { |dir, kind| RustDomain.new(File.basename(dir).downcase, dir, kind) }
+    end
+
+    def rust_domain_dir?(dir, features, root)
+      feature = File.basename(dir).downcase
+      source = generated_source(feature, root: root)
+      features.include?(feature) && (source.nil? || source == dir.delete_prefix("#{root}/"))
+    end
+
+    # Where a generated module came from, read off the stamp bin/project_rust
+    # writes into its metadata.rs — `examples/pizzas`, `/abs/path/embryonaut`,
+    # `the self-hosted language (lib/hecks/language/bluebook)`, with any
+    # ` (uses_framework "X")` suffix dropped. `nil` when not generated.
+    SOURCE_STAMP = %r{GENERATED by bin/project_rust — (.+?)(?: \(uses_framework "\w+"\))?'s own canonical IR,}
+
+    def generated_source(module_name, root: ROOT)
+      metadata = File.join(root, GENERATED_DIR, module_name, "metadata.rs")
+      File.file?(metadata) ? File.read(metadata)[SOURCE_STAMP, 1] : nil
+    end
+
+    def generated_modules(root: ROOT)
+      Dir.children(File.join(root, GENERATED_DIR)).select { |name| File.directory?(File.join(root, GENERATED_DIR, name)) }.sort
+    end
+
+    def generated?(feature, root: ROOT)
+      File.file?(File.join(root, GENERATED_DIR, feature, "merged.rs"))
+    end
+
+    # Framework members `bin/project_rust` writes a module for as a side
+    # effect of some `uses_framework` domain — a module, no merged.rs.
+    def rust_framework_chapters(root: ROOT)
+      modules = generated_modules(root: root)
+      members(:framework, root: root).map(&:stem)
+                                     .select { |stem| modules.include?(stem) && !generated?(stem, root: root) }
+    end
+
+    # The regeneration order the drift check runs. Sorted by path, so
+    # which domain runs last — and so wins Cargo's `default`, mod.rs's cfg
+    # comments and the shared framework modules' attribution stamp — is a
+    # fact of the sorted list, not a hand-picked order. (The old hand list
+    # put waybill last; PR #667 moved to the sort, which makes
+    # has_many_fixture last.) spec/corpus_rust_spec.rb pins last == default.
+    def rust_regen_order(root: ROOT)
+      rust_domains(root: root).select { |domain| generated?(domain.feature, root: root) }
+    end
+
+    # The chapter a bluebook declares — `Hecks.bluebook "<Name>"`, read
+    # off the file rather than guessed from its name (a grammar chapter's
+    # file is named after its role, `aggregate.bluebook`, while its
+    # chapter is always "Bluebook"). Scans the whole file: a framework
+    # member's header comment can run past any fixed line cap.
+    def chapter_name_of(bluebook_path)
+      bluebook_path = Array(bluebook_path).first
+      header = File.foreach(bluebook_path).find { |line| line =~ /\A\s*Hecks\.bluebook\s+"([^"]+)"/ }
+      header && Regexp.last_match(1)
+    end
+  end
+end

data/lib/hecks/deprecation.rb

@@ -0,0 +1,95 @@
+# Deprecation warnings this gem raises about its own API. Not a singleton
+# method on `Hecks` itself: the self-hosted language declares every word
+# that module answers (spec/syntax_conformance_spec.rb), and a warning
+# about an old call shape is not a word of the language — callers name
+# `Hecks::Deprecation.call` in full.
+module Hecks
+  # One warning per call site, naming the caller's line — never a line
+  # inside this gem. A deprecated shape usually reaches the runtime through
+  # a forwarding door (`Hecks::Router`, a namespace shortcut, a
+  # `RemoteDispatcher`), so the site reported is the first frame outside
+  # `lib/hecks`, which is the line a reader can actually change.
+  #
+  #   Hecks::Deprecation.call(:legacy_dispatch_args, "pass facts in with:")
+  #   # warns once: "spec/foo_spec.rb:12: warning: pass facts in with:"
+  #
+  # Per key, in this order:
+  #   `allowing(key) { ... }`  — suppressed for the block, this thread only
+  #                              (the spec that tests a deprecation itself)
+  #   `raise_on!(key)`         — raises `Hecks::Deprecation::Error` (the
+  #                              test suite, so no spec reintroduces it);
+  #                              with a block, only where the block says so,
+  #                              given the site, so a suite can raise on
+  #                              new sites while a known worklist warns
+  #   HECKS_SILENCE_DEPRECATIONS=1 — silent
+  #   otherwise                — `Kernel#warn`, once per key and call site
+  module Deprecation
+    class Error < StandardError
+    end
+
+    LIB_ROOT = File.expand_path(__dir__)
+    LIB_ENTRY = File.expand_path("../hecks.rb", __dir__)
+
+    EVERYWHERE = ->(_site) { true }
+
+    @seen = {}
+    @raising = {}
+    @mutex = Mutex.new
+
+    class << self
+      # { key => where it raises instead of warning }.
+      attr_reader :raising
+
+      def raise_on!(*keys, &where)
+        keys.each { |key| @raising[key] = where || EVERYWHERE }
+        keys
+      end
+
+      def call(key, message)
+        return if allowed?(key)
+
+        uplevel, site = external_frame
+        raise Error, "#{site}: #{message}" if @raising[key]&.call(site)
+        return if ENV["HECKS_SILENCE_DEPRECATIONS"] == "1"
+        return unless first_sighting?(key, site)
+
+        Kernel.warn(message, uplevel: uplevel)
+      end
+
+      def allowing(key)
+        allowed = Thread.current[:hecks_allowed_deprecations] ||= []
+        allowed.push(key)
+        yield
+      ensure
+        allowed.pop
+      end
+
+      # Forget every site already warned about — for specs only.
+      def reset! = @mutex.synchronize { @seen.clear }
+
+      # The first caller frame outside this gem — where a deprecated call
+      # was written.
+      def external?(frame)
+        path = frame.absolute_path || frame.path
+        !(path.start_with?("<internal:") || path == LIB_ENTRY || path.start_with?("#{LIB_ROOT}/"))
+      end
+
+      private
+
+      def allowed?(key) = Array(Thread.current[:hecks_allowed_deprecations]).include?(key)
+
+      def first_sighting?(key, site)
+        @mutex.synchronize { @seen.key?([key, site]) ? false : (@seen[[key, site]] = true) }
+      end
+
+      # `uplevel:` counts from the frame that calls `Kernel.warn` — `call`,
+      # this method's caller — and `caller_locations(1)` starts at that
+      # same frame, so the index found here is the uplevel to pass.
+      def external_frame
+        frames = caller_locations(1)
+        index = frames.index { |frame| external?(frame) } || (frames.size - 1)
+        [index, "#{frames[index].path}:#{frames[index].lineno}"]
+      end
+    end
+  end
+end