archspec 0.3.0 → 0.5.0

data/lib/archspec/rules/dependency_rules.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
 module ArchSpec
+  # The checks ArchSpec runs. Each rule responds to +id+ (its stable rule id,
+  # used in suppressions and the todo file) and <tt>evaluate(graph)</tt>, which
+  # returns ArchSpec::Diagnostic objects. You normally add rules through the
+  # ArchSpec::DSL rather than instantiating these directly, but you can pass a
+  # custom object of the same shape to ArchSpec::DSL::Context#rule.
   module Rules
+    # Base for the allow and forbid dependency rules. Merges repeated
+    # declarations for the same source component.
     class DependencyRule
       attr_reader :source, :targets
 
@@ -34,6 +41,8 @@ module ArchSpec
       end
     end
 
+    # Backs ArchSpec::DSL::ComponentProxy#can_only_use. Flags references from the
+    # source to any component outside its allowlist.
     class AllowDependenciesRule < DependencyRule
       def id
         'dependencies.allow'
@@ -55,6 +64,8 @@ module ArchSpec
       end
     end
 
+    # Backs ArchSpec::DSL::ComponentProxy#cannot_use. Flags references from the
+    # source to any of the named components.
     class ForbidDependenciesRule < DependencyRule
       def id
         'dependencies.forbid'
@@ -76,6 +87,60 @@ module ArchSpec
       end
     end
 
+    # Backs ArchSpec::DSL::ComponentProxy#can_only_be_used_by. The inverse of an
+    # allowlist: flags references to the component from any component that is not
+    # an approved consumer. Use it to protect a shared kernel.
+    class AllowedConsumersRule
+      attr_reader :source, :consumers
+
+      def initialize(source, consumers)
+        @source = source.to_sym
+        @consumers = Array(consumers).flatten.map(&:to_sym).to_set
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def merge!(other)
+        consumers.merge(other.consumers)
+        self
+      end
+
+      def id
+        'dependencies.consumers'
+      end
+
+      def evaluate(graph)
+        graph.dependency_edges.flat_map do |edge|
+          next [] unless graph.target_components_for(edge).include?(source)
+
+          offenders = graph.component_names_for_path(edge.from_path).reject do |component|
+            component == source || consumers.include?(component)
+          end
+
+          offenders.map do |offender|
+            Diagnostic.new(
+              rule: id,
+              message: message_for(offender),
+              location: edge.location,
+              evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge.to}"
+            )
+          end
+        end
+      end
+
+      private
+
+      def message_for(offender)
+        return "#{source} may not be used by #{offender}" if consumers.empty?
+
+        "#{source} may only be used by #{consumers.to_a.sort.join(', ')}, not #{offender}"
+      end
+    end
+
+    # Backs ArchSpec::DSL::ComponentProxy#cannot_reference_constants. Flags
+    # references to the named constants or anything nested under them.
     class CannotReferenceConstantsRule
       attr_reader :source, :constants
 

