hecks 3.5.0 → 3.7.0

data/lib/hecks/bluebook/smoke_test.rb

@@ -11,6 +11,10 @@ module Hecks
         def to_s = "#{domain}::#{aggregate}.#{command}: #{error}"
       end
 
+      # One smoke run: what is being dispatched through, which ids earlier commands minted, and
+      # the failures collected so far.
+      Run = Struct.new(:dispatcher, :domain, :chapter, :created, :failures)
+
       module_function
 
       # Boots an isolated copy of `dir` on Memory bindings, so real stores are never touched.
@@ -46,7 +50,6 @@ module Hecks
       end
 
       # Walks aggregates in declaration order so later ones can reference earlier `created` ids.
-      # rubocop:disable-next Metrics/AbcSize
       #
       # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the
       #   booted dispatcher to dispatch synthesized commands and queries through
@@ -59,45 +62,57 @@ module Hecks
         chapter = dispatcher.registry.bluebook(domain)
         return [] unless chapter
 
-        created  = {}
-        failures = []
-
-        chapter.aggregates.each do |aggregate|
-          creating, noncreating = aggregate.commands.partition(&:creates?)
-
-          creating.each do |command|
-            args = Synthesizer.args_for(chapter, aggregate, command, created)
-            begin
-              result = dispatcher.dispatch_flat("#{domain}::#{aggregate.name}.#{command.hecks_name}", args)
-              created[aggregate.name] = result.instance.id
-            rescue StandardError => e
-              failures << Failure.new(domain: domain, aggregate: aggregate.name, command: command.hecks_name,
-                                      error: "#{e.class}: #{e.message}")
-              next
-            end
-
-            noncreating.each do |nc_command|
-              nc_args = Synthesizer.args_for(chapter, aggregate, nc_command, created).merge(id: created[aggregate.name])
-              dispatcher.dispatch_flat("#{domain}::#{aggregate.name}.#{nc_command.hecks_name}", nc_args)
-            rescue StandardError => e
-              failures << Failure.new(domain: domain, aggregate: aggregate.name, command: nc_command.hecks_name,
-                                      error: "#{e.class}: #{e.message}")
-            end
-          end
-        end
+        run = Run.new(dispatcher, domain, chapter, {}, [])
+        chapter.aggregates.each { |aggregate| smoke_aggregate(run, aggregate) }
+        chapter.read_models.each { |model| smoke_read_model(run, model) }
+        run.failures
+      end
 
-        chapter.read_models.each do |model|
-          root_id = created[model.reference_target]
-          # No root was created, so there is nothing to query yet.
-          next unless root_id
+      # Dispatches every creating command, then, after each that succeeds, every other command.
+      def smoke_aggregate(run, aggregate)
+        creating, noncreating = aggregate.commands.partition(&:creates?)
 
-          dispatcher.query("#{domain}.#{model.query_name}", model.reference_name => root_id)
-        rescue StandardError => e
-          failures << Failure.new(domain: domain, aggregate: model.name, command: "report(#{model.name})",
-                                  error: "#{e.class}: #{e.message}")
+        creating.each do |command|
+          args = Synthesizer.args_for(run.chapter, aggregate, command, run.created)
+          next unless smoke_created?(run, aggregate, command, args)
+
+          noncreating.each { |other| smoke_other(run, aggregate, other) }
         end
+      end
+
+      # @return [Boolean] whether the creating command dispatched; a refusal is recorded instead
+      def smoke_created?(run, aggregate, command, args)
+        result = run.dispatcher.dispatch_flat("#{run.domain}::#{aggregate.name}.#{command.hecks_name}", args)
+        run.created[aggregate.name] = result.instance.id
+        true
+      rescue StandardError => e
+        record_failure(run, aggregate.name, command.hecks_name, e)
+        false
+      end
+
+      # Dispatches a command against the instance the creating command made; a refusal is recorded.
+      def smoke_other(run, aggregate, command)
+        args = Synthesizer.args_for(run.chapter, aggregate, command, run.created).merge(id: run.created[aggregate.name])
+        run.dispatcher.dispatch_flat("#{run.domain}::#{aggregate.name}.#{command.hecks_name}", args)
+      rescue StandardError => e
+        record_failure(run, aggregate.name, command.hecks_name, e)
+      end
+
+      # Queries a read model once its root exists; a refusal is recorded.
+      def smoke_read_model(run, model)
+        root_id = run.created[model.reference_target]
+        # No root was created, so there is nothing to query yet.
+        return unless root_id
+
+        run.dispatcher.query("#{run.domain}.#{model.query_name}", model.reference_name => root_id)
+      rescue StandardError => e
+        record_failure(run, model.name, "report(#{model.name})", e)
+      end
 
