release_ceremony 1.0.0

data/lib/release_ceremony/publish.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module ReleaseCeremony
+  # Publishes a prepared, merged release: validates the merge commit, tags
+  # it, pushes the tag, watches the tag-triggered release workflow, and
+  # confirms the gem appears on RubyGems.
+  class Publish
+    extend Command
+
+    USAGE = 'Usage: release_ceremony publish VERSION'
+    HELP = <<~TEXT.freeze
+      #{USAGE}
+
+      Validate and publish the merged release-vVERSION pull request by tagging
+      its merge commit and monitoring the release workflow.
+    TEXT
+
+    def initialize(version:, runner:, project: nil)
+      @version = version
+      @runner = runner
+      @project = project || Project.discover(runner: runner)
+    end
+
+    def call
+      runner.run('git', 'fetch', '--no-tags', project.remote, project.default_branch)
+      pull_request = merged_pull_request
+      sha = pull_request.sha
+      validate_release_commit!(sha)
+      tags = tag_state
+      validate_existing_tags!(tags, sha)
+      print_summary(pull_request, tags)
+      confirm!
+      publish_tag(tags, sha)
+      monitor_release(sha)
+      true
+    end
+
+    private
+
+    attr_reader :project, :runner, :version
+
+    def merged_pull_request
+      PullRequestFinder.new(version: version, runner: runner, project: project).call
+    end
+
+    def remote_branch
+      "#{project.remote}/#{project.default_branch}"
+    end
+
+    def validate_release_commit!(sha)
+      validate_ancestry!(sha)
+      validate_version_file!(runner.capture('git', 'show', "#{sha}:#{project.version_file}"))
+      validate_changelog!(runner.capture('git', 'show', "#{sha}:#{project.changelog_file}"))
+    end
+
+    def validate_ancestry!(sha)
+      runner.run('git', 'merge-base', '--is-ancestor', sha, remote_branch)
+    rescue Error
+      raise Error, "Merge commit #{sha} is not an ancestor of #{remote_branch}"
+    end
+
+    def validate_version_file!(contents)
+      assignments = contents.lines.grep(/^[ \t]*VERSION[ \t]*=/)
+      expected = /^[ \t]*VERSION = '#{Regexp.escape(version.to_s)}'[ \t]*$/
+      return if assignments.one? && assignments.first.match?(expected)
+
+      raise Error, "#{project.version_file} at the merge commit does not assign VERSION = '#{version}' exactly"
+    end
+
+    def validate_changelog!(contents)
+      return if changelog_heading?(contents) && changelog_link?(contents)
+
+      raise Error,
+            "#{project.changelog_file} at the merge commit lacks the exact #{version} heading or comparison link"
+    end
+
+    def changelog_heading?(contents)
+      heading = /^## \[#{Regexp.escape(version.to_s)}\] - \d{4}-\d{2}-\d{2}[ \t]*$/
+      contents.lines.grep(heading).one?
+    end
+
+    def changelog_link?(contents)
+      link = /^\[#{Regexp.escape(version.to_s)}\]:[ ]#{Regexp.escape(project.compare_base)}
+               v\d+\.\d+\.\d+\.\.\.v#{Regexp.escape(version.to_s)}[ \t]*$/x
+      contents.lines.grep(link).one?
+    end
+
+    def tag_state
+      TagInspector.new(version: version, runner: runner, remote: project.remote).call
+    end
+
+    def validate_existing_tags!(tags, sha)
+      validate_existing_tag!('Local', tags.local_sha, sha)
+      validate_existing_tag!('Remote', tags.remote_sha, sha)
+    end
+
+    def validate_existing_tag!(location, existing_sha, expected_sha)
+      return unless existing_sha
+      return if existing_sha == expected_sha
+
+      raise Error, "#{location} tag #{version.tag} points to #{existing_sha}, not merge commit #{expected_sha}"
+    end
+
+    def print_summary(pull_request, tags)
+      summary_lines(pull_request, tags).each { |line| runner.puts(line) }
+    end
+
+    def summary_lines(pull_request, tags)
+      [
+        "Merged pull request: ##{pull_request.number} #{pull_request.url}",
+        "Merge commit: #{pull_request.sha}",
+        "Tag: #{version.tag}",
+        "Local tag: #{tag_description(tags.local_sha)}",
+        "Remote tag: #{tag_description(tags.remote_sha)}"
+      ]
+    end
+
+    def tag_description(sha)
+      sha ? "exists at #{sha}" : 'absent'
+    end
+
+    def confirm!
+      expected = "publish #{version.tag}"
+      runner.print("Type '#{expected}' to continue: ")
+      return if runner.gets&.chomp == expected
+
+      raise Error, 'Publication cancelled; no tag was created or pushed'
+    end
+
+    def publish_tag(tags, sha)
+      return if tags.remote_sha
+
+      runner.run('git', 'tag', version.tag, sha) unless tags.local_sha
+      runner.run('git', 'push', project.remote, version.tag)
+    end
+
+    def monitor_release(sha)
+      run_id = find_workflow_run(sha)
+      runner.puts('The release uses a protected environment; approve it in GitHub if prompted.')
+      open_workflow_run(run_id)
+      runner.run('gh', 'run', 'watch', run_id.to_s, '--exit-status')
+      verify_published_gem!
+    end
+
+    def open_workflow_run(run_id)
+      runner.run('gh', 'run', 'view', run_id.to_s, '--web')
+    rescue Error => e
+      message = [
+        "Could not open run #{run_id} in a browser: #{e.message}.",
+        "Visit #{project.actions_run_url(run_id)} or run gh run view #{run_id} --web."
+      ].join(' ')
+      runner.warn(message)
+    end
+
+    def find_workflow_run(sha)
+      WorkflowFinder.new(version: version, runner: runner, sha: sha, workflow_file: project.workflow_file).call
+    end
+
+    def verify_published_gem!
+      unless published_versions.include?(version.to_s)
+        raise Error, "RubyGems does not list #{project.gem_name} version #{version}"
+      end
+
+      runner.puts("Published #{project.gem_name} #{version} successfully.")
+    end
+
+    def published_versions
+      output = runner.capture('gem', 'list', '--remote', '--exact', project.gem_name, '--all')
+      output.lines
+            .filter_map { |line| line[/\A#{Regexp.escape(project.gem_name)} \(([^)]+)\)/, 1] }
+            .flat_map { |list| list.split(',').map(&:strip) }
+    end
+  end
+end

data/lib/release_ceremony/pull_request_finder.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ReleaseCeremony
+  # Finds the single merged pull request for the release branch and extracts
+  # its merge commit, refusing ambiguous or malformed data.
+  class PullRequestFinder
+    PR_LIMIT = '100'
+    PullRequest = Struct.new(:number, :url, :sha, keyword_init: true)
+
+    def initialize(version:, runner:, project:)
+      @version = version
+      @runner = runner
+      @project = project
+    end
+
+    def call
+      pull_requests = parse_json(runner.capture(*command))
+      ensure_one_pull_request!(pull_requests)
+      extract_pull_request(pull_requests.first)
+    end
+
+    private
+
+    attr_reader :project, :runner, :version
+
+    def command
+      [
+        'gh', 'pr', 'list', '--state', 'merged', '--base', project.default_branch, '--head', "release-v#{version}",
+        '--json', 'number,url,mergeCommit,mergedAt', '--limit', PR_LIMIT
+      ]
+    end
+
+    def ensure_one_pull_request!(pull_requests)
+      raise Error, 'Malformed merged pull request data: expected a JSON array' unless pull_requests.is_a?(Array)
+      return if pull_requests.one?
+
+      raise Error, "Expected exactly one merged release-v#{version} pull request; found #{pull_requests.length}"
+    end
+
+    def extract_pull_request(pull_request)
+      attributes = pull_request_attributes(pull_request)
+      unless attributes
+        raise Error, 'Merged pull request data is missing a number, URL, merge time, or merge commit SHA'
+      end
+
+      PullRequest.new(number: attributes.fetch(0), url: attributes.fetch(1), sha: attributes.fetch(3))
+    end
+
+    def pull_request_attributes(pull_request)
+      return unless pull_request.is_a?(Hash)
+
+      merge_commit = pull_request['mergeCommit']
+      sha = merge_commit['oid'] if merge_commit.is_a?(Hash)
+      attributes = [
+        pull_request['number'], pull_request['url'], pull_request['mergedAt'], sha
+      ]
+      attributes if valid_pull_request_attributes?(*attributes)
+    end
+
+    def valid_pull_request_attributes?(number, url, merged_at, sha)
+      number.is_a?(Integer) && number.positive? && present?(url) && present?(merged_at) && commit_sha?(sha)
+    end
+
+    def parse_json(output)
+      JSON.parse(output)
+    rescue JSON::ParserError => e
+      raise Error, "Malformed merged pull request JSON: #{e.message}"
+    end
+
+    def present?(value)
+      value.is_a?(String) && !value.empty?
+    end
+
+    def commit_sha?(value)
+      value.is_a?(String) && value.match?(/\A[0-9a-f]{40}(?:[0-9a-f]{24})?\z/)
+    end
+  end
+end

data/lib/release_ceremony/runner.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'shellwords'
+
+module ReleaseCeremony
+  # Runs external commands without a shell and mediates all console
+  # interaction, so command execution and I/O can be faked in tests.
+  class Runner
+    def initialize(stdout: $stdout, stderr: $stderr, stdin: $stdin, sleeper: Kernel)
+      @stdout = stdout
+      @stderr = stderr
+      @stdin = stdin
+      @sleeper = sleeper
+    end
+
+    def capture(*command)
+      validate_command!(command)
+      captured_stdout, captured_stderr, status = Open3.capture3(*command)
+      return captured_stdout if status.success?
+
+      raise_command_error(command, captured_stderr)
+    rescue SystemCallError => e
+      raise_spawn_error(command, e.message)
+    end
+
+    def run(*command)
+      validate_command!(command)
+      result = system(*command)
+      return true if result
+
+      result.nil? ? raise_spawn_error(command) : raise_command_error(command)
+    rescue SystemCallError => e
+      raise_spawn_error(command, e.message)
+    end
+
+    def puts(message = '')
+      @stdout.puts(message)
+    end
+
+    def print(message)
+      @stdout.print(message)
+    end
+
+    def warn(message)
+      @stderr.puts(message)
+    end
+
+    def gets
+      @stdin.gets
+    end
+
+    def sleep(duration)
+      @sleeper.sleep(duration)
+    end
+
+    private
+
+    def validate_command!(command)
+      return if command.length > 1 && command.all?(String)
+
+      raise Error, 'Command must be provided as an executable and separate arguments'
+    end
+
+    def raise_command_error(command, captured_stderr = nil)
+      message = "Command failed: #{Shellwords.join(command.map(&:to_s))}"
+      message = "#{message}\n#{captured_stderr.strip}" unless captured_stderr.to_s.strip.empty?
+      raise Error, message
+    end
+
+    def raise_spawn_error(command, details = 'Executable was not found')
+      message = "Command could not be executed: #{Shellwords.join(command.map(&:to_s))}"
+      raise Error, "#{message}\n#{details}"
+    end
+  end
+end

data/lib/release_ceremony/semver.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'rubygems/version'
+
+module ReleaseCeremony
+  # A strict X.Y.Z release version: no prereleases, no leading zeroes.
+  class Semver
+    include Comparable
+
+    PATTERN = /\A(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\z/
+    ERROR_MESSAGE = 'Version must use the X.Y.Z format'
+
+    class << self
+      def parse(value)
+        raise Error, ERROR_MESSAGE unless value.is_a?(String) && PATTERN.match?(value)
+
+        new(value)
+      end
+
+      private :new
+    end
+
+    def initialize(value)
+      @value = value
+      @gem_version = Gem::Version.new(value)
+    end
+
+    def <=>(other)
+      return unless other.is_a?(self.class)
+
+      gem_version <=> other.gem_version
+    end
+
+    def to_s
+      value
+    end
+
+    def tag
+      "v#{value}"
+    end
+
+    protected
+
+    attr_reader :gem_version
+
+    private
+
+    attr_reader :value
+  end
+end

data/lib/release_ceremony/tag_inspector.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ReleaseCeremony
+  # Reports where the release tag currently points, locally and on the
+  # remote, refusing to guess when the tag data looks unexpected.
+  class TagInspector
+    TagState = Struct.new(:local_sha, :remote_sha, keyword_init: true)
+
+    def initialize(version:, runner:, remote:)
+      @version = version
+      @runner = runner
+      @remote = remote
+    end
+
+    def call
+      TagState.new(local_sha: local_tag_sha, remote_sha: remote_tag_sha)
+    end
+
+    private
+
+    attr_reader :remote, :runner, :version
+
+    def local_tag_sha
+      reference = "refs/tags/#{version.tag}"
+      return unless local_tag_exists?(reference)
+
+      resolve_local_tag(reference)
+    end
+
+    def local_tag_exists?(reference)
+      output = runner.capture('git', 'for-each-ref', '--format=%(refname)', reference)
+      return false if output.empty?
+      raise Error, "Unexpected local tag data for #{version.tag}" unless output.lines.map(&:strip) == [reference]
+
+      true
+    end
+
+    def resolve_local_tag(reference)
+      sha = runner.capture('git', 'rev-parse', '--verify', "#{reference}^{commit}").strip
+      raise Error, "Local tag #{version.tag} does not resolve to a commit" unless commit_sha?(sha)
+
+      sha
+    end
+
+    def remote_tag_sha
+      reference = "refs/tags/#{version.tag}"
+      output = runner.capture('git', 'ls-remote', '--tags', remote, reference, "#{reference}^{}")
+      return if output.empty?
+
+      entries = parse_remote_tag_entries(output, reference)
+      entries.fetch("#{reference}^{}", entries[reference])
+    end
+
+    def parse_remote_tag_entries(output, reference)
+      pairs = output.lines.map { |line| line.strip.split(/\s+/, 2) }
+      raise Error, "Unexpected remote tag data for #{version.tag}" unless valid_remote_tag_pairs?(pairs, reference)
+
+      pairs.to_h { |sha, name| [name, sha] }
+    end
+
+    def valid_remote_tag_pairs?(pairs, reference)
+      names = pairs.map(&:last)
+      unique = names.uniq.length == pairs.length
+      pairs.all? { |pair| valid_remote_tag_pair?(pair, reference) } && unique && names.include?(reference)
+    end
+
+    def valid_remote_tag_pair?(pair, reference)
+      sha, name = pair
+      commit_sha?(sha) && [reference, "#{reference}^{}"].include?(name)
+    end
+
+    def commit_sha?(value)
+      value.is_a?(String) && value.match?(/\A[0-9a-f]{40}(?:[0-9a-f]{24})?\z/)
+    end
+  end
+end

data/lib/release_ceremony/transactional_writer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module ReleaseCeremony
+  # Replaces a set of files atomically: every replacement and a backup of
+  # every original are staged as sibling temporary files first, so a failure
+  # while installing can restore the originals.
+  class TransactionalWriter
+    Artifact = Struct.new(:target, :replacement, :backup, keyword_init: true)
+
+    def initialize(renamer: File.method(:rename))
+      @renamer = renamer
+    end
+
+    def write(changes)
+      artifacts = stage_changes(changes)
+      install(artifacts)
+      true
+    ensure
+      cleanup(artifacts || [])
+    end
+
+    private
+
+    attr_reader :renamer
+
+    def stage_changes(changes)
+      artifacts = {}
+      changes.each { |target, contents| artifacts[target] = stage_change(target, contents) }
+      artifacts.values
+    rescue SystemCallError, IOError => e
+      cleanup(artifacts.values)
+      raise Error, "Could not stage release files: #{e.message}"
+    end
+
+    def stage_change(target, contents)
+      mode = File.stat(target).mode & 0o7777
+      replacement = stage_file(target, contents, mode)
+      backup = stage_file(target, File.binread(target), mode)
+      Artifact.new(target: target, replacement: replacement, backup: backup)
+    rescue SystemCallError, IOError
+      cleanup_tempfiles([replacement, backup].compact)
+      raise
+    end
+
+    def stage_file(target, contents, mode)
+      tempfile = Tempfile.new([".#{File.basename(target)}.release-", '.tmp'], File.dirname(target))
+      tempfile.binmode
+      tempfile.write(contents)
+      tempfile.flush
+      tempfile.close
+      File.chmod(mode, tempfile.path)
+      tempfile
+    rescue SystemCallError, IOError
+      cleanup_tempfiles([tempfile].compact)
+      raise
+    end
+
+    def install(artifacts)
+      artifacts.each { |artifact| renamer.call(artifact.replacement.path, artifact.target) }
+    rescue SystemCallError, IOError => e
+      raise installation_error(e, rollback(artifacts))
+    end
+
+    def rollback(artifacts)
+      artifacts.filter_map do |artifact|
+        renamer.call(artifact.backup.path, artifact.target)
+        nil
+      rescue SystemCallError, IOError => e
+        "#{artifact.target}: #{e.message}"
+      end
+    end
+
+    def installation_error(cause, rollback_errors)
+      message = "Could not install release files: #{cause.message}"
+      if rollback_errors.empty?
+        Error.new("#{message}; original release files were restored")
+      else
+        details = rollback_errors.join(', ')
+        Error.new("#{message}; rollback failed for #{details}; release files may be inconsistent")
+      end
+    end
+
+    def cleanup(artifacts)
+      tempfiles = artifacts.flat_map { |artifact| [artifact.replacement, artifact.backup] }
+      cleanup_tempfiles(tempfiles)
+    end
+
+    def cleanup_tempfiles(tempfiles)
+      tempfiles.each do |tempfile|
+        tempfile.close
+        FileUtils.rm_f(tempfile.path)
+      rescue SystemCallError, IOError
+        nil
+      end
+    end
+  end
+end

data/lib/release_ceremony/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ReleaseCeremony
+  VERSION = '1.0.0'
+end

data/lib/release_ceremony/workflow_finder.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module ReleaseCeremony
+  # Polls GitHub Actions for the workflow run triggered by pushing the
+  # release tag, returning its run ID once it appears.
+  class WorkflowFinder
+    POLL_ATTEMPTS = 12
+    POLL_INTERVAL = 5
+
+    def initialize(version:, runner:, sha:, workflow_file:)
+      @version = version
+      @runner = runner
+      @sha = sha
+      @workflow_file = workflow_file
+    end
+
+    def call
+      POLL_ATTEMPTS.times do
+        run_id = workflow_run_id(runner.capture(*command))
+        return run_id if run_id
+
+        runner.sleep(POLL_INTERVAL)
+      end
+      raise Error, "Release workflow did not appear for #{sha} after 60 seconds"
+    end
+
+    private
+
+    attr_reader :runner, :sha, :version, :workflow_file
+
+    def command
+      [
+        'gh', 'run', 'list', '--workflow', workflow_file, '--commit', sha, '--event', 'push', '--limit', '100',
+        '--json', 'databaseId,headBranch,headSha,event,createdAt'
+      ]
+    end
+
+    def workflow_run_id(output)
+      runs = parse_json(output)
+      validate_workflow_runs!(runs)
+      matching_runs = runs.select { |run| requested_tag_push?(run) }
+      return if matching_runs.empty?
+
+      matching_runs.max_by { |run| Time.iso8601(run.fetch('createdAt')) }.fetch('databaseId')
+    end
+
+    def parse_json(output)
+      JSON.parse(output)
+    rescue JSON::ParserError => e
+      raise Error, "Malformed release workflow run JSON: #{e.message}"
+    end
+
+    def validate_workflow_runs!(runs)
+      raise Error, 'Malformed release workflow run data: expected a JSON array' unless runs.is_a?(Array)
+      return if runs.all? { |run| valid_workflow_run?(run) }
+
+      raise Error, 'Release workflow run data is missing a databaseId or valid ref, SHA, event, or createdAt'
+    end
+
+    def valid_workflow_run?(run)
+      return false unless run.is_a?(Hash)
+
+      id = run['databaseId']
+      strings = %w[headBranch headSha event createdAt].map { |key| run[key] }
+      id.is_a?(Integer) && id.positive? && strings.all? { |value| present?(value) } && valid_time?(run['createdAt'])
+    end
+
+    def valid_time?(value)
+      Time.iso8601(value)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    def requested_tag_push?(run)
+      run['headBranch'] == version.tag && run['headSha'] == sha && run['event'] == 'push'
+    end
+
+    def present?(value)
+      value.is_a?(String) && !value.empty?
+    end
+  end
+end

data/lib/release_ceremony.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'release_ceremony/version'
+require_relative 'release_ceremony/error'
+require_relative 'release_ceremony/semver'
+require_relative 'release_ceremony/runner'
+require_relative 'release_ceremony/project'
+require_relative 'release_ceremony/command'
+require_relative 'release_ceremony/transactional_writer'
+require_relative 'release_ceremony/changelog'
+require_relative 'release_ceremony/prepare'
+require_relative 'release_ceremony/tag_inspector'
+require_relative 'release_ceremony/workflow_finder'
+require_relative 'release_ceremony/pull_request_finder'
+require_relative 'release_ceremony/publish'
+require_relative 'release_ceremony/cli'