hecks 2.6.0 → 2.8.0

data/lib/hecks/release/gem_pin.rb

@@ -0,0 +1,112 @@
+require_relative "gem_pin/published_versions"
+
+module Hecks
+  module Release
+    # Finds the hecks version a project runs on, and refuses one that a
+    # stranger could not install.
+    #
+    # ## Why it exists
+    #
+    # A project that is copied out of its own workspace (handed to someone who
+    # will `bundle install` it, or built in an image with no sibling checkout)
+    # has to name a hecks release RubyGems actually publishes. A `path:` or
+    # `git:` source only works where the path or remote is reachable, and a
+    # version that was never published resolves nowhere. This reads the
+    # project's Gemfiles and lockfiles, without running Bundler, and says which
+    # version each pins or refuses.
+    #
+    # ## Resolution
+    #
+    # For each `Gemfile` under the root (a project can hold several, such as a
+    # domain and a helper app) the pin is, in order: the version its
+    # `Gemfile.lock` resolved, or the newest stable release its version
+    # constraint allows. Each pin must be published; the Gemfiles need not
+    # agree.
+    #
+    # ## Injectable network
+    #
+    # The published list comes from `published:`, any object answering
+    # `include?(version)` and `newest_satisfying(requirement)`. The default asks
+    # RubyGems; a caller without network hands in its own.
+    class GemPin
+      GEM_LINE = /^\s*gem\s+["']hecks["'](?<rest>.*)$/
+      SOURCE_OPTION = /\b(?:path|git|github|gitlab|bitbucket|branch|ref|tag):/
+      LOCKED = /^    hecks \((?<version>[^)]+)\)/
+
+      # What `resolve` found.
+      #
+      # @!attribute [r] version
+      #   @return [String] the newest pin
+      # @!attribute [r] pins
+      #   @return [Hash{String => String}] each Gemfile that declares hecks, relative to the
+      #     root, mapped to the version it runs on
+      Resolved = Struct.new(:version, :pins, keyword_init: true)
+
+      # @param published [#include?, #newest_satisfying] the source of published versions
+      def initialize(published: PublishedVersions.new)
+        @published = published
+      end
+
+      # Resolves the hecks versions the project in `root` runs on.
+      #
+      # @param root [String] the project's root directory
+      # @return [Resolved] the newest pin and every pin
+      # @raise [Error] if no Gemfile declares hecks, one takes it from a source other than
+      #   RubyGems, one pins a version RubyGems does not publish, or a constraint allows
+      #   no published release
+      def resolve(root)
+        pins = gemfiles(root).filter_map { |gemfile| pin_for(gemfile, root) }.to_h
+        raise Error, "no Gemfile declares the hecks gem, so this is not a Hecks project" if pins.empty?
+
+        pins.each do |rel, version|
+          raise Error, "hecks #{version} is not published on RubyGems (#{rel})" unless @published.include?(version)
+        end
+        Resolved.new(version: pins.values.max_by { |version| Gem::Version.new(version) }, pins: pins)
+      end
+
+      private
+
+      def gemfiles(root)
+        Dir.glob("**/Gemfile", base: root).reject { |rel| rel.include?("node_modules/") }.sort
+           .map { |rel| File.join(root, rel) }
+      end
+
+      def pin_for(gemfile, root)
+        declaration = File.read(gemfile).match(GEM_LINE) or return nil
+        rel = gemfile.delete_prefix("#{root}/")
+        if (source = declaration[:rest][SOURCE_OPTION])
+          raise Error, "#{rel} takes hecks from `#{source}`, not from RubyGems; the project must use a published version"
+        end
+
+        [rel, locked_version(gemfile, rel) || newest_allowed(declaration[:rest], rel)]
+      end
+
+      # The version Gemfile.lock resolved, if there is a lockfile. A hecks
+      # entry under `PATH` or `GIT` means the lockfile is not installable either.
+      def locked_version(gemfile, rel)
+        lock = "#{gemfile}.lock"
+        return nil unless File.exist?(lock)
+
+        text = File.read(lock)
+        refuse_unpublished_source!(text, rel)
+        text.match(LOCKED)&.[](:version)
+      end
+
+      def refuse_unpublished_source!(lock_text, rel)
+        lock_text.split("\n\n").each do |section|
+          next unless section.start_with?("PATH", "GIT") && section.match?(LOCKED)
+
+          raise Error, "#{rel}.lock resolves hecks from a #{section.lines.first.strip} source, not from RubyGems"
+        end
+      end
+
+      def newest_allowed(rest, rel)
+        constraints = rest.scan(/["']([^"']+)["']/).flatten.grep(/\A\s*(?:[~><=!]+\s*)?\d/)
+        version = @published.newest_satisfying(Gem::Requirement.new(*constraints))
+        raise Error, "no published hecks release satisfies the constraint in #{rel}" unless version
+
+        version.to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # The npm step when CI publishes: the release tag triggers
+      # `.github/workflows/publish-client.yml`, which publishes `@hecks/client`
+      # with npm trusted publishing, so nothing is published from this machine.
+      # This watches npm until the version appears.
+      #
+      # The clock and the pause are injected, so a spec runs the whole wait
+      # without sleeping.
+      class CiPublisher
+        WORKFLOW = ".github/workflows/publish-client.yml".freeze
+        INTERVAL = 15
+        LIMIT = 600
+
+        # @param root [String] the repository root
+        # @param published [Published] asks npm whether the version is out
+        # @param console [Console] progress output
+        # @param pause [#call] sleeps for a number of seconds
+        # @param now [#call] answers the current time in seconds, monotonically
+        def initialize(root:, published:, console:, pause:, now:)
+          @root = root
+          @published = published
+          @console = console
+          @pause = pause
+          @now = now
+        end
+
+        # Says whether the checkout carries the workflow that publishes the client.
+        #
+        # @return [Boolean] true when `.github/workflows/publish-client.yml` exists
+        def workflow?
+          File.exist?(File.join(@root, WORKFLOW))
+        end
+
+        # Tells the person CI publishes, then waits for the version to reach npm.
+        #
+        # @param version [String] the version being released
+        # @param dry_run [Boolean] say what would happen and wait for nothing
+        # @param wait [Boolean] false to report and return without polling
+        # @return [Boolean] false only when the wait timed out; true when the version appeared or
+        #   nothing was waited for
+        def wait!(version, dry_run:, wait:)
+          @console.say("CI publishes @hecks/client #{version} from the tag (#{WORKFLOW}); nothing is published from here.")
+          return true.tap { preview } if dry_run
+          return true.tap { skip_wait(version) } unless wait
+
+          @console.say("Waiting for @hecks/client #{version} on npm (every #{INTERVAL}s, up to #{LIMIT / 60} minutes)...")
+          arrived = arrives?(version)
+          @console.say("@hecks/client #{version} is on npm.") if arrived
+          arrived
+        end
+
+        # The hint printed when the wait ends without the version on npm.
+        #
+        # @param version [String] the version being released
+        # @return [String] how to look at, re-run and fall back from the CI publish
+        def self.timeout_hint(version)
+          "Timed out after #{LIMIT / 60} minutes waiting for CI to publish @hecks/client #{version}. " \
+            "See the run: gh run list --workflow publish-client.yml. Re-run it: " \
+            "gh workflow run publish-client.yml -f tag=v#{version}. Then finish with: bin/release --npm-only. " \
+            "To publish from this machine instead: bin/release --npm-only --npm-local."
+        end
+
+        private
+
+        def preview
+          @console.say("Dry run: would wait up to #{LIMIT / 60} minutes for it to appear on npm.")
+        end
+
+        def skip_wait(version)
+          @console.say("Not waiting (--no-wait). Check the run: gh run list --workflow publish-client.yml; " \
+                       "npm view @hecks/client@#{version} version")
+        end
+
+        def arrives?(version)
+          deadline = @now.call + LIMIT
+          loop do
+            return true if out?(version)
+            return false if @now.call >= deadline
+
+            @pause.call(INTERVAL)
+          end
+        end
+
+        def out?(version)
+          @published.npm?(version)
+        rescue Refusal
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+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.
+      #
+      # The runner takes any object answering `capture` and `run!` the way this
+      # one does, so a spec hands in a recorder and never starts a real process.
+      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,44 @@
+require "fileutils"
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # The gem step: hands the push to `bin/release_gem`, which owns building the
+      # gem and pushing it with the key 1Password holds. A dry run builds the gem
+      # to prove it builds and 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,89 @@
+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.
+      #
+      # `op run` resolves `release/npm_publish.env` into the environment of the
+      # one `npm publish` process. npm reads its token from a config file, so a
+      # throwaway user config holds a placeholder that npm expands from that
+      # environment; the file never contains the token and is deleted afterwards.
+      # The package's `prepack` builds `dist/`.
+      #
+      # The token is a granular one that bypasses two-factor authentication, because
+      # the account's second factor is a passkey. As a fallback the publish runs with
+      # `--auth-type=web` and its output is not captured, so if npm does ask for an
+      # approval it prints the link straight to the terminal and waits for it.
+      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
+
+        # @param root [String] the repository root
+        # @param commands [#run!] runs npm and op
+        # @param console [Console] progress output
+        def initialize(root:, commands:, console:)
+          @root = root
+          @commands = commands
+          @console = console
+        end
+
+        # Publishes the package, or with `dry_run` only packs it.
+        #
+        # @param version [String] the version being released
+        # @param dry_run [Boolean] run `npm publish --dry-run`, which needs no credentials
+        # @return [void]
+        # @raise [CommandFailed] if installing, building or publishing fails
+        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
+
+        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
+
+        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,119 @@
+require "json"
+require_relative "commands"
+require_relative "git"
+
+module Hecks
+  module Release
+    class Runner
+      # The checks that run before a release does anything: the tools are
+      # installed, the checkout is a clean, current `main`, the gem and the
+      # JavaScript client agree on a version, and the changelog names it.
+      #
+      # Every refusal says what to do about it.
+      class Preflight
+        # What the checks learned about the release.
+        #
+        # @!attribute [r] version
+        #   @return [String] the version `lib/hecks/version.rb` declares
+        # @!attribute [r] sha
+        #   @return [String] the commit `HEAD` points at, which is also `origin/main`
+        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
+
+        # @param root [String] the repository root
+        # @param commands [#capture] runs the tool probes
+        # @param git [Git] the repository the release is cut from
+        # @param tools [Array<String>] the executables the release needs on PATH
+        def initialize(root:, commands:, git:, tools:)
+          @root = root
+          @commands = commands
+          @git = git
+          @tools = tools
+        end
+
+        # Runs every check.
+        #
+        # @return [Facts] the version and commit the release is cut from
+        # @raise [Refusal] on the first check that fails, naming the fix
+        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