archspec 0.4.0 → 1.0.0.rc1

data/lib/archspec/rules/naming_rules.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module ArchSpec
+  module Rules
+    # Backs the +method_names.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
+      VALID_SCOPES = %i[instance class].freeze
+
+      attr_reader :source, :selector, :scope, :except
+
+      def initialize(source:, selector:, constraint:, scope: :instance, except: [])
+        unless VALID_SCOPES.include?(scope)
+          raise Error, "method_names scope: must be :instance or :class, got #{scope.inspect}"
+        end
+
+        @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)
+          raise Error, "method_names matching expects a Regexp, got #{regex.inspect}" unless regex.is_a?(Regexp)
+
+          @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)
+          unless NamingRule::VALID_SCOPES.include?(scope)
+            raise Error, "requires scope: must be :instance or :class, got #{scope.inspect}"
+          end
+          raise Error, "requires expects a String template, got #{template.inspect}" unless template.is_a?(String)
+
+          @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#method_names. 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)
+          validate_template!(template)
+          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?
+
+          name = target.respond_to?(:name) ? target.name : target.to_sym
+          unless @component.definition.component?(name)
+            raise Error, "#{@component.name}.method_names.requires references unknown component: #{name}"
+          end
+
+          name
+        end
+
+        def validate_template!(template)
+          return unless template.is_a?(String)
+
+          captures = @selector.regex.names.to_h { |name| [name.to_sym, name] }
+          template % captures
+        rescue KeyError, ArgumentError => e
+          raise Error, "invalid requires template #{template.inspect}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/archspec/rules/privacy_rule.rb

@@ -36,9 +36,9 @@ module ArchSpec
         public_names = public_constant_names(graph)
 
         graph.dependency_edges.filter_map do |edge|
-          next if component.files.include?(edge.from_path)
+          next if graph.source_components_for(edge).include?(source)
 
-          resolved = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          resolved = graph.resolve_edge_constant(edge)
           next unless graph.component_names_for_constant(resolved).include?(source)
           next if public?(resolved, public_names)
 
@@ -46,7 +46,7 @@ module ArchSpec
             rule: id,
             message: "#{resolved} is private to #{source}",
             location: edge.location,
-            evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{resolved}"
+            evidence: "#{graph.edge_source_name(edge)} #{edge.verb} #{resolved}"
           )
         end
       end

data/lib/archspec/rules/protocol_rules.rb

@@ -35,14 +35,14 @@ module ArchSpec
           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 unless graph.source_components_for(edge).include?(source)
           next if own_method_call?(graph, edge)
 
           Diagnostic.new(
             rule: id,
             message: "#{source} must not call ##{edge.to}",
             location: edge.location,
-            evidence: "#{edge.from_constant || edge.from_path} calls #{edge.to}"
+            evidence: "#{graph.edge_source_name(edge)} calls #{edge.to}"
           )
         end
       end
@@ -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
 
@@ -107,7 +107,10 @@ module ArchSpec
 
       def initialize(source, method_names)
         @source = source.to_sym
-        @method_names = Array(method_names).flatten.map(&:to_sym)
+        names = Array(method_names).flatten.compact
+        raise Error, 'must_implement_one_of requires at least one method' if names.empty?
+
+        @method_names = names.map(&:to_sym)
       end
 
       def merge_key
@@ -154,7 +157,7 @@ module ArchSpec
         component = graph.components[source]
         return [] unless component
 
-        component.constants.flat_map { |name| graph.constants_named(name) }.select(&:class?).uniq(&:name)
+        graph.constants_for_component(source).select(&:class?).uniq(&:name)
       end
 
       def for(constant, methods, unresolved)
@@ -222,13 +225,13 @@ module ArchSpec
       def evaluate(graph)
         graph.edges.filter_map do |edge|
           next unless edge.type == :instantiates_and_invokes
-          next unless graph.component_names_for_path(edge.from_path).include?(source)
+          next unless graph.source_components_for(edge).include?(source)
 
           Diagnostic.new(
             rule: id,
             message: "#{source} must not instantiate and immediately invoke #{edge.to}",
             location: edge.location,
-            evidence: "#{edge.from_constant || edge.from_path} uses #{edge.to}"
+            evidence: "#{graph.edge_source_name(edge)} uses #{edge.to}"
           )
         end
       end

