rubyzen-lint 0.1.0 → 0.2.0

data/lib/rubyzen/matchers/zen_empty_matcher.rb

@@ -1,15 +1,26 @@
-# Custom RSpec matcher that asserts a Rubyzen collection is empty.
-#
-# Used in architectural lint rules to verify that no items match
-# a forbidden pattern (e.g., no controllers call +.where+ directly).
-#
-# @example Ensure no controllers use .where
-#   expect(controllers.all_methods.call_sites.with_name('where')).to zen_empty
-#
-# @example With a custom failure message
-#   expect(violations).to zen_empty("Controllers should not call .where directly")
+# @!parse
+#   module Rubyzen
+#     # Custom RSpec matchers for asserting on Rubyzen collections.
+#     module Matchers
+#       # Asserts that a Rubyzen collection is empty.
+#       #
+#       # Used in architectural lint rules to verify that no items match
+#       # a forbidden pattern (e.g., no controllers call +.where+ directly).
+#       #
+#       # @param custom_message [String, nil] optional failure message
+#       # @param allowlist [Array<String>, nil] items to permanently ignore
+#       # @param baseline [Array<String>, nil] known violations for gradual adoption
+#       #
+#       # @example Ensure no controllers use .where
+#       #   expect(controllers.all_methods.call_sites.with_name('where')).to zen_empty
+#       #
+#       # @example With baseline for gradual adoption
+#       #   expect(violations).to zen_empty(baseline: ['LegacyController'])
+#       def zen_empty(custom_message = nil, allowlist: nil, baseline: nil); end
+#     end
+#   end
 RSpec::Matchers.define :zen_empty do |custom_message=nil, allowlist: nil, baseline: nil|
-  include Rubyzen::Matchers::MatcherHelpers
+  include Rubyzen::ExpectationHelpers
 
   match do |subject_collection|
     options = custom_message.is_a?(Hash) ? custom_message : {}

data/lib/rubyzen/matchers/zen_false_matcher.rb

@@ -1,18 +1,26 @@
-# Custom RSpec matcher that asserts a block returns false for every item in a collection.
-#
-# Supports +allowlist:+ and +baseline:+ for gradual adoption, matching items
-# where the block returns true against exception lists.
-#
-# @example Ensure no methods have more than 5 parameters
-#   expect(methods).to zen_false { |m| m.parameters.size > 5 }
-#
-# @example With a custom failure message
-#   expect(controllers.all_methods.call_sites).to zen_false("Controllers must not call .where directly") { |cs| cs.name == 'where' }
-#
-# @example With a baseline for gradual adoption
-#   expect(classes).to zen_false(baseline: ['LegacyModel']) { |k| k.lines_of_code > 200 }
+# @!parse
+#   module Rubyzen
+#     module Matchers
+#       # Asserts that a block returns false for every item in a collection.
+#       #
+#       # Supports +allowlist:+ and +baseline:+ for gradual adoption, matching items
+#       # where the block returns true against exception lists.
+#       #
+#       # @param custom_message [String, nil] optional 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
+#       #
+#       # @example Ensure no methods have more than 5 parameters
+#       #   expect(methods).to zen_false { |m| m.parameters.size > 5 }
+#       #
+#       # @example With a baseline for gradual adoption
+#       #   expect(classes).to zen_false(baseline: ['LegacyModel']) { |k| k.lines_of_code > 200 }
+#       def zen_false(custom_message = nil, allowlist: nil, baseline: nil, &block); end
+#     end
+#   end
 RSpec::Matchers.define :zen_false do |custom_message=nil, allowlist: nil, baseline: nil|
-  include Rubyzen::Matchers::MatcherHelpers
+  include Rubyzen::ExpectationHelpers
 
   match do |subject_collection|
     options = custom_message.is_a?(Hash) ? custom_message : {}

data/lib/rubyzen/matchers/zen_true_matcher.rb