data/lib/archspec/rules/naming_rules.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module ArchSpec
+  module Rules
+    # Backs the +methods.matching(...)+ DSL. One rule pairs a selector (which
+    # methods it judges) with a constraint (what must hold of them). It judges a
+    # component's defined, public methods in the requested scope, or every such
+    # method in the project when +source+ is nil. Every finding is name-based and
+    # exact, so confidence is always +:high+.
+    class NamingRule
+      attr_reader :source, :selector, :scope, :except
+
+      def initialize(source:, selector:, constraint:, scope: :instance, except: [])
+        @source = source&.to_sym
+        @selector = selector
+        @constraint = constraint
+        @scope = scope
+        @except = Array(except).flatten.map(&:to_sym).to_set
+      end
+
+      def id
+        @constraint.id
+      end
+
+      def evaluate(graph)
+        selected = candidate_methods(graph).filter_map do |definition|
+          next if except.include?(definition.name)
+
+          match = selector.match(definition)
+          [definition, match] if match
+        end
+
+        @constraint.diagnostics(selected, self, graph)
+      end
+
+      private
+
+      def candidate_methods(graph)
+        definitions = source ? graph.method_definitions_for_component(source) : graph.method_definitions
+        definitions.select { |definition| definition.scope == scope && definition.visibility == :public }
+      end
+    end
+
+    # The selectors and constraints the naming DSL composes, plus the builder the
+    # DSL returns.
+    module Naming
+      # Selects methods whose name matches a regex. A named capture in the regex
+      # (such as <tt>(?<base>.+)</tt>) is exposed to the +requires+ constraint.
+      class NameSelector
+        attr_reader :regex
+
+        def initialize(regex)
+          @regex = regex
+        end
+
+        def match(definition)
+          regex.match(definition.name.to_s)
+        end
+
+        def describe
+          "matches #{regex.inspect}"
+        end
+      end
+
+      # Forbids any selected method from existing. Rule id +naming.forbidden+.
+      class Forbidden
+        def initialize(because: nil)
+          @because = because
+        end
+
+        def id
+          'naming.forbidden'
+        end
+
+        def diagnostics(selected, rule, _graph)
+          selected.map do |definition, _match|
+            Diagnostic.new(
+              rule: id,
+              message: message_for(definition),
+              location: definition.location,
+              evidence: "#{definition.owner} defines #{definition.scope} method #{definition.name} (#{rule.selector.describe})"
+            )
+          end
+        end
+
+        private
+
+        def message_for(definition)
+          base = "#{definition.owner} must not define ##{definition.name}"
+          @because ? "#{base}: #{@because}" : base
+        end
+      end
+
+      # Requires each selected method to have a sibling named by a template, in
+      # the same component or another (+on:+), at a given scope. The template
+      # interpolates the selector's named captures, as in
+      # <tt>requires("without_%{base}")</tt>. Rule id +naming.requires+.
+      class Requires
+        def initialize(template, on: nil, scope: :instance, because: nil)
+          @template = template
+          @on = on
+          @target_scope = scope
+          @because = because
+        end
+
+        def id
+          'naming.requires'
+        end
+
+        def diagnostics(selected, rule, graph)
+          target = @on || rule.source
+          existing = existing_names(graph, target)
+
+          selected.filter_map do |definition, match|
+            sibling = expand(match)
+            next if sibling.nil? || existing.include?(sibling.to_sym)
+
+            Diagnostic.new(
+              rule: id,
+              message: message_for(definition, sibling, target, rule),
+              location: definition.location,
+              evidence: "#{definition.owner} defines ##{definition.name}, expected ##{sibling}"
+            )
+          end
+        end
+
+        private
+
+        def existing_names(graph, target)
+          definitions = target ? graph.method_definitions_for_component(target) : graph.method_definitions
+          definitions.select { |definition| definition.scope == @target_scope }.map(&:name).to_set
+        end
+
+        def expand(match)
+          @template % captures(match)
+        rescue KeyError, ArgumentError
+          nil
+        end
+
+        def captures(match)
+          match.is_a?(MatchData) ? match.named_captures.transform_keys(&:to_sym) : {}
+        end
+
+        def message_for(definition, sibling, target, rule)
+          clause =
+            if target && target != rule.source
+              "#{target} to define ##{sibling}"
+            else
+              "a matching ##{sibling}"
+            end
+          base = "#{definition.owner}##{definition.name} requires #{clause}"
+          @because ? "#{base}: #{@because}" : base
+        end
+      end
+
+      # Returned by ArchSpec::DSL::ComponentProxy#methods. Starts a selector.
+      class Builder
+        def initialize(component, scope: :instance)
+          @component = component
+          @scope = scope
+        end
+
+        def matching(regex)
+          Selected.new(@component, NameSelector.new(regex), @scope)
+        end
+      end
+
+      # A chosen selector, waiting for a constraint. Each constraint method builds
+      # a NamingRule, attaches it, and returns the component proxy so rules chain.
+      class Selected
+        def initialize(component, selector, scope)
+          @component = component
+          @selector = selector
+          @scope = scope
+        end
+
+        def forbidden(except: [], because: nil)
+          add(Forbidden.new(because: because), except)
+        end
+
+        def requires(template, on: nil, scope: :instance, except: [], because: nil)
+          add(Requires.new(template, on: component_name(on), scope: scope, because: because), except)
+        end
+
+        private
+
+        def add(constraint, except)
+          rule = NamingRule.new(
+            source: @component.name,
+            selector: @selector,
+            constraint: constraint,
+            scope: @scope,
+            except: except
+          )
+          @component.definition.add_rule(rule)
+          @component
+        end
+
+        def component_name(target)
+          return if target.nil?
+
+          target.respond_to?(:name) ? target.name : target.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/archspec/rules/privacy_rule.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Rules
+    # Backs ArchSpec::DSL::ComponentProxy#public_api. Flags references from
+    # outside the component to constants that are not part of its public API.
+    class PublicApiRule
+      attr_reader :source, :file_patterns, :constants, :namespaces
+
+      def initialize(source, files: [], constants: nil, namespaces: nil)
+        @source = source.to_sym
+        @file_patterns = Array(files).flatten.compact.map(&:to_s)
+        @constants = Array(constants).compact.map { |value| normalize_constant(value) }
+        @namespaces = Array(namespaces).compact.map { |value| normalize_constant(value) }
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def merge!(other)
+        @file_patterns |= other.file_patterns
+        @constants |= other.constants
+        @namespaces |= other.namespaces
+        self
+      end
+
+      def id
+        'dependencies.privacy'
+      end
+
+      def evaluate(graph)
+        component = graph.components[source]
+        return [] unless component
+
+        public_names = public_constant_names(graph)
+
+        graph.dependency_edges.filter_map do |edge|
+          next if component.files.include?(edge.from_path)
+
+          resolved = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          next unless graph.component_names_for_constant(resolved).include?(source)
+          next if public?(resolved, public_names)
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{resolved} is private to #{source}",
+            location: edge.location,
+            evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{resolved}"
+          )
+        end
+      end
+
+      private
+
+      def public_constant_names(graph)
+        paths = file_patterns.flat_map do |pattern|
+          Dir.glob(File.absolute_path(pattern, graph.root))
+        end.map { |path| File.expand_path(path) }.to_set
+
+        names = graph.constants.select { |constant| paths.include?(constant.path) }.map(&:name)
+        (names + constants).to_set
+      end
+
+      # Names from public files and constants: match exactly. Reopened
+      # namespace modules land in public files too, so prefix matching there
+      # would make the whole namespace public. Use namespace: for prefixes.
+      def public?(name, public_names)
+        return true if public_names.include?(name)
+
+        namespaces.any? do |namespace|
+          name == namespace || name.start_with?("#{namespace}::")
+        end
+      end
+
+      def normalize_constant(value)
+        value.to_s.sub(/\A::/, '')
+      end
+    end
+  end
+end

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_*/attribute/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/{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.5.0'
 end

data/lib/archspec.rb

@@ -7,27 +7,64 @@ 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/naming_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'
 require_relative 'archspec/formatters/text'
 require_relative 'archspec/formatters/json'
+require_relative 'archspec/formatters/explanation'
 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.5.0
 platform: ruby
 authors:
 - Carmine Paolino
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-21 00:00:00.000000000 Z
+date: 2026-08-09 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,23 +88,25 @@ 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
 - lib/archspec/diagnostic.rb
 - lib/archspec/dsl.rb
 - lib/archspec/evaluator.rb
+- lib/archspec/formatters/explanation.rb
 - lib/archspec/formatters/json.rb
 - lib/archspec/formatters/text.rb
 - 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/naming_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