semverve 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f0366a11f400a32928725b5f954c9f71e3659a75cb5757cf268a3efc018659c
-  data.tar.gz: 870ae675510264ea80bc7a44dbe86efd5248a4020a98f3884b3123cb1f68bea6
+  metadata.gz: b04f97b571e0eed652d155221cddb5afe06d703f2a27546f15c11e3d26a3d214
+  data.tar.gz: 6c824db22d1967e9daa8de369ca199b6cc7969f6ab2179933600fbba34d1aa6e
 SHA512:
-  metadata.gz: e945ab75c4b9b4eaf3d232ccc5f0be75b7c024a37e9f5488c2a9d31cefe1bfbd1bc6105b27f1b9d51d600d393ea2ca5b3a51445d9bf712ef279a362192ba5166
-  data.tar.gz: 5dcdc6bb2287825fe348c84c289878f76b06e2b453257848990dc1c9cf42a3581dbafc2fd65e04d88ed2861a2f2c17496ce865d929823c5f8bd36e4e8acff13e
+  metadata.gz: 31208572bd96d1d1bb00537673e9960594501a2b4226f821114d8cb624965fd0cd7282722d6284cf0666f80a908706174a3ca3d0bb4109a3b18dc882e9a26ecd
+  data.tar.gz: 8deb952db13cfdf0f8a13fbbcffb07afc23c402ece2efc3d50899d4158ea7455a6bedc993cb79c9d3de8dfc83c8142981f87f52777ee79a8dba1c1b09bc58dcd

data/.gitignore

@@ -1,3 +1,4 @@
 semverve-*.gem
 coverage/*
 docs/*
+_config.yml

data/CONTRIBUTING.md

@@ -100,6 +100,27 @@ 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
 names, defaults, and output.
 
+## Rake Task Interface Design
+Semverve should feel natural from a shell while staying Rake-native. Prefer
+Rake task arguments for direct task inputs:
+
+```sh
+bundle exec rake 'semverve:set[x.y.z]'
+bundle exec rake 'semverve:generate[simple,force]'
+```
+
+For tasks with more than one optional value, prefer meaning-bearing tokens over
+strict positional placeholders. For example, `semverve:generate` treats semantic
+versions as the generated version, `module` or `simple` as the format, and
+`force` as the overwrite mode. That keeps invocations like
+`rake 'semverve:generate[simple]'` and `rake 'semverve:generate[force]'`
+readable without requiring awkward empty slots.
+
+Reserve environment variables for cross-cutting runtime toggles that compose
+across related tasks, such as `SEMVERVE_REPORT_IGNORED=true rake
+semverve:check`. Avoid generic environment variables like `VERSION`, `FORMAT`,
+or `FORCE`; they can collide with a user's shell, CI, or parent build process.
+
 ## Versioning and Release Checks
 Semverve uses Semverve to maintain itself, which doubles as useful
 smoke-testing. The project Rakefile requires `lib/semverve/task` and installs
@@ -123,7 +144,7 @@ bundle exec rake semverve:current
 bundle exec rake semverve:increment:patch
 bundle exec rake semverve:increment:minor
 bundle exec rake semverve:increment:major
-bundle exec rake semverve:set VERSION=x.y.z
+bundle exec rake 'semverve:set[x.y.z]'
 bundle exec rake semverve:check
 bundle exec rake semverve:fix
 ```

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    semverve (0.1.0)
+    semverve (0.2.1)
 
 GEM
   remote: https://rubygems.org/
@@ -84,10 +84,10 @@ PLATFORMS
 DEPENDENCIES
   rake (~> 13.0, >= 13.0.1)
   rdoc
+  semverve!
   simplecov
   standard (~> 1.54.0)
   test-unit (~> 3.3, >= 3.3.5)
-  semverve!
 
 BUNDLED WITH
   4.0.10

data/README.md

@@ -1,4 +1,9 @@
 # Semverve
+[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fevanthegrayt%2Fsemverve%2Fbadge%3Fref%3Dmaster&style=flat)](https://actions-badge.atrox.dev/evanthegrayt/semverve/goto?ref=master)
+[![Language: Ruby](https://img.shields.io/static/v1?label=language&message=Ruby&color=CC342D&style=flat&logo=ruby&logoColor=CC342D)](https://www.ruby-lang.org/)
+[![Gem Version](https://img.shields.io/gem/v/semverve.svg)](https://rubygems.org/gems/semverve)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Rake tasks for handling the tedium surrounding maintaining a version number in
 your Ruby project, with gusto!
 
@@ -26,6 +31,9 @@ tasks can update safe references and run `bundle lock` for generated lockfile
 drift. Specific findings can be skipped with magic comments, similar to RuboCop
 and RDoc.
 
+You can view the documentation
+[here](https://evanthegrayt.github.io/semverve/).
+
 ## Installation
 Add the gem to your Gemfile:
 
@@ -47,7 +55,7 @@ rake semverve:increment:patch
 rake semverve:increment:minor
 rake semverve:increment:major
 rake semverve:generate
-rake semverve:set VERSION=1.2.3
+rake 'semverve:set[1.2.3]'
 rake semverve:check
 rake semverve:fix
 rake semverve:check:references
@@ -56,6 +64,8 @@ rake semverve:check:code
 rake semverve:fix:code
 rake semverve:check:metadata
 rake semverve:fix:metadata
+rake semverve:check:rubygems
+rake semverve:check:release
 ```
 
 ## Configuration
@@ -81,6 +91,8 @@ Semverve.configure do |config|
   config.version_file = "lib/my_gem/version.rb"
   config.module_name = "MyGem"
   config.version_checks = [:doc_references, :code_references, :metadata]
+  config.release_checks = [:rubygems]
+  config.rubygems_host = "https://rubygems.org"
   config.version_code_reference_files.append("lib/**/*.rb")
   config.version_doc_reference_files.append("doc/**/*.md")
   config.version_reference_mode = :non_current