@@ -1,12 +1,23 @@
-# Custom RSpec matcher that asserts a block returns true for every item in a collection.
-#
-# @example Ensure all methods have parameters
-#   expect(methods).to zen_true { |m| m.parameters? }
-#
-# @example With a custom failure message
-#   expect(services).to zen_true("All services must inherit from BaseService") { |s| s.superclass_name == 'BaseService' }
+# @!parse
+#   module Rubyzen
+#     module Matchers
+#       # Asserts that a block returns true for every item in a collection.
+#       #
+#       # @param custom_message [String, nil] optional 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
+#       #
+#       # @example Ensure all methods have parameters
+#       #   expect(methods).to zen_true { |m| m.parameters? }
+#       #
+#       # @example With a custom failure message
+#       #   expect(services).to zen_true("All services must inherit from BaseService") { |s| s.superclass_name == 'BaseService' }
+#       def zen_true(custom_message = nil, allowlist: nil, baseline: nil, &block); end
+#     end
+#   end
 RSpec::Matchers.define :zen_true do |custom_message=nil, allowlist: nil, baseline: nil|
-  include Rubyzen::Matchers::MatcherHelpers
+  include Rubyzen::ExpectationHelpers
 
   match do |subject_collection|
     options = custom_message.is_a?(Hash) ? custom_message : {}

data/lib/rubyzen/minitest.rb

@@ -0,0 +1,33 @@
+# Minitest entry point for Rubyzen.
+#
+# Loads the framework-agnostic core plus the Minitest assertions.
+# Require it from your test/test_helper.rb:
+#
+#   # Gemfile
+#   group :test do
+#     gem 'rubyzen-lint'
+#     gem 'minitest'
+#   end
+#
+#   # test/test_helper.rb
+#   require 'rubyzen/minitest'
+#
+# The assertions (+assert_zen_empty+, +assert_zen_true+, +assert_zen_false+) are
+# mixed into +Minitest::Assertions+, so they are available in every Minitest test
+# class and spec-style block automatically.
+require_relative 'core'
+
+begin
+  require 'minitest'
+rescue LoadError
+  raise LoadError, "Rubyzen's Minitest assertions require the 'minitest' gem. " \
+                   "Add `gem 'minitest'` to your Gemfile, or use the RSpec matchers via `require 'rubyzen/rspec'`."
+end
+
+require_relative 'assertions/zen_assertions'
+
+# Call +include+ via +send+ so YARD's static parser doesn't try to document a
+# mixin into the external Minitest::Assertions namespace (the constant only
+# exists at runtime, after +require 'minitest'+, so YARD would warn). +include+
+# is public on Module, so this is behaviourally identical to a plain call.
+Minitest::Assertions.send(:include, Rubyzen::Assertions)

data/lib/rubyzen/parsers/a_s_t_parser.rb

@@ -1,6 +1,7 @@
 require 'rubocop-ast'
 
 module Rubyzen
+  # Ruby source file parsing utilities.
   module Parsers
     # Singleton parser that converts Ruby source files into Rubyzen declarations
     # using RuboCop's AST processing. Results are cached via {Cache::ParseCache}.

data/lib/rubyzen/providers/blocks_provider.rb

@@ -1,6 +1,7 @@
 module Rubyzen
+  # Mixins that add capabilities (call sites, blocks, attributes, etc.) to declarations.
   module Providers
-    # Provides access to block expressions (do..end / {..}) within a declaration.
+    # Provides access to block expressions (do..end and brace blocks) within a declaration.
     module BlocksProvider
       # @return [Rubyzen::Collections::BlocksCollection] collection of block declarations
       def blocks

data/lib/rubyzen/rspec.rb

@@ -0,0 +1,29 @@
+# RSpec entry point for Rubyzen.
+#
+# Loads the framework-agnostic core plus the RSpec matchers. 
+# Require it from your spec/spec_helper.rb:
+#
+#   # Gemfile
+#   group :test do
+#     gem 'rubyzen-lint'
+#     gem 'rspec' # or rspec-rails
+#   end
+#
+#   # spec/spec_helper.rb
+#   require 'rubyzen/rspec'
+#
+# Every RSpec project should already have the `rspec` gem.
+# If it is missing we raise an error.
+require_relative 'core'
+
+begin
+  require 'rspec'
+rescue LoadError
+  raise LoadError, "Rubyzen's RSpec matchers require the 'rspec' gem. " \
+                   "Add `gem 'rspec'` to your Gemfile, or use the Minitest assertions via `require 'rubyzen/minitest'`."
+end
+
+require_relative 'expectation_helpers'
+require_relative 'matchers/zen_empty_matcher'
+require_relative 'matchers/zen_true_matcher'
+require_relative 'matchers/zen_false_matcher'

