hecks 4.0.0 → 6.0.0

data/lib/hecks/rust_build/conformance.rb

@@ -20,6 +20,9 @@ module Hecks
       USAGE = "usage: hecks check_conformance <domain> <script.json> " \
               "[rust_output.json | native | build | path/to/binary | path/to/module.wasm]"
 
+      # A compiled wasm module's path.
+      WASM_MODULE = /\.wasm\z/
+
       module_function
 
       # @param argv [Array<String>] the domain, the script and optionally the artifact
@@ -48,7 +51,7 @@ module Hecks
         case other
         when "native" then run_binary(native_binary || missing_native!, script)
         when "build" then run_binary(built_binary(domain), script)
-        when /\.wasm\z/ then run_wasm(domain, script, other)
+        when WASM_MODULE then run_wasm(domain, script, other)
         when method(:pinned_binary?) then run_binary(other, script)
         else File.read(other)
         end
@@ -105,18 +108,37 @@ module Hecks
       end
 
       def mismatches(ours, theirs)
-        found = %w[instances events refusals].filter_map do |key|
+        found = %w[instances events refusals cross_domain].filter_map do |key|
           next if ours[key] == theirs[key]
 
           "#{key}:\n  ruby:  #{ours[key].inspect}\n  other: #{theirs[key].inspect}"
         end
         dry = dry_run_mismatch(ours, theirs)
         found << dry if dry
+        validated = validation_mismatch(ours, theirs)
+        found << validated if validated
         found
       end
 
+      # A Rust dry run on the same surface as Ruby's: `verb`, `ok`, and each refusal's kind, stage,
+      # attribute, path and rule where the stage is one both engines list in full.
+      def their_dry_run(dry)
+        reasons = Array(dry["refusals"]).map do |refusal|
+          refusal.values_at("kind", "stage", "attribute", "path", "rule", "refusal")
+        end
+        dry.slice("verb", "ok").merge(Surface.collected_refusals(reasons))
+      end
+
+      # A `validate` step's answer, whole: the same refusals in the same order from both engines.
+      def validation_mismatch(ours, theirs)
+        mine = ours["validations"] || []
+        return if mine == (theirs["validations"] || [])
+
+        "validations:\n  ruby:  #{mine.inspect}\n  other: #{theirs["validations"].inspect}"
+      end
+
       def dry_run_mismatch(ours, theirs)
-        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| dry.slice("verb", "ok") }
+        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| their_dry_run(dry) }
         return if (ours["dry_runs"] || []) == their_dry_runs
 
         "dry_runs:\n  ruby:  #{ours["dry_runs"].inspect}\n  other: #{their_dry_runs.inspect}"

data/lib/hecks/rust_build/conformance_fuzz.rb

@@ -15,7 +15,7 @@ module Hecks
     #
     #   ConformanceFuzz.call([domain, "native" | "path/to/module.wasm", seeds, steps])
     #
-    # `seeds` and `steps` default to `SEEDS` and `STEPS` in the environment, then to 10 and 25.
+    # `seeds` and `steps` default to 10 and 25.
     module ConformanceFuzz
       USAGE = "usage: hecks fuzz_conformance <domain> <native|path/to/module.wasm> [seeds] [steps]"
 
@@ -45,7 +45,7 @@ module Hecks
         domain, artifact, seeds, steps = argv
         raise Failure, USAGE unless domain && artifact
 