@@ -95,6 +107,8 @@ Semverve.configure do |config|
   config.bundle_lock = false
   config.root = Dir.pwd
   config.version_checks = [:doc_references, :code_references, :metadata]
+  config.release_checks = []
+  config.rubygems_host = "https://rubygems.org"
   config.version_reference_mode = :older
   config.version_code_reference_files = Rake::FileList[]
   config.version_code_reference_pattern =
@@ -111,6 +125,23 @@ end
 The empty `version_code_reference_files` default only applies to arbitrary code
 literal scanning. `rake semverve:check` still checks the resolved `.gemspec`
 version and matching `Gemfile.lock` entry through its default metadata check.
+Release checks are empty by default because they may make network requests and
+are intended for release pipelines rather than every local or pull-request run.
+
+Semverve tasks use Rake task arguments for values:
+
+```sh
+rake 'semverve:set[1.2.3]'
+rake 'semverve:generate[1.0.0,simple]'
+rake 'semverve:generate[simple]'
+rake 'semverve:generate[force]'
+```
+
+Quote task invocations that include square brackets. Shells such as zsh may
+otherwise treat brackets as glob patterns before Rake sees them. Flag syntax
+such as `rake semverve:set --version 1.2.3` is not used because `--version` is
+already a Rake option; Semverve stays within Rake's native argument syntax
+instead.
 
 The gem name, module name, and version-file path are inferred by default:
 
@@ -138,48 +169,6 @@ Semverve::Task.new do |config|
 end
 ```
 
-## Publishing generated docs
-Semverve also includes an optional GitHub Pages publishing task for generated
-documentation. It builds docs on your current branch, opens the publishing
-branch in a temporary Git worktree, copies the generated docs there, commits any
-changes, and pushes the publishing branch.
-
-Add this to your Rakefile:
-
-```ruby
-require "semverve/docs_publisher/task"
-
-Semverve::DocsPublisher::Task.new
-```
-
-This defines:
-
-```text
-rake docs:publish
-rake docs:publish:dry_run
-```
-
-The defaults are equivalent to:
-
-```ruby
-Semverve::DocsPublisher::Task.new do |task|
-  task.root = Dir.pwd
-  task.build_task = "rerdoc"
-  task.source_dir = "docs"
-  task.target_dir = "docs"
-  task.branch = "gh-pages"
-  task.remote = "origin"
-  task.commit_message = "Update generated documentation"
-  task.allow_dirty = false
-  task.push = true
-  task.output = $stdout
-end
-```
-
-`docs:publish` requires a clean working tree by default. Set
-`task.allow_dirty = true` only when you intentionally want to publish generated
-documentation from uncommitted source changes.
-
 ## Rails apps
 Rails applications do not need gem-style version files, but an application
 version can still be useful for release notes, support/debug screens,
@@ -261,13 +250,25 @@ rake semverve:generate
 Generate a specific version or format:
 
 ```sh
-rake semverve:generate VERSION=1.0.0 FORMAT=simple
+rake 'semverve:generate[1.0.0,simple]'
+rake 'semverve:generate[simple]'
 ```
 
 Generation fails if the target file already exists. To replace it:
 
 ```sh
