semverve 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c12b376c6b4cb56170cff17c35f9545137b3011f1e1fe6314541dfe259351367
-  data.tar.gz: fae2d93ad6f546f69e081cfa5a7449d7d6de0c9eb25430421dbe41a274171d8c
+  metadata.gz: 9d9765e973d77ca7011cb819202246f5ea7ef2faef574c66a58fc6ad5c058988
+  data.tar.gz: dea8769f32c6f6b70c81d05e2d46129cd9820a8289fbd032f42303dfc0b8dea3
 SHA512:
-  metadata.gz: 92980247baef342765f07bf2f9a398e38b191a3707302ae84f25ca0a322a9bfd428335f680c6da34cebc1039f533cdf7298117e1e062f159413c663e58966f2c
-  data.tar.gz: b9016a36d15e78aa46c6e7fea92feaa48bd5dec2627fcd8e47420e11a55eed4c7083f56eaeb06f95cb1a9baa50f3559f5c9d3e63fb2bc42dae720a49447df775
+  metadata.gz: 38b4aca2a29cfc750a7b6b7164219595ec35f76c9c5d526f441e469868686a6588170ee0e88c02942b97b59725d1c72c79b1496cad5880264042d99c8049846a
+  data.tar.gz: 7cf79a5a6d90a0f454ce03272e5592b140fff266893fee323b6e831ab28956104e7865bb5a141614e6cae6466a4bacbbd738850f299fd98d7f1024f391d61b7c

data/Gemfile.lock

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

data/README.md

