hecks 5.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/doctor_reading/report.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class DoctorReading
+      # Formats the checks: one line each, the fix beneath any check that is not ok.
+      module Report
+        private
+
+        def render(rows)
+          lines = rows.map { |name, status, detail, fix| line(name, status, detail, fix) }
+          (lines + ["status: #{worst(rows)}"]).join("\n")
+        end
+
+        def worst(rows)
+          statuses = rows.map { |row| row[1] }
+          statuses.max_by { |status| %i[ok warn fail].index(status) }
+        end
+
+        def line(name, status, detail, fix)
+          head = format("%<state>-5s %<name>-16s %<detail>s", state: status.to_s.upcase, name: name, detail: detail)
+          fix ? "#{head}\n      fix: #{fix}" : head
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/doctor_reading.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/doctor_reading"
+
+Hecks.adapter "DoctorReading" do
+  port "Doctor"
+end

data/lib/hecks/hecks/adapters/doctor_reading.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "hecks"
+require "open3"
+require "uri"
+require_relative "doctor_reading/report"
+
+module Hecks
+  module Adapters
+    # The `Doctor` port's adapter for `Checkout`: one line per check of whether this copy can run
+    # Hecks here, each with the fix when it is not ok. It reads and never writes: it does not boot
+    # a domain (a boot can mint an era), write to a store, or call GitHub.
+    class DoctorReading
+      include Report
+
+      # The channel a rust-toolchain.toml pins.
+      FIRST_LINE = /\A[^\n]*/
+
+      CHANNEL_PIN = /channel\s*=\s*"([^"]+)"/
+
+      # 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 held [Hash] `domain`, a checkout directory (the current directory when absent)
+      # @return [Hash{Symbol => String}] `text:` one line per check and the overall status
+      def doctor(**held)
+        directory = plain(held[:domain]) || Dir.pwd
+        rows = [overlays(directory), worktree(directory), toolchain(directory),
+                database(directory), version(directory)]
+        { text: render(rows) }
+      end
+
+      private
+
+      # Each row is [name, status, detail, fix], where status is :ok, :warn or :fail.
+      def overlays(directory)
+        files = overlay_files(directory)
+        bad = files.filter_map { |path| (error = syntax_error(path)) && [File.basename(path), error] }
+        return row("overlay files", :ok, "#{files.size} read") if bad.empty?
+
+        name, error = bad.first
+        row("overlay files", :fail, "#{name} does not parse: #{error}", "fix the syntax in #{name}")
+      end
+
+      def overlay_files(directory)
+        [directory, Dir.pwd].uniq.flat_map { |where| Dir[File.join(where, "*.local.{world,hecksagon}")] }.uniq
+      end
+
+      # The first line of a compile error, or nil when the file is valid Ruby. Compiling never runs it.
+      def syntax_error(path)
+        RubyVM::InstructionSequence.compile(File.read(path), path)
+        nil
+      rescue SyntaxError => e
+        first_line(e)
+      end
+
+      def worktree(directory)
+        out, status = Open3.capture2e("git", "-C", directory, "rev-parse", "--git-dir", "--git-common-dir")
+        return row("worktree", :warn, "not a git checkout", "run from a hecks checkout") unless status.success?
+
+        git_dir, common = out.lines.map(&:strip)
+        return row("worktree", :ok, "main checkout") if git_dir == common
+
+        unseen_overlays(directory, File.dirname(File.expand_path(common, directory)))
+      end
+
+      def unseen_overlays(directory, main)
+        here = Dir[File.join(directory, "lib/hecks/hecks/*.local.*")]
+        there = Dir[File.join(main, "lib/hecks/hecks/*.local.*")]
+        return row("worktree", :ok, "linked worktree sees the main checkout's overlays") if here.any? || there.empty?
+
+        row("worktree", :warn, "linked worktree cannot see #{there.size} overlay file(s) in #{main}",
+            "run from #{main}")
+      end
+
+      def toolchain(directory)
+        pin = File.read(File.join(directory, "rust-toolchain.toml"))[CHANNEL_PIN, 1]
+        installed = rustc_version
+        return row("toolchain", :warn, "rustc not on PATH", "install the pinned toolchain with rustup") unless installed
+        return row("toolchain", :ok, installed) if pin && installed.include?(pin)
+
+        row("toolchain", :warn, "installed #{installed}, pinned #{pin || "none"}", "rustup toolchain install #{pin}")
+      rescue Errno::ENOENT
+        row("toolchain", :warn, "no rust-toolchain.toml here", "run from a hecks checkout")
+      end
+
+      def rustc_version
+        out, status = Open3.capture2e("rustc", "--version")
+        status.success? ? out.strip : nil
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # The default store of the domain at this directory, checked without booting it.
+      def database(directory)
+        registry = Hecks.describe(directory).registry
+        store(registry, registry.first_domain_name)
+      rescue StandardError, ScriptError => e
+        row("store", :warn, "could not be read: #{first_line(e)}", "fix the overlay files first")
+      end
+
+      # The default store of one domain: Memory, a file store, or a Postgres database to reach.
+      def store(registry, name)
+        adapter = registry.default_adapter_for(name)
+        return row("store", :ok, "Memory") if adapter.nil? || adapter.to_s == "Memory"
+
+        url = registry.default_database_for(name)
+        return reach(url) if url.to_s.start_with?("postgres")
+
+        file_store(adapter.to_s, url)
+      end
+
+      # A file store is usable when its directory exists; the file itself is made on first write.
+      def file_store(adapter, path)
+        return row("store", :ok, adapter) if path.nil?
+
+        dir = File.dirname(path.to_s)
+        return row("store", :ok, "#{adapter}, #{path}") if File.directory?(dir)
+
+        row("store", :fail, "#{adapter} directory #{dir} is missing", "mkdir -p #{dir}")
+      end
+
+      # Postgres reachable, and the role the URL names exists; a read of the catalog, nothing written.
+      def reach(url)
+        require "pg"
+        PG.connect(url, connect_timeout: 3) { |conn| role_row(conn, URI.parse(url).user) }
+      rescue LoadError
+        row("store", :warn, "pg gem not loaded, so postgres was not tested", "bundle install")
+      rescue PG::Error => e
+        row("store", :fail, "postgres unreachable: #{first_line(e)}", "start postgres")
+      end
+
+      def role_row(conn, role)
+        exists = conn.exec_params("select 1 from pg_roles where rolname = $1", [role]).ntuples.positive?
+        return row("store", :ok, "postgres answers, role #{role} exists") if exists
+
+        row("store", :fail, "postgres answers, role #{role} is missing", "create the role: createuser #{role}")
+      end
+
+      def version(directory)
+        ahead, status = Open3.capture2e("git", "-C", directory, "rev-list", "--count", "origin/main..main")
+        base = "hecks #{Hecks::VERSION}"
+        return row("version", :ok, base) unless status.success? && ahead.to_i.positive?
+
+        row("version", :warn, "#{base}, local main #{ahead.strip} commit(s) ahead of origin/main", "push when ready")
+      end
+
+      def row(name, status, detail, fix = nil) = [name, status, detail, fix]
+
+      def first_line(error)
+        error.message[FIRST_LINE].to_s.strip
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/finding_github.rb

