hecks 1.3.0 → 1.5.0

data/lib/hecks/framework.rb

@@ -1,25 +1,29 @@
 require_relative "runtime/registry"
 
 module Hecks
-  # THE REGISTRY OF FRAMEWORK BLUEBOOKS — Governance, Identity, and
+  # **The registry of framework bluebooks** — Governance, Identity, and
   # whatever lands beside them in `lib/hecks/framework/bluebook/`:
   # domain-agnostic chapters no single example owns, shared by reference
   # rather than copied into every domain that wants one.
   #
-  # UNDER `lib/`, not a top-level sibling — a real consumer (embryonaut)
-  # vendors ONLY `lib/` (`bin/vendor-hecks`, and this gem's own
+  # ## Where it lives
+  #
+  # Under `lib/`, not a top-level sibling — a real consumer (embryonaut)
+  # vendors only `lib/` (`bin/vendor-hecks`, and this gem's own
   # `hecks.gemspec`, both glob `lib/**/*`), so a `framework/`
   # sitting beside `lib/` rather than inside it packaged and vendored
   # cleanly but left `uses_framework` finding nothing at runtime —
   # `Framework::ROOT` pointed at a directory that simply never shipped.
-  # Nothing in THIS repo's own suite caught it, since every spec here
+  # Nothing in this repo's own suite caught it, since every spec here
   # reads the working tree directly; only vendoring into a real consumer
   # did. Same reasoning `lib/hecks/language/bluebook/` already
   # settled for the self-hosted grammar's own `.bluebook` files —
   # non-Ruby data a module owns lives inside `lib/` with the code that
   # reads it, not beside it.
   #
-  # DERIVED FROM THE DIRECTORY, not hand-listed a second time — the same
+  # ## Derived, not hand-listed
+  #
+  # Derived from the directory, not hand-listed a second time — the same
   # reasoning `Assembly::CONTRACTS` gives for reading the language's own
   # fields from a table instead of restating them: a member added here
   # and forgotten in a list would be a member `uses_framework` could
@@ -27,55 +31,105 @@ module Hecks
   # stale in silence. `spec/corpus_spec.rb`'s own `FRAMEWORK_MEMBERS`
   # glob is the precedent this mirrors.
   #
-  # NAMED BY FILE STEM, capitalized — `governance.bluebook` holds
+  # ## Naming
+  #
+  # Named by file stem, capitalized — `governance.bluebook` holds
   # `Hecks.bluebook "Governance"`, the same one-to-one spelling every
   # other chapter in this codebase already keeps between its filename
   # and its declared name.
   module Framework
-    ROOT = File.expand_path("framework/bluebook", __dir__).freeze
-
-    def self.members
-      Dir.glob(File.join(ROOT, "*.bluebook")).to_h do |path|
-        [Naming.pascal(File.basename(path, ".bluebook")), path]
-      end
-    end
-
-    # LOADED FROM ITS OWN REAL PATH, always — never a copy. A domain
+    # Loaded from its own real path, always — never a copy. A domain
     # booted through `Fuzzing::IsolatedBoot`'s tmp-directory copy still
-    # reaches the SAME `framework/bluebook/governance.bluebook` this
+    # reaches the same `framework/bluebook/governance.bluebook` this
     # constant points at, because `uses_framework` runs `Kernel.load`
     # against `ROOT`, not against anything inside the copied domain
     # directory — there is nothing here for a relocated copy to break,
     # the way a symlink carried along with the copy would.
     #
-    # ONLY THE BLUEBOOK — a framework member's own `.hecksagon`, if it
-    # has one, is NOT auto-loaded. Persistence is a WIRING decision, the
+    # Only the bluebook — a framework member's own `.hecksagon`, if it
+    # has one, is not auto-loaded. Persistence is a wiring decision, the
     # same as any other aggregate's, and belongs to whoever is doing the
     # deploying, not to a default baked into the framework member
     # itself: a consuming app needs `Governance::RoleAssignment` durable
     # (Postgres, say), and a framework member hard-coding Memory for its
-    # own specs would silently make that decision FOR every app that
-    # attaches it. The consuming app declares its OWN, SEPARATE
+    # own specs would silently make that decision for every app that
+    # attaches it. The consuming app declares its own, separate
     # `Hecks.hecksagon "Governance" do ... end` block for that — not
     # binds folded into its own hecksagon, which would build but never
     # resolve: `Ports::Persistence::BindingPolicy.resolve` looks up