-rake semverve:generate FORCE=true
+rake 'semverve:generate[force]'
+```
+
+`semverve:generate` accepts optional tokens for version, format, and force.
+Token order does not matter: semantic versions set the generated version,
+`module` or `simple` sets the format, and `force` overwrites an existing version
+file.
+
+```sh
+rake 'semverve:generate[1.0.0,force]'
+rake 'semverve:generate[simple,force]'
+rake 'semverve:generate[1.0.0,simple,force]'
 ```
 
 ## Incrementing
@@ -293,7 +294,7 @@ your gem's version in `Gemfile.lock`.
 Set an exact version without incrementing:
 
 ```sh
-rake semverve:set VERSION=1.2.3
+rake 'semverve:set[1.2.3]'
 ```
 
 Successful updates print the version change:
@@ -325,6 +326,9 @@ Run every version check with:
 rake semverve:check
 ```
 
+This task is designed for normal CI. It uses local project files, prints
+parseable findings, and exits non-zero when it finds drift.
+
 By default, this checks:
 
 - README version references, plus any configured docs or comment files
@@ -430,6 +434,13 @@ same line or the preceding nonblank line.
 This migration note intentionally mentions 1.0.0. <!-- semverve:ignore-version-reference -->
 ```
 
+Audit ignored references by setting `SEMVERVE_REPORT_IGNORED=true` when running
+check tasks:
+
+```sh
+SEMVERVE_REPORT_IGNORED=true rake semverve:check
+```
+
 ### Code version literals
 Code scanning is opt-in to avoid false positives. This is for arbitrary project
 code, not gem metadata. The default is:
@@ -463,6 +474,13 @@ APP_VERSION = "1.2.2"
 spec.version = "1.2.2"
 ```
 
+Ignore an intentional code literal with `semverve:ignore-version-reference` on
+the same line or the preceding nonblank line.
+
+Set `SEMVERVE_REPORT_IGNORED=true` with `semverve:check` or
+`semverve:check:code` to report ignored stale literals without changing
+`semverve:fix` behavior.
+
 The default pattern is Ruby-oriented. Semverve does not inspect file extensions
 or parse other languages for code literals; non-Ruby files are scanned as plain
 text with the same pattern. If a JavaScript, Python, or other source file uses a
@@ -536,6 +554,110 @@ end
 `rake semverve:fix:metadata` updates safe literal gemspec assignments and
 runs `bundle lock` when the lockfile has drifted.
 
