rubyzen-lint 0.1.0 → 0.3.0

data/lib/rubyzen/declarations/assignment_declaration.rb

@@ -0,0 +1,57 @@
+module Rubyzen
+  module Declarations
+    # Represents a local-variable assignment (an +lvasgn+ node), e.g. +x = Repos::Foo.new+.
+    #
+    # @example
+    #   assignment = method.assignments.first
+    #   assignment.name                 #=> "x"
+    #   assignment.value.constructor?   #=> true
+    #   assignment.value.constant_name  #=> "Repos::Foo"
+    #
+    # NOTE: Multiple assignment (+a, b = ...+) is only partially modelled. Each target is
+    # surfaced as its own AssignmentDeclaration with a correct {#name}, but {#value} is +nil+:
+    # in the AST the right-hand side lives on the enclosing +masgn+ node, not on the per-target
+    # +lvasgn+, and which value each variable receives generally cannot be known statically
+    # (e.g. +a, b = build_pair+). If a rule ever needs to trace destructured assignments, model
+    # the shared source explicitly (a +multiple_assignment?+ predicate + +shared_source+) rather
+    # than attributing the shared right-hand side to each variable's {#value}.
+    #
+    class AssignmentDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::SourceCodeProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [MethodDeclaration, BlockDeclaration]
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the +lvasgn+ node
+      # @param parent [MethodDeclaration, BlockDeclaration] the enclosing declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns the name of the assigned local variable.
+      #
+      # @return [String] e.g. +"x"+
+      def name
+        node.children.first.to_s
+      end
+
+      # Returns the assigned value as an expression, or +nil+ when there is no value
+      # node (e.g. the per-variable targets of a multiple assignment, +a, b = foo+).
+      #
+      # @return [ExpressionDeclaration, nil]
+      def value
+        value_node = node.children[1]
+        return nil if value_node.nil?
+
+        ExpressionDeclaration.new(value_node, self)
+      end
+    end
+  end
+end

data/lib/rubyzen/declarations/block_declaration.rb

@@ -17,6 +17,8 @@ module Rubyzen
       include Rubyzen::Providers::RaisesProvider
       include Rubyzen::Providers::SourceCodeProvider
       include Rubyzen::Providers::CallSiteProvider
+      include Rubyzen::Providers::ReturnsProvider
+      include Rubyzen::Providers::AssignmentsProvider
 
       # @return [RuboCop::AST::Node]
       attr_reader :node

data/lib/rubyzen/declarations/call_site_declaration.rb

@@ -13,6 +13,8 @@ module Rubyzen
       include Rubyzen::Providers::LineNumberProvider
       include Rubyzen::Providers::ClassNameProvider
       include Rubyzen::Providers::SourceCodeProvider
+      include Rubyzen::Providers::ArgumentsProvider
+      include Rubyzen::Providers::EnclosingBlocksProvider
 
       # @return [RuboCop::AST::Node]
       attr_reader :node
@@ -41,6 +43,18 @@ module Rubyzen
         node.receiver&.type == :const ? node.receiver.const_name : nil
       end
 
+      # Returns the receiver as an expression, or +nil+ for a receiverless call (e.g. +save+).
+      #
+      # Unlike {#receiver} (which returns a constant-name String), this models the receiver
+      # structurally — constant, constructor, or local variable.
+      #
+      # @return [Rubyzen::Declarations::ExpressionDeclaration, nil]
+      def receiver_expression
+        return nil if node.receiver.nil?
+
+        ExpressionDeclaration.new(node.receiver, self)
+      end
+
       # Returns the called method name.
       #
       # @return [String]

data/lib/rubyzen/declarations/expression_declaration.rb

@@ -0,0 +1,99 @@
+module Rubyzen
+  module Declarations
+    # Represents an arbitrary Ruby value-expression node — the value a method returns,
+    # the receiver of a call, a positional argument, the value of an assignment, and so on.
+    # Wraps any AST node and exposes its "kind" through predicates, so rules can ask
+    # structural questions without touching the raw AST.
+    #
+    # @example
+    #   expr = call_site.receiver_expression
+    #   expr.constructor?     #=> true   (for Repos::Foo.new.bar)
+    #   expr.constant_name    #=> "Repos::Foo"
+    #
+    class ExpressionDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::SourceCodeProvider
+
+      # @return [RuboCop::AST::Node]
+      attr_reader :node
+
+      # @return [Object] the declaration that produced this expression
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the value-expression node
+      # @param parent [Object] the declaration that produced this expression
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # Returns a short identifier: the constant, variable, or method name, falling
+      # back to the node type.
+      #
+      # @return [String]
+      def name
+        constant_name || local_variable_name || (method_call? ? method_name : node.type.to_s)
+      end
+
+      # @return [Boolean] true if the expression is a bare constant, e.g. +Repos::Foo+
+      def constant?
+        node.const_type?
+      end
+
+      # @return [Boolean] true if the expression references a local variable
+      def local_variable?
+        node.lvar_type?
+      end
+
+      # @return [Boolean] true if the expression is a method call (a +send+ node)
+      def method_call?
+        node.send_type?
+      end
+
+      # @return [Boolean] true if the expression is a constructor call, e.g. +Repos::Foo.new+
+      def constructor?
+        method_call? && node.method_name == :new
+      end
+
+      # @return [Boolean] true if the expression is a braced Hash literal with at least one pair
+      def hash_literal?
+        node.hash_type? && node.braces? && node.pairs.any?
+      end
+
+      # @return [Boolean] true if the expression is a symbol literal
+      def symbol?
+        node.sym_type?
+      end
+
+      # @return [Boolean] true if the expression is a string literal
+      def string?
+        node.str_type?
+      end
+
+      # Returns the constant name when the expression is a constant or constructs from one.
+      #
+      # @return [String, nil] e.g. +"Repos::Foo"+ for both +Repos::Foo+ and +Repos::Foo.new+
+      def constant_name
+        return node.const_name if constant?
+        return node.receiver.const_name if constructor? && node.receiver&.const_type?
+
+        nil
+      end
+
+      # Returns the called method name when the expression is a method call.
+      #
+      # @return [String, nil]
+      def method_name
+        node.method_name.to_s if method_call?
+      end
+
+      private
+
+      def local_variable_name
+        node.children.first.to_s if local_variable?
+      end
+    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/declarations/method_declaration.rb

