archspec 0.3.0 → 0.4.0

data/lib/archspec/rules/protocol_rules.rb

@@ -2,16 +2,23 @@
 
 module ArchSpec
   module Rules
+    # Backs ArchSpec::DSL::ComponentProxy#cannot_call. Flags calls to the named
+    # methods, optionally only bare implicit-+self+ calls.
     class CannotCallRule
-      attr_reader :source, :method_names
+      attr_reader :source, :method_names, :receiver
+
+      def initialize(source, methods, receiver: :any)
+        unless %i[any none].include?(receiver)
+          raise Error, "cannot_call receiver: must be :any or :none, got #{receiver.inspect}"
+        end
 
-      def initialize(source, methods)
         @source = source.to_sym
         @method_names = Array(methods).flatten.map(&:to_sym)
+        @receiver = receiver
       end
 
       def merge_key
-        [self.class, source]
+        [self.class, source, receiver]
       end
 
       def merge!(other)
@@ -27,7 +34,9 @@ module ArchSpec
         graph.edges.filter_map do |edge|
           next unless edge.type == :calls_named_method
           next unless method_names.include?(edge.to.to_sym)
+          next if receiver == :none && edge.receiver != :none
           next unless graph.component_names_for_path(edge.from_path).include?(source)
+          next if own_method_call?(graph, edge)
 
           Diagnostic.new(
             rule: id,
@@ -37,8 +46,22 @@ module ArchSpec
           )
         end
       end
+
+      private
+
+      # A receiverless call to a method the class itself defines (directly,
+      # inherited, or via attr_*/delegate) is a call to its own API.
+      def own_method_call?(graph, edge)
+        return false unless edge.receiver == :none && edge.from_constant
+
+        methods, = graph.effective_instance_methods(edge.from_constant)
+        methods.include?(edge.to.to_sym)
+      end
     end
 
+    # Backs ArchSpec::DSL::ComponentProxy#must_implement. Flags classes in the
+    # component that do not implement the method, counting inherited and
+    # mixed-in methods.
     class MustImplementRule
       attr_reader :source, :method_name
 
@@ -57,13 +80,15 @@ module ArchSpec
 
       def evaluate(graph)
         constants_for(graph).filter_map do |constant|
-          next if constant.instance_methods.include?(method_name)
+          methods, unresolved = graph.effective_instance_methods(constant.name)
+          next if methods.include?(method_name)
 
           Diagnostic.new(
             rule: id,
             message: "#{constant.name} must implement ##{method_name}",
             location: constant.location,
-            evidence: "#{constant.name} methods: #{constant.instance_methods.to_a.sort.join(', ')}"
+            evidence: ProtocolEvidence.for(constant, methods, unresolved),
+            confidence: unresolved.empty? ? :high : :medium
           )
         end
       end
@@ -71,12 +96,12 @@ module ArchSpec
       private
 
       def constants_for(graph)
-        graph.components.fetch(source).constants.flat_map { |name| graph.constants_named(name) }.select(&:class?)
-      rescue KeyError
-        []
+        ProtocolEvidence.constants_for(graph, source)
       end
     end
 
+    # Backs ArchSpec::DSL::ComponentProxy#must_implement_one_of. Flags classes
+    # that implement none of the named methods.
     class MustImplementOneOfRule
       attr_reader :source, :method_names
 
@@ -100,13 +125,15 @@ module ArchSpec
 
       def evaluate(graph)
         constants_for(graph).filter_map do |constant|
-          next if method_names.any? { |method_name| constant.instance_methods.include?(method_name) }
+          methods, unresolved = graph.effective_instance_methods(constant.name)
+          next if method_names.any? { |method_name| methods.include?(method_name) }
 
           Diagnostic.new(
             rule: id,
             message: "#{constant.name} must implement one of #{method_names.map { |name| "##{name}" }.join(', ')}",
             location: constant.location,
-            evidence: "#{constant.name} methods: #{constant.instance_methods.to_a.sort.join(', ')}"
+            evidence: ProtocolEvidence.for(constant, methods, unresolved),
+            confidence: unresolved.empty? ? :high : :medium
           )
         end
       end
