hecks 1.4.0 → 1.5.1

data/lib/hecks/adapters/driven/memory.rb

@@ -253,19 +253,19 @@ module Hecks
 
       private
 
-      # THE LANGUAGE'S OWN BOOTSTRAP SAVES ITS SELF-DESCRIPTION QUADRATICALLY
-      # OTHERWISE. `MetaValidator::Judge` dispatches every declaration in the
+      # The language's own bootstrap saves its self-description quadratically
+      # otherwise. `MetaValidator::Judge` dispatches every declaration in the
       # self-hosted grammar into a fresh, private, never-durable `Memory`
       # store (meta_validator.rb's own header: "each bluebook is judged in a
       # fresh in-memory store") — and every nested-entity dispatch (a
       # `ValueObject::Member`, then one `ValueObject::Member::Pair` per
-      # key/value pair) re-saves the WHOLE parent aggregate, because entities
+      # key/value pair) re-saves the whole parent aggregate, because entities
       # have no storage of their own (S17, ADR 0026). A table of N member
-      # rows costs O(N) dispatches, each PAYING TWICE for the aggregate's own
+      # rows costs O(N) dispatches, each paying twice for the aggregate's own
       # size-N state: once in `StateCodec.copy` (`append`/`project`'s own
       # encode-then-decode round trip) and again in `Instance#initialize`'s
       # `hydrate_with_defaults`, which re-walks and re-validates every
-      # element of an entity list on EVERY save regardless of how many of
+      # element of an entity list on every save regardless of how many of
       # them were already valid as of the previous one
       # (`Value::EntityListCoercion#hydrate_entity_list` has no "already
       # hydrated" shortcut for entity elements — only a value-object list
@@ -277,7 +277,7 @@ module Hecks
       #
       # `Runtime::Value.judge_bootstrapping?` (judge.rb's own `send_to`,
       # wrapping every dispatch the judge makes) is already the flag that
-      # marks exactly this window and NOTHING else — "never for a REAL
+      # marks exactly this window and nothing else — "never for a real
       # domain's own declared value objects... which Judge never dispatches
       # commands against" (coercion.rb's own comment on the same flag). It
       # is reused here rather than a new toggle for the same reason: one
@@ -286,13 +286,13 @@ module Hecks
       # both round trips here) is simpler to reason about than two flags
       # that would always be true or false together.
       #
-      # WHY SKIPPING BOTH IS SAFE HERE, AND ONLY HERE: `entry.state` a save
+      # Why skipping both is safe here, and only here: `entry.state` a save
       # ever hands this adapter is always `instance.state.dup`
-      # (`AppendOnly#save`) — a shallow copy of an ALREADY-hydrated,
-      # ALREADY-validated live `Instance`'s own state, built by the very
+      # (`AppendOnly#save`) — a shallow copy of an already-hydrated,
+      # already-validated live `Instance`'s own state, built by the very
       # same `Value.for_attribute`/`hydrate_with_defaults` machinery
       # `StateCodec.copy` and `Instance.new`'s default (`hydrate: true`)
-      # path would otherwise redo. Every VALUE inside it — a `Runtime::
+      # path would otherwise redo. Every value inside it — a `Runtime::
       # Value` (frozen through, see value.rb's own header) or a `list_of`
       # attribute's own array (`Freezer.deep`d the moment it was built,
       # instance.rb's own header on `Instance#dup`) — is already immutable,
@@ -303,13 +303,13 @@ module Hecks
       # pure, avoidable cost for this one caller — never a correctness
       # requirement.
       #
-      # `bootstrap_fast_path?` is the guard, and it is deliberately CHEAP —
+      # `bootstrap_fast_path?` is the guard, and it is deliberately cheap —
       # O(this aggregate's own declared attribute count), never O(N) — so
       # it cannot reintroduce the very cost it exists to avoid: `StateCodec.
       # decoded?` (the obvious-looking alternative) recurses into every
-      # `list_of` element to check IT, which is exactly the O(N) walk this
+      # `list_of` element to check it, which is exactly the O(N) walk this
       # whole change removes. A `Hash` with every top-level key already a
-      # `Symbol` is what `Instance#state` ALWAYS looks like (`Value.hydrate`
+      # `Symbol` is what `Instance#state` always looks like (`Value.hydrate`
       # refuses anything else, coercion.rb's own header), so it is checked
       # here instead — true for the actual shape every real save has,
       # false (falling back to the always-correct slow path) for anything

