hecks 0.2.0 → 0.3.0

data/lib/hecks/projector/narrate_projector.rb

@@ -0,0 +1,243 @@
+require_relative "docs_projector"
+require_relative "../forms/field_shape"
+
+module Hecks
+  module Projector
+    # A BLUEBOOK, PROJECTED AS PROSE AN SME CAN READ BACK AND CONFIRM.
+    #
+    # WHAT THIS IS FOR. `DocsProjector` already answers "what can I call and
+    # what does it want" for the person implementing against a domain —
+    # tables of arguments, shapes, refusal reasons. That is the wrong
+    # register for the person who can actually say whether the domain is
+    # RIGHT: the subject-matter expert who knows what an account is and has
+    # never read a markdown table in their life. This projects the same IR
+    # as sentences instead — "Debit — take money out. Issued by a Teller. It
+    # only goes through if the balance covers it." — so a domain can be
+    # read back to the person who can validate it without them learning the
+    # DSL first.
+    #
+    # SAME SOURCE, SAME GUARANTEE `DocsProjector` gives: nothing here is
+    # invented. Every sentence quotes a `description`, `goal`, or `given`
+    # already declared in the chapter; where a chapter says nothing, this
+    # says nothing rather than manufacturing a sentence out of an
+    # identifier. Registered as `:narrate` beside `:docs`, same call shape
+    # (`Projector.call(:narrate, bluebook: ...)`), same aggregate-scoping
+    # via `options[:aggregate]`.
+    #
+    # WHAT IT DOES NOT DO: replace `DocsProjector`. A shape table still says
+    # "id of a Customer" more precisely than any sentence would, and an
+    # implementer still wants that. This is the other document the same IR
+    # is owed — one written for the reader who is being asked "is this
+    # right?", not "how do I call it?"
+    module NarrateProjector
+      module_function
+
+      # `options[:heading]` sets the top heading level, exactly as
+      # `DocsProjector` does — so this, too, can be spliced into a larger
+      # document rather than always starting at H1.
+      def call(bluebook:, options: {})
+        depth = (options[:heading] || 1).to_i
+        only  = options[:aggregate]
+
+        sections = []
+        sections << chapter_intro(bluebook, depth) unless only
+        Array(DocsProjector.aggregates(bluebook, only)).each do |aggregate|
+          sections << aggregate_narrative(aggregate, only ? depth : depth + 1)
+        end
+        sections << reactions_narrative(bluebook, depth + 1) unless only
+        "#{sections.compact.join("\n\n").rstrip}\n"
+      end
+
+      # ── the chapter ───────────────────────────────────────────────────
+
+      def chapter_intro(bluebook, depth)
+        parts = [DocsProjector.h(depth, bluebook.name)]
+        parts << bluebook.vision if bluebook.vision
+
+        meta = []
+        meta << "This is a #{bluebook.classification} domain." if bluebook.classification
+        meta << "It was formerly known as `#{bluebook.formerly_known_as}`." if bluebook.formerly_known_as
+        parts << meta.join(" ") unless meta.empty?
+
+        names = bluebook.aggregates.map(&:hecks_name)
+        parts << "It's told through #{to_sentence_list(names)}." unless names.empty?
+        parts.join("\n\n")
+      end
+
+      # ── one aggregate ─────────────────────────────────────────────────
+
+      def aggregate_narrative(aggregate, depth)
+        parts = [DocsProjector.h(depth, aggregate.hecks_name)]
+        parts << aggregate.description if aggregate.description
+        parts << identity_sentence(aggregate)
+
+        refs = aggregate.attributes.select(&:reference?)
+        parts << "Each one is linked to #{to_sentence_list(refs.map { |r| "#{a_or_an(r.type.target_name)} #{r.type.target_name}" })}." unless refs.empty?
+
+        parts << lifecycle_narrative(aggregate)
+        parts << verbs_narrative(aggregate, depth + 1)
+        parts << queries_narrative(aggregate.queries, aggregate.hecks_name, depth + 1)
+
+        aggregate.entities.each { |entity| parts << entity_narrative(aggregate, entity, depth + 1) }
+        parts.compact.join("\n\n")
+      end
+
+      def identity_sentence(holder)
+        return nil if holder.identity_heads.empty?
+
+        "Every #{holder.hecks_name} is identified by its #{to_sentence_list(holder.identity_heads.map { |h| "`#{h}`" })}."
+      end
+
+      def entity_narrative(aggregate, entity, depth)
+        parts = [DocsProjector.h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})")]
+        parts << entity.description if entity.description
+        parts << "Reached through its #{aggregate.hecks_name} — you address it by the #{aggregate.hecks_name}'s " \
+                 "id together with its own `#{entity.identity_heads.join('`, `')}`."
+
+        parts << lifecycle_narrative(entity)
+        parts << verbs_narrative(entity, depth + 1)
+        parts << queries_narrative(entity.queries, entity.hecks_name, depth + 1)
+        parts.compact.join("\n\n")
+      end
+
+      # ── the machine ───────────────────────────────────────────────────
+
+      def lifecycle_narrative(holder)
+        lifecycle = holder.lifecycle or return nil
+
+        sentences = ["It carries a `#{lifecycle.field}`, starting out at `#{lifecycle.default}`."]
+        lifecycle.transitions.each do |name, transition|
+          froms = Array(transition.from).map { |f| "`#{f}`" }
+          sentences << "**#{name}** moves it from #{to_sentence_list(froms, conj: 'or')} to `#{transition.target}`."
+        end
+        sentences << "A verb not listed here can be issued from any state."
+        sentences.join(" ")
+      end
+
+      # ── the verbs ─────────────────────────────────────────────────────
+
+      def verbs_narrative(holder, depth)
+        return nil if holder.commands.empty?
+
+        header = DocsProjector.h(depth, "What can happen to #{a_or_an(holder.hecks_name)} #{holder.hecks_name}")
+        body   = holder.commands.map { |command| command_paragraph(command, holder) }.join("\n\n")
+        "#{header}\n\n#{body}"
+      end
+
+      def command_paragraph(command, holder)
+        # THE GOAL, VERBATIM — same rule `DocsProjector` holds to: quoted
+        # exactly as declared, not recased to fit mid-sentence, because the
+        # promise this whole projector makes is that a sentence here is a
+        # sentence the chapter actually wrote.
+        sentences = ["**#{command.hecks_name}**#{command.goal ? " — #{command.goal}." : '.'}"]
+        sentences << "Issued by #{a_or_an(command.role)} #{command.role}." if command.role
+        # `acts_on.nil?`, NOT `creates?` — `creates?` answers true for every
+        # verb an ENTITY declares (it never references itself; see
+        # `Command#acts_on`'s own comment), so reading it directly here would
+        # tell an SME that `LedgerEntry.Amend` brings a new ledger entry into
+        # being, which is exactly backwards.
+        sentences << "This is how a new #{holder.hecks_name} comes into being." if command.acts_on.nil?
+
+        arguments = command.attributes.reject(&:reference?)
+        sentences << "It takes #{to_sentence_list(arguments.map { |a| Forms::Humanize.label(a.name.to_s).downcase })}." unless arguments.empty?
+
+        refs = command.attributes.select(&:reference?)
+        sentences << "It's aimed at one existing #{to_sentence_list(refs.map { |r| r.type.target_name })}, by id." unless refs.empty?
+
+        conditions = conditions_of(command, holder)
+        sentences << "It only goes through if #{conditions.join('; ')}." unless conditions.empty?
+
+        guarantees = command.ensures.map(&:description)
+        sentences << "When it succeeds: #{guarantees.join('; ')}." unless guarantees.empty?
+
+        sentences << "It records `#{command.emits.join('`, `')}` as a fact." unless command.emits.empty?
+
+        sentences.join(" ")
+      end
+
+      # EVERY REQUIRED CONDITION, STATED AS SOMETHING THAT MUST BE TRUE —
+      # the same three sources `DocsProjector#refusals_of` reads (the
+      # lifecycle edge, a reference's existence, and the command's own
+      # `given`s), but kept positive rather than phrased as a refusal
+      # reason. "Refused unless not X" is a sentence a reader has to
+      # invert in their head; "only goes through if X" is not.
+      def conditions_of(command, holder)
+        conditions = []
+
+        lifecycle = holder.lifecycle
+        if lifecycle
+          froms = lifecycle.transitions.filter_map { |name, transition|
+            Array(transition.from) if name.to_s == command.hecks_name
+          }.flatten.uniq
+          conditions << "its `#{lifecycle.field}` is currently #{to_sentence_list(froms.map { |f| "`#{f}`" }, conj: 'or')}" unless froms.empty?
+        end
+
+        conditions + command.givens.map(&:description)
+      end
+
+      # ── the reads ─────────────────────────────────────────────────────
+
+      def queries_narrative(queries, holder_name, depth)
+        return nil if queries.empty?
+
+        header = DocsProjector.h(depth, "Questions you can ask about #{a_or_an(holder_name)} #{holder_name}")
+        lines = queries.map do |query|
+          shape   = query.to_h
+          takes   = Array(shape[:attributes]).map { |a| Forms::Humanize.label(a[:name].to_s).downcase }
+          # `w[:value]` ALREADY WEARS ITS OWN QUOTES OR COLON — it is a
+          # `Literal.render`ed string (see lib/hecks/literal.rb), not a raw
+          # Ruby value, so wrapping it in `.inspect` here would quote an
+          # already-quoted string a second time.
+          filters = Array(shape[:wheres]).map { |w| "`#{w[:field]}` #{op_words(w[:op])} #{w[:value]}" }
+
+          sentence = "- **#{query.hecks_name}**"
+          sentence << " (given #{to_sentence_list(takes)})" unless takes.empty?
+          sentence << " — #{query.description}" if query.description
+          sentence << "." unless sentence.end_with?(".")
+          sentence << " Only where #{to_sentence_list(filters)}." unless filters.empty?
+          sentence
+        end
+        "#{header}\n\n#{lines.join("\n")}"
+      end
+
+      def op_words(op)
+        { eq: "is", lt: "under", lte: "at most", gt: "over", gte: "at least" }[op.to_s.to_sym] || op.to_s
+      end
+
+      # ── what happens on its own ───────────────────────────────────────
+
+      def reactions_narrative(bluebook, depth)
+        return nil if bluebook.policies.empty? && bluebook.process_managers.empty?
+
+        parts = [DocsProjector.h(depth, "Reactions")]
+        bluebook.policies.each do |policy|
+          elsewhere = policy.target_domain ? " in #{policy.target_domain}" : ""
+          parts << "Whenever `#{policy.on_event}` happens, `#{policy.trigger_command}` fires on its own#{elsewhere} — nobody has to ask for it."
+        end
+
+        bluebook.process_managers.each do |saga|
+          shape = saga.to_h
+          parts << "**#{shape[:name]}** is a saga: it starts when `#{shape[:starts_on]}` happens and ends when " \
+                   "`#{shape[:ends_on]}` happens, with each run tracked by its `#{shape[:correlates_by]}`. Along the " \
+                   "way it moves through #{Array(shape[:states]).map { |s| "`#{s}`" }.join(' → ')}."
+        end
+        parts.join("\n\n")
+      end
+
+      # ── small sentence carpentry ──────────────────────────────────────
+
+      def to_sentence_list(items, conj: "and")
+        case items.size
+        when 0 then ""
+        when 1 then items[0].to_s
+        when 2 then "#{items[0]} #{conj} #{items[1]}"
+        else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
+        end
+      end
+
+      def a_or_an(word)
+        %w[a e i o u].include?(word.to_s[0].to_s.downcase) ? "an" : "a"
+      end
+    end
+  end
+end

data/lib/hecks/projector/target.rb

@@ -0,0 +1,97 @@
+module Hecks
+  module Projector
+    # WHAT MAKES A MODULE A PROJECTION TARGET. `Projector.register` has
+    # always accepted anything answering `call(bluebook:, options:)` —
+    # this only removes the second step, so a target declares its own key
+    # beside its own implementation instead of being registered from
+    # somewhere else that has to be kept in sync with it.
+    #
+    #   module Hecks::Projections::OIDC
+    #     extend Hecks::Projector::Target
+    #     projects_as :oidc
+    #
+    #     module_function
+    #
+    #     def call(bluebook:, options: {}) = { ... }
+    #   end
+    #
+    # NAMED `Target`, NOT `Projection`, on purpose. "Projection" already
+    # means two other things in this codebase: `Ports::Projection` is
+    # read-model catch-up (events folded into view state), and `bin/project`
+    # forces that catch-up by hand. Neither has anything to do with
+    # "canonical IR in, external artifact out". A third meaning under the
+    # same word would make the two impossible to grep apart — and from a
+    # domain's point of view `project(X)` really does read as "project TO
+    # a target", so the narrower word is also the more accurate one.
+    module Target
+      # Registering at declaration time means `require`ing a target is
+      # the whole of installing it — there is no separate manifest that
+      # can silently disagree about which targets exist.
+      #
+      # `requires:` NAMES A CAPABILITY, not a shape word.
+      #
+      # This began as `from: :chapter` / `from: :any` — two hand-kept
+      # symbols, admitted by duck-typing on `.aggregates`, which is a
+      # guess at what "is a chapter" means. The capabilities were already
+      # real by then: `Hecks::IR` is the ability to emit IR (its own
+      # header says so), and `Behaviour::Chapter` is the ability to answer
+      # as a chapter. So a projection names the module it needs, and
+      # admission is a genuine check rather than a proxy for one.
+      #
+      #   projects_as :ir,         requires: Hecks::IR
+      #   projects_as :vocabulary                              # chapter, the default
+      #
+      # It also composes: a projection needing two capabilities names
+      # both, instead of a third symbol being invented for the pair.
+      #
+      # THE FAIL-QUIET THIS CLOSES, unchanged in substance: every
+      # construct emits its own IR, so handing a projector an AGGREGATE
+      # instead of a chapter is the natural thing to try. `bluebook:` was
+      # only ever a PARAMETER NAME, never a contract. `:oidc` failed
+      # loudly (no `aggregates` method), but `:shape` returned
+      # `{"name" => "Order", "aggregates" => []}` — well-formed,
+      # confident, and wrong.
+      # `declares:` NAMES AN AGGREGATE THE CHAPTER MUST HAVE.
+      #
+      # A capability says what a construct can DO; this says what it must
+      # CARRY. `:vocabulary` needs a chapter declaring a Vocabulary
+      # aggregate, `:parser_table` one declaring Syntax — and both used
+      # to state that as a `raise` in their own body, which is a
+      # requirement written as behaviour instead of declared. Stated
+      # here, the registry refuses before the projection runs and the
+      # projection stops carrying a guard about its own admission.
+      # `emits:` SAYS WHAT KIND OF ARTIFACT COMES BACK.
+      #
+      # `:artifact` (the default) is one thing — a Hash, or a String.
+      # `:files` is a TREE: a Hash of relative path => contents, which is
+      # what a reference-page or codegen projection produces.
+      #
+      # Declared rather than sniffed, deliberately. Inferring a tree from
+      # an ordinary Hash is guesswork — `{"name" => "Pizzas"}` is
+      # indistinguishable from a one-file tree — so `write` asks what the
+      # projection said rather than inspecting what it returned.
+      def projects_as(key, requires: nil, declares: nil, emits: :artifact)
+        @projection_emits    = emits
+        @projection_key      = key.to_sym
+        @projection_declares = Array(declares)
+        @projection_requires = Array(requires)
+        Projector.register(@projection_key, self)
+        @projection_key
+      end
+
+      def projection_key = @projection_key
+
+      # Empty means "a chapter" — resolved HERE rather than as a default
+      # argument, because Behaviour::Chapter is not loaded yet when this
+      # file is.
+      def projection_declares = @projection_declares || []
+
+      def projection_emits = @projection_emits || :artifact
+
+      def projection_requires
+        req = @projection_requires
+        req.nil? || req.empty? ? [Bluebook::Behaviour::Chapter] : req
+      end
+    end
+  end
+end

data/lib/hecks/projector.rb

@@ -0,0 +1,186 @@
+module Hecks
+  # A named registry of "canonical IR in, external artifact out" tools —
+  # §30 of docs/HECKS_IMPLEMENTATION_PLAN.md. Before this existed, every
+  # such tool was its own thing with its own call shape: `Exporter`
+  # (registry-wide, consumed directly by bin/ir, bin/project_rust, and
+  # translation/audit's approval digest — untouched by this file, still
+  # exactly what those three read), and `RustProjection::Projector`
+  # (`rust/project.rb`, a whole separate Ruby program under a
+  # confusingly-identical module name) are the two that already exist.
+  # Neither is registered here — retrofitting either is real, separate
+  # work (Rust's generator is a whole second toolchain; a UL/OIDC
+  # projector doesn't exist yet at all) — but `:ir` is, as a genuine,
+  # working, golden-tested example of the shape every future projector
+  # (`:rust`, `:ul`, `:openid`, ...) is meant to follow.
+  #
+  # The unit is ONE bluebook's IR, not a whole booted registry — matching
+  # every real projection target (Rust/UL/OIDC all project one domain at
+  # a time), and deliberately narrower than `Exporter.call`'s own
+  # multi-domain shape.
+  # THREE KINDS OF "PROJECT", TOLD APART BY WHAT THEY NEED AS INPUT.
+  # Only the first belongs in this registry.
+  #
+  #   A PROJECTION takes a chapter's DECLARATION and answers something
+  #   that DESCRIBES the domain: its IR, its storage shape, an OIDC scope
+  #   manifest, the parser's keyword table, the reference pages. Inert,
+  #   derived, and runnable against any chapter that carries what it
+  #   declares it needs. These are what `register` holds.
+  #
+  #   AN EXPORT takes a declaration AND its BINDINGS and answers
+  #   something that IS the domain, running elsewhere — rust/project.rb's
+  #   generated crate, the WASM artifact, the SAM template
+  #   bin/project_deploy renders. It needs the `.world`/`.hecksagon` a
+  #   projection never looks at, because a running system has to know how
+  #   it is wired. That is the whole reason bin/project_deploy cannot use
+  #   this protocol: `call(bluebook:, options:)` has no channel for it.
+  #
+  #   A STATE PROJECTION takes RECORDS — a domain after dispatch — and is
+  #   a read-model question wearing the same word.
+  #   `bin/expression_projection` is the one of these: its operators are
+  #   not declared anywhere, they are what exists after
+  #   `Grammar.expression` replays expression_operators.json's ledger of
+  #   dispatches. Converting it into this registry would be a category
+  #   error, however much its name suggests otherwise.
+  #
+  # ONE WORD, THREE OTHER MEANINGS — worth naming too, because grepping
+  # "projection" turns all of these up and none is the above:
+  #
+  #   Ports::Projection    read-model catch-up, events folded into state
+  #   bin/project          forces that catch-up by hand
+  #   RustProjection       rust/project.rb's own separate toolchain
+  module Projector
+    class UnknownProjector < StandardError; end
+    # A chapter-scoped projector was handed something that is not a chapter.
+    class WrongConstruct < StandardError; end
+
+    module_function
+
+    # `projector` needs only to answer `call(bluebook:, options:)` — a
+    # module, a class with a class method, or any object responding to
+    # `call` all work. Re-registering a name replaces it outright,
+    # deliberately unguarded: a spec re-registering a stub under the same
+    # name between examples is the ordinary case, not a footgun to fence
+    # against.
+    def register(name, projector)
+      registry[name.to_sym] = projector
+    end
+
+    # `bluebook:` is kept as the keyword because it is the shipped
+    # spelling and every existing caller uses it — but what it accepts is
+    # any construct that emits IR, and `admits!` is what decides whether
+    # THIS target can actually take the one handed over.
+    def call(name, bluebook:, options: {})
+      projector = registry.fetch(name.to_sym) {
+        raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
+      }
+      admits!(name, projector, bluebook)
+      projector.call(bluebook: bluebook, options: options)
+    end
+
+    # A projection names the CAPABILITIES it needs; this refuses a
+    # construct that lacks one, before the projector runs.
+    #
+    # ONE CHECK COVERS BOTH SHAPES. An ordinary construct INCLUDES its
+    # capabilities and a class-shaped one — Command, Entity, ValueObject
+    # — EXTENDS them, and `is_a?` consults the singleton chain, so it
+    # answers for an extended module as readily as an included one. This
+    # started as two checks on the assumption it would not; a spec
+    # asserting the assumption failed, which is the only reason the
+    # redundant half was noticed.
+    def admits!(name, projector, construct)
+      needed = projector.respond_to?(:projection_requires) ? projector.projection_requires : []
+      missing = needed.reject { |capability| capable?(construct, capability) }
+      unless missing.empty?
+        raise WrongConstruct,
+              "#{name.inspect} needs #{missing.map(&:name).join(' and ')}, and was handed " \
+              "#{construct.class} (#{construct.respond_to?(:hecks_name) ? construct.hecks_name : construct.inspect})."
+      end
+
+      declared = projector.respond_to?(:projection_declares) ? projector.projection_declares : []
+      absent   = declared.reject { |named| construct.aggregate(named) }
+      return if absent.empty?
+
+      raise WrongConstruct,
+            "#{name.inspect} needs a chapter declaring #{absent.join(' and ')}; " \
+            "#{construct.name} declares no such aggregate."
+    end
+
+    def capable?(construct, capability) = construct.is_a?(capability)
+
+    # What KIND of artifact a registered target emits — asked of the
+    # projection rather than inferred from what it returned.
+    def emits_for(name)
+      projector = registry.fetch(name.to_sym) { return :artifact }
+      projector.respond_to?(:projection_emits) ? projector.projection_emits : :artifact
+    end
+
+    def registered?(name) = registry.key?(name.to_sym)
+    def registered = registry.keys
+
+    def registry
+      @registry ||= {}
+    end
+
+    # A target may be addressed by the constant that implements it
+    # (`Projections::OIDC`) or by the bare key it registered under
+    # (`:oidc`). Both resolve here, so the constant form is added
+    # surface rather than a replacement — every `Projector.call(:ir, ...)`
+    # written before this existed keeps working untouched.
+    def key_for(target)
+      return target.projection_key if target.respond_to?(:projection_key) && target.projection_key
+
+      target
+    end
+
+    # WRITING IS THE CALLER'S CHOICE, NOT THE PROJECTOR'S. A projector
+    # returns an artifact and never touches disk, which is what lets
+    # spec/projector_spec.rb compare `:ir`'s output against a golden
+    # fixture without a tmpdir. `out:` is the only thing that writes.
+    #
+    # `as:` comes from the projection's own `emits:` declaration rather
+    # than from inspecting the artifact. A Hash of path => contents and a
+    # Hash that simply happens to hold strings are the same object to
+    # Ruby; only the projection knows which it meant.
+    def write(artifact, out, as: :artifact)
+      return write_tree(artifact, out) if as == :files
+
+      File.write(out, artifact.is_a?(String) ? artifact : "#{JSON.pretty_generate(artifact)}\n")
+      out
+    end
+
+    # Answers the paths written, in the order given — so a caller can
+    # report what happened without re-deriving it from the tree.
+    def write_tree(files, directory)
+      require "fileutils"
+      files.map do |relative, contents|
+        path = File.join(directory, relative)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, contents)
+        path
+      end
+    end
+  end
+end
+
+require "json"
+
+require_relative "projector/exporter"
+require_relative "projector/ir_projector"
+require_relative "projector/target"
+# Neither of these requires this file back — they need `Naming` and nothing
+# else — so unlike a target they are safe to pull in from here.
+require_relative "projector/docs_projector"
+require_relative "projector/narrate_projector"
+require_relative "projector/cli_projector"
+
+Hecks::Projector.register(:ir, Hecks::Projector::IRProjector)
+Hecks::Projector.register(:docs, Hecks::Projector::DocsProjector)
+Hecks::Projector.register(:narrate, Hecks::Projector::NarrateProjector)
+Hecks::Projector.register(:cli, Hecks::Projector::CliProjector)
+
+# The TARGETS are required from lib/hecks.rb, immediately after this
+# file — deliberately not from here. A target requires this file (it
+# needs `Target` and the registry), so requiring them back from here
+# would close a genuine `circular require considered harmful` loop. Ruby
+# tolerates it; the warning is still right, and load order is the kind of
+# thing that only breaks once someone requires a target on its own.