archspec 0.4.0 → 0.5.0

data/lib/archspec/dsl.rb

@@ -56,16 +56,6 @@ module ArchSpec
         self.todo_path = path.to_s
       end
 
-      # Declares acronym inflections for Zeitwerk name checks, mirroring your
-      # +config/initializers/inflections.rb+.
-      #
-      #   inflect "api" => "API", "graphql" => "GraphQL"
-      #
-      # +app/models/api_client.rb+ then expects +APIClient+.
-      def inflect(map)
-        add_inflections(map)
-      end
-
       # Yields each subdirectory matching a glob, so you can declare one
       # component per engine or pack without hardcoding their names. Paths
       # resolve against the +Archspec.rb+ directory, not the working directory,
@@ -97,9 +87,6 @@ module ArchSpec
       #
       # Returns an ArchSpec::DSL::ComponentProxy for attaching rules. The
       # component is also available by name later in the file.
-      #
-      # +layer+ and +role+ are aliases. Use whichever word fits the
-      # architecture you are describing.
       def component(name, in: nil, namespace: nil, constants: nil)
         add_component(
           ComponentSpec.new(name, files: binding.local_variable_get(:in), namespace: namespace, constants: constants)
@@ -107,9 +94,6 @@ module ArchSpec
         ComponentProxy.new(self, name)
       end
 
-      alias layer component
-      alias role component
-
       # Applies a bundled architecture preset, defining its components and
       # rules together.
       #
@@ -117,34 +101,28 @@ module ArchSpec
       #   architecture :hexagonal
       #   architecture :modular_monolith, components: { ... }, allow: { ... }
       #
+      # +preset+ is an alias. Use whichever word fits: +architecture+ reads well
+      # for structural bundles like +:rails+, +preset+ for convention packs like
+      # +:ruby_conventions+.
+      #
       # See ArchSpec::Architectures for every preset and its options.
       def architecture(name, **options)
         Architectures.apply(name, self, **options)
       end
 
+      alias preset architecture
+
       # Forbids dependency cycles between components. Pass +among:+ to limit the
       # check to a subset; omit it to check every declared component.
       #
-      #   no_cycles!
-      #   no_cycles! among: %i[billing catalog shared]
+      #   no_cycles
+      #   no_cycles among: %i[billing catalog shared]
       #
       # Rule id: +dependencies.no_cycles+.
-      def no_cycles!(among: nil)
+      def no_cycles(among: nil)
         add_rule(Rules::NoCyclesRule.new(among: among))
       end
 
-      # Checks that files define the constant their path implies under Zeitwerk.
-      # Pass globs to restrict the check to the autoloaded tree, since Rails
-      # does not autoload +lib+ by default.
-      #
-      #   verify_zeitwerk_names!
-      #   verify_zeitwerk_names! "app/**/*.rb"
-      #
-      # Rule id: +zeitwerk.naming+.
-      def verify_zeitwerk_names!(*only)
-        add_rule(Rules::ZeitwerkNamingRule.new(only: only))
-      end
-
       # Adds a custom rule object. A rule responds to +id+ and
       # <tt>evaluate(graph)</tt>, returning ArchSpec::Diagnostic objects. Use
       # this to extend ArchSpec with project-specific checks.
@@ -176,23 +154,20 @@ module ArchSpec
         @name = name.to_sym
       end
 
-      # Allowlists the components this one may depend on. A reference to any
-      # other declared component fails.
+      # Allowlists the components this one may depend on: only the listed
+      # components are permitted, and a reference to any other declared
+      # component fails. The mirror image of #can_only_be_used_by.
       #
-      #   controllers.can_use :models, :services
+      #   controllers.can_only_use :models, :services
       #
-      # +only_depend_on+ and +must_only_depend_on+ are aliases.
       # Rule id: +dependencies.allow+.
-      def can_use(*targets)
+      def can_only_use(*targets)
         add_rule(Rules::AllowDependenciesRule.new(name, targets))
         self
       end
 
-      alias only_depend_on can_use
-      alias must_only_depend_on can_use
-
-      # Forbids depending on the named components. Narrower than #can_use: only
-      # the listed components fail, other dependencies are left alone.
+      # Forbids depending on the named components. Narrower than #can_only_use:
+      # only the listed components fail, other dependencies are left alone.
       #
       #   models.cannot_use :controllers, :helpers
       #
@@ -203,7 +178,7 @@ module ArchSpec
       end
 
       # Allowlists the components that may reference this one, the inverse of
-      # #can_use. A reference from any other component fails. Use it to protect
+      # #can_only_use. A reference from any other component fails. Use it to protect
       # a shared kernel or a component with a deliberately narrow audience.
       #
       #   shared_kernel.can_only_be_used_by :billing, :catalog
@@ -223,7 +198,8 @@ module ArchSpec
       #   services.cannot_call :render, :params, receiver: :none
       #
       # A bare call to a method the component defines, inherits, or generates
-      # with +attr_*+ or +delegate+ is treated as its own API and not flagged.
+      # with +attr_*+, Rails +attribute+, or +delegate+ is treated as its own API
+      # and not flagged.
       # Rule id: +methods.forbid+.
       def cannot_call(*methods, receiver: :any)
         add_rule(Rules::CannotCallRule.new(name, methods, receiver: receiver))
@@ -329,6 +305,21 @@ module ArchSpec
         self
       end
 
+      # Starts a naming-convention rule over the component's defined, public
+      # methods. Select the methods with +matching+, then assert something about
+      # them. Every check is name-based and exact.
+      #
+      #   models.method_names.matching(/\A(get|set)_/).forbidden
+      #   chat.method_names.matching(/\Awith_(?<base>.+)/).requires("without_%{base}")
+      #   chat.method_names.matching(/\Awith_(?<b>.+)/).requires("%{b}", on: agent, scope: :class)
+      #
+      # Pass <tt>scope: :class</tt> to select class methods instead of instance
+      # methods. See ArchSpec::Rules::Naming::Selected for the constraints
+      # (+forbidden+, +requires+). Rule ids: +naming.forbidden+, +naming.requires+.
+      def method_names(scope: :instance)
+        Rules::Naming::Builder.new(self, scope: scope)
+      end
+
       private
 
       def add_rule(rule)

data/lib/archspec/formatters/explanation.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ArchSpec
+  module Formatters
+    # Renders <tt>archspec explain</tt>: why a file or constant belongs to its
+    # components, and the facts ArchSpec found for it. Raises ArchSpec::Error
+    # when the subject matches no file and no constant.
+    module Explanation
+      module_function
+
+      def print(output = $stdout, graph:, subject:)
+        path = File.expand_path(subject, graph.root)
+
+        if graph.files.key?(path)
+          explain_file(output, graph, path)
+        else
+          explain_constant(output, graph, subject)
+        end
+      end
+
+      def explain_file(output, graph, path)
+        file = graph.files.fetch(path)
+        output.puts file.relative_path
+        output.puts "  defined constants: #{graph.constants_for_path(path).map(&:name).join(', ')}"
+        print_parse_errors(output, file)
+        print_component_reasons(output, graph.component_assignment_reasons_for_path(path))
+        print_suppressions(output, file)
+        output.puts '  outgoing facts:'
+
+        graph.edges.select { |edge| edge.from_path == path }.each do |edge|
+          output.puts "    #{edge.type} #{edge.to} at #{edge.location.line}:#{edge.location.column}"
+        end
+      end
+
+      def explain_constant(output, graph, subject)
+        constants = graph.constants_named(subject)
+        raise Error, "No file or constant found for #{subject.inspect}" if constants.empty?
+
+        constants.each do |constant|
+          output.puts constant.name
+          output.puts "  kind: #{constant.kind}"
+          output.puts "  file: #{constant.location.relative_path(graph.root)}:#{constant.location.line}"
+          print_component_reasons(output, graph.component_assignment_reasons_for_constant(constant.name))
+          output.puts "  superclass: #{constant.superclass || '(none)'}"
+          output.puts "  instance methods: #{constant.instance_methods.to_a.sort.join(', ')}"
+          output.puts "  class methods: #{constant.class_methods.to_a.sort.join(', ')}"
+        end
+      end
+
+      def print_component_reasons(output, assignments)
+        if assignments.empty?
+          output.puts '  components: (none)'
+          return
+        end
+
+        output.puts '  components:'
+        assignments.sort_by { |name, _reasons| name.to_s }.each do |name, reasons|
+          output.puts "    #{name}: #{reasons.empty? ? '(no recorded reason)' : reasons.join('; ')}"
+        end
+      end
+
+      def print_suppressions(output, file)
+        return if file.suppressions.empty?
+
+        output.puts '  suppressions:'
+        file.suppressions.each do |suppression|
+          rule = suppression.rule || '*'
+          reason = suppression.reason ? " -- #{suppression.reason}" : ''
+          output.puts "    #{rule} on line #{line_range(suppression)}#{reason}"
+        end
+      end
+
+      def print_parse_errors(output, file)
+        return if file.parse_errors.empty?
+
+        output.puts '  parse errors:'
+        file.parse_errors.each do |parse_error|
+          output.puts "    #{parse_error.location.line}:#{parse_error.location.column} #{parse_error.message}"
+        end
+      end
+
+      def line_range(suppression)
+        if suppression.end_line == Float::INFINITY
+          "#{suppression.start_line}-EOF"
+        elsif suppression.start_line == suppression.end_line
+          suppression.start_line
+        else
+          "#{suppression.start_line}-#{suppression.end_line}"
+        end
+      end
+    end
+  end
+end

data/lib/archspec/model.rb

@@ -7,7 +7,7 @@ require_relative 'value_object'
 
 module ArchSpec
   ParseError = ValueObject.define(:message, :location)
-  MethodDefinition = ValueObject.define(:owner, :name, :scope, :location)
+  MethodDefinition = ValueObject.define(:owner, :name, :scope, :location, :visibility)
 
   Suppression = ValueObject.define(:rule, :start_line, :end_line, :reason) do
     def matches?(diagnostic)
@@ -18,12 +18,11 @@ module ArchSpec
   end
 
   class SourceFile
-    attr_reader :path, :relative_path, :expected_constant, :parse_errors, :suppressions
+    attr_reader :path, :relative_path, :parse_errors, :suppressions
 
-    def initialize(root:, path:, expected_constant:, parse_errors:, suppressions:)
+    def initialize(root:, path:, parse_errors:, suppressions:)
       @path = path
       @relative_path = Pathname(path).relative_path_from(Pathname(root)).to_s
-      @expected_constant = expected_constant
       @parse_errors = parse_errors
       @suppressions = suppressions
     end
@@ -56,19 +55,28 @@ module ArchSpec
       kind == :module
     end
 
-    def add_instance_method(name, location:)
+    def add_instance_method(name, location:, visibility: :public)
       instance_methods.add(name.to_sym)
-      method_definitions << MethodDefinition.new(self.name, name.to_sym, :instance, location)
+      method_definitions << MethodDefinition.new(self.name, name.to_sym, :instance, location, visibility)
     end
 
-    def add_class_method(name, location:)
+    def add_class_method(name, location:, visibility: :public)
       class_methods.add(name.to_sym)
-      method_definitions << MethodDefinition.new(self.name, name.to_sym, :class, location)
+      method_definitions << MethodDefinition.new(self.name, name.to_sym, :class, location, visibility)
     end
 
     def add_mixin(kind, name)
       mixins.fetch(kind).add(name)
     end
+
+    # Rewrites the visibility of already-recorded definitions, for the
+    # <tt>private :foo, :bar</tt> form that names methods defined earlier.
+    def set_visibility(name, scope, visibility)
+      name = name.to_sym
+      method_definitions.map! do |definition|
+        definition.name == name && definition.scope == scope ? definition.with(visibility: visibility) : definition
+      end
+    end
   end
 
   Edge = ValueObject.define(:type, :from_path, :from_constant, :to, :location, :confidence, :receiver)
@@ -117,11 +125,10 @@ module ArchSpec
       @components = {}
     end
 
-    def add_file(path:, expected_constant:, parse_errors:, suppressions: [])
+    def add_file(path:, parse_errors:, suppressions: [])
       files[path] = SourceFile.new(
         root: root,
         path: path,
-        expected_constant: expected_constant,
         parse_errors: parse_errors,
         suppressions: suppressions
       )
@@ -157,6 +164,12 @@ module ArchSpec
       component.constants.flat_map { |constant_name| constants_named(constant_name) }.flat_map(&:method_definitions)
     end
 
+    # Every method definition in the graph, across all constants. Used by
+    # project-wide naming rules that are not scoped to one component.
+    def method_definitions
+      constants.flat_map(&:method_definitions)
+    end
+
     def assign_components(component_specs)
       @components = {}
 

data/lib/archspec/rules/cycle_rule.rb

@@ -2,7 +2,7 @@
 
 module ArchSpec
   module Rules
-    # Backs ArchSpec::DSL::Context#no_cycles!. Flags dependency cycles between
+    # Backs ArchSpec::DSL::Context#no_cycles. Flags dependency cycles between
     # components, reporting each cycle once in a canonical order.
     class NoCyclesRule
       attr_reader :components

data/lib/archspec/rules/dependency_rules.rb

@@ -41,7 +41,7 @@ module ArchSpec
       end
     end
 
-    # Backs ArchSpec::DSL::ComponentProxy#can_use. Flags references from the
+    # Backs ArchSpec::DSL::ComponentProxy#can_only_use. Flags references from the
     # source to any component outside its allowlist.
     class AllowDependenciesRule < DependencyRule
       def id

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

@@ -50,7 +50,7 @@ module ArchSpec
       private
 
       # A receiverless call to a method the class itself defines (directly,
-      # inherited, or via attr_*/delegate) is a call to its own API.
+      # 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
 

data/lib/archspec/version.rb

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

data/lib/archspec.rb

@@ -12,16 +12,16 @@ 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: archspec
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Carmine Paolino
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -94,17 +94,17 @@ files:
 - 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

data/lib/archspec/presets.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-module ArchSpec
-  # Backwards-compatible alias for ArchSpec::Architectures. New code should use
-  # +architecture+ in the DSL and the ArchSpec::Architectures module.
-  module Presets
-    module_function
-
-    # Delegates to ArchSpec::Architectures.apply.
-    def apply(name, dsl, **options)
-      Architectures.apply(name, dsl, **options)
-    end
-  end
-end