hecks 3.2.0 → 3.3.0

data/lib/hecks/hecks/adapters/codebase/test_runner.rb

@@ -38,7 +38,9 @@ module Hecks
           status = Dir.chdir(@tree.root) { runner.call(["--example", example, path], out, out) }
           raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
-          out.string.strip
+          out.string.strip.tap do |report|
+            raise ConsoleCapture::Failure, "the test runner printed nothing for #{file}" if report.empty?
+          end
         end
 
         private
@@ -47,7 +49,13 @@ module Hecks
           return self.class.runner if self.class.runner
 
           require "rspec/core"
-          RSpec::Core::Runner.method(:run)
+          # A process that runs one example after another, as a resident door does, has to reset
+          # RSpec between runs: its reporter keeps the first run's output stream, so a later run
+          # would write into that and answer an empty report.
+          lambda do |args, err, out|
+            RSpec.reset
+            RSpec::Core::Runner.run(args, err, out)
+          end
         end
       end
     end

data/lib/hecks/hecks/adapters/first_admin.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../../doors/json_door"
+
+module Hecks
+  module Adapters
+    # Gives a booted domain its first administrator through the chapter that provides
+    # `"membership"`, the way a project's hand-written bootstrap script does.
+    #
+    # The chapter names its own verbs (`provides "membership", admit:, grant:, people:`), so no
+    # aggregate is recognised by name. Both dispatches run as a caller that asserts the role the
+    # command is gated to and binds no `actor_id`: Governance checks an identified caller against
+    # its role assignments, which a domain with no administrator cannot have yet, and checks an
+    # unidentified one by comparing the role named (ADR 0025). That is the bootstrap step, and it is
+    # refused once anyone holds an administrator role, so it cannot add a second.
+    class FirstAdmin
+      # The roles that count as an administrator besides the one the grant command is gated to.
+      OWNER_ROLES = %w[Owner].freeze
+
+      # What a bootstrap did.
+      #
+      # @!attribute [r] email
+      #   @return [String] who was granted access
+      # @!attribute [r] role
+      #   @return [String] the role they now hold
+      # @!attribute [r] admitted
+      #   @return [Boolean] whether the person had to be admitted first
+      Result = Struct.new(:email, :role, :admitted, keyword_init: true) do
+        # @return [String] the sentence the verb answers with
+        def to_s = "Granted #{role} access to #{email}#{' (admitted first)' if admitted}"
+      end
+
+      # @param runtime [Hecks::Runtime] the booted domain
+      def initialize(runtime)
+        @runtime = runtime
+        @registry = runtime.registry
+      end
+
+      # Admits the person if they are not yet, then grants them a role.
+      #
+      # @param email [String] the person's email, the membership aggregate's identity
+      # @param name [String, nil] their name; the part of the email before the `@` when nil
+      # @param role [String, nil] the role to grant; the one the grant command is gated to when nil
+      # @return [Result] what was done
+      # @raise [Runtime::NotFound] when the domain has no membership chapter, the email is not an
+      #   email, or an administrator already exists
+      def call(email:, name: nil, role: nil)
+        raise Runtime::NotFound, "#{email.inspect} is not an email address" unless email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+
+        provider = membership_provider
+        verbs    = verbs_of(provider)
+        gate     = gated_role(provider, verbs.fetch(:grant))
+        people   = rows(verbs.fetch(:people))
+        refuse_if_administered!(people, [gate, *OWNER_ROLES].uniq)
+
+        admitted = people.none? { |person| person.dig(:email, :value) == email }
+        admit(provider, verbs.fetch(:admit), email, name || email[/\A[^@]+/]) if admitted
+        grant(provider, verbs.fetch(:grant), email, role || gate)
+        Result.new(email: email, role: role || gate, admitted: admitted)
+      end
+
+      private
+
+      def membership_provider
+        domain = @registry.bluebooks.values.first&.name
+        @registry.membership_provider_for(domain) or
+          raise Runtime::NotFound, "this domain attaches no chapter that provides \"membership\""
+      end
+
+      def verbs_of(provider)
+        %i[admit grant people].to_h { |key| [key, provider.provided_verb(Bluebook::Capabilities::MEMBERSHIP, key)] }
+      end
+
+      def rows(verb) = @runtime.query(verb).map { |row| Doors::JsonDoor.materialize(row) }
+
+      # The role a verb's command declares, which the dispatch must assert to be let through.
+      def gated_role(provider, verb)
+        aggregate, command = verb.split("::").last.split(".")
+        found = provider.aggregates.find { |candidate| candidate.hecks_name == aggregate }
+                        &.commands&.find { |candidate| candidate.hecks_name == command }
+        found&.role&.to_s or raise Runtime::NotFound, "#{verb} declares no role to bootstrap as"
+      end
+
+      def refuse_if_administered!(people, roles)
+        held = people.select { |person| roles.map(&:downcase).include?(person.dig(:role, :value).to_s.downcase) }
+        return if held.empty?
+
+        who = held.map { |person| person.dig(:email, :value) }.join(", ")
+        raise Runtime::NotFound, "an administrator already exists (#{who}); grant roles through the " \
+                                 "domain's own #{roles.first} access instead"
+      end
+
+      def admit(provider, verb, email, name)
+        as(provider, verb) do
+          @runtime.dispatch(verb, with: { email: { value: email }, name: { value: name } })
+        end
+      end
+
+      def grant(provider, verb, email, role)
+        as(provider, verb) { @runtime.dispatch(verb, to: email, with: { role: { value: role } }) }
+      end
+
+      def as(provider, verb, &)
+        Hecks.as_caller(role: gated_role(provider, verb), &)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git.rb