+## Checking release readiness
+Release checks are separate from `rake semverve:check`. They are useful in CI,
+but they are meant for release workflows, tag builds, or pre-publish jobs rather
+than every pull request.
+
+Enable the RubyGems published-version check:
+
+```ruby
+Semverve.configure do |config|
+  config.release_checks = [:rubygems]
+end
+```
+
+Then run:
+
+```sh
+rake semverve:check:release
+```
+
+With `:rubygems` enabled, `semverve:check:release` asks the configured
+RubyGems-compatible host whether the current version already exists. If it does,
+the task exits non-zero with a message like:
+
+```text
+my_gem 1.2.3 already exists on https://rubygems.org.
+```
+
+If all configured release checks pass, it prints:
+
+```text
+Release checks passed.
+```
+
+You can also run the RubyGems check directly without changing
+`config.release_checks`:
+
+```sh
+rake semverve:check:rubygems
+```
+
+When the current version is not published, the focused task prints:
+
+```text
+my_gem 1.2.3 is not published on https://rubygems.org.
+```
+
+Use `config.rubygems_host` for a private RubyGems-compatible server:
+
+```ruby
+Semverve.configure do |config|
+  config.release_checks = [:rubygems]
+  config.rubygems_host = "https://gems.example.com"
+end
+```
+
+The published-version check treats a missing gem as unpublished. It fails closed
+on registry errors, malformed responses, and network failures because release
+pipelines should not silently publish after an inconclusive preflight.
+
+For ordinary CI, keep using the local checks:
+
+```sh
+bundle exec rake test semverve:check
+```
+
+For release CI, run the release check before building or pushing:
+
+```sh
+bundle exec rake semverve:check:release build
+```
+
+## Vim
+While there's no official vim support (yet), you can add the following to
+`~/.vim/plugin/semverve.vim`.
+
+```vim
+command! -bang SemverveAudit call <SID>semverve_audit(<bang>0)
+function! s:semverve_audit(report_ignored) abort
+  let l:old_efm = &errorformat
+  try
+    let &errorformat = '%f:%l:%c:%m'
+    let l:string = ""
+    if !a:report_ignored
+      let l:string .= 'SEMVERVE_REPORT_IGNORED=true '
+    endif
+    let l:string .= 'bundle exec rake semverve:check 2>/dev/null'
+    cexpr systemlist(l:string)
+    if v:shell_error != 0
+      copen
+    else
+      cclose
+      echo 'Semverve checks passed.'
+    endif
+  finally
+    let &errorformat = l:old_efm
+  endtry
+endfunction
+```
+
+You can then call `:SemverveAudit`, which will call `bundle exec rake
+semverve:check`, and `:SemverveAudit!` which will call the same command with
+`SEMVERVE_REPORT_IGNORED=true`, and populate and open the quickfix list if any
+offenses are found.
+
 ## Reporting Bugs and Requesting Features
 If you have an idea or find a bug, please [create an
 issue](https://github.com/evanthegrayt/semverve/issues/new). Just make sure

data/lib/semverve/configuration.rb

@@ -16,6 +16,12 @@ module Semverve
     # @return [Array<Symbol>]
     VALID_VERSION_CHECKS = [:doc_references, :code_references, :metadata].freeze
 
+    ##
+    # Release-readiness surfaces supported by release check tasks.
+    #
+    # @return [Array<Symbol>]
+    VALID_RELEASE_CHECKS = [:rubygems].freeze
+
     ##
     # Default Ruby pattern for code version literals that are safe to rewrite.
     #
@@ -58,12 +64,24 @@ module Semverve
     # @return [Symbol, String, nil]
     attr_reader :preset
 
+    ##
+    # Release-readiness surfaces run by the release check task.
+    #
+    # @return [Array<Symbol, String>]
+    attr_reader :release_checks
+
     ##
     # Project root used when inferring metadata and expanding paths.
     #
     # @return [String, nil]
     attr_reader :root
 
+    ##
+    # RubyGems-compatible host used for published-version checks.
+    #
+    # @return [String]
+    attr_accessor :rubygems_host
+
     ##
     # Explicit version-file path relative to the project root.
     #
@@ -110,6 +128,7 @@ module Semverve
       @command_runner = ->(command) { system(command) }
       @format = :module
       @preset = nil
+      @rubygems_host = "https://rubygems.org"
       @version_code_reference_files = Rake::FileList[]
       self.version_code_reference_pattern = DEFAULT_VERSION_CODE_REFERENCE_PATTERN
       @version_doc_reference_files = Rake::FileList["README*", "**/README*"].exclude(
@@ -119,6 +138,7 @@ module Semverve
         "vendor/**/*"
       )
       @version_reference_mode = :older
+      self.release_checks = []
       self.version_checks = VALID_VERSION_CHECKS
     end
 
@@ -135,7 +155,9 @@ module Semverve
         format: normalized_format,
         gem_name: metadata.gem_name,
         module_name: metadata.module_name,
+        release_checks: normalized_release_checks,
         root: expanded_root,
+        rubygems_host: rubygems_host,
         version_file: metadata.version_file,
         version_checks: normalized_version_checks,
         version_code_reference_files: version_code_reference_files,
@@ -186,6 +208,16 @@ module Semverve
       @preset = preset.nil? ? nil : Presets.fetch(preset).name
     end
 
+    ##
+    # Sets the release-readiness surfaces run by the release check task.
+    #
+    # @param [Array<Symbol, String>] checks
+    #
+    # @return [Array<Symbol>]
+    def release_checks=(checks)
+      @release_checks = normalize_release_checks(checks)
+    end
+
     ##
     # Sets the project root used when expanding paths.
     #
@@ -243,6 +275,14 @@ module Semverve
       resolved_value(:format).to_sym
     end
 
+    ##
+    # Configured release checks normalized for lookup.
+    #
+    # @return [Array<Symbol>]
+    def normalized_release_checks
+      normalize_release_checks(release_checks)
+    end
+
     ##
     # Resolved value for a configurable attribute before metadata inference.
     #
@@ -290,6 +330,22 @@ module Semverve
       raise Error, "Unknown version check #{invalid_checks.map(&:inspect).join(", ")}. Use #{valid_checks}."
     end
 
+    ##
+    # Normalizes and validates release checks.
+    #
+    # @param [Array<Symbol, String>] checks
+    #
+    # @return [Array<Symbol>]
+    def normalize_release_checks(checks)
+      normalized_checks = Array(checks).map do |check|
+        check.respond_to?(:to_sym) ? check.to_sym : check
+      end
+      return normalized_checks if normalized_checks.all? { |check| VALID_RELEASE_CHECKS.include?(check) }
+
+      invalid_checks = normalized_checks.reject { |check| VALID_RELEASE_CHECKS.include?(check) }
+      raise Error, "Unknown release check #{invalid_checks.map(&:inspect).join(", ")}. Use :rubygems."
+    end
+
     ##
     # Validates the configured code reference pattern.
     #
@@ -373,12 +429,24 @@ module Semverve
     # @return [String]
     attr_reader :module_name
 
+    ##
+    # Resolved release-readiness surfaces run by the release check task.
+    #
+    # @return [Array<Symbol>]
+    attr_reader :release_checks
+
     ##
     # Absolute project root.
     #
     # @return [String]
     attr_reader :root
 
+    ##
+    # Resolved RubyGems-compatible host used for published-version checks.
+    #
+    # @return [String]
+    attr_reader :rubygems_host
+
     ##
     # Resolved version-file path relative to the project root.
     #
@@ -423,7 +491,9 @@ module Semverve
     # @param [Symbol] format
     # @param [String] gem_name
     # @param [String] module_name
+    # @param [Array<Symbol>] release_checks
     # @param [String] root
+    # @param [String] rubygems_host
     # @param [String] version_file
     # @param [Array<Symbol>] version_checks
     # @param [Rake::FileList] version_code_reference_files
@@ -438,7 +508,9 @@ module Semverve
       format:,
       gem_name:,
       module_name:,
+      release_checks:,
       root:,
+      rubygems_host:,
       version_file:,
       version_checks:,
       version_code_reference_files:,
@@ -451,7 +523,9 @@ module Semverve
       @format = format
       @gem_name = gem_name
       @module_name = module_name
+      @release_checks = release_checks
       @root = root
+      @rubygems_host = rubygems_host
       @version_file = version_file
       @version_checks = version_checks
       @version_code_reference_files = version_code_reference_files

data/lib/semverve/generator.rb

@@ -11,21 +11,25 @@ module Semverve
   # Generates new Ruby version files from Semverve configuration.
   class Generator
     ##
-    # Default version used when +VERSION+ is not provided.
+    # Default version used when a version argument is not provided.
     #
     # @return [String]
-    DEFAULT_VERSION = "0.1.0"
+    DEFAULT_VERSION = "0.1.0" # semverve:ignore-version-reference
 
     ##
     # Initializes a version-file generator.
     #
     # @param [Semverve::ResolvedConfiguration] configuration
-    # @param [#fetch] env
+    # @param [String, nil] version
+    # @param [String, Symbol, nil] format
+    # @param [Boolean] force
     #
     # @return [Semverve::Generator]
-    def initialize(configuration, env = ENV)
+    def initialize(configuration, version: nil, format: nil, force: false)
       @configuration = configuration
-      @env = env
+      @version = version
+      @format = format
+      @force = force
     end
 
     ##
@@ -33,12 +37,12 @@ module Semverve
     #
     # @return [String]
     def generate
-      version = SemanticVersion.parse(env.fetch("VERSION", DEFAULT_VERSION))
-      format = Formats.fetch(env.fetch("FORMAT", configuration.format))
+      version = SemanticVersion.parse(requested_version)
+      format = Formats.fetch(requested_format)
       path = configuration.absolute_version_file
 
       if File.exist?(path) && !force?
-        raise Error, "Version file already exists at #{path}. Set FORCE=true to overwrite it."
+        raise Error, "Version file already exists at #{path}. Run rake 'semverve:generate[force]' to overwrite it."
       end
 
       FileUtils.mkdir_p(File.dirname(path))
@@ -53,14 +57,30 @@ module Semverve
     # Resolved configuration used for generation.
     #
     # @return [Semverve::ResolvedConfiguration]
-    attr_reader :configuration, :env
+    attr_reader :configuration, :version, :format, :force
+
+    ##
+    # Requested version or default.
+    #
+    # @return [String]
+    def requested_version
+      version || DEFAULT_VERSION
+    end
+
+    ##
+    # Requested format or configured default.
+    #
+    # @return [String, Symbol]
+    def requested_format
+      format || configuration.format
+    end
 
     ##
     # Whether generation should overwrite an existing version file.
     #
     # @return [Boolean]
     def force?
-      env.fetch("FORCE", "false").match?(/\A(true|1|yes)\z/i)
+      force
     end
   end
 end

data/lib/semverve/published_version.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "timeout"
+require "uri"
+
+require_relative "error"
+
+module Semverve
+  ##
+  # Checks whether the current gem version already exists on a
+  # RubyGems-compatible host.
+  class PublishedVersion
+    class << self
+      ##
+      # Callable used to fetch RubyGems-compatible API responses.
+      #
+      # @return [#call]
+      attr_writer :http_getter
+
+      ##
+      # Returns the HTTP response fetcher.
+      #
+      # @return [#call]
+      def http_getter
+        @http_getter ||= ->(uri) { Net::HTTP.get_response(uri) }
+      end
+    end
+
+    ##
+    # Initializes a published-version check.
+    #
+    # @param [Semverve::ResolvedConfiguration] configuration
+    # @param [Semverve::SemanticVersion] current_version
+    #
+    # @return [Semverve::PublishedVersion]
+    def initialize(configuration, current_version)
+      @configuration = configuration
+      @current_version = current_version
+    end
+
+    ##
+    # Whether the current version already exists on the configured host.
+    #
+    # @return [Boolean]
+    def published?
+      versions.any? { |version| version.fetch("number", nil).to_s == current_version.to_s }
+    end
+
+    ##
+    # Raises if the current version already exists.
+    #
+    # @return [void]
+    def check
+      if published?
+        raise Error, "#{configuration.gem_name} #{current_version} already exists on #{configuration.rubygems_host}."
+      end
+    end
+
+    private
+
+    ##
+    # Resolved Semverve configuration.
+    #
+    # @return [Semverve::ResolvedConfiguration]
+    attr_reader :configuration
+
+    ##
+    # Current gem version.
+    #
+    # @return [Semverve::SemanticVersion]
+    attr_reader :current_version
+
+    ##
+    # Published versions from the configured RubyGems-compatible host.
+    #
+    # @return [Array<Hash>]
+    def versions
+      response = self.class.http_getter.call(versions_uri)
+
+      case response.code.to_i
+      when 200
+        parse_versions(response.body)
+      when 404
+        []
+      else
+        raise Error, "Could not check #{configuration.gem_name} on #{configuration.rubygems_host}: HTTP #{response.code}."
+      end
+    rescue JSON::ParserError => error
+      raise Error, "Could not parse published versions for #{configuration.gem_name}: #{error.message}"
+    rescue SystemCallError, Timeout::Error, SocketError, URI::Error => error
+      raise Error, "Could not check #{configuration.gem_name} on #{configuration.rubygems_host}: #{error.message}"
+    end
+
+    ##
+    # Endpoint for a gem's published versions.
+    #
+    # @return [URI::HTTP, URI::HTTPS]
+    def versions_uri
+      URI("#{configuration.rubygems_host.chomp("/")}/api/v1/versions/#{URI.encode_www_form_component(configuration.gem_name)}.json")
+    end
+
+    ##
+    # Parsed version response.
+    #
+    # @param [String] body
+    #
+    # @return [Array<Hash>]
+    def parse_versions(body)
+      versions = JSON.parse(body)
+      return versions if versions.is_a?(Array)
+
+      raise Error, "Could not parse published versions for #{configuration.gem_name}: expected an array."
+    end
+  end
+end

data/lib/semverve/task.rb

@@ -4,6 +4,7 @@ require "rake"
 
 require_relative "../semverve"
 require_relative "generator"
+require_relative "published_version"
 require_relative "semantic_version"
 require_relative "version_file"
 require_relative "version_code_references"
@@ -98,13 +99,19 @@ module Semverve
         end
 
         desc "Generate a version.rb file"
-        task :generate do
-          puts "Generated #{Generator.new(Semverve.configuration.resolved).generate}"
+        task :generate, [:version, :format, :force] do |_task, args|
+          generator_options = generate_options(args)
+          puts "Generated #{Generator.new(
+            Semverve.configuration.resolved,
+            version: generator_options[:version],
+            format: generator_options[:format],
+            force: generator_options[:force]
+          ).generate}"
         end
 