@@ -19,6 +19,9 @@ module Hecks
       # The environment variable that names the repository when no setting does.
       REPOSITORY_VARIABLE = "HECKS_FINDINGS_REPO"
 
+      # The end of an issue's URL, capturing its number.
+      ISSUE_NUMBER = %r{/issues/(\d+)\z}
+
       # @param aggregate [Object, nil] unused
       # @param settings [Hash] `repository:` names the `owner/name` to drive
       # @param root [String, nil] unused
@@ -35,7 +38,7 @@ module Hecks
       #   issue URL
       def open_issue(**held)
         out = gh("issue", "create", "--title", plain(held[:title]).to_s, "--body", plain(held[:body]).to_s)
-        number = out.lines.last.to_s.strip[%r{/issues/(\d+)\z}, 1]
+        number = Text.last_lines(out, 1)[ISSUE_NUMBER, 1]
         raise Error, "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
 
         { issue_number: { value: number.to_i } }

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

@@ -4,10 +4,10 @@ require_relative "../../adapters/driving/json"
 
 module Hecks
   module Adapters
-    # Gives a booted domain its first administrator through the chapter that provides
+    # Gives a booted domain its first administrator through the bluebook 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
+    # The bluebook 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
@@ -17,10 +17,16 @@ module Hecks
       # The roles that count as an administrator besides the one the grant command is gated to.
       OWNER_ROLES = %w[Owner].freeze
 