data/lib/hecks/adapters/driven/mock_stripe_adapter.rb

@@ -17,8 +17,28 @@ module Hecks
     # webhook against it (a smoke test, CI) has something real to key
     # off of — the real shape production has, minus the network hop.
     class MockStripeAdapter
+      # Accepts and discards the shared adapter constructor arguments; this adapter holds no
+      # state of its own.
+      #
+      # @param aggregate [Bluebook::Aggregate, nil] accepted for the shared adapter
+      #   constructor shape and ignored
+      # @param settings [Hash] accepted for the shared adapter constructor shape and ignored
+      # @param root [String, nil] accepted for the shared adapter constructor shape and ignored
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
+      # Builds a fake checkout URL carrying `registration_id`, standing in for a real
+      # Checkout-Session call.
+      #
+      # @param event [Object] the record data a real adapter would read the price and name
+      #   from; adapter-defined shape (whatever the declaring bluebook's `checkout` port
+      #   operation supplies as `event`) and never read here
+      # @param registration_id [String] the registration id to key a signed webhook off of;
+      #   embedded in the returned URL, never read otherwise
+      # @param success_url [String] the base URL to redirect a successful payer to
+      # @param cancel_url [String] accepted for the shared checkout-adapter call shape and
+      #   never read
+      # @return [String] `success_url` with `mock_checkout=1` and `mock_registration_id`
+      #   query parameters appended
       def create_session(event:, registration_id:, success_url:, cancel_url:)
         separator = success_url.include?("?") ? "&" : "?"
         "#{success_url}#{separator}mock_checkout=1&mock_registration_id=#{registration_id}"

data/lib/hecks/adapters/driven/prism.rb

@@ -21,11 +21,22 @@ module Hecks
 
       module_function
 
+      # Recovers a block's body as canonical source text.
+      #
+      # @param block [Proc] a block written in a bluebook file, such as a `given` predicate
+      #   or an `identified_by` path
+      # @return [String, nil] the block body's source, normalised by
+      #   `Bluebook::Expression::CanonicalForm`; nil if `body_source` finds none
       def canonical(block)
         body = body_source(block)
         body && canonicalise(body)
       end
 
+      # Reads a block's own body source text back out of the file it was defined in.
+      #
+      # @param block [Proc] the block to locate, via its own `source_location`
+      # @return [String, nil] the block body's raw source; nil if the file cannot be read,
+      #   or no block node starts on the block's own line
       def body_source(block)
         file, line = block.source_location
         return nil unless file && File.readable?(file)
@@ -34,6 +45,12 @@ module Hecks
         node&.body&.slice
       end
 
+      # Finds the parsed block node starting on a given line of a file.
+      #
+      # @param file [String] the file path, parsed (and cached) through `tree_for`
+      # @param line [Integer] the 1-based source line the block starts on
+      # @return [Prism::BlockNode, nil] the first block node found starting on `line`, or nil
+      #   if none does
       def block_node_at(file, line)
         found = nil
         walk(tree_for(file)) do |node|
@@ -45,12 +62,16 @@ module Hecks
         found
       end
 
+      # Parses a file with `prism`, caching the result for the life of the process.
+      #
+      # @param file [String] the file path to parse and cache under
+      # @return [Prism::ProgramNode] the parsed syntax tree's root node
       def tree_for(file)
         # ::Prism.parse_file(file) reads the file itself, at the C
         # extension level — bypassing Ruby's own File/IO layer entirely.
         # That's invisible to anything that virtualizes the filesystem at
         # the Ruby level instead of the OS level (e.g. tebako's memfs,
-        # used to press a hecks-based app into a single executable —
+        # which presses a hecks-based app into a single executable —
         # see domain/README.md's "Deploying" section in lifeadelics for
         # why that matters). ::Prism.parse(File.read(file)) parses the
         # exact same bytes, just read through Ruby's File.read first,
@@ -66,16 +87,29 @@ module Hecks
       # tree reports a `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. Found for real building