-    # `registry.hecksagon` by the AGGREGATE's own domain name, not the
+    # `registry.hecksagon` by the aggregate's own domain name, not the
     # domain doing the binding, the one invariant this runtime holds
     # everywhere else too. See `examples/banking/bluebook/banking.hecksagon`
     # for the pattern — a real `.hecksagon` file can hold more than one
     # `Hecks.hecksagon` call, one per domain it wires.
-    # IDEMPOTENT, PER REGISTRY — `uses_framework` is now called more than
-    # once for the SAME member within a single boot (S8: a domain
+    ROOT = File.expand_path("framework/bluebook", __dir__).freeze
+
+    # Every framework member available to attach, by declared name.
+    #
+    # @return [Hash{String => String}] each member's capitalized bluebook name,
+    #   mapped to the absolute path of its `.bluebook` file
+    def self.members
+      Dir.glob(File.join(ROOT, "*.bluebook")).to_h do |path|
+        [Naming.pascal(File.basename(path, ".bluebook")), path]
+      end
+    end
+
+    # Every member whose own bluebook declares `provides capability` —
+    # read off the member's real IR (each loaded into a scratch registry,
+    # never the caller's), not off its name. Used where a check needs to
+    # say which member would satisfy it (`refuse_ungoverned_roles!`'s own
+    # suggestion, `Fuzzing::TargetCapabilities`).
+    #
+    # @param capability [String, Symbol] the capability name to look for
+    # @return [Array<String>] the names of every framework member that provides it,
+    #   sorted
+    def self.providers_of(capability)
+      members.keys.select { |name| chapter(name).provides?(capability) }.sort
+    end
+
+    # One member's chapter, built in isolation.
+    #
+    # @param name [String, Symbol] the member's name, such as `"Governance"`
+    # @return [Bluebook::Chapter] the member's chapter, loaded into a scratch registry
+    # @raise [Runtime::WiringError] if no framework member has that name
+    def self.chapter(name)
+      path = members.fetch(name.to_s) do
+        raise Runtime::WiringError,
+              "no framework member named #{name.inspect} — known: #{members.keys.sort.join(', ')}"
+      end
+
+      lib = File.expand_path("..", __dir__)
+      registry = Runtime::Registry.new
+      Hecks.with_registry(registry) do
+        # The same four a chapter needs to build at all (a predicate's
+        # source is recovered through the extraction port) — the seed
+        # `Grammar#grammar_chapters` and `bin/model_check` use.
+        Kernel.load(File.join(lib, "hecks/ports/persistence.port"))
+        Kernel.load(File.join(lib, "hecks/ports/extraction.port"))
+        Kernel.load(File.join(lib, "hecks/adapters/driven/memory.adapter"))
+        Kernel.load(File.join(lib, "hecks/adapters/driven/prism.adapter"))
+        Kernel.load(path)
+      end
+      registry.bluebook(name.to_s)
+    end
+
+    # Idempotent, per registry — `uses_framework` is now called more than
+    # once for the same member within a single boot (S8: a domain
     # attaching Governance for its own role check, plus a framework
     # sibling attaching it too, e.g. `banking.hecksagon`'s Identity
     # block). `Kernel.load` always re-executes the file, unlike
     # `require`, so a second call would re-run `Hecks.bluebook
     # "Governance"` a second time — and the self-hosting meta-domain
     # records every declaration as a real dispatched command against its
-    # own ledger, so a second `Declare` for the SAME aggregate is a real
+    # own ledger, so a second `Declare` for the same aggregate is a real
     # `AlreadyExists`, not a no-op. Skipped once the member's bluebook is
-    # already registered in THIS registry — the same chapter, not merely
+    # already registered in this registry — the same chapter, not merely
     # a same-named one from a stale prior boot.
+    #
+    # @param name [String, Symbol] the member's name, such as `"Governance"`
+    # @return [Boolean, nil] true when this call loaded the member's bluebook, nil when
+    #   the current registry already held it
+    # @raise [Runtime::WiringError] if no framework member has that name
     def self.load!(name)
       path = members.fetch(name.to_s) do
         raise Runtime::WiringError,

