hecks 2.5.1 → 2.7.0

data/lib/hecks/release/gem_pin.rb

@@ -0,0 +1,112 @@
+require_relative "gem_pin/published_versions"
+
+module Hecks
+  module Release
+    # Finds the hecks version a project runs on, and refuses one that a
+    # stranger could not install.
+    #
+    # ## Why it exists
+    #
+    # A project that is copied out of its own workspace (handed to someone who
+    # will `bundle install` it, or built in an image with no sibling checkout)
+    # has to name a hecks release RubyGems actually publishes. A `path:` or
+    # `git:` source only works where the path or remote is reachable, and a
+    # version that was never published resolves nowhere. This reads the
+    # project's Gemfiles and lockfiles, without running Bundler, and says which
+    # version each pins or refuses.
+    #
+    # ## Resolution
+    #
+    # For each `Gemfile` under the root (a project can hold several, such as a
+    # domain and a helper app) the pin is, in order: the version its
+    # `Gemfile.lock` resolved, or the newest stable release its version
+    # constraint allows. Each pin must be published; the Gemfiles need not
+    # agree.
+    #
+    # ## Injectable network
+    #
+    # The published list comes from `published:`, any object answering
+    # `include?(version)` and `newest_satisfying(requirement)`. The default asks
+    # RubyGems; a caller without network hands in its own.
+    class GemPin
+      GEM_LINE = /^\s*gem\s+["']hecks["'](?<rest>.*)$/
+      SOURCE_OPTION = /\b(?:path|git|github|gitlab|bitbucket|branch|ref|tag):/
+      LOCKED = /^    hecks \((?<version>[^)]+)\)/
+
+      # What `resolve` found.
+      #
+      # @!attribute [r] version
+      #   @return [String] the newest pin
+      # @!attribute [r] pins
+      #   @return [Hash{String => String}] each Gemfile that declares hecks, relative to the
+      #     root, mapped to the version it runs on
+      Resolved = Struct.new(:version, :pins, keyword_init: true)
+
+      # @param published [#include?, #newest_satisfying] the source of published versions
+      def initialize(published: PublishedVersions.new)
+        @published = published
+      end
+
+      # Resolves the hecks versions the project in `root` runs on.
+      #
+      # @param root [String] the project's root directory
+      # @return [Resolved] the newest pin and every pin
+      # @raise [Error] if no Gemfile declares hecks, one takes it from a source other than
+      #   RubyGems, one pins a version RubyGems does not publish, or a constraint allows
+      #   no published release
+      def resolve(root)
+        pins = gemfiles(root).filter_map { |gemfile| pin_for(gemfile, root) }.to_h
+        raise Error, "no Gemfile declares the hecks gem, so this is not a Hecks project" if pins.empty?
+
+        pins.each do |rel, version|
+          raise Error, "hecks #{version} is not published on RubyGems (#{rel})" unless @published.include?(version)
+        end
+        Resolved.new(version: pins.values.max_by { |version| Gem::Version.new(version) }, pins: pins)
+      end
+
+      private
+
+      def gemfiles(root)
+        Dir.glob("**/Gemfile", base: root).reject { |rel| rel.include?("node_modules/") }.sort
+           .map { |rel| File.join(root, rel) }
+      end
+
+      def pin_for(gemfile, root)
+        declaration = File.read(gemfile).match(GEM_LINE) or return nil
+        rel = gemfile.delete_prefix("#{root}/")
+        if (source = declaration[:rest][SOURCE_OPTION])
+          raise Error, "#{rel} takes hecks from `#{source}`, not from RubyGems; the project must use a published version"
+        end
+
+        [rel, locked_version(gemfile, rel) || newest_allowed(declaration[:rest], rel)]
+      end
+
+      # The version Gemfile.lock resolved, if there is a lockfile. A hecks
+      # entry under `PATH` or `GIT` means the lockfile is not installable either.
+      def locked_version(gemfile, rel)
+        lock = "#{gemfile}.lock"
+        return nil unless File.exist?(lock)
+
+        text = File.read(lock)
+        refuse_unpublished_source!(text, rel)
+        text.match(LOCKED)&.[](:version)
+      end
+
+      def refuse_unpublished_source!(lock_text, rel)
+        lock_text.split("\n\n").each do |section|
+          next unless section.start_with?("PATH", "GIT") && section.match?(LOCKED)
+
+          raise Error, "#{rel}.lock resolves hecks from a #{section.lines.first.strip} source, not from RubyGems"
+        end
+      end
+
+      def newest_allowed(rest, rel)
+        constraints = rest.scan(/["']([^"']+)["']/).flatten.grep(/\A\s*(?:[~><=!]+\s*)?\d/)
+        version = @published.newest_satisfying(Gem::Requirement.new(*constraints))
+        raise Error, "no published hecks release satisfies the constraint in #{rel}" unless version
+
+        version.to_s
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_rules/arithmetic.rb

