hecks 2.7.0 → 2.9.0

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -1,23 +1,5 @@
-# A TOOLING-INTERNAL DOMAIN, not a business one — never attached via
-# `uses_framework`, never seen by an end-user domain. `bin/project_deploy`
-# boots this directory directly (Ports::Loading.bootstrap + load_domain,
-# the same pipeline lib/hecks/runtime/loader.rb uses, minus a
-# `.world`/`.hecksagon` this domain has no need for) and dispatches one
-# command against it before generating anything from a domain's own
-# `deployed_to("AwsLambda")` settings.
-#
-# WHY THIS EXISTS: `world.bluebook`'s `Wiring`/`Setting` is a DELIBERATELY
-# open, untyped map — "a verb's schema is not even contained in the file
-# being parsed" (syntax.bluebook's own header on this). That's the right
-# call for `Wiring` itself (an adapter verb's shape genuinely isn't the
-# world language's business), but it leaves `deployed_to`'s ACTUAL shape
-# validated nowhere — `bin/project_deploy` used to check it by hand
-# (`deploy_settings[:adapter] == "AwsLambda" or abort ...`,
-# `fetch(:region) { abort ... }`), the exact raw-Ruby-refusal pattern
-# every other kind of bluebook mistake in this codebase does NOT use.
-# This closes that gap the same way any other rule gets enforced here:
-# as a real command, real invariants, a real corpus-testable refusal —
-# not a hand-written abort string discovered only by running the script.
+# Tooling-internal domain `bin/project_deploy` boots directly; never attached via `uses_framework`.
+# It validates the `deployed_to` shape that `world.bluebook`'s untyped `Setting` map leaves open.
 Hecks.bluebook "Deploy" do
   aggregate "LambdaTarget" do
     description "One domain's validated AWS Lambda deploy target — what deployed_to(\"AwsLambda\") must resolve to before bin/project_deploy generates anything from it."
@@ -41,77 +23,39 @@ Hecks.bluebook "Deploy" do
       invariant("a region is named") { !value.to_s.empty? }
     end
 
-    # "Postgres" (a plain AWS::RDS::DBInstance, Embryonaut's own live
-    # choice — bin/project_deploy's Ruby-side default when a domain's
-    # own deployed_to("AwsLambda") names none, so every domain
-    # declared before this attribute existed keeps generating the
-    # identical template it always has) or "Aurora" (Aurora Serverless
-    # v2, Postgres-compatible — the SAME `Adapters::Postgres`/
-    # `tokio_postgres` code on both the Ruby and rust/host sides
-    # either way; this only changes which CloudFormation resource
-    # bin/project_deploy emits, never a runtime adapter).
-    # "Shared" — no RDS/VPC of this domain's own at all; it borrows
-    # another already-deployed domain's instance instead (the
-    # storehouse), isolated from that domain's own data by a native
-    # Postgres SCHEMA (this domain's own lowercase name), not a
-    # separate database. Requires a sibling `owner "OtherDomain"`
-    # setting inside the SAME deployed_to("AwsLambda") block, naming
-    # which already-deployed domain owns the shared instance —
-    # bin/project_deploy checks for that setting itself (Ruby-level,
-    # the same as `pg_version`/`google_oauth_present` below it), not
-    # here: which domain owns the instance is a deploy-time fact, not
-    # a business invariant this validated aggregate's job to hold.
+    # "Postgres" (plain RDS, the default when `deployed_to` names none) or "Aurora"
+    # (Serverless v2);
+    # only the emitted CloudFormation resource differs, never the runtime adapter. "Shared" borrows
+    # another domain's instance under its own Postgres schema and needs an `owner` setting, which
+    # `bin/project_deploy` checks, since the owning domain is a deploy-time fact.
     value_object "Database" do
       attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
     end
 
