hecks 6.0.0 → 7.0.0

data/lib/hecks/{cli → tools}/project_cli/launcher_source.rb

@@ -2,7 +2,7 @@ require_relative "../../naming"
 require_relative "templates"
 
 module Hecks
-  module CLI
+  module Tools
     module ProjectCli
       # The source of one launcher, built from `Templates`. `ProjectCli` extends it.
       module LauncherSource
@@ -19,7 +19,9 @@ module Hecks
         # How every launcher ends.
         PLAIN_ENDING = "status.zero? ? puts(text) : abort(text)".freeze
 
-        # How an opted-in launcher ends: a failed `--wait` run still prints its settled record.
+        # How an opted-in launcher ends: a failed `--wait` run still prints its settled record, and
+        # the process exits with the status the runner answered (`ExitStatus`), a refusal and a
+        # line it could not read apart.
         OPTED_ENDING = <<~LAUNCHER_TAIL.chomp.freeze
           # A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
           # either way, and says why on stderr.
@@ -28,7 +30,8 @@ module Hecks
             warn reason
             exit status
           end
-          status.zero? ? puts(text) : abort(text)
+          status.zero? ? puts(text) : warn(text)
+          exit status
         LAUNCHER_TAIL
 
         # What a Memory command does when refused: say why, from the record's `refusal`.
@@ -64,31 +67,44 @@ module Hecks
         # @param name [String] the bluebook's name
         # @param program [String] the generator's invocation, named in the header
         # @param executable [String, nil] the file's path under the root when not beside the domain
-        # @param legacy [Array<String>, nil] commands an executable hands to `Hecks::CLI` first
         # @param memory_commands [Array<String>, nil] commands that default to Memory
         # @param opted [Boolean] whether the bluebook's world declares a `launcher` setting
+        # @param ledgers [Hash{String => String}] command word => ledger directory, under the root
         # @return [String] the Ruby source
-        # @raise [ArgumentError] if a name, path, executable or legacy command is not plain
-        def launcher(path, name, program, executable: nil, legacy: nil, memory_commands: nil, opted: !executable.nil?) # rubocop:disable Metrics/ParameterLists -- the generator's documented signature
+        # @raise [ArgumentError] if a name, path, executable or memory command is not plain
+        def launcher(path, name, program, executable: nil, memory_commands: nil, opted: !executable.nil?, ledgers: {})
           plain!("bluebook name", name, NAME)
           plain!("domain path", path, PATH)
-          site = executable ? executable_site(path, executable) : plain_site(path, name, program)
+          site = executable ? executable_site(path, executable, ledgers) : plain_site(path, name, program)
           quiet = !Array(memory_commands).empty?
 
           render(LAUNCHER, name: name, program: site.program, where: site.where, up: site.up,
                            encoding: opted ? ENCODING : "",
-                           handoff: handoff_for(executable, legacy, memory_commands, site),
+                           handoff: handoff_for(executable, memory_commands, site, ledgers),
                            ending: ending_for(opted, executable && quiet),
                            entry: entry(name, site.boot, site.shown, opted, quiet: quiet))
         end
 
         # @api private
         # @return [String] what an executable launcher does before it boots, or nothing: it takes
-        #   the gems the checkout's Gemfile pins, hands legacy commands on, defaults Memory ones
-        def handoff_for(executable, legacy, memory_commands, site)
+        #   the gems the checkout's Gemfile pins, and defaults Memory ones
+        def handoff_for(executable, memory_commands, site, ledgers)
           return "" unless executable
 
-          render(PINNED_GEMS, up: site.up) + legacy_handoff(Array(legacy)) + memory_default(Array(memory_commands))
+          render(PINNED_GEMS, up: site.up) + memory_default(Array(memory_commands)) + ledger_route(ledgers)
+        end
+
+        # @api private
+        # @return [String] the lines routing each ledger command word to its directory, or nothing
+        def ledger_route(ledgers)
+          return "" if ledgers.empty?
+
+          routes = ledgers.map do |word, dir|
+            plain!("ledger command", word, VERB)
+            plain!("ledger directory", dir, PATH)
+            %("#{word}" => "#{dir}")
+          end
+          render(LEDGER_ROUTE, routes: routes.join(", "))
         end
 
         # @api private
@@ -100,14 +116,17 @@ module Hecks
 
         # @api private
         # @return [Site] where an executable launcher sits, named by its path under the root
