hecks 2.8.0 → 2.9.0

data/lib/hecks/projections/model.rb

@@ -3,35 +3,14 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # The model classes, projected from the language that declares them.
-    #
-    # A construct's holding half — its readers, its emission, a
-    # constructor that assigns declared fields and hands off — restates
-    # what `bluebook.bluebook` already says, three times over in Ruby.
-    # This renders it instead.
-    #
-    # **Only the holding half**. `Behaviour::X` is hand-written and permanent,
-    # and `settle` is the seam: everything a declaration cannot state
-    # lives behind it, so regenerating can never be lossy. That property
-    # was established construct by construct before any of this was
-    # written — the chapter looked generatable and was not, until its
-    # `@hecks_root`, ports table and child stamping moved behind `settle`.
-    #
-    # The `HOST` manifest is the honest part. The grammar states the fields;
-    # it does not state which constructs are Ruby classes rather than
-    # instances, what a constructor's defaults are, or how a value is
-    # coerced on the way in. Those are facts about Ruby, not about
-    # bluebooks, so they are declared here rather than pretended into the
-    # language — and keeping them in one table is what would let a second
-    # host swap this file rather than edit thirteen.
+    # The model classes' holding half (readers, emission, constructor), projected from the
+    # language. `Behaviour::X` stays hand-written behind `settle`, so regenerating is never lossy.
     module Model
       extend Projector::Target
 
       projects_as :model, declares: "Bluebook", emits: :files
 
-      # **Per-construct Ruby facts**. `coerce` is the only fiddly column: a
-      # declared field arrives as whatever the builder handed over, and
-      # each construct has always normalised its own on the way in.
+      # Per-construct Ruby facts the grammar does not state (defaults, coercion, class shape).
       HOST = {
         "Policy" => {
           construct: "Policy",
@@ -42,22 +21,12 @@ module Hecks
           defaults:  { name: nil, on_event: "nil", trigger_command: "nil",
                        target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
                        with_spec: "[]", aggregate: "nil" },
-          # A flag on the wire is a boolean — the language holds it as
-          # text ("true"), the builder hands over `true`, and a
-          # reconstruction hands back whichever it read; all three land
-          # as the same `true`/`false`.
+          # The language holds a flag as "true" and the builder as `true`; both become a boolean.
           coerce:    { name: ".to_s", aggregate: "&.to_s", expect_undelivered: ".to_s == \"true\"" },
-          # A list of bindings is not a scalar on the wire. Every other
-          # field emits as itself; this one has to render the way
-          # `DispatchSpec`'s own `with_spec` does — keys to strings, and
-          # `render_value` keeping the leading colon on a Symbol, because
-          # a binding that reads an event field and one that supplies a
-          # literal string are otherwise indistinguishable once written
-          # down (see `MetaValidator::Readings`' own note on exactly that).
+          # Bindings render like `DispatchSpec#with_spec`; `render_value` keeps a Symbol's colon
+          # so an event-field read and a literal string stay distinguishable.
           renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }",
-                       # Computed (Deviations::COMPUTED["Policy"]): the structured
-                       # form of `where`, a pure function of that text, the same
-                       # `ast` every rule row carries beside its `canonical`.
+                       # Computed (Deviations::COMPUTED["Policy"]): derived from `where`.
                        where_ast: "-> { where_ast }" },
           settles:   false
         }
@@ -109,11 +78,8 @@ module Hecks
         RUBY
       end
 
-      # The emission, keyed as the model spells it and sourced as the
-      # language declares it.
-      # A computed field (Deviations::COMPUTED) is emitted too — it is
-      # model-only by definition, so it rides after the declared fields
-      # and must have a `renders` entry, there being nothing to `send`.
+      # Renders the `emits_ir` call. A computed field (Deviations::COMPUTED) rides after the
+      # declared ones and needs a `renders` entry, since there is nothing to `send`.
       #
       # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
       #   attributes are read from
@@ -127,10 +93,8 @@ module Hecks
         "emits_ir(\n#{fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n")}\n)"
       end
 
-      # What the construct emits: what the language declares, less every
-      # deviation the tables account for. The generator and
-      # spec/model_shape_conformance_spec compute this the same way, from
-      # the same tables, which is the point of the tables being in lib.
+      # What the construct emits: the declared attributes less every `Deviations` entry.
+      # spec/model_shape_conformance_spec computes it from the same tables.
       #
       # @param bluebook [Bluebook::Chapter] the "Bluebook" chapter the construct's own
       #   attributes are read from
@@ -158,10 +122,7 @@ module Hecks
         accessors = host.fetch(:accessors, [])
         return lines.join("\n") if accessors.empty?
 