-        desc "Set the version.rb file to VERSION"
-        task :set do
-          set
+        desc "Set the version.rb file to version"
+        task :set, [:version] do |_task, args|
+          set(args)
         end
 
         desc "Check version references, code literals, and metadata"
@@ -127,6 +134,16 @@ module Semverve
           task :metadata do
             check_metadata
           end
+
+          desc "Check whether the current gem version is already published"
+          task :rubygems do
+            check_rubygems
+          end
+
+          desc "Check configured release-readiness surfaces"
+          task :release do
+            check_release
+          end
         end
 
         desc "Fix version references, code literals, and metadata"
@@ -169,14 +186,14 @@ module Semverve
     end
 
     ##
-    # Sets the version to the value from the +VERSION+ environment variable.
+    # Sets the version to the value from the Rake +version+ argument.
+    #
+    # @param [Rake::TaskArguments] args
     #
     # @return [void]
-    def set
+    def set(args)
       configuration = Semverve.configuration.resolved
-      requested_version = SemanticVersion.parse(
-        ENV.fetch("VERSION") { raise Error, "Set VERSION=MAJOR.MINOR.PATCH." }
-      )
+      requested_version = SemanticVersion.parse(requested_version_argument(args))
       update = VersionFile.new(configuration).set(requested_version)
 
       report(update, configuration)
