semverve 0.1.0

data/lib/semverve/task.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+require "rake"
+
+require_relative "../semverve"
+require_relative "generator"
+require_relative "semantic_version"
+require_relative "version_file"
+require_relative "version_code_references"
+require_relative "version_metadata"
+require_relative "version_references"
+
+module Semverve
+  ##
+  # Defines Semverve's Rake tasks for the current Rake application.
+  class Task
+    include Rake::DSL
+
+    class << self
+      ##
+      # Installs Semverve tasks once for the current Rake application.
+      #
+      # @return [Semverve::Task, nil]
+      def install
+        return if installed_for_current_application?
+
+        new
+      end
+
+      private
+
+      ##
+      # Whether tasks were already installed for the current Rake application.
+      #
+      # @return [Boolean]
+      def installed_for_current_application?
+        installed_applications.include?(Rake.application.object_id)
+      end
+
+      ##
+      # Rake application object IDs that already have Semverve tasks.
+      #
+      # @return [Array<Integer>]
+      def installed_applications
+        @installed_applications ||= []
+      end
+
+      ##
+      # Records the current Rake application as installed.
+      #
+      # @return [Array<Integer>]
+      def mark_current_application_installed
+        installed_applications << Rake.application.object_id
+      end
+    end
+
+    ##
+    # Configures and defines Semverve tasks if needed.
+    #
+    # @yieldparam [Semverve::Configuration] configuration
+    #
+    # @return [Semverve::Task]
+    def initialize
+      yield Semverve.configuration if block_given?
+
+      unless self.class.send(:installed_for_current_application?)
+        define
+        self.class.send(:mark_current_application_installed)
+      end
+    end
+
+    ##
+    # Defines the +semverve:*+ Rake tasks.
+    #
+    # @return [void]
+    def define
+      namespace :semverve do
+        desc "Print the current version from the version.rb file"
+        task :current do
+          puts VersionFile.new(Semverve.configuration.resolved).current
+        end
+
+        namespace :increment do
+          desc "Increment the version's PATCH level"
+          task :patch do
+            increment(:patch)
+          end
+
+          desc "Increment the version's MINOR level"
+          task :minor do
+            increment(:minor)
+          end
+
+          desc "Increment the version's MAJOR level"
+          task :major do
+            increment(:major)
+          end
+        end
+
+        desc "Generate a version.rb file"
+        task :generate do
+          puts "Generated #{Generator.new(Semverve.configuration.resolved).generate}"
+        end
+
+        desc "Set the version.rb file to VERSION"
+        task :set do
+          set
+        end
+
+        desc "Check version references, code literals, and metadata"
+        task :check do
+          check
+        end
+
+        namespace :check do
+          desc "Check configured files for stale version references"
+          task :references do
+            check_references
+          end
+
+          desc "Check configured code files for version literals"
+          task :code do
+            check_code
+          end
+
+          desc "Check gem metadata for version mismatches"
+          task :metadata do
+            check_metadata
+          end
+        end
+
+        desc "Fix version references, code literals, and metadata"
+        task :fix do
+          fix
+        end
+
+        namespace :fix do
+          desc "Replace stale version references in configured files"
+          task :references do
+            fix_references
+          end
+
+          desc "Replace safe code version literals in configured files"
+          task :code do
+            fix_code
+          end
+
+          desc "Fix safe gem metadata version mismatches"
+          task :metadata do
+            fix_metadata
+          end
+        end
+      end
+    end
+
+    private
+
+    ##
+    # Increments a version level and reports the update.
+    #
+    # @param [Symbol] level
+    #
+    # @return [void]
+    def increment(level)
+      configuration = Semverve.configuration.resolved
+      update = VersionFile.new(configuration).increment(level)
+
+      report(update, configuration)
+    end
+
+    ##
+    # Sets the version to the value from the +VERSION+ environment variable.
+    #
+    # @return [void]
+    def set
+      configuration = Semverve.configuration.resolved
+      requested_version = SemanticVersion.parse(
+        ENV.fetch("VERSION") { raise Error, "Set VERSION=MAJOR.MINOR.PATCH." }
+      )
+      update = VersionFile.new(configuration).set(requested_version)
+
+      report(update, configuration)
+    end
+
+    ##
+    # Checks all version-maintenance surfaces.
+    #
+    # @return [void]
+    def check
+      configuration, current_version = check_context
+      report_findings(
+        check_groups(configuration, current_version),
+        current_version,
+        clean_message: "Version checks passed."
+      )
+    end
+
+    ##
+    # Fixes all check surfaces.
+    #
+    # @return [void]
+    def fix
+      configuration, current_version = check_context
+      report_fix_results(fix_results(configuration, current_version))
+    end
+
+    ##
+    # Checks configured files for stale version references.
+    #
+    # @return [void]
+    def check_references
+      configuration, current_version = check_context
+      report_findings(
+        [["version reference", VersionReferences.new(configuration, current_version).findings]],
+        current_version,
+        clean_message: "Version references are current."
+      )
+    end
+
+    ##
+    # Replaces stale version references in configured files.
+    #
+    # @return [void]
+    def fix_references
+      configuration, current_version = check_context
+      report_fix_results(
+        [["version reference", VersionReferences.new(configuration, current_version).fix]],
+        clean_message: "Version references are current."
+      )
+    end
+
+    ##
+    # Checks configured code files for version literals.
+    #
+    # @return [void]
+    def check_code
+      configuration, current_version = check_context
+      report_findings(
+        [["code version literal", VersionCodeReferences.new(configuration, current_version).findings]],
+        current_version,
+        clean_message: "Code version literals are current."
+      )
+    end
+
+    ##
+    # Replaces safe code version literals in configured files.
+    #
+    # @return [void]
+    def fix_code
+      configuration, current_version = check_context
+      report_fix_results(
+        [["code version literal", VersionCodeReferences.new(configuration, current_version).fix]],
+        clean_message: "Code version literals are current."
+      )
+    end
+
+    ##
+    # Checks gem metadata for version mismatches.
+    #
+    # @return [void]
+    def check_metadata
+      configuration, current_version = check_context
+      report_findings(
+        [[nil, VersionMetadata.new(configuration, current_version).findings]],
+        current_version,
+        clean_message: "Version metadata is current."
+      )
+    end
+
+    ##
+    # Fixes safe gem metadata version mismatches.
+    #
+    # @return [void]
+    def fix_metadata
+      configuration, current_version = check_context
+      report_fix_results(
+        [["metadata version", VersionMetadata.new(configuration, current_version).fix]],
+        clean_message: "Version metadata is current."
+      )
+    end
+
+    ##
+    # Resolved configuration and current version for check tasks.
+    #
+    # @return [Array(Semverve::ResolvedConfiguration, Semverve::SemanticVersion)]
+    def check_context
+      configuration = Semverve.configuration.resolved
+      [configuration, VersionFile.new(configuration).current]
+    end
+
+    ##
+    # Finding groups enabled for the umbrella check task.
+    #
+    # @param [Semverve::ResolvedConfiguration] configuration
+    # @param [Semverve::SemanticVersion] current_version
+    #
+    # @return [Array<Array(String, Array)>]
+    def check_groups(configuration, current_version)
+      groups = []
+      if configuration.version_checks.include?(:doc_references)
+        groups << ["version reference", VersionReferences.new(configuration, current_version).findings]
+      end
+      if configuration.version_checks.include?(:code_references)
+        groups << ["code version literal", VersionCodeReferences.new(configuration, current_version).findings]
+      end
+      if configuration.version_checks.include?(:metadata)
+        groups << [nil, VersionMetadata.new(configuration, current_version).findings]
+      end
+      groups
+    end
+
+    ##
+    # Fix results enabled for the umbrella fix task.
+    #
+    # @param [Semverve::ResolvedConfiguration] configuration
+    # @param [Semverve::SemanticVersion] current_version
+    #
+    # @return [Array<Array(String, #replacement_count, #changed_files)>]
+    def fix_results(configuration, current_version)
+      results = []
+      if configuration.version_checks.include?(:doc_references)
+        results << ["version reference", VersionReferences.new(configuration, current_version).fix]
+      end
+      if configuration.version_checks.include?(:code_references)
+        results << ["code version literal", VersionCodeReferences.new(configuration, current_version).fix]
+      end
+      if configuration.version_checks.include?(:metadata)
+        results << ["metadata version", VersionMetadata.new(configuration, current_version).fix]
+      end
+      results
+    end
+
+    ##
+    # Prints findings and raises when mismatches exist.
+    #
+    # @param [Array<Array(String, Array)>] groups
+    # @param [Semverve::SemanticVersion] current_version
+    # @param [String] clean_message
+    #
+    # @return [void]
+    def report_findings(groups, current_version, clean_message:)
+      findings = groups.flat_map do |(label, group_findings)|
+        group_findings.map { |finding| [label || finding.label, finding] }
+      end
+
+      if findings.empty?
+        puts clean_message
+        return
+      end
+
+      findings.each do |(label, finding)|
+        puts "#{finding.path}:#{finding.line}:#{finding.column}: #{label} #{finding.version} -> #{current_version}"
+      end
+
+      issue = findings.one? ? "issue" : "issues"
+      raise Error, "Found #{findings.count} version check #{issue}."
+    end
+
+    ##
+    # Prints fix results.
+    #
+    # @param [Array<Array(String, #replacement_count, #changed_files)>] results
+    # @param [String] clean_message
+    #
+    # @return [void]
+    def report_fix_results(results, clean_message: "Version checks passed.")
+      replacement_count = results.sum { |(_label, result)| result.replacement_count }
+      bundle_lock_ran = results.any? { |(_label, result)| result.respond_to?(:bundle_lock_ran) && result.bundle_lock_ran }
+
+      if replacement_count.zero? && !bundle_lock_ran
+        puts clean_message
+        return
+      end
+
+      results.each do |(label, result)|
+        result.changed_files.each { |path| puts "Updated #{path}" }
+        next if result.replacement_count.zero?
+
+        noun = (result.replacement_count == 1) ? label : "#{label}s"
+        puts "Replaced #{result.replacement_count} #{noun}."
+      end
+
+      puts "Ran bundle lock." if bundle_lock_ran
+    end
+
+    ##
+    # Reports an update and runs configured follow-up commands.
+    #
+    # @param [Semverve::VersionFile::UpdateResult] update
+    # @param [Semverve::ResolvedConfiguration] configuration
+    #
+    # @return [void]
+    def report(update, configuration)
+      unless update.changed?
+        puts "Version is already #{update.version}"
+        return
+      end
+
+      if update.version < update.previous_version
+        warn "Warning: updating to version #{update.version}, which is lower than the current version #{update.previous_version}."
+      end
+
+      puts "Updating to version #{update.version} (was #{update.previous_version})"
+      configuration.command_runner.call("bundle lock") if configuration.bundle_lock
+    end
+  end
+end
+
+Semverve::Task.install