-    # "None" (the default — nothing changes for a domain that names
-    # neither this nor drops a `lambda_handler.rb`, e.g. Banking) or
-    # "Rust" — the domain's OWN Lambda (rust/host) also serves a public
-    # web UI in-process (rust/host/src/web.rs), reading HECKS_IR_PATH
-    # (a plain-JSON sidecar bin/project_wasm writes beside the .wasm
-    # artifact) and dispatching through the SAME in-process
-    # dispatch::handle/read the internal {"verb"}/{"read"} path already
-    # uses — no second Lambda, no VPC Interface Endpoint, no Ruby.
-    # Deliberately NOT "Ruby" as a third member here: a Ruby WebFunction
-    # is the pre-existing, SEPARATE `lambda_handler.rb`-file-presence
-    # mechanism (Embryonaut's own), untouched by this attribute —
-    # bin/project_deploy refuses generation outright if a domain
-    # declares `web "Rust"` AND has a `lambda_handler.rb`, rather than
-    # silently picking one.
+    # "None" (default) or "Rust": the domain's own Lambda (rust/host) also serves a public web UI
+    # in-process (rust/host/src/web.rs). "Ruby" is not a member: a Ruby WebFunction comes from a
+    # `lambda_handler.rb` file, and `bin/project_deploy` refuses `web "Rust"` alongside one.
     value_object "Web" do
       attribute :value, String, one_of: ["None", "Rust"]
     end
 
-    # 128-10240 MB — AWS Lambda's own real ceiling and floor, not a
-    # number this domain invented. A typo here used to fail deep inside
-    # a real `sam deploy`, sometimes minutes in; now it refuses before
-    # a single file is generated.
+    # 128-10240 MB, AWS Lambda's own floor and ceiling.
     value_object "Memory" do
       attribute :value, Integer
       invariant("memory is at least 128 MB") { value >= 128 }
       invariant("memory is at most 10240 MB") { value <= 10240 }
     end
 
-    # 900s — Lambda's own real ceiling.
+    # Lambda's own ceiling of 900s.
     value_object "Timeout" do
       attribute :value, Integer
       invariant("a timeout is positive") { value.positive? }
       invariant("a timeout fits Lambda's own 900s ceiling") { value <= 900 }
     end
 
-    # ALL FOUR REQUIRED — deliberately, not `optional: true` +
-    # `default:`. Confirmed directly against CommandInterpreter's own
-    # `normalize_args`/`coerce_declared_arguments` (interpreting.rb):
-    # `next unless normalized.key?(attribute.name)` skips coercion
-    # entirely for an absent key, so a command-level `default:` is
-    # honored ONLY at the JSON/Rust-codegen boundary (`scalar_from_json_
-    # expr`'s own domain), never by Ruby's own direct dispatch — a
-    # `default:` here would be quietly false advertising. "What memory
-    # defaults to when unspecified" stays exactly where it already
-    # lived (bin/project_deploy's own `fetch(:memory, 512)`); this
-    # command validates a FULLY-RESOLVED target, and bin/project_deploy
-    # resolves the default before ever dispatching.
+    # All required, no `default:`: command-level defaults apply only at the JSON/Rust-codegen
+    # boundary, not Ruby's direct dispatch (interpreting.rb `normalize_args`). Defaults are
+    # resolved by `bin/project_deploy` before it dispatches.
     command "Declare" do
       goal "Validate one domain's AwsLambda deploy target before anything is generated from it"
 
@@ -133,11 +77,8 @@ Hecks.bluebook "Deploy" do
     end
   end
 
-  # A sibling of `LambdaTarget`, not a shared shape with it — value objects
-  # are not shared across aggregates in this DSL (`Tenant`'s own
-  # `DomainName`/`Realm`/`Schema` below already make the same point), so
-  # this aggregate carries its own copies of `DomainName`/`Region`/
-  # `Database`/`Web` rather than reaching into `LambdaTarget`'s.
+  # A sibling of `LambdaTarget` with its own value objects, since value objects are not
+  # shared across aggregates.
   aggregate "FargateTarget" do
     description "One domain's validated AWS Fargate deploy target — what deployed_to(\"AwsFargate\") must resolve to before bin/project_deploy generates anything from it."
 