@@ -123,7 +123,7 @@ module Hecks
           amount = unwrap_single_numeric_field(amount) if amount.is_a?(Value)
 
           # Widened from Integer to Numeric (migration plan task 4, i106):
-          # miette's organ math increments a Float (`increment: 0.02`) --
+          # an external project's organ math increments a Float (`increment: 0.02`) --
           # the raw, non-value-object path only ever mattered for Integer
           # counters before this corpus existed. Integer stays the common
           # case; Float is now accepted the same way.
@@ -192,7 +192,7 @@ module Hecks
           amount_fields  = amount.to_h
           # Widened from Integer to Numeric -- see #arithmetic's own
           # comment. A synthesised value-object wrapper around a bare
-          # Float attribute (miette's Synapse#strength, auto-wrapped per
+          # Float attribute (an external project's Synapse#strength, auto-wrapped per
           # Part 3a's "bare primitives forbidden" finding) lands here as
           # a one-Float-field Value exactly the way a one-Integer-field
           # Value already did.

data/lib/hecks/runtime/loader.rb

@@ -180,7 +180,8 @@ module Hecks
       # ADR 0033 — this loader no longer names `EraCheck`, or any other
       # era-specific class, at all. Every loaded persistence plugin
       # (`Ports::Persistence.each_plugin` — nothing here if nothing was
-      # ever `require`d) is asked to contribute its own `:pre_verify`/
+      # ever `require`d, or brought in by a bound adapter, see
+      # `load_bound_adapters!`) is asked to contribute its own `:pre_verify`/
       # `:post_verify` gates generically; `:saga_rehydration` is the one
       # gate core still registers directly, because ADR 0031 already
       # proved it's not era-specific.
@@ -193,6 +194,7 @@ module Hecks
       #   a wiring problem
       def self.run_boot_gates!(registry, directory)
         gates = BootGates.new
+        load_bound_adapters!(registry)
         Ports::Persistence.each_plugin { |plugin| plugin.contribute_boot_gates(registry, gates) }
         check_compute_rules_backstop!(registry)
 
@@ -200,11 +202,33 @@ module Hecks
         registry.verify!
 
         gates.register(:saga_rehydration, ->(reg, _dir) { reg.rehydrate_sagas! }, phase: :post_verify) if
-          registry.hecksagons.each_key.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
+          registry.saga_domains.any? { |domain| registry.saga_persistence(domain) != Ports::Persistence::NULL_SAGA_STORE }
         gates.run!(:post_verify, registry, directory)
         gates
       end
 
+      # Resolves the Ruby implementation of every adapter a hecksagon binds.
+      #
+      # An adapter whose implementation loads on first mention (`PostgresEra`,
+      # through the era plugin) registers its persistence plugin as a side effect
+      # of that load. Resolving here, before the gates are collected, is what makes
+      # a domain that declares `persisted_by "PostgresEra"` boot with the plugin
+      # loaded and its era gates registered, without the app requiring the plugin
+      # itself. An adapter with no Ruby implementation is left for `verify!`, which
+      # refuses it with the bind it came from.
+      #
+      # @param registry [Runtime::Registry] the registry mid-boot, whose hecksagons name the binds
+      # @return [void]
+      def self.load_bound_adapters!(registry)
+        registry.hecksagons.each_value do |hexagon|
+          hexagon.binds.each do |bind|
+            registry.adapter_class(bind.adapter)
+          rescue WiringError
+            next
+          end
+        end
+      end
+
       # The one piece of the old, era-owned `check_compute_rules!` core
       # still carries — deliberately thinner. `registry.translations` is
       # plain `Bluebook::Translation`/`TranslationAggregate`/