data/lib/semverve/version.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Semverve
+  ##
+  # Module that contains all gem version information. Follows semantic
+  # versioning. Read: https://semver.org/
+  module Version
+    ##
+    # Major version.
+    #
+    # @return [Integer]
+    MAJOR = 0
+
+    ##
+    # Minor version.
+    #
+    # @return [Integer]
+    MINOR = 1
+
+    ##
+    # Patch version.
+    #
+    # @return [Integer]
+    PATCH = 0
+
+    module_function
+
+    ##
+    # Version as +[MAJOR, MINOR, PATCH]+
+    #
+    # @return [Array<Integer>]
+    def to_a
+      [MAJOR, MINOR, PATCH]
+    end
+
+    ##
+    # Version as +MAJOR.MINOR.PATCH+
+    #
+    # @return [String]
+    def to_s
+      to_a.join(".")
+    end
+  end
+
+  ##
+  # The version, as a string.
+  #
+  # @return [String]
+  VERSION = Version.to_s
+end

data/lib/semverve/version_code_references.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "file_list_resolver"
+require_relative "semantic_version"
+
+module Semverve
+  ##
+  # Finds and updates safe version literals in configured code files.
+  class VersionCodeReferences
+    ##
+    # Ruby assignments that are safe enough to rewrite automatically.
+    #
+    # @return [Regexp]
+    RUBY_ASSIGNMENT_PATTERN = Configuration::DEFAULT_VERSION_CODE_REFERENCE_PATTERN
+
+    ##
+    # A code version literal found in a configured file.
+    class Finding
+      ##
+      # Path relative to the configured project root.
+      #
+      # @return [String]
+      attr_reader :path
+
+      ##
+      # One-based line number.
+      #
+      # @return [Integer]
+      attr_reader :line
+
+      ##
+      # One-based column number.
+      #
+      # @return [Integer]
+      attr_reader :column
+
+      ##
+      # Referenced semantic version.
+      #
+      # @return [Semverve::SemanticVersion]
+      attr_reader :version
+
+      ##
+      # Initializes a finding.
+      #
+      # @param [String] path
+      # @param [Integer] line
+      # @param [Integer] column
+      # @param [Semverve::SemanticVersion] version
+      #
+      # @return [Semverve::VersionCodeReferences::Finding]
+      def initialize(path:, line:, column:, version:)
+        @path = path
+        @line = line
+        @column = column
+        @version = version
+      end
+    end
+
+    ##
+    # Result of fixing code version literals.
+    class FixResult
+      ##
+      # Files changed by the fix.
+      #
+      # @return [Array<String>]
+      attr_reader :changed_files
+
+      ##
+      # Number of replacements made.
+      #
+      # @return [Integer]
+      attr_reader :replacement_count
+
+      ##
+      # Initializes a fix result.
+      #
+      # @param [Array<String>] changed_files
+      # @param [Integer] replacement_count
+      #
+      # @return [Semverve::VersionCodeReferences::FixResult]
+      def initialize(changed_files:, replacement_count:)
+        @changed_files = changed_files
+        @replacement_count = replacement_count
+      end
+    end
+
+    ##
+    # Initializes code version literal scanning.
+    #
+    # @param [Semverve::ResolvedConfiguration] configuration
+    # @param [Semverve::SemanticVersion] current_version
+    #
+    # @return [Semverve::VersionCodeReferences]
+    def initialize(configuration, current_version)
+      @configuration = configuration
+      @current_version = current_version
+    end
+
+    ##
+    # Code version literal findings in configured files.
+    #
+    # @return [Array<Semverve::VersionCodeReferences::Finding>]
+    def findings
+      files.flat_map { |path| findings_for_file(path) }
+    end
+
+    ##
+    # Replaces found code version literals with the current version.
+    #
+    # @return [Semverve::VersionCodeReferences::FixResult]
+    def fix
+      changed_files = []
+      replacement_count = 0
+
+      files.each do |path|
+        content = File.read(path)
+        fixed, count = fixed_content(content)
+
+        next if count.zero?
+
+        File.write(path, fixed)
+        changed_files << relative_path(path)
+        replacement_count += count
+      end
+
+      FixResult.new(changed_files: changed_files, replacement_count: replacement_count)
+    end
+
+    private
+
+    ##
+    # Resolved Semverve configuration.
+    #
+    # @return [Semverve::ResolvedConfiguration]
+    attr_reader :configuration
+
+    ##
+    # Current gem version.
+    #
+    # @return [Semverve::SemanticVersion]
+    attr_reader :current_version
+
+    ##
+    # Absolute configured project root.
+    #
+    # @return [String]
+    def root
+      configuration.root
+    end
+
+    ##
+    # Configured pattern used to find code version literals.
+    #
+    # @return [Regexp]
+    def pattern
+      configuration.version_code_reference_pattern
+    end
+
+    ##
+    # Absolute files to scan.
+    #
+    # @return [Array<String>]
+    def files
+      @files ||= FileListResolver.new(
+        root: root,
+        file_list: configuration.version_code_reference_files
+      ).files.reject { |path| File.expand_path(path) == File.expand_path(configuration.absolute_version_file) }
+    end
+
+    ##
+    # Findings for a single file.
+    #
+    # @param [String] path
+    #
+    # @return [Array<Semverve::VersionCodeReferences::Finding>]
+    def findings_for_file(path)
+      File.readlines(path).filter_map.with_index(1) do |line, line_number|
+        match = line.match(pattern)
+        next unless match
+
+        version = SemanticVersion.parse(match[:version])
+        next if version == current_version
+
+        Finding.new(
+          path: relative_path(path),
+          line: line_number,
+          column: match.begin(:version) + 1,
+          version: version
+        )
+      end
+    end
+
+    ##
+    # Fixed content and replacement count.
+    #
+    # @param [String] content
+    #
+    # @return [Array(String, Integer)]
+    def fixed_content(content)
+      replacement_count = 0
+
+      fixed = content.lines.map do |line|
+        match = line.match(pattern)
+        next line unless match
+
+        version = SemanticVersion.parse(match[:version])
+        next line if version == current_version
+
+        replacement_count += 1
+        replace_matched_version(line)
+      end.join
+
+      [fixed, replacement_count]
+    end
+
+    ##
+    # Replaces only the named version capture in the first pattern match.
+    #
+    # @param [String] line
+    #
+    # @return [String]
+    def replace_matched_version(line)
+      line.sub(pattern) do |matched_text|
+        match = Regexp.last_match
+        version_start = match.begin(:version) - match.begin(0)
+        version_end = match.end(:version) - match.begin(0)
+
+        "#{matched_text[0...version_start]}#{current_version}#{matched_text[version_end..]}"
+      end
+    end
+
+    ##
+    # Path relative to the project root.
+    #
+    # @param [String] path
+    #
+    # @return [String]
+    def relative_path(path)
+      path.delete_prefix("#{root}/")
+    end
+  end
+end