@@ -34,6 +34,8 @@ and RDoc.
 You can view the documentation
 [here](https://evanthegrayt.github.io/semverve/).
 
+If you are upgrading across breaking changes, see [UPGRADING.md](UPGRADING.md).
+
 ## Installation
 Add the gem to your Gemfile:
 
@@ -62,8 +64,10 @@ rake semverve:check:references
 rake semverve:fix:references
 rake semverve:check:code
 rake semverve:fix:code
-rake semverve:check:metadata
-rake semverve:fix:metadata
+rake semverve:check:package_metadata
+rake semverve:fix:package_metadata
+rake semverve:check:rails_config_metadata
+rake semverve:fix:rails_config_metadata
 rake semverve:check:rubygems
 rake semverve:check:release
 ```
@@ -90,7 +94,7 @@ Semverve.configure do |config|
   config.bundle_lock = true
   config.version_file = "lib/my_gem/version.rb"
   config.module_name = "MyGem"
-  config.version_checks = [:doc_references, :code_references, :metadata]
+  config.version_checks = [:doc_references, :code_references, :package_metadata]
   config.release_checks = [:rubygems]
   config.rubygems_host = "https://rubygems.org"
   config.version_code_reference_files.append("lib/**/*.rb")
@@ -103,10 +107,11 @@ The core defaults are equivalent to:
 
 ```ruby
 Semverve.configure do |config|
+  config.adapter = nil
   config.format = :module
   config.bundle_lock = false
   config.root = Dir.pwd
-  config.version_checks = [:doc_references, :code_references, :metadata]
+  config.version_checks = [:doc_references, :code_references, :package_metadata]
   config.release_checks = []
   config.rubygems_host = "https://rubygems.org"
   config.version_match_mode = :older
@@ -124,7 +129,8 @@ 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.
+version and matching `Gemfile.lock` entry through its default package 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.
 
@@ -169,6 +175,11 @@ Semverve::Task.new do |config|
 end
 ```
 
+## Framework adapters
+Framework adapters provide app-oriented defaults without requiring a gemspec or
+package identity. `config.adapter` is the preferred API; `config.preset` remains
+supported as a backward-compatible alias.
+
 ## 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,
@@ -176,17 +187,21 @@ deployment metadata, or API output.
 
 When Rails is loaded, Semverve's Railtie installs the same `semverve:*` Rake
 tasks for `bin/rails`/`rails` automatically. To use Rails-style defaults, set
-the Rails preset:
+the Rails adapter:
 
 ```ruby
 Semverve.configure do |config|
-  config.preset = :rails
+  config.adapter = :rails
 end
 ```
 
-The Rails preset uses `Rails.root`, stores the version in
+`config.preset = :rails` is still accepted for existing setups.
+
+The Rails adapter uses `Rails.root`, stores the version in
 `config/version.rb`, uses the `:simple` format, and infers the module name from
-your Rails application module when possible.
+your Rails application module when possible. Its default checks are app-oriented:
+documentation references, configured code literals, and optional Rails config
+metadata. It does not run package metadata checks unless you opt in.
 
 Generate the file with:
 
@@ -198,14 +213,49 @@ If your app keeps the version somewhere else, override the path:
 
 ```ruby
 Semverve.configure do |config|
-  config.preset = :rails
+  config.adapter = :rails
   config.version_file = "config/releases/version.rb"
 end
 ```
 
-Rails support is only a preset and a Railtie; Semverve does not require a dummy
+Rails support is only an adapter and a Railtie; Semverve does not require a dummy
 app, a Rails plugin layout, or a Rails dependency.
 
+Rails config metadata is optional. When present, Semverve checks safe literals
+in `config/application.rb`, `config/environments/*.rb`, and
+`config/initializers/**/*.rb`:
+
+```ruby
+config.x.version = "1.2.2"
+Rails.application.config.x.version = "1.2.2"
+```
+
+Dynamic assignments are treated as self-managed and left alone:
+
+```ruby
+config.x.version = Storefront::VERSION
+```
+
+Rails engines or apps that publish gems can opt into package metadata checks by
+setting `config.gem_name` and including `:package_metadata` in
+`config.version_checks`. Deployment and container metadata, such as Docker,
+Kamal, and Helm, are intentionally left for future adapter support.
+
+## Sinatra apps
+Sinatra applications can use the Sinatra adapter for app-style defaults:
+
+```ruby
+Semverve.configure do |config|
+  config.adapter = :sinatra
+end
+```
+
+The Sinatra adapter stores the version in `config/version.rb`, uses the
+`:simple` format, infers the module name from the project directory, and checks
+documentation references plus configured code literals by default. It does not
+infer a package name from `config/version.rb` and does not run package metadata
+checks unless you opt in.
+
 ## Formats
 The default `:module` format stores `MAJOR`, `MINOR`, and `PATCH` constants
 under a `Version` module and exposes a top-level `VERSION` constant.
@@ -329,12 +379,15 @@ 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:
+By default, gem/package projects check:
 
 - README version references, plus any configured docs or comment files
 - configured code files for safe version literals
 - the gemspec version and `Gemfile.lock` entry
 
+Rails adapter projects instead check README references, configured code literals,
+and optional Rails config metadata.
+
 Findings are printed in parseable formats and the task exits non-zero:
 
 ```text
@@ -355,11 +408,13 @@ Choose which surfaces the umbrella `check` and `fix` tasks run with
 
 ```ruby
 Semverve.configure do |config|
-  config.version_checks = [:doc_references, :metadata]
+  config.version_checks = [:doc_references, :package_metadata]
 end
 ```
 
-The allowed values are `:doc_references`, `:code_references`, and `:metadata`.
+The allowed values come from Semverve's check registry. Built-in checks are
+`:doc_references`, `:code_references`, and `:package_metadata`; framework
+adapters can add their own checks, such as Rails' `:rails_config_metadata`.
 
 Use focused tasks when you want only one surface:
 
@@ -368,12 +423,15 @@ rake semverve:check:references
 rake semverve:fix:references
 rake semverve:check:code
 rake semverve:fix:code
-rake semverve:check:metadata
-rake semverve:fix:metadata
+rake semverve:check:package_metadata
+rake semverve:fix:package_metadata
+rake semverve:check:rails_config_metadata
+rake semverve:fix:rails_config_metadata
 ```
 
-`semverve:fix:metadata` rewrites literal gemspec versions when safe and
-runs `bundle lock` for `Gemfile.lock` drift.
+`semverve:fix:package_metadata` rewrites literal gemspec versions when safe and
+runs `bundle lock` for `Gemfile.lock` drift. `semverve:fix:rails_config_metadata`
+rewrites safe Rails config version literals.
 
 Pass a semantic version when you want to check or fix only that exact version in
 doc references and code literals:
@@ -383,9 +441,55 @@ 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.
+Package metadata and adapter-owned metadata checks still compare metadata to the
+current version. If you target the current version, check tasks list
+reference/code matches but fix tasks are no-ops because the text is already
+current.
+
+## Extension API
+Semverve exposes small public objects for framework adapters and version checks.
+These APIs are intentionally local registration APIs; Semverve does not yet
+autoload third-party adapter gems.
+
+Register a framework adapter with `Semverve::Adapters.register`. An adapter
+must expose `name`, `defaults(configuration)`, and `checks`. It can also expose
+`infer_package_name?` to control whether app-style version files should be
+treated as package names.
+
+Register a check with `Semverve::VersionChecks.register`, or return adapter-owned
+checks from an adapter's `checks` method. A check object should expose:
+
+- `name` and `task_name`
+- `check_description`, `fix_description`, `finding_label`, and `fix_label`
+- `clean_message`, `targetable?`, and `exact_target_fix_noop_notice?`
+- `findings(configuration, current_version, include_ignored:, target_version:)`
+- `fix(configuration, current_version, target_version:)`
+
+Checks should return `Semverve::Finding` objects from `findings` and a
+`Semverve::FixResult` from `fix`. `Semverve::VersionMatchPolicy` and
+`Semverve::VersionLiteralRewriter` are available for checks that need Semverve's
+standard stale-version matching or named-capture literal rewriting.
+
+For example:
+
+```ruby
+class MyConfigVersionCheck < Semverve::VersionChecks::Check
+  def name = :my_config_metadata
+  def task_name = :my_config_metadata
+  def check_description = "Check app config metadata for version mismatches"
+  def fix_description = "Fix safe app config metadata version mismatches"
+  def finding_label = "app config version"
+  def clean_message = "App config metadata is current."
+
+  def findings(configuration, current_version, include_ignored: false, target_version: nil)
+    []
+  end
+
+  def fix(configuration, current_version, target_version: nil)
+    Semverve::FixResult.new(changed_files: [], replacement_count: 0)
+  end
+end
+```
 
 ### Version references
 Version references are prose-like references to versions. These are usually in
@@ -457,7 +561,7 @@ SEMVERVE_REPORT_IGNORED=true rake 'semverve:check[1.2.2]'
 
 ### Code version literals
 Code scanning is opt-in to avoid false positives. This is for arbitrary project
-code, not gem metadata. The default is:
+code, not package metadata. The default is:
 
 ```ruby
 Semverve.configure do |config|
@@ -532,14 +636,14 @@ The custom value must be a `Regexp` and must include a named capture called
 `rake semverve:fix:code`, and the captured value still has to parse as a
 semantic version.
 
-### Metadata
-Metadata checks are part of `rake semverve:check` by default. They compare the
-current version file against:
+### Package metadata
+Package metadata checks are part of `rake semverve:check` by default for
+gem/package projects. They compare the current version file against:
 
 - the resolved `.gemspec` version
 - the matching `Gemfile.lock` entry, when a lockfile exists
 
-Metadata always requires an exact match, regardless of
+Package metadata always requires an exact match, regardless of
 `config.version_match_mode`.
 
 No file-list configuration is needed for these checks. Semverve resolves the
@@ -565,9 +669,25 @@ Gem::Specification.new do |spec|
 end
 ```
 
-`rake semverve:fix:metadata` updates safe literal gemspec assignments and
+`rake semverve:fix:package_metadata` updates safe literal gemspec assignments and
 runs `bundle lock` when the lockfile has drifted.
 
+### Rails config metadata
+Rails config metadata checks are part of `rake semverve:check` when the Rails
+adapter is active. They scan `config/application.rb`,
+`config/environments/*.rb`, and `config/initializers/**/*.rb` for optional Rails
+config literals:
+
+```ruby
+config.x.version = "1.2.2"
+Rails.application.config.x.version = "1.2.2"
+```
+
+These checks always require an exact match with the current Semverve version.
+`rake semverve:fix:rails_config_metadata` rewrites only those safe string
+literals. Dynamic assignments, including `config.x.version = Storefront::VERSION`,
+are considered self-managed and ignored.
+
 ## 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

data/UPGRADING.md

@@ -0,0 +1,78 @@
+# Upgrading Semverve
+
+## Version 0.4.0
+
+This release changes Semverve's version-check API so Rails and other app
+frameworks can be supported without pretending every project is a gem package.
+
+### Breaking changes
+
+- `:metadata` was removed from `config.version_checks`.
+- `semverve:check:metadata` and `semverve:fix:metadata` were removed.
+- Use `:package_metadata`, `semverve:check:package_metadata`, and
+  `semverve:fix:package_metadata` for gemspec and `Gemfile.lock` checks.
+- Rails defaults no longer include package metadata checks.
+- Rails apps no longer infer a package name from `config/version.rb`.
+
+### Rails apps
+
+Use the Rails adapter:
+
+```ruby
+Semverve.configure do |config|
+  config.adapter = :rails
+end
+```
+
+`config.preset = :rails` still works for compatibility, but `config.adapter` is
+the preferred API.
+
+Rails defaults now use:
+
+```ruby
+[:doc_references, :code_references, :rails_config_metadata]
+```
+
+Rails config metadata is optional. If Semverve finds safe literals like these,
+it checks and can fix them:
+
+```ruby
+config.x.version = "1.2.3"
+Rails.application.config.x.version = "1.2.3"
+```
+
+Dynamic assignments are treated as self-managed:
+
+```ruby
+config.x.version = Storefront::VERSION
+```
+
+Rails engines or apps that publish gems can opt back into package metadata:
+
+```ruby
+Semverve.configure do |config|
+  config.adapter = :rails
+  config.gem_name = "my_engine"
+  config.version_checks = [:doc_references, :code_references, :rails_config_metadata, :package_metadata]
+end
+```
+
+### Sinatra apps
+
+Sinatra apps can opt into app-style defaults:
+
+```ruby
+Semverve.configure do |config|
+  config.adapter = :sinatra
+end
+```
+
+The Sinatra adapter uses `config/version.rb`, `:simple` format, and default
+checks of `[:doc_references, :code_references]`.
+
+### Extension API
+
+Framework integration now goes through `Semverve::Adapters`, and version-check
+integration goes through `Semverve::VersionChecks`. Checks should return
+`Semverve::Finding` objects from `findings` and `Semverve::FixResult` from
+`fix`.

data/lib/semverve/adapters.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "version_checks"
+
+module Semverve
+  ##
+  # Framework-specific configuration adapters.
+  module Adapters
+    class << self
+      ##
+      # Registers a framework adapter.
+      #
+      # @param [#name, #defaults, #checks] adapter
+      #
+      # @return [#name, #defaults, #checks]
+      def register(adapter)
+        adapters[adapter.name] = adapter
+      end
+
+      ##
+      # Returns an adapter by name.
+      #
+      # @param [Symbol, String] name
+      #
+      # @return [#name, #defaults, #checks]
+      def fetch(name)
+        normalized_name = normalize_name(name)
+        adapter = adapters[normalized_name]
+        return adapter if adapter
+
+        raise Error, unknown_adapter_message(name)
+      end
+
+      ##
+      # Defaults for the configured adapter.
+      #
+      # @param [Symbol, String, nil] name
+      # @param [Semverve::Configuration] configuration
+      #
+      # @return [Hash]
+      def defaults_for(name, configuration)
+        return {} unless name
+
+        fetch(name).defaults(configuration)
+      end
+
+      ##
+      # Checks supplied by all registered adapters.
+      #
+      # @return [Array<#name>]
+      def checks
+        adapters.values.flat_map(&:checks).each_with_object({}) do |check, checks|
+          checks[check.name] = check
+        end.values
+      end
+
+      ##
+      # Checks supplied by the configured adapter.
+      #
+      # @param [Symbol, String, nil] name
+      #
+      # @return [Array<#name>]
+      def checks_for(name)
+        return [] unless name
+
+        fetch(name).checks
+      end
+
+      ##
+      # Whether package names should be inferred for the configured adapter.
+      #
+      # @param [Symbol, String, nil] name
+      #
+      # @return [Boolean]
+      def infer_package_name?(name)
+        return true unless name
+
+        fetch(name).infer_package_name?
+      end
+
+      ##
+      # Registered adapter names.
+      #
+      # @return [Array<Symbol>]
+      def names
+        adapters.keys
+      end
+
+      private
+
+      ##
+      # Adapter registry.
+      #
+      # @return [Hash<Symbol, #name>]
+      def adapters
+        @adapters ||= {}
+      end
+
+      ##
+      # Normalizes an adapter name.
+      #
+      # @param [Object] name
+      #
+      # @return [Symbol, Object]
+      def normalize_name(name)
+        name.respond_to?(:to_sym) ? name.to_sym : name
+      end
+
+      ##
+      # Error message for invalid adapters.
+      #
+      # @param [Object] name
+      #
+      # @return [String]
+      def unknown_adapter_message(name)
+        adapter_names = names.map(&:inspect)
+        valid_adapters = "#{adapter_names[0...-1].join(", ")}, or #{adapter_names.last}"
+        "Unknown adapter #{name.inspect}. Use #{valid_adapters}."
+      end
+    end
+
+    ##
+    # Shared adapter helpers.
+    class Base
+      ##
+      # Framework-specific checks.
+      #
+      # @return [Array<#name>]
+      def checks
+        []
+      end
+
+      ##
+      # Whether Semverve should infer package names from version files or gemspecs.
+      #
+      # @return [Boolean]
+      def infer_package_name?
+        true
+      end
+
+      private
+
+      ##
+      # Module name fallback based on the project directory.
+      #
+      # @param [String] root
+      #
+      # @return [String]
+      def project_module_name(root)
+        camelize(File.basename(File.expand_path(root)))
+      end
+
+      ##
+      # Converts a project directory into a Ruby module name.
+      #
+      # @param [String] value
+      #
+      # @return [String]
+      def camelize(value)
+        value.split(/[_-]/).map(&:capitalize).join
+      end
+    end
+
+    ##
+    # Rails application adapter.
+    class Rails < Base
+      ##
+      # Adapter name.
+      #
+      # @return [Symbol]
+      def name
+        :rails
+      end
+
+      ##
+      # Rails-specific Semverve defaults.
+      #
+      # @param [Semverve::Configuration] _configuration
+      #
+      # @return [Hash]
+      def defaults(_configuration)
+        root = rails_root || Dir.pwd
+
+        {
+          format: :simple,
+          module_name: rails_module_name || project_module_name(root),
+          root: root,
+          version_checks: [:doc_references, :code_references, :rails_config_metadata],
+          version_file: File.join("config", "version.rb")
+        }
+      end
+
+      ##
+      # Rails-specific checks.
+      #
+      # @return [Array<#name>]
+      def checks
+        [VersionChecks::RailsConfigMetadataCheck.new]
+      end
+
+      ##
+      # Rails apps should not infer a package name from config/version.rb.
+      #
+      # @return [Boolean]
+      def infer_package_name?
+        false
+      end
+
+      private
+
+      ##
+      # Rails.root when Rails is available.
+      #
+      # @return [String, nil]
+      def rails_root
+        return unless rails_defined?
+        return unless ::Rails.respond_to?(:root)
+        return unless ::Rails.root
+
+        ::Rails.root.to_s
+      end
+
+      ##
+      # Application module name inferred from Rails.application.
+      #
+      # @return [String, nil]
+      def rails_module_name
+        return unless rails_defined?
+        return unless ::Rails.respond_to?(:application)
+        return unless ::Rails.application
+
+        application_class = ::Rails.application.class
+        return application_class.module_parent_name if application_class.respond_to?(:module_parent_name)
+
+        class_name = application_class.name
+        return unless class_name&.include?("::")
+
+        class_name.split("::").first
+      end
+
+      ##
+      # Whether Rails is loaded.
+      #
+      # @return [Boolean]
+      def rails_defined?
+        Object.const_defined?(:Rails)
+      end
+    end
+
+    ##
+    # Sinatra application adapter.
+    class Sinatra < Base
+      ##
+      # Adapter name.
+      #
+      # @return [Symbol]
+      def name
+        :sinatra
+      end
+
+      ##
+      # Sinatra-specific Semverve defaults.
+      #
+      # @param [Semverve::Configuration] _configuration
+      #
+      # @return [Hash]
+      def defaults(_configuration)
+        root = Dir.pwd
+
+        {
+          format: :simple,
+          module_name: project_module_name(root),
+          root: root,
+          version_checks: [:doc_references, :code_references],
+          version_file: File.join("config", "version.rb")
+        }
+      end
+
+      ##
+      # Sinatra apps should not infer a package name from config/version.rb.
+      #
+      # @return [Boolean]
+      def infer_package_name?
+        false
+      end
+    end
+  end
+end
+
+Semverve::Adapters.register(Semverve::Adapters::Rails.new)
+Semverve::Adapters.register(Semverve::Adapters::Sinatra.new)