hecks 2.8.0 → 3.0.0

data/lib/hecks/bluebook/value_object.rb

@@ -5,48 +5,25 @@ module Hecks
   module Bluebook
     Invariant = Struct.new(:description, :canonical, :predicate, :ast, keyword_init: true)
 
-    # A value object — a declaration holder, never instantiated.
-    #
-    # `ValueObjectBuilder` returns an anonymous subclass whose singleton
-    # carries the declaration : attributes, invariants, members. Nothing ever
-    # calls `.new` on one — coercion builds `Runtime::Value` wrappers, and
-    # invariants run as canonical text through the Evaluator. The runtime
-    # reaches a shape through `aggregate.value_object(name)`, the IR's own
-    # finder ; there is no constant nesting and no second index.
-    #
-    # `to_h` does not move. It is a byte-for-byte contract pinned by the
-    # golden fixtures, so it keeps spelling the short declared name, which
-    # is what `hecks_name` carries. Declarations in the graph, strings in the
-    # export.
+    # A value object: a declaration holder, never instantiated.
+    # `ValueObjectBuilder` returns a subclass carrying attributes, invariants and members;
+    # reach one through `aggregate.value_object(name)`.
+    # `to_h` spells the short declared name (`hecks_name`), a contract pinned by golden fixtures.
     class ValueObject
       extend Construct
-      # Extended, not included — this construct is a class, so its
-      # emission is a class method. See Hecks::IR's own note on
-      # the two shapes.
+      # Extended, not included: this construct is a class, so emission is a class method.
       extend Hecks::IR
       extend Behaviour::ValueObject
 
       emits_ir(
         name:       :hecks_name,
         attributes: many(:attributes),
-        # `ast:` — a JSON-serializable rendering of the same predicate
-        # `canonical` already spells as text, alongside it rather than
-        # replacing it (`canonical` stays the human-facing/doctest-facing
-        # form; parsing it back would just re-derive what `ast` already
-        # states directly). Ground truth and the full reasoning:
-        # `Expression::AstJson`'s own header — built for `rust/host`'s
-        # own mint-time invariant check (`reference_validate.rs`), which
-        # has no kernel crate to parse `canonical` with.
+        # `ast` sits beside `canonical` because rust/host's mint-time invariant check
+        # has no kernel crate to parse `canonical` with (see `Expression::AstJson`).
         invariants: -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         closed_set: :closed_set?,
-        # The field name is stringified, never the value. A `member` row can
-        # hold any of the scalar types an attribute declares — `Integer 84`
-        # (`StatementFrequency#retention_months`, statements.bluebook), not
-        # only `String` — and stringifying it on the way out would erase
-        # that: `84` and `"84"` (a member some other row might legitimately
-        # spell as text) would become indistinguishable once they reached
-        # `to_h`. The declared name still moves (`field.to_s`) — that half
-        # was never a Ruby object with a type to lose.
+        # Only the field name is stringified: a member value can be an Integer, and
+        # stringifying it would make `84` and `"84"` indistinguishable in `to_h`.
         members:    -> { members.map { |member| member.map { |field, value| [field.to_s, value] } } }
       )
 
@@ -57,10 +34,8 @@ module Hecks
         # the bluebook declares and the thing Ruby holds are one object.
         #
         # @param name [String, Symbol] the value object's declared type name
-        # @param attributes [Array<Bluebook::Attribute>] the value object's declared
-        #   fields
-        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every
-        #   instance of this value object
+        # @param attributes [Array<Bluebook::Attribute>] the value object's declared fields
+        # @param invariants [Array<Bluebook::Invariant>] the rules checked against every instance
         # @param members [Array<Hash{Symbol => Object}>] the declared `one_of` members, one
         #   row of field values per member
         # @param closed_set [Boolean] whether a `one_of` was declared, even with no

data/lib/hecks/bluebook.rb

@@ -1,36 +1,19 @@
-# Hecks::Bluebook
-#
-# Everything a .bluebook file becomes on its way to running: the expression
-# language (expression/), the model itself (the chapter class plus
-# everything it declares), the assembly that turns
-# declarations back into that graph (assembly.rb + assembly/), the authoring
-# DSL (dsl/), and the meta-validator that judges a chapter against the
-# language's own grammar (meta_validator.rb + meta_validator/).
-#
-# The require order below matters: expression and IR load first (pure
-# declarations), assembly's collaborators load before its face, and the DSL
-# loads before the meta-validator that its builders call at build time.
+# Everything a .bluebook file becomes on its way to running: expression language, model,
+# assembly, authoring DSL and meta-validator.
 
 module Hecks