-        def executable_site(path, executable)
+        def executable_site(path, executable, ledgers = {})
           plain!("launcher executable", executable, PATH)
           if executable.split("/").include?("..")
             raise ArgumentError, "launcher executable #{executable.inspect} must stay inside the root"
           end
 
           up = "../" * File.dirname(executable).split("/").count { |part| part != "." }
-          Site.new(up, %(File.expand_path("#{up}#{path}", __dir__)), GENERATOR, executable, File.basename(executable))
+          # The boot is a ledger's directory when the route above set `ledger`.
+          named  = %(File.expand_path("#{up}#{path}", __dir__))
+          routed = %(File.expand_path(ledger ? "#{up}\#{ledger}" : "#{up}#{path}", __dir__))
+          Site.new(up, ledgers.empty? ? named : routed, GENERATOR, executable, File.basename(executable))
         end
 
         # @api private
@@ -164,15 +183,6 @@ module Hecks
           commands.each { |command| plain!("memory command", command, VERB) }
           render(MEMORY_DEFAULT, commands: commands.join(" "))
         end
-
-        # @api private
-        # @return [String] the lines that hand the legacy commands to `Hecks::CLI`, or nothing
-        def legacy_handoff(legacy)
-          return "" if legacy.empty?
-
-          legacy.each { |command| plain!("legacy command", command, VERB) }
-          render(LEGACY_HANDOFF, commands: legacy.join(" "))
-        end
       end
     end
   end

data/lib/hecks/{cli → tools}/project_cli/templates.rb

@@ -1,5 +1,5 @@
 module Hecks
-  module CLI
+  module Tools
     module ProjectCli
       # The text of a launcher, as templates: each `{{name}}` is filled in by `render`.
       module Templates
@@ -22,6 +22,8 @@ module Hecks
           {{encoding}}$LOAD_PATH.unshift File.expand_path("{{up}}lib", __dir__)
           {{handoff}}
           require "hecks"
+          # Every secret a world hands an adapter is masked in whatever this process prints.
+          Hecks::Secrets.guard!
 
           {{entry}}
           {{ending}}
@@ -38,7 +40,14 @@ module Hecks
           described = begin
             Hecks.describe(domain)
           rescue StandardError => e
-            abort "cannot open {{name}}: #{e.message.lines.first.strip}"
+            abort "cannot open {{name}}: #{e.message.strip}"
+          end
+
+          # `hecks usage` reads the local record of what this launcher ran; it boots nothing.
+          if ARGV.first == "usage"
+            known = Hecks::Adapters::Driving::CliRunner.known_names(runtime: described, program: program)
+            puts Hecks::Adapters::Driving::UsageLog.summary(known: known)
+            exit 0
           end
 
           text, status, reason = Hecks::Adapters::Driving::CliRunner.usage(
@@ -48,13 +57,13 @@ module Hecks
             runtime = begin
               {{started}}
             rescue StandardError => e
-              abort "cannot open {{name}}: #{e.message.lines.first.strip}"
+              abort "cannot open {{name}}: #{e.message.strip}"
             end
             # A question the world lists under `streams`, given `--stream`, tails until interrupted.
             streamed = Hecks::Adapters::Driving::CliRunner.stream(runtime: runtime, argv: ARGV, program: program)
             exit streamed unless streamed.nil?
             text, status, reason = Hecks::Adapters::Driving::CliRunner.call(
-              runtime: runtime, argv: ARGV, program: program
+              runtime: runtime, argv: ARGV, program: program, usage_log: true
             )
           end
         RUBY
@@ -72,6 +81,15 @@ module Hecks
           )
         RUBY
 
+        # The lines that send a command a ledger answers to the ledger's own directory. The ledger's
+        # name is dropped from the command line, and the boot below reads `ledger`.
+        LEDGER_ROUTE = <<~RUBY.freeze
+
+          # A command a ledger answers boots that ledger's directory, not this domain's.
+          ledger = { {{routes}} }.fetch(ARGV.first, nil)
+          ARGV.shift if ledger
+        RUBY
+
         # The lines that default listed commands to Memory.
         MEMORY_DEFAULT = <<~RUBY.freeze
 
@@ -101,17 +119,6 @@ module Hecks
           end
         RUBY
 
-        # The lines that hand the legacy commands to `Hecks::CLI`.
-        LEGACY_HANDOFF = <<~RUBY.freeze
-
-          # The names the gem has always shipped keep their positional forms.
-          LEGACY = %w[{{commands}}].freeze
-          if LEGACY.include?(ARGV.first)
-            require "hecks/cli"
-            exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
-          end
-        RUBY
-
         # Fills a template's `{{name}}` placeholders.
         #
         # @param template [String] the template text