@@ -60,6 +60,55 @@ module Hecks
         { report: { value: out.string } }
       end
 
+      # Checks a project's vendored packages against their `bluebook.lock` files and describes
+      # them as the manifest a client image carries, through `Hecks::EmbryonautBluebook::Manifest`.
+      #
+      # The manifest records the project's own commit and whether its tree has uncommitted changes,
+      # read from the repository the project stands in (`unknown` outside one).
+      #
+      # @param held [Hash] the `Package` query's arguments: `root` (the project; the current
+      #   directory when absent)
+      # @return [Hash{Symbol => String}] `text:` the manifest as JSON
+      # @raise [Runtime::NotFound] naming each package whose files disagree with its lock
+      def verify(**held)
+        root = File.expand_path(plain(held[:root]) || Dir.pwd)
+        raise Runtime::NotFound, "#{root} is not a directory" unless File.directory?(root)
+
+        { text: EmbryonautBluebook::Manifest.new(root, built_from: built_from(root)).to_json_text }
+      rescue EmbryonautBluebook::Manifest::Mismatch => e
+        raise Runtime::NotFound, e.message
+      end
+
+      # Judges every package of a bluebook registry against its latest release, through
+      # `Hecks::EmbryonautBluebook::Registry#check`.
+      #
+      # @param held [Hash] the `Registry` query's arguments: `root` (the registry; the current
+      #   directory when absent)
+      # @return [Hash{Symbol => String}] `text:` the notes and `versions ok`
+      # @raise [Runtime::NotFound] naming each package at fault, or when `root` is no repository
+      def check(**held)
+        report = registry(held).check
+        raise Runtime::NotFound, report.to_s unless report.ok?
+
+        { text: report.to_s }
+      rescue Vendoring::Error => e
+        raise Runtime::NotFound, e.message
+      end
+
+      # Tags a package of a bluebook registry at the version its `bluebook.yml` carries, through
+      # `Hecks::EmbryonautBluebook::Registry#release`. The tag is made in the local repository and
+      # never pushed.
+      #
+      # @param held [Hash] the `Registry` record: `package`, and `root` (the current directory when
+      #   absent)
+      # @return [Hash{Symbol => Hash}] `report:` the tag made and the command that publishes it
+      # @raise [ConsoleCapture::Failure] when the package breaks a release rule
+      def tag(**held)
+        { report: { value: registry(held).release(plain(held[:package])).to_s } }
+      rescue Vendoring::Error => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
       # Who the repository at a directory commits as: its configured name and email.
       #
       # @param chdir [String, nil] a directory inside the repository; the current one when nil
@@ -87,6 +136,16 @@ module Hecks
 
       private
 