-        failures
+      # @return [Array<Failure>] `run.failures`, now holding one more
+      def record_failure(run, aggregate_name, command_name, error)
+        run.failures << Failure.new(domain: run.domain, aggregate: aggregate_name, command: command_name,
+                                    error: "#{error.class}: #{error.message}")
       end
     end
   end

data/lib/hecks/bluebook/synthesizer.rb

@@ -39,16 +39,24 @@ module Hecks
       #   field — the closed set's own first admitted member's fields, or one
       #   freshly synthesized scalar per declared field
       def value_for(chapter, aggregate, type_name)
-        value_object = aggregate.value_object(type_name) ||
-                       chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
+        value_object = find_value_object(chapter, aggregate, type_name)
         return "smoke-test" unless value_object
-
-        closed_set = value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
-        return value_object.members.first.to_h if closed_set
+        return value_object.members.first.to_h if populated_closed_set?(value_object)
 
         value_object.attributes.to_h { |field| [field.name, field_value_for(chapter, aggregate, field.type)] }
       end
 
+      # The value object `type_name` names, on `aggregate` first, then on any other aggregate.
+      def find_value_object(chapter, aggregate, type_name)
+        aggregate.value_object(type_name) ||
+          chapter.aggregates.filter_map { |a| a.value_object(type_name) }.first
+      end
+
+      # Whether `value_object` is a closed set that admits at least one member.
+      def populated_closed_set?(value_object)
+        value_object.respond_to?(:closed_set?) && value_object.closed_set? && value_object.members.any?
+      end
+
       # A field's value: a scalar for a primitive type, otherwise the nested value object.
       #
       # @param chapter [Bluebook::Chapter] see `value_for`

data/lib/hecks/bluebook/translation.rb

@@ -1,3 +1,5 @@
+require_relative "keyword_fields"
+
 module Hecks
   module Bluebook
     # One field crossing a value-object boundary, or carried under a new name.
@@ -32,6 +34,12 @@ module Hecks
     class TranslationAggregate
       attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :computes, :rekeys, :backfills
 
+      # Every optional field and what it holds when the declaration omits it.
+      FIELD_DEFAULTS = {
+        was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
+        computes: [], rekeys: [], backfills: []
+      }.freeze
+
       # @param name [String, Symbol] the aggregate's name in the destination era
       # @param was [String, Symbol, nil] its name in the origin era, or `nil` if unchanged
       # @param renames [Hash{Symbol => Symbol}] old field name to new field name
@@ -42,18 +50,10 @@ module Hecks
       # @param computes [Array<Bluebook::TranslationCompute>] fields computed by Postgres-only SQL
       # @param rekeys [Array<Bluebook::TranslationRekey>] SQL recomputing the aggregate's identity
       # @param backfills [Array<Bluebook::TranslationBackfill>] new required fields, no old source
-      def initialize(name:, was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
-                     computes: [], rekeys: [], backfills: [])
-        @name      = name.to_s
-        @was       = was&.to_s
-        @renames   = renames
-        @moves     = moves
-        @converts  = converts
-        @drops     = drops
-        @retypes   = retypes
-        @computes  = computes
-        @rekeys    = rekeys
-        @backfills = backfills
+      def initialize(name:, **given)
+        KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
+        @name = name.to_s
+        @was  = @was&.to_s
       end
     end
 

data/lib/hecks/bluebook.rb

@@ -27,7 +27,7 @@ require_relative "bluebook/domain_port"
 require_relative "bluebook/policy"
 require_relative "bluebook/process_manager"
 require_relative "bluebook/aggregate"
-require_relative "bluebook/hexagon"
+require_relative "bluebook/hecksagon"
 require_relative "bluebook/translation"
 
 require_relative "bluebook/assembly/contract"

data/lib/hecks/cache_dir.rb

@@ -20,6 +20,16 @@ module Hecks
       File.join(root, name)
     end
 