-        Run.new(domain, artifact, Integer(seeds || ENV["SEEDS"] || 10), Integer(steps || ENV["STEPS"] || 25),
+        Run.new(domain, artifact, Integer(seeds || 10), Integer(steps || 25),
                 scratch_dir(domain))
       end
 

data/lib/hecks/rust_build/domain_name.rb

@@ -14,11 +14,14 @@ module Hecks
       # vocabulary.
       CARGO_RESERVED = Hecks::Vocabulary.fetch("CargoReservedName")
 
+      # A plain lowercase identifier: a letter or underscore, then letters, digits, underscores.
+      IDENTIFIER = /\A[a-z_][a-z0-9_]*\z/
+
       # @param name [String] the domain's directory name
       # @return [Boolean] whether it is a plain lowercase identifier and no reserved word
       def self.valid?(name)
         text = name.to_s
-        text.match?(/\A[a-z_][a-z0-9_]*\z/) &&
+        text.match?(IDENTIFIER) &&
           Hecks::Bluebook::ModelCheck.rust_reserved_name_findings(domain_name: text).empty?
       end
     end

data/lib/hecks/rust_build/host.rb

@@ -5,6 +5,7 @@ require "open3"
 require_relative "../rust_build"
 require_relative "wasm"
 require_relative "prebuilt_binary"
+require_relative "target_dir"
 
 module Hecks
   module RustBuild
@@ -15,7 +16,7 @@ module Hecks
     #
     # The host is compiled from the workspace this release carries (`rust/host`), so the binary is
     # the one the installed gem was released with; nothing is fetched. The module and IR come from
-    # `Wasm`. `CARGO_TARGET_DIR` names where Cargo writes (the copy's `target/` for a client), so
+    # `Wasm`. `TargetDir` names where Cargo writes (one shared cache for an installed copy), so
     # a second build recompiles only what changed. Stages `<domain>-host`, `<domain>.wasm` and
     # `<domain>.ir.json` in `--stage` (default `.hecks/host/<target>/` in the working directory).
     module Host
@@ -28,10 +29,13 @@ module Hecks
       # A Rust target triple: `<arch>-<vendor>-<os>`, with an optional `-<env>`.
       TRIPLE = /\A[a-z0-9_]+(-[a-z0-9_.]+){2,3}\z/
 
+      # The `host: <triple>` line of `rustc -vV`, capturing the triple.
+      HOST_LINE = /^host: (\S+)/
+
       module_function
 
-      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>` and
-      #   `--stage=<directory>`
+      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>`,
+      #   `--stage=<directory>` and `--no-prebuilt` (compile the host, download no published one)
       # @return [Integer] the exit status
       # @raise [Failure] when the toolchain, the target or a step is missing or fails
       def call(argv)
@@ -39,13 +43,15 @@ module Hecks
           raise Failure, "usage: hecks build_host <domain> [target=<triple>] [stage=<directory>]"
         target = flag(argv, "target") || host_triple
         require_buildable!(target)
-        stage = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
+        stage = stage_for(argv, target)
 
         build_module(domain)
-        publish(compile(target), File.basename(domain.chomp("/")), stage)
+        publish(compile(target, prebuilt: !argv.include?("--no-prebuilt")), File.basename(domain.chomp("/")), stage)
         0
       end
 
+      def stage_for(argv, target) = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
+
       def build_module(domain)
         raise Failure, "project_wasm failed for #{domain}" unless Wasm.call([domain]).zero?
       end
@@ -61,7 +67,7 @@ module Hecks
       # @raise [Failure] when there is no Rust toolchain
       def host_triple
         require_rustup!
-        query("rustup", "run", TOOLCHAIN, "rustc", "-vV").to_s[/^host: (\S+)/, 1] or
+        query("rustup", "run", TOOLCHAIN, "rustc", "-vV").to_s[HOST_LINE, 1] or
           raise Failure, "rustup has no #{TOOLCHAIN} toolchain. Install it once with:\n\n    " \
                          "rustup toolchain install #{TOOLCHAIN}\n\nthen re-run the build."
       end
@@ -100,11 +106,11 @@ module Hecks
 
       # `rustup run`, not bare `cargo`, as `Wasm` does. A cross target links with the
       # `<arch>-linux-gnu-gcc` on PATH unless `CARGO_TARGET_<TRIPLE>_LINKER` already names a linker.
-      def compile(target)
+      def compile(target, prebuilt: true)
         host_dir = File.join(RustBuild.rust_dir, "host")
-        target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(host_dir, "target"))
+        target_dir = TargetDir.for(host_dir)
         binary = File.join(target_dir, target, "release", BINARY)