@@ -161,60 +102,40 @@ Hecks.bluebook "Deploy" do
       invariant("a region is named") { !value.to_s.empty? }
     end
 
-    # A positive integer, nothing more — AWS's real cpu/memory
-    # combinations (256 cpu units needs 512-2048 MB of `memory`, say)
-    # are a pairing `ECS` itself enforces at deploy time; encoding that
-    # whole table here would duplicate AWS's own rules for no benefit
-    # this generator needs. This only catches a typo (zero, negative)
-    # before a single file is generated, the same floor `Memory`/`Port`
-    # below hold for their own ranges.
+    # Positive only: ECS enforces AWS's cpu/memory pairings at deploy time, so this just
+    # catches a typo.
     value_object "Cpu" do
       attribute :value, Integer
       invariant("cpu is positive") { value.positive? }
     end
 
-    # Fargate's own valid range, not Lambda's 128-10240 MB —
-    # `LambdaTarget`'s own `Memory` value object (above) is scoped to
-    # that aggregate alone, so this is a distinct value object under the
-    # same name rather than a shared one. A plain sanity floor and
-    # ceiling, not AWS's own cpu-paired table (see `Cpu`'s own comment).
+    # Fargate's own range, not Lambda's 128-10240 MB. A sanity floor and ceiling, not AWS's
+    # cpu-paired table (see `Cpu`).
     value_object "Memory" do
       attribute :value, Integer
       invariant("memory is positive") { value.positive? }
       invariant("memory is at most 122880 MB") { value <= 122880 }
     end
 
-    # Same shape and reasoning as `LambdaTarget`'s own `Database` —
-    # "Postgres"/"Aurora" provision this domain's own RDS instance;
-    # "Shared" borrows another already-deployed domain's instance,
-    # isolated by a native Postgres schema. See that value object's own
-    # comment for the full reasoning; it applies unchanged here.
+    # As `LambdaTarget`'s `Database`.
     value_object "Database" do
       attribute :value, String, one_of: ["Postgres", "Aurora", "Shared"]
     end
 
-    # Same shape and reasoning as `LambdaTarget`'s own `Web` — "Rust"
-    # means the domain's own task also serves its public web UI
-    # in-process, over the port this aggregate's own `Port` attribute
-    # declares.
+    # As `LambdaTarget`'s `Web`; "Rust" serves the web UI in-process on this aggregate's `Port`.
     value_object "Web" do
       attribute :value, String, one_of: ["None", "Rust"]
     end
 
-    # The container port the task listens on and the target group
-    # routes to — a real TCP port, not an arbitrary integer.
+    # The container port the task listens on and the target group routes to.
     value_object "Port" do
       attribute :value, Integer
       invariant("a port is at least 1") { value >= 1 }
       invariant("a port is at most 65535") { value <= 65535 }
     end
 
-    # All seven required, for the identical reason `LambdaTarget.Declare`
-    # requires all of its own attributes — see that command's own
-    # comment on `normalize_args`/`coerce_declared_arguments`. This
-    # validates a fully-resolved target, after `bin/project_deploy`'s own
-    # defaulting (`cpu`/`memory`/`port` each fall back to a Ruby-side
-    # default before this ever dispatches), not instead of it.
+    # All seven required for the same reason as `LambdaTarget.Declare`; this validates a
+    # target already resolved by `bin/project_deploy`'s defaults.
     command "Declare" do
       goal "Validate one domain's AwsFargate deploy target before anything is generated from it"
 
@@ -238,24 +159,8 @@ Hecks.bluebook "Deploy" do
     end
   end
 