data/lib/hecks/runtime/registry/saga_persistence.rb

@@ -56,7 +56,13 @@ module Hecks
           end
         end
 
-        # Walks every loaded domain, repopulating `saga_instances` from
+        # Every domain whose sagas can persist somewhere: one with a hecksagon, or one a
+        # world's `default_adapter` binds though it has none.
+        #
+        # @return [Array<String>] the domain names, hecksagon domains first
+        def saga_domains = @hecksagons.keys | @bluebooks.keys.select { |domain| default_adapter_for(domain) }
+
+        # Walks every loaded domain in `saga_domains`, repopulating `saga_instances` from
         # whatever `saga_persistence(domain)` resolves to — a real store
         # for a domain whose adapter answers the capability, `each_saga`
         # yielding real rows; `NULL_SAGA_STORE`'s own `each_saga` for
@@ -79,7 +85,7 @@ module Hecks
         #
         # @return [Hecks::Runtime::Registry] self
         def rehydrate_sagas!
-          @hecksagons.each_key do |domain|
+          saga_domains.each do |domain|
             saga_persistence(domain).each_saga do |process_manager, correlation, state, memory, completed_compensations = []|
               pending = memory.delete(SAGA_PENDING_DISPATCH_KEY)
               @saga_instances[process_manager][correlation] =

data/lib/hecks/runtime/registry/verification.rb

@@ -17,10 +17,12 @@ module Hecks
         # @raise [Runtime::WiringError] if a bind names an undeclared aggregate, an
         #   adapter cannot satisfy its port's verb or declared `answers`, a world
         #   setting names a field its adapter does not declare, the default adapter
-        #   is unusable, a command declares a role with no authorization provider
-        #   attached, or a membership chapter is loaded with no identity chapter
+        #   is unusable, a world's `default_adapter` is not a persistence adapter, a
+        #   command declares a role with no authorization provider attached, or a
+        #   membership chapter is loaded with no identity chapter
         def verify!
           verify_default_adapter!
+          verify_world_defaults!
           verify_singleton_port_answers!
           refuse_cross_package_bluebook_merge!
           refuse_membership_without_identity!

data/lib/hecks/runtime/registry/world_defaults.rb

