semverve 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 436e6dece23a174761d954e1c1efc74d95d68b8b47d82f876bb5b785eb204748
-  data.tar.gz: 62e9b4496586062f8e03f71d0838ddd510e5e42faa200d10fbef2560f214fa4c
+  metadata.gz: c12b376c6b4cb56170cff17c35f9545137b3011f1e1fe6314541dfe259351367
+  data.tar.gz: fae2d93ad6f546f69e081cfa5a7449d7d6de0c9eb25430421dbe41a274171d8c
 SHA512:
-  metadata.gz: cc055ab321689871de38a8fc0276a8cc85011ea9c7765c7844d97c71962bba2765cd867cd9dbb96236b11ea695edc63e8289c087fd5a90482ab1ea376d82981a
-  data.tar.gz: 8a4cbb86d9548b4aeeedf94bd883e300532a6d4c062dc1c1c1170d412ae5bb94a4fe50bdfbc29098482a51632a194ef32be93cee35ef8a5219d77f5957d54c98
+  metadata.gz: 92980247baef342765f07bf2f9a398e38b191a3707302ae84f25ca0a322a9bfd428335f680c6da34cebc1039f533cdf7298117e1e062f159413c663e58966f2c
+  data.tar.gz: b9016a36d15e78aa46c6e7fea92feaa48bd5dec2627fcd8e47420e11a55eed4c7083f56eaeb06f95cb1a9baa50f3559f5c9d3e63fb2bc42dae720a49447df775

data/CONTRIBUTING.md

@@ -100,6 +100,31 @@ 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.
+
+Use Rake task arguments for one-off exact inputs, such as
+`rake 'semverve:check[1.2.3]'` when a user wants to scan only for a specific
+version.
+
+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

data/Gemfile.lock

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

data/README.md

@@ -95,7 +95,7 @@ Semverve.configure do |config|
   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
+  config.version_match_mode = :non_current
 end
 ```
 
@@ -109,7 +109,7 @@ Semverve.configure do |config|
   config.version_checks = [:doc_references, :code_references, :metadata]
   config.release_checks = []
   config.rubygems_host = "https://rubygems.org"
-  config.version_reference_mode = :older
+  config.version_match_mode = :older
   config.version_code_reference_files = Rake::FileList[]
   config.version_code_reference_pattern =
     /^\s*(?:(?:[A-Z]\w*::)*(?:[A-Z]\w*VERSION[A-Z0-9_]*|VERSION)|(?:[a-z_]\w*|self)\.version)\s*=\s*(?<quote>["'])(?<version>\d+\.\d+\.\d+)\k<quote>/
@@ -133,6 +133,7 @@ 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]'
 ```
 
@@ -250,6 +251,7 @@ Generate a specific version or format:
 
 ```sh
 rake 'semverve:generate[1.0.0,simple]'
+rake 'semverve:generate[simple]'
 ```
 
 Generation fails if the target file already exists. To replace it:
@@ -258,11 +260,14 @@ Generation fails if the target file already exists. To replace it:
 rake 'semverve:generate[force]'
 ```
 
-`semverve:generate` accepts optional `version` and `format` arguments. Add a
-`force` token to overwrite an existing version file:
+`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]'
 ```
 
@@ -370,6 +375,18 @@ rake semverve:fix:metadata
 `semverve:fix:metadata` rewrites literal gemspec versions when safe and
 runs `bundle lock` for `Gemfile.lock` drift.
 
+Pass a semantic version when you want to check or fix only that exact version in
+doc references and code literals:
+
+```sh
+rake 'semverve:check[1.2.2]'
+rake 'semverve:fix:references[1.2.2]'
+```
+
+Metadata checks still compare metadata to the current version. If you target the
+current version, check tasks list those matches but fix tasks are no-ops because
+the text is already current.
+
 ### Version references
 Version references are prose-like references to versions. These are usually in
 README files, docs, guides, or comments. By default, Semverve scans README files
@@ -405,20 +422,21 @@ end
 Ruby files are scanned only in comments. Text files with `.md`, `.markdown`,
 `.txt`, `.rdoc`, and `.adoc` extensions are scanned as full text.
 
-The default reference mode is `:older`, which flags only semantic versions lower
-than the current version:
+The default version match mode is `:older`, which flags only semantic versions
+lower than the current version in doc references and code literals:
 
 ```ruby
 Semverve.configure do |config|