@@ -114,12 +141,32 @@ module ArchSpec
       private
 
       def constants_for(graph)
-        graph.components.fetch(source).constants.flat_map { |name| graph.constants_named(name) }.select(&:class?)
-      rescue KeyError
-        []
+        ProtocolEvidence.constants_for(graph, source)
+      end
+    end
+
+    # Builds the shared "methods: ..." evidence string for the protocol rules
+    # and resolves the classes in a component. Internal helper.
+    module ProtocolEvidence
+      module_function
+
+      def constants_for(graph, source)
+        component = graph.components[source]
+        return [] unless component
+
+        component.constants.flat_map { |name| graph.constants_named(name) }.select(&:class?).uniq(&:name)
+      end
+
+      def for(constant, methods, unresolved)
+        evidence = "#{constant.name} methods: #{methods.empty? ? '(none)' : methods.to_a.sort.join(', ')}"
+        return evidence if unresolved.empty?
+
+        "#{evidence}; unresolved ancestors: #{unresolved.to_a.sort.join(', ')}"
       end
     end
 
+    # Backs ArchSpec::DSL::ComponentProxy#cannot_define. Flags method
+    # definitions in the component matching the named methods.
     class CannotDefineMethodRule
       attr_reader :source, :method_names
 
@@ -155,6 +202,8 @@ module ArchSpec
       end
     end
 
+    # Backs ArchSpec::DSL::ComponentProxy#cannot_instantiate_and_invoke. Flags
+    # the one-shot <tt>Thing.new(...).call</tt> pattern.
     class CannotInstantiateAndInvokeRule
       attr_reader :source
 

data/lib/archspec/rules/zeitwerk_rule.rb

@@ -2,14 +2,28 @@
 
 module ArchSpec
   module Rules
+    # Backs ArchSpec::DSL::Context#verify_zeitwerk_names!. Flags files that do
+    # not define the constant their path implies under Zeitwerk.
     class ZeitwerkNamingRule
+      attr_reader :only
+
+      # only: globs restricting which files are checked. Default is every file
+      # ArchSpec can name, but lib autoloading is opt-in, so apps that require
+      # lib manually scope this to app/.
+      def initialize(only: nil)
+        @only = Array(only).flatten.compact.map(&:to_s)
+      end
+
       def id
         'zeitwerk.naming'
       end
 
       def evaluate(graph)
+        scoped_paths = scoped_paths(graph)
+
         graph.files.values.filter_map do |file|
           next unless file.expected_constant
+          next if scoped_paths && !scoped_paths.include?(file.path)
 
           defined = graph.constants_for_path(file.path).map(&:name)
           next if defined.include?(file.expected_constant)
@@ -22,6 +36,16 @@ module ArchSpec
           )
         end
       end
+
+      private
+
+      def scoped_paths(graph)
+        return nil if only.empty?
+
+        only.flat_map { |pattern| Dir.glob(File.absolute_path(pattern, graph.root)) }
+            .map { |path| File.expand_path(path) }
+            .to_set
+      end
     end
   end
 end

data/lib/archspec/{baseline.rb → todo.rb}

@@ -3,7 +3,11 @@
 require 'yaml'
 
 module ArchSpec
-  class Baseline
+  # A file of accepted existing violations. ArchSpec still checks the files
+  # these come from, but subtracts the recorded violations so you can adopt it
+  # in an existing app and burn the list down over time. Matched by
+  # ArchSpec::Diagnostic#fingerprint, so entries survive edits that shift lines.
+  class Todo
     def self.empty(root: nil)
       new(Set.new, root: root)
     end

data/lib/archspec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ArchSpec
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/archspec.rb

@@ -7,14 +7,16 @@ require_relative 'archspec/diagnostic'
 require_relative 'archspec/component_spec'
 require_relative 'archspec/model'
 require_relative 'archspec/definition'