+      def registry(held)
+        EmbryonautBluebook::Registry.new(File.expand_path(plain(held[:root]) || Dir.pwd))
+      end
+
+      def built_from(root)
+        head = capture("rev-parse", "HEAD", chdir: root)
+        status = capture("status", "--porcelain", "--", ".", chdir: root)
+        { "commit" => head.ok? ? head.out.strip : "unknown", "dirty" => status.ok? && !status.out.strip.empty? }
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
 
       # A source that is not a repository is worded here; the vendoring's own refusal for it is a

data/lib/hecks/hecks/adapters/in_process_access.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "first_admin"
+
+module Hecks
+  module Adapters
+    # What the `DomainRuntime` port's adapter does when an `Operation` asks it to give a domain its
+    # first administrator.
+    module InProcessAccess
+      # Boots the domain and grants the first administrator through its membership chapter.
+      #
+      # @param held [Hash] the `Operation` record: `subject` (the domain), `email`, and optionally
+      #   `name` and `role`
+      # @return [Hash{Symbol => Hash}] `output:` the sentence saying who now holds which role
+      # @raise [Runtime::NotFound] if the domain cannot be found or has no membership chapter, or an
+      #   administrator already exists
+      def bootstrap(**held)
+        result = FirstAdmin.new(boot(held[:subject])).call(
+          email: plain(held[:email]), name: plain(held[:name]), role: plain(held[:role])
+        )
+        output(result.to_s)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/in_process_boot.rb

@@ -9,6 +9,7 @@ require_relative "../../cli/stores"
 require_relative "../../cli/shape"
 require_relative "../../cli/history"
 require_relative "in_process_operations"
+require_relative "in_process_access"
 
 module Hecks
   module Adapters
@@ -25,6 +26,7 @@ module Hecks
     # a projection refresh, a behaviors run, a smoke test and a bounded follow.
     class InProcessBoot
       include InProcessOperations
+      include InProcessAccess
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #

data/lib/hecks/hecks/adapters/rust_toolchain.rb

@@ -19,9 +19,9 @@ module Hecks
     # minutes, so it starts as a child through `ProcessPool`.
     class RustToolchain
       # The `Hecks::RustBuild` tool each ask runs.
-      TOOLS = { generate: "project_rust", wasm: "project_wasm", browser_wasm: "project_wasm_browser",
-                conform: "rust_conformance", replay: "rust_conformance_fuzz",
-                coverage: "rust_coverage" }.freeze
+      TOOLS = { generate: "project_rust", wasm: "project_wasm", host: "project_host",
+                browser_wasm: "project_wasm_browser", conform: "rust_conformance",
+                replay: "rust_conformance_fuzz", coverage: "rust_coverage" }.freeze
 
       # The load path the benchmark child runs with: this checkout's or gem's `lib/`.
       LIB = File.expand_path("../../..", __dir__)
@@ -73,6 +73,21 @@ module Hecks
         child(:wasm, [plain(held[:domain])])
       end
 
+      # Generates the domain, compiles it to a `wasm32-wasip1` module, builds the host binary from
+      # the workspace and stages the three files in a directory an image copies from.
+      #
+      # @param held [Hash] the `Build` record: `domain`, `target` (the machine's own when absent)
+      #   and `stage_dir` (`.hecks/host/<target>/` when absent)
+      # @return [Hash{Symbol => Hash}] `output:` where the files were staged
+      # @raise [ConsoleCapture::Failure] when the toolchain or the target is missing, or a step
+      #   fails
+      def host(**held)
+        argv = [plain(held[:domain])]
+        argv << "--target=#{plain(held[:target])}" if plain(held[:target])
+        argv << "--stage=#{plain(held[:stage_dir])}" if plain(held[:stage_dir])
+        child(:host, argv)
+      end
+
       # Generates the domain, then compiles it to an ES module for a browser through wasm-bindgen.
       #
       # @param held [Hash] the `Build` record: `domain`

data/lib/hecks/hecks/adapters/rust_workspace.rb

@@ -22,7 +22,7 @@ module Hecks
       CHECKOUT_MARKER = "hecks.gemspec"
 
       # What a copy holds: the workspace manifest, the kernel and every crate a domain build uses.