data/lib/archspec/source_location.rb

@@ -5,9 +5,15 @@ require 'pathname'
 require_relative 'value_object'
 
 module ArchSpec
-  SourceLocation = ValueObject.define(:path, :line, :column) do
+  SourceLocation = ValueObject.define(:path, :line, :column, :end_line, :end_column) do
     def self.from_prism(path, location)
-      new(path, location.start_line, location.start_column + 1)
+      new(path, location.start_line, location.start_column + 1, location.end_line, location.end_column + 1)
+    end
+
+    # A zero-width location for diagnostics that point at a file rather than a
+    # span of code.
+    def self.point(path, line, column)
+      new(path, line, column, line, column)
     end
 
     def relative_path(root)

data/lib/archspec/todo.rb

@@ -16,11 +16,24 @@ module ArchSpec
       return empty(root: root) unless path && File.exist?(path)
 
       document = YAML.safe_load_file(path, permitted_classes: [], aliases: false) || {}
-      ids = Array(document['violations']).filter_map do |entry|
-        entry.is_a?(Hash) ? entry['id'] : entry
+      unless document.is_a?(Hash) && (document['violations'].nil? || document['violations'].is_a?(Array))
+        raise Error, "invalid todo file #{path}: expected a violations list"
+      end
+
+      ids = Array(document['violations']).map.with_index do |entry, index|
+        id = entry.is_a?(Hash) ? entry['id'] : entry
+        unless id.is_a?(String) && !id.empty?
+          raise Error, "invalid todo file #{path}: violation #{index + 1} has no id"
+        end
+
+        id
       end
 
       new(ids.to_set, root: root)
+    rescue Error
+      raise
+    rescue Psych::Exception, SystemCallError => e
+      raise Error, "could not load todo file #{path}: #{e.message}"
     end
 
     def self.write(path, diagnostics, root:)
@@ -37,6 +50,8 @@ module ArchSpec
       }
 
       File.write(path, payload.to_yaml)
+    rescue SystemCallError => e
+      raise Error, "could not write todo file #{path}: #{e.message}"
     end
 
     def initialize(ids, root:)

data/lib/archspec/value_object.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module ArchSpec
+  # A frozen value type with positional or keyword construction and #with,
+  # mirroring Ruby 3.2's Data.define. Deliberately hand-rolled: the gem
+  # supports Ruby 3.1, where Data does not exist. Do not replace this with
+  # Data until the required Ruby version reaches 3.2.
   module ValueObject
     def self.define(*members, &block)
       klass = Struct.new(*members) do

data/lib/archspec/version.rb

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

data/lib/archspec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'archspec/error'
 require_relative 'archspec/version'
 require_relative 'archspec/value_object'
 require_relative 'archspec/source_location'
@@ -12,16 +13,17 @@ 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/style'
 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.
@@ -43,15 +45,7 @@ require_relative 'archspec/cli'
 #
 # 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
@@ -60,16 +54,17 @@ module ArchSpec
     #     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.
+    # An +Archspec.rb+ file is not written with 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.
+    # Returns the ArchSpec::Definition.
     def define(name = nil, &block)
       definition = Definition.new(name)
       definition.extend(DSL::Context)
       definition.instance_eval(&block) if block
-      self.last_definition = definition
+      definition
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: archspec
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Carmine Paolino
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 2026-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -93,18 +93,20 @@ files:
 - lib/archspec/definition.rb
 - lib/archspec/diagnostic.rb
 - lib/archspec/dsl.rb
+- lib/archspec/error.rb
 - lib/archspec/evaluator.rb
+- lib/archspec/formatters/explanation.rb
 - lib/archspec/formatters/json.rb
+- lib/archspec/formatters/style.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

data/lib/archspec/rules/zeitwerk_rule.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-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)
-
-          Diagnostic.new(
-            rule: id,
-            message: "#{file.relative_path} should define #{file.expected_constant}",
-            location: SourceLocation.new(file.path, 1, 1),
-            evidence: "defined constants: #{defined.empty? ? '(none)' : defined.join(', ')}"
-          )
-        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