-        # A declared field the model deliberately does not emit still
-        # needs a reader, and the reason it is off the wire is carried
-        # here rather than typed in — a comment that survives
-        # regeneration is one the generator writes.
+        # The off-the-wire reason is emitted so the comment survives regeneration.
         reasons = Deviations::OFF_THE_WIRE.fetch(host.fetch(:construct, ""), {})
         (lines + accessors.map do |a|
           why = reasons[a]

data/lib/hecks/projections/oidc.rb

@@ -3,42 +3,12 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # An OIDC client/scope manifest derived from a domain's own IR: what
-    # an identity provider has to know about this domain before it can
-    # issue a token that means anything here.
+    # An OIDC client/scope manifest derived from a domain's IR: the audience, one scope per
+    # command, and the roles those commands demand.
     #
-    # ## The artifact half of something already half-built
-    #
-    # `spec/oidc_projection_spec.rb` covers the integration half — verified
-    # claims in, `IdentityResolution.resolve` → `Authorization.holds_role?`
-    # → a dispatch scoped by `Hecks.as_caller(role:)`. That half enforces
-    # a role per command. It just had no way to say, up front and as data,
-    # which role each command wants — every answer came from asking the
-    # live runtime one dispatch at a time.
-    #
-    # This is that catalogue, and the two are checked against each other
-    # rather than merely coexisting: `verb` here is spelled exactly as
-    # `Runtime::Dispatcher#dispatch` takes it and exactly as
-    # `Bluebook#verbs` lists it, so a scope can never name a command
-    # the domain does not have (spec/projections/oidc_projection_spec.rb
-    # holds the two lists equal), and `role` is the same string
-    # `Ports::Authorization.holds_role?` compares against a real
-    # `Governance::RoleAssignment`.
-    #
-    # ## Roles come from the commands, not from governance
-    #
-    # A command's own `role "Compliance officer"` is in the bluebook IR
-    # (`Command#role`), whereas `uses_framework "Governance"` is
-    # declared in the `.hecksagon` — which `call(bluebook:, options:)`
-    # cannot see at all. Reading the commands is both the only thing
-    # available here and the more accurate source: it says what each
-    # command actually demands, not merely which role vocabulary the
-    # application happened to mount.
-    #
-    # A command with no declared role projects `"role" => nil` rather
-    # than being dropped — an unguarded command is a real fact about the
-    # domain, and silently omitting it would make the manifest read as
-    # though the command did not exist.
+    # `verb` matches `Bluebook#verbs` and `role` matches what `Ports::Authorization.holds_role?`
+    # compares. Roles come from each command's own `role`, since `.hecksagon` is not visible here.
+    # A command with no declared role projects `"role" => nil` rather than being dropped.
     module OIDC
       extend Projector::Target
 
@@ -46,9 +16,8 @@ module Hecks
 
       module_function
 
-      # `audience:` overrides the domain name, for the ordinary case
-      # where the IdP's registered audience is a URL rather than a bare
-      # chapter name.
+      # Projects the manifest; `audience:` overrides the domain name (an IdP audience is
+      # usually a URL).
       #
       # @param bluebook [Bluebook::Chapter] the chapter being projected
       # @param options [Hash{Symbol => Object}] `:audience` (String, Symbol, nil)
@@ -66,16 +35,8 @@ module Hecks
         }
       end
 
-      # Sorted by scope, not left in declaration order — a manifest is
-      # something two versions of get diffed, and the same precedent
-      # `StorageShape.project` sets for its own aggregate list.
-      #
-      # Recurses into entities, not just an aggregate's own direct
-      # commands — the exact same gap `Bluebook#verbs` closed for the
-      # same reason (`chapter.rb`'s own comment): a command reached
-      # through `Dispatcher#dispatch`'s dotted `Entity.Command` routing
-      # is real and callable, so a manifest that never names it can
-      # never grant a client a scope for it either.
+      # Every command's scope entry, entity commands included (they dispatch as `Entity.Command`).
+      # Sorted by scope so two manifest versions diff cleanly.
       #
       # @param bluebook [Bluebook::Chapter] the chapter being projected
       # @return [Array<Hash{String => Object}>] every command's scope entry (see
@@ -100,10 +61,7 @@ module Hecks
           aggregate.entities.flat_map { |entity| entity_scopes(entity, verb_prefix, scope_prefix) }
       end
 
-      # S17, ADR 0026 — an entity can nest further entities (`Dispatch`,
-      # inside `Handler`), so this recurses the same way `Chapter#verbs`
-      # now does. The verb and scope prefixes grow in lockstep, each
-      # `.`-joined the same way its own kind already was.
+      # Projects an entity's commands, recursing into nested entities (ADR 0026).
       #
       # @param entity [Bluebook::Entity] the entity being projected
       # @param verb_prefix [String] the enclosing aggregate or entity's own verb
@@ -120,10 +78,8 @@ module Hecks
           entity.entities.flat_map { |piece| entity_scopes(piece, verb_prefix, scope_prefix) }
       end
 
-      # `banking:account.open` — the shape an OIDC scope is conventionally
-      # spelled in, and snake_cased through the same `Naming.snake` the
-      # facade uses to name a command's own door method, so a scope and
-      # the Ruby call that satisfies it cannot drift apart.
+      # One scope entry per command, spelled like `banking:account.open`; snake-cased through
+      # `Naming.snake`, as the facade names its door methods.
       #
       # @param commands [Array<Bluebook::Command>] the commands to project
       # @param verb_prefix [String] the owning aggregate or entity's fully-qualified