-      PACKAGED = %w[Cargo.toml Cargo.lock project.rb project_rust_pipeline.rb project src codegen parser
+      PACKAGED = %w[Cargo.toml Cargo.lock src codegen parser
                     host build web lsp].freeze
 
       # Left out of a copy: build output anywhere, the corpus tests, and the corpus domains.

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -1,21 +1,29 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "console_capture"
+require_relative "shell"
 require_relative "codebase/tree"
 require_relative "codebase/ruby_child"
+require "hecks/tools"
+require "hecks/tools/site_routes"
+require "hecks/projections/site/live_edge"
 
 module Hecks
   module Adapters
     # The `SiteToolchain` port's adapter: projects a site's route table into its `routes.ts`, or
     # checks the file on disk is current.
     #
-    # The projection runs the `project_site` tool in a child of the checkout, with its printing and
-    # exit status captured: a tool that ends non-zero is a refusal whose reason is what it printed.
-    # Outside a hecks checkout the ask is refused with "needs a hecks checkout".
+    # The projection runs the `project_site` tool in this process, with its printing and exit status
+    # captured: a tool that ends non-zero is a refusal whose reason is what it printed. The tool
+    # ships in the gem and reads only the project it is given, so it needs no hecks checkout.
     class SiteToolchain
       # The `Hecks::Tools` tool the ask runs, by ask.
       SCRIPTS = { project: "project_site" }.freeze
 
+      # The tool's flag for each `SiteProjection` field that takes a value.
+      FLAGS = { "out" => :out, "template" => :template, "extension" => :extension }.freeze
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -25,29 +33,98 @@ module Hecks
 
       # Writes a project's `routes.ts` from its declared route table, or with `check` only compares.
       #
-      # @param held [Hash] the `SiteProjection` record: `domain`, and `out` and `check` when set
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `out`, `template`, `extension`
+      #   and `check` when set
       # @return [Hash{Symbol => Hash}] `output:` one line per file written or found current
-      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, the route table is
-      #   refused (an unknown cache class, a duplicate path), or under `check` a file is out of date
+      # @raise [ConsoleCapture::Failure] when the route table is refused (an unknown cache class,
+      #   a duplicate path), a path or the extension is refused, or under `check` a file is out
+      #   of date
       def project(**held)
-        flags = []
-        flags << "--out=#{plain(held[:out])}" unless plain(held[:out]).nil?
+        flags = FLAGS.filter_map { |flag, key| "--#{flag}=#{located(key, held[key])}" unless plain(held[key]).nil? }
         flags << "--check" if plain(held[:check]) == true
-        tree = Codebase::Tree.new
-        tree.require_checkout!
-        result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(:project), *flags, plain(held[:domain]))
+        result = Codebase::RubyChild.new(Codebase::Tree.new).capture(SCRIPTS.fetch(:project), *flags,
+                                                                     located(:domain, held[:domain]))
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?
 
         { output: { value: result.out } }
       end
 
+      # Compares the CloudFront behaviours a project's edge generates with a live distribution's.
+      # The live configuration is read from a saved `get-distribution-config` answer (`live`) or
+      # fetched with that one read-only call (`distribution`, the distribution's id); nothing is
+      # changed on either side.
+      #
+      # @param held [Hash] the `SiteProjection` record: `domain`, and `live` or `distribution`,
+      #   with `expect_new` (path patterns, comma separated) and `refs` (`!Ref Name=id` words,
+      #   comma separated) when set
+      # @return [Hash{Symbol => Hash}] `output:` the report of a distribution that matches
+      # @raise [ConsoleCapture::Failure] when the project has no edge, the live configuration
+      #   cannot be read, or the two differ; the message is the report
+      def compare(**held)
+        edge = edge_of(located(:domain, held[:domain]))
+        live = live_configuration(held)
+        live_edge = Projections::Site::LiveEdge
+        comparison = live_edge.new(edge, live, expect_new: words(held[:expect_new]),
+                                               refs:       live_edge.refs_from(plain(held[:refs]))).call
+        raise ConsoleCapture::Failure, comparison.to_s unless comparison.clean?
+
+        { output: { value: comparison.to_s } }
+      end
+
       private
 