-require_relative 'archspec/baseline'
+require_relative 'archspec/todo'
 require_relative 'archspec/dsl'
 require_relative 'archspec/analyzer'
 require_relative 'archspec/evaluator'
 require_relative 'archspec/architectures'
 require_relative 'archspec/presets'
 require_relative 'archspec/rules/component_rules'
+require_relative 'archspec/rules/concern_rules'
 require_relative 'archspec/rules/dependency_rules'
+require_relative 'archspec/rules/privacy_rule'
 require_relative 'archspec/rules/protocol_rules'
 require_relative 'archspec/rules/cycle_rule'
 require_relative 'archspec/rules/zeitwerk_rule'
@@ -22,12 +24,47 @@ require_relative 'archspec/formatters/text'
 require_relative 'archspec/formatters/json'
 require_relative 'archspec/cli'
 
+# ArchSpec turns your application's architecture into executable checks.
+#
+# You describe components, dependencies, and boundaries in an +Archspec.rb+
+# file written in the ArchSpec::DSL, then run <tt>archspec check</tt> to verify
+# every change. ArchSpec reads Ruby source with Prism and never boots the app.
+#
+# The DSL is the public API. An +Archspec.rb+ file is evaluated directly:
+#
+#   architecture :rails
+#
+#   component :services, in: "app/services/**/*.rb"
+#   services.cannot_call :render, :redirect_to, receiver: :none
+#
+# See ArchSpec::DSL::Context for the top-level DSL and
+# ArchSpec::DSL::ComponentProxy for per-component rules. See
+# ArchSpec::Architectures for the bundled architecture presets.
+#
+# You can also build a definition in plain Ruby with ArchSpec.define.
 module ArchSpec
+  # Raised for configuration and usage errors, such as an unknown architecture
+  # name or a malformed rule option.
   class Error < StandardError; end
 
   class << self
+    # The definition produced by the most recent ArchSpec.define call, or by
+    # evaluating an +Archspec.rb+ file. The CLI reads this after loading config.
     attr_accessor :last_definition
 
+    # Builds an architecture definition from a block of DSL calls.
+    #
+    #   ArchSpec.define do
+    #     component :models, in: "app/models/**/*.rb"
+    #     component :controllers, in: "app/controllers/**/*.rb"
+    #     models.cannot_use :controllers
+    #   end
+    #
+    # An +Archspec.rb+ file does not need this wrapper. Its top level is already
+    # the DSL, so bare +component+ and +architecture+ calls work directly. Use
+    # +define+ when constructing a definition from Ruby, such as in a test.
+    #
+    # Returns the ArchSpec::Definition, which is also stored as last_definition.
     def define(name = nil, &block)
       definition = Definition.new(name)
       definition.extend(DSL::Context)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: archspec
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Carmine Paolino
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-21 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -58,6 +58,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.6'
 description: A static architecture linter for Ruby and Rails. Declare your components,
   dependencies, and boundaries in one file, then check every change in CI. It reads
   source with Prism and never boots the app.
@@ -74,7 +88,6 @@ files:
 - lib/archspec.rb
 - lib/archspec/analyzer.rb
 - lib/archspec/architectures.rb
-- lib/archspec/baseline.rb
 - lib/archspec/cli.rb
 - lib/archspec/component_spec.rb
 - lib/archspec/definition.rb
@@ -86,11 +99,14 @@ files:
 - lib/archspec/model.rb
 - lib/archspec/presets.rb
 - lib/archspec/rules/component_rules.rb
+- lib/archspec/rules/concern_rules.rb
 - lib/archspec/rules/cycle_rule.rb
 - lib/archspec/rules/dependency_rules.rb
+- lib/archspec/rules/privacy_rule.rb
 - lib/archspec/rules/protocol_rules.rb
 - lib/archspec/rules/zeitwerk_rule.rb
 - lib/archspec/source_location.rb
+- lib/archspec/todo.rb
 - lib/archspec/value_object.rb
 - lib/archspec/version.rb
 homepage: https://archspecrb.dev