hecks 2.8.0 → 3.0.0

data/lib/hecks/hecks/adapters/deploy_toolchain.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "console_capture"
+require_relative "codebase/tree"
+require_relative "codebase/ruby_child"
+require "hecks/projections/deploy/template_diff"
+
+module Hecks
+  module Adapters
+    # The `DeployToolchain` port's adapter: generates a domain's deploy recipe, lints and compares
+    # what was generated, and projects the OIDC manifests.
+    #
+    # The recipe, the lint and the manifests run the `Hecks::Tools` tool that already does the work,
+    # 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. They write into a hecks checkout, so outside one the
+    # ask is refused with "needs a hecks checkout". A comparison needs no checkout.
+    class DeployToolchain
+      # The `Hecks::Tools` tool an ask runs, by ask.
+      SCRIPTS = { generate: "project_deploy", lint: "lint_deploy_recipes", manifest: "project_oidc" }.freeze
+
+      # `hecks deploy project`'s flag for each `Recipe` field it takes.
+      GENERATE_FLAGS = { "--tenant" => :tenant, "--schema" => :schema, "--out" => :out,
+                         "--environment" => :environment }.freeze
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Writes a domain's deploy recipe (the template, scripts and Makefile) from its declared
+      # `deployed_to` target, through `hecks deploy project`.
+      #
+      # @param held [Hash] the `Recipe` record: `domain`, and `tenant`, `schema`, `out` and
+      #   `environment` when set
+      # @return [Hash{Symbol => Hash}] `output:` one line per file written
+      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, or the generator refuses
+      #   (no `deployed_to` target, conflicting settings, a schema with no tenant)
+      def generate(**held)
+        flags = GENERATE_FLAGS.filter_map { |flag, key| "#{flag}=#{plain(held[key])}" unless plain(held[key]).nil? }
+        child(:generate, [*flags, plain(held[:domain])])
+      end
+
+      # Lints generated deploy Makefiles for prod-touching recipes that hide failure, through
+      # `hecks deploy lint`.
+      #
+      # @param held [Hash] the `MakefileCheck` record: `makefiles` (comma separated paths; three
+      #   generated fixture domains when absent)
+      # @return [Hash{Symbol => Hash}] `report:` what the linter printed
+      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, or the linter found a
+      #   violation; the message is its report
+      def scan(**held)
+        paths = plain(held[:makefiles]).to_s.split(",").map(&:strip).reject(&:empty?)
+        { report: { value: child(:lint, paths).dig(:output, :value) } }
+      end
+
+      # Projects each domain's OIDC client and scope manifest into its `oidc.json`, through
+      # `hecks deploy project_oidc`.
+      #
+      # @param held [Hash] the `OidcManifest` record: `domains` (comma separated directories; every
+      #   domain of the checkout when absent)
+      # @return [Hash{Symbol => Hash}] `output:` one line per manifest written or skipped
+      # @raise [ConsoleCapture::Failure] when the tree is not a checkout
+      def manifest(**held)
+        domains = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
+        child(:manifest, domains)
+      end
+
+      # Compares two CloudFormation templates by logical id, in this process.
+      #
+      # A difference is an answer, not a refusal: `different:` says whether there was one, and
+      # the record decides what a difference means.
+      #
+      # @param held [Hash] the `TemplateComparison` record: `before`, `after`, and `json` and
+      #   `strict` when set
+      # @return [Hash{Symbol => Hash}] `report:` the comparison as text (JSON when `json`), and
+      #   `different:` whether the templates differ
+      # @raise [ConsoleCapture::Failure] when a template is missing or is not a template
+      def compare(**held)
+        diff = Projections::Deploy::TemplateDiff
+        report = diff.diff_files(plain(held[:before]), plain(held[:after]), strict: plain(held[:strict]) == true)
+        text = plain(held[:json]) == true ? diff.render_json(report) : diff.render(report)
+        { report: { value: text }, different: { value: report.different? } }
+      rescue ArgumentError => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
+      private
+
+      def child(ask, argv)
+        tree = Codebase::Tree.new
+        tree.require_checkout!
+        result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(ask), *argv)
+        raise ConsoleCapture::Failure, message_of(result) unless result.ok?
+
+        { output: { value: result.out } }
+      end
+
+      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
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/git"
+
+Hecks.adapter "Git" do
+  port "Git"
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "shell"
+require_relative "console_capture"
+require_relative "codebase/publishing"
+require "hecks/vendoring/git_environment"
+require "hecks/embryonaut_bluebook/vendor_cli"
+
+module Hecks
+  module Adapters
+    # The `Git` port's adapter: the calls a Custodian command makes to `git`.
+    #
+    # Every call runs under `Vendoring::GitEnvironment.clean`, so a `GIT_DIR` inherited from a hook
+    # or a parent process cannot redirect it to another repository. Subprocesses start through the
+    # `Shell` adapter.
+    class Git
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @shell = Shell.new
+      end
+
+      # Runs `git` in a directory.
+      #
+      # @param args [Array<String>] the git subcommand and its arguments
+      # @param chdir [String, nil] the directory to run in
+      # @return [Shell::Result] what git said and how it ended
+      def capture(*, chdir: nil)
+        @shell.capture("git", *, env: Vendoring::GitEnvironment.clean, chdir: chdir)
+      end
+
+      # Vendors one package of the bluebook registry into a project, pinned to a release or a
+      # commit, through `Hecks::EmbryonautBluebook::VendorCli`.
+      #
+      # The source is `from`, else `EMBRYONAUT_BLUEBOOKS_SRC`; the project is `root`, else the
+      # current directory. `ALLOW_DOWNGRADE=1` lets an older release through, as for the script.
+      #
+      # @param held [Hash] the `Package` record: `package` (`name` or `name@version-or-commit`),
+      #   `from` and `root`
+      # @return [Hash{Symbol => Hash}] `report:` what was vendored and whether its storage shape
+      #   changed
+      # @raise [ConsoleCapture::Failure] when the source is not a git repository, or the vendoring
+      #   was refused (no such release, a downgrade, an era-breaking shape change)
+      def pin(**held)
+        from = plain(held[:from]) || ENV.fetch("EMBRYONAUT_BLUEBOOKS_SRC", nil)
+        root = plain(held[:root]) || Dir.pwd
+        require_repository!(from)
+
+        argv = [plain(held[:package])]
+        argv += ["--from", from] if from
+        out = StringIO.new
+        err = StringIO.new
+        status = EmbryonautBluebook::VendorCli.run(argv + ["--root", root], out: out, err: err, root: root)
+        raise ConsoleCapture::Failure, err.string.strip unless status.zero?
+
+        { report: { value: out.string } }
+      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
+      # @return [String] `Name <email>`, or whichever half is configured
+      # @raise [ConsoleCapture::Failure] when git has neither a name nor an email configured
+      def identity(chdir: nil)
+        name  = capture("config", "user.name", chdir: chdir).out.strip
+        email = capture("config", "user.email", chdir: chdir).out.strip
+        who = [name, (email.empty? ? nil : "<#{email}>")].compact.reject(&:empty?).join(" ")
+        raise ConsoleCapture::Failure, "git has no user.name or user.email configured to approve as" if who.empty?
+
+        who
+      end
+
+      # The facts a release of this repository is judged by: branch, tree, versions, changelog and
+      # where a tag stands. The rules that judge them are the givens of `PublishingRun.Clear`.
+      #
+      # @param held [Hash] the `PublishingRun` record: `operation`
+      # @return [Hash] each fact, as `Codebase::ReleaseFacts` reads it
+      # @raise [ConsoleCapture::Failure] when git or a file cannot be read
+      def survey(**held)
+        commands = Codebase::Publishing.commands || Hecks::Release::Runner::Commands.new
+        Codebase::ReleaseFacts.new(Codebase::Tree.new, commands: commands).gather(plain(held[:operation]))
+      end
+
+      private
+
+      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
+      # bare "no commit" that names neither the directory nor the cause.
+      def require_repository!(from)
+        return unless from && File.directory?(from)
+        return if capture("rev-parse", "--git-dir", chdir: from).ok?
+
+        raise ConsoleCapture::Failure, "#{from} is not a git repository"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/host_http.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/host_http"
+
+Hecks.adapter "HostHttp" do
+  port "HostHttp"
+end