-        return binary if PrebuiltBinary.fetch("host", host_dir, target: target, into: binary)
+        return binary if PrebuiltBinary.fetch_for("rust/host", host_dir, target: target, into: binary, allowed: prebuilt)
 
         cargo_build(target, host_dir, { "CARGO_TARGET_DIR" => target_dir }.merge(linker_for(target)))
         binary

data/lib/hecks/rust_build/native_build.rb

@@ -80,7 +80,8 @@ module Hecks
         return if relative.start_with?("target/") || !File.file?(path)
 
         stat = File.stat(path)
-        digest << "#{relative}\0#{stat.size}\0#{stat.mtime.to_i}.#{stat.mtime.nsec}\n"
+        mtime = stat.mtime
+        digest << "#{relative}\0#{stat.size}\0#{mtime.to_i}.#{mtime.nsec}\n"
       end
 
       # Holds an exclusive flock from `cargo build` through the copy-out: parallel sweeps share

data/lib/hecks/rust_build/prebuilt_binary.rb

@@ -10,13 +10,13 @@ module Hecks
   module RustBuild
     # A binary hecks has already compiled and published, named by what went into it (ADR 0110).
     #
-    # The `PrebuiltBinary` rows of the Vocabulary chapter say which binaries are published: the
+    # The `PrebuiltBinary` rows of the Vocabulary bluebook say which binaries are published: the
     # crate to key, the Cargo binary, the target it is built for. A release tagged `<name>-<key>`
     # holds the binary and its `.sha256`; the key is a hash of the crate's build inputs, so the
     # same bytes are the same release, whichever commit they come from. `fetch` downloads it and
     # checks its hash, and answers nil on any miss (not published yet, no network, a hash that
-    # does not match) so a caller compiles as it always did. `HECKS_PREBUILT=off` turns the
-    # download off.
+    # does not match) so a caller compiles as it always did. `--no-prebuilt` on the host build
+    # turns the download off.
     module PrebuiltBinary
       # Where releases are published.
       REPOSITORY = "heckslabs/hecks"
@@ -36,6 +36,26 @@ module Hecks
           raise KeyError, "no PrebuiltBinary row named #{name.inspect}"
       end
 
+      # @param crate [String] a row's crate, the directory under the checkout (`rust/host`)
+      # @param target [String] the triple the caller builds for
+      # @return [String, nil] the name of the row that publishes the crate for the target,
+      #   nil when none does
+      def name_for(crate, target)
+        found = Hecks::Vocabulary.rows("PrebuiltBinary").find { |row| row["crate"] == crate && row["target"] == target }
+        found&.fetch("name")
+      end
+
+      # @param crate [String] a row's crate
+      # @param crate_dir [String] the crate's directory
+      # @param target [String] the triple the caller builds for
+      # @param into [String] the file to write the binary to
+      # @return [String, nil] `into`, or nil when no row publishes the crate for the target
+      #   or `fetch` misses
+      def fetch_for(crate, crate_dir, target:, into:, allowed: true)
+        name = name_for(crate, target) or return
+        fetch(name, crate_dir, target: target, into: into, allowed: allowed)
+      end
+
       # @param crate_dir [String] the crate's directory
       # @return [String] a hash of every file that goes into the build: each path and its bytes, in
       #   path order, so it does not depend on the checkout it is read from
@@ -66,8 +86,8 @@ module Hecks
       # @param into [String] the file to write the binary to
       # @return [String, nil] `into`, or nil when the binary is not published for this target or
       #   could not be fetched and verified