data/lib/hecks/{cli → tools}/project_cli.rb

@@ -1,10 +1,11 @@
 require "fileutils"
 require_relative "../../hecks"
 require_relative "project_cli/launcher_source"
+require_relative "../corpus"
 
 module Hecks
-  module CLI
-    # The command behind `hecks project_cli` and `hecks project_cli`: writes a
+  module Tools
+    # The command behind `hecks launch.project_cli!` and `hecks launch.project_cli!`: writes a
     # command-line launcher beside each domain, named after its bluebook, so
     # `Hecks.bluebook "QualityControl"` in `qa/` becomes `qa/quality_control`.
     #
@@ -55,7 +56,7 @@ module Hecks
       # @api private
       def refuse_unknown(flags)
         unknown = flags - ["--check"]
-        abort "hecks project_cli: unknown option #{unknown.first} (the only option is --check)" unless unknown.empty?
+        abort "hecks launch.project_cli!: unknown option #{unknown.first} (the only option is --check)" unless unknown.empty?
       end
 
       # Says which launchers drifted or could not be made, and exits 1 if any did.
@@ -66,7 +67,9 @@ module Hecks
         failed  = outcomes.select { |_, outcome| outcome == :failed }.keys
         return if drifted.empty? && failed.empty?
 
-        warn "launcher out of date for: #{drifted.join(", ")}; run `hecks project_cli #{drifted.join(" ")}`" unless drifted.empty?
+        unless drifted.empty?
+          warn "launcher out of date for: #{drifted.join(", ")}; run `hecks launch.project_cli! #{drifted.join(" ")}`"
+        end
         warn "no launcher could be checked or written for: #{failed.join(", ")}" unless failed.empty?
         exit 1
       end
@@ -80,7 +83,7 @@ module Hecks
       def under_root(root, path)
         expanded = File.expand_path(path, root)
         inside   = expanded == root || expanded.start_with?("#{root}/")
-        abort "hecks project_cli: #{path.inspect} is outside #{root}" unless inside
+        abort "hecks launch.project_cli!: #{path.inspect} is outside #{root}" unless inside
 
         relative = expanded.delete_prefix(root).delete_prefix("/")
         relative.empty? ? "." : relative
@@ -120,8 +123,9 @@ module Hecks
         snake      = Naming.snake(name)
         executable = setting[:executable]
         label      = executable || "#{path}/#{snake}"
-        text       = launcher(path, name, program, executable: executable, legacy: setting[:legacy],
-                                                   memory_commands: setting[:memory_commands], opted: !setting.empty?)
+        text       = launcher(path, name, program, executable: executable,
+                                                   memory_commands: setting[:memory_commands], opted: !setting.empty?,
+                                                   ledgers: executable ? Corpus::ROTATION_LEDGER : {})
         Target.new(name, label, File.join(root, label), text, snake, executable)
       end
 

data/lib/hecks/{cli → tools}/project_diagrams.rb

@@ -1,7 +1,7 @@
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks project_diagrams`: boots a
     # domain, finds the bluebook it names, and writes its Mermaid diagrams
     # (`Projections::Diagrams`) under `docs/generated/diagrams/<bluebook>/` below the
@@ -48,9 +48,9 @@ module Hecks
       # @api private
       def report(declaration_name, directory, written)
         if written.empty?
-          puts "#{declaration_name} declares no lifecycle, relationship, or dispatch to project yet"
+          warn "#{declaration_name} declares no lifecycle, relationship, or dispatch to project yet"
         else
-          puts "wrote #{written.size} diagram(s) to #{directory}:"
+          warn "wrote #{written.size} diagram(s) to #{directory}:"
           written.each { |path| puts "  #{path}" }
         end
       end

data/lib/hecks/{cli → tools}/project_glossary.rb

@@ -1,7 +1,7 @@
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks glossary`: boots a domain and projects one bluebook into its
     # Ubiquitous Language glossary, `glossary.md` plus `html/index.html` rendered from it, in the
     # domain's own `glossary/` folder.
@@ -25,7 +25,7 @@ module Hecks
 
         written = write_glossary(File.expand_path(domain_path, Dir.pwd), declaration_name)
 
-        puts "wrote #{written.size} file(s):"
+        warn "wrote #{written.size} file(s):"
         written.each { |path| puts "  #{path}" }
       end
 

data/lib/hecks/{cli → tools}/reference.rb