-      # What the refusal says when no chapter provides membership: the line to add to one.
-      NO_MEMBERSHIP = "this domain attaches no chapter that provides \"membership\". Add a line like " \
+      # An email address: one `@` with no whitespace on either side.
+      EMAIL = /\A[^\s@]+@[^\s@]+\z/
+
+      # The part of an email address before its `@`.
+      LOCAL_PART = /\A[^@]+/
+
+      # What the refusal says when no bluebook provides membership: the line to add to one.
+      NO_MEMBERSHIP = "this domain attaches no bluebook that provides \"membership\". Add a line like " \
                       "`provides \"membership\", admit: \"Person.Admit\", grant: \"Person.GrantAccess\", " \
-                      "people: \"Person.All\"` to the chapter that keeps who may sign in: admit and grant " \
+                      "people: \"Person.All\"` to the bluebook that keeps who may sign in: admit and grant " \
                       "name its commands (the grant command is gated to the administrator role), people " \
                       "names the query that lists everyone (docs/running-a-rules-service.md)"
 
@@ -49,7 +55,7 @@ module Hecks
       # @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
+      # @raise [Runtime::NotFound] when the domain has no membership bluebook, 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?(email)
@@ -58,14 +64,14 @@ module Hecks
         verbs, gate, people = check_unadministered(provider)
 
         admitted = people.none? { |person| person[:email] == email }
-        admit(provider, verbs.fetch(:admit), email, name || email[/\A[^@]+/]) if admitted
+        admit(provider, verbs.fetch(:admit), email, name || email[LOCAL_PART]) if admitted
         grant(provider, verbs.fetch(:grant), email, role || gate)
         Result.new(email: email, role: role || gate, admitted: admitted)
       end
 
       private
 
-      def email?(email) = email.to_s.match?(/\A[^\s@]+@[^\s@]+\z/)
+      def email?(email) = email.to_s.match?(EMAIL)
 
       # The membership verbs, the role the grant is gated to and the people held, once no
       # administrator is found among them.
@@ -78,7 +84,8 @@ module Hecks
       end
 
       def membership_provider
-        domain = @registry.bluebooks.values.first&.name
+        bluebook = @registry.first_bluebook
+        domain = bluebook&.name
         @registry.membership_provider_for(domain) or
           raise Runtime::NotFound, NO_MEMBERSHIP
       end

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

@@ -39,18 +39,18 @@ module Hecks
       # 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.
+      # The source is `from`, else `EMBRYONAUT_BLUEBOOKS_SRC`, else the `embryonaut_bluebooks`
+      # checkout beside the project; 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
+      # @return [Hash{Symbol => Hash}] `report:` what was vendored and whether its 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
+        from = plain(held[:from]) || EmbryonautBluebook::VendorCli.default_source(root)
         require_repository!(from)
 
         { report: { value: vendored(held[:package], from, root) } }

data/lib/hecks/hecks/adapters/git_checkout.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_checkout"
+
+Hecks.adapter "GitCheckout" do
+  port "Reading"
+end

