semverve 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d9765e973d77ca7011cb819202246f5ea7ef2faef574c66a58fc6ad5c058988
-  data.tar.gz: dea8769f32c6f6b70c81d05e2d46129cd9820a8289fbd032f42303dfc0b8dea3
+  metadata.gz: 91afb799328562d219bfe20353b21fd1158edaac251765ec88fd789fd17bdf5c
+  data.tar.gz: b5b4a04dab5c048344804256fb690de2d69155f311c77696e5b90f59d095f1d1
 SHA512:
-  metadata.gz: 38b4aca2a29cfc750a7b6b7164219595ec35f76c9c5d526f441e469868686a6588170ee0e88c02942b97b59725d1c72c79b1496cad5880264042d99c8049846a
-  data.tar.gz: 7cf79a5a6d90a0f454ce03272e5592b140fff266893fee323b6e831ab28956104e7865bb5a141614e6cae6466a4bacbbd738850f299fd98d7f1024f391d61b7c
+  metadata.gz: 7c15980531e364e12460998b7e0f8c0e2d7ae30829cf690dc5d93a2e57296a46b1b2c6a365c27093d89603e605bc9261a5ceaec0ec2014ef6f5b7deaaedbbff8
+  data.tar.gz: a3443c1637f4d382c7de5fab79da81e09422c4faeb09357b2d0da786212c3da23d9dd0aad45d420cf3b89ee0453fbf68ef0cc1cc4b6d7925e8556a131a5a926a

data/CONTRIBUTING.md

@@ -75,26 +75,10 @@ bundle exec rake rdoc:coverage
 
 RDoc uses `README.md` as the main page and documents files under `lib/**/*.rb`.
 Generated documentation is written to `docs/`, which is ignored on development
-branches. The generated site is maintained on the `gh-pages` branch for GitHub
-Pages.
-
-Publish generated docs with:
-
-```sh
-bundle exec rake docs:publish
-```
-
-That task runs `rerdoc`, opens `gh-pages` in a temporary Git worktree, copies
-the generated `docs/` output there, commits changed docs, pushes to
-`origin/gh-pages`, and removes the temporary worktree. To preview whether
-publishing would change the docs branch without committing or pushing, run:
-
-```sh
-bundle exec rake docs:publish:dry_run
-```
+branches.
 
 Keep public RDoc comments current as code changes so `bundle exec rake
-rdoc:coverage` stays clean and the published API docs remain useful.
+rdoc:coverage` stays clean and the API docs remain useful.
 
 When changing behavior, update the README at the same time. The README is the
 primary user guide, so examples should match real task names, configuration
@@ -166,7 +150,6 @@ bundle exec rake standard
 bundle exec rake rdoc:coverage
 bundle exec rake rerdoc
 bundle exec rake build
-bundle exec rake docs:publish:dry_run
 ```
 
 The build task writes the packaged gem under `pkg/`. Inspect the package if you

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    semverve (0.4.0)
+    semverve (0.4.1)
 
 GEM
   remote: https://rubygems.org/

data/Rakefile

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "lib/semverve/task"
-require_relative "lib/semverve/docs_publisher/task"
 require "bundler/gem_tasks"
 require "rdoc/task"
 require "rake/testtask"
@@ -24,8 +23,6 @@ Semverve::Task.new do |t|
   t.version_code_reference_files.append("lib/**/*.rb", "semverve.gemspec", "Rakefile")
 end
 
-Semverve::DocsPublisher::Task.new
-
 standardrb = ->(*args) do
   sh(["bundle", "exec", "standardrb", *args].join(" "))
 end

data/lib/semverve/version.rb

@@ -21,7 +21,7 @@ module Semverve
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 0
+    PATCH = 1
 
     module_function
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semverve
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Evan Gray
@@ -111,8 +111,6 @@ files:
 - lib/semverve.rb
 - lib/semverve/adapters.rb
 - lib/semverve/configuration.rb
-- lib/semverve/docs_publisher.rb
-- lib/semverve/docs_publisher/task.rb
 - lib/semverve/error.rb
 - lib/semverve/file_list_resolver.rb
 - lib/semverve/finding.rb

data/lib/semverve/docs_publisher/task.rb

