rubyzen-lint 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e0bc97dbd17202e4245c3c8c6b1d16f7fcdef64eab20ff96ab835113e21fbd9
-  data.tar.gz: 4fb9b3a30754c283823a44e208bd4de9ca0a035db5733df418ef1e70bd98172d
+  metadata.gz: 7ce170df4572f8af2962998ff57160f0027b39288a5f53d566234ff5e1442b43
+  data.tar.gz: 1189a743bb4de63887b7f45d4387a3b3fb6571ef5cb4a67763bbc0f69c31bde8
 SHA512:
-  metadata.gz: c23bf87e539bdda57d28a5b9f0b5fdbbee847a88ce93bf012c92a1c00eaf48fe1f5e2a99bea6a2e070749c2c74451821026f742a2e4e50e12c5395ed4295b870
-  data.tar.gz: 189a609b17528f6d0898defda84762df30273f4607f4e97882d21d255b111d719818adb9148d452c4ff5b9d7c29dbcc5c68749f36d0e96c86740451d096dc778
+  metadata.gz: c424e1404f091fa5c965a4253f15b853e031b9078b305df0fa770d94fa545524f5f17776100bc7986ff630cb10c9506338886604d3a0c6b11f77058b66725a9b
+  data.tar.gz: 4275ca620f94b150758f12222064d2ec5b0314502a4a3da4a8bed40d1d937fc580f8f8d23878dfd74933a59615843c6bc5b35c0ff106fb525c816d2c1419c224

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## [0.2.0]
+
+### Added
+
+- **Minitest adapter.** Write architectural lint rules with Minitest using
+  `require 'rubyzen/minitest'`. This provides the `assert_zen_empty`, `assert_zen_true`,
+  and `assert_zen_false` assertions, which mirror the RSpec matchers.
+
+### Changed
+
+- **`rspec` is no longer a runtime dependency.** Rubyzen no longer depends 
+  on RSpec at runtime; RSpec users should add `gem 'rspec'` (or `rspec-rails`)
+  to their Gemfile. This allows Minitest users to not depend on RSpec.
+
+### Migration from 0.1.x
+
+- Change `require 'rubyzen'` to `require 'rubyzen/rspec'`.
+- Ensure `gem 'rspec'` is in your Gemfile's test group.
+
+## [0.1.0]
+
+- Initial release

data/README.md

@@ -1,6 +1,10 @@
 # Rubyzen
 
