rubyzen-lint 0.1.0

data/lib/rubyzen/providers/collection_filter_provider.rb

@@ -0,0 +1,64 @@
+module Rubyzen
+  module Providers
+    # Provides name-based filtering methods for collections.
+    module CollectionFilterProvider
+      # @param name [String] the exact name to match
+      # @return [self] filtered collection containing only items with the given name
+      def with_name(name)
+        filter { |item| item.name == name }
+      end
+
+      # @param suffix [String] the suffix to match against item names
+      # @return [self] filtered collection of items whose names end with the suffix
+      def with_name_ending_with(suffix)
+        filter { |item| item.name&.end_with?(suffix) }
+      end
+
+      # @param prefix [String] the prefix to match against item names
+      # @return [self] filtered collection of items whose names start with the prefix
+      def with_name_starting_with(prefix)
+        filter { |item| item.name&.start_with?(prefix) }
+      end
+
+      # @param substring [String] the substring to search for in item names
+      # @param case_sensitive [Boolean] whether the match is case-sensitive (default: true)
+      # @return [self] filtered collection of items whose names contain the substring
+      def with_name_including(substring, case_sensitive: true)
+        if case_sensitive
+          filter { |item| item.name&.include?(substring) }
+        else
+          filter { |item| item.name&.downcase&.include?(substring.downcase) }
+        end
+      end
+
+      # @param names [Array<String>] names to exclude
+      # @return [self] filtered collection excluding items with any of the given names
+      def without_name(*names)
+        filter { |item| !names.include?(item.name) }
+      end
+
+      # @param suffix [String] the suffix to exclude
+      # @return [self] filtered collection excluding items whose names end with the suffix
+      def without_name_ending_with(suffix)
+        filter { |item| !item.name&.end_with?(suffix) }
+      end
+
+      # @param prefix [String] the prefix to exclude
+      # @return [self] filtered collection excluding items whose names start with the prefix
+      def without_name_starting_with(prefix)
+        filter { |item| !item.name&.start_with?(prefix) }
+      end
+
+      # @param substring [String] the substring to exclude
+      # @param case_sensitive [Boolean] whether the match is case-sensitive (default: true)
+      # @return [self] filtered collection excluding items whose names contain the substring
+      def without_name_including(substring, case_sensitive: true)
+        if case_sensitive
+          filter { |item| !item.name&.include?(substring) }
+        else
+          filter { |item| !item.name&.downcase&.include?(substring.downcase) }
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/constants_provider.rb

@@ -0,0 +1,17 @@
+module Rubyzen
+  module Providers
+    # Provides access to constant references and assignments within a declaration.
+    module ConstantsProvider
+      # @return [Rubyzen::Collections::ConstantsCollection] collection of constant declarations
+      def constants
+        constant_nodes = node.each_descendant(:casgn, :const)
+
+        Collections::ConstantsCollection.new(
+          constant_nodes.map do |const_node|
+            Declarations::ConstantDeclaration.new(const_node, self)
+          end
+        )
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/file_path_provider.rb

@@ -0,0 +1,26 @@
+module Rubyzen
+  module Providers
+    # Provides access to the file path of a declaration by traversing parent declarations.
+    module FilePathProvider
+      # @return [String, nil] the file path containing this declaration
+      def file_path
+        file_path_recursive(self)
+      end
+
+      private
+
+      def file_path_recursive(declaration)
+        return if declaration.nil?
+        return declaration.path if declaration.respond_to?(:path)
+
+        if declaration.respond_to?(:file_declaration)
+          return file_path_recursive(declaration.file_declaration)
+        elsif declaration.respond_to?(:parent)
+          return file_path_recursive(declaration.parent)
+        elsif declaration.respond_to?(:parent_class)
+          return file_path_recursive(declaration.parent_class)
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/if_statements_provider.rb

@@ -0,0 +1,11 @@
+module Rubyzen
+  module Providers
+    # Provides access to if/unless conditional statements within a declaration.
+    module IfStatementsProvider
+      # @return [Rubyzen::Collections::DeclarationCollection] collection of if statement declarations
+      def if_statements
+        Rubyzen::Collections::DeclarationCollection.new(node.each_node(:if).map { |if_node| Rubyzen::Declarations::IfStatementDeclaration.new(if_node, self) })
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/line_number_provider.rb

@@ -0,0 +1,11 @@
+module Rubyzen
+  module Providers
+    # Provides access to the starting line number of a declaration in its source file.
+    module LineNumberProvider
+      # @return [Integer] the line number where this declaration begins
+      def line
+        node.loc.expression.line
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/lines_of_code_provider.rb