-      # `Hecks::Codemod` (lib/hecks/codemod.rb), which used to
-      # reach into `TREES.clear` directly — a private implementation
-      # detail poked from outside. `forget`/`forget_all` are the real
-      # API so nothing else that reloads an edited file in-process has
-      # to know `TREES` exists at all.
+      # extraction" on a perfectly valid file. Built for real building
+      # `Hecks::Codemod` (lib/hecks/codemod.rb), which needs exactly this
+      # invalidation rather than reaching into `TREES.clear` directly — a
+      # private implementation detail poked from outside. `forget`/
+      # `forget_all` are the real API so nothing else that reloads an
+      # edited file in-process has to know `TREES` exists at all.
+      #
+      # @param file [String] the file path to drop from the cache
+      # @return [Prism::ProgramNode, nil] the cached tree that was removed, or nil if
+      #   nothing was cached for `file`
       def forget(file) = TREES.delete(file)
 
+      # Drops every cached parse tree.
+      #
+      # @return [Hash] the now-empty cache
       def forget_all = TREES.clear
 
+      # Visits `node` and every descendant depth-first, calling `visit` on each.
+      #
+      # @param node [Prism::Node, Object] the node to walk; anything that is not a
+      #   `Prism::Node` is a silent no-op
+      # @yieldparam node [Prism::Node] each node visited, `node` itself first
+      # @return [void]
       def walk(node, &visit)
         return unless node.is_a?(::Prism::Node)
 
@@ -83,6 +117,11 @@ module Hecks
         node.compact_child_nodes.each { |child| walk(child, &visit) }
       end
 
+      # Normalises raw source text into the framework's own canonical form.
+      #
+      # @param source [String] the raw source text to normalise
+      # @return [String] the normalised text (whitespace collapsed, linked replacements
+      #   applied)
       def canonicalise(source)
         Bluebook::Expression::CanonicalForm.apply(source)
       end

data/lib/hecks/adapters/driven/secure_random_identity.rb

@@ -8,6 +8,9 @@ module Hecks
     module SecureRandomIdentity
       module_function
 
+      # Mints a fresh random identity value.
+      #
+      # @return [String] a newly minted, random UUID
       def uuid = SecureRandom.uuid
     end
   end

data/lib/hecks/adapters/driven/system_clock.rb

@@ -8,6 +8,9 @@ module Hecks
     module SystemClock
       module_function
 
+      # Reads the machine's own current time.
+      #
+      # @return [Integer] the current time, in Unix epoch seconds
       def now = Time.now.to_i
     end
   end

data/lib/hecks/adapters/driven/tenant_provisioner.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "TenantProvisioner" do
+  port "TenantProvisioning"
+end

data/lib/hecks/adapters/driven/tenant_provisioner.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Hecks
+  module Adapters
+    # THE IMPERATIVE HALF of provisioning a tenant, pulled out of
+    # `bin/project_tenant` and behind a real driven port
+    # (`Deploy::Tenant.port "TenantProvisioning"`) instead — the same
+    # hexagonal reasoning `GithubChecks` already gives for its own
+    # port: real, impure, side-effecting work (writing the overlay
+    # file) belongs in an adapter, not in a bare script or a command
+    # handler. `Deploy::Tenant`'s own `asks "Provision"` operation calls
+    # `#provision` and turns whatever it returns into `TenantProvisioned`,
+    # or whatever it raises into `ProvisioningRefused` — see
+    # `PortOperationInterpreter#ask`'s own "every failure is an answer"
+    # comment for why nothing here needs its own rescue.
+    #
+    # DELIBERATELY DOES NOT BOOT THE TARGET DOMAIN — that step (proving
+    # it boots for real, running the tenant_capable? gate) stays in
+    # `bin/project_tenant` itself, called AFTER this operation answers,
+    # not nested inside it. Booting a whole domain from inside an
+    # adapter method that is itself running mid-dispatch (this port
+    # operation) is a real, separate concern from writing one file, and
+    # keeping the two apart avoids a nested `Hecks.boot` call ever
+    # running inside another boot's own dispatch call stack.
+    #
+    # RETURNS A HASH SHAPED LIKE `Tenancy::Tenant.Register`'S OWN
+    # ARGUMENTS, on purpose — `tenancy.hecksagon`'s own `translates`
+    # reaction forwards an answered event's payload verbatim, so this
+    # adapter's own return value IS the translation from Deploy's
+    # vocabulary into Tenancy's, decided here rather than in a mapping
+    # layer neither side could see into.
+    class TenantProvisioner
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # `directory:` IS REQUIRED, NOT DERIVED FROM `domain` — a real,
+      # confirmed bug found only under CI's own real-Postgres suite: a
+      # domain's own DECLARED NAME (`domain`, e.g. "Scratch") is not a
+      # filesystem path, and File.expand_path(domain, Dir.pwd) silently
+      # resolved to the wrong directory (relative to whatever the
+      # RUNNING PROCESS' own cwd happened to be) whenever the CLI's own
+      # `--domain=` value didn't happen to equal its own directory
+      # argument by coincidence. `bin/project_tenant` passes its own
+      # real `domain_directory` local straight through.
+
+      def provision(slug:, domain:, realm:, schema:, database:, adapter:, directory:)
+        domain_directory = File.expand_path(directory[:value] || directory)
+
+        overlay_path = File.join(domain_directory, "environments", "#{slug[:value] || slug}.world")
+        FileUtils.mkdir_p(File.dirname(overlay_path))
+        File.write(overlay_path, <<~WORLD)
+          Hecks.world "#{domain[:value] || domain}" do
+            realm "#{realm[:value] || realm}"
+            persisted_by("#{adapter[:value] || adapter}") do
+              database "#{database[:value] || database}"
+              schema   "#{schema[:value] || schema}"
+            end
+          end
+        WORLD
+
+        { slug: slug, domain: domain, realm: realm, schema: schema }
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven.rb