-Rubyzen is an architectural linter for Ruby that lets you write architectural lint rules as unit tests, inspired by [Konsist](https://github.com/LemonAppDev/konsist) (for Kotlin) and [Harmonize](https://github.com/perrystreetsoftware/Harmonize) (for Swift).
+[![Gem Version](https://badge.fury.io/rb/rubyzen-lint.svg)](https://badge.fury.io/rb/rubyzen-lint)
+[![CI](https://github.com/perrystreetsoftware/Rubyzen/actions/workflows/tests.yml/badge.svg)](https://github.com/perrystreetsoftware/Rubyzen/actions/workflows/tests.yml)
+[![Docs](https://img.shields.io/badge/docs-yard-blue)](https://perrystreetsoftware.github.io/Rubyzen)
+
+Rubyzen is an architectural linter for Ruby that allows you to write architectural lint rules as unit tests, inspired by [Konsist](https://github.com/LemonAppDev/konsist) (for Kotlin) and [Harmonize](https://github.com/perrystreetsoftware/Harmonize) (for Swift).
 
 ## Architectural linters in the era of AI-generated code
 
@@ -24,22 +28,26 @@ Traditional linters such as [RuboCop](https://github.com/rubocop/rubocop) requir
 
 ## Setup
 
-Add Rubyzen to your Gemfile:
+Add Rubyzen to your Gemfile's test group, alongside your test framework.
 
 ```ruby
-gem 'rubyzen-lint', group: :test
+group :test do
+  gem 'rubyzen-lint'
+  # gem 'rspec'      # if you use RSpec (or rspec-rails)
+  # gem 'minitest'   # if you use Minitest
+end
 ```
 
 Then run `bundle install`.
 
-That's it. Rubyzen auto-discovers your project structure (`app/`, `lib/`, `src/`, `spec/`) from your project root. No environment variables or configuration needed.
+Rubyzen auto-discovers your project structure (`app/`, `lib/`, `src/`, `spec/`) from your project root. If you need to lint other directories (e.g., `config/`, `db/`), see [Custom Paths](#custom-paths) below.
 
 ## Write your first set of lint rules
 
 Create a spec file anywhere in your project (e.g., `spec/architecture/sample_spec.rb`) and start enforcing your architecture:
 
 ```ruby
-require 'rubyzen'
+require 'rubyzen/rspec'
 
 RSpec.describe 'Architecture rules' do
   let(:project) { Rubyzen::Project.new }
@@ -64,15 +72,49 @@ end
 
 You can find more sample lint rules in the [`sample_project/spec/`](sample_project/spec/) directory.
 
+## Using Minitest
+
+If you use Minitest instead of RSpec, replace `require 'rubyzen/rspec'` with `require 'rubyzen/minitest'` and use the equivalent Minitest assertions:
+
+```ruby
+require 'rubyzen/minitest'
+
+class ArchitectureTest < Minitest::Test
+  def controllers = Rubyzen::Project.new.files.with_paths('app/controllers/').classes
+
+  def test_controllers_do_not_call_active_record_directly
+    assert_zen_empty(controllers.all_methods.call_sites.with_name('where'))
+  end
+end
+```
+
+## Matchers and assertions
+
+Rubyzen provides three checks for your architectural lint rules:
+
+| Using RSpec | Using Minitest | Checks that |
+|---|---|---|
+| `zen_empty` | `assert_zen_empty(collection)` | the collection is empty |
+| `zen_true { \|item\| }` | `assert_zen_true(collection) { \|item\| }` | the block returns true for every element |
+| `zen_false { \|item\| }` | `assert_zen_false(collection) { \|item\| }` | the block returns false for every element |
+
+All three accept an `allowlist:` of exceptions that are permanently exempt from the rule, a `baseline:` of known existing violations (technical debt) to fix over time, and a custom failure message.
+
 ## Run your lint rules
 
 ```bash
+# If you use RSpec:
 bundle exec rspec spec/architecture/
+
+# If you use Minitest in Rails:
+bin/rails test test/architecture
 ```
 
-## Custom Paths (Optional)
+If you use Minitest outside of Rails, you can use a `Rake::TestTask` to run all lint rules in `test/architecture/`.
+
+## Custom Paths
 
-By default, `Rubyzen::Project.new` scans standard directories (`app/`, `lib/`, `src/`, `spec/`) from your project root. You can override this:
+By default, `Rubyzen::Project.new` scans `app/`, `lib/`, `src/`, and `spec/`. If you need to lint other directories (e.g., `config/`, `db/`), add them explicitly, otherwise those files won't be scanned and queries against them will return empty results.
 
 ```ruby
 # In your spec file — scope to specific directories
@@ -80,7 +122,7 @@ project = Rubyzen::Project.new(['app/models', 'app/controllers'])
 
 # Or in spec/spec_helper.rb — configure globally for all specs
 Rubyzen.configure do |config|
-  config.paths = ['app', 'lib']
+  config.paths = ['app', 'lib', 'config']
 end
 ```
 
@@ -93,6 +135,8 @@ Add a step to your existing CI workflow to run your lint rules automatically whe
   run: bundle exec rspec spec/architecture/
 ```
 
+If you use Minitest in Rails, run `bin/rails test test/architecture` instead. For plain Ruby apps, use the `Rake::TestTask` described above.
+
 ## AI Agent Skills
 
 Rubyzen includes agent skills in `.claude/skills/` (also symlinked at `.github/skills/`) that work with both Claude Code and GitHub Copilot:
@@ -107,4 +151,8 @@ Rubyzen includes agent skills in `.claude/skills/` (also symlinked at `.github/s
 
 ## Contributing
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on setting up the project, enhancing the API, and adding tests.
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on setting up the project, enhancing the API, and adding tests.
+
+## Perry Street Software is hiring
+
+If you are a Ruby or DevOps engineer excited about [application architecture](https://itnext.io/a-visual-history-of-web-api-architecture-c36044df2ac7) on a platform running at very large scale, check out our [careers](https://www.perrystreet.com/careers) page! Our company has written extensively about our technical approach on the [Perry Street Software Engineering Blog](https://medium.com/perry-street-software-engineering).

data/lib/rubyzen/assertions/assert_zen_empty.rb

@@ -0,0 +1,51 @@
+module Rubyzen
+  module Assertions
+    # Asserts that a Rubyzen collection is empty (the Minitest counterpart of
+    # the +zen_empty+ matcher).
+    #
+    # Used in architectural lint rules to verify that no items match a forbidden
+    # pattern (e.g., no controllers call +.where+ directly).
+    #
+    # @param collection [Enumerable] a Rubyzen collection of declarations
+    # @param message [String, nil] optional custom failure message
+    # @param allowlist [Array<String>, nil] items to permanently ignore
+    # @param baseline [Array<String>, nil] known violations for gradual adoption
+    # @return [true] when the assertion passes
+    # @raise [Minitest::Assertion] when there are live violations or stale entries
+    #
+    # @example Ensure no controllers use .where
+    #   assert_zen_empty(controllers.all_methods.call_sites.with_name('where'))
+    #
+    # @example With a baseline for gradual adoption
+    #   assert_zen_empty(violations, baseline: ['LegacyController'])
+    def assert_zen_empty(collection, message: nil, allowlist: nil, baseline: nil)
+      @failure_message = nil
+      @custom_message = message
+      @classified_items = classify_items(collection, allowlist: allowlist, baseline: baseline)
+
+      violations = @classified_items[:violations]
+      stale_baseline = @classified_items[:stale_baseline]
+      stale_allowlist = @classified_items[:stale_allowlist]
+
+      stale_groups = []
+      stale_groups << 'baseline entries' if stale_baseline.any?
+      stale_groups << 'allowlist entries' if stale_allowlist.any?
+
+      reason =
+        if violations.any? && stale_groups.any?
+          "Expected to be empty, but found live violations and stale #{stale_groups.join(' and ')}."
+        elsif violations.any?
+          if allowlist || baseline
+            'Expected to be empty, but found live violations.'
+          else
+            'Expected to be empty, but had elements.'
+          end
+        elsif stale_groups.any?
+          "Expected to be empty, but found stale #{stale_groups.join(' and ')}."
+        end
+
+      passed = violations.empty? && stale_baseline.empty? && stale_allowlist.empty?
+      assert(passed, message_for_failure(reason || 'Expected to be empty, but had elements.'))
+    end
+  end
+end

data/lib/rubyzen/assertions/assert_zen_false.rb

@@ -0,0 +1,49 @@
+module Rubyzen
+  module Assertions
+    # Asserts that a block returns false for every item in a collection (the
+    # Minitest counterpart of the +zen_false+ matcher).
+    #
+    # @param collection [Enumerable] a Rubyzen collection of declarations
+    # @param message [String, nil] optional custom failure message
+    # @param allowlist [Array<String>, nil] items to permanently ignore
+    # @param baseline [Array<String>, nil] known violations for gradual adoption
+    # @yield [item] block that should return false for each item
+    # @return [true] when the assertion passes
+    # @raise [ArgumentError] when no block is given
+    # @raise [Minitest::Assertion] when the block returns truthy for a live item
+    #
+    # @example Ensure no methods have more than 5 parameters
+    #   assert_zen_false(methods) { |m| m.parameters.size > 5 }
+    #
+    # @example With a baseline for gradual adoption
+    #   assert_zen_false(classes, baseline: ['LegacyModel']) { |k| k.lines_of_code > 200 }
+    def assert_zen_false(collection, message: nil, allowlist: nil, baseline: nil, &block)
+      raise ArgumentError, 'assert_zen_false requires a block' unless block
+
+      @failure_message = nil
+      @custom_message = message
+      failing_items = Array(collection).filter { |item| block.call(item) }
+      @classified_items = classify_items(failing_items, allowlist: allowlist, baseline: baseline)
+
+      violations = @classified_items[:violations]
+      stale_baseline = @classified_items[:stale_baseline]
+      stale_allowlist = @classified_items[:stale_allowlist]
+
+      stale_groups = []
+      stale_groups << 'baseline entries' if stale_baseline.any?
+      stale_groups << 'allowlist entries' if stale_allowlist.any?
+
+      reason =
+        if violations.any? && stale_groups.any?
+          "Expected to return false for all elements, but found live violations and stale #{stale_groups.join(' and ')}."
+        elsif violations.any?
+          'Expected to return false for all elements.'
+        elsif stale_groups.any?
+          "Expected to return false for all elements, but found stale #{stale_groups.join(' and ')}."
+        end
+
+      passed = violations.empty? && stale_baseline.empty? && stale_allowlist.empty?
+      assert(passed, message_for_failure(reason || 'Expected to return false for all elements.'))
+    end
+  end
+end

data/lib/rubyzen/assertions/assert_zen_true.rb

@@ -0,0 +1,49 @@
+module Rubyzen
+  module Assertions
+    # Asserts that a block returns true for every item in a collection (the
+    # Minitest counterpart of the +zen_true+ matcher).
+    #
+    # @param collection [Enumerable] a Rubyzen collection of declarations
+    # @param message [String, nil] optional custom failure message
+    # @param allowlist [Array<String>, nil] items to permanently ignore
+    # @param baseline [Array<String>, nil] known violations for gradual adoption
+    # @yield [item] block that should return true for each item
+    # @return [true] when the assertion passes
+    # @raise [ArgumentError] when no block is given
+    # @raise [Minitest::Assertion] when the block returns falsey for a live item
+    #
+    # @example Ensure all methods have parameters
+    #   assert_zen_true(methods) { |m| m.parameters? }
+    #
+    # @example With a custom failure message
+    #   assert_zen_true(services, message: 'All services must inherit from BaseService') { |s| s.superclass_name == 'BaseService' }
+    def assert_zen_true(collection, message: nil, allowlist: nil, baseline: nil, &block)
+      raise ArgumentError, 'assert_zen_true requires a block' unless block
+
+      @failure_message = nil
+      @custom_message = message
+      failing_items = Array(collection).filter { |item| !block.call(item) }
+      @classified_items = classify_items(failing_items, allowlist: allowlist, baseline: baseline)
+
+      violations = @classified_items[:violations]
+      stale_baseline = @classified_items[:stale_baseline]
+      stale_allowlist = @classified_items[:stale_allowlist]
+
+      stale_groups = []
+      stale_groups << 'baseline entries' if stale_baseline.any?
+      stale_groups << 'allowlist entries' if stale_allowlist.any?
+
+      reason =
+        if violations.any? && stale_groups.any?
+          "Expected to return true for all elements, but found live violations and stale #{stale_groups.join(' and ')}."
+        elsif violations.any?
+          'Expected to return true for all elements.'
+        elsif stale_groups.any?
+          "Expected to return true for all elements, but found stale #{stale_groups.join(' and ')}."
+        end
+
+      passed = violations.empty? && stale_baseline.empty? && stale_allowlist.empty?
+      assert(passed, message_for_failure(reason || 'Expected to return true for all elements.'))
+    end
+  end
+end

data/lib/rubyzen/assertions/zen_assertions.rb

@@ -0,0 +1,29 @@
+require_relative '../expectation_helpers'
+
+module Rubyzen
+  # Minitest equivalents of the +zen_empty+ / +zen_true+ / +zen_false+ RSpec
+  # matchers. Mixed into +Minitest::Assertions+ by +require 'rubyzen/minitest'+,
+  # so the methods are available in every +Minitest::Test+ (and spec-style block).
+  #
+  # All three delegate to the shared {Rubyzen::ExpectationHelpers} for
+  # violation/allowlist/baseline classification and failure-message formatting.
+  # The behavior is identical to the RSpec matchers ({Rubyzen::Matchers}).
+  #
+  # @example
+  #   class ArchitectureTest < Minitest::Test
+  #     def test_controllers_have_no_if_statements
+  #       assert_zen_empty(controllers.all_methods.if_statements)
+  #     end
+  #
+  #     def test_repos_live_in_module
+  #       assert_zen_true(repos) { |repo| repo.top_level_module == 'Repos' }
+  #     end
+  #   end
+  module Assertions
+    include Rubyzen::ExpectationHelpers
+  end
+end
+
+require_relative 'assert_zen_empty'
+require_relative 'assert_zen_true'
+require_relative 'assert_zen_false'

data/lib/rubyzen/cache/parse_cache.rb

@@ -1,6 +1,7 @@
 require 'digest'
 
 module Rubyzen
+  # Caching utilities for parsed AST results.
   module Cache
     # In-memory cache for parsed AST results, keyed by file path and SHA256 checksum.
     # Automatically invalidates entries when file contents change.

data/lib/rubyzen/collections/base_collection.rb

@@ -1,4 +1,5 @@
 module Rubyzen
+  # Typed collections that wrap arrays of declarations with filtering and aggregation.
   module Collections
     # Base collection class for all Rubyzen collections.
     # Extends Array and replaces +select+/+reject+ with a single +filter+ method

data/lib/rubyzen/core.rb

@@ -0,0 +1,114 @@
+require 'rubocop-ast'
+require 'zeitwerk'
+
+# Framework-agnostic core of Rubyzen.
+#
+# Owns the Zeitwerk autoloading of the parsing API (declarations, collections,
+# providers, parsers) and defines the +Rubyzen+ module and its +Configuration+.
+#
+# This file deliberately does NOT require any test framework (RSpec or Minitest)
+# so that adapters can load only what they need:
+#   * +require 'rubyzen'+          → core only (no test framework)
+#   * +require 'rubyzen/rspec'+    → core + RSpec matchers
+#   * +require 'rubyzen/minitest'+ → core + Minitest assertions
+lib_dir = File.expand_path('..', __dir__)
+
+loader = Zeitwerk::Loader.new
+loader.tag = 'rubyzen'
+loader.push_dir(lib_dir)
+# Entry points and adapter directories are loaded explicitly, not autoloaded.
+loader.ignore("#{lib_dir}/rubyzen.rb")
+loader.ignore("#{lib_dir}/rubyzen-lint.rb")
+loader.ignore("#{__dir__}/core.rb")
+loader.ignore("#{__dir__}/minitest.rb")
+loader.ignore("#{__dir__}/lint.rb")
+loader.ignore("#{__dir__}/matchers")
+loader.ignore("#{__dir__}/assertions")
+loader.ignore("#{__dir__}/expectation_helpers.rb")
+loader.ignore("#{__dir__}/rspec.rb")
+loader.setup
+
+# Rubyzen is a Ruby architectural linter that lets you write lint rules as unit tests.
+# It wraps RuboCop AST to provide a high-level, easy-to-use API for enforcing architectural
+# rules across a codebase.
+#
+# `require 'rubyzen'` loads this framework-agnostic core API only. To make an assertion on a
+# collection in a test, require the respective adapter: +rubyzen/rspec+ (the +zen_*+ matchers) or
+# +rubyzen/minitest+ (the +assert_zen_*+ assertions).
+#
+# @example Querying the project
+#   project = Rubyzen::Project.new(["/path/to/src", "/path/to/spec"])
+#   controllers = project.files.with_paths("controllers/").classes
+#   controllers.all_methods.call_sites.with_name("where") # => CallSiteCollection
+#
+# @example Using auto-discovery (from project root)
+#   project = Rubyzen::Project.new  # scans app/, lib/, src/, spec/ automatically
+#
+module Rubyzen
+  # Base error class for all Rubyzen errors.
+  class Error < StandardError; end
+
+  # Raised when a Ruby file cannot be parsed.
+  class ParseError < Error; end
+
+  # Yields the global configuration for customization.
+  #
+  # @example
+  #   Rubyzen.configure do |config|
+  #     config.paths = ['app', 'lib']
+  #   end
+  def self.configure
+    yield(configuration)
+  end
+
+  # Returns the global configuration instance.
+  #
+  # @return [Configuration]
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Holds project path configuration with auto-discovery support.
+  #
+  # Resolution order:
+  # 1. Explicit paths via {#paths=} (set via +Rubyzen.configure+)
+  # 2. Auto-discovery of +app/+, +lib/+, +src/+, +spec/+ from +Dir.pwd+
+  #
+  # @example
+  #   Rubyzen.configure { |c| c.paths = ['app/models', 'app/controllers'] }
+  #   Rubyzen.configuration.project_paths #=> ["/full/path/app/models", "/full/path/app/controllers"]
+  #
+  class Configuration
+    # Sets explicit paths to scan.
+    # Relative paths are resolved against +Dir.pwd+.
+    #
+    # @param value [Array<String>] directories to analyze
+    attr_writer :paths
+
+    # Returns the resolved project paths.
+    #
+    # @return [Array<String>] absolute paths to directories to analyze
+    def project_paths
+      resolve_paths(@paths) || auto_discover_paths
+    end
+
+    private
+
+    def resolve_paths(paths)
+      return nil unless paths&.any?
+
+      root = Dir.pwd
+      paths.map do |path|
+        File.expand_path(path, root)
+      end
+    end
+
+    def auto_discover_paths
+      root = Dir.pwd
+      candidates = %w[app lib src spec].map { |d| File.join(root, d) }
+      paths = candidates.select { |d| Dir.exist?(d) }
+      paths = [root] if paths.empty?
+      paths
+    end
+  end
+end

data/lib/rubyzen/declarations/file_declaration.rb

@@ -1,4 +1,5 @@
 module Rubyzen
+  # Domain objects wrapping AST nodes with high-level accessors.
   module Declarations
     # Represents a parsed Ruby source file. This is the root of the declaration
     # hierarchy — all other declarations are accessed through a FileDeclaration.

data/lib/rubyzen/expectation_helpers.rb

@@ -0,0 +1,184 @@
+module Rubyzen
+  # Shared helper methods for Rubyzen's +zen_*+ / +assert_zen_*+ expectations —
+  # used by both the RSpec matchers ({Rubyzen::Matchers}) and the Minitest
+  # assertions ({Rubyzen::Assertions}).
+  #
+  # Provides utilities for normalizing exception lists, extracting item details,
+  # matching items against allowlist/baseline entries, and formatting failure
+  # messages. These methods are framework-agnostic — they operate only on plain
+  # declaration objects and instance variables set by the caller.
+  module ExpectationHelpers
+    # Normalizes a list of exception entries into unique, non-blank strings.
+    #
+    # @param entries [Array<String>, String, nil] raw exception entries
+    # @return [Array<String>] deduplicated, stripped, non-empty strings
+    def normalize_exception_entries(entries)
+      Array(entries).flatten.compact.map(&:to_s).map(&:strip).reject(&:empty?).uniq
+    end
+
+    # Extracts identifying details from a declaration item.
+    #
+    # @param item [Object] a declaration object (e.g., FileDeclaration, ClassDeclaration)
+    # @return [Hash{Symbol => String, nil}] hash with :name, :class_name, :file_path, :line
+    def item_details(item)
+      {
+        name: item.respond_to?(:name) ? item.name : nil,
+        class_name: item.respond_to?(:class_name) ? item.class_name : nil,
+        file_path: item.respond_to?(:file_path) ? item.file_path : 'Unknown file',
+        line: item.respond_to?(:line) ? item.line : nil
+      }
+    end
+
+    # Returns a list of unique identifier strings for an item, used for matching.
+    #
+    # @param item [Object] a declaration object
+    # @return [Array<String>] identifiers such as name, class name, file path, and file:line
+    def item_identifiers(item)
+      details = item_details(item)
+      identifiers = [details[:name], details[:class_name], details[:file_path]]
+
+      if details[:line]
+        identifiers << "#{details[:file_path]}:#{details[:line]}"
+      end
+
+      identifiers.compact.uniq
+    end
+
+    # Checks whether a given exception entry string matches an item.
+    #
+    # @param entry [String] an allowlist or baseline entry
+    # @param item [Object] a declaration object
+    # @return [Boolean] true if the entry matches the item by name, class, or path
+    def exception_entry_matches_item?(entry, item)
+      normalized_entry = entry.to_s.strip
+      return false if normalized_entry.empty?
+
+      details = item_details(item)
+      return true if item_identifiers(item).include?(normalized_entry)
+
+      file_path = details[:file_path]
+      file_path && (file_path.end_with?(normalized_entry) || file_path.end_with?("/#{normalized_entry}"))
+    end
+
+    # Classifies items into violations, baseline matches, allowlist matches,
+    # and detects stale entries in either list.
+    #
+    # @param subject_collection [Array, Object] items to classify
+    # @param allowlist [Array<String>, nil] allowed exception entries
+    # @param baseline [Array<String>, nil] baseline exception entries
+    # @return [Hash{Symbol => Array<String>}] keys: :violations, :baseline, :allowlist,
+    #   :stale_baseline, :stale_allowlist
+    def classify_items(subject_collection, allowlist: nil, baseline: nil)
+      items = Array(subject_collection).compact
+      normalized_allowlist = normalize_exception_entries(allowlist)
+      normalized_baseline = normalize_exception_entries(baseline)
+      matched_baseline_entries = []
+      matched_allowlist_entries = []
+
+      grouped_items = items.group_by do |item|
+        matching_baseline_entry = normalized_baseline.find do |entry|
+          exception_entry_matches_item?(entry, item)
+        end
+
+        if matching_baseline_entry
+          matched_baseline_entries << matching_baseline_entry
+          :baseline
+        else
+          matching_allowlist_entry = normalized_allowlist.find do |entry|
+            exception_entry_matches_item?(entry, item)
+          end
+
+          if matching_allowlist_entry
+            matched_allowlist_entries << matching_allowlist_entry
+            :allowlist
+          else
+            :violations
+          end
+        end
+      end
+
+      classifications = {
+        baseline: Array(grouped_items[:baseline]).map { |item| element_name(item) },
+        allowlist: Array(grouped_items[:allowlist]).map { |item| element_name(item) },
+        violations: Array(grouped_items[:violations]).map { |item| element_name(item) }
+      }
+
+      classifications.merge(
+        stale_baseline: normalized_baseline - matched_baseline_entries.uniq,
+        stale_allowlist: normalized_allowlist - matched_allowlist_entries.uniq
+      )
+    end
+
+    # Formats a human-readable description of an item for failure messages.
+    #
+    # @param item [Object] a declaration object
+    # @return [String] formatted multi-line description
+    def element_name(item)
+      details = item_details(item)
+      location = [details[:file_path], details[:line]].compact.join(':')
+
+      case
+      when details[:name] && details[:class_name]
+        "  - element: #{details[:name]}\n  - class: #{details[:class_name]}\n  - file: #{location}"
+      when details[:name]
+        "  - element: #{details[:name]}\n  - file: #{location}"
+      when details[:class_name]
+        "  - class: #{details[:class_name]}\n  - file: #{location}"
+      else
+        "  - unknown element in #{location}"
+      end
+    end
+
+    # Builds a formatted string of violations and stale entries for failure output.
+    #
+    # @return [String, nil] formatted sections or nil if no classified items
+    def formatted_matcher_groups
+      return unless defined?(@classified_items) && @classified_items
+
+      sections = []
+
+      if @classified_items[:violations].any?
+        sections << "Violations:\n#{@classified_items[:violations].join("\n")}"
+      end
+
+      if @classified_items[:stale_baseline].any?
+        stale_entries = @classified_items[:stale_baseline].map { |entry| "  - #{entry}" }
+        sections << "Stale baseline entries:\n#{stale_entries.join("\n")}"
+      end
+
+      if @classified_items[:stale_allowlist].any?
+        stale_entries = @classified_items[:stale_allowlist].map { |entry| "  - #{entry}" }
+        sections << "Stale allowlist entries:\n#{stale_entries.join("\n")}"
+      end
+
+      sections.join("\n")
+    end
+
+    # Formats the failure message by combining the base message with
+    # custom messages and classified item details (violations, stale entries).
+    #
+    # Works unchanged in both RSpec matchers and Minitest assertions, since it
+    # only reads instance variables set by the caller (+@failure_message+,
+    # +@custom_message+, +@classified_items+).
+    #
+    # @param base_message [String] the default failure message
+    # @return [String] formatted failure message
+    def message_for_failure(base_message)
+      return @failure_message if @failure_message
+
+      details = formatted_matcher_groups
+
+      if @custom_message
+        if details && !details.empty?
+          "#{@custom_message}\n#{details}"
+        else
+          @custom_message
+        end
+      elsif details && !details.empty?
+        "#{base_message}\n#{details}"
+      else
+        base_message
+      end
+    end
+  end
+end