data/lib/hecks/hecks/adapters/git_checkout.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "git_worktrees"
+
+module Hecks
+  module Adapters
+    # The `Reading` port's adapter for `Checkout`: answers what state a checkout is in, as text,
+    # so nothing needs a raw `git status`, `git diff` or `git log`. It reads and never writes.
+    #
+    # Every query takes `checkout`, a directory inside the repository (the current directory when
+    # absent), and answers `text:`; a refusal is a `Runtime::NotFound`.
+    class GitCheckout
+      include GitWorktrees
+
+      # How many commits `log` prints when it is given no range.
+      RECENT = 20
+
+      # A commit range as git writes one: names joined by `..` or `...`, never an option.
+      RANGE = %r{\A[0-9A-Za-z_][0-9A-Za-z_./^~@{}-]*\z}
+
+      # 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)
+        @git = Git.new
+      end
+
+      # The branch, whether the checkout is a linked worktree, where it stands against local
+      # `main` and `origin/main`, and each changed or untracked path.
+      #
+      # @param held [Hash] `checkout`
+      # @return [Hash{Symbol => String}] `text:` one `name: value` line each, then the paths
+      # @raise [Runtime::NotFound] when the checkout is not a repository
+      def status(**held)
+        answering(held) do
+          lines = ["branch: #{read("rev-parse", "--abbrev-ref", "HEAD")}", "head: #{short(read("rev-parse", "HEAD"))}",
+                   "worktree: #{linked? ? "linked" : "primary"} (#{@checkout})",
+                   standing("main"), standing("origin/main")].compact
+          changed = dirty
+          lines << (changed.empty? ? "clean" : "changed:") << changed.map { |line| "  #{line}" }
+          lines.flatten.join("\n")
+        end
+      end
+
+      # What a checkout changed since a ref: the diffstat, or the paths alone.
+      #
+      # @param held [Hash] `checkout`; `since` (a ref, default `main`); `names_only` (true for the
+      #   paths alone, not the diffstat)
+      # @return [Hash{Symbol => String}] `text:` the diffstat, or one path per line
+      # @raise [Runtime::NotFound] when the checkout or the ref is not found
+      def changes(**held)
+        answering(held) do
+          since = ref(plain(held[:since]) || "main")
+          flag = plain(held[:names_only]).to_s == "true" ? "--name-only" : "--stat"
+          read("diff", flag, read("merge-base", since, "HEAD"))
+        end
+      end
+
+      # The commits in a range, newest first, one `short-sha subject` line each.
+      #
+      # @param held [Hash] `checkout`; `range` (default: the last 20 commits)
+      # @return [Hash{Symbol => String}] `text:` the commits
+      # @raise [Runtime::NotFound] when the checkout or the range is not found
+      def history(**held)
+        answering(held) do
+          range = plain(held[:range])
+          read("log", "--format=%h %s", *(range ? [checked_range(range)] : ["-n", RECENT.to_s]))
+        end
+      end
+
+      private
+
+      def answering(held)
+        settle(held)
+        { text: "#{yield}\n" }
+      rescue ConsoleCapture::Failure => e
+        raise Runtime::NotFound, e.message
+      end
+
+      def linked? = primary.path != @checkout
+
+      # How far `HEAD` is ahead of and behind a ref, or nil when the repository has no such ref.
+      def standing(other)
+        return nil unless @git.capture("rev-parse", "--verify", "--quiet", other, chdir: @checkout).ok?
+
+        behind, ahead = read("rev-list", "--left-right", "--count", "#{other}...HEAD").split.map(&:to_i)
+        "#{other}: ahead #{ahead}, behind #{behind}"
+      end
+
+      def checked_range(range)
+        return range if range.match?(RANGE)
+
+        raise ConsoleCapture::Failure, "#{range.inspect} is not a commit range"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_commit.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_commit"
+
+Hecks.adapter "GitCommit" do
+  port "Committing"
+end