@@ -1,166 +0,0 @@
-# frozen_string_literal: true
-
-require "rake"
-
-require_relative "../docs_publisher"
-
-module Semverve
-  class DocsPublisher
-    ##
-    # Defines Rake tasks for publishing generated documentation.
-    class Task
-      include Rake::DSL
-
-      ##
-      # Source project root.
-      #
-      # @return [String]
-      attr_accessor :root
-
-      ##
-      # Rake task that builds documentation before publishing.
-      #
-      # @return [String]
-      attr_accessor :build_task
-
-      ##
-      # Directory containing generated documentation.
-      #
-      # @return [String]
-      attr_accessor :source_dir
-
-      ##
-      # Documentation directory on the publishing branch.
-      #
-      # @return [String]
-      attr_accessor :target_dir
-
-      ##
-      # Branch that receives generated documentation.
-      #
-      # @return [String]
-      attr_accessor :branch
-
-      ##
-      # Remote used when pushing the publishing branch.
-      #
-      # @return [String]
-      attr_accessor :remote
-
-      ##
-      # Commit message for generated documentation updates.
-      #
-      # @return [String]
-      attr_accessor :commit_message
-
-      ##
-      # Optional path for the temporary worktree.
-      #
-      # @return [String, nil]
-      attr_accessor :worktree_path
-
-      ##
-      # Whether dirty source working trees are allowed.
-      #
-      # @return [Boolean]
-      attr_accessor :allow_dirty
-
-      ##
-      # Whether the publishing branch should be pushed.
-      #
-      # @return [Boolean]
-      attr_accessor :push
-
-      ##
-      # Output stream for status messages.
-      #
-      # @return [#puts]
-      attr_accessor :output
-
-      ##
-      # Namespace for the generated tasks.
-      #
-      # @return [Symbol, String]
-      attr_accessor :task_namespace
-
-      ##
-      # Initializes and defines documentation publishing tasks.
-      #
-      # @yieldparam [Semverve::DocsPublisher::Task] task
-      #
-      # @return [Semverve::DocsPublisher::Task]
-      def initialize
-        @root = Dir.pwd
-        @build_task = "rerdoc"
-        @source_dir = "docs"
-        @target_dir = "docs"
-        @branch = "gh-pages"
-        @remote = "origin"
-        @commit_message = "Update generated documentation"
-        @worktree_path = nil
-        @allow_dirty = false
-        @push = true
-        @output = $stdout
-        @task_namespace = :docs
-
-        yield self if block_given?
-
-        define
-      end
-
-      ##
-      # Defines the documentation publishing tasks.
-      #
-      # @return [void]
-      def define
-        namespace namespace_name do
-          desc "Publish generated documentation to #{branch}"
-          task :publish do
-            publish(dry_run: false)
-          end
-
-          namespace :publish do
-            desc "Show whether generated documentation would change #{branch}"
-            task :dry_run do
-              publish(dry_run: true)
-            end
-          end
-        end
-      end
-
-      private
-
-      ##
-      # Normalized namespace name.
-      #
-      # @return [Symbol]
-      def namespace_name
-        task_namespace.to_sym
-      end
-
-      ##
-      # Builds and publishes documentation.
-      #
-      # @param [Boolean] dry_run
-      #
-      # @return [void]
-      def publish(dry_run:)
-        Rake::Task[build_task].invoke
-
-        DocsPublisher.new do |publisher|
-          publisher.root = root
-          publisher.source_dir = source_dir
-          publisher.target_dir = target_dir
-          publisher.branch = branch
-          publisher.remote = remote
-          publisher.commit_message = commit_message
-          publisher.worktree_path = worktree_path
-          publisher.allow_dirty = allow_dirty
-          publisher.push = push
-          publisher.dry_run = dry_run
-          publisher.output = output
-        end.publish
-      end
-    end
-  end
-end

data/lib/semverve/docs_publisher.rb