@@ -40,7 +40,9 @@ require_relative "driven/prism"
 require_relative "driven/folder"
 require_relative "driven/d1"
 require_relative "driven/mock_stripe_adapter"
+require_relative "driven/tenant_provisioner"
 require_relative "driven/secure_random_identity"
+require_relative "driven/in_process_key_vault"
 require_relative "driven/system_clock"
 # `SequentialIdentity` — the deterministic identity_generation test
 # double — is not required here on purpose. It lives at

data/lib/hecks/adapters/driving/github_webhook.rb

@@ -26,6 +26,8 @@ module Hecks
       # in `qa/adapters/github_ci_webhook.rb`, the subclass of this file
       # that actually knows what a `QualityControl::Clearance` is.
       #
+      # ## A plain rack app
+      #
       # A plain rack app (`#call(env)`) — no Sinatra, no Rails — the same
       # shape `Hecks::Forms::App` (lib/hecks/forms/app.rb) already
       # established for the one other HTTP-facing surface this library
@@ -37,7 +39,9 @@ module Hecks
       # `rack` installed, the same "opt in by requiring the file at all"
       # contract `hecks/forms.rb` already has for `Forms::App`.
       #
-      # **Subclass responsibility**: implement `#handle_event(event, action,
+      # ## Subclass responsibility
+      #
+      # Implement `#handle_event(event, action,
       # payload)`, returning `[http_status, response_body_hash]`. Called
       # only after the signature has verified and the body has parsed as
       # JSON — a subclass never has to re-check either. `event` is
@@ -79,12 +83,21 @@ module Hecks
         # or wherever it keeps one — rather than this class reaching into
         # the environment itself and hiding that requirement inside a
         # default.
+        # @param secret [String] the shared webhook secret (e.g. `ENV.fetch
+        #   ("GITHUB_WEBHOOK_SECRET")`), checked against each request's `X-Hub-Signature-256`
+        # @raise [ArgumentError] if `secret` is nil or empty
         def initialize(secret:)
           raise ArgumentError, "no webhook secret configured" if secret.to_s.empty?
 
           @secret = secret
         end
 
+        # The rack entry point: verifies, parses, and routes one webhook request.
+        #
+        # @param env [Hash] the rack environment
+        # @return [Array(Integer, Hash, Array<String>)] the rack response triple — status,
+        #   headers, and a one-element body Array holding the JSON-encoded response
+        # @raise [NotImplementedError] if the subclass has not implemented `#handle_event`
         def call(env)
           request = Rack::Request.new(env)
           return respond(405, error: "MethodNotAllowed", message: "POST only") unless request.post?

data/lib/hecks/behaviors/dsl.rb

@@ -16,6 +16,7 @@ module Hecks
     # `validate_expect!` (private, below) is where a malformed or empty
     # `expect` is refused at build time rather than silently passing later.
     class TestCaseBuilder
+      # @param description [String] the `test "description" do ... end` text
       def initialize(description)
         @description   = description
         @tests_command = nil
@@ -26,19 +27,46 @@ module Hecks
         @expect        = {}
       end
 