@@ -0,0 +1,106 @@
+module Hecks
+  module Runtime
+    class Registry
+      # **World defaults** — the `default_database` and `default_adapter` words a
+      # `.world` can declare once for every chapter a boot loaded, resolved against
+      # the registry's own worlds. Included into Registry; the callers are the
+      # persistence binding policy (`default_adapter_for`), every reader of a bind's
+      # world settings (`binding_settings`), and `verify!` (`verify_world_defaults!`).
+      #
+      # **Resolution order**, most specific first — nothing here ever overrides a
+      # chapter's own explicit declaration:
+      #
+      #   1. the chapter's own `persisted_by(...) { database ... }` block, and the
+      #      hecksagon bind (aggregate-specific, then domain-level) that names its adapter;
+      #   2. the default declared by the chapter's own world;
+      #   3. the default declared by the project's world — the world of the first
+      #      chapter the boot loaded, the same convention `Loader#dispatcher_for` uses
+      #      to find the domain a boot targets;
+      #   4. today's behavior: no database setting, and the framework's in-memory
+      #      adapter for a chapter with no hecksagon.
+      #
+      # A default is resolved when a bind's settings or binding are asked for, never
+      # written into a chapter's world or hecksagon, so a chapter's own declarations
+      # stay exactly what its files say and a hecksagon-less chapter still trips the
+      # sibling-hecksagon gates the way it always did.
+      module WorldDefaults
+        # The settings a chapter's world gives one bind, with the project's default
+        # database filled in where the chapter left it out.
+        #
+        # The default database only ever reaches a persistence bind whose adapter
+        # declares a `database` field — a projection or an adapter without one is
+        # untouched. A `database` the chapter's own settings name wins; every other
+        # setting the chapter declared rides along unchanged.
+        #
+        # @param domain [String, Symbol] the domain whose world is asked
+        # @param verb [String, Symbol] the bind's port verb, such as `"persisted_by"`
+        # @param adapter [String, Symbol] the bind's adapter name
+        # @return [Hash{Symbol => Object}] the chapter's own settings for the bind, plus
+        #   `:database` from the default when one applies; `{}` when there is nothing
+        def binding_settings(domain, verb, adapter)
+          declared = world(domain)&.for_binding(verb, adapter) || {}
+          database = default_database_for(domain)
+          return declared unless database && default_database_applies?(verb, adapter)
+
+          { adapter: adapter.to_s, database: database }.merge(declared)
+        end
+
+        # The persistence adapter a chapter's aggregates fall back to when their
+        # hecksagon does not bind them.
+        #
+        # @param domain [String, Symbol] the domain to resolve the default for
+        # @return [String, nil] the chapter's own world's `default_adapter`, else the
+        #   project's; `nil` when neither declares one
+        def default_adapter_for(domain) = world_default(domain, :default_adapter)
+
+        # The database connection a chapter's database-taking persistence adapter uses
+        # when its own settings name none.
+        #
+        # @param domain [String, Symbol] the domain to resolve the default for
+        # @return [String, nil] the chapter's own world's `default_database`, else the
+        #   project's; `nil` when neither declares one
+        def default_database_for(domain) = world_default(domain, :default_database)
+
+        # Refuses a `default_adapter` that no persistence adapter answers to.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if a world's `default_adapter` names an unknown
+        #   adapter, one that is not a persistence adapter, or one with no Ruby
+        #   implementation
+        def verify_world_defaults!
+          @worlds.each_value do |declared|
+            name = declared.default_adapter
+            next unless name
+
+            verify_default_adapter_named!(declared.domain, name)
+          end
+          self
+        end
+
+        private
+
+        # The chapter's own world answers first; the project's world fills the gap.
+        def world_default(domain, field)
+          world(domain)&.public_send(field) || project_world&.public_send(field)
+        end
+
+        # The world of the first chapter this registry loaded — the target of a boot, ahead of
+        # any framework member it attaches.
+        def project_world = world(@bluebooks.keys.first || @worlds.keys.first)
+
+        def default_database_applies?(verb, adapter)
+          verb.to_s == Ports::Persistence::VERB && @adapters[adapter.to_s]&.declares?(:database)
+        end
+
+        def verify_default_adapter_named!(domain, name)
+          check_verb(Bluebook::Bind.new(aggregate: "(default)", verb: Ports::Persistence::VERB, adapter: name))
+          adapter_class(name)
+        rescue WiringError => e
+          raise WiringError,
+                "#{domain}'s world declares default_adapter #{name.inspect}, which is not a usable " \
+                "persistence adapter: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry.rb

@@ -1,5 +1,6 @@
 require_relative "registry/verification"
 require_relative "registry/saga_persistence"
+require_relative "registry/world_defaults"
 require_relative "outbox"
 require_relative "../naming"
 
@@ -10,10 +11,12 @@ module Hecks
     # The collections a boot gathers — bluebooks, hexagons, ports, adapters,
     # worlds, the logs — and how a repository is resolved from them. The
     # wiring gate lives in registry/verification.rb, saga persistence
-    # resolution in registry/saga_persistence.rb.
+    # resolution in registry/saga_persistence.rb, and a `.world`'s project-wide
+    # defaults in registry/world_defaults.rb.
     class Registry
       include Verification
       include SagaPersistence
+      include WorldDefaults
 
       attr_reader :root, :bluebooks, :hecksagons, :ports, :adapters, :worlds, :event_log,
                   :reaction_log, :saga_log, :saga_instances, :translations, :saga_mutex,
@@ -257,7 +260,7 @@ module Hecks
       # entry into a real `Privacy::Marking.Mark` once a dispatcher exists.
       #
       # @param domain [String] the marked attribute's own aggregate FQN, e.g.
-      #   `"Lifeadelics::Registration"`
+      #   `"Site::Registration"`
       # @param attribute_path [String] the dotted path within that aggregate, e.g.
       #   `"attendee.medications"`
       # @param category [String] the marking's own sensitivity category, e.g. `"phi"`
@@ -593,7 +596,7 @@ module Hecks
       #   concatenated, `base` then `overlay`
       def merge_hecksagons(base, overlay)
         # Same-name blocks concatenate regardless of which file they came