data/lib/hecks/freezer.rb

@@ -1,30 +1,30 @@
 module Hecks
-  # THE ONE PLACE THAT KNOWS HOW TO FREEZE A DOMAIN VALUE.
+  # The one place that knows how to freeze a domain value.
   #
   # Freezing here has been fixed four times in four places, each time by
   # topping the container and leaving the contents: list attributes, the
   # event log, query rows, and value objects. `.freeze` on a Hash stops a
-  # key being added or removed and NOTHING ELSE — the String, Array or
+  # key being added or removed and nothing else — the String, Array or
   # Hash a field holds stays mutable, so a caller reaches straight
   # through and edits in place. Each fix looked complete and none was.
   #
-  # WHAT SHOULD BE FROZEN, and why it is not everything:
+  # ## What should be frozen, and why it is not everything
   #
-  #   A VALUE OBJECT has no identity to change over. `with` already
+  #   a value object has no identity to change over. `with` already
   #   answers a new one rather than mutating, so freezing it through is
   #   what it always claimed to be.
   #
-  #   AN EMITTED EVENT is a record of something that happened. A mutable
+  #   an emitted event is a record of something that happened. A mutable
   #   audit trail is not one.
   #
-  #   A QUERY ROW is an answer, not a handle — mutating one edits nobody's
+  #   a query row is an answer, not a handle — mutating one edits nobody's
   #   state and silently disagrees with the store.
   #
-  #   AN INSTANCE'S STATE is NOT frozen, deliberately: the interpreter
+  #   an instance's state is not frozen, deliberately: the interpreter
   #   builds it up across a dispatch, and a command's whole job is to
-  #   change it. Its VALUES are frozen; the holder is not.
+  #   change it. Its values are frozen; the holder is not.
   #
-  #   A COMMAND'S ARGUMENTS are not frozen either. They arrive from
+  #   a command's arguments are not frozen either. They arrive from
   #   outside, are normalised and coerced on the way in, and the coerced
   #   result is what becomes a frozen value.
   module Freezer
@@ -32,7 +32,11 @@ module Hecks
 
     # Numbers, symbols, nil and booleans are already immediate or frozen;
     # a Value froze itself when it was built. What is left is the mutable
-    # trio, and each has to be WALKED rather than topped.
+    # trio, and each has to be walked rather than topped.
+    #
+    # @param held [Object] any domain value
+    # @return [Object] `held`, recursively frozen if it is a Hash, Array, or
+    #   String; returned unchanged otherwise
     def deep(held)
       case held
       when Hash   then held.each_value { |inner| deep(inner) }.freeze
@@ -43,13 +47,22 @@ module Hecks
     end
 
     # The question a gate asks, rather than the act. Answers false for the
-    # FIRST thing that is reachable and mutable, which is what makes a
+    # first thing that is reachable and mutable, which is what makes a
     # failure message worth reading.
+    #
+    # @param held [Object] any domain value
+    # @return [Boolean] true if `held` and everything reachable from it is frozen
     def deeply_frozen?(held) = unfrozen_within(held).nil?
 
     # The path to the first mutable thing reachable from `held`, or nil.
     # A path rather than a boolean because "something in this event is
     # mutable" is not an actionable sentence.
+    #
+    # @param held [Object] any domain value
+    # @param path [Array<String>] the owner path accumulated by the recursive
+    #   walk so far; callers pass nothing and get the default
+    # @return [String, nil] the dotted path (Hash keys, Array indices, or
+    #   `"(the value itself)"`) to the first mutable value found, or nil if none
     def unfrozen_within(held, path = [])
       return (path.empty? ? "(the value itself)" : path.join(".")) unless immune?(held) || held.frozen?
 
@@ -62,6 +75,9 @@ module Hecks
     # Immediates are frozen in every Ruby that matters, but asking
     # `frozen?` of them and trusting the answer has bitten enough people
     # that it is worth being explicit.
+    #
+    # @param held [Object] any domain value
+    # @return [Boolean] true if `held` is nil, true, false, a Numeric, or a Symbol
     def immune?(held) = held.nil? || held == true || held == false || held.is_a?(Numeric) || held.is_a?(Symbol)
   end
 end