-      def fetch(name, crate_dir, target:, into:)
-        return if ENV["HECKS_PREBUILT"] == "off" || row(name)["target"] != target
+      def fetch(name, crate_dir, target:, into:, allowed: true)
+        return if !allowed || row(name)["target"] != target
 
         body = verified(name, crate_dir) or return
         FileUtils.mkdir_p(File.dirname(into))

data/lib/hecks/rust_build/project_rust/codegen_run.rb

@@ -14,8 +14,8 @@ module Hecks
       class CodegenRun
         META_LABEL = "the self-hosted language (lib/hecks/language/bluebook)"
 
-        # One chapter's IR, generated into its own module.
-        Chapter = Struct.new(:mod_name, :label, :ir)
+        # One bluebook's IR, generated into its own module.
+        Declaration = Struct.new(:mod_name, :label, :ir)
 
         # The `hecks-codegen` crate: the workspace's own copy when it carries one (a packaged
         # workspace does), otherwise the checkout's, so a scratch crate holding only the generated
@@ -41,14 +41,15 @@ module Hecks
 
         # @param rust_dir [String] the workspace being generated into
         # @param out_root [String] the crate's `src/generated`
-        # @param target [Chapter] the domain being projected
-        # @param chapters [Array<Chapter>] every other bluebook the target attached
-        # @param meta [Hash] the self-hosted language's IR
-        def initialize(rust_dir:, out_root:, target:, chapters:, meta:)
+        # @param target [Bluebook] the domain being projected
+        # @param bluebooks [Array<Bluebook>] every other bluebook the target attached
+        # @param meta [Hash, nil] the self-hosted language's IR; nil leaves the `meta/` module as an
+        #   earlier run wrote it
+        def initialize(rust_dir:, out_root:, target:, declarations:, meta:)
           @rust_dir = rust_dir
           @out_root = out_root
           @target = target
-          @chapters = chapters
+          @declarations = declarations
           @meta = meta
         end
 
@@ -59,7 +60,7 @@ module Hecks
           Dir.mktmpdir("hecks-codegen-full") do |tmp|
             stage = File.join(tmp, "generated")
             FileUtils.mkdir_p(stage)
-            generate_meta(stage, tmp)
+            generate_meta(stage, tmp) if @meta
             generate_target(stage, tmp)
             sync(stage)
           end
@@ -81,8 +82,8 @@ module Hecks
 
         def generate_target(stage, tmp)
           args = [stage, @target.mod_name, @target.label, write_ir(tmp, @target.mod_name, @target.ir)]
-          @chapters.each do |chapter|
-            args.push(chapter.mod_name, chapter.label, write_ir(tmp, chapter.mod_name, chapter.ir))
+          @declarations.each do |declaration|
+            args.push(declaration.mod_name, declaration.label, write_ir(tmp, declaration.mod_name, declaration.ir))
           end
           run("full", *args)
         end

data/lib/hecks/rust_build/project_rust/domain_loader.rb

@@ -10,6 +10,9 @@ module Hecks
         FRAMEWORK_FILES = %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
                              adapters/driven/prism.adapter adapters/driven/postgres_era.adapter].freeze
 
+        # A `runs` line in an `.adapter` file: the adapter is a wasm plugin.
+        RUNS_LINE = /^\s*runs\s/
+
         # @return [Hecks::Runtime::Registry] the registry the domain was loaded into
         attr_reader :registry
 
@@ -26,7 +29,7 @@ module Hecks
         end
 
         # `root:` is the domain's own directory: a domain that declares `attaches ... from: :vendor`
-        # resolves its vendored chapters beneath it.
+        # resolves its vendored bluebooks beneath it.
         #
         # @return [DomainLoader] self, with the registry loaded
         def call
@@ -35,6 +38,7 @@ module Hecks
             load_framework
             Hecks::Adapters::Folder.new.load_bluebooks(@bluebook_dir)
             load_siblings
+            load_plugins
             load_environment
           end
           @domain_name = @registry.bluebooks.keys.first
