rubyzen-lint 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e0bc97dbd17202e4245c3c8c6b1d16f7fcdef64eab20ff96ab835113e21fbd9
-  data.tar.gz: 4fb9b3a30754c283823a44e208bd4de9ca0a035db5733df418ef1e70bd98172d
+  metadata.gz: 500e791179afc539a3b93a9300c55661567131776188a7ae484e5a2cffa3e12d
+  data.tar.gz: 1793077a6d2cfaa933c8a607cab96a3f84afe97e58f1a1926eaf6d60d2febed6
 SHA512:
-  metadata.gz: c23bf87e539bdda57d28a5b9f0b5fdbbee847a88ce93bf012c92a1c00eaf48fe1f5e2a99bea6a2e070749c2c74451821026f742a2e4e50e12c5395ed4295b870
-  data.tar.gz: 189a609b17528f6d0898defda84762df30273f4607f4e97882d21d255b111d719818adb9148d452c4ff5b9d7c29dbcc5c68749f36d0e96c86740451d096dc778
+  metadata.gz: fc076838beaafc1461c8c650e7a50e92ad0f4d32adc1c7f2ee15e9b47aeb9ac33a4742b2a98d47c23c2a73085f58b9cbbaa16d6a0d03526866472462bcb8f71f
+  data.tar.gz: b26b14d82f55b207b61601dd629154765488bf6154256738e11b1e96dfe14669109406513a12d4814c128e2cfbfc97b697c88ae68910d9d6c6c03a96c0d62164

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## [0.3.0]
+
+### Added
+
+- **`ExpressionDeclaration`** — a value-expression primitive wrapping any AST node, with
+  predicates (`constant?`, `local_variable?`, `method_call?`, `constructor?`, `hash_literal?`,
+  `symbol?`, `string?`) and accessors (`constant_name`, `method_name`, `name`).
+- **`#returns`** on `MethodDeclaration` and `BlockDeclaration` — the points at which it yields a
+  value (the implicit final expression plus explicit `return`s) as `ReturnDeclaration`s
+  (`#explicit?`, `#implicit?`, `#expression`), collected in a `ReturnsCollection` (`#expressions`).
+  `#return_expressions` remains as a shortcut for `returns.expressions` — an `ExpressionsCollection`
+  (`#hash_literals`, `#constants`). Both are bridged on `MethodsCollection` and `BlocksCollection`.
+- **`CallSiteDeclaration#arguments`** — the call's arguments as an `ArgumentsCollection`
+  (a subclass of `ExpressionsCollection`, so it keeps `#hash_literals`/`#constants`).
+- **`CallSiteDeclaration#receiver_expression`** — the receiver modeled structurally (constant /
+  constructor / local variable). `#receiver` (String const-name) is unchanged.
+- **`CallSiteDeclaration#enclosing_blocks`** — the chain of enclosing `do..end`/`{ }` blocks
+  (innermost first), as a `BlocksCollection`.
+- **`#assignments`** on `MethodDeclaration` and `BlockDeclaration` — local-variable assignments
+  (`AssignmentDeclaration`, with `#name` and `#value`) as an `AssignmentsCollection`. Bridged on
+  `MethodsCollection` and `BlocksCollection`.
+
+All additions are backward-compatible; no existing API changed.
+
+## [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/arguments_collection.rb

@@ -0,0 +1,16 @@
+module Rubyzen
+  module Collections
+    # Collection of {Rubyzen::Declarations::ExpressionDeclaration} representing the arguments
+    # passed at a call site.
+    #
+    # A specialization of {ExpressionsCollection}: arguments are value-expressions, so this
+    # inherits the value-expression filters (`#hash_literals`, `#constants`) and remains a
+    # drop-in `ExpressionsCollection`. It exists as a distinct type so argument-specific
+    # filters (e.g. positional vs keyword) can be added later without a breaking change.
+    #
+    # @example
+    #   call_site.arguments.first.constant_name
+    class ArgumentsCollection < ExpressionsCollection
+    end
+  end
+end

data/lib/rubyzen/collections/assignments_collection.rb

@@ -0,0 +1,11 @@
+module Rubyzen
+  module Collections
+    # Collection of {Rubyzen::Declarations::AssignmentDeclaration} (local-variable assignments).
+    #
+    # @example
+    #   method.assignments.with_name('user')
+    class AssignmentsCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+    end
+  end
+end

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/collections/blocks_collection.rb

@@ -22,6 +22,27 @@ module Rubyzen
         all_call_sites = flat_map(&:call_sites)
         CallSiteCollection.new(all_call_sites)
       end
+
+      # Returns all return points across every block.
+      #
+      # @return [ReturnsCollection]
+      def returns
+        ReturnsCollection.new(flat_map(&:returns))
+      end
+
+      # Returns all return expressions across every block.
+      #
+      # @return [ExpressionsCollection]
+      def return_expressions
+        returns.expressions
+      end
+
+      # Returns all local-variable assignments across every block.
+      #
+      # @return [AssignmentsCollection]
+      def assignments
+        AssignmentsCollection.new(flat_map(&:assignments))
+      end
     end
   end
 end

data/lib/rubyzen/collections/expressions_collection.rb

@@ -0,0 +1,27 @@
+module Rubyzen
+  module Collections
+    # Collection of {Rubyzen::Declarations::ExpressionDeclaration} — return values,
+    # call arguments, and other value-expressions.
+    #
+    # @example
+    #   method.return_expressions.hash_literals
+    class ExpressionsCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+
+      # Filters to only braced Hash-literal expressions.
+      #
+      # @return [ExpressionsCollection]
+      def hash_literals
+        filter(&:hash_literal?)
+      end
+
+      # Filters to only constant expressions, including constructors of a constant
+      # (e.g. both +Repos::Foo+ and +Repos::Foo.new+).
+      #
+      # @return [ExpressionsCollection]
+      def constants
+        filter(&:constant_name)
+      end
+    end
+  end
+end

data/lib/rubyzen/collections/methods_collection.rb

@@ -62,6 +62,35 @@ module Rubyzen
           end
         )
       end
+
+      # Returns all return points across every method.
+      #
+      # @return [ReturnsCollection]
+      def returns
+        ReturnsCollection.new(
+          flat_map do |method|
+            method.returns
+          end
+        )
+      end
+
+      # Returns all return expressions across every method.
+      #
+      # @return [ExpressionsCollection]
+      def return_expressions
+        returns.expressions
+      end
+
+      # Returns all local-variable assignments across every method.
+      #
+      # @return [AssignmentsCollection]
+      def assignments
+        AssignmentsCollection.new(
+          flat_map do |method|
+            method.assignments
+          end
+        )
+      end
     end
   end
 end

data/lib/rubyzen/collections/returns_collection.rb

@@ -0,0 +1,20 @@
+module Rubyzen
+  module Collections
+    # Collection of {Rubyzen::Declarations::ReturnDeclaration} — the points at which a
+    # method or block yields a value.
+    #
+    # @example
+    #   method.returns.expressions.hash_literals
+    class ReturnsCollection < BaseCollection
+      include Rubyzen::Providers::CollectionFilterProvider
+
+      # The value expressions of every return. Bare +return+s (which have no value)
+      # are omitted.
+      #
+      # @return [ExpressionsCollection]
+      def expressions
+        ExpressionsCollection.new(filter_map(&:expression))
+      end
+    end
+  end
+end

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