data/lib/rubyzen/version.rb

@@ -1,3 +1,4 @@
 module Rubyzen
-  VERSION = '0.1.0'
+  # @return [String] the current gem version
+  VERSION = '0.2.0'
 end

data/lib/rubyzen.rb

@@ -1,98 +1,11 @@
-require 'rubocop-ast'
-require 'rspec'
-require 'zeitwerk'
-
-loader = Zeitwerk::Loader.for_gem
-loader.ignore("#{__dir__}/rubyzen/matchers")
-loader.ignore("#{__dir__}/rubyzen/rspec")
-loader.ignore("#{__dir__}/rubyzen/lint.rb")
-loader.ignore("#{__dir__}/rubyzen-lint.rb")
-loader.setup
-
-require_relative 'rubyzen/matchers/matcher_helpers'
-require_relative 'rubyzen/matchers/zen_empty_matcher'
-require_relative 'rubyzen/matchers/zen_true_matcher'
-require_relative 'rubyzen/matchers/zen_false_matcher'
-
-# Rubyzen is a Ruby architectural linter that lets you write lint rules as RSpec tests.
-# It wraps RuboCop AST to provide a high-level, easy-to-use API for enforcing architectural
-# rules across a codebase.
+# Rubyzen entry point — loads the framework-agnostic core only.
 #
-# @example Basic usage
-#   project = Rubyzen::Project.new(["/path/to/src", "/path/to/spec"])
-#   controllers = project.files.with_paths("controllers/").classes
+# `require 'rubyzen'` gives you the parsing/analysis API (Rubyzen::Project,
+# declarations, collections) without any test framework attached. To write lint
+# rules, require the adapter for your test framework instead:
 #
-#   # Assert controllers don't call ActiveRecord directly
-#   expect(controllers.all_methods.call_sites.with_name("where")).to zen_empty
+#   require 'rubyzen/rspec'      # RSpec matchers:     zen_empty / zen_true / zen_false
+#   require 'rubyzen/minitest'   # Minitest assertions: assert_zen_empty / _true / _false
 #
-# @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
+# Each adapter loads this core automatically
+require_relative 'rubyzen/core'

data/rubyzen-lint.gemspec

@@ -4,7 +4,7 @@ Gem::Specification.new do |spec|
   spec.name          = 'rubyzen-lint'
   spec.version       = Rubyzen::VERSION
   spec.authors       = ['Perry Street Software']
-  spec.summary       = 'Architectural linter for Ruby — write lint rules as RSpec tests'
+  spec.summary       = 'Architectural linter for Ruby — write lint rules as unit tests'
   spec.description   = 'Rubyzen is a modern linter for Ruby that allows you to write architectural ' \
                        'lint rules as unit tests. In the era of AI-generated code, it provides your ' \
                        'team with deterministic guardrails to keep your codebase clean, maintainable, ' \
@@ -14,15 +14,20 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 3.1'
 
-  spec.files = Dir.glob(%w[lib/**/*.rb rubyzen-lint.gemspec LICENSE README.md])
+  spec.files = Dir.glob(%w[lib/**/*.rb rubyzen-lint.gemspec LICENSE README.md CHANGELOG.md])
   spec.require_paths = ['lib']
 
   spec.add_dependency 'rubocop-ast', '~> 1.26'
   spec.add_dependency 'zeitwerk', '~> 2.6'
