semverve 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b04f97b571e0eed652d155221cddb5afe06d703f2a27546f15c11e3d26a3d214
-  data.tar.gz: 6c824db22d1967e9daa8de369ca199b6cc7969f6ab2179933600fbba34d1aa6e
+  metadata.gz: 9d9765e973d77ca7011cb819202246f5ea7ef2faef574c66a58fc6ad5c058988
+  data.tar.gz: dea8769f32c6f6b70c81d05e2d46129cd9820a8289fbd032f42303dfc0b8dea3
 SHA512:
-  metadata.gz: 31208572bd96d1d1bb00537673e9960594501a2b4226f821114d8cb624965fd0cd7282722d6284cf0666f80a908706174a3ca3d0bb4109a3b18dc882e9a26ecd
-  data.tar.gz: 8deb952db13cfdf0f8a13fbbcffb07afc23c402ece2efc3d50899d4158ea7455a6bedc993cb79c9d3de8dfc83c8142981f87f52777ee79a8dba1c1b09bc58dcd
+  metadata.gz: 38b4aca2a29cfc750a7b6b7164219595ec35f76c9c5d526f441e469868686a6588170ee0e88c02942b97b59725d1c72c79b1496cad5880264042d99c8049846a
+  data.tar.gz: 7cf79a5a6d90a0f454ce03272e5592b140fff266893fee323b6e831ab28956104e7865bb5a141614e6cae6466a4bacbbd738850f299fd98d7f1024f391d61b7c

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.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,12 +94,12 @@ 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")
   config.version_doc_reference_files.append("doc/**/*.md")
-  config.version_reference_mode = :non_current
+  config.version_match_mode = :non_current
 end
 ```
 
@@ -103,13 +107,14 @@ 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_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>/
@@ -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,73 @@ 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:
+
+```sh
+rake 'semverve:check[1.2.2]'
+rake 'semverve:fix:references[1.2.2]'
+```
+
+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
@@ -410,20 +526,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,11 +556,12 @@ check tasks:
 
 ```sh
 SEMVERVE_REPORT_IGNORED=true rake semverve:check
+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|
@@ -518,15 +636,15 @@ 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
-`config.version_reference_mode`.
+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
 gemspec from the project root and reads `Gemfile.lock` when one exists.
@@ -551,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`.