@@ -1,370 +0,0 @@
-# frozen_string_literal: true
-
-# TODO: Turn this into its own gem.
-
-require "fileutils"
-require "open3"
-require "tmpdir"
-
-require_relative "error"
-
-module Semverve
-  ##
-  # Publishes generated documentation to a Git branch through a temporary
-  # worktree.
-  class DocsPublisher
-    ##
-    # Small command runner used by the publisher.
-    class Shell
-      ##
-      # Runs a command and raises when it fails.
-      #
-      # @param [Array<String>] command
-      # @param [String, nil] chdir
-      #
-      # @return [String]
-      def run(command, chdir: nil)
-        stdout, stderr, status = capture_command(command, chdir: chdir)
-        return stdout if status.success?
-
-        raise Error, "Command failed: #{command.join(" ")}\n#{stderr}"
-      end
-
-      ##
-      # Captures a command's standard output and raises when it fails.
-      #
-      # @param [Array<String>] command
-      # @param [String, nil] chdir
-      #
-      # @return [String]
-      def capture(command, chdir: nil)
-        run(command, chdir: chdir)
-      end
-
-      ##
-      # Whether a command exits successfully.
-      #
-      # @param [Array<String>] command
-      # @param [String, nil] chdir
-      #
-      # @return [Boolean]
-      def success?(command, chdir: nil)
-        _stdout, _stderr, status = capture_command(command, chdir: chdir)
-        status.success?
-      end
-
-      private
-
-      ##
-      # Captures a command, omitting +chdir+ when none was provided.
-      #
-      # @param [Array<String>] command
-      # @param [String, nil] chdir
-      #
-      # @return [Array(String, String, Process::Status)]
-      def capture_command(command, chdir:)
-        options = chdir ? {chdir: chdir} : {}
-
-        Open3.capture3(*command, **options)
-      end
-    end
-
-    ##
-    # Source project root.
-    #
-    # @return [String]
-    attr_accessor :root
-
-    ##
-    # Directory containing generated documentation, relative to +root+.
-    #
-    # @return [String]
-    attr_accessor :source_dir
-
-    ##
-    # Documentation directory on the publishing branch.
-    #
-    # @return [String]
-    attr_accessor :target_dir
-
-    ##
-    # Branch that receives generated documentation.
-    #
-    # @return [String]
-    attr_accessor :branch
-
-    ##
-    # Remote used when pushing the publishing branch.
-    #
-    # @return [String]
-    attr_accessor :remote
-
-    ##
-    # Commit message for generated documentation updates.
-    #
-    # @return [String]
-    attr_accessor :commit_message
-
-    ##
-    # Optional path for the temporary worktree.
-    #
-    # @return [String, nil]
-    attr_accessor :worktree_path
-
-    ##
-    # Whether dirty source working trees are allowed.
-    #
-    # @return [Boolean]
-    attr_accessor :allow_dirty
-
-    ##
-    # Whether the publishing branch should be pushed.
-    #
-    # @return [Boolean]
-    attr_accessor :push
-
-    ##
-    # Whether to report changes without committing or pushing.
-    #
-    # @return [Boolean]
-    attr_accessor :dry_run
-
-    ##
-    # Command runner used for Git commands.
-    #
-    # @return [#run, #capture, #success?]
-    attr_accessor :command_runner
-
-    ##
-    # Output stream for status messages.
-    #
-    # @return [#puts]
-    attr_accessor :output
-
-    ##
-    # Initializes a documentation publisher.
-    #
-    # @yieldparam [Semverve::DocsPublisher] publisher
-    #
-    # @return [Semverve::DocsPublisher]
-    def initialize
-      @root = Dir.pwd
-      @source_dir = "docs"
-      @target_dir = "docs"
-      @branch = "gh-pages"
-      @remote = "origin"
-      @commit_message = "Update generated documentation"
-      @worktree_path = nil
-      @allow_dirty = false
-      @push = true
-      @dry_run = false
-      @command_runner = Shell.new
-      @output = $stdout
-
-      yield self if block_given?
-    end
-
-    ##
-    # Publishes generated documentation.
-    #
-    # @return [Boolean] whether documentation changes were found
-    def publish
-      validate!
-      ensure_clean_source_worktree unless allow_dirty
-
-      with_worktree do |worktree|
-        sync_docs_to(worktree)
-
-        unless publishing_worktree_changed?(worktree)
-          output.puts "Documentation is already current on #{branch}."
-          return false
-        end
-
-        if dry_run
-          output.puts "Documentation changes detected for #{branch}; dry run did not commit or push."
-          return true
-        end
-
-        commit_docs(worktree)
-        push_docs(worktree) if push
-        output.puts "Published documentation to #{remote}/#{branch}."
-        true
-      end
-    end
-
-    private
-
-    ##
-    # Validates publishing configuration.
-    #
-    # @return [void]
-    def validate!
-      raise Error, "Documentation source directory does not exist: #{source_path}." unless File.directory?(source_path)
-
-      if target_dir.nil? || target_dir.empty? || target_dir == "." || target_dir.start_with?("/")
-        raise Error, "target_dir must be a relative directory such as \"docs\"."
-      end
-    end
-
-    ##
-    # Absolute source project root.
-    #
-    # @return [String]
-    def source_root
-      @source_root ||= File.expand_path(root)
-    end
-
-    ##
-    # Absolute source documentation directory.
-    #
-    # @return [String]
-    def source_path
-      File.expand_path(source_dir, source_root)
-    end
-
-    ##
-    # Ensures the source working tree is clean.
-    #
-    # @return [void]
-    def ensure_clean_source_worktree
-      status = git_capture(source_root, "status", "--porcelain")
-      return if status.empty?
-
-      raise Error, "Working tree must be clean before publishing documentation. Commit, stash, or set allow_dirty."
-    end
-
-    ##
-    # Yields a temporary publishing worktree and removes it afterward.
-    #
-    # @yieldparam [String] worktree
-    #
-    # @return [Object]
-    def with_worktree
-      temporary_path = worktree_path || Dir.mktmpdir("semverve-docs-publish-")
-      temporary_worktree = worktree_path.nil?
-      worktree_added = false
-
-      if temporary_worktree
-        FileUtils.rm_rf(temporary_path)
-      elsif File.exist?(temporary_path)
-        raise Error, "Worktree path already exists: #{temporary_path}."
-      end
-
-      add_worktree(temporary_path)
-      worktree_added = true
-      yield temporary_path
-    ensure
-      remove_worktree(temporary_path) if temporary_path && worktree_added
-      FileUtils.rm_rf(temporary_path) if temporary_path && temporary_worktree
-    end
-
-    ##
-    # Adds a worktree for the publishing branch.
-    #
-    # @param [String] path
-    #
-    # @return [void]
-    def add_worktree(path)
-      if local_branch?
-        git_run(source_root, "worktree", "add", path, branch)
-      elsif remote_branch?
-        git_run(source_root, "worktree", "add", "-b", branch, path, "#{remote}/#{branch}")
-      else
-        raise Error, "Could not find #{branch} locally or at #{remote}/#{branch}."
-      end
-    end
-
-    ##
-    # Removes a worktree.
-    #
-    # @param [String] path
-    #
-    # @return [void]
-    def remove_worktree(path)
-      git_run(source_root, "worktree", "remove", "--force", path) if File.directory?(path)
-    end
-
-    ##
-    # Whether the publishing branch exists locally.
-    #
-    # @return [Boolean]
-    def local_branch?
-      command_runner.success?(["git", "show-ref", "--verify", "--quiet", "refs/heads/#{branch}"], chdir: source_root)
-    end
-
-    ##
-    # Whether the publishing branch exists as a remote-tracking branch.
-    #
-    # @return [Boolean]
-    def remote_branch?
-      command_runner.success?(["git", "show-ref", "--verify", "--quiet", "refs/remotes/#{remote}/#{branch}"], chdir: source_root)
-    end
-
-    ##
-    # Copies generated documentation into the publishing worktree.
-    #
-    # @param [String] worktree
-    #
-    # @return [void]
-    def sync_docs_to(worktree)
-      target_path = File.expand_path(target_dir, worktree)
-
-      FileUtils.rm_rf(target_path)
-      FileUtils.mkdir_p(File.dirname(target_path))
-      FileUtils.cp_r(source_path, target_path)
-    end
-
-    ##
-    # Whether the publishing worktree has documentation changes.
-    #
-    # @param [String] worktree
-    #
-    # @return [Boolean]
-    def publishing_worktree_changed?(worktree)
-      !git_capture(worktree, "status", "--porcelain", "--", target_dir).empty?
-    end
-
-    ##
-    # Commits documentation changes in the publishing worktree.
-    #
-    # @param [String] worktree
-    #
-    # @return [void]
-    def commit_docs(worktree)
-      git_run(worktree, "add", target_dir)
-      git_run(worktree, "commit", "-m", commit_message)
-    end
-
-    ##
-    # Pushes documentation changes.
-    #
-    # @param [String] worktree
-    #
-    # @return [void]
-    def push_docs(worktree)
-      git_run(worktree, "push", remote, branch)
-    end
-
-    ##
-    # Runs a Git command in a directory.
-    #
-    # @param [String] directory
-    # @param [Array<String>] arguments
-    #
-    # @return [String]
-    def git_run(directory, *arguments)
-      command_runner.run(["git", *arguments], chdir: directory)
-    end
-
-    ##
-    # Captures a Git command in a directory.
-    #
-    # @param [String] directory
-    # @param [Array<String>] arguments
-    #
-    # @return [String]
-    def git_capture(directory, *arguments)
-      command_runner.capture(["git", *arguments], chdir: directory)
-    end
-  end
-end