+    # The directory the gem ships prebuilt cache files in, beside `lib/` so the digest of `lib/`
+    # that names a cache file never covers the files built from it. It exists only in a packaged
+    # gem, and it is part of the gem's own code, so it needs no ownership check.
+    #
+    # @param name [String] the file name inside it
+    # @return [String] the absolute path of `name` under the gem's `prebuilt/`
+    def prebuilt(name)
+      File.join(File.expand_path("../..", __dir__), "prebuilt", name)
+    end
+
     # The cache root, resolved once per process.
     #
     # @return [String] the absolute path of the directory every `path` lives under

data/lib/hecks/chapters.rb

@@ -51,7 +51,7 @@ module Hecks
 
       raise Runtime::WiringError,
             "attaches #{name.inspect}: the gem carries no chapter of that name — known: " \
-            "#{table.keys.sort.join(', ')}. To attach a vendored package, write " \
+            "#{table.keys.sort.join(", ")}. To attach a vendored package, write " \
             "`attaches #{name.to_s.inspect}, from: :vendor`"
     end
 
@@ -65,35 +65,51 @@ module Hecks
     # @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"
+      paths = chapter_paths(name)
+      registry = open_registry(name)
       return refuse_own_chapter(registry, name.to_s) if registry.bluebook(name.to_s)
 
       load_atomically(registry, name.to_s, paths)
       true
     end
 
+    # @return [Array<String>] the files of the named chapter
+    # @raise [Runtime::WiringError] if no attachable chapter has that name
+    def self.chapter_paths(name)
+      index.fetch(name.to_s) do
+        raise Runtime::WiringError,
+              "no attachable chapter named #{name.inspect} — known: #{index.keys.join(", ")}"
+      end
+    end
+
+    # @return [Runtime::Registry] the registry the current boot is loading into
+    # @raise [Runtime::WiringError] when no boot is open
+    def self.open_registry(name)
+      Hecks.current_registry or
+        raise Runtime::WiringError, "attaches #{name.to_s.inspect} outside a boot: no registry is open"
+    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
+      before = { 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) }
+      roll_back(registry, name, before)
       raise
     end
-    private_class_method :load_atomically
+
+    # Puts the registry back as `load_atomically` found it.
+    def self.roll_back(registry, name, before)
+      registry.forget_chapter(name)
+      Bluebook::MetaValidator.deferred_chapters.replace(before[:queued])
+      registry.ports.delete_if { |key, _| !before[:ports].include?(key) }
+      registry.adapters.delete_if { |key, _| !before[:adapters].include?(key) }
+    end
+    private_class_method :chapter_paths, :open_registry, :load_atomically, :roll_back
 
     # 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
@@ -105,7 +121,7 @@ module Hecks
 
       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"
+            "#{foreign.join(", ")} — rename it, since the gem's own #{name} chapter cannot merge into it"
     end
     private_class_method :refuse_own_chapter
 

data/lib/hecks/cli/behaviors.rb

@@ -19,24 +19,31 @@ module Hecks
         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
+        summary = File.directory?(target) ? sweep_directory(target) : run_file(target)
         exit(bad?(summary) ? 1 : 0)
       end
 
+      # @api private
+      def sweep_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"
+        summary
+      end
+
+      # @api private
+      def run_file(target)
+        result = Hecks::Behaviors.run(target)
+        report_file(result)
+        Hecks::Behaviors.summarize([result])
+      end
+
       # @api private
       def report_file(result)
         puts result.path

data/lib/hecks/cli/check_era.rb

@@ -40,11 +40,11 @@ module Hecks
       def sentence(verdict, file)
         case verdict.status
         when :match
-          "era #{verdict.era} is expected (#{verdict.allowed.join(', ')})"
+          "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(', ')})"
+          "host reports era #{verdict.era}, which is not in #{file} (expected: #{verdict.allowed.join(", ")})"
         end
       end
     end

data/lib/hecks/cli/command_table.rb

