hecks 1.3.0 → 1.5.0

data/lib/hecks/ir.rb

@@ -1,29 +1,32 @@
 module Hecks
-  # WHAT A CONSTRUCT EMITS, DECLARED RATHER THAN WRITTEN OUT.
+  # What a construct emits, declared rather than written out.
   #
-  # `IR` is a thing this framework PRODUCES, not a thing its model IS.
+  # `IR` is a thing this framework produces, not a thing its model is.
   # The language self-hosts, and its own bluebook declares aggregates
   # named `Bluebook`, `Aggregate`, `Command`, `Entity`, `ValueObject`,
   # `Policy`, `ReadModel` — there is no `IR` aggregate anywhere in the
   # grammar. Where the grammar's own vision line does say IR it means the
-  # emission: "the IR it STORES must equal the IR the DSL builder
-  # PRODUCES". `IR_VERSION` says the same thing structurally — a version
+  # emission: "the IR it stores must equal the IR the DSL builder
+  # produces". `IR_VERSION` says the same thing structurally — a version
   # stamped on `to_h`'s output rather than on the object is a version of
-  # the EMISSION, which only makes sense if the two are different things.
+  # the emission, which only makes sense if the two are different things.
   #
-  # So emitting IR is a CAPABILITY a construct has, and this is that
+  # So emitting IR is a capability a construct has, and this is that
   # capability: `include Hecks::IR` and declare the shape once.
-  # The model it emits FROM is `Hecks::Bluebook` — a chapter class
+  # The model it emits from is `Hecks::Bluebook` — a chapter class
   # nesting everything a chapter declares. It is deliberately not named
   # after this, its own output.
   #
-  # Before this, eighteen constructs each hand-wrote a `to_h` that said
-  # the same four things in the same order — read a field, recurse into a
-  # child, recurse into a list, or compute something — and the shape of a
-  # construct was knowable only by reading a method body. Declared, it is
-  # data: `ir_spec` can be walked by anything that wants to know what a
-  # construct carries, which is the whole point of hanging emission off
-  # the model rather than burying it.
+  # ## Why declared, not hand-written
+  #
+  # A hand-written `to_h` per construct would say the same four things in the
+  # same order — read a field, recurse into a child, recurse into a list, or
+  # compute something — leaving a construct's shape knowable only by reading a
+  # method body. Declared, it is data: `ir_spec` can be walked by anything
+  # that wants to know what a construct carries, which is the whole point of
+  # hanging emission off the model rather than burying it.
+  #
+  # ## Usage
   #
   #   include Hecks::IR            # an instance-shaped construct
   #
@@ -36,18 +39,18 @@ module Hecks
   #     canonical_form: -> { CanonicalForm.table } # anything else
   #   )
   #
-  # KEY ORDER IS THE DECLARATION ORDER, and that is load-bearing rather
+  # Key order is the declaration order, and that is load-bearing rather
   # than cosmetic: `spec/golden/ir/*.json` pins the emitted form exactly,
   # so a reordered declaration is a changed artifact and the golden specs
   # will say so.
   module IR
-    # THE TWO SHAPES A CONSTRUCT COMES IN, and why this module has two
+    # The two shapes a construct comes in, and why this module has two
     # doors instead of hiding the difference.
     #
     # `Bluebook`/`Aggregate`/`Policy`/`ReadModel` are ordinary objects —
     # metadata records, one instance per declaration. `Command`/`Entity`/
-    # `ValueObject` are anonymous CLASSES (`Class.new(self)`, see
-    # `Command.declare`), because those three are referenced as TYPES in
+    # `ValueObject` are anonymous classes (`Class.new(self)`, see
+    # `Command.declare`), because those three are referenced as types in
     # a bluebook (`attribute :price, Money`) and a type has to be a real
     # Ruby constant to be named.
     #
@@ -57,11 +60,20 @@ module Hecks
     #   extend  Hecks::IR   # class-shaped    — to_h is a class method
     #
     # Both get the same `emits_ir` and the same emission rules.
+    #
+    # Wires an instance-shaped construct's declaration and emission sides in.
+    #
+    # @param base [Class, Module] the includer
+    # @return [void]
     def self.included(base)
       base.extend(Declares)
       base.include(Emits)
     end
 
+    # Wires a class-shaped construct's declaration and emission sides in.
+    #
+    # @param base [Class, Module] the extender
+    # @return [void]
     def self.extended(base)
       base.extend(Declares)
       base.extend(Emits)