-        # from (`lifeadelics.hecksagon`, `context_map.hecksagon`, an
+        # from (`site.hecksagon`, `context_map.hecksagon`, an
         # environment overlay). Order-independent: list facts uniq, so
         # loading context_map before or after the domain file is the same
         # merged hecksagon. Binds stay concatenated (BindingPolicy still
@@ -610,8 +613,8 @@ module Hecks
       end
 
       # Recovered and generalized — see `add_world`'s own comment. `realm`/
-      # `latest` are scalars, so the overlay's value wins when present,
-      # else the base's survives; `settings` is a shallow merge keyed by
+      # `latest`, `default_database` and `default_adapter` are scalars, so the overlay's
+      # value wins when present, else the base's survives; `settings` is a shallow merge keyed by
       # verb (and `"verb:adapter"`) — an overlay entry for a key the base
       # also declares replaces that key's whole resolved hash (the same
       # all-or-nothing shape `WorldBuilder#method_missing` already builds
@@ -623,10 +626,12 @@ module Hecks
       #   present, and `settings` shallow-merged, `overlay`'s keys winning
       def merge_worlds(base, overlay)
         Bluebook::World.new(
-          domain:   base.domain,
-          realm:    overlay.realm || base.realm,
-          latest:   overlay.latest || base.latest,
-          settings: base.settings.merge(overlay.settings)
+          domain:           base.domain,
+          realm:            overlay.realm || base.realm,
+          latest:           overlay.latest || base.latest,
+          settings:         base.settings.merge(overlay.settings),
+          default_database: overlay.default_database || base.default_database,
+          default_adapter:  overlay.default_adapter || base.default_adapter
         )
       end
     end

data/lib/hecks/runtime/tenant_check.rb

@@ -38,7 +38,7 @@ module Hecks
     # search_path` — proven for real, not assumed, by
     # tenant_isolation_spec.rb. Plain Postgres (no schema story) and D1
     # (no schema-equivalent at all — see world.bluebook's own comment on
-    # the lifeadelics D1 tradeoff) answer false, or don't answer at all,
+    # the D1 tradeoff) answer false, or don't answer at all,
     # which this module treats identically to false.
     module TenantCheck
       module_function

data/lib/hecks/vendoring/git_environment.rb

@@ -0,0 +1,35 @@
+module Hecks
+  module Vendoring
+    # The environment a `git` subprocess needs so it resolves its repository
+    # from the directory it is pointed at, not from whoever launched Ruby.
+    #
+    # Git exports `GIT_DIR`, `GIT_INDEX_FILE` and their kin to the hooks it
+    # runs (a push from a linked worktree runs `pre-push` this way). Every
+    # `git` that a hook's process tree starts inherits them, and they outrank
+    # both `git -C` and the working directory: a command aimed at a scratch
+    # repository would read, or commit into, the repository that was pushing.
+    module GitEnvironment
+      # The variables that pin git to one repository, work tree or index.
+      INHERITED = %w[
+        GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_PREFIX GIT_COMMON_DIR
+        GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
+      ].freeze
+
+      # An environment hash for `Open3`, `IO.popen` and `system` that unsets
+      # every repository-pinning variable and leaves the rest alone.
+      #
+      # @return [Hash{String => nil}] each inherited variable mapped to nil
+      def self.clean
+        INHERITED.to_h { |name| [name, nil] }
+      end
+
+      # Removes the repository-pinning variables from this process's own
+      # environment, so every later `git` child starts clean.
+      #
+      # @return [void]
+      def self.scrub!
+        INHERITED.each { |name| ENV.delete(name) }
+      end
+    end
+  end
+end

data/lib/hecks/vendoring/git_source.rb