data/lib/hecks/hecks/adapters/host_http.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "console_capture"
+require "hecks/cli/smoke_http"
+require "hecks/cli/check_era"
+
+module Hecks
+  module Adapters
+    # The `HostHttp` port's adapter: talks HTTP to a running service on an operator's behalf, to
+    # sign a webhook against it (`probe`) or to read the era it reports (`fetch`).
+    #
+    # The signing secret is read from `SMOKE_WEBHOOK_SECRET` and never from a command argument,
+    # so it is not written to the journal or shown by `ps`.
+    class HostHttp
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Runs the signed-webhook and idempotency checks against a service.
+      #
+      # @param held [Hash] the `Operation` record: `url`, `path`, `header`, `scheme`, `payload`,
+      #   `payload_file`, `health_path` and `state_path`
+      # @return [Hash{Symbol => Hash}] `output:` the checks as reported
+      # @raise [ArgumentError] if the path or the secret is missing, or the scheme is unknown
+      # @raise [ConsoleCapture::Failure] when any check failed
+      def probe(**held)
+        options = %i[url path header scheme payload health_path state_path].to_h { |name| [name, plain(held[name])] }
+        options[:payload] ||= File.read(plain(held[:payload_file])) if plain(held[:payload_file])
+
+        out = StringIO.new
+        status = CLI::SmokeHttp.new(CLI::SmokeHttp.resolve(options.compact, ENV), out: out).run
+        raise ConsoleCapture::Failure, out.string.strip unless status.zero?
+
+        { output: { value: out.string } }
+      end
+
+      # Reads the version and era a running `rust/host` reports and compares the era with an
+      # allow-list file. A mismatch is an answer, not a refusal: the record keeps what was found.
+      #
+      # @param held [Hash] the `Host` record: `host` (the base URL), `expected` (the allow-list
+      #   file) and `timeout` (seconds; 10 when absent)
+      # @return [Hash{Symbol => Hash}] `era:`, `version:`, `verdict:` (`match`, `unlisted` or
+      #   `mismatch`) and `report:` (the sentence `hecks check_era` prints)
+      # @raise [ArgumentError] if no allow-list file was named
+      # @raise [Errno::ENOENT] if the allow-list 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 fetch(**held)
+        file = plain(held[:expected]) or raise ArgumentError, "no allow-list file to compare the era with"
+        finding = CLI::CheckEra.assess(plain(held[:host]), file, timeout: (plain(held[:timeout]) || 10).to_f)
+
+        { era: { value: finding.verdict.era }, version: { value: finding.version },
+          verdict: { value: finding.verdict.status.to_s }, report: { value: finding.line } }
+      end
+
+      private
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/in_process_boot.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/in_process_boot"
+
+Hecks.adapter "InProcessBoot" do
+  port "DomainRuntime"
+end

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks"
+# A domain wired to PostgresEra needs this plugin loaded explicitly, and the `:shape` projection
+# reads `Runtime::StorageShape` from it (ADR 0033).
+require_relative "../../ports/persistence/plugins/era"
+require_relative "../../cli/stores"
+require_relative "../../cli/shape"
+require_relative "../../cli/history"
+require_relative "in_process_operations"
+
+module Hecks
+  module Adapters
+    # The `DomainRuntime` port's adapter: boots a target domain in this process and answers what
+    # Custodian's Introspection queries ask about it.
+    #
+    # Each method returns the text the matching tool prints, so the launcher shows the
+    # same bytes; a projection that would have written files answers a map of file name to text
+    # instead. Arguments arrive materialized, so a value object is `{ value: "x" }`. A domain or
+    # chapter that cannot be found raises `Runtime::NotFound`, which the launcher words as a
+    # refusal.
+    #
+    # It also answers the asks of journaled commands (`InProcessOperations`): a model check, a run,
+    # a projection refresh, a behaviors run, a smoke test and a bounded follow.
+    class InProcessBoot
+      include InProcessOperations
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # @param domain [Hash, String, nil] a domain directory; the nearest enclosing one when absent
+      # @param translations [Boolean] only the translations, not the whole IR
+      # @param meta [Boolean] the language's own IR, not a domain's
+      # @return [Hash] `text:` the IR as JSON
+      # @raise [Runtime::NotFound] if the domain cannot be found
+      def ir(domain: nil, translations: false, meta: false)
+        if meta
+          require_relative "../../bluebook/meta_validator"
+          return report(Projector::Exporter.json(Bluebook::MetaValidator.grammar_registry))
+        end
+
+        registry = boot(domain).registry
+        report(translations ? Projector::Exporter.translations_json(registry) : Projector::Exporter.json(registry))
+      end
+
+      # @param domain [Hash, String] a bluebook file, or a directory of them
+      # @return [Hash] `text:` the storage-shape projection as JSON for a file, or
+      #   one `<Domain> <label>` line per domain for a directory
+      # @raise [Runtime::NotFound] if the path does not exist or holds no bluebook
+      def shape(domain:)
+        report(CLI::Shape.render(plain(domain)))
+      end
+
+      # @param domain [Hash, String] a domain directory
+      # @return [Hash] `text:` every aggregate's current records as one JSON document
+      # @raise [Runtime::NotFound] if the domain cannot be found
+      def stores(domain:)
+        registry = boot(domain).registry
+        stores = registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            all[aggregate.storage_name] = CLI::Stores.data_for(registry.repository(name, aggregate))
+          end
+        end
+
+        report(JSON.generate(stores))
+      end
+
+      # @param domain [Hash, String] a domain directory
+      # @return [Hash] `text:` every journal entry the domain's append-only adapters
+      #   hold, as JSON
+      # @raise [Runtime::NotFound] if the domain cannot be found
+      def history(domain:)
+        report(JSON.generate(CLI::History.document(boot(domain).registry)))
+      end
+
+      # @param domain [Hash, String] a domain directory
+      # @param chapter [Hash, String] the chapter's name
+      # @return [Hash] `text:` the chapter's declared facts, one sentence a line
+      # @raise [Runtime::NotFound] if the domain or chapter cannot be found
+      def statements(domain:, chapter:)
+        report(Projector.call(:statements, bluebook: chapter_of(domain, chapter)).join("\n"))
+      end
+
+      # @param domain [Hash, String, nil] a domain directory; the nearest enclosing one when absent
+      # @param aggregate [Hash, String, nil] narrate only this aggregate
+      # @return [Hash] `text:` the domain in English
+      # @raise [Runtime::NotFound] if the domain or aggregate cannot be found
+      def narrate(domain: nil, aggregate: nil)
+        document(:narrate, domain, aggregate)
+      end
+
+      # @param domain [Hash, String, nil] a domain directory; the nearest enclosing one when absent
+      # @param aggregate [Hash, String, nil] document only this aggregate
+      # @return [Hash] `text:` the domain's usage document
+      # @raise [Runtime::NotFound] if the domain or aggregate cannot be found
+      def docs(domain: nil, aggregate: nil)
+        document(:docs, domain, aggregate)
+      end
+
+      # @param domain [Hash, String] a domain directory
+      # @param chapter [Hash, String] the chapter's name
+      # @return [Array<Hash{Symbol => String}>] one `name:`/`text:` row per diagram file
+      # @raise [Runtime::NotFound] if the domain or chapter cannot be found
+      def project_diagrams(domain:, chapter:)
+        runtime = boot(domain)
+        name    = plain(chapter)
+        options = { hecksagon: runtime.registry.hecksagon(name) }
+
+        projected_files(Projector.call(:diagrams, bluebook: chapter_in(runtime, name), options: options))
+      end
+
+      # @param domain [Hash, String] a domain directory
+      # @param chapter [Hash, String] the chapter's name
+      # @return [Array<Hash{Symbol => String}>] one `name:`/`text:` row per glossary file
+      # @raise [Runtime::NotFound] if the domain or chapter cannot be found
+      def glossary(domain:, chapter:)
+        runtime = boot(domain)
+        name    = plain(chapter)
+        markings = runtime.registry.pending_privacy_markings.select do |marking|
+          marking[:domain].to_s.start_with?("#{name}::")
+        end
+
+        projected_files(Projector.call(:glossary, bluebook: chapter_in(runtime, name),
+                                                  options:  { markings: markings }))
+      end
+
+      # One generated, valid dispatch sequence for a domain, through the generator `hecks fuzz`
+      # draws from. The fuzzing toolkit is loaded here, on the first ask, and never by a boot.
+      #
+      # @param domain [Hash, String] a domain directory
+      # @param seed [Integer, nil] the generator's seed (1 when absent)
+      # @param steps [Integer, nil] how many steps to ask for (30 when absent)
+      # @param adversarial [Float, nil] the fraction of steps mutated to be refused (0.0 if none)
+      # @return [Hash] `text:` a replayable script as JSON: its name, a note on how it
+      #   was made, its steps
+      # @raise [Runtime::NotFound] if the domain cannot be found
+      def generate_sequence(domain:, seed: nil, steps: nil, adversarial: nil)
+        require "hecks/fuzzing"
+        target = plain(domain)
+        raise Runtime::NotFound, "no such domain #{target.inspect}" unless File.exist?(target)
+
+        seed ||= 1
+        steps ||= 30
+        generated = Fuzzing::SequenceGenerator.generate(target, seed: seed, steps: steps,
+                                                                adversarial: adversarial || 0.0)
+        script = { name:  "#{File.basename(target)}-generated",
+                   note:  "generated by hecks generate_sequence: seed #{seed}, #{steps} steps " \
+                          "requested (#{generated.length} produced)",
+                   steps: generated }
+        report(JSON.pretty_generate(script))
+      end
+
+      private
+
+      # A value object arrives as `{ value: x }`; a bare argument is already plain.
+      def plain(argument)
+        argument.is_a?(Hash) ? argument[:value] : argument
+      end
+
+      # Boots the domain at `domain`, or at the nearest enclosing domain directory when absent.
+      def boot(domain)
+        path = plain(domain) || Adapters::Folder.new.domain_root
+        raise Runtime::NotFound, "no domain here, and none named" unless path
+        raise Runtime::NotFound, "no such domain #{path.inspect}" unless Dir.exist?(path)
+
+        Hecks.boot(File.expand_path(path), install_doors: false)
+      end
+
+      def chapter_of(domain, chapter)
+        chapter_in(boot(domain), plain(chapter))
+      end
+
+      def chapter_in(runtime, name)
+        runtime.registry.bluebook(name) or raise Runtime::NotFound, "no chapter named #{name}"
+      end
+
+      # The domain's own chapter, not a framework member it attached: insertion order.
+      def document(projection, domain, aggregate)
+        bluebook = boot(domain).registry.bluebooks.values.first or raise Runtime::NotFound, "no bluebook loaded"
+        name = plain(aggregate)
+
+        report(Projector.call(projection, bluebook: bluebook, options: name ? { aggregate: name } : {}))
+      end
+
+      # The `Document` a query returns: one document of text.
+      def report(text) = { text: text }
+
+      # The `ProjectedFile` rows a projection that would have written files answers instead.
+      def projected_files(files) = files.map { |name, text| { name: name, text: text } }
+    end
+  end
+end