-  # `bin/project_tenant`'S OWN VALIDATED SHAPE — same split LambdaTarget
-  # draws with `bin/project_deploy`: this aggregate validates, that
-  # script GENERATES/ACTS (writes `environments/<slug>.world`, ensures
-  # the Postgres schema, boots once to prove it). Deliberately NOT a
-  # saga/process manager with durable runtime state — every step
-  # `bin/project_tenant` takes is already idempotent by construction
-  # (`CREATE SCHEMA IF NOT EXISTS` — PostgresEra#connect_for's own,
-  # File.write of the overlay — a plain overwrite, `Hecks.boot` itself),
-  # the same "generator script, not a business process" shape
-  # `bin/project_deploy` already is; a saga's own resumability earns
-  # its cost coordinating a real distributed transaction across
-  # multiple ports with real failure boundaries (Payments::Payment's
-  # own PaymentGateway, say) — three local, idempotent, single-process
-  # steps have no such boundary to resume across. A durable, reactable
-  # RUNTIME fact ("this tenant exists, is active, is suspended") is a
-  # different, later, business-facing thing — deliberately not built
-  # here, and deliberately not named Deploy::Tenant to avoid colliding
-  # with this validation-only aggregate should it ever land.
+  # The validated shape of `bin/project_tenant`, which does the generating and provisioning.
+  # Not a saga: each of its steps is idempotent and local, so there is nothing to resume.
   aggregate "Tenant" do
     description "One tenant's validated identity — which realm and Postgres schema `bin/project_tenant` provisions before booting a domain directory under Runtime.boot's own `environment:` overlay for it."
 
@@ -266,11 +171,8 @@ Hecks.bluebook "Deploy" do
     attribute :realm,  Realm
     attribute :schema, Schema
 
-    # LOWERCASE, NO SPACES — a slug becomes both the `environments/
-    # <slug>.world` filename and (by convention, not enforced here —
-    # `schema` is its own, separately-declared field precisely so a
-    # tenant CAN choose a different schema name than its slug)
-    # ordinarily the schema name too.
+    # Lowercase, no spaces: a slug becomes the `environments/<slug>.world` filename and, by
+    # convention only, the schema name (`schema` is separate so a tenant can differ).
     value_object "Slug" do
       attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
       invariant("a tenant slug is named") { !value.to_s.empty? }
@@ -286,20 +188,9 @@ Hecks.bluebook "Deploy" do
       invariant("a tenant realm is named") { !value.to_s.empty? }
     end
 
-    # POSTGRES'S OWN REAL IDENTIFIER RULES, loosely — lowercase (this
-    # adapter never quotes a mixed-case identifier back out consistently
-    # once created), letters/digits/underscores, starting with a letter.
-    # NOT a byte-length ceiling too (Postgres's own real 63-byte
-    # NAMEDATALEN limit) — the expression grammar invariants compile
-    # through admits a narrow arithmetic/comparison subset, not
-    # arbitrary method dispatch (`bytesize` included; found live,
-    # writing this: `Bluebook::Expression::Evaluator` tries to resolve
-    # a dotted chain as a FIELD lookup, not a method call, the same
-    # "admits + but not -, no parentheses" narrowness
-    # embryonaut_bluebooks/payments' own Refund command already
-    # documents). Postgres itself refuses a too-long identifier loudly
-    # on its own; not worth fighting the expression grammar for a
-    # corner case this rare.
+    # Lowercase, letters/digits/underscores, starting with a letter. Postgres's 63-byte
+    # identifier limit is not checked: the invariant expression grammar has no `bytesize`, and
+    # Postgres refuses a too-long identifier itself.
     value_object "Schema" do
       attribute :value, String, pattern: '^[a-z][a-z0-9_]*$'
       invariant("a schema is named") { !value.to_s.empty? }

data/lib/hecks/deploy/bluebook/deploy.hecksagon

@@ -2,15 +2,8 @@
 Hecks.hecksagon "Deploy" do
   persisted_by "Memory"
 