@@ -211,7 +228,7 @@ module Semverve
     def check_references
       configuration, current_version = check_context
       report_findings(
-        [["version reference", VersionReferences.new(configuration, current_version).findings]],
+        [["version reference", VersionReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]],
         current_version,
         clean_message: "Version references are current."
       )
@@ -236,7 +253,7 @@ module Semverve
     def check_code
       configuration, current_version = check_context
       report_findings(
-        [["code version literal", VersionCodeReferences.new(configuration, current_version).findings]],
+        [["code version literal", VersionCodeReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]],
         current_version,
         clean_message: "Code version literals are current."
       )
@@ -267,6 +284,31 @@ module Semverve
       )
     end
 
+    ##
+    # Checks whether the current gem version is already published.
+    #
+    # @return [void]
+    def check_rubygems
+      configuration, current_version = check_context
+      PublishedVersion.new(configuration, current_version).check
+
+      puts "#{configuration.gem_name} #{current_version} is not published on #{configuration.rubygems_host}."
+    end
+
+    ##
+    # Checks configured release-readiness surfaces.
+    #
+    # @return [void]
+    def check_release
+      configuration, current_version = check_context
+
+      if configuration.release_checks.include?(:rubygems)
+        PublishedVersion.new(configuration, current_version).check
+      end
+
+      puts "Release checks passed."
+    end
+
     ##
     # Fixes safe gem metadata version mismatches.
     #
