hecks 2.7.0 → 2.9.0

data/lib/hecks/release/runner/commands.rb

@@ -0,0 +1,66 @@
+require "open3"
+
+module Hecks
+  module Release
+    class Runner
+      # Raised when a command a release step runs exits non-zero or cannot start.
+      class CommandFailed < StandardError; end
+
+      # Raised when a check refuses the release; the message names the fix.
+      class Refusal < StandardError; end
+
+      # Runs the release's external commands (git, gem, npm, curl, op) through
+      # any object answering `capture`/`run!`, so a spec injects a recorder.
+      class Commands
+        # What a captured command printed and whether it succeeded.
+        #
+        # @!attribute [r] stdout
+        #   @return [String] standard output
+        # @!attribute [r] stderr
+        #   @return [String] standard error, or the reason the command could not start
+        # @!attribute [r] success
+        #   @return [Boolean] true when the command exited zero
+        Result = Struct.new(:stdout, :stderr, :success, keyword_init: true) do
+          # Says whether the command exited zero.
+          #
+          # @return [Boolean] true when it did
+          def success?
+            success
+          end
+        end
+
+        # Runs a command and returns what it printed, whatever its exit status.
+        #
+        # @param argv [Array<String>] the command and its arguments, never a shell string
+        # @param env [Hash{String => String, nil}] variables to set, or unset with nil
+        # @param chdir [String, nil] the directory to run in; the current one when nil
+        # @return [Result] the output and status; a command that cannot start is a failed result
+        def capture(*argv, env: {}, chdir: nil)
+          stdout, stderr, status = Open3.capture3(env, *argv, **directory(chdir))
+          Result.new(stdout: stdout, stderr: stderr, success: status.success?)
+        rescue SystemCallError => e
+          Result.new(stdout: "", stderr: e.message, success: false)
+        end
+
+        # Runs a command with its output going straight to the terminal.
+        #
+        # @param argv [Array<String>] the command and its arguments, never a shell string
+        # @param env [Hash{String => String, nil}] variables to set, or unset with nil
+        # @param chdir [String, nil] the directory to run in; the current one when nil
+        # @return [true] when the command exits zero
+        # @raise [CommandFailed] if the command exits non-zero or cannot start
+        def run!(*argv, env: {}, chdir: nil)
+          return true if system(env, *argv, **directory(chdir))
+
+          raise CommandFailed, "`#{argv.first(2).join(' ')}` failed"
+        end
+
+        private
+
+        def directory(chdir)
+          chdir ? { chdir: chdir } : {}
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/console.rb