-  # THE IMPERATIVE HALF, BEHIND A REAL PORT — `bin/project_tenant`
-  # dispatches this `asks` once `Tenant.Declare` has already validated
-  # the request; `TenantProvisioner` (lib/hecks/adapters/driven/
-  # tenant_provisioner.rb) writes the overlay file and answers or
-  # refuses. `database`/`adapter`/`directory` are declared here, not on
-  # `Tenant` itself — CLI-only facts this validated request never
-  # needed to hold as its own state. `directory` is the real
-  # filesystem path being provisioned — NOT re-derivable from `Tenant`'s
-  # own `domain` (its declared NAME, e.g. "Scratch", never a path).
+  # `bin/project_tenant` dispatches this after `Tenant.Declare` validates; `directory` is a real
+  # filesystem path, which `Tenant`'s declared `domain` name cannot supply.
   Deploy::Tenant.port "TenantProvisioning" do
     asks "Provision", to: Tenant do
       attribute :database,  DatabaseName

data/lib/hecks/embryonaut_bluebook/lock.rb

@@ -2,31 +2,10 @@ require "digest"
 
 module Hecks
   module EmbryonautBluebook
-    # What a vendored package records about the release it came from:
-    # `vendor/embryonaut_bluebooks/<name>/bluebook.lock`.
-    #
-    # ## File format
-    #
-    # One `key: value` line each for `package`, `version`, `tag`, `commit`
-    # and `digest`, then one `shape: <Domain> <label>` line per domain:
-    #
-    #     package: payments
-    #     version: 1.2.0
-    #     tag: payments-v1.2.0
-    #     commit: <full commit id the tag points at>
-    #     digest: <sha256 of the vendored *.bluebook files>
-    #     shape: Payments d33c23
-    #
-    # The digest is the sha256 of the `<sha256>  <name>` lines of every
-    # top-level `*.bluebook` file, sorted by name. The source repository's own
-    # `bin/bluebook_digest` prints the same number for the tagged release, which
-    # is how a vendored copy is proven to be exactly what it claims to be.
+    # The digest here must match the source repo's own bin/bluebook_digest
+    # output for the same tag, or a vendored copy cannot be trusted.
     Lock = Struct.new(:package, :version, :tag, :commit, :digest, :shape, keyword_init: true) do
-      # Computes the content digest of a directory's `*.bluebook` files.
-      #
-      # @param dir [String] the directory to measure
-      # @return [String, nil] 64 lowercase hex characters, nil when the directory holds
-      #   no bluebook file
+      # Sorted by name so the digest never depends on directory listing order.
       def self.digest_of(dir)
         names = Dir.children(dir).select { |name| name.end_with?(".bluebook") }.sort
         return nil if names.empty?
@@ -35,20 +14,12 @@ module Hecks
         Digest::SHA256.hexdigest(lines.join)
       end
 
-      # Reads a lock file.
-      #
-      # @param path [String] the `bluebook.lock` path
-      # @return [Lock, nil] the parsed lock, nil when the file does not exist
       def self.read(path)
         return nil unless File.file?(path)
 
         parse(File.read(path))
       end
 
-      # Parses a lock's text.
-      #
-      # @param text [String] the file's content
-      # @return [Lock] the lock, with `shape` as an Array of lines (empty when none)
       def self.parse(text)
         fields = { shape: [] }
         text.each_line do |line|
@@ -60,9 +31,6 @@ module Hecks
         new(**fields.slice(*members))
       end
 
-      # Renders the lock as the text written to `bluebook.lock`.
-      #
-      # @return [String] the lines described above, newline terminated
       def to_s
         header = %i[package version tag commit digest].map { |key| "#{key}: #{self[key]}\n" }
         (header + Array(shape).map { |line| "shape: #{line}\n" }).join

data/lib/hecks/embryonaut_bluebook/shape.rb

@@ -2,21 +2,10 @@ require_relative "../ports/persistence/plugins/era/storage_shape"
 
 module Hecks
   module EmbryonautBluebook
-    # The storage-shape labels of a directory of `*.bluebook` files.
-    #
-    # A label is what `PostgresEra` mints an era from, so a vendored package
-    # whose label changed is one whose next deploy mints a new era. This reads
-    # the files the way the era guard reads a held era's text: parse only, no
-    # boot, no wiring, no database, each file loaded into a scratch registry.
+    # A label change here means a vendored package's next deploy mints a new PostgresEra.
     module Shape
       module_function
 
