hecks 2.8.0 → 2.9.0

data/lib/hecks/cli/project_cli.rb

@@ -7,33 +7,17 @@ module Hecks
     # command-line launcher beside each domain, named after its bluebook, so
     # `Hecks.bluebook "QualityControl"` in `qa/` becomes `qa/quality_control`.
     #
-    # ## A launcher, not a CLI
-    #
-    # Each file is a dozen lines pinning one directory and handing over to
-    # `Facade::CliRunner`. The surface still comes from `Projector.call(:cli, …)` at
-    # the moment it runs, so editing a chapter changes the launcher's behaviour
-    # without regenerating anything. Re-run this when a domain is added or renamed.
-    #
-    # ## Beside the domain
-    #
-    # A domain's command line lives with the domain, so a folder is the whole unit.
-    # The launcher boots `__dir__`, and reaches `lib` by counting how deep the domain
-    # sits below the root, so no line knows where the checkout was cloned.
+    # Each launcher is a dozen lines pinning one directory and handing over to
+    # `Facade::CliRunner`; the surface itself is projected at the moment it runs,
+    # so editing a chapter changes behaviour without regenerating anything.
     module ProjectCli
       # Build output and other trees under a root that hold no domain a caller means.
       IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
 
       module_function
 
-      # Writes a launcher for each domain `argv` names, or for every domain under
-      # `root`.
-      #
-      # @param argv [Array<String>] domain paths relative to `root`; empty for all of them
-      # @param program [String] the name the generated header credits
-      # @param root [String] the directory domains are found under and paths resolve against
-      # @param remove_stale_bin [Boolean] whether to delete `root/bin/<name>`, where a
-      #   launcher for the same chapter would otherwise linger as a second front door
-      # @return [void]
+      # `remove_stale_bin` deletes `root/bin/<name>`, where a launcher for the same
+      # chapter would otherwise linger as a second front door.
       def call(argv, program:, root:, remove_stale_bin: true)
         wanted = argv.empty? ? domains(root) : argv.map { |path| path.delete_prefix("#{root}/").chomp("/") }
 
@@ -50,11 +34,6 @@ module Hecks
         end
       end
 
-      # Finds every domain under `root` a launcher can be written for.
-      #
-      # @param root [String] the directory to search under
-      # @return [Array<String>] domain directory paths relative to `root`,
-      #   deduplicated and sorted
       def domains(root)
         folder = Adapters::Folder.new
         Dir.glob(File.join(root, "**/*.hecksagon"))
@@ -65,14 +44,8 @@ module Hecks
            .uniq.sort
       end
 
-      # Boots the domain to read its declared name, which comes from
-      # `Hecks.bluebook "…"` rather than the directory, so a domain renamed with
-      # `formerly_known_as` gets a launcher under its new name.
-      #
-      # @param root [String] the directory `path` is relative to
-      # @param path [String] a domain directory path
-      # @return [String, nil] the domain's declared bluebook name, or nil after warning
-      #   when it fails to boot
+      # Reads the name from `Hecks.bluebook "…"` rather than the directory, so a
+      # domain using `formerly_known_as` gets a launcher under its current name.
       def bluebook_name(root, path)
         Hecks.boot(File.join(root, path), install_facade: false).registry.bluebooks.keys.first
       rescue StandardError => e
@@ -80,12 +53,6 @@ module Hecks
         nil
       end
 
-      # Renders one domain's launcher.
-      #
-      # @param path [String] the domain directory path, relative to the root
-      # @param name [String] the domain's declared bluebook name
-      # @param program [String] the name the generated header credits
-      # @return [String] the launcher script's full source
       def launcher(path, name, program)
         snake = Naming.snake(name)
         up    = "../" * path.count("/").succ

data/lib/hecks/cli/project_diagrams.rb

@@ -9,13 +9,6 @@ module Hecks
     module ProjectDiagrams
       module_function
 
-      # Projects and writes one chapter's diagrams, then lists what was written.
-      #
-      # @param argv [Array<String>] the domain path, then the chapter name
-      # @param program [String] the name the usage message calls this command by
-      # @param root [String] the directory `docs/generated/diagrams/` is written under
-      # @return [void]
-      # @raise [SystemExit] when either argument is missing
       def call(argv, program:, root:)
         usage = "usage: #{program} <domain-path> <ChapterName>"
         domain_path  = argv[0] or abort usage

data/lib/hecks/cli/run.rb

@@ -10,20 +10,12 @@ module Hecks
     # command line, or executes a JSON step list and reports instances, events,
     # refusals, reactions, sagas and query rows.
     #