-  # Declared as a class, not a module — `Hecks::Bluebook` is a
-  # chapter (bluebook/chapter.rb carries its body). Everything a chapter
-  # declares nests under it, as do the ways to build one (`DSL`) and to
-  # judge one (`MetaValidator`). Reopening this anywhere must say `class`.
+  # `Hecks::Bluebook` is a class defined in bluebook/chapter.rb; reopen it with `class`.
   module Bluebook
   end
 end
 
-# What the chapter's own files lean on at class-body level (`extend
-# Construct`, the assembly's QuerySpecification marks) — required here
-# because those files' contents are frozen and cannot say so themselves.
+# Required here because the chapter's frozen files lean on these at class-body level.
+# Load order: expression and IR first, assembly's collaborators before its face, DSL last.
 require_relative "construct"
 require_relative "literal"
 require_relative "query_specification"
 
 require_relative "bluebook/expression"
-# **The model itself** — the chapter class's own body first, then everything
-# a chapter declares. Order matters only for reading: each is a bag of
-# declarations with no load-time cross-references.
 require_relative "bluebook/chapter"
 require_relative "bluebook/reference"
 require_relative "bluebook/attribute"

data/lib/hecks/cache_dir.rb

@@ -3,30 +3,11 @@ require "fileutils"
 require "tmpdir"
 
 module Hecks
-  # The one place the runtime's own scratch files live, outside the gem.
+  # The one place the runtime's own scratch files live, outside the gem: an
+  # installed gem is read-only, and a checkout's `tmp/` isn't this library's to assume.
   #
-  # The syntax-boot cache and the Storehouse audit log are written on a
-  # normal run, so they cannot sit under the gem's own directory: an
-  # installed gem is read-only, and a checkout's `tmp/` is not a place a
-  # library gets to assume. Both ask this module for a subdirectory instead.
-  #
-  # ## Where the root is
-  #
-  # The first of these that can be made a private directory wins:
-  #
-  # 1. `$XDG_CACHE_HOME/hecks`, when `XDG_CACHE_HOME` is set to an absolute path
-  # 2. `~/.cache/hecks`
-  # 3. `<system temp dir>/hecks-<uid>`
-  #
-  # ## Private, or not used
-  #
-  # The syntax-boot cache is read back with `Marshal.load`, so a directory
-  # another account can write to is a way to run code as this one. A
-  # candidate is accepted only if it is owned by the current user and
-  # writable by nobody else; the shared temp directory in particular is
-  # where a predictable name can be planted by someone else. When no candidate
-  # qualifies, a fresh per-process directory stands in: the cache still
-  # works within the process and is never shared with a stranger.
+  # A candidate root is used only if it is private to the current user, since the
+  # syntax-boot cache it holds is read back with `Marshal.load`.
   module CacheDir
     module_function
 

data/lib/hecks/canonical_json.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  # A JSON document with every object's keys sorted. Key order is not semantics, so a diff a person
+  # reads should not have to notice it moved.
+  module CanonicalJson
+    module_function
+
+    # Sorts every Hash's keys within a parsed JSON document, recursively.
+    #
+    # @param node [Object] a value from `JSON.parse`: a `Hash`, an `Array`, or a JSON scalar
+    # @return [Object] the same shape with every nested `Hash`'s keys sorted by their string form
+    def sort_deep(node)
+      case node
+      when Hash then node.sort_by { |key, _| key.to_s }.to_h { |key, value| [key, sort_deep(value)] }
+      when Array then node.map { |item| sort_deep(item) }
+      else node
+      end
+    end
+
+    # @param text [String] a JSON document
+    # @return [String] the document pretty-printed with its keys in order
+    # @raise [JSON::ParserError] if the text is not JSON
+    def pretty(text)
+      JSON.pretty_generate(sort_deep(JSON.parse(text)))
+    end
+  end
+end

data/lib/hecks/chapters.rb