-      # Measures every domain a directory's bluebook files declare.
-      #
-      # @param dir [String] a directory holding `*.bluebook` files
-      # @return [Array<String>] one `"<Domain> <label>"` line per domain, sorted by domain name
-      # @raise [Vendoring::Error] if the directory holds no bluebook file, or the files do
-      #   not load, the refusal a boot would raise
       def labels(dir)
         files = Dir[File.join(dir, "*.bluebook")]
         raise Vendoring::Error, "no *.bluebook files in #{dir}" if files.empty?
@@ -26,11 +15,6 @@ module Hecks
         end
       end
 
-      # Loads bluebook files into a registry of their own.
-      #
-      # @param files [Array<String>] absolute bluebook file paths, in load order
-      # @return [Runtime::Registry] the scratch registry holding what the files declared
-      # @raise [Vendoring::Error] if any file fails to load
       def load_all(files)
         scratch = Runtime::Registry.new
         library = Ports::Loading.bootstrap

data/lib/hecks/embryonaut_bluebook/vendor.rb

@@ -5,32 +5,8 @@ require_relative "shape"
 
 module Hecks
   module EmbryonautBluebook
-    # Vendors one package of the bluebook registry into a consuming project.
-    #
-    # ## What it does
-    #
-    # Pins the package's top-level `bluebook/*.bluebook` files from one commit
-    # of a local source repository into
-    # `<root>/vendor/embryonaut_bluebooks/<name>/bluebook/`, where `load!`
-    # resolves them. Only bluebook files are taken: a `.hecksagon`, `.port` or
-    # `.adapter` is a wiring decision for whoever deploys, never part of the
-    # vendored package.
-    #
-    # ## Releases and bare commits
-    #
-    # The source repository tags each release `<name>-v<X.Y.Z>` on a commit
-    # whose `<name>/bluebook.yml` says that version. A release pin (`ref` nil for
-    # the newest tag, `"1.2.0"`, or the tag name) also writes `bluebook.lock`,
-    # which records version, tag, commit, content digest and storage shape, and
-    # holds two refusals, because a production project is bound to `PostgresEra`:
-    #
-    # - a version lower than the vendored one, unless `allow_downgrade`;
-    # - a storage-shape change that does not raise the version by at least a
-    #   minor, so a new era shows in the version number and not only in a hash.
-    #
-    # Any other commit-ish pins that commit and writes only the marker, with no
-    # lock and no version checks. Either way nothing on disk changes when a
-    # pin is refused or its files do not load.
+    # Pins a package's `bluebook/*.bluebook` files from a source repo commit; a
+    # release pin also refuses a downgrade or an era-breaking storage-shape change.
     class Vendor
       # A release version, `X.Y.Z`.
       VERSION = /\A\d+\.\d+\.\d+\z/
@@ -38,33 +14,17 @@ module Hecks
       # A package name is a directory name and a bluebook name stem.
       NAME = /\A[a-z][a-z0-9_]*\z/
 
-      # What a vendoring changed.
-      #
-      # @!attribute [r] previous_version
-      #   @return [String, nil] the version recorded before, nil when there was none
-      # @!attribute [r] previous_shape
-      #   @return [Array<String>, nil] the shape lines measured before, nil when there was
-      #   no earlier copy
+      # What a vendoring changed; previous_version/previous_shape are nil when
+      # there was no earlier vendored copy.
       Result = Struct.new(:package, :commit, :version, :tag, :digest, :shape,
                           :previous_version, :previous_shape, :dir, keyword_init: true) do
-        # Says whether this was a release pin, which writes a lock.
-        #
-        # @return [Boolean] true for a release, false for a bare commit
         def release? = !tag.nil?
 
-        # Says whether the storage shape moved since the earlier copy.
-        #
-        # @return [Boolean] true when an earlier copy existed and its shape differs
         def shape_changed? = !previous_shape.nil? && previous_shape != shape
       end
 