data/lib/hecks/hecks/adapters/git_commit.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "git_worktrees"
+
+module Hecks
+  module Adapters
+    # The `Committing` port's adapter for `Commit`: stages the named paths, then commits what is
+    # staged under the message, on the branch the checkout is on.
+    #
+    # It never pushes, never amends, never forces, and never commits onto `main`: that goes through
+    # `Landing`, and a push goes through `PushTrain`. A commit with nothing staged is declined.
+    class GitCommit
+      include GitWorktrees
+
+      # 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)
+        @git = Git.new
+      end
+
+      # Commits what is staged in a checkout, after staging the named paths when there are some.
+      #
+      # @param held [Hash] the `Commit` record: `checkout` (a directory inside the worktree; the
+      #   current directory when absent), `message`, and `paths` (whitespace-separated, optional)
+      # @return [Hash{Symbol => Hash}] `sha:` the commit made, `report:` what it says
+      # @raise [ConsoleCapture::Failure] on an empty message, a commit onto `main`, nothing staged,
+      #   or a directory outside a repository
+      def commit(**held)
+        settle(held)
+        message = plain(held[:message]).to_s.strip
+        raise ConsoleCapture::Failure, "a commit needs a message" if message.empty?
+
+        branch = current_branch
+        raise ConsoleCapture::Failure, "a commit onto main goes through Landing" if branch == "main"
+
+        stage(plain(held[:paths]))
+        refuse_nothing_staged
+        read("commit", "-m", message)
+        sha = read("rev-parse", "--short", "HEAD")
+        { sha: { value: sha }, report: { value: "committed #{sha} on #{branch}" } }
+      end
+
+      private
+
+      # Stages each named path; `--` keeps a path from being read as an option.
+      def stage(paths)
+        names = paths.to_s.split
+        read("add", "--", *names) unless names.empty?
+      end
+
+      def refuse_nothing_staged
+        return unless read("diff", "--cached", "--name-only").empty?
+
+        raise ConsoleCapture::Failure, "nothing is staged to commit"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_landing/finisher.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../git_worktrees"
+require_relative "../git_main_pull"
+require_relative "../shell"
+
+module Hecks
+  module Adapters
+    class GitLanding
+      # The steps before a landing that an agent used to run by hand: refuse unsaved work, rebase the
+      # branch onto local `main`, and run the quick gate in the branch's worktree.
+      #
+      # Each step refuses by name at the first failure, with the reason, and leaves the branch as it
+      # was: a rebase that conflicts is aborted. The landing itself and the tidy after it are
+      # {GitLanding#merge}'s.
+      class Finisher
+        include GitWorktrees
+        include GitMainPull
+
+        # The command that runs the seconds-long checks in a worktree.
+        GATE = %w[exe/hecks gate_run.gate! stage=quick --wait].freeze
+
+        # What a completed gate run prints.
+        COMPLETED = /"status":\s*"completed"/
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the worktree the branch is checked out in
+        # @param branch [String] the branch to finish
+        # @param onto [String] the branch to rebase onto
+        # @param gate [#call] answers the {Shell::Result} of the quick gate run in a directory
+        def initialize(git, checkout, branch:, onto:, gate: nil)
+          @git = git
+          @checkout = checkout
+          @branch = ref(branch)
+          @onto = ref(onto)
+          @gate = gate || ->(dir) { Shell.new.capture(*GATE, chdir: dir) }
+        end
+
+        # Refuses unsaved work, pulls `main` when it is the target, rebases and runs the gate.
+        #
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] naming the step that failed: unsaved work, conflict or
+        #   gate red
+        def prepare
+          refuse_unsaved
+          pull_main if @onto == "main"
+          rebase
+          run_gate
+        end
+
+        private
+
+        def refuse_unsaved
+          changed = dirty(@checkout)
+          raise ConsoleCapture::Failure, "unsaved work: #{@checkout} holds #{changed.join(", ")}" unless changed.empty?
+        end
+
+        def rebase
+          result = @git.capture("rebase", @onto, chdir: @checkout)
+          return if result.ok?
+
+          conflicts = @git.capture("diff", "--name-only", "--diff-filter=U", chdir: @checkout).out.split
+          @git.capture("rebase", "--abort", chdir: @checkout)
+          raise ConsoleCapture::Failure,
+                "conflict: rebasing #{@branch} onto #{@onto} conflicts in #{conflicts.join(", ")}; nothing changed"
+        end
+
+        def run_gate
+          result = @gate.call(@checkout)
+          return if result.ok? && result.out.match?(COMPLETED)
+
+          raise ConsoleCapture::Failure, "gate red: the quick gate failed in #{@checkout}: #{tail(result)}"
+        end
+
+        def tail(result)
+          lines = result.out.lines.last(5)
+          lines.join.strip
+        end
+      end
+    end
+  end
+end