-  spec.add_dependency 'rspec', '~> 3.12'
+
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'minitest', '>= 5.0', '< 7.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
 
   spec.metadata = {
     'source_code_uri' => 'https://github.com/perrystreetsoftware/Rubyzen',
-    'bug_tracker_uri' => 'https://github.com/perrystreetsoftware/Rubyzen/issues'
+    'bug_tracker_uri' => 'https://github.com/perrystreetsoftware/Rubyzen/issues',
+    'documentation_uri' => 'https://perrystreetsoftware.github.io/Rubyzen',
+    'changelog_uri' => 'https://github.com/perrystreetsoftware/Rubyzen/blob/main/CHANGELOG.md'
   }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubyzen-lint
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Perry Street Software
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-15 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop-ast
@@ -45,13 +45,47 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
 description: Rubyzen is a modern linter for Ruby that allows you to write architectural
   lint rules as unit tests. In the era of AI-generated code, it provides your team
   with deterministic guardrails to keep your codebase clean, maintainable, and consistent
@@ -61,10 +95,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/rubyzen-lint.rb
 - lib/rubyzen.rb
+- lib/rubyzen/assertions/assert_zen_empty.rb
+- lib/rubyzen/assertions/assert_zen_false.rb
+- lib/rubyzen/assertions/assert_zen_true.rb
+- lib/rubyzen/assertions/zen_assertions.rb
 - lib/rubyzen/cache/parse_cache.rb
 - lib/rubyzen/collections/attributes_collection.rb
 - lib/rubyzen/collections/base_collection.rb
@@ -81,6 +120,7 @@ files:
 - lib/rubyzen/collections/raises_collection.rb
 - lib/rubyzen/collections/requires_collection.rb
 - lib/rubyzen/collections/rescues_collection.rb
+- lib/rubyzen/core.rb
 - lib/rubyzen/declarations/attribute_declaration.rb
 - lib/rubyzen/declarations/block_declaration.rb
 - lib/rubyzen/declarations/call_site_declaration.rb
@@ -95,11 +135,12 @@ files:
 - lib/rubyzen/declarations/raise_declaration.rb
 - lib/rubyzen/declarations/require_declaration.rb
 - lib/rubyzen/declarations/rescue_declaration.rb
+- lib/rubyzen/expectation_helpers.rb
 - lib/rubyzen/lint.rb
-- lib/rubyzen/matchers/matcher_helpers.rb
 - lib/rubyzen/matchers/zen_empty_matcher.rb
 - lib/rubyzen/matchers/zen_false_matcher.rb
 - lib/rubyzen/matchers/zen_true_matcher.rb
+- lib/rubyzen/minitest.rb
 - lib/rubyzen/parsers/a_s_t_parser.rb
 - lib/rubyzen/project.rb
 - lib/rubyzen/providers/attributes_provider.rb
@@ -118,6 +159,7 @@ files:
 - lib/rubyzen/providers/rescues_provider.rb
 - lib/rubyzen/providers/source_code_provider.rb
 - lib/rubyzen/providers/visibility_provider.rb
+- lib/rubyzen/rspec.rb
 - lib/rubyzen/version.rb
 - rubyzen-lint.gemspec
 homepage: https://github.com/perrystreetsoftware/Rubyzen
@@ -126,6 +168,8 @@ licenses:
 metadata:
   source_code_uri: https://github.com/perrystreetsoftware/Rubyzen
   bug_tracker_uri: https://github.com/perrystreetsoftware/Rubyzen/issues
+  documentation_uri: https://perrystreetsoftware.github.io/Rubyzen
+  changelog_uri: https://github.com/perrystreetsoftware/Rubyzen/blob/main/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -144,5 +188,5 @@ requirements: []
 rubygems_version: 3.0.3.1
 signing_key: 
 specification_version: 4
-summary: Architectural linter for Ruby — write lint rules as RSpec tests
+summary: Architectural linter for Ruby — write lint rules as unit tests
 test_files: []

data/lib/rubyzen/matchers/matcher_helpers.rb

@@ -1,176 +0,0 @@
-module Rubyzen
-  module Matchers
-    # Shared helper methods used by Rubyzen's custom RSpec matchers.
-    #
-    # Provides utilities for normalizing exception lists, extracting item
-    # details, matching items against allowlist/baseline entries, and
-    # formatting failure messages.
-    module MatcherHelpers
-      # 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
-
-      def self.included(base)
-        base.define_method(:message_for_failure) do |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
-  end
-end