semverve 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b04f97b571e0eed652d155221cddb5afe06d703f2a27546f15c11e3d26a3d214
-  data.tar.gz: 6c824db22d1967e9daa8de369ca199b6cc7969f6ab2179933600fbba34d1aa6e
+  metadata.gz: c12b376c6b4cb56170cff17c35f9545137b3011f1e1fe6314541dfe259351367
+  data.tar.gz: fae2d93ad6f546f69e081cfa5a7449d7d6de0c9eb25430421dbe41a274171d8c
 SHA512:
-  metadata.gz: 31208572bd96d1d1bb00537673e9960594501a2b4226f821114d8cb624965fd0cd7282722d6284cf0666f80a908706174a3ca3d0bb4109a3b18dc882e9a26ecd
-  data.tar.gz: 8deb952db13cfdf0f8a13fbbcffb07afc23c402ece2efc3d50899d4158ea7455a6bedc993cb79c9d3de8dfc83c8142981f87f52777ee79a8dba1c1b09bc58dcd
+  metadata.gz: 92980247baef342765f07bf2f9a398e38b191a3707302ae84f25ca0a322a9bfd428335f680c6da34cebc1039f533cdf7298117e1e062f159413c663e58966f2c
+  data.tar.gz: b9016a36d15e78aa46c6e7fea92feaa48bd5dec2627fcd8e47420e11a55eed4c7083f56eaeb06f95cb1a9baa50f3559f5c9d3e63fb2bc42dae720a49447df775

data/CONTRIBUTING.md

@@ -116,6 +116,10 @@ versions as the generated version, `module` or `simple` as the format, and
 `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`,

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    semverve (0.2.1)
+    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>/
@@ -375,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
@@ -410,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
 ```
 
@@ -439,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
@@ -526,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.

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]
@@ -412,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]
@@ -438,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
@@ -454,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,13 +15,13 @@ module Semverve
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 2
+    MINOR = 3
 
     ##
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 1
+    PATCH = 0
 
     module_function
 

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.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Evan Gray