-    # ## Two forms, one argument
-    #
-    # `run bug.discover reference=BUG#1 severity=high …` needs no JSON. The verb
-    # tree, every argument, its declared type and every way the verb can refuse are
-    # projected out of the bluebook (`Projector::CliProjector`) and run by
-    # `Facade::CliRunner`, so this knows nothing about any domain and its help
-    # cannot go stale. The step-list form takes a script path, `-` for stdin, or the
-    # JSON itself, which is how the corpus scripts under `spec/corpus/` are run.
-    #
-    # ## Standing in a domain is enough
-    #
-    # `Adapters::Folder#domain_root` walks up for the nearest `.hecksagon`, so inside
-    # a domain the path can be left off. The first argument is a domain only when it
-    # is a directory.
+    # `run bug.discover reference=BUG#1 severity=high …` needs no JSON; the verb
+    # tree and its arguments are projected from the bluebook, so this knows nothing
+    # about any domain and its help cannot go stale. The step-list form takes a
+    # script path, `-` for stdin, or the JSON itself. The first argument is a
+    # domain only when it is a directory; otherwise the nearest enclosing one is
+    # used.
     module Run
       module_function
 
@@ -59,19 +51,9 @@ module Hecks
         abort unmet.join("\n") unless unmet.empty?
       end
 
-      # Boots `domain` and dispatches `argv` as a projected verb invocation, printing
-      # the result and exiting the process.
-      #
-      # **No fall-through**. This is reached only when the argument is not
-      # script-shaped, so a near miss deserves the runner's "did you mean" rather
-      # than the step-list form's "no such script".
-      #
-      # @param domain [String] the domain's directory path
-      # @param argv [Array<String>] the arguments after the domain, e.g.
-      #   `["bug.discover", "reference=BUG#1"]`
-      # @param program [String] the name the runner's help calls this command by
-      # @return [void]
-      # @raise [SystemExit] always
+      # No fall-through: reached only when the argument is not script-shaped, so a
+      # near miss deserves the runner's "did you mean" rather than the step-list
+      # form's "no such script".
       def cli_form(domain, argv, program)
         runtime = Hecks.boot(domain, install_facade: false)
         text, status = Facade::CliRunner.call(runtime: runtime, argv: argv, program: program)
@@ -79,20 +61,10 @@ module Hecks
         exit 0
       end
 