@@ -0,0 +1,11 @@
+module Rubyzen
+  module Providers
+    # Provides the number of lines of code a declaration spans.
+    module LinesOfCodeProvider
+      # @return [Integer] the total number of source lines in this declaration
+      def lines_of_code
+        node.loc.expression.source.split("\n").size
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/macros_provider.rb

@@ -0,0 +1,17 @@
+module Rubyzen
+  module Providers
+    # Provides access to macro-style method calls (e.g., validates, has_many) within a declaration.
+    module MacrosProvider
+      # @return [Rubyzen::Collections::MacrosCollection] collection of macro declarations
+      def macros
+        macros_nodes = node.each_descendant(:send).select(&:macro?)
+
+        macros_declarations = macros_nodes.map do |macro_node|
+          Rubyzen::Declarations::MacroDeclaration.new(macro_node, self)
+        end
+
+        Rubyzen::Collections::MacrosCollection.new(macros_declarations)
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/raises_provider.rb

@@ -0,0 +1,19 @@
+module Rubyzen
+  module Providers
+    # Provides access to raise statements within a declaration.
+    module RaisesProvider
+      # @return [Rubyzen::Collections::RaisesCollection] collection of raise declarations
+      def raises
+        raise_nodes = node.each_descendant(:send).select do |send_node|
+          send_node.method_name == :raise
+        end
+
+        raise_declarations = raise_nodes.map do |raise_node|
+          Rubyzen::Declarations::RaiseDeclaration.new(raise_node, self)
+        end
+
+        Rubyzen::Collections::RaisesCollection.new(raise_declarations)
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/requires_provider.rb

@@ -0,0 +1,19 @@
+module Rubyzen
+  module Providers
+    # Provides access to require, require_relative, and load statements within a declaration.
+    module RequiresProvider
+      # @return [Rubyzen::Collections::RequiresCollection] collection of require declarations
+      def requires
+        require_nodes = node.each_descendant(:send).select do |send_node|
+          %w[require require_relative load].include?(send_node.method_name.to_s)
+        end
+
+        require_declarations = require_nodes.map do |require_node|
+          Rubyzen::Declarations::RequireDeclaration.new(require_node, self)
+        end
+
+        Rubyzen::Collections::RequiresCollection.new(require_declarations)
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/rescues_provider.rb

@@ -0,0 +1,17 @@
+module Rubyzen
+  module Providers
+    # Provides access to rescue clauses within a declaration.
+    module RescuesProvider
+      # @return [Rubyzen::Collections::RescuesCollection] collection of rescue declarations
+      def rescues
+        rescue_nodes = node.each_descendant(:resbody)
+
+        rescue_declarations = rescue_nodes.map do |rescue_node|
+          Rubyzen::Declarations::RescueDeclaration.new(rescue_node, self)
+        end
+
+        Rubyzen::Collections::RescuesCollection.new(rescue_declarations)
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/source_code_provider.rb

@@ -0,0 +1,11 @@
+module Rubyzen
+  module Providers
+    # Provides access to the raw source code text of a declaration.
+    module SourceCodeProvider
+      # @return [String] the source code of this declaration
+      def source_code
+        node.loc.expression.source
+      end
+    end
+  end
+end

data/lib/rubyzen/providers/visibility_provider.rb

@@ -0,0 +1,49 @@
+module Rubyzen
+  module Providers
+    # Provides method visibility detection (public, private, protected).
+    module VisibilityProvider
+      # @return [Symbol] the visibility of this declaration (:public, :private, or :protected)
+      def visibility
+        determine_visibility
+      end
+
+      # @return [Boolean] true if this declaration is private
+      def private?
+        visibility == :private
+      end
+
+      # @return [Boolean] true if this declaration is protected
+      def protected?
+        visibility == :protected
+      end
+
+      # @return [Boolean] true if this declaration is public
+      def public?
+        visibility == :public
+      end
+
+      private
+
+      def determine_visibility
+        return :public unless parent_class
+
+        visibility_nodes = parent_class.node.each_descendant(:send).select do |send_node|
+          send_node.method_name.to_s.match?(/^(private|protected|public)$/) &&
+          send_node.arguments.empty?
+        end
+
+        declaration_line = node.loc.expression.line
+
+        applicable_visibility = visibility_nodes
+          .select { |v_node| v_node.loc.expression.line < declaration_line }
+          .max_by { |v_node| v_node.loc.expression.line }
+
+        if applicable_visibility
+          applicable_visibility.method_name.to_sym
+        else
+          :public
+        end
+      end
+    end
+  end
+end

data/lib/rubyzen/version.rb

@@ -0,0 +1,3 @@
+module Rubyzen
+  VERSION = '0.1.0'
+end