@@ -0,0 +1,72 @@
+module Hecks
+  module CLI
+    # One subcommand: a one-line summary, its usage line, the file that holds it and the
+    # call that runs it (given the argv after the name, its program name and its own name).
+    Command = Struct.new(:summary, :usage, :file, :run)
+
+    # Every subcommand, in the order the help lists them.
+    COMMANDS = {
+      "run"              => Command.new(
+        "Dispatch a verb, or run a JSON step list, against a domain.",
+        "hecks run [domain] <verb [name=value …] | script.json | - | '{\"steps\":[…]}'>",
+        "cli/run",
+        ->(argv, program, _name) { Run.call(argv, program: program) }
+      ),
+      "docs"             => Command.new(
+        "Print a domain's usage document, projected from its bluebook.",
+        "hecks docs [domain-path] [aggregate]",
+        "cli/document",
+        ->(argv, program, name) { Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd) }
+      ),
+      "narrate"          => Command.new(
+        "Print a domain read back in English, projected from its bluebook.",
+        "hecks narrate [domain-path] [aggregate]",
+        "cli/document",
+        ->(argv, program, name) { Document.call(argv, projection: name.to_sym, program: program, root: Dir.pwd) }
+      ),
+      "ir"               => Command.new(
+        "Print a booted domain's IR as JSON.",
+        "hecks ir <domain> [--translations] | hecks ir --meta",
+        "cli/ir",
+        ->(argv, program, _name) { Ir.call(argv, program: program) }
+      ),
+      "stores"           => Command.new(
+        "Print every aggregate's current records as JSON.",
+        "hecks stores <domain>",
+        "cli/stores",
+        ->(argv, program, _name) { Stores.call(argv, program: program) }
+      ),
+      "model_check"      => Command.new(
+        "Statically check a domain's IR for dead states and unreachable steps.",
+        "hecks model_check [--strict] [--profile client] [--wait] [<domain> …]",
+        "cli/model_check",
+        ->(argv, program, _name) { ModelCheck.call(argv, program: program, root: checkout_root) }
+      ),
+      "smoke_test"       => Command.new(
+        "Boot a domain and dispatch every declared command and report once.",
+        "hecks smoke_test [domain]",
+        "cli/smoke_test",
+        ->(argv, _program, _name) { SmokeTest.call(argv, root: Dir.pwd) }
+      ),
+      "project_diagrams" => Command.new(
+        "Write a domain's Mermaid diagrams under ./docs/generated/diagrams/ (positional form only).",
+        "hecks project_diagrams <domain-path> <ChapterName>  (writes) | " \
+        "hecks project_diagrams domain=<path> chapter=<Name>  (prints; writes nothing)",
+        "cli/project_diagrams",
+        ->(argv, program, _name) { ProjectDiagrams.call(argv, program: program, root: Dir.pwd) }
+      ),
+      "project_cli"      => Command.new(
+        "Write a command-line launcher beside each domain, named after its bluebook.",
+        "hecks project_cli [domain-path …]",
+        "cli/project_cli",
+        ->(argv, program, _name) { ProjectCli.call(argv, program: program, root: Dir.pwd, remove_stale_bin: false) }
+      ),
+      "mcp"              => Command.new(
+        "Serve the MCP door over stdio (no authentication; stdio only).",
+        "hecks mcp [--stdio]",
+        "cli/mcp",
+        ->(argv, _program, _name) { Mcp.call(argv) }
+      )
+    }.freeze
+  end
+end

data/lib/hecks/cli/console.rb

@@ -50,18 +50,21 @@ module Hecks
       # @return [String] each chapter's vision, and its aggregates' descriptions and 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(", ")
-            description = aggregate.description.to_s.strip
-            lines = ["    #{aggregate.name}: #{commands}"]
-            lines << "      #{description}" unless description.empty?
-            lines.join("\n")
-          end
+          aggregates = bluebook.aggregates.map { |aggregate| aggregate_overview(aggregate) }
 
           "\n    #{bluebook.name} — #{bluebook.vision}\n#{aggregates.join("\n")}\n"
         end.join
       end
 
+      # @api private
+      def aggregate_overview(aggregate)
+        commands = aggregate.commands.map { |command| "#{Naming.snake(command.hecks_name)}!" }.sort.join(", ")
+        description = aggregate.description.to_s.strip
+        lines = ["    #{aggregate.name}: #{commands}"]
+        lines << "      #{description}" unless description.empty?
+        lines.join("\n")
+      end
+
       # @param domain [String, nil] a domain directory, or nil for the bundled pizzas domain
       # @return [String] the version, and for the pizzas domain a first session to try
       def banner(domain = nil)

data/lib/hecks/cli/deploy_template_diff.rb

@@ -19,22 +19,35 @@ module Hecks
       # @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
+        parser = option_parser(program, options)
         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