+      # Records which command or query this test exercises.
+      #
+      # @param command [String, Symbol] the command or query verb, bare or dotted FQN
+      # @param on [String, Symbol, nil] the aggregate `command` is dispatched on, when
+      #   `command` is not already a dotted FQN
+      # @param kind [Symbol] `:command` or `:query`
+      # @return [void]
       def tests(command, on: nil, kind: :command)
         @tests_command = command
         @on_aggregate  = on
         @kind          = kind
       end
 
+      # Records one setup command to dispatch before the test itself runs.
+      #
+      # @param command [String, Symbol] the setup command's verb
+      # @param kwargs [Hash{Symbol => Object}] the setup command's own arguments
+      # @return [void]
       def setup(command, **kwargs)
         @setups << TestSetup.new(command: command, args: kwargs)
       end
 
+      # Merges fields into the arguments the tested command or query is called with.
+      #
+      # @param kwargs [Hash{Symbol => Object}] argument names and values to merge in
+      # @return [Hash{Symbol => Object}] the input Hash so far
       def input(**kwargs)  = @input.merge!(kwargs)
+
+      # Merges fields into what this test expects of the tested dispatch.
+      #
+      # @param kwargs [Hash{Symbol => Object}] expectation keys (`ok:`, `refused:`,
+      #   `emits:`, `count:`, or a field name) and their expected values
+      # @return [Hash{Symbol => Object}] the expectation Hash so far
       def expect(**kwargs) = @expect.merge!(kwargs)
 
+      # Builds the `TestCase` this builder collected.
+      #
+      # @return [TestCase] the built test case
+      # @raise [Malformed] if `tests` was never called, `expect` is empty, or
+      #   `expect` declares `count:` on a command or `emits:` on a query
       def build
         unless @tests_command
           raise Malformed, "test #{@description.inspect} never calls `tests` — " \
@@ -84,6 +112,8 @@ module Hecks
     # `vision`/`loads`/`test` calls and builds a `BehaviorsSuite` (ir.rb),
     # refusing to build one missing either `vision` or `loads` (`#build`).
     class BehaviorsBuilder
+      # @param name [String] the suite's declared name
+      # @param source_path [String] the `.behaviors` file's own path
       def initialize(name, source_path:)
         @name        = name
         @source_path = source_path
@@ -93,21 +123,40 @@ module Hecks
         @tests       = []
       end
 
+      # Records the suite's one-line description of what it is examples of.
+      #
+      # @param text [String] the vision text
+      # @return [String] `text`, unchanged
       def vision(text) = @vision = text
 
       # Relative to this `.behaviors` file, never to the filesystem's cwd
       # or a same-stem convention — scope is a fact this file declares,
       # not one a runner infers.
+      #
+      # @param paths [Array<String>] paths to the files this suite's domain boots
+      #   from, relative to the `.behaviors` file
+      # @return [void]
       def loads(*paths)
         @loads = paths.map { |path| File.expand_path(path, @source_dir) }
       end
 
+      # Builds and records one test case.
+      #
+      # @param description [String] the test's own description
+      # @yield the test's body, evaluated against a `TestCaseBuilder`
+      # @return [void]
+      # @raise [Malformed] if the test never calls `tests`, has no `expect`, or
+      #   declares `count:` on a command or `emits:` on a query
       def test(description, &block)
         builder = TestCaseBuilder.new(description)
         builder.instance_eval(&block) if block
         @tests << builder.build
       end
 
+      # Builds the `BehaviorsSuite` this builder collected.
+      #
+      # @return [BehaviorsSuite] the built suite
+      # @raise [Malformed] if the suite declares no `vision` or no `loads`
       def build
         unless @vision
           raise Malformed, "#{@source_path}: no `vision \"...\"` — say in one line " \
@@ -122,6 +171,15 @@ module Hecks
                            tests: @tests, path: @source_path)
       end
 
+      # Builds a suite in one call: constructs a builder, evaluates `block`
+      # against it, and builds the result.
+      #
+      # @param name [String] the suite's declared name
+      # @param source_path [String] the `.behaviors` file's own path
+      # @yield the suite's body, evaluated against the new builder
+      # @return [BehaviorsSuite] the built suite
+      # @raise [Malformed] if the suite declares no `vision` or `loads`, or any of
+      #   its `test` blocks is malformed
       def self.build(name, source_path:, &block)
         builder = new(name, source_path: source_path)
         builder.instance_eval(&block) if block