@@ -79,17 +91,36 @@ module Hecks
     # back — walking the superclass chain so an anonymous `Class.new(base)`
     # inherits its base's shape instead of redeclaring it.
     module Declares
+      # Records this construct's field -> emission-rule map.
+      #
+      # @param spec [Hash{Symbol => Symbol, Many, One, Proc}] each emitted key,
+      #   mapped to how it is produced: a Symbol is sent to the construct, `many`/
+      #   `one` recurse into nested constructs, and a Proc is instance-`exec`'d
+      # @return [void]
       def emits_ir(**spec)
         @ir_spec = spec
       end
 
+      # Marks a field as a list of nested constructs, each emitting itself.
+      #
+      # @param source [Symbol] the method that returns the list
+      # @return [Many] the wrapped source, for `emits_ir`
       def many(source) = Many.new(source)
+
+      # Marks a field as one nested construct, or nothing.
+      #
+      # @param source [Symbol] the method that returns the construct, or nil
+      # @return [One] the wrapped source, for `emits_ir`
       def one(source)  = One.new(source)
 
       # Walks the superclass chain so a `Class.new(ValueObject)` — which
-      # is what every declared value object actually IS — inherits the
+      # is what every declared value object actually is — inherits the
       # shape its base declared, rather than each anonymous subclass
       # having to redeclare it.
+      #
+      # @return [Hash{Symbol => Symbol, Many, One, Proc}, nil] the field -> rule
+      #   map declared by `emits_ir`, inherited from the nearest superclass that
+      #   declared one; nil if nothing in the chain ever declared a shape
       def ir_spec
         return @ir_spec if defined?(@ir_spec) && @ir_spec
 
@@ -112,7 +143,7 @@ module Hecks
       private
 
       # An instance reads its class's declaration; a class-shaped
-      # construct IS the declaration holder.
+      # construct is the declaration holder.
       def ir_spec_for(construct)
         return construct.ir_spec if construct.respond_to?(:ir_spec)
 

data/lib/hecks/language/bluebook/bluebook.bluebook

@@ -73,6 +73,26 @@ Hecks.bluebook "Bluebook", version: "1" do
     # chapters attach to nothing, and ABSENT IS NOT EMPTY, the same
     # reading `version`/`formerly_known_as` above give.
     attribute :attaches_to, list_of(AttachesToContext)
+    # A CAPABILITY THIS CHAPTER ANSWERS FOR OTHER DOMAINS — declared, so
+    # nothing downstream has to recognise the chapter BY NAME. One row
+    # per (capability, key, verb): `provides "authorization", grant:
+    # "RoleAssignment.Assign"` is the row (authorization, grant,
+    # RoleAssignment.Assign). The runtime's role check, boot's
+    # ungoverned-role refusal, the authorization adapter and the fuzzer
+    # all read the rows rather than the literal "Governance". Most
+    # chapters provide nothing, and ABSENT IS NOT EMPTY, the same reading
+    # `attaches_to` above gives.
+    attribute :provides, list_of(Provision)
+
+    value_object "Provision" do
+      attribute :capability, String
+      attribute :key,        String
+      attribute :verb,       String
+    end
+
+    value_object "ProvisionText" do
+      attribute :value, String
+    end
 
     value_object "RuleText" do
       # deliberately permissive : source_token and replacement are legitimately
@@ -159,6 +179,22 @@ Hecks.bluebook "Bluebook", version: "1" do
       emits ChapterAttached
     end
 
+    # ONE ROW OF ONE CAPABILITY — `provides "authorization", assignments:
+    # ..., grant: ..., transitions: ...` offers three, one per key, in the
+    # order they were written.
+    command "Provide" do
+      role "Language"
+      goal "Declare one verb this chapter answers a capability with"
+
+      attribute :capability, ProvisionText
+      attribute :key,        ProvisionText
+      attribute :verb,       ProvisionText
+
+      sets :provides, append: { capability: :capability, key: :key, verb: :verb }
+
+      emits CapabilityProvided
+    end
+
     # THE WAY BACK.
     #
     # Until these existed the meta-domain was write-only: twelve categories, 34
@@ -214,6 +250,7 @@ Hecks.bluebook "Bluebook", version: "1" do
       member word: "vision", context: "Bluebook", body: "none", inner: "", opens: "", fills: "vision"
       member word: "formerly_known_as", context: "Bluebook", body: "none",   inner: "",               opens: "",               fills: "formerly_known_as"
       member word: "attaches_to",     context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "attaches_to", calls: "attaches_to_impl"