@@ -48,7 +52,7 @@ module Hecks
           FRAMEWORK_FILES.each { |file| Kernel.load(File.join(lib, file)) }
         end
 
-        # Translation edges, hecksagons (whose `attaches` loads a framework chapter into the
+        # Translation edges, hecksagons (whose `attaches` loads a framework bluebook into the
         # same registry) and worlds (whose `default_adapter` binds what a hecksagon leaves out), in
         # the order the language loads them.
         def load_siblings
@@ -57,6 +61,15 @@ module Hecks
           Dir.glob(File.join(@bluebook_dir, "*.world")).each { |file| Kernel.load(file) }
         end
 
+        # The domain's own wasm plugins, so the IR carries them to the host: only an `.adapter`
+        # that `runs` a module, since the build needs no Ruby adapter and its code may need gems
+        # the build does not have. A vendored package's plugins load with its bluebook.
+        def load_plugins
+          Dir.glob(File.join(@bluebook_dir, "{,adapters/}*.adapter")).each do |file|
+            Kernel.load(file) if File.read(file).match?(RUNS_LINE)
+          end
+        end
+
         # Production is the default environment when `environments/production.hecksagon` exists
         # (`rust/host` is the production runtime); `HECKS_PROJECT_ENVIRONMENT` overrides it.
         def load_environment

data/lib/hecks/rust_build/project_rust/root_mod/notes.rb

@@ -18,7 +18,7 @@ module Hecks
             "// every OTHER domain's `pub mod` unconditionally, so one domain's own",
             "// non-compiling generated code (a `has_many` field, before this fix)",
             "// broke every feature's build, not just its own. A shared FRAMEWORK",
-            "// chapter (governance/identity — no merged.rs of its own, so absent",
+            "// bluebook (governance/identity — no merged.rs of its own, so absent",
             "// from `domains`) stays unconditional: it has no single feature of its",
             "// own to gate behind, and is compiled in by whichever domain(s) attach",
             "// it via `attaches`."

data/lib/hecks/rust_build/project_rust/target_ir.rb

@@ -9,9 +9,9 @@ module Hecks
       # facts, so `bluebook.to_h` never mentions them).
       class TargetIr
         # The optional attachments `rust/host` reads from `ir.json`, each omitted when nothing
-        # attached provides it: exporter method, then the key it is written under.
-        SEAMS = %i[authorization membership identity newsletter newsletter_issues payments
-                   registrations payment_connection checkout].freeze
+        # attached provides it: exporter method, then the key it is written under. `provides`
+        # holds every capability a package declares, by name.
+        SEAMS = %i[authorization membership identity provides].freeze
 
         # Round-trips a value through JSON so generators see the string-keyed shape a real
         # `ir.json` carries, never live Ruby symbols.
@@ -39,6 +39,7 @@ module Hecks
           add_persistence_wiring(ir, exporter)
           add_seams(ir, exporter)
           add_edges_and_source(ir)
+          add_plugins(ir, exporter)
           ir
         end
 
@@ -52,6 +53,14 @@ module Hecks
 
         def shaped(payload) = self.class.json_shaped(payload)
 
+        # The wasm plugins the host runs for queries no hecksagon binds; none, no key.
+        #
+        # @return [void]
+        def add_plugins(document, exporter)
+          plugins = exporter.plugins(@registry)
+          document[:plugins] = shaped(plugins) unless plugins.empty?
+        end
+
         # The bound persistence adapters' declarations, from the `.adapter` files under the
         # source root's `lib/` and the domain's own directory, so the host can look them up.
         def adapters(exporter, persistence)

data/lib/hecks/rust_build/project_rust.rb

@@ -22,18 +22,25 @@ module Hecks
     # The era plugin is required unconditionally so the generator works for any domain, lineage
     # capable or not; `pg` stays lazy inside it, so nothing here opens a database connection.
     class ProjectRust