@@ -21,6 +21,8 @@ module Rubyzen
       include Rubyzen::Providers::VisibilityProvider
       include Rubyzen::Providers::RescuesProvider
       include Rubyzen::Providers::RaisesProvider
+      include Rubyzen::Providers::ReturnsProvider
+      include Rubyzen::Providers::AssignmentsProvider
 
       # @return [RuboCop::AST::Node]
       attr_reader :node

data/lib/rubyzen/declarations/return_declaration.rb

@@ -0,0 +1,51 @@
+module Rubyzen
+  module Declarations
+    # Represents a single point at which a method or block yields a value: the
+    # implicit final expression of its body, or an explicit +return+ statement.
+    #
+    # @example
+    #   ret = method.returns.first
+    #   ret.explicit?                 #=> false
+    #   ret.expression.hash_literal?  #=> true
+    #
+    class ReturnDeclaration
+      include Rubyzen::Providers::FilePathProvider
+      include Rubyzen::Providers::LineNumberProvider
+      include Rubyzen::Providers::ClassNameProvider
+      include Rubyzen::Providers::SourceCodeProvider
+
+      # @return [RuboCop::AST::Node] the +return+ node, or the implicit final-expression node
+      attr_reader :node
+
+      # @return [MethodDeclaration, BlockDeclaration] the declaration that returns this value
+      attr_reader :parent
+
+      # @param node [RuboCop::AST::Node] the +return+ node, or the implicit final-expression node
+      # @param parent [MethodDeclaration, BlockDeclaration] the enclosing declaration
+      def initialize(node, parent)
+        @node = node
+        @parent = parent
+      end
+
+      # @return [Boolean] true if this is an explicit +return+ statement
+      def explicit?
+        node.return_type?
+      end
+
+      # @return [Boolean] true if this is the implicit final expression of the body
+      def implicit?
+        !explicit?
+      end
+
+      # The value expression being returned.
+      #
+      # @return [ExpressionDeclaration, nil] +nil+ for a bare +return+ with no value
+      def expression
+        value_node = explicit? ? node.children.first : node
+        return nil if value_node.nil?
+
+        ExpressionDeclaration.new(value_node, self)
+      end
+    end
+  end
+end

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

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/arguments_provider.rb

@@ -0,0 +1,15 @@
+module Rubyzen
+  module Providers
+    # Provides the arguments passed at a call site (or macro), as expressions.
+    module ArgumentsProvider
+      # @return [Rubyzen::Collections::ArgumentsCollection]
+      def arguments
+        Collections::ArgumentsCollection.new(
+          node.arguments.map do |argument_node|
+            Declarations::ExpressionDeclaration.new(argument_node, self)
+          end
+        )
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/assignments_provider.rb

@@ -0,0 +1,15 @@
+module Rubyzen
+  module Providers
+    # Provides local-variable assignments within a method or block.
+    module AssignmentsProvider
+      # @return [Rubyzen::Collections::AssignmentsCollection]
+      def assignments
+        Collections::AssignmentsCollection.new(
+          node.each_descendant(:lvasgn).map do |assignment_node|
+            Declarations::AssignmentDeclaration.new(assignment_node, self)
+          end
+        )
+      end
+    end
+  end
+end

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/providers/enclosing_blocks_provider.rb

@@ -0,0 +1,16 @@
+module Rubyzen
+  module Providers
+    # Provides the chain of blocks (do..end / { }) that lexically enclose a declaration,
+    # innermost first.
+    module EnclosingBlocksProvider
+      # @return [Rubyzen::Collections::BlocksCollection]
+      def enclosing_blocks
+        Collections::BlocksCollection.new(
+          node.each_ancestor(:block).map do |block_node|
+            Declarations::BlockDeclaration.new(block_node, parent)
+          end
+        )
+      end
+    end
+  end
+end