-      # @param name [String, Symbol] the package's directory name, such as `"payments"`
-      # @param from [String] path of the local source repository
-      # @param ref [String, nil] `X.Y.Z`, a release tag name, any commit-ish, or nil for the
-      #   newest release
-      # @param root [String] the consuming project's root
-      # @param allow_downgrade [Boolean] whether a release older than the vendored one is allowed
-      # @raise [Vendoring::Error] if the name is not a plain package name
+      # `ref` accepts `X.Y.Z`, a release tag name, any commit-ish, or nil for
+      # the newest release.
       def initialize(name, from:, root:, ref: nil, allow_downgrade: false)
         @name = name.to_s
         raise Vendoring::Error, "#{name.inspect} is not a package name" unless @name.match?(NAME)
@@ -76,10 +36,6 @@ module Hecks
       end
 
       # Pins the package and reports what changed.
-      #
-      # @return [Result] the commit, version and shape now vendored
-      # @raise [Vendoring::Error] if the release or commit is not found, the tagged commit
-      #   disagrees with its own version, the files do not load, or a refusal above applies
       def call
         tag, version = release
         previous_version, previous_shape = existing
@@ -99,9 +55,8 @@ module Hecks
 
       def package_dir = File.join(@root, "vendor", "embryonaut_bluebooks", @name)
 
-      # Resolves what `ref` asks for into a release tag and its version.
-      #
-      # @return [Array(String, String), nil] tag and version for a release, nil for a bare commit
+      # Resolves what `ref` asks for into a release tag and its version, or nil
+      # for a bare commit.
       def release
         tag = release_tag
         return nil unless tag

data/lib/hecks/embryonaut_bluebook/vendor_cli.rb

@@ -3,21 +3,10 @@ require_relative "vendor"
 
 module Hecks
   module EmbryonautBluebook
-    # The command line behind `bin/vendor_bluebook`.
+    # The command line behind `bin/vendor_bluebook`; lives in the gem so a
+    # consuming project reaches it through its own bundle, no script to copy.
     #
-    # It lives in the gem, not in a script, so a consuming project reaches it
-    # through its own bundle without a copy of the script:
-    #
-    #     bundle exec ruby -rhecks \
-    #       -e 'exit Hecks::EmbryonautBluebook::VendorCli.run(ARGV)' payments@1.2.0
-    #
-    # ## Usage
-    #
-    #     vendor_bluebook <package>[@<version-or-commit>] [--from <path>] [--root <path>]
-    #
-    # `--from` defaults to `$EMBRYONAUT_BLUEBOOKS_SRC` and `--root` to the current
-    # directory. `ALLOW_DOWNGRADE=1` in the environment permits a release older
-    # than the vendored one.
+    #     vendor_bluebook <package>[@<version-or-commit>] [--from path] [--root path]
     module VendorCli
       USAGE = "usage: vendor_bluebook <package>[@<version-or-commit>] [--from PATH] [--root PATH]".freeze
 
@@ -44,11 +33,7 @@ module Hecks
         1
       end
 
-      # Reads the options into a hash and picks out the package argument.
-      #
-      # @param argv [Array<String>] the command-line arguments
-      # @param options [Hash{Symbol => String}] receives `:from` and `:root` when given
-      # @return [String, nil] the one positional argument, nil unless exactly one was given
+      # nil unless argv held exactly one positional argument.
       def self.parse(argv, options)
         parser = OptionParser.new
         parser.on("--from PATH") { |path| options[:from] = path }

data/lib/hecks/embryonaut_bluebook.rb

@@ -1,75 +1,6 @@
 module Hecks