@@ -298,10 +340,10 @@ module Semverve
     def check_groups(configuration, current_version)
       groups = []
       if configuration.version_checks.include?(:doc_references)
-        groups << ["version reference", VersionReferences.new(configuration, current_version).findings]
+        groups << ["version reference", VersionReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]
       end
       if configuration.version_checks.include?(:code_references)
-        groups << ["code version literal", VersionCodeReferences.new(configuration, current_version).findings]
+        groups << ["code version literal", VersionCodeReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]
       end
       if configuration.version_checks.include?(:metadata)
         groups << [nil, VersionMetadata.new(configuration, current_version).findings]
@@ -309,6 +351,67 @@ module Semverve
       groups
     end
 
+    ##
+    # Whether check tasks should report references hidden by ignore markers.
+    #
+    # @return [Boolean]
+    def report_ignored?
+      ENV.fetch("SEMVERVE_REPORT_IGNORED", "false").match?(/\A(true|1|yes)\z/i)
+    end
+
+    ##
+    # Parsed arguments for +semverve:generate+.
+    #
+    # @param [Rake::TaskArguments] args
+    #
+    # @return [Hash]
+    def generate_options(args)
+      args.to_a.each_with_object({force: false}) do |value, options|
+        assign_generate_option(value, options)
+      end
+    end
+
+    ##
+    # Assigns a single +semverve:generate+ token by meaning.
+    #
+    # @param [String] value
+    # @param [Hash] options
+    #
+    # @return [void]
+    def assign_generate_option(value, options)
+      case value
+      when nil, ""
+        nil
+      when "force"
+        raise Error, "Duplicate generate option force." if options[:force]
+
+        options[:force] = true
+      when SemanticVersion::PATTERN
+        raise Error, "Duplicate generate version #{value.inspect}." if options[:version]
+
+        options[:version] = value
+      when "module", "simple"
+        raise Error, "Duplicate generate format #{value.inspect}." if options[:format]
+
+        options[:format] = value
+      else
+        raise Error, "Unknown generate option #{value.inspect}. Use a semantic version, module, simple, or force."
+      end
+    end
+
+    ##
+    # Required version argument for +semverve:set+.
+    #
+    # @param [Rake::TaskArguments] args
+    #
+    # @return [String]
+    def requested_version_argument(args)
+      version = args[:version]
+      raise Error, "Run rake 'semverve:set[MAJOR.MINOR.PATCH]'." if version.nil? || version.empty?
+
+      version
+    end
+
     ##
     # Fix results enabled for the umbrella fix task.
     #