-      # Says whether `arg` is a step list rather than a verb: stdin, inline JSON, or
-      # a file that exists.
-      #
-      # @param arg [String] the first argument after the domain
-      # @return [Boolean] true when `arg` is script-shaped
       def script_shaped?(arg) = arg == "-" || arg.match?(/\A\s*\{/) || File.file?(arg)
 
-      # Reads the step list from stdin, from the argument itself, or from a file,
-      # decided by looking, because a script beginning with `{` is not a filename
+      # Decided by looking, because a script beginning with `{` is not a filename
       # anybody meant.
-      #
-      # @param script [String] `-`, inline JSON, or a file path
-      # @return [String] the script's JSON text
-      # @raise [SystemExit] when `script` names no file
       def read_source(script)
         case script
         when "-" then $stdin.read
@@ -102,25 +74,14 @@ module Hecks
         end
       end
 
-      # Parses the step list before anything boots, because booting opens a real
-      # store and a typo in the JSON should cost a sentence, not a connection.
-      #
-      # @param source [String] the script's JSON text
-      # @return [Hash{String => Object}] the parsed script
-      # @raise [SystemExit] when `source` is not JSON
+      # Parsed before anything boots, because booting opens a real store and a typo
+      # in the JSON should cost a sentence, not a connection.
       def parse(source)
         JSON.parse(source)
       rescue JSON::ParserError => e
         abort "that is not JSON: #{e.message.lines.first.strip}"
       end
 
-      # Runs every step and gathers what the runtime holds afterwards.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @param steps [Array<Hash{String => Object}>] the script's steps, each a
-      #   `"verb"` or a `"query"` with optional `"args"`
-      # @return [Hash{Symbol => Object}] `:instances`, `:events`, `:refusals`,
-      #   `:reactions`, `:sagas` and `:queries`, in the order they are printed
       def execute(runtime, steps)
         refusals = []
         queries = []
@@ -171,13 +132,6 @@ module Hecks
         end
       end
 
-      # Checks the script's `"expectations"` against what the run produced.
-      #
-      # @param expectations [Hash{String => Object}] the script's `"event_names"`,
-      #   `"refusals"` and `"instances"` expectations; `{}` when it declares none
-      # @param report [Hash{Symbol => Object}] what `execute` answered
-      # @return [Array<String>] one message per unmet expectation; empty when every
-      #   one held
       def unmet_expectations(expectations, report)
         missing_events = Array(expectations["event_names"]) - report[:events].map { |event| event[:name] }
         unmet = []

data/lib/hecks/cli/smoke_test.rb

@@ -7,22 +7,12 @@ module Hecks
     # and dispatches one synthesized call per declared command and report
     # (`Bluebook::SmokeTest`), printing every failure rather than the first.
     #
-    # It needs a real `.hecksagon`: a bare `.bluebook` with nothing bound to an
-    # adapter has nothing to run commands against. A failure may be a domain bug or
-    # a value the synthesizer's naive choices (0, an empty list, "smoke-test") cannot
-    # satisfy; the message underneath says which. Smoke-testing proves nothing
+    # Needs a real `.hecksagon`; a failure may be a domain bug or a value the
+    # synthesizer's naive choices cannot satisfy — smoke-testing proves nothing
     # crashes, not that an answer is right.
     module SmokeTest
       module_function
 
-      # Smoke-tests the domain `argv` names, or every wired domain under
-      # `root/examples/`, and exits with the verdict.
-      #
-      # @param argv [Array<String>] an optional domain directory
-      # @param root [String] the directory whose `examples/*` are tested when `argv`
-      #   names no domain
-      # @return [void]
-      # @raise [SystemExit] always: 0 when clean, 1 with failures or no domain found
       def call(argv, root:)
         dir_arg = argv.first
         targets = dir_arg ? [dir_arg] : Dir.glob("#{root}/examples/*/").map { |d| d.chomp("/") }.select { |d| wired?(d) }
@@ -35,10 +25,6 @@ module Hecks
         exit(ok ? 0 : 1)
       end
 
-      # Says whether `dir`, or something nested under it, is a bindable domain.
-      #
-      # @param dir [String] a directory to check
-      # @return [Boolean] true if `dir` contains at least one `.hecksagon` file
       def wired?(dir) = !Dir.glob(File.join(dir, "**/*.hecksagon")).empty?
 
       # @api private

data/lib/hecks/cli/stores.rb

@@ -4,8 +4,7 @@ require_relative "../../hecks"
 module Hecks
   module CLI
     # The command behind `bin/stores` and `hecks stores`: every aggregate's current
-    # records as JSON, the head rather than the journal (`bin/history` prints the
-    # full write history).
+    # records as JSON (the head, not the journal — see `bin/history` for that).
     module Stores
       module_function
 

data/lib/hecks/cli.rb

@@ -1,27 +1,9 @@
 module Hecks
   # The `hecks` command an installed gem puts on the path: one router over the
-  # domain-operator tools, each of which also runs from a checkout as `bin/<name>`.
+  # domain-operator tools, each also runnable from a checkout as `bin/<name>`.
   #
-  # ## A router, not a second copy
-  #
-  # Every subcommand's logic lives in `lib/hecks/cli/`, and the matching `bin/`
-  # script is a thin wrapper over the same entry point, so `hecks run` and
-  # `bin/run` cannot drift apart. The domain-scoped verbs go through
-  # `Facade::CliRunner`, the same way `bin/run` does.
-  #
-  # ## What a checkout has and an install does not
-  #
-  # The `bin/` wrappers pass the repository root, which is where they look for
-  # `examples/`, `rust/` and `docs/generated/`. Here the root is the working
-  # directory, so a command that lists or writes files does it where the caller
-  # stands. `model_check` with no domain sweeps the repository's corpus, which an
-  # install does not carry, so here it needs at least one domain path.
-  #
-  # ## Loading
-  #
-  # Nothing here requires the framework. A subcommand loads it when it runs, and
-  # `mcp` checks its transport before anything else loads, as
-  # `McpStdioGuard.enforce_stdio!` requires.
+  # Every subcommand's logic lives under `cli/`, with `bin/<name>` a thin wrapper
+  # over the same entry point, so the two can't drift apart.
   #
   # See `docs/decisions/0066-the-gem-ships-a-hecks-executable-and-dev-tooling-stays-in-the-repo.md`.
   module CLI
@@ -74,6 +56,18 @@ module Hecks
 
     HELP_FLAGS = ["--help", "-h"].freeze
 
+    # Printed above the usage line by `overview`, on every path that reaches it
+    # (a bare `hecks`, `hecks --help`, and an unknown subcommand alike).
+    HERO = <<~BANNER.freeze
+      #   #  #####   ####  #  #    ####
+      #   #  #      #      # #    #
+      #####  ####   #      ##      ###
+      #   #  #      #      # #        #
+      #   #  #####   ####  #  #   ####
+
+          It's all about the specs
+    BANNER
+
     # Exit status for a missing or unknown subcommand.
     USAGE_STATUS = 2
 
@@ -81,9 +75,8 @@ module Hecks
 
     # Routes `argv` to its subcommand and runs it.
     #
-    # A subcommand followed by only `--help` or `-h` prints that subcommand's usage
-    # without running it; any other arguments pass through untouched, so
-    # `hecks run order.place --help` still reaches the verb's own help.
+    # A subcommand followed only by `--help`/`-h` prints its usage without
+    # running it; other arguments still reach the verb itself.
     #
     # @param argv [Array<String>] the command line, subcommand first
     # @param out [#puts] where help goes
@@ -148,6 +141,7 @@ module Hecks
 
     # @api private
     def overview(io)
+      io.puts HERO
       io.puts "usage: hecks <command> [arguments]"
       io.puts ""
       width = COMMANDS.keys.map(&:length).max

data/lib/hecks/construct.rb

@@ -1,29 +1,12 @@
 module Hecks
-  # The invisible field a built construct carries.
+  # The invisible identity a built construct carries: an owner chain under `hecks_`-prefixed
+  # fields, not an attribute and not a key in `to_h`.
   #
-  # ## Identity
+  # The fully-qualified name walks owners and matches the id `MetaValidator::Judge#identify` mints.
   #
-  # A construct is a record with an owner chain — the chapter (Bluebook)
-  # owns its aggregates, an aggregate owns everything declared on it — and the
-  # bluebook identity is carried in its own field, under a `hecks_` prefix that
-  # no domain attribute can collide with. Invisible means exactly that: not an
-  # attribute, not a key in `to_h`, not a reader on instances. Framework
-  # metadata about the construct, not part of the domain it describes.
-  #
-  # The identity is computed by walking owners rather than stamped, so nothing
-  # has to be re-stamped when a chapter is assembled after its aggregates:
-  #
-  #     Pizzas                     the chapter — no owner
+  #     Pizzas                     the chapter, no owner
   #     Pizzas::Pizza              an aggregate joins its chapter with ::
   #     Pizzas::Pizza.Price        everything else joins its owner with .
-  #
-  # That spelling is not invented here. It is the id `MetaValidator::Judge`
-  # already mints in `#identify`, so a construct and the meta-domain's
-  # record of that construct carry the same identity, and there is no
-  # translation table between them to be quietly wrong in.
-  #
-  # ## Usage
-  #
   #     price = Class.new(ValueObject)   # a declaration holder
   #     price.hecks_name  = "Price"
   #     price.hecks_owner = pizza_ir         # the Aggregate that declares it
@@ -32,15 +15,12 @@ module Hecks
     # A construct asked for an identity it cannot compute.
     class Unowned < StandardError; end
 
-    # What declares this one — the chapter above an aggregate, the aggregate
-    # above a value object. nil for a chapter, which is the top.
+    # What declares this construct; nil for a chapter, which is the top.
     attr_accessor :hecks_owner
 
     attr_writer :hecks_name
 
-    # A chapter is the only construct that legitimately has no owner. Everything
-    # else is declared in something, so a missing owner is an unstamped construct
-    # rather than a top — see hecks_fqn.
+    # Marks a chapter, the only construct that legitimately has no owner.
     attr_writer :hecks_root
 
     # Whether this construct is the top of its own owner chain.
@@ -53,18 +33,12 @@ module Hecks
     # @return [String] the construct's own name, without any owner prefix
     def hecks_name = @hecks_name
 
-    # How this construct joins its owner. An aggregate is a member of its
-    # chapter's namespace (`::`) ; everything else is declared on its owner
-    # (`.`). Overridden by Aggregate, defaulted here for every other construct.
+    # How this construct joins its owner: `::` for an aggregate, `.` for everything else.
     #
     # @return [String] `"."`, the separator this construct uses in `hecks_fqn`
     def hecks_separator = "."
 
-    # Refuses rather than guesses. A construct with no owner and no claim to be a
-    # chapter has simply not been stamped yet — entity commands are in that state
-    # while entities are still IR objects — and answering the bare name would be a
-    # plausible half-truth that no test would notice. That shape of falsehood is
-    # what this repo keeps finding, so it goes red instead.
+    # Refuses rather than answering a bare name for an unstamped construct.
     #
     # @return [String] the fully-qualified name, joining every owner from the
     #   chapter down to this construct