@@ -0,0 +1,102 @@
+require_relative "naming"
+require_relative "runtime/registry"
+require_relative "bluebook/meta_validator"
+
+module Hecks
+  # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
+  # declared in itself, Expression, Tenancy, Deploy and QualityControl. Framework members stay in
+  # `Framework`.
+  #
+  # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
+  # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
+  # its store: `<snake_name>.ports.hecksagon` (the ports it declares, as a `Hecks.hecksagon`
+  # block that merges into the attaching one) and `adapters/*.adapter` (the adapters binding them).
+  module Chapters
+    # Where attachable chapters live, relative to `lib/hecks/`.
+    GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
+               deploy/bluebook/*.bluebook quality_control/*.bluebook].freeze
+
+    # Every attachable chapter, by name, with the files that declare it.
+    #
+    # @return [Hash{String => Array<String>}] chapter name to its files' absolute paths, sorted
+    def self.index
+      @index ||= GLOBS.flat_map { |glob| Dir.glob(File.join(__dir__, glob)) }.sort
+                      .group_by { |path| chapter_name(path) }
+                      .reject { |name, _| name.nil? }
+                      .freeze
+    end
+
+    # Loads a chapter's files into the current registry, unless it already holds the chapter.
+    #
+    # The files load together inside `MetaValidator.defer`, so a chapter spread over several files
+    # is judged once, whole. The chapter's ports file and adapters load after it, since a port
+    # names the chapter's aggregates.
+    #
+    # @param name [String] the chapter's name, such as `"Deploy"`
+    # @return [Boolean, nil] true when this call loaded the chapter, nil when it was already held
+    # @raise [Runtime::WiringError] if no attachable chapter has that name
+    def self.load!(name)
+      paths = index.fetch(name.to_s) do
+        raise Runtime::WiringError,
+              "no attachable chapter named #{name.inspect} — known: #{index.keys.join(', ')}"
+      end
+      registry = Hecks.current_registry or
+        raise Runtime::WiringError, "attaches #{name.to_s.inspect} outside a boot: no registry is open"
+      return refuse_own_chapter(registry, name.to_s) if registry.bluebook(name.to_s)
+
+      load_atomically(registry, name.to_s, paths)
+      true
+    end
+
+    # Loads a chapter whole or not at all: a raise anywhere leaves the registry as it was, so a
+    # retry loads the chapter again instead of finding a half-built one already held.
+    def self.load_atomically(registry, name, paths)
+      queued = Bluebook::MetaValidator.deferred_chapters.dup
+      ports    = registry.ports.keys
+      adapters = registry.adapters.keys
+      Bluebook::MetaValidator.defer { paths.each { |path| Kernel.load(path) } }
+      Bluebook::MetaValidator.judge_deferred!(registry)
+      load_wiring(name, paths)
+    rescue Exception # rubocop:disable Lint/RescueException -- rolls back, then re-raises
+      registry.forget_chapter(name)
+      Bluebook::MetaValidator.deferred_chapters.replace(queued)
+      registry.ports.delete_if { |key, _| !ports.include?(key) }
+      registry.adapters.delete_if { |key, _| !adapters.include?(key) }
+      raise
+    end
+    private_class_method :load_atomically
+
+    # Returns nil for a chapter this gem already loaded; raises for a chapter of the same name
+    # that a user's own file declared, which `attaches` would otherwise silently take for the
+    # gem's.
+    def self.refuse_own_chapter(registry, name)
+      foreign = Array(registry.bluebook_sources[name]).compact
+                                                      .reject { |path| File.expand_path(path).start_with?("#{__dir__}/") }
+      return if foreign.empty?
+
+      raise Runtime::WiringError,
+            "attaches #{name.inspect}, but a chapter named #{name.inspect} is already declared in " \
+            "#{foreign.join(', ')} — rename it, since the gem's own #{name} chapter cannot merge into it"
+    end
+    private_class_method :refuse_own_chapter
+
+    # Loads what a chapter ships beside its bluebook: its ports file, then its adapters.
+    #
+    # @param name [String] the chapter's name
+    # @param paths [Array<String>] the chapter's bluebook files
+    # @return [void]
+    def self.load_wiring(name, paths)
+      directory = File.dirname(paths.first)
+      ports     = File.join(directory, "#{Naming.snake(name)}.ports.hecksagon")
+      Kernel.load(ports) if File.file?(ports)
+      Dir.glob(File.join(directory, "adapters", "*.adapter")).each { |adapter| Kernel.load(adapter) }
+    end
+    private_class_method :load_wiring
+
+    # The name a file's `Hecks.bluebook "Name"` header declares, or nil for a file without one.
+    def self.chapter_name(path)
+      File.foreach(path) { |line| return Regexp.last_match(1) if line =~ /\A\s*Hecks\.bluebook\s+"([^"]+)"/ }
+      nil
+    end
+  end
+end

data/lib/hecks/cli/behaviors.rb

@@ -0,0 +1,61 @@
+require_relative "../../hecks"
+require_relative "../behaviors"
+
+module Hecks
+  module CLI
+    # The command behind `hecks run_behaviors` and Custodian's `Operation.RunBehaviors`: runs
+    # `.behaviors` files and reports pass, fail or error per test (docs/guides/behaviors.md).
+    module Behaviors
+      module_function
+
+      # Runs one `.behaviors` file, or every one under a directory, and exits with the verdict.
+      #
+      # @param argv [Array<String>] the file or directory to run
+      # @param program [String] the name the usage message calls this command by
+      # @return [void]
+      # @raise [SystemExit] always: 0 when every test passed, 1 when any failed, errored or did
+      #   not parse, or when a directory holds no `.behaviors` file
+      def call(argv, program:)
+        target = argv.first or abort "usage: #{program} <file.behaviors | directory>"
+        abort "no such file or directory: #{target}" unless File.exist?(target)
+
+        if File.directory?(target)
+          sweep = Hecks::Behaviors.run_all(target)
+          abort "no .behaviors files under #{target}" if sweep.files_swept.zero?
+
+          sweep.files.each { |file| report_file(file) }
+          summary = sweep.summary
+          puts
+          puts "#{sweep.files_swept} file(s) swept — #{summary[:total]} test(s): " \
+               "#{summary[:passed]} passed, #{summary[:failed]} failed, #{summary[:errored]} errored, " \
+               "#{summary[:parse_errors]} file(s) failed to parse"
+        else
+          result = Hecks::Behaviors.run(target)
+          report_file(result)
+          summary = Hecks::Behaviors.summarize([result])
+        end
+        exit(bad?(summary) ? 1 : 0)
+      end
+
+      # @api private
+      def report_file(result)
+        puts result.path
+        if result.parse_error
+          puts "  PARSE ERROR — #{result.parse_error}"
+          return
+        end
+
+        result.runs.each do |run|
+          marker = { pass: "ok", fail: "FAIL", error: "ERROR" }.fetch(run.status)
+          puts "  #{marker.ljust(5)} #{run.description}"
+          puts "        #{run.message}" if run.message
+        end
+      end
+
+      # @api private
+      def bad?(summary)
+        ((summary[:failed] || 0) + (summary[:errored] || 0) + (summary[:parse_errors] || 0)).positive?
+      end
+    end
+  end
+end

data/lib/hecks/cli/canonicalise.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../canonical_json"
+
+module Hecks
+  module CLI
+    # The command behind `hecks canonicalise`: prints a JSON document with every object's keys
+    # sorted, recursively. Key order is not semantics, so a diff a person reads should not have
+    # to notice it moved.
+    module Canonicalise
+      module_function
+
+      # Prints the document at the path in `argv`, canonicalised.
+      #
+      # @param argv [Array<String>] the path of the JSON file, first
+      # @param out [IO] where the document goes
+      # @return [Integer] the exit status, always 0
+      # @raise [IndexError] when no path is given
+      def call(argv, out: $stdout)
+        out.puts Hecks::CanonicalJson.pretty(File.read(argv.fetch(0)))
+        0
+      end
+    end
+  end
+end

data/lib/hecks/cli/check_engine_agreement.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks"
+require_relative "../engine_agreement"
+
+module Hecks
+  module CLI
+    # The command behind `hecks check_engine_agreement`: fails when a query engine re-grows its
+    # own comparator dispatch, or when a declared comparator lacks a shared `Comparison` case or
+    # a cross-engine agreement spec. Grep-based.
+    module CheckEngineAgreement
+      module_function
+
+      # Checks the tree and prints the verdict.
+      #
+      # @param root [String] the repository root to check
+      # @param out [IO] where a clean verdict goes
+      # @param err [IO] where the problems go
+      # @return [Integer] 0 when clean, 1 with problems
+      def call(root:, out: $stdout, err: $stderr)
+        finding = Hecks::EngineAgreement.check(root: root)
+        if finding.problems.empty?
+          out.puts Hecks::EngineAgreement.clean_line(finding)
+          return 0
+        end
+
+        err.puts Hecks::EngineAgreement.problem_lines(finding)
+        1
+      end
+    end
+  end
+end

data/lib/hecks/cli/check_era.rb

@@ -0,0 +1,88 @@
+require_relative "../ports/persistence/plugins/era/expected_era"
+
+module Hecks
+  module CLI
+    # The command behind `hecks check_era` and Custodian's `Host.CheckEra`: asks a running host
+    # which era it reports and compares it with an allow-list file. Read-only: one GET, no writes.
+    module CheckEra
+      USAGE = "usage: hecks check_era <url> <expected-era-file> [--timeout=<seconds>]".freeze
+
+      # What a check found.
+      #
+      # @!attribute [r] verdict
+      #   @return [Runtime::EraCheck::ExpectedEra::Verdict] the era compared with the list
+      # @!attribute [r] version
+      #   @return [String] the gem version the host reports, empty when it reports none
+      # @!attribute [r] line
+      #   @return [String] the sentence `hecks check_era` prints for this finding
+      Finding = Struct.new(:verdict, :version, :line)
+
+      module_function
+
+      # Fetches the host's `/version` and compares its era with the allow-list file.
+      #
+      # @param url [String] the host's base URL, or its `/version` URL
+      # @param file [String] path of the allow-list file
+      # @param timeout [Numeric] seconds allowed for connecting and for reading
+      # @return [Finding] the comparison, whether or not the era is listed
+      # @raise [Errno::ENOENT, Errno::EACCES] if the file cannot be read
+      # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
+      # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
+      def assess(url, file, timeout: 10)
+        expected = Runtime::EraCheck::ExpectedEra
+        allowed  = expected.parse(File.read(file))
+        document = expected.fetch_version(url, timeout: timeout)
+        verdict  = expected.verdict(document.fetch("era"), allowed)
+        Finding.new(verdict, document.fetch("version"), sentence(verdict, file))
+      end
+
+      # Runs `hecks check_era`: prints the finding and answers the exit status.
+      #
+      # @param argv [Array<String>] the url, the allow-list file and an optional `--timeout=N`
+      # @param out [IO] where a finding goes
+      # @param err [IO] where a refusal goes
+      # @return [Integer] 0 when the era is expected or unlisted, 1 on a mismatch, 2 on bad
+      #   usage or an unreadable file, 3 when the host cannot be reached or answers no era
+      def run(argv, out: $stdout, err: $stderr)
+        timeout = 10
+        args = argv.reject do |arg|
+          next false unless arg.start_with?("--timeout=")
+
+          timeout = arg.delete_prefix("--timeout=").to_f
+          true
+        end
+        url, file = args
+        return usage(err) unless url && file && args.size == 2 && timeout.positive?
+
+        finding = assess(url, file, timeout: timeout)
+        (finding.verdict.ok? ? out : err).puts(finding.line)
+        finding.verdict.ok? ? 0 : 1
+      rescue Errno::ENOENT, Errno::EACCES => e
+        err.puts("cannot read #{file}: #{e.message}")
+        2
+      rescue Runtime::EraCheck::ExpectedEra::Unreachable, Runtime::EraCheck::ExpectedEra::BadResponse => e
+        err.puts("era check failed: #{e.message}")
+        3
+      end
+
+      # @param verdict [Runtime::EraCheck::ExpectedEra::Verdict] the comparison
+      # @param file [String] the allow-list file, named in the sentence
+      # @return [String] the one line that says what the comparison found
+      def sentence(verdict, file)
+        case verdict.status
+        when :match
+          "era #{verdict.era} is expected (#{verdict.allowed.join(', ')})"
+        when :unlisted
+          "host reports era #{verdict.era}; #{file} lists no era, so nothing was compared"
+        else
+          "host reports era #{verdict.era}, which is not in #{file} (expected: #{verdict.allowed.join(', ')})"
+        end
+      end
+
+      def usage(err)
+        err.puts(USAGE)
+        2
+      end
+    end
+  end
+end

data/lib/hecks/cli/console.rb

@@ -0,0 +1,66 @@
+require_relative "../../hecks"
+require "irb"
+# The era/lineage subsystem is a persistence plugin core does not require by default (ADR 0033);
+# a domain passed to the console may bind it.
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `hecks console` and Custodian's `Operation.OpenConsole`: boots a domain
+    # (pizzas on Memory by default) and drops into IRB with its door installed, for dispatching a
+    # real command by hand. No argument needs no database (ADR 0073); a domain directory boots as
+    # it is wired, which may bind PostgresEra.
+    module Console
+      PIZZAS = File.expand_path("../../../examples/pizzas", __dir__)
+
+      DEFAULT_FILES = [
+        File.join(PIZZAS, "bluebook/pizzas.bluebook"),
+        File.join(PIZZAS, "pizzas_behaviors.hecksagon")
+      ].freeze
+
+      module_function
+
+      # Boots the domain, prints what it declares, and starts IRB; returns when the session ends.
+      #
+      # @param domain [String, nil] a domain directory; the bundled pizzas domain when nil
+      # @param launcher [#call] starts the interactive session; IRB unless a caller stands in
+      # @return [Runtime] the runtime the session ran against
+      def call(domain = nil, launcher: -> { IRB.start(__FILE__) })
+        runtime = domain ? Hecks.boot(domain) : Hecks.boot_files(DEFAULT_FILES)
+        puts overview(runtime)
+        puts banner
+        launcher.call
+        runtime
+      end
+
+      # @param runtime [Runtime] a booted domain
+      # @return [String] each chapter's vision and its aggregates' commands
+      def overview(runtime)
+        runtime.registry.bluebooks.each_value.map do |bluebook|
+          aggregates = bluebook.aggregates.map do |aggregate|
+            commands = aggregate.commands.map { |command| "#{Naming.snake(command.hecks_name)}!" }.sort.join(", ")
+            "    #{aggregate.name}: #{commands}"
+          end
+
+          "\n    #{bluebook.name} — #{bluebook.vision}\n#{aggregates.join("\n")}\n"
+        end.join
+      end
+
+      # @return [String] the version and a first session to try against the pizzas domain
+      def banner
+        <<~BANNER
+
+          hecks #{Hecks::VERSION}
+
+          try:
+            order = Order.create_pizza!(name: { value: "Margherita" }, pizza: { price_cents: { cents: 1200 }, size: { value: "large" } })
+            order.add_topping!(topping: { value: "Basil" }, amount: { value: 3 })
+            order.purchase!(customer_name: { value: "Chris" }, amount: { cents: 1200 })
+            order.status
+            order.events.last
+
+        BANNER
+      end
+    end
+  end
+end

data/lib/hecks/cli/deploy_template_diff.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../projections/deploy/template_diff"
+
+module Hecks
+  module CLI
+    # The command behind `hecks deploy diff` and `hecks deploy diff`: compares two
+    # CloudFormation templates offline and reports differences by logical id; `--strict` also
+    # counts cosmetic differences (comments, key order).
+    module DeployTemplateDiff
+      module_function
+
+      # Prints the comparison and answers the exit status.
+      #
+      # @param argv [Array<String>] `<before.yaml> <after.yaml> [--json] [--strict]`
+      # @param program [String] the name the usage message calls this command by
+      # @return [Integer] 0 when the templates match, 1 when they differ, 2 for bad input
+      # @raise [SystemExit] when there are not exactly two templates
+      def call(argv, program: "hecks deploy diff")
+        options = { json: false, strict: false }
+        parser = OptionParser.new do |opts|
+          opts.banner = "usage: #{program} <before.yaml> <after.yaml> [--json] [--strict]"
+          opts.on("--json", "write the report as JSON") { options[:json] = true }
+          opts.on("--strict", "count cosmetic differences too") { options[:strict] = true }
+        end
+        files = parser.parse(argv)
+        abort parser.banner unless files.size == 2
+
+        diff = Hecks::Projections::Deploy::TemplateDiff
+        report = diff.diff_files(files[0], files[1], strict: options[:strict])
+        puts(options[:json] ? diff.render_json(report) : diff.render(report))
+        report.different? ? 1 : 0
+      rescue ArgumentError => e
+        warn e.message
+        2
+      end
+    end
+  end
+end

data/lib/hecks/cli/doc_coverage.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../../hecks"
+require_relative "../doc/reference"
+
+module Hecks
+  module CLI
+    # The command behind `hecks measure_doc_coverage`: refuses unless every live word in
+    # `docs/implemented/reference/` has prose and a running example. It checks that an example
+    # exists; `spec/reference_doctest_spec.rb` checks that it passes. `ruby skip` fences and
+    # hidden `<!-- doctest:boot -->` blocks do not count as examples.
+    module DocCoverage
+      module_function
+
+      # Prints the coverage report.
+      #
+      # @param root [String] the repository root
+      # @param out [IO] where the report goes
+      # @param err [IO] where the refusal goes
+      # @return [Integer] 0 when every word is covered, 1 otherwise
+      def call(root:, out: $stdout, err: $stderr)
+        clean, report = Hecks::Doc::Reference.coverage_report(File.join(root, "docs/implemented/reference"))
+        out.puts report
+        return 0 if clean
+
+        err.puts "docs/implemented/reference/ is behind the language. " \
+                 "Regenerate with hecks project_reference to see the words in place."
+        1
+      end
+    end
+  end
+end