+        print_report(files, options).different? ? 1 : 0
       rescue ArgumentError => e
         warn e.message
         2
       end
+
+      # Prints the comparison of two templates.
+      #
+      # @api private
+      # @return [Object] the comparison report
+      def print_report(files, options)
+        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
+      end
+
+      # @api private
+      def option_parser(program, options)
+        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
+      end
     end
   end
 end

data/lib/hecks/cli/document.rb

@@ -30,22 +30,26 @@ module Hecks
         path, aggregate = target(argv, here)
         refuse_without_domain(program, root) unless path
 
+        bluebook = boot_bluebook(path)
+        begin
+          puts Projector.call(projection, bluebook: bluebook, options: aggregate ? { aggregate: aggregate } : {})
+        rescue Runtime::NotFound => e
+          abort e.message
+        end
+      end
+
+      # The domain's own chapter, not a framework member it attached: insertion
+      # order, the same distinction `Runtime::Loader.dispatcher_for` draws.
+      #
+      # @api private
+      def boot_bluebook(path)
         begin
           runtime = Hecks.boot(path, install_doors: false)
         rescue StandardError => e
           abort "cannot read #{path}: #{e.message.lines.first.strip}"
         end
 
-        # The domain's own chapter, not a framework member it attached: insertion
-        # order, the same distinction `Runtime::Loader.dispatcher_for` draws.
-        bluebook = runtime.registry.bluebooks.values.first
-        abort "#{path} loaded no bluebook" unless bluebook
-
-        begin
-          puts Projector.call(projection, bluebook: bluebook, options: aggregate ? { aggregate: aggregate } : {})
-        rescue Runtime::NotFound => e
-          abort e.message
-        end
+        runtime.registry.bluebooks.values.first or abort "#{path} loaded no bluebook"
       end
 
       # Lists every directory under `root` that `Hecks.boot` would accept.

data/lib/hecks/cli/domain_stub.rb

@@ -77,7 +77,7 @@ module Hecks
         end
         return if ADAPTERS.key?(adapter)
 
-        raise ArgumentError, "unknown adapter #{adapter.inspect}; choose one of #{adapters.join(', ')}"
+        raise ArgumentError, "unknown adapter #{adapter.inspect}; choose one of #{adapters.join(", ")}"
       end
 
       # @api private

data/lib/hecks/cli/domain_writer.rb

@@ -14,7 +14,7 @@ module Hecks
       # @raise [ArgumentError] when any file, or a bluebook the files would add, is already there
       def write!(files, target)
         taken = taken(files, target)
-        raise ArgumentError, "nothing written; already there: #{taken.join(', ')}" unless taken.empty?
+        raise ArgumentError, "nothing written; already there: #{taken.join(", ")}" unless taken.empty?
 
         files.each do |path, text|
           full = File.join(target, path)

data/lib/hecks/cli/expression_projection.rb

@@ -23,12 +23,7 @@ module Hecks
       # @return [Integer] the exit status, 0 once written or printed
       # @raise [SystemExit] with the refusal when the projection drops a self-bearing operator
       def call(argv, out: $stdout)
-        result = begin
-          Hecks::ProjectionFiles.build(:expression_tables)
-        rescue Hecks::ProjectionFiles::Refused => e
-          abort e.message
-        end
-
+        result = build
         if argv.include?("--stdout")
           out.print result.content.values.first
         else
@@ -36,6 +31,13 @@ module Hecks
         end
         0
       end
+
+      # @api private
+      def build
+        Hecks::ProjectionFiles.build(:expression_tables)
+      rescue Hecks::ProjectionFiles::Refused => e
+        abort e.message
+      end
     end
   end
 end

data/lib/hecks/cli/follow.rb

@@ -76,13 +76,19 @@ module Hecks
 
         loop do
           events = repository.events
-          if events.size > seen
-            events[seen..].each { |event| puts JSON.generate(event.to_h) if matches?(event, options[:aggregate]) }
-            seen = events.size
-          end
+          seen = print_new(events, seen, options[:aggregate]) if events.size > seen
           sleep options[:interval]
         end
       end
+
+      # Prints the events past `seen` that pass the filter.
+      #
+      # @api private
+      # @return [Integer] the new count of events seen
+      def print_new(events, seen, filter)
+        events[seen..].each { |event| puts JSON.generate(event.to_h) if matches?(event, filter) }
+        events.size
+      end
     end
   end
 end