@@ -0,0 +1,52 @@
+module Hecks
+  module Release
+    class Runner
+      # Talks to the person running the release: progress lines, warnings and the
+      # y/N questions that come before anything irreversible.
+      class Console
+        # @param input [IO] where answers are read from
+        # @param out [IO] where progress goes
+        # @param err [IO] where refusals and failures go
+        # @param assume_yes [Boolean] answer every question yes without asking
+        def initialize(input:, out:, err:, assume_yes: false)
+          @input = input
+          @out = out
+          @err = err
+          @assume_yes = assume_yes
+        end
+
+        # Prints a progress line.
+        #
+        # @param text [String] the line
+        # @return [void]
+        def say(text)
+          @out.puts(text)
+        end
+
+        # Prints a refusal or failure line.
+        #
+        # @param text [String] the line
+        # @return [void]
+        def warn(text)
+          @err.puts(text)
+        end
+
+        # Asks a yes/no question, defaulting to no.
+        #
+        # @param question [String] what will happen if the answer is yes
+        # @return [Boolean] true for `y` or `yes`, or always under `assume_yes`; false on anything
+        #   else, including a closed input
+        def confirm?(question)
+          if @assume_yes
+            say("#{question} yes (--yes)")
+            return true
+          end
+
+          @out.print("#{question} [y/N] ")
+          @out.flush
+          %w[y yes].include?(@input.gets.to_s.strip.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/gem_publisher.rb

@@ -0,0 +1,43 @@
+require "fileutils"
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # The gem step: hands the push to `bin/release_gem`, which builds and pushes
+      # it with the key 1Password holds; a dry run only builds it, then deletes it.
+      class GemPublisher
+        # @param root [String] the repository root
+        # @param commands [#run!] runs the build and the push
+        # @param console [Console] progress output
+        def initialize(root:, commands:, console:)
+          @root = root
+          @commands = commands
+          @console = console
+        end
+
+        # Pushes the gem, or with `dry_run` only builds it.
+        #
+        # @param version [String] the version being released
+        # @param dry_run [Boolean] build and delete the gem, pushing nothing
+        # @return [void]
+        # @raise [CommandFailed] if the build or the push fails
+        def publish!(version, dry_run:)
+          return build_only(version) if dry_run
+
+          @console.say("Publishing hecks #{version} to rubygems.org via bin/release_gem...")
+          @commands.run!(File.join(@root, "bin/release_gem"), chdir: @root)
+        end
+
+        private
+
+        def build_only(version)
+          @console.say("Dry run: building hecks-#{version}.gem (nothing is pushed)...")
+          @commands.run!("gem", "build", "hecks.gemspec", chdir: @root)
+        ensure
+          FileUtils.rm_f(File.join(@root, "hecks-#{version}.gem"))
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/git.rb

@@ -0,0 +1,48 @@
+require "hecks/vendoring/git_environment"
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # The release's view of the repository: git run in the checkout, with the
+      # repository-pinning environment variables a git hook exports unset.
+      class Git
+        # @param root [String] the repository root
+        # @param commands [#capture, #run!] runs the git commands
+        def initialize(root:, commands:)
+          @root = root
+          @commands = commands
+        end
+
+        # Runs a git command and returns what it printed.
+        #
+        # @param args [Array<String>] git's arguments
+        # @return [String] standard output
+        # @raise [Refusal] if git exits non-zero
+        def read(*args)
+          result = capture(*args)
+          raise Refusal, "git #{args.first} failed: #{result.stderr.strip}" unless result.success?
+
+          result.stdout
+        end
+
+        # Runs a git command and returns the result whatever its status.
+        #
+        # @param args [Array<String>] git's arguments
+        # @return [Commands::Result] output and status
+        def capture(*)
+          @commands.capture("git", *, env: Vendoring::GitEnvironment.clean, chdir: @root)
+        end
+
+        # Runs a git command that changes something, showing its output.
+        #
+        # @param args [Array<String>] git's arguments
+        # @return [true] when git exits zero
+        # @raise [CommandFailed] if git exits non-zero
+        def run!(*)
+          @commands.run!("git", *, env: Vendoring::GitEnvironment.clean, chdir: @root)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/npm_publisher.rb

@@ -0,0 +1,75 @@
+require "tempfile"
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # The npm step: publishes `@hecks/client` from `packages/hecks-client`
+      # with the token 1Password holds.
+      class NpmPublisher
+        PACKAGE_DIR = "packages/hecks-client".freeze
+        ENV_FILE = "release/npm_publish.env".freeze
+        APPROVAL_NOTICE = "npm will print an approval link; open it and approve with your security key or passkey. " \
+                          "This step waits for you.".freeze
+        USERCONFIG_LINE = "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}".freeze
+
+        def initialize(root:, commands:, console:)
+          @root = root
+          @commands = commands
+          @console = console
+        end
+
+        # Publishes the package, or with `dry_run` only packs it, which needs no
+        # credentials.
+        def publish!(version, dry_run:)
+          install_dependencies
+          if dry_run
+            @console.say("Dry run: npm publish --dry-run for @hecks/client #{version} (nothing is published)...")
+            @commands.run!("npm", "publish", "--dry-run", "--access", "public", chdir: package_dir)
+          else
+            @console.say("Publishing @hecks/client #{version} to npm (1Password will prompt for Touch ID)...")
+            @console.say(APPROVAL_NOTICE)
+            publish_with_token
+          end
+        end
+
+        private
+
+        def package_dir
+          File.join(@root, PACKAGE_DIR)
+        end
+
+        # npm's `prepack` hook builds `dist/`; there is no separate build step here.
+        def install_dependencies
+          return if Dir.exist?(File.join(package_dir, "node_modules"))
+
+          @console.say("Installing the client's dependencies (npm ci)...")
+          @commands.run!("npm", "ci", chdir: package_dir)
+        end
+
+        # The token bypasses 2FA (the account's second factor is a passkey); this
+        # fallback publish runs with `--auth-type=web` and doesn't capture output,
+        # so an approval prompt reaches the terminal.
+        def publish_with_token
+          with_userconfig do |userconfig|
+            @commands.run!(
+              "op", "run", "--env-file=#{File.join(@root, ENV_FILE)}", "--",
+              "npm", "publish", "--access", "public", "--auth-type=web", "--userconfig", userconfig,
+              chdir: package_dir
+            )
+          end
+        end
+
+        def with_userconfig
+          file = Tempfile.new(["hecks-npmrc", ".npmrc"])
+          file.chmod(0o600)
+          file.write("#{USERCONFIG_LINE}\n")
+          file.flush
+          yield file.path
+        ensure
+          file&.close!
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/preflight.rb

@@ -0,0 +1,104 @@
+require "json"
+require_relative "commands"
+require_relative "git"
+
+module Hecks
+  module Release
+    class Runner
+      # The checks that run before a release does anything: tools installed, a
+      # clean current `main`, matching versions, and a changelog entry.
+      class Preflight
+        # What the checks learned; `sha` is also `origin/main`, enforced by check_current.
+        Facts = Struct.new(:version, :sha, keyword_init: true)
+
+        INSTALL_HINTS = {
+          "git"  => "install git",
+          "gem"  => "install Ruby, which ships gem",
+          "npm"  => "install Node.js: brew install node",
+          "curl" => "install curl",
+          "op"   => "install the 1Password CLI: brew install 1password-cli"
+        }.freeze
+        VERSION_LINE = /^\s*VERSION\s*=\s*"(?<version>[^"]+)"/
+        CLIENT_PACKAGE = "packages/hecks-client/package.json".freeze
+
+        def initialize(root:, commands:, git:, tools:)
+          @root = root
+          @commands = commands
+          @git = git
+          @tools = tools
+        end
+
+        # Runs every check; the first refusal stops it.
+        def check!
+          check_tools
+          check_branch
+          check_current
+          check_clean
+          version = declared_version
+          check_client_version(version)
+          check_changelog(version)
+          Facts.new(version: version, sha: git("rev-parse", "HEAD").strip)
+        end
+
+        private
+
+        def check_tools
+          @tools.each do |tool|
+            next if @commands.capture(tool, "--version").success?
+
+            raise Refusal, "#{tool} not found on PATH; #{INSTALL_HINTS.fetch(tool, "install #{tool}")}"
+          end
+        end
+
+        def check_branch
+          branch = git("rev-parse", "--abbrev-ref", "HEAD").strip
+          return if branch == "main"
+
+          raise Refusal, "on branch #{branch}, not main; release from main: git checkout main"
+        end
+
+        def check_current
+          fetch = @git.capture("fetch", "origin")
+          raise Refusal, "git fetch origin failed (#{fetch.stderr.strip}); check the network and the remote" unless fetch.success?
+
+          head = git("rev-parse", "HEAD").strip
+          upstream = git("rev-parse", "origin/main").strip
+          return if head == upstream
+
+          raise Refusal, "main (#{head[0, 7]}) is not origin/main (#{upstream[0, 7]}); " \
+                         "merge the release PR, then git pull --ff-only"
+        end
+
+        def check_clean
+          return if git("status", "--porcelain").strip.empty?
+
+          raise Refusal, "the working tree has uncommitted changes; commit or discard them before releasing"
+        end
+
+        def declared_version
+          match = File.read(File.join(@root, "lib/hecks/version.rb")).match(VERSION_LINE)
+          raise Refusal, "lib/hecks/version.rb declares no VERSION; restore it" unless match
+
+          match[:version]
+        end
+
+        def check_client_version(version)
+          client = JSON.parse(File.read(File.join(@root, CLIENT_PACKAGE))).fetch("version")
+          return if client == version
+
+          raise Refusal, "packages/hecks-client is at #{client} but Hecks::VERSION is #{version}; bump the package first."
+        end
+
+        def check_changelog(version)
+          return if File.read(File.join(@root, "CHANGELOG.md")).match?(/^## \[#{Regexp.escape(version)}\]/)
+
+          raise Refusal, "CHANGELOG.md has no `## [#{version}]` heading; add the release entry in the release PR"
+        end
+
+        def git(*)
+          @git.read(*)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/published.rb

@@ -0,0 +1,55 @@
+require "json"
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # Asks the registries whether a version is already out, so a re-run of the
+      # release skips what an earlier run finished.
+      #
+      # Neither question needs credentials.
+      class Published
+        GEM_VERSIONS_URL = "https://rubygems.org/api/v1/versions/hecks.json".freeze
+        NPM_PACKAGE = "@hecks/client".freeze
+
+        # @param root [String] the repository root
+        # @param commands [#capture] runs curl and npm
+        def initialize(root:, commands:)
+          @root = root
+          @commands = commands
+        end
+
+        # Says whether RubyGems lists the hecks gem at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Refusal] if RubyGems cannot be reached or answers with something unreadable
+        def gem?(version)
+          result = @commands.capture("curl", "-fsS", GEM_VERSIONS_URL, chdir: @root)
+          unless result.success?
+            raise Refusal, "could not list published hecks versions (#{result.stderr.strip}); " \
+                           "check the network and re-run"
+          end
+
+          JSON.parse(result.stdout).any? { |entry| entry["number"] == version }
+        rescue JSON::ParserError
+          raise Refusal, "RubyGems answered with something other than a version list; re-run in a minute"
+        end
+
+        # Says whether npm lists @hecks/client at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Refusal] if npm fails for any reason other than the version not existing
+        def npm?(version)
+          result = @commands.capture("npm", "view", "#{NPM_PACKAGE}@#{version}", "version", chdir: @root)
+          return result.stdout.strip == version if result.success?
+          return false if result.stderr.include?("E404")
+
+          raise Refusal, "could not check npm for #{NPM_PACKAGE}@#{version} (#{result.stderr.strip.lines.first}); " \
+                         "check the network and re-run"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/tagger.rb

@@ -0,0 +1,80 @@
+require_relative "commands"
+require_relative "git"
+
+module Hecks
+  module Release
+    class Runner
+      # Makes sure the release tag `vX.Y.Z` is an annotated tag on the release
+      # commit and is on origin, creating and pushing it only when it is missing.
+      class Tagger
+        def initialize(git:, console:, dry_run:)
+          @git = git
+          @console = console
+          @dry_run = dry_run
+        end
+
+        # Brings the tag to the state described above, saying what it did; returns
+        # false only when the person declined the confirmation.
+        def ensure!(facts)
+          tag = "v#{facts.version}"
+          local = local_commit(tag)
+          remote = remote_commit(tag)
+          refuse_elsewhere(tag, facts.sha, local: local, remote: remote)
+          return true.tap { already_there(tag) } if remote
+          return true.tap { preview(tag, facts.sha, local) } if @dry_run
+          return false unless @console.confirm?(question(tag, facts.sha, local))
+
+          create(tag, facts.sha) unless local
+          push(tag)
+          true
+        end
+
+        private
+
+        def already_there(tag)
+          @console.say("Tag #{tag} is already on origin at the release commit; skipping.")
+        end
+
+        def preview(tag, sha, local)
+          @console.say("Would create annotated tag #{tag} at #{sha[0, 7]}.") unless local
+          @console.say("Would push #{tag} to origin.")
+        end
+
+        def question(tag, sha, local)
+          verb = local ? "Push" : "Create and push"
+          "#{verb} annotated tag #{tag} at #{sha[0, 7]} to origin?"
+        end
+
+        def create(tag, sha)
+          @git.run!("tag", "-a", tag, "-m", "Release #{tag.delete_prefix('v')}", sha)
+        end
+
+        def push(tag)
+          @git.run!("push", "origin", tag)
+        end
+
+        def refuse_elsewhere(tag, sha, local:, remote:)
+          { "locally" => local, "on origin" => remote }.each do |where, commit|
+            next if commit.nil? || commit == sha
+
+            raise Refusal, "tag #{tag} already points at #{commit[0, 7]} #{where}, not at the release commit " \
+                           "#{sha[0, 7]}; if that tag was never released, delete it (git tag -d #{tag}; " \
+                           "git push origin :refs/tags/#{tag}) and re-run, otherwise main has moved since the release " \
+                           "and the missing package must be published from a checkout of #{tag}"
+          end
+        end
+
+        def local_commit(tag)
+          result = @git.capture("rev-parse", "-q", "--verify", "refs/tags/#{tag}^{commit}")
+          result.success? ? result.stdout.strip : nil
+        end
+
+        def remote_commit(tag)
+          listing = @git.read("ls-remote", "--tags", "origin", "refs/tags/#{tag}", "refs/tags/#{tag}^{}")
+          shas = listing.lines.to_h { |line| line.split.then { |sha, ref| [ref, sha] } }
+          shas.fetch("refs/tags/#{tag}^{}") { shas["refs/tags/#{tag}"] }
+        end
+      end
+    end
+  end
+end