-  # A vendored, external bluebook.
-  #
-  # ## What it is
-  #
-  # Same shape as Framework (framework.rb), for members that don't ship
-  # inside hecks's own lib/ at all: a separate, independently-versioned
-  # package (github.com/chrisyoung/embryonaut_bluebooks) that a consuming
-  # project vendors into its own checkout, the same way a project already
-  # vendors hecks itself (bin/vendor_hecks, vendor/hecks/).
-  #
-  # ## Recovered, not rebuilt
-  #
-  # This module and its `uses_embryonaut_bluebook`
-  # DSL word (hecksagon_builder.rb) were built on a prior commit of this
-  # repo (933d1dd), vendored out to a real consumer (a client site's domain,
-  # for embryonaut_bluebooks/payments), and then lost from this repo's own
-  # reachable history — a hard reset or rebase left no branch containing
-  # that commit. The consumer's vendor snapshot (a `git archive` of that
-  # commit, committed into their repo) was the only surviving copy; this
-  # file is ported forward from it, checked against current `main`'s own
-  # conventions rather than copied wholesale, since the two trees had
-  # otherwise diverged for weeks in both directions.
-  #
-  # ## Resolution
-  #
-  # Resolved from the consuming registry's own root, not this gem's
-  # __dir__ — Framework::ROOT can be a fixed, `__dir__`-relative constant
-  # because framework members ship inside this gem; an embryonaut bluebook
-  # ships inside the consumer's own checkout instead, at
-  # `<registry.root>/vendor/embryonaut_bluebooks/<name>/bluebook/`. There
-  # is no fixed answer until a registry (and its root) actually exists, so
-  # this resolves lazily, per call — the same reason `uses_framework`
-  # itself only runs at hecksagon-build time, when a real registry is
-  # current.
-  #
-  # ## Load order
-  #
-  # Every `.bluebook` file in the package, sorted — not just one. Unlike a
-  # framework member (one file, named by its own stem), a vendored package
-  # can span several bluebook files that reopen the same `Hecks.bluebook`
-  # (embryonaut_bluebooks/payments/bluebook/{payment,payments,policies}
-  # .bluebook all reopen "Payments"). Load order matters — policies
-  # .bluebook names `Payment::Succeed` and needs the aggregate already
-  # built — and a plain alphabetical sort already gives the right order:
-  # payment < payments < policies, the same reason that package's own
-  # files are named to fall in that order in the first place.
-  #
-  # ## Scope
-  #
-  # Only the bluebook files — same restriction Framework draws, same
-  # reason: a `.hecksagon`/`.port`/`.adapter` is a wiring decision
-  # (persistence, which processor adapter is bound) that belongs to
-  # whoever is deploying, never baked into the vendored package itself.
-  # embryonaut_bluebooks/payments ships its own mock `.hecksagon` for its
-  # own spec suite; a consumer declares its own separate
-  # `Hecks.hecksagon "Payments" do ... end` to bind real storage/adapters
-  # — see Framework's own comment for the fuller reasoning, identical here.
-  #
-  # ## Idempotency
-  #
-  # Idempotent the same way `Framework.load!` is — checked against the
-  # bluebook this package actually declares (`Naming.pascal("payments")`
-  # => "Payments"), not a separate ledger. A vendored package's directory
-  # name and its declared `Hecks.bluebook` name are the one convention
-  # this reuses from Framework rather than reinventing.
-  #
-  # ## Vendoring
-  #
-  # `vendor!` is the other direction: it pins a package from a local checkout
-  # of the registry into a consuming project's own `vendor/` tree, and is the
-  # one implementation behind `bin/vendor_bluebook` (see Vendoring and Vendor).
+  # A vendored, external bluebook: same shape as Framework, but for a
+  # package that ships outside hecks's own lib/ (see .load! and .vendor!).
   module EmbryonautBluebook
     autoload :Lock, File.join(__dir__, "embryonaut_bluebook/lock")
     autoload :Shape, File.join(__dir__, "embryonaut_bluebook/shape")
@@ -103,6 +34,8 @@ module Hecks
               "vendor it with bin/vendor_bluebook #{name}"
       end
 
+      # Loaded in the glob's alphabetical order; a package with several
+      # files that reopen the same bluebook is named to rely on that.
       files.each { |file| Kernel.load(file) }
     end