-      # @param argv [Array<String>] the domain's directory
+      # The flag that leaves the self-hosted language's `meta/` module as it is: every domain
+      # writes the same one, so a run over many domains asks for it once.
+      SKIP_META = "--skip-meta"
+
+      # @param argv [Array<String>] the domain's directory, and `--skip-meta` to leave `meta/` alone
       # @return [Integer] the exit status
       # @raise [Failure] when the domain's name cannot be a Rust module and Cargo feature name
       def self.call(argv)
-        domain = argv.first or raise Failure, "usage: hecks project_rust <domain>"
-        new(domain).call
+        flags, paths = argv.partition { |arg| arg == SKIP_META }
+        domain = paths.first or raise Failure, "usage: hecks project_rust <domain> [#{SKIP_META}]"
+        new(domain, skip_meta: !flags.empty?).call
       end
 
       # @param domain [String] the domain's directory
-      def initialize(domain)
+      # @param skip_meta [Boolean] leave the `meta/` module as an earlier run wrote it
+      def initialize(domain, skip_meta: false)
         @domain = domain
         @mod_name = File.basename(domain)
+        @skip_meta = skip_meta
       end
 
       # @return [Integer] the exit status
@@ -71,7 +78,7 @@ module Hecks
       end
 
       def prepare_output
-        @rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(RustBuild::ROOT, "rust"))
+        @rust_dir = RustBuild.rust_dir
         @out_root = File.join(@rust_dir, "src/generated")
         FileUtils.mkdir_p(@out_root)
       end
@@ -79,31 +86,38 @@ module Hecks
       # `hecks-codegen` is the generator; this process only builds the IR it reads from the live
       # registry, so a domain's persistence, seams, translations and source text reach `ir.json`.
       def generate_with_codegen
-        meta = Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
         CodegenRun.new(
-          rust_dir: @rust_dir, out_root: @out_root, meta: TargetIr.json_shaped(meta), chapters: chapters,
-          target: CodegenRun::Chapter.new(@mod_name, @domain, @ir)
+          rust_dir: @rust_dir, out_root: @out_root, meta: meta_ir, declarations: declarations,
+          target: CodegenRun::Declaration.new(@mod_name, @domain, @ir)
         ).call
       end
 
-      def chapters
+      # @return [Hash, nil] the self-hosted language's IR, or nil when `--skip-meta` leaves it be
+      def meta_ir
+        return nil if @skip_meta
+
+        meta = Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
+        TargetIr.json_shaped(meta)
+      end
+
+      def declarations
         vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
         (@registry.bluebooks.keys - [@domain_name]).map do |name|
           ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
           label = "#{@domain} (#{attachment(name, vendored)})"
-          CodegenRun::Chapter.new(name.downcase, label, TargetIr.json_shaped(ir))
+          CodegenRun::Declaration.new(name.downcase, label, TargetIr.json_shaped(ir))
         end
       end
 
-      # How the target attached a chapter, across every hecksagon the registry loaded: a chapter a
+      # How the target attached a bluebook, across every hecksagon the registry loaded: a bluebook a
       # sibling hecksagon vendors in is labelled as vendored.
-      def attachment(chapter_name, vendored)
-        name = vendored.find { |candidate| Hecks::Naming.pascal(candidate.to_s) == chapter_name }
-        name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{chapter_name.inspect}"
+      def attachment(declaration_name, vendored)
+        name = vendored.find { |candidate| Hecks::Naming.pascal(candidate.to_s) == declaration_name }
+        name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{declaration_name.inspect}"
       end
 
       # `src/generated/mod.rs`: every domain ever generated, scanned off disk. A directory is a
-      # selectable domain exactly when it carries its own `merged.rs`; a framework chapter has
+      # selectable domain exactly when it carries its own `merged.rs`; a framework bluebook has
       # none and is always compiled in.
       def write_root_mod
         all_dirs = Dir.children(@out_root).select { |name| File.directory?(File.join(@out_root, name)) }.sort