@@ -0,0 +1,102 @@
+require "open3"
+require "tmpdir"
+require_relative "git_environment"
+
+module Hecks
+  module Vendoring
+    # A local git repository read through the `git` executable, never through
+    # its working tree.
+    #
+    # Everything here names a commit and reads what that commit holds, so a
+    # shared checkout with uncommitted edits, or a different branch checked
+    # out, cannot leak into what gets vendored. Every command runs under
+    # {GitEnvironment.clean}, so a `GIT_DIR` inherited from a hook cannot
+    # redirect it to some other repository.
+    class GitSource
+      # @param path [String] a directory that is a git repository (or a
+      #   worktree of one)
+      # @raise [Vendoring::Error] if `path` is not a directory
+      def initialize(path)
+        @path = File.expand_path(path.to_s)
+        raise Error, "no source repository at #{@path}" unless File.directory?(@path)
+      end
+
+      # @return [String] the absolute path of the repository
+      attr_reader :path
+
+      # Resolves a commit-ish to the full commit id it names.
+      #
+      # @param ref [String] a branch, tag, abbreviated or full commit id
+      # @return [String] the 40-character commit id
+      # @raise [Vendoring::Error] if `ref` names no commit in the repository
+      def commit(ref)
+        out, _err, status = git("rev-parse", "--verify", "--quiet", "#{ref}^{commit}")
+        raise Error, "no commit #{ref.inspect} in #{@path}" unless status.success?
+
+        out.strip
+      end
+
+      # Lists tag names matching a shell pattern.
+      #
+      # @param pattern [String] a `git tag --list` pattern, such as `"payments-v*"`
+      # @return [Array<String>] the matching tag names, in git's own order
+      def tags(pattern)
+        out, _err, status = git("tag", "--list", pattern)
+        status.success? ? out.lines.map(&:chomp) : []
+      end
+
+      # Reads one file as a commit holds it.
+      #
+      # @param ref [String] the commit-ish to read from
+      # @param file [String] a repository-relative path
+      # @return [String, nil] the file's content, or nil when the commit has no such file
+      def read(ref, file)
+        out, _err, status = git("show", "#{ref}:#{file}")
+        status.success? ? out : nil
+      end
+
+      # Lists the files directly inside a directory of a commit.
+      #
+      # Subdirectories are left out on purpose: a vendored package carries the
+      # top-level files of its subtree and nothing nested beneath.
+      #
+      # @param ref [String] the commit-ish to read from
+      # @param subtree [String] a repository-relative directory, such as `"payments/bluebook"`
+      # @param glob [String] a `File.fnmatch` pattern the file's own name must match
+      # @return [Array<String>] repository-relative paths, sorted
+      def files(ref, subtree, glob = "*")
+        out, _err, status = git("ls-tree", "-r", "--name-only", ref, "--", subtree)
+        return [] unless status.success?
+
+        out.lines.map(&:chomp).select do |file|
+          File.dirname(file) == subtree && File.fnmatch(glob, File.basename(file))
+        end.sort
+      end
+
+      # Extracts named files of a commit into a directory with `git archive`,
+      # keeping their repository-relative paths.
+      #
+      # @param ref [String] the commit-ish to export
+      # @param files [Array<String>] repository-relative paths to export
+      # @param into [String] an existing directory to extract into
+      # @return [void]
+      # @raise [Vendoring::Error] if `git archive` or `tar` fails
+      def export(ref, files, into)
+        Dir.mktmpdir("hecks-archive") do |scratch|
+          tarball = File.join(scratch, "export.tar")
+          run!("git archive", "git", "-C", @path, "archive", "--format=tar", "--output=#{tarball}", ref, "--", *files)
+          run!("tar", "tar", "-xf", tarball, "-C", into)
+        end
+      end
+
+      private
+
+      def git(*) = Open3.capture3(GitEnvironment.clean, "git", "-C", @path, *)
+
+      def run!(label, *command)
+        _out, err, status = Open3.capture3(GitEnvironment.clean, *command)
+        raise Error, "#{label} failed: #{err.lines.first.to_s.strip}" unless status.success?
+      end
+    end
+  end
+end

data/lib/hecks/vendoring.rb