@@ -4,8 +4,8 @@ require_relative "../../hecks"
 require_relative "../projection_files"
 
 module Hecks
-  module CLI
-    # The command behind `hecks language_run.project_reference`: regenerates
+  module Tools
+    # The command behind `hecks language_run.project_reference!`: regenerates
     # `docs/implemented/reference/` from
     # the language's Syntax bluebook. Tables come from the declaration; prose is kept from the
     # committed pages.

data/lib/hecks/{cli → tools}/refresh_projections.rb

@@ -1,7 +1,7 @@
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The logic behind `hecks refresh_projections` and Custodian's `Operation.RefreshProjections`:
     # forces every
     # read-model projection a booted domain declares to catch up now, the same catch-up a boot

data/lib/hecks/{cli → tools}/refresh_rspec_runtime_baseline.rb

@@ -6,7 +6,7 @@ require "open3"
 require "yaml"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks refresh_runtime_baseline`: regenerates the committed runtime
     # baselines the sharded CI jobs group from. It prefers one CI run's timings; a local run is
     # the fallback.

data/lib/hecks/tools/regeneration_run/pool.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module Hecks
+  module Tools
+    module RegenerationRun
+      # Forks one `hecks project_rust` child per domain, up to `workers` at a time, and prints each
+      # child's output whole, in domain order, as soon as every domain before it has been printed.
+      #
+      # A child inherits the parent's memoized grammar registry through the fork. Its output goes to
+      # a temporary file, so a child that writes a lot never waits on a reader. A child that fails
+      # stops the pool from starting more; the ones already running are left to finish, so no
+      # child is cut off in the middle of a write. The run then aborts, naming the failed domains.
+      class Pool
+        # What a child runs: `hecks project_rust` with the domain and the declared-domain flags,
+        # writing to the streams it was given.
+        PROJECT_RUST = lambda do |argv|
+          Hecks::RustBuild.run("project_rust", argv, out: STDOUT, err: STDERR)
+        end
+
+        # @param domains [Array<String>] the domains, in the order their output is printed
+        # @param flags [Array<String>] the declared-domain flags every child is given
+        # @param workers [Integer] how many children may run at once
+        # @param runner [#call] what a child does with its argument list, answering an exit status
+        def initialize(domains, flags, workers, runner: PROJECT_RUST)
+          @domains = domains
+          @flags = flags
+          @workers = workers
+          @runner = runner
+          @pending = domains.each_index.to_a
+          @running = {}
+          @results = {}
+          @shown = Set.new
+          @finished = Queue.new
+        end
+
+        # Runs every domain, or until one fails and the children already running are done.
+        #
+        # @return [void]
+        # @raise [SystemExit] when a child fails: the message names every domain that did
+        def call
+          start_children
+          until @running.empty?
+            finish(*@finished.pop)
+            start_children
+          end
+          print_rest
+          abort_on_failure
+        ensure
+          stop_children
+        end
+
+        private
+
+        def start_children
+          while @running.size < @workers && failed.empty? && (index = @pending.shift)
+            @running[index] = start(index)
+          end
+        end
+
+        # @return [Array<Integer>] the indexes of the children that ended badly, in domain order
+        def failed = @results.reject { |_, (_, status)| status.success? }.keys.sort
+
+        # @return [Array(Integer, Tempfile)] the child's process id and its output file
+        def start(index)
+          out = Tempfile.new("regen-project-rust")
+          pid = fork { run_child(out, [@domains[index], *@flags]) }
+          Thread.new { @finished << [index, Process.wait2(pid).last] }
+          [pid, out]
+        end
+
+        def finish(index, status)
+          _, out = @running.delete(index)
+          @results[index] = [out, status]
+          print_ready
+        end
+
+        # Prints the finished children in domain order, each once every domain before it is shown.
+        def print_ready
+          next_up = (0...@domains.size).find { |index| !@shown.include?(index) }
+          while next_up && @results.key?(next_up)
+            show(next_up)
+            next_up += 1
+          end
+        end
+
+        # After a failure some domains were never started: shows the ones that ran, in order.
+        def print_rest
+          @results.keys.sort.each { |index| show(index) unless @shown.include?(index) }
+        end
+
+        def show(index)
+          @shown << index
+          out, = @results.fetch(index)
+          puts "== hecks project_rust #{@domains[index]} =="
+          out.rewind
+          $stdout.write(out.read)
+          out.close!
+          puts
+        end
+
+        def abort_on_failure
+          names = failed
+          return if names.empty?
+
+          first, *others = names
+          also = others.empty? ? "" : " (also failed: #{others.map { |index| @domains[index] }.join(", ")})"
+          abort "hecks regenerate_corpus: hecks project_rust #{@domains[first]} failed " \
+                "(#{@results.fetch(first).last.inspect})#{also}"
+        end
+
+        # Ends the children still running when the parent leaves early (an interrupt, say).
+        def stop_children
+          @running.each_value do |pid, _|
+            Process.kill("TERM", pid)
+          rescue Errno::ESRCH
+            next
+          end
+        end
+
+        # @param out [Tempfile] the child's end, which becomes its stdout and stderr
+        # @param argv [Array<String>] the arguments of `hecks project_rust`
+        # @return [void] never returns: the child leaves without the parent's exit handlers
+        def run_child(out, argv)
+          # The real descriptors, not the globals: a caller may have swapped those for a buffer.
+          STDOUT.reopen(out)
+          STDERR.reopen(out)
+          $stdout = STDOUT
+          $stderr = STDERR
+          status = child_status(argv)
+          $stdout.flush
+          exit!(status)
+        end
+
+        # @return [Integer] the exit status of the runner with the arguments
+        def child_status(argv)
+          @runner.call(argv)
+        rescue SystemExit => e
+          e.status
+        rescue StandardError => e
+          warn "#{e.class}: #{e.message}"
+          1
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/regeneration_run/scratch.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "tmpdir"
+
+module Hecks
+  module Tools
+    module RegenerationRun
+      # The scratch crate of a `--check`: copies of the generated tree and Cargo.toml that a
+      # projection writes into, and the comparison of what it wrote with the tree on disk. The
+      # working tree is never written.
+      module Scratch
+        # The refusal when a check finds nothing generated to compare.
+        NOT_MATERIALIZED = "hecks regeneration_run.regenerate_corpus! --check: rust/src/generated has no generated output to " \
+                           "compare. It is committed: restore it from git, or run " \
+                           "`hecks regeneration_run.regenerate_corpus! --confirm`, then the check."
+
+        # A scratch crate: copies of the generated tree and Cargo.toml, all `hecks build.project_rust!`
+        # writes.
+        #
+        # @param root [String] the checkout
+        # @return [String] the scratch directory
+        def scratch_crate(root)
+          abort NOT_MATERIALIZED unless File.directory?(File.join(root, "rust/src/generated/meta"))
+
+          scratch = Dir.mktmpdir("regen-codegen-check")
+          FileUtils.mkdir_p(File.join(scratch, "src"))
+          FileUtils.cp_r(File.join(root, "rust/src/generated"), File.join(scratch, "src/generated"))
+          FileUtils.cp(File.join(root, "rust/Cargo.toml"), scratch)
+          scratch
+        end
+
+        # Puts back, in the scratch crate, every module the named domains do not own, as the tree
+        # has it: a run of some domains rewrites the shared bluebooks and the grammar as its own last
+        # writer would, which is not what the whole corpus's last writer left in the tree.
+        #
+        # @param scratch [String] the scratch crate
+        # @param root [String] the checkout
+        # @param owned [Array<String>] the features of the domains that ran
+        # @return [void]
+        def restore_shared(scratch, root, owned)
+          source = File.join(root, "rust/src/generated")
+          Dir.children(source).each do |entry|
+            next if owned.include?(entry) || !File.directory?(File.join(source, entry))
+
+            FileUtils.rm_rf(File.join(scratch, "src/generated", entry))
+            FileUtils.cp_r(File.join(source, entry), File.join(scratch, "src/generated"))
+          end
+        end
+
+        # The gate: the scratch projection must match the generated sources and Cargo.toml on disk.
+        #
+        # @param scratch [String] the scratch crate, removed here
+        # @return [Integer] 0 when it matches, 1 after printing the difference
+        def verdict(scratch)
+          same = matches_scratch?(scratch)
+          FileUtils.rm_rf(scratch)
+          same ? 0 : 1
+        end
+
+        # @param scratch [String] the scratch crate
+        # @return [Boolean] whether it matches the tree, printing `git diff` output when it does not
+        def matches_scratch?(scratch)
+          pairs = [["rust/src/generated", File.join(scratch, "src/generated")],
+                   ["rust/Cargo.toml", File.join(scratch, "Cargo.toml")]]
+          pairs.map do |on_disk, projected|
+            out, status = Open3.capture2e("git", "diff", "--no-index", "--exit-code", "--", on_disk, projected)
+            print out
+            status.success?
+          end.all?
+        end
+      end
+    end
+  end
+end