@@ -121,9 +135,9 @@ module Hecks
       def sync_cargo_features
         path = File.join(@rust_dir, "Cargo.toml")
         manifest = File.read(path)
-        manifest = manifest.sub(/\A/, FEATURES_HEADER) unless manifest.include?("[features]")
+        manifest = "#{FEATURES_HEADER}#{manifest}" unless manifest.include?("[features]")
         @domains.each { |name| manifest = add_feature(manifest, name) }
-        manifest = manifest.sub(/^default\s*=.*$/, "default = [#{@mod_name.inspect}]")
+        manifest = manifest.sub(DEFAULT_FEATURE, "default = [#{@mod_name.inspect}]")
         # An unchanged manifest is not rewritten: a new mtime makes Cargo rebuild the whole crate.
         if WriteIfChanged.call(path, manifest)
           puts "wrote #{path} (default feature: #{@mod_name})"
@@ -135,10 +149,10 @@ module Hecks
       # Checked against the `[features]` table only: `[package]`'s `name` or a `[[bin]]` path can
       # share a word with a domain name.
       def add_feature(manifest, name)
-        table = manifest[/^\[features\](?:\n(?!\[).*)*$/] || ""
+        table = manifest[FEATURES_TABLE] || ""
         return manifest if table =~ /^#{Regexp.escape(name)}\s*=/
 
-        manifest.sub(/^default\s*=.*$/) { "#{Regexp.last_match(0)}\n#{name} = []" }
+        manifest.sub(DEFAULT_FEATURE) { "#{Regexp.last_match(0)}\n#{name} = []" }
       end
 
       FEATURES_HEADER = <<~TOML
@@ -154,6 +168,12 @@ module Hecks
 
       TOML
       private_constant :FEATURES_HEADER
+
+      # The `default = [...]` line of a Cargo manifest's `[features]` table.
+      DEFAULT_FEATURE = /^default\s*=.*$/
+      # The `[features]` table of a Cargo manifest, up to the next table header.
+      FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*$/
+      private_constant :DEFAULT_FEATURE, :FEATURES_TABLE
     end
   end
 end

data/lib/hecks/rust_build/target_dir.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../rust_build"
+
+module Hecks
+  module RustBuild
+    # Where Cargo writes a crate's build output.
+    #
+    # A checkout of hecks builds into the crate's own `target/`. An installed copy (a gem, or a
+    # bundler checkout of a git revision) sits under `Gem.path`, where every new revision is a new
+    # directory, so a build there goes to one shared cache instead: each revision reuses the last
+    # one's compiled dependencies, and the output is kept once rather than once per revision.
+    # `CARGO_TARGET_DIR` overrides both.
+    module TargetDir
+      module_function
+
+      # @param crate_dir [String] the crate's directory
+      # @param root [String] the hecks copy the crate belongs to
+      # @return [String] the directory Cargo writes the crate's output to
+      def for(crate_dir, root: ROOT)
+        ENV.fetch("CARGO_TARGET_DIR") do
+          installed?(root) ? shared(File.basename(crate_dir)) : File.join(crate_dir, "target")
+        end
+      end
+
+      # @param root [String] a hecks copy's directory
+      # @return [Boolean] whether the copy is installed under one of RubyGems' directories
+      def installed?(root)
+        Gem.path.any? { |dir| File.expand_path(root).start_with?(File.join(File.expand_path(dir), "")) }
+      end
+
+      # @param name [String] the crate's name
+      # @return [String] the crate's directory in the per-user cache
+      #   (`XDG_CACHE_HOME`, else `~/.cache`)
+      def shared(name)
+        File.join(ENV.fetch("XDG_CACHE_HOME", File.join(Dir.home, ".cache")), "hecks", "cargo-target", name)
+      end
+    end
+  end
+end