data/lib/semverve/version.rb

@@ -15,13 +15,13 @@ module Semverve
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 1
+    MINOR = 2
 
     ##
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 0
+    PATCH = 1
 
     module_function
 

data/lib/semverve/version_code_references.rb

@@ -8,6 +8,12 @@ module Semverve
   ##
   # Finds and updates safe version literals in configured code files.
   class VersionCodeReferences
+    ##
+    # Marker that suppresses version-reference findings.
+    #
+    # @return [String]
+    IGNORE_MARKER = "semverve:ignore-version-reference"
+
     ##
     # Ruby assignments that are safe enough to rewrite automatically.
     #
@@ -93,9 +99,10 @@ module Semverve
     # @param [Semverve::SemanticVersion] current_version
     #
     # @return [Semverve::VersionCodeReferences]
-    def initialize(configuration, current_version)
+    def initialize(configuration, current_version, include_ignored: false)
       @configuration = configuration
       @current_version = current_version
+      @include_ignored = include_ignored
     end
 
     ##
@@ -142,6 +149,12 @@ module Semverve
     # @return [Semverve::SemanticVersion]
     attr_reader :current_version
 
+    ##
+    # Whether ignored code literals should be included in findings.
+    #
+    # @return [Boolean]
+    attr_reader :include_ignored
+
     ##
     # Absolute configured project root.
     #
@@ -176,7 +189,11 @@ module Semverve
     #
     # @return [Array<Semverve::VersionCodeReferences::Finding>]
     def findings_for_file(path)
-      File.readlines(path).filter_map.with_index(1) do |line, line_number|
+      lines = File.readlines(path)
+
+      lines.filter_map.with_index(1) do |line, line_number|
+        next if !include_ignored && ignored_line?(line_number, lines)
+
         match = line.match(pattern)
         next unless match
 
@@ -200,8 +217,11 @@ module Semverve
     # @return [Array(String, Integer)]
     def fixed_content(content)
       replacement_count = 0
+      lines = content.lines
+
+      fixed = lines.map.with_index(1) do |line, line_number|
+        next line if ignored_line?(line_number, lines)
 
-      fixed = content.lines.map do |line|
         match = line.match(pattern)
         next line unless match
 
@@ -215,6 +235,23 @@ module Semverve
       [fixed, replacement_count]
     end
 
+    ##
+    # Whether findings on a line should be ignored.
+    #
+    # @param [Integer] line_number
+    # @param [Array<String>] lines
+    #
+    # @return [Boolean]
+    def ignored_line?(line_number, lines)
+      return true if lines.fetch(line_number - 1).include?(IGNORE_MARKER)
+
+      # Ruby 3.2 and 3.3 do not support Array#rfind.
+      # rubocop:disable Style/ReverseFind
+      previous_nonblank_line = lines[0...(line_number - 1)].reverse_each.find { |candidate| !candidate.strip.empty? }
+      # rubocop:enable Style/ReverseFind
+      previous_nonblank_line&.include?(IGNORE_MARKER)
+    end
+
     ##
     # Replaces only the named version capture in the first pattern match.
     #

data/lib/semverve/version_references.rb

@@ -107,9 +107,10 @@ module Semverve
     # @param [Semverve::SemanticVersion] current_version
     #
     # @return [Semverve::VersionReferences]
-    def initialize(configuration, current_version)
+    def initialize(configuration, current_version, include_ignored: false)
       @configuration = configuration
       @current_version = current_version
+      @include_ignored = include_ignored
     end
 
     ##
@@ -156,6 +157,12 @@ module Semverve
     # @return [Semverve::SemanticVersion]
     attr_reader :current_version
 
+    ##
+    # Whether ignored references should be included in findings.
+    #
+    # @return [Boolean]
+    attr_reader :include_ignored
+
     ##
     # Absolute configured project root.
     #
@@ -346,7 +353,7 @@ module Semverve
     #
     # @return [Array<Hash>]
     def references_for_segment(segment, content)
-      return [] if ignored_line?(segment[:line], content)
+      return [] if !include_ignored && ignored_line?(segment[:line], content)
 
       segment[:text].to_enum(:scan, VERSION_PATTERN).filter_map do
         match = Regexp.last_match

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semverve
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Evan Gray
@@ -119,6 +119,7 @@ files:
 - lib/semverve/generator.rb
 - lib/semverve/presets.rb
 - lib/semverve/project_metadata.rb
+- lib/semverve/published_version.rb
 - lib/semverve/railtie.rb
 - lib/semverve/semantic_version.rb
 - lib/semverve/task.rb