data/lib/rubyzen-lint.rb

@@ -0,0 +1 @@
+require_relative 'rubyzen'

data/lib/rubyzen.rb

@@ -0,0 +1,98 @@
+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.
+#
+# @example Basic usage
+#   project = Rubyzen::Project.new(["/path/to/src", "/path/to/spec"])
+#   controllers = project.files.with_paths("controllers/").classes
+#
+#   # Assert controllers don't call ActiveRecord directly
+#   expect(controllers.all_methods.call_sites.with_name("where")).to zen_empty
+#
+# @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/rubyzen-lint.gemspec

@@ -0,0 +1,28 @@
+require_relative 'lib/rubyzen/version'
+
+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.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 as it grows.'
+  spec.homepage      = 'https://github.com/perrystreetsoftware/Rubyzen'
+  spec.license       = 'Apache-2.0'
+
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.files = Dir.glob(%w[lib/**/*.rb rubyzen-lint.gemspec LICENSE README.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.metadata = {
+    'source_code_uri' => 'https://github.com/perrystreetsoftware/Rubyzen',
+    'bug_tracker_uri' => 'https://github.com/perrystreetsoftware/Rubyzen/issues'
+  }
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: rubyzen-lint
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Perry Street Software
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop-ast
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.26'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+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
+  as it grows.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rubyzen-lint.rb
+- lib/rubyzen.rb
+- lib/rubyzen/cache/parse_cache.rb
+- lib/rubyzen/collections/attributes_collection.rb
+- lib/rubyzen/collections/base_collection.rb
+- lib/rubyzen/collections/blocks_collection.rb
+- lib/rubyzen/collections/call_site_collection.rb
+- lib/rubyzen/collections/classes_collection.rb
+- lib/rubyzen/collections/constants_collection.rb
+- lib/rubyzen/collections/declaration_collection.rb
+- lib/rubyzen/collections/file_collection.rb
+- lib/rubyzen/collections/macros_collection.rb
+- lib/rubyzen/collections/methods_collection.rb
+- lib/rubyzen/collections/modules_collection.rb
+- lib/rubyzen/collections/parameters_collection.rb
+- lib/rubyzen/collections/raises_collection.rb
+- lib/rubyzen/collections/requires_collection.rb
+- lib/rubyzen/collections/rescues_collection.rb
+- lib/rubyzen/declarations/attribute_declaration.rb
+- lib/rubyzen/declarations/block_declaration.rb
+- lib/rubyzen/declarations/call_site_declaration.rb
+- lib/rubyzen/declarations/class_declaration.rb
+- lib/rubyzen/declarations/constant_declaration.rb
+- lib/rubyzen/declarations/file_declaration.rb
+- lib/rubyzen/declarations/if_statement_declaration.rb
+- lib/rubyzen/declarations/macro_declaration.rb
+- lib/rubyzen/declarations/method_declaration.rb
+- lib/rubyzen/declarations/module_declaration.rb
+- lib/rubyzen/declarations/parameter_declaration.rb
+- lib/rubyzen/declarations/raise_declaration.rb
+- lib/rubyzen/declarations/require_declaration.rb
+- lib/rubyzen/declarations/rescue_declaration.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/parsers/a_s_t_parser.rb
+- lib/rubyzen/project.rb
+- lib/rubyzen/providers/attributes_provider.rb
+- lib/rubyzen/providers/blocks_provider.rb
+- lib/rubyzen/providers/call_site_provider.rb
+- lib/rubyzen/providers/class_name_provider.rb
+- lib/rubyzen/providers/collection_filter_provider.rb
+- lib/rubyzen/providers/constants_provider.rb
+- lib/rubyzen/providers/file_path_provider.rb
+- lib/rubyzen/providers/if_statements_provider.rb
+- lib/rubyzen/providers/line_number_provider.rb
+- lib/rubyzen/providers/lines_of_code_provider.rb
+- lib/rubyzen/providers/macros_provider.rb
+- lib/rubyzen/providers/raises_provider.rb
+- lib/rubyzen/providers/requires_provider.rb
+- lib/rubyzen/providers/rescues_provider.rb
+- lib/rubyzen/providers/source_code_provider.rb
+- lib/rubyzen/providers/visibility_provider.rb
+- lib/rubyzen/version.rb
+- rubyzen-lint.gemspec
+homepage: https://github.com/perrystreetsoftware/Rubyzen
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/perrystreetsoftware/Rubyzen
+  bug_tracker_uri: https://github.com/perrystreetsoftware/Rubyzen/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Architectural linter for Ruby — write lint rules as RSpec tests
+test_files: []