+      member word: "provides",        context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "provides", calls: "provides_impl"
       member word: "core",            context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
       member word: "supporting",      context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
       member word: "generic",         context: "Bluebook", body: "none",     inner: "",               opens: "",               fills: "classification"
@@ -246,6 +283,10 @@ Hecks.bluebook "Bluebook", version: "1" do
       member keyword: "vision",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "vision", coerce: "false"
       member keyword: "formerly_known_as", context: "Bluebook", at: "1", named: "",      kind: "text",     required: "true",  fills: "formerly_known_as"
       member keyword: "attaches_to",     context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "attaches_to", variadic: "true"
+      member keyword: "provides",        context: "Bluebook", at: "1", named: "",            kind: "text", required: "true",  fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "assignments", kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "grant",       kind: "text", required: "false", fills: "provides"
+      member keyword: "provides",        context: "Bluebook", at: "",  named: "transitions", kind: "text", required: "false", fills: "provides"
       member keyword: "aggregate",       context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"
       member keyword: "read_model", context: "Bluebook", at: "1", named: "", kind: "text", required: "true", fills: "name"
       member keyword: "policy",          context: "Bluebook", at: "1", named: "",        kind: "text",     required: "true",  fills: "name"

data/lib/hecks/language/bluebook/policy.bluebook

@@ -21,6 +21,13 @@ Hecks.bluebook "Bluebook" do
     attribute :on_event,        PolicyText
     attribute :trigger_command, PolicyText
     attribute :target_domain,   PolicyText
+    # AN `across` TARGET THIS DOMAIN EXPECTS NEVER TO REACH — declared on
+    # the policy that owns the expectation, not held in a core allowlist
+    # keyed by domain name. `ModelCheck` honours it both ways: the
+    # unknown-target and unacknowledged-relationship findings it would
+    # otherwise raise are expected, and a declaration whose target turns
+    # out to be known or acknowledged after all is STALE and fails.
+    attribute :expect_undelivered, PolicyText
     # THE GUARD, CARRIED AS TEXT — same discipline `Command.givens`
     # already holds: the block that wrote it is never called at
     # runtime, only its EXTRACTED SOURCE is (Ports::Extraction), so
@@ -92,6 +99,7 @@ Hecks.bluebook "Bluebook" do
       attribute :on_event,        PolicyText
       attribute :trigger_command, PolicyText
       attribute :target_domain,   PolicyText, optional: true
+      attribute :expect_undelivered, PolicyText, optional: true
       attribute :where,           PolicyText, optional: true
       attribute :for_each,        PolicyText, optional: true
 
@@ -102,6 +110,7 @@ Hecks.bluebook "Bluebook" do
       sets :on_event
       sets :trigger_command
       sets :target_domain
+      sets :expect_undelivered
       sets :where
       sets :for_each
       sets :position
@@ -153,7 +162,7 @@ Hecks.bluebook "Bluebook" do
 
       member word: "on",              context: "Policy",    body: "none", inner: "", opens: "",       fills: "on_event", calls: "on_impl"
       member word: "trigger",         context: "Policy",    body: "none", inner: "", opens: "",       fills: "trigger_command", calls: "trigger_impl"
-      member word: "across",          context: "Policy",    body: "none", inner: "", opens: "",       fills: "target_domain"
+      member word: "across",          context: "Policy",    body: "none", inner: "", opens: "",       fills: "target_domain", calls: "across_impl"
       member word: "where",           context: "Policy",    body: "source", inner: "", opens: "", fills: "where"
       member word: "for_each",        context: "Policy",    body: "none", inner: "", opens: "", fills: "for_each"
 
@@ -181,6 +190,7 @@ Hecks.bluebook "Bluebook" do
       member keyword: "trigger",         context: "Policy", at: "1", named: "", kind: "constant", required: "true", fills: "trigger_command"
       member keyword: "trigger",         context: "Policy", at: "1", named: "", kind: "text",     required: "true", fills: "trigger_command"
       member keyword: "across",          context: "Policy", at: "1", named: "", kind: "text", required: "true", fills: "target_domain"
+      member keyword: "across",          context: "Policy", at: "", named: "expect_undelivered", kind: "flag", required: "false", fills: "expect_undelivered"
       member keyword: "for_each",        context: "Policy", at: "1", named: "", kind: "text", required: "true", fills: "for_each"
       member keyword: "trigger", context: "Policy", at: "", named: "with", kind: "pairs", required: "false", fills: "with_spec", pairs_shape: "verbatim"