+      # The project's checked edge, read the way `project_site` reads it.
+      def edge_of(root)
+        registry = nil
+        outcome = ConsoleCapture.capture { registry = Tools::SiteRoutes.registry_for(root) }
+        raise ConsoleCapture::Failure, outcome.output.strip unless outcome.ok?
+
+        site = Projections::Site
+        chapter = site::Table.chapter(registry)
+        table = site::Table.read(chapter, registry: registry)
+        site::Edge.read(chapter, table: table, vocabulary: site::Table.vocabulary(registry)) ||
+          raise(ConsoleCapture::Failure, "#{root} declares no Edge rows")
+      rescue Projections::Site::Table::Invalid => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
+      def live_configuration(held)
+        file = plain(held[:live])
+        id = plain(held[:distribution])
+        text = file ? read_saved(file) : fetch(id)
+        JSON.parse(text)
+      rescue JSON::ParserError => e
+        raise ConsoleCapture::Failure, "the live configuration is not JSON: #{e.message.lines.first.strip}"
+      end
+
+      def read_saved(path)
+        File.read(File.expand_path(path))
+      rescue SystemCallError => e
+        raise ConsoleCapture::Failure, "cannot read the live configuration: #{e.message}"
+      end
+
+      # The one AWS call: reading a distribution's configuration.
+      def fetch(id)
+        result = Shell.new.capture("aws", "cloudfront", "get-distribution-config", "--id", id.to_s)
+        return result.out if result.ok?
+
+        raise ConsoleCapture::Failure, "aws cloudfront get-distribution-config failed: #{message_of(result)}"
+      end
+
+      def words(argument) = plain(argument).to_s.split(",").map(&:strip).reject(&:empty?)
+
       def message_of(result)
         text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
         text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
       end
 
+      # The tool runs from the tool's own root, so a path the caller gave relative to where they
+      # stand is made absolute first; the extension is not a path.
+      def located(key, argument)
+        value = plain(argument)
+        value.nil? || key == :extension ? value : File.expand_path(value)
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end

data/lib/hecks/hecks/codebase.behaviors

@@ -85,6 +85,12 @@ Hecks.behaviors "Codebase" do
     expect refused: "must match"
   end
 
+  test "ProjectToolsDoc refuses a run that is not named" do
+    tests "ProjectToolsDoc", on: "RegenerationRun"
+    input run: { value: "" }
+    expect refused: "must match"
+  end
+
   test "DecideCiGate refuses a run that is not named" do
     tests "DecideCiGate", on: "RegenerationRun"
     input run: { value: "" }, gate: { value: "runtime_changed" }

data/lib/hecks/hecks/codebase.bluebook

@@ -1027,6 +1027,22 @@ Hecks.bluebook "Hecks" do
       emits ProjectCiGatesRequested
     end
 
+    command "ProjectToolsDoc" do
+      role "Maintainer"
+      goal "Write the launcher forms of docs/tools.md from the RetiredScript rows, or with check only compare them"
+
+      attribute :check,   Switch, optional: true
+      attribute :run,     RunKey
+      attribute :confirm, Switch, optional: true
+
+      sets :check
+      sets :run
+      sets :confirm
+      sets :operation, to: "project_tools_doc"
+
+      emits ProjectToolsDocRequested
+    end
+
     command "DecideCiGate" do
       role "Maintainer"
       goal "Say whether this run's change touches what a CiGate row guards, as the gated job's detector"
@@ -1105,6 +1121,11 @@ Hecks.bluebook "Hecks" do
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
   end
 
+  policy "ExamineWhenProjectToolsDocRequested" do
+    on      "RegenerationRun.ProjectToolsDocRequested"
+    trigger RegenerationRun::SourceTree::Examine, with: { run: :run }
+  end
+
   policy "ExamineWhenDecideCiGateRequested" do
     on      "RegenerationRun.DecideCiGateRequested"
     trigger RegenerationRun::SourceTree::Examine, with: { run: :run }

data/lib/hecks/hecks/custodian.behaviors

@@ -176,4 +176,10 @@ Hecks.behaviors "Custodian" do
     input domain: { value: "examples/pizzas" }, run: { value: "" }
     expect refused: "must match"
   end
+
+  test "BuildHost refuses a target that is not a triple" do
+    tests "BuildHost", on: "Build"
+    input domain: { value: "examples/pizzas" }, run: { value: "host" }, target: { value: "arm64" }
+    expect refused: "must match"
+  end
 end