data/lib/hecks/projections/parser_table.rb

@@ -2,14 +2,8 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # The Rust parser's keyword table, projected from the chapter's own
-    # Syntax aggregate — "the parser's grammar knowledge is derived from
-    # hecks's self-description, not hand-typed a second time", which
-    # is the anti-drift idea the whole Rust-parser plan rests on.
-    #
-    # A registered target now, rather than a module living inside its own
-    # bin/ script. It was already a projection in everything but call
-    # shape; this only stops it being a fifth way of spelling one.
+    # The Rust parser's keyword table, projected from the chapter's own Syntax aggregate,
+    # so the parser's grammar knowledge is derived rather than hand-typed a second time.
     module ParserTable
       extend Projector::Target
       projects_as :parser_table, declares: "Syntax"
@@ -27,10 +21,8 @@ module Hecks
 
       module_function
 
-      # The chapter is handed over, not reached for — reaching for the grammar
-      # registry directly would pin the projection to one chapter, the language's
-      # own, and the projector protocol already hands over the chapter as an
-      # argument, at no cost.
+      # The chapter's `Syntax` aggregate. Taken from the argument, not the grammar registry,
+      # so the projection is not pinned to the language's own chapter.
       #
       # @param bluebook [Bluebook::Chapter] the chapter to read the Syntax aggregate
       #   from
@@ -38,10 +30,7 @@ module Hecks
       #   it declares none
       def syntax(bluebook) = bluebook.aggregate("Syntax")
 
-      # Every cell as text — exactly spec/syntax_conformance_spec.rb's own
-      # `rows` helper, reused rather than re-derived: a member's fields decode
-      # back through typed literal decoding on the way out of reconstruction,
-      # and this reads it back as what was written.
+      # Every cell as text, as spec/syntax_conformance_spec.rb's `rows` helper reads it.
       #
       # @param bluebook [Bluebook::Chapter] the chapter to read from
       # @param name [String] the closed-set value object's name, such as `"Context"`
@@ -63,10 +52,8 @@ module Hecks
       ARGUMENT_FIELDS = %i[keyword context at named kind required fills selects
                            pair_key_fills pair_value_fills pairs_shape status variadic minimum].freeze
 
-      # A Rust string literal for one field's value — every field here is
-      # plain ASCII (a word, a context name, a digit, "true"/"false"), so this
-      # only has to be safe against the two characters Rust string literals
-      # themselves reserve.
+      # A Rust string literal for one field's value. Fields are plain ASCII, so only
+      # the backslash and double quote need escaping.
       #
       # @param value [Object] the field value to render; stringified before escaping
       # @return [String] a quoted Rust string literal
@@ -100,14 +87,8 @@ module Hecks
         "pub static #{name}: &[&str] = &[\n#{lines.join("\n")}\n];\n"
       end
 
-      # S14, ADR 0026 — Keyword/Argument are genuine entities of Syntax
-      # now, dispatched (not merely declared) so their own `status`
-      # really is a lifecycle. `SyntaxBoot.call` reads the still-static
-      # seed rows (`KeywordSeed`/`ArgumentSeed`), dispatches each one
-      # through the real admission/lifecycle door, and hands back rows in
-      # the same shape `rows` reads for every other closed set here —
-      # symbol keys, string values, `status` included — so nothing else
-      # in this file needs to change.
+      # Renders the whole Rust source. Keyword and Argument rows come from `SyntaxBoot.call`,
+      # which dispatches the seed rows so `status` is a real lifecycle (ADR 0026).
       #
       # @param bluebook [Bluebook::Chapter] the chapter to project
       # @return [String] the rendered `KEYWORDS`/`ARGUMENTS`/closed-set Rust source

data/lib/hecks/projections/reference.rb

@@ -9,21 +9,8 @@ module Hecks
   end
 
   module Projections
-    # The DSL reference pages, projected from the chapter's own Syntax
-    # aggregate — the tables come from the declaration, the prose is
-    # preserved from whatever is already committed.
-    #
-    # The first projection that emits a tree. `emits: :files` says so,
-    # and the framework writes the map rather than inferring one: a Hash
-    # of path => contents and a Hash that merely holds strings are the
-    # same object to Ruby, so only the projection can know which it
-    # meant. This is the case the output contract was designed for and
-    # deliberately left unimplemented until something real needed it.
-    #
-    # Not pure, and it cannot be. `Doc::Reference.pages` reads the
-    # committed pages to harvest their prose, so the existing directory
-    # is an input — passed as `from:` rather than assumed, so the
-    # projection never reaches for a path of its own choosing.
+    # The DSL reference pages, projected from the chapter's Syntax aggregate;
+    # tables come from the declaration, prose is preserved from what's already committed.
     module Reference
       extend Projector::Target