@@ -0,0 +1,102 @@
+require "fileutils"
+require "tmpdir"
+require_relative "vendoring/git_environment"
+require_relative "vendoring/git_source"
+
+module Hecks
+  # Pins an exact commit of one directory of another repository into a
+  # project's own tree.
+  #
+  # ## What it is
+  #
+  # A project that consumes a package from a private repository cannot clone
+  # that repository when its image builds, and a live pull would make the build
+  # depend on whatever is checked out. So the files are exported from one
+  # commit, committed into the consumer, and a marker file beside them records
+  # which commit they came from. Only the files directly inside the named
+  # subtree are taken; the source's own specs, ports, adapters and data stay
+  # where they are.
+  #
+  # ## Marker
+  #
+  # `VENDORED_COMMIT` holds the full 40-character commit id and a newline, so
+  # `git -C <source> show <id>:<subtree>` reproduces the vendored files. The
+  # marker sits in `into`, beside the exported directory.
+  #
+  # ## Whole-directory replacement
+  #
+  # A pin replaces `into` entirely, so a file the source dropped does not
+  # linger. Nothing is touched until the export succeeded and the optional
+  # block accepted it.
+  module Vendoring
+    # Raised when a pin cannot be made or is refused.
+    class Error < StandardError; end
+
+    # File name of the commit marker written into every pinned directory.
+    MARKER = "VENDORED_COMMIT".freeze
+
+    # What a pin produced.
+    #
+    # @!attribute [r] commit
+    #   @return [String] the full commit id the files were exported from
+    # @!attribute [r] dir
+    #   @return [String] the directory holding the exported subtree
+    # @!attribute [r] files
+    #   @return [Array<String>] the exported files' names, sorted
+    Pin = Struct.new(:commit, :dir, :files, keyword_init: true)
+
+    # Exports the top-level files of one directory at one commit into `into`.
+    #
+    # The exported files land in `into/<last segment of subtree>/`; the marker
+    # lands in `into` itself. The optional block sees the staged files before
+    # anything is replaced and may raise to refuse the pin.
+    #
+    # @param from [String] path of the local source repository
+    # @param ref [String] the commit-ish to export (branch, tag or commit id)
+    # @param subtree [String] repository-relative directory to export, such as
+    #   `"payments/bluebook"`
+    # @param into [String] the directory to replace with the export
+    # @param glob [String] `File.fnmatch` pattern each exported file's name must match
+    # @param marker [String] name of the file recording the commit
+    # @yield [staged, commit] the staged files, before `into` is touched
+    # @yieldparam staged [String] directory holding the exported files
+    # @yieldparam commit [String] the resolved commit id
+    # @yieldreturn [Hash{String => String}, nil] extra files to write into `into`,
+    #   keyed by file name; nil for none
+    # @return [Pin] the commit and where the files landed
+    # @raise [Vendoring::Error] if the source is missing, `ref` names no commit,
+    #   the subtree holds no matching file, or the block refuses
+    def self.pin(from:, ref:, subtree:, into:, glob: "*", marker: MARKER)
+      source = GitSource.new(from)
+      commit = source.commit(ref)
+      files = source.files(commit, subtree, glob)
+      raise Error, "no #{glob} files in #{subtree} at #{ref} in #{source.path}" if files.empty?
+
+      Dir.mktmpdir("hecks-vendoring") do |stage|
+        source.export(commit, files, stage)
+        staged = File.join(stage, subtree)
+        extras = block_given? ? yield(staged, commit) : nil
+        install(staged, into, marker, commit, extras || {})
+        Pin.new(commit: commit, dir: File.join(into, File.basename(subtree)),
+                files: files.map { |file| File.basename(file) })
+      end
+    end
+
+    # Replaces `into` with the staged files, the marker and any extras.
+    #
+    # @param staged [String] directory holding the exported files
+    # @param into [String] the directory to replace
+    # @param marker [String] marker file name
+    # @param commit [String] commit id the marker records
+    # @param extras [Hash{String => String}] more files to write into `into`
+    # @return [void]
+    def self.install(staged, into, marker, commit, extras)
+      FileUtils.rm_rf(into)
+      FileUtils.mkdir_p(into)
+      FileUtils.cp_r(staged, File.join(into, File.basename(staged)))
+      File.write(File.join(into, marker), "#{commit}\n")
+      extras.each { |name, text| File.write(File.join(into, name), text) }
+    end
+    private_class_method :install
+  end
+end

data/lib/hecks/version.rb

@@ -12,5 +12,5 @@ module Hecks
   # it there, or even in the consuming Gemfile, never closed the gap,
   # because gemspec evaluation happens before anything Bundler
   # resolves is actually loadable yet.
-  VERSION = "2.5.1".freeze
+  VERSION = "2.7.0".freeze
 end