-  config.version_reference_mode = :older
+  config.version_match_mode = :older
 end
 ```
 
-Use `:non_current` when every reference should match the current version:
+Use `:non_current` when every doc reference and code literal should match the
+current version:
 
 ```ruby
 Semverve.configure do |config|
-  config.version_reference_mode = :non_current
+  config.version_match_mode = :non_current
 end
 ```
 
@@ -434,6 +452,7 @@ check tasks:
 
 ```sh
 SEMVERVE_REPORT_IGNORED=true rake semverve:check
+SEMVERVE_REPORT_IGNORED=true rake 'semverve:check[1.2.2]'
 ```
 
 ### Code version literals
@@ -521,7 +540,7 @@ current version file against:
 - the matching `Gemfile.lock` entry, when a lockfile exists
 
 Metadata always requires an exact match, regardless of
-`config.version_reference_mode`.
+`config.version_match_mode`.
 
 No file-list configuration is needed for these checks. Semverve resolves the
 gemspec from the project root and reads `Gemfile.lock` when one exists.
@@ -620,6 +639,39 @@ For release CI, run the release check before building or pushing:
 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

@@ -113,10 +113,10 @@ module Semverve
     attr_reader :version_checks
 
     ##
-    # Version-reference comparison mode.
+    # Version matching mode for reference and code-literal checks.
     #
     # @return [Symbol, String]
-    attr_accessor :version_reference_mode
+    attr_accessor :version_match_mode
 
     ##
     # Initializes configuration with Semverve's default settings.
@@ -137,7 +137,7 @@ module Semverve
         "tmp/**/*",
         "vendor/**/*"
       )
-      @version_reference_mode = :older
+      @version_match_mode = :older
       self.release_checks = []
       self.version_checks = VALID_VERSION_CHECKS
     end
@@ -163,7 +163,7 @@ module Semverve
         version_code_reference_files: version_code_reference_files,
         version_code_reference_pattern: version_code_reference_pattern,
         version_doc_reference_files: version_doc_reference_files,
-        version_reference_mode: normalized_version_reference_mode
+        version_match_mode: normalized_version_match_mode
       )
     end
 
@@ -305,11 +305,11 @@ module Semverve
     end
 
     ##
-    # Configured version-reference mode normalized for lookup.
+    # Configured version matching mode normalized for lookup.
     #
     # @return [Symbol]
-    def normalized_version_reference_mode
-      version_reference_mode.to_sym
+    def normalized_version_match_mode
+      version_match_mode.to_sym
     end
 
     ##
@@ -478,10 +478,10 @@ module Semverve
     attr_reader :version_doc_reference_files
 
     ##
-    # Resolved version-reference comparison mode.
+    # Resolved version matching mode for reference and code-literal checks.
     #
     # @return [Symbol]
-    attr_reader :version_reference_mode
+    attr_reader :version_match_mode
 
     ##
     # Initializes a resolved configuration.
@@ -499,7 +499,7 @@ module Semverve
     # @param [Rake::FileList] version_code_reference_files
     # @param [Regexp] version_code_reference_pattern
     # @param [Rake::FileList] version_doc_reference_files
-    # @param [Symbol] version_reference_mode
+    # @param [Symbol] version_match_mode
     #
     # @return [Semverve::ResolvedConfiguration]
     def initialize(
@@ -516,7 +516,7 @@ module Semverve
       version_code_reference_files:,
       version_code_reference_pattern:,
       version_doc_reference_files:,
-      version_reference_mode:
+      version_match_mode:
     )
       @bundle_lock = bundle_lock
       @command_runner = command_runner
@@ -531,7 +531,7 @@ module Semverve
       @version_code_reference_files = version_code_reference_files
       @version_code_reference_pattern = version_code_reference_pattern
       @version_doc_reference_files = version_doc_reference_files
-      @version_reference_mode = version_reference_mode
+      @version_match_mode = version_match_mode
     end
 
     ##

data/lib/semverve/task.rb

@@ -115,19 +115,19 @@ module Semverve
         end
 
         desc "Check version references, code literals, and metadata"
-        task :check do
-          check
+        task :check, [:version] do |_task, args|
+          check(args)
         end
 
         namespace :check do
           desc "Check configured files for stale version references"
-          task :references do
-            check_references
+          task :references, [:version] do |_task, args|
+            check_references(args)
           end
 
           desc "Check configured code files for version literals"
-          task :code do
-            check_code
+          task :code, [:version] do |_task, args|
+            check_code(args)
           end
 
           desc "Check gem metadata for version mismatches"
@@ -147,19 +147,19 @@ module Semverve
         end
 
         desc "Fix version references, code literals, and metadata"
-        task :fix do
-          fix
+        task :fix, [:version] do |_task, args|
+          fix(args)
         end
 
         namespace :fix do
           desc "Replace stale version references in configured files"
-          task :references do
-            fix_references
+          task :references, [:version] do |_task, args|
+            fix_references(args)
           end
 
           desc "Replace safe code version literals in configured files"
-          task :code do
-            fix_code
+          task :code, [:version] do |_task, args|
+            fix_code(args)
           end
 
           desc "Fix safe gem metadata version mismatches"
@@ -203,11 +203,14 @@ module Semverve
     # Checks all version-maintenance surfaces.
     #
     # @return [void]
-    def check
+    def check(args = nil)
       configuration, current_version = check_context
+      target_version = target_version_argument(args, "semverve:check")
       report_findings(
-        check_groups(configuration, current_version),
+        check_groups(configuration, current_version, target_version),
         current_version,
+        target_version: target_version,
+        fix_task_name: "semverve:fix",
         clean_message: "Version checks passed."
       )
     end
@@ -216,20 +219,34 @@ module Semverve
     # Fixes all check surfaces.
     #
     # @return [void]
-    def fix
+    def fix(args = nil)
       configuration, current_version = check_context
-      report_fix_results(fix_results(configuration, current_version))
+      target_version = target_version_argument(args, "semverve:fix")
+      return report_current_target_noop(target_version) if target_version == current_version
+
+      report_fix_results(fix_results(configuration, current_version, target_version))
     end
 
     ##
     # Checks configured files for stale version references.
     #
     # @return [void]
-    def check_references
+    def check_references(args = nil)
       configuration, current_version = check_context
+      target_version = target_version_argument(args, "semverve:check:references")
       report_findings(
-        [["version reference", VersionReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]],
+        [[
+          "version reference",
+          VersionReferences.new(
+            configuration,
+            current_version,
+            include_ignored: report_ignored?,
+            target_version: target_version
+          ).findings
+        ]],
         current_version,
+        target_version: target_version,
+        fix_task_name: "semverve:fix:references",
         clean_message: "Version references are current."
       )
     end
@@ -238,10 +255,16 @@ module Semverve
     # Replaces stale version references in configured files.
     #
     # @return [void]
-    def fix_references
+    def fix_references(args = nil)
       configuration, current_version = check_context
+      target_version = target_version_argument(args, "semverve:fix:references")
+      return report_current_target_noop(target_version) if target_version == current_version
+
       report_fix_results(
-        [["version reference", VersionReferences.new(configuration, current_version).fix]],
+        [[
+          "version reference",
+          VersionReferences.new(configuration, current_version, target_version: target_version).fix
+        ]],
         clean_message: "Version references are current."
       )
     end
@@ -250,11 +273,22 @@ module Semverve
     # Checks configured code files for version literals.
     #
     # @return [void]
-    def check_code
+    def check_code(args = nil)
       configuration, current_version = check_context
+      target_version = target_version_argument(args, "semverve:check:code")
       report_findings(
-        [["code version literal", VersionCodeReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]],
+        [[
+          "code version literal",
+          VersionCodeReferences.new(
+            configuration,
+            current_version,
+            include_ignored: report_ignored?,
+            target_version: target_version
+          ).findings
+        ]],
         current_version,
+        target_version: target_version,
+        fix_task_name: "semverve:fix:code",
         clean_message: "Code version literals are current."
       )
     end
@@ -263,10 +297,16 @@ module Semverve
     # Replaces safe code version literals in configured files.
     #
     # @return [void]
-    def fix_code
+    def fix_code(args = nil)
       configuration, current_version = check_context
+      target_version = target_version_argument(args, "semverve:fix:code")
+      return report_current_target_noop(target_version) if target_version == current_version
+
       report_fix_results(
-        [["code version literal", VersionCodeReferences.new(configuration, current_version).fix]],
+        [[
+          "code version literal",
+          VersionCodeReferences.new(configuration, current_version, target_version: target_version).fix
+        ]],
         clean_message: "Code version literals are current."
       )
     end
@@ -336,14 +376,32 @@ module Semverve
     # @param [Semverve::ResolvedConfiguration] configuration
     # @param [Semverve::SemanticVersion] current_version
     #
+    # @param [Semverve::SemanticVersion, nil] target_version
+    #
     # @return [Array<Array(String, Array)>]
-    def check_groups(configuration, current_version)
+    def check_groups(configuration, current_version, target_version = nil)
       groups = []
       if configuration.version_checks.include?(:doc_references)
-        groups << ["version reference", VersionReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]
+        groups << [
+          "version reference",
+          VersionReferences.new(
+            configuration,
+            current_version,
+            include_ignored: report_ignored?,
+            target_version: target_version
+          ).findings
+        ]
       end
       if configuration.version_checks.include?(:code_references)
-        groups << ["code version literal", VersionCodeReferences.new(configuration, current_version, include_ignored: report_ignored?).findings]
+        groups << [
+          "code version literal",
+          VersionCodeReferences.new(
+            configuration,
+            current_version,
+            include_ignored: report_ignored?,
+            target_version: target_version
+          ).findings
+        ]
       end
       if configuration.version_checks.include?(:metadata)
         groups << [nil, VersionMetadata.new(configuration, current_version).findings]
@@ -366,17 +424,37 @@ module Semverve
     #
     # @return [Hash]
     def generate_options(args)
-      values = args.to_a
-      force = values.delete("force")
-      if values.length > 2
-        raise Error, "Run rake 'semverve:generate[VERSION,FORMAT,force]'."
+      args.to_a.each_with_object({force: false}) do |value, options|
+        assign_generate_option(value, options)
       end
+    end
 
-      {
-        version: values[0],
-        format: values[1],
-        force: !force.nil?
-      }
+    ##
+    # 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
 
     ##
@@ -392,20 +470,43 @@ module Semverve
       version
     end
 
+    ##
+    # Optional exact version argument for check and fix tasks.
+    #
+    # @param [Rake::TaskArguments, nil] args
+    # @param [String] task_name
+    #
+    # @return [Semverve::SemanticVersion, nil]
+    def target_version_argument(args, task_name)
+      version = args&.[](:version)
+      return nil if version.nil? || version.empty?
+
+      SemanticVersion.parse(version)
+    rescue Error
+      raise Error, "Run rake '#{task_name}[MAJOR.MINOR.PATCH]'."
+    end
+
     ##
     # Fix results enabled for the umbrella fix task.
     #
     # @param [Semverve::ResolvedConfiguration] configuration
     # @param [Semverve::SemanticVersion] current_version
+    # @param [Semverve::SemanticVersion, nil] target_version
     #
     # @return [Array<Array(String, #replacement_count, #changed_files)>]
-    def fix_results(configuration, current_version)
+    def fix_results(configuration, current_version, target_version = nil)
       results = []
       if configuration.version_checks.include?(:doc_references)
-        results << ["version reference", VersionReferences.new(configuration, current_version).fix]
+        results << [
+          "version reference",
+          VersionReferences.new(configuration, current_version, target_version: target_version).fix
+        ]
       end
       if configuration.version_checks.include?(:code_references)
-        results << ["code version literal", VersionCodeReferences.new(configuration, current_version).fix]
+        results << [
+          "code version literal",
+          VersionCodeReferences.new(configuration, current_version, target_version: target_version).fix
+        ]
       end
       if configuration.version_checks.include?(:metadata)
         results << ["metadata version", VersionMetadata.new(configuration, current_version).fix]
@@ -418,10 +519,12 @@ module Semverve
     #
     # @param [Array<Array(String, Array)>] groups
     # @param [Semverve::SemanticVersion] current_version
+    # @param [Semverve::SemanticVersion, nil] target_version
+    # @param [String, nil] fix_task_name
     # @param [String] clean_message
     #
     # @return [void]
-    def report_findings(groups, current_version, clean_message:)
+    def report_findings(groups, current_version, clean_message:, target_version: nil, fix_task_name: nil)
       findings = groups.flat_map do |(label, group_findings)|
         group_findings.map { |finding| [label || finding.label, finding] }
       end
@@ -434,11 +537,36 @@ module Semverve
       findings.each do |(label, finding)|
         puts "#{finding.path}:#{finding.line}:#{finding.column}: #{label} #{finding.version} -> #{current_version}"
       end
+      if target_version == current_version && fix_task_name && reference_or_code_findings?(findings)
+        puts "Target version #{target_version} is already current; #{fix_task_name}[#{target_version}] will not change these references."
+      end
 
       issue = findings.one? ? "issue" : "issues"
       raise Error, "Found #{findings.count} version check #{issue}."
     end
 
+    ##
+    # Prints a no-op message for exact fix requests targeting the current version.
+    #
+    # @param [Semverve::SemanticVersion, nil] target_version
+    #
+    # @return [void]
+    def report_current_target_noop(target_version)
+      puts "Target version #{target_version} is already current; nothing to fix."
+    end
+
+    ##
+    # Whether findings include references controlled by exact-target fixes.
+    #
+    # @param [Array<Array(String, Object)>] findings
+    #
+    # @return [Boolean]
+    def reference_or_code_findings?(findings)
+      findings.any? do |(label, _finding)|
+        ["version reference", "code version literal"].include?(label)
+      end
+    end
+
     ##
     # Prints fix results.
     #

data/lib/semverve/version.rb

@@ -15,7 +15,7 @@ module Semverve
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 2
+    MINOR = 3
 
     ##
     # Patch version.

data/lib/semverve/version_code_references.rb

@@ -99,10 +99,11 @@ module Semverve
     # @param [Semverve::SemanticVersion] current_version
     #
     # @return [Semverve::VersionCodeReferences]
-    def initialize(configuration, current_version, include_ignored: false)
+    def initialize(configuration, current_version, include_ignored: false, target_version: nil)
       @configuration = configuration
       @current_version = current_version
       @include_ignored = include_ignored
+      @target_version = target_version
     end
 
     ##
@@ -155,6 +156,12 @@ module Semverve
     # @return [Boolean]
     attr_reader :include_ignored
 
+    ##
+    # Exact version to match, when supplied by the task invocation.
+    #
+    # @return [Semverve::SemanticVersion, nil]
+    attr_reader :target_version
+
     ##
     # Absolute configured project root.
     #
@@ -198,7 +205,7 @@ module Semverve
         next unless match
 
         version = SemanticVersion.parse(match[:version])
-        next if version == current_version
+        next unless report?(version)
 
         Finding.new(
           path: relative_path(path),
@@ -226,7 +233,7 @@ module Semverve
         next line unless match
 
         version = SemanticVersion.parse(match[:version])
-        next line if version == current_version
+        next line unless report?(version)
 
         replacement_count += 1
         replace_matched_version(line)
@@ -252,6 +259,25 @@ module Semverve
       previous_nonblank_line&.include?(IGNORE_MARKER)
     end
 
+    ##
+    # Whether a referenced version should be reported or fixed.
+    #
+    # @param [Semverve::SemanticVersion] version
+    #
+    # @return [Boolean]
+    def report?(version)
+      return version == target_version if target_version
+
+      case configuration.version_match_mode
+      when :older
+        version < current_version
+      when :non_current
+        version != current_version
+      else
+        raise Error, "Unknown version match mode #{configuration.version_match_mode.inspect}. Use :older or :non_current."
+      end
+    end
+
     ##
     # Replaces only the named version capture in the first pattern match.
     #

data/lib/semverve/version_references.rb

@@ -107,10 +107,11 @@ module Semverve
     # @param [Semverve::SemanticVersion] current_version
     #
     # @return [Semverve::VersionReferences]
-    def initialize(configuration, current_version, include_ignored: false)
+    def initialize(configuration, current_version, include_ignored: false, target_version: nil)
       @configuration = configuration
       @current_version = current_version
       @include_ignored = include_ignored
+      @target_version = target_version
     end
 
     ##
@@ -163,6 +164,12 @@ module Semverve
     # @return [Boolean]
     attr_reader :include_ignored
 
+    ##
+    # Exact version to match, when supplied by the task invocation.
+    #
+    # @return [Semverve::SemanticVersion, nil]
+    attr_reader :target_version
+
     ##
     # Absolute configured project root.
     #
@@ -377,13 +384,15 @@ module Semverve
     #
     # @return [Boolean]
     def report?(version)
-      case configuration.version_reference_mode
+      return version == target_version if target_version
+
+      case configuration.version_match_mode
       when :older
         version < current_version
       when :non_current
         version != current_version
       else
-        raise Error, "Unknown version reference mode #{configuration.version_reference_mode.inspect}. Use :older or :non_current."
+        raise Error, "Unknown version match mode #{configuration.version_match_mode.inspect}. Use :older or :non_current."
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semverve
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Evan Gray